@suaveplan/drive-mesh-protocol - Wire protocol for chunk discovery, request, and delivery across the mesh. Three request forms (whole/specific/bitset), bitpacker-compressed presence bitsets, response presence piggyback, probabilistic trust model. Types + codecs + validators only — no runtime side effects.

Summary

Wire protocol for chunk discovery, request, and delivery across the mesh. Three envelope shapes (cd:request, cd:advertise, cd:response) with three request forms (whole / specific / bitset), bitpacker-compressed presence bitsets, response presence piggyback, and a probabilistic trust model. Types + codecs + selectors only — zero runtime side effects.

Documentation tree

advertise — Encodes and decodes cd:advertise envelope payloads — the gossip messages a peer emits to announce which chunks it cur…
bitset — Implements the wire-format bitset codec for the mesh protocol. Bitsets carry chunk presence (cd:advertise) and chunk-…
common — Internal helpers shared by the four envelope codec modules (request.ts, advertise.ts, response.ts, error.ts). C…
error — Encodes and decodes cd:error envelopes — the responder-to-requester error channel that carries a structured `ChunkErr…
request — Encodes and decodes cd:request envelope payloads for the chunk-request side of the mesh protocol. Owns the wire forma…
response — Encodes and decodes cd:response envelope payloads — the responder-side messages that carry chunk bytes back to a requ…
monotonic — Implements GenerationTracker, the receiver-side state machine that keeps the highest seen generation per `(peerId,…
throttle — Implements AdvertiseThrottle, the issuer-side rate limiter that caps outgoing cd:advertise envelopes at one per `(n…
schemas — (no submodules)
- envelope.schema — (no submodules)
select — (no submodules)
- form — (no submodules)
decay — Implements the probabilistic-skip decay logic (DMP-15) the request scheduler uses to decide whether to include a peer i…
sample — Implements the adaptive sample-verification rate (DMP-17). On every incoming cd:advertise, the protocol MAY request a…
score — Implements TrustMap, the per-(peerId, fileId) trust state container the request scheduler in drive-mesh uses to d…
error-codes — Frozen registry of error codes plus the error class for the @suaveplan/drive-mesh-protocol package. Every rejection p…

- [envelope.schema](./src/schemas/envelope.schema.md) — _(no submodules)_- [select](./src/select/form.md) — _(no submodules)_- [form](./src/select/form.md) — _(no submodules)_- [decay](./src/trust/decay.md) — Implements the probabilistic-skip decay logic (DMP-15) the request scheduler uses to decide whether to include a peer i…

sample — Implements the adaptive sample-verification rate (DMP-17). On every incoming cd:advertise, the protocol MAY request a…
score — Implements TrustMap, the per-(peerId, fileId) trust state container the request scheduler in drive-mesh uses to d…
error-codes — Frozen registry of error codes plus the error class for the @suaveplan/drive-mesh-protocol package. Every rejection p…
envelope.schema — (no submodules)- select — (no submodules)- form — (no submodules)- decay — Implements the probabilistic-skip decay logic (DMP-15) the request scheduler uses to decide whether to include a peer i…
sample — Implements the adaptive sample-verification rate (DMP-17). On every incoming cd:advertise, the protocol MAY request a…
score — Implements TrustMap, the per-(peerId, fileId) trust state container the request scheduler in drive-mesh uses to d…
error-codes — Frozen registry of error codes plus the error class for the @suaveplan/drive-mesh-protocol package. Every rejection p…
envelope.schema — (no submodules)- select — (no submodules)- form — (no submodules)- decay — Implements the probabilistic-skip decay logic (DMP-15) the request scheduler uses to decide whether to include a peer i…
sample — Implements the adaptive sample-verification rate (DMP-17). On every incoming cd:advertise, the protocol MAY request a…
score — Implements TrustMap, the per-(peerId, fileId) trust state container the request scheduler in drive-mesh uses to d…
error-codes — Frozen registry of error codes plus the error class for the @suaveplan/drive-mesh-protocol package. Every rejection p…
envelope.schema — (no submodules)- select — (no submodules) - form — (no submodules)- decay — Implements the probabilistic-skip decay logic (DMP-15) the request scheduler uses to decide whether to include a peer i…
sample — Implements the adaptive sample-verification rate (DMP-17). On every incoming cd:advertise, the protocol MAY request a…
score — Implements TrustMap, the per-(peerId, fileId) trust state container the request scheduler in drive-mesh uses to d…
error-codes — Frozen registry of error codes plus the error class for the @suaveplan/drive-mesh-protocol package. Every rejection p…

Install

bun add @suaveplan/drive-mesh-protocol

Quick start

import {
    DMP_CODES,
    DmpError,
    selectForm,
    selectWhole,
    type ChunkRequestEnvelope,
} from "@suaveplan/drive-mesh-protocol";

// Pick the most compact request form for a list of missing chunks.
const request = selectForm([0, 5, 17]);
// → { kind: 'specific', chunkIds: [0, 5, 17] }

// Or request everything the holder has.
const wholeRequest = selectWhole();
// → { kind: 'whole' }

// Errors carry stable codes from DMP_CODES.
try {
    selectForm([]);
} catch (err) {
    if (err instanceof DmpError && err.code === DMP_CODES.EMPTY_REQUEST) {
        console.error("use selectWhole() for empty-needed lists");
    }
}

Modules

src/error-codes.md — DMP_CODES registry and DmpError class.
src/select/form.md — selectForm, selectWhole, encodeBitset, decodeBitset, plus the SELECT_FORM_BITSET_THRESHOLD constant.
src/types/protocol.types.ts — wire envelope and payload shapes (ChunkRequest, ChunkRequestEnvelope, ChunkAdvertisePayload, ChunkResponsePayload, ChunkErrorPayload, TrustScore).

Subpath exports

@suaveplan/drive-mesh-protocol — full barrel.
@suaveplan/drive-mesh-protocol/types — wire types only (no runtime).
@suaveplan/drive-mesh-protocol/select — form-selection helpers and bitset codec.
@suaveplan/drive-mesh-protocol/errors — DMP_CODES, DmpError.

Spec reference

The wire protocol is canonical in the specification (DMP-01..DMP-22). The architectural reference is docs/drive/mesh-protocol.md.

Status

Skeleton — types, error registry, and form-selection helpers shipped. The full codec layer (bitpacker-network framing, schema validation, trust scoring) lands in subsequent commits.

8.5 KiB Raw Blame History