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