# Checkpoint 4: Seriatim Input Adapter

## Status

This document describes planned work, not implemented behavior.

## Goal

Add the first real input source while keeping transcript-specific behavior
isolated inside an input adapter.

This checkpoint should allow Seriatim minimal transcript JSON to become a
generic `SourceDocument`.

## Scope

In scope:

- `internal/adapters/input/seriatim`;
- parser for Seriatim minimal output JSON;
- mapping into `SourceDocument` and `SourceUnit`;
- source-document validation;
- adapter registry wiring;
- fixtures and tests;
- CLI/config path to select the adapter if the CLI shell exists.

Out of scope:

- D&D extraction;
- LLM extraction calls;
- transcript-specific behavior in runner/core packages;
- support for every possible Seriatim schema variant.

## Proposed Stages

### Stage 1: Seriatim Source Model

Define adapter-local structs for the Seriatim minimal output schema.

Expected external shape:

- top-level `metadata`;
- top-level `segments`;
- segment `id`;
- segment `start`;
- segment `end`;
- segment `speaker`;
- segment `text`.

Keep these structs in the adapter package.

### Stage 2: Parse And Validate

Implement parser and validation behavior.

Validation should cover:

- valid JSON;
- required metadata fields;
- required segment fields;
- unique segment IDs;
- non-empty segment text;
- valid start/end values as appropriate.

Prefer clear adapter-specific errors.

### Stage 3: Map To SourceDocument

Map Seriatim data into the generic source model:

- segment `id` becomes `SourceUnit.ID`;
- segment `text` becomes `SourceUnit.Text`;
- unit kind should identify transcript-like units without requiring core
  packages to know transcript semantics;
- `speaker`, `start`, and `end` become unit metadata;
- Seriatim metadata becomes document metadata.

The resulting `SourceDocument` should pass core source validation.

### Stage 4: Registry And CLI Wiring

Register the adapter under a stable key, likely `seriatim`.

If CLI support exists, add provisional selection:

```sh
notarius extract ./transcript.json --input seriatim
```

The command may still use fake extractors until checkpoint 5.

### Stage 5: Fixtures And Tests

Add fixtures and tests for:

- valid Seriatim minimal transcript;
- malformed JSON;
- missing metadata;
- missing or duplicate segment IDs;
- empty segment text;
- source-reference compatibility with generated unit IDs.

## Done Criteria

- `go test ./...` passes.
- Seriatim minimal transcript JSON maps into `SourceDocument`.
- Transcript fields do not appear in core runner contracts.
- The adapter is selectable through the registry.
- Tests prove transcript-specific assumptions are isolated to the adapter.

## Review Questions

- Are segment, speaker, and timestamp assumptions contained inside the adapter?
- Are unit IDs stable and suitable for source references?
- Does the adapter preserve enough metadata for transcript-oriented output later?
- Should the adapter accept only Seriatim minimal output for now?