Add integration and artifact contract documentation

docs/integrations/seriatim.md

@@ -1,7 +1,7 @@
 # Seriatim Minimal Transcript JSON
 
-This document describes the Seriatim input format currently accepted by the
-`seriatim` input adapter.
+This document is the external input contract for the implemented `seriatim`
+input adapter.
 
 ## Adapter
 
@@ -10,33 +10,39 @@ This document describes the Seriatim input format currently accepted by the
 - 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.
+The adapter parses raw Seriatim JSON into a generic source document. It owns
+transcript-specific JSON parsing and metadata mapping; core source and pipeline
+code stay source-format agnostic.
 
 ## Accepted Shape
 
-The input must be a JSON object with top-level `metadata` and `segments` fields:
+The input must be one JSON object with top-level `metadata` and `segments`
+fields:
 
 ```json
 {
   "metadata": {
     "id": "session-alpha",
-    "title": "Synthetic session transcript"
+    "title": "Synthetic D&D spell session"
   },
   "segments": [
     {
       "id": "seg-001",
       "start": 0,
-      "end": 4.5,
-      "speaker": "Narrator",
-      "text": "The stone door opens."
+      "end": 4,
+      "speaker": "Aria",
+      "text": "Aria raises her holy symbol and casts Cure Wounds."
     }
   ]
 }
 ```
 
-Extra compatible fields are ignored. Multiple top-level JSON values are
-rejected.
+The maintained example is
+[examples/seriatim-minimal-transcript.json](../../examples/seriatim-minimal-transcript.json).
+
+Top-level metadata entries are preserved. Other segment fields are ignored.
+
+Multiple top-level JSON values are rejected.
 
 ## Validation
 
@@ -44,8 +50,11 @@ The adapter rejects:
 
 - empty raw input;
 - malformed JSON;
+- top-level JSON that is not an object;
 - missing, null, or non-object `metadata`;
 - missing, null, non-array, or empty `segments`;
+- segment values that are not objects;
+- non-string `id`, `speaker`, or `text`;
 - empty segment IDs;
 - segment IDs with leading or trailing whitespace;
 - duplicate segment IDs;
@@ -55,19 +64,16 @@ The adapter rejects:
 - `end` values before `start`;
 - missing or empty `text`.
 
-Segment text may keep leading or trailing whitespace, but it must not be empty
-after trimming.
+Segment text is preserved as provided, but it must not be empty after trimming.
 
 ## Source Mapping
 
-The adapter maps Seriatim input into the source model as follows:
+The adapter maps input to `SourceDocument`:
 
-- 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.
+- `metadata` becomes `SourceDocument.Metadata`;
+- `SourceDocument.Kind` is `transcript`;
+- `SourceDocument.Format` is `application/vnd.seriatim.minimal+json`;
+- `SourceDocument.Digest` is `sha256:<hex>` of the exact raw input bytes.
 
 `SourceDocument.ID` is selected in this order:
 
@@ -76,6 +82,13 @@ The adapter maps Seriatim input into the source model as follows:
 3. `metadata.source_id`, when it is a non-empty string after trimming;
 4. `seriatim:<first-16-hex-chars-of-raw-sha256>`.
 
+Each segment becomes one `SourceUnit`:
+
+- `segment.id` becomes `SourceUnit.ID`;
+- `segment.text` becomes `SourceUnit.Text`;
+- `SourceUnit.Kind` is `transcript_segment`;
+- `speaker`, `start`, and `end` are stored in source-unit metadata.
+
 ## Metadata Keys
 
 Seriatim unit metadata uses these keys:
@@ -84,18 +97,17 @@ Seriatim unit metadata uses these keys:
 - `start`: `json.Number` start value;
 - `end`: `json.Number` end value.
 
-The `internal/modules/input/seriatim` package provides typed accessors for
-these metadata values.
+The `internal/modules/input/seriatim` package exposes typed accessors for these
+values.
 
 ## Capabilities
 
-The module declares these provided capabilities for pipeline validation:
+The module declares these provided capabilities:
 
 - `source.transcript`
 - `transcript.speaker`
 - `transcript.timestamps`
 
-## Limits
+## Compatibility Limit
 
-Only the Seriatim minimal transcript shape described here is supported. Broader
-Seriatim schema variants are not currently accepted as a compatibility contract.
+This contract covers only the minimal transcript JSON shape described here.