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.7.0 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. Configured references require support for the --reference contract introduced in Notarius v0.6.0. Cache controls require support for the selected --resume and --chunk_cache flags. Notarius v0.7.0 is the tested cache integration baseline, not an unconditional minimum version; Narratio does not impose a runtime version gate. Each reference binding is a separate argument before --json. When pipeline.notarius.config_profile is present, its exact value is another argument pair before --json:

notarius run <pipeline_id> --config <config_path> --input <trimmed_json> --output-dir <staging_dir> [--resume] [--chunk_cache <mode>] [--reference <selector>=<verified_snapshot_path>]... [--config-profile <name>] --json

Notarius v0.7.0 is a known supporting version for --config-profile; using the option requires a compatible Notarius executable, but deployments that omit the field acquire no additional version requirement. Omitted or null configuration adds no flag. Supplied empty, default, and named selectors are forwarded without normalization so Notarius can apply its own ConfigKit semantics. This option selects a Notarius configuration overlay, not a PromptKit profile through --llm-profile, and Narratio never substitutes its own selected profile name. A missing or invalid downstream overlay is an ordinary Notarius subprocess failure: Narratio does not retry without the selector or fall back to another profile.

Reference paths are absolute stable snapshots streamed from manifest-verified canonical files prepared inside the current Narratio session workspace. They live at cache/notarius/references/<sha256>/<prepared-basename> and retain the full lowercase content digest. Narratio verifies snapshot checksum and size before and after the subprocess, reconstructs missing or corrupt regular files from a still-valid prepared source, and passes only configured bindings, ordered lexically by normalized selector, as direct argument-vector entries without shell interpretation. Symlinks, directories, other non-regular conflicts, and prepared-source mismatches fail rather than being deleted. A CLI binding takes precedence over a matching external path in Notarius configuration. Narratio never emits --without-reference.

For canonical party configuration, the party binding is the unchanged, validated authored roster and the players binding is its generated projection. Both retain their established narratio.input.party and narratio.input.players source IDs, and both are resolved from the prepared manifest rather than from campaign configuration at extraction time.

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 verified glossary snapshot> \
  --reference party=<absolute verified party snapshot> \
  --reference players=<absolute verified players snapshot> \
  --reference spell_catalog=<absolute verified spell catalog snapshot> \
  --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.

Ordinary extraction maps pipeline.notarius.resume: true to --resume and a nonempty pipeline.notarius.chunk_cache to --chunk_cache <mode>. Forced extraction always omits --resume and supplies --chunk_cache refresh. Notarius owns checkpoint enablement, recording, identity, and both cache roots; Narratio neither reads nor synthesizes its configuration. Use explicit persistent roots in Notarius when reuse must span subprocess invocations. Changing a reference path/digest or other upstream identity input correctly causes a cold miss. Chunk refresh bypasses lookup and publishes the accepted replacement for the active source; it does not delete unrelated plans or checkpoint state.

When pipeline.notarius.llm_api_key is absent or null, Narratio adds no credential to that environment. When configured, the field names an environment variable whose already-loaded nonempty value is forwarded under that exact name. Operators must use the same name as the api_key_env in the selected Notarius/PromptKit profile. Narratio does not inspect the Notarius configuration to infer a provider or destination name, and it does not forward unrelated credentials from its parent environment or secrets directory.

The selected name is registered with Narratio's shared streaming redactor. Credential bytes written by the child to captured stdout, captured stderr, or stderr-derived failure diagnostics are replaced with <redacted>, including custom names not known to the built-in sensitive-name list. Narratio does not serialize the credential into arguments, stage metadata, manifests, or generated configuration.

This captured-stream protection is not a filesystem sandbox. Notarius remains responsible for keeping credentials out of files it writes directly, including bundle artifacts and its own diagnostics. Narratio does not scan or rewrite arbitrary downstream files and cannot promise redaction of transformed or encoded credentials.

Accepted Result

Narratio's tested invocation baseline is Notarius v0.7.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. An accepted reused producer may report producer_attempt_count: 0; Narratio preserves that valid summary rather than treating it as a missing field. 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.

Opt-in Integration Test

The production-boundary cache test requires an absolute path to a locally built Notarius v0.7.0-compatible executable. It uses only a local OpenAI-compatible httptest provider and temporary cache/config/output roots:

NARRATIO_TEST_NOTARIUS_BINARY=/absolute/path/to/notarius \
  GOWORK=off go test ./internal/stage \
  -run '^TestNotariusCacheReuseIntegration$' -count=1 -v

When the variable is unset, the normal test suite skips this test and never searches PATH, a sibling checkout, the network, or a real provider.

11 KiB Raw Blame History