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.
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. Committed sources use their exact source-to-destination mapping, while the isolated legacy reader rejects ambiguous fallback matches.

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 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; force prepare after changing source bytes that are not otherwise reflected by the semantic selection.

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/stage/semantic_contracts_initial.go, internal/stage/semantic_contracts_initial_test.go, internal/audio/s3_audio_test.go, internal/previouscache/*_test.go

3.7 KiB Raw Blame History