# 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`](./architecture.md) | The `AbstractStorage` contract, the capability matrix (`partialReads`/`partialWrites`/`nativeStreams`/`atomicWrites`/`contentAddressable`), `setPartial` semantics, and `NamespacedStorage` scoping. |
| [`backends.md`](./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`](./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`](./architecture.md) — understand the contract.
2. [`backends.md`](./backends.md) — see what concrete substrates are available.
3. [`../drive/architecture.md`](../drive/architecture.md) — see how the layer above consumes it.
4. [`../drive-storage-network.md`](../drive-storage-network.md) — see the whole composition.