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

Document Notarius configuration profiles

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-21 15:16:11 +00:00
parent a51a513804
commit 3438fe82c9
7 changed files with 109 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -23,11 +23,13 @@ procedures belong in [Operations](../operations.md).
reusing verified bytes or reconstructing a missing/corrupt regular entry,
and rejects any source change observed while copying;
4. fingerprints the byte- and provenance-bearing Notarius invocation evidence,
including sorted reference identities;
including sorted reference identities and the explicit downstream
configuration-profile selection;
5. creates a run-local staging directory and invokes the injected
`notarius.Runner`, carrying the optional already-resolved credential
reference without exposing its value, plus effective resume and chunk-cache
controls after force precedence;
reference without exposing its value, the optional exact configuration
profile, plus effective resume and chunk-cache controls after force
precedence;
6. revalidates the reference snapshots, then validates the v2 successful
receipt, confined index, management documents, configured required lane
descriptors, validation summaries, and regular payload files;
@@ -70,7 +72,9 @@ outputs is stable and does not repeatedly invalidate dependent stages.
Before the focused validator runs, the application compares extract's versioned
semantic fingerprint. It covers enablement, Notarius pipeline identity, sorted
reference selector/source mappings, sorted declared output contracts, and each
canonical `narratio.extraction.<key>` output identity. It excludes executable,
canonical `narratio.extraction.<key>` output identity. It also covers the
explicit Notarius configuration-profile selection; omitted, empty, and exact
`default` selectors share the base-selection identity. It excludes executable,
timeout, working directory, config path, and private Notarius config contents.
Credential presence, reference name, and resolved value are likewise
operational-only and excluded. Ordinary command loading still resolves a
@@ -81,13 +85,15 @@ not rerun a valid completed extraction or stale its dependents.
stage record still matches the current byte- and provenance-bearing invocation
evidence. That evidence covers the current direct trimmed-transcript identity,
sorted prepared-reference identities, pipeline identity, and configured output
contracts. The same reference helper and transcript identity are resolved again
for artifact evidence, so changing current transcript bytes, reference bytes,
or producer identity makes the prior extraction obsolete. Operational runner
settings do not invalidate otherwise current durable evidence. This includes
`resume` and `chunk_cache`; changing them alone cannot make a complete
extraction non-resumable. If extraction executes, ordinary runs forward the
configured values, while force disables resume and selects `refresh`.
contracts, plus the same downstream profile-selection identity. The same
reference helper and transcript identity are resolved again for artifact
evidence, so changing current transcript bytes, reference bytes, producer
identity, or a named downstream selection makes the prior extraction obsolete.
Operational runner settings do not invalidate otherwise current durable
evidence. This includes `resume` and `chunk_cache`; changing them alone cannot
make a complete extraction non-resumable. If extraction executes, ordinary
runs forward the configured values, while force disables resume and selects
`refresh`.
A valid prepared-reference change makes extraction non-resumable. Missing,
unsafe, or checksum-inconsistent prepared evidence is a hard validation error
@@ -100,10 +106,12 @@ contracts and provenance, regular-file status, and stored checksums. Missing or
obsolete results are non-resumable and run again; unsafe filesystem conditions
return an error rather than silently accepting or replacing data.
Neither contract can observe files imported by Notarius configuration, profile
contents, prompt/module definitions, or other transitive inputs. Operators must
force extraction after changing any such private input behind a stable
identifier.
This sensitivity is limited to the explicit downstream selector. Narratio's
own profile label and whole effective-configuration digest are not blanket
extraction invalidators. Neither contract can observe files imported by
Notarius configuration, profile contents, prompt/module definitions, or other
transitive inputs. Operators must force extraction after changing any such
private input behind a stable identifier.
## Failure Behavior