suaveplan/docs/drive/implementation-status.md

# Drive — Implementation Status

Source of truth: [`STATUS.md`](../../STATUS.md), the canonical [`openspec/specs/drive/spec.md`](../../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`](../../openspec/changes/enterprise-drive/proposal.md) | Monolith — chunks/CoW/dedup/snapshots/transforms all in one fat package. | 0% impl. 25 ADDED requirements. **Conflicts with the migrated drive design.** |
| [`drive-port`](../../openspec/changes/drive-port/proposal.md) | 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`](../../openspec/changes/drive-network-integration/proposal.md) | 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`](../../openspec/changes/enterprise-types-cross-cutting/proposal.md) | 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.