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