first commit

docs/foundation/flow/streams-chunk-queue/src/validator/chunk-verifier-validator.md

@@ -0,0 +1,89 @@
+# chunk-verifier-validator
+
+## Purpose
+
+Bridges the structural `ChunkVerifier` shape from `@suaveplan/packer`
+into the canonical `ChunkValidator` strategy. The packer's verifier
+returns a discriminated result (`{ ok: true, metadata }` or
+`{ ok: false, code, message }`); this adapter coerces the failure
+branch into the canonical `StreamsChunkQueueError(VALIDATION_FAILED)`
+with the packer's diagnostic preserved in `context.verifierCode`.
+
+## Features
+
+- Accepts any structurally compatible verifier (`ChunkVerifierLike`),
+  so adapter tests don't need a real packer instance.
+- Preserves the verifier's `code` + `message` inside the typed error's
+  `context` for downstream observability.
+- Returns the input bytes unchanged on success — `ChunkVerifier`
+  validates the wire frame but does not modify it.
+- Falls back to a sensible default `code`/`message` if the verifier
+  omits them, keeping the contract uniform.
+
+## Usage: Basic
+
+```ts
+import { ChunkVerifier } from "@suaveplan/packer";
+import { ChunkVerifierValidator } from "@suaveplan/streams-chunk-queue";
+
+const verifier = new ChunkVerifier(serverPubKey);
+const queue = new StreamingChunkQueue({
+    fileId: 1n,
+    totalChunks: 5n,
+    validator: new ChunkVerifierValidator(verifier),
+});
+```
+
+## Usage: Advanced
+
+```ts
+import type { ChunkVerifierLike } from "@suaveplan/streams-chunk-queue";
+
+const hsmVerifier: ChunkVerifierLike = {
+    verify(bytes) {
+        return hsmSignatureVerify(bytes)
+            ? { ok: true }
+            : { ok: false, code: "HSM.REJECTED", message: "HSM rejected" };
+    },
+};
+const validator = new ChunkVerifierValidator(hsmVerifier);
+```
+
+## API Reference
+
+### `ChunkVerifierLike`
+
+```ts
+interface ChunkVerifierLike {
+    verify(bytes: Uint8Array): {
+        ok: boolean;
+        code?: string;
+        message?: string;
+    };
+}
+```
+
+### `ChunkVerifierValidator`
+
+```ts
+new ChunkVerifierValidator(verifier: ChunkVerifierLike)
+```
+
+Implements `ChunkValidator`. On `ok: true` returns
+`{ data: <input bytes> }`. On `ok: false` rejects with
+`StreamsChunkQueueError(VALIDATION_FAILED)` whose
+`context.chunkId` is the offending chunk id and `context.verifierCode`
+carries the verifier's own code.
+
+## Implementation Notes
+
+The adapter does not mutate `data` because `ChunkVerifier.verify` only
+checks the bytes — it does not strip a header. If a future verifier
+returns transformed bytes, the adapter contract can be extended without
+breaking callers (the success branch already returns `{ data }`). The
+adapter is intentionally synchronous on the verifier side (the wrapper
+itself returns a `Promise` to satisfy the strategy interface), so a
+fast in-process verifier does not allocate an extra microtask. The
+structural typing of `ChunkVerifierLike` means hardware-backed
+verifiers, mock test verifiers, and the real packer class are all
+interchangeable.