first commit

docs/networking/drive/drive-mesh-protocol/src/schemas/envelope.schema.md

@@ -0,0 +1,61 @@
+# envelope.schema
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Defines every Zod boundary schema the codec modules invoke before letting payload bytes touch protocol logic, plus the frozen numeric constants the spec pins (`MAX_CHUNKS_DEFAULT`, `MAX_CHUNKS_HARD_CAP`, `SAMPLE_RATE_HEALTHY`, `SAMPLE_RATE_SUSPECT`, `TRUST_SUSPECT_THRESHOLD`, `TRUST_MISS_RATE_FLOOR`, `TRUST_DECAY_SLOPE`, `ADVERTISE_THROTTLE_MS_DEFAULT`, `ADVERTISE_THROTTLE_MS_MAX`, `GENERATION_WRAP_THRESHOLD`, `SELECT_FORM_BITSET_THRESHOLD`). Centralising the schemas + constants keeps every codec / trust / generation module branchless against ad-hoc magic numbers.
+
+## Features
+
+- `FileIdSchema` — hex string, 1–128 chars (`[0-9a-f]+`).
+- `ChunkRequestSchema` — discriminated union (`whole` / `specific` / `bitset`).
+- `ChunkRequestPayloadSchema`, `ChunkAdvertisePayloadSchema`, `ChunkResponsePayloadSchema`, `ChunkErrorPayloadSchema`, `ChunkBytesSchema`, `ChunkRequestPrioritySchema`, `ChunkErrorCodeSchema`.
+- Numeric constants documented inline so monitoring dashboards can reference the same source-of-truth as the codec.
+
+## Usage: Basic Example
+
+```ts
+import {
+    ChunkRequestPayloadSchema,
+    MAX_CHUNKS_HARD_CAP,
+} from "@suaveplan/drive-mesh-protocol";
+
+const result = ChunkRequestPayloadSchema.safeParse(unknownInput);
+if (!result.success) throw new Error(result.error.message);
+const payload = result.data;
+console.log(MAX_CHUNKS_HARD_CAP); // 1024
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+    ChunkAdvertisePayloadSchema,
+    ChunkErrorCodeSchema,
+    SELECT_FORM_BITSET_THRESHOLD,
+    TRUST_SUSPECT_THRESHOLD,
+} from "@suaveplan/drive-mesh-protocol";
+
+function isSuspectScore(score: number): boolean {
+    return score < TRUST_SUSPECT_THRESHOLD;
+}
+
+function pickForm(needed: number[]) {
+    return needed.length <= SELECT_FORM_BITSET_THRESHOLD
+        ? "specific"
+        : "bitset";
+}
+
+const allErrorCodes = ChunkErrorCodeSchema.options;
+```
+
+## API Reference
+
+- Schemas: `FileIdSchema`, `ChunkRequestPrioritySchema`, `ChunkRequestSchema`, `ChunkRequestPayloadSchema`, `ChunkAdvertisePayloadSchema`, `ChunkBytesSchema`, `ChunkResponsePayloadSchema`, `ChunkErrorCodeSchema`, `ChunkErrorPayloadSchema`.
+- Numeric constants: `MAX_CHUNKS_DEFAULT` (64), `MAX_CHUNKS_HARD_CAP` (1024), `SELECT_FORM_BITSET_THRESHOLD` (64), `SAMPLE_RATE_HEALTHY` (100), `SAMPLE_RATE_SUSPECT` (10), `TRUST_SUSPECT_THRESHOLD` (0.95), `TRUST_MISS_RATE_FLOOR` (0.05), `TRUST_DECAY_SLOPE` (20), `ADVERTISE_THROTTLE_MS_DEFAULT` (1000), `ADVERTISE_THROTTLE_MS_MAX` (60000), `GENERATION_WRAP_THRESHOLD` (2³¹).
+
+## Implementation Notes
+
+The `chunkIds` array on `kind:'specific'` is intentionally permissive (no `.min(1)`) so the explicit DMP-03 / DMP-22 gates in the codec (which throw `DMP.EMPTY_REQUEST`) are reachable. The `maxChunks` check is lower-bound only at the schema layer; the upper-bound DMP-07 enforcement lives in the codec so the failure carries the spec-mandated `DMP.MAX_CHUNKS_EXCEEDED` code rather than a generic `DMP.ENVELOPE_MALFORMED`. `// schema: boundary-only` annotations on the priority enum suppress the conformance-script warning about consumer-facing schemas that aren't reflected internally.