Prepare the v2.2.0 release

docs/cli.md

@@ -98,6 +98,8 @@ a session nor create a workspace, manifest, run, lock, adapter, or remote
 connection. Like every pipeline-loading command, they bootstrap the selected or
 conventional secrets directory before resolving configuration; `config show`
 never includes bootstrap reports or secret values in its YAML output.
+Typed credential references, including `notarius.llm_api_key`, must therefore
+resolve even though these inspection commands never construct an adapter.
 
 Campaign selection is optional for a pipeline without party-driven artifact
 families. A pipeline with `scriptorium.artifact_families` needs a selected or
@@ -175,6 +177,9 @@ Behavior:
 - rejects unknown endpoints and a `--from` endpoint after `--through`;
 - runs `render` before `extract`; an omitted or disabled Notarius
   configuration records an explicit `notarius_disabled` self-skip;
+- resolves every selected typed credential during the initial configuration
+  load, including a Notarius credential when extract is disabled, outside the
+  selected range, or later skipped as resumable;
 - skips already-succeeded stages unless `--force` is set or a stage-specific
   resume check finds its durable result obsolete;
 - applies `--force` only to stages in the selected range;
@@ -207,6 +212,10 @@ artifacts and any prerequisites required by those targets; without
 never run. Common session/configuration options and repeatable artifact values
 pass through unchanged.
 
+The forced extraction rebuilds the complete configured Notarius bundle,
+disables Notarius checkpoint loading, and requests chunk-plan refresh.
+`--artifacts` narrows only the analysis work; it never selects Notarius lanes.
+
 Because the expansion owns `--force`, `--from`, and `--through`, callers cannot
 supply those options. The shared `run` parser reports them as duplicate
 singleton flags. The alias has no private execution options or behavior, and
@@ -249,6 +258,10 @@ Equivalent to:
 narratio run-stage analyze <session_id> --force [...common config flags]
 ```
 
+This selects only `analyze`: it does not invoke Notarius, replace extraction,
+or remove existing extract outputs. `--artifacts` narrows the forced analysis
+targets and their required analysis prerequisites.
+
 ### `publish`
 
 ```bash

docs/config.md

@@ -227,8 +227,12 @@ inputs:
 - Do not place raw secrets in YAML.
 - Credential fields contain environment-variable names, represented internally
   as ConfigKit typed secret references (for example
-  `pipeline.audita.llm_api_key: AUDITA_LLM_API_KEY`). A configured reference
+  `pipeline.notarius.llm_api_key: NOTARIUS_LLM_API_KEY`). A configured reference
   must resolve to a nonempty environment value during load.
+- Every surviving reference is resolved during ordinary pipeline loading,
+  regardless of whether its integration is disabled, outside the selected
+  stage range, or eligible for resume. Omit the field or set it to `null` when
+  that deployment should not require the credential.
 - Every command that loads a pipeline accepts `--secrets-dir <path>`. When the
   flag is omitted, Narratio uses a present `secrets/` directory beside the
   resolved root `pipeline.yml`; an absent conventional directory is ignored.
@@ -236,8 +240,10 @@ inputs:
   and a missing or empty explicit selection is an error.
 - Each immediate regular file whose name is a valid environment-variable name
   supplies one value. ConfigKit removes trailing CR/LF, permits a symlink as the
-  selected directory, rejects symlink entries, and limits input to 1 MiB per
+  selected directory, rejects non-hidden symlink entries, and limits input to
-  file, 8 MiB total, and 1024 entries.
+  1 MiB per file, 8 MiB total, and 1024 entries. Dot-prefixed entries (including
+  files, directories, and symlinks) are ignored and omitted from bootstrap
+  reports, but still count toward the directory entry limit.
 - An existing process environment value takes precedence over a credential file.
 - On POSIX, operators must provision the directory with no group/other access
   (normally `0700`) and files with no group/other access (normally `0600`);
@@ -353,10 +359,14 @@ Rules:
 | `pipeline.trim.seriatim.report` | bool | No | `false` |
 | `pipeline.notarius.enabled` | bool | No | `false` |
 | `pipeline.notarius.binary` | string | No | `notarius` |
+| `pipeline.notarius.llm_api_key` | secret reference | No | unset; exact environment-variable name forwarded to Notarius |
+| `pipeline.notarius.config_profile` | string | No | unset; exact Notarius ConfigKit profile selector |
 | `pipeline.notarius.config_path` | string | Conditional | required when enabled; relative paths resolve from the pipeline file directory |
 | `pipeline.notarius.pipeline_id` | string | Conditional | required when enabled |
 | `pipeline.notarius.timeout` | duration | No | `3h`; must be positive |
 | `pipeline.notarius.working_directory` | string | No | directory containing resolved `config_path`; relative paths resolve from the pipeline file directory |
+| `pipeline.notarius.resume` | bool | No | `false`; request compatible Notarius checkpoint reuse during ordinary executed extraction |
+| `pipeline.notarius.chunk_cache` | string | No | empty; when set, exactly `auto`, `bypass`, or `refresh` |
 | `pipeline.notarius.references` | map[string]string | No | empty; maps normalized Notarius selectors to supported prepared Narratio source IDs; maximum 256 entries |
 | `pipeline.notarius.outputs` | map | Conditional | at least one entry when enabled |
 | `pipeline.render.enabled` | bool | No | `true` |
@@ -373,6 +383,73 @@ Rules:
 | `pipeline.scriptorium.artifact_families` | map | No | empty; expands one ordinary artifact per canonical party character |
 | `pipeline.notification.mode` | string | No | `noop`; the only supported notification mode until a provider is implemented |
 
+### Notarius Configuration Profile
+
+`pipeline.notarius.config_profile` optionally selects a Notarius ConfigKit
+configuration profile when extraction executes:
+
+```yaml
+notarius:
+  config_profile: downstream-economy
+```
+
+When the field is omitted or `null`, Narratio supplies no downstream profile
+selector and preserves Notarius's existing configuration-selection behavior.
+When present, Narratio forwards the exact string to Notarius, including an
+empty string or `default`, which explicitly select Notarius's composed base
+configuration. Notarius owns selector interpretation and validation; Narratio
+does not restrict profile names, resolve profile files, or rewrite the value.
+
+This selection is independent of Narratio's own `--profile` selection. A
+Narratio overlay may explicitly select a differently named Notarius overlay,
+but Narratio never forwards its own profile name automatically. It is also
+independent of `pipeline.notarius.llm_api_key`: an overlay may change either or
+both fields according to the deployed Notarius configuration. See the
+[Notarius integration contract](./integrations/notarius.md) for invocation and
+failure behavior.
+
+### Notarius Credential
+
+`pipeline.notarius.llm_api_key` optionally names the one environment variable
+to forward to the Notarius child process:
+
+```yaml
+notarius:
+  llm_api_key: OPENROUTER_API_KEY
+```
+
+The field contains the variable name, not a credential value. That name must
+match `api_key_env` in the Notarius/PromptKit profile selected by the deployed
+Notarius pipeline; Narratio does not infer or remap provider names. Omission or
+`null` forwards nothing. A non-null selected reference must resolve at pipeline
+load time through the process environment or existing secrets-directory
+bootstrap, even when Notarius is disabled, extract is outside the requested
+range, or a completed extraction can be reused.
+
+The Notarius child receives only Narratio's minimal execution environment plus
+this exact selected name and loaded value. Other credentials are not forwarded.
+Changing the value, name, presence, or absence does not invalidate extract's
+semantic resume evidence. The public name remains part of safe effective
+inspection, so renaming it may appear in `config diff` and change the effective
+configuration digest; rotating only its value does neither.
+
+See the [Notarius integration contract](./integrations/notarius.md) for the
+delivery and redaction boundary.
+
+### Notarius Cache Controls
+
+`pipeline.notarius.resume` defaults to `false`. When true, an executed ordinary
+extraction passes `--resume`; the deployed Notarius configuration must already
+enable checkpoint recording and should select an explicit persistent checkpoint
+root. Narratio does not inspect or generate that configuration.
+
+`pipeline.notarius.chunk_cache` is empty by default, leaving Notarius's
+configured mode in control. A nonempty value must be `auto`, `bypass`, or
+`refresh` and is passed as `--chunk_cache`. Forced extraction takes precedence
+over both fields: it omits `--resume` and passes `--chunk_cache refresh`.
+Neither field changes Narratio's semantic extraction fingerprint, so changing
+them alone does not rerun an otherwise complete durable extraction.
+
 ### Notarius Reference Bindings
 
 `pipeline.notarius.references` maps a Notarius CLI selector to a prepared
@@ -402,8 +479,8 @@ It validates only selector structure and the prepared source vocabulary;
 Notarius owns target-slot declarations and media compatibility.
 
 Before extraction, Narratio resolves every binding from the current prepared
-session manifest and streams it into a verified invocation-local snapshot whose
+session manifest and streams it into a verified, content-addressed session
-absolute path is passed to Notarius. Missing, unsafe, empty,
+snapshot whose absolute path is passed to Notarius. Missing, unsafe, empty,
 changed-during-copy, or checksum-inconsistent prepared evidence fails with
 guidance to force `prepare`. Bindings are sorted by normalized selector and are
 part of extraction fingerprint and resume identity. See the

docs/integrations/notarius.md

@@ -7,14 +7,14 @@ lanes from the final trimmed Seriatim transcript. Narratio owns invocation,
 safe bundle discovery, lane selection, and its own artifact metadata. Notarius
 owns pipeline definitions, lane schemas, the receipt, and bundle formats.
 
-Canonical Notarius v0.6.0 references:
+Canonical Notarius v0.7.0 references:
 
-- [CLI reference](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.6.0/docs/cli.md)
+- [CLI reference](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.7.0/docs/cli.md)
-- [Subprocess consumer contract](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.6.0/docs/consumers/subprocess.md)
+- [Subprocess consumer contract](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.7.0/docs/consumers/subprocess.md)
-- [D&D pipeline and lane contracts](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.6.0/docs/consumers/dnd-pipeline.md)
+- [D&D pipeline and lane contracts](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.7.0/docs/consumers/dnd-pipeline.md)
-- [Run-result receipt](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.6.0/docs/integrations/run-result.md)
+- [Run-result receipt](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.7.0/docs/integrations/run-result.md)
-- [JSON output bundle](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.6.0/docs/integrations/json-output.md)
+- [JSON output bundle](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.7.0/docs/integrations/json-output.md)
-- [D&D spell-catalog overlay](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.6.0/docs/integrations/dnd-spell-catalog-overlays.md)
+- [D&D spell-catalog overlay](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.7.0/docs/integrations/dnd-spell-catalog-overlays.md)
 
 The [complete Narratio example](../../examples/pipeline.full.annotated.yml)
 records the exact current constraints for all ten D&D lanes. Treat the linked
@@ -25,19 +25,38 @@ duplicate the complete schemas.
 
 When `pipeline.notarius.enabled` is true, Narratio resolves the executable,
 configuration path, input path, output directory, and working directory to
-absolute paths. Narratio requires the Notarius v0.6.0 CLI contract when
+absolute paths. Configured references require support for the `--reference`
-references are configured and invokes each binding as a separate argument
+contract introduced in Notarius v0.6.0. Cache controls require support for the
-before `--json`:
+selected `--resume` and `--chunk_cache` flags. Notarius v0.7.0 is the tested
+cache integration baseline, not an unconditional minimum version; Narratio
+does not impose a runtime version gate. Each reference binding is a separate
+argument before `--json`. When `pipeline.notarius.config_profile` is present,
+its exact value is another argument pair before `--json`:
 
 ```text
-notarius run <pipeline_id> --config <config_path> --input <trimmed_json> --output-dir <staging_dir> [--reference <selector>=<verified_snapshot_path>]... --json
+notarius run <pipeline_id> --config <config_path> --input <trimmed_json> --output-dir <staging_dir> [--resume] [--chunk_cache <mode>] [--reference <selector>=<verified_snapshot_path>]... [--config-profile <name>] --json
 ```
 
-Reference paths are absolute invocation-local snapshots streamed from the
+Notarius v0.7.0 is a known supporting version for `--config-profile`; using the
-manifest-verified canonical files prepared inside the current Narratio session
+option requires a compatible Notarius executable, but deployments that omit the
-workspace. Narratio verifies snapshot checksum and size before and after the
+field acquire no additional version requirement. Omitted or null configuration
-subprocess, and passes only configured bindings, ordered lexically by normalized
+adds no flag. Supplied empty, `default`, and named selectors are forwarded
-selector, as direct argument-vector entries without shell interpretation. A CLI
+without normalization so Notarius can apply its own ConfigKit semantics. This
+option selects a Notarius configuration overlay, not a PromptKit profile through
+`--llm-profile`, and Narratio never substitutes its own selected profile name.
+A missing or invalid downstream overlay is an ordinary Notarius subprocess
+failure: Narratio does not retry without the selector or fall back to another
+profile.
+
+Reference paths are absolute stable snapshots streamed from manifest-verified
+canonical files prepared inside the current Narratio session workspace. They
+live at `cache/notarius/references/<sha256>/<prepared-basename>` and retain the
+full lowercase content digest. Narratio verifies snapshot checksum and size
+before and after the subprocess, reconstructs missing or corrupt regular files
+from a still-valid prepared source, and passes only configured bindings,
+ordered lexically by normalized selector, as direct argument-vector entries
+without shell interpretation. Symlinks, directories, other non-regular
+conflicts, and prepared-source mismatches fail rather than being deleted. A CLI
 binding takes precedence over a matching external path in Notarius
 configuration. Narratio never emits `--without-reference`.
 
@@ -75,9 +94,41 @@ It does not pass a Narratio session ID or run `notarius config validate`
 automatically; the configured working directory and Narratio's minimal child
 environment apply to the subprocess.
 
+Ordinary extraction maps `pipeline.notarius.resume: true` to `--resume` and a
+nonempty `pipeline.notarius.chunk_cache` to `--chunk_cache <mode>`. Forced
+extraction always omits `--resume` and supplies `--chunk_cache refresh`.
+Notarius owns checkpoint enablement, recording, identity, and both cache roots;
+Narratio neither reads nor synthesizes its configuration. Use explicit
+persistent roots in Notarius when reuse must span subprocess invocations.
+Changing a reference path/digest or other upstream identity input correctly
+causes a cold miss. Chunk refresh bypasses lookup and publishes the accepted
+replacement for the active source; it does not delete unrelated plans or
+checkpoint state.
+
+When `pipeline.notarius.llm_api_key` is absent or null, Narratio adds no
+credential to that environment. When configured, the field names an environment
+variable whose already-loaded nonempty value is forwarded under that exact
+name. Operators must use the same name as the `api_key_env` in the selected
+Notarius/PromptKit profile. Narratio does not inspect the Notarius configuration
+to infer a provider or destination name, and it does not forward unrelated
+credentials from its parent environment or secrets directory.
+
+The selected name is registered with Narratio's shared streaming redactor.
+Credential bytes written by the child to captured stdout, captured stderr, or
+stderr-derived failure diagnostics are replaced with `<redacted>`, including
+custom names not known to the built-in sensitive-name list. Narratio does not
+serialize the credential into arguments, stage metadata, manifests, or
+generated configuration.
+
+This captured-stream protection is not a filesystem sandbox. Notarius remains
+responsible for keeping credentials out of files it writes directly, including
+bundle artifacts and its own diagnostics. Narratio does not scan or rewrite
+arbitrary downstream files and cannot promise redaction of transformed or
+encoded credentials.
+
 ## Accepted Result
 
-Narratio's supported invocation baseline is Notarius v0.6.0. The accepted
+Narratio's tested invocation baseline is Notarius v0.7.0. The accepted
 receipt remains `notarius.run-result.v2`; reference flags do not change the
 receipt or ten-lane output contract. The receipt
 must identify the configured pipeline, and its `index_file` must be exactly
@@ -102,6 +153,8 @@ version, and, when configured, module key. Missing, duplicate, rejected, or
 incompatible required lanes fail extraction even if Notarius exited zero. A
 configured lane whose v2 validation summary is `rejected` or `incomplete` also
 fails extraction.
+An accepted reused producer may report `producer_attempt_count: 0`; Narratio
+preserves that valid summary rather than treating it as a missing field.
 Unconfigured lanes may remain in the preserved bundle but do not become
 selectable Narratio sources.
 
@@ -130,3 +183,18 @@ Configuration fields and defaults are in [Configuration](../config.md).
 Operator paths, rerun procedures, and bundle retention are in
 [Operations](../operations.md). See [Troubleshooting](../troubleshooting.md)
 for failure recovery.
+
+## Opt-in Integration Test
+
+The production-boundary cache test requires an absolute path to a locally
+built Notarius v0.7.0-compatible executable. It uses only a local
+OpenAI-compatible `httptest` provider and temporary cache/config/output roots:
+
+```sh
+NARRATIO_TEST_NOTARIUS_BINARY=/absolute/path/to/notarius \
+  GOWORK=off go test ./internal/stage \
+  -run '^TestNotariusCacheReuseIntegration$' -count=1 -v
+```
+
+When the variable is unset, the normal test suite skips this test and never
+searches `PATH`, a sibling checkout, the network, or a real provider.

docs/integrations/whisperx.md

@@ -17,11 +17,20 @@ Narratio sends an HTTP `POST` to the configured transcription URL using
 The server must return a `2xx` response whose body is valid JSON. Narratio does
 not currently require a more specific response schema at this boundary.
 
-The transcription URL must be an absolute `http` or `https` URL. The audio body
+The transcription URL must be an absolute `http` or `https` URL. Each
-is streamed through a fresh multipart writer for every attempt, so its memory
+application attempt creates one bounded multipart framing and streams the audio
-use is bounded by the transport buffer rather than by the complete audio file.
+from an open file between that framing; it does not buffer the complete audio
+or spool a multipart copy. The file field precedes the language field.
 WhisperX response acquisition is capped at 10 MiB.
 
+The initial request body and any transport-requested replay use the same
+multipart boundary and framing. Every body opens an independent audio handle
+and replay starts at the beginning. Narratio closes all bodies created for the
+attempt on response, failure, timeout, or cancellation, including when a
+transport abandons an earlier body. Genuine source read/close failures remain
+request failures; deliberate early closure of an abandoned original does not
+poison a valid replay.
+
 ## Request And Result Contract
 
 Each adapter request identifies a speaker, a readable audio file, and the
@@ -43,6 +52,11 @@ transcript output.
 - Narratio waits the configured retry delay between attempts and aborts that
   wait when the parent context is canceled.
 
+Transport replay occurs inside one application attempt and does not consume an
+entry from the configured retry budget or increment the reported attempt
+count. The standard HTTP redirect policy remains in effect; body replay can
+also support body-preserving redirects.
+
 ## Validation And Failure Semantics
 
 Client construction rejects a missing or non-HTTP(S) absolute transcription URL,
@@ -55,12 +69,19 @@ failure to install the output causes the transcription to fail. Errors include
 attempt context, and the result retains attempts, final status when available,
 and elapsed duration for diagnostics.
 
+Replay makes a fresh request body available to the HTTP transport; it does not
+provide an exactly-once server guarantee and does not prove recovery from every
+proxy or protocol-level failure. A server may have received work before the
+client learns that a request failed. WhisperX operations should therefore be
+safe to retry for the same input when practical.
+
 ## Determinism And Concurrency
 
 Each audio request has stable multipart field names, and successful bytes are
 installed atomically. The transcribe stage may process speaker files in
-parallel, bounded by the configured concurrency. It records results in stable
+parallel, bounded by the configured concurrency. Each validated speaker is
-speaker order after all work completes; any speaker failure fails the stage.
+checkpointed independently; any speaker failure still fails the aggregate
+stage, while committed earlier speakers remain reusable on an ordinary retry.
 
 ## Related Canonical Docs
 

docs/internal/adapters.md

@@ -65,6 +65,14 @@ Notarius is composed only when extraction is enabled; the extract stage owns
 prepared reference resolution, receipt, bundle, and configured-lane policy.
 The adapter validates the ordered selector/absolute-path pairs and is the sole
 owner of serializing them as repeated `--reference` arguments before `--json`.
+It also serializes an effective resume request as `--resume` and a nonempty
+validated chunk mode as `--chunk_cache <mode>`. The extract stage, not the
+adapter, resolves force precedence before constructing the request.
+Its request may also carry one already-resolved opaque ConfigKit secret
+reference. Only the Notarius adapter reads that value, rejects an unresolved or
+empty programmatic reference, and maps the exact configured name/value into the
+shared subprocess override and sensitive-name fields. It never rereads the
+parent environment. A nil reference preserves the previous invocation.
 
 Application-owned object-store construction loads configured filesystem
 secrets before invoking the invocation's storage factory. Production commands

docs/internal/configuration.md

@@ -168,6 +168,10 @@ Configuration stores credentials as ConfigKit typed references. A successful
 load resolves their values inside the opaque typed boundary, while this safe
 projection serializes only `EnvName()` identities. Credential-value changes are
 therefore never hashed; reference-name changes remain ordinary provenance.
+The optional Notarius credential follows the same path even for disabled or
+resumable extraction; normalization copies the opaque reference without reading
+or resolving it again. Direct YAML serialization has a configuration-owned safe
+projection so only the reference name can leave this boundary.
 `recomputePipelineEffectiveDigest` is the single package-owned refresh point
 for later runtime expansion.
 

docs/internal/manifest.md

@@ -50,6 +50,45 @@ The model admits these stage states:
 - `stale`
 - `interrupted`
 
+### Transcribe-owned speaker state
+
+A `transcribe` stage record may carry `transcribe_state_version: 1` and a
+`transcribe_speakers` map keyed by the existing derived speaker ID. The version
+is the authority marker: a versioned empty map means that no earlier speaker
+completion is reusable. Absence of both fields is accepted as legacy
+aggregate-only state so current Narratio can read older manifests.
+
+Each map entry represents one completed speaker only. It binds a versioned
+fingerprint to the session-relative audio path, audio SHA-256 and size, one
+canonical `transcript_raw` output with its path, SHA-256 and size, and the
+producer run ID. Paths must be canonical and session-relative, checksums must
+be lowercase SHA-256 values, and the record and output producer identities
+must agree. Other stages cannot carry this transcribe-owned state.
+Audio size is nonnegative; WhisperX determines whether that audio can be
+transcribed. Output size remains positive and the transcript must be valid JSON.
+
+Transcribe reconciles this collection against the current prepared audio set
+and observable WhisperX semantics. Missing or corrupt regular outputs become
+work; unsafe or non-regular evidence is rejected. It saves the reconciled
+collection before HTTP dispatch and saves a detached candidate after each
+validated completion. Only after a save succeeds is the candidate installed as
+live authority. Canonical bytes produced before an unsuccessful save are not a
+completion record.
+
+Aggregate transcribe status still describes the whole invocation. A failed,
+running, stale, or interrupted aggregate may therefore retain reusable speaker
+records, while aggregate outputs are declared only after the current
+collection is complete. Ordinary retry reconciles and reuses those records.
+Force first checkpoints an empty current collection, preventing later retries
+from reviving pre-force results.
+
+Older aggregate-only transcribe success is conservatively regenerated once
+when transcribe is selected because it does not bind individual outputs to the
+audio bytes used. The session-manifest schema identifier remains
+`narratio.session-manifest.v1`; this additive state is accepted by current
+Narratio, but older strict-decoding binaries may reject manifests after these
+fields have been written.
+
 ### Analyze-owned artifact state
 
 Every `analyze` stage record carries `analyze_state_version: 1` and an
@@ -156,10 +195,10 @@ establish a current immutable snapshot.
 
 Manifest replacement provides atomic visibility, not a crash- or power-loss
 durability guarantee. Callers reload after a returned save error before retrying.
-An analyze checkpoint error leaves the prior manifest as per-artifact authority.
+A transcribe or analyze checkpoint error leaves the prior manifest collection
-The runner then attempts to persist the bounded failed/stale retry collection;
+as authority. The runner then attempts to persist the aggregate failure; if
-if that terminal save also fails, its error is joined with the originating
+that terminal save also fails, its error is joined with the originating failure
-failure and the next invocation must reconcile from the last readable manifest.
+and the next invocation must reconcile from the last readable manifest.
 
 ## Execution Semantics
 
@@ -193,11 +232,11 @@ only fields returned by the new result. Marking a record stale does not clear
 those details because resume validation and diagnosis may still require them
 before execution begins.
 
-Aggregate lifecycle clearing deliberately preserves the analyze-owned
+Aggregate lifecycle clearing deliberately preserves both the transcribe-owned
-per-artifact collection. This lets later reconciliation replace only evaluated
+speaker collection and the analyze-owned per-artifact collection. This lets
-entries without erasing unrelated current results. Other stages retain their
+later reconciliation replace only non-current entries without erasing durable
-existing aggregate-only lifecycle behavior and are forbidden from carrying the
+completions. Other stages retain aggregate-only lifecycle behavior and are
-analyze-specific fields.
+forbidden from carrying either collection.
 
 A stage may explicitly return a skipped disposition and stable reason. The
 runner persists that outcome in the session manifest, clears older outputs,
@@ -228,7 +267,7 @@ evidence and focused durable validators:
 | Work | Reuse authority | Focused owners |
 | --- | --- | --- |
 | prepare | aggregate semantic fingerprint | [prepare](stage-prepare.md) |
-| transcribe | aggregate semantic fingerprint | [transcribe](stage-transcribe.md), [WhisperX](../integrations/whisperx.md) |
+| transcribe speakers | aggregate semantic fingerprint plus per-speaker input/output reconciliation | [transcribe](stage-transcribe.md), [WhisperX](../integrations/whisperx.md) |
 | merge | aggregate semantic fingerprint | [merge](stage-merge.md), [Seriatim](../integrations/seriatim.md) |
 | polish | aggregate semantic fingerprint | [polish](stage-polish.md), [Audita](../integrations/audita.md) |
 | normalize | aggregate semantic fingerprint | [normalize](stage-normalize.md), [Seriatim](../integrations/seriatim.md) |
@@ -310,6 +349,7 @@ where the last session transition can require operator interpretation.
 - Remote commit model and readers: `internal/artifacts/remote_commit.go`,
   `internal/artifacts/current_state_commit.go`,
 - Persistence and validation: `internal/manifest/store.go`
+- Transcribe speaker state: `internal/manifest/transcribe_state.go`
 - Package tests: `internal/manifest/*_test.go`
 - Assembled execution behavior: `internal/app/runner_test.go`,
   `internal/app/run_stage_test.go`

docs/internal/overview.md

@@ -53,11 +53,12 @@ adapters. The normative rules for these relationships remain in
 [Architecture](../policy/architecture.md).
 
 Command execution normalizes one private dependency value per invocation.
-Configuration reads, secret-directory reads, remote downloads, object-store
+Pipeline configuration-path discovery, configuration reads, secret-directory
-construction, and restore phase functions use that value throughout the
+reads, remote downloads, object-store construction, and restore phase functions
-command. Public command entry points supply production defaults, while focused
+use that value throughout the command. Public command entry points supply the
-tests replace only the external or sequencing boundary they exercise without
+canonical discovery and production defaults, while focused tests may provide
-mutating package state.
+invocation-owned discovery candidates or replace only the external or sequencing
+boundary they exercise without mutating package state.
 
 Pipeline execution and `session plan` share the same inclusive contiguous-range
 model and the same pure pre-execution decision over recorded status, force, and

docs/internal/stage-extract.md

@@ -19,12 +19,17 @@ procedures belong in [Operations](../operations.md).
 1. resolves the final trimmed transcript from the shared artifact catalog;
 2. resolves every configured prepared reference through the shared
    manifest-authoritative identity resolver before creating run-local output;
-3. streams each verified reference into an invocation-local snapshot and
+3. resolves each reference to a stable content-addressed session snapshot,
-   rejects any source change observed while copying;
+   reusing verified bytes or reconstructing a missing/corrupt regular entry,
+   and rejects any source change observed while copying;
 4. fingerprints the byte- and provenance-bearing Notarius invocation evidence,
-   including sorted reference identities;
+   including sorted reference identities and the explicit downstream
+   configuration-profile selection;
 5. creates a run-local staging directory and invokes the injected
-   `notarius.Runner`;
+   `notarius.Runner`, carrying the optional already-resolved credential
+   reference without exposing its value, the optional exact configuration
+   profile, plus effective resume and chunk-cache controls after force
+   precedence;
 6. revalidates the reference snapshots, then validates the v2 successful
    receipt, confined index, management documents, configured required lane
    descriptors, validation summaries, and regular payload files;
@@ -41,14 +46,22 @@ Narratio run ID, the resolved trimmed-input identity, and invocation
 fingerprint. The input identity binds the exact transcript bytes, canonical
 source ID, producer stage/output/run identity, and resolution provenance.
 Reference metadata contains only selector, source ID, canonical session-relative
-path, checksum, and size; adapter requests receive selector and absolute
+path, checksum, and size; adapter requests receive selector and absolute stable
-invocation-local snapshot path, never payload contents. Snapshot bytes must
+snapshot path, never payload contents. Snapshot bytes must
 match the prepared identity both before and after Notarius runs, so a concurrent
 prepared-file replacement cannot make recorded provenance describe different
 bytes from those supplied to Notarius.
 Validation completes before the single durable rename, so a rejected result
 cannot expose a partial durable bundle.
 
+Snapshot destinations are owned by `internal/artifacts` under
+`cache/notarius/references/<sha256>/<prepared-basename>`. They contain no run ID
+or timestamp and can be reused across invocations. Identical bytes and basename
+share a verified file; changed bytes select a different digest directory.
+Unsafe path components and non-regular conflicts fail without recursive
+deletion. Snapshot paths are delivery details and never become manifest output
+evidence or prerequisites for reuse of an already complete extract bundle.
+
 Any executed extraction outcome that replaces a different effective outcome
 marks succeeded analysis and delivery dependents stale. Render is an independent
 sibling and remains current. Repeating the same disabled self-skip with no
@@ -59,17 +72,28 @@ outputs is stable and does not repeatedly invalidate dependent stages.
 Before the focused validator runs, the application compares extract's versioned
 semantic fingerprint. It covers enablement, Notarius pipeline identity, sorted
 reference selector/source mappings, sorted declared output contracts, and each
-canonical `narratio.extraction.<key>` output identity. It excludes executable,
+canonical `narratio.extraction.<key>` output identity. It also covers the
+explicit Notarius configuration-profile selection; omitted, empty, and exact
+`default` selectors share the base-selection identity. It excludes executable,
 timeout, working directory, config path, and private Notarius config contents.
+Credential presence, reference name, and resolved value are likewise
+operational-only and excluded. Ordinary command loading still resolves a
+selected reference before resume evaluation, but a credential-only change does
+not rerun a valid completed extraction or stale its dependents.
 
 `internal/stage/extract_resume.go` then permits a skip only when the existing
 stage record still matches the current byte- and provenance-bearing invocation
 evidence. That evidence covers the current direct trimmed-transcript identity,
 sorted prepared-reference identities, pipeline identity, and configured output
-contracts. The same reference helper and transcript identity are resolved again
+contracts, plus the same downstream profile-selection identity. The same
-for artifact evidence, so changing current transcript bytes, reference bytes,
+reference helper and transcript identity are resolved again for artifact
-or producer identity makes the prior extraction obsolete. Operational runner
+evidence, so changing current transcript bytes, reference bytes, producer
-settings do not invalidate otherwise current durable evidence.
+identity, or a named downstream selection makes the prior extraction obsolete.
+Operational runner settings do not invalidate otherwise current durable
+evidence. This includes `resume` and `chunk_cache`; changing them alone cannot
+make a complete extraction non-resumable. If extraction executes, ordinary
+runs forward the configured values, while force disables resume and selects
+`refresh`.
 
 A valid prepared-reference change makes extraction non-resumable. Missing,
 unsafe, or checksum-inconsistent prepared evidence is a hard validation error
@@ -82,10 +106,12 @@ contracts and provenance, regular-file status, and stored checksums. Missing or
 obsolete results are non-resumable and run again; unsafe filesystem conditions
 return an error rather than silently accepting or replacing data.
 
-Neither contract can observe files imported by Notarius configuration, profile
+This sensitivity is limited to the explicit downstream selector. Narratio's
-contents, prompt/module definitions, or other transitive inputs. Operators must
+own profile label and whole effective-configuration digest are not blanket
-force extraction after changing any such private input behind a stable
+extraction invalidators. Neither contract can observe files imported by
-identifier.
+Notarius configuration, profile contents, prompt/module definitions, or other
+transitive inputs. Operators must force extraction after changing any such
+private input behind a stable identifier.
 
 ## Failure Behavior
 
@@ -110,9 +136,13 @@ recovery.
   `internal/stage/extract_resume.go`,
   `internal/stage/extract_test.go`,
   `internal/stage/semantic_contracts_delivery.go`
+- Stable snapshot materialization and verification:
+  `internal/stage/extract_references.go`
 - Subprocess boundary: `internal/adapters/notarius/subprocess.go`,
   `internal/adapters/notarius/subprocess_test.go`
 - Catalog hydration: `internal/artifacts/extraction_catalog.go`,
   `internal/artifacts/extraction_catalog_test.go`
 - Composition and downstream behavior: `internal/app/runner_test.go`,
   `internal/stage/analyze_test.go`, `internal/stage/publish_test.go`
+- Opt-in Notarius v0.7.0 production-boundary coverage:
+  `internal/stage/notarius_cache_integration_test.go`

docs/internal/stage-merge.md

@@ -17,7 +17,11 @@ Normalize raw transcript inputs and merge into base transcript via Seriatim.
 
 ## Key Behavior
 
-- discovers and validates raw transcript inputs.
+- discovers and validates raw transcript inputs. For versioned transcribe
+  state, discovery requires aggregate transcribe success and consumes only the
+  aggregate outputs that exactly match the current per-speaker collection.
+  Partial checkpoints and orphaned files are not merge inputs. Legacy/manual
+  workflows without versioned speaker state retain directory discovery.
 - normalizes each raw transcript (`seriatim.Normalize`) into run-local scratch output.
 - merges normalized inputs (`seriatim.Run`) into base transcript.
 - validates merged transcript and optional report JSON.
@@ -26,6 +30,8 @@ Normalize raw transcript inputs and merge into base transcript via Seriatim.
 ## Invariants
 
 - merge always consumes normalized forms of raw inputs.
+- a versioned transcribe collection is usable only through its complete,
+  successful aggregate output declaration.
 - base transcript must validate before stage success.
 - report output is config-gated.
 

docs/internal/stage-transcribe.md

@@ -14,12 +14,19 @@ Generate raw per-speaker transcripts from prepared audio using WhisperX.
 
 ## Key Behavior
 
-- discovers prepared audio from manifest inputs or canonical audio directory.
+- discovers prepared audio from manifest inputs or the canonical audio
-- derives the transcript identity from the prepared `.flac` filename.
+  directory and derives each speaker identity from its `.flac` filename.
-- dispatches one WhisperX request per prepared file through a bounded errgroup.
+- hashes the current audio and reconciles it with the versioned per-speaker
-- validates each output as JSON.
+  completion collection before starting HTTP work.
-- writes run-local outputs then materializes canonical transcript outputs only
+- reuses only records whose audio identity, observable WhisperX semantics,
-  after every planned request succeeds.
+  canonical output location, JSON, checksum, and size remain current.
+- durably checkpoints the reconciled collection before dispatch, then sends
+  only missing or obsolete speakers through the bounded worker group.
+- validates each successful run-local response, rechecks the audio bytes,
+  materializes the canonical raw transcript, and checkpoints that speaker
+  before accepting another completion.
+- rebuilds aggregate stage outputs in stable speaker order from the complete
+  current collection, including records produced by earlier invocations.
 
 ## Invariants
 
@@ -28,21 +35,48 @@ Generate raw per-speaker transcripts from prepared audio using WhisperX.
 - output path returned by adapter must match requested output path.
 - an empty adapter result path means the requested path; adapters cannot select
   an alternate destination.
-- each successful output is validated before stage success, and cancellation or
+- candidate collection construction, manifest save, and installation into live
-  incomplete dispatch cannot be reported as a successful result.
+  state are serialized. Expensive hashing and HTTP work remain outside that
+  critical section.
+- a canonical file has no completion authority until its manifest checkpoint
+  succeeds. A save failure preserves the last successfully committed
+  collection for ordinary retry.
+- each successful output is validated before its checkpoint, and cancellation,
+  incomplete dispatch, or a failed aggregate save cannot be reported as
+  aggregate stage success.
+- removed audio inputs are omitted from the current collection and aggregate
+  output list; reconciliation does not delete arbitrary transcript files.
+- merge cannot consume a partial versioned collection: it requires transcribe
+  aggregate success and an exact match between current speaker records and
+  declared aggregate outputs.
 
 ## Resume Evidence
 
-Transcribe records a versioned semantic-configuration fingerprint containing
+Each completed speaker record binds the speaker ID, session-relative audio
-the Narratio-visible WhisperX service URL and recognition language. Changes to
+path, streamed audio checksum and size, the Narratio-visible WhisperX service
-either rerun transcription and stale its fixed descendants while leaving
+URL and recognition language, and the canonical transcript path, checksum,
-prepare reusable. Retry count/delay, concurrency, timeout, credentials, and
+size, and producer run. Changed audio bytes select that speaker for replacement;
-diagnostic locations are operational and do not change this evidence.
+a changed URL or language selects every speaker. Either case stales fixed
+descendants through the normal runner decision. Retry count/delay, concurrency,
+timeout, credentials, and diagnostic locations are operational and do not
+change this evidence.
+
+An ordinary retry reuses every valid speaker checkpoint even when aggregate
+transcribe status is failed, running, or stale. A succeeded stage is skipped only
+when its stored speaker set and aggregate output evidence also match the current
+collection. Otherwise, execution repairs those records without retranscribing
+reusable speakers and stales dependents through the normal runner path.
+`--force` first durably replaces
+the collection with an empty versioned collection, so a later ordinary retry
+cannot resurrect pre-force results; speakers checkpointed by that forced
+attempt remain reusable.
 
 WhisperX models or private service configuration not exposed by Narratio's
 adapter contract cannot be fingerprinted; use `--force` after changing them.
-An existing successful transcribe record without evidence reruns once when
+An older aggregate-only transcribe record has no trustworthy audio-to-output
-selected.
+binding. When transcribe is next selected, every current speaker is therefore
+generated once and recorded in the versioned collection; later invocations can
+reuse it normally.
 
 ## Related Contracts And Tests
 
@@ -51,6 +85,9 @@ selected.
 - [Configuration](../config.md#pipeline) owns concurrency and other
   operator-selected values.
 - Implementation and tests: `internal/stage/transcribe.go`,
+  `internal/stage/transcribe_reconciliation.go`,
+  `internal/stage/transcribe_execution_state.go`,
+  `internal/stage/transcribe_resume.go`,
   `internal/stage/transcribe_test.go`,
-  `internal/stage/semantic_contracts_initial.go`, and
+  `internal/stage/transcribe_reconciliation_test.go`, and
-  `internal/stage/semantic_contracts_initial_test.go`
+  `internal/stage/transcribe_checkpoint_test.go`

docs/internal/workspace.md

@@ -37,6 +37,12 @@ validates and renames the external bundle to the unique immutable Notarius
 bundle path supplied by `internal/artifacts`. Exact physical paths belong in
 [Operations](../operations.md#extraction-workflow).
 
+Prepared references delivered to Notarius use session-durable paths owned by
+`internal/artifacts` beneath
+`cache/notarius/references/<sha256>/<prepared-basename>`. These verified
+content-addressed snapshots are outside run-local layout, survive ordinary
+published-run cleanup, and are excluded from publish and restore enumeration.
+
 ## Locking
 
 `artifacts.LocalStore` enforces the single-writer session lock via an

docs/operations.md

@@ -116,8 +116,8 @@ Execution rules:
   perpetually rerun dependent work.
 
 Every aggregate stage except analyze currently provides semantic-configuration
-evidence; analyze retains its more precise per-artifact fingerprints and
+evidence; transcribe additionally reconciles per-speaker completion evidence,
-validator.
+while analyze retains its more precise per-artifact fingerprints and validator.
 Prepare additionally validates current stable/local/S3 source identity and the
 checksums of its durable prepared copies before reuse. Changed bytes, audio
 membership, S3 object identity, or missing/tampered copies rerun prepare and
@@ -187,7 +187,68 @@ shared session lifecycle. In particular, render does not require Notarius or
 Scriptorium, extract does not require Scriptorium, and analyze does not require
 the transcription, Seriatim, Audita, or Notarius adapters.
 
-For the common post-transcript development loop, use:
+### Transcription continuation and replacement
+
+Transcribe checkpoints each validated speaker independently. If a later
+speaker exhausts HTTP retries, the process is canceled, or the aggregate stage
+save fails, the aggregate stage is not successful and downstream merge cannot
+consume the partial set. The last successfully saved speaker records and their
+canonical `transcripts/raw/<speaker>.json` files remain durable, however.
+
+After correcting the underlying problem, retry normally:
+
+```bash
+narratio run-stage transcribe 2026-04-04
+```
+
+Narratio hashes the current prepared audio, validates recorded transcript JSON,
+checksum, size, and location, and calls WhisperX only for missing or obsolete
+speakers. A changed audio file replaces only its speaker; a changed WhisperX
+URL or language makes every current speaker non-reusable. Retry, timeout, and
+concurrency tuning do not invalidate completed speakers.
+
+Use force only when every current transcript must be replaced, including after
+a WhisperX model or private server-side configuration changes behind the same
+URL and language:
+
+```bash
+narratio run-stage transcribe 2026-04-04 --force
+```
+
+Force durably clears the reusable collection before sending requests. If that
+forced attempt fails, a later ordinary retry reuses only replacement speakers
+checkpointed after the reset; it does not revive pre-force results. Do not edit
+speaker checksums or copy older JSON into the canonical directory to influence
+reuse.
+
+The first current Narratio invocation that selects transcribe for an older
+aggregate-only manifest retranscribes every current speaker once because the
+old record cannot prove which audio bytes produced each file. Subsequent runs
+reuse the new versioned evidence normally. The overall session-manifest schema
+identifier is unchanged, but older strict-decoding Narratio binaries may reject
+a manifest after current Narratio writes the additive speaker fields; retain a
+backup or complete the upgrade before relying on downgrade.
+
+Restoring a manifest does not implicitly publish or restore every raw speaker
+file. If a recorded canonical transcript is absent locally, ordinary
+reconciliation schedules that speaker again. Removing run directories does not
+remove canonical checkpointed transcripts and does not by itself invalidate
+them.
+
+## Artifact Development Workflows
+
+Choose the narrowest workflow that matches the intended replacement:
+
+| Intent | Command | Preserved and rebuilt state |
+| --- | --- | --- |
+| Rebuild analysis only | [`narratio analyze 2026-04-04`](./cli.md#analyze) | Preserves transcripts and the current extraction bundle; force-runs selected analysis artifacts and their required analysis prerequisites. |
+| Rebuild extraction and analysis | [`narratio regenerate-artifacts 2026-04-04`](./cli.md#regenerate-artifacts) | Preserves transcripts; force-runs the complete configured extraction bundle, then selected analysis. `--artifacts` narrows analysis only. |
+| Continue bounded work normally | [`narratio run 2026-04-04 --from extract --through analyze`](./cli.md#run) | Uses ordinary resume decisions: current extraction and analysis can be skipped, while incomplete or obsolete work runs. |
+
+All three stop before publication. Inspect the results and run
+[`narratio publish`](./cli.md#publish) separately when delivery is intended.
+
+For the extraction-plus-analysis development loop, use:
 
 ```bash
 narratio regenerate-artifacts 2026-04-04
@@ -220,6 +281,30 @@ earlier checkpoints are reused and execution resumes with failed, stale, or
 missing work in dependency order. `--force` is unnecessary unless the operator
 intends to replace otherwise-current artifacts.
 
+### Developing With A Notarius Configuration Profile
+
+A Narratio development overlay can explicitly select a Notarius overlay without
+requiring the names to match. For example, `profiles/testing.yml` may contain:
+
+```yaml
+notarius:
+  config_profile: downstream-economy
+```
+
+Selecting Narratio's `testing` profile then supplies `downstream-economy` only
+when extraction executes. Switching that explicit selector makes a recorded
+extraction non-current and reruns it when `extract` is in the selected stage
+range; the usual dependent invalidation then applies. Selecting a profile does
+not create a separate workspace or retain a separate current extraction result.
+
+Narratio cannot observe edits inside Notarius configuration behind an unchanged
+selector. Force extraction after such an edit when a replacement is intended.
+Use `regenerate-artifacts` when both extraction and analysis must be rebuilt;
+use `analyze` when the existing extraction bundle should be preserved. Field
+semantics belong in [Configuration](./config.md#notarius-configuration-profile),
+and the exact downstream invocation belongs in the
+[Notarius integration contract](./integrations/notarius.md#invocation).
+
 ## Artifact Selection
 
 For a configured artifact family, selecting its family key expands to every
@@ -260,9 +345,14 @@ are not selectable or published implicitly.
 Configured Notarius references resolve only from the current manifest-backed
 prepared inputs. Their canonical locations are `inputs/party.yml`,
 `inputs/players.yml`, `inputs/glossary.yml`, and, when configured,
-`inputs/spell_catalog.json`. Extraction supplies Notarius with verified copies
+`inputs/spell_catalog.json`. Extraction supplies Notarius with verified,
-under `runs/<run_id>/extract/references/` so a concurrent refresh of canonical
+content-addressed copies under
-prepared files cannot change the bytes consumed by an in-flight invocation.
+`cache/notarius/references/<sha256>/<prepared-basename>`. The full lowercase
+SHA-256 digest identifies the reference bytes, so retries and later invocations
+reuse the same path while changed bytes select a new path. Older snapshots are
+retained and are not current artifact evidence. A concurrent refresh of
+canonical prepared files therefore cannot change the bytes consumed by an
+in-flight invocation.
 For a canonical party, preparation retains the validated authored party bytes
 at `inputs/party.yml` and generates `inputs/players.yml` from that roster.
 The manifest records their checksums separately, with the players input marked
@@ -297,6 +387,28 @@ Notarius extraction validates its run-local bundle and moves it once to the
 unique durable bundle path. A pre-existing durable destination is a collision;
 no duplicate promotion tree is created.
 
+`pipeline.notarius.resume` and `pipeline.notarius.chunk_cache` control work
+inside an executed Notarius invocation. Ordinary extraction forwards their
+configured values. Forced extraction always disables checkpoint loading and
+requests chunk-plan `refresh`, even when the configured mode is `bypass`.
+Refresh regenerates and replaces only the active input's accepted chunk plan;
+it is not cache deletion.
+
+Notarius checkpoint recording must be enabled in the deployed Notarius
+configuration. Narratio neither creates a Notarius pipeline/configuration nor
+reads it to infer checkpoint availability. Configure explicit persistent
+Notarius chunk-plan and checkpoint roots when reuse must survive separate
+Narratio subprocesses. A changed reference, transcript, selected profile,
+profile content, endpoint, or other Notarius checkpoint identity input can
+produce a legitimate cold miss.
+
+There are two independent resume boundaries: Narratio may skip a completed
+`extract` stage without invoking Notarius, while `--resume` allows Notarius to
+reuse compatible accepted work only after Narratio has decided extraction must
+execute. Deleting Narratio's local reference snapshots does not invalidate a
+complete durable extraction; missing snapshots are reconstructed only when a
+later extraction actually runs.
+
 ## External Command Lifecycle
 
 When an external command is cancelled or times out, Narratio terminates its
@@ -337,13 +449,13 @@ narratio run-stage extract 2026-04-04 --force
 Narratio automatically reruns extraction when its recorded invocation contract,
 prepared Narratio reference identities, or durable output validation changes.
 The semantic portion covers Notarius enablement, pipeline identity, declared
-reference mapping, and output contracts. Executable, timeout, working directory,
+reference mapping, output contracts, and the explicit Notarius configuration
-and private config-file paths are operational and do not invalidate a current
+profile selector. Executable, timeout, working directory, and private
-result.
+config-file paths are operational and do not invalidate a current result.
-It cannot fingerprint configuration files, profiles, prompts, modules, or
+It cannot fingerprint configuration or profile contents, prompts, modules, or
 other references loaded transitively by Notarius itself. Force extraction after
-changing any of those inputs, even when the top-level Narratio and Notarius
+changing any of those inputs behind an unchanged selector, even when the
-config paths remain the same. A forced extract
+top-level Narratio and Notarius config paths remain the same. A forced extract
 marks successful downstream stages stale. Ordinary extraction failures or
 outcome changes also stale affected downstream stages, while an identical
 repeated `notarius_disabled` self-skip does not repeatedly invalidate them.
@@ -509,6 +621,7 @@ Durable session paths:
 - `logs/**`
 - `config/**`
 - `runs/**`
+- `cache/notarius/references/<sha256>/<prepared-basename>`
 
 `manifest.json` is the versioned session-progress document. Narratio accepts
 only `narratio.session-manifest.v1`. Do not edit unsupported session state to
@@ -519,6 +632,13 @@ relevant workflow requires.
 Validated Notarius bundles live below `artifacts/notarius/{run_id}/`; receipt,
 stderr, and pre-promotion output remain in the producing run's `extract`
 directory as described in [Extraction Workflow](#extraction-workflow).
+Stable reference snapshots live in the session cache path above. Ordinary
+published-run cleanup removes its selected run-local target but retains this
+cache, and publish/restore never enumerate it as an artifact. Remove a snapshot
+or digest directory manually only while no command is active for the session;
+regular missing or corrupt content is reconstructed on the next executed
+extraction, while symlinks, directories, and other unsafe conflicts must be
+investigated and removed deliberately.
 
 Run-local layout:
 

docs/releases/v2.1.0.md

@@ -0,0 +1,70 @@
+# Narratio v2.1.0
+
+This release adds explicit Notarius credential forwarding and cache reuse,
+with predictable forced regeneration and clearer artifact-development guidance.
+
+## Summary
+
+Narratio can pass one typed API-key reference to Notarius and opt into reuse of
+its accepted execution checkpoints. Stable, verified reference snapshots allow
+unchanged references to retain their cache identity across Narratio invocations.
+Configuration loading now uses ConfigKit v0.3.0.
+
+## Compatibility
+
+The new `notarius.llm_api_key`, `notarius.resume`, and `notarius.chunk_cache`
+fields are optional. Existing v2 configuration needs no schema migration.
+Configured credential references must resolve during configuration loading,
+even when extraction will not execute; omitted references add no requirement.
+
+Forced extraction now omits Notarius checkpoint loading and requests chunk-plan
+refresh. This includes `regenerate-artifacts`, which remains an alias for a
+forced run from extract through analyze. `analyze` continues to force analysis
+only, preserving extraction results and transcripts.
+
+Notarius v0.7.0 is the tested cache integration baseline, not an unconditional
+minimum-version gate. The executable must support the flags selected for the
+invocation, including `--chunk_cache refresh` for forced extraction. Reference
+bindings retain the contract introduced in Notarius v0.6.0. Receipt and artifact
+schemas are unchanged; reused producers may report zero production attempts.
+
+Supported release platforms remain Linux amd64/arm64 and best-effort macOS
+arm64. macOS validation is cross-compilation, not native runtime testing.
+
+## Upgrade
+
+No special migration is required for existing v2 configuration. To use the new
+features:
+
+- Declare `notarius.llm_api_key` with the environment-variable name expected by
+  the deployed Notarius profile, supplying its value through the existing
+  environment or secrets-directory mechanism.
+- Enable checkpoint recording in Notarius configuration before setting
+  Narratio's `notarius.resume: true`. Prefer explicit persistent Notarius cache
+  roots for service deployments. An optional `notarius.chunk_cache` overrides
+  its ordinary chunk-plan policy.
+- Expect an initial checkpoint miss when moving from old run-local reference
+  paths to stable session snapshots. No migration or deletion of old caches is
+  required. Force refreshes the current input's plan, not the whole cache.
+- Use `narratio analyze SESSION` for analysis-only iteration, and
+  `narratio regenerate-artifacts SESSION` when extraction should also be rebuilt.
+
+See [Configuration](../config.md), the
+[Notarius integration contract](../integrations/notarius.md), and
+[Artifact Development Workflows](../operations.md#artifact-development-workflows)
+for current details.
+
+## Changes
+
+- Upgraded ConfigKit from v0.1.2 to v0.3.0 and isolated pipeline-discovery tests
+  from machine configuration.
+- Added optional typed Notarius credentials, exact-name environment delivery,
+  safe configuration projections, and captured-stream redaction for custom names.
+- Added Notarius resume and chunk-cache controls with force taking precedence.
+- Added verified, content-addressed session reference snapshots that survive
+  ordinary run cleanup without becoming published artifacts.
+- Preserved relative-workspace support for snapshot delivery and confinement.
+- Kept credentials and cache-policy controls outside extract's semantic resume
+  identity, so operational changes alone do not invalidate completed results.
+- Added an opt-in real Notarius integration test using a local provider to
+  verify reuse, partial-failure recovery, and forced refresh without paid calls.

docs/releases/v2.1.1.md

@@ -0,0 +1,33 @@
+# Narratio v2.1.1
+
+This release fixes configuration loading for publish rules that explicitly set
+requiredness while relying on a derived destination.
+
+## Summary
+
+Publish rules with a derivable source and omitted `dest` now load correctly
+whether `required` is omitted, explicitly true, or explicitly false. Previously,
+explicit requiredness could trigger ConfigKit's `resolve.unrecorded_change`
+diagnostic instead of accepting valid configuration.
+
+## Compatibility
+
+This is a backward-compatible bookkeeping correction. Publish schemas,
+destination derivation, requiredness defaults, and YAML syntax support are
+unchanged. Explicit destinations and explicit false values remain intact.
+No ConfigKit upgrade or publication/storage behavior change is involved.
+
+## Upgrade
+
+No special upgrade action or configuration migration is required. Operators
+need not add a derivable `dest`, remove explicit `required` values, or change
+flow-style YAML to block-style YAML. See the
+[configuration reference](../config.md#publish-configuration-summary).
+
+## Changes
+
+- Recorded derived publish destinations at ConfigKit's atomic sequence boundary
+  while retaining field-level resolution records.
+- Added real load/validation and safe effective-configuration regression coverage
+  for built-in and configured-artifact sources, explicit requiredness, and an
+  explicit destination that must remain unchanged.

docs/releases/v2.1.2.md

@@ -0,0 +1,26 @@
+# Narratio v2.1.2
+
+This release allows secrets directories to contain hidden metadata without
+preventing credential loading.
+
+## Summary
+
+ConfigKit v0.3.1 ignores dot-prefixed entries such as `.git`, `.gitignore`, and
+`.DS_Store` during secrets bootstrap. These entries no longer block otherwise
+valid credentials from loading and are omitted from bootstrap reports.
+
+## Compatibility
+
+This is a backward-compatible dependency bug fix. Configuration schemas,
+existing-environment precedence, and validation of non-hidden entries are
+unchanged. Hidden entries still count toward the directory entry limit.
+
+## Upgrade
+
+No special upgrade action or configuration migration is required. See the
+[credential configuration reference](../config.md) for secrets-directory usage.
+
+## Changes
+
+- Updated ConfigKit from v0.3.0 to v0.3.1.
+- Clarified hidden-entry handling in the secrets-directory documentation.

docs/releases/v2.2.0.md

@@ -0,0 +1,53 @@
+# Narratio v2.2.0
+
+This release adds resumable per-speaker transcription, replayable WhisperX
+uploads, and explicit Notarius configuration profile selection.
+
+## Summary
+
+Successfully checkpointed speaker transcripts survive later transcription
+failures. Ordinary retry reuses valid completed speakers and processes only the
+remaining work. WhisperX uploads can now be replayed by the HTTP transport
+without buffering whole audio files.
+
+## Compatibility
+
+Existing CLI commands, speaker identities, transcript formats, and pipeline
+ordering are unchanged. Session manifests gain optional per-speaker completion
+evidence. Older manifests remain readable, but older Narratio binaries may
+reject manifests containing the new fields; downgrading after transcription
+is not transparent.
+
+The optional `pipeline.notarius.config_profile` field selects a downstream
+Notarius configuration profile independently of Narratio's own profile. Using
+it requires a Notarius version supporting `--config-profile`; v0.7.0 is a known
+supporting version. Omitting the field retains downstream default selection.
+
+## Upgrade
+
+No configuration migration is required. When transcribe is next selected for
+an older aggregate-only manifest, all current speakers are transcribed once
+to establish reusable evidence. Previously unrecorded results from failed runs
+are not automatically imported.
+
+Use ordinary run/resume to retain valid checkpoints. Forcing transcribe resets
+reuse of prior results; an ordinary retry after a failed forced invocation can
+retain replacements already checkpointed by that attempt. See the
+[operations guide](../operations.md) and
+[Notarius profile configuration](../config.md#notarius-configuration-profile).
+
+## Changes
+
+- Persist validated speaker completions independently of aggregate stage status,
+  with serialized saves for concurrent work and input/output integrity checks.
+- Rebuild aggregate transcript references when speakers are removed or those
+  references need repair, without retranscribing otherwise-current speakers.
+- Keep removed and incomplete speaker results out of versioned merge inputs.
+- Permit checkpoint evidence for zero-byte audio when WhisperX accepts it;
+  service rejection still fails normally.
+- Provide fresh streaming multipart bodies for HTTP transport replay while
+  preserving application retries, cancellation, and resource cleanup. This
+  addresses the missing-body-replay limitation, not persistent upstream
+  protocol failures or exactly-once service execution.
+- Pass explicit Notarius configuration profiles through the CLI and include
+  their selection in extraction reuse decisions.

docs/roadmap/configkit-adoption.md

@@ -1,375 +0,0 @@
-# ConfigKit Adoption and Platform Simplification
-
-**Status:** Accepted; implementation pending
-
-## Purpose
-
-Narratio currently owns a substantial YAML configuration subsystem for strict
-decoding, explicit imports, additive composition, profile overlays, presence
-tracking, provenance, and effective-value inspection. ConfigKit was extracted
-from this implementation and now provides those generic responsibilities as a
-maintained library.
-
-Narratio 2.0 will adopt ConfigKit as its configuration foundation, remove the
-superseded generic infrastructure, and retain only Narratio-specific configuration
-policy and domain resolution. The same major release will narrow the supported
-platform set to the systems that Narratio is expected to run on in practice.
-
-This roadmap defines the desired contracts and end state. The
-[implementation plan](implementation.md) owns sequencing and completion gates.
-
-## Goals
-
-- Reduce Narratio-owned configuration code and tests by delegating generic YAML
-  mechanics to ConfigKit.
-- Establish one strict and explainable configuration lifecycle rather than
-  retaining parallel or compatibility loaders.
-- Preserve Narratio's application-specific defaults, validation, campaign/session
-  resolution, party handling, artifact-family expansion, digests, and CLI policy.
-- Make individual artifact definitions easy to organize, identify, inspect, and
-  reuse as dependencies of later artifacts.
-- Keep raw credentials out of YAML and adopt a predictable secrets-directory
-  convention that works before configuration loading.
-- Remove unsupported platform code and release obligations that provide no known
-  user value.
-- Deliver the resulting contract changes as Narratio v2.0.0 with a clear migration
-  guide.
-
-## Platform Contract
-
-Narratio's v2 platform matrix is:
-
-| Platform | Status | Required evidence and deliverables |
-| --- | --- | --- |
-| Linux amd64 | Primary, supported | Default tests, race checks, static analysis, build validation, and a release asset |
-| Linux arm64 | Primary, supported | Cross-build validation and a release asset; native validation is used when an appropriate runner is available |
-| macOS arm64 | Best effort | Cross-build validation and a release asset; native CI and platform-equivalent runtime guarantees are not required release gates |
-| macOS amd64 | Unsupported | No build gate, release asset, compatibility promise, or platform-specific maintenance |
-| Windows | Unsupported | No build gate, release asset, compatibility promise, or platform-specific maintenance |
-
-Windows- and Intel-Mac-specific code, tests, CI entries, release packaging, and
-documentation are removed when they no longer serve a supported build. Portable
-code should remain portable where doing so is natural, but accidental compilation
-on an unsupported target does not create a support commitment.
-
-Best-effort macOS arm64 support means Narratio intends to keep the target buildable
-and will consider reported defects when practical. Lack of a native runner or an
-unverified platform-specific behavior does not block a release. A target for which
-Narratio publishes an asset must still pass its configured cross-build gate.
-
-## ConfigKit Dependency and Ownership
-
-Narratio will depend on the tagged ConfigKit module at an exact reviewed version,
-initially `gitea.maximumdirect.net/eric/ConfigKit@v0.1.1`. ConfigKit is pre-1.0 and
-may make compatibility changes in later minor versions, so dependency upgrades are
-intentional changes accompanied by contract review and focused Narratio integration
-tests; Narratio does not follow an unpinned branch or automatically accept a newer
-minor release.
-
-ConfigKit owns:
-
-- bounded file, byte, and reader input;
-- the accepted YAML syntax and strict typed decoding;
-- import declarations, traversal, containment, and resource limits;
-- additive composition and conflict attribution;
-- selected-profile overlay semantics;
-- explicit input presence and source provenance;
-- application-default and recorded-resolution coordination;
-- structured configuration diagnostics;
-- secret-reference parsing and resolution;
-- secrets-directory loading and its safe report; and
-- detached effective configuration inspection supplied by its public result.
-
-Narratio owns:
-
-- pipeline, campaign, session, party, and runtime domain types;
-- configuration-file discovery and CLI selection;
-- concrete defaults, normalization, and semantic validation;
-- campaign/session identity and stable-input resolution;
-- canonical party parsing requirements and authored-byte retention;
-- character artifact-family expansion and generated ownership attribution;
-- root-relative interpretation of Narratio-owned runtime paths;
-- effective pipeline digests and semantic profile diffs;
-- command output and exit behavior; and
-- adapter and runtime initialization after configuration succeeds.
-
-Narratio must use ConfigKit through its public package. It must not import
-ConfigKit's private YAML implementation or reproduce ConfigKit's parser,
-composition, profile, provenance, or secret-bootstrap mechanics locally.
-
-## Configuration Format
-
-Narratio adopts ConfigKit's configuration conventions directly. The old Narratio
-`composition:` envelope, declared profile catalog, arbitrary overlay paths, and
-`composition.default_profile` are removed without a compatibility parser.
-
-The root pipeline uses `configkit.imports` declarations. Import paths, optional
-imports, globs, recursion, ordering, composition conflicts, containment, and limits
-have the meanings defined by the pinned ConfigKit contract. Narratio does not add a
-second import syntax or narrower application-specific traversal implementation.
-
-The unoverlaid root and its imports are the production configuration. A named
-profile is a ConfigKit overlay at `profiles/<name>.yml`; in particular,
-`profiles/testing.yml` contains inexpensive-model overrides and testing-only
-artifacts. Omitting `--profile`, or selecting ConfigKit's `default` profile, uses the
-production base. `--profile testing` applies the testing overlay. Narratio does not
-maintain a separate configured default-profile mechanism or validate unselected
-profile files.
-
-ConfigKit's rules for explicit false, zero, empty, and null values replace
-Narratio's custom presence tracking. Application defaults and normalization use a
-ConfigKit definition and recorded resolution where the final value depends on
-whether input was present. `NormalizeConfig.UnmarshalYAML` and equivalent
-parser-coupled application hooks are removed.
-
-Pipeline, campaign, session, and party inputs use the common ConfigKit loading
-boundary where its schema model can represent their types. Narratio may perform
-narrow pre- or post-load domain work, such as retaining authored party bytes,
-rejecting unresolved session-template placeholders, resolving stable inputs, and
-expanding artifact families. Such work must not recreate a second generic YAML
-loader.
-
-## Artifact Definition Ergonomics
-
-The canonical v2 configuration layout defines each ordinary Scriptorium artifact
-in its own file under `artifacts/`. The root pipeline imports the directory through
-ConfigKit, for example:
-
-```yaml
-configkit:
-  imports:
-    - glob: artifacts/*.yml
-```
-
-Each file contributes one ordinary entry at
-`scriptorium.artifacts.<artifact_key>`. The map key is the authoritative Narratio
-artifact key and therefore makes the artifact's internal identity explicit in the
-definition itself:
-
-```yaml
-# artifacts/session_recap.yml
-scriptorium:
-  artifacts:
-    session_recap:
-      enabled: true
-      prompt_id: dnd.session_recap
-      output_path: artifacts/session_recap.md
-```
-
-The canonical reusable source ID is derived without another configured identifier:
-`session_recap` becomes `narratio.artifact.session_recap`. The recommended filename
-is `<artifact_key>.yml`, but the filename is organizational rather than an identity
-source. Renaming or moving a file without changing its map key does not change the
-artifact contract. ConfigKit additive composition rejects duplicate artifact keys.
-
-The one-artifact-per-file layout is the documented happy path and is used by
-maintained examples. Narratio does not prohibit an inline artifact or another
-ConfigKit-compatible source organization merely because it differs from that
-layout. Artifact identity always comes from the effective map key, never implicitly
-from a filename or import position.
-
-Artifact families use the corresponding `artifact-families/*.yml` convention, with
-one `scriptorium.artifact_families.<family_key>` entry per file. The family key is
-explicit. Concrete member keys and source IDs continue to use Narratio's existing
-deterministic family/member naming rule after canonical party resolution.
-
-Narratio adds a read-only `narratio config artifacts` command using the ordinary
-pipeline, profile, and campaign selectors. It reports every effective ordinary
-artifact's key, canonical `narratio.artifact.<key>` source ID, defining source,
-enabled state, output path, and effective dependencies. Generated family members
-also report their family origin. Output ordering is deterministic by artifact key,
-and the command does not require a session or initialize runtime adapters.
-
-A configured-artifact input creates an implicit dependency on the referenced
-artifact. For example:
-
-```yaml
-inputs:
-  recap:
-    source: narratio.artifact.session_recap
-```
-
-The effective dependency graph is the union of explicit `depends_on` entries and
-dependencies inferred from `narratio.artifact.<key>` inputs. Inferred and explicit
-duplicates collapse to one dependency. `depends_on` remains available for an
-ordering requirement when the upstream output is not supplied as an input.
-Validation applies the same existence, self-reference, and cycle rules to both
-kinds of dependency, and diagnostics identify the declaration or input that
-introduced an invalid edge. Operators no longer need to repeat an artifact input in
-`depends_on` merely to make that input valid.
-
-## Effective Inspection, Digests, and Profile Diff
-
-ConfigKit results are the authority for composed input presence, base/profile
-origins, diagnostics, and the initial typed effective configuration. Narratio's
-configuration commands adapt those results to existing application-facing command
-formats rather than exposing ConfigKit implementation types directly.
-
-Party-dependent artifact families are expanded only after the selected campaign and
-canonical party are known. That derived state is intentionally outside ConfigKit's
-completed load snapshot. Narratio retains a narrow application-owned layer that:
-
-- records generated family/member and publish-rule attribution;
-- projects the final post-expansion pipeline for operator inspection;
-- recomputes the effective pipeline digest after expansion; and
-- ensures stages and adapters receive only the final concrete configuration.
-
-Narratio continues to own semantic `config diff` behavior because ConfigKit does
-not provide configuration diffs or fingerprints. Each side of a profile comparison
-may be loaded independently through ConfigKit. The former guarantee that both sides
-come from one parsed source snapshot is removed; operators must not rely on a
-meaningful comparison while concurrently modifying its source files. Equality is
-still based on normalized effective values rather than YAML formatting or source
-layout.
-
-## Credential and Secrets Convention
-
-Raw API keys and other credential values remain prohibited in pipeline, campaign,
-session, generated configuration, manifests, diagnostics, examples, and logs.
-Credential-bearing configuration fields use ConfigKit secret references: YAML
-contains an environment-variable name, while the resolved value remains available
-only through ConfigKit's trusted typed boundary. Fields should use credential names
-rather than legacy names ending in `_env` when the v2 schema is updated.
-
-The `pipeline.secrets.env_dir` stanza is removed. Narratio selects a secrets
-directory before parsing the pipeline using this precedence:
-
-1. an explicitly supplied `--secrets-dir PATH`; otherwise
-2. the `secrets` subdirectory beside the selected root pipeline file.
-
-The conventional directory is derived from the resolved root pipeline path, never
-from the current working directory, an imported file, or a selected profile. A
-relative explicit CLI path is resolved from the caller's current working directory,
-consistent with an ordinary command-line path argument.
-
-If an explicitly selected directory is missing or invalid, the command fails with a
-clear bootstrap diagnostic. If the conventional directory is absent, Narratio
-performs no directory bootstrap and continues; pre-existing environment variables
-may satisfy all references. If the conventional directory exists but ConfigKit
-rejects or cannot read it, the command fails. Already-set environment variables,
-including empty values, retain ConfigKit's documented precedence.
-
-Narratio explicitly calls `configkit.LoadSecretsDir` at most once for a command,
-before the first ConfigKit load that may resolve secret references and before any
-concurrent work or runtime client initialization. This application-level convention
-does not make ConfigKit's ordinary `Load` mutate process-global state. The bootstrap
-report is rendered or summarized through a safe Narratio command boundary without
-secret values.
-
-Narratio adopts ConfigKit's secret-directory rules and limits without restoring its
-old permission-mode, selected-directory-symlink, invalid-entry, byte-limit, or
-newline-trimming behavior through compatibility wrappers. Configuration inspection
-may require the referenced environment variables or the selected secrets directory
-because an ordinary successful ConfigKit load resolves effective typed secret
-references. Inspection output may show non-secret reference names where appropriate,
-but must never expose resolved values.
-
-## Validation and Diagnostics
-
-Narratio's semantic rules remain recognizable application code registered with the
-appropriate ConfigKit definition. Validation continues to reject invalid pipeline,
-campaign, session, party, adapter, publish, and artifact relationships before
-runtime work where practical. Validation order and exact prose are not compatibility
-contracts.
-
-ConfigKit diagnostic codes, paths, and source locations should be preserved through
-the application error boundary where useful. Narratio adds command context and exit
-classification but does not parse ConfigKit error strings or expose raw parser
-errors. Secret values must remain absent from success and failure diagnostics.
-
-## Compatibility and Migration
-
-This work intentionally changes supported platforms, pipeline composition syntax,
-profile layout and selection, secret configuration, YAML semantics, diagnostics,
-and some inspection prerequisites. It is released as Narratio v2.0.0.
-
-There is no runtime compatibility layer for the old `composition` or
-`pipeline.secrets` syntax. Maintained examples are converted to the ConfigKit
-format, and the v2 release documentation provides a concise migration guide that
-covers:
-
-- converting imports to `configkit.imports` declarations;
-- folding the production overlay into the base configuration;
-- placing testing overrides in `profiles/testing.yml`;
-- moving ordinary artifacts and artifact families into the recommended individual
-  definition files and using their map keys as canonical identities;
-- removing redundant `depends_on` entries when a configured-artifact input now
-  supplies the same dependency;
-- moving secret files to the conventional sibling `secrets/` directory or using
-  `--secrets-dir`;
-- renaming credential-reference fields where applicable;
-- ConfigKit's stricter YAML and explicit-value semantics;
-- the independent-load behavior of `config diff`; and
-- the removal of Windows and macOS amd64 artifacts.
-
-Obsolete application implementation, tests, documentation, examples, CI paths, and
-release machinery are removed rather than left deprecated inside the v2 codebase.
-
-## Required Changes
-
-- Add and pin the ConfigKit module dependency and establish a small application
-  integration boundary for definitions, result adaptation, and diagnostics.
-- Replace Narratio's generic YAML parsing, composition, import, profile, presence,
-  and provenance implementation with ConfigKit public APIs.
-- Express existing defaults, presence-sensitive normalization, and semantic
-  validation through ConfigKit definitions without moving Narratio domain policy
-  into the library.
-- Adapt pipeline/campaign/session/party loading and preserve the existing
-  application resolution steps that occur after their independent typed loads.
-- Rework effective configuration, sources, and diff commands around ConfigKit
-  results plus Narratio's post-party generated-attribution layer.
-- Add the maintained per-artifact and per-family file layouts, the read-only
-  `config artifacts` catalog, and effective dependency inference from configured
-  artifact inputs.
-- Convert credential configuration to typed references, add the common
-  `--secrets-dir` option, implement conventional-directory selection, and replace
-  the custom API-key directory loader with `configkit.LoadSecretsDir`.
-- Update adapters to consume resolved credentials or safe environment reference
-  names from typed configuration without independently rediscovering secret values.
-- Remove Windows and macOS amd64 build targets, release assets, CI entries,
-  platform-specific implementation, and obsolete tests and documentation.
-- Convert maintained examples and add v2 migration and release documentation.
-- Retain focused Narratio tests for domain policy and assembled application
-  behavior while deleting parser/composer/bootstrap mechanism tests now owned by
-  ConfigKit. Tests remain deterministic, offline, credential-free, and aligned with
-  the repository testing policy.
-- Update canonical architecture, configuration, CLI, operations, development,
-  internal, troubleshooting, and release documentation only as the corresponding
-  behavior is implemented.
-
-## Target End State
-
-Narratio v2.0.0 has one configuration infrastructure dependency and no duplicate
-YAML composition subsystem. Operators maintain a production base configuration,
-optional explicit imports, and fixed named overlays such as `testing`. ConfigKit
-provides strict parsing, composition, typed loading, provenance, diagnostics, and
-credential resolution; Narratio supplies domain meaning and its post-campaign
-artifact expansion.
-
-Operators can add an artifact by creating one discoverable YAML file whose map key
-is its stable Narratio identity. `config artifacts` exposes that key, its canonical
-source ID, origin, output, and effective dependency set. A later artifact can reuse
-the output through `narratio.artifact.<key>` without repeating the same edge in
-`depends_on`, while explicit ordering-only dependencies remain supported.
-
-Secrets normally live in a predictable `secrets/` directory beside the selected
-pipeline, with `--secrets-dir` available for deployment-specific placement. Raw
-credential values never enter YAML or inspection output. The bootstrap is explicit
-in application startup and ordinary ConfigKit loading remains free of process-global
-mutation.
-
-Release and CI maintenance covers Linux amd64 and arm64 as the primary platforms
-and macOS arm64 on a best-effort basis. Windows and macOS amd64 carry no remaining
-support or release burden. The repository contains no legacy configuration parser,
-profile compatibility layer, obsolete platform implementation, or redundant tests
-for behavior owned by ConfigKit.
-
-## Deferred Work
-
-- A ConfigKit reference-only inspection or typed prepare/finalize lifecycle may be
-  considered upstream if credential-free inspection becomes a demonstrated shared
-  requirement. Narratio does not implement a private substitute in this migration.
-- ConfigKit hot reload, remote providers, automatic configuration migration, and
-  application command frameworks remain outside Narratio's scope.
-- Native macOS arm64 CI may be added later when a reliable runner is available; it
-  is not required for v2.0.0.

docs/roadmap/feature-request-notarius-config-profile.yml

@@ -0,0 +1,102 @@
+---
+title: Select a Notarius configuration profile through Narratio
+status: proposed
+consumer: rakestraw.dnd Ansible collection and its pipeline role
+
+use_case: >-
+  The Ansible pipeline role deploys Narratio and Notarius as independently
+  configured applications. Operators select Narratio's testing profile to
+  develop prompts and other pipeline assets with inexpensive models while
+  retaining production settings in the base configuration. That selection
+  currently cannot select a Notarius configuration profile, leaving extraction
+  on its production settings.
+
+desired_outcome: >-
+  Narratio's testing overlay can explicitly select Notarius's testing overlay.
+  Notarius owns the resulting model choices and any other testing-specific
+  settings. The operator selects testing once when invoking Narratio, without
+  editing production files or separately invoking Notarius.
+
+rationale: >-
+  Both applications already use ConfigKit configuration overlays. Selecting
+  the downstream overlay preserves each application's configuration ownership
+  and supports future Notarius testing adjustments without adding a Narratio
+  configuration field for every downstream setting. This is explicit profile
+  composition, not a requirement for arbitrary recursive orchestration.
+
+requested_interface:
+  field: pipeline.notarius.config_profile
+  value: Optional Notarius ConfigKit configuration profile name
+  supplied: >-
+    Invoke Notarius with --config-profile and the selected name when extraction
+    executes. The setting is available in Narratio's base configuration and
+    its ordinary configuration overlays.
+  omitted_or_null: >-
+    Do not supply a profile-selection flag. Preserve existing Notarius
+    configuration selection behavior.
+  downstream_semantics: >-
+    Retain Notarius's existing selector semantics, including the default
+    selector for its base configuration. Notarius resolves profiles relative
+    to its own configuration root, not Narratio's root.
+  explicit_selection: >-
+    Do not automatically forward Narratio's profile name. The selected
+    Notarius profile may have the same name or a different name.
+  distinction: >-
+    This selects a ConfigKit configuration overlay through --config-profile,
+    not a PromptKit LLM profile through --llm-profile. The Notarius overlay
+    can itself select the desired LLM profiles using native Notarius settings.
+
+illustrative_consumer_configuration:
+  note: >-
+    These are separate files managed by the Ansible suite, not a proposed
+    combined configuration document. The Notarius pipeline and LLM profile
+    names are illustrative; the referenced LLM profile must be available to
+    Notarius.
+  narratio_profiles_testing_yml: |
+    notarius:
+      config_profile: testing
+  notarius_profiles_testing_yml: |
+    pipelines:
+      dnd-session:
+        llm_profile: gemini-flash-latest
+  operator_workflow: >-
+    Select --profile testing on the ordinary Narratio invocation. Narratio
+    selects Notarius's testing configuration overlay when it runs extraction;
+    other Narratio testing overrides continue to apply normally.
+
+observable_behavior:
+  - >-
+    Notarius owns overlay discovery, composition, validation, and the effective
+    downstream settings. A missing or invalid selected overlay must not silently
+    fall back to production or be reported as successful extraction.
+  - >-
+    Changing the selected Notarius configuration profile must not silently
+    reuse Narratio's completed extraction from the previous selection.
+    Existing downstream invalidation behavior applies when extraction changes.
+  - >-
+    Editing Notarius overlay contents behind an unchanged selector retains
+    the existing operator responsibility to force extraction when needed.
+    This request does not require inspecting or tracking private Notarius files.
+  - >-
+    Existing credential forwarding remains independently configurable through
+    notarius.llm_api_key, including in the Narratio testing overlay when the
+    selected Notarius settings require a different credential reference.
+
+consumer_follow_up: >-
+  After Narratio releases this interface, the standalone Narratio Ansible role
+  can expose an optional variable and omit the field when unset. The suite role
+  can deploy Notarius's testing overlay and select it from Narratio's testing
+  overlay, then distribute the changes through the collection. These consumer
+  updates are separate from this upstream feature request.
+
+scope_boundaries:
+  - No Notarius change is currently required; v0.7.0 supports --config-profile.
+  - No separate Narratio-side Notarius LLM-profile selector is requested.
+  - No automatic profile-name propagation or downstream configuration rewriting.
+  - No new credential discovery, copying, or provider-name remapping.
+  - This request specifies consumer behavior, not internal Narratio code changes.
+
+references:
+  narratio_configuration: ../config.md
+  narratio_notarius_integration: ../integrations/notarius.md
+  notarius_cli: https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.7.0/docs/cli.md

docs/roadmap/fix-publish-output-destination-resolution.md

@@ -0,0 +1,171 @@
+# Bugfix Request: Preserve Publish Destination Derivation with Explicit Rules
+
+Status: Implemented; release target v2.1.1
+
+## Summary
+
+Narratio should successfully derive a publish destination when a valid
+`publish.outputs` rule omits `dest`, regardless of whether that rule explicitly
+sets `required`. Narratio v2.1.0 currently rejects this valid configuration in
+some cases with a ConfigKit `resolve.unrecorded_change` diagnostic.
+
+This is a configuration-resolution bookkeeping defect, not a YAML formatting
+restriction. The fix should preserve the existing public configuration
+contract: operators may omit a derivable destination and may independently set
+`required` to either `true` or `false`.
+
+## Observed Behavior
+
+A pipeline containing a rule equivalent to the following fails during native
+configuration loading:
+
+```yaml
+publish:
+  outputs: [{"source": "narratio.transcript.final", "required": true}]
+```
+
+Narratio reports:
+
+```text
+error [resolve.unrecorded_change] /publish/outputs: application resolution changed a value without a covering record
+```
+
+The same failure is possible with ordinary block-style YAML when `required` is
+explicit and `dest` is omitted. Flow-style YAML is valid input and is not the
+cause of the defect.
+
+The existing destination-derivation tests do not expose this case because
+their rules also omit `required`. Narratio then supplies the default value for
+`required` and records a change covering the complete `publish.outputs`
+sequence. That broader record happens to cover the destination mutation as
+well, masking the missing resolution record that occurs when `required` is
+already explicit.
+
+## Expected Contract
+
+The current configuration contract remains unchanged:
+
+- `publish.outputs[].source` is required;
+- `publish.outputs[].dest` may be omitted when Narratio can derive it from the
+  selected built-in or configured artifact source;
+- `publish.outputs[].required` defaults to `true`, but an operator may set it
+  explicitly to either `true` or `false`; and
+- equivalent valid YAML representations have equivalent configuration
+  semantics.
+
+For example, both rules below should load and validate, retain their explicit
+requiredness, and receive the canonical derived destination:
+
+```yaml
+publish:
+  outputs:
+    - source: narratio.transcript.final
+      required: true
+    - source: narratio.transcript.final_markdown
+      required: false
+```
+
+## Root Cause
+
+ConfigKit intentionally treats sequences as atomic when comparing values
+before and after application resolution. Changing a field within one
+`publish.outputs` entry is therefore observed as a change to the
+`/publish/outputs` sequence.
+
+Narratio currently derives each missing destination by recording a
+normalization at the individual `publish.outputs[index].dest` path. That child
+record does not cover the atomic parent-sequence change. A separate
+container-level record is currently created only when Narratio also defaults
+an omitted `required` value, so configurations with explicit `required` values
+lose that incidental coverage.
+
+## Recommended Fix
+
+Make Narratio's publish-output resolution bookkeeping conform to ConfigKit's
+atomic-sequence contract. Whenever resolution derives one or more destinations
+inside `publish.outputs`, the recorded resolution changes must cover the
+`/publish/outputs` container. Destination derivation must not depend on an
+unrelated `required` default being applied in the same list.
+
+The implementation may retain more specific provenance where useful, but it
+must provide valid container-level coverage for the sequence mutation. Do not
+change ConfigKit's sequence comparison semantics merely to accommodate this
+call site.
+
+## Scope
+
+- Correct destination derivation for publish rules that explicitly set
+  `required` and omit a derivable `dest`.
+- Preserve explicit `required: true` and `required: false` values.
+- Preserve canonical destination derivation for built-in transcript sources
+  and configured artifact sources.
+- Add focused regression coverage through Narratio's real configuration load
+  and validation boundary.
+- Prepare a backward-compatible patch release after the fix passes the normal
+  repository validation.
+
+## Non-goals
+
+- Changing the `publish.outputs` schema, defaults, source vocabulary, or
+  destination derivation rules.
+- Requiring operators or configuration generators to supply `dest` when it is
+  derivable.
+- Requiring operators to omit explicit `required: true` values.
+- Treating flow-style YAML or JSON-compatible YAML values as unsupported.
+- Changing ConfigKit's documented atomic treatment of sequences.
+- Adding storage, publication, or network integration behavior.
+
+## Regression Coverage
+
+Add one focused package-level behavioral test that loads and validates a
+pipeline with omitted destinations and explicit requiredness. A representative
+list should include both `required: true` and `required: false`, then assert
+that:
+
+- loading and validation succeed;
+- each destination is derived from its source; and
+- each explicit `required` value is preserved.
+
+Using the compact flow-style representation that exposed the integration
+failure is reasonable, while the existing block-style cases continue to cover
+omitted `required`. The test should exercise the public configuration behavior,
+not ConfigKit call choreography or Narratio's private recording mechanism.
+
+No network service, object store, credential, or test double is required.
+
+## Target End State
+
+All valid publish rules with derivable sources behave consistently across
+these cases:
+
+| `dest` | `required` | Result |
+| --- | --- | --- |
+| omitted | omitted | destination derived; required defaults to `true` |
+| omitted | `true` | destination derived; explicit `true` retained |
+| omitted | `false` | destination derived; explicit `false` retained |
+| explicit | either value | explicit destination and requiredness retained |
+
+`narratio config validate`, `narratio config show`, and ordinary pipeline
+loading accept the corrected cases without an unrecorded-change diagnostic.
+No operator configuration migration or workaround is required.
+
+## Release
+
+This is a backward-compatible correction to documented configuration behavior
+and should be released as Narratio `v2.1.1`. The release note should identify
+the corrected explicit-required/derived-destination interaction and state that
+no special upgrade action is required.
+
+## Acceptance Criteria
+
+- The focused regression test fails against v2.1.0 behavior and passes after
+  the fix.
+- Publish rules with explicit `required: true` or `required: false` and omitted
+  derivable destinations load and validate successfully.
+- Derived destinations and explicit requiredness appear correctly in the safe
+  effective configuration.
+- Existing destination derivation, publish validation, imports, profiles, and
+  configuration inspection tests remain green.
+- The complete repository validation and release-candidate checks pass.
+- The correction is published as the immutable `v2.1.1` tag with the required
+  release note.

docs/roadmap/implementation.md

@@ -1,522 +1,431 @@
-# ConfigKit Adoption Implementation Plan
+# Implementation Plan: Speaker Checkpoints and Replayable Uploads
-
+
-Status: Complete
+Status: Implementation complete; Stages 1-7 complete.
-
+
-Implement the [ConfigKit adoption roadmap](configkit-adoption.md) in the order
+## Scope and Instructions
-below. The target is Narratio v2.0.0: ConfigKit v0.1.1, the reduced platform
+
-matrix, and the artifact-authoring workflow described there. Each stage is a
+Implement [the feature roadmap](transcribe-checkpoints-and-replay.md). This plan
-bounded implementation assignment for a gpt-5.6-terra coding agent. Mark a stage
+replaces the completed Notarius-profile plan; that work remains in Git history.
-complete only after its changes and acceptance checks succeed; record a short
+Complete the numbered stages in order, one bounded implementation prompt per
-completion and verification note beside its status.
+stage for gpt-5.6-terra. Record completion and actual verification results here.
-
+Intermediate stages are not a finished feature and must not be released alone.
-## Instructions for every stage
+
-
+Before working, read `AGENTS.md`, `docs/development.md`, all three policies in
-- Read `docs/development.md` and all three policies under `docs/policy/`.
+`docs/policy/`, the roadmap, and the stage-specific preparation below. Use the
-  Read the relevant roadmap section and the stage-specific sources listed below.
+maintained Go 1.26 toolchain. Preserve operator choices, speaker filenames,
-  Paths identify starting points, not an exhaustive edit allowlist; inspect callers
+bounded concurrency, streaming, and existing credentials/settings. Do not add
-  and tests before changing a package boundary.
+new commands, dependencies, service requirements, arbitrary speaker limits,
-- Use the tagged ConfigKit public API. The local `../ConfigKit` checkout is useful
+strict transcript schemas, or a generic checkpoint framework. No release or
-  reference material, but verify its version before relying on it. The module
+upstream service work is part of this plan.
-  cache for v0.1.1 is an alternative. Do not require a sibling checkout, a local
+
-  `replace`, a Go workspace, an upstream patch, or an unpinned revision to build.
+## Settled Design Decisions
-- Keep Narratio domain policy in `internal/config`, startup and selectors in
+
-  `internal/app`, and credential delivery in the owning adapters. Do not build
+### Progress Representation and Recovery
-  a general configuration framework around ConfigKit.
+
-- Keep each stage buildable and run focused behavioral tests for its changed
+Add optional `transcribe_state_version` (version 1) and `transcribe_speakers`
-  boundary. Temporary migration helpers may exist between stages only where
+to `manifest.StageRecord`. The latter is a map keyed by the existing derived
-  named here; they must not introduce runtime format auto-detection or fallback.
+speaker ID, containing completed results only. Absence means that work must be
-- Update each canonical current-behavior document when its behavior changes.
+done; a separate pending/running/failed state machine is unnecessary. Aggregate
-  The roadmap remains the owner of unimplemented work. Preserve historical
+stage status/error remains authoritative for invocation failure. A versioned
-  release notes; their descriptions of old platforms and formats are history.
+empty collection is meaningful: no earlier completions are reusable.
-- Tests use real ConfigKit and temporary files, with fake external adapters or
+
-  storage where needed. Use synthetic credentials and isolate environment
+Use a typed `TranscribeSpeakerRecord` with fingerprint version/digest,
-  mutation; such tests must not run in parallel. Retain domain and security
+session-relative audio path, audio SHA-256 and size, one `ArtifactRecord` output
-  coverage, remove superseded mechanism tests, and avoid exact diagnostic prose
+of kind `transcript_raw`, output size, and producer run ID. The output carries
-  or private callback choreography assertions.
+its session-relative canonical path and SHA-256. No new transcript source IDs,
-- Do not tag or publish v2.0.0 as part of this plan. Release preparation belongs
+synthetic schema contracts, timestamps, or historical attempt collections are
-  here; release authorization and tag publication are a later task. The existing
+needed. Existing aggregate diagnostics can retain attempt/status/duration data
-  release completion boundary remains successful upstream tag push, with no CI
+for work performed in the current invocation; do not fabricate that information
-  polling or waiting.
+for reused outputs.
-
+
-## Decisions that apply across stages
+Keep the session-manifest schema identifier unchanged for this optional additive
-
+state; validate supported per-stage versions and retain strict decoding. New
-The roadmap is authoritative for product scope. These implementation choices
+Narratio reads old manifests. Old binaries may reject the added fields under
-make that scope concrete:
+their existing strict decoding; document this downgrade limitation.
-
+
-- Enable ConfigKit imports and profile selection for pipeline files only.
+For pre-feature manifests with no speaker evidence, regenerate transcription
-  Campaign, session, and party are single-source definitions with imports and
+once when transcribe is next selected, even if the aggregate status succeeded.
-  profiles disabled. Preserve their domain schemas and source-relative inputs.
+Old records do not bind individual transcript results to the audio bytes they
-  Omitted or empty profile and the exact name `default` select the base; other
+used. Do not guess that association from current files, old `per_file` metadata,
-  names use ConfigKit's fixed `profiles/<name>.yml` convention.
+or abandoned run directories. This is the conservative upgrade path, not a new
-- Defaults apply to absent fields. Explicit empty/zero/false/null values follow
+general migration system. No other stage or unselected range is forcibly run.
-  ConfigKit decoding and then domain validation; do not refill invalid explicit
+
-  values with legacy defaults. Optional null stage sections remain absent;
+### Reuse and Persistence
-  required sections fail domain validation rather than being resurrected.
+
-- Keep ConfigKit metadata/result snapshots separate from runtime-only Narratio
+Compute a versioned per-speaker fingerprint from speaker ID, session-relative
-  state. ConfigKit discards ignored and unexported fields when detaching values;
+audio identity, actual audio SHA-256/size, and the existing transcribe semantic
-  attach root paths, retained party bytes, family catalogs, and digest metadata
+configuration fingerprint (URL and language). Do not include invocation ID,
-  after loading. No validator may mutate bound configuration.
+absolute workspace root, concurrency, retry settings, timeout, or credentials.
-- Use one Narratio-owned safe effective projection for the final expanded
+Stream input hashing with cancellation; do not trust stored input checksums
-  pipeline. It contains configuration values and credential reference names,
+alone. Recheck input bytes before accepting a new result to catch changes
-  never resolved credential bytes. It feeds show, semantic diff, digest, and
+observed during transcription; fail that job without checkpointing mismatched
-  catalog data. ConfigKit metadata remains the authority for input provenance;
+evidence. This is not a hostile-filesystem snapshot or concurrent-editor
-  Narratio adds only domain-generated attribution.
+transaction guarantee and requires no extra audio copies or file locks.
-- Rename `storage.s3.access_key_id_env` to `access_key_id`,
+
-  `storage.s3.secret_access_key_env` to `secret_access_key`, and
+Validate reusable output identity, canonical location, JSON, checksum, and size.
-  `audita.llm_api_key_env` to `llm_api_key`. Each is an optional `*configkit.Secret`.
+Use existing confinement/file primitives. Missing or corrupt regular outputs
-  An explicit reference always resolves during loading, even if the associated
+become work; unsafe paths/non-regular conflicts follow existing safety errors,
-  stage will not execute. Require both S3 fields together or neither. With neither,
+not recursive deletion. Missing required audio is an input error, not permission
-  retain the AWS SDK default credential chain; do not synthesize mandatory secret
+to reuse an unverifiable transcript. Removed inputs are removed from the current
-  references that would break role-based authentication or local-only inspection.
+collection and aggregate outputs without deleting arbitrary files.
-  With no Audita reference, preserve its existing downstream credential discovery.
+
-  Explicit references replace Narratio's old per-adapter environment lookup.
+One stage-owned mutex serializes candidate collection construction, manifest
-- Keep absent S3 credentials out of defaults; migration examples explicitly name
+save, and installation of committed state. Save a detached candidate and only
-  the existing AWS variables when static credentials are intended. A non-nil
+then update live authority, following analyze's pattern. Workers must not mutate
-  missing/empty reference fails instead of silently falling back. This preserves
+the live manifest outside that serialized section. Keep expensive HTTP work
-  provider-managed credentials while making explicit configuration trustworthy.
+outside the mutex. Stop dispatch/acceptance on checkpoint failure, join workers
-- `config artifacts` uses the existing configuration command selectors and text
+before return, and preserve the last successfully committed collection.
-  output convention. No new JSON mode, artifact creation wizard, inferred filename
+
-  identity, or profile catalog is added.
+Before launching requests, durably checkpoint the reconciled collection. For
-- Preserve the roadmap's unique base artifact definition rule explicitly:
+force, that collection is empty: this prevents later ordinary retries from
-  ConfigKit rejects conflicting leaves but can compose disjoint children of the
+resurrecting pre-force outputs. If this initial save fails, do not start requests
-  same mapping. Use its public source metadata to reject an ordinary artifact key
+or overwrite outputs. Force again clears the current collection again; ordinary
-  declared by multiple base files, even if their fields are disjoint. Apply the
+retry retains replacements already checkpointed after the previous force.
-  same rule to family keys. A selected profile may override or extend a definition.
+
-  This is a narrow Narratio declaration rule, not a different merge algorithm.
+Save each validated result at its canonical raw-transcript location before
-- Relax only the obsolete configuration/secrets filesystem restrictions identified
+checkpointing it. Run-local files remain staging/diagnostics, not reuse
-  by the roadmap. Do not remove session restore, cleanup, publication, workspace
+dependencies. Bytes left by an unsuccessful checkpoint have no completion
-  confinement, or ordinary shared-workspace mode guarantees as collateral work.
+authority. A worker may checkpoint a completed result using the parent stage
-
+context even if a sibling canceled the work context; parent cancellation or a
-## Stage 1 — Reduce the platform and release matrix
+checkpoint failure may prevent that save. Guarantee retention of committed
-
+work, not all responses that happened to finish during cancellation.
-Status: Complete — Reduced CI and release output to Linux amd64/arm64 and macOS
+
-arm64, removed Windows-only runtime implementations and accommodations, and
+### Multipart Replay Mechanism
-verified focused tests, all three cross-builds, exact asset names, and embedded
+
-version reporting.
+Replace the pipe/producer upload mechanism with a small pull-based multipart
-
+body backed by the audio reader. Use `mime/multipart.Writer` to encode a bounded
-Read: roadmap “Platform Contract”; `scripts/build-release-assets.sh`,
+metadata prefix and suffix around the file payload: capture the prefix after
-`scripts/check-release-candidate.sh`, `.woodpecker/`, `internal/releasecheck`,
+`CreateFormFile`, then encode the language field and closing boundary as the
-`docs/release.md`, and platform-specific files in application, file operations,
+suffix. Generate this framing once per application attempt. Each body combines
-and subprocess packages.
+fresh readers for prefix, freshly opened audio, and suffix using `io.MultiReader`.
-
+No full-audio buffer or temporary multipart spool is needed.
-1. Make Linux amd64, Linux arm64, and macOS arm64 the only maintained build and
+
-   release targets. Remove Windows suffix/packaging branches and macOS amd64
+The initial body and `Request.GetBody` use the same factory/framing. Each owns
-   targets from scripts, workflows, tests, and current documentation.
+an independent audio handle. Give bodies idempotent Close and context-triggered
-2. Delete Windows-only implementations and tests; simplify paired build-tag
+closure (for example `context.AfterFunc`), without holding a mutex across a
-   files where the remaining implementations can be shared. Preserve portable
+blocking Read. Read/Close coordination must release a blocked source and retain
-   code when retaining it adds no special support machinery. Preserve functioning
+genuine source-read/close errors while not treating deliberate early closure as
-   Unix subprocess cancellation, locking, and file operations on both supported OSes.
+source failure. The attempt owns cleanup of all created bodies, including
-3. Retain the local Linux verification gates and cross-build gates for all three
+replays; reject new body creation after its context expires.
-   published assets. Do not introduce a native macOS runner requirement or claim
+
-   that cross-compilation verifies runtime behavior.
+Remove the old producer `Wait` dependency. Track body-local source errors with
-4. Update architecture/operations platform statements and contributor/release
+synchronization so a swallowed upload read error cannot become a successful
-   guidance. Keep existing release protections and the no-CI-wait boundary intact.
+transcript, and a deliberately closed original body cannot poison a successful
-
+replay. Keep the outer retry policy and per-attempt context. Do not add replay
-Acceptance: focused platform/subprocess/fileops/releasecheck tests pass; build all
+counters to the user retry budget or depend on Go's exact internal retry count.
-three targets with `CGO_ENABLED=0`; verify the asset builder produces exactly the
+Preserve ordinary HTTP redirect policy; body replay can also enable Go's
-three expected versioned binaries and the host binary reports the supplied version.
+body-preserving redirects. Do not introduce a new redirect restriction.
-Existing release tests still prove guarded publication. No current support promise
+
-or asset list retains Windows or macOS amd64.
+## Stage 1: Add Durable Speaker Completion State
-
+
-## Stage 2 — Separate configuration normalization from validation
+Status: Complete.
-
+
-Status: Complete — Added explicit deterministic pipeline normalization before
+Completion marker (2026-09-21): Added optional versioned transcribe-owned
-validation, made Notarius validation read-only on accepted and rejected inputs,
+per-speaker completion records, strict load/save validation, isolated collection
-documented the boundary, and verified config race tests plus app/stage consumers.
+cloning, legacy aggregate-only compatibility, and lifecycle-preservation
-
+coverage. Verified with `go test ./internal/manifest` and `git diff --check`.
-Read: `internal/config/load.go`, `defaults.go`, `normalize.go`, `validate*.go`,
+
-`artifact_families.go`, and ConfigKit's “Recorded application resolution”,
+Preparation: `internal/manifest/manifest.go`, `store.go`, `analyze_state.go`,
-“Semantic validation”, and “Defaults and typed decoding” contracts.
+their tests, and `docs/internal/manifest.md`.
-
+
-1. Separate value-producing normalization from read-only validation, including
+1. Implement the additive fields, record type, version constants, validation,
-   Notarius reference/output normalization currently performed by
+   and deep-copy helper described above in a focused transcribe state file.
-   `validateNotarius`. Audit all validators for map, slice, pointer, and scalar
+2. Validate ownership by the transcribe stage, supported versions, required
-   mutations, including changes that would occur only on error paths.
+   completed-record evidence, output kind, safe relative paths, SHA-256 values,
-2. Keep reusable domain normalization ordinary package code. Validation checks the
+   sizes, and producer identity consistency. Use existing speaker IDs as-is;
-   already normalized candidate and must work for both loaded and programmatically
+   do not apply analysis-artifact key regexes or copy unrelated analysis limits.
-   constructed values without silently fixing them.
+3. Integrate validation with both load and save. Preserve speaker state through
-3. Inventory defaults in `load.go`: static defaults, per-map-entry/list-element
+   running/failed/stale transitions and aggregate result clearing. Generic stage
-   defaults, and inherited or presence-sensitive defaults. Retain named constants
+   invalidation does not discard checkpoints; reconciliation checks their data.
-   in `defaults.go`. This inventory should guide code and concise comments, not
+4. Test round-trip populated and versioned-empty collections, old manifests
-   become a permanent parallel defaults document.
+   without fields, malformed evidence, deep-copy isolation, and lifecycle
-4. Keep the current loader calling normalization explicitly before validation
+   preservation. Avoid imposing JSON formatting or map order as contracts.
-   during this preparatory stage. The ConfigKit resolver replaces that loading
+
-   choreography in Stage 4. Preserve family expansion as an explicit domain step.
+Verify: `go test ./internal/manifest`.
-
+
-Acceptance: focused configuration tests prove normalization is deterministic and
+Done when durable storage can represent partial completion independently of
-validation does not mutate accepted or rejected inputs. Cover representative
+aggregate status, without activating new stage behavior yet.
-Notarius normalization/collision handling and existing artifact/publish rules.
+
-Do not add a separate mutation test for every trivial validator.
+## Stage 2: Implement Read-Only Speaker Reconciliation
-
+
-## Stage 3 — Replace composition-dependent effective projection
+Status: Complete.
-
+
-Status: Complete — Introduced one typed safe projection for effective YAML,
+Completion marker (2026-09-21): Extracted shared deterministic transcribe job
-semantic values, source paths, and the versioned v3 digest; removed composition
+construction and added read-only, cancellation-aware per-speaker input and
-parsing from those consumers and verified ordering, expansion, relocation,
+output reconciliation. Covered unchanged reuse, semantic and operational
-nil/empty, exact-integer, CLI diff, and semantic-resume behavior.
+settings, changed/added/removed inputs, legacy and forced work, missing/corrupt
-
+outputs, unsafe evidence, and missing audio without connecting runtime skip or
-Read: `internal/config/effective_pipeline.go`, `effective_digest.go`,
+checkpoint behavior. Verified with
-`pipeline_composition.go`, `internal/app/config_commands.go`, the config-diff
+`go test ./internal/stage ./internal/manifest` and `git diff --check`.
-implementation, and `docs/internal/configuration.md`.
+
-
+Preparation: `internal/stage/transcribe.go`, `semantic_contracts_initial.go`,
-1. Introduce one package-owned, schema-specific safe projection of the effective
+`analyze_reconciliation.go`, `extract_resume.go`, their tests, and the artifact
-   pipeline. Use explicit typed projections with stable configuration field names;
+path/integrity helpers they use.
-   preserve null versus empty containers and exact integers. Ordinary nested
+
-   configuration types may be reused where they contain no runtime state.
+1. Extract the existing audio discovery/job construction into a shared,
-   Credential fields must be projected explicitly as reference names when Stage 7
+   transcribe-local reconciliation path. Preserve current input selection and
-   changes their types. Do not introduce a generic reflection schema engine.
+   speaker identity behavior. Build sorted jobs and classify completed results
-2. Render this projection as deterministic YAML using the existing YAML encoder;
+   against the current input set and evidence defined above.
-   encoding output is not a replacement YAML loader. Produce semantic records
+2. Add pure fingerprint construction and streamed input/output inspection.
-   directly from the safe projection using standard JSON encoding/decoding with
+   Resolve manifest input paths with existing session-relative/absolute reading
-   number preservation if a plain value tree is useful. Do not reparse YAML or
+   helpers; do not change input precedence or assume the current working directory
-   reconstruct `compositionNode` trees to compare or hash effective values.
+   is the session root. Newly written checkpoint paths are always relative.
-3. Make show, diff values, and digest use that common projection. Mapping order is
+3. Return current records and work-to-do without writing files or manifest state.
-   immaterial; sequences remain atomic for diff; nil and empty remain distinct.
+   Force selects all work and an empty starting collection; old unversioned
-   Exclude family declarations once expanded, all runtime metadata, profile names,
+   transcribe state supplies no reusable records. Do not connect aggregate skip
-   source locations, and raw credentials. Preserve logical Notarius path handling
+   validation until execution can produce the new evidence in Stage 3.
-   so moving an equivalent bundle does not change its digest.
+4. Test unchanged reuse; one changed audio among unchanged speakers; URL/language
-4. Version the changed digest encoding explicitly using the package's digest
+   changes; operational-setting exclusions; added/removed speakers; missing and
-   version constant. Digest/profile metadata remains provenance, never a blanket
+   corrupt regular outputs; unsafe record paths; missing audio; and force.
-   resume cache key. Keep stage/artifact semantic evidence behavior intact.
+   Prefer compact tables and real temporary files over mocked hashing.
-5. Decouple enumeration of effective field paths from the legacy composition
+
-   renderer. Input ownership can still come from the current loader until Stage 4.
+Verify: `go test ./internal/stage ./internal/manifest`.
-
+
-Acceptance: show/diff/digest tests cover equivalent monolithic/split values,
+Done when one read-only decision path describes exactly which speakers need
-different map insertion order, null/empty distinction, family-expanded outputs,
+work, without altering existing runtime behavior prematurely.
-and bundle relocation. A meaningful artifact change changes the digest; formatting
+
-and profile naming alone do not. Existing semantic resume tests pass. No effective
+## Stage 3: Execute and Checkpoint Speakers Incrementally
-projection consumer needs the custom composition parser/renderer.
+
-
+Status: Complete.
-## Stage 4 — Cut pipeline loading over to ConfigKit
+
-
+Completion marker (2026-09-21): Connected reconciliation to bounded execution,
-Status: Complete — Replaced pipeline composition with ConfigKit v0.1.1 imports,
+durably checkpointed the starting and per-speaker collections through detached
-fixed-path profile selection, fresh typed defaults, recorded resolution, source
+manifest candidates, preserved committed work across failures and cancellation,
-metadata adaptation, and duplicate base artifact/family enforcement; removed the
+rebuilt deterministic aggregate outputs from reusable evidence, and added
-legacy parser and verified all tests plus the configuration race suite.
+speaker-aware resume validation. Updated production-style fixtures and covered
-
+serialized concurrent saves, force/retry replacement, input rechecks, save
-Read: ConfigKit v0.1.1 `docs/config.md`, `docs/consumers/README.md`, and its
+failures, partial recovery, and aggregate reconstruction. Verified with
-Narratio-shaped compiled example; Narratio `internal/config/load.go`,
+`go test ./internal/stage ./internal/app`, `go test -race ./internal/stage`, and
-`composition.go`, `pipeline_composition.go`, and profile/composition tests.
+`git diff --check`.
-
+
-1. Pin `gitea.maximumdirect.net/eric/ConfigKit v0.1.1` in `go.mod`/`go.sum`.
+Preparation: `internal/stage/transcribe.go`, `analyze_execution_state.go`,
-   Implement a small pipeline definition using `Load`, `File`, enabled imports,
+`run_local.go`,
-   `Options.Profile`, defaults, recorded resolution, and read-only validation.
+`internal/app/runner.go`, and transcribe/checkpoint test fixtures.
-2. Migrate static defaults to fresh default values. Apply map-entry, list-element,
+
-   and inherited defaults with `Resolution.Default`/`IsExplicit`; use recorded
+1. Wire reconciliation into Run, require the existing ManifestStore collaborator,
-   normalization for transformations from Stage 2. Do not call old post-decode
+   and checkpoint the starting collection before launching HTTP work. Implement
-   zero-filling defaults. Remove `NormalizeConfig.UnmarshalYAML` and its private
+   detached candidate saves and serialized live-state updates. Audit Store.Save's
-   presence bit. Include publication list-entry defaults, optional section
+   normalization side effects so a failed candidate save cannot mutate shared
-   allocation, and trim's Scriptorium requirement in this conversion.
+   authority; use detached records/collections wherever it may write.
-3. Perform file-local semantic checks in the definition. Defer checks needing
+2. Retain bounded errgroup execution and fail-fast cancellation. Check the work
-   canonical party expansion or campaign/session context to the existing explicit
+   context before beginning each queued request. After success, validate adapter
-   resolution boundary; do not reject references to future concrete family members
+   output path/JSON, recheck audio evidence, materialize canonical bytes, compute
-   merely because the campaign has not loaded yet. Run full checks after expansion.
+   output evidence, and checkpoint the new record. Check a checkpoint-failure
-4. Replace pipeline composition and profile loaders. `configkit.imports` is the
+   latch under the serialization lock before accepting further completions.
-   only directive; no `composition` or `_configkit` alias is accepted. Pass profile
+3. Preserve committed successes on all error/cancellation exits, including
-   selection directly under the agreed convention; unselected overlays are not read.
+   starting-save, canonical-write, per-speaker-save, and aggregate-save failures.
-   `LoadPipelineProfilePair` may remain a thin pair of independent loads, with no
+   Return meaningful speaker/error context and let the runner retain its existing
-   shared parse cache or paired source-snapshot promise.
+   terminal failure behavior. Do not report partial aggregate outputs as success.
-5. Adapt ConfigKit sources and metadata to Narratio's existing reporting records.
+4. Assemble final outputs in deterministic speaker order from the reconciled
-   Translate paths structurally using public path APIs, not error-message parsing.
+   completed records, including reused speakers, with original producer IDs and
-   Preserve multiple contributing locations for composite/profile-owned mappings
+   checksums. If all records are current but aggregate status is failed/running,
-   and distinguish defaults/resolution from authored values.
+   finish without WhisperX calls and rebuild the aggregate success.
-   Check artifact/family map-entry ownership for duplicate base declarations using
+5. Implement `transcribeStage.ValidateResume` using the same read-only
-   those locations; ignore synthetic defaults and allow the selected overlay.
+   reconciliation, so a succeeded stage cannot skip changed audio or invalid
-6. Attach runtime metadata only after load succeeds. Preserve root-relative runtime
+   transcripts. Retain the existing URL/language semantic check and runner
-   path interpretation and capture logical paths before making them absolute.
+   invalidation behavior; no whole-config digest invalidation.
-   Retain family declarations and original ConfigKit metadata for later expansion.
+6. Adapt existing tests that require no canonical partial files: the new contract
-7. Replace generic mechanism tests with a small integration set proving actual
+   permits checkpointed files but forbids aggregate success. Update fixtures to
-   Narratio wiring. Convert fixtures affected by this stage. Delete
+   provide real manifest stores and records rather than a production fallback
-   `composition.go`, obsolete pipeline traversal/overlay/presence machinery, and
+   that silently disables checkpointing.
-   their redundant tests once the callers are migrated.
+7. Test A/B completion followed by C failure and D unattempted (concurrency 1),
-
+   reload and retry only C/D; concurrently finishing speakers without lost saves;
-Acceptance: a real root with imports and a testing overlay loads; duplicate claims
+   failure and cancellation after a checkpoint; save failure retaining earlier
-fail with useful source attribution, including two base files contributing disjoint
+   authority; and force failure followed by ordinary retry without old-result reuse.
-fields to one artifact or family key; base/default selection works; malformed
+
-unselected profiles do not fail base loading. Omitted defaults and representative
+Verify: `go test ./internal/stage ./internal/app` and
-explicit false/zero/empty/null inputs obey the new semantics. Invalid domain values
+`go test -race ./internal/stage`.
-still fail. Commands use the new pipeline loader with no format fallback. Update
+
-`docs/config.md` and configuration internals for the implemented boundary.
+Done when incremental progress and aggregate success work together safely under
-
+ordinary, concurrent, canceled, and forced execution.
-## Stage 5 — Migrate campaign, session, and canonical party loading
+
-
+## Stage 4: Verify Runner, Merge, and Durable Lifecycle Integration
-Status: Complete — Migrated campaign, session, and canonical-party documents to
+
-independent ConfigKit definitions, preserved bounded session inspection, exact
+Status: Complete.
-party bytes and metadata-derived authored order, and retained identity, source,
+
-family-expansion, and validation behavior; verified all tests and focused races.
+Completion marker (2026-09-22): Added real-persistence application coverage for
-
+cross-invocation retry, interrupted running state, failed aggregate saves,
-Read: `internal/config/load.go`, `party.go`, `party_resolution.go`,
+force/reset persistence, downstream invalidation, and one-time legacy upgrade.
-`artifact_families.go`, session-template tests, `internal/app/config_loader.go`,
+Versioned merge input discovery now requires aggregate success and an exact
-and ConfigKit source/schema/version contracts.
+match between current speaker evidence and declared aggregate outputs, while
-
+legacy/manual directory fallback remains available. Restore coverage preserves
-1. Use separate ConfigKit definitions for campaign, session, and party. Replace
+session-relative speaker paths, leaves unpublished raw transcripts absent, and
-   `decodeStrictYAML*` and the custom party YAML-node parser. Model the party input
+canonical transcripts remain reusable after run-directory cleanup. Verified
-   as the existing string schema version and character-keyed typed map, with the
+with `go test ./internal/app ./internal/stage ./internal/manifest`,
-   existing `alias` list, ordered class list, and optional positive class level.
+`go test -race ./internal/app`, and `git diff --check`.
-2. Keep party domain checks: valid IDs, required display names and classes,
+
-   trimmed/control-free names, case-insensitive name/alias ambiguity, and duplicate
+Preparation: `internal/app/runner.go`, `runner_runtime.go`,
-   class checks. Validate the required version through `VersionRule`. Keep an
+`analyze_checkpoint_recovery_test.go`, `runner_terminal_failure_test.go`,
-   exact independent copy of authored bytes outside ConfigKit's schema object.
+`restore_manifest_paths.go`, `internal/stage/merge.go`, and existing publish,
-3. Preserve authored character order using successful metadata source coordinates
+restore, and cleanup tests routed from `docs/internal/overview.md`.
-   for the single party input when constructing `CanonicalParty.Characters`.
+
-   Preserve class/alias sequence order naturally. Family expansion and players
+1. Add application-level tests with real manifest persistence and fake WhisperX:
-   projection continue using their existing deterministic ID sorting. Do not keep
+   failed stage across separate invocations; all speakers committed before a
-   a second YAML parse just to recover mapping order.
+   failed aggregate save; interrupted running state; force/reset persistence;
-4. Preserve the narrow session placeholder rejection before typed load, expected
+   and unchanged upstream/succeeded downstream invalidation behavior. Inject
-   session/previous-session identity checks, campaign selection, stable-input
+   errors at durable boundaries, not every private method call.
-   precedence, and local versus remotely downloaded session provenance.
+2. Close `discoverRawTranscripts`' directory-scan fallback for versioned
-   Retain the initially loaded pipeline/campaign during remote session acquisition.
+   transcribe state: incomplete aggregate state is not usable, and completed
-5. Where bytes must be retained or inspected before `ConfigKit.Bytes`, bound the
+   state consumes only declared current aggregate outputs. Keep legacy/manual
-   initial read too, using the existing fileops bounded-read helper and a named
+   fallback behavior for manifests without the new state rather than banning
-   package constant of 8 MiB matching the pinned source limit. Otherwise prefer
+   previously allowed standalone workflows. Test that partial files and removed
-   `ConfigKit.File`. Do not read an unbounded file and rely on later rejection.
+   speaker files cannot leak into a versioned merge, including direct stage calls.
-6. Complete post-party family and publish-rule expansion, then full cross-config
+3. Audit manifest copies/projections, remote manifest publication, restored path
-   validation and digest refresh. Keep generated origins outside the library
+   handling, and cleanup. Preserve relative speaker paths on restore and verify
-   snapshot. Remove unused decoder plumbing and obsolete party parsing tests.
+   they resolve under the destination session, not the producer machine. Reuse
-
+   existing confinement validation, not a second path-policy layer.
-Acceptance: retained authored party bytes are identical; domain errors, aliases,
+4. Add focused round-trip coverage through existing publish/restore fixtures for
-class order, family origins, and derived players are correct. Local and remote
+   speaker records. Restored outputs absent from the published selection are
-session loads preserve identity, input path bases, and the original pipeline.
+   non-reusable locally; do not silently expand remote publication to every raw
-Unknown fields and disabled directives fail through ConfigKit. Focused config,
+   speaker or upload audio as a new default. Removing run directories must not
-prepare/extract, and application loading tests pass.
+   remove canonical checkpointed transcripts or make reuse require run files.
-
+5. Verify old succeeded manifests are readable and rerun once when transcribe is
-## Stage 6 — Move secrets bootstrap before all configuration loads
+   selected, then reuse normally. Keep old manifests usable for other commands
-
+   and bounded ranges. Do not automatically import old unrecorded JSON files.
-Status: Complete — Added invocation-scoped ConfigKit secrets bootstrap before
+
-all pipeline loads and adapter construction, exposed consistent explicit and
+Verify: `go test ./internal/app ./internal/stage ./internal/manifest` and
-conventional directory selection across the CLI, removed the retired pipeline
+`go test -race ./internal/app`.
-schema and custom loader, and verified focused, full, and race test suites.
+
-
+Done when the new authority survives runner and storage lifecycles and cannot
-Read: roadmap “Credential and Secrets Convention”; ConfigKit's bootstrap
+expose incomplete transcripts downstream.
-contract; `internal/app/secrets_env*.go`, `config_loader.go`, `config_commands.go`,
+
-`object_store.go`, command dependencies, and command argument owners.
+## Stage 5: Implement Replayable Streaming Multipart Bodies
-
+
-1. Add a shared `--secrets-dir` selector to every CLI path that loads a pipeline,
+Status: Complete.
-   including configuration inspection/diff, execution aliases, planning, publish,
+
-   and session/storage operations. Route all through one command-owned bootstrap
+Completion marker (2026-09-22): Replaced the producer-goroutine/pipe upload
-   context. Help/version and commands that do not load configuration do not bootstrap.
+with bounded standard-library multipart framing and independently opened,
-2. Discover the root pipeline first. An explicit relative directory is based on
+pull-based streaming bodies shared by the initial request and `GetBody`.
-   caller CWD; otherwise choose `secrets/` beside the resolved root pipeline.
+Bodies are tracked, idempotently closed, canceled with their attempt context,
-   An explicitly empty flag is invalid. Missing conventional directories are
+and retain genuine read/close failures without treating an intentionally
-   skipped; missing explicit directories and unreadable/invalid existing directories
+abandoned original as a replay failure. Added focused coverage for identical
-   fail. Use ConfigKit's selected-directory symlink behavior without custom rejection.
+framing, partial-read restart, simultaneous handles, source failures, and
-3. Call `LoadSecretsDir` at most once per command before any ConfigKit load or
+blocked-reader release. Verified with `go test ./internal/adapters/whisperx`,
-   adapter creation, including both loads of config diff and remote session lookup.
+`go test -race ./internal/adapters/whisperx` (including ten repeated runs), and
-   Use invocation state, not a package-global `sync.Once`. A new command gets its
+`git diff --check`.
-   own bootstrap; library config loaders themselves never mutate the environment.
+
-4. Present safe bootstrap warnings/failures through stderr or the existing safe
+Preparation: `internal/adapters/whisperx/http.go`, `http_test.go`,
-   diagnostic boundary, never into YAML show output. Preserve the partial report
+`docs/integrations/whisperx.md`, and the installed Go net/http Request/GetBody
-   on bootstrap failure. Do not add rollback or reinterpret ConfigKit file rules.
+contract. Keep this change inside the WhisperX adapter.
-5. Remove late bootstrap calls in object-store and runner composition, the custom
+
-   directory reader and permission platform files, `pipeline.secrets`, its defaults
+1. Implement the pull-based framing/body factory described above, using standard
-   and validators, and their obsolete tests. Convert affected fixtures immediately.
+   multipart encoding rather than hand-escaped MIME headers. Add no new payload
-
+   cap or upload-size setting. Preserve file-before-language wire semantics and
-Acceptance: test absent conventional directory, explicit override from another
+   the existing form names.
-CWD, invalid explicit directory, already-set empty/nonempty environment values,
+2. Install the initial body and GetBody with the same per-attempt boundary.
-and bootstrap failure before adapter construction. A diff invocation and a remote
+   Track and close all opened bodies even if a custom transport returns early;
-session acquisition each bootstrap once. Config inspection requires no session,
+   make cleanup/context callbacks safe against overlapping reads and closes.
-workspace writes, manifests, or runtime clients. Update CLI, config, operations,
+   A GetBody failure must be returned, not converted into an empty upload.
-architecture, and troubleshooting to the new bootstrap/permission contract.
+3. Replace pipe-specific Wait/error paths in doTranscribeAttempt with source-error
-
+   handling appropriate to pull bodies. Genuine source errors remain visible;
-## Stage 7 — Resolve typed credentials and protect all output boundaries
+   intentional closure during transport retry is not itself a source error.
-
+   Keep response bounds, JSON validation, output installation, retry
-Status: Complete — Migrated S3 and Audita credentials to optional ConfigKit
+   classification/delay, cancellation, and application attempt reporting intact.
-typed references, passed resolved values directly to runtime adapters, preserved
+4. Remove obsolete producer-only helpers rather than retaining two upload paths.
-the AWS default provider chain when unconfigured, and verified reference-only
+   Adapt tests tied to producer goroutines to assert streaming and resource
-inspection, provenance, generated configuration, manifest, and diagnostic
+   release, which are the actual contracts.
-boundaries with focused, full, and race test suites.
+5. Add focused body tests: original/replayed bytes parse identically; replay
-
+   after partial consumption starts from the beginning; simultaneous bodies use
-Read: ConfigKit “Typed secret references” and rendering contracts;
+   independent handles; source failures propagate; Close/cancel releases a
-`internal/config/config.go`, `defaults.go`, `validate_adapters.go`, the safe
+   blocked reader without deadlock. Use synthetic audio and gated readers.
-projection from Stage 3, `internal/adapters/storage/s3_backend.go`,
+
-`internal/adapters/audita/subprocess.go`, and their composition callers.
+Verify: `go test ./internal/adapters/whisperx` and
-
+`go test -race ./internal/adapters/whisperx`.
-1. Implement the three renamed optional typed fields and S3 pair policy above.
+
-   Reject old `_env` schema keys; remove their default-name and lookup helpers.
+Done when replay is available without whole-file buffering or producer-lifetime
-   Convert maintained fixtures with synthetic environment setup where references
+ambiguity, and all existing HTTP behavior tests still pass.
-   are present. Do not add credentials to unrelated local pipeline fixtures.
+
-2. Pass resolved S3 values to the SDK adapter's explicit static provider only when
+## Stage 6: Verify Replay Through the HTTP Adapter Boundary
-   the pair is configured. With neither, preserve its default provider chain.
+
-   Pass Audita the resolved value and safe reference name; deliver the value only
+Status: Complete.
-   through the child environment's existing `AUDITA_LLM_API_KEY` override.
+
-   Do not re-read the environment for an explicitly resolved reference.
+Completion marker (2026-09-22): Added a deterministic transport regression
-3. Adapt every serialization, digest, source/diff output, diagnostic, generated
+that abandons a partially consumed original request, obtains and parses a fresh
-   invocation config, manifest, and provenance caller to safe reference names.
+multipart replay from `GetBody`, and installs the returned transcript within one
-   Never YAML-marshal ConfigKit's opaque secret directly or call `Value()` in an
+application attempt. Covered replay open/read failures, early responses,
-   inspection path. Secret changes alone must not alter effective digests or
+parent cancellation during replay, and disposal of every opened source, while
-   invalidate artifact evidence; reference-name changes may change provenance.
+proving an abandoned original does not poison a valid replay. Added a real HTTP
-4. Keep ConfigKit errors structured and safe. Domain validation messages must
+retry-exhaustion integration that durably retains an earlier speaker and resumes
-   avoid raw credential values; do not unwrap private parser errors or interpolate
+only the uncommitted speakers. This controlled boundary verifies Narratio's
-   whole trusted configuration structs into error messages.
+replay contract, not recovery from every real proxy protocol failure. Verified
-5. Preserve downstream tool ownership for Notarius/Scriptorium credentials that
+with `go test ./internal/adapters/whisperx ./internal/app ./internal/stage`,
-   Narratio does not configure. Do not add a parallel credential schema for them.
+`go test -race ./internal/adapters/whisperx ./internal/app ./internal/stage`,
-
+ten repeated race-enabled adapter runs, and `git diff --check`.
-Acceptance: use distinctive synthetic secrets to prove no leakage in show, sources,
+
-diff, catalog-ready projections, success/failure diagnostics, manifests, or generated
+Preparation: Existing injectable HTTPClient/RoundTripper seam and local-server
-Audita configuration. Verify the child receives the credential and an environment
+tests in `internal/adapters/whisperx/http_test.go`; app WhisperX wiring tests.
-change after loading does not change explicit delivery. Test S3 paired references,
+
-partial-pair rejection, missing effective references, and nil SDK fallback offline.
+1. Add a deterministic transport-boundary regression: consume part of the
-Update adapter and credential documentation and remove obsolete lookup tests.
+   original request, close it as a transport would, call GetBody, consume and
-
+   parse the replay using the request Content-Type, then return valid JSON.
-## Stage 8 — Infer and normalize artifact dependencies once
+   Verify exact audio/language, installed output, and one application attempt.
-
+   This must fail before replay support; merely checking non-nil GetBody is
-Status: Complete — Finalized one normalized artifact graph from explicit ordering
+   insufficient. Do not assert Go's internal retry count or require a flaky
-edges and configured-artifact inputs (including rewritten family members), retained
+   handcrafted HTTP/2 peer in the default suite.
-edge origins for diagnostics, and verified focused/full tests plus the full race
+2. Cover replay-open/read failure, early response, parent cancellation during
-suite and an assembled input-only analyze workflow.
+   replay, and disposal of all body handles. Reuse Stage 5 body coverage rather
-
+   than repeat every low-level case. Prove an intentionally abandoned original
-Read: `internal/config/validate_scriptorium.go`, `artifact_families.go`,
+   body does not turn a valid replay response into failure.
-`internal/artifactpolicy`, `internal/artifacts`, analyze planning/execution, and
+3. Retain local HTTP tests for application retries, non-retryable responses,
-their artifact dependency and semantic-evidence tests.
+   response limits, invalid JSON, and bounded streaming; exercise that an
-
+   exhausted HTTP failure still leaves earlier speaker checkpoints reusable
-1. At the final configuration resolution boundary, union explicit `depends_on`
+   using the existing stage/app seams.
-   with configured-artifact input references. Use the existing source-ID parser;
+4. Record the verification boundary honestly: controlled transport replay proves
-   do not infer edges from filenames, arbitrary strings, or non-artifact inputs.
+   Narratio's body contract, not recovery from every real proxy PROTOCOL_ERROR.
-2. Infer after family member inputs become concrete `narratio.artifact.<key>`
+
-   sources. Normalize, deduplicate, and sort the effective dependency list once.
+Verify: `go test ./internal/adapters/whisperx ./internal/app ./internal/stage`
-   Keep explicit ordering-only dependencies valid. Repeated finalization must not
+and race tests for changed packages.
-   accumulate edges or alter ordering. Store source-edge attribution separately
+
-   from the effective graph for diagnostics and generated provenance.
+Done when the replay defect is protected at the adapter boundary and the
-3. Apply existing existence, self-reference, enabled-dependency, output, and cycle
+application retry/checkpoint behavior remains intact.
-   validation to the union. Remove the error requiring an input to be repeated in
+
-   `depends_on`. Retain diagnostics pointing to the explicit list entry or the
+## Stage 7: Document and Validate the Completed Feature
-   input that contributed an invalid edge, including family origin where relevant.
+
-4. Ensure execution, targeted analysis, planning, prerequisite closure, reuse,
+Status: Complete.
-   forced regeneration, and semantic evidence consume this same concrete graph.
+
-   No adapter or command may infer a second graph. Refresh final projection/digest
+Completion marker (2026-09-22): Updated the canonical transcribe, merge,
-   after inference; equivalent explicit and inferred declarations compare equally.
+manifest, WhisperX, operations, and troubleshooting documentation for durable
-
+speaker reconciliation, serialized checkpoints, aggregate gating, durable
-Acceptance: cover input-only dependency ordering, duplicate explicit/inferred edges,
+force reset, legacy upgrade and downgrade limits, replayable streaming bodies,
-ordering-only edges, missing/self/cyclic references, and rewritten family inputs.
+resource ownership, and the absence of an exactly-once remote guarantee.
-Use an assembled fake-artifact workflow to prove upstream output is supplied to a
+Reviewed the completed implementation against the feature roadmap and
-dependent artifact and failure/resume retains successful predecessors. Existing
+implementation-discipline guidance. Verified with `go test ./...`,
-force/selection and invalidation tests remain valid. Update config and analyze
+`go test -race ./...`, `go vet ./...`, `go build ./...`,
-internals with the implemented inference rule.
+`go test ./internal/doccheck`,
-
+`go test ./internal/config -run '^TestExamplesLoadAndValidate$'`, and
-## Stage 9 — Add the effective artifact catalog command
+`git diff --check`.
-
+
-Status: Complete — Added the read-only `config artifacts` catalog over finalized
+1. Update canonical transcribe and manifest internals for the collection,
-configuration, including effective dependencies and definition/family/party
+   reconciliation, durable-reset force behavior, serialized saves, and aggregate
-provenance; documented it and verified focused, full, and race test suites.
+   gate. Remove obsolete all-speakers-before-canonical-write descriptions.
-
+2. Update the WhisperX contract for replayable bounded streaming, application
-Read: `internal/app/config_commands.go`, config diff/source rendering, the safe
+   attempts versus transport replay, resource ownership, and the lack of an
-projection and family-origin catalogs, and `docs/cli.md`.
+   exactly-once server guarantee. Do not claim the remote protocol issue is fixed.
-
+3. Update operations/troubleshooting with ordinary resume versus force, durable
-1. Add `narratio config artifacts` to dispatch and help. Reuse ordinary pipeline,
+   partial success, old-manifest one-time retranscription on selecting transcribe,
-   profile, campaign, campaign-file, and secrets-directory parsing/resolution.
+   downgrade limitations, and private-model-change guidance. No new CLI flags
-   Resolve a campaign when families require it or when explicitly selected; a
+   or promises of automatic historical-file recovery. Keep detailed wire and
-   pipeline with only ordinary artifacts can be inspected without a campaign.
+   storage contracts in their canonical owners.
-2. Render one stable record per effective concrete artifact in key order with
+4. Review changes against the feature roadmap and the implementation-discipline
-   key, `narratio.artifact.<key>` source ID, defining source location(s), enabled
+   guidance. Do not elevate selected storage encoding, internal ordering, test
-   state, output path, and sorted effective dependencies. Family members additionally
+   synchronization, or exact error wording into new product guarantees.
-   identify family key, character ID, defining family source, and party source.
+5. Run the full repository gates below; document results and update completion
-3. Derive identity from the map key. A profile may contribute to an existing
+   statuses only after they pass. Leave release preparation for a separate task.
-   artifact, so report contributing definition locations instead of inventing
+
-   a single filename owner. Use a deterministic escaped tabular text rendering;
+```sh
-   include a header and no records for an empty catalog. Propagate writer errors.
+go test ./...
-4. Use the same finalized state as show/sources/diff and runtime configuration.
+go test -race ./...
-   No session download, adapter initialization, manifest access, or workspace
+go vet ./...
-   materialization is allowed. Secret bootstrap remains the agreed startup exception.
+go build ./...
-
+go test ./internal/doccheck
-Acceptance: CLI tests cover ordinary and generated artifacts, disabled entries,
+go test ./internal/config -run '^TestExamplesLoadAndValidate$'
-profile-added/overridden artifacts, empty catalog, no-campaign ordinary inspection,
+git diff --check
-required-campaign failure for families, stable ordering, and no runtime side effects.
+```
-Check identity stays the same after moving an artifact file without changing its key.
-Document the command in its canonical CLI owner and link to config layout examples.
-
-## Stage 10 — Finish the operator layout and v2 migration documentation
-
-Status: Complete
-
-Completion: Reworked the maintained bundle around an unprofiled production base,
-one-entry artifact and family imports, and a testing overlay; updated the example
-harness and inspection workflows; consolidated the v2 configuration guidance; and
-added the v2.0.0 operator migration checklist. Focused documentation/example tests,
-the offline inspection walkthrough, and the full normal/race suites pass.
-
-Read: roadmap “Artifact Definition Ergonomics” and “Compatibility and Migration”;
-`examples/README.md`, existing example bundles and their loader test,
-`docs/config.md`, `docs/operations.md`, `docs/release.md`, and internal configuration
-and artifact documentation.
-
-1. Convert maintained pipeline examples to a production base with explicit
-   `configkit.imports`, `artifacts/<key>.yml`, `artifact-families/<key>.yml`, and
-   `profiles/testing.yml`. Each recommended artifact/family file defines exactly
-   one explicit map entry. Fold old production overlays into the base.
-2. Include an input-only dependency example and at least two character-family
-   examples sharing a campaign-owned party roster. Keep supported inline artifacts
-   legal; file layout is guidance, not a filename-based validation requirement.
-3. Update the example validation harness to load root configurations and selected
-   testing profiles, not attempt to load each imported fragment as a full pipeline.
-   Use synthetic environment setup for explicit references. No example includes
-   real credentials or depends on local tools/cloud services to validate.
-4. Consolidate canonical documentation updates from earlier stages. Remove current
-   references to old composition/profile catalogs, default-profile configuration,
-   secrets.env_dir, credential `_env` fields, credential-free inspection guarantees,
-   paired diff snapshots, and removed platform support. Explain explicit-value and
-   null changes without promising reloadable inspection output.
-5. Add `docs/releases/v2.0.0.md` using the release-note structure, with a concrete
-   migration checklist linking to the canonical config/CLI docs and examples.
-   Include static S3-reference migration versus SDK credential discovery, new
-   inspection prerequisites, artifact input dependency inference, and platform
-   removals. Do not claim publication or edit older immutable release notes.
-
-Acceptance: `go test ./internal/doccheck` and
-`go test ./internal/config -run '^TestExamplesLoadAndValidate$'` pass. Walk through
-the new operator examples with config validate/show/sources/diff/artifacts offline.
-Their identities, family members, origins, and testing overrides agree.
-
-## Stage 11 — Verify the complete migration and remove remaining scaffolding
-
-Status: Complete
-
-Completion: Audited the accepted roadmap and the full change set from `1558c9c`;
-no legacy configuration loader, profile/composition traversal, presence store,
-custom secrets loader, or production YAML decoder remains. The migration removes a
-net 1,235 production and 843 test Go lines; remaining configuration code owns domain
-defaults, normalization, validation, expansion, provenance, and safe projections.
-Go 1.26.7 module hygiene, tests, race tests, vet, build, documentation, examples,
-and the v2.0.0 release-candidate checker pass. Linux amd64 was tested natively;
-Linux arm64 and macOS arm64 release assets were cross-built, with native macOS
-arm64 validation remaining best effort and outside the release gate.
-
-Read: the whole feature roadmap, completed stage notes, and the current test and
-release procedures. Review the diff from the commit introducing this plan.
-
-1. Audit every roadmap requirement against current code and executable evidence.
-   Remove temporary migration adapters and any residual generic YAML parser,
-   composer, profile traversal, explicit-presence store, old secrets loader,
-   decoder hooks, or unused tests. `gopkg.in/yaml.v3` may remain for output encoding
-   and unrelated external formats; it must not supply a second configuration loader.
-2. Confirm result-owned snapshots versus final expanded configuration are handled
-   consistently; every inspection/runtime path sees normalized inferred dependencies
-   and generated publish rules. Recheck secret safety and semantic resume boundaries.
-3. Inspect current platform conditions and asset lists. Retain historical notes but
-   no active Windows/macOS amd64 obligation. Compare owned production/test code
-   before and after; report removals and any remaining complexity with reasons.
-   Do not chase a LOC quota by removing useful domain checks or regressions.
-4. Run the repository gates with the maintained Go 1.26 toolchain:
-
-   ```sh
-   go test ./...
-   go test -race ./...
-   go vet ./...
-   go build ./...
-   go test ./internal/doccheck
-   go test ./internal/config -run '^TestExamplesLoadAndValidate$'
-   ```
-
-5. Run `scripts/check-release-candidate.sh v2.0.0` after the release note and all
-   candidate changes exist. This also verifies module hygiene and all three
-   release assets with `GOWORK=off`. Resolve failures; do not bypass checks or
-   publish a tag. Record native versus cross-build evidence accurately.
-
-Acceptance: all gates pass and every roadmap outcome has direct evidence. No
-dependency on the sibling ConfigKit checkout remains. Record completion and any
-best-effort platform limitations, then hand off for a separate release decision.
 
 ## Open Questions
 
-None required before implementation. The agreed roadmap and the explicit choices
+None requiring user input. The agreed roadmap supplies the product decisions;
-above resolve the migration decisions. Upstream credential-free inspection and
+this plan selects a completed-only manifest collection, conservative old-record
-native macOS arm64 CI remain deferred, not prerequisites for this plan.
+handling, and pull-based replay as implementation choices. No stronger remote
+reliability guarantee, new operator restriction, or generic orchestration
+surface is proposed.

docs/roadmap/notarius-config-profile.md

@@ -0,0 +1,151 @@
+# Notarius Configuration Profile Selection
+
+Status: Implemented.
+
+## Goal and Authority
+
+Implement the consumer behavior in the
+[feature request](feature-request-notarius-config-profile.yml): let a Narratio
+configuration overlay explicitly select a Notarius configuration overlay.
+Operators can select testing once in Narratio while each application retains
+ownership of its own model choices and other settings.
+
+This roadmap describes the target state and required change areas, not an
+implementation sequence; the [implementation plan](implementation.md) owns
+the ordered work and implementation decisions. The feature request is the scope
+authority; the mechanisms suggested below do not establish additional
+user-facing contracts.
+
+## Underlying Issue
+
+Narratio can select its own testing profile, but extraction currently invokes
+Notarius without a configuration-profile selector. Consequently, a Narratio
+testing invocation cannot explicitly select the independently deployed Notarius
+testing overlay through pipeline configuration.
+
+Adding individual downstream model or tuning fields would duplicate Notarius's
+configuration responsibilities. Passing its existing profile selector provides
+the requested flexibility without that duplication.
+
+## Targeted End State
+
+### Explicit Configuration Composition
+
+`pipeline.notarius.config_profile` is an optional Notarius configuration-profile
+name, usable in Narratio's base configuration and ordinary overlays. For
+example, Narratio's `profiles/testing.yml` may contain:
+
+```yaml
+notarius:
+  config_profile: testing
+```
+
+Selecting Narratio's `--profile testing` then selects that explicit downstream
+profile whenever extraction executes. The two profile names need not match.
+Narratio does not automatically forward its own profile name.
+
+When supplied, the selection is passed through Notarius's `--config-profile`
+argument. Omitted or null values add no profile-selection flag and preserve
+existing downstream selection behavior. Notarius's selector semantics remain
+authoritative, including empty and `default` selections for the composed base
+configuration. Narratio does not introduce a stricter profile-name policy.
+
+This field selects a ConfigKit configuration overlay, not a PromptKit profile
+through `--llm-profile`. The Notarius overlay owns any resulting LLM-profile
+selection. Notarius resolves overlays relative to its own configuration root;
+Narratio neither resolves those files against its own root nor rewrites them.
+
+### Execution, Reuse, and Failure
+
+A changed downstream profile selection must not silently reuse Narratio's
+completed extraction from the previous selection. Existing dependent-stage
+invalidation applies when extraction changes; the feature does not change the
+pipeline order or transcript-generation behavior.
+
+Notarius continues to own downstream overlay discovery, composition, validation,
+and cache compatibility. A missing or invalid selected overlay must fail
+extraction through the existing subprocess error path, without silently falling
+back to production or reporting successful extraction.
+
+Existing resume and chunk-cache controls, including force precedence, remain
+in place. Profile selection does not itself mean forced regeneration or cache
+deletion. Narratio's decision to execute extraction and Notarius's decision to
+reuse compatible work remain separate responsibilities.
+
+Changes to private Notarius configuration behind an unchanged selector retain
+the existing operator responsibility to force extraction when needed. There is
+no new downstream file inspection or content-tracking requirement.
+
+Credential forwarding remains independently configured through
+`notarius.llm_api_key`. A Narratio testing overlay may select a different
+credential reference alongside the downstream profile; no new credential
+discovery or provider-name mapping is introduced.
+
+## Required Change Areas
+
+### Configuration and Inspection
+
+Extend the typed Notarius configuration and its existing safe effective-YAML
+projection to carry the optional field. Preserve the ordinary configuration
+composition behavior for base values, overlay overrides, and null values.
+Configuration inspection must reflect the selected field without exposing
+credential values. No replacement configuration loader or downstream preflight
+loader is needed.
+
+### Stage and Adapter Boundary
+
+Carry the selection from resolved configuration through the extraction request
+to the subprocess adapter. Construct the optional CLI flag using the existing
+argument-vector mechanism, alongside the current configuration path, references,
+credential forwarding, and cache controls. Retain normal Notarius error handling.
+
+### Extraction Reuse Evidence
+
+Account for the downstream selection in the existing extraction reuse evidence.
+The current semantic-configuration and invocation fingerprints are the relevant
+change points. Keep their treatment of selection consistent so that a profile
+change cannot bypass the required rerun and downstream invalidation.
+
+This roadmap does not require a new manifest schema, separate profile-indexed
+workspaces, historical per-profile result retention, or an upgrade-wide forced
+rerun.
+
+### Verification and Documentation
+
+Use focused behavioral coverage for configuration composition and inspection,
+explicit argument forwarding and omission, changed-selection reuse decisions,
+and ordinary subprocess failure handling. Reuse existing test coverage where
+it already protects unchanged credentials, force behavior, and invalidation;
+do not duplicate Notarius's complete profile-validation or cache test suites.
+
+When implemented, update the canonical
+[configuration reference](../config.md),
+[Notarius integration contract](../integrations/notarius.md),
+[extract internals](../internal/stage-extract.md), and relevant maintained
+examples. The development workflow in [Operations](../operations.md) should
+explain explicit profile composition and the existing need to force extraction
+after private downstream edits. Clarify that profile selection does not create
+an isolated testing workspace or separate current extraction state.
+
+## Compatibility and Scope Boundaries
+
+Notarius v0.7.0 already documents `--config-profile`; no upstream change is
+required. Document the capability needed when the option is used, without adding
+an unconditional runtime version gate for existing unconfigured deployments.
+
+This feature adds no Narratio CLI selector, automatic profile propagation,
+Notarius LLM-profile selector, downstream configuration rewriting, new
+credential mechanism, or generalized recursive orchestration. Existing output
+and receipt contracts remain unchanged.
+
+The consumer's Ansible role and suite updates are follow-up work outside this
+repository. They can deploy downstream overlays and populate this field after
+the interface is released.
+
+## Scope Review
+
+No stronger requirements or new invariants are proposed beyond the feature
+request and existing repository contracts. In particular, minimizing one-time
+upgrade invalidation and avoiding reruns between equivalent base selectors are
+implementation considerations, not additional acceptance guarantees imposed
+by this roadmap. No user decisions are currently required before planning.

docs/roadmap/remediation.md

@@ -1,331 +1,104 @@
-# ConfigKit Migration Review — Required Remediations
+# Transcription Checkpoint Review Remediation
-
+
-Reviewed 2026-09-07 at `f7a40af`, against the changes after `1558c9c`, the
+Status: Complete.
-[feature roadmap](configkit-adoption.md), and the completed
+
-[implementation plan](implementation.md).
+Reviewed commits `7b0bf99` through `96b4e73` against the speaker-checkpoint and
-
+upload-replay roadmap and the original user request. No production changes were
-The main migration is implemented. The following findings are reproducible gaps
+made during review. The two failures below were reproduced with temporary tests
-in the intended behavior, not proposals to restore retired compatibility or
+using the existing stage fixtures; those temporary tests were removed afterward.
-filesystem restrictions. P2 denotes a correctness issue to fix before release;
+
-P3 denotes an operator-facing completeness issue also required by the accepted
+## 1. Reconcile Aggregate State Even When No Speaker Needs HTTP Work
-plan. No application code was changed during this review.
+
-
+Priority: P2. Status: Complete.
-## 1. Derive explicit publish destinations after family expansion
+
-
+Implemented read-only aggregate identity/evidence checks before resume skips.
-Status: Resolved — P2
+Regression tests cover removed inputs, missing/duplicate/mismatched outputs,
-
+repair without HTTP requests, downstream invalidation, and exclusion of removed
-Resolution: Missing destinations are now derived through one shared domain helper
+speakers from merge without deleting their files. Equivalent path forms and
-both during ConfigKit resolution and again after concrete family expansion. Explicit
+output ordering remain reusable. Focused app/stage tests and documentation
-destinations remain unchanged, while unknown sources still fail read-only publish
+checks pass.
-validation. Regression coverage verifies resolved runtime and effective inspection
+
-output for generated members, explicit overrides, and unknown sources.
+Location: `internal/stage/transcribe_resume.go:21` and the reconciliation result
-
+consumed there.
-**Evidence:** `internal/config/pipeline_configkit.go:208` derives missing publish
+
-destinations during the ConfigKit resolver. A concrete family member does not
+`ValidateResume` returns reusable whenever `reconciliation.work` is empty. That
-exist yet, so the resolver ignores the failed derivation. After family expansion,
+only establishes that the remaining speakers need no transcription; it does
-`internal/config/artifact_families.go:141` calls the now-read-only publish
+not establish that the stored speaker collection and aggregate outputs match
-validator, which rejects the still-empty destination. The previous implementation
+the current input set. Removing a speaker while the remaining inputs are
-could derive it during that later validation.
+unchanged produces an empty work list, so a succeeded record can be skipped
-
+without pruning the removed speaker. Its old aggregate output can then remain
-**Reproduction:** In an otherwise valid pipeline, define a family `meta` over
+available to merge. Likewise, missing/inconsistent aggregate output references
-`party.characters`, with output pattern `artifacts/{character_id}.md`. Select a
+are not repaired when all individual checkpoints remain valid. A prepare rerun
-valid campaign whose party contains `alice`, and add:
+may already stale transcribe in some workflows, but the resume validator cannot
-
+rely on that to satisfy its own current-input/output checks.
-```yaml
+
-publish:
+Reproduction: create complete alice/bob checkpoint records and aggregate
-  outputs:
+outputs with the existing fixture, mark the stage succeeded, remove bob from
-    - source: narratio.artifact.meta_alice
+the manifest's audio inputs, and call `ValidateResume`. It returns reusable
-```
+despite still retaining bob in the stored collection and aggregate outputs.
-
+
-`config validate --config <pipeline> --campaign-file <campaign>` fails with
+Required change:
-`pipeline.publish.outputs[0].dest is required when destination cannot be derived
+
-from "narratio.artifact.meta_alice"`. Adding `dest: artifacts/alice.md` makes the
+- Distinguish no HTTP work from no reconciliation work. Validate that the
-same configuration pass. The destination is therefore available and derivable;
+  committed speaker set and aggregate transcript references represent the
-the lifecycle omits the required final normalization step.
+  reconciled current set, including relevant identity/evidence, before skipping.
-
+- When only collection/output repair is needed, return non-resumable and let
-**Required change:** Complete publish destination resolution after concrete
+  normal execution checkpoint the pruned collection and rebuild aggregate
-artifacts exist, before publish validation and final projection/digest generation.
+  outputs without retranscribing reusable speakers. Preserve existing dependent
-Share the domain derivation logic and keep validation read-only. Preserve
+  invalidation; do not force otherwise-current speaker jobs.
-explicit destinations and generated family publish-rule collision checks. Do not
+- Keep resume inspection read-only. Do not fix this by deleting incidental
-require redundant `dest` fields or revive mutation inside validators.
+  transcript files or changing stage selection rules.
-
+
-**Acceptance:** Test an explicit publish source naming a generated member with
+Verification: add removed-only input coverage (not just removal combined with
-omitted destination, an explicit destination override, and a genuinely unknown
+an added speaker), plus incomplete/inconsistent aggregate output coverage.
-source. Validate both effective inspection and resolved runtime configuration.
+Exercise the runner skip path and assert zero additional WhisperX requests,
-
+correct rebuilt outputs, and no removed speaker reaching merge.
-## 2. Stop re-defaulting an explicitly empty Notarius working directory
+
-
+## 2. Remove the Unrequested Positive Audio-Size Requirement
-Status: Resolved — P2
+
-
+Priority: P2. Status: Complete.
-Resolution: Removed both legacy blank-value fallbacks after ConfigKit resolution.
+
-An omitted working directory is still derived by the presence-aware resolver, an
+Audio evidence now permits zero size while still rejecting negative values.
-explicit relative directory is still rooted at the pipeline, and explicit empty or
+Regression tests verify zero-size manifest round trips, successful service
-whitespace-only values remain empty and fail enabled-Notarius validation. Existing
+results being checkpointed and reused, and service rejection being propagated
-relocation-invariant digest coverage remains green.
+without creating a completion record. Nonempty valid-JSON output validation is
-
+unchanged. Both new success regressions failed before the fix.
-**Evidence:** ConfigKit's resolver correctly uses presence-aware defaulting at
+
-`internal/config/pipeline_configkit.go:180`. However,
+Location: `internal/manifest/transcribe_state.go:95`.
-`internal/config/load.go:454` subsequently replaces any blank working directory
+
-with the config file's directory, irrespective of input presence.
+The new record validator requires `AudioSize > 0`. Previously Narratio accepted
-`internal/config/effective_digest.go` also applies a blank-value fallback while
+a regular `.flac` file and delegated transcription acceptance to WhisperX;
-capturing logical paths. These retained legacy fallbacks bypass the new rule that
+neither the user request nor the roadmap introduced minimum audio size or a new
-defaults apply only to absent fields.
+audio-content validation policy. Zero-byte content still has a valid checksum
-
+and can be represented by the checkpoint mechanism. The current check runs
-**Reproduction:** Set `notarius.enabled: true`, a valid config path, pipeline ID
+after a successful response and output materialization, causing the entire
-and output map, and `notarius.working_directory: ""`. With
+stage to fail instead of retaining the completed work.
-`config_path: notarius/config.yml`, `config show` succeeds and reports
+
-`working_directory: notarius`; validation never sees the explicit invalid blank.
+Reproduction: prepare one speaker, replace its prepared audio with an empty
-
+regular file, and use the existing successful fake WhisperX client. Stage
-**Required change:** Let the ConfigKit resolver own the absent-field default.
+execution fails at checkpoint validation with `audio_size must be positive`.
-The subsequent runtime and logical-path conversions must preserve explicit
+This demonstrates the extra Narratio restriction; it does not assert that a
-emptiness so enabled-Notarius validation can reject it. Remove duplicate
+particular production WhisperX deployment accepts empty audio.
-value-based defaulting rather than adding another private presence mechanism.
+
-
+Required change:
-**Acceptance:** Omission still derives the expected directory; explicit empty
+
-and whitespace-only values fail when Notarius is enabled; a configured relative
+- Permit zero audio size and reject negative sizes. Keep byte hashing and
-directory resolves from the pipeline root. Preserve digest relocation invariance.
+  size equality checks. Let the downstream service decide whether the input
-
+  can be transcribed, as before.
-## 3. Enforce unique base definitions even when a profile removes them
+- Do not remove the nonempty valid-JSON output requirement, which has a separate
-
+  existing justification. Do not add a new early empty-audio rejection instead.
-Status: Resolved — P2
+- Update any new tests/documentation that promote strictly positive input size
-
+  to a contract.
-Resolution: Loading now discovers base declarations through ConfigKit's public
+
-historical-path enumeration and metadata history from the selected result,
+Verification: cover a zero-size record round-trip and successful adapter result
-without separately resolving the base (see finding 7). Duplicate ordinary or
+being checkpointed/reused for that input; retain negative-size rejection and
-family definitions therefore fail even when an overlay nulls their container or
+ordinary downstream-failure tests.
-all of Scriptorium. A single base owner
+
-with a legitimate profile override remains supported.
+## Verification After Remediation
-
+
-**Evidence:** `rejectDuplicateBaseDefinitions` at
+Completed on 2026-09-22 with Go 1.26.8: focused stage/application tests,
-`internal/config/pipeline_configkit.go:354` enumerates only artifact/family keys
+changed-package race tests, `go test ./...`, `go test -race ./...`,
-remaining in the final typed configuration. It inspects history for those keys
+`go vet ./...`, `go build ./...`, `go test ./internal/doccheck`,
-but never examines base declarations removed by an overlay.
+`go test ./internal/config -run '^TestExamplesLoadAndValidate$'`, and
-
+`git diff --check` all passed. Existing replay and cancellation regression
-**Reproduction:** Import `first.yml` defining
+tests remain intact; the HTTP adapter required no changes.
-`scriptorium.artifacts.recap.prompt_id` and `second.yml` defining
-`scriptorium.artifacts.recap.output_path`. Base validation correctly rejects the
-two-file declaration. Add `profiles/clear.yml` containing:
-
-```yaml
-scriptorium:
-  artifacts: null
-```
-
-The same root with `--profile clear` passes. A selected profile can thus hide the
-base ownership conflict, contrary to the plan's unique base-definition rule.
-This concerns disjoint contributions to one artifact, not ConfigKit's generic
-conflicting-leaf checks, which still work.
-
-**Required change:** Discover the complete base declaration set through public
-ConfigKit metadata/history, including declarations displaced by an overlay, and
-validate ownership independently of final effective-key survival. Keep legitimate
-profile overrides and profile-only definitions supported. Do not reparse source
-YAML or add a second composer.
-
-**Acceptance:** Cover duplicate ordinary and family definitions hidden by a null
-artifact/family container or null Scriptorium section. Base and selected-profile
-loads must reject the same base conflict, while a single base declaration with a
-valid overlay remains accepted.
-
-## 4. Preserve null versus empty collections in effective YAML
-
-Status: Resolved — P2
-
-Resolution: Effective YAML is now emitted from the credential-safe JSON value
-projection through an output-only YAML-node conversion. Explicit nulls, empty maps,
-empty slices, booleans, strings, and exact JSON numbers retain their semantic types.
-Public show/diff tests cover null and empty maps and slices, while digest,
-credential-redaction, deterministic output, and exact-integer coverage remain intact.
-
-**Evidence:** `internal/config/effective_pipeline.go:154` marshals the typed
-projection directly with `yaml.Marshal`. The encoder emits nil slices as `[]`
-and nil maps as `{}`, while the JSON projection used by diff and digest preserves
-them as `null`. The shared input type does not guarantee shared output semantics.
-
-**Reproduction:** Set `audita.modules: null` in a valid base and
-`audita.modules: []` in `profiles/empty.yml`. Both `config show` invocations emit
-`modules: []`, but `config diff default empty` reports:
-
-```text
-changed audita.modules null []
-```
-
-The commands disagree about the effective value. The same renderer also supplies
-the resolved pipeline diagnostic written by prepare.
-
-**Required change:** Render YAML from a credential-safe projection that explicitly
-preserves nulls and empty collections, consistently with the semantic projection.
-Keep exact integers and safe credential reference names. An output-only conversion
-is appropriate; do not restore YAML decoding or a configuration parser. This
-requires truthful inspection, not a guarantee that inspection output is reloadable.
-
-**Acceptance:** Verify null versus empty maps and slices through the public show
-boundary, and agreement with diff/digest distinctions. Retain credential-leakage
-and exact-integer regression coverage.
-
-## 5. Complete provenance for generated artifacts and inferred dependencies
-
-Status: Resolved — P3
-
-Resolution: Generated catalog records now collect the complete base/profile family
-definition set from ConfigKit history. Effective source ownership for materialized
-dependency lists is rebuilt narrowly from retained explicit-list and input-edge
-origins, including mixed and generated-family dependencies. CLI tests verify a
-profiled family catalog agrees with generated source attribution and that inferred
-ordinary edges name their input contributor instead of the central default.
-
-Two new reporting paths lose available declaration information:
-
-- **Profile contributions to family members:**
-  `internal/config/artifact_catalog.go:52` fills a generated member's definitions
-  from the single `member.Source`. That source is chosen by the first matching
-  non-default family field in `artifactFamilySource`, not the full set of effective
-  contributors. Define family `meta` in the base and override its `prompt_id` in
-  `profiles/testing.yml`. `config artifacts --profile testing` reports only the
-  base file for `meta_alice`, even though `config sources` correctly attributes
-  that member's prompt to the testing overlay.
-- **Inferred ordinary dependencies:** With `second.inputs.prior.source` set to
-  `narratio.artifact.first` and no explicit dependency list, `config sources`
-  reports `scriptorium.artifacts.second.depends_on` as `default / default`.
-  `finalizeArtifactDependencies` stores the input-edge origin, but the effective
-  ownership projection retains the pre-inference default attribution from
-  `internal/config/effective_digest.go:55` and does not consult that origin.
-
-**Impact:** Operators inspecting a testing profile or following a dependency can
-be directed to the wrong file or told a user-derived value is a central default.
-Runtime ordering and generated artifact values were correct in these reproductions.
-
-**Required change:** Use ConfigKit's contributing locations for family definition
-sets, as for ordinary artifacts, and add narrow generated attribution for inferred
-dependency lists using their retained edge origins. Preserve family/character/party
-identity and deterministic ordering. Avoid introducing a second general provenance
-store or choosing a file based on the first alphabetically visited field.
-
-**Acceptance:** A profiled family catalog exposes both relevant files; an inferred
-edge points back to its input declaration; mixed explicit/inferred dependencies
-retain their relevant contributors. Verify catalog and sources agree after expansion.
-
-## 6. Surface successful secrets bootstrap reports, including skipped empty variables
-
-Status: Resolved — P3
-
-Resolution: Successful bootstrap reports now flow once through the command
-diagnostics channel, while direct internal command calls default that channel to
-discard. ConfigKit's value-free report makes skipped existing empty variables
-explicit and remains available before later typed-load failures; structured output
-stays isolated on stdout. Command-level coverage verifies successful reporting,
-skipped-empty reporting, value redaction, clean config-show output, and one report
-for a two-profile diff.
-
-**Evidence:** `internal/app/secrets_bootstrap.go:36` discards the report whenever
-`LoadSecretsDir` returns no error. Reports are only rendered when directory
-bootstrap itself fails. This does not implement the roadmap's safe bootstrap
-reporting boundary or Stage 6's warning presentation requirement.
-
-**Reproduction:** Place a synthetic key in `secrets/NARRATIO_REVIEW_KEY`, reference
-it from `audita.llm_api_key`, and invoke config validation with
-`NARRATIO_REVIEW_KEY=` in the environment. ConfigKit correctly skips the file
-because the variable already exists, then typed loading fails with `secret.empty`.
-Narratio shows only that load failure, omitting the bootstrap report's
-`skipped_existing` and `ExistingEmpty` information. A successful load likewise
-discards all bootstrap results.
-
-**Required change:** Retain and render or summarize the safe report once per
-invocation through a diagnostic output channel, including when a later typed load
-fails. Make skipped-existing-empty outcomes explicit. Preserve process environment
-precedence and the existing partial report on failure; keep values out of all
-diagnostics and keep structured/YAML stdout uncontaminated. Do not add bootstrap
-rollback, retries, or repeated directory loading.
-
-**Acceptance:** Command-level tests demonstrate safe success/report output and a
-useful skipped-empty diagnostic, without leaking a synthetic secret or polluting
-show output. A two-profile diff still bootstraps and reports only once.
-
-## 7. Do not resolve unused base credentials when loading a profile
-
-Status: Resolved — P2
-
-Resolution: Upgraded to released ConfigKit v0.1.2 and replaced the extra base load
-with `Metadata.HistoricalPaths()` enumeration of declaration paths in the selected
-result. Ownership checks still inspect base-layer history for both ordinary
-artifacts and families, even when overlays remove them. Regression tests verify
-that a profile can replace an unset production credential with a resolvable testing
-reference or remove it with null. Existing hidden-duplicate and legitimate-override
-tests remain intact. No local dependency replacement or second composer is needed.
-
-Follow-up review: 2026-09-07 at `3ce1981`. The original six reproductions are
-addressed, but the fix for finding 3 introduces this regression.
-
-**Evidence:** `internal/config/pipeline_configkit.go:49-57` loads the base again
-without a profile to check duplicate base definitions. This calls the complete
-typed ConfigKit loader, including secret resolution, domain resolution, and
-validation—not just declaration ownership inspection. Consequently, loading a
-valid testing profile also requires credentials from the unselected base.
-
-**Reproduction:** In an otherwise valid base, set `audita.llm_api_key` to
-`NARRATIO_REVIEW_PROD_KEY`. In `profiles/testing.yml`, replace it with
-`NARRATIO_REVIEW_TEST_KEY`. Leave the production variable unset and supply only
-the testing variable with a synthetic value. `config validate --config <root>
---profile testing` fails with `secret.unset` at the base credential declaration.
-Supplying both variables makes it pass. A profile that instead sets
-`audita.llm_api_key: null` also fails when the unused production variable is
-unset. Both failures were reproduced through the current CLI.
-
-**Impact:** Operators cannot use an independent testing credential environment
-or remove a production credential requirement through a profile. Commands fail
-despite having all credentials required by their effective configuration. The
-extra full load also unnecessarily repeats configuration processing.
-
-**Required change:** Enforce unique base ownership without requiring the
-unselected base to succeed as a separately resolved runtime configuration.
-Inspect complete declaration history through ConfigKit's public metadata,
-including declarations displaced by overlays. If additional upstream metadata
-support is needed, address that explicitly rather than requiring unused secrets,
-suppressing arbitrary load failures, reparsing YAML, or restoring a second
-composer. Preserve the duplicate-definition protection added for finding 3.
-
-**Acceptance:** Add public-boundary regression tests for a profile replacing an
-unset production credential with an available testing credential, and for a
-profile removing that credential with null. Both must load successfully without
-the production variable. Retain failures for duplicate base ordinary/family
-definitions hidden by null overlays, along with legitimate profile override and
-profile-only definition coverage. Resolve secrets only for the selected effective
-configuration.
-
-## Follow-up verification
-
-After adopting ConfigKit v0.1.2 and completing finding 7, the full
-`scripts/check-release-candidate.sh v2.0.0` check passed: module hygiene,
-formatting/whitespace, uncached tests and race tests, vet, build, documentation,
-maintained examples, and Linux amd64/arm64 plus macOS arm64 release cross-builds.
-`go mod verify` also passed. The new credential regressions failed before the
-ownership-check fix and passed afterward. No local module replacements, release
-tags, or pushes were used.
-
-At `3ce1981`, `go test ./...`, `go test -race ./...`, `go vet ./...`, and
-`go build ./...` passed. The new finding was reproduced with a freshly built CLI,
-temporary configuration files, and synthetic credentials; no external adapters
-or cloud services were invoked. That review pass changed only this review record.
-
-## Original verification and scope
-
-The following checks passed at the reviewed commit:
-
-- `go test ./...`
-- `go test -race ./...`
-- `go vet ./...`
-- `go build ./...`
-- The release asset builder for `v2.0.0`, producing exactly Linux amd64, Linux
-  arm64, and macOS arm64 assets; the Linux amd64 binary reported the expected version.
-
-The existing full suites include documentation and maintained-example checks.
-The findings above were additionally reproduced through a freshly built CLI with
-isolated temporary YAML fixtures and synthetic credentials. No live downstream
-tools or cloud services were invoked. Linux arm64 and macOS arm64 were cross-built,
-not tested natively. No tag was created or pushed.
-
-The migration removes a net 1,235 production Go lines and 843 test Go lines versus
-`1558c9c` (physical diff lines, including comments and whitespace). ConfigKit owns
-generic loading/composition; Narratio retains domain resolution, orchestration,
-safe inspection, and adapter delivery. These findings require completing that
-design, not reversing the simplification.

docs/roadmap/transcribe-checkpoints-and-replay.md

@@ -0,0 +1,183 @@
+# Resumable Speaker Transcription and Replayable Uploads
+
+Status: Implemented.
+
+## Goal and User Intent
+
+Preserve completed speaker transcriptions when another speaker fails, so an
+ordinary run or resume does not repeat expensive successful work. Separately,
+allow Go's HTTP transport to replay WhisperX uploads when it encounters a
+recoverable connection or stream failure.
+
+The motivating incident exhausted four transcription attempts for one speaker
+after three other speakers had completed. The final error reported an HTTP/2
+peer `PROTOCOL_ERROR` and an inability to replay the request body without
+`Request.GetBody`.
+
+These are related reliability improvements, not a promise to eliminate all
+service failures. This document owns the target state and scope; the
+[implementation plan](implementation.md) owns ordered changes and concrete
+storage and replay decisions.
+
+## Pre-implementation Limitations
+
+The [transcribe stage](../internal/stage-transcribe.md) writes successful
+responses into the invocation's run directory. It installs canonical transcripts
+and returns its per-file metadata only after every speaker succeeds. A failure
+therefore leaves no durable per-speaker progress that ordinary resume can use,
+even though some completed JSON files may remain on disk.
+
+The [WhisperX adapter](../integrations/whisperx.md) already retries requests at
+the application level, reopening audio for each attempt. Its multipart request
+body is streamed through a pipe and has no replay callback. Transport-level
+recovery within an attempt cannot reconstruct a consumed body. Providing that
+capability addresses the replay limitation, not the underlying peer protocol
+error; persistent failures can still require service or proxy investigation.
+
+## Targeted End State
+
+### Durable Per-Speaker Completion
+
+Each successfully transcribed speaker file is validated, saved, and recorded
+durably before that work is treated as reusable. The session manifest remains
+the progress authority. Follow the existing analyze-stage checkpoint pattern
+without turning speakers into pipeline stages or introducing a general task
+engine.
+
+Ordinary execution reconciles the current prepared audio set with recorded
+speaker results. It reuses valid completed work and schedules failed,
+unattempted, missing, or obsolete results. A result is not reusable merely
+because a matching filename exists. Evidence binds it to the speaker/audio
+identity, audio content, Narratio-visible recognition settings, and the saved
+transcript's integrity.
+
+The relevant recognition settings remain the WhisperX service URL and language.
+Retry count/delay, concurrency, timeout, credentials, and diagnostic locations
+remain operational settings rather than reasons to discard completed results.
+Changes to private service models or configuration remain an operator reason
+to force transcription; Narratio does not inspect the service's private state.
+
+Changes to individual audio inputs require replacement of affected results,
+not automatic retranscription of unrelated unchanged speakers. New speakers
+need transcription; removed speakers do not remain in the current aggregate
+output set. Records must describe the inputs actually used, not grant reuse to
+old bytes under a changed identity.
+
+### Aggregate Completion, Failure, and Force
+
+The overall stage succeeds only when every currently required speaker has a
+validated, durably recorded result. Incomplete per-speaker progress does not
+make the aggregate stage successful or authorize downstream consumption of an
+incomplete collection. Existing dependent-stage invalidation remains in effect.
+
+Retain bounded concurrency and the current fail-fast behavior: a speaker
+failure cancels outstanding work. Results already checkpointed remain reusable
+after failure, cancellation, or process interruption. A later ordinary run or
+resume retries the remaining work; it does not need a new CLI command.
+
+Checkpoint writes must be serialized so concurrently finishing speakers cannot
+overwrite each other's progress. A failed persistence operation must not
+advertise an unrecorded result as complete. Previously committed progress remains
+the recovery authority, and checkpoint errors must be surfaced rather than
+reported as successful transcription.
+
+`--force` on transcribe regenerates all currently required speakers instead of
+reusing their prior completions. Successful replacements are checkpointed too,
+so an ordinary retry after a failed forced invocation can retain the newly
+completed work. Old results for speakers not successfully regenerated must not
+satisfy that unfinished forced replacement on the next ordinary retry.
+
+This deliberately relaxes the current all-speakers-before-canonical-installation
+implementation: individual durable results may exist while the stage remains
+failed or incomplete. The all-speakers-before-stage-success boundary remains.
+
+### Replayable WhisperX Requests
+
+Provide `Request.GetBody` so the HTTP transport can obtain a fresh body for the
+same request. Replay reopens the audio and reproduces the multipart boundary,
+filename, fields, and framing used by the original request. Independent bodies
+must not share a consumed reader or mutable read position.
+
+Preserve bounded-memory streaming rather than buffering entire audio files in
+memory. Correctly close every original and replay body and its audio resources;
+preserve source-read errors and cancellation, including partial uploads and
+early server responses. Successful response handling must not accidentally wait
+on, or report errors solely from, an abandoned body instead of the replay that
+produced the response.
+
+Keep the existing application-level retry count, delay, classification, and
+per-attempt timeout semantics. Transport replays occur within an application
+attempt and its context; they are not additional Narratio-configured attempts.
+Do not add another custom retry loop, silently increase retries, or disable
+HTTP/2 globally as a substitute for replay support.
+
+The adapter still validates and installs only successful JSON responses.
+Request replay does not provide exactly-once server execution: a lost response
+can cause repeated transcription work, as can existing application retries.
+No new service-side idempotency protocol is required by this feature.
+
+## Required Change Areas
+
+- **Manifest and persistence:** Add transcribe-owned per-speaker progress and
+  evidence, with safe checkpoint updates and preservation through runner failure
+  handling. Review manifest validation, copying, serialization, and existing
+  publish/restore handling wherever the new records pass through those paths.
+- **Stage execution and reuse:** Reconcile speaker records before scheduling,
+  checkpoint validated completions, rebuild aggregate outputs from the current
+  set, and account for partial progress in ordinary and forced execution.
+  Review successful-stage reuse as well as failed-stage retries so stale audio
+  or missing/corrupt transcript evidence is not bypassed by an aggregate skip.
+- **Artifact lifecycle:** Use existing path, installation, integrity, and manifest
+  mechanisms. Ensure checkpointed results do not depend on an ephemeral run
+  directory surviving cleanup. Do not introduce a second authoritative ledger
+  or infer completion by scanning abandoned runs.
+- **HTTP adapter:** Make multipart bodies reproducible and correctly manage
+  every replay's lifetime, without changing the WhisperX HTTP schema or requiring
+  an upstream service change.
+- **Tests:** Cover per-speaker recovery after a later failure, interruption and
+  checkpoint failure; changed/missing inputs or outputs; force followed by an
+  ordinary retry; concurrent successful completions; and aggregate downstream
+  gating. Extend existing fixtures rather than duplicating analyze's complete
+  test suite. Exercise actual body reconstruction after partial consumption,
+  multipart equivalence, cancellation/resource cleanup, and existing bounded
+  streaming and retry behavior—not just the presence of a callback. Default
+  tests remain offline and use local/fake HTTP boundaries, never paid services.
+- **Documentation:** Update the canonical
+  [stage guide](../internal/stage-transcribe.md),
+  [manifest guide](../internal/manifest.md),
+  [WhisperX contract](../integrations/whisperx.md),
+  [operations guide](../operations.md), and
+  [troubleshooting guide](../troubleshooting.md) when implemented. Explain
+  partial completion, ordinary retry versus force, and the distinction between
+  request replay limitations and persistent peer protocol failures.
+
+## Compatibility and Scope Boundaries
+
+Existing speaker identities, raw transcript formats, and the fixed pipeline
+order remain unchanged. Existing manifests remain readable, but must not be
+treated as containing per-speaker evidence they never recorded. Recovery relies
+on verified recorded evidence, not guessed associations between old transcripts
+and current audio. No general legacy-migration framework is part of the feature.
+
+Automatic adoption of unrecorded outputs from previously failed runs is outside
+this feature. Such files may be recoverable after verifying their inputs, but
+their presence alone does not prove completion. No recovery/import command,
+speaker-selection CLI, historical invocation ledger, new service configuration
+discovery, or broader orchestration refactor is included.
+
+The feature does not diagnose the remote service/proxy's underlying HTTP/2
+problem, guarantee recovery from persistent protocol errors, or change the
+policy for continuing unrelated work after failure.
+
+## Completion Criteria
+
+For speakers A, B, C, and D: if A and B are checkpointed, C fails, and D has not
+completed, ordinary resume retains A and B, retries C, and completes D. No
+downstream stage receives an incomplete successful transcription collection.
+Force replaces all four, while an ordinary retry can reuse checkpoints from
+that forced replacement attempt.
+
+The HTTP transport can reconstruct the upload after consuming the original
+body, without whole-file memory buffering, lost source errors, or stranded
+upload resources. A persistent peer error still fails normally after the
+configured application attempts, without discarding checkpointed speakers.

docs/troubleshooting.md

@@ -213,6 +213,134 @@ input validation.
 
 Relevant reference: [Operations: Stage Execution and Continuation Behavior](./operations.md#stage-execution-and-continuation-behavior).
 
+## Transcription retries speakers that previously finished
+
+Symptom:
+
+- an ordinary transcribe retry calls WhisperX for a speaker that appeared to
+  finish earlier; or
+- an older successful session retranscribes all speakers once after upgrade.
+
+Likely causes:
+
+- the earlier response or canonical file was not followed by a successful
+  speaker manifest checkpoint;
+- the prepared audio bytes/path, WhisperX URL, or language changed;
+- the canonical transcript is missing, unsafe, non-regular, invalid JSON, or
+  no longer matches its recorded size/checksum;
+- the previous invocation used `--force`, which durably cleared pre-force
+  speaker authority; or
+- the manifest has only legacy aggregate transcribe state and cannot bind old
+  outputs to their source audio.
+
+Safe fix:
+
+- inspect the reported speaker and filesystem error, repair the prepared input
+  or canonical-output path when needed, then retry transcribe normally;
+- allow a legacy aggregate-only record to regenerate once; and
+- do not edit the manifest or copy an old JSON file into place as a substitute
+  for a successful checkpoint.
+
+```bash
+narratio run-stage transcribe 2026-04-04
+```
+
+Valid earlier speaker checkpoints remain reusable even while aggregate
+transcribe status is failed or interrupted. Merge remains gated until
+transcribe reaches aggregate success with the complete current set.
+
+Relevant reference: [Operations: Transcription continuation and replacement](./operations.md#transcription-continuation-and-replacement).
+
+## WhisperX model changed but transcription was reused
+
+Symptom:
+
+- WhisperX model weights, prompts, or private server configuration changed at
+  the same configured URL, but Narratio still considers speaker transcripts
+  current.
+
+Likely cause:
+
+- Narratio can fingerprint its configured URL and language, not private state
+  loaded behind the service boundary.
+
+Safe fix:
+
+- explicitly force transcribe to establish a durable reset, then use ordinary
+  retry if the replacement attempt is interrupted.
+
+```bash
+narratio run-stage transcribe 2026-04-04 --force
+```
+
+Transport replay and application retries do not provide an exactly-once remote
+execution guarantee. Investigate server-side failures or duplicate work using
+WhisperX diagnostics; do not infer completion from a server log without the
+local speaker checkpoint.
+
+Relevant references: [WhisperX integration](./integrations/whisperx.md) and
+[Transcribe internals](./internal/stage-transcribe.md).
+
+## Transcription manifest checkpoint failed
+
+Symptom:
+
+- transcribe reports that a speaker completed but the session manifest could
+  not be saved.
+
+Likely causes:
+
+- the workspace is unwritable or out of space;
+- the manifest path or parent directory is unsafe or the wrong type; or
+- a transient filesystem error interrupted atomic replacement.
+
+Safe fix:
+
+- correct the reported filesystem or permission problem and retry transcribe
+  normally. Narratio reconciles from the last readable collection and reuses
+  only successfully checkpointed speakers.
+
+A canonical raw transcript left by the failed checkpoint is incidental and
+does not become reusable authority. Preserve the manifest and diagnostics if
+the failure repeats; do not advertise the file by editing manifest evidence.
+
+Relevant references: [Manifest persistence](./internal/manifest.md#persistence-semantics)
+and [Transcribe internals](./internal/stage-transcribe.md).
+
+## Notarius credential reference unavailable
+
+Symptom:
+
+- configuration loading reports `secret.unset`, `secret.empty`, or an invalid
+  name for `pipeline.notarius.llm_api_key`, including during inspection or a
+  run that would not execute extraction.
+
+Likely causes:
+
+- the named environment variable is absent or empty;
+- the selected secrets directory lacks a file with that exact name;
+- a process environment variable exists but is empty, so bootstrap correctly
+  leaves it in place; or
+- the Narratio reference name does not match `api_key_env` in the selected
+  Notarius/PromptKit profile.
+
+Safe fix:
+
+- set the exact nonempty environment variable or provide an equivalently named
+  file through the conventional or explicit secrets directory;
+- remove or set the field to `null` when that deployment needs no credential;
+  and
+- use `config show`, `config sources`, and `config diff` to inspect the public
+  reference name and ownership without exposing its value.
+
+Narratio resolves selected credential references during ordinary pipeline
+loading, before stage selection or resume. Credential changes alone do not
+invalidate a completed extraction, but the current reference must still resolve
+for the command to proceed.
+
+Relevant references: [Secrets](./config.md#secrets-handling) and
+[Notarius credential](./config.md#notarius-credential).
+
 ## Notarius executable missing
 
 Symptom:
@@ -289,6 +417,59 @@ Do not point Notarius directly at the original source path or edit the manifest
 checksum. Relevant references: [Notarius reference configuration](./config.md#notarius-reference-bindings)
 and [Operations: Extraction Workflow](./operations.md#extraction-workflow).
 
+## Notarius reference snapshot cache conflict
+
+Symptom:
+
+- extraction reports that a path beneath
+  `cache/notarius/references/<sha256>/` is a symlink, directory, or another
+  non-regular or unsafe entry.
+
+Safe fix:
+
+- stop commands for the affected session and inspect the exact reported path;
+- investigate unexpected links or special files as possible tampering; and
+- remove only the reported conflicting leaf or digest directory after
+  confirming it belongs to the reconstructible reference cache.
+
+A missing snapshot or corrupt regular snapshot is reconstructed automatically
+from currently verified prepared input. Do not recursively delete the session
+root, edit the manifest checksum, or remove cache entries while extraction is
+active.
+
+Relevant reference: [Operations: Extraction Workflow](./operations.md#extraction-workflow).
+
+## Notarius resume executes work instead of reusing it
+
+Symptom:
+
+- Narratio executes `extract`, and Notarius makes provider calls despite
+  `pipeline.notarius.resume: true`.
+
+Likely causes:
+
+- checkpoint recording is disabled in the Notarius configuration;
+- Notarius is using a nonpersistent or different checkpoint root;
+- transcript/reference bytes, reference paths, pipeline/profile content,
+  local-backend endpoint, selected lanes, or another checkpoint identity input
+  changed; or
+- Narratio extraction was forced, which deliberately omits `--resume`.
+
+Safe fix:
+
+- validate the deployed Notarius configuration and configure explicit
+  persistent chunk-plan and checkpoint roots;
+- inspect Notarius checkpoint decision reason codes for a legitimate cold miss;
+  and
+- retry without force only when reuse is intended.
+
+Remember that Narratio skipping a completed `extract` stage is separate from
+Notarius reusing work inside an extraction that does execute. Narratio does not
+read the Notarius configuration to infer checkpoint enablement.
+
+Relevant references: [Notarius cache controls](./config.md#notarius-cache-controls)
+and [Notarius integration](./integrations/notarius.md).
+
 ## Notarius reference selector or generated-handoff collision
 
 Symptom:
@@ -361,10 +542,10 @@ Symptom:
 
 Likely causes:
 
-- the executable/config path, pipeline ID, timeout, working directory, or
+- the pipeline ID or configured output contracts changed;
-  configured output contracts changed;
 - a configured prepared reference selector, source, path, checksum, or byte
   size changed;
+- the direct trimmed transcript identity or bytes changed; or
 - the durable bundle, index, lane set, provenance, regular-file status, or
   checksum no longer validates.
 
@@ -374,6 +555,11 @@ Safe fix:
   an unsafe path or bundle symlink error as filesystem corruption or tampering
   and investigate it rather than replacing files manually.
 
+Executable, config path, timeout, working directory, and Notarius credential
+changes are operational and do not by themselves invalidate reusable extraction
+evidence. A newly selected credential must nevertheless resolve during command
+configuration loading.
+
 ## Notarius transitive configuration changed
 
 Symptom:
@@ -488,18 +674,22 @@ Symptom:
   or unsupported; or
 - restore rejects a committed remote session manifest for the same reason.
 
-Likely cause:
+Likely causes:
 
 - the manifest predates the supported canonical state contract. Narratio
   rejects it at the schema boundary rather than interpreting aggregate output
-  lists or incidental files as current authority.
+  lists or incidental files as current authority; or
+- an older strict-decoding Narratio binary is reading a current manifest that
+  contains additive transcribe speaker state it does not recognize.
 
 Safe fix:
 
 - for unsupported local state, move the old manifest aside and regenerate, or
   restore a verified current committed snapshot when one is authoritative;
 - for unsupported committed remote state, regenerate healthy local state as
-  needed and republish the session.
+  needed and republish the session; and
+- for a downgrade rejection, return to the current binary or restore a verified
+  pre-upgrade backup. Do not delete only the speaker fields by hand.
 
 ```bash
 narratio run 2026-04-04
@@ -511,7 +701,7 @@ old files into canonical paths merely to influence selection; availability is
 manifest-owned.
 
 Relevant references: [Operations: Stage Execution and Continuation Behavior](./operations.md#stage-execution-and-continuation-behavior)
-and [Manifest Internals](./internal/manifest.md#analyze-owned-artifact-state).
+and [Manifest Internals](./internal/manifest.md#transcribe-owned-speaker-state).
 
 ## Scriptorium private input changed without a rerun
 
@@ -726,7 +916,7 @@ Diagnostics:
 
 ```bash
 ls -la /path/to/secrets_dir
-env | sed 's/=.*//' | grep -E 'OBJECT_STORAGE|AWS|AUDITA|SCRIPTORIUM'
+env | sed 's/=.*//' | grep -E 'OBJECT_STORAGE|AWS|AUDITA|NOTARIUS|SCRIPTORIUM'
 ```
 
 Safe fix:

examples/README.md

@@ -60,17 +60,17 @@ with the sample campaign and a compatible local- or S3-audio session.
   [glossary](campaigns/sample-campaign/glossary.yml), and canonical
   [party](campaigns/sample-campaign/party.yml) fixture, plus an optional
   [spell-catalog overlay](campaigns/sample-campaign/spell_catalog.json) that
-  follows the Notarius v0.6 contract. Narratio derives the players projection
+  follows the Notarius v0.7 contract. Narratio derives the players projection
   from this party source.
 - [Sample speaker audio](audio/sample-speaker.flac) is a text placeholder that
   reserves the expected filename and directory shape. Replace it with a real
   FLAC file before running transcription.
 
 The examples contain environment-variable names but no credential values. Set
-`OBJECT_STORAGE_KEY_ID`, `OBJECT_STORAGE_KEY`, and `AUDITA_LLM_API_KEY` to
+`OBJECT_STORAGE_KEY_ID`, `OBJECT_STORAGE_KEY`, `AUDITA_LLM_API_KEY`, and
-nonempty synthetic or real values before loading the production-shaped and full
+`NOTARIUS_LLM_API_KEY` to nonempty synthetic or real values before loading the
-annotated pipelines. They use fictional campaign content and reserved example
+examples that reference them. They use fictional campaign content and reserved
-domains.
+example domains.
 
 For a deployed bundle, keep credential files out of source control in a
 `secrets/` directory beside the root `pipeline.yml`, one file per referenced

examples/pipeline.full.annotated.yml

@@ -128,13 +128,26 @@ trim:
     report: false
 
 notarius:
-  # Optional structured extraction between trim and render.
+  # Optional structured extraction after render and before analyze.
   enabled: true
   binary: notarius
+  # Optional environment-variable reference. Match this name to api_key_env in
+  # the selected Notarius/PromptKit profile; never put the credential here.
+  llm_api_key: NOTARIUS_LLM_API_KEY
+  # Optionally select a Notarius ConfigKit overlay when extraction runs. This
+  # is independent of Narratio's selected profile and may use a different name.
+  # See docs/config.md and docs/integrations/notarius.md for the contracts.
+  # config_profile: downstream-economy
   config_path: /usr/local/etc/notarius/config.yml
   pipeline_id: dnd-session
   timeout: 3h
   working_directory: /usr/local/etc/notarius
+  # Reuse compatible accepted Notarius checkpoints during executed extraction.
+  # The Notarius config must enable recording and provide persistent cache roots.
+  resume: true
+  # auto uses or creates a source-addressed chunk plan. Forced Narratio
+  # extraction overrides this with refresh and disables checkpoint loading.
+  chunk_cache: auto
   # External campaign references use prepared Narratio source IDs. Omit an
   # optional binding when the selected Notarius pipeline does not need it.
   references:

go.mod

@@ -3,7 +3,7 @@ module gitea.maximumdirect.net/eric/narratio
 go 1.26.0
 
 require (
-	gitea.maximumdirect.net/eric/ConfigKit v0.1.2
+	gitea.maximumdirect.net/eric/ConfigKit v0.3.1
 	github.com/aws/aws-sdk-go-v2/config v1.32.17
 	github.com/aws/aws-sdk-go-v2/credentials v1.19.16
 	github.com/aws/aws-sdk-go-v2/service/s3 v1.101.0

go.sum

@@ -1,5 +1,5 @@
-gitea.maximumdirect.net/eric/ConfigKit v0.1.2 h1:uZ5Mvf271SLItXEvUpQYfAvCOVYj9RaoG0auCcbCcSU=
+gitea.maximumdirect.net/eric/ConfigKit v0.3.1 h1:etfTI/dxO3NnS18La0V6IeUh/Iv+3PjVfEyaN8hTuOM=
-gitea.maximumdirect.net/eric/ConfigKit v0.1.2/go.mod h1:tYWpsrbLyu05r8+1MapWp5fN6ZrX9I8hU2xEPedYmYk=
+gitea.maximumdirect.net/eric/ConfigKit v0.3.1/go.mod h1:tYWpsrbLyu05r8+1MapWp5fN6ZrX9I8hU2xEPedYmYk=
 github.com/aws/aws-sdk-go-v2 v1.41.7 h1:DWpAJt66FmnnaRIOT/8ASTucrvuDPZASqhhLey6tLY8=
 github.com/aws/aws-sdk-go-v2 v1.41.7/go.mod h1:4LAfZOPHNVNQEckOACQx60Y8pSRjIkNZQz1w92xpMJc=
 github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.10 h1:gx1AwW1Iyk9Z9dD9F4akX5gnN3QZwUB20GGKH/I+Rho=

internal/adapters/notarius/fake.go

@@ -15,6 +15,10 @@ func (f *FakeRunner) Run(ctx context.Context, req RunRequest) (RunResult, error)
 		return RunResult{}, err
 	}
 	copyRequest := req
+	if req.ConfigProfile != nil {
+		profile := *req.ConfigProfile
+		copyRequest.ConfigProfile = &profile
+	}
 	copyRequest.References = append([]ReferenceBinding(nil), req.References...)
 	f.Requests = append(f.Requests, copyRequest)
 	if f.Err != nil {

internal/adapters/notarius/runner.go

@@ -4,6 +4,8 @@ package notarius
 import (
 	"context"
 	"time"
+
+	configkit "gitea.maximumdirect.net/eric/ConfigKit"
 )
 
 const ReceiptSchemaVersion = "notarius.run-result.v2"
@@ -23,6 +25,9 @@ type ReferenceBinding struct {
 // RunRequest contains the resolved inputs and diagnostic destinations for one invocation.
 type RunRequest struct {
 	Binary string
+	// LLMAPIKey is an optional already-resolved credential reference.
+	LLMAPIKey        *configkit.Secret
+	ConfigProfile    *string
 	ConfigPath       string
 	PipelineID       string
 	InputPath        string
@@ -31,6 +36,8 @@ type RunRequest struct {
 	ReceiptPath      string
 	LogPath          string
 	Timeout          time.Duration
+	Resume           bool
+	ChunkCache       string
 	References       []ReferenceBinding
 }
 

internal/adapters/notarius/subprocess.go

@@ -52,6 +52,20 @@ func (r *SubprocessRunner) Run(ctx context.Context, req RunRequest) (RunResult,
 	if err != nil {
 		return RunResult{}, err
 	}
+	var envOverrides map[string]string
+	var sensitiveEnvNames []string
+	if req.LLMAPIKey != nil {
+		if !req.LLMAPIKey.IsResolved() {
+			return RunResult{}, fmt.Errorf("notarius LLM API credential must be resolved and nonempty")
+		}
+		name := req.LLMAPIKey.EnvName()
+		value := req.LLMAPIKey.Value()
+		if value == "" {
+			return RunResult{}, fmt.Errorf("notarius LLM API credential must be resolved and nonempty")
+		}
+		envOverrides = map[string]string{name: value}
+		sensitiveEnvNames = []string{name}
+	}
 
 	args := []string{
 		"run", req.PipelineID,
@@ -59,9 +73,18 @@ func (r *SubprocessRunner) Run(ctx context.Context, req RunRequest) (RunResult,
 		"--input", req.InputPath,
 		"--output-dir", req.OutputRoot,
 	}
+	if req.Resume {
+		args = append(args, "--resume")
+	}
+	if req.ChunkCache != "" {
+		args = append(args, "--chunk_cache", req.ChunkCache)
+	}
 	for _, reference := range references {
 		args = append(args, "--reference", reference.Selector+"="+reference.Path)
 	}
+	if req.ConfigProfile != nil {
+		args = append(args, "--config-profile", *req.ConfigProfile)
+	}
 	args = append(args, "--json")
 	processResult, err := r.run(ctx, subprocess.RunRequest{
 		Executable:        req.Binary,
@@ -71,6 +94,8 @@ func (r *SubprocessRunner) Run(ctx context.Context, req RunRequest) (RunResult,
 		DiagnosticOwner:   "notarius",
 		StdoutLogPath:     req.ReceiptPath,
 		StderrLogPath:     req.LogPath,
+		EnvOverrides:      envOverrides,
+		SensitiveEnvNames: sensitiveEnvNames,
 	})
 	baseResult := RunResult{
 		ReceiptPath: req.ReceiptPath,
@@ -143,6 +168,9 @@ func validateRunRequest(req RunRequest) ([]ReferenceBinding, error) {
 	if req.Timeout <= 0 {
 		return nil, fmt.Errorf("notarius timeout must be positive")
 	}
+	if !validChunkCacheMode(req.ChunkCache) {
+		return nil, fmt.Errorf("notarius chunk cache mode must be empty, auto, bypass, or refresh")
+	}
 	for label, path := range map[string]string{
 		"config":            req.ConfigPath,
 		"input":             req.InputPath,
@@ -201,6 +229,15 @@ func validateRunRequest(req RunRequest) ([]ReferenceBinding, error) {
 	return references, nil
 }
 
+func validChunkCacheMode(mode string) bool {
+	switch mode {
+	case "", "auto", "bypass", "refresh":
+		return true
+	default:
+		return false
+	}
+}
+
 type receiptDocument struct {
 	SchemaVersion             string                      `json:"schema_version"`
 	RunID                     string                      `json:"run_id"`
@@ -248,7 +285,7 @@ func validateValidationSummaries(documents []validationSummaryDocument) ([]Valid
 		if document.Status != "complete" && document.Status != "rejected" && document.Status != "incomplete" {
 			return nil, fmt.Errorf("notarius validation summary status %q is invalid", document.Status)
 		}
-		if document.ProducerAttemptCount == nil || *document.ProducerAttemptCount <= 0 || !validTerminalAction(document.TerminalAction) {
+		if document.ProducerAttemptCount == nil || *document.ProducerAttemptCount < 0 || !validTerminalAction(document.TerminalAction) {
 			return nil, fmt.Errorf("notarius validation summary is missing required fields")
 		}
 		summaries = append(summaries, ValidationSummary{

internal/adapters/notarius/subprocess_test.go

@@ -11,6 +11,7 @@ import (
 	"testing"
 	"time"
 
+	configkit "gitea.maximumdirect.net/eric/ConfigKit"
 	sharedsubprocess "gitea.maximumdirect.net/eric/narratio/internal/adapters/subprocess"
 )
 
@@ -76,6 +77,174 @@ func TestSubprocessRunnerBuildsExactInvocationAndDiscoversBundle(t *testing.T) {
 	}
 }
 
+func TestSubprocessRunnerMapsCacheControlsToArguments(t *testing.T) {
+	tests := []struct {
+		name       string
+		resume     bool
+		chunkCache string
+		want       []string
+	}{
+		{name: "resume", resume: true, want: []string{"--resume"}},
+		{name: "auto", chunkCache: "auto", want: []string{"--chunk_cache", "auto"}},
+		{name: "bypass", chunkCache: "bypass", want: []string{"--chunk_cache", "bypass"}},
+		{name: "refresh", chunkCache: "refresh", want: []string{"--chunk_cache", "refresh"}},
+		{name: "resume and mode", resume: true, chunkCache: "auto", want: []string{"--resume", "--chunk_cache", "auto"}},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			req := validRunRequest(t)
+			req.Resume = test.resume
+			req.ChunkCache = test.chunkCache
+			var captured sharedsubprocess.RunRequest
+			runner := &SubprocessRunner{run: func(_ context.Context, processReq sharedsubprocess.RunRequest) (sharedsubprocess.RunResult, error) {
+				captured = processReq
+				writeValidBundleAndReceipt(t, req, false)
+				return sharedsubprocess.RunResult{ExitCode: 0}, nil
+			}}
+
+			if _, err := runner.Run(context.Background(), req); err != nil {
+				t.Fatalf("Run() error = %v", err)
+			}
+			want := []string{
+				"run", req.PipelineID, "--config", req.ConfigPath, "--input", req.InputPath,
+				"--output-dir", req.OutputRoot,
+			}
+			want = append(want, test.want...)
+			want = append(want, "--json")
+			if !reflect.DeepEqual(captured.Args, want) {
+				t.Fatalf("subprocess args = %#v, want %#v", captured.Args, want)
+			}
+		})
+	}
+}
+
+func TestSubprocessRunnerMapsConfigProfileToArgumentPair(t *testing.T) {
+	tests := []struct {
+		name     string
+		supplied bool
+		value    string
+	}{
+		{name: "omitted"},
+		{name: "empty", supplied: true},
+		{name: "default", supplied: true, value: "default"},
+		{name: "named", supplied: true, value: "inexpensive"},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			req := validRunRequest(t)
+			if test.supplied {
+				req.ConfigProfile = &test.value
+			}
+			var captured sharedsubprocess.RunRequest
+			runner := &SubprocessRunner{run: func(_ context.Context, processReq sharedsubprocess.RunRequest) (sharedsubprocess.RunResult, error) {
+				captured = processReq
+				writeValidBundleAndReceipt(t, req, false)
+				return sharedsubprocess.RunResult{ExitCode: 0}, nil
+			}}
+
+			if _, err := runner.Run(context.Background(), req); err != nil {
+				t.Fatalf("Run() error = %v", err)
+			}
+			flagIndex := -1
+			for index, arg := range captured.Args {
+				if arg == "--config-profile" {
+					flagIndex = index
+					break
+				}
+			}
+			if !test.supplied {
+				if flagIndex >= 0 {
+					t.Fatalf("subprocess args unexpectedly contain config profile: %#v", captured.Args)
+				}
+				return
+			}
+			if flagIndex < 0 || flagIndex+2 >= len(captured.Args) || captured.Args[flagIndex+1] != test.value || captured.Args[flagIndex+2] != "--json" {
+				t.Fatalf("config profile argument boundary = %#v, want flag, exact value, then --json", captured.Args)
+			}
+		})
+	}
+}
+
+func TestSubprocessRunnerRejectsInvalidChunkCacheBeforeLaunch(t *testing.T) {
+	for _, mode := range []string{"AUTO", "invalid", " auto "} {
+		t.Run(mode, func(t *testing.T) {
+			req := validRunRequest(t)
+			req.ChunkCache = mode
+			started := false
+			runner := &SubprocessRunner{run: func(context.Context, sharedsubprocess.RunRequest) (sharedsubprocess.RunResult, error) {
+				started = true
+				return sharedsubprocess.RunResult{}, nil
+			}}
+			_, err := runner.Run(context.Background(), req)
+			if err == nil || !strings.Contains(err.Error(), "chunk cache mode") {
+				t.Fatalf("Run() error = %v, want chunk cache validation failure", err)
+			}
+			if started {
+				t.Fatal("subprocess started with invalid chunk cache mode")
+			}
+		})
+	}
+}
+
+func TestSubprocessRunnerForwardsLoadedCredentialWithoutRereadingEnvironment(t *testing.T) {
+	const envName = "NARRATIO_NOTARIUS_CUSTOM_LLM_KEY"
+	const loadedValue = "loaded-notarius-credential"
+	credential := loadTestCredential(t, envName, loadedValue)
+	t.Setenv(envName, "changed-parent-credential")
+
+	req := validRunRequest(t)
+	req.LLMAPIKey = credential
+	var captured sharedsubprocess.RunRequest
+	runner := &SubprocessRunner{run: func(_ context.Context, processReq sharedsubprocess.RunRequest) (sharedsubprocess.RunResult, error) {
+		captured = processReq
+		writeValidBundleAndReceipt(t, req, false)
+		return sharedsubprocess.RunResult{ExitCode: 0}, nil
+	}}
+	if _, err := runner.Run(context.Background(), req); err != nil {
+		t.Fatalf("Run() error = %v", err)
+	}
+	if len(captured.EnvOverrides) != 1 || captured.EnvOverrides[envName] != loadedValue {
+		t.Fatal("subprocess did not receive exactly the loaded credential override")
+	}
+	if !reflect.DeepEqual(captured.SensitiveEnvNames, []string{envName}) {
+		t.Fatalf("sensitive environment names = %#v, want configured reference name", captured.SensitiveEnvNames)
+	}
+	wantArgs := []string{
+		"run", req.PipelineID, "--config", req.ConfigPath, "--input", req.InputPath,
+		"--output-dir", req.OutputRoot, "--json",
+	}
+	if !reflect.DeepEqual(captured.Args, wantArgs) {
+		t.Fatalf("subprocess args = %#v, want %#v", captured.Args, wantArgs)
+	}
+}
+
+func TestSubprocessRunnerRejectsInvalidProgrammaticCredentialBeforeLaunch(t *testing.T) {
+	for _, test := range []struct {
+		name      string
+		reference configkit.Secret
+	}{
+		{name: "unresolved", reference: configkit.SecretEnv("NARRATIO_NOTARIUS_UNRESOLVED_KEY")},
+		{name: "empty", reference: configkit.SecretEnv("")},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			req := validRunRequest(t)
+			req.LLMAPIKey = &test.reference
+			started := false
+			runner := &SubprocessRunner{run: func(context.Context, sharedsubprocess.RunRequest) (sharedsubprocess.RunResult, error) {
+				started = true
+				return sharedsubprocess.RunResult{}, nil
+			}}
+			_, err := runner.Run(context.Background(), req)
+			if err == nil || !strings.Contains(err.Error(), "resolved and nonempty") {
+				t.Fatalf("Run() error = %v, want credential validation failure", err)
+			}
+			if started {
+				t.Fatal("subprocess started with an invalid credential")
+			}
+		})
+	}
+}
+
 func TestSubprocessRunnerBuildsOrderedReferenceArguments(t *testing.T) {
 	req := validRunRequest(t)
 	referenceRoot := t.TempDir()
@@ -172,16 +341,23 @@ func TestSubprocessRunnerRejectsInvalidReferencesBeforeLaunch(t *testing.T) {
 }
 
 func TestSubprocessRunnerUsesMinimalEnvironmentAndSeparatesStreams(t *testing.T) {
+	const envName = "NARRATIO_NOTARIUS_CUSTOM_CAPTURE_KEY"
+	const canary = "notarius-captured-stream-canary"
+	const unrelated = "NARRATIO_NOTARIUS_UNRELATED_PARENT_KEY"
 	req := validRunRequest(t)
+	req.LLMAPIKey = loadTestCredential(t, envName, canary)
 	writeValidBundleAndReceipt(t, req, false)
 	receiptFixture := req.ReceiptPath + ".fixture"
 	data, err := os.ReadFile(req.ReceiptPath)
 	if err != nil {
 		t.Fatalf("ReadFile(receipt) error = %v", err)
 	}
-	if err := os.WriteFile(receiptFixture, data, 0o644); err != nil {
+	var receipt map[string]any
-		t.Fatalf("WriteFile(receipt fixture) error = %v", err)
+	if err := json.Unmarshal(data, &receipt); err != nil {
+		t.Fatalf("decode receipt fixture: %v", err)
 	}
+	receipt["credential_echo"] = canary
+	writeJSONFile(t, receiptFixture, receipt)
 	if err := os.Remove(req.ReceiptPath); err != nil {
 		t.Fatalf("Remove(receipt) error = %v", err)
 	}
@@ -193,27 +369,55 @@ func TestSubprocessRunnerUsesMinimalEnvironmentAndSeparatesStreams(t *testing.T)
 	script := writeShellScript(t, `#!/bin/sh
 pwd > "$NOTARIUS_CAPTURE_DIR/working-directory"
 printf '%s' "$NOTARIUS_INHERITED_VALUE" > "$NOTARIUS_CAPTURE_DIR/environment"
-printf 'diagnostic stream\n' >&2
+if [ "$`+envName+`" != '`+canary+`' ]; then
+  printf 'selected credential mismatch\n' >&2
+  exit 8
+fi
+if [ -n "$`+unrelated+`" ]; then
+  printf 'unrelated credential inherited\n' >&2
+  exit 9
+fi
+printf '%s\n' "$`+envName+`" >&2
 cat "$NOTARIUS_RECEIPT_FIXTURE"
 `)
 	req.Binary = script
 	t.Setenv("NOTARIUS_CAPTURE_DIR", captureDir)
 	t.Setenv("NOTARIUS_INHERITED_VALUE", "inherited-value")
 	t.Setenv("NOTARIUS_RECEIPT_FIXTURE", receiptFixture)
+	t.Setenv(unrelated, "unrelated-parent-credential")
 
 	if _, err := NewSubprocessRunner().Run(context.Background(), req); err != nil {
 		t.Fatalf("Run() error = %v", err)
 	}
 	assertTextFile(t, filepath.Join(captureDir, "working-directory"), req.WorkingDirectory+"\n")
 	assertTextFile(t, filepath.Join(captureDir, "environment"), "")
-	assertTextFile(t, req.LogPath, "diagnostic stream\n")
+	assertRedactedCredentialFile(t, req.LogPath, canary)
 	receiptBytes, err := os.ReadFile(req.ReceiptPath)
 	if err != nil {
 		t.Fatalf("ReadFile(receipt) error = %v", err)
 	}
-	if strings.Contains(string(receiptBytes), "diagnostic stream") {
+	assertRedactedCredentialBytes(t, receiptBytes, canary)
-		t.Fatal("receipt contains stderr output")
+}
+
+func TestSubprocessRunnerRedactsCredentialOnProcessFailure(t *testing.T) {
+	const envName = "NARRATIO_NOTARIUS_CUSTOM_FAILURE_KEY"
+	const canary = "notarius-failure-stream-canary"
+	req := validRunRequest(t)
+	req.LLMAPIKey = loadTestCredential(t, envName, canary)
+	req.Binary = writeShellScript(t, `#!/bin/sh
+printf '%s\n' "$`+envName+`"
+printf '%s\n' "$`+envName+`" >&2
+exit 7
+`)
+	_, err := NewSubprocessRunner().Run(context.Background(), req)
+	if err == nil {
+		t.Fatal("Run() error = nil, want process failure")
 	}
+	if strings.Contains(err.Error(), canary) || !strings.Contains(err.Error(), "<redacted>") {
+		t.Fatal("process failure did not return redacted diagnostics")
+	}
+	assertRedactedCredentialFile(t, req.ReceiptPath, canary)
+	assertRedactedCredentialFile(t, req.LogPath, canary)
 }
 
 func TestSubprocessRunnerReturnsProcessFailuresWithoutParsingStdout(t *testing.T) {
@@ -231,6 +435,10 @@ func TestSubprocessRunnerReturnsProcessFailuresWithoutParsingStdout(t *testing.T
 	for _, test := range tests {
 		t.Run(test.name, func(t *testing.T) {
 			req := validRunRequest(t)
+			if test.name == "nonzero" {
+				profile := "missing-profile"
+				req.ConfigProfile = &profile
+			}
 			req.Binary = writeShellScript(t, "#!/bin/sh\n"+test.scriptBody)
 			req.Timeout = test.timeout
 			ctx := context.Background()
@@ -527,7 +735,8 @@ func TestLoadDiagnosticSummariesValidateBoundsAndTolerateUnknownFields(t *testin
 }
 
 func TestFakeRunnerCapturesRequestsAndHonorsContextAndError(t *testing.T) {
-	req := RunRequest{PipelineID: "pipeline", References: []ReferenceBinding{{Selector: "party", Path: "/references/party.json"}}}
+	profile := "testing"
+	req := RunRequest{PipelineID: "pipeline", ConfigProfile: &profile, References: []ReferenceBinding{{Selector: "party", Path: "/references/party.json"}}}
 	want := RunResult{BundleRoot: "/bundle"}
 	fake := &FakeRunner{Result: want}
 	got, err := fake.Run(context.Background(), req)
@@ -538,6 +747,10 @@ func TestFakeRunnerCapturesRequestsAndHonorsContextAndError(t *testing.T) {
 	if fake.Requests[0].References[0].Path != "/references/party.json" {
 		t.Fatalf("fake retained aliased request references: %#v", fake.Requests[0].References)
 	}
+	profile = "changed"
+	if *fake.Requests[0].ConfigProfile != "testing" {
+		t.Fatalf("fake retained aliased config profile: %q", *fake.Requests[0].ConfigProfile)
+	}
 
 	wantErr := errors.New("configured failure")
 	fake.Err = wantErr
@@ -579,6 +792,56 @@ func validRunRequest(t *testing.T) RunRequest {
 	}
 }
 
+func loadTestCredential(t *testing.T, envName, value string) *configkit.Secret {
+	t.Helper()
+	t.Setenv(envName, value)
+	type testConfig struct {
+		Credential *configkit.Secret `yaml:"credential"`
+	}
+	result, err := configkit.Load(configkit.Bytes("credential.yml", []byte("credential: "+envName+"\n")), configkit.Options[testConfig]{})
+	if err != nil {
+		t.Fatalf("load test credential: %v", err)
+	}
+	return result.Config.Credential
+}
+
+func assertRedactedCredentialFile(t *testing.T, path, canary string) {
+	t.Helper()
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("ReadFile(%q) error = %v", path, err)
+	}
+	assertRedactedCredentialBytes(t, data, canary)
+}
+
+func assertRedactedCredentialBytes(t *testing.T, data []byte, canary string) {
+	t.Helper()
+	text := string(data)
+	if strings.Contains(text, canary) || !strings.Contains(text, "<redacted>") {
+		t.Fatal("captured stream did not contain the required redaction marker")
+	}
+}
+
+func TestValidateValidationSummariesAcceptsReusedProducerWithoutAttempts(t *testing.T) {
+	zero := 0
+	summaries, err := validateValidationSummaries([]validationSummaryDocument{{
+		Stage: "chunk", Status: "complete", ProducerAttemptCount: &zero, TerminalAction: "accepted",
+	}})
+	if err != nil {
+		t.Fatalf("validateValidationSummaries() error = %v", err)
+	}
+	if len(summaries) != 1 || summaries[0].ProducerAttemptCount != 0 {
+		t.Fatalf("summaries = %#v, want one reused producer with zero attempts", summaries)
+	}
+
+	negative := -1
+	if _, err := validateValidationSummaries([]validationSummaryDocument{{
+		Stage: "chunk", Status: "complete", ProducerAttemptCount: &negative, TerminalAction: "accepted",
+	}}); err == nil {
+		t.Fatal("validateValidationSummaries() negative producer attempts error = nil")
+	}
+}
+
 func writeValidBundleAndReceipt(t *testing.T, req RunRequest, includeUnknown bool) {
 	t.Helper()
 	bundle := filepath.Join(req.OutputRoot, "notarius-run-1")

internal/adapters/whisperx/http.go

@@ -6,14 +6,11 @@ import (
 	"errors"
 	"fmt"
 	"io"
-	"mime/multipart"
 	"net"
 	"net/http"
 	"net/url"
 	"os"
-	"path/filepath"
 	"strings"
-	"sync"
 	"time"
 
 	"gitea.maximumdirect.net/eric/narratio/internal/fileops"
@@ -21,7 +18,6 @@ import (
 
 const (
 	defaultMaxWhisperXResponseBytes int64 = 10 * 1024 * 1024
-	whisperXUploadBufferSize              = 32 * 1024
 )
 
 // HTTPClientConfig contains parsed, deterministic WhisperX HTTP client settings.
@@ -192,21 +188,32 @@ func (c *HTTPClient) Transcribe(ctx context.Context, req TranscribeRequest) (Tra
 }
 
 func (c *HTTPClient) doTranscribeAttempt(ctx context.Context, audioPath string) (int, []byte, error) {
-	upload := newMultipartUpload(ctx, audioPath, c.language, c.openAudio)
+	upload, err := newMultipartBodyFactory(ctx, audioPath, c.language, c.openAudio)
-	defer upload.Close()
+	if err != nil {
+		return 0, nil, fmt.Errorf("prepare whisperx request body: %w", err)
+	}
+	defer func() { _ = upload.Close() }()
+	body, err := upload.NewBody()
+	if err != nil {
+		return 0, nil, fmt.Errorf("open whisperx request body: %w", err)
+	}
 
-	req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.url.String(), upload)
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.url.String(), body)
 	if err != nil {
 		return 0, nil, fmt.Errorf("build whisperx request: %w", err)
 	}
 	req.Header.Set("Content-Type", upload.contentType)
 	req.Header.Set("Expect", "100-continue")
+	req.GetBody = upload.NewBody
 
 	resp, err := c.httpClient.Do(req)
 	if err != nil {
 		_ = upload.Close()
-		if producerErr := upload.Wait(); producerErr != nil {
+		if sourceErr := upload.SourceError(true); sourceErr != nil {
-			return 0, nil, fmt.Errorf("stream whisperx request body: %w", producerErr)
+			return 0, nil, fmt.Errorf("stream whisperx request body: %w", sourceErr)
+		}
+		if ctxErr := ctx.Err(); ctxErr != nil {
+			return 0, nil, fmt.Errorf("perform whisperx request: %w", ctxErr)
 		}
 		return 0, nil, fmt.Errorf("perform whisperx request: %w", err)
 	}
@@ -214,8 +221,8 @@ func (c *HTTPClient) doTranscribeAttempt(ctx context.Context, audioPath string)
 
 	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
 		_ = upload.Close()
-		if producerErr := upload.Wait(); producerErr != nil {
+		if sourceErr := upload.SourceError(false); sourceErr != nil {
-			return resp.StatusCode, nil, fmt.Errorf("stream whisperx request body: %w", producerErr)
+			return resp.StatusCode, nil, fmt.Errorf("stream whisperx request body: %w", sourceErr)
 		}
 		if _, err := readWhisperXResponse(resp.Body, c.maxResponseBytes); err != nil {
 			return resp.StatusCode, nil, fmt.Errorf("read whisperx response body: %w", err)
@@ -223,13 +230,19 @@ func (c *HTTPClient) doTranscribeAttempt(ctx context.Context, audioPath string)
 		return resp.StatusCode, nil, fmt.Errorf("whisperx returned status %d", resp.StatusCode)
 	}
 
-	if err := upload.Wait(); err != nil {
+	data, responseErr := readWhisperXResponse(resp.Body, c.maxResponseBytes)
-		return resp.StatusCode, nil, fmt.Errorf("stream whisperx request body: %w", err)
+	_ = upload.Close()
+	if sourceErr := upload.SourceError(false); sourceErr != nil {
+		if responseErr != nil {
+			return resp.StatusCode, nil, fmt.Errorf("stream whisperx request body: %w", errors.Join(sourceErr, responseErr))
 		}
-
+		return resp.StatusCode, nil, fmt.Errorf("stream whisperx request body: %w", sourceErr)
-	data, err := readWhisperXResponse(resp.Body, c.maxResponseBytes)
+	}
-	if err != nil {
+	if err := ctx.Err(); err != nil {
-		return resp.StatusCode, nil, fmt.Errorf("read whisperx response body: %w", err)
+		return resp.StatusCode, nil, fmt.Errorf("complete whisperx request: %w", err)
+	}
+	if responseErr != nil {
+		return resp.StatusCode, nil, fmt.Errorf("read whisperx response body: %w", responseErr)
 	}
 	return resp.StatusCode, data, nil
 }
@@ -286,161 +299,6 @@ func isHTTPURLScheme(scheme string) bool {
 	}
 }
 
-type multipartUpload struct {
-	reader      *io.PipeReader
-	writer      *io.PipeWriter
-	contentType string
-	done        chan struct{}
-
-	mu      sync.Mutex
-	audio   io.Closer
-	err     error
-	aborted bool
-}
-
-func newMultipartUpload(ctx context.Context, audioPath, language string, openAudio func(string) (io.ReadCloser, error)) *multipartUpload {
-	reader, writer := io.Pipe()
-	multipartWriter := multipart.NewWriter(writer)
-	upload := &multipartUpload{
-		reader:      reader,
-		writer:      writer,
-		contentType: multipartWriter.FormDataContentType(),
-		done:        make(chan struct{}),
-	}
-
-	go func() {
-		err := upload.write(ctx, multipartWriter, audioPath, language, openAudio)
-		if err != nil {
-			_ = writer.CloseWithError(err)
-		} else {
-			_ = writer.Close()
-		}
-		upload.mu.Lock()
-		upload.err = err
-		upload.audio = nil
-		upload.mu.Unlock()
-		close(upload.done)
-	}()
-
-	go func() {
-		select {
-		case <-ctx.Done():
-			upload.abort()
-		case <-upload.done:
-		}
-	}()
-
-	return upload
-}
-
-func (u *multipartUpload) Read(p []byte) (int, error) {
-	return u.reader.Read(p)
-}
-
-func (u *multipartUpload) Close() error {
-	u.abort()
-	return nil
-}
-
-func (u *multipartUpload) Wait() error {
-	<-u.done
-	u.mu.Lock()
-	defer u.mu.Unlock()
-	return u.err
-}
-
-func (u *multipartUpload) write(ctx context.Context, writer *multipart.Writer, audioPath, language string, openAudio func(string) (io.ReadCloser, error)) error {
-	fileWriter, err := writer.CreateFormFile("file", filepath.Base(audioPath))
-	if err != nil {
-		return u.producerError(ctx, fmt.Errorf("create multipart file field: %w", err))
-	}
-
-	audioFile, err := openAudio(audioPath)
-	if err != nil {
-		return u.producerError(ctx, fmt.Errorf("open audio file %q: %w", audioPath, err))
-	}
-	u.setAudio(audioFile)
-
-	_, copyErr := io.CopyBuffer(fileWriter, &contextReader{ctx: ctx, reader: audioFile}, make([]byte, whisperXUploadBufferSize))
-	closeErr := audioFile.Close()
-	u.clearAudio(audioFile)
-	if copyErr != nil {
-		return u.producerError(ctx, fmt.Errorf("copy audio file %q: %w", audioPath, copyErr))
-	}
-	if closeErr != nil {
-		return u.producerError(ctx, fmt.Errorf("close audio file %q: %w", audioPath, closeErr))
-	}
-
-	if err := writer.WriteField("language", language); err != nil {
-		return u.producerError(ctx, fmt.Errorf("write language form field: %w", err))
-	}
-	if err := writer.Close(); err != nil {
-		return u.producerError(ctx, fmt.Errorf("close multipart writer: %w", err))
-	}
-	return nil
-}
-
-func (u *multipartUpload) producerError(ctx context.Context, err error) error {
-	if ctx.Err() != nil {
-		return ctx.Err()
-	}
-	u.mu.Lock()
-	aborted := u.aborted
-	u.mu.Unlock()
-	if aborted {
-		return nil
-	}
-	return err
-}
-
-func (u *multipartUpload) setAudio(audio io.Closer) {
-	u.mu.Lock()
-	u.audio = audio
-	aborted := u.aborted
-	u.mu.Unlock()
-	if aborted {
-		_ = audio.Close()
-	}
-}
-
-func (u *multipartUpload) clearAudio(audio io.Closer) {
-	u.mu.Lock()
-	if u.audio == audio {
-		u.audio = nil
-	}
-	u.mu.Unlock()
-}
-
-func (u *multipartUpload) abort() {
-	u.mu.Lock()
-	if u.aborted {
-		u.mu.Unlock()
-		return
-	}
-	u.aborted = true
-	audio := u.audio
-	u.mu.Unlock()
-
-	_ = u.reader.Close()
-	if audio != nil {
-		_ = audio.Close()
-	}
-}
-
-type contextReader struct {
-	ctx    context.Context
-	reader io.Reader
-}
-
-func (r *contextReader) Read(p []byte) (int, error) {
-	select {
-	case <-r.ctx.Done():
-		return 0, r.ctx.Err()
-	default:
-		return r.reader.Read(p)
-	}
-}
-
 func writeFileAtomic(path string, data []byte, perm os.FileMode) error {
 	if strings.TrimSpace(path) == "" {
 		return fmt.Errorf("path is required")

internal/adapters/whisperx/http_replay_test.go

@@ -0,0 +1,261 @@
+package whisperx
+
+import (
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+func TestHTTPClientTransportReplaysAbandonedMultipartBody(t *testing.T) {
+	var opens atomic.Int32
+	var closes atomic.Int32
+	transport := roundTripFunc(func(request *http.Request) (*http.Response, error) {
+		partial := make([]byte, 17)
+		if _, err := io.ReadFull(request.Body, partial); err != nil {
+			return nil, err
+		}
+		if err := request.Body.Close(); err != nil {
+			return nil, err
+		}
+		if request.GetBody == nil {
+			return nil, errors.New("request GetBody is nil")
+		}
+		replay, err := request.GetBody()
+		if err != nil {
+			return nil, err
+		}
+		replayedBytes, err := io.ReadAll(replay)
+		if err != nil {
+			_ = replay.Close()
+			return nil, err
+		}
+		if err := replay.Close(); err != nil {
+			return nil, err
+		}
+		parts := parseMultipartParts(t, request.Header.Get("Content-Type"), replayedBytes)
+		if len(parts) != 2 || parts[0].name != "file" || parts[0].filename != "audio.flac" || string(parts[0].data) != "audio-data" {
+			t.Fatalf("replayed file part = %#v, want exact audio.flac payload", parts)
+		}
+		if parts[1].name != "language" || string(parts[1].data) != "en" {
+			t.Fatalf("replayed language part = %#v, want language=en", parts[1])
+		}
+		return whisperXJSONResponse(request), nil
+	})
+	client := newReplayTestHTTPClient(t, transport)
+	client.openAudio = func(string) (io.ReadCloser, error) {
+		opens.Add(1)
+		return &countedReadCloser{Reader: strings.NewReader("audio-data"), closes: &closes}, nil
+	}
+	outPath := filepath.Join(t.TempDir(), "raw.json")
+
+	result, err := client.Transcribe(context.Background(), TranscribeRequest{
+		AudioPath:               "audio.flac",
+		OutputRawTranscriptPath: outPath,
+	})
+	if err != nil {
+		t.Fatalf("Transcribe() error = %v", err)
+	}
+	if result.Attempts != 1 {
+		t.Fatalf("application attempts = %d, want 1", result.Attempts)
+	}
+	verifyJSONFile(t, outPath)
+	if got := opens.Load(); got != 2 {
+		t.Fatalf("audio opens = %d, want original and replay", got)
+	}
+	if got := closes.Load(); got != 2 {
+		t.Fatalf("audio closes = %d, want all body handles disposed", got)
+	}
+}
+
+func TestHTTPClientTransportReturnsReplayOpenFailure(t *testing.T) {
+	replayErr := errors.New("replay open failed")
+	var opens atomic.Int32
+	var closes atomic.Int32
+	transport := roundTripFunc(func(request *http.Request) (*http.Response, error) {
+		if _, err := io.ReadFull(request.Body, make([]byte, 1)); err != nil {
+			return nil, err
+		}
+		_ = request.Body.Close()
+		_, err := request.GetBody()
+		return nil, err
+	})
+	client := newReplayTestHTTPClient(t, transport)
+	client.openAudio = func(string) (io.ReadCloser, error) {
+		if opens.Add(1) == 2 {
+			return nil, replayErr
+		}
+		return &countedReadCloser{Reader: strings.NewReader("audio-data"), closes: &closes}, nil
+	}
+	outPath := filepath.Join(t.TempDir(), "raw.json")
+
+	result, err := client.Transcribe(context.Background(), TranscribeRequest{
+		AudioPath:               "audio.flac",
+		OutputRawTranscriptPath: outPath,
+	})
+	if !errors.Is(err, replayErr) {
+		t.Fatalf("Transcribe() error = %v, want replay open failure", err)
+	}
+	if result.Attempts != 1 {
+		t.Fatalf("application attempts = %d, want 1", result.Attempts)
+	}
+	if got := closes.Load(); got != 1 {
+		t.Fatalf("audio closes = %d, want original disposed", got)
+	}
+	if _, statErr := os.Stat(outPath); !errors.Is(statErr, os.ErrNotExist) {
+		t.Fatalf("output should not exist, stat error = %v", statErr)
+	}
+}
+
+func TestHTTPClientTransportCannotSwallowReplayReadFailure(t *testing.T) {
+	replayErr := errors.New("replay read failed")
+	var opens atomic.Int32
+	transport := roundTripFunc(func(request *http.Request) (*http.Response, error) {
+		if _, err := io.ReadFull(request.Body, make([]byte, 1)); err != nil {
+			return nil, err
+		}
+		_ = request.Body.Close()
+		replay, err := request.GetBody()
+		if err != nil {
+			return nil, err
+		}
+		_, _ = io.ReadAll(replay)
+		_ = replay.Close()
+		return whisperXJSONResponse(request), nil
+	})
+	client := newReplayTestHTTPClient(t, transport)
+	client.openAudio = func(string) (io.ReadCloser, error) {
+		if opens.Add(1) == 2 {
+			return &failingReadCloser{first: []byte("partial"), err: replayErr}, nil
+		}
+		return io.NopCloser(strings.NewReader("audio-data")), nil
+	}
+	outPath := filepath.Join(t.TempDir(), "raw.json")
+
+	_, err := client.Transcribe(context.Background(), TranscribeRequest{
+		AudioPath:               "audio.flac",
+		OutputRawTranscriptPath: outPath,
+	})
+	if !errors.Is(err, replayErr) {
+		t.Fatalf("Transcribe() error = %v, want replay read failure", err)
+	}
+	if _, statErr := os.Stat(outPath); !errors.Is(statErr, os.ErrNotExist) {
+		t.Fatalf("output should not exist, stat error = %v", statErr)
+	}
+}
+
+func TestHTTPClientTransportEarlyResponseDisposesOriginalBody(t *testing.T) {
+	var closes atomic.Int32
+	client := newReplayTestHTTPClient(t, roundTripFunc(func(request *http.Request) (*http.Response, error) {
+		return whisperXJSONResponse(request), nil
+	}))
+	client.openAudio = func(string) (io.ReadCloser, error) {
+		return &countedReadCloser{Reader: strings.NewReader("audio-data"), closes: &closes}, nil
+	}
+
+	_, err := client.Transcribe(context.Background(), TranscribeRequest{
+		AudioPath:               "audio.flac",
+		OutputRawTranscriptPath: filepath.Join(t.TempDir(), "raw.json"),
+	})
+	if err != nil {
+		t.Fatalf("Transcribe() error = %v", err)
+	}
+	if got := closes.Load(); got != 1 {
+		t.Fatalf("audio closes = %d, want early-response body disposed", got)
+	}
+}
+
+func TestHTTPClientParentCancellationDuringReplayClosesEveryBody(t *testing.T) {
+	var opens atomic.Int32
+	var originalCloses atomic.Int32
+	replaySource := newSignalingBlockedReadCloser()
+	transport := roundTripFunc(func(request *http.Request) (*http.Response, error) {
+		if _, err := io.ReadFull(request.Body, make([]byte, 1)); err != nil {
+			return nil, err
+		}
+		_ = request.Body.Close()
+		replay, err := request.GetBody()
+		if err != nil {
+			return nil, err
+		}
+		_, _ = io.ReadAll(replay)
+		_ = replay.Close()
+		return nil, request.Context().Err()
+	})
+	client := newReplayTestHTTPClient(t, transport)
+	client.openAudio = func(string) (io.ReadCloser, error) {
+		if opens.Add(1) == 1 {
+			return &countedReadCloser{Reader: strings.NewReader("audio-data"), closes: &originalCloses}, nil
+		}
+		return replaySource, nil
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	done := make(chan error, 1)
+	go func() {
+		_, err := client.Transcribe(ctx, TranscribeRequest{
+			AudioPath:               "audio.flac",
+			OutputRawTranscriptPath: filepath.Join(t.TempDir(), "raw.json"),
+		})
+		done <- err
+	}()
+
+	select {
+	case <-replaySource.blocked:
+		cancel()
+	case <-time.After(time.Second):
+		cancel()
+		t.Fatal("replay source did not block")
+	}
+	select {
+	case err := <-done:
+		if !errors.Is(err, context.Canceled) {
+			t.Fatalf("Transcribe() error = %v, want context cancellation", err)
+		}
+	case <-time.After(time.Second):
+		t.Fatal("Transcribe() did not return after replay cancellation")
+	}
+	if got := originalCloses.Load(); got != 1 {
+		t.Fatalf("original audio closes = %d, want 1", got)
+	}
+	select {
+	case <-replaySource.closed:
+	case <-time.After(time.Second):
+		t.Fatal("replay audio source was not closed")
+	}
+}
+
+type roundTripFunc func(*http.Request) (*http.Response, error)
+
+func (roundTrip roundTripFunc) RoundTrip(request *http.Request) (*http.Response, error) {
+	return roundTrip(request)
+}
+
+func newReplayTestHTTPClient(t *testing.T, transport http.RoundTripper) *HTTPClient {
+	t.Helper()
+	client, err := NewHTTPClient(HTTPClientConfig{
+		TranscribeURL: "http://whisperx.test/transcribe",
+		Language:      "en",
+		Timeout:       time.Second,
+		HTTPClient:    &http.Client{Transport: transport},
+	})
+	if err != nil {
+		t.Fatalf("NewHTTPClient() error = %v", err)
+	}
+	return client
+}
+
+func whisperXJSONResponse(request *http.Request) *http.Response {
+	return &http.Response{
+		StatusCode: http.StatusOK,
+		Status:     "200 OK",
+		Header:     make(http.Header),
+		Body:       io.NopCloser(strings.NewReader(`{"source":"transport-replay","segments":[]}`)),
+		Request:    request,
+	}
+}

internal/adapters/whisperx/http_test.go

@@ -365,7 +365,7 @@ func TestHTTPClientEarlyServerResponseReturns(t *testing.T) {
 	}
 }
 
-func TestHTTPClientCancellationReleasesBlockedProducer(t *testing.T) {
+func TestHTTPClientCancellationReleasesBlockedSource(t *testing.T) {
 	release := make(chan struct{})
 	source := newGatedReadCloser([]byte("audio-data"), release)
 	firstByteReceived := make(chan struct{})

internal/adapters/whisperx/multipart_body.go

@@ -0,0 +1,263 @@
+package whisperx
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"mime/multipart"
+	"path/filepath"
+	"sync"
+)
+
+type multipartBodyFactory struct {
+	ctx         context.Context
+	audioPath   string
+	openAudio   func(string) (io.ReadCloser, error)
+	prefix      []byte
+	suffix      []byte
+	contentType string
+
+	mu     sync.Mutex
+	closed bool
+	bodies []*multipartBody
+}
+
+func newMultipartBodyFactory(
+	ctx context.Context,
+	audioPath string,
+	language string,
+	openAudio func(string) (io.ReadCloser, error),
+) (*multipartBodyFactory, error) {
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	if openAudio == nil {
+		return nil, fmt.Errorf("audio opener is required")
+	}
+	var framing bytes.Buffer
+	writer := multipart.NewWriter(&framing)
+	if _, err := writer.CreateFormFile("file", filepath.Base(audioPath)); err != nil {
+		return nil, fmt.Errorf("create multipart file field: %w", err)
+	}
+	prefixLength := framing.Len()
+	if err := writer.WriteField("language", language); err != nil {
+		return nil, fmt.Errorf("write language form field: %w", err)
+	}
+	if err := writer.Close(); err != nil {
+		return nil, fmt.Errorf("close multipart framing: %w", err)
+	}
+	framingBytes := framing.Bytes()
+	return &multipartBodyFactory{
+		ctx:         ctx,
+		audioPath:   audioPath,
+		openAudio:   openAudio,
+		prefix:      append([]byte(nil), framingBytes[:prefixLength]...),
+		suffix:      append([]byte(nil), framingBytes[prefixLength:]...),
+		contentType: writer.FormDataContentType(),
+	}, nil
+}
+
+func (factory *multipartBodyFactory) NewBody() (io.ReadCloser, error) {
+	factory.mu.Lock()
+	if factory.closed {
+		factory.mu.Unlock()
+		return nil, fmt.Errorf("multipart body factory is closed")
+	}
+	if err := factory.ctx.Err(); err != nil {
+		factory.mu.Unlock()
+		return nil, err
+	}
+	audio, err := factory.openAudio(factory.audioPath)
+	if err != nil {
+		factory.mu.Unlock()
+		return nil, fmt.Errorf("open audio file %q: %w", factory.audioPath, err)
+	}
+	if err := factory.ctx.Err(); err != nil {
+		factory.mu.Unlock()
+		_ = audio.Close()
+		return nil, err
+	}
+	source := &multipartAudioSource{audio: audio, closeDone: make(chan struct{})}
+	body := &multipartBody{
+		ctx:    factory.ctx,
+		source: source,
+		reader: io.MultiReader(bytes.NewReader(factory.prefix), source, bytes.NewReader(factory.suffix)),
+	}
+	factory.bodies = append(factory.bodies, body)
+	factory.mu.Unlock()
+	stopCancel := context.AfterFunc(factory.ctx, func() {
+		_ = body.Close()
+	})
+	body.mu.Lock()
+	body.stopCancel = stopCancel
+	closed := body.closed
+	body.mu.Unlock()
+	if closed {
+		stopCancel()
+	}
+	if err := factory.ctx.Err(); err != nil {
+		_ = body.Close()
+		return nil, err
+	}
+	return body, nil
+}
+
+func (factory *multipartBodyFactory) Close() error {
+	factory.mu.Lock()
+	if factory.closed {
+		bodies := append([]*multipartBody(nil), factory.bodies...)
+		factory.mu.Unlock()
+		return multipartBodyCloseErrors(bodies)
+	}
+	factory.closed = true
+	bodies := append([]*multipartBody(nil), factory.bodies...)
+	factory.mu.Unlock()
+	for _, body := range bodies {
+		_ = body.Close()
+	}
+	return multipartBodyCloseErrors(bodies)
+}
+
+func (factory *multipartBodyFactory) SourceError(includeAbandoned bool) error {
+	factory.mu.Lock()
+	bodies := append([]*multipartBody(nil), factory.bodies...)
+	factory.mu.Unlock()
+	var result error
+	for _, body := range bodies {
+		if err := body.sourceError(includeAbandoned); err != nil {
+			result = errors.Join(result, err)
+		}
+	}
+	return result
+}
+
+func multipartBodyCloseErrors(bodies []*multipartBody) error {
+	var result error
+	for _, body := range bodies {
+		if err := body.sourceError(false); err != nil {
+			result = errors.Join(result, err)
+		}
+	}
+	return result
+}
+
+type multipartBody struct {
+	ctx        context.Context
+	reader     io.Reader
+	source     *multipartAudioSource
+	stopCancel func() bool
+
+	mu        sync.Mutex
+	closed    bool
+	abandoned bool
+}
+
+func (body *multipartBody) Read(buffer []byte) (int, error) {
+	if err := body.ctx.Err(); err != nil {
+		return 0, err
+	}
+	body.mu.Lock()
+	closed := body.closed
+	body.mu.Unlock()
+	if closed {
+		return 0, io.ErrClosedPipe
+	}
+	return body.reader.Read(buffer)
+}
+
+func (body *multipartBody) Close() error {
+	body.mu.Lock()
+	if body.closed {
+		body.mu.Unlock()
+		return body.source.Close()
+	}
+	body.closed = true
+	body.abandoned = !body.source.reachedEOF()
+	stopCancel := body.stopCancel
+	body.mu.Unlock()
+	if stopCancel != nil {
+		stopCancel()
+	}
+	return body.source.Close()
+}
+
+func (body *multipartBody) sourceError(includeAbandoned bool) error {
+	body.mu.Lock()
+	abandoned := body.abandoned
+	body.mu.Unlock()
+	err := body.source.Err()
+	if err != nil {
+		return err
+	}
+	if abandoned && !includeAbandoned {
+		return nil
+	}
+	return nil
+}
+
+type multipartAudioSource struct {
+	audio io.ReadCloser
+
+	mu          sync.Mutex
+	closing     bool
+	eof         bool
+	readErr     error
+	closeErr    error
+	closeDone   chan struct{}
+	closeResult error
+	closed      bool
+}
+
+func (source *multipartAudioSource) Read(buffer []byte) (int, error) {
+	n, err := source.audio.Read(buffer)
+	source.mu.Lock()
+	switch {
+	case errors.Is(err, io.EOF):
+		source.eof = true
+	case err != nil && !source.closing:
+		source.readErr = errors.Join(source.readErr, err)
+	}
+	source.mu.Unlock()
+	return n, err
+}
+
+func (source *multipartAudioSource) Close() error {
+	source.mu.Lock()
+	if source.closed {
+		done := source.closeDone
+		source.mu.Unlock()
+		<-done
+		source.mu.Lock()
+		err := source.closeResult
+		source.mu.Unlock()
+		return err
+	}
+	source.closed = true
+	source.closing = true
+	reachedEOF := source.eof
+	source.mu.Unlock()
+
+	err := source.audio.Close()
+	source.mu.Lock()
+	source.closeResult = err
+	if err != nil && reachedEOF {
+		source.closeErr = err
+	}
+	close(source.closeDone)
+	source.mu.Unlock()
+	return err
+}
+
+func (source *multipartAudioSource) reachedEOF() bool {
+	source.mu.Lock()
+	defer source.mu.Unlock()
+	return source.eof
+}
+
+func (source *multipartAudioSource) Err() error {
+	source.mu.Lock()
+	defer source.mu.Unlock()
+	return errors.Join(source.readErr, source.closeErr)
+}

internal/adapters/whisperx/multipart_body_test.go

@@ -0,0 +1,327 @@
+package whisperx
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"mime"
+	"mime/multipart"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+func TestMultipartBodyReplayUsesIdenticalFraming(t *testing.T) {
+	factory := newTestMultipartBodyFactory(t, context.Background(), "audio-data")
+	defer factory.Close()
+
+	original, err := factory.NewBody()
+	if err != nil {
+		t.Fatalf("NewBody() original error = %v", err)
+	}
+	replay, err := factory.NewBody()
+	if err != nil {
+		t.Fatalf("NewBody() replay error = %v", err)
+	}
+	originalBytes, err := io.ReadAll(original)
+	if err != nil {
+		t.Fatalf("ReadAll(original) error = %v", err)
+	}
+	replayBytes, err := io.ReadAll(replay)
+	if err != nil {
+		t.Fatalf("ReadAll(replay) error = %v", err)
+	}
+	if !bytes.Equal(originalBytes, replayBytes) {
+		t.Fatal("original and replay multipart bytes differ")
+	}
+
+	parts := parseMultipartParts(t, factory.contentType, replayBytes)
+	if len(parts) != 2 {
+		t.Fatalf("part count = %d, want 2", len(parts))
+	}
+	if parts[0].name != "file" || parts[0].filename != "audio.flac" || string(parts[0].data) != "audio-data" {
+		t.Fatalf("file part = %#v, want file/audio.flac with exact audio", parts[0])
+	}
+	if parts[1].name != "language" || string(parts[1].data) != "en" {
+		t.Fatalf("language part = %#v, want language=en", parts[1])
+	}
+}
+
+func TestMultipartBodyReplayRestartsAfterPartialOriginal(t *testing.T) {
+	factory := newTestMultipartBodyFactory(t, context.Background(), "audio-data")
+	defer factory.Close()
+
+	original, err := factory.NewBody()
+	if err != nil {
+		t.Fatalf("NewBody() original error = %v", err)
+	}
+	partial := make([]byte, len(factory.prefix)+3)
+	if _, err := io.ReadFull(original, partial); err != nil {
+		t.Fatalf("ReadFull(original) error = %v", err)
+	}
+	if err := original.Close(); err != nil {
+		t.Fatalf("Close(original) error = %v", err)
+	}
+
+	replay, err := factory.NewBody()
+	if err != nil {
+		t.Fatalf("NewBody() replay error = %v", err)
+	}
+	replayBytes, err := io.ReadAll(replay)
+	if err != nil {
+		t.Fatalf("ReadAll(replay) error = %v", err)
+	}
+	parts := parseMultipartParts(t, factory.contentType, replayBytes)
+	if got := string(parts[0].data); got != "audio-data" {
+		t.Fatalf("replayed audio = %q, want complete payload", got)
+	}
+	if err := factory.SourceError(false); err != nil {
+		t.Fatalf("SourceError(false) = %v, want abandoned original ignored", err)
+	}
+}
+
+func TestMultipartBodySimultaneousBodiesUseIndependentSources(t *testing.T) {
+	var opens atomic.Int32
+	var closes atomic.Int32
+	factory, err := newMultipartBodyFactory(context.Background(), "audio.flac", "en", func(string) (io.ReadCloser, error) {
+		opens.Add(1)
+		return &countedReadCloser{Reader: strings.NewReader("audio-data"), closes: &closes}, nil
+	})
+	if err != nil {
+		t.Fatalf("newMultipartBodyFactory() error = %v", err)
+	}
+
+	first, err := factory.NewBody()
+	if err != nil {
+		t.Fatalf("NewBody() first error = %v", err)
+	}
+	second, err := factory.NewBody()
+	if err != nil {
+		t.Fatalf("NewBody() second error = %v", err)
+	}
+	var firstBytes, secondBytes []byte
+	var firstErr, secondErr error
+	var group sync.WaitGroup
+	group.Add(2)
+	go func() {
+		defer group.Done()
+		firstBytes, firstErr = io.ReadAll(first)
+	}()
+	go func() {
+		defer group.Done()
+		secondBytes, secondErr = io.ReadAll(second)
+	}()
+	group.Wait()
+	if firstErr != nil || secondErr != nil {
+		t.Fatalf("concurrent reads returned (%v, %v)", firstErr, secondErr)
+	}
+	if !bytes.Equal(firstBytes, secondBytes) {
+		t.Fatal("independent body bytes differ")
+	}
+	if got := opens.Load(); got != 2 {
+		t.Fatalf("audio opens = %d, want 2", got)
+	}
+	if err := factory.Close(); err != nil {
+		t.Fatalf("Close() error = %v", err)
+	}
+	if err := factory.Close(); err != nil {
+		t.Fatalf("second Close() error = %v", err)
+	}
+	if got := closes.Load(); got != 2 {
+		t.Fatalf("audio closes = %d, want 2", got)
+	}
+}
+
+func TestMultipartBodyReportsSourceFailures(t *testing.T) {
+	t.Run("read", func(t *testing.T) {
+		sourceErr := errors.New("read source")
+		factory, err := newMultipartBodyFactory(context.Background(), "audio.flac", "en", func(string) (io.ReadCloser, error) {
+			return &failingReadCloser{first: []byte("partial"), err: sourceErr}, nil
+		})
+		if err != nil {
+			t.Fatalf("newMultipartBodyFactory() error = %v", err)
+		}
+		body, err := factory.NewBody()
+		if err != nil {
+			t.Fatalf("NewBody() error = %v", err)
+		}
+		if _, err := io.ReadAll(body); !errors.Is(err, sourceErr) {
+			t.Fatalf("ReadAll() error = %v, want source failure", err)
+		}
+		_ = body.Close()
+		if err := factory.SourceError(false); !errors.Is(err, sourceErr) {
+			t.Fatalf("SourceError(false) = %v, want source failure", err)
+		}
+	})
+
+	t.Run("close after complete read", func(t *testing.T) {
+		closeErr := errors.New("close source")
+		factory, err := newMultipartBodyFactory(context.Background(), "audio.flac", "en", func(string) (io.ReadCloser, error) {
+			return &errorCloseReadCloser{Reader: strings.NewReader("audio-data"), err: closeErr}, nil
+		})
+		if err != nil {
+			t.Fatalf("newMultipartBodyFactory() error = %v", err)
+		}
+		body, err := factory.NewBody()
+		if err != nil {
+			t.Fatalf("NewBody() error = %v", err)
+		}
+		if _, err := io.ReadAll(body); err != nil {
+			t.Fatalf("ReadAll() error = %v", err)
+		}
+		if err := body.Close(); !errors.Is(err, closeErr) {
+			t.Fatalf("Close() error = %v, want source close failure", err)
+		}
+		if err := factory.SourceError(false); !errors.Is(err, closeErr) {
+			t.Fatalf("SourceError(false) = %v, want source close failure", err)
+		}
+	})
+}
+
+func TestMultipartBodyCloseAndCancelReleaseBlockedSource(t *testing.T) {
+	for _, test := range []struct {
+		name    string
+		release func(context.CancelFunc, io.ReadCloser)
+	}{
+		{name: "close", release: func(_ context.CancelFunc, body io.ReadCloser) { _ = body.Close() }},
+		{name: "cancel", release: func(cancel context.CancelFunc, _ io.ReadCloser) { cancel() }},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			ctx, cancel := context.WithCancel(context.Background())
+			defer cancel()
+			source := newSignalingBlockedReadCloser()
+			factory, err := newMultipartBodyFactory(ctx, "audio.flac", "en", func(string) (io.ReadCloser, error) {
+				return source, nil
+			})
+			if err != nil {
+				t.Fatalf("newMultipartBodyFactory() error = %v", err)
+			}
+			defer factory.Close()
+			body, err := factory.NewBody()
+			if err != nil {
+				t.Fatalf("NewBody() error = %v", err)
+			}
+			readDone := make(chan error, 1)
+			go func() {
+				_, err := io.ReadAll(body)
+				readDone <- err
+			}()
+			select {
+			case <-source.blocked:
+			case <-time.After(time.Second):
+				t.Fatal("audio source did not block")
+			}
+			test.release(cancel, body)
+			select {
+			case <-source.closed:
+			case <-time.After(time.Second):
+				t.Fatal("audio source was not closed")
+			}
+			select {
+			case <-readDone:
+			case <-time.After(time.Second):
+				t.Fatal("blocked body read did not return")
+			}
+			if test.name == "cancel" {
+				if _, err := factory.NewBody(); !errors.Is(err, context.Canceled) {
+					t.Fatalf("NewBody() after cancellation error = %v, want context.Canceled", err)
+				}
+			}
+		})
+	}
+}
+
+func newTestMultipartBodyFactory(t *testing.T, ctx context.Context, audio string) *multipartBodyFactory {
+	t.Helper()
+	factory, err := newMultipartBodyFactory(ctx, "audio.flac", "en", func(string) (io.ReadCloser, error) {
+		return io.NopCloser(strings.NewReader(audio)), nil
+	})
+	if err != nil {
+		t.Fatalf("newMultipartBodyFactory() error = %v", err)
+	}
+	return factory
+}
+
+type multipartTestPart struct {
+	name     string
+	filename string
+	data     []byte
+}
+
+func parseMultipartParts(t *testing.T, contentType string, body []byte) []multipartTestPart {
+	t.Helper()
+	mediaType, params, err := mime.ParseMediaType(contentType)
+	if err != nil {
+		t.Fatalf("ParseMediaType() error = %v", err)
+	}
+	if mediaType != "multipart/form-data" {
+		t.Fatalf("media type = %q, want multipart/form-data", mediaType)
+	}
+	reader := multipart.NewReader(bytes.NewReader(body), params["boundary"])
+	var parts []multipartTestPart
+	for {
+		part, err := reader.NextPart()
+		if errors.Is(err, io.EOF) {
+			return parts
+		}
+		if err != nil {
+			t.Fatalf("NextPart() error = %v", err)
+		}
+		data, err := io.ReadAll(part)
+		if err != nil {
+			t.Fatalf("ReadAll(part %q) error = %v", part.FormName(), err)
+		}
+		parts = append(parts, multipartTestPart{name: part.FormName(), filename: part.FileName(), data: data})
+	}
+}
+
+type countedReadCloser struct {
+	io.Reader
+	closes *atomic.Int32
+	once   sync.Once
+}
+
+func (reader *countedReadCloser) Close() error {
+	reader.once.Do(func() { reader.closes.Add(1) })
+	return nil
+}
+
+type errorCloseReadCloser struct {
+	io.Reader
+	err error
+}
+
+func (reader *errorCloseReadCloser) Close() error { return reader.err }
+
+type signalingBlockedReadCloser struct {
+	blocked chan struct{}
+	closed  chan struct{}
+	once    sync.Once
+	read    bool
+}
+
+func newSignalingBlockedReadCloser() *signalingBlockedReadCloser {
+	return &signalingBlockedReadCloser{blocked: make(chan struct{}), closed: make(chan struct{})}
+}
+
+func (reader *signalingBlockedReadCloser) Read(buffer []byte) (int, error) {
+	if !reader.read {
+		reader.read = true
+		return copy(buffer, "audio-data"), nil
+	}
+	reader.once.Do(func() { close(reader.blocked) })
+	<-reader.closed
+	return 0, errors.New("audio source closed")
+}
+
+func (reader *signalingBlockedReadCloser) Close() error {
+	select {
+	case <-reader.closed:
+	default:
+		close(reader.closed)
+	}
+	return nil
+}

internal/app/analyze_artifacts_commands_test.go

@@ -272,13 +272,18 @@ func TestExecuteAnalyzeRejectsPositionalArgsAndForceFlag(t *testing.T) {
 }
 
 func TestExecuteAnalyzeMissingConfigUsesRunStageLoadingPath(t *testing.T) {
+	deps, missingPath, executor := guardedMissingPipelineDiscovery(t)
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
-	code := Execute([]string{"analyze", "2026-05-03"}, &stdout, &stderr)
+	code := executeWithDependencies([]string{"analyze", "2026-05-03"}, &stdout, &stderr, deps, executor)
 	if code == 0 {
 		t.Fatal("exit code = 0, want non-zero")
 	}
-	if !strings.Contains(stderr.String(), "analyze: no pipeline config path provided and no default pipeline config found; searched:") {
+	if stdout.Len() != 0 {
+		t.Fatalf("stdout = %q, want empty", stdout.String())
+	}
+	if got := stderr.String(); !strings.Contains(got, "analyze: no pipeline config path provided") ||
+		!strings.Contains(got, "no default pipeline config found") || !strings.Contains(got, missingPath) {
 		t.Fatalf("stderr = %q, want pipeline discovery error", stderr.String())
 	}
 }
@@ -371,13 +376,18 @@ func TestExecutePublishUnknownArtifactFailsValidation(t *testing.T) {
 }
 
 func TestExecutePublishMissingConfigUsesRunStageLoadingPath(t *testing.T) {
+	deps, missingPath, executor := guardedMissingPipelineDiscovery(t)
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
-	code := Execute([]string{"publish", "2026-05-03"}, &stdout, &stderr)
+	code := executeWithDependencies([]string{"publish", "2026-05-03"}, &stdout, &stderr, deps, executor)
 	if code == 0 {
 		t.Fatal("exit code = 0, want non-zero")
 	}
-	if !strings.Contains(stderr.String(), "publish: no pipeline config path provided and no default pipeline config found; searched:") {
+	if stdout.Len() != 0 {
+		t.Fatalf("stdout = %q, want empty", stdout.String())
+	}
+	if got := stderr.String(); !strings.Contains(got, "publish: no pipeline config path provided") ||
+		!strings.Contains(got, "no default pipeline config found") || !strings.Contains(got, missingPath) {
 		t.Fatalf("stderr = %q, want pipeline discovery error", stderr.String())
 	}
 }

internal/app/command_dependencies.go

@@ -11,6 +11,7 @@ import (
 
 type commandDependencies struct {
 	diagnostics                io.Writer
+	resolvePipelineConfigPath  func(string) (string, error)
 	loadPipelineConfig         func(string, config.PipelineLoadOptions) (*config.PipelineConfig, error)
 	downloadObjectToTemp       func(context.Context, storage.ObjectStore, string, string) (string, error)
 	loadSecretsDir             func(string) (*configkit.SecretsReport, error)
@@ -25,6 +26,9 @@ func normalizeCommandDependencies(deps commandDependencies) commandDependencies
 	if deps.diagnostics == nil {
 		deps.diagnostics = io.Discard
 	}
+	if deps.resolvePipelineConfigPath == nil {
+		deps.resolvePipelineConfigPath = resolvePipelineConfigPath
+	}
 	if deps.loadPipelineConfig == nil {
 		deps.loadPipelineConfig = config.LoadPipelineWithOptions
 	}

internal/app/commands_test.go

@@ -62,6 +62,7 @@ func TestExecuteMissingRequiredFlags(t *testing.T) {
 		name                string
 		args                []string
 		want                string
+		controlledDiscovery bool
 	}{
 		{name: "run missing session", args: []string{"run"}, want: "run: session_id is required"},
 		{name: "plan old top-level removed", args: []string{"plan"}, want: `unknown command: "plan"`},
@@ -69,7 +70,7 @@ func TestExecuteMissingRequiredFlags(t *testing.T) {
 		{name: "resume removed", args: []string{"resume"}, want: `unknown command: "resume"`},
 		{name: "run-stage missing name", args: []string{"run-stage", "--config", "a", "--session", "b"}, want: "run-stage: expected stage name and session_id"},
 		{name: "run-stage missing session", args: []string{"run-stage", "polish"}, want: "run-stage: expected stage name and session_id"},
-		{name: "run missing config uses defaults", args: []string{"run", "2026-05-03", "--session", "session.yml"}, want: "run: no pipeline config path provided and no default pipeline config found; searched:"},
+		{name: "run missing config uses defaults", args: []string{"run", "2026-05-03", "--session", "session.yml"}, want: "run: no pipeline config path provided", controlledDiscovery: true},
 	}
 
 	for _, tc := range cases {
@@ -77,7 +78,13 @@ func TestExecuteMissingRequiredFlags(t *testing.T) {
 			var stdout bytes.Buffer
 			var stderr bytes.Buffer
 
-			code := Execute(tc.args, &stdout, &stderr)
+			deps := commandDependencies{}
+			executor := pipelineExecutor(executePlan)
+			missingPath := ""
+			if tc.controlledDiscovery {
+				deps, missingPath, executor = guardedMissingPipelineDiscovery(t)
+			}
+			code := executeWithDependencies(tc.args, &stdout, &stderr, deps, executor)
 			if code == 0 {
 				t.Fatalf("exit code = 0, want non-zero")
 			}
@@ -87,6 +94,11 @@ func TestExecuteMissingRequiredFlags(t *testing.T) {
 			if !strings.Contains(stderr.String(), tc.want) {
 				t.Fatalf("stderr = %q, want to contain %q", stderr.String(), tc.want)
 			}
+			if tc.controlledDiscovery {
+				if got := stderr.String(); !strings.Contains(got, "no default pipeline config found") || !strings.Contains(got, missingPath) {
+					t.Fatalf("stderr = %q, want controlled searched path %q", got, missingPath)
+				}
+			}
 		})
 	}
 }

internal/app/config_commands_test.go

@@ -371,6 +371,8 @@ func TestConfigInspectionOutputsNeverExposeResolvedCredentialValues(t *testing.T
 		"NARRATIO_INSPECT_SECRET":       firstCanary,
 		"NARRATIO_INSPECT_LLM_ONE":      firstCanary,
 		"NARRATIO_INSPECT_LLM_TWO":      secondCanary,
+		"NARRATIO_INSPECT_NOTARIUS_ONE": firstCanary,
+		"NARRATIO_INSPECT_NOTARIUS_TWO": secondCanary,
 	} {
 		t.Setenv(name, value)
 	}
@@ -384,13 +386,23 @@ func TestConfigInspectionOutputsNeverExposeResolvedCredentialValues(t *testing.T
     access_key_id: NARRATIO_INSPECT_ACCESS
     secret_access_key: NARRATIO_INSPECT_SECRET
 `, 1)
+	pipelineYAML += `notarius:
+  enabled: false
+  llm_api_key: NARRATIO_INSPECT_NOTARIUS_ONE
+`
 	if err := os.WriteFile(pipelinePath, []byte(pipelineYAML), 0o644); err != nil {
 		t.Fatal(err)
 	}
 	writeInspectionProfiles(t, pipelinePath,
 		"audita:\n  model: production\n  llm_api_key: NARRATIO_INSPECT_LLM_ONE\n",
-		"audita:\n  model: testing\n  llm_api_key: NARRATIO_INSPECT_LLM_TWO\n",
+		"audita:\n  model: testing\n  llm_api_key: NARRATIO_INSPECT_LLM_TWO\nnotarius:\n  llm_api_key: NARRATIO_INSPECT_NOTARIUS_TWO\n",
 	)
+	mustWriteTestFile(t, filepath.Join(filepath.Dir(pipelinePath), "profiles", "without-notarius-key.yml"), "notarius:\n  llm_api_key: null\n")
+
+	var validate bytes.Buffer
+	if err := ConfigValidate(context.Background(), []string{"--config", pipelinePath, "--profile", "production"}, &validate); err != nil {
+		t.Fatalf("config validate: %v", err)
+	}
 
 	var show bytes.Buffer
 	if err := ConfigShow(context.Background(), []string{"--config", pipelinePath, "--profile", "production"}, &show); err != nil {
@@ -408,19 +420,41 @@ func TestConfigInspectionOutputsNeverExposeResolvedCredentialValues(t *testing.T
 	if err := ConfigDiff(context.Background(), []string{"production", "testing", "--config", pipelinePath}, &diff); err != nil {
 		t.Fatalf("config diff: %v", err)
 	}
+	var removed bytes.Buffer
+	if err := ConfigShow(context.Background(), []string{"--config", pipelinePath, "--profile", "without-notarius-key"}, &removed); err != nil {
+		t.Fatalf("config show with removed Notarius credential: %v", err)
+	}
 	for label, output := range map[string]string{"show": show.String(), "sources": sources.String(), "artifacts": catalog.String(), "diff": diff.String()} {
 		if strings.Contains(output, firstCanary) || strings.Contains(output, secondCanary) {
 			t.Fatalf("%s output exposed credential value: %q", label, output)
 		}
 	}
-	for _, reference := range []string{"NARRATIO_INSPECT_ACCESS", "NARRATIO_INSPECT_SECRET", "NARRATIO_INSPECT_LLM_ONE"} {
+	for _, reference := range []string{"NARRATIO_INSPECT_ACCESS", "NARRATIO_INSPECT_SECRET", "NARRATIO_INSPECT_LLM_ONE", "NARRATIO_INSPECT_NOTARIUS_ONE"} {
 		if !strings.Contains(show.String(), reference) {
 			t.Fatalf("show omitted safe credential reference %q: %q", reference, show.String())
 		}
 	}
-	if !strings.Contains(diff.String(), "NARRATIO_INSPECT_LLM_ONE") || !strings.Contains(diff.String(), "NARRATIO_INSPECT_LLM_TWO") {
+	if !strings.Contains(diff.String(), "NARRATIO_INSPECT_LLM_ONE") || !strings.Contains(diff.String(), "NARRATIO_INSPECT_LLM_TWO") ||
+		!strings.Contains(diff.String(), "NARRATIO_INSPECT_NOTARIUS_ONE") || !strings.Contains(diff.String(), "NARRATIO_INSPECT_NOTARIUS_TWO") {
 		t.Fatalf("diff omitted safe credential references: %q", diff.String())
 	}
+	if !strings.Contains(sources.String(), "notarius.llm_api_key") {
+		t.Fatalf("sources omitted Notarius credential ownership: %q", sources.String())
+	}
+	if strings.Contains(removed.String(), "llm_api_key") || strings.Contains(removed.String(), "NARRATIO_INSPECT_NOTARIUS_ONE") {
+		t.Fatalf("profile null did not remove Notarius credential: %q", removed.String())
+	}
+}
+
+func TestConfigValidateRejectsUnavailableNotariusCredential(t *testing.T) {
+	const envName = "NARRATIO_INSPECT_NOTARIUS_MISSING"
+	restoreEnvAfterTest(t, envName)
+	path := filepath.Join(t.TempDir(), "pipeline.yml")
+	mustWriteTestFile(t, path, "whisperx:\n  transcribe_url: https://transcription.example.test/transcribe\nnotarius:\n  enabled: false\n  llm_api_key: "+envName+"\n")
+	err := ConfigValidate(context.Background(), []string{"--config", path}, io.Discard)
+	if err == nil || !strings.Contains(err.Error(), "secret.unset") {
+		t.Fatalf("ConfigValidate() error = %v, want unavailable credential failure", err)
+	}
 }
 
 func TestConfigCommandsInspectMaintainedSplitBundleWithoutRuntimeState(t *testing.T) {

internal/app/config_loader.go

@@ -163,7 +163,7 @@ func loadPipelineCampaignConfigWithDependencies(pipelineFlag, campaignFlag, camp
 
 func loadPipelineConfigWithDependencies(pipelineFlag string, opts config.PipelineLoadOptions, secretsDir *string, deps commandDependencies) (string, *config.PipelineConfig, error) {
 	deps = normalizeCommandDependencies(deps)
-	resolvedPipelinePath, err := resolvePipelineConfigPath(pipelineFlag)
+	resolvedPipelinePath, err := deps.resolvePipelineConfigPath(pipelineFlag)
 	if err != nil {
 		return "", nil, err
 	}

internal/app/extract_lifecycle_test.go

@@ -7,11 +7,13 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"reflect"
 	"sort"
 	"strings"
 	"testing"
 	"time"
 
+	configkit "gitea.maximumdirect.net/eric/ConfigKit"
 	"gitea.maximumdirect.net/eric/narratio/internal/adapters/notarius"
 	"gitea.maximumdirect.net/eric/narratio/internal/artifactmodel"
 	"gitea.maximumdirect.net/eric/narratio/internal/artifactpolicy"
@@ -181,12 +183,16 @@ func TestExtractLifecyclePrepareBindsVerifiedReferenceSnapshots(t *testing.T) {
 	for index, expected := range want {
 		binding := request.References[index]
 		canonical := filepath.Join(paths.InputsDir, expected.filename)
-		snapshot := filepath.Join(
+		descriptor, ok := artifactpolicy.DescribePreparedInputSource(expected.sourceID)
-			artifacts.SessionRunNotariusReferencesDirForCampaign(
+		if !ok {
-				cfg.Pipeline.Workspace.Root, cfg.Session.Campaign, cfg.Session.SessionID, loaded.RunID,
+			t.Fatalf("DescribePreparedInputSource(%q) ok = false", expected.sourceID)
-			),
+		}
-			expected.filename,
+		snapshot, err := artifacts.SessionNotariusReferenceSnapshotPath(
+			paths, lifecycleInputChecksum(t, loaded, descriptor.ManifestKind), expected.filename,
 		)
+		if err != nil {
+			t.Fatalf("SessionNotariusReferenceSnapshotPath(%q) error = %v", expected.sourceID, err)
+		}
 		if binding.Selector != expected.selector || binding.Path != snapshot || binding.Path == canonical || binding.Path == originalPaths[expected.sourceID] {
 			t.Fatalf("reference[%d] = %#v, want selector %q snapshot %q and not prepared/source paths", index, binding, expected.selector, snapshot)
 		}
@@ -393,6 +399,140 @@ func TestExtractLifecycleFailureInvalidatesAndOrdinaryRetryRerunsDownstream(t *t
 	}
 }
 
+func TestExtractLifecycleRetryReusesStableSnapshotsAndChangedReferenceSelectsNewPath(t *testing.T) {
+	cfg, env, runner := extractionLifecycleFixture(t, true)
+	configureLifecycleReferences(t, cfg)
+	runner.failuresRemaining = 1
+	plan := prepareExtractLifecyclePlan(t)
+
+	if _, err := executeStages(context.Background(), cfg, plan, RunOptions{Env: env}); err == nil {
+		t.Fatal("first executeStages() error = nil, want extraction failure")
+	}
+	if len(runner.requests) != 1 {
+		t.Fatalf("failed requests = %d, want 1", len(runner.requests))
+	}
+	firstPaths := lifecycleReferencePaths(runner.requests[0])
+	if _, err := executeStages(context.Background(), cfg, plan, RunOptions{Env: env}); err != nil {
+		t.Fatalf("retry executeStages() error = %v", err)
+	}
+	if len(runner.requests) != 2 {
+		t.Fatalf("retry requests = %d, want 2", len(runner.requests))
+	}
+	if secondPaths := lifecycleReferencePaths(runner.requests[1]); !reflect.DeepEqual(secondPaths, firstPaths) {
+		t.Fatalf("snapshot paths changed on retry:\nfirst %#v\nsecond %#v", firstPaths, secondPaths)
+	}
+
+	partyDocument, err := config.ParseParty([]byte(`schema_version: narratio.party.v1
+characters:
+  changed:
+    player: {name: Eric}
+    character:
+      name: Changed
+      classes: [{name: wizard}]
+`))
+	if err != nil {
+		t.Fatalf("ParseParty(changed party) error = %v", err)
+	}
+	cfg.Party.Canonical = partyDocument
+	persisted := loadLifecycleManifest(t, cfg)
+	prepare, err := stage.Select("prepare")
+	if err != nil {
+		t.Fatalf("stage.Select(prepare) error = %v", err)
+	}
+	if _, err := prepare.Run(context.Background(), env, persisted); err != nil {
+		t.Fatalf("prepare.Run() error = %v", err)
+	}
+	if err := (&manifest.LocalStore{}).Save(context.Background(), manifestPathFor(cfg), persisted); err != nil {
+		t.Fatalf("Save(reprepared manifest) error = %v", err)
+	}
+	extractPlan, _ := BuildSingleStagePlan("extract")
+	if _, err := executeStages(context.Background(), cfg, extractPlan, RunOptions{Env: env}); err != nil {
+		t.Fatalf("changed-reference executeStages() error = %v", err)
+	}
+	if len(runner.requests) != 3 {
+		t.Fatalf("changed-reference requests = %d, want 3", len(runner.requests))
+	}
+	thirdPaths := lifecycleReferencePaths(runner.requests[2])
+	if thirdPaths["party"] == firstPaths["party"] {
+		t.Fatalf("changed party retained snapshot path %q", thirdPaths["party"])
+	}
+	if thirdPaths["players"] == firstPaths["players"] {
+		t.Fatalf("changed party retained derived players snapshot path %q", thirdPaths["players"])
+	}
+	for selector, firstPath := range firstPaths {
+		if selector != "party" && selector != "players" && thirdPaths[selector] != firstPath {
+			t.Fatalf("unchanged %s snapshot path = %q, want %q", selector, thirdPaths[selector], firstPath)
+		}
+		if _, err := os.Stat(firstPath); err != nil {
+			t.Fatalf("old %s snapshot %q was not retained: %v", selector, firstPath, err)
+		}
+	}
+}
+
+func TestExtractLifecycleCacheControlsAndSnapshotLossDoNotInvalidateCompleteResult(t *testing.T) {
+	cfg, env, runner := extractionLifecycleFixture(t, true)
+	configureLifecycleReferences(t, cfg)
+	if _, err := executeStages(context.Background(), cfg, prepareExtractLifecyclePlan(t), RunOptions{Env: env}); err != nil {
+		t.Fatalf("initial executeStages() error = %v", err)
+	}
+	paths := artifacts.NewLocalStore(cfg.Pipeline.Workspace.Root).SessionPathsFor(cfg.Session.Campaign, cfg.Session.SessionID)
+	cacheRoot := artifacts.SessionNotariusReferenceCacheDir(paths)
+	if err := os.RemoveAll(cacheRoot); err != nil {
+		t.Fatalf("RemoveAll(snapshot cache) error = %v", err)
+	}
+	cfg.Pipeline.Notarius.Resume = true
+	cfg.Pipeline.Notarius.ChunkCache = "bypass"
+	extractPlan, _ := BuildSingleStagePlan("extract")
+	summary, err := executeStages(context.Background(), cfg, extractPlan, RunOptions{Env: env})
+	if err != nil {
+		t.Fatalf("resume executeStages() error = %v", err)
+	}
+	if len(summary.Executed) != 0 || !reflect.DeepEqual(summary.Skipped, []string{"extract"}) || len(runner.requests) != 1 {
+		t.Fatalf("resume summary = %#v requests=%d", summary, len(runner.requests))
+	}
+	if _, err := os.Stat(cacheRoot); !errors.Is(err, os.ErrNotExist) {
+		t.Fatalf("skipped extraction recreated snapshot cache: %v", err)
+	}
+}
+
+func TestAnalyzeOnlyLifecyclePreservesExtractionWithoutInvokingNotarius(t *testing.T) {
+	cfg, env, runner := extractionLifecycleFixture(t, true)
+	extractPlan, _ := BuildSingleStagePlan("extract")
+	if _, err := executeStages(context.Background(), cfg, extractPlan, RunOptions{Env: env}); err != nil {
+		t.Fatalf("extract executeStages() error = %v", err)
+	}
+	before := loadLifecycleManifest(t, cfg).Stages["extract"]
+	beforeJSON, _ := json.Marshal(before)
+	analyzeRuns := 0
+	if _, err := executeStages(context.Background(), cfg, []stage.Stage{countingStage{name: "analyze", runs: &analyzeRuns}}, RunOptions{Env: env, Force: true}); err != nil {
+		t.Fatalf("analyze-only executeStages() error = %v", err)
+	}
+	after := loadLifecycleManifest(t, cfg).Stages["extract"]
+	afterJSON, _ := json.Marshal(after)
+	if analyzeRuns != 1 || len(runner.requests) != 1 || string(afterJSON) != string(beforeJSON) {
+		t.Fatalf("analyze-only lifecycle changed extraction: analyze=%d requests=%d\nbefore=%s\nafter=%s", analyzeRuns, len(runner.requests), beforeJSON, afterJSON)
+	}
+	for _, output := range after.Outputs {
+		if _, err := os.Stat(output.LocalPath); err != nil {
+			t.Fatalf("analyze-only lifecycle removed extract output %q: %v", output.LocalPath, err)
+		}
+	}
+}
+
+func TestForcedArtifactRegenerationUsesOrdinaryExtractAndAnalyzePath(t *testing.T) {
+	cfg, env, runner := extractionLifecycleFixture(t, true)
+	cfg.Pipeline.Notarius.Resume = true
+	cfg.Pipeline.Notarius.ChunkCache = "bypass"
+	analyzeRuns := 0
+	plan := extractionLifecyclePlan(t, &analyzeRuns)
+	if _, err := executeStages(context.Background(), cfg, plan, RunOptions{Env: env, Force: true, SelectedArtifacts: []string{"session_recap"}}); err != nil {
+		t.Fatalf("forced artifact regeneration error = %v", err)
+	}
+	if len(runner.requests) != 1 || runner.requests[0].Resume || runner.requests[0].ChunkCache != "refresh" || analyzeRuns != 1 {
+		t.Fatalf("forced path request=%#v analyze=%d", runner.requests, analyzeRuns)
+	}
+}
+
 func TestExtractLifecycleForcedSelfSkipInvalidatesDownstream(t *testing.T) {
 	cfg, env, _ := extractionLifecycleFixture(t, false)
 	markLifecycleStageSucceeded(t, cfg, "analyze")
@@ -485,6 +625,273 @@ func TestExtractLifecycleSkipsCurrentResumableResult(t *testing.T) {
 	}
 }
 
+func TestExtractLifecycleCredentialChangesRemainResumable(t *testing.T) {
+	for _, test := range []struct {
+		name   string
+		before func(*testing.T) *configkit.Secret
+		after  func(*testing.T) *configkit.Secret
+	}{
+		{
+			name: "added",
+			after: func(t *testing.T) *configkit.Secret {
+				return loadLifecycleNotariusCredential(t, "NARRATIO_LIFECYCLE_ADDED_KEY", "added-value")
+			},
+		},
+		{
+			name: "removed",
+			before: func(t *testing.T) *configkit.Secret {
+				return loadLifecycleNotariusCredential(t, "NARRATIO_LIFECYCLE_REMOVED_KEY", "removed-value")
+			},
+		},
+		{
+			name: "renamed",
+			before: func(t *testing.T) *configkit.Secret {
+				return loadLifecycleNotariusCredential(t, "NARRATIO_LIFECYCLE_FIRST_KEY", "first-value")
+			},
+			after: func(t *testing.T) *configkit.Secret {
+				return loadLifecycleNotariusCredential(t, "NARRATIO_LIFECYCLE_SECOND_KEY", "second-value")
+			},
+		},
+		{
+			name: "value rotated",
+			before: func(t *testing.T) *configkit.Secret {
+				return loadLifecycleNotariusCredential(t, "NARRATIO_LIFECYCLE_ROTATED_KEY", "first-value")
+			},
+			after: func(t *testing.T) *configkit.Secret {
+				return loadLifecycleNotariusCredential(t, "NARRATIO_LIFECYCLE_ROTATED_KEY", "second-value")
+			},
+		},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			cfg, env, runner := extractionLifecycleFixture(t, true)
+			if test.before != nil {
+				cfg.Pipeline.Notarius.LLMAPIKey = test.before(t)
+			}
+			analyzeRuns := 0
+			plan := extractionLifecyclePlan(t, &analyzeRuns)
+			if _, err := executeStages(context.Background(), cfg, plan, RunOptions{Env: env}); err != nil {
+				t.Fatalf("initial executeStages() error = %v", err)
+			}
+			cfg.Pipeline.Notarius.LLMAPIKey = nil
+			if test.after != nil {
+				cfg.Pipeline.Notarius.LLMAPIKey = test.after(t)
+			}
+			resumed, err := executeStages(context.Background(), cfg, plan, RunOptions{Env: env})
+			if err != nil {
+				t.Fatalf("resume executeStages() error = %v", err)
+			}
+			if len(resumed.Executed) != 0 || len(resumed.Skipped) != 2 || len(runner.requests) != 1 || analyzeRuns != 1 {
+				t.Fatalf("credential-only change reexecuted work: summary=%#v requests=%d analyze=%d", resumed, len(runner.requests), analyzeRuns)
+			}
+			loaded := loadLifecycleManifest(t, cfg)
+			if loaded.Stages["extract"].Status != manifest.StatusSucceeded || loaded.Stages["analyze"].Status != manifest.StatusSucceeded {
+				t.Fatalf("credential-only change invalidated stages: extract=%q analyze=%q", loaded.Stages["extract"].Status, loaded.Stages["analyze"].Status)
+			}
+		})
+	}
+}
+
+func TestExtractLifecycleConfigProfileChangesRerunExtractionAndDependents(t *testing.T) {
+	cfg, env, runner := extractionLifecycleFixture(t, true)
+	selected := "inexpensive"
+	cfg.Pipeline.Notarius.ConfigProfile = &selected
+	analyzeRuns := 0
+	plan := extractionLifecyclePlan(t, &analyzeRuns)
+
+	if _, err := executeStages(context.Background(), cfg, plan, RunOptions{Env: env}); err != nil {
+		t.Fatalf("initial executeStages() error = %v", err)
+	}
+	if len(runner.requests) != 1 || runner.requests[0].ConfigProfile == nil || *runner.requests[0].ConfigProfile != selected || analyzeRuns != 1 {
+		t.Fatalf("initial requests=%#v analyze=%d, want selected extraction and analysis", runner.requests, analyzeRuns)
+	}
+	reused, err := executeStages(context.Background(), cfg, plan, RunOptions{Env: env})
+	if err != nil {
+		t.Fatalf("reuse executeStages() error = %v", err)
+	}
+	if len(reused.Executed) != 0 || len(runner.requests) != 1 || analyzeRuns != 1 {
+		t.Fatalf("same-profile reuse summary=%#v requests=%d analyze=%d", reused, len(runner.requests), analyzeRuns)
+	}
+
+	markLifecycleStageSucceeded(t, cfg, "render")
+	markLifecycleStageSucceeded(t, cfg, "publish")
+	before := loadLifecycleManifest(t, cfg)
+	trimBefore, err := json.Marshal(before.Stages["trim"])
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	changed := "experimental"
+	cfg.Pipeline.Notarius.ConfigProfile = &changed
+	rerun, err := executeStages(context.Background(), cfg, plan, RunOptions{Env: env})
+	if err != nil {
+		t.Fatalf("changed-profile executeStages() error = %v", err)
+	}
+	if len(rerun.Executed) != 2 || len(runner.requests) != 2 || runner.requests[1].ConfigProfile == nil || *runner.requests[1].ConfigProfile != changed || analyzeRuns != 2 {
+		t.Fatalf("changed-profile summary=%#v requests=%#v analyze=%d", rerun, runner.requests, analyzeRuns)
+	}
+	after := loadLifecycleManifest(t, cfg)
+	trimAfter, err := json.Marshal(after.Stages["trim"])
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(trimAfter) != string(trimBefore) {
+		t.Fatalf("profile change altered upstream trim record:\nbefore=%s\nafter=%s", trimBefore, trimAfter)
+	}
+	if after.Stages["render"].Status != manifest.StatusSucceeded || after.Stages["analyze"].Status != manifest.StatusSucceeded || after.Stages["publish"].Status != manifest.StatusStale {
+		t.Fatalf("changed-profile lifecycle render=%#v analyze=%#v publish=%#v", after.Stages["render"], after.Stages["analyze"], after.Stages["publish"])
+	}
+
+	cfg.Pipeline.Notarius.ConfigProfile = nil
+	returned, err := executeStages(context.Background(), cfg, plan, RunOptions{Env: env})
+	if err != nil {
+		t.Fatalf("return-to-base executeStages() error = %v", err)
+	}
+	if len(returned.Executed) != 2 || len(runner.requests) != 3 || runner.requests[2].ConfigProfile != nil || analyzeRuns != 3 {
+		t.Fatalf("return-to-base summary=%#v requests=%#v analyze=%d", returned, runner.requests, analyzeRuns)
+	}
+	final := loadLifecycleManifest(t, cfg)
+	if final.Stages["trim"].Status != manifest.StatusSucceeded || final.Stages["render"].Status != manifest.StatusSucceeded {
+		t.Fatalf("return-to-base invalidated upstream siblings: trim=%#v render=%#v", final.Stages["trim"], final.Stages["render"])
+	}
+}
+
+func TestExtractLifecycleConfigProfileFailureClearsCurrentResultAndDependents(t *testing.T) {
+	cfg, env, runner := extractionLifecycleFixture(t, true)
+	selected := "inexpensive"
+	cfg.Pipeline.Notarius.ConfigProfile = &selected
+	analyzeRuns := 0
+	plan := extractionLifecyclePlan(t, &analyzeRuns)
+	if _, err := executeStages(context.Background(), cfg, plan, RunOptions{Env: env}); err != nil {
+		t.Fatalf("initial executeStages() error = %v", err)
+	}
+	markLifecycleStageSucceeded(t, cfg, "render")
+	markLifecycleStageSucceeded(t, cfg, "publish")
+
+	changed := "missing-profile"
+	cfg.Pipeline.Notarius.ConfigProfile = &changed
+	runner.failuresRemaining = 1
+	if _, err := executeStages(context.Background(), cfg, plan, RunOptions{Env: env}); err == nil {
+		t.Fatal("changed-profile executeStages() error = nil, want downstream failure")
+	}
+	failed := loadLifecycleManifest(t, cfg)
+	extract := failed.Stages["extract"]
+	if extract.Status != manifest.StatusFailed || len(extract.Outputs) != 0 || len(extract.Logs) != 0 || len(extract.GeneratedConfigs) != 0 || len(extract.Metadata) != 0 {
+		t.Fatalf("failed changed-profile extraction advertised prior success: %#v", extract)
+	}
+	if failed.Stages["trim"].Status != manifest.StatusSucceeded || failed.Stages["render"].Status != manifest.StatusSucceeded ||
+		failed.Stages["analyze"].Status != manifest.StatusStale || failed.Stages["publish"].Status != manifest.StatusStale || analyzeRuns != 1 {
+		t.Fatalf("failed changed-profile lifecycle trim=%#v render=%#v analyze=%#v publish=%#v analyzeRuns=%d",
+			failed.Stages["trim"], failed.Stages["render"], failed.Stages["analyze"], failed.Stages["publish"], analyzeRuns)
+	}
+	if len(runner.requests) != 2 || runner.requests[1].ConfigProfile == nil || *runner.requests[1].ConfigProfile != changed {
+		t.Fatalf("failed request = %#v, want changed selector", runner.requests)
+	}
+}
+
+func TestExtractLifecycleRealConfigProfilesSelectNotariusExplicitly(t *testing.T) {
+	seed, env, runner := extractionLifecycleFixture(t, true)
+	workspace := seed.Pipeline.Workspace.Root
+	pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspace)
+	pipelineFile, err := os.OpenFile(pipelinePath, os.O_APPEND|os.O_WRONLY, 0)
+	if err != nil {
+		t.Fatal(err)
+	}
+	_, writeErr := pipelineFile.WriteString(`notarius:
+  enabled: true
+  binary: ` + filepath.Join(workspace, "notarius") + `
+  config_path: notarius.yml
+  pipeline_id: dnd-session
+  timeout: 45m
+  outputs:
+    npc_registry:
+      lane_id: npc-registry
+      media_type: application/json
+      schema_id: notarius.dnd.npc_registry
+      schema_version: v1
+      module_key: dnd/npc-registry
+`)
+	closeErr := pipelineFile.Close()
+	if writeErr != nil || closeErr != nil {
+		t.Fatalf("write Notarius configuration: %v / %v", writeErr, closeErr)
+	}
+	if err := os.WriteFile(filepath.Join(filepath.Dir(pipelinePath), "notarius.yml"), []byte("pipelines: {}\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	profilesDir := filepath.Join(filepath.Dir(pipelinePath), "profiles")
+	if err := os.MkdirAll(profilesDir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	for name, contents := range map[string]string{
+		"testing":           "whisperx:\n  language: fr\nnotarius:\n  config_profile: downstream-economy\n",
+		"narratio-only":     "whisperx:\n  language: de\n",
+		"narratio-only-two": "whisperx:\n  language: es\n",
+	} {
+		if err := os.WriteFile(filepath.Join(profilesDir, name+".yml"), []byte(contents), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	load := func(profile string) *config.Config {
+		t.Helper()
+		loaded, err := config.LoadWithSessionOptions(pipelinePath, campaignPath, sessionPath, config.SessionLoadOptions{Profile: &profile})
+		if err != nil {
+			t.Fatalf("load profile %q: %v", profile, err)
+		}
+		return loaded
+	}
+	plan, err := BuildSingleStagePlan("extract")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	testingConfig := load("testing")
+	runner.cfg = testingConfig.Pipeline.Notarius
+	if _, err := executeStages(context.Background(), testingConfig, plan, RunOptions{Env: env}); err != nil {
+		t.Fatalf("execute testing profile: %v", err)
+	}
+	if len(runner.requests) != 1 || runner.requests[0].ConfigProfile == nil || *runner.requests[0].ConfigProfile != "downstream-economy" {
+		t.Fatalf("testing profile request = %#v, want explicit differently named downstream selector", runner.requests)
+	}
+
+	narratioOnly := load("narratio-only")
+	runner.cfg = narratioOnly.Pipeline.Notarius
+	if _, err := executeStages(context.Background(), narratioOnly, plan, RunOptions{Env: env}); err != nil {
+		t.Fatalf("execute Narratio-only profile: %v", err)
+	}
+	if len(runner.requests) != 2 || runner.requests[1].ConfigProfile != nil {
+		t.Fatalf("Narratio-only profile request = %#v, want no automatic downstream selector", runner.requests)
+	}
+
+	narratioOnlyTwo := load("narratio-only-two")
+	runner.cfg = narratioOnlyTwo.Pipeline.Notarius
+	reused, err := executeStages(context.Background(), narratioOnlyTwo, plan, RunOptions{Env: env})
+	if err != nil {
+		t.Fatalf("execute second Narratio-only profile: %v", err)
+	}
+	if len(reused.Executed) != 0 || len(runner.requests) != 2 {
+		t.Fatalf("Narratio profile label/effective digest broadened invalidation: summary=%#v requests=%#v", reused, runner.requests)
+	}
+}
+
+func TestPreparedPipelineAndManifestExcludeNotariusCredentialValue(t *testing.T) {
+	const name = "NARRATIO_LIFECYCLE_PERSISTED_KEY"
+	const canary = "notarius-persisted-credential-canary"
+	cfg, env, _ := extractionLifecycleFixture(t, true)
+	cfg.Pipeline.Notarius.LLMAPIKey = loadLifecycleNotariusCredential(t, name, canary)
+	if _, err := executeStages(context.Background(), cfg, prepareExtractLifecyclePlan(t), RunOptions{Env: env}); err != nil {
+		t.Fatalf("executeStages() error = %v", err)
+	}
+	paths := artifacts.NewLocalStore(cfg.Pipeline.Workspace.Root).SessionPathsFor(cfg.Session.Campaign, cfg.Session.SessionID)
+	for _, path := range []string{paths.ManifestPath, filepath.Join(paths.InputsDir, "pipeline.resolved.yml")} {
+		data, err := os.ReadFile(path)
+		if err != nil {
+			t.Fatalf("ReadFile(%q) error = %v", path, err)
+		}
+		if strings.Contains(string(data), canary) {
+			t.Fatalf("persisted Narratio file %q contains the credential value", path)
+		}
+	}
+}
+
 func TestExtractLifecycleRerunsAfterDirectTranscriptChange(t *testing.T) {
 	cfg, env, runner := extractionLifecycleFixture(t, true)
 	analyzeRuns := 0
@@ -696,6 +1103,14 @@ func lifecycleInputChecksum(t *testing.T, m *manifest.Manifest, kind string) str
 	return ""
 }
 
+func lifecycleReferencePaths(request notarius.RunRequest) map[string]string {
+	paths := make(map[string]string, len(request.References))
+	for _, reference := range request.References {
+		paths[reference.Selector] = reference.Path
+	}
+	return paths
+}
+
 func lifecycleDndOutputs() map[string]config.NotariusOutputConfig {
 	return map[string]config.NotariusOutputConfig{
 		"item_registry":        {LaneID: "item-registry", MediaType: "application/json", SchemaID: "notarius.dnd.item_registry", SchemaVersion: "v1", ModuleKey: "dnd/item-registry"},
@@ -761,3 +1176,17 @@ func extractionLifecycleFixture(t *testing.T, enabled bool) (*config.Config, *st
 	runner := &materializingNotariusRunner{cfg: cfg.Pipeline.Notarius}
 	return cfg, &stage.Env{Notarius: runner}, runner
 }
+
+func loadLifecycleNotariusCredential(t *testing.T, name, value string) *configkit.Secret {
+	t.Helper()
+	t.Setenv(name, value)
+	path := filepath.Join(t.TempDir(), "pipeline.yml")
+	if err := os.WriteFile(path, []byte("whisperx:\n  transcribe_url: https://transcription.example.test/transcribe\nnotarius:\n  enabled: false\n  llm_api_key: "+name+"\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	pipeline, err := config.LoadPipeline(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return pipeline.Notarius.LLMAPIKey
+}

internal/app/operator_helpers_test.go

@@ -164,19 +164,19 @@ func TestExecuteSessionInitRequiresSessionID(t *testing.T) {
 }
 
 func TestExecuteSessionInitMissingDefaultConfigReportsSearchedPaths(t *testing.T) {
-	origPipelineDefaults := append([]string(nil), config.DefaultPipelineConfigSearchPaths...)
+	deps, missingPath, executor := guardedMissingPipelineDiscovery(t)
-	config.DefaultPipelineConfigSearchPaths = []string{filepath.Join(t.TempDir(), "missing-pipeline.yml")}
-	t.Cleanup(func() {
-		config.DefaultPipelineConfigSearchPaths = origPipelineDefaults
-	})
 
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
-	code := Execute([]string{"session", "init", "2026-06-07", "--remote"}, &stdout, &stderr)
+	code := executeWithDependencies([]string{"session", "init", "2026-06-07", "--remote"}, &stdout, &stderr, deps, executor)
 	if code == 0 {
 		t.Fatal("exit code = 0, want non-zero")
 	}
-	if !strings.Contains(stderr.String(), "session init: no pipeline config path provided and no default pipeline config found; searched:") {
+	if stdout.Len() != 0 {
+		t.Fatalf("stdout = %q, want empty", stdout.String())
+	}
+	if got := stderr.String(); !strings.Contains(got, "session init: no pipeline config path provided") ||
+		!strings.Contains(got, "no default pipeline config found") || !strings.Contains(got, missingPath) {
 		t.Fatalf("stderr = %q, want default pipeline searched-path error", stderr.String())
 	}
 }

internal/app/pipeline_config_path_test.go

@@ -1,10 +1,16 @@
 package app
 
 import (
+	"bytes"
+	"context"
+	"errors"
 	"os"
 	"path/filepath"
 	"strings"
 	"testing"
+
+	configkit "gitea.maximumdirect.net/eric/ConfigKit"
+	"gitea.maximumdirect.net/eric/narratio/internal/config"
 )
 
 func TestResolvePipelineConfigPathWithCandidatesExplicitWins(t *testing.T) {
@@ -55,11 +61,57 @@ func TestResolvePipelineConfigPathWithCandidatesPrecedence(t *testing.T) {
 }
 
 func TestResolvePipelineConfigPathWithCandidatesMissing(t *testing.T) {
-	_, err := resolvePipelineConfigPathWithCandidates("", []string{"/does/not/exist/one.yml", "/does/not/exist/two.yml"})
+	directory := t.TempDir()
+	first := filepath.Join(directory, "one.yml")
+	second := filepath.Join(directory, "two.yml")
+	_, err := resolvePipelineConfigPathWithCandidates("", []string{first, second})
 	if err == nil {
 		t.Fatal("expected error, got nil")
 	}
 	if !strings.Contains(err.Error(), "no default pipeline config found") {
 		t.Fatalf("error = %q, want missing-defaults context", err.Error())
 	}
+	if !strings.Contains(err.Error(), first) || !strings.Contains(err.Error(), second) {
+		t.Fatalf("error = %q, want controlled searched paths", err.Error())
+	}
+}
+
+func TestExecuteMissingExplicitConfigDiscoversExistingDefaultBeforeLoading(t *testing.T) {
+	directory := t.TempDir()
+	missing := filepath.Join(directory, "missing.yml")
+	existing := filepath.Join(directory, "pipeline.yml")
+	if err := os.WriteFile(existing, []byte("workspace:\n  root: ./tmp\n"), 0o644); err != nil {
+		t.Fatalf("write default pipeline: %v", err)
+	}
+
+	controlledErr := errors.New("controlled pipeline loader boundary")
+	loadedPath := ""
+	deps := commandDependenciesForPipelineCandidates(missing, existing)
+	deps.loadPipelineConfig = func(path string, _ config.PipelineLoadOptions) (*config.PipelineConfig, error) {
+		loadedPath = path
+		return nil, controlledErr
+	}
+	deps.loadSecretsDir = func(string) (*configkit.SecretsReport, error) {
+		t.Fatal("absent conventional secrets directory unexpectedly invoked bootstrap loader")
+		return nil, nil
+	}
+
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+	code := executeWithDependencies([]string{"config", "validate"}, &stdout, &stderr, deps, func(context.Context, *config.Config, BoundedPlan, RunOptions) (*RunSummary, error) {
+		t.Fatal("config validation unexpectedly invoked pipeline executor")
+		return nil, nil
+	})
+	if code == 0 {
+		t.Fatal("exit code = 0, want controlled loader failure")
+	}
+	if loadedPath != existing {
+		t.Fatalf("loader path = %q, want discovered default %q", loadedPath, existing)
+	}
+	if stdout.Len() != 0 {
+		t.Fatalf("stdout = %q, want empty", stdout.String())
+	}
+	if !strings.Contains(stderr.String(), controlledErr.Error()) {
+		t.Fatalf("stderr = %q, want controlled loader error", stderr.String())
+	}
 }

internal/app/restore_execution_test.go

@@ -82,6 +82,28 @@ func TestExecuteRestoreRoundTripsPublishedExtractionAndManifestMetadata(t *testi
 	remoteManifest.RunID = "20260519T010203Z-a1b2c3d4"
 	producerRoot := "/prior/workspace/work/sample-campaign/2026-05-03"
 	remoteManifest.LocalWorkDir = filepath.Join(producerRoot, "runs", remoteManifest.RunID)
+	rawRelative := "transcripts/raw/alice.json"
+	rawOutput := manifest.ArtifactRecord{
+		Kind: "transcript_raw", LocalPath: filepath.Join(producerRoot, filepath.FromSlash(rawRelative)),
+		ProducerRunID: remoteManifest.RunID, Checksum: strings.Repeat("b", 64),
+	}
+	remoteManifest.MarkStageSucceeded("transcribe", time.Now().UTC(), []manifest.ArtifactRecord{rawOutput})
+	remoteManifest.Stages["transcribe"].TranscribeStateVersion = manifest.TranscribeStateContractVersion
+	remoteManifest.Stages["transcribe"].TranscribeSpeakers = map[string]manifest.TranscribeSpeakerRecord{
+		"alice": {
+			FingerprintVersion: manifest.TranscribeFingerprintContractVersion,
+			Fingerprint:        strings.Repeat("c", 64),
+			AudioPath:          "audio/alice.flac",
+			AudioSHA256:        strings.Repeat("a", 64),
+			AudioSize:          12,
+			Output: manifest.ArtifactRecord{
+				Kind: "transcript_raw", LocalPath: rawRelative,
+				ProducerRunID: remoteManifest.RunID, Checksum: strings.Repeat("b", 64),
+			},
+			OutputSize:    15,
+			ProducerRunID: remoteManifest.RunID,
+		},
+	}
 	remoteManifest.Stages["extract"] = &manifest.StageRecord{
 		Name: "extract", Status: manifest.StatusSucceeded,
 		Outputs: []manifest.ArtifactRecord{{
@@ -121,6 +143,13 @@ func TestExecuteRestoreRoundTripsPublishedExtractionAndManifestMetadata(t *testi
 	if want := filepath.Join(sessionRoot, "artifacts", "encounters.json"); lane.LocalPath != want {
 		t.Fatalf("rebased extraction path = %q, want %q", lane.LocalPath, want)
 	}
+	speaker := restored.Stages["transcribe"].TranscribeSpeakers["alice"]
+	if speaker.AudioPath != "audio/alice.flac" || speaker.Output.LocalPath != rawRelative {
+		t.Fatalf("restored speaker paths = %#v, want session-relative paths", speaker)
+	}
+	if _, err := os.Stat(filepath.Join(sessionRoot, filepath.FromSlash(rawRelative))); !os.IsNotExist(err) {
+		t.Fatalf("unpublished raw transcript should not be restored; stat err=%v", err)
+	}
 }
 
 func TestExecuteRestoreIncludeAudioRestoresAudio(t *testing.T) {

internal/app/restore_plan_test.go

@@ -24,6 +24,7 @@ func TestRestorePlanDefaultScope(t *testing.T) {
 	seedCurrentRestoreObject(t, store, current, current.SessionPrefix+"audio/alice.flac", []byte("audio"))
 	seedRestoreObject(store, current.SessionPrefix+"runs/20260519T010203Z-a1b2/manifest.json", []byte("{}"))
 	seedRestoreObject(store, current.SessionPrefix+"logs/publish.log", []byte("log"))
+	seedRestoreObject(store, current.SessionPrefix+"cache/notarius/references/ignored/party.yml", []byte("cache"))
 
 	plan, err := buildRestorePlan(context.Background(), cfg, current, store, RestorePlanOptions{})
 	if err != nil {

internal/app/runner_test.go

@@ -1082,7 +1082,7 @@ func TestExecuteStagesReportsSkippedStage(t *testing.T) {
 		t.Fatalf("Save manifest error = %v", err)
 	}
 
-	summary, err := executeStages(context.Background(), cfg, []stage.Stage{BuildFullPlan()[1]}, RunOptions{})
+	summary, err := executeStages(context.Background(), cfg, []stage.Stage{resultStage{name: "transcribe"}}, RunOptions{})
 	if err != nil {
 		t.Fatalf("executeStages() error = %v", err)
 	}
@@ -1302,7 +1302,7 @@ func TestExecuteStagesSkippedStagePreservesExistingOutputsProvenance(t *testing.
 		t.Fatalf("Save manifest error = %v", err)
 	}
 
-	summary, err := executeStages(context.Background(), cfg, []stage.Stage{BuildFullPlan()[1]}, RunOptions{})
+	summary, err := executeStages(context.Background(), cfg, []stage.Stage{resultStage{name: "transcribe"}}, RunOptions{})
 	if err != nil {
 		t.Fatalf("executeStages() error = %v", err)
 	}

internal/app/runner_test_helpers_test.go

@@ -2,10 +2,18 @@ package app
 
 import (
 	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"os"
+	"path/filepath"
+	"slices"
+	"strings"
 	"testing"
 
+	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
 	"gitea.maximumdirect.net/eric/narratio/internal/config"
 	"gitea.maximumdirect.net/eric/narratio/internal/manifest"
+	"gitea.maximumdirect.net/eric/narratio/internal/pathsafe"
 	"gitea.maximumdirect.net/eric/narratio/internal/stage"
 )
 
@@ -38,6 +46,94 @@ func seedCurrentSemanticEvidence(t *testing.T, cfg *config.Config, m *manifest.M
 			t.Fatalf("fingerprint stage %q: %v", name, err)
 		}
 		record.SemanticConfig = &fingerprint
+		if name == "transcribe" {
+			seedCurrentTranscribeEvidence(t, cfg, m, fingerprint)
+		}
+	}
+}
+
+func seedCurrentTranscribeEvidence(
+	t *testing.T,
+	cfg *config.Config,
+	m *manifest.Manifest,
+	semantic manifest.SemanticConfigFingerprint,
+) {
+	t.Helper()
+	store := artifacts.NewLocalStore(cfg.Pipeline.Workspace.Root)
+	paths := store.SessionPathsFor(cfg.Session.Campaign, m.SessionID)
+	if strings.TrimSpace(m.RunID) == "" {
+		m.RunID = "20260503T010203Z-a1b2c3d4"
+	}
+	records := make(map[string]manifest.TranscribeSpeakerRecord)
+	for _, input := range m.Inputs {
+		if input.Kind != "audio" {
+			continue
+		}
+		audioPath := artifacts.ResolveSessionLocalPathForRead(paths, input.Path)
+		audioBytes, err := os.ReadFile(audioPath)
+		if err != nil {
+			t.Fatalf("read transcribe audio fixture %q: %v", audioPath, err)
+		}
+		audioRelative, err := pathsafe.SlashRelativeFromRoot(paths.Root, audioPath)
+		if err != nil {
+			t.Fatalf("relativize transcribe audio fixture %q: %v", audioPath, err)
+		}
+		speaker := strings.TrimSuffix(filepath.Base(audioPath), filepath.Ext(audioPath))
+		outputRelative := filepath.ToSlash(filepath.Join("transcripts", "raw", speaker+".json"))
+		outputPath, err := pathsafe.JoinSlashRelativeUnderRoot(paths.Root, outputRelative)
+		if err != nil {
+			t.Fatalf("resolve transcribe output fixture: %v", err)
+		}
+		if _, err := os.Stat(outputPath); os.IsNotExist(err) {
+			mustWriteTestFile(t, outputPath, `{"segments":[]}`)
+		} else if err != nil {
+			t.Fatalf("inspect transcribe output fixture %q: %v", outputPath, err)
+		}
+		outputBytes, err := os.ReadFile(outputPath)
+		if err != nil {
+			t.Fatalf("read transcribe output fixture %q: %v", outputPath, err)
+		}
+		audioDigest := sha256.Sum256(audioBytes)
+		outputDigest := sha256.Sum256(outputBytes)
+		fingerprint, err := stage.FingerprintSemanticConfig(
+			manifest.TranscribeFingerprintContractVersion,
+			struct {
+				SpeakerID             string `json:"speaker_id"`
+				AudioPath             string `json:"audio_path"`
+				AudioSHA256           string `json:"audio_sha256"`
+				AudioSize             int64  `json:"audio_size"`
+				SemanticConfigVersion int    `json:"semantic_config_version"`
+				SemanticConfigDigest  string `json:"semantic_config_digest"`
+			}{
+				SpeakerID: speaker, AudioPath: audioRelative,
+				AudioSHA256: hex.EncodeToString(audioDigest[:]), AudioSize: int64(len(audioBytes)),
+				SemanticConfigVersion: semantic.Version, SemanticConfigDigest: semantic.Digest,
+			},
+		)
+		if err != nil {
+			t.Fatalf("fingerprint transcribe speaker fixture %q: %v", speaker, err)
+		}
+		output := manifest.ArtifactRecord{
+			Kind: "transcript_raw", LocalPath: outputRelative,
+			ProducerRunID: m.RunID, Checksum: hex.EncodeToString(outputDigest[:]),
+		}
+		records[speaker] = manifest.TranscribeSpeakerRecord{
+			FingerprintVersion: manifest.TranscribeFingerprintContractVersion,
+			Fingerprint:        fingerprint.Digest, AudioPath: audioRelative,
+			AudioSHA256: hex.EncodeToString(audioDigest[:]), AudioSize: int64(len(audioBytes)),
+			Output: output, OutputSize: int64(len(outputBytes)), ProducerRunID: m.RunID,
+		}
+	}
+	record := m.Stages["transcribe"]
+	record.TranscribeStateVersion = manifest.TranscribeStateContractVersion
+	record.TranscribeSpeakers = records
+	if len(record.Outputs) == 0 {
+		for _, speakerRecord := range records {
+			record.Outputs = append(record.Outputs, speakerRecord.Output)
+		}
+		slices.SortFunc(record.Outputs, func(a, b manifest.ArtifactRecord) int {
+			return strings.Compare(a.LocalPath, b.LocalPath)
+		})
 	}
 }
 

internal/app/secrets_bootstrap_test.go

@@ -2,6 +2,7 @@ package app
 
 import (
 	"bytes"
+	"fmt"
 	"io"
 	"os"
 	"path/filepath"
@@ -119,6 +120,52 @@ func TestSecretsBootstrapPreservesExistingEnvironmentValues(t *testing.T) {
 	}
 }
 
+func TestNotariusCredentialLoadsFromCommandSecretBootstrap(t *testing.T) {
+	tests := []struct {
+		name        string
+		explicit    bool
+		environment string
+		fileValue   string
+		wantValue   string
+	}{
+		{name: "conventional", fileValue: "conventional-value", wantValue: "conventional-value"},
+		{name: "explicit", explicit: true, fileValue: "explicit-value", wantValue: "explicit-value"},
+		{name: "environment precedence", explicit: true, environment: "environment-value", fileValue: "file-value", wantValue: "environment-value"},
+	}
+	for index, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			envName := fmt.Sprintf("NARRATIO_NOTARIUS_BOOTSTRAP_%d", index)
+			restoreEnvAfterTest(t, envName)
+			root := t.TempDir()
+			pipelinePath := filepath.Join(root, "pipeline.yml")
+			if err := os.WriteFile(pipelinePath, []byte("whisperx:\n  transcribe_url: https://transcription.example.test/transcribe\nnotarius:\n  enabled: false\n  llm_api_key: "+envName+"\n"), 0o644); err != nil {
+				t.Fatal(err)
+			}
+			secretsDir := filepath.Join(root, "secrets")
+			var selection *string
+			if test.explicit {
+				secretsDir = filepath.Join(t.TempDir(), "selected-secrets")
+				selection = &secretsDir
+			}
+			mustWriteSecretFile(t, filepath.Join(secretsDir, envName), test.fileValue+"\n")
+			if test.environment != "" {
+				if err := os.Setenv(envName, test.environment); err != nil {
+					t.Fatal(err)
+				}
+			}
+
+			_, pipeline, err := loadPipelineConfigWithDependencies(pipelinePath, config.PipelineLoadOptions{}, selection, commandDependencies{diagnostics: io.Discard})
+			if err != nil {
+				t.Fatalf("load pipeline: %v", err)
+			}
+			if pipeline.Notarius == nil || pipeline.Notarius.LLMAPIKey == nil || !pipeline.Notarius.LLMAPIKey.IsResolved() ||
+				pipeline.Notarius.LLMAPIKey.EnvName() != envName || pipeline.Notarius.LLMAPIKey.Value() != test.wantValue {
+				t.Fatal("Notarius credential did not resolve from the selected command bootstrap source")
+			}
+		})
+	}
+}
+
 func TestSecretsBootstrapPreservesSafePartialReportOnFailure(t *testing.T) {
 	directory := t.TempDir()
 	mustWriteSecretFile(t, filepath.Join(directory, "INVALID-NAME"), "must-not-appear\n")
@@ -173,7 +220,7 @@ func TestExecuteConfigValidateReportsSkippedEmptyBeforeTypedLoadFailure(t *testi
 	if err != nil {
 		t.Fatal(err)
 	}
-	pipelineYAML = []byte(strings.Replace(string(pipelineYAML), "audita:\n  binary:", "audita:\n  llm_api_key: "+name+"\n  binary:", 1))
+	pipelineYAML = append(pipelineYAML, []byte("notarius:\n  enabled: false\n  llm_api_key: "+name+"\n")...)
 	if err := os.WriteFile(pipelinePath, pipelineYAML, 0o644); err != nil {
 		t.Fatal(err)
 	}

internal/app/test_environment_test.go

@@ -1,11 +1,13 @@
 package app
 
 import (
+	"context"
 	"os"
 	"path/filepath"
 	"testing"
 
 	configkit "gitea.maximumdirect.net/eric/ConfigKit"
+	"gitea.maximumdirect.net/eric/narratio/internal/config"
 )
 
 // restoreEnvAfterTest clears names for a test and restores both their prior
@@ -47,3 +49,29 @@ func mustWriteSecretFile(t *testing.T, path, value string) {
 		t.Fatal(err)
 	}
 }
+
+func commandDependenciesForPipelineCandidates(candidates ...string) commandDependencies {
+	ownedCandidates := append([]string(nil), candidates...)
+	return commandDependencies{resolvePipelineConfigPath: func(flagValue string) (string, error) {
+		return resolvePipelineConfigPathWithCandidates(flagValue, ownedCandidates)
+	}}
+}
+
+func guardedMissingPipelineDiscovery(t *testing.T) (commandDependencies, string, pipelineExecutor) {
+	t.Helper()
+	candidate := filepath.Join(t.TempDir(), "missing-pipeline.yml")
+	deps := commandDependenciesForPipelineCandidates(candidate)
+	deps.loadSecretsDir = func(string) (*configkit.SecretsReport, error) {
+		t.Fatal("secret bootstrap continued after pipeline discovery failed")
+		return nil, nil
+	}
+	deps.loadPipelineConfig = func(string, config.PipelineLoadOptions) (*config.PipelineConfig, error) {
+		t.Fatal("typed pipeline loading continued after pipeline discovery failed")
+		return nil, nil
+	}
+	executor := func(context.Context, *config.Config, BoundedPlan, RunOptions) (*RunSummary, error) {
+		t.Fatal("pipeline execution continued after pipeline discovery failed")
+		return nil, nil
+	}
+	return deps, candidate, executor
+}

internal/app/transcribe_checkpoint_recovery_test.go

@@ -0,0 +1,472 @@
+package app
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"slices"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/adapters/seriatim"
+	"gitea.maximumdirect.net/eric/narratio/internal/adapters/whisperx"
+	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
+	"gitea.maximumdirect.net/eric/narratio/internal/config"
+	"gitea.maximumdirect.net/eric/narratio/internal/manifest"
+	"gitea.maximumdirect.net/eric/narratio/internal/stage"
+)
+
+func TestExecuteStagesDelegatesEmptyAudioAcceptanceToWhisperX(t *testing.T) {
+	for _, rejected := range []bool{false, true} {
+		name := "accepted"
+		if rejected {
+			name = "rejected"
+		}
+		t.Run(name, func(t *testing.T) {
+			cfg, store := setupTranscribeRecoveryFixture(t, []string{"alice"})
+			paths := artifacts.NewLocalStore(cfg.Pipeline.Workspace.Root).SessionPathsFor(cfg.Session.Campaign, cfg.Session.SessionID)
+			if err := os.WriteFile(filepath.Join(paths.AudioDir, "alice.flac"), nil, 0o644); err != nil {
+				t.Fatal(err)
+			}
+			fake := &whisperx.FakeClient{}
+			if rejected {
+				fake.Err = errors.New("service rejected audio")
+			}
+			transcribe := mustSelectStage(t, "transcribe")
+			_, err := executeStages(context.Background(), cfg, []stage.Stage{transcribe}, RunOptions{
+				Env: &Env{ManifestStore: store, WhisperX: fake},
+			})
+			if !errors.Is(err, fake.Err) {
+				t.Fatalf("transcribe error = %v, want %v", err, fake.Err)
+			}
+			if len(fake.RequestsSnapshot()) != 1 {
+				t.Fatal("empty audio was not sent to service")
+			}
+			m := loadTranscribeRecoveryManifest(t, store, cfg)
+			if rejected {
+				if len(m.Stages["transcribe"].TranscribeSpeakers) != 0 {
+					t.Fatal("rejected audio was checkpointed")
+				}
+				return
+			}
+			record, ok := m.Stages["transcribe"].TranscribeSpeakers["alice"]
+			if !ok || record.AudioSize != 0 {
+				t.Fatalf("missing zero-size checkpoint: %#v", record)
+			}
+			retry := &whisperx.FakeClient{}
+			summary, err := executeStages(context.Background(), cfg, []stage.Stage{transcribe}, RunOptions{
+				Env: &Env{ManifestStore: store, WhisperX: retry},
+			})
+			if err != nil {
+				t.Fatal(err)
+			}
+			if len(summary.Skipped) != 1 || len(retry.RequestsSnapshot()) != 0 {
+				t.Fatal("successful empty-audio result was not reused")
+			}
+		})
+	}
+}
+
+func TestExecuteStagesRetriesOnlyUncommittedTranscribeSpeakers(t *testing.T) {
+	cfg, baseStore := setupTranscribeRecoveryFixture(t, []string{"a", "b", "c", "d"})
+	concurrency := 1
+	cfg.Pipeline.WhisperX.Concurrency = &concurrency
+	cause := errors.New("speaker c failed")
+	failing := &whisperx.FakeClient{TranscribeFn: func(
+		_ context.Context,
+		req whisperx.TranscribeRequest,
+	) (whisperx.TranscribeResult, error) {
+		if req.SpeakerID == "c" {
+			return whisperx.TranscribeResult{}, cause
+		}
+		if req.SpeakerID == "d" {
+			t.Fatalf("speaker d was dispatched after c failed")
+		}
+		return writeTranscribeRecoveryResult(req)
+	}}
+	transcribe := mustSelectStage(t, "transcribe")
+
+	if _, err := executeStages(context.Background(), cfg, []stage.Stage{transcribe}, RunOptions{
+		Env: &Env{ManifestStore: baseStore, WhisperX: failing},
+	}); !errors.Is(err, cause) {
+		t.Fatalf("failed executeStages() error = %v, want %v", err, cause)
+	}
+	failed := loadTranscribeRecoveryManifest(t, baseStore, cfg)
+	if failed.Stages["transcribe"].Status != manifest.StatusFailed {
+		t.Fatalf("transcribe status = %q, want failed", failed.Stages["transcribe"].Status)
+	}
+	if got := transcribeSpeakerKeys(failed); !slices.Equal(got, []string{"a", "b"}) {
+		t.Fatalf("checkpointed speakers = %#v, want a and b", got)
+	}
+	if failed.Stages["prepare"].Status != manifest.StatusSucceeded {
+		t.Fatalf("prepare status = %q, want unchanged success", failed.Stages["prepare"].Status)
+	}
+	if failed.Stages["merge"].Status != manifest.StatusStale {
+		t.Fatalf("merge status = %q, want stale after transcribe failure", failed.Stages["merge"].Status)
+	}
+
+	retry := &whisperx.FakeClient{}
+	if _, err := executeStages(context.Background(), cfg, []stage.Stage{transcribe}, RunOptions{
+		Env: &Env{ManifestStore: baseStore, WhisperX: retry},
+	}); err != nil {
+		t.Fatalf("retry executeStages() error = %v", err)
+	}
+	if got := requestedTranscribeSpeakers(retry); !slices.Equal(got, []string{"c", "d"}) {
+		t.Fatalf("retry speakers = %#v, want c and d", got)
+	}
+	completed := loadTranscribeRecoveryManifest(t, baseStore, cfg)
+	if completed.Stages["transcribe"].Status != manifest.StatusSucceeded {
+		t.Fatalf("transcribe status = %q, want succeeded", completed.Stages["transcribe"].Status)
+	}
+	if got := transcribeSpeakerKeys(completed); !slices.Equal(got, []string{"a", "b", "c", "d"}) {
+		t.Fatalf("completed speakers = %#v", got)
+	}
+}
+
+func TestExecuteStagesRebuildsTranscribeAggregateAfterFinalSaveFailure(t *testing.T) {
+	cfg, baseStore := setupTranscribeRecoveryFixture(t, []string{"alice", "bob"})
+	store := &transcribeAggregateSaveFailingStore{
+		Store: baseStore,
+		Err:   errors.New("aggregate save failed"),
+	}
+	fake := &whisperx.FakeClient{}
+	transcribe := mustSelectStage(t, "transcribe")
+
+	if _, err := executeStages(context.Background(), cfg, []stage.Stage{transcribe}, RunOptions{
+		Env: &Env{ManifestStore: store, WhisperX: fake},
+	}); !errors.Is(err, store.Err) {
+		t.Fatalf("executeStages() error = %v, want aggregate save failure", err)
+	}
+	failed := loadTranscribeRecoveryManifest(t, baseStore, cfg)
+	if failed.Stages["transcribe"].Status != manifest.StatusFailed {
+		t.Fatalf("transcribe status = %q, want failed", failed.Stages["transcribe"].Status)
+	}
+	if got := transcribeSpeakerKeys(failed); !slices.Equal(got, []string{"alice", "bob"}) {
+		t.Fatalf("checkpointed speakers = %#v, want both speakers", got)
+	}
+
+	retry := &whisperx.FakeClient{}
+	if _, err := executeStages(context.Background(), cfg, []stage.Stage{transcribe}, RunOptions{
+		Env: &Env{ManifestStore: baseStore, WhisperX: retry},
+	}); err != nil {
+		t.Fatalf("retry executeStages() error = %v", err)
+	}
+	if got := len(retry.RequestsSnapshot()); got != 0 {
+		t.Fatalf("retry adapter requests = %d, want aggregate-only rebuild", got)
+	}
+	completed := loadTranscribeRecoveryManifest(t, baseStore, cfg)
+	if completed.Stages["transcribe"].Status != manifest.StatusSucceeded || len(completed.Stages["transcribe"].Outputs) != 2 {
+		t.Fatalf("rebuilt aggregate = %#v", completed.Stages["transcribe"])
+	}
+}
+
+func TestExecuteStagesRepairsSucceededTranscribeAggregateWithoutRequests(t *testing.T) {
+	for _, test := range []struct {
+		name    string
+		mutate  func(*manifest.Manifest)
+		removed bool
+	}{
+		{name: "removed speaker", removed: true, mutate: func(m *manifest.Manifest) {
+			m.Inputs = slices.DeleteFunc(m.Inputs, func(in manifest.InputRecord) bool { return filepath.Base(in.Path) == "bob.flac" })
+		}},
+		{name: "missing output", mutate: func(m *manifest.Manifest) { m.Stages["transcribe"].Outputs = m.Stages["transcribe"].Outputs[:1] }},
+		{name: "duplicate output", mutate: func(m *manifest.Manifest) { m.Stages["transcribe"].Outputs[1] = m.Stages["transcribe"].Outputs[0] }},
+		{name: "wrong path", mutate: func(m *manifest.Manifest) { m.Stages["transcribe"].Outputs[0].LocalPath = "transcripts/raw/other.json" }},
+		{name: "wrong checksum", mutate: func(m *manifest.Manifest) { m.Stages["transcribe"].Outputs[0].Checksum = "obsolete" }},
+		{name: "wrong producer", mutate: func(m *manifest.Manifest) { m.Stages["transcribe"].Outputs[0].ProducerRunID = "other-run" }},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			cfg, store := setupTranscribeRecoveryFixture(t, []string{"alice", "bob"})
+			transcribe := mustSelectStage(t, "transcribe")
+			if _, err := executeStages(context.Background(), cfg, []stage.Stage{transcribe}, RunOptions{
+				Env: &Env{ManifestStore: store, WhisperX: &whisperx.FakeClient{}},
+			}); err != nil {
+				t.Fatal(err)
+			}
+			m := loadTranscribeRecoveryManifest(t, store, cfg)
+			test.mutate(m)
+			m.MarkStageSucceeded("merge", time.Now().UTC(), nil)
+			if err := store.Save(context.Background(), manifestPathFor(cfg), m); err != nil {
+				t.Fatal(err)
+			}
+			retry := &whisperx.FakeClient{}
+			summary, err := executeStages(context.Background(), cfg, []stage.Stage{transcribe}, RunOptions{
+				Env: &Env{ManifestStore: store, WhisperX: retry},
+			})
+			if err != nil {
+				t.Fatal(err)
+			}
+			if len(summary.Skipped) != 0 || len(retry.RequestsSnapshot()) != 0 {
+				t.Fatalf("want aggregate repair without HTTP; summary=%#v requests=%#v", summary, retry.RequestsSnapshot())
+			}
+			completed := loadTranscribeRecoveryManifest(t, store, cfg)
+			want := []string{"alice", "bob"}
+			if test.removed {
+				want = []string{"alice"}
+			}
+			record := completed.Stages["transcribe"]
+			if !slices.Equal(transcribeSpeakerKeys(completed), want) || len(record.Outputs) != len(want) {
+				t.Fatalf("unexpected repaired state: %#v", record)
+			}
+			for _, output := range record.Outputs {
+				speaker := record.TranscribeSpeakers[strings.TrimSuffix(filepath.Base(output.LocalPath), ".json")]
+				if output.Checksum != speaker.Output.Checksum || output.ProducerRunID != speaker.ProducerRunID {
+					t.Fatalf("aggregate evidence does not match checkpoint: %#v", output)
+				}
+			}
+			if completed.Stages["merge"].Status != manifest.StatusStale {
+				t.Fatal("aggregate repair did not stale merge")
+			}
+			if test.removed {
+				paths := artifacts.NewLocalStore(cfg.Pipeline.Workspace.Root).SessionPathsFor(cfg.Session.Campaign, cfg.Session.SessionID)
+				for _, name := range []string{"speakers.yml", "autocorrect.yml"} {
+					if err := os.WriteFile(filepath.Join(paths.InputsDir, name), []byte("{}"), 0o644); err != nil {
+						t.Fatal(err)
+					}
+				}
+				merge := &seriatim.FakeRunner{}
+				if _, err := executeStages(context.Background(), cfg, []stage.Stage{mustSelectStage(t, "merge")}, RunOptions{
+					Env: &Env{ManifestStore: store, Seriatim: merge},
+				}); err != nil {
+					t.Fatal(err)
+				}
+				if len(merge.NormalizeRequests) != 1 || filepath.Base(merge.NormalizeRequests[0].InputTranscriptPath) != "alice.json" {
+					t.Fatalf("removed speaker reached merge: %#v", merge.NormalizeRequests)
+				}
+				if _, err := os.Stat(filepath.Join(paths.TranscriptsRawDir, "bob.json")); err != nil {
+					t.Fatalf("incidental transcript was removed: %v", err)
+				}
+			}
+		})
+	}
+}
+
+func TestExecuteStagesResumesInterruptedRunningTranscribeState(t *testing.T) {
+	cfg, baseStore := setupTranscribeRecoveryFixture(t, []string{"alice", "bob"})
+	concurrency := 1
+	cfg.Pipeline.WhisperX.Concurrency = &concurrency
+	stageErr := errors.New("speaker b failed")
+	terminalErr := errors.New("terminal save interrupted")
+	store := &interruptAfterTranscribeCheckpointStore{Store: baseStore, Err: terminalErr}
+	fake := &whisperx.FakeClient{TranscribeFn: func(
+		_ context.Context,
+		req whisperx.TranscribeRequest,
+	) (whisperx.TranscribeResult, error) {
+		if req.SpeakerID == "bob" {
+			return whisperx.TranscribeResult{}, stageErr
+		}
+		return writeTranscribeRecoveryResult(req)
+	}}
+	transcribe := mustSelectStage(t, "transcribe")
+
+	_, err := executeStages(context.Background(), cfg, []stage.Stage{transcribe}, RunOptions{
+		Env: &Env{ManifestStore: store, WhisperX: fake},
+	})
+	if !errors.Is(err, stageErr) || !errors.Is(err, terminalErr) {
+		t.Fatalf("executeStages() error = %v, want stage and terminal failures", err)
+	}
+	interrupted := loadTranscribeRecoveryManifest(t, baseStore, cfg)
+	if interrupted.Stages["transcribe"].Status != manifest.StatusRunning {
+		t.Fatalf("transcribe status = %q, want durable running state", interrupted.Stages["transcribe"].Status)
+	}
+	if got := transcribeSpeakerKeys(interrupted); !slices.Equal(got, []string{"alice"}) {
+		t.Fatalf("checkpointed speakers = %#v, want alice", got)
+	}
+
+	retry := &whisperx.FakeClient{}
+	if _, err := executeStages(context.Background(), cfg, []stage.Stage{transcribe}, RunOptions{
+		Env: &Env{ManifestStore: baseStore, WhisperX: retry},
+	}); err != nil {
+		t.Fatalf("retry executeStages() error = %v", err)
+	}
+	if got := requestedTranscribeSpeakers(retry); !slices.Equal(got, []string{"bob"}) {
+		t.Fatalf("retry speakers = %#v, want bob", got)
+	}
+}
+
+func TestExecuteStagesPersistsForcedTranscribeResetAcrossRetry(t *testing.T) {
+	cfg, store := setupTranscribeRecoveryFixture(t, []string{"alice", "bob"})
+	concurrency := 1
+	cfg.Pipeline.WhisperX.Concurrency = &concurrency
+	transcribe := mustSelectStage(t, "transcribe")
+	if _, err := executeStages(context.Background(), cfg, []stage.Stage{transcribe}, RunOptions{
+		Env: &Env{ManifestStore: store, WhisperX: &whisperx.FakeClient{}},
+	}); err != nil {
+		t.Fatalf("baseline executeStages() error = %v", err)
+	}
+
+	cause := errors.New("forced bob failed")
+	forced := &whisperx.FakeClient{TranscribeFn: func(
+		_ context.Context,
+		req whisperx.TranscribeRequest,
+	) (whisperx.TranscribeResult, error) {
+		if req.SpeakerID == "bob" {
+			return whisperx.TranscribeResult{}, cause
+		}
+		return writeTranscribeRecoveryResult(req)
+	}}
+	if _, err := executeStages(context.Background(), cfg, []stage.Stage{transcribe}, RunOptions{
+		Force: true,
+		Env:   &Env{ManifestStore: store, WhisperX: forced},
+	}); !errors.Is(err, cause) {
+		t.Fatalf("forced executeStages() error = %v, want %v", err, cause)
+	}
+	failed := loadTranscribeRecoveryManifest(t, store, cfg)
+	if got := transcribeSpeakerKeys(failed); !slices.Equal(got, []string{"alice"}) {
+		t.Fatalf("speakers after forced failure = %#v, want only replacement alice", got)
+	}
+
+	retry := &whisperx.FakeClient{}
+	if _, err := executeStages(context.Background(), cfg, []stage.Stage{transcribe}, RunOptions{
+		Env: &Env{ManifestStore: store, WhisperX: retry},
+	}); err != nil {
+		t.Fatalf("retry executeStages() error = %v", err)
+	}
+	if got := requestedTranscribeSpeakers(retry); !slices.Equal(got, []string{"bob"}) {
+		t.Fatalf("retry speakers = %#v, want bob", got)
+	}
+}
+
+func TestExecuteStagesUpgradesLegacyTranscribeSuccessOnce(t *testing.T) {
+	cfg, store := setupTranscribeRecoveryFixture(t, []string{"alice"})
+	m := loadTranscribeRecoveryManifest(t, store, cfg)
+	m.MarkStageSucceeded("transcribe", time.Now().UTC(), []manifest.ArtifactRecord{{
+		Kind: "transcript_raw", LocalPath: "transcripts/raw/alice.json",
+	}})
+	if err := store.Save(context.Background(), manifestPathFor(cfg), m); err != nil {
+		t.Fatalf("save legacy transcribe success: %v", err)
+	}
+	transcribe := mustSelectStage(t, "transcribe")
+	upgrade := &whisperx.FakeClient{}
+	if _, err := executeStages(context.Background(), cfg, []stage.Stage{transcribe}, RunOptions{
+		Env: &Env{ManifestStore: store, WhisperX: upgrade},
+	}); err != nil {
+		t.Fatalf("upgrade executeStages() error = %v", err)
+	}
+	if got := requestedTranscribeSpeakers(upgrade); !slices.Equal(got, []string{"alice"}) {
+		t.Fatalf("upgrade speakers = %#v, want alice", got)
+	}
+	upgraded := loadTranscribeRecoveryManifest(t, store, cfg)
+	if upgraded.Stages["transcribe"].TranscribeStateVersion != manifest.TranscribeStateContractVersion {
+		t.Fatalf("transcribe state version = %d, want current", upgraded.Stages["transcribe"].TranscribeStateVersion)
+	}
+
+	reused := &whisperx.FakeClient{}
+	summary, err := executeStages(context.Background(), cfg, []stage.Stage{transcribe}, RunOptions{
+		Env: &Env{ManifestStore: store, WhisperX: reused},
+	})
+	if err != nil {
+		t.Fatalf("reuse executeStages() error = %v", err)
+	}
+	if len(summary.Skipped) != 1 || len(reused.RequestsSnapshot()) != 0 {
+		t.Fatalf("reuse summary = %#v, requests = %#v, want skipped without HTTP", summary, reused.RequestsSnapshot())
+	}
+}
+
+type transcribeAggregateSaveFailingStore struct {
+	manifest.Store
+	Err    error
+	Failed bool
+}
+
+func (store *transcribeAggregateSaveFailingStore) Save(
+	ctx context.Context,
+	path string,
+	m *manifest.Manifest,
+) error {
+	record := m.Stages["transcribe"]
+	if !store.Failed && record != nil && record.Status == manifest.StatusSucceeded &&
+		record.TranscribeStateVersion == manifest.TranscribeStateContractVersion {
+		store.Failed = true
+		return store.Err
+	}
+	return store.Store.Save(ctx, path, m)
+}
+
+type interruptAfterTranscribeCheckpointStore struct {
+	manifest.Store
+	Err         error
+	Interrupted bool
+}
+
+func (store *interruptAfterTranscribeCheckpointStore) Save(
+	ctx context.Context,
+	path string,
+	m *manifest.Manifest,
+) error {
+	if store.Interrupted {
+		return store.Err
+	}
+	record := m.Stages["transcribe"]
+	err := store.Store.Save(ctx, path, m)
+	if err == nil && record != nil && record.Status == manifest.StatusRunning && len(record.TranscribeSpeakers) == 1 {
+		store.Interrupted = true
+	}
+	return err
+}
+
+func setupTranscribeRecoveryFixture(t *testing.T, speakers []string) (*config.Config, *manifest.LocalStore) {
+	t.Helper()
+	cfg := testConfig(t)
+	store := &manifest.LocalStore{}
+	artifactStore := artifacts.NewLocalStore(cfg.Pipeline.Workspace.Root)
+	paths, err := artifactStore.EnsureLayoutFor(cfg.Session.Campaign, cfg.Session.SessionID)
+	if err != nil {
+		t.Fatalf("prepare session layout: %v", err)
+	}
+	m := manifest.New(cfg.Session.SessionID, time.Now().UTC())
+	m.Campaign = cfg.Session.Campaign
+	m.Inputs = make([]manifest.InputRecord, 0, len(speakers))
+	for _, speaker := range speakers {
+		relative := filepath.ToSlash(filepath.Join("audio", speaker+".flac"))
+		if err := os.WriteFile(filepath.Join(paths.AudioDir, speaker+".flac"), []byte("audio-"+speaker), 0o644); err != nil {
+			t.Fatalf("write audio fixture: %v", err)
+		}
+		m.Inputs = append(m.Inputs, manifest.InputRecord{Kind: "audio", Path: relative})
+	}
+	m.MarkStageSucceeded("prepare", time.Now().UTC(), nil)
+	m.MarkStageSucceeded("merge", time.Now().UTC(), nil)
+	if err := store.Save(context.Background(), paths.ManifestPath, m); err != nil {
+		t.Fatalf("save recovery fixture: %v", err)
+	}
+	return cfg, store
+}
+
+func writeTranscribeRecoveryResult(req whisperx.TranscribeRequest) (whisperx.TranscribeResult, error) {
+	if err := os.MkdirAll(filepath.Dir(req.OutputRawTranscriptPath), 0o755); err != nil {
+		return whisperx.TranscribeResult{}, err
+	}
+	if err := os.WriteFile(req.OutputRawTranscriptPath, []byte(`{"segments":[]}`), 0o644); err != nil {
+		return whisperx.TranscribeResult{}, err
+	}
+	return whisperx.TranscribeResult{OutputRawTranscriptPath: req.OutputRawTranscriptPath}, nil
+}
+
+func loadTranscribeRecoveryManifest(t *testing.T, store manifest.Store, cfg *config.Config) *manifest.Manifest {
+	t.Helper()
+	m, err := store.Load(context.Background(), manifestPathFor(cfg))
+	if err != nil {
+		t.Fatalf("load transcribe recovery manifest: %v", err)
+	}
+	return m
+}
+
+func transcribeSpeakerKeys(m *manifest.Manifest) []string {
+	keys := make([]string, 0, len(m.Stages["transcribe"].TranscribeSpeakers))
+	for key := range m.Stages["transcribe"].TranscribeSpeakers {
+		keys = append(keys, key)
+	}
+	slices.Sort(keys)
+	return keys
+}
+
+func requestedTranscribeSpeakers(fake *whisperx.FakeClient) []string {
+	requests := fake.RequestsSnapshot()
+	speakers := make([]string, 0, len(requests))
+	for _, request := range requests {
+		speakers = append(speakers, request.SpeakerID)
+	}
+	return speakers
+}

internal/app/whisperx_wiring_test.go

@@ -7,9 +7,12 @@ import (
 	"net/http/httptest"
 	"os"
 	"path/filepath"
+	"slices"
 	"strings"
+	"sync"
 	"sync/atomic"
 	"testing"
+	"time"
 
 	"gitea.maximumdirect.net/eric/narratio/internal/adapters/whisperx"
 	"gitea.maximumdirect.net/eric/narratio/internal/config"
@@ -118,6 +121,86 @@ func TestExecuteStagesDefaultWiringWhisperXFailureMarksManifestFailed(t *testing
 	}
 }
 
+func TestExhaustedWhisperXFailurePreservesEarlierSpeakerCheckpoint(t *testing.T) {
+	var successful atomic.Bool
+	var requestMu sync.Mutex
+	var requested []string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		file, header, err := r.FormFile("file")
+		if err != nil {
+			t.Errorf("FormFile(file) error = %v", err)
+			http.Error(w, "invalid multipart", http.StatusBadRequest)
+			return
+		}
+		_, readErr := io.Copy(io.Discard, file)
+		_ = file.Close()
+		if readErr != nil {
+			t.Errorf("read uploaded file: %v", readErr)
+			return
+		}
+		speaker := strings.TrimSuffix(header.Filename, filepath.Ext(header.Filename))
+		requestMu.Lock()
+		requested = append(requested, speaker)
+		requestMu.Unlock()
+		if speaker == "b" && !successful.Load() {
+			http.Error(w, "temporary", http.StatusInternalServerError)
+			return
+		}
+		_, _ = w.Write([]byte(`{"segments":[]}`))
+	}))
+	defer srv.Close()
+
+	cfg, store := setupTranscribeRecoveryFixture(t, []string{"a", "b", "c"})
+	setWhisperXConfig(cfg, srv.URL, 1)
+	concurrency := 1
+	cfg.Pipeline.WhisperX.Concurrency = &concurrency
+	httpClient, err := whisperx.NewHTTPClient(whisperx.HTTPClientConfig{
+		TranscribeURL: srv.URL,
+		Language:      "en",
+		Timeout:       2 * time.Second,
+		Retries:       1,
+		RetryDelay:    time.Millisecond,
+	})
+	if err != nil {
+		t.Fatalf("NewHTTPClient() error = %v", err)
+	}
+	transcribe := mustSelectStage(t, "transcribe")
+
+	if _, err := executeStages(context.Background(), cfg, []stage.Stage{transcribe}, RunOptions{
+		Env: &Env{ManifestStore: store, WhisperX: httpClient},
+	}); err == nil {
+		t.Fatal("executeStages() error = nil, want exhausted HTTP failure")
+	}
+	failed := loadTranscribeRecoveryManifest(t, store, cfg)
+	if got := transcribeSpeakerKeys(failed); !slices.Equal(got, []string{"a"}) {
+		t.Fatalf("checkpointed speakers = %#v, want a", got)
+	}
+	requestMu.Lock()
+	firstRequests := append([]string(nil), requested...)
+	requested = nil
+	requestMu.Unlock()
+	if !slices.Equal(firstRequests, []string{"a", "b", "b"}) {
+		t.Fatalf("initial HTTP speakers = %#v, want a then two attempts for b", firstRequests)
+	}
+
+	successful.Store(true)
+	if _, err := executeStages(context.Background(), cfg, []stage.Stage{transcribe}, RunOptions{
+		Env: &Env{ManifestStore: store, WhisperX: httpClient},
+	}); err != nil {
+		t.Fatalf("retry executeStages() error = %v", err)
+	}
+	requestMu.Lock()
+	retryRequests := append([]string(nil), requested...)
+	requestMu.Unlock()
+	if !slices.Equal(retryRequests, []string{"b", "c"}) {
+		t.Fatalf("retry HTTP speakers = %#v, want only b and c", retryRequests)
+	}
+	completed := loadTranscribeRecoveryManifest(t, store, cfg)
+	if got := transcribeSpeakerKeys(completed); !slices.Equal(got, []string{"a", "b", "c"}) {
+		t.Fatalf("completed speakers = %#v, want all speakers", got)
+	}
+}
+
 func TestExecuteStagesExplicitWhisperXInjectionOverridesDefaultWiring(t *testing.T) {
 	cfg := testConfig(t)
 	setWhisperXConfig(cfg, "https://127.0.0.1:1/transcribe", 0)

internal/artifacts/paths.go

@@ -10,6 +10,8 @@ import (
 	"gitea.maximumdirect.net/eric/narratio/internal/pathsafe"
 )
 
+const sha256HexLength = 64
+
 // SessionPaths contains canonical local paths for one session work directory.
 type SessionPaths struct {
 	WorkspaceRoot         string
@@ -28,6 +30,7 @@ type SessionPaths struct {
 	CurrentDir            string
 	RunsDir               string
 	PreviousDir           string
+	CacheDir              string
 	PreviousManifestPath  string
 	PreviousArtifactsDir  string
 	ManifestPath          string
@@ -108,17 +111,37 @@ func SessionRunNotariusLogPathForCampaign(rootDir, campaign, sessionID, runID st
 	return filepath.Join(SessionRunExtractDirForCampaign(rootDir, campaign, sessionID, runID), "notarius.stderr.log")
 }
 
-// SessionRunNotariusReferencesDirForCampaign returns the invocation-local
-// directory containing verified reference snapshots supplied to Notarius.
-func SessionRunNotariusReferencesDirForCampaign(rootDir, campaign, sessionID, runID string) string {
-	return filepath.Join(SessionRunExtractDirForCampaign(rootDir, campaign, sessionID, runID), "references")
-}
-
 // SessionRunNotariusOutputRootForCampaign returns the invocation-local Notarius output root.
 func SessionRunNotariusOutputRootForCampaign(rootDir, campaign, sessionID, runID string) string {
 	return filepath.Join(SessionRunExtractDirForCampaign(rootDir, campaign, sessionID, runID), "notarius-output")
 }
 
+// SessionNotariusReferenceCacheDir returns the stable cache root for verified
+// reference snapshots supplied to Notarius.
+func SessionNotariusReferenceCacheDir(paths SessionPaths) string {
+	return filepath.Join(paths.CacheDir, "notarius", "references")
+}
+
+// SessionNotariusReferenceSnapshotPath returns the content-addressed path for
+// one verified prepared reference snapshot.
+func SessionNotariusReferenceSnapshotPath(paths SessionPaths, checksum, preparedBasename string) (string, error) {
+	if len(checksum) != sha256HexLength {
+		return "", fmt.Errorf("reference checksum must be a full lowercase SHA-256 digest")
+	}
+	for _, character := range checksum {
+		if (character < '0' || character > '9') && (character < 'a' || character > 'f') {
+			return "", fmt.Errorf("reference checksum must be a full lowercase SHA-256 digest")
+		}
+	}
+	if err := pathsafe.ValidateOpaqueSegment(preparedBasename); err != nil {
+		return "", fmt.Errorf("prepared reference basename: %w", err)
+	}
+	return pathsafe.JoinSlashRelativeUnderRoot(
+		SessionNotariusReferenceCacheDir(paths),
+		checksum+"/"+preparedBasename,
+	)
+}
+
 // SessionNotariusBundleDirForCampaign returns one immutable durable bundle destination.
 func SessionNotariusBundleDirForCampaign(rootDir, campaign, sessionID, runID string) string {
 	return filepath.Join(
@@ -268,6 +291,7 @@ func buildSessionPathsFromRoot(workspaceRoot, campaign, sessionID, root string)
 		CurrentDir:            filepath.Join(root, config.PathCurrentDirSegment),
 		RunsDir:               filepath.Join(root, config.PathRunsDirSegment),
 		PreviousDir:           filepath.Join(root, config.PathPreviousDirSegment),
+		CacheDir:              filepath.Join(root, config.PathCacheDirSegment),
 		PreviousManifestPath:  filepath.Join(root, config.PathPreviousDirSegment, config.PathManifestFile),
 		PreviousArtifactsDir:  filepath.Join(root, config.PathPreviousDirSegment, config.PathArtifactsDirSegment),
 		ManifestPath:          filepath.Join(root, config.PathManifestFile),

internal/artifacts/paths_model_test.go

@@ -2,6 +2,7 @@ package artifacts
 
 import (
 	"path/filepath"
+	"strings"
 	"testing"
 )
 
@@ -54,7 +55,6 @@ func TestSessionNotariusPathsForCampaign(t *testing.T) {
 		{name: "extract directory", got: SessionRunExtractDirForCampaign(root, campaign, sessionID, runID), want: extractDir},
 		{name: "receipt", got: SessionRunNotariusReceiptPathForCampaign(root, campaign, sessionID, runID), want: filepath.Join(extractDir, "notarius.receipt.json")},
 		{name: "stderr", got: SessionRunNotariusLogPathForCampaign(root, campaign, sessionID, runID), want: filepath.Join(extractDir, "notarius.stderr.log")},
-		{name: "references", got: SessionRunNotariusReferencesDirForCampaign(root, campaign, sessionID, runID), want: filepath.Join(extractDir, "references")},
 		{name: "output root", got: SessionRunNotariusOutputRootForCampaign(root, campaign, sessionID, runID), want: filepath.Join(extractDir, "notarius-output")},
 		{name: "durable bundle", got: SessionNotariusBundleDirForCampaign(root, campaign, sessionID, runID), want: filepath.Join(root, "work", campaign, sessionID, "artifacts", "notarius", runID)},
 	}
@@ -67,6 +67,43 @@ func TestSessionNotariusPathsForCampaign(t *testing.T) {
 	}
 }
 
+func TestSessionNotariusReferenceSnapshotPath(t *testing.T) {
+	paths := buildSessionPaths("/tmp/workspace", "forsaken", "2026-04-19")
+	checksum := strings.Repeat("a", 64)
+	got, err := SessionNotariusReferenceSnapshotPath(paths, checksum, "party.yml")
+	if err != nil {
+		t.Fatalf("SessionNotariusReferenceSnapshotPath() error = %v", err)
+	}
+	wantRoot := filepath.Join(paths.Root, "cache", "notarius", "references")
+	if root := SessionNotariusReferenceCacheDir(paths); root != wantRoot {
+		t.Fatalf("SessionNotariusReferenceCacheDir() = %q, want %q", root, wantRoot)
+	}
+	if want := filepath.Join(wantRoot, checksum, "party.yml"); got != want {
+		t.Fatalf("SessionNotariusReferenceSnapshotPath() = %q, want %q", got, want)
+	}
+}
+
+func TestSessionNotariusReferenceSnapshotPathRejectsUnsafeIdentity(t *testing.T) {
+	paths := buildSessionPaths("/tmp/workspace", "forsaken", "2026-04-19")
+	validChecksum := strings.Repeat("a", 64)
+	for _, test := range []struct {
+		name, checksum, basename string
+	}{
+		{name: "short digest", checksum: "abc", basename: "party.yml"},
+		{name: "uppercase digest", checksum: strings.Repeat("A", 64), basename: "party.yml"},
+		{name: "nonhex digest", checksum: strings.Repeat("g", 64), basename: "party.yml"},
+		{name: "empty basename", checksum: validChecksum},
+		{name: "nested basename", checksum: validChecksum, basename: "nested/party.yml"},
+		{name: "parent basename", checksum: validChecksum, basename: ".."},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			if got, err := SessionNotariusReferenceSnapshotPath(paths, test.checksum, test.basename); err == nil {
+				t.Fatalf("SessionNotariusReferenceSnapshotPath() = %q, want error", got)
+			}
+		})
+	}
+}
+
 func TestSessionPreviousPathsForCampaign(t *testing.T) {
 	root := "/tmp/workspace"
 	previousDir := SessionPreviousDirForCampaign(root, "forsaken", "2026-04-19")

internal/config/config.go

@@ -309,6 +309,10 @@ type ScriptoriumInputConfig struct {
 type NotariusConfig struct {
 	Enabled          bool                            `yaml:"enabled" json:"enabled"`
 	Binary           string                          `yaml:"binary" json:"binary"`
+	LLMAPIKey        *configkit.Secret               `yaml:"llm_api_key,omitempty" json:"llm_api_key,omitempty"`
+	ConfigProfile    *string                         `yaml:"config_profile,omitempty" json:"config_profile,omitempty"`
+	Resume           bool                            `yaml:"resume,omitempty" json:"resume,omitempty"`
+	ChunkCache       string                          `yaml:"chunk_cache,omitempty" json:"chunk_cache,omitempty"`
 	ConfigPath       string                          `yaml:"config_path" json:"config_path"`
 	PipelineID       string                          `yaml:"pipeline_id" json:"pipeline_id"`
 	Timeout          string                          `yaml:"timeout" json:"timeout"`

internal/config/credential_projection.go

@@ -50,6 +50,31 @@ func (cfg AuditaConfig) MarshalYAML() (any, error) {
 	}, nil
 }
 
+// MarshalYAML exposes only the public Notarius credential reference name.
+func (cfg NotariusConfig) MarshalYAML() (any, error) {
+	type safeNotarius struct {
+		Enabled          bool                            `yaml:"enabled"`
+		Binary           string                          `yaml:"binary"`
+		LLMAPIKey        *string                         `yaml:"llm_api_key,omitempty"`
+		ConfigProfile    *string                         `yaml:"config_profile,omitempty"`
+		Resume           bool                            `yaml:"resume,omitempty"`
+		ChunkCache       string                          `yaml:"chunk_cache,omitempty"`
+		ConfigPath       string                          `yaml:"config_path"`
+		PipelineID       string                          `yaml:"pipeline_id"`
+		Timeout          string                          `yaml:"timeout"`
+		WorkingDirectory string                          `yaml:"working_directory"`
+		References       map[string]string               `yaml:"references"`
+		Outputs          map[string]NotariusOutputConfig `yaml:"outputs"`
+	}
+	return safeNotarius{
+		Enabled: cfg.Enabled, Binary: cfg.Binary, LLMAPIKey: secretReferenceName(cfg.LLMAPIKey),
+		ConfigProfile: cfg.ConfigProfile,
+		Resume:        cfg.Resume, ChunkCache: cfg.ChunkCache,
+		ConfigPath: cfg.ConfigPath, PipelineID: cfg.PipelineID, Timeout: cfg.Timeout,
+		WorkingDirectory: cfg.WorkingDirectory, References: cfg.References, Outputs: cfg.Outputs,
+	}, nil
+}
+
 func secretReferenceName(secret *configkit.Secret) *string {
 	if secret == nil {
 		return nil

internal/config/defaults.go

@@ -78,6 +78,7 @@ const (
 	PathCurrentDirSegment      = "current"
 	PathRunsDirSegment         = "runs"
 	PathPreviousDirSegment     = "previous"
+	PathCacheDirSegment        = "cache"
 	PathManifestFile           = "manifest.json"
 	PathLockFile               = ".lock"
 	PathTranscriptBase         = artifactmodel.TranscriptPathBase

internal/config/load_validate_test.go

@@ -92,6 +92,7 @@ func TestCredentialValuesNeverEnterEffectiveProjectionOrDigest(t *testing.T) {
 	t.Setenv("NARRATIO_TEST_ACCESS_KEY", firstCanary)
 	t.Setenv("NARRATIO_TEST_SECRET_KEY", firstCanary)
 	t.Setenv("NARRATIO_TEST_AUDITA_KEY", firstCanary)
+	t.Setenv("NARRATIO_TEST_NOTARIUS_KEY", firstCanary)
 	pipelineYAML := strings.Replace(testPipelineBaseYAML, "audita:\n  binary: audita\n", "audita:\n  binary: audita\n  llm_api_key: NARRATIO_TEST_AUDITA_KEY\n", 1) + `
 storage:
   backend: s3
@@ -99,6 +100,10 @@ storage:
     bucket: test-bucket
     access_key_id: NARRATIO_TEST_ACCESS_KEY
     secret_access_key: NARRATIO_TEST_SECRET_KEY
+notarius:
+  enabled: false
+  llm_api_key: NARRATIO_TEST_NOTARIUS_KEY
+  config_profile: ""
 `
 	pipelinePath, _ := writeConfigFiles(t, pipelineYAML, testSessionBaseYAML)
 
@@ -130,16 +135,35 @@ storage:
 		if strings.Contains(output, firstCanary) {
 			t.Fatalf("effective output exposed credential value: %q", output)
 		}
-		for _, reference := range []string{"NARRATIO_TEST_ACCESS_KEY", "NARRATIO_TEST_SECRET_KEY", "NARRATIO_TEST_AUDITA_KEY"} {
+		for _, reference := range []string{"NARRATIO_TEST_ACCESS_KEY", "NARRATIO_TEST_SECRET_KEY", "NARRATIO_TEST_AUDITA_KEY", "NARRATIO_TEST_NOTARIUS_KEY"} {
 			if !strings.Contains(output, reference) {
 				t.Fatalf("effective output omitted safe reference %q: %q", reference, output)
 			}
 		}
 	}
+	if !strings.Contains(string(firstYAML), "config_profile: \"\"\n") {
+		t.Fatalf("effective YAML omitted explicit empty Notarius config profile: %q", firstYAML)
+	}
+	var roundTrip struct {
+		Notarius *struct {
+			LLMAPIKey     *string `yaml:"llm_api_key"`
+			ConfigProfile *string `yaml:"config_profile"`
+		} `yaml:"notarius"`
+	}
+	if err := yaml.Unmarshal(firstYAML, &roundTrip); err != nil {
+		t.Fatalf("round-trip effective YAML: %v", err)
+	}
+	if roundTrip.Notarius == nil || roundTrip.Notarius.ConfigProfile == nil || *roundTrip.Notarius.ConfigProfile != "" {
+		t.Fatalf("round-trip config profile = %#v, want explicit empty", roundTrip.Notarius)
+	}
+	if roundTrip.Notarius.LLMAPIKey == nil || *roundTrip.Notarius.LLMAPIKey != "NARRATIO_TEST_NOTARIUS_KEY" {
+		t.Fatalf("round-trip credential reference = %#v, want safe public name", roundTrip.Notarius.LLMAPIKey)
+	}
 
 	t.Setenv("NARRATIO_TEST_ACCESS_KEY", secondCanary)
 	t.Setenv("NARRATIO_TEST_SECRET_KEY", secondCanary)
 	t.Setenv("NARRATIO_TEST_AUDITA_KEY", secondCanary)
+	t.Setenv("NARRATIO_TEST_NOTARIUS_KEY", secondCanary)
 	second, err := LoadPipeline(pipelinePath)
 	if err != nil {
 		t.Fatal(err)
@@ -156,6 +180,15 @@ storage:
 	if EffectivePipelineDigest(first) == EffectivePipelineDigest(alternate) {
 		t.Fatal("credential reference-name change did not alter effective digest")
 	}
+	t.Setenv("NARRATIO_TEST_NOTARIUS_KEY_ALTERNATE", secondCanary)
+	alternateNotariusPath, _ := writeConfigFiles(t, strings.Replace(pipelineYAML, "NARRATIO_TEST_NOTARIUS_KEY", "NARRATIO_TEST_NOTARIUS_KEY_ALTERNATE", 1), testSessionBaseYAML)
+	alternateNotarius, err := LoadPipeline(alternateNotariusPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if EffectivePipelineDigest(first) == EffectivePipelineDigest(alternateNotarius) {
+		t.Fatal("Notarius credential reference-name change did not alter effective digest")
+	}
 }
 
 func TestEffectivePipelineValuesPreserveNilEmptyAndExactIntegers(t *testing.T) {
@@ -252,6 +285,7 @@ func TestExamplesLoadAndValidate(t *testing.T) {
 	t.Setenv("OBJECT_STORAGE_KEY_ID", "synthetic-example-access-key")
 	t.Setenv("OBJECT_STORAGE_KEY", "synthetic-example-secret-key")
 	t.Setenv("AUDITA_LLM_API_KEY", "synthetic-example-audita-key")
+	t.Setenv("NOTARIUS_LLM_API_KEY", "synthetic-example-notarius-key")
 	examplesDir := filepath.Join("..", "..", "examples")
 	if got, want := maintainedPipelineRoots(t, examplesDir), []string{
 		"pipeline.extraction-subset.yml",
@@ -439,6 +473,7 @@ func TestMaintainedExtractionExamplesPreservePublishedContracts(t *testing.T) {
 	t.Setenv("OBJECT_STORAGE_KEY_ID", "synthetic-example-access-key")
 	t.Setenv("OBJECT_STORAGE_KEY", "synthetic-example-secret-key")
 	t.Setenv("AUDITA_LLM_API_KEY", "synthetic-example-audita-key")
+	t.Setenv("NOTARIUS_LLM_API_KEY", "synthetic-example-notarius-key")
 	examplesDir := filepath.Join("..", "..", "examples")
 	full, err := LoadPipeline(filepath.Join(examplesDir, "pipeline.full.annotated.yml"))
 	if err != nil {

internal/config/notarius_test.go

@@ -1,12 +1,15 @@
 package config
 
 import (
+	"encoding/json"
 	"fmt"
 	"os"
 	"path/filepath"
 	"reflect"
 	"strings"
 	"testing"
+
+	"gopkg.in/yaml.v3"
 )
 
 func TestNotariusOmittedAndDisabledBehavior(t *testing.T) {
@@ -45,11 +48,80 @@ notarius:
 	if disabled.Notarius.Binary != DefaultNotariusBinary || disabled.Notarius.Timeout != DefaultNotariusTimeout {
 		t.Fatalf("disabled defaults = %#v", disabled.Notarius)
 	}
+	if disabled.Notarius.Resume || disabled.Notarius.ChunkCache != "" {
+		t.Fatalf("disabled cache-control defaults = %#v", disabled.Notarius)
+	}
 	if disabled.Notarius.ConfigPath != "relative/notarius.yml" || disabled.Notarius.WorkingDirectory != "" {
 		t.Fatalf("disabled paths were resolved unexpectedly: %#v", disabled.Notarius)
 	}
 }
 
+func TestNotariusCredentialReferenceLoading(t *testing.T) {
+	const envName = "NARRATIO_TEST_NOTARIUS_KEY"
+	const canary = "notarius-credential-canary"
+	t.Setenv(envName, canary)
+
+	tests := []struct {
+		name       string
+		credential string
+		wantNil    bool
+	}{
+		{name: "omitted", wantNil: true},
+		{name: "null", credential: "  llm_api_key: null\n", wantNil: true},
+		{name: "custom reference", credential: "  llm_api_key: " + envName + "\n"},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			path := filepath.Join(t.TempDir(), "pipeline.yml")
+			pipelineYAML := testPipelineBaseYAML + "\nnotarius:\n  enabled: false\n" + test.credential
+			if err := os.WriteFile(path, []byte(pipelineYAML), 0o644); err != nil {
+				t.Fatal(err)
+			}
+			cfg, err := LoadPipeline(path)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if test.wantNil {
+				if cfg.Notarius.LLMAPIKey != nil {
+					t.Fatal("credential reference should be nil")
+				}
+				return
+			}
+			if cfg.Notarius.LLMAPIKey == nil || cfg.Notarius.LLMAPIKey.EnvName() != envName ||
+				!cfg.Notarius.LLMAPIKey.IsResolved() || cfg.Notarius.LLMAPIKey.Value() != canary {
+				t.Fatal("credential reference was not loaded and resolved")
+			}
+		})
+	}
+}
+
+func TestNotariusCredentialReferenceFailures(t *testing.T) {
+	const missing = "NARRATIO_TEST_NOTARIUS_MISSING"
+	if err := os.Unsetenv(missing); err != nil {
+		t.Fatal(err)
+	}
+	tests := []struct {
+		name, reference, want string
+	}{
+		{name: "missing", reference: missing, want: "secret.unset"},
+		{name: "empty", reference: `""`, want: "secret.invalid_name"},
+		{name: "invalid", reference: "123-NOT-AN-ENV-NAME", want: "secret.invalid_name"},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			path := filepath.Join(t.TempDir(), "pipeline.yml")
+			pipelineYAML := testPipelineBaseYAML + "\nnotarius:\n  enabled: false\n  llm_api_key: " + test.reference + "\n"
+			if err := os.WriteFile(path, []byte(pipelineYAML), 0o644); err != nil {
+				t.Fatal(err)
+			}
+			_, err := LoadPipeline(path)
+			if err == nil || !strings.Contains(err.Error(), test.want) {
+				t.Fatalf("LoadPipeline() error = %v, want classification %q", err, test.want)
+			}
+		})
+	}
+}
+
 func TestNotariusEnabledDefaultsAndPathResolution(t *testing.T) {
 	dir := t.TempDir()
 	pipelinePath := filepath.Join(dir, "deployment", "pipeline.yml")
@@ -121,6 +193,89 @@ notarius:
 	}
 }
 
+func TestNotariusCacheControlNormalizationAndValidation(t *testing.T) {
+	for _, mode := range []string{"", "auto", "bypass", "refresh"} {
+		t.Run("mode "+mode, func(t *testing.T) {
+			cfg := validNotariusConfig()
+			cfg.Resume = true
+			if mode != "" {
+				cfg.ChunkCache = "  " + mode + "  "
+			}
+			if err := NormalizePipelineConfig(&PipelineConfig{Notarius: cfg}); err != nil {
+				t.Fatalf("NormalizePipelineConfig() error = %v", err)
+			}
+			if cfg.ChunkCache != mode {
+				t.Fatalf("ChunkCache = %q, want %q", cfg.ChunkCache, mode)
+			}
+			if !cfg.Resume {
+				t.Fatal("Resume = false, want true")
+			}
+			if err := validateNotarius(cfg, nil); err != nil {
+				t.Fatalf("validateNotarius() error = %v", err)
+			}
+		})
+	}
+
+	for _, mode := range []string{"AUTO", "invalid"} {
+		t.Run("invalid "+mode, func(t *testing.T) {
+			cfg := validNotariusConfig()
+			cfg.ChunkCache = mode
+			err := validateNotarius(cfg, nil)
+			if err == nil || !strings.Contains(err.Error(), "pipeline.notarius.chunk_cache") {
+				t.Fatalf("validateNotarius() error = %v, want chunk_cache error", err)
+			}
+		})
+	}
+
+	disabled := &NotariusConfig{Enabled: false, Resume: true, ChunkCache: " INVALID "}
+	if err := NormalizePipelineConfig(&PipelineConfig{Notarius: disabled}); err != nil {
+		t.Fatalf("NormalizePipelineConfig(disabled) error = %v", err)
+	}
+	if disabled.ChunkCache != " INVALID " {
+		t.Fatalf("disabled ChunkCache = %q, want unchanged", disabled.ChunkCache)
+	}
+	if err := validateNotarius(disabled, nil); err != nil {
+		t.Fatalf("validateNotarius(disabled) error = %v", err)
+	}
+}
+
+func TestNotariusCacheControlsSafeSerialization(t *testing.T) {
+	cfg := validNotariusConfig()
+	cfg.Resume = true
+	cfg.ChunkCache = "refresh"
+
+	yamlData, err := yaml.Marshal(cfg)
+	if err != nil {
+		t.Fatal(err)
+	}
+	jsonData, err := json.Marshal(cfg)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(yamlData), "resume: true") || !strings.Contains(string(yamlData), "chunk_cache: refresh") {
+		t.Fatalf("YAML omitted cache controls: %s", yamlData)
+	}
+	if !strings.Contains(string(jsonData), `"resume":true`) || !strings.Contains(string(jsonData), `"chunk_cache":"refresh"`) {
+		t.Fatalf("JSON omitted cache controls: %s", jsonData)
+	}
+
+	cfg.Resume = false
+	cfg.ChunkCache = ""
+	yamlData, err = yaml.Marshal(cfg)
+	if err != nil {
+		t.Fatal(err)
+	}
+	jsonData, err = json.Marshal(cfg)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, serialized := range []string{string(yamlData), string(jsonData)} {
+		if strings.Contains(serialized, "resume") || strings.Contains(serialized, "chunk_cache") {
+			t.Fatalf("zero-value cache controls were serialized: %s", serialized)
+		}
+	}
+}
+
 func TestNotariusRelativePathsDoNotMakeEffectiveDigestLocationDependent(t *testing.T) {
 	pipelineYAML := testPipelineBaseYAML + `
 notarius:

internal/config/party_test.go

@@ -60,7 +60,8 @@ characters:
 		want string
 	}{
 		{name: "unsupported version", yaml: strings.Replace(valid, PartySchemaVersion, "narratio.party.v2", 1), want: "unsupported"},
-		{name: "non-string version", yaml: strings.Replace(valid, PartySchemaVersion, "1", 1), want: "version.type"},
+		{name: "unsupported integer version", yaml: strings.Replace(valid, PartySchemaVersion, "1", 1), want: "unsupported"},
+		{name: "boolean version", yaml: strings.Replace(valid, PartySchemaVersion, "true", 1), want: "version.type"},
 		{name: "unknown top field", yaml: valid + "unknown: true\n", want: "decode.unknown_field"},
 		{name: "unknown nested field", yaml: strings.Replace(valid, "      name: Eric\n", "      name: Eric\n      role: GM\n", 1), want: "decode.unknown_field"},
 		{name: "trailing document", yaml: valid + "---\ncharacters: {}\n", want: "yaml.multiple_documents"},

internal/config/pipeline_configkit.go

@@ -209,11 +209,17 @@ func resolvePipelineConfig(cfg *PipelineConfig, resolution *configkit.Resolution
 		resolution.Record(configkit.Keys("notarius"), configkit.ChangeNormalization, "canonical Notarius configuration")
 	}
 	if cfg.Publish != nil {
-		for _, derived := range deriveMissingPublishDestinations(cfg.Publish, cfg.Scriptorium, cfg.Notarius) {
+		destinations := deriveMissingPublishDestinations(cfg.Publish, cfg.Scriptorium, cfg.Notarius)
+		for _, derived := range destinations {
 			output := cfg.Publish.Outputs[derived.index]
 			configkit.Normalize(resolution, configkit.Keys("publish", "outputs").Index(derived.index).Key("dest"), &output.Dest, derived.dest, "derived from publish source")
 			cfg.Publish.Outputs[derived.index] = output
 		}
+		if len(destinations) > 0 {
+			// ConfigKit compares sequences atomically; child records alone do not
+			// cover the list mutation when requiredness was already explicit.
+			resolution.Record(configkit.Keys("publish", "outputs"), configkit.ChangeNormalization, "derived publish destinations")
+		}
 	}
 	return nil
 }

internal/config/pipeline_configkit_test.go

@@ -3,6 +3,7 @@ package config
 import (
 	"os"
 	"path/filepath"
+	"reflect"
 	"strings"
 	"testing"
 )
@@ -117,6 +118,161 @@ func TestPipelineProfileDoesNotRequireUnusedBaseCredentials(t *testing.T) {
 	}
 }
 
+func TestNotariusCredentialProfileReplacementAndProvenance(t *testing.T) {
+	const baseKey = "NARRATIO_NOTARIUS_UNUSED_BASE_KEY"
+	const profileKey = "NARRATIO_NOTARIUS_PROFILE_KEY"
+	if err := os.Unsetenv(baseKey); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv(profileKey, "synthetic-notarius-profile-key")
+
+	for _, credential := range []string{profileKey, "null"} {
+		t.Run(credential, func(t *testing.T) {
+			dir := t.TempDir()
+			root := writePipelineFixture(t, dir, "pipeline.yml", "whisperx:\n  transcribe_url: https://transcription.example.test/transcribe\nnotarius:\n  enabled: false\n  llm_api_key: "+baseKey+"\n")
+			overlay := writePipelineFixture(t, dir, "profiles/testing.yml", "notarius:\n  llm_api_key: "+credential+"\n")
+			profile := "testing"
+			cfg, err := LoadPipelineWithOptions(root, PipelineLoadOptions{Profile: &profile})
+			if err != nil {
+				t.Fatal(err)
+			}
+			if credential == "null" {
+				if cfg.Notarius.LLMAPIKey != nil {
+					t.Fatal("profile did not remove the base credential")
+				}
+				return
+			}
+			if cfg.Notarius.LLMAPIKey == nil || cfg.Notarius.LLMAPIKey.EnvName() != profileKey || !cfg.Notarius.LLMAPIKey.IsResolved() {
+				t.Fatal("profile credential was not resolved")
+			}
+			sources, err := EffectivePipelineSources(cfg, ResolvedParty{})
+			if err != nil {
+				t.Fatal(err)
+			}
+			found := false
+			for _, source := range sources {
+				if source.Path == "notarius.llm_api_key" {
+					found = source.Source == overlay
+				}
+			}
+			if !found {
+				t.Fatal("Notarius credential provenance did not identify the selected profile")
+			}
+		})
+	}
+}
+
+func TestNotariusConfigProfileComposition(t *testing.T) {
+	tests := []struct {
+		name        string
+		baseValue   string
+		overlayName string
+		overlay     string
+		want        *string
+	}{
+		{name: "omitted"},
+		{name: "explicit empty", baseValue: `""`, want: stringPointer("")},
+		{name: "explicit default", baseValue: "default", want: stringPointer("default")},
+		{name: "base named selection", baseValue: "production", want: stringPointer("production")},
+		{name: "profile replaces named selection", baseValue: "production", overlayName: "testing", overlay: "notarius:\n  config_profile: inexpensive\n", want: stringPointer("inexpensive")},
+		{name: "profile clears named selection", baseValue: "production", overlayName: "testing", overlay: "notarius:\n  config_profile: null\n"},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			dir := t.TempDir()
+			rootYAML := "whisperx:\n  transcribe_url: https://transcription.example.test/transcribe\nnotarius:\n  enabled: false\n"
+			if test.baseValue != "" {
+				rootYAML += "  config_profile: " + test.baseValue + "\n"
+			}
+			root := writePipelineFixture(t, dir, "pipeline.yml", rootYAML)
+			options := PipelineLoadOptions{}
+			if test.overlayName != "" {
+				writePipelineFixture(t, dir, "profiles/"+test.overlayName+".yml", test.overlay)
+				options.Profile = &test.overlayName
+			}
+			cfg, err := LoadPipelineWithOptions(root, options)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if cfg.Notarius == nil || !reflect.DeepEqual(cfg.Notarius.ConfigProfile, test.want) {
+				t.Fatalf("config profile = %#v, want %#v", cfg.Notarius.ConfigProfile, test.want)
+			}
+		})
+	}
+}
+
+func TestNotariusCredentialRootProvenance(t *testing.T) {
+	const envName = "NARRATIO_NOTARIUS_ROOT_KEY"
+	t.Setenv(envName, "synthetic-notarius-root-key")
+	dir := t.TempDir()
+	root := writePipelineFixture(t, dir, "pipeline.yml", "whisperx:\n  transcribe_url: https://transcription.example.test/transcribe\nnotarius:\n  enabled: false\n  llm_api_key: "+envName+"\n")
+	cfg, err := LoadPipeline(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	sources, err := EffectivePipelineSources(cfg, ResolvedParty{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, source := range sources {
+		if source.Path == "notarius.llm_api_key" && source.Source == root {
+			return
+		}
+	}
+	t.Fatal("Notarius credential provenance did not identify the root pipeline")
+}
+
+func TestNotariusCacheControlProfileReplacementAndNullReset(t *testing.T) {
+	tests := []struct {
+		name       string
+		overlay    string
+		wantResume bool
+		wantMode   string
+		wantSource bool
+		wantNil    bool
+	}{
+		{name: "replacement", overlay: "notarius:\n  resume: true\n  chunk_cache: refresh\n", wantResume: true, wantMode: "refresh", wantSource: true},
+		{name: "null reset", overlay: "notarius: null\n", wantNil: true},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			dir := t.TempDir()
+			root := writePipelineFixture(t, dir, "pipeline.yml", "whisperx:\n  transcribe_url: https://transcription.example.test/transcribe\nnotarius:\n  enabled: false\n  resume: false\n  chunk_cache: bypass\n")
+			overlay := writePipelineFixture(t, dir, "profiles/testing.yml", test.overlay)
+			profile := "testing"
+			cfg, err := LoadPipelineWithOptions(root, PipelineLoadOptions{Profile: &profile})
+			if err != nil {
+				t.Fatal(err)
+			}
+			if test.wantNil {
+				if cfg.Notarius != nil {
+					t.Fatalf("Notarius = %#v, want null reset", cfg.Notarius)
+				}
+				return
+			}
+			if cfg.Notarius == nil || cfg.Notarius.Resume != test.wantResume || cfg.Notarius.ChunkCache != test.wantMode {
+				t.Fatalf("cache controls = resume %v, mode %q; want resume %v, mode %q", cfg.Notarius.Resume, cfg.Notarius.ChunkCache, test.wantResume, test.wantMode)
+			}
+			if !test.wantSource {
+				return
+			}
+			sources, err := EffectivePipelineSources(cfg, ResolvedParty{})
+			if err != nil {
+				t.Fatal(err)
+			}
+			found := map[string]bool{}
+			for _, source := range sources {
+				if source.Path == "notarius.resume" || source.Path == "notarius.chunk_cache" {
+					found[source.Path] = source.Source == overlay
+				}
+			}
+			if !found["notarius.resume"] || !found["notarius.chunk_cache"] {
+				t.Fatalf("cache-control provenance did not identify profile: %#v", found)
+			}
+		})
+	}
+}
+
 func TestPipelineConfigKitAllowsOneBaseDeclarationWithProfileOverride(t *testing.T) {
 	dir := t.TempDir()
 	writePipelineFixture(t, dir, "pipeline.yml", `configkit:

internal/config/pipeline_normalize.go

@@ -14,6 +14,7 @@ func NormalizePipelineConfig(cfg *PipelineConfig) error {
 	}
 	notarius := *cfg.Notarius
 	notarius.Binary = strings.TrimSpace(notarius.Binary)
+	notarius.ChunkCache = strings.TrimSpace(notarius.ChunkCache)
 	notarius.ConfigPath = cleanNotariusPath(notarius.ConfigPath)
 	notarius.PipelineID = strings.TrimSpace(notarius.PipelineID)
 	notarius.Timeout = strings.TrimSpace(notarius.Timeout)

internal/config/storage_publish_test.go

@@ -3,6 +3,8 @@ package config
 import (
 	"strings"
 	"testing"
+
+	"gopkg.in/yaml.v3"
 )
 
 func TestStorageS3DefaultsAndValidation(t *testing.T) {
@@ -549,6 +551,52 @@ publish:
 	}
 }
 
+func TestPublishDerivedDestinationsPreserveExplicitRequiredness(t *testing.T) {
+	pipelinePath, sessionPath := writeConfigFiles(t, testPipelineBaseYAML+`
+scriptorium:
+  artifacts:
+    session_recap:
+      enabled: true
+      prompt_id: dnd.session_recap
+      output_path: artifacts/session_recap.md
+publish:
+  outputs:
+    - {source: narratio.transcript.final, required: true}
+    - {source: narratio.transcript.final_markdown, required: false}
+    - {source: narratio.artifact.session_recap, required: false}
+    - {source: narratio.transcript.final_trimmed, dest: custom/trimmed.json, required: true}
+`, testSessionBaseYAML)
+	cfg, err := Load(pipelinePath, sessionPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := Validate(cfg); err != nil {
+		t.Fatal(err)
+	}
+	effective, err := MarshalEffectivePipeline(cfg.Pipeline)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var projected struct {
+		Publish PublishConfig `yaml:"publish"`
+	}
+	if err := yaml.Unmarshal(effective, &projected); err != nil {
+		t.Fatal(err)
+	}
+	wantDest := []string{"transcripts/final.json", "transcripts/final.md", "artifacts/session_recap.md", "custom/trimmed.json"}
+	wantRequired := []bool{true, false, false, true}
+	for label, publish := range map[string]*PublishConfig{"loaded": cfg.Pipeline.Publish, "effective": &projected.Publish} {
+		if len(publish.Outputs) != len(wantDest) {
+			t.Fatalf("%s output count = %d, want %d", label, len(publish.Outputs), len(wantDest))
+		}
+		for i, output := range publish.Outputs {
+			if output.Dest != wantDest[i] || output.Required == nil || *output.Required != wantRequired[i] {
+				t.Errorf("%s output %d = %#v, want destination %q and required %t", label, i, output, wantDest[i], wantRequired[i])
+			}
+		}
+	}
+}
+
 func TestScriptoriumOutputPathsIgnoreInvalidKeys(t *testing.T) {
 	scriptorium := &ScriptoriumConfig{Artifacts: map[string]ScriptoriumArtifactConfig{
 		" artifact": {OutputPath: "artifacts/invalid.md"},

internal/config/validate_notarius.go

@@ -39,10 +39,12 @@ func validateNotarius(cfg *NotariusConfig, scriptorium *ScriptoriumConfig) error
 	if len(cfg.References) > MaxNotariusReferenceBindings {
 		return fmt.Errorf("pipeline.notarius.references must contain at most %d bindings", MaxNotariusReferenceBindings)
 	}
-
 	if err := validateNotariusCanonicalScalars(cfg); err != nil {
 		return err
 	}
+	if !validNotariusChunkCacheMode(cfg.ChunkCache) {
+		return fmt.Errorf("pipeline.notarius.chunk_cache must be empty, auto, bypass, or refresh")
+	}
 	if err := validateNotariusReferences(cfg.References); err != nil {
 		return err
 	}
@@ -56,6 +58,7 @@ func validateNotariusCanonicalScalars(cfg *NotariusConfig) error {
 		want string
 	}{
 		{name: "binary", got: cfg.Binary, want: strings.TrimSpace(cfg.Binary)},
+		{name: "chunk_cache", got: cfg.ChunkCache, want: strings.TrimSpace(cfg.ChunkCache)},
 		{name: "config_path", got: cfg.ConfigPath, want: cleanNotariusPath(cfg.ConfigPath)},
 		{name: "pipeline_id", got: cfg.PipelineID, want: strings.TrimSpace(cfg.PipelineID)},
 		{name: "timeout", got: cfg.Timeout, want: strings.TrimSpace(cfg.Timeout)},
@@ -69,6 +72,15 @@ func validateNotariusCanonicalScalars(cfg *NotariusConfig) error {
 	return nil
 }
 
+func validNotariusChunkCacheMode(mode string) bool {
+	switch mode {
+	case "", "auto", "bypass", "refresh":
+		return true
+	default:
+		return false
+	}
+}
+
 func normalizeNotariusReferences(references map[string]string) (map[string]string, error) {
 	selectors := make([]string, 0, len(references))
 	for selector := range references {

internal/manifest/manifest.go

@@ -62,6 +62,8 @@ type StageRecord struct {
 	Error                  *ErrorRecord                       `json:"error,omitempty"`
 	Metadata               map[string]any                     `json:"metadata,omitempty"`
 	SemanticConfig         *SemanticConfigFingerprint         `json:"semantic_config,omitempty"`
+	TranscribeStateVersion int                                `json:"transcribe_state_version,omitempty"`
+	TranscribeSpeakers     map[string]TranscribeSpeakerRecord `json:"transcribe_speakers,omitempty"`
 	AnalyzeStateVersion    int                                `json:"analyze_state_version,omitempty"`
 	AnalyzeArtifacts       map[string]AnalyzeArtifactRecord   `json:"analyze_artifacts,omitempty"`
 }

internal/manifest/store.go

@@ -119,6 +119,9 @@ func (s *LocalStore) Save(ctx context.Context, path string, m *Manifest) error {
 	}
 	for name, stage := range m.Stages {
 		normalizeAnalyzeArtifactCollection(stage.AnalyzeArtifacts)
+		if err := validateTranscribeStageState(name, stage.TranscribeStateVersion, stage.TranscribeSpeakers); err != nil {
+			return fmt.Errorf("save manifest: stages.%s: %w", name, err)
+		}
 		if err := validateAnalyzeStageState(name, stage.AnalyzeStateVersion, stage.AnalyzeArtifacts); err != nil {
 			return fmt.Errorf("save manifest: stages.%s: %w", name, err)
 		}
@@ -160,6 +163,9 @@ func validateLoadedManifest(m *Manifest) error {
 		return err
 	}
 	for name, stage := range m.Stages {
+		if err := validateTranscribeStageState(name, stage.TranscribeStateVersion, stage.TranscribeSpeakers); err != nil {
+			return fmt.Errorf("stages.%s: %w", name, err)
+		}
 		if err := validateAnalyzeStageState(name, stage.AnalyzeStateVersion, stage.AnalyzeArtifacts); err != nil {
 			return fmt.Errorf("stages.%s: %w", name, err)
 		}

internal/manifest/transcribe_state.go

@@ -0,0 +1,128 @@
+package manifest
+
+import (
+	"fmt"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/pathsafe"
+)
+
+const (
+	// TranscribeStateContractVersion identifies the supported per-speaker
+	// completion representation owned by the transcribe stage.
+	TranscribeStateContractVersion = 1
+	// TranscribeFingerprintContractVersion identifies the fingerprint
+	// representation stored by the supported transcribe state contract.
+	TranscribeFingerprintContractVersion = 1
+)
+
+// TranscribeSpeakerRecord binds one completed raw transcript to the audio and
+// observable recognition settings that produced it.
+type TranscribeSpeakerRecord struct {
+	FingerprintVersion int            `json:"fingerprint_version"`
+	Fingerprint        string         `json:"fingerprint"`
+	AudioPath          string         `json:"audio_path"`
+	AudioSHA256        string         `json:"audio_sha256"`
+	AudioSize          int64          `json:"audio_size"`
+	Output             ArtifactRecord `json:"output"`
+	OutputSize         int64          `json:"output_size"`
+	ProducerRunID      string         `json:"producer_run_id"`
+}
+
+// HasVersionedTranscribeState reports whether a transcribe stage record carries
+// the supported per-speaker authority. An aggregate-only record returns false.
+func (s *StageRecord) HasVersionedTranscribeState() bool {
+	return s != nil && s.Name == "transcribe" && s.TranscribeStateVersion == TranscribeStateContractVersion
+}
+
+// ValidateTranscribeSpeakerCollection validates one complete session
+// collection independently of its containing manifest.
+func ValidateTranscribeSpeakerCollection(version int, records map[string]TranscribeSpeakerRecord) error {
+	if version != TranscribeStateContractVersion {
+		return fmt.Errorf("unsupported transcribe state version %d", version)
+	}
+	for speakerID, record := range records {
+		if err := validateTranscribeSpeakerRecord(speakerID, record); err != nil {
+			return fmt.Errorf("transcribe speaker %q: %w", speakerID, err)
+		}
+	}
+	return nil
+}
+
+// CloneTranscribeSpeakerCollection returns a deep copy so checkpoint candidates
+// and installed authority cannot share mutable artifact metadata.
+func CloneTranscribeSpeakerCollection(records map[string]TranscribeSpeakerRecord) map[string]TranscribeSpeakerRecord {
+	if records == nil {
+		return nil
+	}
+	cloned := make(map[string]TranscribeSpeakerRecord, len(records))
+	for speakerID, record := range records {
+		output := cloneArtifactRecord(&record.Output)
+		record.Output = *output
+		cloned[speakerID] = record
+	}
+	return cloned
+}
+
+func validateTranscribeStageState(stageName string, version int, records map[string]TranscribeSpeakerRecord) error {
+	if stageName != "transcribe" {
+		if version != 0 || records != nil {
+			return fmt.Errorf("stage %q cannot contain transcribe-owned state", stageName)
+		}
+		return nil
+	}
+	if version == 0 && records == nil {
+		return nil
+	}
+	return ValidateTranscribeSpeakerCollection(version, records)
+}
+
+func validateTranscribeSpeakerRecord(speakerID string, record TranscribeSpeakerRecord) error {
+	if speakerID == "" {
+		return fmt.Errorf("speaker ID is required")
+	}
+	if record.FingerprintVersion != TranscribeFingerprintContractVersion {
+		return fmt.Errorf("unsupported fingerprint version %d", record.FingerprintVersion)
+	}
+	if err := validateSHA256("fingerprint", record.Fingerprint); err != nil {
+		return err
+	}
+	if err := validateCanonicalRelativePath("audio_path", record.AudioPath); err != nil {
+		return err
+	}
+	if err := validateSHA256("audio_sha256", record.AudioSHA256); err != nil {
+		return err
+	}
+	if record.AudioSize < 0 {
+		return fmt.Errorf("audio_size must not be negative")
+	}
+	if record.Output.Kind != "transcript_raw" {
+		return fmt.Errorf("output kind %q must be transcript_raw", record.Output.Kind)
+	}
+	if err := validateCanonicalRelativePath("output local_path", record.Output.LocalPath); err != nil {
+		return err
+	}
+	if err := validateSHA256("output checksum", record.Output.Checksum); err != nil {
+		return err
+	}
+	if record.OutputSize <= 0 {
+		return fmt.Errorf("output_size must be positive")
+	}
+	if err := pathsafe.ValidateOpaqueSegment(record.ProducerRunID); err != nil {
+		return fmt.Errorf("producer_run_id is invalid: %w", err)
+	}
+	if record.Output.ProducerRunID != record.ProducerRunID {
+		return fmt.Errorf("output producer_run_id %q does not match record", record.Output.ProducerRunID)
+	}
+	return nil
+}
+
+func validateCanonicalRelativePath(field, value string) error {
+	normalized, err := pathsafe.NormalizeRelativeDestination(value)
+	if err != nil {
+		return fmt.Errorf("%s is unsafe: %w", field, err)
+	}
+	if normalized != value {
+		return fmt.Errorf("%s %q is not canonical %q", field, value, normalized)
+	}
+	return nil
+}

internal/manifest/transcribe_state_test.go

@@ -0,0 +1,254 @@
+package manifest
+
+import (
+	"context"
+	"encoding/json"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestTranscribeSpeakerStateRoundTripsPopulatedAndVersionedEmptyCollections(t *testing.T) {
+	now := time.Date(2026, 9, 21, 12, 0, 0, 0, time.UTC)
+	store := &LocalStore{}
+	zeroAudio := validTranscribeSpeakerRecord("Alice Table 1")
+	zeroAudio.AudioSize = 0
+
+	for _, test := range []struct {
+		name    string
+		records map[string]TranscribeSpeakerRecord
+	}{
+		{
+			name: "populated",
+			records: map[string]TranscribeSpeakerRecord{
+				"Alice Table 1": validTranscribeSpeakerRecord("Alice Table 1"),
+			},
+		},
+		{name: "versioned empty", records: map[string]TranscribeSpeakerRecord{}},
+		{name: "zero size audio", records: map[string]TranscribeSpeakerRecord{"Alice Table 1": zeroAudio}},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			m := New("session", now)
+			m.Stages["transcribe"] = &StageRecord{
+				Name: "transcribe", Status: StatusSucceeded, CreatedAt: now, UpdatedAt: now,
+				TranscribeStateVersion: TranscribeStateContractVersion,
+				TranscribeSpeakers:     test.records,
+			}
+			path := filepath.Join(t.TempDir(), "manifest.json")
+			if err := store.Save(context.Background(), path, m); err != nil {
+				t.Fatalf("Save() error = %v", err)
+			}
+			loaded, err := store.Load(context.Background(), path)
+			if err != nil {
+				t.Fatalf("Load() error = %v", err)
+			}
+			stage := loaded.Stages["transcribe"]
+			if !stage.HasVersionedTranscribeState() {
+				t.Fatalf("transcribe state = %#v, want supported version", stage)
+			}
+			if len(stage.TranscribeSpeakers) != len(test.records) {
+				t.Fatalf("speaker count = %d, want %d", len(stage.TranscribeSpeakers), len(test.records))
+			}
+			if len(test.records) != 0 {
+				got := stage.TranscribeSpeakers["Alice Table 1"]
+				if got.AudioSize != test.records["Alice Table 1"].AudioSize {
+					t.Fatalf("audio size = %d, want %d", got.AudioSize, test.records["Alice Table 1"].AudioSize)
+				}
+				if got.AudioPath != "inputs/audio/Alice Table 1.flac" || got.Output.LocalPath != "transcripts/raw/Alice Table 1.json" {
+					t.Fatalf("round-tripped record = %#v", got)
+				}
+			}
+		})
+	}
+}
+
+func TestTranscribeSpeakerStateAllowsLegacyAggregateOnlyManifest(t *testing.T) {
+	legacy := `{
+  "schema_version": "narratio.session-manifest.v1",
+  "session_id": "session",
+  "created_at": "2026-09-21T12:00:00Z",
+  "updated_at": "2026-09-21T12:01:00Z",
+  "stages": {
+    "transcribe": {
+      "name": "transcribe",
+      "status": "succeeded",
+      "created_at": "2026-09-21T12:00:00Z",
+      "updated_at": "2026-09-21T12:01:00Z",
+      "outputs": [{"kind":"transcript_raw","local_path":"transcripts/raw/alice.json"}]
+    }
+  }
+}`
+	loaded, err := (&LocalStore{}).LoadReader(context.Background(), strings.NewReader(legacy))
+	if err != nil {
+		t.Fatalf("LoadReader() error = %v", err)
+	}
+	if loaded.Stages["transcribe"].HasVersionedTranscribeState() {
+		t.Fatal("legacy aggregate-only manifest unexpectedly gained per-speaker authority")
+	}
+	if err := (&LocalStore{}).Save(context.Background(), filepath.Join(t.TempDir(), "manifest.json"), loaded); err != nil {
+		t.Fatalf("Save(legacy aggregate-only manifest) error = %v", err)
+	}
+}
+
+func TestValidateTranscribeSpeakerCollectionRejectsMalformedEvidence(t *testing.T) {
+	valid := validTranscribeSpeakerRecord("alice")
+	tests := []struct {
+		name      string
+		speakerID string
+		mutate    func(*TranscribeSpeakerRecord)
+		want      string
+	}{
+		{name: "empty speaker ID", speakerID: "", want: "speaker ID is required"},
+		{name: "unsupported fingerprint version", speakerID: "alice", mutate: func(r *TranscribeSpeakerRecord) { r.FingerprintVersion = 2 }, want: "unsupported fingerprint version"},
+		{name: "bad fingerprint", speakerID: "alice", mutate: func(r *TranscribeSpeakerRecord) { r.Fingerprint = "bad" }, want: "fingerprint must be"},
+		{name: "unsafe audio path", speakerID: "alice", mutate: func(r *TranscribeSpeakerRecord) { r.AudioPath = "../alice.flac" }, want: "audio_path is unsafe"},
+		{name: "noncanonical audio path", speakerID: "alice", mutate: func(r *TranscribeSpeakerRecord) { r.AudioPath = "inputs/audio/../alice.flac" }, want: "not canonical"},
+		{name: "bad audio checksum", speakerID: "alice", mutate: func(r *TranscribeSpeakerRecord) { r.AudioSHA256 = strings.Repeat("G", 64) }, want: "audio_sha256 must be"},
+		{name: "negative audio size", speakerID: "alice", mutate: func(r *TranscribeSpeakerRecord) { r.AudioSize = -1 }, want: "audio_size"},
+		{name: "bad output kind", speakerID: "alice", mutate: func(r *TranscribeSpeakerRecord) { r.Output.Kind = "transcript" }, want: "must be transcript_raw"},
+		{name: "unsafe output path", speakerID: "alice", mutate: func(r *TranscribeSpeakerRecord) { r.Output.LocalPath = "/tmp/alice.json" }, want: "output local_path is unsafe"},
+		{name: "bad output checksum", speakerID: "alice", mutate: func(r *TranscribeSpeakerRecord) { r.Output.Checksum = "bad" }, want: "output checksum must be"},
+		{name: "bad output size", speakerID: "alice", mutate: func(r *TranscribeSpeakerRecord) { r.OutputSize = 0 }, want: "output_size must be positive"},
+		{name: "bad producer run", speakerID: "alice", mutate: func(r *TranscribeSpeakerRecord) { r.ProducerRunID = "bad/run" }, want: "producer_run_id is invalid"},
+		{name: "producer mismatch", speakerID: "alice", mutate: func(r *TranscribeSpeakerRecord) { r.Output.ProducerRunID = "other-run" }, want: "does not match record"},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			record := valid
+			if test.mutate != nil {
+				test.mutate(&record)
+			}
+			err := ValidateTranscribeSpeakerCollection(TranscribeStateContractVersion, map[string]TranscribeSpeakerRecord{test.speakerID: record})
+			if err == nil || !strings.Contains(err.Error(), test.want) {
+				t.Fatalf("error = %v, want %q", err, test.want)
+			}
+		})
+	}
+	if err := ValidateTranscribeSpeakerCollection(99, nil); err == nil || !strings.Contains(err.Error(), "unsupported transcribe state version") {
+		t.Fatalf("unsupported version error = %v", err)
+	}
+}
+
+func TestTranscribeSpeakerStateValidationAppliesOnSaveAndLoad(t *testing.T) {
+	now := time.Date(2026, 9, 21, 12, 0, 0, 0, time.UTC)
+	invalid := validTranscribeSpeakerRecord("alice")
+	invalid.AudioSHA256 = "bad"
+	m := New("session", now)
+	m.Stages["transcribe"] = &StageRecord{
+		Name: "transcribe", Status: StatusSucceeded, CreatedAt: now, UpdatedAt: now,
+		TranscribeStateVersion: TranscribeStateContractVersion,
+		TranscribeSpeakers:     map[string]TranscribeSpeakerRecord{"alice": invalid},
+	}
+	store := &LocalStore{}
+	if err := store.Save(context.Background(), filepath.Join(t.TempDir(), "manifest.json"), m); err == nil || !strings.Contains(err.Error(), "audio_sha256") {
+		t.Fatalf("Save() error = %v, want audio evidence validation", err)
+	}
+
+	data, err := json.Marshal(m)
+	if err != nil {
+		t.Fatalf("Marshal() error = %v", err)
+	}
+	if _, err := store.LoadReader(context.Background(), strings.NewReader(string(data))); err == nil || !strings.Contains(err.Error(), "audio_sha256") {
+		t.Fatalf("LoadReader() error = %v, want audio evidence validation", err)
+	}
+}
+
+func TestTranscribeSpeakerStateOwnershipAndVersionAreValidated(t *testing.T) {
+	now := time.Date(2026, 9, 21, 12, 0, 0, 0, time.UTC)
+	store := &LocalStore{}
+
+	for _, test := range []struct {
+		name  string
+		stage *StageRecord
+		want  string
+	}{
+		{
+			name: "wrong owner",
+			stage: &StageRecord{Name: "merge", Status: StatusSucceeded, CreatedAt: now, UpdatedAt: now,
+				TranscribeStateVersion: TranscribeStateContractVersion,
+				TranscribeSpeakers:     map[string]TranscribeSpeakerRecord{}},
+			want: "cannot contain transcribe-owned state",
+		},
+		{
+			name: "missing version",
+			stage: &StageRecord{Name: "transcribe", Status: StatusSucceeded, CreatedAt: now, UpdatedAt: now,
+				TranscribeSpeakers: map[string]TranscribeSpeakerRecord{"alice": validTranscribeSpeakerRecord("alice")}},
+			want: "unsupported transcribe state version 0",
+		},
+		{
+			name: "unsupported version",
+			stage: &StageRecord{Name: "transcribe", Status: StatusSucceeded, CreatedAt: now, UpdatedAt: now,
+				TranscribeStateVersion: 2},
+			want: "unsupported transcribe state version 2",
+		},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			m := New("session", now)
+			m.Stages[test.stage.Name] = test.stage
+			if err := store.Save(context.Background(), filepath.Join(t.TempDir(), "manifest.json"), m); err == nil || !strings.Contains(err.Error(), test.want) {
+				t.Fatalf("Save() error = %v, want %q", err, test.want)
+			}
+		})
+	}
+}
+
+func TestCloneTranscribeSpeakerCollectionIsIsolated(t *testing.T) {
+	original := map[string]TranscribeSpeakerRecord{"alice": validTranscribeSpeakerRecord("alice")}
+	cloned := CloneTranscribeSpeakerCollection(original)
+	record := cloned["alice"]
+	record.AudioPath = "inputs/audio/replacement.flac"
+	record.Output.Checksum = strings.Repeat("c", 64)
+	cloned["alice"] = record
+
+	if got := original["alice"]; got.AudioPath != "inputs/audio/alice.flac" || got.Output.Checksum != strings.Repeat("b", 64) {
+		t.Fatalf("original changed through clone: %#v", got)
+	}
+}
+
+func TestTranscribeSpeakerStateSurvivesAggregateLifecycleTransitions(t *testing.T) {
+	now := time.Date(2026, 9, 21, 12, 0, 0, 0, time.UTC)
+	for _, transition := range []struct {
+		name  string
+		apply func(*Manifest)
+	}{
+		{name: "running", apply: func(m *Manifest) { m.MarkStageRunning("transcribe", now.Add(time.Minute)) }},
+		{name: "failed", apply: func(m *Manifest) { m.MarkStageFailed("transcribe", now.Add(time.Minute), "request failed") }},
+		{name: "stale", apply: func(m *Manifest) { m.MarkStageStale("transcribe", now.Add(time.Minute), "audio changed") }},
+	} {
+		t.Run(transition.name, func(t *testing.T) {
+			m := New("session", now)
+			m.Stages["transcribe"] = &StageRecord{
+				Name: "transcribe", Status: StatusSucceeded, CreatedAt: now, UpdatedAt: now,
+				Outputs: []ArtifactRecord{{Kind: "transcript_raw", LocalPath: "transcripts/raw/old.json"}},
+				Logs:    []string{"runs/old/transcribe.log"}, Metadata: map[string]any{"attempts": 1},
+				TranscribeStateVersion: TranscribeStateContractVersion,
+				TranscribeSpeakers:     map[string]TranscribeSpeakerRecord{"alice": validTranscribeSpeakerRecord("alice")},
+			}
+			transition.apply(m)
+			stage := m.Stages["transcribe"]
+			if !stage.HasVersionedTranscribeState() || stage.TranscribeSpeakers["alice"].AudioPath != "inputs/audio/alice.flac" {
+				t.Fatalf("speaker completion was lost during %s: %#v", transition.name, stage)
+			}
+			if transition.name != "stale" && (len(stage.Outputs) != 0 || len(stage.Logs) != 0 || len(stage.Metadata) != 0) {
+				t.Fatalf("aggregate details survived %s: %#v", transition.name, stage)
+			}
+		})
+	}
+}
+
+func validTranscribeSpeakerRecord(speakerID string) TranscribeSpeakerRecord {
+	runID := "run-1"
+	return TranscribeSpeakerRecord{
+		FingerprintVersion: TranscribeFingerprintContractVersion,
+		Fingerprint:        strings.Repeat("a", 64),
+		AudioPath:          "inputs/audio/" + speakerID + ".flac",
+		AudioSHA256:        strings.Repeat("1", 64),
+		AudioSize:          1024,
+		Output: ArtifactRecord{
+			Kind: "transcript_raw", LocalPath: "transcripts/raw/" + speakerID + ".json",
+			Checksum: strings.Repeat("b", 64), ProducerRunID: runID,
+		},
+		OutputSize: 256, ProducerRunID: runID,
+	}
+}

internal/stage/cleanup_test.go

@@ -58,9 +58,12 @@ func TestCleanupStageRemovesOnlySelectedPublishedRunTargets(t *testing.T) {
 			otherSpool := filepath.Join(env.Config.Pipeline.Spool.Root, m.Campaign, m.SessionID, "other-run", "audio")
 			otherWorkspace := filepath.Join(env.Config.Pipeline.Workspace.Root, "work", m.Campaign, m.SessionID, "runs", "other-run")
 			cacheFile := filepath.Join(env.Config.Pipeline.Cache.Root, "s3", "audio.cache")
+			sessionPaths := artifacts.NewLocalStore(env.Config.Pipeline.Workspace.Root).SessionPathsFor(m.Campaign, m.SessionID)
+			referenceCacheFile := filepath.Join(artifacts.SessionNotariusReferenceCacheDir(sessionPaths), strings.Repeat("a", 64), "party.yml")
 			writeStageTestFile(t, filepath.Join(otherSpool, "audio.wav"), "other spool")
 			writeStageTestFile(t, filepath.Join(otherWorkspace, "result.txt"), "other workspace")
 			writeStageTestFile(t, cacheFile, "cache")
+			writeStageTestFile(t, referenceCacheFile, "reference cache")
 
 			result, err := (cleanupStage{}).Run(context.Background(), env, m)
 			if err != nil {
@@ -81,7 +84,7 @@ func TestCleanupStageRemovesOnlySelectedPublishedRunTargets(t *testing.T) {
 					t.Fatalf("unselected workspace target changed: %v", err)
 				}
 			}
-			for _, preserved := range []string{otherSpool, otherWorkspace, cacheFile} {
+			for _, preserved := range []string{otherSpool, otherWorkspace, cacheFile, referenceCacheFile} {
 				if _, err := os.Stat(preserved); err != nil {
 					t.Fatalf("preserved path %q: %v", preserved, err)
 				}

internal/stage/extract.go

@@ -124,20 +124,13 @@ func (extractStage) Run(ctx context.Context, env *Env, m *manifest.Manifest) (re
 	if err != nil {
 		return nil, fmt.Errorf("extract: resolve durable bundle path: %w", err)
 	}
-	referenceSnapshotRoot, err := absolutePath(artifacts.SessionRunNotariusReferencesDirForCampaign(workspaceRoot, campaign, sessionID, runID))
-	if err != nil {
-		return nil, fmt.Errorf("extract: resolve reference snapshot path: %w", err)
-	}
 	directories := []string{filepath.Dir(receiptPath), outputRoot, filepath.Dir(durableBundle)}
-	if len(references.Bindings) > 0 {
-		directories = append(directories, referenceSnapshotRoot)
-	}
 	for _, directory := range directories {
 		if err := fileops.EnsureWorkspaceDirectory(directory); err != nil {
 			return nil, fmt.Errorf("extract: create directory %q: %w", directory, err)
 		}
 	}
-	referenceBindings, err := materializeExtractReferenceSnapshots(paths, references, referenceSnapshotRoot)
+	referenceBindings, err := materializeExtractReferenceSnapshots(paths, references)
 	if err != nil {
 		return nil, fmt.Errorf("extract: materialize Notarius reference snapshots: %w", err)
 	}
@@ -146,10 +139,17 @@ func (extractStage) Run(ctx context.Context, env *Env, m *manifest.Manifest) (re
 	if err != nil {
 		return nil, fmt.Errorf("extract: build configuration fingerprint: %w", err)
 	}
+	resume := notariusConfig.Resume
+	chunkCache := notariusConfig.ChunkCache
+	if env.Force {
+		resume = false
+		chunkCache = "refresh"
+	}
 	request := notarius.RunRequest{
-		Binary: resolvedBinary, ConfigPath: configPath, PipelineID: notariusConfig.PipelineID,
+		Binary: resolvedBinary, LLMAPIKey: notariusConfig.LLMAPIKey, ConfigProfile: notariusConfig.ConfigProfile,
+		ConfigPath: configPath, PipelineID: notariusConfig.PipelineID,
 		InputPath: inputPath, OutputRoot: outputRoot, WorkingDirectory: workingDirectory,
-		ReceiptPath: receiptPath, LogPath: logPath, Timeout: timeout, References: referenceBindings,
+		ReceiptPath: receiptPath, LogPath: logPath, Timeout: timeout, Resume: resume, ChunkCache: chunkCache, References: referenceBindings,
 	}
 	stageSucceeded := false
 	bundleMoved := false
@@ -176,7 +176,7 @@ func (extractStage) Run(ctx context.Context, env *Env, m *manifest.Manifest) (re
 	if adapterResult.Receipt.RunID == "" || adapterResult.Receipt.PipelineID != notariusConfig.PipelineID {
 		return nil, fmt.Errorf("extract: notarius receipt identity is missing or incompatible")
 	}
-	if err := verifyExtractReferenceSnapshots(referenceSnapshotRoot, references); err != nil {
+	if err := verifyExtractReferenceSnapshots(paths, references); err != nil {
 		return nil, fmt.Errorf("extract: verify Notarius reference snapshots: %w", err)
 	}
 
@@ -451,6 +451,7 @@ type fingerprintOutput struct {
 
 type fingerprintDocument struct {
 	PipelineID    string                            `json:"pipeline_id"`
+	ConfigProfile string                            `json:"config_profile,omitempty"`
 	Input         artifacts.ExtractionInputIdentity `json:"input"`
 	References    []extractReferenceIdentity        `json:"references"`
 	Outputs       []fingerprintOutput               `json:"outputs"`
@@ -485,7 +486,8 @@ func extractionFingerprint(
 		return sortedReferences[i].Path < sortedReferences[j].Path
 	})
 	payload, err := json.Marshal(fingerprintDocument{
-		PipelineID: cfg.PipelineID, Input: input, References: sortedReferences, Outputs: outputs,
+		PipelineID: cfg.PipelineID, ConfigProfile: notariusConfigProfileReuseIdentity(cfg.ConfigProfile),
+		Input: input, References: sortedReferences, Outputs: outputs,
 	})
 	if err != nil {
 		return "", err

internal/stage/extract_references.go

@@ -3,6 +3,7 @@ package stage
 import (
 	"crypto/sha256"
 	"encoding/hex"
+	"errors"
 	"fmt"
 	"io"
 	"os"
@@ -16,6 +17,7 @@ import (
 	"gitea.maximumdirect.net/eric/narratio/internal/fileops"
 	"gitea.maximumdirect.net/eric/narratio/internal/manifest"
 	"gitea.maximumdirect.net/eric/narratio/internal/notariusref"
+	"gitea.maximumdirect.net/eric/narratio/internal/pathsafe"
 )
 
 type extractReferenceIdentity struct {
@@ -29,83 +31,204 @@ type extractReferenceIdentity struct {
 func materializeExtractReferenceSnapshots(
 	paths artifacts.SessionPaths,
 	references resolvedExtractReferences,
-	snapshotRoot string,
 ) ([]notarius.ReferenceBinding, error) {
+	var err error
+	paths, err = absoluteExtractSnapshotPaths(paths)
+	if err != nil {
+		return nil, err
+	}
 	if len(references.Bindings) != len(references.Identities) {
 		return nil, fmt.Errorf("reference bindings and identities have different lengths")
 	}
 	bindings := make([]notarius.ReferenceBinding, len(references.Bindings))
-	copied := make(map[string]string, len(references.Bindings))
+	materialized := make(map[string]extractReferenceIdentity, len(references.Bindings))
-	destinationOwners := make(map[string]string, len(references.Bindings))
 	for index, binding := range references.Bindings {
 		identity := references.Identities[index]
-		destination, ok := copied[identity.SourceID]
+		destination, err := extractReferenceSnapshotDestination(paths, identity)
-		if !ok {
-			filename := filepath.Base(filepath.FromSlash(identity.Path))
-			if filename == "" || filename == "." || filename == string(filepath.Separator) {
-				return nil, fmt.Errorf("reference %q source %q has invalid prepared filename", identity.Selector, identity.SourceID)
-			}
-			destination = filepath.Join(snapshotRoot, filename)
-			if owner, duplicate := destinationOwners[destination]; duplicate && owner != identity.SourceID {
-				return nil, fmt.Errorf("reference sources %q and %q resolve to the same snapshot path", owner, identity.SourceID)
-			}
-			destinationOwners[destination] = identity.SourceID
-
-			file, err := os.Open(filepath.Join(paths.Root, filepath.FromSlash(identity.Path)))
 		if err != nil {
-				return nil, fmt.Errorf("open reference %q source %q for snapshot: %w", identity.Selector, identity.SourceID, err)
+			return nil, fmt.Errorf("reference %q source %q snapshot path: %w", identity.Selector, identity.SourceID, err)
 		}
-			checksum, copyErr := fileops.WriteReaderAtomicWithChecksum(destination, file, fileops.WorkspaceFileMode)
+		if previous, ok := materialized[destination]; ok {
-			closeErr := file.Close()
+			if previous.Checksum != identity.Checksum || previous.SizeBytes != identity.SizeBytes {
-			if copyErr != nil {
+				return nil, fmt.Errorf("references %q and %q have conflicting identities for snapshot %q", previous.Selector, identity.Selector, destination)
-				return nil, fmt.Errorf("snapshot reference %q source %q: %w", identity.Selector, identity.SourceID, copyErr)
 			}
-			if closeErr != nil {
+			bindings[index] = notarius.ReferenceBinding{Selector: binding.Selector, Path: destination}
-				return nil, fmt.Errorf("close reference %q source %q: %w", identity.Selector, identity.SourceID, closeErr)
+			continue
 		}
-			info, err := os.Lstat(destination)
+		if err := materializeExtractReferenceSnapshot(paths, identity, destination); err != nil {
-			if err != nil {
+			return nil, err
-				return nil, fmt.Errorf("inspect reference %q snapshot: %w", identity.Selector, err)
-			}
-			if !info.Mode().IsRegular() || !strings.EqualFold(checksum, identity.Checksum) || info.Size() != identity.SizeBytes {
-				return nil, fmt.Errorf("reference %q source %q changed while its verified snapshot was created", identity.Selector, identity.SourceID)
-			}
-			copied[identity.SourceID] = destination
 		}
+		materialized[destination] = identity
 		bindings[index] = notarius.ReferenceBinding{Selector: binding.Selector, Path: destination}
 	}
 	return bindings, nil
 }
 
-func verifyExtractReferenceSnapshots(snapshotRoot string, references resolvedExtractReferences) error {
+func materializeExtractReferenceSnapshot(paths artifacts.SessionPaths, identity extractReferenceIdentity, destination string) error {
-	verified := make(map[string]struct{}, len(references.Identities))
+	if err := checkExtractSnapshotDirectory(paths.Root, filepath.Dir(destination), true); err != nil {
+		return fmt.Errorf("reference %q snapshot cache: %w", identity.Selector, err)
+	}
+	info, err := os.Lstat(destination)
+	if err == nil && !info.Mode().IsRegular() {
+		return unsafeExtractSnapshotPath(destination, "the destination is not a regular file")
+	}
+	if err != nil && !errors.Is(err, os.ErrNotExist) {
+		return fmt.Errorf("inspect reference %q snapshot %q: %w", identity.Selector, destination, err)
+	}
+	if err == nil {
+		if verifyErr := verifyExtractReferenceFile(destination, identity); verifyErr == nil {
+			return nil
+		}
+	}
+
+	source, err := pathsafe.JoinSlashRelativeUnderRoot(paths.Root, identity.Path)
+	if err != nil {
+		return fmt.Errorf("resolve reference %q prepared source: %w", identity.Selector, err)
+	}
+	if err := verifyExtractReferenceFile(source, identity); err != nil {
+		return fmt.Errorf("reference %q prepared source %q no longer matches its manifest identity; rerun prepare with --force: %w", identity.Selector, source, err)
+	}
+	checksum, err := fileops.CopyFileAtomicWithChecksum(source, destination, fileops.WorkspaceFileMode)
+	if err != nil {
+		return fmt.Errorf("snapshot reference %q source %q to %q: %w", identity.Selector, identity.SourceID, destination, err)
+	}
+	if checksum != identity.Checksum {
+		return cleanupInvalidExtractSnapshot(paths, identity, destination,
+			fmt.Errorf("copied checksum %q does not match manifest checksum %q", checksum, identity.Checksum))
+	}
+	if err := verifyExtractReferenceFile(destination, identity); err != nil {
+		return cleanupInvalidExtractSnapshot(paths, identity, destination, err)
+	}
+	return nil
+}
+
+func cleanupInvalidExtractSnapshot(paths artifacts.SessionPaths, identity extractReferenceIdentity, destination string, verifyErr error) error {
+	err := fmt.Errorf("reference %q source %q changed while snapshot %q was created; rerun prepare with --force: %w", identity.Selector, identity.SourceID, destination, verifyErr)
+	if cleanupErr := fileops.RemoveFileUnderRoot(artifacts.SessionNotariusReferenceCacheDir(paths), destination); cleanupErr != nil {
+		return errors.Join(err, fmt.Errorf("remove invalid newly written snapshot %q: %w", destination, cleanupErr))
+	}
+	return err
+}
+
+func verifyExtractReferenceSnapshots(paths artifacts.SessionPaths, references resolvedExtractReferences) error {
+	var err error
+	paths, err = absoluteExtractSnapshotPaths(paths)
+	if err != nil {
+		return err
+	}
+	verified := make(map[string]extractReferenceIdentity, len(references.Identities))
 	for _, identity := range references.Identities {
-		if _, ok := verified[identity.SourceID]; ok {
+		destination, err := extractReferenceSnapshotDestination(paths, identity)
+		if err != nil {
+			return fmt.Errorf("reference %q source %q snapshot path: %w", identity.Selector, identity.SourceID, err)
+		}
+		if previous, ok := verified[destination]; ok {
+			if previous.Checksum != identity.Checksum || previous.SizeBytes != identity.SizeBytes {
+				return fmt.Errorf("references %q and %q have conflicting identities for snapshot %q", previous.Selector, identity.Selector, destination)
+			}
 			continue
 		}
-		filename := filepath.Base(filepath.FromSlash(identity.Path))
+		if err := checkExtractSnapshotDirectory(paths.Root, filepath.Dir(destination), false); err != nil {
-		file, err := os.Open(filepath.Join(snapshotRoot, filename))
+			return fmt.Errorf("reference %q snapshot cache: %w", identity.Selector, err)
+		}
+		if err := verifyExtractReferenceFile(destination, identity); err != nil {
+			return fmt.Errorf("reference %q source %q snapshot changed while Notarius was running at %q: %w", identity.Selector, identity.SourceID, destination, err)
+		}
+		verified[destination] = identity
+	}
+	return nil
+}
+
+// Resolve both roots against the caller's working directory before comparing
+// paths. A session-prefixed relative destination is not relative to Root.
+func absoluteExtractSnapshotPaths(paths artifacts.SessionPaths) (artifacts.SessionPaths, error) {
+	var err error
+	paths.Root, err = filepath.Abs(paths.Root)
 	if err != nil {
-			return fmt.Errorf("reopen reference %q source %q snapshot: %w", identity.Selector, identity.SourceID, err)
+		return paths, fmt.Errorf("resolve snapshot session root: %w", err)
+	}
+	paths.CacheDir, err = filepath.Abs(paths.CacheDir)
+	if err != nil {
+		return paths, fmt.Errorf("resolve snapshot cache root: %w", err)
+	}
+	return paths, nil
+}
+
+func extractReferenceSnapshotDestination(paths artifacts.SessionPaths, identity extractReferenceIdentity) (string, error) {
+	basename := filepath.Base(filepath.FromSlash(identity.Path))
+	return artifacts.SessionNotariusReferenceSnapshotPath(paths, identity.Checksum, basename)
+}
+
+func verifyExtractReferenceFile(path string, identity extractReferenceIdentity) error {
+	info, err := os.Lstat(path)
+	if err != nil {
+		return err
+	}
+	if !info.Mode().IsRegular() {
+		return unsafeExtractSnapshotPath(path, "the path is not a regular file")
+	}
+	file, err := os.Open(path)
+	if err != nil {
+		return err
 	}
 	digest := sha256.New()
 	size, readErr := io.Copy(digest, file)
 	closeErr := file.Close()
 	if readErr != nil {
-			return fmt.Errorf("revalidate reference %q source %q snapshot: %w", identity.Selector, identity.SourceID, readErr)
+		return readErr
 	}
 	if closeErr != nil {
-			return fmt.Errorf("close reference %q source %q snapshot: %w", identity.Selector, identity.SourceID, closeErr)
+		return closeErr
 	}
 	checksum := hex.EncodeToString(digest.Sum(nil))
-		if !strings.EqualFold(checksum, identity.Checksum) || size != identity.SizeBytes {
+	if checksum != identity.Checksum || size != identity.SizeBytes || info.Size() != identity.SizeBytes {
-			return fmt.Errorf("reference %q source %q snapshot changed while Notarius was running", identity.Selector, identity.SourceID)
+		return fmt.Errorf("content identity is checksum %q size %d, want checksum %q size %d", checksum, size, identity.Checksum, identity.SizeBytes)
-		}
-		verified[identity.SourceID] = struct{}{}
 	}
 	return nil
 }
 
+func checkExtractSnapshotDirectory(sessionRoot, directory string, create bool) error {
+	relative, err := pathsafe.SlashRelativeFromRoot(sessionRoot, directory)
+	if err != nil {
+		return fmt.Errorf("resolve snapshot directory %q below session root: %w", directory, err)
+	}
+	root, err := os.OpenRoot(sessionRoot)
+	if err != nil {
+		return fmt.Errorf("open session root %q: %w", sessionRoot, err)
+	}
+	defer func() { _ = root.Close() }()
+
+	current := ""
+	for _, component := range strings.Split(relative, "/") {
+		if current == "" {
+			current = component
+		} else {
+			current += "/" + component
+		}
+		info, err := root.Lstat(current)
+		if errors.Is(err, os.ErrNotExist) && create {
+			if err := root.Mkdir(current, fileops.WorkspaceDirectoryMode.Perm()); err != nil && !errors.Is(err, os.ErrExist) {
+				return fmt.Errorf("create snapshot cache directory %q: %w", filepath.Join(sessionRoot, filepath.FromSlash(current)), err)
+			}
+			info, err = root.Lstat(current)
+		}
+		if err != nil {
+			return fmt.Errorf("inspect snapshot cache directory %q: %w", filepath.Join(sessionRoot, filepath.FromSlash(current)), err)
+		}
+		if !info.IsDir() || info.Mode()&os.ModeSymlink != 0 {
+			return unsafeExtractSnapshotPath(filepath.Join(sessionRoot, filepath.FromSlash(current)), "a path component is not a real directory")
+		}
+		if err := root.Chmod(current, fileops.WorkspaceDirectoryMode); err != nil {
+			return fmt.Errorf("set snapshot cache directory permissions %q: %w", filepath.Join(sessionRoot, filepath.FromSlash(current)), err)
+		}
+	}
+	return nil
+}
+
+func unsafeExtractSnapshotPath(path, reason string) error {
+	return fmt.Errorf("unsafe Notarius reference snapshot cache path %q: %s; remove or replace it only while the session is inactive", path, reason)
+}
+
 type resolvedExtractReferences struct {
 	Bindings   []notarius.ReferenceBinding
 	Identities []extractReferenceIdentity

internal/stage/extract_test.go

@@ -2,6 +2,8 @@ package stage
 
 import (
 	"context"
+	"crypto/sha256"
+	"encoding/hex"
 	"encoding/json"
 	"errors"
 	"fmt"
@@ -51,7 +53,27 @@ func TestExtractStageDisabledReturnsExplicitSkip(t *testing.T) {
 }
 
 func TestExtractStageResolvesManifestInputAndBuildsExactRequest(t *testing.T) {
+	const credentialName = "NARRATIO_EXTRACT_NOTARIUS_KEY"
+	const credentialCanary = "extract-notarius-credential-canary"
+	t.Setenv(credentialName, credentialCanary)
+	credentialPipelinePath := filepath.Join(t.TempDir(), "pipeline.yml")
+	if err := os.WriteFile(credentialPipelinePath, []byte(`whisperx:
+  transcribe_url: https://transcription.example.test/transcribe
+notarius:
+  enabled: false
+  llm_api_key: NARRATIO_EXTRACT_NOTARIUS_KEY
+`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	loadedPipeline, err := config.LoadPipeline(credentialPipelinePath)
+	if err != nil {
+		t.Fatalf("LoadPipeline() error = %v", err)
+	}
+
 	env, m, fake := setupExtractEnv(t)
+	env.Config.Pipeline.Notarius.LLMAPIKey = loadedPipeline.Notarius.LLMAPIKey
+	configProfile := "inexpensive"
+	env.Config.Pipeline.Notarius.ConfigProfile = &configProfile
 	result, err := (extractStage{}).Run(context.Background(), env, m)
 	if err != nil {
 		t.Fatalf("Run() error = %v", err)
@@ -78,14 +100,70 @@ func TestExtractStageResolvesManifestInputAndBuildsExactRequest(t *testing.T) {
 	if len(req.References) != 0 {
 		t.Fatalf("references = %#v, want none", req.References)
 	}
+	if req.Resume || req.ChunkCache != "" {
+		t.Fatalf("default cache controls = resume %v, mode %q", req.Resume, req.ChunkCache)
+	}
+	if req.LLMAPIKey != loadedPipeline.Notarius.LLMAPIKey || req.LLMAPIKey.EnvName() != credentialName || !req.LLMAPIKey.IsResolved() {
+		t.Fatal("request did not retain the loaded Notarius credential reference")
+	}
+	if req.ConfigProfile == nil || *req.ConfigProfile != configProfile {
+		t.Fatalf("request config profile = %#v, want %q", req.ConfigProfile, configProfile)
+	}
 	if result.Metadata["reference_count"] != 0 || len(result.Metadata["references"].([]map[string]any)) != 0 {
 		t.Fatalf("reference metadata = count %#v references %#v", result.Metadata["reference_count"], result.Metadata["references"])
 	}
+	metadata, err := json.Marshal(result.Metadata)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(string(metadata), credentialCanary) || strings.Contains(string(metadata), credentialName) {
+		t.Fatal("result metadata contains the Notarius credential")
+	}
 	if len(result.Outputs) != 2 {
 		t.Fatalf("outputs = %#v, want lane and index", result.Outputs)
 	}
 }
 
+func TestExtractStageAppliesNotariusCacheControlsAndForcePrecedence(t *testing.T) {
+	tests := []struct {
+		name             string
+		configuredResume bool
+		configuredMode   string
+		force            bool
+		wantResume       bool
+		wantMode         string
+	}{
+		{name: "ordinary defaults"},
+		{name: "ordinary configured", configuredResume: true, configuredMode: "bypass", wantResume: true, wantMode: "bypass"},
+		{name: "force overrides configured", configuredResume: true, configuredMode: "bypass", force: true, wantMode: "refresh"},
+		{name: "force overrides defaults", force: true, wantMode: "refresh"},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			env, m, fake := setupExtractEnv(t)
+			configProfile := "inexpensive"
+			env.Config.Pipeline.Notarius.ConfigProfile = &configProfile
+			env.Config.Pipeline.Notarius.Resume = test.configuredResume
+			env.Config.Pipeline.Notarius.ChunkCache = test.configuredMode
+			env.Force = test.force
+
+			if _, err := (extractStage{}).Run(context.Background(), env, m); err != nil {
+				t.Fatalf("Run() error = %v", err)
+			}
+			if len(fake.Requests) != 1 {
+				t.Fatalf("requests = %d, want 1", len(fake.Requests))
+			}
+			request := fake.Requests[0]
+			if request.Resume != test.wantResume || request.ChunkCache != test.wantMode {
+				t.Fatalf("cache controls = resume %v, mode %q; want resume %v, mode %q", request.Resume, request.ChunkCache, test.wantResume, test.wantMode)
+			}
+			if request.ConfigProfile == nil || *request.ConfigProfile != configProfile {
+				t.Fatalf("config profile = %#v, want %q", request.ConfigProfile, configProfile)
+			}
+		})
+	}
+}
+
 func TestExtractStageResolvesAllPreparedReferencesInSelectorOrder(t *testing.T) {
 	env, m, fake := setupExtractEnv(t)
 	configured := []struct {
@@ -121,12 +199,16 @@ func TestExtractStageResolvesAllPreparedReferencesInSelectorOrder(t *testing.T)
 	}
 	for index, selector := range wantSelectors {
 		binding := fake.Requests[0].References[index]
-		wantPath := filepath.Join(
+		checksum, err := artifacts.SHA256File(preparedPaths[selector])
-			artifacts.SessionRunNotariusReferencesDirForCampaign(
+		if err != nil {
-				env.Config.Pipeline.Workspace.Root, m.Campaign, m.SessionID, m.RunID,
+			t.Fatalf("SHA256File(%q) error = %v", selector, err)
-			),
+		}
-			filepath.Base(preparedPaths[selector]),
+		wantPath, err := artifacts.SessionNotariusReferenceSnapshotPath(
+			sessionPathsForEnv(env, m.SessionID), checksum, filepath.Base(preparedPaths[selector]),
 		)
+		if err != nil {
+			t.Fatalf("SessionNotariusReferenceSnapshotPath(%q) error = %v", selector, err)
+		}
 		if binding.Selector != selector || binding.Path != wantPath || binding.Path == preparedPaths[selector] || !filepath.IsAbs(binding.Path) {
 			t.Fatalf("reference[%d] = %#v, want selector %q verified snapshot %q", index, binding, selector, wantPath)
 		}
@@ -166,7 +248,7 @@ type referenceMutationRunner struct {
 	delegate      notarius.Runner
 	preparedPath  string
 	preparedBytes []byte
-	mutateSnapshot bool
+	mutate        func(string) error
 	snapshotBytes []byte
 }
 
@@ -182,8 +264,8 @@ func (r *referenceMutationRunner) Run(ctx context.Context, req notarius.RunReque
 		return notarius.RunResult{}, err
 	}
 	r.snapshotBytes = data
-	if r.mutateSnapshot {
+	if r.mutate != nil {
-		if err := os.WriteFile(req.References[0].Path, []byte("tampered snapshot\n"), 0o664); err != nil {
+		if err := r.mutate(req.References[0].Path); err != nil {
 			return notarius.RunResult{}, err
 		}
 	}
@@ -206,22 +288,293 @@ func TestExtractStageInvokesNotariusWithVerifiedReferenceSnapshot(t *testing.T)
 		t.Fatalf("Notarius reference bytes = %q, want verified snapshot", runner.snapshotBytes)
 	}
 	if len(fake.Requests) != 1 || fake.Requests[0].References[0].Path == preparedPath {
-		t.Fatalf("adapter requests = %#v, want a run-local reference snapshot", fake.Requests)
+		t.Fatalf("adapter requests = %#v, want a stable reference snapshot", fake.Requests)
 	}
 }
 
 func TestExtractStageRejectsReferenceSnapshotChangedDuringNotariusRun(t *testing.T) {
+	for _, test := range []struct {
+		name   string
+		mutate func(string) error
+	}{
+		{name: "content", mutate: func(path string) error { return os.WriteFile(path, []byte("tampered snapshot\n"), 0o664) }},
+		{name: "missing", mutate: os.Remove},
+		{name: "symlink", mutate: func(path string) error {
+			if err := os.Remove(path); err != nil {
+				return err
+			}
+			return os.Symlink(path+".outside", path)
+		}},
+		{name: "directory", mutate: func(path string) error {
+			if err := os.Remove(path); err != nil {
+				return err
+			}
+			return os.Mkdir(path, 0o775)
+		}},
+	} {
+		t.Run(test.name, func(t *testing.T) {
 			env, m, fake := setupExtractEnv(t)
 			env.Config.Pipeline.Notarius.References = map[string]string{"party": artifactpolicy.SourceInputParty}
 			preparedPath := recordPreparedExtractInput(t, env, m, artifactpolicy.SourceInputParty, "verified party\n")
 			env.Notarius = &referenceMutationRunner{
-		delegate: fake, preparedPath: preparedPath, preparedBytes: []byte("changed after snapshot\n"), mutateSnapshot: true,
+				delegate: fake, preparedPath: preparedPath, preparedBytes: []byte("changed after snapshot\n"), mutate: test.mutate,
 			}
 
 			result, err := (extractStage{}).Run(context.Background(), env, m)
 			if err == nil || !strings.Contains(err.Error(), "snapshot changed while Notarius was running") || result != nil {
 				t.Fatalf("Run() result = %#v error = %v, want changed-snapshot failure", result, err)
 			}
+		})
+	}
+}
+
+func TestExtractReferenceSnapshotsAreStableReusableAndRecoverable(t *testing.T) {
+	env, m, _ := setupExtractEnv(t)
+	env.Config.Pipeline.Notarius.References = map[string]string{"party": artifactpolicy.SourceInputParty}
+	preparedPath := recordPreparedExtractInput(t, env, m, artifactpolicy.SourceInputParty, "stable party\n")
+	paths := sessionPathsForEnv(env, m.SessionID)
+	references, err := resolveExtractReferences(paths, m, env.Config.Pipeline.Notarius, m.SessionID)
+	if err != nil {
+		t.Fatalf("resolveExtractReferences() error = %v", err)
+	}
+	first, err := materializeExtractReferenceSnapshots(paths, references)
+	if err != nil {
+		t.Fatalf("materializeExtractReferenceSnapshots(first) error = %v", err)
+	}
+	if len(first) != 1 {
+		t.Fatalf("first bindings = %#v", first)
+	}
+	firstPath := first[0].Path
+
+	oldTime := time.Unix(123, 0)
+	if err := os.Chtimes(firstPath, oldTime, oldTime); err != nil {
+		t.Fatalf("Chtimes(snapshot) error = %v", err)
+	}
+	m.RunID = "20260810T020304Z-fedcba98"
+	second, err := materializeExtractReferenceSnapshots(paths, references)
+	if err != nil {
+		t.Fatalf("materializeExtractReferenceSnapshots(second run) error = %v", err)
+	}
+	if second[0].Path != firstPath {
+		t.Fatalf("snapshot path changed across run IDs: %q != %q", second[0].Path, firstPath)
+	}
+	info, err := os.Stat(firstPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !info.ModTime().Equal(oldTime) {
+		t.Fatalf("verified snapshot was rewritten: modtime = %v, want %v", info.ModTime(), oldTime)
+	}
+
+	if err := os.Remove(firstPath); err != nil {
+		t.Fatalf("Remove(snapshot) error = %v", err)
+	}
+	if _, err := materializeExtractReferenceSnapshots(paths, references); err != nil {
+		t.Fatalf("reconstruct missing snapshot error = %v", err)
+	}
+	assertFileContents(t, firstPath, "stable party\n")
+
+	if err := os.WriteFile(firstPath, []byte("corrupt snapshot\n"), 0o664); err != nil {
+		t.Fatalf("WriteFile(corrupt snapshot) error = %v", err)
+	}
+	if _, err := materializeExtractReferenceSnapshots(paths, references); err != nil {
+		t.Fatalf("repair corrupt snapshot error = %v", err)
+	}
+	assertFileContents(t, firstPath, "stable party\n")
+
+	if err := os.WriteFile(preparedPath, []byte("changed party bytes\n"), 0o664); err != nil {
+		t.Fatalf("WriteFile(changed prepared source) error = %v", err)
+	}
+	if err := os.WriteFile(firstPath, []byte("corrupt before source mismatch\n"), 0o664); err != nil {
+		t.Fatalf("WriteFile(corrupt snapshot) error = %v", err)
+	}
+	if _, err := materializeExtractReferenceSnapshots(paths, references); err == nil || !strings.Contains(err.Error(), "prepared source") {
+		t.Fatalf("materialize with changed prepared source error = %v, want prepared-source mismatch", err)
+	}
+	assertFileContents(t, firstPath, "corrupt before source mismatch\n")
+
+	changedChecksum, err := artifacts.SHA256File(preparedPath)
+	if err != nil {
+		t.Fatalf("SHA256File(changed prepared source) error = %v", err)
+	}
+	descriptor, _ := artifactpolicy.DescribePreparedInputSource(artifactpolicy.SourceInputParty)
+	for index := range m.Inputs {
+		if m.Inputs[index].Kind == descriptor.ManifestKind {
+			m.Inputs[index].Checksum = changedChecksum
+		}
+	}
+	changed, err := resolveExtractReferences(paths, m, env.Config.Pipeline.Notarius, m.SessionID)
+	if err != nil {
+		t.Fatalf("resolveExtractReferences(changed) error = %v", err)
+	}
+	changedBindings, err := materializeExtractReferenceSnapshots(paths, changed)
+	if err != nil {
+		t.Fatalf("materializeExtractReferenceSnapshots(changed) error = %v", err)
+	}
+	if changedBindings[0].Path == firstPath || filepath.Base(changedBindings[0].Path) != filepath.Base(firstPath) {
+		t.Fatalf("changed bytes paths = old %q new %q, want new digest path with same basename", firstPath, changedBindings[0].Path)
+	}
+	assertFileContents(t, firstPath, "corrupt before source mismatch\n")
+	assertFileContents(t, changedBindings[0].Path, "changed party bytes\n")
+}
+
+func TestExtractReferenceSnapshotsDeduplicateEquivalentDestinations(t *testing.T) {
+	env, m, _ := setupExtractEnv(t)
+	path := recordPreparedExtractInput(t, env, m, artifactpolicy.SourceInputParty, "shared bytes\n")
+	checksum, err := artifacts.SHA256File(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	identity := extractReferenceIdentity{
+		Selector: "party", SourceID: artifactpolicy.SourceInputParty, Path: "inputs/party.yml",
+		Checksum: checksum, SizeBytes: int64(len("shared bytes\n")),
+	}
+	references := resolvedExtractReferences{
+		Bindings: []notarius.ReferenceBinding{{Selector: "party"}, {Selector: "alternate"}},
+		Identities: []extractReferenceIdentity{
+			identity,
+			{Selector: "alternate", SourceID: artifactpolicy.SourceInputGlossary, Path: identity.Path, Checksum: checksum, SizeBytes: identity.SizeBytes},
+		},
+	}
+	bindings, err := materializeExtractReferenceSnapshots(sessionPathsForEnv(env, m.SessionID), references)
+	if err != nil {
+		t.Fatalf("materializeExtractReferenceSnapshots() error = %v", err)
+	}
+	if len(bindings) != 2 || bindings[0].Path != bindings[1].Path {
+		t.Fatalf("equivalent bindings = %#v, want shared destination", bindings)
+	}
+}
+
+func TestExtractReferenceSnapshotsWithRelativeWorkspace(t *testing.T) {
+	env, m, _ := setupExtractEnv(t)
+	prepared := recordPreparedExtractInput(t, env, m, artifactpolicy.SourceInputParty, "party bytes\n")
+	env.Config.Pipeline.Notarius.References = map[string]string{"party": artifactpolicy.SourceInputParty}
+	absPaths := sessionPathsForEnv(env, m.SessionID)
+	references, err := resolveExtractReferences(absPaths, m, env.Config.Pipeline.Notarius, m.SessionID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Chdir(env.Config.Pipeline.Workspace.Root)
+	paths := artifacts.NewLocalStore(".").SessionPathsFor(m.Campaign, m.SessionID)
+	first, err := materializeExtractReferenceSnapshots(paths, references)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !filepath.IsAbs(first[0].Path) {
+		t.Fatalf("adapter reference remains relative: %q", first[0].Path)
+	}
+	m.RunID = "20260809T020203Z-abcdef13"
+	second, err := materializeExtractReferenceSnapshots(paths, references)
+	if err != nil || !reflect.DeepEqual(first, second) {
+		t.Fatalf("second invocation bindings = %#v, error = %v", second, err)
+	}
+	if err := verifyExtractReferenceSnapshots(paths, references); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := os.Stat(filepath.Join(absPaths.Root, paths.Root)); !errors.Is(err, os.ErrNotExist) {
+		t.Fatalf("duplicated session prefix exists or cannot be inspected: %v", err)
+	}
+
+	// A controlled executable proves the production adapter accepts the paths.
+	// It intentionally produces no receipt; receipt validation is covered elsewhere.
+	marker := filepath.Join(t.TempDir(), "started")
+	binary := filepath.Join(t.TempDir(), "notarius")
+	if err := os.WriteFile(binary, []byte("#!/bin/sh\nprintf started > '"+marker+"'\n"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	diagnostics := t.TempDir()
+	_, err = notarius.NewSubprocessRunner().Run(context.Background(), notarius.RunRequest{
+		Binary: binary, PipelineID: "dnd-session", ConfigPath: env.Config.Pipeline.Notarius.ConfigPath,
+		InputPath: prepared, OutputRoot: t.TempDir(), WorkingDirectory: env.Config.Pipeline.Workspace.Root,
+		Timeout: time.Second * 10, References: first,
+		ReceiptPath: filepath.Join(diagnostics, "receipt.json"), LogPath: filepath.Join(diagnostics, "stderr.log"),
+	})
+	if err == nil {
+		t.Fatal("expected missing receipt error")
+	}
+	if _, err := os.Stat(marker); err != nil {
+		t.Fatalf("adapter did not launch with the snapshot bindings: %v", err)
+	}
+
+	// A symlink on the actual cache path must not be missed by a duplicated walk.
+	if err := os.Remove(first[0].Path); err != nil {
+		t.Fatal(err)
+	}
+	digestDir := filepath.Dir(first[0].Path)
+	if err := os.Remove(digestDir); err != nil {
+		t.Fatal(err)
+	}
+	outside := t.TempDir()
+	if err := os.Symlink(outside, digestDir); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := materializeExtractReferenceSnapshots(paths, references); err == nil {
+		t.Fatal("accepted symlink on actual cache path")
+	}
+	if _, err := os.Stat(filepath.Join(outside, filepath.Base(first[0].Path))); !errors.Is(err, os.ErrNotExist) {
+		t.Fatalf("unsafe cache path wrote outside session: %v", err)
+	}
+}
+
+func TestExtractReferenceSnapshotsRejectUnsafeConflicts(t *testing.T) {
+	for _, test := range []struct {
+		name  string
+		setup func(*testing.T, artifacts.SessionPaths, string)
+	}{
+		{name: "leaf symlink", setup: func(t *testing.T, _ artifacts.SessionPaths, destination string) {
+			if err := os.MkdirAll(filepath.Dir(destination), 0o775); err != nil {
+				t.Fatal(err)
+			}
+			if err := os.Symlink(filepath.Join(t.TempDir(), "outside"), destination); err != nil {
+				t.Fatal(err)
+			}
+		}},
+		{name: "leaf directory", setup: func(t *testing.T, _ artifacts.SessionPaths, destination string) {
+			if err := os.MkdirAll(destination, 0o775); err != nil {
+				t.Fatal(err)
+			}
+		}},
+		{name: "digest symlink", setup: func(t *testing.T, paths artifacts.SessionPaths, destination string) {
+			cacheRoot := artifacts.SessionNotariusReferenceCacheDir(paths)
+			if err := os.MkdirAll(cacheRoot, 0o775); err != nil {
+				t.Fatal(err)
+			}
+			if err := os.Symlink(t.TempDir(), filepath.Dir(destination)); err != nil {
+				t.Fatal(err)
+			}
+		}},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			env, m, _ := setupExtractEnv(t)
+			env.Config.Pipeline.Notarius.References = map[string]string{"party": artifactpolicy.SourceInputParty}
+			recordPreparedExtractInput(t, env, m, artifactpolicy.SourceInputParty, "party bytes\n")
+			paths := sessionPathsForEnv(env, m.SessionID)
+			references, err := resolveExtractReferences(paths, m, env.Config.Pipeline.Notarius, m.SessionID)
+			if err != nil {
+				t.Fatal(err)
+			}
+			destination, err := extractReferenceSnapshotDestination(paths, references.Identities[0])
+			if err != nil {
+				t.Fatal(err)
+			}
+			test.setup(t, paths, destination)
+			_, err = materializeExtractReferenceSnapshots(paths, references)
+			if err == nil || !strings.Contains(err.Error(), artifacts.SessionNotariusReferenceCacheDir(paths)) || !strings.Contains(err.Error(), "session is inactive") {
+				t.Fatalf("materializeExtractReferenceSnapshots() error = %v, want actionable unsafe-path failure for %q", err, destination)
+			}
+		})
+	}
+}
+
+func assertFileContents(t *testing.T, path, want string) {
+	t.Helper()
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("ReadFile(%q) error = %v", path, err)
+	}
+	if string(data) != want {
+		t.Fatalf("ReadFile(%q) = %q, want %q", path, data, want)
+	}
 }
 
 func TestExtractStageRejectsUnavailableReferenceBeforeInvocationOrRunDirectoryCreation(t *testing.T) {
@@ -630,6 +983,60 @@ func TestExtractionFingerprintIsIndependentOfOutputMapOrder(t *testing.T) {
 	}
 }
 
+func TestExtractionFingerprintBaseSelectorsPreservePriorPayloadShape(t *testing.T) {
+	input := artifacts.ExtractionInputIdentity{
+		Checksum: "checksum", SourceID: artifacts.ArtifactTranscriptFinalTrimmed,
+		ProducerStage: "trim", OutputKind: artifacts.TranscriptOutputKindFinalTrimmed,
+		ProducerRunID: "trim-run", Provenance: "manifest.trim.outputs",
+	}
+	references := []extractReferenceIdentity{{
+		Selector: "party", SourceID: artifactpolicy.SourceInputParty,
+		Path: "inputs/party.yml", Checksum: "party-checksum", SizeBytes: 34,
+	}}
+	cfg := &config.NotariusConfig{
+		PipelineID: "pipeline",
+		Outputs: map[string]config.NotariusOutputConfig{
+			"alpha": {LaneID: "a", MediaType: "application/json", SchemaID: "a", SchemaVersion: "v1"},
+		},
+	}
+	legacyPayload, err := json.Marshal(struct {
+		PipelineID string                            `json:"pipeline_id"`
+		Input      artifacts.ExtractionInputIdentity `json:"input"`
+		References []extractReferenceIdentity        `json:"references"`
+		Outputs    []fingerprintOutput               `json:"outputs"`
+	}{
+		PipelineID: cfg.PipelineID,
+		Input:      input,
+		References: references,
+		Outputs: []fingerprintOutput{{
+			Key: "alpha", LaneID: "a", MediaType: "application/json", SchemaID: "a", SchemaVersion: "v1",
+		}},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	legacyDigest := sha256.Sum256(legacyPayload)
+	want := hex.EncodeToString(legacyDigest[:])
+	for _, profile := range []*string{nil, stringPointerForExtractTest(""), stringPointerForExtractTest("default")} {
+		cfg.ConfigProfile = profile
+		got, err := extractionFingerprint(cfg, input, references)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if got != want {
+			t.Fatalf("base selection fingerprint = %q, want prior no-profile payload digest %q", got, want)
+		}
+	}
+	cfg.ConfigProfile = stringPointerForExtractTest("inexpensive")
+	named, err := extractionFingerprint(cfg, input, references)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if named == want {
+		t.Fatal("named selection retained prior no-profile fingerprint")
+	}
+}
+
 func TestExtractStageResumeValidationAcceptsCurrentImmutableResult(t *testing.T) {
 	env, m, _ := setupExtractEnv(t)
 	env.Config.Pipeline.Notarius.References = map[string]string{
@@ -648,6 +1055,31 @@ func TestExtractStageResumeValidationAcceptsCurrentImmutableResult(t *testing.T)
 	}
 }
 
+func TestExtractStageResumeValidationTracksConfigProfile(t *testing.T) {
+	env, m, _ := setupExtractEnv(t)
+	selected := "inexpensive"
+	env.Config.Pipeline.Notarius.ConfigProfile = &selected
+	seedSucceededExtractResult(t, env, m)
+
+	validation, err := (extractStage{}).ValidateResume(context.Background(), env, m)
+	if err != nil {
+		t.Fatalf("ValidateResume(same selection) error = %v", err)
+	}
+	if !validation.Resumable {
+		t.Fatalf("same selection validation = %#v, want reusable recorded bundle", validation)
+	}
+
+	changed := "experimental"
+	env.Config.Pipeline.Notarius.ConfigProfile = &changed
+	validation, err = (extractStage{}).ValidateResume(context.Background(), env, m)
+	if err != nil {
+		t.Fatalf("ValidateResume(changed selection) error = %v", err)
+	}
+	if validation.Resumable || !strings.Contains(validation.Reason, "invocation contract changed") {
+		t.Fatalf("changed selection validation = %#v, want non-resumable invocation evidence", validation)
+	}
+}
+
 func TestExtractStageResumeValidationRejectsChangedPreparedReferenceIdentity(t *testing.T) {
 	env, m, _ := setupExtractEnv(t)
 	env.Config.Pipeline.Notarius.References = map[string]string{
@@ -936,6 +1368,8 @@ type extractFixture struct {
 	inputPath string
 }
 
+func stringPointerForExtractTest(value string) *string { return &value }
+
 func extractFixtureFromEnv(t *testing.T, env *Env, m *manifest.Manifest) extractFixture {
 	t.Helper()
 	paths := sessionPathsForEnv(env, m.SessionID)

internal/stage/merge.go

@@ -306,6 +306,12 @@ func normalizeMergeInputs(
 }
 
 func discoverRawTranscripts(m *manifest.Manifest, paths artifacts.SessionPaths) ([]string, error) {
+	if record, versioned, err := transcribeManifestState(m); err != nil {
+		return nil, err
+	} else if versioned {
+		return discoverVersionedRawTranscripts(record, paths)
+	}
+
 	fromManifest := make([]string, 0)
 	if m != nil && m.Stages != nil {
 		if tr := m.Stages["transcribe"]; tr != nil {
@@ -350,6 +356,64 @@ func discoverRawTranscripts(m *manifest.Manifest, paths artifacts.SessionPaths)
 	return dedupeAndSortPaths(out), nil
 }
 
+func discoverVersionedRawTranscripts(
+	record *manifest.StageRecord,
+	paths artifacts.SessionPaths,
+) ([]string, error) {
+	if record.Status != manifest.StatusSucceeded {
+		return nil, fmt.Errorf("versioned transcribe state is not aggregate-successful (status %q)", record.Status)
+	}
+	if err := manifest.ValidateTranscribeSpeakerCollection(
+		record.TranscribeStateVersion,
+		record.TranscribeSpeakers,
+	); err != nil {
+		return nil, fmt.Errorf("validate versioned transcribe state: %w", err)
+	}
+	if len(record.TranscribeSpeakers) == 0 {
+		return nil, fmt.Errorf("versioned transcribe state has no completed speakers")
+	}
+
+	expected := make(map[string]string, len(record.TranscribeSpeakers))
+	for speaker, speakerRecord := range record.TranscribeSpeakers {
+		path := filepath.Clean(artifacts.ResolveSessionLocalPathForRead(paths, speakerRecord.Output.LocalPath))
+		if other, exists := expected[path]; exists {
+			return nil, fmt.Errorf("versioned transcribe speakers %q and %q declare the same output", other, speaker)
+		}
+		expected[path] = speaker
+	}
+	inputs := make([]string, 0, len(expected))
+	for _, output := range record.Outputs {
+		if output.Kind != "transcript_raw" {
+			continue
+		}
+		path := strings.TrimSpace(output.LocalPath)
+		if path == "" {
+			return nil, fmt.Errorf("versioned transcribe aggregate output has an empty local path")
+		}
+		path = filepath.Clean(artifacts.ResolveSessionLocalPathForRead(paths, path))
+		speaker, declared := expected[path]
+		if !declared {
+			return nil, fmt.Errorf("versioned transcribe aggregate output %q is not declared by current speaker state", output.LocalPath)
+		}
+		if speaker == "" {
+			return nil, fmt.Errorf("versioned transcribe aggregate output %q is duplicated", output.LocalPath)
+		}
+		expected[path] = ""
+		inputs = append(inputs, path)
+	}
+	missing := make([]string, 0)
+	for _, speaker := range expected {
+		if speaker != "" {
+			missing = append(missing, speaker)
+		}
+	}
+	if len(missing) > 0 {
+		sort.Strings(missing)
+		return nil, fmt.Errorf("versioned transcribe aggregate outputs are incomplete for speakers: %s", strings.Join(missing, ", "))
+	}
+	return dedupeAndSortPaths(inputs), nil
+}
+
 func dedupeAndSortPaths(paths []string) []string {
 	if len(paths) == 0 {
 		return nil

internal/stage/merge_test.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"slices"
 	"strings"
 	"testing"
 	"time"
@@ -191,6 +192,70 @@ func TestMergeStageFallsBackToRawDirectoryWhenTranscribeOutputsMissing(t *testin
 	}
 }
 
+func TestMergeStageRejectsPartialVersionedTranscribeState(t *testing.T) {
+	env, m := setupMergeEnv(t)
+	paths := sessionPathsForEnv(env, m.SessionID)
+	writeFile(t, filepath.Join(paths.TranscriptsRawDir, "alice.json"), `{"segments":[]}`)
+	writeFile(t, filepath.Join(paths.TranscriptsRawDir, "uncommitted.json"), `{"segments":[]}`)
+	writeFile(t, filepath.Join(paths.InputsDir, "speakers.yml"), "match: []\n")
+	writeFile(t, filepath.Join(paths.InputsDir, "autocorrect.yml"), "rules: []\n")
+	setVersionedTranscribeMergeState(t, m, manifest.StatusFailed, map[string]string{
+		"alice": "transcripts/raw/alice.json",
+	})
+	fake := &seriatim.FakeRunner{}
+	env.Seriatim = fake
+
+	_, err := (mergeStage{}).Run(context.Background(), env, m)
+	if err == nil || !strings.Contains(err.Error(), "not aggregate-successful") {
+		t.Fatalf("merge.Run() error = %v, want incomplete aggregate rejection", err)
+	}
+	if len(fake.Requests) != 0 || len(fake.NormalizeRequests) != 0 {
+		t.Fatalf("adapter requests = %#v / %#v, want none", fake.Requests, fake.NormalizeRequests)
+	}
+}
+
+func TestMergeStageUsesOnlyCurrentVersionedAggregateOutputs(t *testing.T) {
+	env, m := setupMergeEnv(t)
+	paths := sessionPathsForEnv(env, m.SessionID)
+	alice := filepath.Join(paths.TranscriptsRawDir, "alice.json")
+	writeFile(t, alice, `{"segments":[]}`)
+	writeFile(t, filepath.Join(paths.TranscriptsRawDir, "removed.json"), `{"segments":[]}`)
+	writeFile(t, filepath.Join(paths.InputsDir, "speakers.yml"), "match: []\n")
+	writeFile(t, filepath.Join(paths.InputsDir, "autocorrect.yml"), "rules: []\n")
+	setVersionedTranscribeMergeState(t, m, manifest.StatusSucceeded, map[string]string{
+		"alice": "transcripts/raw/alice.json",
+	})
+	fake := &seriatim.FakeRunner{}
+	env.Seriatim = fake
+
+	if _, err := (mergeStage{}).Run(context.Background(), env, m); err != nil {
+		t.Fatalf("merge.Run() error = %v", err)
+	}
+	if len(fake.NormalizeRequests) != 1 || fake.NormalizeRequests[0].InputTranscriptPath != alice {
+		t.Fatalf("normalize requests = %#v, want only current alice", fake.NormalizeRequests)
+	}
+}
+
+func TestMergeStageRejectsIncompleteVersionedAggregateOutputs(t *testing.T) {
+	env, m := setupMergeEnv(t)
+	paths := sessionPathsForEnv(env, m.SessionID)
+	writeFile(t, filepath.Join(paths.TranscriptsRawDir, "alice.json"), `{"segments":[]}`)
+	writeFile(t, filepath.Join(paths.TranscriptsRawDir, "bob.json"), `{"segments":[]}`)
+	writeFile(t, filepath.Join(paths.InputsDir, "speakers.yml"), "match: []\n")
+	writeFile(t, filepath.Join(paths.InputsDir, "autocorrect.yml"), "rules: []\n")
+	setVersionedTranscribeMergeState(t, m, manifest.StatusSucceeded, map[string]string{
+		"alice": "transcripts/raw/alice.json",
+		"bob":   "transcripts/raw/bob.json",
+	})
+	m.Stages["transcribe"].Outputs = m.Stages["transcribe"].Outputs[:1]
+	env.Seriatim = &seriatim.FakeRunner{}
+
+	_, err := (mergeStage{}).Run(context.Background(), env, m)
+	if err == nil || !strings.Contains(err.Error(), "incomplete for speakers: bob") {
+		t.Fatalf("merge.Run() error = %v, want incomplete aggregate output rejection", err)
+	}
+}
+
 func TestMergeStageResolvesWorkspaceQualifiedManifestOutputsWithoutDuplication(t *testing.T) {
 	env, m := setupMergeEnvWithRelativeWorkspaceRoot(t)
 	paths := sessionPathsForEnv(env, m.SessionID)
@@ -414,3 +479,44 @@ func setupMergeEnvWithWorkspace(t *testing.T, workspace string) (*Env, *manifest
 		ArtifactStore: store,
 	}, manifest.New("2026-05-03", time.Now().UTC())
 }
+
+func setVersionedTranscribeMergeState(
+	t *testing.T,
+	m *manifest.Manifest,
+	status manifest.StageStatus,
+	outputs map[string]string,
+) {
+	t.Helper()
+	if m.RunID == "" {
+		m.RunID = "20260503T010203Z-a1b2c3d4"
+	}
+	aggregate := make([]manifest.ArtifactRecord, 0, len(outputs))
+	records := make(map[string]manifest.TranscribeSpeakerRecord, len(outputs))
+	for speaker, outputPath := range outputs {
+		output := manifest.ArtifactRecord{
+			Kind: "transcript_raw", LocalPath: outputPath,
+			ProducerRunID: m.RunID, Checksum: strings.Repeat("b", 64),
+		}
+		aggregate = append(aggregate, output)
+		records[speaker] = manifest.TranscribeSpeakerRecord{
+			FingerprintVersion: manifest.TranscribeFingerprintContractVersion,
+			Fingerprint:        strings.Repeat("c", 64),
+			AudioPath:          "audio/" + speaker + ".flac",
+			AudioSHA256:        strings.Repeat("a", 64),
+			AudioSize:          1,
+			Output:             output,
+			OutputSize:         1,
+			ProducerRunID:      m.RunID,
+		}
+	}
+	slices.SortFunc(aggregate, func(a, b manifest.ArtifactRecord) int {
+		return strings.Compare(a.LocalPath, b.LocalPath)
+	})
+	m.MarkStageSucceeded("transcribe", time.Now().UTC(), aggregate)
+	record := m.Stages["transcribe"]
+	record.TranscribeStateVersion = manifest.TranscribeStateContractVersion
+	record.TranscribeSpeakers = records
+	if status != manifest.StatusSucceeded {
+		m.MarkStageFailed("transcribe", time.Now().UTC(), "incomplete")
+	}
+}

internal/stage/notarius_cache_integration_test.go

@@ -0,0 +1,379 @@
+package stage
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync/atomic"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/adapters/notarius"
+	"gitea.maximumdirect.net/eric/narratio/internal/artifactmodel"
+	"gitea.maximumdirect.net/eric/narratio/internal/artifactpolicy"
+	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
+	"gitea.maximumdirect.net/eric/narratio/internal/config"
+	"gitea.maximumdirect.net/eric/narratio/internal/manifest"
+)
+
+const notariusIntegrationBinaryEnv = "NARRATIO_TEST_NOTARIUS_BINARY"
+
+// Run with:
+// NARRATIO_TEST_NOTARIUS_BINARY=/absolute/path/to/notarius GOWORK=off go test ./internal/stage -run '^TestNotariusCacheReuseIntegration$' -count=1 -v
+func TestNotariusCacheReuseIntegration(t *testing.T) {
+	binary := strings.TrimSpace(os.Getenv(notariusIntegrationBinaryEnv))
+	if binary == "" {
+		t.Skipf("set %s to an absolute Notarius v0.7.0-compatible executable to run this integration test", notariusIntegrationBinaryEnv)
+	}
+	if !filepath.IsAbs(binary) {
+		t.Fatalf("%s = %q, want an absolute path", notariusIntegrationBinaryEnv, binary)
+	}
+	info, err := os.Stat(binary)
+	if err != nil {
+		t.Fatalf("inspect %s: %v", notariusIntegrationBinaryEnv, err)
+	}
+	if !info.Mode().IsRegular() || info.Mode().Perm()&0o111 == 0 {
+		t.Fatalf("%s = %q, want an executable regular file", notariusIntegrationBinaryEnv, binary)
+	}
+
+	t.Run("reuse reference identity and forced refresh", func(t *testing.T) {
+		provider := newNotariusIntegrationProvider(t)
+		env, runManifest, fixture := newNotariusIntegrationFixture(t, binary, provider.URL(), "dnd-session")
+
+		first := runNotariusIntegrationExtraction(t, env, runManifest, "20260916T010101Z-a0000001", false)
+		if got := provider.Calls(); got != 2 {
+			t.Fatalf("first provider calls = %d, want 2", got)
+		}
+		if first.ChunkPlan == nil || first.ChunkPlan.Action != "generated" {
+			t.Fatalf("first chunk plan = %#v, want generated", first.ChunkPlan)
+		}
+
+		env.Config.Pipeline.Notarius.Resume = true
+		second := runNotariusIntegrationExtraction(t, env, runManifest, "20260916T010102Z-a0000002", false)
+		if got := provider.Calls(); got != 2 {
+			t.Fatalf("resumed provider calls = %d, want unchanged count 2", got)
+		}
+		assertNotariusIntegrationDecision(t, second, "extract", "spells-first", "reused", "checkpoint_reused")
+		assertNotariusIntegrationDecision(t, second, "extract", "spells-second", "reused", "checkpoint_reused")
+
+		oldSnapshot := notariusIntegrationSnapshotPath(t, env, runManifest, artifactpolicy.SourceInputParty)
+		setNotariusIntegrationReference(t, runManifest, fixture.partyPath, "The party now travels with a silver dragon.\n")
+		third := runNotariusIntegrationExtraction(t, env, runManifest, "20260916T010103Z-a0000003", false)
+		if got := provider.Calls(); got != 4 {
+			t.Fatalf("changed-reference provider calls = %d, want 4", got)
+		}
+		assertNotariusIntegrationDecision(t, third, "extract", "spells-first", "executed", "checkpoint_missing")
+		newSnapshot := notariusIntegrationSnapshotPath(t, env, runManifest, artifactpolicy.SourceInputParty)
+		if newSnapshot == oldSnapshot {
+			t.Fatalf("changed reference retained snapshot %q", newSnapshot)
+		}
+		for _, path := range []string{oldSnapshot, newSnapshot} {
+			if _, err := os.Stat(path); err != nil {
+				t.Fatalf("snapshot %q is unavailable: %v", path, err)
+			}
+		}
+
+		setNotariusIntegrationTranscript(t, runManifest, fixture.transcriptPath, notariusIntegrationTranscript("session-unrelated", "The wizard studies Magic Missile."))
+		unrelated := runNotariusIntegrationExtraction(t, env, runManifest, "20260916T010104Z-a0000004", false)
+		if unrelated.ChunkPlan == nil || unrelated.ChunkPlan.Action != "generated" {
+			t.Fatalf("unrelated chunk plan = %#v, want generated", unrelated.ChunkPlan)
+		}
+		unrelatedPlan := filepath.Join(fixture.chunkRoot, strings.TrimPrefix(unrelated.ChunkPlan.SourceDigest, "sha256:"), "plan.json")
+		unrelatedBefore, err := os.ReadFile(unrelatedPlan)
+		if err != nil {
+			t.Fatalf("read unrelated chunk plan: %v", err)
+		}
+
+		setNotariusIntegrationTranscript(t, runManifest, fixture.transcriptPath, notariusIntegrationTranscript("session-cache", "Aria casts Cure Wounds."))
+		forced := runNotariusIntegrationExtraction(t, env, runManifest, "20260916T010105Z-a0000005", true)
+		if got := provider.Calls(); got != 8 {
+			t.Fatalf("forced provider calls = %d, want 8", got)
+		}
+		if len(forced.CheckpointDecisions) != 0 {
+			t.Fatalf("forced extraction loaded checkpoint state: %#v", forced.CheckpointDecisions)
+		}
+		if forced.ChunkPlan == nil || forced.ChunkPlan.Action != "refreshed" {
+			t.Fatalf("forced chunk plan = %#v, want refreshed", forced.ChunkPlan)
+		}
+		unrelatedAfter, err := os.ReadFile(unrelatedPlan)
+		if err != nil {
+			t.Fatalf("read unrelated chunk plan after refresh: %v", err)
+		}
+		if string(unrelatedAfter) != string(unrelatedBefore) {
+			t.Fatal("forced refresh changed the unrelated input's cached plan")
+		}
+	})
+
+	t.Run("partial failure resumes accepted predecessor", func(t *testing.T) {
+		provider := newNotariusIntegrationProvider(t)
+		provider.FailRequest(2)
+		env, runManifest, _ := newNotariusIntegrationFixture(t, binary, provider.URL(), "dnd-recovery")
+		env.Config.Pipeline.Notarius.Resume = true
+
+		runManifest.RunID = "20260916T020101Z-b0000001"
+		env.Force = false
+		if result, err := (extractStage{}).Run(context.Background(), env, runManifest); err == nil || result != nil {
+			t.Fatalf("partial extraction result = %#v error = %v, want failure", result, err)
+		}
+		if got := provider.Calls(); got != 2 {
+			t.Fatalf("failed invocation provider calls = %d, want 2", got)
+		}
+
+		provider.FailRequest(0)
+		recovered := runNotariusIntegrationExtraction(t, env, runManifest, "20260916T020102Z-b0000002", false)
+		if got := provider.Calls(); got != 3 {
+			t.Fatalf("recovery provider calls = %d, want one additional call (3 total)", got)
+		}
+		assertNotariusIntegrationDecision(t, recovered, "extract", "spells-first", "reused", "checkpoint_reused")
+		assertNotariusIntegrationDecision(t, recovered, "extract", "spells-second", "executed", "")
+	})
+}
+
+type notariusIntegrationProvider struct {
+	server *httptest.Server
+	calls  atomic.Int64
+	failAt atomic.Int64
+}
+
+func newNotariusIntegrationProvider(t *testing.T) *notariusIntegrationProvider {
+	t.Helper()
+	provider := &notariusIntegrationProvider{}
+	provider.server = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, request *http.Request) {
+		call := provider.calls.Add(1)
+		if request.Method != http.MethodPost || request.URL.Path != "/v1/chat/completions" {
+			t.Errorf("provider request = %s %s, want POST /v1/chat/completions", request.Method, request.URL.Path)
+			http.Error(w, "unexpected request", http.StatusNotFound)
+			return
+		}
+		if provider.failAt.Load() == call {
+			http.Error(w, "controlled provider failure", http.StatusInternalServerError)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"id":"local-completion","object":"chat.completion","created":1,"model":"local-model","choices":[{"index":0,"message":{"role":"assistant","content":"{\"spell_casts\":[]}"},"finish_reason":"stop"}],"usage":{"prompt_tokens":10,"completion_tokens":4,"total_tokens":14}}`))
+	}))
+	t.Cleanup(provider.server.Close)
+	return provider
+}
+
+func (p *notariusIntegrationProvider) URL() string               { return p.server.URL }
+func (p *notariusIntegrationProvider) Calls() int64              { return p.calls.Load() }
+func (p *notariusIntegrationProvider) FailRequest(request int64) { p.failAt.Store(request) }
+
+type notariusIntegrationFixture struct {
+	transcriptPath string
+	partyPath      string
+	chunkRoot      string
+}
+
+func newNotariusIntegrationFixture(t *testing.T, binary, endpoint, pipelineID string) (*Env, *manifest.Manifest, notariusIntegrationFixture) {
+	t.Helper()
+	env, runManifest, _ := setupExtractEnv(t)
+	initialOutput := artifacts.SessionRunNotariusOutputRootForCampaign(
+		env.Config.Pipeline.Workspace.Root, runManifest.Campaign, runManifest.SessionID, runManifest.RunID,
+	)
+	if err := os.RemoveAll(initialOutput); err != nil {
+		t.Fatalf("remove synthetic output fixture: %v", err)
+	}
+
+	root := env.Config.Pipeline.Workspace.Root
+	profilePath := filepath.Join(root, "local-profile.yml")
+	if err := os.WriteFile(profilePath, []byte("id: local-test\nbackend: local\nmodel: local-model\ntimeout_seconds: 30\n"), 0o600); err != nil {
+		t.Fatalf("write local profile: %v", err)
+	}
+	chunkRoot := filepath.Join(root, "notarius-cache", "chunk-plans")
+	checkpointRoot := filepath.Join(root, "notarius-cache", "checkpoints")
+	configPath := filepath.Join(root, "notarius-integration.yml")
+	content := fmt.Sprintf(`version: 5
+promptkit:
+  profile_file: %q
+  local_backend:
+    endpoint: %q
+    concurrency_limit: 1
+concurrency:
+  total_llm: 1
+  stage_workers:
+    extract: 1
+output:
+  directory: %q
+cache:
+  chunk_plans:
+    mode: auto
+    directory: %q
+  checkpoints:
+    enabled: true
+    directory: %q
+pipelines:
+  %s:
+    llm_profile: local-test
+    input:
+      module: seriatim
+    chunk:
+      module: generic
+    output:
+      module: json
+    steps:
+      - id: collect-first
+        artifacts:
+          spells-first:
+            extract:
+              module: dnd/spells
+            normalize:
+              module: dnd/spells
+      - id: collect-second
+        artifacts:
+          spells-second:
+            extract:
+              module: dnd/spells
+            normalize:
+              module: dnd/spells
+`, profilePath, endpoint+"/v1", filepath.Join(root, "unused-output"), chunkRoot, checkpointRoot, pipelineID)
+	if err := os.WriteFile(configPath, []byte(content), 0o600); err != nil {
+		t.Fatalf("write Notarius integration config: %v", err)
+	}
+
+	transcriptPath := filepath.Join(sessionPathsForEnv(env, runManifest.SessionID).ArtifactsDir, "trimmed.from-manifest.json")
+	setNotariusIntegrationTranscript(t, runManifest, transcriptPath, notariusIntegrationTranscript("session-cache", "Aria casts Cure Wounds."))
+	partyPath := recordPreparedExtractInput(t, env, runManifest, artifactpolicy.SourceInputParty, "The party includes Aria the cleric.\n")
+	env.Notarius = notarius.NewSubprocessRunner()
+	env.Config.Pipeline.Notarius = &config.NotariusConfig{
+		Enabled: true, Binary: binary, ConfigPath: configPath, PipelineID: pipelineID,
+		Timeout: "2m", WorkingDirectory: root, ChunkCache: "auto",
+		References: map[string]string{"party": artifactpolicy.SourceInputParty},
+		Outputs: map[string]config.NotariusOutputConfig{
+			"spells_first": {
+				LaneID: "spells-first", MediaType: "application/json", ModuleKey: "dnd/spells",
+				SchemaID: "notarius.dnd.spells", SchemaVersion: "v1",
+			},
+			"spells_second": {
+				LaneID: "spells-second", MediaType: "application/json", ModuleKey: "dnd/spells",
+				SchemaID: "notarius.dnd.spells", SchemaVersion: "v1",
+			},
+		},
+	}
+	return env, runManifest, notariusIntegrationFixture{transcriptPath: transcriptPath, partyPath: partyPath, chunkRoot: chunkRoot}
+}
+
+func notariusIntegrationTranscript(id, text string) []byte {
+	return []byte(fmt.Sprintf(`{"metadata":{"id":%q,"title":"Cache integration"},"segments":[{"id":1,"start":0,"end":4,"speaker":"Aria","text":%q}]}`, id, text))
+}
+
+func setNotariusIntegrationTranscript(t *testing.T, runManifest *manifest.Manifest, path string, content []byte) {
+	t.Helper()
+	if err := os.WriteFile(path, content, 0o644); err != nil {
+		t.Fatalf("write integration transcript: %v", err)
+	}
+	checksum, err := artifacts.SHA256File(path)
+	if err != nil {
+		t.Fatalf("checksum integration transcript: %v", err)
+	}
+	record := runManifest.Stages["trim"]
+	if record == nil || len(record.Outputs) != 1 {
+		t.Fatalf("trim record = %#v, want one output", record)
+	}
+	record.Outputs[0].Kind = artifactmodel.TranscriptOutputKindFinalTrimmed
+	record.Outputs[0].SourceID = artifactmodel.SourceTranscriptFinalTrimmed
+	record.Outputs[0].LocalPath = path
+	record.Outputs[0].Checksum = checksum
+}
+
+func setNotariusIntegrationReference(t *testing.T, runManifest *manifest.Manifest, path, content string) {
+	t.Helper()
+	descriptor, ok := artifactpolicy.DescribePreparedInputSource(artifactpolicy.SourceInputParty)
+	if !ok {
+		t.Fatal("prepared party input descriptor is unavailable")
+	}
+	if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
+		t.Fatalf("write integration reference: %v", err)
+	}
+	checksum, err := artifacts.SHA256File(path)
+	if err != nil {
+		t.Fatalf("checksum integration reference: %v", err)
+	}
+	for index := range runManifest.Inputs {
+		if runManifest.Inputs[index].Kind == descriptor.ManifestKind {
+			runManifest.Inputs[index].Checksum = checksum
+			return
+		}
+	}
+	t.Fatalf("prepared party input not found in %#v", runManifest.Inputs)
+}
+
+func notariusIntegrationSnapshotPath(t *testing.T, env *Env, runManifest *manifest.Manifest, sourceID string) string {
+	t.Helper()
+	descriptor, ok := artifactpolicy.DescribePreparedInputSource(sourceID)
+	if !ok {
+		t.Fatalf("prepared input descriptor %q is unavailable", sourceID)
+	}
+	for _, input := range runManifest.Inputs {
+		if input.Kind != descriptor.ManifestKind {
+			continue
+		}
+		path, err := artifacts.SessionNotariusReferenceSnapshotPath(
+			sessionPathsForEnv(env, runManifest.SessionID), input.Checksum, filepath.Base(input.Path),
+		)
+		if err != nil {
+			t.Fatalf("resolve integration snapshot: %v", err)
+		}
+		return path
+	}
+	t.Fatalf("prepared input %q not found", sourceID)
+	return ""
+}
+
+func runNotariusIntegrationExtraction(t *testing.T, env *Env, runManifest *manifest.Manifest, runID string, force bool) notariusIntegrationRunManifest {
+	t.Helper()
+	runManifest.RunID = runID
+	env.Force = force
+	result, err := (extractStage{}).Run(context.Background(), env, runManifest)
+	if err != nil {
+		receiptPath := artifacts.SessionRunNotariusReceiptPathForCampaign(env.Config.Pipeline.Workspace.Root, runManifest.Campaign, runManifest.SessionID, runID)
+		if data, readErr := os.ReadFile(receiptPath); readErr == nil {
+			t.Logf("failed Notarius receipt: %s", data)
+		}
+		t.Fatalf("extract run %q: %v", runID, err)
+	}
+	bundleRoot, ok := result.Metadata["bundle_root"].(string)
+	if !ok || bundleRoot == "" {
+		t.Fatalf("extract metadata bundle_root = %#v", result.Metadata["bundle_root"])
+	}
+	data, err := os.ReadFile(filepath.Join(bundleRoot, "manifest.json"))
+	if err != nil {
+		t.Fatalf("read Notarius manifest: %v", err)
+	}
+	var published notariusIntegrationRunManifest
+	if err := json.Unmarshal(data, &published); err != nil {
+		t.Fatalf("decode Notarius manifest: %v", err)
+	}
+	return published
+}
+
+type notariusIntegrationRunManifest struct {
+	ChunkPlan *struct {
+		Action       string `json:"action"`
+		SourceDigest string `json:"source_digest"`
+	} `json:"chunk_plan"`
+	CheckpointDecisions []struct {
+		Stage      string `json:"stage"`
+		LaneID     string `json:"lane_id"`
+		Category   string `json:"category"`
+		ReasonCode string `json:"reason_code"`
+	} `json:"checkpoint_decisions"`
+}
+
+func assertNotariusIntegrationDecision(t *testing.T, published notariusIntegrationRunManifest, stageName, laneID, category, reasonCode string) {
+	t.Helper()
+	for _, decision := range published.CheckpointDecisions {
+		if decision.Stage == stageName && decision.LaneID == laneID {
+			if decision.Category != category || reasonCode != "" && decision.ReasonCode != reasonCode {
+				t.Fatalf("checkpoint decision for %s/%s = %#v, want category %q reason %q", stageName, laneID, decision, category, reasonCode)
+			}
+			return
+		}
+	}
+	t.Fatalf("checkpoint decision for %s/%s not found in %#v", stageName, laneID, published.CheckpointDecisions)
+}

internal/stage/publish_test.go

@@ -324,6 +324,9 @@ func TestPublishRejectsDeclaredDirectoryBeforeUploading(t *testing.T) {
 func TestPublishDoesNotUploadUndeclaredRunFile(t *testing.T) {
 	env, m, runRoot := publishFixture(t)
 	writeStageTestFile(t, filepath.Join(runRoot, "unlisted.txt"), "outside of manifest\n")
+	paths := artifacts.NewLocalStore(env.Config.Pipeline.Workspace.Root).SessionPathsFor(m.Campaign, m.SessionID)
+	cacheFile := filepath.Join(artifacts.SessionNotariusReferenceCacheDir(paths), strings.Repeat("a", 64), "party.yml")
+	writeStageTestFile(t, cacheFile, "local Notarius reference cache\n")
 
 	if _, err := (publishStage{}).Run(context.Background(), env, m); err != nil {
 		t.Fatalf("Run() error = %v", err)
@@ -333,8 +336,8 @@ func TestPublishDoesNotUploadUndeclaredRunFile(t *testing.T) {
 		t.Fatal("undeclared run file was uploaded")
 	}
 	for _, object := range fake.Objects {
-		if strings.Contains(string(object.Data), "outside of manifest") {
+		if strings.Contains(string(object.Data), "outside of manifest") || strings.Contains(string(object.Data), "local Notarius reference cache") {
-			t.Fatalf("undeclared bytes were uploaded in %q", object.Key)
+			t.Fatalf("undeclared or cache bytes were uploaded in %q", object.Key)
 		}
 	}
 }

internal/stage/semantic_contracts_delivery.go

@@ -22,10 +22,18 @@ const (
 type extractSemanticConfig struct {
 	Enabled       bool                       `json:"enabled"`
 	PipelineID    string                     `json:"pipeline_id,omitempty"`
+	ConfigProfile string                     `json:"config_profile,omitempty"`
 	References    []extractSemanticReference `json:"references"`
 	Outputs       []extractSemanticOutput    `json:"outputs"`
 }
 
+func notariusConfigProfileReuseIdentity(profile *string) string {
+	if profile == nil || *profile == "" || *profile == "default" {
+		return ""
+	}
+	return *profile
+}
+
 type extractSemanticReference struct {
 	Selector string `json:"selector"`
 	SourceID string `json:"source_id"`
@@ -77,6 +85,7 @@ func (extractStage) SemanticConfigFingerprint(env *Env) (manifest.SemanticConfig
 	}
 	payload.Enabled = true
 	payload.PipelineID = strings.TrimSpace(cfg.PipelineID)
+	payload.ConfigProfile = notariusConfigProfileReuseIdentity(cfg.ConfigProfile)
 	for rawSelector, rawSourceID := range cfg.References {
 		selector, err := notariusref.NormalizeSelector(rawSelector)
 		if err != nil {

internal/stage/semantic_contracts_delivery_test.go

@@ -2,11 +2,14 @@ package stage
 
 import (
 	"context"
+	"os"
+	"path/filepath"
 	"testing"
 
 	configkit "gitea.maximumdirect.net/eric/ConfigKit"
 	"gitea.maximumdirect.net/eric/narratio/internal/artifactpolicy"
 	"gitea.maximumdirect.net/eric/narratio/internal/config"
+	"gitea.maximumdirect.net/eric/narratio/internal/manifest"
 )
 
 func testSecretReference(name string) *configkit.Secret {
@@ -74,6 +77,94 @@ func TestExtractSemanticConfigSensitivityAndOperationalExclusions(t *testing.T)
 	if !want.Equal(got) {
 		t.Fatalf("operational settings changed fingerprint: got %#v want %#v", got, want)
 	}
+
+	for _, test := range []struct {
+		name   string
+		mutate func(*config.NotariusConfig)
+	}{
+		{name: "resume", mutate: func(cfg *config.NotariusConfig) { cfg.Resume = true }},
+		{name: "chunk cache", mutate: func(cfg *config.NotariusConfig) { cfg.ChunkCache = "refresh" }},
+	} {
+		t.Run("operational "+test.name, func(t *testing.T) {
+			env := downstreamSemanticEnv()
+			test.mutate(env.Config.Pipeline.Notarius)
+			got, err := (extractStage{}).SemanticConfigFingerprint(env)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if !want.Equal(got) {
+				t.Fatalf("%s changed semantic fingerprint: got %#v want %#v", test.name, got, want)
+			}
+		})
+	}
+
+	profilePointer := func(value string) *string { return &value }
+	baseFingerprints := make([]manifest.SemanticConfigFingerprint, 0, 3)
+	for _, profile := range []*string{nil, profilePointer(""), profilePointer("default")} {
+		env := downstreamSemanticEnv()
+		env.Config.Pipeline.Notarius.ConfigProfile = profile
+		fingerprint, err := (extractStage{}).SemanticConfigFingerprint(env)
+		if err != nil {
+			t.Fatal(err)
+		}
+		baseFingerprints = append(baseFingerprints, fingerprint)
+	}
+	for index := 1; index < len(baseFingerprints); index++ {
+		if !baseFingerprints[0].Equal(baseFingerprints[index]) {
+			t.Fatal("nil, empty, and default Notarius selections must share base reuse evidence")
+		}
+	}
+	profiled := downstreamSemanticEnv()
+	profiled.Config.Pipeline.Notarius.ConfigProfile = profilePointer("inexpensive")
+	firstProfile, err := (extractStage{}).SemanticConfigFingerprint(profiled)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if baseFingerprints[0].Equal(firstProfile) {
+		t.Fatal("base to named Notarius selection retained semantic fingerprint")
+	}
+	unchangedProfile, err := (extractStage{}).SemanticConfigFingerprint(profiled)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !firstProfile.Equal(unchangedProfile) {
+		t.Fatal("unchanged Notarius selection changed semantic fingerprint")
+	}
+	profiled.Config.Pipeline.Notarius.ConfigProfile = profilePointer("experimental")
+	secondProfile, err := (extractStage{}).SemanticConfigFingerprint(profiled)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if firstProfile.Equal(secondProfile) {
+		t.Fatal("named to different named Notarius selection retained semantic fingerprint")
+	}
+	profiled.Config.Pipeline.Notarius.ConfigProfile = nil
+	returnedToBase, err := (extractStage{}).SemanticConfigFingerprint(profiled)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !baseFingerprints[0].Equal(returnedToBase) {
+		t.Fatal("named to base Notarius selection did not restore base semantic evidence")
+	}
+	if secondProfile.Equal(returnedToBase) {
+		t.Fatal("named to base Notarius selection retained named semantic evidence")
+	}
+	disabledBase := downstreamSemanticEnv()
+	disabledBase.Config.Pipeline.Notarius.Enabled = false
+	disabledNamed := downstreamSemanticEnv()
+	disabledNamed.Config.Pipeline.Notarius.Enabled = false
+	disabledNamed.Config.Pipeline.Notarius.ConfigProfile = profilePointer("ignored")
+	disabledBaseFingerprint, err := (extractStage{}).SemanticConfigFingerprint(disabledBase)
+	if err != nil {
+		t.Fatal(err)
+	}
+	disabledNamedFingerprint, err := (extractStage{}).SemanticConfigFingerprint(disabledNamed)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !disabledBaseFingerprint.Equal(disabledNamedFingerprint) {
+		t.Fatal("disabled extraction became sensitive to unused Notarius selection")
+	}
 }
 
 func TestExtractResumeValidationExcludesOperationalSettings(t *testing.T) {
@@ -83,6 +174,8 @@ func TestExtractResumeValidationExcludesOperationalSettings(t *testing.T) {
 	env.Config.Pipeline.Notarius.ConfigPath = "/not/present/private.yml"
 	env.Config.Pipeline.Notarius.Timeout = "not-a-duration"
 	env.Config.Pipeline.Notarius.WorkingDirectory = "/not/present/work"
+	env.Config.Pipeline.Notarius.Resume = true
+	env.Config.Pipeline.Notarius.ChunkCache = "bypass"
 
 	validation, err := (extractStage{}).ValidateResume(context.Background(), env, m)
 	if err != nil {
@@ -93,6 +186,55 @@ func TestExtractResumeValidationExcludesOperationalSettings(t *testing.T) {
 	}
 }
 
+func TestExtractSemanticConfigExcludesLoadedCredentialChanges(t *testing.T) {
+	const firstName = "NARRATIO_SEMANTIC_NOTARIUS_KEY"
+	const secondName = "NARRATIO_SEMANTIC_NOTARIUS_KEY_TWO"
+	first := loadNotariusCredentialForSemanticTest(t, firstName, "first-value")
+	rotated := loadNotariusCredentialForSemanticTest(t, firstName, "rotated-value")
+	renamed := loadNotariusCredentialForSemanticTest(t, secondName, "second-value")
+
+	baseline := downstreamSemanticEnv()
+	baseline.Config.Pipeline.Notarius.LLMAPIKey = first
+	want, err := (extractStage{}).SemanticConfigFingerprint(baseline)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, test := range []struct {
+		name       string
+		credential *configkit.Secret
+	}{
+		{name: "removed", credential: nil},
+		{name: "renamed", credential: renamed},
+		{name: "value rotated", credential: rotated},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			env := downstreamSemanticEnv()
+			env.Config.Pipeline.Notarius.LLMAPIKey = test.credential
+			got, err := (extractStage{}).SemanticConfigFingerprint(env)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if !want.Equal(got) {
+				t.Fatalf("credential-only change altered extract semantic fingerprint")
+			}
+		})
+	}
+}
+
+func loadNotariusCredentialForSemanticTest(t *testing.T, name, value string) *configkit.Secret {
+	t.Helper()
+	t.Setenv(name, value)
+	path := filepath.Join(t.TempDir(), "pipeline.yml")
+	if err := os.WriteFile(path, []byte("whisperx:\n  transcribe_url: https://transcription.example.test/transcribe\nnotarius:\n  enabled: false\n  llm_api_key: "+name+"\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	pipeline, err := config.LoadPipeline(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return pipeline.Notarius.LLMAPIKey
+}
+
 func TestPublishSemanticConfigSensitivityAndOperationalExclusions(t *testing.T) {
 	want, err := (publishStage{}).SemanticConfigFingerprint(downstreamSemanticEnv())
 	if err != nil {

internal/stage/transcribe.go

@@ -8,7 +8,6 @@ import (
 	"path/filepath"
 	"sort"
 	"strings"
-	"sync"
 
 	"golang.org/x/sync/errgroup"
 
@@ -28,11 +27,14 @@ func (transcribeStage) Run(ctx context.Context, env *Env, m *manifest.Manifest)
 	if env.ArtifactStore == nil {
 		return nil, fmt.Errorf("transcribe: artifact store is required")
 	}
+	if env.ManifestStore == nil {
+		return nil, fmt.Errorf("transcribe: manifest store is required")
+	}
 	if env.Config.Pipeline == nil || env.Config.Session == nil {
 		return nil, fmt.Errorf("transcribe: resolved config must include pipeline and session")
 	}
-	if env.WhisperX == nil {
+	if m == nil {
-		return nil, fmt.Errorf("transcribe: whisperx adapter is required")
+		return nil, fmt.Errorf("transcribe: session manifest is required")
 	}
 
 	var sessionID string
@@ -47,59 +49,40 @@ func (transcribeStage) Run(ctx context.Context, env *Env, m *manifest.Manifest)
 	}
 
 	paths := sessionPathsForEnv(env, sessionID)
+	reconciliation, err := reconcileTranscribeSpeakers(ctx, env, m)
+	if err != nil {
+		return nil, fmt.Errorf("transcribe: reconcile speakers: %w", err)
+	}
+	state := newTranscribeExecutionState(env, m, paths, reconciliation.current)
+	if err := state.checkpointStartingCollection(ctx); err != nil {
+		return nil, fmt.Errorf("transcribe: checkpoint reconciled speaker collection before execution: %w", err)
+	}
+
+	jobs := append([]transcribeReconciliationJob(nil), reconciliation.work...)
+	if len(jobs) > 0 && env.WhisperX == nil {
+		return nil, fmt.Errorf("transcribe: whisperx adapter is required")
+	}
+	if len(jobs) > 0 {
 		runLayout, err := resolveRunStageLayout(env, m, paths, sessionID, "transcribe")
 		if err != nil {
 			return nil, fmt.Errorf("transcribe: resolve run-stage layout: %w", err)
 		}
-	audioFiles, err := discoverPreparedAudio(m, paths.AudioDir)
+		for index := range jobs {
+			jobs[index].runOutputPath, err = runLocalPathForCanonical(runLayout, paths, jobs[index].canonicalOutputPath)
 			if err != nil {
-		return nil, fmt.Errorf("transcribe: resolve audio inputs: %w", err)
+				return nil, fmt.Errorf("transcribe: resolve run-local output path for %q: %w", jobs[index].speakerID, err)
+			}
 		}
-	if len(audioFiles) == 0 {
-		return nil, fmt.Errorf("transcribe: no prepared audio files found")
 	}
 
 	concurrency := 1
 	if env.Config.Pipeline.WhisperX.Concurrency != nil && *env.Config.Pipeline.WhisperX.Concurrency > 0 {
 		concurrency = *env.Config.Pipeline.WhisperX.Concurrency
 	}
-	if concurrency > len(audioFiles) {
+	if len(jobs) > 0 && concurrency > len(jobs) {
-		concurrency = len(audioFiles)
+		concurrency = len(jobs)
 	}
 
-	type job struct {
-		speakerID string
-		audioPath string
-		outPath   string
-	}
-	jobs := make([]job, 0, len(audioFiles))
-	seenSpeaker := map[string]string{}
-	for _, audioPath := range audioFiles {
-		base := strings.TrimSuffix(filepath.Base(audioPath), filepath.Ext(audioPath))
-		if base == "" {
-			return nil, fmt.Errorf("transcribe: could not derive speaker id from %q", audioPath)
-		}
-		if prev, ok := seenSpeaker[base]; ok {
-			return nil, fmt.Errorf("transcribe: duplicate speaker/audio basename %q from %q and %q", base, prev, audioPath)
-		}
-		seenSpeaker[base] = audioPath
-		canonicalOut := filepath.Join(paths.TranscriptsRawDir, base+".json")
-		runOut, err := runLocalPathForCanonical(runLayout, paths, canonicalOut)
-		if err != nil {
-			return nil, fmt.Errorf("transcribe: resolve run-local output path for %q: %w", base, err)
-		}
-		jobs = append(jobs, job{
-			speakerID: base,
-			audioPath: audioPath,
-			outPath:   runOut,
-		})
-	}
-
-	var (
-		mu        sync.Mutex
-		completed int
-		perFile   = map[string]map[string]any{}
-	)
 	group, groupCtx := errgroup.WithContext(ctx)
 	group.SetLimit(concurrency)
 	for _, job := range jobs {
@@ -108,40 +91,36 @@ func (transcribeStage) Run(ctx context.Context, env *Env, m *manifest.Manifest)
 			if err := groupCtx.Err(); err != nil {
 				return err
 			}
+			if err := state.checkpointFailure(); err != nil {
+				return err
+			}
 			res, runErr := env.WhisperX.Transcribe(groupCtx, whisperx.TranscribeRequest{
 				SpeakerID:               job.speakerID,
 				AudioPath:               job.audioPath,
-				OutputRawTranscriptPath: job.outPath,
+				OutputRawTranscriptPath: job.runOutputPath,
 			})
 			if runErr != nil {
 				return fmt.Errorf("speaker %q (%s): %w", job.speakerID, filepath.Base(job.audioPath), runErr)
 			}
 
-			if _, err := authoritativeOutputPath(job.outPath, res.OutputRawTranscriptPath); err != nil {
-				return fmt.Errorf("speaker %q: %w", job.speakerID, err)
-			}
-			if err := validateTranscriptJSONFile(job.outPath); err != nil {
-				return fmt.Errorf("speaker %q output %q invalid: %w", job.speakerID, job.outPath, err)
-			}
-
 			meta := map[string]any{
 				"attempts":    res.Attempts,
 				"http_status": res.HTTPStatus,
 				"duration_ms": res.Duration.Milliseconds(),
-				"output_path": job.outPath,
+				"output_path": job.runOutputPath,
 			}
 
-			mu.Lock()
+			if err := state.acceptSpeaker(ctx, job, res.OutputRawTranscriptPath, meta); err != nil {
-			perFile[job.speakerID] = meta
+				return fmt.Errorf("speaker %q: %w", job.speakerID, err)
-			completed++
+			}
-			mu.Unlock()
 			return nil
 		})
 	}
 	groupErr := group.Wait()
-	mu.Lock()
+	if err := state.checkpointFailure(); err != nil {
-	completedCount := completed
+		return nil, err
-	mu.Unlock()
+	}
+	completedCount := state.completedCount()
 	if err := ctx.Err(); err != nil {
 		return nil, fmt.Errorf("transcribe: canceled after completing %d of %d audio jobs: %w", completedCount, len(jobs), err)
 	}
@@ -151,35 +130,9 @@ func (transcribeStage) Run(ctx context.Context, env *Env, m *manifest.Manifest)
 	if completedCount != len(jobs) {
 		return nil, fmt.Errorf("transcribe: completed %d of %d planned audio jobs", completedCount, len(jobs))
 	}
-
+	outputs, outputPaths, runOutputPaths, orderedPerFile, err := state.successDetails()
-	speakers := make([]string, 0, len(perFile))
-	for speaker := range perFile {
-		speakers = append(speakers, speaker)
-	}
-	sort.Strings(speakers)
-
-	outputs := make([]artifacts.Ref, 0, len(speakers))
-	runOutputPaths := make([]string, 0, len(speakers))
-	outputPaths := make([]string, 0, len(speakers))
-	orderedPerFile := make(map[string]any, len(speakers))
-	for _, speaker := range speakers {
-		var runOut string
-		for _, job := range jobs {
-			if job.speakerID == speaker {
-				runOut = job.outPath
-				break
-			}
-		}
-		runOutputPaths = append(runOutputPaths, runOut)
-		canonicalOut := filepath.Join(paths.TranscriptsRawDir, speaker+".json")
-		ref := artifacts.Ref{Kind: "transcript_raw", Category: "transcripts", SessionID: sessionID, AbsolutePath: runOut}
-		materialized, err := materializeRunLocalOutput(env.ArtifactStore, runOut, canonicalOut, ref)
 	if err != nil {
-			return nil, fmt.Errorf("transcribe: materialize %q output: %w", speaker, err)
+		return nil, fmt.Errorf("transcribe: assemble completed outputs: %w", err)
-		}
-		outputs = append(outputs, materialized)
-		outputPaths = append(outputPaths, canonicalOut)
-		orderedPerFile[speaker] = perFile[speaker]
 	}
 
 	retries := 0
@@ -191,7 +144,7 @@ func (transcribeStage) Run(ctx context.Context, env *Env, m *manifest.Manifest)
 		Outputs: outputs,
 		Metadata: map[string]any{
 			"stage":             "transcribe",
-			"audio_files_count": len(audioFiles),
+			"audio_files_count": len(reconciliation.jobs),
 			"language":          env.Config.Pipeline.WhisperX.Language,
 			"concurrency":       concurrency,
 			"retries":           retries,
@@ -204,7 +157,39 @@ func (transcribeStage) Run(ctx context.Context, env *Env, m *manifest.Manifest)
 	}, nil
 }
 
-func discoverPreparedAudio(m *manifest.Manifest, audioDir string) ([]string, error) {
+type transcribeJob struct {
+	speakerID           string
+	audioPath           string
+	canonicalOutputPath string
+	runOutputPath       string
+}
+
+func buildTranscribeJobs(m *manifest.Manifest, paths artifacts.SessionPaths) ([]transcribeJob, error) {
+	audioFiles, err := discoverPreparedAudio(m, paths)
+	if err != nil {
+		return nil, err
+	}
+	jobs := make([]transcribeJob, 0, len(audioFiles))
+	seenSpeaker := map[string]string{}
+	for _, audioPath := range audioFiles {
+		base := strings.TrimSuffix(filepath.Base(audioPath), filepath.Ext(audioPath))
+		if base == "" {
+			return nil, fmt.Errorf("could not derive speaker id from %q", audioPath)
+		}
+		if previous, exists := seenSpeaker[base]; exists {
+			return nil, fmt.Errorf("duplicate speaker/audio basename %q from %q and %q", base, previous, audioPath)
+		}
+		seenSpeaker[base] = audioPath
+		jobs = append(jobs, transcribeJob{
+			speakerID:           base,
+			audioPath:           audioPath,
+			canonicalOutputPath: filepath.Join(paths.TranscriptsRawDir, base+".json"),
+		})
+	}
+	return jobs, nil
+}
+
+func discoverPreparedAudio(m *manifest.Manifest, paths artifacts.SessionPaths) ([]string, error) {
 	fromManifest := make([]string, 0)
 	if m != nil {
 		for _, in := range m.Inputs {
@@ -215,7 +200,7 @@ func discoverPreparedAudio(m *manifest.Manifest, audioDir string) ([]string, err
 			if p == "" {
 				continue
 			}
-			fromManifest = append(fromManifest, filepath.Clean(p))
+			fromManifest = append(fromManifest, artifacts.ResolveSessionLocalPathForRead(paths, p))
 		}
 	}
 	if len(fromManifest) > 0 {
@@ -226,9 +211,9 @@ func discoverPreparedAudio(m *manifest.Manifest, audioDir string) ([]string, err
 		return fromManifest, nil
 	}
 
-	entries, err := os.ReadDir(audioDir)
+	entries, err := os.ReadDir(paths.AudioDir)
 	if err != nil {
-		return nil, fmt.Errorf("read audio directory %q: %w", audioDir, err)
+		return nil, fmt.Errorf("read audio directory %q: %w", paths.AudioDir, err)
 	}
 
 	out := make([]string, 0)
@@ -236,7 +221,7 @@ func discoverPreparedAudio(m *manifest.Manifest, audioDir string) ([]string, err
 		if entry.IsDir() {
 			continue
 		}
-		p := filepath.Join(audioDir, entry.Name())
+		p := filepath.Join(paths.AudioDir, entry.Name())
 		if !isFlac(p) {
 			continue
 		}

internal/stage/transcribe_checkpoint_test.go

@@ -0,0 +1,330 @@
+package stage
+
+import (
+	"context"
+	"errors"
+	"os"
+	"slices"
+	"sync/atomic"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/adapters/whisperx"
+	"gitea.maximumdirect.net/eric/narratio/internal/manifest"
+)
+
+func TestTranscribeFailureCheckpointsEarlierSpeakersAndRetryRunsOnlyRemaining(t *testing.T) {
+	env, m := setupTranscribeEnv(t, []string{"a.flac", "b.flac", "c.flac", "d.flac"})
+	concurrency := 1
+	env.Config.Pipeline.WhisperX.Concurrency = &concurrency
+	if _, err := (prepareStage{}).Run(context.Background(), env, m); err != nil {
+		t.Fatalf("prepare.Run() error = %v", err)
+	}
+	cause := errors.New("speaker c failed")
+	env.WhisperX = &whisperx.FakeClient{TranscribeFn: func(
+		_ context.Context,
+		req whisperx.TranscribeRequest,
+	) (whisperx.TranscribeResult, error) {
+		if req.SpeakerID == "c" {
+			return whisperx.TranscribeResult{}, cause
+		}
+		if req.SpeakerID == "d" {
+			t.Fatalf("speaker d was dispatched after failure")
+		}
+		if err := writeJSONFile(req.OutputRawTranscriptPath, map[string]any{"speaker": req.SpeakerID}); err != nil {
+			return whisperx.TranscribeResult{}, err
+		}
+		return whisperx.TranscribeResult{OutputRawTranscriptPath: req.OutputRawTranscriptPath}, nil
+	}}
+
+	if _, err := (transcribeStage{}).Run(context.Background(), env, m); !errors.Is(err, cause) {
+		t.Fatalf("Run() error = %v, want %v", err, cause)
+	}
+	durable, err := env.ManifestStore.Load(context.Background(), sessionPathsForEnv(env, m.SessionID).ManifestPath)
+	if err != nil {
+		t.Fatalf("load durable manifest: %v", err)
+	}
+	if got := sortedTranscribeSpeakerKeys(durable.Stages["transcribe"].TranscribeSpeakers); !slices.Equal(got, []string{"a", "b"}) {
+		t.Fatalf("durable speakers = %#v, want a and b", got)
+	}
+
+	retry := &whisperx.FakeClient{}
+	env.WhisperX = retry
+	result, err := (transcribeStage{}).Run(context.Background(), env, m)
+	if err != nil {
+		t.Fatalf("retry Run() error = %v", err)
+	}
+	requests := retry.RequestsSnapshot()
+	gotRequests := make([]string, 0, len(requests))
+	for _, request := range requests {
+		gotRequests = append(gotRequests, request.SpeakerID)
+	}
+	if !slices.Equal(gotRequests, []string{"c", "d"}) {
+		t.Fatalf("retry speakers = %#v, want c and d", gotRequests)
+	}
+	if len(result.Outputs) != 4 {
+		t.Fatalf("retry outputs = %d, want all four speakers", len(result.Outputs))
+	}
+}
+
+func TestTranscribeConcurrentCheckpointsDoNotLoseCompletions(t *testing.T) {
+	env, m := setupTranscribeEnv(t, []string{"a.flac", "b.flac", "c.flac", "d.flac"})
+	concurrency := 4
+	env.Config.Pipeline.WhisperX.Concurrency = &concurrency
+	env.WhisperX = &whisperx.FakeClient{}
+	if _, err := (prepareStage{}).Run(context.Background(), env, m); err != nil {
+		t.Fatalf("prepare.Run() error = %v", err)
+	}
+	if _, err := (transcribeStage{}).Run(context.Background(), env, m); err != nil {
+		t.Fatalf("Run() error = %v", err)
+	}
+	durable, err := env.ManifestStore.Load(context.Background(), sessionPathsForEnv(env, m.SessionID).ManifestPath)
+	if err != nil {
+		t.Fatalf("load durable manifest: %v", err)
+	}
+	if got := sortedTranscribeSpeakerKeys(durable.Stages["transcribe"].TranscribeSpeakers); !slices.Equal(got, []string{"a", "b", "c", "d"}) {
+		t.Fatalf("durable speakers = %#v, want all completions", got)
+	}
+}
+
+func TestTranscribeStartingCheckpointFailurePreventsRequestsAndCanonicalWrites(t *testing.T) {
+	env, m := setupTranscribeEnv(t, []string{"alice.flac"})
+	if _, err := (prepareStage{}).Run(context.Background(), env, m); err != nil {
+		t.Fatalf("prepare.Run() error = %v", err)
+	}
+	cause := errors.New("starting checkpoint failed")
+	base := env.ManifestStore
+	env.ManifestStore = &failingTranscribeManifestStore{Store: base, FailAt: 1, Err: cause}
+	fake := &whisperx.FakeClient{}
+	env.WhisperX = fake
+
+	if _, err := (transcribeStage{}).Run(context.Background(), env, m); !errors.Is(err, cause) {
+		t.Fatalf("Run() error = %v, want %v", err, cause)
+	}
+	if got := len(fake.RequestsSnapshot()); got != 0 {
+		t.Fatalf("adapter requests = %d, want none", got)
+	}
+	canonical := sessionPathsForEnv(env, m.SessionID).TranscriptsRawDir + "/alice.json"
+	if _, err := os.Stat(canonical); !os.IsNotExist(err) {
+		t.Fatalf("canonical output exists after starting checkpoint failure: %v", err)
+	}
+}
+
+func TestTranscribeCheckpointFailureRetainsEarlierAuthority(t *testing.T) {
+	env, m := setupTranscribeEnv(t, []string{"a.flac", "b.flac", "c.flac"})
+	concurrency := 1
+	env.Config.Pipeline.WhisperX.Concurrency = &concurrency
+	if _, err := (prepareStage{}).Run(context.Background(), env, m); err != nil {
+		t.Fatalf("prepare.Run() error = %v", err)
+	}
+	cause := errors.New("speaker checkpoint failed")
+	base := env.ManifestStore
+	env.ManifestStore = &failingTranscribeManifestStore{Store: base, FailAt: 3, Err: cause}
+	fake := &whisperx.FakeClient{}
+	env.WhisperX = fake
+
+	if _, err := (transcribeStage{}).Run(context.Background(), env, m); !errors.Is(err, cause) {
+		t.Fatalf("Run() error = %v, want %v", err, cause)
+	}
+	requests := fake.RequestsSnapshot()
+	if len(requests) != 2 {
+		t.Fatalf("adapter requests = %d, want a and b only", len(requests))
+	}
+	durable, err := base.Load(context.Background(), sessionPathsForEnv(env, m.SessionID).ManifestPath)
+	if err != nil {
+		t.Fatalf("load durable manifest: %v", err)
+	}
+	if got := sortedTranscribeSpeakerKeys(durable.Stages["transcribe"].TranscribeSpeakers); !slices.Equal(got, []string{"a"}) {
+		t.Fatalf("durable speakers = %#v, want only a", got)
+	}
+	if got := sortedTranscribeSpeakerKeys(m.Stages["transcribe"].TranscribeSpeakers); !slices.Equal(got, []string{"a"}) {
+		t.Fatalf("live speakers = %#v, want last committed collection", got)
+	}
+}
+
+func TestTranscribeFailedForceRetryDoesNotResurrectOldSpeakers(t *testing.T) {
+	env, m := setupTranscribeEnv(t, []string{"a.flac", "b.flac"})
+	concurrency := 1
+	env.Config.Pipeline.WhisperX.Concurrency = &concurrency
+	env.WhisperX = &whisperx.FakeClient{}
+	if _, err := (prepareStage{}).Run(context.Background(), env, m); err != nil {
+		t.Fatalf("prepare.Run() error = %v", err)
+	}
+	if _, err := (transcribeStage{}).Run(context.Background(), env, m); err != nil {
+		t.Fatalf("seed Run() error = %v", err)
+	}
+
+	m.RunID = "20260503T020304Z-b2c3d4e5"
+	env.Force = true
+	cause := errors.New("forced b failed")
+	env.WhisperX = &whisperx.FakeClient{TranscribeFn: func(
+		_ context.Context,
+		req whisperx.TranscribeRequest,
+	) (whisperx.TranscribeResult, error) {
+		if req.SpeakerID == "b" {
+			return whisperx.TranscribeResult{}, cause
+		}
+		if err := writeJSONFile(req.OutputRawTranscriptPath, map[string]any{"replacement": req.SpeakerID}); err != nil {
+			return whisperx.TranscribeResult{}, err
+		}
+		return whisperx.TranscribeResult{OutputRawTranscriptPath: req.OutputRawTranscriptPath}, nil
+	}}
+	if _, err := (transcribeStage{}).Run(context.Background(), env, m); !errors.Is(err, cause) {
+		t.Fatalf("forced Run() error = %v, want %v", err, cause)
+	}
+	if got := sortedTranscribeSpeakerKeys(m.Stages["transcribe"].TranscribeSpeakers); !slices.Equal(got, []string{"a"}) {
+		t.Fatalf("speakers after failed force = %#v, want only replacement a", got)
+	}
+
+	env.Force = false
+	retry := &whisperx.FakeClient{}
+	env.WhisperX = retry
+	if _, err := (transcribeStage{}).Run(context.Background(), env, m); err != nil {
+		t.Fatalf("retry Run() error = %v", err)
+	}
+	requests := retry.RequestsSnapshot()
+	if len(requests) != 1 || requests[0].SpeakerID != "b" {
+		t.Fatalf("retry requests = %#v, want only b", requests)
+	}
+}
+
+func TestTranscribeRejectsAudioChangedDuringRequest(t *testing.T) {
+	env, m := setupTranscribeEnv(t, []string{"alice.flac"})
+	if _, err := (prepareStage{}).Run(context.Background(), env, m); err != nil {
+		t.Fatalf("prepare.Run() error = %v", err)
+	}
+	env.WhisperX = &whisperx.FakeClient{TranscribeFn: func(
+		_ context.Context,
+		req whisperx.TranscribeRequest,
+	) (whisperx.TranscribeResult, error) {
+		if err := writeJSONFile(req.OutputRawTranscriptPath, map[string]any{"speaker": req.SpeakerID}); err != nil {
+			return whisperx.TranscribeResult{}, err
+		}
+		if err := os.WriteFile(req.AudioPath, []byte("changed"), 0o644); err != nil {
+			return whisperx.TranscribeResult{}, err
+		}
+		return whisperx.TranscribeResult{OutputRawTranscriptPath: req.OutputRawTranscriptPath}, nil
+	}}
+	if _, err := (transcribeStage{}).Run(context.Background(), env, m); err == nil {
+		t.Fatal("Run() error = nil, want changed-audio failure")
+	}
+	if got := len(m.Stages["transcribe"].TranscribeSpeakers); got != 0 {
+		t.Fatalf("checkpointed speakers = %d, want none", got)
+	}
+}
+
+func TestTranscribeResumeValidationUsesSpeakerEvidence(t *testing.T) {
+	env, m := setupTranscribeEnv(t, []string{"alice.flac"})
+	env.WhisperX = &whisperx.FakeClient{}
+	if _, err := (prepareStage{}).Run(context.Background(), env, m); err != nil {
+		t.Fatalf("prepare.Run() error = %v", err)
+	}
+	if _, err := (transcribeStage{}).Run(context.Background(), env, m); err != nil {
+		t.Fatalf("Run() error = %v", err)
+	}
+	validation, err := (transcribeStage{}).ValidateResume(context.Background(), env, m)
+	if err != nil || validation.Resumable {
+		t.Fatalf("ValidateResume() = %#v, %v, want missing aggregate repaired", validation, err)
+	}
+	if len(m.Stages["transcribe"].Outputs) != 0 {
+		t.Fatal("resume inspection mutated aggregate outputs")
+	}
+	m.Stages["transcribe"].Outputs = []manifest.ArtifactRecord{m.Stages["transcribe"].TranscribeSpeakers["alice"].Output}
+	validation, err = (transcribeStage{}).ValidateResume(context.Background(), env, m)
+	if err != nil || !validation.Resumable {
+		t.Fatalf("ValidateResume() = %#v, %v, want resumable", validation, err)
+	}
+	if err := os.WriteFile(m.Inputs[0].Path, []byte("changed"), 0o644); err != nil {
+		t.Fatalf("change audio: %v", err)
+	}
+	validation, err = (transcribeStage{}).ValidateResume(context.Background(), env, m)
+	if err != nil || validation.Resumable {
+		t.Fatalf("ValidateResume() = %#v, %v, want execution required", validation, err)
+	}
+}
+
+func TestTranscribeRebuildsAggregateFromCurrentSpeakersWithoutRequests(t *testing.T) {
+	env, m := setupTranscribeEnv(t, []string{"alice.flac", "bob.flac"})
+	fake := &whisperx.FakeClient{}
+	env.WhisperX = fake
+	if _, err := (prepareStage{}).Run(context.Background(), env, m); err != nil {
+		t.Fatalf("prepare.Run() error = %v", err)
+	}
+	seed, err := (transcribeStage{}).Run(context.Background(), env, m)
+	if err != nil {
+		t.Fatalf("seed Run() error = %v", err)
+	}
+	originalRunID := m.RunID
+	m.MarkStageFailed("transcribe", m.UpdatedAt.Add(1), "aggregate save failed")
+	m.RunID = "20260503T030405Z-c3d4e5f6"
+	fake = &whisperx.FakeClient{}
+	env.WhisperX = fake
+
+	result, err := (transcribeStage{}).Run(context.Background(), env, m)
+	if err != nil {
+		t.Fatalf("rebuild Run() error = %v", err)
+	}
+	if got := len(fake.RequestsSnapshot()); got != 0 {
+		t.Fatalf("adapter requests = %d, want none", got)
+	}
+	if len(result.Outputs) != len(seed.Outputs) {
+		t.Fatalf("rebuilt outputs = %d, want %d", len(result.Outputs), len(seed.Outputs))
+	}
+	for index, output := range result.Outputs {
+		if output.ProducerRunID != originalRunID {
+			t.Fatalf("output %d producer = %q, want %q", index, output.ProducerRunID, originalRunID)
+		}
+		if output.Checksum != seed.Outputs[index].Checksum {
+			t.Fatalf("output %d checksum = %q, want %q", index, output.Checksum, seed.Outputs[index].Checksum)
+		}
+	}
+}
+
+func TestTranscribeReuseDoesNotDependOnRunDirectory(t *testing.T) {
+	env, m := setupTranscribeEnv(t, []string{"alice.flac"})
+	env.WhisperX = &whisperx.FakeClient{}
+	if _, err := (prepareStage{}).Run(context.Background(), env, m); err != nil {
+		t.Fatalf("prepare.Run() error = %v", err)
+	}
+	if _, err := (transcribeStage{}).Run(context.Background(), env, m); err != nil {
+		t.Fatalf("Run() error = %v", err)
+	}
+	m.Stages["transcribe"].Outputs = []manifest.ArtifactRecord{m.Stages["transcribe"].TranscribeSpeakers["alice"].Output}
+	paths := sessionPathsForEnv(env, m.SessionID)
+	if err := os.RemoveAll(paths.RunsDir); err != nil {
+		t.Fatalf("remove run directory: %v", err)
+	}
+	if _, err := os.Stat(paths.TranscriptsRawDir + "/alice.json"); err != nil {
+		t.Fatalf("canonical transcript missing after run cleanup: %v", err)
+	}
+	validation, err := (transcribeStage{}).ValidateResume(context.Background(), env, m)
+	if err != nil || !validation.Resumable {
+		t.Fatalf("ValidateResume() = %#v, %v, want canonical reuse", validation, err)
+	}
+}
+
+type failingTranscribeManifestStore struct {
+	manifest.Store
+	Saves  atomic.Int64
+	FailAt int64
+	Err    error
+}
+
+func (store *failingTranscribeManifestStore) Save(
+	ctx context.Context,
+	path string,
+	m *manifest.Manifest,
+) error {
+	if store.Saves.Add(1) == store.FailAt {
+		return store.Err
+	}
+	return store.Store.Save(ctx, path, m)
+}
+
+func sortedTranscribeSpeakerKeys(records map[string]manifest.TranscribeSpeakerRecord) []string {
+	keys := make([]string, 0, len(records))
+	for key := range records {
+		keys = append(keys, key)
+	}
+	slices.Sort(keys)
+	return keys
+}

internal/stage/transcribe_execution_state.go

@@ -0,0 +1,292 @@
+package stage
+
+import (
+	"context"
+	"fmt"
+	"reflect"
+	"sort"
+	"strings"
+	"sync"
+	"time"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
+	"gitea.maximumdirect.net/eric/narratio/internal/manifest"
+	"gitea.maximumdirect.net/eric/narratio/internal/pathsafe"
+)
+
+type transcribeExecutionState struct {
+	env      *Env
+	manifest *manifest.Manifest
+	paths    artifacts.SessionPaths
+
+	mu            sync.Mutex
+	records       map[string]manifest.TranscribeSpeakerRecord
+	checkpointErr error
+	completed     int
+	perFile       map[string]map[string]any
+	runOutputs    map[string]string
+}
+
+func newTranscribeExecutionState(
+	env *Env,
+	m *manifest.Manifest,
+	paths artifacts.SessionPaths,
+	current map[string]manifest.TranscribeSpeakerRecord,
+) *transcribeExecutionState {
+	return &transcribeExecutionState{
+		env:        env,
+		manifest:   m,
+		paths:      paths,
+		records:    manifest.CloneTranscribeSpeakerCollection(current),
+		perFile:    make(map[string]map[string]any),
+		runOutputs: make(map[string]string),
+	}
+}
+
+func (state *transcribeExecutionState) checkpointStartingCollection(ctx context.Context) error {
+	state.mu.Lock()
+	defer state.mu.Unlock()
+	if record := transcribeStageRecord(state.manifest); record != nil &&
+		record.TranscribeStateVersion == manifest.TranscribeStateContractVersion &&
+		reflect.DeepEqual(record.TranscribeSpeakers, state.records) {
+		return nil
+	}
+	if err := state.checkpointCollectionLocked(ctx, state.records); err != nil {
+		state.checkpointErr = err
+		return err
+	}
+	return nil
+}
+
+func (state *transcribeExecutionState) acceptSpeaker(
+	ctx context.Context,
+	job transcribeReconciliationJob,
+	adapterOutputPath string,
+	metadata map[string]any,
+) error {
+	if _, err := authoritativeOutputPath(job.runOutputPath, adapterOutputPath); err != nil {
+		return err
+	}
+	if err := validateTranscriptJSONFile(job.runOutputPath); err != nil {
+		return fmt.Errorf("output %q invalid: %w", job.runOutputPath, err)
+	}
+	audioSHA256, audioSize, err := hashRegularFileWithContext(ctx, job.audioPath)
+	if err != nil {
+		return fmt.Errorf("recheck audio %q: %w", job.audioPath, err)
+	}
+	if audioSHA256 != job.audioSHA256 || audioSize != job.audioSize {
+		return fmt.Errorf("audio %q changed during transcription", job.audioPath)
+	}
+	if err := state.checkpointFailure(); err != nil {
+		return err
+	}
+
+	producerRunID := strings.TrimSpace(state.manifest.RunID)
+	ref := artifacts.Ref{
+		Kind:          "transcript_raw",
+		Category:      "transcripts",
+		SessionID:     state.manifest.SessionID,
+		AbsolutePath:  job.runOutputPath,
+		ProducerRunID: producerRunID,
+	}
+	materialized, err := materializeRunLocalOutput(
+		state.env.ArtifactStore,
+		job.runOutputPath,
+		job.canonicalOutputPath,
+		ref,
+	)
+	if err != nil {
+		return fmt.Errorf("materialize output: %w", err)
+	}
+	outputSHA256, outputSize, err := hashRegularFileWithContext(ctx, job.canonicalOutputPath)
+	if err != nil {
+		return fmt.Errorf("inspect materialized output %q: %w", job.canonicalOutputPath, err)
+	}
+	if materialized.Checksum != outputSHA256 {
+		return fmt.Errorf("materialized output checksum changed while inspecting")
+	}
+	record := manifest.TranscribeSpeakerRecord{
+		FingerprintVersion: manifest.TranscribeFingerprintContractVersion,
+		Fingerprint:        job.fingerprint,
+		AudioPath:          job.audioRelativePath,
+		AudioSHA256:        job.audioSHA256,
+		AudioSize:          job.audioSize,
+		Output: manifest.ArtifactRecord{
+			Kind:          "transcript_raw",
+			LocalPath:     job.outputRelativePath,
+			ArchivePath:   materialized.ArchivePath,
+			ProducerRunID: producerRunID,
+			Checksum:      outputSHA256,
+		},
+		OutputSize:    outputSize,
+		ProducerRunID: producerRunID,
+	}
+
+	state.mu.Lock()
+	defer state.mu.Unlock()
+	if state.checkpointErr != nil {
+		return state.checkpointErr
+	}
+	candidate := manifest.CloneTranscribeSpeakerCollection(state.records)
+	candidate[job.speakerID] = record
+	if err := state.checkpointCollectionLocked(ctx, candidate); err != nil {
+		state.checkpointErr = fmt.Errorf("transcribe: checkpoint speaker %q: %w", job.speakerID, err)
+		return state.checkpointErr
+	}
+	state.completed++
+	state.perFile[job.speakerID] = cloneStringAnyMap(metadata)
+	state.runOutputs[job.speakerID] = job.runOutputPath
+	return nil
+}
+
+func (state *transcribeExecutionState) checkpointCollectionLocked(
+	ctx context.Context,
+	records map[string]manifest.TranscribeSpeakerRecord,
+) error {
+	if state.manifest == nil {
+		return fmt.Errorf("session manifest is required")
+	}
+	if state.env == nil || state.env.ManifestStore == nil {
+		return fmt.Errorf("manifest store is required")
+	}
+	if err := manifest.ValidateTranscribeSpeakerCollection(
+		manifest.TranscribeStateContractVersion,
+		records,
+	); err != nil {
+		return fmt.Errorf("validate transcribe speaker collection: %w", err)
+	}
+
+	candidate := cloneManifestForTranscribeCheckpoint(state.manifest)
+	if candidate.Stages == nil {
+		candidate.Stages = make(map[string]*manifest.StageRecord)
+	}
+	record := candidate.Stages["transcribe"]
+	if record == nil {
+		now := time.Now().UTC()
+		record = &manifest.StageRecord{
+			Name: "transcribe", Status: manifest.StatusRunning, CreatedAt: now, UpdatedAt: now,
+		}
+		candidate.Stages["transcribe"] = record
+	}
+	record.TranscribeStateVersion = manifest.TranscribeStateContractVersion
+	record.TranscribeSpeakers = manifest.CloneTranscribeSpeakerCollection(records)
+	record.UpdatedAt = time.Now().UTC()
+	if err := state.env.ManifestStore.Save(ctx, state.paths.ManifestPath, candidate); err != nil {
+		return fmt.Errorf("save session manifest %q: %w", state.paths.ManifestPath, err)
+	}
+
+	live := transcribeStageRecord(state.manifest)
+	if live == nil {
+		live = &manifest.StageRecord{}
+		if state.manifest.Stages == nil {
+			state.manifest.Stages = make(map[string]*manifest.StageRecord)
+		}
+		state.manifest.Stages["transcribe"] = live
+	}
+	live.TranscribeStateVersion = candidate.Stages["transcribe"].TranscribeStateVersion
+	live.TranscribeSpeakers = manifest.CloneTranscribeSpeakerCollection(
+		candidate.Stages["transcribe"].TranscribeSpeakers,
+	)
+	live.UpdatedAt = candidate.Stages["transcribe"].UpdatedAt
+	state.manifest.UpdatedAt = candidate.UpdatedAt
+	state.records = manifest.CloneTranscribeSpeakerCollection(live.TranscribeSpeakers)
+	return nil
+}
+
+func (state *transcribeExecutionState) checkpointFailure() error {
+	state.mu.Lock()
+	defer state.mu.Unlock()
+	return state.checkpointErr
+}
+
+func (state *transcribeExecutionState) completedCount() int {
+	state.mu.Lock()
+	defer state.mu.Unlock()
+	return state.completed
+}
+
+func (state *transcribeExecutionState) successDetails() (
+	[]artifacts.Ref,
+	[]string,
+	[]string,
+	map[string]any,
+	error,
+) {
+	state.mu.Lock()
+	defer state.mu.Unlock()
+
+	speakers := make([]string, 0, len(state.records))
+	for speaker := range state.records {
+		speakers = append(speakers, speaker)
+	}
+	sort.Strings(speakers)
+	outputs := make([]artifacts.Ref, 0, len(speakers))
+	outputPaths := make([]string, 0, len(speakers))
+	runOutputPaths := make([]string, 0, len(state.runOutputs))
+	orderedPerFile := make(map[string]any, len(state.perFile))
+	for _, speaker := range speakers {
+		record := state.records[speaker]
+		absolute, err := pathsafe.JoinSlashRelativeUnderRoot(state.paths.Root, record.Output.LocalPath)
+		if err != nil {
+			return nil, nil, nil, nil, fmt.Errorf("speaker %q output path: %w", speaker, err)
+		}
+		outputs = append(outputs, artifacts.Ref{
+			Kind:          record.Output.Kind,
+			Category:      "transcripts",
+			SessionID:     state.manifest.SessionID,
+			RelativePath:  record.Output.LocalPath,
+			AbsolutePath:  absolute,
+			ArchivePath:   record.Output.ArchivePath,
+			RemoteKey:     record.Output.RemoteKey,
+			Checksum:      record.Output.Checksum,
+			ProducerRunID: record.ProducerRunID,
+		})
+		outputPaths = append(outputPaths, absolute)
+		if runPath, ok := state.runOutputs[speaker]; ok {
+			runOutputPaths = append(runOutputPaths, runPath)
+		}
+		if metadata, ok := state.perFile[speaker]; ok {
+			orderedPerFile[speaker] = cloneStringAnyMap(metadata)
+		}
+	}
+	return outputs, outputPaths, runOutputPaths, orderedPerFile, nil
+}
+
+func transcribeStageRecord(m *manifest.Manifest) *manifest.StageRecord {
+	if m == nil || m.Stages == nil {
+		return nil
+	}
+	return m.Stages["transcribe"]
+}
+
+func cloneManifestForTranscribeCheckpoint(source *manifest.Manifest) *manifest.Manifest {
+	clone := *source
+	clone.Inputs = append([]manifest.InputRecord(nil), source.Inputs...)
+	clone.Artifacts = append([]manifest.ArtifactRecord(nil), source.Artifacts...)
+	clone.Stages = make(map[string]*manifest.StageRecord, len(source.Stages))
+	for name, sourceRecord := range source.Stages {
+		if sourceRecord == nil {
+			clone.Stages[name] = nil
+			continue
+		}
+		record := *sourceRecord
+		record.Outputs = append([]manifest.ArtifactRecord(nil), sourceRecord.Outputs...)
+		record.Logs = append([]string(nil), sourceRecord.Logs...)
+		record.GeneratedConfigs = append([]string(nil), sourceRecord.GeneratedConfigs...)
+		record.TranscribeSpeakers = manifest.CloneTranscribeSpeakerCollection(sourceRecord.TranscribeSpeakers)
+		record.AnalyzeArtifacts = manifest.CloneAnalyzeArtifactCollection(sourceRecord.AnalyzeArtifacts)
+		clone.Stages[name] = &record
+	}
+	return &clone
+}
+
+func cloneStringAnyMap(source map[string]any) map[string]any {
+	if source == nil {
+		return nil
+	}
+	clone := make(map[string]any, len(source))
+	for key, value := range source {
+		clone[key] = value
+	}
+	return clone
+}

internal/stage/transcribe_reconciliation.go

@@ -0,0 +1,339 @@
+package stage
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
+	"gitea.maximumdirect.net/eric/narratio/internal/manifest"
+	"gitea.maximumdirect.net/eric/narratio/internal/pathsafe"
+)
+
+type transcribeReconciliationJob struct {
+	transcribeJob
+	audioRelativePath  string
+	audioSHA256        string
+	audioSize          int64
+	outputRelativePath string
+	fingerprint        string
+}
+
+type transcribeReconciliation struct {
+	jobs    []transcribeReconciliationJob
+	current map[string]manifest.TranscribeSpeakerRecord
+	work    []transcribeReconciliationJob
+}
+
+type transcribeSpeakerFingerprint struct {
+	SpeakerID             string `json:"speaker_id"`
+	AudioPath             string `json:"audio_path"`
+	AudioSHA256           string `json:"audio_sha256"`
+	AudioSize             int64  `json:"audio_size"`
+	SemanticConfigVersion int    `json:"semantic_config_version"`
+	SemanticConfigDigest  string `json:"semantic_config_digest"`
+}
+
+// reconcileTranscribeSpeakers compares the current prepared audio set with
+// manifest-owned per-speaker evidence without mutating either.
+func reconcileTranscribeSpeakers(ctx context.Context, env *Env, m *manifest.Manifest) (transcribeReconciliation, error) {
+	if env == nil || env.Config == nil || env.Config.Pipeline == nil || env.Config.Session == nil {
+		return transcribeReconciliation{}, fmt.Errorf("transcribe reconciliation requires resolved pipeline and session config")
+	}
+	if env.ArtifactStore == nil {
+		return transcribeReconciliation{}, fmt.Errorf("transcribe reconciliation requires artifact store")
+	}
+	if err := contextError(ctx); err != nil {
+		return transcribeReconciliation{}, err
+	}
+
+	sessionID := strings.TrimSpace(env.Config.Session.SessionID)
+	if m != nil && strings.TrimSpace(m.SessionID) != "" {
+		sessionID = strings.TrimSpace(m.SessionID)
+	}
+	if sessionID == "" {
+		return transcribeReconciliation{}, fmt.Errorf("transcribe reconciliation requires session ID")
+	}
+	paths := sessionPathsForEnv(env, sessionID)
+	baseJobs, err := buildTranscribeJobs(m, paths)
+	if err != nil {
+		return transcribeReconciliation{}, fmt.Errorf("resolve audio inputs: %w", err)
+	}
+	if len(baseJobs) == 0 {
+		return transcribeReconciliation{}, fmt.Errorf("no prepared audio files found")
+	}
+	semantic, err := (transcribeStage{}).SemanticConfigFingerprint(env)
+	if err != nil {
+		return transcribeReconciliation{}, err
+	}
+
+	result := transcribeReconciliation{
+		jobs:    make([]transcribeReconciliationJob, 0, len(baseJobs)),
+		current: map[string]manifest.TranscribeSpeakerRecord{},
+		work:    make([]transcribeReconciliationJob, 0, len(baseJobs)),
+	}
+	for _, base := range baseJobs {
+		candidate, err := inspectTranscribeJob(ctx, paths, base, semantic)
+		if err != nil {
+			return transcribeReconciliation{}, fmt.Errorf("speaker %q: %w", base.speakerID, err)
+		}
+		result.jobs = append(result.jobs, candidate)
+	}
+
+	stageRecord, versioned, err := transcribeManifestState(m)
+	if err != nil {
+		return transcribeReconciliation{}, err
+	}
+	if env.Force || !versioned {
+		result.work = append(result.work, result.jobs...)
+		return result, nil
+	}
+
+	for _, candidate := range result.jobs {
+		record, exists := stageRecord.TranscribeSpeakers[candidate.speakerID]
+		if !exists {
+			result.work = append(result.work, candidate)
+			continue
+		}
+		if err := manifest.ValidateTranscribeSpeakerCollection(
+			stageRecord.TranscribeStateVersion,
+			map[string]manifest.TranscribeSpeakerRecord{candidate.speakerID: record},
+		); err != nil {
+			return transcribeReconciliation{}, fmt.Errorf("speaker %q manifest evidence: %w", candidate.speakerID, err)
+		}
+		if !sameTranscribeInputEvidence(candidate, record) {
+			result.work = append(result.work, candidate)
+			continue
+		}
+		current, err := inspectTranscribeOutput(ctx, paths, candidate, record)
+		if err != nil {
+			return transcribeReconciliation{}, fmt.Errorf("speaker %q output evidence: %w", candidate.speakerID, err)
+		}
+		if !current {
+			result.work = append(result.work, candidate)
+			continue
+		}
+		result.current[candidate.speakerID] = manifest.CloneTranscribeSpeakerCollection(
+			map[string]manifest.TranscribeSpeakerRecord{candidate.speakerID: record},
+		)[candidate.speakerID]
+	}
+	return result, nil
+}
+
+func inspectTranscribeJob(
+	ctx context.Context,
+	paths artifacts.SessionPaths,
+	job transcribeJob,
+	semantic manifest.SemanticConfigFingerprint,
+) (transcribeReconciliationJob, error) {
+	audioRelative, err := pathsafe.SlashRelativeFromRoot(paths.Root, job.audioPath)
+	if err != nil {
+		return transcribeReconciliationJob{}, fmt.Errorf("derive session-relative audio path: %w", err)
+	}
+	outputRelative, err := pathsafe.SlashRelativeFromRoot(paths.Root, job.canonicalOutputPath)
+	if err != nil {
+		return transcribeReconciliationJob{}, fmt.Errorf("derive session-relative output path: %w", err)
+	}
+	audioSHA256, audioSize, err := hashRegularFileWithContext(ctx, job.audioPath)
+	if err != nil {
+		return transcribeReconciliationJob{}, fmt.Errorf("inspect audio %q: %w", job.audioPath, err)
+	}
+	fingerprint, err := fingerprintTranscribeSpeaker(transcribeSpeakerFingerprint{
+		SpeakerID:             job.speakerID,
+		AudioPath:             audioRelative,
+		AudioSHA256:           audioSHA256,
+		AudioSize:             audioSize,
+		SemanticConfigVersion: semantic.Version,
+		SemanticConfigDigest:  semantic.Digest,
+	})
+	if err != nil {
+		return transcribeReconciliationJob{}, err
+	}
+	return transcribeReconciliationJob{
+		transcribeJob:      job,
+		audioRelativePath:  audioRelative,
+		audioSHA256:        audioSHA256,
+		audioSize:          audioSize,
+		outputRelativePath: outputRelative,
+		fingerprint:        fingerprint,
+	}, nil
+}
+
+func fingerprintTranscribeSpeaker(payload transcribeSpeakerFingerprint) (string, error) {
+	fingerprint, err := FingerprintSemanticConfig(manifest.TranscribeFingerprintContractVersion, payload)
+	if err != nil {
+		return "", fmt.Errorf("build per-speaker fingerprint: %w", err)
+	}
+	return fingerprint.Digest, nil
+}
+
+func transcribeManifestState(m *manifest.Manifest) (*manifest.StageRecord, bool, error) {
+	if m == nil || m.Stages == nil || m.Stages["transcribe"] == nil {
+		return nil, false, nil
+	}
+	record := m.Stages["transcribe"]
+	if record.Name != "transcribe" {
+		return nil, false, fmt.Errorf("transcribe manifest record has stage name %q", record.Name)
+	}
+	if record.TranscribeStateVersion == 0 && record.TranscribeSpeakers == nil {
+		return record, false, nil
+	}
+	if record.TranscribeStateVersion != manifest.TranscribeStateContractVersion {
+		return nil, false, fmt.Errorf("unsupported transcribe state version %d", record.TranscribeStateVersion)
+	}
+	return record, true, nil
+}
+
+func sameTranscribeInputEvidence(candidate transcribeReconciliationJob, record manifest.TranscribeSpeakerRecord) bool {
+	return record.FingerprintVersion == manifest.TranscribeFingerprintContractVersion &&
+		record.Fingerprint == candidate.fingerprint &&
+		record.AudioPath == candidate.audioRelativePath &&
+		record.AudioSHA256 == candidate.audioSHA256 &&
+		record.AudioSize == candidate.audioSize &&
+		record.Output.LocalPath == candidate.outputRelativePath
+}
+
+func inspectTranscribeOutput(
+	ctx context.Context,
+	paths artifacts.SessionPaths,
+	candidate transcribeReconciliationJob,
+	record manifest.TranscribeSpeakerRecord,
+) (bool, error) {
+	if record.Output.LocalPath != candidate.outputRelativePath {
+		return false, nil
+	}
+	absolute, err := pathsafe.JoinSlashRelativeUnderRoot(paths.Root, record.Output.LocalPath)
+	if err != nil {
+		return false, fmt.Errorf("resolve recorded output path: %w", err)
+	}
+	exists, err := requireSafeTranscribeOutput(paths.Root, record.Output.LocalPath)
+	if err != nil {
+		return false, err
+	}
+	if !exists {
+		return false, nil
+	}
+	if err := validateTranscriptJSONFile(absolute); err != nil {
+		return false, nil
+	}
+	checksum, size, err := hashRegularFileWithContext(ctx, absolute)
+	if err != nil {
+		return false, fmt.Errorf("verify output: %w", err)
+	}
+	return checksum == record.Output.Checksum && size == record.OutputSize, nil
+}
+
+func requireSafeTranscribeOutput(rootPath, relativePath string) (bool, error) {
+	normalized, err := pathsafe.NormalizeRelativeDestination(relativePath)
+	if err != nil {
+		return false, fmt.Errorf("recorded output path is unsafe: %w", err)
+	}
+	root, err := os.OpenRoot(rootPath)
+	if err != nil {
+		return false, fmt.Errorf("open session root: %w", err)
+	}
+	defer func() { _ = root.Close() }()
+
+	parts := strings.Split(normalized, "/")
+	current := root
+	opened := make([]*os.Root, 0, len(parts)-1)
+	defer func() {
+		for index := len(opened) - 1; index >= 0; index-- {
+			_ = opened[index].Close()
+		}
+	}()
+	for _, part := range parts[:len(parts)-1] {
+		info, err := current.Lstat(part)
+		if errors.Is(err, os.ErrNotExist) {
+			return false, nil
+		}
+		if err != nil {
+			return false, fmt.Errorf("inspect output ancestor %q: %w", part, err)
+		}
+		if info.Mode()&os.ModeSymlink != 0 || !info.IsDir() {
+			return false, fmt.Errorf("output ancestor %q is not a directory without symlinks", part)
+		}
+		next, err := current.OpenRoot(part)
+		if err != nil {
+			return false, fmt.Errorf("open output ancestor %q: %w", part, err)
+		}
+		opened = append(opened, next)
+		current = next
+	}
+	leaf := parts[len(parts)-1]
+	info, err := current.Lstat(leaf)
+	if errors.Is(err, os.ErrNotExist) {
+		return false, nil
+	}
+	if err != nil {
+		return false, fmt.Errorf("inspect output %q: %w", normalized, err)
+	}
+	if info.Mode()&os.ModeSymlink != 0 || !info.Mode().IsRegular() {
+		return false, fmt.Errorf("output %q is not a regular file without symlinks", normalized)
+	}
+	return true, nil
+}
+
+func hashRegularFileWithContext(ctx context.Context, path string) (string, int64, error) {
+	if err := contextError(ctx); err != nil {
+		return "", 0, err
+	}
+	file, err := os.Open(path)
+	if err != nil {
+		return "", 0, err
+	}
+	info, err := file.Stat()
+	if err != nil {
+		_ = file.Close()
+		return "", 0, err
+	}
+	if !info.Mode().IsRegular() {
+		_ = file.Close()
+		return "", 0, fmt.Errorf("path is not a regular file")
+	}
+	hash := sha256.New()
+	size, copyErr := io.Copy(hash, &contextReadChecker{ctx: ctx, reader: file})
+	closeErr := file.Close()
+	if copyErr != nil {
+		return "", 0, copyErr
+	}
+	if closeErr != nil {
+		return "", 0, closeErr
+	}
+	if err := contextError(ctx); err != nil {
+		return "", 0, err
+	}
+	if size != info.Size() {
+		return "", 0, fmt.Errorf("file size changed while reading")
+	}
+	return hex.EncodeToString(hash.Sum(nil)), size, nil
+}
+
+type contextReadChecker struct {
+	ctx    context.Context
+	reader io.Reader
+}
+
+func (r *contextReadChecker) Read(buffer []byte) (int, error) {
+	if err := contextError(r.ctx); err != nil {
+		return 0, err
+	}
+	return r.reader.Read(buffer)
+}
+
+func contextError(ctx context.Context) error {
+	if ctx == nil {
+		return nil
+	}
+	select {
+	case <-ctx.Done():
+		return ctx.Err()
+	default:
+		return nil
+	}
+}

internal/stage/transcribe_reconciliation_test.go

@@ -0,0 +1,316 @@
+package stage
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"reflect"
+	"slices"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
+	"gitea.maximumdirect.net/eric/narratio/internal/manifest"
+)
+
+func TestReconcileTranscribeSpeakersReusesUnchangedCompletedEvidence(t *testing.T) {
+	env, m := setupCurrentTranscribeReconciliation(t, []string{"bob.flac", "alice.flac"})
+	reconciled, err := reconcileTranscribeSpeakers(context.Background(), env, m)
+	if err != nil {
+		t.Fatalf("reconcileTranscribeSpeakers() error = %v", err)
+	}
+	if got := reconciliationSpeakerIDs(reconciled.jobs); !slices.Equal(got, []string{"alice", "bob"}) {
+		t.Fatalf("jobs = %#v, want sorted speakers", got)
+	}
+	if len(reconciled.current) != 2 || len(reconciled.work) != 0 {
+		t.Fatalf("reconciliation = current %d work %d, want 2/0", len(reconciled.current), len(reconciled.work))
+	}
+
+	// Manifest paths may be session-relative; reconciliation must not resolve
+	// them against the process working directory.
+	for index := range m.Inputs {
+		if m.Inputs[index].Kind == "audio" {
+			relative, relErr := filepath.Rel(sessionPathsForEnv(env, m.SessionID).Root, m.Inputs[index].Path)
+			if relErr != nil {
+				t.Fatal(relErr)
+			}
+			m.Inputs[index].Path = filepath.ToSlash(relative)
+		}
+	}
+	reconciled, err = reconcileTranscribeSpeakers(context.Background(), env, m)
+	if err != nil || len(reconciled.current) != 2 || len(reconciled.work) != 0 {
+		t.Fatalf("session-relative reconciliation = %#v, error %v", reconciled, err)
+	}
+}
+
+func TestTranscribeResumeAcceptsEquivalentOutputsAndInspectsRemovalReadOnly(t *testing.T) {
+	env, m := setupCurrentTranscribeReconciliation(t, []string{"alice.flac", "bob.flac"})
+	record := m.Stages["transcribe"]
+	record.Status = manifest.StatusSucceeded
+	// Reverse speaker order and mix the supported local path representations.
+	bob := record.TranscribeSpeakers["bob"].Output
+	bob.LocalPath = filepath.Join(sessionPathsForEnv(env, m.SessionID).Root, filepath.FromSlash(bob.LocalPath))
+	record.Outputs = []manifest.ArtifactRecord{bob, record.TranscribeSpeakers["alice"].Output}
+	validation, err := (transcribeStage{}).ValidateResume(context.Background(), env, m)
+	if err != nil || !validation.Resumable {
+		t.Fatalf("equivalent aggregate: %#v, %v", validation, err)
+	}
+	m.Inputs = slices.DeleteFunc(m.Inputs, func(in manifest.InputRecord) bool { return filepath.Base(in.Path) == "bob.flac" })
+	before := cloneManifestForTranscribeCheckpoint(m)
+	validation, err = (transcribeStage{}).ValidateResume(context.Background(), env, m)
+	if err != nil || validation.Resumable {
+		t.Fatalf("removed speaker: %#v, %v", validation, err)
+	}
+	if !reflect.DeepEqual(m, before) {
+		t.Fatal("resume inspection mutated manifest")
+	}
+}
+
+func TestReconcileTranscribeSpeakersReplacesOnlyChangedAudio(t *testing.T) {
+	env, m := setupCurrentTranscribeReconciliation(t, []string{"alice.flac", "bob.flac"})
+	paths := sessionPathsForEnv(env, m.SessionID)
+	writeFile(t, filepath.Join(paths.AudioDir, "alice.flac"), "replacement audio")
+
+	reconciled, err := reconcileTranscribeSpeakers(context.Background(), env, m)
+	if err != nil {
+		t.Fatalf("reconcileTranscribeSpeakers() error = %v", err)
+	}
+	if got := reconciliationSpeakerIDs(reconciled.work); !slices.Equal(got, []string{"alice"}) {
+		t.Fatalf("work = %#v, want alice", got)
+	}
+	if _, current := reconciled.current["bob"]; !current || len(reconciled.current) != 1 {
+		t.Fatalf("current = %#v, want only bob", reconciled.current)
+	}
+}
+
+func TestReconcileTranscribeSpeakersTracksSemanticAndExcludesOperationalSettings(t *testing.T) {
+	for _, test := range []struct {
+		name   string
+		mutate func(*Env)
+		work   bool
+	}{
+		{name: "service URL", mutate: func(env *Env) { env.Config.Pipeline.WhisperX.TranscribeURL = "https://other.example/transcribe" }, work: true},
+		{name: "language", mutate: func(env *Env) { env.Config.Pipeline.WhisperX.Language = "fr" }, work: true},
+		{name: "timeout", mutate: func(env *Env) { env.Config.Pipeline.WhisperX.Timeout = "45m" }},
+		{name: "retry policy", mutate: func(env *Env) {
+			retries := 9
+			env.Config.Pipeline.WhisperX.Retries = &retries
+			env.Config.Pipeline.WhisperX.RetryDelay = "15s"
+		}},
+		{name: "concurrency", mutate: func(env *Env) {
+			concurrency := 1
+			env.Config.Pipeline.WhisperX.Concurrency = &concurrency
+		}},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			env, m := setupCurrentTranscribeReconciliation(t, []string{"alice.flac"})
+			test.mutate(env)
+			reconciled, err := reconcileTranscribeSpeakers(context.Background(), env, m)
+			if err != nil {
+				t.Fatalf("reconcileTranscribeSpeakers() error = %v", err)
+			}
+			if test.work {
+				if len(reconciled.work) != 1 || len(reconciled.current) != 0 {
+					t.Fatalf("semantic change reconciliation = current %d work %d", len(reconciled.current), len(reconciled.work))
+				}
+			} else if len(reconciled.work) != 0 || len(reconciled.current) != 1 {
+				t.Fatalf("operational change reconciliation = current %d work %d", len(reconciled.current), len(reconciled.work))
+			}
+		})
+	}
+}
+
+func TestReconcileTranscribeSpeakersHandlesAddedAndRemovedInputs(t *testing.T) {
+	env, m := setupCurrentTranscribeReconciliation(t, []string{"alice.flac", "bob.flac"})
+	paths := sessionPathsForEnv(env, m.SessionID)
+	caraPath := filepath.Join(paths.AudioDir, "cara.flac")
+	writeFile(t, caraPath, "cara audio")
+	m.Inputs = append(m.Inputs, manifest.InputRecord{Kind: "audio", Path: caraPath})
+
+	reconciled, err := reconcileTranscribeSpeakers(context.Background(), env, m)
+	if err != nil {
+		t.Fatalf("reconcile added input error = %v", err)
+	}
+	if got := reconciliationSpeakerIDs(reconciled.work); !slices.Equal(got, []string{"cara"}) || len(reconciled.current) != 2 {
+		t.Fatalf("added input reconciliation = current %#v work %#v", reconciled.current, got)
+	}
+
+	inputs := m.Inputs[:0]
+	for _, input := range m.Inputs {
+		if input.Kind != "audio" || filepath.Base(input.Path) != "bob.flac" {
+			inputs = append(inputs, input)
+		}
+	}
+	m.Inputs = inputs
+	reconciled, err = reconcileTranscribeSpeakers(context.Background(), env, m)
+	if err != nil {
+		t.Fatalf("reconcile removed input error = %v", err)
+	}
+	if got := reconciliationSpeakerIDs(reconciled.jobs); !slices.Equal(got, []string{"alice", "cara"}) {
+		t.Fatalf("jobs after removal = %#v", got)
+	}
+	if _, retained := reconciled.current["bob"]; retained {
+		t.Fatalf("removed bob record retained in current collection: %#v", reconciled.current)
+	}
+}
+
+func TestReconcileTranscribeSpeakersTreatsMissingAndCorruptRegularOutputsAsWork(t *testing.T) {
+	for _, test := range []struct {
+		name   string
+		mutate func(*testing.T, string)
+	}{
+		{name: "missing", mutate: func(t *testing.T, path string) {
+			if err := os.Remove(path); err != nil {
+				t.Fatal(err)
+			}
+		}},
+		{name: "invalid JSON", mutate: func(t *testing.T, path string) { writeFile(t, path, "not-json") }},
+		{name: "checksum mismatch", mutate: func(t *testing.T, path string) { writeFile(t, path, `{"speaker":"changed"}`) }},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			env, m := setupCurrentTranscribeReconciliation(t, []string{"alice.flac"})
+			path := filepath.Join(sessionPathsForEnv(env, m.SessionID).TranscriptsRawDir, "alice.json")
+			test.mutate(t, path)
+			reconciled, err := reconcileTranscribeSpeakers(context.Background(), env, m)
+			if err != nil {
+				t.Fatalf("reconcileTranscribeSpeakers() error = %v", err)
+			}
+			if len(reconciled.current) != 0 || len(reconciled.work) != 1 {
+				t.Fatalf("reconciliation = current %d work %d, want 0/1", len(reconciled.current), len(reconciled.work))
+			}
+		})
+	}
+}
+
+func TestReconcileTranscribeSpeakersRejectsUnsafeEvidenceAndMissingAudio(t *testing.T) {
+	t.Run("unsafe record path", func(t *testing.T) {
+		env, m := setupCurrentTranscribeReconciliation(t, []string{"alice.flac"})
+		record := m.Stages["transcribe"].TranscribeSpeakers["alice"]
+		record.Output.LocalPath = "../alice.json"
+		m.Stages["transcribe"].TranscribeSpeakers["alice"] = record
+		_, err := reconcileTranscribeSpeakers(context.Background(), env, m)
+		if err == nil || !strings.Contains(err.Error(), "unsafe") {
+			t.Fatalf("error = %v, want unsafe record path", err)
+		}
+	})
+
+	t.Run("non-regular output", func(t *testing.T) {
+		env, m := setupCurrentTranscribeReconciliation(t, []string{"alice.flac"})
+		path := filepath.Join(sessionPathsForEnv(env, m.SessionID).TranscriptsRawDir, "alice.json")
+		if err := os.Remove(path); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.Mkdir(path, 0o755); err != nil {
+			t.Fatal(err)
+		}
+		_, err := reconcileTranscribeSpeakers(context.Background(), env, m)
+		if err == nil || !strings.Contains(err.Error(), "not a regular file") {
+			t.Fatalf("error = %v, want non-regular safety error", err)
+		}
+	})
+
+	t.Run("missing audio", func(t *testing.T) {
+		env, m := setupCurrentTranscribeReconciliation(t, []string{"alice.flac"})
+		if err := os.Remove(filepath.Join(sessionPathsForEnv(env, m.SessionID).AudioDir, "alice.flac")); err != nil {
+			t.Fatal(err)
+		}
+		_, err := reconcileTranscribeSpeakers(context.Background(), env, m)
+		if err == nil || !strings.Contains(err.Error(), "not found") {
+			t.Fatalf("error = %v, want missing audio input error", err)
+		}
+	})
+}
+
+func TestReconcileTranscribeSpeakersForceAndLegacyStateSelectAllWork(t *testing.T) {
+	for _, test := range []struct {
+		name   string
+		mutate func(*Env, *manifest.Manifest)
+	}{
+		{name: "force", mutate: func(env *Env, _ *manifest.Manifest) { env.Force = true }},
+		{name: "legacy aggregate only", mutate: func(_ *Env, m *manifest.Manifest) {
+			stage := m.Stages["transcribe"]
+			stage.TranscribeStateVersion = 0
+			stage.TranscribeSpeakers = nil
+		}},
+		{name: "versioned empty", mutate: func(_ *Env, m *manifest.Manifest) {
+			m.Stages["transcribe"].TranscribeSpeakers = map[string]manifest.TranscribeSpeakerRecord{}
+		}},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			env, m := setupCurrentTranscribeReconciliation(t, []string{"alice.flac", "bob.flac"})
+			test.mutate(env, m)
+			reconciled, err := reconcileTranscribeSpeakers(context.Background(), env, m)
+			if err != nil {
+				t.Fatalf("reconcileTranscribeSpeakers() error = %v", err)
+			}
+			if len(reconciled.current) != 0 || len(reconciled.work) != 2 {
+				t.Fatalf("reconciliation = current %d work %d, want 0/2", len(reconciled.current), len(reconciled.work))
+			}
+		})
+	}
+}
+
+func TestReconcileTranscribeSpeakersHonorsCancellationWhileInspectingInputs(t *testing.T) {
+	env, m := setupCurrentTranscribeReconciliation(t, []string{"alice.flac"})
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	_, err := reconcileTranscribeSpeakers(ctx, env, m)
+	if !errors.Is(err, context.Canceled) {
+		t.Fatalf("error = %v, want context cancellation", err)
+	}
+}
+
+func setupCurrentTranscribeReconciliation(t *testing.T, audioFiles []string) (*Env, *manifest.Manifest) {
+	t.Helper()
+	env, m := setupTranscribeEnv(t, audioFiles)
+	if _, err := (prepareStage{}).Run(context.Background(), env, m); err != nil {
+		t.Fatalf("prepare.Run() error = %v", err)
+	}
+	initial, err := reconcileTranscribeSpeakers(context.Background(), env, m)
+	if err != nil {
+		t.Fatalf("initial reconciliation error = %v", err)
+	}
+	records := make(map[string]manifest.TranscribeSpeakerRecord, len(initial.work))
+	for _, candidate := range initial.work {
+		if err := writeJSONFile(candidate.canonicalOutputPath, map[string]any{"speaker": candidate.speakerID}); err != nil {
+			t.Fatal(err)
+		}
+		checksum, err := artifacts.SHA256File(candidate.canonicalOutputPath)
+		if err != nil {
+			t.Fatal(err)
+		}
+		info, err := os.Stat(candidate.canonicalOutputPath)
+		if err != nil {
+			t.Fatal(err)
+		}
+		records[candidate.speakerID] = manifest.TranscribeSpeakerRecord{
+			FingerprintVersion: manifest.TranscribeFingerprintContractVersion,
+			Fingerprint:        candidate.fingerprint,
+			AudioPath:          candidate.audioRelativePath,
+			AudioSHA256:        candidate.audioSHA256,
+			AudioSize:          candidate.audioSize,
+			Output: manifest.ArtifactRecord{
+				Kind: "transcript_raw", LocalPath: candidate.outputRelativePath,
+				Checksum: checksum, ProducerRunID: "run-current",
+			},
+			OutputSize: info.Size(), ProducerRunID: "run-current",
+		}
+	}
+	now := time.Date(2026, 9, 21, 12, 0, 0, 0, time.UTC)
+	m.Stages["transcribe"] = &manifest.StageRecord{
+		Name: "transcribe", Status: manifest.StatusFailed, CreatedAt: now, UpdatedAt: now,
+		TranscribeStateVersion: manifest.TranscribeStateContractVersion,
+		TranscribeSpeakers:     records,
+	}
+	return env, m
+}
+
+func reconciliationSpeakerIDs(jobs []transcribeReconciliationJob) []string {
+	ids := make([]string, 0, len(jobs))
+	for _, job := range jobs {
+		ids = append(ids, job.speakerID)
+	}
+	return ids
+}

internal/stage/transcribe_resume.go

@@ -0,0 +1,60 @@
+package stage
+
+import (
+	"context"
+	"fmt"
+	"sort"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
+	"gitea.maximumdirect.net/eric/narratio/internal/manifest"
+)
+
+func (transcribeStage) ValidateResume(
+	ctx context.Context,
+	env *Env,
+	m *manifest.Manifest,
+) (ResumeValidation, error) {
+	reconciliation, err := reconcileTranscribeSpeakers(ctx, env, m)
+	if err != nil {
+		return ResumeValidation{}, fmt.Errorf("transcribe resume: reconcile speakers: %w", err)
+	}
+	if len(reconciliation.work) == 0 {
+		paths := sessionPathsForEnv(env, m.SessionID)
+		if !transcribeAggregateCurrent(m.Stages["transcribe"], reconciliation.current, paths) {
+			return NonResumable("speaker collection or aggregate outputs require reconciliation"), nil
+		}
+		return Resumable(), nil
+	}
+	speakers := make([]string, 0, len(reconciliation.work))
+	for _, job := range reconciliation.work {
+		speakers = append(speakers, job.speakerID)
+	}
+	sort.Strings(speakers)
+	return NonResumable("speaker transcripts require execution: " + strings.Join(speakers, ", ")), nil
+}
+
+// No HTTP work does not imply that the aggregate is current. The reconciled
+// collection is a subset of the stored records, so its cardinality also detects
+// removed speakers. Compare local output evidence independently of list order
+// and of the supported absolute/session-relative path representations.
+func transcribeAggregateCurrent(record *manifest.StageRecord, current map[string]manifest.TranscribeSpeakerRecord, paths artifacts.SessionPaths) bool {
+	if len(record.TranscribeSpeakers) != len(current) || len(record.Outputs) != len(current) {
+		return false
+	}
+	expected := make(map[string]manifest.ArtifactRecord, len(current))
+	for _, speaker := range current {
+		expected[artifacts.ResolveSessionLocalPathForRead(paths, speaker.Output.LocalPath)] = speaker.Output
+	}
+	for _, output := range record.Outputs {
+		path := artifacts.ResolveSessionLocalPathForRead(paths, output.LocalPath)
+		want, ok := expected[path]
+		if !ok || output.Kind != want.Kind || output.Checksum != want.Checksum || output.ProducerRunID != want.ProducerRunID {
+			return false
+		}
+		delete(expected, path)
+	}
+	return len(expected) == 0
+}
+
+var _ ResumeValidator = transcribeStage{}

internal/stage/transcribe_test.go

@@ -322,7 +322,7 @@ func TestTranscribeStagePreservesDistinctSameBasenameAudio(t *testing.T) {
 	}
 }
 
-func TestTranscribeStageCancellationDoesNotMaterializePartialOutputs(t *testing.T) {
+func TestTranscribeStageCancellationPreservesCheckpointedOutputs(t *testing.T) {
 	env, m := setupTranscribeEnv(t, []string{"alice.flac", "bob.flac", "cara.flac"})
 	m.RunID = "20260810T214607Z-a1b2c3d4"
 	fastComplete := make(chan struct{})
@@ -351,6 +351,21 @@ func TestTranscribeStageCancellationDoesNotMaterializePartialOutputs(t *testing.
 	}()
 	select {
 	case <-fastComplete:
+		manifestPath := sessionPathsForEnv(env, m.SessionID).ManifestPath
+		deadline := time.Now().Add(time.Second)
+		for {
+			durable, err := env.ManifestStore.Load(context.Background(), manifestPath)
+			if err == nil {
+				if _, ok := durable.Stages["transcribe"].TranscribeSpeakers["alice"]; ok {
+					break
+				}
+			}
+			if time.Now().After(deadline) {
+				cancel()
+				t.Fatal("alice completion was not checkpointed before cancellation")
+			}
+			time.Sleep(5 * time.Millisecond)
+		}
 		cancel()
 	case <-time.After(time.Second):
 		cancel()
@@ -365,8 +380,15 @@ func TestTranscribeStageCancellationDoesNotMaterializePartialOutputs(t *testing.
 	}
 
 	canonical := filepath.Join(sessionPathsForEnv(env, m.SessionID).TranscriptsRawDir, "alice.json")
-	if _, err := os.Stat(canonical); !os.IsNotExist(err) {
+	if _, err := os.Stat(canonical); err != nil {
-		t.Fatalf("partial canonical output should not exist, stat err = %v", err)
+		t.Fatalf("checkpointed canonical output missing: %v", err)
+	}
+	durable, err := env.ManifestStore.Load(context.Background(), sessionPathsForEnv(env, m.SessionID).ManifestPath)
+	if err != nil {
+		t.Fatalf("load checkpointed manifest: %v", err)
+	}
+	if _, ok := durable.Stages["transcribe"].TranscribeSpeakers["alice"]; !ok {
+		t.Fatalf("checkpointed speakers = %#v, want alice", durable.Stages["transcribe"].TranscribeSpeakers)
 	}
 }
 
@@ -454,8 +476,13 @@ func setupTranscribeEnv(t *testing.T, audioFiles []string) (*Env, *manifest.Mani
 	env := &Env{
 		Config:        cfg,
 		ArtifactStore: artifacts.NewLocalStore(workspace),
+		ManifestStore: &manifest.LocalStore{},
 	}
-	return env, manifest.New("2026-05-03", time.Now().UTC())
+	m := manifest.New("2026-05-03", time.Now().UTC())
+	m.Campaign = "sample-campaign"
+	m.RunID = "20260503T010203Z-a1b2c3d4"
+	m.MarkStageRunning("transcribe", time.Now().UTC())
+	return env, m
 }
 
 func writeJSONFile(path string, payload any) error {