84 lines
4.2 KiB
Markdown
84 lines
4.2 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 currently accepts receipt schema `notarius.run-result.v1`. 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`, and
|
|
`warnings.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, and lane-list fields remain mandatory. Narratio applies
|
|
bounded reads to the receipt, index, rejection, and warning documents. 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.
|
|
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 and warning summaries retain structured stage, scope, lane, and
|
|
reason-code fields for diagnostics without exposing free-form external messages
|
|
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.
|