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.
- owns a read-only typed work planner. Its explicit targets are enabled
  artifacts by default or the exact normalized `--artifacts` selection when
  supplied. It closes targets over configured prerequisites, orders the closure
  topologically, reuses current members, and schedules every non-current member
  before its dependents.
- force applies only to explicit targets. A current prerequisite is reused
  unless it is itself an explicit forced target; disabled prerequisites may be
  rebuilt when required, while unrelated disabled artifacts are excluded.
- the work plan carries explicit targets, prerequisite-only work, deterministic
  execution and reuse lists, invalidated and removed records, and a cloned
  projected record collection. Valid unrelated configured records survive the
  projection, removed records are omitted, and legacy files never become
  current without regeneration.
- 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](../config.md#scriptorium-artifact-entries) owns artifact
  fields and source-selection rules.
- [CLI](../cli.md) owns user-visible artifact selection.
- [Scriptorium](../integrations/scriptorium.md) 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`,
  `internal/stage/analyze_plan.go`, and `internal/stage/analyze_plan_test.go`