suaveplan/openspec/specs/drive-network-integration/spec.md

Drive ⇄ Network Integration Boundary

Cross-cutting architectural contract clarifying responsibility boundaries between the drive ecosystem (@suaveplan/drive-mesh, @suaveplan/drive-plugin-chunks, @suaveplan/drive-transport-*, @suaveplan/drive-webrtc) and the network mesh ecosystem (@suaveplan/network-plugin-content-delivery, @suaveplan/network-plugin-registry, the broader @suaveplan/network family).

Requirements

Requirement: Single peer-identity source

@suaveplan/network-plugin-registry SHALL be the single source of truth for peer identity, capability advertisement, and connection lifecycle across the entire mesh. No other package MAY operate an independent peer registry.

@suaveplan/drive-mesh MAY keep a per-file availability index (peer → bitset of held chunks) but MUST NOT duplicate peer-identity state — it consumes identity from network-plugin-registry.

Requirement: Chunk-scheduling ownership

@suaveplan/drive-mesh SHALL own per-file chunk scheduling: which peer to fetch from, the racing-window strategy, parallel-pull concurrency, peer scoring derived from latency + success rate + signature verification outcomes. network-plugin-content-delivery MUST NOT make per-chunk fetch decisions.

Requirement: Chunk-redundancy ownership

@suaveplan/network-plugin-content-delivery SHALL own mesh-wide chunk redundancy: how many copies of each chunk exist across the mesh, when to re-replicate after peer departure, prefetch heuristics based on mesh-wide access patterns. drive-mesh MUST NOT manage redundancy policy.

Requirement: Integrity-verification placement

Cryptographic integrity (signature + hash verification) SHALL be performed at the layer that receives untrusted bytes:

• drive-plugin-chunks.verifyChunkSig on every chunk read from any source.
• drive-webrtc.ChunkIntegrityManager.verifySignature on every chunk received over a WebRTC data channel before the bytes are exposed to higher layers.
• network-plugin-content-delivery BLAKE3 integrity check on chunks it redistributes via mesh-wide replication.

A peer that ever delivers a chunk with an invalid signature MUST be added to the delivering layer's denylist (per-session or persistent, configurable); the denylist MUST be reported back to network-plugin-registry so other drive consumers benefit.

Requirement: Wire-transport ownership

@suaveplan/drive-transport-https, @suaveplan/drive-transport-webrtc, and any future drive-transport-* packages SHALL each implement a single DriveTransport interface contract (defined canonically in @suaveplan/drive-mesh) and SHALL be consumed by both drive-mesh and network-plugin-content-delivery without modification.

The 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>

Requirement: Event flow

@suaveplan/drive-mesh SHALL subscribe to the following NetworkBus events emitted by network-plugin-registry:

• peer:joined — admit peer into per-file availability index.
• peer:left — evict peer from per-file index, cancel in-flight chunk requests routed to that peer.
• peer:metric — update peer-scoring weights.

@suaveplan/drive-mesh SHALL emit the following events to NetworkBus for consumption by network-plugin-content-delivery:

• drive:chunk-served{peerId, fileId, chunkId, outcome} — observed delivery.
• drive:chunk-bad-sig{peerId, fileId, chunkId} — bad-signature detection.
• drive:peer-denied{peerId, reason} — denylist entry.

Requirement: No duplicate registries

It is a defect (caught by CI conformance test in openspec/specs/) for any PR to introduce a second PeerRegistry-shaped data structure outside @suaveplan/network-plugin-registry. Per-file availability indices and scoring state are NOT considered registries for this rule — they index over peer identity but do not own it.

Requirement: Documentation

The README of every drive-tier and network-tier package SHALL include a "Layering" section linking to this spec, so consumers understand which package they're standing in when reading the API surface.