63 lines
2.3 KiB
Markdown
63 lines
2.3 KiB
Markdown
# 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](../internal/adapters.md).
|
|
|
|
## 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.
|
|
Each Seriatim JSON or rendered-text result is limited to 64 MiB and must be a
|
|
regular file without symlinked path components.
|
|
|
|
## 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](../config.md#pipeline).
|
|
|
|
Maintained examples with Seriatim config:
|
|
|
|
- [Full annotated pipeline](../../examples/pipeline.full.annotated.yml)
|
|
- [Production-shaped pipeline](../../examples/pipeline.production.yml)
|