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`).