Initial Commit

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

@@ -0,0 +1,97 @@
+# 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.