# Seriatim Minimal Transcript JSON

This document describes the Seriatim input format currently accepted by the
`seriatim` input adapter.

## Adapter

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

The adapter parses raw Seriatim JSON into a generic `SourceDocument`. It does
not add transcript-specific fields to core source or runner contracts.

## Accepted Shape

The input must be a JSON object with top-level `metadata` and `segments` fields:

```json
{
  "metadata": {
    "id": "session-alpha",
    "title": "Synthetic session transcript"
  },
  "segments": [
    {
      "id": "seg-001",
      "start": 0,
      "end": 4.5,
      "speaker": "Narrator",
      "text": "The stone door opens."
    }
  ]
}
```

Extra compatible fields are ignored. Multiple top-level JSON values are
rejected.

## Validation

The adapter rejects:

- empty raw input;
- malformed JSON;
- missing, null, or non-object `metadata`;
- missing, null, non-array, or empty `segments`;
- empty segment IDs;
- segment IDs with leading or trailing whitespace;
- 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 may keep leading or trailing whitespace, but it must not be empty
after trimming.

## Source Mapping

The adapter maps Seriatim input into the source model as follows:

- top-level `metadata` becomes `SourceDocument.Metadata`;
- `SourceDocument.Digest` is `sha256:<hex>` of the exact raw input bytes;
- `segment.id` becomes `SourceUnit.ID`;
- `segment.text` becomes `SourceUnit.Text`;
- each source unit has kind `transcript_segment`;
- segment `speaker`, `start`, and `end` are stored in source-unit metadata.

`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>`.

## 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 provides typed accessors for
these metadata values.

## Capabilities

The module declares these provided capabilities for pipeline validation:

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

## Limits

Only the Seriatim minimal transcript shape described here is supported. Broader
Seriatim schema variants are not currently accepted as a compatibility contract.