narratio/docs/internal/stage-prepare.md

Stage: prepare

Purpose

Materialize all required session inputs into canonical local workspace paths and record input provenance in the session manifest.

Inputs and Outputs

Inputs:

• session.yml (resolved session config)
• pipeline.resolved.yml (materialized from resolved pipeline config)
• speakers.yml
• autocorrect.yml
• glossary.yml
• audio source:
  • local (session.inputs.audio_dir or session.inputs.audio_files), or
  • S3 (session.inputs.audio_s3.prefix)

Outputs:

• inputs/session.yml
• inputs/pipeline.resolved.yml
• inputs/speakers.yml
• inputs/autocorrect.yml
• inputs/glossary.yml
• audio/*.flac in session workdir
• manifest.Inputs records with checksums and source metadata

Boundaries

Owns:

• Input path resolution and validation
• Local copy/materialization of configs and audio files
• S3 audio download to run-scoped spool, then copy into work audio dir

Does not own:

• Transcript generation/processing
• Archive publish behavior

Config Fields Used

• session.session_id
• session.campaign
• session.inputs.speakers_file
• session.inputs.autocorrect_file
• session.inputs.glossary_file
• session.inputs.audio_dir
• session.inputs.audio_files
• session.inputs.audio_s3.prefix
• pipeline.workspace.root
• pipeline.spool.root
• pipeline.storage.s3.bucket
• pipeline.storage.s3.root_prefix

External Adapters Used

• Object storage backend (env.ObjectStore) for S3 audio list/download when audio_s3 is configured.

State and Manifest Behavior

• Ensures workspace layout exists.
• Writes resolved config and input files to canonical inputs/ paths.
• Records all prepared inputs into manifest.Inputs (sorted deterministically by kind/path).
• For S3 audio, records S3Bucket, S3Key, S3Size, S3ETag, and SpoolPath in each audio input record.

Skip and Resume Behavior

• Runner-level skip applies when stage already succeeded and --force is not set.
• Stage itself is deterministic/idempotent for unchanged inputs (copyFileIfChanged, writeBytesIfChanged).

Failure Behavior

• Fails on missing required files, invalid audio source combinations, no discoverable .flac files, duplicate audio basenames, missing object store for S3 mode, or S3 list/download failures.

Tests to Inspect Before Changing

• internal/stage/prepare_test.go
• internal/app/session_cli_test.go
• internal/config/load_validate_test.go

Architectural Invariants

• audio_dir/audio_files and audio_s3 are mutually exclusive.
• Audio files must be .flac.
• Canonical inputs/* and audio/* paths are the durable source for downstream stages.