From 91bec3ae521ec9cf268244df3d18f1b1caa839f1 Mon Sep 17 00:00:00 2001
From: Eric Rakestraw <eric@rakestraw.us>
Date: Fri, 3 Jul 2026 21:18:24 +0000
Subject: [PATCH] Document Seriatim input integration

---
 docs/integrations/seriatim.md | 101 ++++++++++++++++++++++++++++++++++
 1 file changed, 101 insertions(+)
 create mode 100644 docs/integrations/seriatim.md

diff --git a/docs/integrations/seriatim.md b/docs/integrations/seriatim.md
new file mode 100644
index 0000000..69b98b1
--- /dev/null
+++ b/docs/integrations/seriatim.md
@@ -0,0 +1,101 @@
+# 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.