Rewrite internal documentation for current stage and state contracts

docs/internal/storage.md

@@ -1,75 +1,37 @@
 # Internal: Storage
 
 ## Purpose
-Document Narratio's remote storage backend contracts and implementations under `internal/adapters/storage`.
+Document remote object-store contracts and S3 implementation behavior.
 
-## Inputs and outputs
-Inputs:
-- Resolved storage config (`pipeline.storage.*`).
-- Already-loaded environment variables for configured S3 credentials.
-- Bucket-relative object keys and local file paths from app/stage orchestration.
+## Primary Contract
+`storage.ObjectStore` interface:
+- `List(ctx, prefix)`
+- `Download(ctx, key, localPath)`
+- `Upload(ctx, localPath, key, opts)`
+- `Exists(ctx, key)`
 
-Outputs:
-- Listed/downloaded/uploaded object metadata (`ObjectInfo`).
-- Existence checks and storage-layer errors.
+Key invariant:
+- callers pass full bucket-relative keys;
+- storage implementations do not infer campaign/session/run prefixes.
 
-## Boundaries
-Owns:
-- Remote object-store interface and implementation details.
-- S3 client wiring and API calls.
-- Object key normalization and upload/download/list primitives.
+## Configuration
+`NewObjectStoreFromConfig` currently supports S3-backed stores from `pipeline.storage.*` config.
 
-Does not own:
-- Session/run prefix semantics.
-- Archive commit order semantics.
-- Manifest updates.
-- Filesystem secret loading from `pipeline.secrets.env_dir`.
+S3 constructor behavior:
+- requires configured bucket;
+- uses region/endpoint/path-style options when set;
+- resolves credentials from configured env var names (with defaults).
 
-## Config fields used
-- `pipeline.storage.backend`
-- `pipeline.storage.s3.bucket`
-- `pipeline.storage.s3.region`
-- `pipeline.storage.s3.endpoint`
-- `pipeline.storage.s3.force_path_style`
-- `pipeline.storage.s3.access_key_id_env`
-- `pipeline.storage.s3.secret_access_key_env`
+## S3 Backend Behavior
+- normalizes object keys.
+- `List` paginates and returns normalized `ObjectInfo`.
+- `Download` writes local files with parent directory creation.
+- `Upload` streams local file and returns remote metadata.
+- `Exists` maps not-found responses to `false`.
 
-## External adapters used
-Storage package contracts:
-- `ObjectStore` (active remote object-store boundary): `List`, `Download`, `Upload`, `Exists`.
-- `Backend` (legacy compatibility boundary): currently implemented with `NoopBackend` only.
+## Legacy Compatibility Interface
+`storage.Backend` (with `ArchiveRequest`) remains as compatibility surface with `NoopBackend`; it is not used by current stage execution.
 
-Implementations:
-- `S3Backend`: AWS SDK-backed `ObjectStore` implementation.
-- `FakeBackend`: deterministic test `ObjectStore` and compatibility backend.
-- `NoopBackend`: deterministic no-op compatibility backend for wiring/tests.
-
-## State and manifest behavior
-- Storage implementations are stateless with respect to manifest/session lifecycle.
-- Caller supplies fully-qualified bucket-relative keys.
-- Storage layer does not infer campaign/session/run/root-prefix semantics.
-- Caller controls publish ordering; storage layer executes individual operations in the order invoked.
-
-## Skip and resume behavior
-- No storage-level skip/resume behavior.
-- Skip/resume decisions are made by stage/app logic before storage calls occur.
-
-## Failure behavior
-- `NewObjectStoreFromConfig` fails when no remote backend is configured or required S3 config is missing.
-- `S3Backend` constructor fails when required bucket is missing or AWS client setup fails.
-- App command orchestration loads configured filesystem secrets before calling the object-store factory.
-- CRUD operations return contextual errors (including not-found behavior via `Exists`).
-- Key normalization is applied before operations (`\\` to `/`, leading slash trimmed).
-- Remote session loading uses `List` to find the exact `session.yml` key and `Download` to materialize it to a local temp file.
-
-## Tests to inspect before changing
-- `internal/adapters/storage/factory_test.go`
-- `internal/adapters/storage/s3_backend_test.go`
-- `internal/adapters/storage/fake_test.go`
-- `internal/adapters/storage/keys_test.go`
-- `internal/adapters/storage/archive.go` + consumers in stage tests (`prepare`, `publish`)
-
-## Architectural invariants
-- Callers pass full bucket-relative keys.
-- Storage backends must not prepend or infer narratio prefixes.
-- Remote transport details remain isolated to storage adapter implementations.
+## Invariants
+- storage layer is stateless regarding manifest/stage progression.
+- publish ordering semantics are owned by stage/app code, not storage adapters.