notarius/docs/roadmap/5-seriatim-input-module.md

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:

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?