Reconcile Notarius extraction documentation

This commit is contained in:
2026-08-10 02:10:37 +00:00
parent 665039f4dc
commit 701b6726d7
8 changed files with 113 additions and 33 deletions

View File

@@ -85,7 +85,12 @@ Execution rules:
- succeeded stages are skipped unless `--force` is set;
- `run` continues interrupted or partially completed sessions by running non-succeeded stages;
- force rerunning a succeeded upstream stage marks succeeded downstream stages as `stale`.
- forcing an upstream stage marks succeeded downstream stages as `stale` before
the replacement runs; and
- an executed failure, changed self-skip, or success that replaces a different
effective upstream outcome also marks succeeded downstream stages stale. A
repeated self-skip with the same reason and no outputs is stable and does not
perpetually rerun downstream work.
Single-stage execution:
@@ -108,6 +113,10 @@ Selection behavior:
## Extraction Workflow
When Notarius is omitted or disabled, `extract` records an explicit skipped
outcome with reason `notarius_disabled` and no outputs. A later invocation
reconsiders the skipped stage, so enabling Notarius does not require force.
When Notarius extraction is enabled, the stage consumes the final trimmed JSON
and preserves the complete validated Notarius bundle at:
@@ -130,6 +139,12 @@ Run-local diagnostics are:
- `runs/{run_id}/extract/notarius.stderr.log`
- `runs/{run_id}/extract/notarius-output/` before durable promotion
The run-record upload excludes the complete
`extract/notarius-output/**` subtree. The receipt and stderr files remain
eligible run-record diagnostics. The durable bundle is never scanned for
implicit publication; only lanes named by explicit `pipeline.publish.outputs`
rules are uploaded.
To intentionally replace the current extraction result, run:
```bash
@@ -141,7 +156,9 @@ or durable output validation changes. It cannot fingerprint configuration
files, profiles, prompts, modules, or references loaded transitively by
Notarius. Force extraction after changing any of those inputs, even when the
top-level Narratio and Notarius config paths remain the same. A forced extract
marks successful downstream stages stale through normal continuation behavior.
marks successful downstream stages stale. Ordinary extraction failures or
outcome changes also stale affected downstream stages, while an identical
repeated `notarius_disabled` self-skip does not repeatedly invalidate them.
## Publish Workflow
@@ -159,8 +176,10 @@ narratio run-stage publish 2026-04-04 --force
Publish commit model:
- uploads run files under `{session_prefix}/runs/{run_id}/`;
- uploads configured published outputs;
- uploads eligible run files under `{session_prefix}/runs/{run_id}/`, excluding
audio and the run-local Notarius staging bundle;
- uploads configured published outputs, including only explicitly configured
extraction lanes;
- uploads `previous/**` cache files when present;
- writes `current/manifest.json`;
- writes `current/run_id.txt` last.