# 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.