suaveplan/openspec/specs/drive-mesh/spec.md

@suaveplan/drive-mesh — P2P Mesh Orchestration Capability

P2P mesh layer over @suaveplan/drive-plugin-chunks: peer registry, bitset gossip, parallel chunk pull (multi-peer racing window), peer scoring, server fallback (built-in ServerFallback HTTPS path — see "HTTPS chunk fetch via ServerFallback" below), and bad-signature denylist. Consumes a pluggable list of peer-to-peer DriveTransport implementations (currently WebRTC, via @suaveplan/drive-transport-webrtc) without importing @suaveplan/drive core directly.

Requirements

Requirement: Mesh orchestrator surface

The package SHALL expose a DriveMesh class with:

• start(signal?) — begin gossip + listen for chunk requests.
• stop(reason?) — drain in-flight, close transports. Idempotent.
• requestChunk(fileId, chunkId, signal?): Promise<Uint8Array> — fetch a chunk from the mesh, falling back to the server if configured.
• advertise(fileId, bitset) / unadvertise(fileId) — push our local availability through the gossip engine.
• peers(): Iterable<PeerInfo> — snapshot of the peer registry.
• registry — direct handle on the PeerRegistry for application glue.
• tickGossip() — manual tick (testable / configurable cadence).
• TypedEventEmitter for chunk:* / peer:* / gossip:* events.

Requirement: Server is root of trust

DriveMesh SHALL treat the configured serverPubKey as the only authority for chunk validity:

• Every chunk delivered by a peer MUST be passed through drive-plugin-chunks signature verification before being returned to the caller.
• A peer that delivers a chunk with an invalid signature MUST be added to the registry's denylist (per-session by default, persistent if configured).
• A bad-sig peer MUST emit peer:denied{peerId, reason: "bad-signature"} so upstream NetworkBus consumers can take action.

Scenario: Bad-sig peer evicted

• WHEN a peer delivers bytes whose signature fails verifyChunkSig(serverPubKey, …)
• THEN peerRegistry.recordBadSig(peerId) MUST be called and the peer MUST NOT be selected for subsequent chunk pulls.

Requirement: PeerRegistry overlay

PeerRegistry SHALL track per-peer state including availability bitsets per fileId, EMA latency (α=0.3), success / failure / bad-sig counts, and a composite score for rank(fileId, chunkId). The registry is an overlay that consumes peer-identity events from network-plugin-registry (per the drive-network-integration boundary spec); it MUST NOT duplicate peer- identity storage.

Requirement: Gossip engine

GossipEngine SHALL emit periodic outbound advertisements with compressed bitsets per fileId (using @suaveplan/drive-mesh-protocol framed-bitset helpers) and SHALL ingest inbound advertisements into the PeerRegistry.

Requirement: Parallel puller with racing window

ParallelPuller SHALL issue chunk requests to the top-K candidates (default 3) within a configurable racing window (default 250 ms), accept the first verified response, and abort the losers via a shared AbortController. maxParallelRequests SHALL cap global concurrency (default 8). Failed or timed-out attempts blacklist that peer for the specific chunkId only; bad-signature is the only failure that escalates to a registry-wide denylist.

Requirement: Server fallback

ServerFallback SHALL accept a { url, transport } config and execute equal-jitter exponential backoff retries when all peer attempts fail. Server-delivered chunks MUST still pass signature verification.

Scenario: All-peers-fail with no fallback

• WHEN every peer attempt fails AND no serverFallback is configured
• THEN requestChunk MUST reject with DriveMeshError(ALL_PEERS_FAILED).

Requirement: Wire transports as plugins

DriveMesh SHALL accept a list of DriveTransport implementations through its constructor and use them interchangeably. The structural DriveTransport interface MUST expose:

• requestChunk(peerId, fileId, chunkId, signal?): AsyncIterable<Uint8Array>
• advertise(peerId, fileId, bitset): Promise<void>
• onAdvertisement(handler): () => void
• peers(): Iterable<PeerInfo>
• dispose(): Promise<void>

@suaveplan/drive-transport-webrtc satisfies this interface. The HTTPS chunk-fetch path is NOT a DriveTransport plugin — see "HTTPS chunk fetch via ServerFallback" below.

Requirement: No network-plugin-registry import

