narratio/docs/roadmap/notarius-v0.6-cli-references.md

Notarius v0.6 CLI Reference Integration

Status

Accepted target state. Delivery sequencing and implementation status are owned by implementation.md.

Purpose

Upgrade Narratio's extraction boundary to the Notarius v0.6.0 subprocess contract and supply session reference documents explicitly with repeatable --reference selector=path arguments.

The maintained D&D integration must make the prepared party roster, player context, glossary, and optional spell catalog available to every compatible Notarius target. Notarius must continue to own pipeline topology, reference-slot compatibility, generated artifact handoffs, prompts, and D&D schemas. Narratio owns selection and preparation of its external reference files, exact CLI invocation, provenance, and extraction reuse correctness.

Current State And Gap

Narratio currently invokes Notarius as:

notarius run <pipeline_id> --config <config_path> --input <transcript> --output-dir <staging_dir> --json

The prepare stage already materializes campaign/session party, players, and glossary files under the session inputs/ directory, but extract does not pass them to Notarius. Narratio also has no stable spell-catalog input. As a result, a Notarius deployment must duplicate these paths in its own configuration, cannot reliably receive session overrides, and may extract without the same campaign context supplied to Narratio's analysis stage.

Notarius v0.6.0 makes an unqualified CLI selector pipeline-scoped. For example, --reference party=/absolute/path/party.yml supplies the file to every selected target that declares party. Scoped selectors remain available for exceptional overrides. CLI paths are resolved from the Notarius process working directory, so subprocess callers are expected to provide absolute paths.

The v0.6.0 receipt, index, warning, diagnostic, and ten-lane D&D artifact contracts remain compatible with Narratio's current v0.5 integration. This feature changes the invocation and input-provenance contract rather than the accepted output inventory.

User Outcome

With the maintained complete D&D configuration, an operator can declare the campaign reference sources once in Narratio. For each extraction Narratio will:

1. materialize the effective campaign/session files during prepare;
2. resolve those prepared files by stable Narratio source ID;
3. pass absolute paths for party, players, glossary, and, when configured, spell_catalog to Notarius through repeatable CLI arguments;
4. fail before launching Notarius when a configured reference is unavailable;
5. rerun extraction when a selector, source binding, or reference file changes; and
6. retain bounded reference identities and checksums for diagnosis and provenance without copying reference contents into manifest metadata.

Session-level stable-input overrides must flow through the same mechanism. A custom Notarius pipeline may bind different external slots without requiring a Narratio code change.

Chosen Architecture

Explicit Reference Bindings

Extend pipeline.notarius with an explicit map from a Notarius CLI selector to a prepared Narratio input source:

notarius:
  enabled: true
  binary: notarius
  config_path: /usr/local/etc/notarius/config.yml
  pipeline_id: dnd-session
  working_directory: /usr/local/etc/notarius
  references:
    party: narratio.input.party
    players: narratio.input.players
    glossary: narratio.input.glossary
    spell_catalog: narratio.input.spell_catalog
  outputs:
    # Existing required lane contracts remain unchanged.

Each configured binding is required. An operator who does not maintain an optional Notarius reference, such as a spell catalog, omits that binding. This keeps missing-input behavior explicit and avoids a second required/optional policy inside each entry.

The maintained complete D&D example will show all four external reference slots. The three existing campaign context bindings use the canonical party, players, and glossary spellings. Narratio will not emit the deprecated roster alias.

The binding is deliberately source-based rather than path-based. Pipeline configuration should not reconstruct session workspace paths or bypass prepare; it names the stable input whose effective campaign/session value is already owned by Narratio. The map also avoids hard-coded behavior keyed to the literal dnd-session pipeline ID, preserving custom-pipeline support.

Narratio accepts the selector forms published by Notarius v0.6.0:

• slot;
• chunk.slot;
• lane.slot; and
• lane.extract.slot, lane.merge.slot, or lane.normalize.slot.

Configuration validation will reject empty or structurally invalid selectors, selectors containing =, unsupported source IDs, and duplicate YAML keys. Notarius remains authoritative for whether a selected target actually declares the slot and whether a file satisfies that slot's media type and size contract. Narratio will not duplicate the Notarius module registry.

Stable Reference Inputs

Continue to use the existing prepared sources and canonical files:

Narratio source	Prepared file	Notarius slot
narratio.input.party	inputs/party.yml	party
narratio.input.players	inputs/players.yml	players
narratio.input.glossary	inputs/glossary.yml	glossary
narratio.input.spell_catalog	inputs/spell_catalog.json	spell_catalog

Add optional spell_catalog_file fields to campaign and session inputs, with the existing campaign-default/session-override resolution behavior. When provided, prepare copies it into the session input area and records its origin and checksum consistently with the other stable inputs. The prepared filename remains JSON so Notarius can apply its published spell-catalog media contract.

The new source must be added everywhere stable inputs are enumerated: strict configuration decoding and merging, validation, prepare materialization, artifact policy/source descriptions, operator inspection, manifest input records, examples, and canonical documentation. It remains optional at the campaign level; a configured Notarius binding makes it mandatory for that extraction.

