Protect initial pipeline stage resume semantics

This commit is contained in:
2026-08-30 12:54:38 +00:00
parent 82cb53e107
commit 4d6086fefb
13 changed files with 549 additions and 5 deletions

View File

@@ -29,9 +29,23 @@ Normalize raw transcript inputs and merge into base transcript via Seriatim.
- base transcript must validate before stage success.
- report output is config-gated.
## Resume Evidence
Merge records a versioned semantic-configuration fingerprint for the Seriatim
merge operation, output schema, coalesce gap, and every configured advanced
merge transformation. A change reruns merge and stales only its fixed
descendants; prepare and transcribe remain reusable. Binary path, timeout,
report emission, logs, and diagnostic retention are operational exclusions.
Configuration or resources loaded privately inside Seriatim are outside
Narratio's observable contract and require `--force` when changed. An existing
successful merge record without evidence reruns once when selected.
## Related Contracts And Tests
- [Seriatim](../integrations/seriatim.md) owns subprocess and output semantics.
- [Configuration](../config.md#pipeline) owns operator-selected Seriatim values.
- Implementation and tests: `internal/stage/merge.go`,
`internal/stage/merge_test.go`
`internal/stage/merge_test.go`,
`internal/stage/semantic_contracts_initial.go`, and
`internal/stage/semantic_contracts_initial_test.go`

View File

@@ -57,6 +57,21 @@ mapping, while the isolated legacy reader rejects ambiguous fallback matches.
- managed `previous/` state represents only the current requirement set.
- `manifest.inputs` ordering is deterministic (`kind`, `path`).
## Resume Evidence
Prepare records a versioned semantic-configuration fingerprint for the
resolved campaign/session selection, local-versus-S3 audio mode and canonical
audio names, stable-input ownership/presence, previous-session identity, and
the effective previous-artifact requirement set. A change reruns prepare and
stales its fixed descendants. Existing successful records without this
evidence rerun once when selected.
Workspace, spool, and cache placement and absolute source relocation are not
semantic when logical selection, canonical names, and bytes are equivalent.
The fingerprint deliberately does not read or rehash large audio. Prepared
input checksums remain the content provenance; force prepare after changing
source bytes that are not otherwise reflected by the semantic selection.
## Related Contracts And Tests
- [Configuration](../config.md) owns audio selection, stable input fields, and
@@ -66,5 +81,8 @@ mapping, while the isolated legacy reader rejects ambiguous fallback matches.
- [Storage Internals](storage.md) and [Artifact Internals](artifacts.md) explain
the internal collaborators.
- Implementation and tests: `internal/stage/prepare.go`,
`internal/stage/prepare_test.go`, `internal/audio/s3_audio_test.go`,
`internal/stage/prepare_test.go`,
`internal/stage/semantic_contracts_initial.go`,
`internal/stage/semantic_contracts_initial_test.go`,
`internal/audio/s3_audio_test.go`,
`internal/previouscache/*_test.go`

View File

@@ -31,6 +31,19 @@ Generate raw per-speaker transcripts from prepared audio using WhisperX.
- each successful output is validated before stage success, and cancellation or
incomplete dispatch cannot be reported as a successful result.
## 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.
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.
## Related Contracts And Tests
- [WhisperX](../integrations/whisperx.md) owns HTTP, retry, timeout, and
@@ -38,4 +51,6 @@ Generate raw per-speaker transcripts from prepared audio using WhisperX.
- [Configuration](../config.md#pipeline) owns concurrency and other
operator-selected values.
- Implementation and tests: `internal/stage/transcribe.go`,
`internal/stage/transcribe_test.go`
`internal/stage/transcribe_test.go`,
`internal/stage/semantic_contracts_initial.go`, and
`internal/stage/semantic_contracts_initial_test.go`

View File

@@ -88,7 +88,9 @@ Canonical stage order:
Execution rules:
- succeeded stages are skipped unless `--force` is set;
- succeeded stages are skipped unless `--force` is set; stages with semantic
configuration contracts additionally require matching versioned evidence,
and missing legacy evidence causes a safe one-time rerun;
- `run` continues interrupted or partially completed sessions by running non-succeeded stages;
- forcing a stage marks succeeded transitive dependents as `stale` before the
replacement runs; render and extract are independent siblings; and
@@ -97,6 +99,15 @@ Execution rules:
repeated self-skip with the same reason and no outputs is stable and does not
perpetually rerun dependent work.
Prepare, transcribe, and merge currently provide semantic-configuration
evidence. Changing prepare selection semantics reruns all fixed descendants;
changing WhisperX language/service identity reuses prepare; and changing a
Seriatim merge transformation reuses prepare and transcribe. Operational
timeouts, retry/concurrency tuning, executable paths, workspace/cache/spool
placement, reports, diagnostics, and secret values are excluded. Configuration,
models, prompts, modules, or resources loaded privately inside external tools
remain unobservable to Narratio and require an explicit `--force` after change.
An explicit self-skip is a durable `skipped` stage outcome that later runs
reconsider. It differs from successful no-output execution: disabled `render`
and `publish`, and absent or no-executable `analyze`, record `succeeded` with

View File

@@ -303,7 +303,7 @@ configuration before selectable profiles can change those values.
## Stage 4 — Prepare, Transcribe, And Merge Semantic Contracts
**Status: Pending**
**Status: Completed**
### Goal