# Data formats

All JSON files use UTF-8 and `schema_version: 1`. Dates are ISO 8601 UTC. SHA-256 values identify exact file bytes. Local paths and hashes are evidence bookkeeping, not authentication or digital signatures; someone able to alter all inputs and reports can forge them.

## Preparation bundle

`prepare` accepts an audio or video file. An optional `--reference` points to UTF-8 text. Its new output directory contains:

```text
bundle.json
audio.wav
reference.txt   # only when supplied
```

Example shape (hashes abbreviated for documentation only):

```json
{
  "schema_version": 1,
  "created_at": "2026-10-14T00:00:00+00:00",
  "source_path": "/absolute/path/input.wav",
  "source_sha256": "64 hexadecimal characters",
  "audio_file": "audio.wav",
  "audio_sha256": "64 hexadecimal characters",
  "channels": 1,
  "sample_rate": 48000,
  "sample_frames": 2880000,
  "duration_seconds": 60.0,
  "sample_width_bytes": 2,
  "conversion": "Description of actual conversion",
  "publication_approved": false,
  "reference_file": "reference.txt",
  "reference_sha256": "64 hexadecimal characters"
}
```

The last two fields are omitted when there is no reference. `sample_frames` counts interleaved audio frames, each containing one sample per channel. Duration is `sample_frames / sample_rate`; stereo does not double the duration. Both the original input and prepared audio must exist unchanged when reviewing.

## Calibration output

```text
report.json
clean.wav
silence.wav
reverse.wav
```

The report includes `reference_path`, `reference_sha256`, `human_confirmed_reference`, `service`, `cases`, `errors`, `status` and `publication_approved: false`.

`cases` contains `clean`, `silence` and `reverse`. Each records its audio filename/hash, prompt hash, raw `response_text`, elapsed request time and parsed `assessment` where possible. A malformed JSON response is retained with `parse_error`. Expected assessment fields:

```json
{
  "intelligible_speech": true,
  "heard_words": "Words actually recognized from the recording",
  "audible_problems": [],
  "sound_description": "Specific acoustic observations"
}
```

Clean audio must report intelligible speech, at least eight heard words, an acoustic description and no audible problems. Silence/reverse must report no intelligible speech, use empty/whitespace-only `heard_words`, and supply the expected structured fields. Fabricated words or labels such as `none` fail validation. The words and acoustic accuracy still need inspection. Control processing reverses complete interleaved sample frames, preserving stereo channel pairing.

## Review output

```text
report.json
window_001.wav
window_002.wav
...
```

`report.json` includes:

| Field | Meaning |
| --- | --- |
| `bundle_path`, `bundle_sha256` | Exact prepared bundle used |
| `calibration_path`, `calibration_sha256` | Exact controls report used |
| `audio_sha256` | Exact prepared full recording |
| `service` | Verified Space, host, revision and stated backend limitation |
| `full_clip.blind` | Blind full-recording assessment and raw response |
| `full_clip.reference` | Additional reference pass, only when a reference exists |
| `windows` | Ordered sample-counted windows, responses and per-window errors |
| `coverage` | Sample rate/count, duration, overlap, number of windows, `gap_free` |
| `errors` | All validation failures; acoustic failures are never discarded |
| `status` | `running`, `candidate_evidence_requires_inspection`, `held` or `failed` |
| `publication_approved` | Always `false` |
| `error` | Execution failure description, if a failure occurred |

Every window records `audio_file`, `audio_sha256`, `start_sample` (inclusive), `end_sample` (exclusive), derived start/end seconds, raw response and parsed findings. Full clips require specific opening/middle/ending observations. Windows require heard words and acoustic descriptions. Required quality checks are `speech_intelligibility`, `pronunciation`, `pacing_delivery` and `recording_mix`, each with `status` and `evidence`. Only the final window must confirm `ending_complete: true`; other windows must return null. Issues or uncertainties prevent candidate status.

The exact requested model schemas are defined in `CALIBRATION_PROMPT`, `FULL_PROMPT` and `WINDOW_PROMPT` in `tool.py`. No duration or timestamp generated by a model is used to prove coverage.

## Failures and immutability

Run directories must not exist before the command. Once an operation creates its directory, it checkpoints its own report atomically using a temporary file and replacement. This updates the active run's report; it does not overwrite a previous run. A process interrupted between checkpoints can leave `running` or a temporary file; treat that run as incomplete and preserve it.

Preparation errors after directory creation produce `failure.json`. Network operations preserve partial results as `failed`. An interrupted review may have no `coverage` object or fewer windows. Such a report is never complete evidence.