# Checkpoint 5: Seriatim Input Module

## 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-stage module.

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

## Scope

In scope:

- `internal/modules/input/seriatim`;
- parser for Seriatim minimal output JSON;
- mapping into `SourceDocument` and `SourceUnit`;
- source-document validation;
- input adapter registry wiring;
- module metadata/capabilities for pipeline validation;
- fixtures and tests;
- config path to use the input module through a named pipeline profile if
  config loading 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

### Seriatim Source Model

Define module-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 Seriatim input module package.

### 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 module-specific errors.

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

### Registry And CLI Wiring

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

Declare module metadata for pipeline validation. Initial provided capabilities
should include transcript-oriented metadata such as `speaker` and `timestamps`
if those fields are preserved from Seriatim input.

If config and CLI support exist, add a minimal pipeline-profile fixture or test
config using the Seriatim input module:

```sh
notarius run dnd-session --input ./transcript.json --only spells
```

The command may still use fake extract, merge, normalize, and output modules
until checkpoint 6.

### 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 input module is selectable through the registry and pipeline-profile
  configuration when config support exists.
- The input module declares capabilities needed for pipeline validation.
- Tests prove transcript-specific assumptions are isolated to the input module.

## Review Questions

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