# Seriatim Transcript JSON

This document is the external input contract for the implemented `seriatim`
input adapter.

## Adapter

- Module key: `seriatim`
- Document kind: `transcript`
- Unit kind: `transcript_segment`
- Source format: `application/vnd.seriatim+json`

The adapter parses raw Seriatim JSON into a generic source document. It owns
transcript-specific JSON parsing and metadata mapping; core source and pipeline
code stay source-format agnostic.

## Accepted Shape

The input must be one JSON object with top-level `metadata` and `segments`
fields. This covers the maintained minimal fixture and Seriatim intermediate
output that provides the same required segment fields.

```json
{
  "metadata": {
    "id": "session-alpha",
    "title": "Synthetic D&D spell session"
  },
  "segments": [
    {
      "id": 1,
      "start": 0,
      "end": 4,
      "speaker": "Aria",
      "text": "Aria raises her holy symbol and casts Cure Wounds."
    }
  ]
}
```

The maintained example is
[examples/seriatim-minimal-transcript.json](../../examples/seriatim-minimal-transcript.json).

Top-level metadata entries are preserved. Other segment fields, such as
`categories`, are ignored.

Multiple top-level JSON values are rejected.

## Validation

The adapter rejects:

- empty raw input;
- malformed JSON;
- top-level JSON that is not an object;
- missing, null, or non-object `metadata`;
- missing, null, non-array, or empty `segments`;
- segment values that are not objects;
- segment `id` values that are not positive integer JSON numbers or numeric
  strings;
- non-string `speaker` or `text`;
- duplicate segment IDs;
- missing or empty `speaker`;
- missing, empty, invalid, non-finite, or negative `start`;
- missing, empty, invalid, non-finite, or negative `end`;
- `end` values before `start`;
- missing or empty `text`.

Segment text is preserved as provided, but it must not be empty after trimming.

## Source Mapping

The adapter maps input to `SourceDocument`:

- `metadata` becomes `SourceDocument.Metadata`;
- `SourceDocument.Kind` is `transcript`;
- `SourceDocument.Format` is `application/vnd.seriatim+json`;
- `SourceDocument.Digest` is `sha256:<hex>` of the exact raw input bytes.

`SourceDocument.ID` is selected in this order:

1. the parse request source ID, after trimming;
2. `metadata.id`, when it is a non-empty string after trimming;
3. `metadata.source_id`, when it is a non-empty string after trimming;
4. `seriatim:<first-16-hex-chars-of-raw-sha256>`.

Each segment becomes one `SourceUnit`:

- `segment.id` becomes integer `SourceUnit.ID`;
- `segment.text` becomes `SourceUnit.Text`;
- `SourceUnit.Kind` is `transcript_segment`;
- `speaker`, `start`, and `end` are stored in source-unit metadata.

## Metadata Keys

Seriatim unit metadata uses these keys:

- `speaker`: string speaker label;
- `start`: `json.Number` start value;
- `end`: `json.Number` end value.

The `internal/modules/input/seriatim` package exposes typed accessors for these
values.

## Capabilities

The module declares these provided capabilities:

- `source.transcript`
- `transcript.speaker`
- `transcript.timestamps`

## Compatibility Limit

This contract covers only Seriatim transcript JSON with the top-level
`metadata` object and `segments` array described here. Broader Seriatim output
schemas are compatible only when they provide these required fields with the
accepted types.