narratio/docs/internal/adapters.md

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.

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:

• WhisperX HTTP client from pipeline config.
• Seriatim subprocess runner.
• Audita subprocess runner.
• Scriptorium subprocess runner.
• Notarius subprocess runner when extraction is enabled.
• Noop notifier (notify.NoopSender).
• Object store only when required by selected stages/config.

Notarius is composed only when extraction is enabled; the extract stage owns receipt, bundle, and configured-lane policy rather than the adapter.

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.

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, Seriatim, Audita, Scriptorium, and Notarius contracts before changing an externally visible boundary. Operator-selected values belong in Configuration.