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 five 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	Actionable process-degradation warnings.
diagnostics.json	Accepted-artifact quality advisories and normalization observations.
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 selected source-unit excerpt, 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",
  "diagnostics_file": "diagnostics.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.
diagnostics_file	Yes	Always diagnostics.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, NPC registry, NPC occurrences, combat turns, item registry, item occurrences, scene descriptions, enemy events, location registry, and location occurrences.

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, validation_summaries
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.

Each validation_summaries entry is a bounded outcome for one producer result. It has required status, producer_attempt_count, and terminal_action; the stage and affected step, lane, module, or chunk identity are present when applicable. status is complete, rejected, or incomplete. rejecting_validators, reason_codes, and incomplete_validators preserve configured validator order and omit later duplicates. Entries contain no raw candidate response, correction guidance, validator diagnostic message, or artifact payload. The same shape may appear as validation on an affected rejection entry.

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, Warnings, And Diagnostics

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. An entry may also contain the bounded validation summary described above; the existing singular validator and reason fields remain the first configured rejection for compatibility.

warnings.json is always the notarius.warnings.v2 envelope:

{
  "schema_version": "notarius.warnings.v2",
  "group_count": 0,
  "occurrence_count": 0,
  "groups": []
}

It contains only process warnings. group_count is exact, and occurrence_count is the exact sum of its group occurrence counts.

diagnostics.json is always the notarius.diagnostics.v1 envelope:

{
  "schema_version": "notarius.diagnostics.v1",
  "group_count": 0,
  "occurrence_count": 0,
  "truncated": false,
  "unrepresented_occurrence_count": 0,
  "groups": []
}

It contains only advisory and observation groups. group_count counts groups represented in groups; occurrence_count includes both represented and unrepresented occurrences. When truncated is true, unrepresented_occurrence_count is the exact number omitted from group representation.

Each group has disposition, category, reason_code, framework-owned origin, exact occurrence_count, bounded samples, and omitted_sample_count. Samples carry safe scope and message, plus a chunk ID and zero-based chunk index when applicable. A group retains at most three distinct samples. The framework fails rather than truncating actionable warnings beyond 128 groups; it represents at most 256 advisory/observation groups and records further occurrences through the diagnostic truncation fields above.

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.