Files
notarius/docs/integrations/json-output.md

80 lines
3.9 KiB
Markdown
Raw Normal View History

# Published JSON Output
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.
## Bundle Layout
Paths are relative, slash-separated paths beneath the run-specific directory:
2026-07-26 17:22:27 +00:00
| 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](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.