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

Document prepared Notarius references

Browse Source
This commit is contained in:
Eric Rakestraw
2026-08-29 15:40:23 +00:00
parent 905ff03ccc
commit 3a9e60cda9
15 changed files with 268 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -17,16 +17,19 @@ procedures belong in [Operations](../operations.md).
`internal/stage/extract.go`:
1. resolves the final trimmed transcript from the shared artifact catalog;
2. resolves and fingerprints the Notarius invocation contract;
3. creates a run-local staging directory and invokes the injected
2. resolves every configured prepared reference through the shared
manifest-authoritative identity resolver before creating run-local output;
3. fingerprints the Notarius invocation contract, including sorted reference
identities;
4. creates a run-local staging directory and invokes the injected
`notarius.Runner`;
4. validates the v2 successful receipt, confined index, management documents,
5. validates the v2 successful receipt, confined index, management documents,
configured required lane descriptors, validation summaries, and regular
payload files;
5. atomically promotes the complete bundle to its immutable durable location;
6. records one non-selectable `notarius_index` output and one selectable
6. atomically promotes the complete bundle to its immutable durable location;
7. records one non-selectable `notarius_index` output and one selectable
`notarius_lane` output per configured lane; and
7. registers each lane as `narratio.extraction.<output_key>` for downstream
8. registers each lane as `narratio.extraction.<output_key>` for downstream
Scriptorium and publish resolution.
Lane records retain checksum, contract, producer run ID, and Notarius system,
@@ -35,6 +38,9 @@ root, receipt, diagnostic paths, rejection/warning summaries, producing
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
prepared path, never payload contents.
Validation completes before
promotion, so a rejected result cannot expose a partial durable bundle.
@@ -47,11 +53,16 @@ with no outputs is stable and does not repeatedly invalidate downstream stages.
`internal/stage/extract_resume.go` permits a skip only when the existing stage
record succeeded and still matches the current invocation fingerprint. The
fingerprint covers the resolved executable and config paths, pipeline ID,
timeout, working directory, sorted configured output contracts, and the current
direct trimmed-transcript identity. The same identity is resolved again for
timeout, working directory, sorted configured output contracts, the current
direct trimmed-transcript identity, and sorted prepared-reference identities.
The same reference helper and transcript identity are resolved again for
artifact evidence, so changing the current transcript bytes or producer
identity makes the prior extraction obsolete.
A valid prepared-reference change makes extraction non-resumable. Missing,
unsafe, or checksum-inconsistent prepared evidence is a hard validation error
with prepare-force guidance because an immediate extract rerun cannot succeed.
The validator then checks the producing run identity, canonical immutable
bundle root, path confinement and absence of symlink components, receipt
identity, exactly one canonical index, the exact configured source set,