Clarify user and integration documentation contracts

2026-08-09 21:41:23 +00:00
parent 115a44f629
commit bd2d5e2496
8 changed files with 187 additions and 63 deletions
--- a/docs/integrations/README.md
+++ b/docs/integrations/README.md
@@ -1,19 +1,33 @@
 # Integrations Index

 ## Audience
-Developers and coding agents changing Narratio's external integration boundaries.
+
+Operators, developers, and coding agents who need to understand Narratio's
+externally observable integration boundaries.

 ## Scope
-`docs/integrations/` is the implementation-level reference for downstream tool adapter contracts.

-These docs cover what Narratio expects from external tools and what each adapter guarantees back to stage code.
+`docs/integrations/` is the canonical reference for protocols, invocation and
+data contracts, logical outputs, and compatibility behavior at external tool
+boundaries.
+
+These documents describe what Narratio sends or invokes, what it accepts in
+return, and how failures are surfaced. Internal composition and stage mechanics
+belong in [the adapter implementation guide](../internal/adapters.md) and the
+focused stage documents.

 ## Integration Contracts
- `audita.md`: transcript polishing adapter (`audita process`).
- `seriatim.md`: merge/normalize/trim/render adapter (`seriatim`).
- `scriptorium.md`: artifact run/render adapter (`scriptorium run|render`).
+
+- [Audita](./audita.md): transcript polishing (`audita process`).
+- [Seriatim](./seriatim.md): merge, normalize, trim, and render operations.
+- [Scriptorium](./scriptorium.md): artifact generation and debug rendering
+  (`scriptorium run|render`).
+- [WhisperX](./whisperx.md): speaker-audio transcription over HTTP.

 ## Related Canonical Docs
- `docs/config.md`: operator-facing configuration reference.
- `docs/internal/adapters.md`: shared adapter boundary and runner wiring.
- `docs/internal/stage-*.md`: stage-specific integration usage.
+
+- [Configuration](../config.md): operator-facing configuration reference.
+- [Adapter implementation](../internal/adapters.md): shared adapter boundary and
+  runner wiring.
+- [Internal documentation](../internal/overview.md): stage-specific integration
+  usage and component ownership.
--- a/docs/integrations/audita.md
+++ b/docs/integrations/audita.md
@@ -3,16 +3,12 @@
 ## Purpose
 Define the Audita adapter contract used by the `polish` stage.

-## Adapter Boundary
-Interface:
- `audita.Runner`
- method: `Run(ctx, PolishRequest) (PolishResult, error)`
+## External Boundary

-Primary implementation:
- `internal/adapters/audita/SubprocessRunner`
-
-Execution mode:
- subprocess invocation of `audita process`
+Narratio invokes `audita process` as a subprocess for each polish operation.
+The configured timeout and parent cancellation bound the invocation. Internal
+runner composition is documented in
+[the adapter implementation guide](../internal/adapters.md).

 ## Request Contract
 `PolishRequest` carries:
@@ -52,8 +48,10 @@ Failure results still include output/log/config/exit metadata for diagnostics.
 - Generated invocation YAML (`audita.generated.v1`) is emitted when requested.
 - Manifest writes are stage-owned; adapter itself is stateless.

