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 and evidence-context publication, 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 pipeline-wide artifact files when their corresponding artifacts are available:

A subprocess caller first obtains the physical bundle root from the run-result receipt, 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:

{
  "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 and Published Evidence Context, 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, NPCs, NPC interactions, combat turns, item events, and scene descriptions, and enemy events.

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.

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.