notarius/docs/integrations/json-output.md

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. Output configuration, including chunk-map export, belongs in Configuration.

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 chunk-map files when their corresponding artifacts are available:

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.

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:

{
  "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.

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. A chunk_map descriptor contains artifact_kind, file, media_type, schema_id, schema_name, and schema_version; its payload is defined by the Accepted Chunk Map contract.

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, NPCs, NPC interactions, combat turns, item events, and scene descriptions.

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.

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.