Rewrite internal documentation for current stage and state contracts

docs/internal/adapters.md

@@ -1,38 +1,12 @@
 # Internal: Adapters
 
 ## Purpose
-Describe the external adapter boundaries used by Narratio stages and app orchestration, including default runtime wiring.
+Define external integration boundaries and default adapter wiring used by app/stage orchestration.
 
-## 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.
+## Adapter Boundaries
+Narratio stage logic depends on adapter interfaces, not transport-specific details.
 
-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.publish.*` (object-store construction/gating)
-- `pipeline.notification.*` (sender boundary exists; placeholder behavior today)
-
-## External adapters used
-Runtime env boundary fields (`internal/stage.Env`):
+Primary adapters:
 - `whisperx.Client`
 - `seriatim.Runner`
 - `audita.Runner`
@@ -40,39 +14,39 @@ Runtime env boundary fields (`internal/stage.Env`):
 - `storage.ObjectStore`
 - `notify.Sender`
 
-Current execution usage:
-- Actively used by implemented stages: `WhisperX`, `Seriatim`, `Audita`, `Scriptorium`, `ObjectStore`, `Notifier`.
-- Present but not used by implemented stage set: legacy `storage.Backend`.
+Legacy compatibility boundary:
+- `storage.Backend` remains in the storage adapter package and defaults to `NoopBackend`; current pipeline stages use `storage.ObjectStore`.
 
-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`.
-- Object-store construction goes through app command orchestration so configured filesystem secrets are loaded before the storage adapter is initialized.
-- Callers can inject test/fake implementations through `app.RunOptions.Env`.
+## Ownership
+Adapters own:
+- HTTP/subprocess/SDK argument and transport details.
+- Backend-specific request/response mapping.
 
-## 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).
+Adapters do not own:
+- stage ordering/skip/force logic;
+- manifest transitions;
+- canonical path policy.
 
-## Skip and resume behavior
-- No adapter-level skip/resume semantics.
-- Skip/resume/force behavior is decided by app runner using manifest stage state.
+## 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.
 
-## 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.
+Object-store construction goes through `newCommandObjectStore`, which loads configured filesystem secrets before adapter initialization.
 
-## Tests to inspect before changing
+## 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/adapters/notify/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.