Extract and analyze should use one shared prepared-input source resolver rather than maintain separate source-to-filename tables. The resolver must return an absolute, regular, non-empty file beneath the current session workspace and produce actionable prepare --force guidance when a configured source is missing. It must not fall back to the original campaign path after preparation.

Adapter Request And CLI Construction

Extend the transport-neutral Notarius run request with an ordered collection of resolved reference bindings. Each binding contains only its selector and absolute prepared-file path. The extraction stage resolves source IDs and file identity; the subprocess adapter validates and serializes the request.

The production command becomes:

notarius run <pipeline_id>
  --config <config_path>
  --input <trimmed_json>
  --output-dir <staging_dir>
  --reference party=<absolute_prepared_party_path>
  --reference players=<absolute_prepared_players_path>
  --reference glossary=<absolute_prepared_glossary_path>
  --reference spell_catalog=<absolute_prepared_spell_catalog_path>
  --json

Only configured bindings are emitted. Selectors are sorted before request construction so argument order, tests, logs, and fingerprints are deterministic. Arguments are passed directly to the subprocess without shell interpretation; paths containing spaces or platform-specific separators remain one argument.

CLI bindings intentionally override matching external paths in the deployed Notarius configuration. Narratio must not pass --without-reference and must not synthesize CLI bindings for location_registry, item_registry, npc_registry, scene_descriptions, combat_turns, or npc_occurrences. Those are generated same-run artifact handoffs in the complete D&D pipeline and remain entirely under Notarius configuration and execution control. A custom configuration that collides an external CLI binding with a generated handoff is expected to fail with Notarius's normal resolution error.

Fingerprints, Resume, And Provenance

Reference identity is part of the extraction input contract. The extraction fingerprint and resume validator must include, in deterministic selector order:

• the selector;
• the configured Narratio source ID;
• the resolved prepared path identity; and
• the prepared file's content checksum and size.

This is required even though Notarius generates a prompt session ID from the input module and transcript bytes: Notarius intentionally does not include references in that identifier. Narratio must therefore prevent an old extraction from being reused after a roster, player list, glossary, spell catalog, selector, or source mapping changes.

A changed reference makes the prior extract result non-reusable and follows Narratio's normal downstream invalidation rules. A failed reference-resolution or checksum check also prevents reuse; it must not silently accept the prior bundle.

Successful extract metadata should record a bounded, deterministic list of selector, source ID, workspace-relative path, checksum, and size. It must not record reference contents, original absolute operator paths, or values from the files. Existing receipt and bundle provenance behavior remains unchanged.

Error And Compatibility Behavior

Narratio's documented minimum supported Notarius version becomes v0.6.0 for an enabled reference binding. Compatibility remains contract-based rather than dependent on parsing notarius --version: an older or incompatible executable will fail at the CLI boundary with captured diagnostics.

Errors must identify the responsible selector and Narratio source without including file contents. Configuration errors are reported before pipeline execution. Missing, empty, non-regular, unsafe, or unreadable prepared files fail extraction before the Notarius subprocess starts. Notarius continues to report undeclared slots, media incompatibility, size limits, required-slot failures, and generated-handoff collisions.

When Notarius is disabled, extraction retains its current explicit skip behavior and does not resolve reference inputs. Receipt v2 ingestion, bundle confinement, ten-lane selection, and downstream artifact source IDs are not otherwise changed by this feature.

Target End State

Narratio and Notarius have a clear orchestration boundary:

• prepare owns the effective, immutable session copies of external campaign context;
• extract maps configured stable source IDs to Notarius v0.6 CLI selectors, supplies absolute file paths, and owns reuse/provenance policy;
• the Notarius adapter owns exact subprocess serialization and supported result decoding;
• Notarius owns slot compatibility, reference precedence within its pipeline, generated artifact handoffs, and output schemas; and
• analyze consumes the resulting ten structured lane artifacts exactly as it does today.

The maintained complete D&D workflow passes party, players, glossary, and spell catalog context from the same prepared session inputs used elsewhere in Narratio. Updating any of those documents deterministically causes fresh extraction, and operators can diagnose the effective bindings without exposing file contents.

Out Of Scope

• Reproducing Notarius pipeline, lane, binding, or media-type validation in Narratio.
• Passing or overriding Notarius generated artifact handoffs.
• Adding --without-reference, Notarius resume/recompute controls, lane selection, model selection, profile selection, or session-ID overrides.
• Changing the ten accepted D&D lane contracts or the Scriptorium analysis design.
• Reading reference payloads into Narratio manifests or logs.
• Automatically running notarius config validate for every session.

Settled Policy Choices

The implementation must preserve these choices unless implementation evidence shows a contract conflict:

• explicit selector-to-source mappings are preferred over pipeline-ID-specific defaults;
• every configured mapping is required;
• spell_catalog_file is optional until a mapping requests its prepared source;
• the complete D&D example demonstrates all four external references; and
• Notarius v0.6.0 is the minimum supported CLI contract for reference-enabled extraction.