narratio/docs/integrations/notarius.md

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
• Subprocess consumer contract
• D&D pipeline and lane contracts
• Run-result receipt
• JSON output bundle
• D&D spell-catalog overlay

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. Narratio requires the Notarius v0.6.0 CLI contract when references are configured and invokes each binding as a separate argument before --json:

notarius run <pipeline_id> --config <config_path> --input <trimmed_json> --output-dir <staging_dir> [--reference <selector>=<prepared_path>]... --json

Reference paths are absolute canonical files prepared inside the current Narratio session workspace. Narratio 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:

notarius run dnd-session \
  --config <absolute config path> \
  --input <absolute trimmed transcript path> \
  --output-dir <absolute staging directory> \
  --reference glossary=<absolute prepared glossary path> \
  --reference party=<absolute prepared party path> \
  --reference players=<absolute prepared players path> \
  --reference spell_catalog=<absolute prepared spell catalog path> \
  --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. Operator paths, rerun procedures, and bundle retention are in Operations. See Troubleshooting for failure recovery.