# Transcript and Glossary File Integration

## Scope

This document defines the input file contracts for:
- transcript JSON;
- glossary YAML.

These files are loaded and validated before processing begins.

## Transcript JSON Contract

Audita accepts either top-level shape:
- JSON array of segments; or
- JSON object with a `segments` array.

Segment fields:
- `id` (optional integer in source form);
- `speaker` (required non-empty string);
- `start` (required finite non-negative number);
- `end` (required finite non-negative number, `>= start`);
- `text` (required non-empty string);
- `categories` (optional string array; entries must be non-empty).

Additional rules:
- transcript must contain at least one segment;
- duplicate segment IDs are rejected when IDs are present.

Example (`examples/tiny-transcript.json`):

```json
[
  {
    "id": 1,
    "speaker": "A",
    "start": 0.0,
    "end": 1.2,
    "text": "hello world"
  }
]
```

## Glossary YAML Contract

Audita expects top-level `glossary` list entries.

Entry fields:
- `name` (required non-empty string);
- `category` (required non-empty string);
- `summary` (required non-empty string);
- `aliases` (optional list of strings; entries must be non-empty);
- `plural` (optional string).

Additional rules:
- glossary must contain at least one entry.

Example (`examples/tiny-glossary.yaml`):

```yaml
glossary:
  - name: Audita
    aliases:
      - audita
    category: product
    summary: The Audita transcript correction CLI.
```

## Validation Failure Behavior

Representative transcript validation failures:
- invalid JSON;
- unsupported top-level shape;
- empty `speaker` or `text`;
- invalid times (`NaN`, `Inf`, negative, or `end < start`);
- duplicate IDs;
- empty transcript array.

Representative glossary validation failures:
- invalid YAML;
- empty or missing glossary entries;
- missing required entry fields;
- empty alias values.

These failures surface as schema errors and the process exits nonzero.

## CLI Usage

Minimal invocation:

```sh
audita process ./transcript.json --glossary ./glossary.yaml --output ./corrected.json
```

See also:
- [`docs/cli.md`](../cli.md)
- [`docs/config.md`](../config.md)
- [`examples/tiny-transcript.json`](../../examples/tiny-transcript.json)
- [`examples/tiny-glossary.yaml`](../../examples/tiny-glossary.yaml)