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