80 lines
3.3 KiB
Markdown
80 lines
3.3 KiB
Markdown
# 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.
|