-## Config Mapping
-Config fields consumed through runner/stage wiring are under `pipeline.audita.*`.
+## Configuration
+
+Operator-selected values are defined under `pipeline.audita.*` in the
+[configuration reference](../config.md#pipeline).

 Maintained example with Audita config:
 - `examples/pipeline.full.annotated.yml`
--- a/docs/integrations/scriptorium.md
+++ b/docs/integrations/scriptorium.md
@@ -3,20 +3,17 @@
 ## Purpose
 Define the Scriptorium adapter contract used by `analyze` and trim-bounds generation in `trim`.

-## Adapter Boundary
-Interface:
- `scriptorium.Runner`
- methods:
-  - `RunArtifact(ctx, RunArtifactRequest)`
-  - `RenderArtifact(ctx, RenderArtifactRequest)`
+## External Boundary

-Primary implementation:
- `internal/adapters/scriptorium/SubprocessRunner`
+Narratio invokes Scriptorium as a subprocess in these modes:

-Execution modes:
 - `scriptorium run`
 - `scriptorium render`

+The request timeout and parent cancellation bound each invocation. Internal
+runner composition is documented in
+[the adapter implementation guide](../internal/adapters.md).
+
 ## Request Contract
 Both request types carry:
 - binary/config/prompt/profile IDs;
@@ -59,8 +56,11 @@ Render behavior:
 - generated invocation YAML (`scriptorium.generated.v1`) is emitted when requested.
 - adapter is stateless and does not own artifact-selection policy.

-## Config Mapping
-Config fields consumed through runner/stage wiring are under `pipeline.scriptorium.*` plus per-artifact settings under `pipeline.scriptorium.artifacts.*`.
+## Configuration
+
+Operator-selected values are defined under `pipeline.scriptorium.*`, including
+per-artifact settings under `pipeline.scriptorium.artifacts.*`, in the
+[configuration reference](../config.md#pipeline).

 Maintained examples with Scriptorium config:
 - `examples/pipeline.full.annotated.yml`
--- a/docs/integrations/seriatim.md
+++ b/docs/integrations/seriatim.md
@@ -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`
--- a/docs/integrations/whisperx.md
+++ b/docs/integrations/whisperx.md
@@ -0,0 +1,66 @@
+# Integration: WhisperX
+
+## Purpose
+
+WhisperX transcribes each prepared speaker audio file for Narratio's
+`transcribe` stage. Narratio uses an HTTP boundary and installs each successful
+response as that speaker's raw transcript JSON.
+
+## HTTP Boundary
+
+Narratio sends an HTTP `POST` to the configured transcription URL using
+`multipart/form-data` with:
+
+- `file`: the audio file, retaining its base filename; and
+- `language`: the configured language string.
+
+The server must return a `2xx` response whose body is valid JSON. Narratio does
+not currently require a more specific response schema at this boundary.
+
+## Request And Result Contract
+
+Each adapter request identifies a speaker, a readable audio file, and the
+destination for the raw transcript. The HTTP request carries the audio and
+language; the speaker identifier remains Narratio orchestration metadata.
+
+On success, Narratio atomically writes the response body to the requested
+destination. The adapter result reports that logical output together with the
+attempt count, final HTTP status when available, elapsed duration, and adapter
+identity metadata. A failed or invalid response is not installed as the
+transcript output.
+
+## Retry, Timeout, And Cancellation
+
+- The configured timeout applies independently to each HTTP attempt.
+- `retries` means additional attempts after the first.
+- HTTP `429`, HTTP `5xx`, attempt timeouts, and network errors are retryable.
+- Other HTTP `4xx` responses and explicit cancellation are not retryable.
+- Narratio waits the configured retry delay between attempts and aborts that
+  wait when the parent context is canceled.
+
+## Validation And Failure Semantics
+
+Client construction rejects a missing or invalid absolute transcription URL,
+a missing language, a non-positive timeout, negative retries, or a negative
+retry delay. A request fails before transmission when its audio or output path
+is missing.
+
+Non-`2xx` status, transport failure, response-size overflow, invalid JSON, or
+failure to install the output causes the transcription to fail. Errors include
+attempt context, and the result retains attempts, final status when available,
+and elapsed duration for diagnostics.
+
+## Determinism And Concurrency
+
+Each audio request has stable multipart field names, and successful bytes are
+installed atomically. The transcribe stage may process speaker files in
+parallel, bounded by the configured concurrency. It records results in stable
+speaker order after all work completes; any speaker failure fails the stage.
+
+## Related Canonical Docs
+
+- [Configuration](../config.md#pipeline) defines the operator-selected
+  WhisperX URL, language, timeouts, retry policy, and concurrency.
+- [Adapter implementation](../internal/adapters.md) describes internal wiring.
+- [Transcribe stage](../internal/stage-transcribe.md) describes stage mechanics,
+  durable artifacts, and manifests.