4.6 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 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. Operator paths, rerun procedures, and bundle retention are in Operations. See Troubleshooting for failure recovery.