suaveplan/openspec/archive/2026-05-12-drive-mesh-port/tasks.md

Tasks: drive-mesh-port

Blocked on: drive-plugin-chunks-port, at least one drive-transport-*-port.

1. Scaffold

• 1.1 packages/drive/drive-mesh/ with package.json (@suaveplan/drive-mesh@0.0.0), tsconfig.json, vitest.config.ts, README.md.
• 1.2 Workspace deps: @suaveplan/drive-plugin-chunks (interface only), @suaveplan/error, @suaveplan/types, @suaveplan/events, @suaveplan/streams, @opentelemetry/api, zod.

2. Types

• 2.1 src/types/mesh.types.ts — DriveMeshOptions, PeerInfo, PeerScore, ChunkRequest, SchedulerConfig, PeerPolicy.
• 2.2 src/types/transport.types.ts — DriveTransport interface (consumed by mesh, implemented by transport packages): requestChunk(peerId, fileId, chunkId): AsyncIterable<Uint8Array>, advertise(peerId, fileId, bitset), onAdvertisement(handler), peers(): Iterable<PeerInfo>.
• 2.3 src/error-codes.ts — defineCodes("MESH", [...]).

3. Peer registry

• 3.1 src/registry/peer-registry.ts — addPeer, removePeer, peersFor(fileId, chunkId), score updates.
• 3.2 src/registry/availability-index.ts — BitSet-per-file index, gzip wire encoding.

4. Scheduler

• 4.1 src/scheduler/scheduler.ts — concurrency cap, racing window, per-chunk timeout, server fallback.
• 4.2 src/scheduler/peer-score.ts — EMA latency, success/error rates, sig-fail = -∞.

5. Upload governor

• 5.1 src/upload/governor.ts — per-peer concurrency cap, datachannel buffer watermark.

6. Manifest bootstrap

• 6.1 src/bootstrap/fetch-manifest.ts — peer-first then server fallback, sig-verify gate.
• 6.2 src/bootstrap/fetch-file.ts — resolves manifest → diffs chunks → schedules missing.

7. DriveMesh class

• 7.1 src/mesh.ts — start, stop, fetchFile, fetchChunks, event emitter.
• 7.2 Lifecycle: opens transports on start, closes on stop; idempotent.

8. Spec

• 8.1 openspec/specs/drive-mesh/spec.md — MESH-01 … MESH-NN with **Verified by:** lines.

9. Conformance tests

• 9.1 src/scheduler/scheduler.spec-conformance.test.ts — racing window, parallel pull, server fallback (MESH-SCHED-01, -02, -03).
• 9.2 src/scheduler/peer-score.spec-conformance.test.ts — bad-sig blocks peer, score updates (MESH-SCORE-01, -02).
• 9.3 src/registry/availability-index.spec-conformance.test.ts — bitset advertise/receive, gzip round-trip (MESH-GOSSIP-01).
• 9.4 src/bootstrap/fetch-manifest.spec-conformance.test.ts — peer-first then fallback (MESH-BOOTSTRAP-01).
• 9.5 src/bootstrap/fetch-file.spec-conformance.test.ts — end-to-end happy path with fake transports (MESH-FETCH-FILE-01).
• 9.6 src/upload/governor.spec-conformance.test.ts — per-peer cap, watermark pause (MESH-UPLOAD-01).
• 9.7 src/error-codes.spec-conformance.test.ts — frozen registry (MESH-CODES-01).

10. Verify

• 10.1 bunx turbo lint typecheck test --filter=@suaveplan/drive-mesh green.
• 10.2 bunx turbo test:coverage --filter=@suaveplan/drive-mesh 100/100/100/100.
• 10.3 bun scripts/openspec-conformance.ts @suaveplan/drive-mesh PASS.