narratio/docs/integrations/seriatim.md

Integration: seriatim

Purpose

Define Narratio's adapter contract for merge, normalize, and trim subprocess invocations of Seriatim.

Inputs and Outputs

Inputs:

• MergeRequest: raw/per-speaker normalized transcript inputs, base output path, optional report, speaker/autocorrect paths, logs/config
• NormalizeRequest: input transcript, output path, schema, optional report, timeout/log/config
• TrimRequest: input transcript, output path, keep selector, timeout/log/config

Outputs:

• MergeResult, NormalizeResult, TrimResult with output paths, logs/config paths, exit code, duration, binary provenance, and metadata.

Boundaries

Owns:

• Validated deterministic CLI invocation construction
• Optional env tuning propagation for merge
• Invocation config file emission
• JSON output validation

Does not own:

• Transcript input selection/promotion logic (stage-owned)
• Bounds computation (scriptorium/trim-stage-owned)

Config Fields Used

Via pipeline.seriatim.* mapped in app/stage wiring:

• binary, timeout, output_schema, coalesce_gap, report
• env.overlap_word_run_gap
• env.overlap_word_run_reorder_window
• env.backchannel_max_duration
• env.filler_max_duration

External Adapters Used

• Shared subprocess helper (internal/adapters/subprocess).

State and Manifest Behavior

• No direct manifest writes.
• Stage metadata consumes adapter result fields and preserves generated config/log references.

Skip and Resume Behavior

• Adapter has no skip/resume logic. Runner controls stage execution.

Failure Behavior

• Constructor fails for invalid binary/timeout/output-schema/coalesce-gap.
• Merge fails on missing output path/inputs/report path (if enabled), subprocess errors, invalid merged output JSON, invalid report JSON.
• Normalize fails on missing input/output, invalid schema, subprocess errors, invalid final output JSON shape, invalid report JSON.
• Trim fails on missing input/output/keep selector, subprocess errors, invalid final-trimmed output JSON shape.

Tests to Inspect Before Changing

• internal/adapters/seriatim/subprocess_test.go
• internal/adapters/seriatim/fake_test.go
• internal/stage/merge_test.go
• internal/stage/normalize_test.go
• internal/stage/trim_test.go

Architectural Invariants

• Supported output schemas are limited to seriatim-minimal, seriatim-intermediate, seriatim-full.
• Final and final-trimmed outputs must include segments arrays.
• Merge/normalize/trim all route through deterministic subprocess invocation.