narratio/docs/internal/stage-analyze.md

# Stage: analyze

## Purpose
Execute selected configured Scriptorium artifacts in dependency order and materialize outputs.

## Inputs
- configured artifacts from `pipeline.scriptorium.artifacts`
- optional selected artifact filter (`--artifacts`)
- built-in/configured/previous-session source references in artifact inputs

Supported source families:
- built-ins: `narratio.transcript.*`, `narratio.bounds.session`
- configured artifacts: `narratio.artifact.<key>`
- previous-session cache: `narratio.previous_session.artifact.<key>`

## Outputs
- one materialized output per executed configured artifact (`output_path`)
- stage metadata describing selected/generated/reused artifacts

## Key Behavior
- skips with metadata when Scriptorium config is missing or no executable artifacts remain.
- builds runtime artifact catalog (built-ins + configured artifacts).
- marks non-executable configured artifacts as reusable when output files already exist.
- validates selected artifact dependency order (cycle-safe topo ordering).
- resolves required/optional inputs per artifact source definition.
- resolves previous-session sources from local `previous/` cache only.
- runs optional render-debug, then artifact execution.
- validates non-empty output files and materializes canonical outputs.

## Failure Semantics
- required missing configured/previous-session inputs fail.
- missing required previous-session source includes prepare rerun guidance.
- dependency cycles or unavailable required dependencies fail.
- adapter validation failures fail stage.

## Invariants
- `analyze` performs no remote storage calls for previous-session source resolution.
- output provenance and metadata are deterministic per execution.