suaveplan/docs/storage/README.md

Storage

The storage layer is a pluggable, content-agnostic key→bytes substrate. It is the lowest level of the file stack: it knows nothing about files, paths, chunks, encryption, or peers — it stores Uint8Array values addressed by string keys, and exposes a uniform capability matrix so the layer above it (@suaveplan/drive) can decide which optimisations are safe.

This folder is the architectural reference for the storage layer. It does not duplicate the OpenSpec capability spec — it explains it.

Documents in this folder

File	Purpose
architecture.md	The AbstractStorage contract, the capability matrix (partialReads/partialWrites/nativeStreams/atomicWrites/contentAddressable), setPartial semantics, and NamespacedStorage scoping.
backends.md	Every storage backend the platform supports or will support: MemoryStorage, S3, browser (IndexedDB/localStorage/OPFS), Node fs, SQLite, FAT/exFAT/ext4 via WASM, and the planned WebRTC/HTTPS chunk transports. Each entry lists capability values, runtime, and migration status.
implementation-status.md	What is actually shipped on genesis today vs what still lives on main (and what is brand-new).

One-paragraph summary

AbstractStorage is a Zod-validated, OTel-instrumented base class that defines get, set, setPartial, delete, has, clear, list, batch, createReadStream, createWriteStream, plus an explicit capabilities field. Every concrete backend extends AbstractStorage and overrides exactly the methods it can implement natively; the base class provides default fallbacks (most importantly a read-modify-write defaultSetPartial) so consumers can call any method on any backend without runtime probing. NamespacedStorage wraps another storage to give it a key prefix and inherits the inner backend's capabilities. Encryption, signing, integrity, manifests, paths, directories, and CoW versioning all live above this layer — the storage layer never sees a plaintext byte that doesn't belong to it.

What storage is not

• Not a filesystem. It has no concept of directories, .., cwd, mode bits, owners, mtime, or symlinks. The drive layer (above) builds those concepts on top.
• Not a database. No queries, joins, indexes, or relations. SQLite-backed storage uses SQLite as a blob store, not as a query engine.
• Not a transport. It does not push bytes to peers. The drive-mesh and drive-transport-* layers do that.
• Not encrypted by itself. Storage stores the bytes you give it, byte-for-byte. If you want encryption-at-rest, write ciphertext (the chunks plugin does this for you).

Reading order

If you are new to this stack, read in this order:

1. architecture.md — understand the contract.
2. backends.md — see what concrete substrates are available.
3. ../drive/architecture.md — see how the layer above consumes it.
4. ../drive-storage-network.md — see the whole composition.