first commit

docs/foundation/flow/streams-chunk-queue/src/binary-protocol/encoder.md

@@ -0,0 +1,73 @@
+# binary-protocol / encoder
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Produces the chunk-request wire frame consumed by `@suaveplan/drive-mesh`,
+`drive-transport-https`, and any peer that needs to tell the sender which
+chunks of a file it is still missing. The frame is compact (12-byte
+header + bitmap) so even a 100k-chunk request stays under 13 kB, and it
+is fixed-layout so receivers can validate it without a schema.
+
+## Features
+
+- 8-byte big-endian `fileId` (u64).
+- 4-byte big-endian `totalChunks` (u32).
+- `⌈totalChunks / 8⌉` byte bitmap where bit `i` of byte `floor(i/8)` is
+  set iff chunk `i` is requested.
+- Zero-allocation hot path: a single `Uint8Array` of the exact size and
+  one DataView for the header.
+- Range checks raise `StreamsChunkQueueError` with the matching code
+  (`INVALID_CHUNK_ID` for fileId, `INVALID_TOTAL_CHUNKS` for
+  totalChunks).
+- Chunk ids outside `[0, totalChunks)` are silently dropped — the
+  encoder's contract is "request these chunks, capped by the file
+  size".
+
+## Usage: Basic
+
+```ts
+import { encodeChunkRequest } from "@suaveplan/streams-chunk-queue";
+
+const frame = encodeChunkRequest({
+    fileId: 12345n,
+    totalChunks: 10n,
+    chunkIds: [0n, 2n, 5n],
+});
+```
+
+## Usage: Advanced
+
+```ts
+const missing = queue.getMissingChunkIds();
+const frame = encodeChunkRequest({
+    fileId: queue.getStatus().fileId,
+    totalChunks: queue.getStatus().totalChunks,
+    chunkIds: missing,
+});
+await webrtcDc.send(frame);
+```
+
+## API Reference
+
+### `encodeChunkRequest({ fileId, totalChunks, chunkIds })` → `Uint8Array`
+
+Returns the encoded frame. Throws `StreamsChunkQueueError` when
+`fileId` is outside the u64 range or `totalChunks` is outside the u32
+range.
+
+### `CHUNK_REQUEST_HEADER_SIZE`
+
+Constant `12`. Exposed for callers that decode the frame.
+
+## Implementation Notes
+
+The encoder iterates over `chunkIds` (typically the missing set,
+bounded by realistic transfer sizes) instead of `[0, totalChunks)` so
+the hot path stays O(|chunkIds|) regardless of file size. The 8-byte
+big-endian `fileId` is written as two `setUint32` calls because
+`DataView` does not have a `setBigUint64` on every supported runtime
+target.