2026-07-26 13:38:55 +00:00
|
|
|
# Published JSON Output
|
2026-07-04 03:11:29 +00:00
|
|
|
|
2026-11-22 06:32:22 +00:00
|
|
|
This contract defines logical files emitted by the production JSON output
|
|
|
|
|
encoder. [Operations](../operations.md#output-bundles) owns physical placement,
|
|
|
|
|
publication failures, permissions, and retention. [Configuration](../config.md#module-bindings-and-validators)
|
|
|
|
|
owns output options; the [CLI completion report](../cli.md#completion-report)
|
|
|
|
|
identifies a successful run's directory.
|
2026-07-04 03:11:29 +00:00
|
|
|
|
2026-07-26 13:38:55 +00:00
|
|
|
## Bundle Layout
|
2026-07-04 03:11:29 +00:00
|
|
|
|
2026-11-22 06:32:22 +00:00
|
|
|
Paths are relative, slash-separated paths beneath the run-specific directory:
|
2026-07-26 17:22:27 +00:00
|
|
|
|
2026-07-26 13:38:55 +00:00
|
|
|
| Path | Purpose |
|
|
|
|
|
| --- | --- |
|
2026-11-22 06:32:22 +00:00
|
|
|
| `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.
|
2026-07-26 13:38:55 +00:00
|
|
|
|
|
|
|
|
## Lane Payloads
|
|
|
|
|
|
2026-11-22 06:32:22 +00:00
|
|
|
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](dnd-spell-artifacts.md).
|
|
|
|
|
- [NPC registry](dnd-npc-registry-artifacts.md) and
|
|
|
|
|
[NPC occurrences](dnd-npc-occurrence-artifacts.md).
|
|
|
|
|
- [Combat turns](dnd-combat-turn-artifacts.md).
|
|
|
|
|
- [Item registry](dnd-item-registry-artifacts.md) and
|
|
|
|
|
[item occurrences](dnd-item-occurrence-artifacts.md).
|
|
|
|
|
- [Scene descriptions](dnd-scene-description-artifacts.md).
|
|
|
|
|
- [Enemy events](dnd-enemy-event-artifacts.md).
|
|
|
|
|
- [Location registry](dnd-location-registry-artifacts.md) and
|
|
|
|
|
[location occurrences](dnd-location-occurrence-artifacts.md).
|
|
|
|
|
|
|
|
|
|
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](chunk-map.md) and [evidence context](evidence-context.md) 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](../consumers/subprocess.md)
|
|
|
|
|
and [complete D&D workflow](../consumers/dnd-pipeline.md) explain caller tasks.
|
|
|
|
|
|
|
|
|
|
Removing reporting/discovery files is intentional, not a domain schema or
|
|
|
|
|
filename-mapping change. [Migration guidance](../consumers/native-migration.md)
|
|
|
|
|
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.
|