91 lines
4.6 KiB
Markdown
91 lines
4.6 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 references:
|
|
|
|
- [Subprocess consumer contract](https://gitea.maximumdirect.net/eric/notarius/src/branch/main/docs/consumers/subprocess.md)
|
|
- [D&D pipeline and lane contracts](https://gitea.maximumdirect.net/eric/notarius/src/branch/main/docs/consumers/dnd-pipeline.md)
|
|
- [Run-result receipt](https://gitea.maximumdirect.net/eric/notarius/src/branch/main/docs/integrations/run-result.md)
|
|
- [JSON output bundle](https://gitea.maximumdirect.net/eric/notarius/src/branch/main/docs/integrations/json-output.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 and invokes:
|
|
|
|
```text
|
|
notarius run <pipeline_id> --config <config_path> --input <trimmed_json> --output-dir <staging_dir> --json
|
|
```
|
|
|
|
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 accepts the Notarius v0.5.0 receipt schema
|
|
`notarius.run-result.v2`. 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.
|
|
|
|
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.
|