suaveplan/docs/storage/implementation-status.md

Storage — Implementation Status

Source of truth: 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) — 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.