narratio/docs/internal/stage-prepare.md

# Stage: prepare

## Purpose

Materialize canonical current-session inputs before processing stages.

## Inputs

- resolved campaign, session, and pipeline configuration
- stable input files (`speakers`, `autocorrect`, `glossary`, `players`, `party`)
- optional spell-catalog overlay
- one resolved local or S3 audio source
- enabled configured artifact input requirements for previous-session sources

## Outputs

- `inputs/campaign.yml`
- `inputs/session.yml`
- `inputs/pipeline.resolved.yml`
- `inputs/speakers.yml`
- `inputs/autocorrect.yml`
- `inputs/glossary.yml`
- `inputs/players.yml`
- `inputs/party.yml`
- optional `inputs/spell_catalog.json`
- `audio/*.flac`
- optional `previous/manifest.json`
- optional `previous/artifacts/**`
- deterministic `manifest.inputs` entries (checksums + provenance)

## Key Behavior

- validates required config/store state.
- enforces local audio vs S3 audio mutual exclusivity.
- rejects duplicate explicit local audio sources after resolution.
- gives distinct local source paths with the same basename deterministic unique
  prepared filenames so neither source is overwritten.
- materializes S3 audio through spool/cache-aware logic.
- materializes a configured spell catalog with checksum and provenance, or
  safely removes an obsolete canonical spell catalog and its manifest record
  when the effective input is omitted.
- copies the validated canonical party bytes unchanged and deterministically
  generates the prepared players projection.
- scans enabled configured artifact inputs for `narratio.previous_session.artifact.*` requirements.
- clears managed `previous/` state on every invocation, then, when requirements exist:
  - resolves the pointer-selected previous source through the shared resolver;
  - downloads previous manifest/artifacts;
  - records previous inputs in `manifest.inputs`.

Required previous-session inputs fail when unavailable; optional missing inputs
are typed skipped results. Each requirement resolves only from its unique
`published_output` declaration in the pointer-selected remote commit. Prepare
strips that selected run's immutable `published/` prefix to derive the local
cache path, then validates the committed checksum, size, and generation.

## Invariants

- only `prepare` hydrates canonical `previous/` cache state.
- managed previous artifacts are stored under `previous/artifacts/**` without
  duplicate `artifacts/artifacts/` nesting.
- managed `previous/` state represents only the current requirement set.
- `manifest.inputs` ordering is deterministic (`kind`, `path`).

## Resume Evidence

Prepare records a versioned semantic-configuration fingerprint for the
resolved campaign/session selection, local-versus-S3 audio mode and canonical
audio names, stable-input ownership/presence, previous-session identity, and
the party mode plus canonical players projection version, and the effective
previous-artifact requirement set. A change reruns prepare and
stales its fixed descendants. Existing successful records without this
evidence rerun once when selected.

Workspace, spool, and cache placement and absolute source relocation are not
semantic when logical selection, canonical names, and bytes are equivalent.
The fingerprint deliberately does not read or rehash large audio. Prepared
input checksums remain the content provenance. Before reusing success, prepare
validates every durable prepared copy and compares current stable-input bytes,
canonical party and derived-player bytes, local audio membership/checksums, or
S3 key/size/entity-tag identity with that provenance. Source relocation with
equivalent names and bytes remains reusable; changed or unavailable evidence
causes a normal prepare rerun.

## Related Contracts And Tests

- [Configuration](../config.md) owns audio selection, stable input fields, and
  previous-session settings.
- [Operations](../operations.md) owns physical input, audio, spool, cache, and
  previous-state layout.
- [Storage Internals](storage.md) and [Artifact Internals](artifacts.md) explain
  the internal collaborators.
- Implementation and tests: `internal/stage/prepare.go`,
  `internal/stage/prepare_test.go`,
  `internal/stage/prepare_resume.go`,
  `internal/stage/prepare_resume_test.go`,
  `internal/stage/semantic_contracts_initial.go`,
  `internal/stage/semantic_contracts_initial_test.go`,
  `internal/audio/s3_audio_test.go`,
  `internal/previouscache/*_test.go`