3.9 KiB
Published JSON Output
This contract defines logical files emitted by the production JSON output encoder. Operations owns physical placement, publication failures, permissions, and retention. Configuration owns output options; the CLI completion report identifies a successful run's directory.
Bundle Layout
Paths are relative, slash-separated paths beneath the run-specific directory:
| Path | Purpose |
|---|---|
lanes/<safe-lane-id>.json |
One normalized domain artifact per available selected lane, including supported qualified fallback. |
chunk-map.json |
Optional materialized chunk map, when enabled and available. |
evidence-context.json |
Optional selected source-unit excerpt, when enabled and available. |
There is no required index, manifest, persisted receipt, rejection file, warning file, or diagnostic sidecar. Expected lanes come from pipeline configuration; optional auxiliaries use the paths above. Consumers need no metadata bundle or debug data to decode artifacts.
The lane filename mapping is unchanged: trim the ID, replace characters outside
ASCII letters, digits, periods, underscores, and hyphens with underscores,
neutralize .. sequences, and trim leading/trailing periods and underscores.
An empty resulting name or colliding paths fails encoding. Maintained D&D lane
IDs already map directly to their filenames.
Files are pretty-printed JSON with a trailing newline. Lane payloads require
application/json; the encoder validates the artifact boundary without
wrapping payloads in reporting metadata. Report presentation format does not
change artifact encoding.
Lane Payloads
Each lane file is its codec-owned normalized JSON value. Select the contract from the configured lane/module, not an absent discovery descriptor. Existing D&D payload contracts remain unchanged:
- Spells.
- NPC registry and NPC occurrences.
- Combat turns.
- Item registry and item occurrences.
- Scene descriptions.
- Enemy events.
- Location registry and location occurrences.
Intrinsic fields, identities, source references, and schemas are preserved. Supported fallback meets intrinsic/downstream invariants without asserting ordinary semantic approval. Run qualification belongs in the native completion report, not new payload fields or sidecars.
Auxiliary Artifacts
Chunk map and evidence context are pipeline-wide artifacts, not lanes. Their existing payload schemas and logical paths remain; no index descriptor is required.
Enabled, available auxiliaries count as deliverables, including when built from reused results or supported fallback. Disabled/unavailable auxiliaries are not published. Evidence can cover the complete source; authoritative citations remain in normalized lane payloads.
Consumer Use And Compatibility
Check process status before decoding a successful native report. Use its absolute run directory, then the configured lane and selected auxiliary paths. Decode each file against its domain contract. The subprocess guide and complete D&D workflow explain caller tasks.
Removing reporting/discovery files is intentional, not a domain schema or filename-mapping change. Migration guidance replaces receipt/index traversal. Debug and cache are not public output contracts. Post-publication failure can leave valid files; failed publication can leave a partial directory. Neither supplies a successful completion report.