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

3.9 KiB

Published JSON Output

This contract defines logical files emitted by the production JSON output encoder. Operations owns physical placement, publication failures, permissions, and retention. Configuration owns output options; the CLI completion report identifies a successful run's directory.

Bundle Layout

Paths are relative, slash-separated paths beneath the run-specific directory:

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:

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 and evidence context 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 and complete D&D workflow explain caller tasks.

Removing reporting/discovery files is intentional, not a domain schema or filename-mapping change. Migration guidance 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.