Document resumable transcription and replay

docs/internal/manifest.md

@@ -50,6 +50,43 @@ 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.
+
+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 +193,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.
-The runner then attempts to persist the bounded failed/stale retry collection;
-if that terminal save also fails, its error is joined with the originating
-failure and the next invocation must reconcile from the last readable manifest.
+A transcribe or analyze checkpoint error leaves the prior manifest collection
+as authority. The runner then attempts to persist the aggregate failure; if
+that terminal save also fails, its error is joined with the originating failure
+and the next invocation must reconcile from the last readable manifest.
 
 ## Execution Semantics
 
@@ -193,11 +230,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
-per-artifact collection. This lets later reconciliation replace only evaluated
-entries without erasing unrelated current results. Other stages retain their
-existing aggregate-only lifecycle behavior and are forbidden from carrying the
-analyze-specific fields.
+Aggregate lifecycle clearing deliberately preserves both the transcribe-owned
+speaker collection and the analyze-owned per-artifact collection. This lets
+later reconciliation replace only non-current entries without erasing durable
+completions. Other stages retain aggregate-only lifecycle behavior and are
+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 +265,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 +347,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/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.
-- derives the transcript identity from the prepared `.flac` filename.
-- dispatches one WhisperX request per prepared file through a bounded errgroup.
-- validates each output as JSON.
-- writes run-local outputs then materializes canonical transcript outputs only
-  after every planned request succeeds.
+- discovers prepared audio from manifest inputs or the canonical audio
+  directory and derives each speaker identity from its `.flac` filename.
+- hashes the current audio and reconciles it with the versioned per-speaker
+  completion collection before starting HTTP work.
+- reuses only records whose audio identity, observable WhisperX semantics,
+  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,44 @@ 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
-  incomplete dispatch cannot be reported as a successful result.
+- candidate collection construction, manifest save, and installation into live
+  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
-the Narratio-visible WhisperX service URL and recognition language. Changes to
-either rerun transcription and stale its fixed descendants while leaving
-prepare reusable. Retry count/delay, concurrency, timeout, credentials, and
-diagnostic locations are operational and do not change this evidence.
+Each completed speaker record binds the speaker ID, session-relative audio
+path, streamed audio checksum and size, the Narratio-visible WhisperX service
+URL and recognition language, and the canonical transcript path, checksum,
+size, and producer run. Changed audio bytes select that speaker for replacement;
+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. `--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
-selected.
+An older aggregate-only transcribe record has no trustworthy audio-to-output
+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 +81,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/semantic_contracts_initial_test.go`
+  `internal/stage/transcribe_reconciliation_test.go`, and
+  `internal/stage/transcribe_checkpoint_test.go`