suaveplan/openspec/archive/2026-05-12-drive-network-integration/proposal.md

OpenSpec Change: drive-network-integration

• Change ID: drive-network-integration
• Package: — (spec-only cross-cutting change)
• Status: PROPOSED
• Date: 2026-05-01

---

Summary

Clarify the architectural relationship between the drive ecosystem (drive-mesh, drive-plugin-chunks, drive-transport-*) and the network mesh ecosystem (network-plugin-content-delivery, network-plugin-registry, network-plugin-relay). This change does not create a new package; it updates existing proposals and the canonical spec to eliminate ambiguity about layering, duplicate peer registries, and responsibility boundaries.

---

Why

Current ambiguity:

1. drive-mesh-port proposes a PeerRegistry that tracks live peers, availability bitsets, and latency EMAs.
2. network-plugin-registry already maintains a fixed-capacity peer registry with binary encoding.
3. network-plugin-content-delivery proposes P2P chunk distribution with redundancy and prefetch.
4. drive-mesh-port proposes parallel chunk pull, peer scoring, and upload backpressure.

These two registries and two chunk-distribution layers could diverge or duplicate effort.

Required clarity:

• Which layer owns peer discovery and registry state?
• Which layer owns chunk redundancy and prefetch?
• How does drive-mesh consume network mesh events?

---

Layered architecture

┌─────────────────────────────────────────────────────────────┐
│  APPLICATION                                                │
│  fetchFile(fileId) → DriveMesh.fetchFile()                 │
├─────────────────────────────────────────────────────────────┤
│  DRIVE MESH LAYER      @suaveplan/drive-mesh               │
│  - Chunk scheduling (parallel pull, racing window)         │
│  - Peer scoring (latency, success rate, sig-verify)        │
│  - Upload backpressure                                     │
│  - Availability gossip (compressed bitsets per file)       │
│  Consumes: ChunkSource (drive-plugin-chunks)               │
│  Consumes: DriveTransport (drive-transport-webrtc/https)   │
│  Consumes: NetworkBus events from network-plugin-registry  │
├─────────────────────────────────────────────────────────────┤
│  NETWORK CONTENT DELIVERY   @suaveplan/network-plugin-     │
│  LAYER                      content-delivery               │
│  - Mesh-wide chunk redundancy (N copies)                   │
│  - Gossip index of chunk holders                           │
│  - Prefetch engine                                         │
│  - BLAKE3 integrity verification                           │
│  - Re-replication on peer departure                        │
├─────────────────────────────────────────────────────────────┤
│  NETWORK MESH ORCHESTRATION  @suaveplan/network + plugins  │
│  - Peer registry (network-plugin-registry)                 │
│  - Topology / tiers (network-plugin-topology)              │
│  - Transport manager (network-plugin-transport-manager)    │
│  - Relay / federation (network-plugin-relay)               │
│  - Governance / elections (network-plugin-governance)      │
├─────────────────────────────────────────────────────────────┤
│  STORAGE BACKENDS            @suaveplan/storage-*          │
└─────────────────────────────────────────────────────────────┘

Responsibility contract

Concern	Owner	Reason
Peer identity & lifecycle	network-plugin-registry	Single source of truth for all mesh peers
Peer availability for files	drive-mesh	File-specific bitsets don't belong in network registry
Chunk scheduling (which peer, racing window)	drive-mesh	Drive knows chunk boundaries and urgency
Chunk redundancy (how many copies, re-replication)	network-plugin-content-delivery	Mesh-wide policy, not file-system concern
Chunk integrity	network-plugin-content-delivery	BLAKE3 verification is a delivery concern
Chunk prefetch	network-plugin-content-delivery	Predictive loading based on mesh-wide access patterns
Wire transport	drive-transport-webrtc / drive-transport-https	Lowest layer, shared by both drive-mesh and content-delivery

Integration points

1. Drive-mesh consumes registry events

drive-mesh MUST NOT maintain a separate PeerRegistry for peer identity. Instead, it listens to network-plugin-registry events on the NetworkBus:

// In drive-mesh startup
bus.on("peer:joined", ({ peerId, tier, latency }) => {
  driveMesh.peerIndex.add(peerId, { tier, latency });
});
bus.on("peer:left", ({ peerId }) => {
  driveMesh.peerIndex.remove(peerId);
});

drive-mesh maintains an index (not a registry) that maps peerId → file availability bitsets. The peer identity comes from the network layer.

2. Content-delivery drives redundancy; drive-mesh drives fetch scheduling

network-plugin-content-delivery decides where chunks should be stored (redundancy policy). drive-mesh decides from where to fetch a chunk given the peers that have it (scheduling policy).

// Content-delivery pushes chunks to peers
cd.redundancyManager.ensureCopies(fileId, chunkId, n = 3);

// Drive-mesh pulls chunks from peers
driveMesh.scheduler.fetchChunk(fileId, chunkId, candidates);

3. Shared transport abstraction

Both drive-mesh and network-plugin-content-delivery use DriveTransport (or Transport) implementations. They share the same WebRTC data channels but use different message types:

• drive-mesh uses chunk:request / chunk:response
• network-plugin-content-delivery uses cd:advertise / cd:push

Proposed changes to existing proposals

Update drive-mesh-port/proposal.md

• Replace PeerRegistry with PeerIndex (clarify it's an index overlay, not a registry).
• Add "Registry consumption" section documenting NetworkBus event subscription.
• Add dependency on network-plugin-registry.

Update network-plugin-content-delivery/proposal.md

• Add explicit boundary: "This plugin does NOT schedule individual chunk fetches; that is drive-mesh."
• Add dependency on drive-mesh for fetch completion events.

Update network-suite/proposal.md

• Add drive-network-integration as a child change or reference.
• Update the "Drive integration" bullet to reference the layered architecture above.

---

Verification approach

• tests/cross-layer/dep-graph.test.ts — pins no import of drive-mesh from network-plugin-registry, and no import of network-plugin-registry from drive-mesh.
• tests/cross-layer/event-contract.test.ts — pins that peer:joined / peer:left events from network-plugin-registry have the shape drive-mesh expects.
• Update existing conformance tests in drive-mesh-port and network-plugin-content-delivery to reference this contract.

---

Out of scope

• New code packages — this is a spec/clarity change only.
• Implementation of the integration — handled by the respective package changes (drive-mesh-port, network-plugin-content-delivery).