# Internal: Adapters

## Purpose

Explain the adapter interfaces and production composition used by application
and stage orchestration. Externally observable protocols and formats belong in
the [integration contracts](../integrations/).

## Adapter Boundaries

Narratio stage logic depends on adapter interfaces, not transport-specific details.

Primary adapters:

- `whisperx.Client`
- `seriatim.Runner`
- `audita.Runner`
- `scriptorium.Runner`
- `notarius.Runner`
- `storage.ObjectStore`
- `notify.Sender`

## Ownership

Adapters own:

- HTTP/subprocess/SDK argument and transport details.
- Backend-specific request/response mapping.

Adapters do not own:

- stage ordering/skip/force logic;
- manifest transitions;
- canonical path policy.

## Default Wiring

`internal/app/runner.go` initializes default adapters when not injected and
only when the selected execution plan needs them:

- WhisperX HTTP client for `transcribe`.
- Seriatim subprocess runner for `merge`, `normalize`, `trim`, or `render`.
- Audita subprocess runner for `polish`.
- Scriptorium subprocess runner for `trim` or `analyze`.
- Notarius subprocess runner for `extract` when extraction is enabled.
- Noop notifier (`notify.NoopSender`) for `notify`.
- Object store only when required by selected stages/config.

Remote publish locks are loaded only for a selected, enabled publish that
uploads a run. Shared session lifecycle setup still applies to every selected
range, but an unselected integration is neither initialized nor validated by
runner composition. Each selected stage retains its own fail-fast configuration
and input validation.

`session plan` is outside production adapter composition. It performs
resume validation and models selected transitions against cloned manifest
state without constructing or invoking stage-execution adapters. The shared
command configuration loader may still use object storage to retrieve a missing
remote session file before planning begins.

Notarius is composed only when extraction is enabled; the extract stage owns
prepared reference resolution, receipt, bundle, and configured-lane policy.
The adapter validates the ordered selector/absolute-path pairs and is the sole
owner of serializing them as repeated `--reference` arguments before `--json`.

Object-store construction goes through `newCommandObjectStore`, which loads
configured filesystem secrets before adapter initialization.

## Failure Semantics

- Constructor errors fail stage execution setup early.
- Runtime adapter errors propagate to stage code and then manifest failure handling.
- Subprocess adapters persist stage logs/generated configs through stage-managed paths.
- Shared subprocess execution starts an owned process group on Linux/macOS or a
  kill-on-close job object on Windows. Every terminal path disposes of that
  owned tree before returning. After a natural leader exit, Unix checks for
  remaining group members and uses bounded graceful then forceful termination;
  Windows closes the job so kill-on-close applies. Cancellation, deadlines, and
  diagnostic limits use the same terminal disposal path without losing their
  original result classification. Child environments contain only the execution
  baseline and adapter-specified values; configured credentials are explicit
  sensitive values. Stdout and stderr are redacted while streaming into separate
  8 MiB diagnostic captures; a bounded wait closes a stream retained by a
  departed leader's descendant. Unsupported platforms reject owned command
  execution.

## Implementation And Tests

- Composition: `internal/app/runner.go`, `internal/app/object_store.go`
- Shared subprocess mechanics: `internal/adapters/subprocess`
- Focused adapters: `internal/adapters/{whisperx,seriatim,audita,scriptorium,notarius,storage,notify}`
- `internal/adapters/whisperx/http_test.go`
- `internal/adapters/seriatim/subprocess_test.go`
- `internal/adapters/audita/subprocess_test.go`
- `internal/adapters/scriptorium/subprocess_test.go`
- `internal/adapters/notarius/subprocess_test.go`
- `internal/adapters/storage/*_test.go`
- `internal/app/runner_test.go`

See the [WhisperX](../integrations/whisperx.md),
[Seriatim](../integrations/seriatim.md), [Audita](../integrations/audita.md),
[Scriptorium](../integrations/scriptorium.md), and
[Notarius](../integrations/notarius.md) contracts before changing an
externally visible boundary. Operator-selected values belong in
[Configuration](../config.md).