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 keys supplied through the stage environment
• built-in, configured, extraction, and previous-session source references in artifact inputs

Supported source families:

• built-ins: narratio.transcript.*, narratio.bounds.session
• prepared stable inputs: narratio.input.players, narratio.input.party, narratio.input.glossary, narratio.input.spell_catalog
• configured artifacts: narratio.artifact.<key>
• extraction lanes: narratio.extraction.<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

• when Scriptorium is absent or no configured artifact is executable, completes successfully with no outputs and records explanatory metadata. This is not an explicit self-skip: both manifests record success, satisfy publish's prerequisite, and an ordinary later run reuses the result until forced.
• builds a runtime artifact catalog containing built-ins, configured artifacts, and configured extraction lanes. Extraction availability is hydrated only from compatible successful extraction evidence.
• uses enabled configured artifacts by default. An explicit --artifacts selection is a one-invocation override: it makes exactly the named configured artifacts executable even when disabled, and does not automatically include dependencies. A selected artifact's dependencies must instead already be available to the catalog.
• makes a non-executable configured artifact reusable only when its current manifest record and durable output pass the configured-artifact evidence contract; an incidental or stale canonical file is unavailable.
• validates selected artifact dependency order (cycle-safe topo ordering).
• resolves required/optional inputs per artifact source definition into an ordered semantic identity. Each identity records the configured input name, canonical source ID, required policy, explicit presence, source contract, checksum, size, and a source-based logical identity. Workspace paths and producer run IDs are excluded.
• orders input identities by configured input name independently of Go map iteration. Runtime adapter paths remain a separate execution-only map.
• omits an unavailable optional input from the adapter request while retaining explicit absence in its semantic identity; an unavailable required input fails.
• resolves prepared stable input sources through the shared manifest-authoritative identity resolver; it does not accept incidental files or fall back to campaign/session source paths.
• reuses checksums and sizes from validated prepared, extraction, and current configured-artifact evidence. Other resolved inputs are hashed as confined regular files with streaming reads and the central resolved-artifact size limit.
• owns a versioned SHA-256 fingerprint contract with one fixed-field canonical JSON payload and no map serialization. Configured artifacts are fingerprinted in deterministic dependency order.
• fingerprints the normalized artifact key, prompt and profile identifiers, normalized Scriptorium executable and config logical identities, effective render-debug behavior, session-relative output identity, sorted dependency keys, ordered input declarations and semantic identities, validated current dependency-output identities, and sorted effective Scriptorium variables (including Narratio's sticky session variable).
• provides read-only reconciliation that classifies each configured record as current, stale, missing, failed, legacy, or otherwise non-resumable, and separately identifies manifest records removed from current configuration. A record is current only when its fingerprint version and value match and its configured output still passes manifest-authoritative evidence validation.
• 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 prepared stable input source includes prepare rerun guidance.
• missing required previous-session source includes prepare rerun guidance.
• missing required narratio.transcript.final_markdown or narratio.transcript.final_trimmed_markdown inputs includes render 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.
• input-identity resolution is read-only: it does not invoke adapters, materialize outputs, update status, or create run records.
• fingerprints exclude timeouts, retries, timestamps, producer and Narratio run IDs, absolute executable/config/workspace roots, diagnostic locations, and executable or private transitive configuration contents. A change that is visible only inside Scriptorium—such as a file privately loaded by its config path—requires an explicit forced regeneration.
• output provenance and metadata are deterministic per execution.

Related Contracts And Tests

• Configuration owns artifact fields and source-selection rules.
• CLI owns user-visible artifact selection.
• Scriptorium owns the subprocess contract.
• Implementation and tests: internal/stage/analyze.go, internal/stage/analyze_input_identity.go, internal/stage/analyze_test.go, internal/stage/analyze_input_identity_test.go, internal/stage/analyze_fingerprint.go, internal/stage/analyze_fingerprint_test.go, internal/stage/analyze_reconciliation.go, and internal/stage/analyze_reconciliation_test.go