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