# Drive

The **drive** layer is the file-level abstraction that sits on top of [storage](../storage/README.md). It turns "key→bytes" into "path→file" and adds the things real users expect from a drive: directories, stat, streams, plugins for chunking/encryption/integrity, partition-based sharing, and peer-to-peer transfer.

The genesis design is **n drives**, each parameterised by:

- one or more `AbstractStorage` backends (its substrate),
- a plugin chain (chunks, sharing, mesh, transports, custom middleware),
- an optional network identity (so the drive can both serve and consume chunks across the mesh).

Drives can talk to each other. A drive on a phone, a drive on a laptop, and a drive on a server can all hold the same logical file, agree on the same manifest, and serve chunks to whichever drive needs them — encrypted end-to-end, signed by the original writer, verified on every read.

## Documents in this folder

| File | Purpose |
| --- | --- |
| [`architecture.md`](./architecture.md) | The `Drive` class, the `DriveStorage` view, plugin lifecycle, capability fallbacks, and the genesis decision to keep drive a thin VFS core with everything else as plugins. |
| [`index-and-paths.md`](./index-and-paths.md) | The directory metadata index and the file→location index — the two indexes that turn opaque storage keys into a navigable filesystem. Why nested directories are stored as packed metadata objects, and how a path resolves to a chunk manifest. Includes the on-disk-shape comparison across backends. |
| [`plugins.md`](./plugins.md) | The plugin chain (`drive-plugin-chunks`, `drive-sharing`, `drive-mesh`, `drive-transport-https`, `drive-transport-webrtc`, custom). Hook ordering, middleware semantics, and what each plugin's responsibility actually is. |
| [`encryption.md`](./encryption.md) | On-the-fly encrypt/sign/decrypt/verify. The chunked AEAD pipeline, the manifest signature, and where keys come from. Why storage never sees plaintext. |
| [`mesh-and-sharing.md`](./mesh-and-sharing.md) | How drives find each other, share files, and replicate chunks. The boundary between `drive-mesh` (per-file scheduling) and `network-plugin-content-delivery` (mesh-wide redundancy). |
| [`mesh-protocol.md`](./mesh-protocol.md) | The wire-protocol spec for chunk requests, advertisements, and responses. Three request forms (whole / specific / bitset), bitpacker-compressed presence bitsets, response piggyback, trust model. |
| [`dehydrated-drives.md`](./dehydrated-drives.md) | Server-signed `DriveTemplate` — pre-configured folder structure with bytes arriving later from peers and CDN. Per-file policy flags (`autoDownload` / `meshAllowed` / `cdnAllowed`), CDN reversed-ID URL convention, retroactive key grants, lock-icon UX. |
| [`implementation-status.md`](./implementation-status.md) | What's shipped, what's pending, and the architectural decisions (`drive-port` over `enterprise-drive`, `enterprise-types-cross-cutting` archived, `drive-network-integration` boundary contract). |

> **System review:** [`../system-review.md`](../system-review.md) — 16 numbered findings (2 blockers, 9 majors, 5 minors) covering chunk request batching, dehydrated drives, CDN fallback, per-file policies, lock-icon UX, key distribution, retention, trust validation, and replay protection. Each finding cross-references the doc that resolves it.

## One-paragraph summary

`Drive` is a generic class parameterised by a storage map. It exposes `read`, `write`, `delete`, `stat`, `list`, `createReadStream`, `createWriteStream`, plus `usePlugin(plugin)` and `useMiddleware(mw)`. It owns its lifecycle (`initialize`, `dispose`) and tracks which storages it connected itself, so calling `dispose()` only closes what `Drive` opened. All file-level intelligence — splitting a file into chunks, signing them, encrypting them, finding them on peers, reassembling them — lives in plugins. The core knows nothing about chunks, signatures, or peers; it only knows how to walk a middleware chain on its way to and from `AbstractStorage`. This is what lets the same `Drive` class run on a server (with `S3` and `network-plugin-webrtc`), in a browser (with `OpfsStorage` and `drive-transport-webrtc`), or on disk (with `FileStorage` and no network at all).

## How n drives work

A drive is identified by a stable id (the public key it signs with, plus an instance discriminator). Two drives that share the same root partition (same partition key) are mirrors of each other; two drives that hold different partitions are siblings on the mesh. Every drive in a deployment can:

1. **Hold local data** — bytes live in its `AbstractStorage` backends.
2. **Serve to peers** — exposes its chunk inventory through `network-plugin-content-delivery`.
3. **Consume from peers** — when a chunk is missing locally, `drive-mesh` resolves it from the mesh.
4. **Reconcile** — the manifest is authoritative; conflicts in chunk content are detected by signature and discarded.

There is **no central drive**. There is sometimes a central server (which is just another drive with elevated authority — see [`../network/topology-and-failover.md`](../network/topology-and-failover.md)), but the whole stack works without it.

## Reading order

1. [`architecture.md`](./architecture.md) — what a `Drive` actually is.
2. [`index-and-paths.md`](./index-and-paths.md) — how paths become bytes.
3. [`plugins.md`](./plugins.md) — what each plugin does.
4. [`encryption.md`](./encryption.md) — the crypto pipeline.
5. [`mesh-and-sharing.md`](./mesh-and-sharing.md) — how drives find each other.
6. [`../drive-storage-network.md`](../drive-storage-network.md) — the whole composition.