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)
• 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
• 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.
• materializes S3 audio through spool/cache-aware logic.
• scans enabled configured artifact inputs for narratio.previous_session.artifact.* requirements.
• when previous requirements exist:
  • clears managed previous/ state;
  • builds previous-cache remote plan;
  • downloads previous manifest/artifacts;
  • records previous inputs in manifest.inputs.

Required previous-session inputs fail when unavailable; optional missing inputs are skipped.

Invariants

• only prepare hydrates canonical previous/ cache state.
• managed previous artifacts are stored under previous/artifacts/** without duplicate artifacts/artifacts/ nesting.
• manifest.inputs ordering is deterministic (kind, path).

Related Contracts And Tests

• Configuration owns audio selection, stable input fields, and previous-session settings.
• Operations owns physical input, audio, spool, cache, and previous-state layout.
• Storage Internals and Artifact Internals explain the internal collaborators.
• Implementation and tests: internal/stage/prepare.go, internal/stage/prepare_test.go, internal/audio/s3_audio_test.go, internal/previouscache/*_test.go