first commit

docs/foundation/flow/streams/src/utils/stream/validate-integrity/validate-integrity.md

@@ -0,0 +1,77 @@
+# validateStreamIntegrity
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+`validateStreamIntegrity` walks a `ReadableStream<Uint8Array>` chunk by chunk
+and applies a caller-supplied predicate to each chunk. It returns `true` if
+every chunk satisfies the predicate and the stream closes cleanly, or `false`
+the first time the predicate rejects a chunk. On a rejection it cancels the
+underlying reader so upstream producers can release resources rather than
+continuing to fill a buffer that will be discarded.
+
+The function is the streams-package equivalent of "fold a boolean over the
+chunks". It is small but worth centralising because the short-circuit + reader
+cancel + lock-release dance is easy to get wrong, especially when combined
+with WHATWG Streams' lock semantics around early teardown.
+
+## Features
+
+- Short-circuits on first failure — does not consume the rest of the stream.
+- Cancels the underlying reader on failure to free upstream resources.
+- Always releases the reader lock via `finally`, even on validator throws.
+- Returns `true` for an empty stream (vacuous truth).
+- Synchronous predicate keeps the per-chunk cost minimal.
+
+## Usage: Basic Example
+
+```ts
+import { validateStreamIntegrity } from "@suaveplan/streams/utils/stream/validate-integrity/validate-integrity";
+
+const allEven = await validateStreamIntegrity(stream, (chunk) =>
+    chunk.every((b) => b % 2 === 0)
+);
+```
+
+## Usage: Advanced Example
+
+```ts
+import { validateStreamIntegrity } from "@suaveplan/streams/utils/stream/validate-integrity/validate-integrity";
+
+// Each frame: 4-byte big-endian length || N payload bytes || 1-byte checksum.
+// Verify checksum without buffering the whole stream.
+function checksummed(chunk: Uint8Array): boolean {
+    if (chunk.byteLength < 5) return false;
+    const dv = new DataView(chunk.buffer, chunk.byteOffset, chunk.byteLength);
+    const len = dv.getUint32(0);
+    if (chunk.byteLength !== 4 + len + 1) return false;
+    let sum = 0;
+    for (let i = 0; i < 4 + len; i++) sum = (sum + chunk[i]!) & 0xff;
+    return sum === chunk[chunk.byteLength - 1];
+}
+
+const ok = await validateStreamIntegrity(stream, checksummed);
+```
+
+## API Reference
+
+### `validateStreamIntegrity(stream, validate): Promise<boolean>`
+
+- **`stream: ReadableStream<Uint8Array>`** — source stream.
+- **`validate: (chunk: Uint8Array) => boolean`** — predicate run per chunk.
+- **Returns** — `Promise<boolean>` resolving to `true` if all chunks pass,
+  `false` on first failure.
+- **Throws** — rejects with whatever the underlying stream throws.
+
+## Implementation Notes
+
+- The reader is acquired via `getReader()` and released in `finally`. On the
+  failure path we additionally `await reader.cancel()` to ensure the upstream
+  source observes the cancellation before we resolve `false`.
+- The predicate is invoked exactly once per non-empty chunk; chunks of size 0
+  still trigger a call (a zero-byte chunk is observable in the WHATWG model
+  and a strict validator may want to reject it).
+- A predicate `throw` propagates as a rejection rather than a `false`; callers
+  who wish otherwise can wrap their predicate in a try/catch.