distillate 0.6.0 → 0.8.0

package/README.md

@@ -4,7 +4,7 @@
 [![npm](https://img.shields.io/npm/v/distillate)](https://www.npmjs.com/package/distillate)
 [![license](https://img.shields.io/npm/l/distillate)](./LICENSE)
 
-Probabilistic data structures for JavaScript: space-efficient, approximate answers with tunable error and zero false negatives. TypeScript-first, zero dependencies, and the right structure per workload. It opens with a family of membership filters (the next-generation successor to Bloom filter packages) and is built to grow into other sketches.
+Probabilistic data structures for JavaScript: space-efficient, approximate answers with tunable error and zero false negatives. TypeScript-first, zero dependencies, and the right structure per workload. It opens with a family of membership filters and is built to grow into other sketches.
 
 > **Pre-release (0.x).** The published structures are correct, tested, and benchmarked, but the public API may still change before `1.0`, and more structures (Cuckoo, Scalable Bloom) are on the way. Pin a version if you depend on it.
 
@@ -12,10 +12,12 @@ Probabilistic data structures for JavaScript: space-efficient, approximate answe
 
 An approximate-membership query (AMQ) filter answers "is this in the set?" with a tunable false-positive rate and **zero false negatives**, in a fraction of the space of storing the set itself.
 
-- **Runs anywhere**: Node, Bun, Deno, browsers, and Cloudflare/Vercel edge. No `eval`, no required WASM compile.
-- **Correct**: no false negatives (property-tested); false-positive rates validated against theory.
-- **Small**: per-structure subpath imports, `sideEffects: false`, zero runtime dependencies.
-- **Portable**: a versioned little-endian binary format (`toBytes` / `fromBytes`) for persistence and cross-language reads.
+- **Runs anywhere**: Node, Bun, Deno, browsers, Cloudflare/Vercel edge.
+- **Correct**: no false negatives, property-tested.
+- **Small**: per-structure subpath imports, zero runtime dependencies.
+- **Portable**: a versioned binary format (`toBytes` / `fromBytes`).
+
+Why these promises, and what the incumbents get wrong: [overview.md](./docs/overview.md).
 
 ## Install
 
@@ -40,11 +42,11 @@ Every push runs a CI smoke matrix that imports the built package on Node 22/24,
 
 Each structure ships as its own subpath, so you only bundle what you import.
 
-| Import               | Structure     | Mutable? | Use for                                              |
-| -------------------- | ------------- | -------- | ---------------------------------------------------- |
-| `distillate/bloom`   | Classic Bloom | yes      | Familiar default, migration from `bloom-filters`     |
-| `distillate/blocked` | Blocked Bloom | yes      | Faster lookups and a lower FPR for ~15% more space   |
-| `distillate/fuse`    | Binary Fuse   | no       | Static set built once and queried a lot; least space |
+| Import               | Structure     | Mutable? | Use for                                                  |
+| -------------------- | ------------- | -------- | -------------------------------------------------------- |
+| `distillate/bloom`   | Classic Bloom | yes      | Familiar default, migration from `bloom-filters`         |
+| `distillate/blocked` | Blocked Bloom | yes      | Faster lookups and a lower FPR for a small space premium |
+| `distillate/fuse`    | Binary Fuse   | no       | Static set built once and queried a lot; least space     |
 
 ### Classic Bloom (`distillate/bloom`)
 
@@ -72,11 +74,11 @@ filter.add("alice");
 filter.has("alice"); // true
 ```
 
-Same surface as Classic Bloom (`add` / `has` / `union` / `toBytes` / `fromBytes` / `bitsPerKey`). Confines every lookup to a single cache line, so it is consistently faster than Classic across sizes (measured on Apple M5: ~7% faster at 100k keys, widening to ~1.4x once the filter outgrows CPU cache at tens of millions), and its sizing gives a lower false-positive rate. The cost is ~15% more space. Reach for it when lookup throughput matters; prefer Classic when space is tight.
+Same surface as Classic Bloom (`add` / `has` / `union` / `toBytes` / `fromBytes` / `bitsPerKey`). Reach for it when lookup throughput matters; prefer Classic when space is tight. Cache-line rationale, speed ratios, and the space penalty: [Blocked Bloom guide](https://distillate.akxp.net/guides/blocked/).
 
 ### Binary Fuse (`distillate/fuse`)
 
-A **static** filter: built once from the full key set, then immutable. The most space-efficient option (~9 bits/key at ~0.39% FPR for 8-bit; ~19 bits/key at ~1/65536 for 16-bit), and it queries at ~11 M ops/s (Apple M5, 100k keys).
+A **static** filter: built once from the full key set, then immutable. The most space-efficient option in the lineup. Bits-per-key, FPR, and query throughput: [Binary Fuse guide](https://distillate.akxp.net/guides/fuse/).
 
 ```ts
 import { BinaryFuse8, BinaryFuse16 } from "distillate/fuse";
@@ -94,14 +96,14 @@ Also: `toBytes` / `fromBytes`. No `add` / `delete`; rebuild `from` the new set t
 
 ## Performance
 
-Classic Bloom head-to-head at a **matched 1% false-positive rate** over the same 100k keys, measured by identical code (Node, Apple M5):
+Classic Bloom head-to-head at a **matched 1% false-positive rate** over the same 100k keys, measured by identical code (cross-library harness, node v24.14.1, Apple M5):
 
 | Classic Bloom  | bits/key | measured FPR | `has` throughput |
 | -------------- | -------- | ------------ | ---------------- |
-| **distillate** | 9.59     | 1.03%        | ~21 M ops/s      |
+| **distillate** | 9.59     | 1.01%        | ~21.8 M ops/s    |
 | bloom-filters  | 9.59     | 0.99%        | ~0.29 M ops/s    |
 
-Same space, same accuracy, **~72x the lookup throughput** of [`bloom-filters`](https://www.npmjs.com/package/bloom-filters) (the package distillate replaces), while hashing UTF-8 bytes with MurmurHash3 so filters stay portable and cross-language readable.
+Same space, same accuracy, **~75x the lookup throughput** of [`bloom-filters`](https://www.npmjs.com/package/bloom-filters) (the package distillate replaces), while hashing UTF-8 bytes with MurmurHash3 so filters stay portable and cross-language readable.
 
 These are a point-in-time snapshot on one machine. The full report (blocked/fuse, 1M capacity, the `bloomfilter` micro-package) and exactly how it is measured live in the [`apps/bench`](https://github.com/akshay-xp/distillate/tree/main/apps/bench) workspace: [RESULTS.md](https://github.com/akshay-xp/distillate/blob/main/apps/bench/RESULTS.md), [METHODOLOGY.md](https://github.com/akshay-xp/distillate/blob/main/apps/bench/METHODOLOGY.md).
 
@@ -110,10 +112,11 @@ These are a point-in-time snapshot on one machine. The full report (blocked/fuse
 Design notes, the structure decision matrix, hashing, and the binary format live in [`docs/`](./docs):
 
 - [overview](./docs/overview.md): what and why
-- [structures](./docs/structures.md): decision matrix and the full lineup
-- [architecture](./docs/architecture.md), [hashing](./docs/hashing.md), [serialization](./docs/serialization.md)
-- [versioning](./docs/versioning.md): SemVer policy and supported-runtime baseline
-- [API reference](./docs/api): generated from TSDoc (per entry point)
+- [choosing a structure](https://distillate.akxp.net/guides/choosing-a-structure/): decision matrix and the full lineup
+- [serialization](https://distillate.akxp.net/reference/serialization/): the binary format spec
+- [versioning](https://distillate.akxp.net/reference/versioning/): SemVer policy and supported-runtime baseline
+- [architecture](./docs/architecture.md), [hashing](./docs/hashing.md): contributor notes, on GitHub
+- [API reference](https://distillate.akxp.net/api/readme/): generated from TSDoc at site build time (per entry point)
 
 ## License
 

package/dist/blocked/index.cjs

@@ -1,20 +1,13 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_serialize = require("../serialize-BIIKUHH6.cjs");
-const require_params = require("../params--8CNXYWu.cjs");
+const require_serialize = require("../serialize-CXnRWItH.cjs");
+const require_params = require("../params-UTZbJ22c.cjs");
 //#region src/blocked/blocked.ts
 const TYPE = 2;
 const SALT = Uint32Array.of(1203114875, 1150766481, 2284105051, 2729912477, 1884591559, 770785867, 2667333959, 1550580529);
-const scratch2 = /* @__PURE__ */ new Uint32Array(2);
+const scratch2 = new Uint32Array(2);
 const BLOCK_BITS = 256;
 const LANE_BITS = 32;
 const LANES = 8;
-/**
-* Modeled false-positive rate of a split-block filter at `bitsPerKey`. A block
-* holding `j` keys has FPR `(1 - (1 - 1/32)^j)^8` (8 lanes of 32 bits, one probe
-* each); the filter's rate averages that over the Poisson block load
-* `lambda = 256 / bitsPerKey`. This clustering average is why the blocked curve
-* is not linear in `log10(1/epsilon)`.
-*/
 function blockedFprAt(bitsPerKey) {
 	const lambda = BLOCK_BITS / bitsPerKey;
 	let fpr = 0;
@@ -27,46 +20,20 @@ function blockedFprAt(bitsPerKey) {
 	return fpr;
 }
 const MAX_BITS_PER_KEY = 128;
-/**
-* Minimal integer bits-per-key whose modeled split-block FPR is at or below
-* `epsilon`. Throws {@link ParamError} when even the densest supported filter
-* cannot reach the target, so callers get a typed rejection instead of a
-* silently under-provisioned filter.
-*/
 function blockedBitsPerKey(epsilon) {
 	for (let bpk = 1; bpk <= MAX_BITS_PER_KEY; bpk++) if (blockedFprAt(bpk) <= epsilon) return bpk;
 	throw new require_params.ParamError(`epsilon ${String(epsilon)} is below the blocked-filter floor; use a classic or fuse filter`);
 }
-/** Thrown when an operation requires two filters built with identical parameters. */
 var BlockedBloomParamMismatchError = class extends Error {
-	/** Discriminates this error from other `Error`s. */
 	name = "BlockedBloomParamMismatchError";
 };
-/**
-* A blocked (split-block) Bloom filter: confines every lookup to a single cache
-* line, trading ~15% more space for higher lookup throughput and a lower FPR.
-*
-* @example
-* ```ts
-* const filter = BlockedBloomFilter.create(100_000, 0.01);
-* filter.add("alice");
-* filter.has("alice"); // true
-* ```
-*/
 var BlockedBloomFilter = class BlockedBloomFilter {
 	#lanes;
 	#numBlocks;
 	#seed;
 	#n;
-	#words = /* @__PURE__ */ new Uint32Array(8);
-	#bits = /* @__PURE__ */ new Uint32Array(8);
-	/**
-	* Creates a filter sized for `n` expected keys at a target false-positive rate.
-	*
-	* @param n - Expected number of keys.
-	* @param epsilon - Target false-positive rate, e.g. `0.01` for 1%.
-	* @returns A new, empty filter.
-	*/
+	#words = new Uint32Array(8);
+	#bits = new Uint32Array(8);
 	static create(n, epsilon) {
 		require_params.assertPositiveInt(n, "n");
 		require_params.assertProbability(epsilon, "epsilon");
@@ -75,26 +42,12 @@ var BlockedBloomFilter = class BlockedBloomFilter {
 			capacity: n
 		});
 	}
-	/**
-	* Builds a filter from `keys`, sized for their count at the target
-	* false-positive rate. The ergonomic entry point when the key set is already
-	* in hand; use {@link BlockedBloomFilter.create} to size for a count known
-	* ahead.
-	*
-	* @param keys - The keys to insert.
-	* @param epsilon - Target false-positive rate, e.g. `0.01` for 1%.
-	* @returns A new filter containing every key.
-	*/
 	static from(keys, epsilon) {
 		const arr = [...keys];
 		const f = BlockedBloomFilter.create(Math.max(1, arr.length), epsilon);
 		for (const k of arr) f.add(k);
 		return f;
 	}
-	/**
-	* Constructs a filter from low-level {@link BlockedBloomParams}. Prefer
-	* {@link BlockedBloomFilter.create} unless restoring a specific configuration.
-	*/
 	constructor({ bitsPerKey, capacity, seed = 0 }) {
 		require_params.assertPositiveFinite(bitsPerKey, "bitsPerKey");
 		require_params.assertPositiveInt(capacity, "capacity");
@@ -114,19 +67,15 @@ var BlockedBloomFilter = class BlockedBloomFilter {
 		f.#n = n;
 		return f;
 	}
-	/** Actual bits allocated per key (`total bits / capacity`). */
 	get bitsPerKey() {
 		return this.#numBlocks * 256 / this.#n;
 	}
-	/** Number of 256-bit blocks; one of the two fields `union` requires to match. */
 	get numBlocks() {
 		return this.#numBlocks;
 	}
-	/** Hash seed; the other field `union` requires to match. */
 	get seed() {
 		return this.#seed;
 	}
-	/** Number of bits currently set across all lanes. */
 	get length() {
 		let bits = 0;
 		for (let w of this.#lanes) while (w) {
@@ -135,23 +84,9 @@ var BlockedBloomFilter = class BlockedBloomFilter {
 		}
 		return bits;
 	}
-	/**
-	* Estimates the current false-positive rate from the actual fill,
-	* `(length / totalBits) ** 8`. A split-block query checks exactly 8 lane-bits,
-	* so the exponent is 8 rather than a classic probe count `k`. This reflects
-	* how full the filter is right now, not the design target.
-	*
-	* @returns The estimated false-positive rate, `0` for an empty filter.
-	*/
 	rate() {
 		return (this.length / (this.#numBlocks * 256)) ** 8;
 	}
-	/**
-	* Restores a filter from its {@link BlockedBloomFilter.toBytes} serialization.
-	*
-	* @param bytes - The serialized filter.
-	* @returns The reconstructed filter.
-	*/
 	static fromBytes(bytes) {
 		const { type, flags, body } = require_serialize.readHeader(bytes);
 		if (type !== TYPE) throw new require_serialize.SerializationError(`expected AMQF type ${String(TYPE)}, got ${String(type)}`);
@@ -167,11 +102,6 @@ var BlockedBloomFilter = class BlockedBloomFilter {
 		new Uint8Array(f.#lanes.buffer).set(body.subarray(12));
 		return f;
 	}
-	/**
-	* Serializes the filter to a portable little-endian byte layout.
-	*
-	* @returns The serialized filter, readable by {@link BlockedBloomFilter.fromBytes}.
-	*/
 	toBytes() {
 		const lanes = new Uint8Array(this.#lanes.buffer, this.#lanes.byteOffset, this.#lanes.byteLength);
 		return require_serialize.writeFrame({
@@ -185,52 +115,21 @@ var BlockedBloomFilter = class BlockedBloomFilter {
 			body.set(lanes, 12);
 		});
 	}
-	/**
-	* Tests structural equality: `true` when `other` serializes to identical
-	* bytes, meaning identical parameters and set bits.
-	*
-	* @param other - The filter to compare against.
-	* @returns `true` if the two filters are byte-for-byte identical.
-	*/
 	equals(other) {
 		return require_serialize.bytesEqual(this.toBytes(), other.toBytes());
 	}
-	/**
-	* Serializes the filter to a JSON-friendly envelope wrapping the base64 of
-	* {@link BlockedBloomFilter.toBytes}.
-	*
-	* @returns The envelope, readable by {@link BlockedBloomFilter.fromJSON}.
-	*/
 	toJSON() {
 		return require_serialize.toJSONEnvelope(this.toBytes());
 	}
-	/**
-	* Restores a filter from its {@link BlockedBloomFilter.toJSON} envelope.
-	*
-	* @param value - The JSON envelope.
-	* @returns The reconstructed filter.
-	*/
 	static fromJSON(value) {
 		return BlockedBloomFilter.fromBytes(require_serialize.fromJSONEnvelope(value));
 	}
-	/**
-	* Returns a new filter containing the union of this filter and `other`.
-	*
-	* @param other - A filter built with identical parameters.
-	* @returns A new filter reporting membership for keys in either input.
-	* @throws {@link BlockedBloomParamMismatchError} if the parameters differ.
-	*/
 	union(other) {
 		if (this.#numBlocks !== other.#numBlocks || this.#seed !== other.#seed) throw new BlockedBloomParamMismatchError("cannot union blocked Bloom filters whose parameters do not match");
 		const r = BlockedBloomFilter.#fromNumBlocks(this.#numBlocks, this.#seed, this.#n);
 		for (let i = 0; i < this.#lanes.length; i++) r.#lanes[i] = (this.#lanes[i] ?? 0) | (other.#lanes[i] ?? 0);
 		return r;
 	}
-	/**
-	* Adds a key to the set.
-	*
-	* @param key - The key to insert, as a string or bytes.
-	*/
 	add(key) {
 		fillBlock(key, this.#numBlocks, this.#seed, this.#words, this.#bits);
 		for (let i = 0; i < 8; i++) {
@@ -238,12 +137,6 @@ var BlockedBloomFilter = class BlockedBloomFilter {
 			this.#lanes[w] = (this.#lanes[w] ?? 0) | (this.#bits[i] ?? 0);
 		}
 	}
-	/**
-	* Tests whether a key is in the set.
-	*
-	* @param key - The key to test.
-	* @returns `true` if present (possibly a false positive); `false` guarantees absence.
-	*/
 	has(key) {
 		fillBlock(key, this.#numBlocks, this.#seed, this.#words, this.#bits);
 		for (let i = 0; i < 8; i++) {
@@ -264,6 +157,14 @@ function fillBlock(key, numBlocks, seed, outWords, outBits) {
 	}
 }
 //#endregion
+exports.BadMagicError = require_serialize.BadMagicError;
 exports.BlockedBloomFilter = BlockedBloomFilter;
 exports.BlockedBloomParamMismatchError = BlockedBloomParamMismatchError;
+exports.ChecksumError = require_serialize.ChecksumError;
 exports.ParamError = require_params.ParamError;
+exports.SerializationError = require_serialize.SerializationError;
+exports.TruncatedError = require_serialize.TruncatedError;
+exports.UnknownHashVariantError = require_serialize.UnknownHashVariantError;
+exports.UnknownVersionError = require_serialize.UnknownVersionError;
+exports.blockedBitsPerKey = blockedBitsPerKey;
+exports.blockedFprAt = blockedFprAt;

package/dist/blocked/index.d.cts

@@ -1,6 +1,21 @@
-import { n as BytesLike, t as FilterJSON } from "../serialize-DRKh6QOr.cjs";
+import { a as TruncatedError, c as BytesLike, i as SerializationError, n as ChecksumError, o as UnknownHashVariantError, r as FilterJSON, s as UnknownVersionError, t as BadMagicError } from "../serialize-ChyWpB9F.cjs";
 import { t as ParamError } from "../params-DnqJBqLS.cjs";
 //#region src/blocked/blocked.d.ts
+/**
+ * Modeled false-positive rate of a split-block filter at `bitsPerKey`. A block
+ * holding `j` keys has FPR `(1 - (1 - 1/32)^j)^8` (8 lanes of 32 bits, one probe
+ * each); the filter's rate averages that over the Poisson block load
+ * `lambda = 256 / bitsPerKey`. This clustering average is why the blocked curve
+ * is not linear in `log10(1/epsilon)`.
+ */
+declare function blockedFprAt(bitsPerKey: number): number;
+/**
+ * Minimal integer bits-per-key whose modeled split-block FPR is at or below
+ * `epsilon`. Throws {@link ParamError} when even the densest supported filter
+ * cannot reach the target, so callers get a typed rejection instead of a
+ * silently under-provisioned filter.
+ */
+declare function blockedBitsPerKey(epsilon: number): number;
 /** Thrown when an operation requires two filters built with identical parameters. */
 declare class BlockedBloomParamMismatchError extends Error {
   /** Discriminates this error from other `Error`s. */
@@ -127,4 +142,4 @@ declare class BlockedBloomFilter {
   has(key: BytesLike): boolean;
 }
 //#endregion
-export { BlockedBloomFilter, BlockedBloomParamMismatchError, type BlockedBloomParams, type FilterJSON, ParamError };
+export { BadMagicError, BlockedBloomFilter, BlockedBloomParamMismatchError, type BlockedBloomParams, ChecksumError, type FilterJSON, ParamError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError, blockedBitsPerKey, blockedFprAt };

package/dist/blocked/index.d.ts

@@ -1,6 +1,21 @@
-import { n as BytesLike, t as FilterJSON } from "../serialize-DRKh6QOr.js";
+import { a as TruncatedError, c as BytesLike, i as SerializationError, n as ChecksumError, o as UnknownHashVariantError, r as FilterJSON, s as UnknownVersionError, t as BadMagicError } from "../serialize-ChyWpB9F.js";
 import { t as ParamError } from "../params-DnqJBqLS.js";
 //#region src/blocked/blocked.d.ts
+/**
+ * Modeled false-positive rate of a split-block filter at `bitsPerKey`. A block
+ * holding `j` keys has FPR `(1 - (1 - 1/32)^j)^8` (8 lanes of 32 bits, one probe
+ * each); the filter's rate averages that over the Poisson block load
+ * `lambda = 256 / bitsPerKey`. This clustering average is why the blocked curve
+ * is not linear in `log10(1/epsilon)`.
+ */
+declare function blockedFprAt(bitsPerKey: number): number;
+/**
+ * Minimal integer bits-per-key whose modeled split-block FPR is at or below
+ * `epsilon`. Throws {@link ParamError} when even the densest supported filter
+ * cannot reach the target, so callers get a typed rejection instead of a
+ * silently under-provisioned filter.
+ */
+declare function blockedBitsPerKey(epsilon: number): number;
 /** Thrown when an operation requires two filters built with identical parameters. */
 declare class BlockedBloomParamMismatchError extends Error {
   /** Discriminates this error from other `Error`s. */
@@ -127,4 +142,4 @@ declare class BlockedBloomFilter {
   has(key: BytesLike): boolean;
 }
 //#endregion
-export { BlockedBloomFilter, BlockedBloomParamMismatchError, type BlockedBloomParams, type FilterJSON, ParamError };
+export { BadMagicError, BlockedBloomFilter, BlockedBloomParamMismatchError, type BlockedBloomParams, ChecksumError, type FilterJSON, ParamError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError, blockedBitsPerKey, blockedFprAt };

package/dist/blocked/index.js

@@ -1,19 +1,12 @@
-import { _ as reduce, a as bytesEqual, c as toJSONEnvelope, i as assertMinBodyLength, l as writeFrame, m as hash32x2Into, n as UnknownHashVariantError, o as fromJSONEnvelope, r as assertBodyLength, s as readHeader, t as SerializationError } from "../serialize-BnwtzcMw.js";
-import { i as assertProbability, n as assertPositiveFinite, o as assertUint32, r as assertPositiveInt, t as ParamError } from "../params-BrWuBC2A.js";
+import { a as UnknownHashVariantError, c as assertMinBodyLength, d as readHeader, f as toJSONEnvelope, i as TruncatedError, l as bytesEqual, n as ChecksumError, o as UnknownVersionError, p as writeFrame, r as SerializationError, s as assertBodyLength, t as BadMagicError, u as fromJSONEnvelope, v as hash32x2Into, x as reduce } from "../serialize-BqIcsR2J.js";
+import { i as assertProbability, n as assertPositiveFinite, o as assertUint32, r as assertPositiveInt, t as ParamError } from "../params-CeajSrwv.js";
 //#region src/blocked/blocked.ts
 const TYPE = 2;
 const SALT = Uint32Array.of(1203114875, 1150766481, 2284105051, 2729912477, 1884591559, 770785867, 2667333959, 1550580529);
-const scratch2 = /* @__PURE__ */ new Uint32Array(2);
+const scratch2 = new Uint32Array(2);
 const BLOCK_BITS = 256;
 const LANE_BITS = 32;
 const LANES = 8;
-/**
-* Modeled false-positive rate of a split-block filter at `bitsPerKey`. A block
-* holding `j` keys has FPR `(1 - (1 - 1/32)^j)^8` (8 lanes of 32 bits, one probe
-* each); the filter's rate averages that over the Poisson block load
-* `lambda = 256 / bitsPerKey`. This clustering average is why the blocked curve
-* is not linear in `log10(1/epsilon)`.
-*/
 function blockedFprAt(bitsPerKey) {
 	const lambda = BLOCK_BITS / bitsPerKey;
 	let fpr = 0;
@@ -26,46 +19,20 @@ function blockedFprAt(bitsPerKey) {
 	return fpr;
 }
 const MAX_BITS_PER_KEY = 128;
-/**
-* Minimal integer bits-per-key whose modeled split-block FPR is at or below
-* `epsilon`. Throws {@link ParamError} when even the densest supported filter
-* cannot reach the target, so callers get a typed rejection instead of a
-* silently under-provisioned filter.
-*/
 function blockedBitsPerKey(epsilon) {
 	for (let bpk = 1; bpk <= MAX_BITS_PER_KEY; bpk++) if (blockedFprAt(bpk) <= epsilon) return bpk;
 	throw new ParamError(`epsilon ${String(epsilon)} is below the blocked-filter floor; use a classic or fuse filter`);
 }
-/** Thrown when an operation requires two filters built with identical parameters. */
 var BlockedBloomParamMismatchError = class extends Error {
-	/** Discriminates this error from other `Error`s. */
 	name = "BlockedBloomParamMismatchError";
 };
-/**
-* A blocked (split-block) Bloom filter: confines every lookup to a single cache
-* line, trading ~15% more space for higher lookup throughput and a lower FPR.
-*
-* @example
-* ```ts
-* const filter = BlockedBloomFilter.create(100_000, 0.01);
-* filter.add("alice");
-* filter.has("alice"); // true
-* ```
-*/
 var BlockedBloomFilter = class BlockedBloomFilter {
 	#lanes;
 	#numBlocks;
 	#seed;
 	#n;
-	#words = /* @__PURE__ */ new Uint32Array(8);
-	#bits = /* @__PURE__ */ new Uint32Array(8);
-	/**
-	* Creates a filter sized for `n` expected keys at a target false-positive rate.
-	*
-	* @param n - Expected number of keys.
-	* @param epsilon - Target false-positive rate, e.g. `0.01` for 1%.
-	* @returns A new, empty filter.
-	*/
+	#words = new Uint32Array(8);
+	#bits = new Uint32Array(8);
 	static create(n, epsilon) {
 		assertPositiveInt(n, "n");
 		assertProbability(epsilon, "epsilon");
@@ -74,26 +41,12 @@ var BlockedBloomFilter = class BlockedBloomFilter {
 			capacity: n
 		});
 	}
-	/**
-	* Builds a filter from `keys`, sized for their count at the target
-	* false-positive rate. The ergonomic entry point when the key set is already
-	* in hand; use {@link BlockedBloomFilter.create} to size for a count known
-	* ahead.
-	*
-	* @param keys - The keys to insert.
-	* @param epsilon - Target false-positive rate, e.g. `0.01` for 1%.
-	* @returns A new filter containing every key.
-	*/
 	static from(keys, epsilon) {
 		const arr = [...keys];
 		const f = BlockedBloomFilter.create(Math.max(1, arr.length), epsilon);
 		for (const k of arr) f.add(k);
 		return f;
 	}
-	/**
-	* Constructs a filter from low-level {@link BlockedBloomParams}. Prefer
-	* {@link BlockedBloomFilter.create} unless restoring a specific configuration.
-	*/
 	constructor({ bitsPerKey, capacity, seed = 0 }) {
 		assertPositiveFinite(bitsPerKey, "bitsPerKey");
 		assertPositiveInt(capacity, "capacity");
@@ -113,19 +66,15 @@ var BlockedBloomFilter = class BlockedBloomFilter {
 		f.#n = n;
 		return f;
 	}
-	/** Actual bits allocated per key (`total bits / capacity`). */
 	get bitsPerKey() {
 		return this.#numBlocks * 256 / this.#n;
 	}
-	/** Number of 256-bit blocks; one of the two fields `union` requires to match. */
 	get numBlocks() {
 		return this.#numBlocks;
 	}
-	/** Hash seed; the other field `union` requires to match. */
 	get seed() {
 		return this.#seed;
 	}
-	/** Number of bits currently set across all lanes. */
 	get length() {
 		let bits = 0;
 		for (let w of this.#lanes) while (w) {
@@ -134,23 +83,9 @@ var BlockedBloomFilter = class BlockedBloomFilter {
 		}
 		return bits;
 	}
-	/**
-	* Estimates the current false-positive rate from the actual fill,
-	* `(length / totalBits) ** 8`. A split-block query checks exactly 8 lane-bits,
-	* so the exponent is 8 rather than a classic probe count `k`. This reflects
-	* how full the filter is right now, not the design target.
-	*
-	* @returns The estimated false-positive rate, `0` for an empty filter.
-	*/
 	rate() {
 		return (this.length / (this.#numBlocks * 256)) ** 8;
 	}
-	/**
-	* Restores a filter from its {@link BlockedBloomFilter.toBytes} serialization.
-	*
-	* @param bytes - The serialized filter.
-	* @returns The reconstructed filter.
-	*/
 	static fromBytes(bytes) {
 		const { type, flags, body } = readHeader(bytes);
 		if (type !== TYPE) throw new SerializationError(`expected AMQF type ${String(TYPE)}, got ${String(type)}`);
@@ -166,11 +101,6 @@ var BlockedBloomFilter = class BlockedBloomFilter {
 		new Uint8Array(f.#lanes.buffer).set(body.subarray(12));
 		return f;
 	}
-	/**
-	* Serializes the filter to a portable little-endian byte layout.
-	*
-	* @returns The serialized filter, readable by {@link BlockedBloomFilter.fromBytes}.
-	*/
 	toBytes() {
 		const lanes = new Uint8Array(this.#lanes.buffer, this.#lanes.byteOffset, this.#lanes.byteLength);
 		return writeFrame({
@@ -184,52 +114,21 @@ var BlockedBloomFilter = class BlockedBloomFilter {
 			body.set(lanes, 12);
 		});
 	}
-	/**
-	* Tests structural equality: `true` when `other` serializes to identical
-	* bytes, meaning identical parameters and set bits.
-	*
-	* @param other - The filter to compare against.
-	* @returns `true` if the two filters are byte-for-byte identical.
-	*/
 	equals(other) {
 		return bytesEqual(this.toBytes(), other.toBytes());
 	}
-	/**
-	* Serializes the filter to a JSON-friendly envelope wrapping the base64 of
-	* {@link BlockedBloomFilter.toBytes}.
-	*
-	* @returns The envelope, readable by {@link BlockedBloomFilter.fromJSON}.
-	*/
 	toJSON() {
 		return toJSONEnvelope(this.toBytes());
 	}
-	/**
-	* Restores a filter from its {@link BlockedBloomFilter.toJSON} envelope.
-	*
-	* @param value - The JSON envelope.
-	* @returns The reconstructed filter.
-	*/
 	static fromJSON(value) {
 		return BlockedBloomFilter.fromBytes(fromJSONEnvelope(value));
 	}
-	/**
-	* Returns a new filter containing the union of this filter and `other`.
-	*
-	* @param other - A filter built with identical parameters.
-	* @returns A new filter reporting membership for keys in either input.
-	* @throws {@link BlockedBloomParamMismatchError} if the parameters differ.
-	*/
 	union(other) {
 		if (this.#numBlocks !== other.#numBlocks || this.#seed !== other.#seed) throw new BlockedBloomParamMismatchError("cannot union blocked Bloom filters whose parameters do not match");
 		const r = BlockedBloomFilter.#fromNumBlocks(this.#numBlocks, this.#seed, this.#n);
 		for (let i = 0; i < this.#lanes.length; i++) r.#lanes[i] = (this.#lanes[i] ?? 0) | (other.#lanes[i] ?? 0);
 		return r;
 	}
-	/**
-	* Adds a key to the set.
-	*
-	* @param key - The key to insert, as a string or bytes.
-	*/
 	add(key) {
 		fillBlock(key, this.#numBlocks, this.#seed, this.#words, this.#bits);
 		for (let i = 0; i < 8; i++) {
@@ -237,12 +136,6 @@ var BlockedBloomFilter = class BlockedBloomFilter {
 			this.#lanes[w] = (this.#lanes[w] ?? 0) | (this.#bits[i] ?? 0);
 		}
 	}
-	/**
-	* Tests whether a key is in the set.
-	*
-	* @param key - The key to test.
-	* @returns `true` if present (possibly a false positive); `false` guarantees absence.
-	*/
 	has(key) {
 		fillBlock(key, this.#numBlocks, this.#seed, this.#words, this.#bits);
 		for (let i = 0; i < 8; i++) {
@@ -263,4 +156,4 @@ function fillBlock(key, numBlocks, seed, outWords, outBits) {
 	}
 }
 //#endregion
-export { BlockedBloomFilter, BlockedBloomParamMismatchError, ParamError };
+export { BadMagicError, BlockedBloomFilter, BlockedBloomParamMismatchError, ChecksumError, ParamError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError, blockedBitsPerKey, blockedFprAt };