Document Notarius cache reuse workflow
This commit is contained in:
@@ -7,14 +7,14 @@ lanes from the final trimmed Seriatim transcript. Narratio owns invocation,
|
||||
safe bundle discovery, lane selection, and its own artifact metadata. Notarius
|
||||
owns pipeline definitions, lane schemas, the receipt, and bundle formats.
|
||||
|
||||
Canonical Notarius v0.6.0 references:
|
||||
Canonical Notarius v0.7.0 references:
|
||||
|
||||
- [CLI reference](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.6.0/docs/cli.md)
|
||||
- [Subprocess consumer contract](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.6.0/docs/consumers/subprocess.md)
|
||||
- [D&D pipeline and lane contracts](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.6.0/docs/consumers/dnd-pipeline.md)
|
||||
- [Run-result receipt](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.6.0/docs/integrations/run-result.md)
|
||||
- [JSON output bundle](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.6.0/docs/integrations/json-output.md)
|
||||
- [D&D spell-catalog overlay](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.6.0/docs/integrations/dnd-spell-catalog-overlays.md)
|
||||
- [CLI reference](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.7.0/docs/cli.md)
|
||||
- [Subprocess consumer contract](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.7.0/docs/consumers/subprocess.md)
|
||||
- [D&D pipeline and lane contracts](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.7.0/docs/consumers/dnd-pipeline.md)
|
||||
- [Run-result receipt](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.7.0/docs/integrations/run-result.md)
|
||||
- [JSON output bundle](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.7.0/docs/integrations/json-output.md)
|
||||
- [D&D spell-catalog overlay](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.7.0/docs/integrations/dnd-spell-catalog-overlays.md)
|
||||
|
||||
The [complete Narratio example](../../examples/pipeline.full.annotated.yml)
|
||||
records the exact current constraints for all ten D&D lanes. Treat the linked
|
||||
@@ -25,19 +25,23 @@ duplicate the complete schemas.
|
||||
|
||||
When `pipeline.notarius.enabled` is true, Narratio resolves the executable,
|
||||
configuration path, input path, output directory, and working directory to
|
||||
absolute paths. Narratio requires the Notarius v0.6.0 CLI contract when
|
||||
absolute paths. Narratio requires the Notarius v0.7.0 CLI contract when
|
||||
references are configured and invokes each binding as a separate argument
|
||||
before `--json`:
|
||||
|
||||
```text
|
||||
notarius run <pipeline_id> --config <config_path> --input <trimmed_json> --output-dir <staging_dir> [--reference <selector>=<verified_snapshot_path>]... --json
|
||||
notarius run <pipeline_id> --config <config_path> --input <trimmed_json> --output-dir <staging_dir> [--resume] [--chunk_cache <mode>] [--reference <selector>=<verified_snapshot_path>]... --json
|
||||
```
|
||||
|
||||
Reference paths are absolute invocation-local snapshots streamed from the
|
||||
manifest-verified canonical files prepared inside the current Narratio session
|
||||
workspace. Narratio verifies snapshot checksum and size before and after the
|
||||
subprocess, and passes only configured bindings, ordered lexically by normalized
|
||||
selector, as direct argument-vector entries without shell interpretation. A CLI
|
||||
Reference paths are absolute stable snapshots streamed from manifest-verified
|
||||
canonical files prepared inside the current Narratio session workspace. They
|
||||
live at `cache/notarius/references/<sha256>/<prepared-basename>` and retain the
|
||||
full lowercase content digest. Narratio verifies snapshot checksum and size
|
||||
before and after the subprocess, reconstructs missing or corrupt regular files
|
||||
from a still-valid prepared source, and passes only configured bindings,
|
||||
ordered lexically by normalized selector, as direct argument-vector entries
|
||||
without shell interpretation. Symlinks, directories, other non-regular
|
||||
conflicts, and prepared-source mismatches fail rather than being deleted. A CLI
|
||||
binding takes precedence over a matching external path in Notarius
|
||||
configuration. Narratio never emits `--without-reference`.
|
||||
|
||||
@@ -75,6 +79,17 @@ It does not pass a Narratio session ID or run `notarius config validate`
|
||||
automatically; the configured working directory and Narratio's minimal child
|
||||
environment apply to the subprocess.
|
||||
|
||||
Ordinary extraction maps `pipeline.notarius.resume: true` to `--resume` and a
|
||||
nonempty `pipeline.notarius.chunk_cache` to `--chunk_cache <mode>`. Forced
|
||||
extraction always omits `--resume` and supplies `--chunk_cache refresh`.
|
||||
Notarius owns checkpoint enablement, recording, identity, and both cache roots;
|
||||
Narratio neither reads nor synthesizes its configuration. Use explicit
|
||||
persistent roots in Notarius when reuse must span subprocess invocations.
|
||||
Changing a reference path/digest or other upstream identity input correctly
|
||||
causes a cold miss. Chunk refresh bypasses lookup and publishes the accepted
|
||||
replacement for the active source; it does not delete unrelated plans or
|
||||
checkpoint state.
|
||||
|
||||
When `pipeline.notarius.llm_api_key` is absent or null, Narratio adds no
|
||||
credential to that environment. When configured, the field names an environment
|
||||
variable whose already-loaded nonempty value is forwarded under that exact
|
||||
@@ -98,7 +113,7 @@ encoded credentials.
|
||||
|
||||
## Accepted Result
|
||||
|
||||
Narratio's supported invocation baseline is Notarius v0.6.0. The accepted
|
||||
Narratio's tested invocation baseline is Notarius v0.7.0. The accepted
|
||||
receipt remains `notarius.run-result.v2`; reference flags do not change the
|
||||
receipt or ten-lane output contract. The receipt
|
||||
must identify the configured pipeline, and its `index_file` must be exactly
|
||||
@@ -123,6 +138,8 @@ version, and, when configured, module key. Missing, duplicate, rejected, or
|
||||
incompatible required lanes fail extraction even if Notarius exited zero. A
|
||||
configured lane whose v2 validation summary is `rejected` or `incomplete` also
|
||||
fails extraction.
|
||||
An accepted reused producer may report `producer_attempt_count: 0`; Narratio
|
||||
preserves that valid summary rather than treating it as a missing field.
|
||||
Unconfigured lanes may remain in the preserved bundle but do not become
|
||||
selectable Narratio sources.
|
||||
|
||||
@@ -151,3 +168,18 @@ Configuration fields and defaults are in [Configuration](../config.md).
|
||||
Operator paths, rerun procedures, and bundle retention are in
|
||||
[Operations](../operations.md). See [Troubleshooting](../troubleshooting.md)
|
||||
for failure recovery.
|
||||
|
||||
## Opt-in Integration Test
|
||||
|
||||
The production-boundary cache test requires an absolute path to a locally
|
||||
built Notarius v0.7.0-compatible executable. It uses only a local
|
||||
OpenAI-compatible `httptest` provider and temporary cache/config/output roots:
|
||||
|
||||
```sh
|
||||
NARRATIO_TEST_NOTARIUS_BINARY=/absolute/path/to/notarius \
|
||||
GOWORK=off go test ./internal/stage \
|
||||
-run '^TestNotariusCacheReuseIntegration$' -count=1 -v
|
||||
```
|
||||
|
||||
When the variable is unset, the normal test suite skips this test and never
|
||||
searches `PATH`, a sibling checkout, the network, or a real provider.
|
||||
|
||||
Reference in New Issue
Block a user