DriveMesh MUST NOT import @suaveplan/network-plugin-registry directly. Applications glue peer:joined / peer:left from NetworkBus to mesh.registry.addOrUpdate / mesh.registry.forget. This enforces the layering decision recorded in openspec/specs/drive-network-integration/spec.md.

Requirement: Error registry

The package SHALL export DriveMeshError extends SuaveplanError<…> with 10 stable codes covering chunk unavailable, all-peers-fail, signature failure, transport failure, fallback failure, invalid bitset, peer-denied paths.

Requirement: AbortSignal threading

Every async surface (start, stop, requestChunk, advertise) SHALL accept an optional AbortSignal. Pre-aborted signals reject before any side effect. Mid-flight aborts cancel transport requests and racing attempts cleanly.

Requirement: Universal-tier-clean tests

Tests MUST NOT use vi.mock or vi.stubGlobal. The package SHALL ship real-implementation fixtures (in-memory Broker + FakeDriveTransport, real ed25519 keypairs via @suaveplan/crypto-curve, real buildSignedChunk from @suaveplan/drive-plugin-chunks, real encodeFramedBitset from @suaveplan/drive-mesh-protocol). All test imports come from @suaveplan/testing/runner.

Requirement: Coverage + gate

bunx turbo lint typecheck test:coverage --filter=@suaveplan/drive-mesh MUST be green and istanbul coverage MUST be 100% on every touched module (statements / branches / functions / lines) before any release.

ADDED Requirements

Requirement: HTTPS chunk fetch via ServerFallback

The HTTPS / server-fallback chunk-fetch path SHALL be served by the built-in ServerFallback module that ships inside @suaveplan/drive-mesh (./server-fallback/server-fallback) — NOT by a separate DriveTransport-shaped plugin package.

ServerFallback SHALL:

• Issue HTTPS GET to ${baseUrl}/${fileId}/${chunkId} via an injectable fetchFn (defaults to globalThis.fetch).
• Run every fetched chunk through verifyChunkSig(serverPubKey, …) from @suaveplan/drive-plugin-chunks before returning bytes to the scheduler — same root-of-trust contract as peer-served chunks.
• Apply equal-jitter exponential backoff with a caller-configurable maxRetries, backoffBaseMs, and backoffMaxMs.
• Thread an AbortSignal through every retry.
• Surface every failure as a DriveMeshError(FALLBACK_FAILED) with the underlying HTTP status / fetch error preserved in cause.

Bearer-token or other authentication SHALL be supplied by the consumer through the fetchFn closure (e.g. wrapping globalThis.fetch with an Authorization header) — no transport-level auth plumbing is added.

ServerFallback deliberately does NOT implement the DriveTransport interface. Advertisement / peer-discovery / receive semantics do not apply to a server-driven HTTPS fetch path; modelling HTTPS as a degraded DriveTransport (with no-op advertise, onAdvertisement, and a single synthetic peer) was rejected because it adds no consumer-facing capability beyond what ServerFallback already provides while doubling the surface the scheduler has to reason about.

Scenario: Bad-sig server chunk rejected

• WHEN ServerFallback.fetchChunk(fileId, chunkId) returns bytes whose signature fails verifyChunkSig(serverPubKey, …)
• THEN requestChunk MUST reject with DriveMeshError(FALLBACK_FAILED) and the chunk MUST NOT be cached.

Scenario: Auth wrapping happens in the consumer's fetchFn

• WHEN a consumer needs bearer-token authentication against the fallback endpoint
• THEN the consumer SHALL pass an authenticated fetchFn to ServerFallback (e.g. (url, init) => fetch(url, { ...init, headers: { ...init?.headers, Authorization: 'Bearer ...' } })) rather than registering a separate transport.

Requirement: No HTTPS DriveTransport plugin

There SHALL NOT be a parallel @suaveplan/drive-transport-https (or similar) package implementing the DriveTransport interface for the HTTPS path. The original drive-transport-https-port proposal was retired on 2026-05-12 because ServerFallback already provides every documented capability (HTTPS chunk fetch, signature verification, exponential backoff with jitter, injectable fetchFn for tests, AbortSignal threading) without inheriting the peer-shaped surface (advertise / onAdvertisement / peers) that would have to be no-ops on a unidirectional HTTPS link.