notarius/docs/consumers/dnd-pipeline.md

Consuming The Complete D&D Pipeline

Use this workflow when an orchestrator runs the maintained complete D&D pipeline and consumes its structured JSON artifacts. The generic subprocess consumer guide owns process-level responsibilities; this guide connects that workflow to the complete D&D configuration, its Seriatim input, and its artifact inventory.

The CLI reference, configuration reference, run-result receipt, and published JSON output contract remain the canonical definitions of those public interfaces.

Prepare And Validate The Deployment

Start from the maintained complete D&D configuration. It uses the dnd-session pipeline and demonstrates every implemented D&D lane, ordered artifact handoffs, campaign references, chunk-map publication, and evidence context.

A deployment must provide its own PromptKit profile and campaign reference files. Use absolute paths for service and subprocess deployments. In particular, observe these different resolution rules:

• reference paths in YAML are resolved relative to the Notarius configuration file; and
• promptkit.profile_file is resolved relative to the Notarius process working directory.

Do not copy the repository example's relative profile path into a deployment without also controlling that working directory. The complete path and profile rules are defined in Configuration.

Preflight the deployed configuration before processing sessions and whenever it changes:

notarius config validate \
  --config /absolute/path/to/notarius.yml \
  --pipeline dnd-session

Provide credentials through the environment or the documented configuration mechanism. Do not put credentials in command arguments, generated configuration, or logs.

Supply The Transcript

The complete pipeline consumes a Seriatim JSON document. The Seriatim input contract defines its required metadata, segments, and validation rules. Preserve segment IDs: D&D artifact citations use those segment IDs as source-unit ranges.

When the caller maintains several transcript tiers, use the final trimmed JSON transcript so extraction operates on the same session content presented to later consumers. For example, Narratio identifies this implemented artifact as narratio.transcript.final_trimmed and normally stores it at transcripts/final.trimmed.json.

Notarius generates a stable prompt session from the resolved input module and the exact input bytes. An ordinary orchestrator should not pass --session-id. Use that override only when intentionally changing the routing relationship between invocations; it is not a credential or output identity.

Run Notarius

Invoke the pipeline with explicit absolute paths and request its machine-readable receipt:

notarius run dnd-session \
  --config /absolute/path/to/notarius.yml \
  --input /absolute/path/to/transcripts/final.trimmed.json \
  --output-dir /absolute/path/to/notarius-output \
  --json

The caller should:

• capture stdout and stderr separately;
• propagate cancellation and impose an operator-appropriate timeout;
• wait for process completion before interpreting stdout; and
• retain stderr for diagnosis without copying secrets or transcript content into other logs.

Only exit status 0 permits decoding stdout as a receipt. Ignore stdout after a nonzero exit because a failed receipt write can leave partial bytes. The CLI reference defines the complete stream and exit-status contract.

Discover The Published Bundle

Decode the successful stdout document as a supported run-result schema. For the current contract, schema_version is notarius.run-result.v1. Tolerate unknown fields allowed by that version, but reject an unsupported schema version.

Use the receipt's absolute output_directory as the exact run-specific bundle root. Do not scan the output root for its newest directory, guess a run ID, or construct a bundle path. Resolve index_file beneath output_directory and reject an absolute logical path or any result that escapes the bundle root.

Read index.json and locate each requested lane in output_files by its exact lane_id. Do not guess a lane filename. Before decoding a payload:

1. resolve its descriptor's relative file beneath the bundle root with the same confinement check;
2. verify the descriptor's media type and schema identity against the linked artifact contract; and
3. decode the payload according to that contract.

The published JSON output contract defines the index and bundle layout. Treat all paths obtained from a decoded external document as untrusted until confined to their documented root.

Complete Artifact Inventory

When every configured lane is accepted, the complete example publishes these lane artifacts:

Lane ID	Purpose	Canonical contract
item-registry	Canonical registry of encountered items and currency.	Item registry
npc-registry	Canonical registry of named NPCs.	NPC registry
location-registry	Canonical registry of named locations.	Location registry
scene-descriptions	Classification, title, and summary for each scene.	Scene descriptions
item-occurrences	Source-grounded item discovery, acquisition, use, transfer, and loss events.	Item occurrences
spells	Source-grounded spell casts and casters.	Spell casts
combat-turns	Source-grounded combat turn participation.	Combat turns
npc-occurrences	Source-grounded NPC interaction occurrences.	NPC occurrences
location-occurrences	Source-grounded location occurrences.	Location occurrences
enemy-events	Source-grounded enemy combat events.	Enemy events

The JSON encoder always publishes these bundle-management files:

File	Purpose
index.json	Discovery document for lane and pipeline-wide artifacts.
manifest.json	Run provenance and result summaries.
rejected.json	Rejected pipeline outputs.
warnings.json	Accepted-output and run warnings.

The complete configuration also requests two pipeline-wide artifacts:

• chunk-map.json, the accepted chunk plan and chunk metadata; and
• evidence-context.json, a reading excerpt containing the union of selected cited source units and the configured surrounding window.

Discover both from their top-level index.json descriptors rather than treating them as lanes. Evidence context is convenient reading material, not authoritative provenance; citations in the normalized lane payloads remain the evidence contract.

Every optional or lane file is published only when its corresponding artifact is available. A successful process does not guarantee that all configured lanes were accepted.

Decide What Counts As Consumer Success

Exit status 0 means Notarius completed the pipeline and published its result bundle. The receipt or bundle may still report warnings, rejected outputs, or missing lane descriptors. A downstream consumer must define its own required artifact set explicitly.

A caller that claims to consume the complete D&D workflow should normally require all ten lane IDs in the table and verify each descriptor's expected contract. If any required lane is missing, rejected, or incompatible, fail the caller's extraction step while retaining the Notarius bundle for diagnosis. A consumer that needs only a subset may define and document a narrower policy.

Keep the successful receipt with the complete published bundle. Retain manifest.json, rejected.json, warnings.json, and captured process logs as required by the caller's provenance, diagnosis, and retention policies. Avoid selectively copying payload files without also preserving enough index and manifest information to identify their originating run and contracts.

The transcript, lane artifacts, evidence context, manifest, debug data, and logs can all contain private campaign information. Apply the same access, publication, and retention controls used for the source transcript.

Consumer Checklist

• Validate the deployed Notarius configuration and dnd-session pipeline.
• Pass the final trimmed Seriatim JSON transcript with stable segment IDs.
• Use absolute configuration, input, output-root, profile, and reference paths in service deployments.
• Capture stdout and stderr separately and enforce cancellation and timeout.
• Parse stdout only after exit status 0.
• Accept only supported receipt, index, and artifact schema versions while tolerating permitted unknown fields.
• Use the receipt's output_directory; never guess the run directory.
• Confine index_file and every descriptor path to the published bundle root.
• Discover lanes by lane_id and verify descriptor compatibility before decoding payloads.
• Enforce an explicit required-lane policy and inspect rejections and warnings.
• Preserve the receipt and sufficient bundle provenance for every retained artifact.
• Protect all transcript-derived files and diagnostic streams as sensitive campaign data.