eric/narratio
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 15 Wiki Activity

Reconcile Notarius extraction documentation

Browse Source
This commit is contained in:
Eric Rakestraw
2026-08-10 02:10:37 +00:00
parent 665039f4dc
commit 701b6726d7
8 changed files with 113 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
docs/internal/stage-extract.md
View File

@@ -4,8 +4,8 @@
`extract` runs after `trim` and before `render`. It converts the canonical
`narratio.transcript.final_trimmed` JSON into configured Notarius lane artifacts.
An omitted or disabled Notarius section makes the stage succeed as a no-op and
does not require a Notarius runner.
An omitted or disabled Notarius section makes the stage explicitly self-skip
with reason `notarius_disabled`, no outputs, and no Notarius runner.
The external protocol is documented in the
[Notarius integration contract](../integrations/notarius.md). Configuration
@@ -34,6 +34,10 @@ root, receipt, diagnostic paths, rejection/warning summaries, producing
Narratio run ID, and invocation fingerprint. Validation completes before
promotion, so a rejected result cannot expose a partial durable bundle.
Any executed extraction outcome that replaces a different effective outcome
marks succeeded downstream stages stale. Repeating the same disabled self-skip
with no outputs is stable and does not repeatedly invalidate downstream stages.
## Resume Validation
`internal/stage/extract_resume.go` permits a skip only when the existing stage
@@ -63,14 +67,12 @@ has passed validation and promotion.
## Implementation And Focused Tests
- Stage execution and selection: `internal/stage/extract.go`,
- Stage execution, selection, and resume validation: `internal/stage/extract.go`,
`internal/stage/extract_resume.go`,
`internal/stage/extract_test.go`
- Resume validation: `internal/stage/extract_resume.go`,
`internal/stage/extract_resume_test.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`

11
docs/internal/stage-publish.md
View File

@@ -26,8 +26,13 @@ Exact remote placement and the operator workflow belong in
- stage can self-skip when publish disabled or run upload disabled.
- validates prerequisite stage success and object-store availability.
- collects deterministic run file list plus run `manifest.json`.
- collects a deterministic run file list plus run `manifest.json`, excluding
`audio/**` and the run-local `extract/notarius-output/**` staging bundle.
- keeps run-local Notarius receipt and stderr diagnostics eligible for the run
archive.
- resolves publish output sources through runtime artifact catalog and manifest-aware resolution.
- publishes extraction lanes only through explicit configured output rules;
neither run-local nor durable Notarius bundles are scanned or uploaded wholesale.
- selected artifact filter applies to configured artifact sources only.
- locked outputs are skipped intentionally (including required ones).
- optional missing outputs are skipped; required missing unlocked outputs fail.
@@ -48,7 +53,9 @@ Includes counts/lists for:
## Invariants
- `current/run_id.txt` is the remote commit marker and is written last.
- run upload excludes `audio/**`.
- run upload excludes `audio/**` and `extract/notarius-output/**`.
- `extract/notarius.receipt.json` and `extract/notarius.stderr.log` remain
eligible run-record diagnostics.
- publish locks are not overridden by `--force`.
The commit boundary and cleanup gate are normative architecture invariants; see