127 lines
6.7 KiB
Markdown
127 lines
6.7 KiB
Markdown
# Notarius Integration Contract
|
|
|
|
## Boundary
|
|
|
|
Narratio uses Notarius as a subprocess to extract configured structured JSON
|
|
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:
|
|
|
|
- [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)
|
|
|
|
The [complete Narratio example](../../examples/pipeline.full.annotated.yml)
|
|
records the exact current constraints for all ten D&D lanes. Treat the linked
|
|
Notarius documents as canonical when changing those values; Narratio does not
|
|
duplicate the complete schemas.
|
|
|
|
## Invocation
|
|
|
|
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
|
|
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
|
|
```
|
|
|
|
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
|
|
binding takes precedence over a matching external path in Notarius
|
|
configuration. Narratio never emits `--without-reference`.
|
|
|
|
The maintained D&D boundary binds only the four campaign-owned external slots:
|
|
|
|
```text
|
|
notarius run dnd-session \
|
|
--config <absolute config path> \
|
|
--input <absolute trimmed transcript path> \
|
|
--output-dir <absolute staging directory> \
|
|
--reference glossary=<absolute verified glossary snapshot> \
|
|
--reference party=<absolute verified party snapshot> \
|
|
--reference players=<absolute verified players snapshot> \
|
|
--reference spell_catalog=<absolute verified spell catalog snapshot> \
|
|
--json
|
|
```
|
|
|
|
The spell-catalog binding is omitted when the campaign does not maintain that
|
|
optional overlay. Registry, scene-description, combat-turn, and occurrence
|
|
handoffs generated during the same Notarius run remain in Notarius pipeline
|
|
composition and must not be emitted as CLI references. The linked CLI and D&D
|
|
consumer documents own selector targeting, declared slots, media compatibility,
|
|
and generated-handoff collision rules.
|
|
|
|
Standard output is reserved for the JSON receipt. Standard error is captured
|
|
separately as diagnostic output. Narratio applies the configured timeout and
|
|
does not interpret stdout as a receipt unless the subprocess exits successfully.
|
|
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.
|
|
|
|
## Accepted Result
|
|
|
|
Narratio's supported invocation baseline is Notarius v0.6.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
|
|
`index.json` beneath the reported bundle root. The production index must name
|
|
the management files exactly as `manifest.json`, `rejected.json`,
|
|
`warnings.json`, and `diagnostics.json`. All receipt, index, and lane paths must
|
|
stay inside that bundle; symlinks and non-regular lane payloads are rejected.
|
|
|
|
Supported receipt and index shapes tolerate unknown fields for forward
|
|
compatibility, while required identity, validation, count, manifest,
|
|
rejection, warning, diagnostic, and lane-list fields remain mandatory.
|
|
Narratio applies bounded reads to the receipt, index, rejection, warning, and
|
|
diagnostic documents. Warning and diagnostic envelopes, group counts,
|
|
occurrence counts, truncation state, framework-owned origins, and
|
|
receipt-to-bundle counts must be internally consistent. Optional chunk-map and
|
|
evidence-context descriptors must carry their complete generic contract
|
|
metadata when present.
|
|
|
|
For every entry in `pipeline.notarius.outputs`, Narratio requires exactly one
|
|
index descriptor with the configured lane ID, media type, schema ID, schema
|
|
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.
|
|
Unconfigured lanes may remain in the preserved bundle but do not become
|
|
selectable Narratio sources.
|
|
|
|
Each accepted configured lane is registered as
|
|
`narratio.extraction.<output_key>`. The bundle index is retained for audit and
|
|
resume validation but is not selectable. Scriptorium and publish rules consume
|
|
only explicitly named lane sources; `--artifacts` never selects Notarius lanes.
|
|
|
|
## Failure And Compatibility Behavior
|
|
|
|
- Startup and nonzero-exit errors fail extraction and retain captured diagnostics.
|
|
- Invalid receipt JSON or an unsupported receipt schema fails before bundle use.
|
|
- Unsafe or incompatible index data and required-lane rejection fail before the
|
|
staged bundle is promoted to durable storage.
|
|
- Contract and external provenance metadata are preserved on lane artifact
|
|
records and through explicit publication.
|
|
- Undeclared selectors, incompatible reference files, and external/generated
|
|
reference collisions are Notarius errors and fail extraction normally.
|
|
|
|
Rejection, validation, warning, and diagnostic summaries retain bounded stable
|
|
identity, category, origin, reason-code, status, and occurrence fields without
|
|
copying free-form external messages into Narratio manifest metadata or reading
|
|
lane payload bodies.
|
|
|
|
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.
|