Initial Commit

docs/storage/implementation-status.md

@@ -0,0 +1,49 @@
+# Storage — Implementation Status
+
+Source of truth: [`STATUS.md`](../../STATUS.md) (auto-generated from the suaveplan→genesis migration manifest) and the `packages/storage/` directory on the `genesis` branch.
+
+## Shipped on `genesis`
+
+| Package | Notes |
+| --- | --- |
+| `@suaveplan/storage` | `AbstractStorage`, `MemoryStorage`, `NamespacedStorage`, `StorageFactory`, four typed errors. Spec-conformance for `STORAGE-01..04`. |
+| `@suaveplan/storage-s3` | `S3` backend. Multipart upload via `@suaveplan/retry`, presigned URLs, OTel. Integration-tested against Garage. |
+
+## Pending — to be ported from `main` (`/mnt/s/web/suaveplan`)
+
+| Package | Description (from main `README.md`) |
+| --- | --- |
+| `@suaveplan/storage-browser` | Browser storage (IndexedDB, localStorage). |
+| `@suaveplan/storage-browser-opfs` | OPFS backend for `@suaveplan/storage`. |
+| `@suaveplan/storage-file` | Node.js filesystem storage. |
+
+These three are the **immediate** backlog: they unblock browser-side drives, server-side drives, and the OPFS drive that everyone wants. None of the three needs new design — port the existing implementation, retest against the canonical `STORAGE-01..04` conformance suite, and verify the capability flags are correct.
+
+## Planned — new on `genesis`
+
+| Package | Why it's new |
+| --- | --- |
+| `@suaveplan/storage-sqlite` | We have `@suaveplan/db-sqlite`; a thin `AbstractStorage` adapter on top is straight-line work and unlocks single-file backups for embedded/browser drives. |
+| `@suaveplan/storage-fat` | Wraps `fatfs-wasm` (preferred) or `fatfs` (Node-only). Enables removable-media export and embedded FS use cases. |
+| `@suaveplan/storage-content-addressed` | Wrapper backend that derives key from `BLAKE3(content)`. Substrate for drive-level dedup and the chunk pool that `network-plugin-content-delivery` consumes. |
+
+## Deferred
+
+| Package | Reason |
+| --- | --- |
+| `@suaveplan/storage-exfat` | `node-exfat` is parser-only. Wait for a real exFAT JS implementation. FAT covers most of the gap. |
+| `@suaveplan/storage-ext4` | `lwext4` needs (a) a Node/WASM binding (~2 weeks) and (b) GPL-vs-BSD license clearance on the extents/xattr modules. Defer until there is a use case that FAT cannot serve. |
+
+## Migration checklist (for each port)
+
+1. Copy source structure from `/mnt/s/web/suaveplan/packages/storage-*/` into `packages/storage/<pkg>/` on `genesis`. Do not pull in old transitive deps that have been replaced (`@suaveplan/error`, `@suaveplan/types`, `@suaveplan/streams` are already migrated; rewire imports).
+2. Subclass `AbstractStorage` from `@suaveplan/storage`. Reuse the canonical `STORAGE-01..04` conformance test from `packages/storage/storage/src/abstract/abstract.spec-conformance.test.ts` — point it at the new backend.
+3. Set `capabilities` honestly. If you can't do partial writes natively, leave `partialWrites=false` and let `defaultSetPartial` handle it.
+4. Add OTel: `meter.createCounter("storage.ops")`, `meter.createHistogram("storage.op.duration_ms")`, `meter.createHistogram("storage.value.bytes")`. The base class wires this up; you only need to call it.
+5. Add a `<pkg>` entry to `MANIFEST.md`, run `bun scripts/folder-reorg/generate-manifest.ts`.
+6. Pre-publish gate: `bunx turbo lint typecheck test:coverage --filter=@suaveplan/<pkg>` green at 100% coverage.
+
+## Cross-cutting work that unblocks storage
+
+- **`enterprise-types-cross-cutting`** ([proposal](../../openspec/changes/enterprise-types-cross-cutting/proposal.md)) — adds the canonical `StorageLike`, `ChunkSource`, `ChunkRef` interfaces to `@suaveplan/types`. Already implemented; awaits archive. **Block clearing this unlocks downstream packages from re-declaring the same types locally.**
+- **`storage-set-partial`** (already archived) — added `setPartial` to the abstract surface, including the `defaultSetPartial` RMW helper. This is what makes browser backends tolerable for chunk-based drives.