2026-05-18 22:03:59 -05:00
|
|
|
# Stage: prepare
|
|
|
|
|
|
|
|
|
|
## Purpose
|
2026-08-09 21:50:21 +00:00
|
|
|
|
2026-05-23 12:57:59 +00:00
|
|
|
Materialize canonical current-session inputs before processing stages.
|
2026-05-18 22:03:59 -05:00
|
|
|
|
2026-05-23 12:57:59 +00:00
|
|
|
## Inputs
|
2026-08-09 21:50:21 +00:00
|
|
|
|
|
|
|
|
- resolved campaign, session, and pipeline configuration
|
2026-05-27 09:34:05 -05:00
|
|
|
- stable input files (`speakers`, `autocorrect`, `glossary`, `players`, `party`)
|
2026-08-09 21:50:21 +00:00
|
|
|
- one resolved local or S3 audio source
|
2026-05-23 12:57:59 +00:00
|
|
|
- enabled configured artifact input requirements for previous-session sources
|
|
|
|
|
|
|
|
|
|
## Outputs
|
2026-08-09 21:50:21 +00:00
|
|
|
|
2026-05-23 12:57:59 +00:00
|
|
|
- `inputs/campaign.yml`
|
|
|
|
|
- `inputs/session.yml`
|
|
|
|
|
- `inputs/pipeline.resolved.yml`
|
|
|
|
|
- `inputs/speakers.yml`
|
|
|
|
|
- `inputs/autocorrect.yml`
|
|
|
|
|
- `inputs/glossary.yml`
|
2026-05-27 09:34:05 -05:00
|
|
|
- `inputs/players.yml`
|
|
|
|
|
- `inputs/party.yml`
|
2026-05-23 12:57:59 +00:00
|
|
|
- `audio/*.flac`
|
|
|
|
|
- optional `previous/manifest.json`
|
|
|
|
|
- optional `previous/artifacts/**`
|
|
|
|
|
- deterministic `manifest.inputs` entries (checksums + provenance)
|
|
|
|
|
|
|
|
|
|
## Key Behavior
|
2026-08-09 21:50:21 +00:00
|
|
|
|
2026-05-23 12:57:59 +00:00
|
|
|
- validates required config/store state.
|
|
|
|
|
- enforces local audio vs S3 audio mutual exclusivity.
|
2026-08-10 21:53:54 +00:00
|
|
|
- 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.
|
2026-05-23 12:57:59 +00:00
|
|
|
- materializes S3 audio through spool/cache-aware logic.
|
|
|
|
|
- scans enabled configured artifact inputs for `narratio.previous_session.artifact.*` requirements.
|
2026-08-10 21:53:54 +00:00
|
|
|
- clears managed `previous/` state on every invocation, then, when requirements exist:
|
2026-08-10 21:20:59 +00:00
|
|
|
- resolves the pointer-selected previous source through the shared resolver;
|
2026-05-23 12:57:59 +00:00
|
|
|
- downloads previous manifest/artifacts;
|
|
|
|
|
- records previous inputs in `manifest.inputs`.
|
2026-05-18 22:03:59 -05:00
|
|
|
|
2026-08-10 21:20:59 +00:00
|
|
|
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.
|
2026-05-18 22:03:59 -05:00
|
|
|
|
2026-05-23 12:57:59 +00:00
|
|
|
## Invariants
|
2026-08-09 21:50:21 +00:00
|
|
|
|
2026-05-23 12:57:59 +00:00
|
|
|
- only `prepare` hydrates canonical `previous/` cache state.
|
2026-08-09 21:50:21 +00:00
|
|
|
- managed previous artifacts are stored under `previous/artifacts/**` without
|
|
|
|
|
duplicate `artifacts/artifacts/` nesting.
|
2026-08-10 21:53:54 +00:00
|
|
|
- managed `previous/` state represents only the current requirement set.
|
2026-05-23 12:57:59 +00:00
|
|
|
- `manifest.inputs` ordering is deterministic (`kind`, `path`).
|
2026-08-09 21:50:21 +00:00
|
|
|
|
|
|
|
|
## 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/audio/s3_audio_test.go`,
|
|
|
|
|
`internal/previouscache/*_test.go`
|
