Clarify user and integration documentation contracts

This commit is contained in:
2026-08-09 21:41:23 +00:00
parent 115a44f629
commit bd2d5e2496
8 changed files with 187 additions and 63 deletions

View File

@@ -3,24 +3,19 @@
## Purpose
Define the Seriatim adapter contract used by `merge`, `normalize`, `trim`, and `render`.
## Adapter Boundary
Interface:
- `seriatim.Runner`
- methods:
- `Run(ctx, MergeRequest)`
- `Normalize(ctx, NormalizeRequest)`
- `Trim(ctx, TrimRequest)`
- `Render(ctx, RenderRequest)`
## External Boundary
Primary implementation:
- `internal/adapters/seriatim/SubprocessRunner`
Narratio invokes Seriatim as a subprocess in these modes:
Execution 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.
@@ -53,8 +48,11 @@ When report paths are provided/enabled, report files must parse as JSON.
- 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.*` and `pipeline.render.*`.
## Configuration
Operator-selected values are defined under `pipeline.seriatim.*` and
`pipeline.render.*` in the
[configuration reference](../config.md#pipeline).
Maintained examples with Seriatim config:
- `examples/pipeline.full.annotated.yml`