narratio/docs/internal/stage-prepare.md

Stage: prepare

Purpose

Materialize canonical current-session inputs before processing stages.

Inputs

• resolved campaign.yml, session.yml, and pipeline config
• stable input files (speakers, autocorrect, glossary, players, party)
• audio source:
  • local audio_dir/audio_files, or
  • S3 audio_s3.prefix
• 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).