203 lines
9.6 KiB
Markdown
203 lines
9.6 KiB
Markdown
# 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](subprocess.md) 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](../cli.md), [configuration reference](../config.md),
|
|
[run-result receipt](../integrations/run-result.md), and
|
|
[published JSON output contract](../integrations/json-output.md) remain the
|
|
canonical definitions of those public interfaces.
|
|
|
|
## Prepare And Validate The Deployment
|
|
|
|
Start from the maintained
|
|
[complete D&D configuration](../../examples/dnd-complete.config.yml). 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](../config.md).
|
|
|
|
Preflight the deployed configuration before processing sessions and whenever
|
|
it changes:
|
|
|
|
```sh
|
|
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](../integrations/seriatim.md) 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:
|
|
|
|
```sh
|
|
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](../cli.md#output-streams-and-exit-statuses) 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](../integrations/json-output.md) 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](../integrations/dnd-item-registry-artifacts.md) |
|
|
| `npc-registry` | Canonical registry of named NPCs. | [NPC registry](../integrations/dnd-npc-registry-artifacts.md) |
|
|
| `location-registry` | Canonical registry of named locations. | [Location registry](../integrations/dnd-location-registry-artifacts.md) |
|
|
| `scene-descriptions` | Classification, title, and summary for each scene. | [Scene descriptions](../integrations/dnd-scene-description-artifacts.md) |
|
|
| `item-occurrences` | Source-grounded item discovery, acquisition, use, transfer, and loss events. | [Item occurrences](../integrations/dnd-item-occurrence-artifacts.md) |
|
|
| `spells` | Source-grounded spell casts and casters. | [Spell casts](../integrations/dnd-spell-artifacts.md) |
|
|
| `combat-turns` | Source-grounded combat turn participation. | [Combat turns](../integrations/dnd-combat-turn-artifacts.md) |
|
|
| `npc-occurrences` | Source-grounded NPC interaction occurrences. | [NPC occurrences](../integrations/dnd-npc-occurrence-artifacts.md) |
|
|
| `location-occurrences` | Source-grounded location occurrences. | [Location occurrences](../integrations/dnd-location-occurrence-artifacts.md) |
|
|
| `enemy-events` | Source-grounded enemy combat events. | [Enemy events](../integrations/dnd-enemy-event-artifacts.md) |
|
|
|
|
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`](../integrations/chunk-map.md), the accepted chunk plan and
|
|
chunk metadata; and
|
|
- [`evidence-context.json`](../integrations/evidence-context.md), 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.
|