140 lines
6.7 KiB
Markdown
140 lines
6.7 KiB
Markdown
# Published JSON Output
|
||
|
||
This document defines the logical JSON bundle emitted by the production JSON
|
||
output encoder. The bundle’s physical destination, atomic publication, and
|
||
retention are operational concerns; see [Operations](../operations.md#output-bundles).
|
||
Output configuration, including chunk-map and evidence-context publication, belongs in
|
||
[Configuration](../config.md#module-bindings-and-validators).
|
||
|
||
## Bundle Layout
|
||
|
||
All paths below are logical, relative, slash-separated bundle paths. The
|
||
encoder always emits the first four JSON files below and adds lane or
|
||
pipeline-wide artifact files when their corresponding artifacts are available:
|
||
|
||
A subprocess caller first obtains the physical bundle root from the
|
||
[run-result receipt](run-result.md), then resolves `index.json` beneath that
|
||
root for the logical discovery described here.
|
||
|
||
| Path | Purpose |
|
||
| --- | --- |
|
||
| `index.json` | Entry point that names the other published files and lane payloads. |
|
||
| `manifest.json` | Run provenance and result summaries. |
|
||
| `rejected.json` | Rejected pipeline outputs. |
|
||
| `warnings.json` | Accepted-output and run warnings. |
|
||
| `lanes/<safe-lane-id>.json` | One normalized artifact payload for each lane. |
|
||
| `chunk-map.json` | Optional accepted chunk map, when its export is enabled and available. |
|
||
| `evidence-context.json` | Optional source-context artifact, when evidence publication is enabled. |
|
||
|
||
JSON files are pretty-printed with a trailing newline. Lane payloads are
|
||
accepted only when their media type is `application/json`.
|
||
|
||
## `index.json`
|
||
|
||
`index.json` is the bundle’s discovery document. An approved run with no
|
||
normalized lanes has this valid minimal index:
|
||
|
||
```json
|
||
{
|
||
"manifest_file": "manifest.json",
|
||
"output_files": [],
|
||
"rejected_file": "rejected.json",
|
||
"warnings_file": "warnings.json"
|
||
}
|
||
```
|
||
|
||
| Field | Required | Meaning |
|
||
| --- | --- | --- |
|
||
| `manifest_file` | Yes | Always `manifest.json`. |
|
||
| `output_files` | Yes | Lane descriptors sorted by `lane_id`. |
|
||
| `rejected_file` | Yes | Always `rejected.json`. |
|
||
| `warnings_file` | Yes | Always `warnings.json`. |
|
||
| `chunk_map` | No | Descriptor for the pipeline-wide `chunk-map.json`; never a lane descriptor. |
|
||
| `evidence_context` | No | Descriptor for the pipeline-wide `evidence-context.json`; never a lane descriptor. |
|
||
|
||
Each lane descriptor has required `lane_id` and `file`. It may also include
|
||
`media_type`, `module_key`, `schema_id`, `schema_name`, and `schema_version`
|
||
when supplied by the normalized artifact. Each pipeline-wide artifact
|
||
descriptor (`chunk_map` or `evidence_context`) contains `artifact_kind`,
|
||
`file`, `media_type`, `schema_id`, `schema_name`, and `schema_version`. Their
|
||
payloads are defined by the [Accepted Chunk Map contract](chunk-map.md) and
|
||
[Published Evidence Context](evidence-context.md), respectively.
|
||
|
||
The lane path is derived from its lane ID. Characters outside letters, digits,
|
||
periods, underscores, and hyphens become underscores; `..` sequences are
|
||
neutralized; leading and trailing periods and underscores are removed. A lane
|
||
that produces an empty name, or two lanes that produce the same path, makes
|
||
output encoding fail.
|
||
|
||
## Lane Payloads
|
||
|
||
Each `lanes/<safe-lane-id>.json` file is the codec-owned normalized JSON for
|
||
that lane. Consumers should use the index descriptor’s schema identity rather
|
||
than infer a lane schema from its name. The current D&D payload contracts are
|
||
[spells](dnd-spell-artifacts.md), [NPCs](dnd-npc-artifacts.md),
|
||
[NPC interactions](dnd-npc-interaction-artifacts.md),
|
||
[combat turns](dnd-combat-turn-artifacts.md),
|
||
[item events](dnd-item-event-artifacts.md),
|
||
[scene descriptions](dnd-scene-description-artifacts.md), and
|
||
[enemy events](dnd-enemy-event-artifacts.md).
|
||
|
||
## `manifest.json`
|
||
|
||
`manifest.json` is published provenance, not a copy of lane payloads or a
|
||
checkpoint store. Fields without a value may be omitted. Its top-level fields
|
||
group into the following externally observable summaries:
|
||
|
||
| Group | Fields |
|
||
| --- | --- |
|
||
| Run identity and result | `run_id`, `pipeline_id`, `pipeline_digest`, `schema_version`, `validation_status`, `started_at`, `completed_at` |
|
||
| Resolved components | `input_module`, `chunker`, `extractors`, `merger`, `normalizer`, `output_encoder`, `artifact_lanes`, `validator_chains`, `module_metadata` |
|
||
| Source and references | `source_digests`, `references` |
|
||
| Published result summaries | `normalized_outputs`, `rejected_outputs` |
|
||
| Execution summaries | `chunk_plan`, `checkpoint_decisions`, `llm_profiles`, `metadata` |
|
||
|
||
`references` records provenance such as the target, slot, origin, digest,
|
||
media type, size, and generated-artifact identity. It does not contain
|
||
reference content. `normalized_outputs` and `rejected_outputs` likewise
|
||
summarize results without embedding lane payload bytes. A chunk-plan summary is
|
||
provenance for the plan used by this run; cache records, debug artifacts, and
|
||
other operational state are not published as bundle files.
|
||
|
||
When present, `metadata.session_id` is the effective non-secret routing
|
||
correlation identifier used for the run. It can be visible to providers and is
|
||
not a substitute for a cache or checkpoint identity. Its generation and
|
||
override behavior are defined by the [CLI reference](../cli.md#run).
|
||
|
||
Each `llm_profiles` entry identifies effective, non-secret LLM execution
|
||
provenance:
|
||
|
||
| Field | Required | Meaning |
|
||
| --- | --- | --- |
|
||
| `id` | Yes | Selected PromptKit profile identifier. |
|
||
| `provider` | No | Notarius adapter provider identifier. |
|
||
| `model` | No | Effective provider model identifier. |
|
||
| `backend_id` | No | Effective PromptKit backend registration identifier. Endpoint-only profiles omit it. |
|
||
| `reasoning_effort` | No | Effective opaque provider reasoning setting. An empty or explicitly cleared setting is omitted. |
|
||
|
||
These values describe observed execution; they are not a backend-registration
|
||
interface. Entries that differ by backend or effective reasoning remain
|
||
distinct even when their profile, provider, and model are otherwise equal.
|
||
|
||
## Rejections And Warnings
|
||
|
||
`rejected.json` is always an object with a `rejected` array. Each entry has
|
||
required `stage` and `message`; `step_id`, `lane_id`, `module_key`, `chunk_id`,
|
||
`chunk_index`, `validator_name`, `reason_code`, `attempt_count`, and
|
||
`diagnostic_artifact_path` are present only when applicable.
|
||
|
||
`warnings.json` is always an object with a `warnings` array. Each warning has
|
||
`reason_code` and `message`; `scope` is optional. Both arrays are empty when
|
||
there is nothing to report.
|
||
|
||
## Compatibility
|
||
|
||
The index is the authoritative map from a logical lane to its published
|
||
payload. Consumers must tolerate omitted optional manifest and descriptor
|
||
fields, and should rely on the linked artifact contract for each lane’s JSON
|
||
shape. This contract describes the published logical bundle only; it does not
|
||
promise a filesystem layout or expose internal state formats.
|