narratio/docs/internal/stage-analyze.md

Stage: analyze

Purpose

Execute selected configured Scriptorium artifacts in deterministic dependency order and promote successful outputs to canonical session artifact paths.

Inputs and outputs

Inputs:

• configured artifact definitions from pipeline.scriptorium.artifacts;
• selected artifact filter (--artifacts) when provided;
• resolved artifact sources from resolver/catalog.

Source types used by analyze:

• built-ins: narratio.transcript.*, narratio.bounds.session;
• configured artifacts: narratio.artifact.<artifact_key>;
• canonical previous-session artifacts: narratio.previous_session.artifact.<artifact_key>;
• legacy path-based previous-session source: previous_session_artifact (uses inputs.*.path).

Outputs:

• promoted configured artifact files at each configured output_path;
• stage metadata (generated_artifacts, reused_artifacts, selected/order info).

Boundaries

Owns:

• runtime artifact catalog construction;
• selected-artifact planning and dependency ordering;
• per-input resolution and required/optional handling;
• Scriptorium render/run invocation;
• run-local output generation and canonical promotion.

Does not own:

• prepare-time previous-session hydration;
• object-store access for previous-session sources;
• archive promotion policy.

Config fields used

• session.session_id
• session.campaign
• pipeline.workspace.root
• pipeline.scriptorium.binary
• pipeline.scriptorium.config_path
• pipeline.scriptorium.timeout
• pipeline.scriptorium.render_debug
• pipeline.scriptorium.artifacts.<name>.*

External adapters used

• Scriptorium adapter:
  • optional RenderArtifact when render-debug is enabled;
  • RunArtifact for artifact generation.

State and manifest behavior

• If Scriptorium config is absent, or no artifacts are executable after filtering, analyze returns success metadata with skipped=true.
• Builds runtime catalog with built-ins and configured narratio.artifact.<name> entries.
• Non-executable configured artifacts may still be marked available from existing canonical output files.
• Resolves canonical previous-session sources from local prepared previous/ cache:
  • prefers manifest-backed previous input paths when present;
  • may fall back to current-session previous/ filesystem paths.
• Analyze does not call object storage for canonical previous-session source resolution.
• Required canonical previous-session input missing:
  • fails with guidance to run narratio run-stage --force prepare.
• Optional missing sources are omitted from adapter input paths.

Skip and resume behavior

• Runner-level skip applies when analyze is already succeeded and --force is not set.
• Analyze is stage-scoped for resume; no per-artifact manifest resume state.
• --artifacts filters executable artifacts but does not imply force rerun.

Failure behavior

• Fails on dependency-order violations, missing required inputs, resolver validation failures, adapter errors, and missing/empty generated outputs.
• Required unavailable configured artifact source (narratio.artifact.<name>) fails before invocation.
• Required canonical previous-session source fails with prepare-rerun guidance.

Tests to inspect before changing

• internal/stage/analyze_test.go
• internal/artifacts/catalog_test.go
• internal/artifacts/artifact_resolver_test.go
• internal/app/restore_workflow_test.go

Architectural invariants

• Canonical previous-session behavior is local-cache only during analyze.
• Generated outputs are validated and promoted before stage success is recorded.
• Resolver/catalog decisions stay deterministic and validation-gated.