first commit

docs/foundation/bitpacker/bitpacker-compressed/src/rle/rle.schema.md

@@ -0,0 +1,48 @@
+# RLE Compression Options Schema
+
+## Purpose
+
+Zod schema for the per-call `CompressionOptions` accepted by `compressRle` / `decompressRle`. The RLE codec is byte-only and exposes a single tuning knob (`level`) — this schema validates that knob at the boundary so untrusted input can be normalized before reaching the codec.
+
+## Features
+
+- `rleCompressionOptionsSchema` — strict, single optional field
+- `level` is a non-negative integer; the codec ignores values outside its supported range
+- `as unknown as z.ZodType<T>` cast for the EOPT mismatch
+
+## Usage: Basic Example
+
+```ts
+import { compressRle, rleCompressionOptionsSchema } from "@suaveplan/bitpacker-compressed";
+
+const opts = rleCompressionOptionsSchema.parse({ level: 1 });
+const compressed = compressRle(new Uint8Array([0, 0, 0, 0, 1, 2]), opts);
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+    compressRle,
+    decompressRle,
+    rleCompressionOptionsSchema,
+} from "@suaveplan/bitpacker-compressed";
+
+function safeRoundTrip(data: Uint8Array, rawOpts: unknown) {
+    const opts = rleCompressionOptionsSchema.parse(rawOpts);
+    const compressed = compressRle(data, opts);
+    const decompressed = decompressRle(compressed);
+    return decompressed;
+}
+```
+
+## API Reference
+
+### `rleCompressionOptionsSchema: z.ZodType<CompressionOptions>`
+
+Strict schema. `level` is an optional non-negative integer. Throws `ZodError` on negative or non-integer values, or on unknown keys.
+
+## Implementation Notes
+
+- **Why a one-field schema.** Even a single-field bundle benefits from boundary validation: a `{ level: "9" }` (string instead of number) would otherwise reach the codec and produce undefined behaviour. Refusing it at parse time keeps the codec's contract simple.
+- **Codec ignores out-of-range levels.** The schema enforces non-negative integer; the codec itself ignores values outside `[0, 9]`. The schema is the boundary; the codec is the implementation.