narratio/docs/integrations/seriatim.md

Integration: Seriatim

Purpose

Define the Seriatim adapter contract used by merge, normalize, and trim.

Adapter Boundary

Interface:

• seriatim.Runner
• methods:
  • Run(ctx, MergeRequest)
  • Normalize(ctx, NormalizeRequest)
  • Trim(ctx, TrimRequest)

Primary implementation:

• internal/adapters/seriatim/SubprocessRunner

Execution modes:

• seriatim merge
• seriatim normalize
• seriatim trim

Request/Result Contracts

• MergeRequest/MergeResult: multi-input merge to base transcript, optional report.
• NormalizeRequest/NormalizeResult: transcript normalization with explicit schema.
• TrimRequest/TrimResult: transcript trimming with required keep selector.

Results include output/log/config paths, timing, exit code, and metadata.

Validation and Failure Semantics

Runner construction validates:

• binary presence;
• timeout > 0;
• supported output schema (seriatim-minimal|seriatim-intermediate|seriatim-full);
• non-negative coalesce gap.

Invocation fails on:

• missing required request paths/inputs;
• invalid normalize schema override;
• subprocess failure;
• invalid JSON outputs;
• missing segments array for normalize/trim transcript outputs.

When report paths are provided/enabled, report files must parse as JSON.

Deterministic Behavior

• argument ordering is deterministic per command construction.
• merge env overrides are explicit (SERIATIM_*) and only emitted when configured.
• generated invocation YAML (seriatim.generated.v1) is emitted when requested.
• adapter does not write manifests or choose stage inputs.

Config Mapping

Config fields consumed through runner/stage wiring are under pipeline.seriatim.*.

Maintained examples with Seriatim config:

• examples/pipeline.full.annotated.yml
• examples/pipeline.production.yml