narratio/docs/integrations/seriatim.md

Integration: Seriatim

Purpose

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

External Boundary

Narratio invokes Seriatim as a subprocess in these modes:

• seriatim merge
• seriatim normalize
• seriatim trim
• seriatim render

The configured timeout and parent cancellation bound each invocation. Internal runner composition is documented in the adapter implementation guide.

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.
• RenderRequest/RenderResult: transcript-to-markdown rendering with explicit format and render booleans.

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;
• unsupported render format;
• subprocess failure;
• invalid JSON outputs for merge/normalize/trim;
• missing segments array for normalize/trim transcript outputs;
• empty render output files.

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.

Configuration

Operator-selected values are defined under pipeline.seriatim.* and pipeline.render.* in the configuration reference.

Maintained examples with Seriatim config:

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