4.0 KiB
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:
The complete Narratio example 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:
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 inherited environment
apply to the subprocess.
Accepted Result
Narratio currently accepts receipt schema notarius.run-result.v1. The receipt
must identify the configured pipeline and a bundle root containing a confined
index.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. Operator paths, rerun procedures, and bundle retention are in Operations. See Troubleshooting for failure recovery.