suaveplan/docs/drive/README.md

Drive

The drive layer is the file-level abstraction that sits on top of storage. 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	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	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	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	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	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	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	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	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 — 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), but the whole stack works without it.

Reading order

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