# JSON Output

This document is the durable JSON output file-format contract produced by the
implemented `json` output module and written by the CLI.

## Output Directory

The CLI writes logical output files under:

```text
<output-root>/<run-id>/
```

The default output root is `./notarius-output`. Operational behavior is covered
in [Operations](../operations.md).

## Files

The `json` output module writes:

- `index.json`
- `manifest.json`
- `outputs/<lane-id>.json`, one file per normalized raw lane output
- `rejected.json`
- `warnings.json`

Files are pretty-printed JSON with a trailing newline when the payload is JSON.

## `index.json`

Shape:

```json
{
  "manifest_file": "manifest.json",
  "output_files": [
    {
      "lane_id": "spells",
      "media_type": "application/json",
      "file": "outputs/spells.json",
      "module_key": "noop",
      "schema_id": "notarius.dnd.spells",
      "schema_name": "notarius_dnd_spells_v1",
      "schema_version": "v1"
    }
  ],
  "rejected_file": "rejected.json",
  "warnings_file": "warnings.json"
}
```

`output_files` is in normalized output order. Output file names are produced by
sanitizing the lane ID:

- characters outside `A-Z`, `a-z`, `0-9`, `.`, `_`, and `-` become `_`;
- repeated `..` sequences are replaced;
- leading and trailing `.`, `_`, and `-` are trimmed;
- empty sanitized names are rejected;
- two lanes that sanitize to the same output file are rejected.

## `manifest.json`

`manifest.json` contains a run manifest:

```json
{
  "run_id": "run-123",
  "pipeline_id": "dnd-session",
  "pipeline_digest": "sha256:...",
  "input_module": "seriatim",
  "chunker": "dnd/scenes",
  "source_digests": ["sha256:..."],
  "extractors": ["dnd/spells"],
  "merger": "appendorder",
  "normalizer": "noop",
  "output_encoder": "json",
  "artifact_lanes": [
    {
      "id": "spells",
      "extractor": "dnd/spells",
      "merger": "appendorder",
      "normalizer": "noop"
    }
  ],
  "validation_status": "approved",
  "started_at": "2026-01-01T00:00:00Z",
  "completed_at": "2026-01-01T00:00:01Z"
}
```

Fields with empty values may be omitted by JSON encoding.

`source_digests` contains source document digests only. Bound references are
recorded separately under `references`, which contains provenance only: target
stage, lane ID when present, slot name, origin type and URI, digest, media
type, byte size, and binding source. Reference content is not written to
durable output.

Reference `stage` is `chunk`, `extract`, `merge`, or `normalize`. `lane_id` is
omitted for chunk references and present for extract, merge, and normalize
references.

`validation_status` is `approved` when no raw outputs were rejected and
`rejected` when one or more raw outputs were rejected.

## Output Payload Files

Each normalized raw output is written to `outputs/<sanitized-lane-id>.json`.
For `application/json` payloads, the file contains the raw JSON payload
pretty-printed. Other media types are written as raw bytes with the media type
reported in `index.json`.

For the current D&D spell extractor, `outputs/spells.json` has this shape:

```json
{
  "spell_casts": [
    {
      "caster": "Aria",
      "spell": "Cure Wounds",
      "effect": "heals an injured ally",
      "narrative_description": "Aria raises her holy symbol and casts Cure Wounds.",
      "source_refs": [
        {
          "source_id": "session-alpha",
          "start_unit_id": 1,
          "end_unit_id": 1
        }
      ]
    }
  ]
}
```

## `rejected.json`

Shape:

```json
{
  "rejected": []
}
```

When raw output validation rejects an output, entries use the
`contracts.RejectedOutput` shape, including stage, lane ID, module key,
validator name, reason code, message, attempt count, and optional diagnostic
artifact path.

## `warnings.json`

Shape:

```json
{
  "warnings": [
    {
      "scope": "extract",
      "reason_code": "example",
      "message": "human-readable warning"
    }
  ]
}
```

`warnings` is an empty array when no warnings are reported.