narratio/docs/internal/adapters.md

# Internal: Adapters

## Purpose
Define external integration boundaries and default adapter wiring used by app/stage orchestration.

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

Primary adapters:
- `whisperx.Client`
- `seriatim.Runner`
- `audita.Runner`
- `scriptorium.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:
- WhisperX HTTP client from pipeline config.
- Seriatim subprocess runner.
- Audita subprocess runner.
- Scriptorium subprocess runner.
- Noop notifier (`notify.NoopSender`).
- Object store only when required by selected stages/config.

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.

## Test Surfaces
- `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/storage/*_test.go`
- `internal/app/runner_test.go`