98 lines
4.2 KiB
Markdown
98 lines
4.2 KiB
Markdown
# 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.
|