diff --git a/docs/internal/manifest.md b/docs/internal/manifest.md index 2759a9d..3f9a2db 100644 --- a/docs/internal/manifest.md +++ b/docs/internal/manifest.md @@ -193,6 +193,25 @@ establish a current immutable snapshot. - writes through a sibling temporary file and atomic replacement visibility; - updates `updated_at` on save. +### Checkpoint persistence boundary + +Analyze and transcribe share one private checkpoint operation in +`internal/stage`. Their typed callers still decide when to checkpoint, validate +their collections, populate stage-owned fields, and serialize access. The +shared operation copies the manifest and its checkpoint-relevant mutable +collections, applies the typed update to the copied target record, and calls +the existing `manifest.Store` exactly once. Only after that save succeeds does +it promote the saved target record and manifest `updated_at` into live state; +it preserves an existing target record's identity and leaves unrelated live +stage records in place. + +The copy boundary includes stage records, input and artifact slices, aggregate +output/log/configuration slices, and the typed analyze and transcribe +collections that callbacks or `LocalStore.Save` may modify. Metadata and other +pointer fields remain shared read-only because neither checkpoint callback nor +the store mutates them. This is a bounded execution helper, not a general +manifest clone or a transaction across transcript/artifact files. + Manifest replacement provides atomic visibility, not a crash- or power-loss durability guarantee. Callers reload after a returned save error before retrying. A transcribe or analyze checkpoint error leaves the prior manifest collection diff --git a/docs/internal/stage-analyze.md b/docs/internal/stage-analyze.md index a6190a1..698df95 100644 --- a/docs/internal/stage-analyze.md +++ b/docs/internal/stage-analyze.md @@ -115,7 +115,11 @@ Supported source families: - before the first adapter call, checkpoints the reconciled starting collection when it removed configuration records or cleared obsolete authority. After each successful artifact, checkpoints the complete collection before making - that artifact available to the next scheduled dependent. + that artifact available to the next scheduled dependent. Analyze supplies + its typed update to the shared + [checkpoint persistence boundary](manifest.md#checkpoint-persistence-boundary) + and refreshes its working and committed collections only after the save + succeeds. - keeps adapter output in the invocation's run-local analyze directory until it is a safe, non-empty, bounded regular file with a calculated checksum and complete output contract. Canonical replacement uses the shared atomic file diff --git a/docs/internal/stage-transcribe.md b/docs/internal/stage-transcribe.md index 2b088ec..616a25f 100644 --- a/docs/internal/stage-transcribe.md +++ b/docs/internal/stage-transcribe.md @@ -35,9 +35,10 @@ 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. -- candidate collection construction, manifest save, and installation into live - state are serialized. Expensive hashing and HTTP work remain outside that - critical section. +- candidate collection construction, the shared + [checkpoint persistence boundary](manifest.md#checkpoint-persistence-boundary), + and installation into live state are serialized by transcribe's mutex. + 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. diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 324a1b7..13a4d25 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -1,6 +1,6 @@ # Implementation Plan: Shared Stage Checkpoint Mechanics -Status: Implementation in progress; Stages 1-3 complete. +Status: Complete. ## Scope and Authority @@ -273,7 +273,24 @@ copy implementation, with their different models and synchronization intact. ## Stage 4: Document, Review Scope, and Validate -Status: Pending. +Status: Complete. + +Completion marker (2026-09-22): Documented the private shared checkpoint +persistence boundary and linked the stage guides back to it while retaining +their separate analyze and transcribe progress policies. The refactor removed +the two local candidate/save/promotion sequences and the transcription-only +bounded clone; the retained thin wrappers own typed validation, updates, +working-state refresh, and their existing serialization and failure behavior. +The collective test review retained focused helper integrity coverage plus +stage/application recovery tests, without duplicating the helper's isolation +matrix. A cumulative scope audit found no schema, validation-policy, +scheduling, force, concurrency, output-selection, stage-order, adapter-call, +configuration, or public-interface change. + +Verified with `go test ./...`, `go test -race ./...`, `go vet ./...`, +`go build ./...`, `go test ./internal/doccheck`, +`go test ./internal/config -run '^TestExamplesLoadAndValidate$'`, and +`git diff --check`; all passed. Preparation: `docs/internal/manifest.md`, `docs/internal/stage-transcribe.md`, `docs/internal/stage-analyze.md`, documentation/testing policies, and the