225 lines
9.4 KiB
Markdown
225 lines
9.4 KiB
Markdown
# 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:
|
|
|
|
```sh
|
|
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.
|