Add storage backends and safety checks

docs/internal/storage.md

@@ -0,0 +1,37 @@
+# Storage
+
+## Purpose
+
+`internal/storage` defines backend-rooted logical file access for core packages. Callers use slash-separated paths relative to a configured backend root.
+
+## Inputs and outputs
+
+The storage interface supports byte reads, stream reads, byte writes, stream writes, exact metadata lookup, traversal, destination emptiness checks, and guarded managed deletion.
+
+Entries report a logical path, type, and size when available. Entry types are `file`, `directory`, `symlink`, and `other`.
+
+## Boundaries
+
+Core packages should depend on `internal/storage`, not adapter packages. Adapter-specific path handling stays behind backend implementations.
+
+The local adapter lives in `internal/adapters/local`. The fake backend lives in `internal/storage/fake` for tests and is not registered for runtime use.
+
+## Paths
+
+Logical file paths must be non-empty, relative, clean, slash-separated, and must not contain `.` or `..` segments or backslashes. Prefix paths follow the same rules, except an empty prefix means the backend root.
+
+## Failure behavior
+
+Storage errors use typed categories such as not found, already exists, invalid path, conflict, permission, temporary, unsupported, and unknown. Callers should use helper predicates rather than matching error strings.
+
+## Deletion
+
+Backends expose guarded managed deletion only. `DeleteManagedBundle` may delete listed managed outputs plus `.distributor.json`; it does not provide broad recursive deletion.
+
+## Tests
+
+Before changing storage behavior, inspect tests under:
+
+- `internal/storage`
+- `internal/storage/fake`
+- `internal/adapters/local`