narratio/docs/internal/adapters.md

Internal: Adapters

Purpose

Describe the external adapter boundaries used by Narratio stages and app orchestration, including default runtime wiring.

Inputs and outputs

Inputs:

• Stage requests passed through adapter interfaces (for example transcription, merge/normalize/trim, polish, artifact generation, object-store operations, notifications).
• Resolved config values used to construct default adapters.

Outputs:

• Adapter-specific result structs (paths, metadata, status/attempt info, duration/exit details).
• Adapter errors returned to stage/app orchestration.

Boundaries

Owns:

• Transport/process/SDK details at system boundaries (HTTP, subprocess CLI invocation, AWS SDK calls).
• Request/response contracts in internal/adapters/* packages.

Does not own:

• Stage sequencing, skip/force/resume decisions.
• Manifest transition logic.
• Canonical workspace path policy.

Config fields used

Default wiring and adapter calls consume:

• pipeline.whisperx.*
• pipeline.seriatim.*
• pipeline.audita.*
• pipeline.scriptorium.*
• pipeline.storage.* and pipeline.archive.* (object-store construction/gating)
• pipeline.notification.* (sender boundary exists; placeholder behavior today)

External adapters used

Runtime env boundary fields (internal/stage.Env):

• whisperx.Client
• seriatim.Runner
• audita.Runner
• scriptorium.Runner
• storage.ObjectStore
• notify.Sender
• analyzer.Runner

Current execution usage:

• Actively used by implemented stages: WhisperX, Seriatim, Audita, Scriptorium, ObjectStore, Notifier.
• Present but not used by implemented stage set: Analyzer, legacy storage.Backend.

Default construction in app runner:

• Auto-constructed when not injected: WhisperX HTTP client, Seriatim subprocess runner, Audita subprocess runner, Scriptorium subprocess runner, object store (only when needed), and notify.NoopSender.
• Callers can inject test/fake implementations through app.RunOptions.Env.

State and manifest behavior

• Adapters do not directly mutate session/run manifests.
• Stages and runner own manifest writes and stage status transitions.
• Adapter outputs are persisted indirectly through stage result mapping (outputs/logs/generated configs/metadata).

Skip and resume behavior

• No adapter-level skip/resume semantics.
• Skip/resume/force behavior is decided by app runner using manifest stage state.

Failure behavior

• Adapter constructors validate config-derived values and fail early on invalid required inputs.
• Adapter run-time failures are returned to stage code with boundary context and are recorded as stage failures by runner logic.
• Subprocess adapters preserve stdout/stderr and generated-config paths to aid diagnosis.

Tests to inspect before changing

• 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/adapters/notify/fake_test.go
• internal/adapters/analyzer/fake_test.go
• internal/app/runner_test.go

Architectural invariants

• Stage code depends on adapter interfaces, not transport-specific implementation types.
• External SDK-specific types remain inside adapter implementations.
• Default app wiring must remain deterministic and overrideable via injected env dependencies.