notarius/docs/roadmap/dnd-subprocess-documentation.md

D&D Subprocess Consumer Documentation

Status

Completed. The target guide is docs/consumers/dnd-pipeline.md.

Purpose

Provide one task-oriented guide for applications that run Notarius as a subprocess to execute the maintained complete D&D pipeline and consume its published artifacts. The initial concrete consumer is Narratio, but the guide must describe the public Notarius workflow rather than depend on Narratio internals.

The guide should make the safe integration path obvious without duplicating the CLI, input, receipt, output-bundle, or individual artifact contracts that already have canonical documentation.

Current State

The public integration surface is documented accurately but is distributed across several documents:

• docs/consumers/subprocess.md defines the generic subprocess workflow;
• docs/cli.md owns commands, flags, stream behavior, and exit statuses;
• docs/integrations/seriatim.md owns the accepted transcript input shape;
• docs/integrations/run-result.md owns the machine-readable successful-run receipt;
• docs/integrations/json-output.md owns bundle discovery and logical files;
• the D&D integration documents own the individual lane payload contracts;
• examples/dnd-complete.config.yml is the maintained complete pipeline.

A consumer can reconstruct the full workflow from those documents, but there is no D&D-focused guide that connects the maintained example to its input, invocation, complete artifact inventory, discovery procedure, and downstream acceptance decisions.

Target Documentation Set

Create docs/consumers/dnd-pipeline.md

This document should own the end-to-end consumer workflow for the maintained complete D&D configuration. It should be useful to Narratio and to another subprocess orchestrator with the same needs.

The guide should contain the following sections.

Prerequisites And Deployment Configuration

• Link to examples/dnd-complete.config.yml rather than embedding a second complete configuration.
• Explain that a deployment must provide the configured PromptKit profile and campaign reference files.
• Recommend absolute paths for a service or orchestrator deployment.
• Call out the path-resolution distinction explicitly: YAML reference paths are relative to the Notarius configuration file, while promptkit.profile_file is relative to the Notarius process working directory.
• Recommend validating the selected configuration and dnd-session pipeline before processing sessions.

Transcript Input

• State that the complete pipeline consumes a Seriatim JSON document.
• Link to the canonical Seriatim contract for required fields and validation.
• Recommend the caller's final trimmed transcript when the caller maintains transcript tiers. For Narratio, identify the implemented source as narratio.transcript.final_trimmed, normally stored at transcripts/final.trimmed.json.
• Explain that segment IDs must remain stable because D&D source references cite those units.
• Explain that Notarius derives its default prompt session from the input module and exact input bytes and that ordinary callers should not supply --session-id.

Subprocess Invocation

• Show one concise invocation using notarius run dnd-session, explicit absolute --config, --input, and --output-dir paths, and --json.
• Direct callers to capture stdout and stderr separately, propagate cancellation, impose an operator-appropriate timeout, and wait for process completion before parsing stdout.
• State that only exit status zero permits receipt decoding and link to the CLI contract for the complete exit-status definition.
• Recommend retaining stderr and the invocation context for diagnosis without logging secrets or transcript content.

Receipt And Bundle Discovery

• Require callers to accept only supported run-result schema versions while tolerating unknown fields allowed by that version.
• Direct callers to obtain the exact run-specific bundle from the receipt's absolute output_directory; they must not scan for the newest run directory or construct a run ID.
• Require a confinement check when resolving index_file beneath the reported bundle root.
• Direct callers to discover lane payloads by lane_id in index.json, then verify descriptor media type and schema identity before decoding them.
• Explain that descriptor paths are untrusted relative paths and require the same confinement discipline.

Complete D&D Artifact Inventory

Include a compact table for the ten lane IDs selected by the maintained complete configuration:

• item-registry;
• npc-registry;
• location-registry;
• scene-descriptions;
• item-occurrences;
• spells;
• combat-turns;
• npc-occurrences;
• location-occurrences;
• enemy-events.

For each row, give a one-line purpose and link to the corresponding canonical D&D artifact contract. Do not copy its fields or schema rules into the consumer guide.

Document the four always-published bundle files—index.json, manifest.json, rejected.json, and warnings.json—and the complete example's configured chunk-map.json and evidence-context.json pipeline-wide artifacts. Link to their canonical contracts and distinguish pipeline-wide artifacts from lane outputs.

The inventory must say that a file is available only when its corresponding artifact was accepted and published. It must not imply that process success guarantees every configured lane.

Downstream Acceptance And Retention

• Explain that exit status zero can coexist with rejected outputs, warnings, or absent lane descriptors.
• Require the consumer to define its required lane set explicitly. Recommend treating all ten lanes as required when the caller claims to consume the complete D&D workflow, while allowing another consumer to adopt a narrower documented policy.
• Recommend retaining the receipt, the complete published bundle, and captured diagnostic streams long enough to support provenance and failure analysis.
• Explain that evidence-context.json is a reading excerpt; authoritative citations remain in lane payloads.
• Treat transcripts, lane artifacts, evidence context, manifests, and logs as sensitive campaign data.

Compatibility Checklist

End with a concise checklist covering process exit, receipt schema, path confinement, pipeline identity, index decoding, required descriptors, descriptor schema/media compatibility, warnings and rejections, checksums or retention, and secure handling. Compatibility should be based on published receipt and artifact contracts rather than parsing a human version string.

Update Existing Navigation

• Add a short link from docs/consumers/subprocess.md to the D&D-specific workflow. Keep generic subprocess policy in the existing document.
• Add the guide to the documentation links in README.md.
• Extend the subprocess-consumer row in docs/development.md so maintainers working on the D&D workflow are routed to the new guide and the canonical contracts.

Verify Canonical Contract Documents

Review the linked integration documents and the complete example while writing the guide. Correct an integration document only if repository inspection finds an actual stale contract. Do not move schema definitions, field tables, CLI flags, or configuration semantics into the new guide.

Narratio Alignment

The guide may name Narratio as the motivating consumer and identify its current final-trimmed transcript source. It must not claim that Narratio already has a Notarius adapter or extraction stage. Until that feature is implemented, Narratio-specific architecture, configuration, stage behavior, manifest records, and artifact source IDs belong in Narratio's roadmap.

Once Narratio implements the integration, its own integration documentation should link to this guide and the durable Notarius contracts instead of repeating them.

Validation

Documentation implementation should include:

go run ./cmd/notarius config validate \
  --config examples/dnd-complete.config.yml \
  --pipeline dnd-session
go test ./...

Also verify all new and changed relative Markdown links, compare the artifact inventory directly with the maintained complete configuration, and confirm that commands and path semantics match the CLI and configuration references. If the repository still has no automated link checker, record that fact and perform a focused manual link review.

Acceptance Criteria

• A subprocess integrator can follow one D&D-focused guide from a Seriatim transcript through safe discovery of every artifact configured by the complete example.
• The guide makes stdout, stderr, exit-status, receipt, and path-confinement responsibilities unambiguous.
• The ten configured D&D lanes and both configured pipeline-wide artifacts are listed and linked to their canonical contracts.
• The guide distinguishes process success from the caller's required-artifact policy.
• The profile-path and reference-path resolution rules are clearly stated.
• Existing navigation makes the guide discoverable.
• No volatile contract is defined in two places, and no unimplemented Narratio behavior is presented as current.

Non-Goals

• Implementing or documenting Narratio's future adapter or stage as current Notarius behavior.
• Adding a new Notarius command, receipt version, output format, or artifact schema.
• Duplicating the complete configuration or individual D&D payload schemas in prose.
• Defining a universal partial-result policy for every Notarius consumer.