suaveplan/docs/drive/implementation-status.md

Drive — Implementation Status

Source of truth: STATUS.md, the canonical openspec/specs/drive/spec.md, and the in-flight changes under openspec/changes/.

Shipped on genesis

Package	Notes
@suaveplan/drive	Thin VFS core. Drive, DriveStorage, plugin chain, lifecycle, capability fallbacks. Spec-conformance for DRIVE-01..09.
@suaveplan/drive-plugin-chunks	Locked v0x0001 chunk format. Sparse-file + chunk-keys layouts. AEAD encrypt + Ed25519 sign + manifest. 12 spec-conformance tests.

Pending — to be ported from main

Package	Description
@suaveplan/drive-sharing	Partition-based access control + envelope encryption + grant/revoke/tokens.
@suaveplan/drive-react-sharing	React UI — <ShareDialog>, <PartitionBadge>, useSharing().
@suaveplan/drive-webrtc	Pre-packaged "browser drive" plugin: chunks + transport-webrtc + signalling, in one.

Planned — new on genesis

Package	Why it's new
@suaveplan/drive-mesh	Per-file chunk scheduling, peer scoring, bitset advertisement. The proposal is in openspec/changes/drive-mesh-port/.
@suaveplan/drive-transport-https	HTTPS chunk transport. GET /v1/chunks/<fileId>/<chunkId> with Range requests. Server fallback. Proposal in drive-transport-https-port.
@suaveplan/drive-transport-webrtc	WebRTC datachannel chunk transport. [uint32 BE frameLen][uint8 frameType][payload] framing. Proposal in drive-transport-webrtc-port.
@suaveplan/drive-plugin-cow	Copy-on-write versioning + snapshots. Re-proposed from the enterprise-drive monolith but as its own plugin.
@suaveplan/drive-plugin-dedup	Content-addressed dedup. Builds on ContentAddressedStorage.

The architectural conflict to resolve

Two competing proposals targeting the same package name:

Proposal	Stance	Status
enterprise-drive	Monolith — chunks/CoW/dedup/snapshots/transforms all in one fat package.	0% impl. 25 ADDED requirements. Conflicts with the migrated drive design.
drive-port	Split — drive is a thin VFS core, everything else is sibling packages.	The genesis-canonical design. Already implemented in the migrated @suaveplan/drive. Spec is DRIVE-01..09.

Recommendation: archive enterprise-drive. Re-propose CoW and snapshot from it as drive-plugin-cow (a sibling plugin, not part of drive core). Re-propose its useful spec deltas (Zod option schemas, OTel coverage, AbortSignal everywhere) as small additive changes against openspec/specs/drive/spec.md.

In-flight clarification changes (no code, all spec)

Change	What it resolves
drive-network-integration	The boundary between drive-mesh, network-plugin-registry, and network-plugin-content-delivery. Pure spec — no code, no spec-delta directory; resolves a 3-way ambiguity in one document.
enterprise-types-cross-cutting	Adds ChunkSource, ChunkRef, DrivePlugin, MiddlewareHandler to @suaveplan/types so plugins don't redeclare them. Mostly implemented; awaits archive.

Critical-path order

1. Land enterprise-types-cross-cutting (archive it). This is the unlock for everything below — drive-mesh, drive-transport-, drive-webrtc, network-plugin- all reference these types.
2. Resolve enterprise-drive vs drive-port (decide; archive the loser). The genesis recommendation is keep drive-port as canonical, archive enterprise-drive.
3. Land drive-network-integration (no-code spec change). Establishes the contract that lets steps 4–7 land independently.
4. Port storage-browser-opfs, storage-browser, storage-file (parallel work, all from main). Unblocks every browser/server drive scenario.
5. Implement drive-transport-https (proposal already written). Server-fallback transport — needed before drive-mesh ships, because mesh races mesh peers against the server fallback.
6. Implement drive-mesh (proposal already written). Per-file scheduling. Depends on chunks (shipped), transport-https (step 5), and the network registry (in network-suite).
7. Implement drive-transport-webrtc + port drive-webrtc. Browser-to-browser chunk transfer.
8. Port drive-sharing + drive-react-sharing. Access control on top.
9. Implement drive-plugin-cow and drive-plugin-dedup. Sugar; not on the critical path.

Steps 1–3 are zero-code. Step 4 is parallel three-way work. Steps 5–9 are sequential because each depends on the previous interface.

Test debt to inherit / avoid

The docs/old-network-planning/test-failures-analysis.md, test-isolation-fix-plan.md, and test-isolation-implementation-guide.md document a real test-isolation bug class on the main branch:

• Singleton transport registries that persist across tests (MemoryTransport._instances).
• Singleton timer controllers that share state.
• Real setTimeout in time-sensitive tests instead of FakeClock.
• Voting / partition handlers that retain history between tests.

The genesis testing rule (from CLAUDE.md): no mocks of internal services, real services only. And the test-infrastructure design (@suaveplan/testing-integration) explicitly enforces fixture lifecycle (parallel start, reverse stop, idempotent teardown). Drive tests follow the same rule: every drive test gets a fresh MemoryStorage, a fresh Drive instance, and a fresh NetworkNode if the test exercises the mesh. No shared state between tests.