distillate 0.9.0 → 0.11.0

package/README.md

@@ -42,12 +42,13 @@ 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     | Answers            | Use for                                                  |
-| -------------------- | ------------- | ------------------ | -------------------------------------------------------- |
-| `distillate/bloom`   | Classic Bloom | seen this key?     | Familiar default, migration from `bloom-filters`         |
-| `distillate/blocked` | Blocked Bloom | seen this key?     | Faster lookups and a lower FPR for a small space premium |
-| `distillate/fuse`    | Binary Fuse   | seen this key?     | Static set built once and queried a lot; least space     |
-| `distillate/hll`     | HyperLogLog   | how many distinct? | Counting distinct users, IPs, or keys in fixed space     |
+| Import                | Structure      | Answers            | Use for                                                  |
+| --------------------- | -------------- | ------------------ | -------------------------------------------------------- |
+| `distillate/bloom`    | Classic Bloom  | seen this key?     | Familiar default, migration from `bloom-filters`         |
+| `distillate/scalable` | Scalable Bloom | seen this key?     | Key count unknown or growing; keeps its FPR bound        |
+| `distillate/blocked`  | Blocked Bloom  | seen this key?     | Faster lookups and a lower FPR for a small space premium |
+| `distillate/fuse`     | Binary Fuse    | seen this key?     | Static set built once and queried a lot; least space     |
+| `distillate/hll`      | HyperLogLog    | how many distinct? | Counting distinct users, IPs, or keys in fixed space     |
 
 The filters are mutable except Binary Fuse, which is built once from the whole
 key set. HyperLogLog is not a filter: it counts distinct keys and cannot report
@@ -69,6 +70,24 @@ const restored = BloomFilter.fromBytes(bytes);
 
 Also: `union(other)` (merge equal-parameter filters), `bitsPerKey`, and a low-level `new BloomFilter({ m, k, seed })`.
 
+### Scalable Bloom (`distillate/scalable`)
+
+For when you cannot say how many keys are coming. It grows by opening larger, tighter Bloom stages as keys arrive, and keeps its false-positive rate under the target however many open. Full API and trade-offs: [Scalable Bloom guide](https://distillate.akxp.net/guides/scalable/).
+
+```ts
+import { ScalableBloomFilter } from "distillate/scalable";
+
+const seen = ScalableBloomFilter.create(10, 0.01); // first stage, target FPR
+for (let i = 0; i < 30; i++) seen.add(`key-${String(i)}`);
+
+seen.stages; // 2
+seen.has("key-29"); // true
+```
+
+A key already held is not counted again, so duplicates never use up capacity. It costs more bits per key than a Classic Bloom sized for a known `n`; if you know `n`, use that.
+
+Also: `from(keys, epsilon)`, `union`, `equals`, `rate`, `toBytes` / `fromBytes`, `toJSON` / `fromJSON`, and `growth` / `tightening` / `seed` options.
+
 ### Blocked Bloom (`distillate/blocked`)
 
 ```ts
@@ -135,6 +154,25 @@ Classic Bloom head-to-head at a **matched 1% false-positive rate** over the same
 
 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.
 
+Cardinality is a separate head-to-head, at a **matched register count** (`m = 2 ** p`, `p = 14`, the configuration Redis uses) over the same keys, swept from 1k to 10M distinct:
+
+| p = 14, m = 16384    | distillate      | bloom-filters    |
+| -------------------- | --------------- | ---------------- |
+| rel. error, n=1k     | 0.00%           | 49.63%           |
+| rel. error, n=100k   | 0.82%           | 0.78%            |
+| rel. error, n=10M    | 0.15%           | 0.41%            |
+| serialized, n=10M    | 12,314 B binary | 40,247 B JSON    |
+| build 10M keys       | 0.63 s          | 1,165 s (19 min) |
+| sustained add, n=10M | ~16 M ops/s     | ~9 k ops/s       |
+
+Both sketches carry the same theoretical error at this precision (`1.04 / sqrt(m)`, about 0.81%), and once `n` is well past `m` both stay inside it. The differences are elsewhere.
+
+**Small counts.** `bloom-filters` has no working small-range correction, so below roughly `2.5 * m` it is off by about half: counting a few thousand distinct keys in a 16k-register sketch, it answers 504 for 1,000. distillate is exact there because it is still holding sparse entries, not because its estimator is better.
+
+**Memory does not grow.** From 10k distinct keys to 10M, distillate stays at exactly 12,314 bytes. The incumbent's JSON grows from 32,904 to 40,247 bytes over the same range, because larger register values take more digits to spell out.
+
+**Building the sketch.** `bloom-filters` holds a flat 9k adds/sec at every size, so its cost is purely linear: 10.6 seconds for 100k distinct keys, 109 seconds for 1M, and 1,165 seconds for 10M. distillate counts the same 10M in 0.63 seconds, and its rate climbs with `n` rather than staying flat, reaching about 16 M ops/s once the registers are dense.
+
 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).
 
 ## Docs

package/dist/bitset-Cf2jwRJX.js

@@ -0,0 +1,32 @@
+//#region src/core/bitset.ts
+var BitSetRangeError = class extends RangeError {
+	name = "BitSetRangeError";
+};
+const MAX_BITS = 2 ** 32;
+var BitSet = class {
+	#bits;
+	constructor(nbits) {
+		if (nbits > MAX_BITS) throw new BitSetRangeError(`BitSet capacity ${String(nbits)} exceeds the 2^32-bit limit`);
+		this.#bits = new Uint8Array(Math.ceil(nbits / 8));
+	}
+	set(i) {
+		const idx = i >>> 3;
+		this.#bits[idx] = (this.#bits[idx] ?? 0) | 1 << (i & 7);
+	}
+	get(i) {
+		return ((this.#bits[i >>> 3] ?? 0) & 1 << (i & 7)) !== 0;
+	}
+	get bytes() {
+		return this.#bits;
+	}
+	count() {
+		let total = 0;
+		for (let byte of this.#bits) while (byte) {
+			byte &= byte - 1;
+			total++;
+		}
+		return total;
+	}
+};
+//#endregion
+export { BitSet as t };

package/dist/bitset-QYGqxnEf.cjs

@@ -0,0 +1,37 @@
+//#region src/core/bitset.ts
+var BitSetRangeError = class extends RangeError {
+	name = "BitSetRangeError";
+};
+const MAX_BITS = 2 ** 32;
+var BitSet = class {
+	#bits;
+	constructor(nbits) {
+		if (nbits > MAX_BITS) throw new BitSetRangeError(`BitSet capacity ${String(nbits)} exceeds the 2^32-bit limit`);
+		this.#bits = new Uint8Array(Math.ceil(nbits / 8));
+	}
+	set(i) {
+		const idx = i >>> 3;
+		this.#bits[idx] = (this.#bits[idx] ?? 0) | 1 << (i & 7);
+	}
+	get(i) {
+		return ((this.#bits[i >>> 3] ?? 0) & 1 << (i & 7)) !== 0;
+	}
+	get bytes() {
+		return this.#bits;
+	}
+	count() {
+		let total = 0;
+		for (let byte of this.#bits) while (byte) {
+			byte &= byte - 1;
+			total++;
+		}
+		return total;
+	}
+};
+//#endregion
+Object.defineProperty(exports, "BitSet", {
+	enumerable: true,
+	get: function() {
+		return BitSet;
+	}
+});

package/dist/blocked/index.cjs

@@ -1,8 +1,11 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_serialize = require("../serialize-Ul2LKFJU.cjs");
+const require_hasher = require("../hasher-MhY7aQ8F.cjs");
+const require_serialize = require("../serialize-CHikZ4GH.cjs");
 const require_params = require("../params-UTZbJ22c.cjs");
 //#region src/blocked/blocked.ts
 const TYPE = 2;
+const PARAMS_SIZE = 16;
+const PARAMS_FIELDS_END = 12;
 const SALT = Uint32Array.of(1203114875, 1150766481, 2284105051, 2729912477, 1884591559, 770785867, 2667333959, 1550580529);
 const scratch2 = new Uint32Array(2);
 const BLOCK_BITS = 256;
@@ -91,28 +94,29 @@ var BlockedBloomFilter = class BlockedBloomFilter {
 		const { type, flags, body } = require_serialize.readHeader(bytes);
 		if (type !== TYPE) throw new require_serialize.SerializationError(`expected DSTL type ${String(TYPE)}, got ${String(type)}`);
 		if ((flags & 15) !== 0) throw new require_serialize.UnknownHashVariantError(`unsupported hash variant ${String(flags & 15)}`);
-		require_serialize.assertMinBodyLength(body.length, 12, "blocked");
+		require_serialize.assertMinBodyLength(body.length, PARAMS_SIZE, "blocked");
+		require_serialize.assertParamsPadding(body, PARAMS_FIELDS_END, PARAMS_SIZE, "blocked");
 		const dv = new DataView(body.buffer, body.byteOffset, body.byteLength);
 		const numBlocks = dv.getUint32(0, true);
 		const seed = dv.getUint32(4, true);
 		const n = dv.getUint32(8, true);
 		if (numBlocks === 0 || n === 0) throw new require_serialize.SerializationError(`blocked frame declares numBlocks=${String(numBlocks)}, n=${String(n)}; both must be positive`);
-		require_serialize.assertBodyLength(body.length, 12 + numBlocks * 32, "blocked");
+		require_serialize.assertBodyLength(body.length, PARAMS_SIZE + numBlocks * 32, "blocked");
 		const f = BlockedBloomFilter.#fromNumBlocks(numBlocks, seed, n);
-		new Uint8Array(f.#lanes.buffer).set(body.subarray(12));
+		new Uint8Array(f.#lanes.buffer).set(body.subarray(PARAMS_SIZE));
 		return f;
 	}
 	toBytes() {
 		const lanes = new Uint8Array(this.#lanes.buffer, this.#lanes.byteOffset, this.#lanes.byteLength);
 		return require_serialize.writeFrame({
-			version: 4,
+			version: 5,
 			type: TYPE,
 			flags: 0
-		}, 12 + lanes.length, (body, dv) => {
+		}, PARAMS_SIZE, lanes.length, (body, dv) => {
 			dv.setUint32(0, this.#numBlocks, true);
 			dv.setUint32(4, this.#seed, true);
 			dv.setUint32(8, this.#n, true);
-			body.set(lanes, 12);
+			body.set(lanes, PARAMS_SIZE);
 		});
 	}
 	equals(other) {
@@ -147,8 +151,8 @@ var BlockedBloomFilter = class BlockedBloomFilter {
 	}
 };
 function fillBlock(key, numBlocks, seed, outWords, outBits) {
-	require_serialize.hash32x2Into(key, seed, scratch2);
-	const block = require_serialize.reduce(scratch2[0] ?? 0, numBlocks);
+	require_hasher.hash32x2Into(key, seed, scratch2);
+	const block = require_hasher.reduce(scratch2[0] ?? 0, numBlocks);
 	const x = scratch2[1] ?? 0;
 	const base = block * 8;
 	for (let i = 0; i < 8; i++) {
@@ -162,6 +166,7 @@ exports.BlockedBloomFilter = BlockedBloomFilter;
 exports.BlockedBloomParamMismatchError = BlockedBloomParamMismatchError;
 exports.ChecksumError = require_serialize.ChecksumError;
 exports.ParamError = require_params.ParamError;
+exports.ReservedBitsError = require_serialize.ReservedBitsError;
 exports.SerializationError = require_serialize.SerializationError;
 exports.TruncatedError = require_serialize.TruncatedError;
 exports.UnknownHashVariantError = require_serialize.UnknownHashVariantError;

package/dist/blocked/index.d.cts

@@ -1,4 +1,5 @@
-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-Bv1zWzrh.cjs";
+import { t as BytesLike } from "../bytes-DCuYtUVS.cjs";
+import { a as ReservedBitsError, c as UnknownHashVariantError, l as UnknownVersionError, n as ChecksumError, o as SerializationError, r as FilterJSON, s as TruncatedError, t as BadMagicError } from "../serialize--xR6vGSW.cjs";
 import { t as ParamError } from "../params-DnqJBqLS.cjs";
 //#region src/blocked/blocked.d.ts
 /**
@@ -8,16 +9,16 @@ import { t as ParamError } from "../params-DnqJBqLS.cjs";
  * `lambda = 256 / bitsPerKey`. This clustering average is why the blocked curve
  * is not linear in `log10(1/epsilon)`.
  */
-declare function blockedFprAt(bitsPerKey: number): number;
+export 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;
+export declare function blockedBitsPerKey(epsilon: number): number;
 /** Thrown when an operation requires two filters built with identical parameters. */
-declare class BlockedBloomParamMismatchError extends Error {
+export declare class BlockedBloomParamMismatchError extends Error {
   /** Discriminates this error from other `Error`s. */
   override readonly name = "BlockedBloomParamMismatchError";
 }
@@ -41,7 +42,7 @@ interface BlockedBloomParams {
  * filter.has("alice"); // true
  * ```
  */
-declare class BlockedBloomFilter {
+export declare class BlockedBloomFilter {
   #private;
   /**
    * Creates a filter sized for `n` expected keys at a target false-positive rate.
@@ -142,4 +143,4 @@ declare class BlockedBloomFilter {
   has(key: BytesLike): boolean;
 }
 //#endregion
-export { BadMagicError, BlockedBloomFilter, BlockedBloomParamMismatchError, type BlockedBloomParams, ChecksumError, type FilterJSON, ParamError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError, blockedBitsPerKey, blockedFprAt };
+export { BadMagicError, type BlockedBloomParams, ChecksumError, type FilterJSON, ParamError, ReservedBitsError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError };

package/dist/blocked/index.d.ts

@@ -1,4 +1,5 @@
-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-Bv1zWzrh.js";
+import { t as BytesLike } from "../bytes-DCuYtUVS.js";
+import { a as ReservedBitsError, c as UnknownHashVariantError, l as UnknownVersionError, n as ChecksumError, o as SerializationError, r as FilterJSON, s as TruncatedError, t as BadMagicError } from "../serialize--xR6vGSW.js";
 import { t as ParamError } from "../params-DnqJBqLS.js";
 //#region src/blocked/blocked.d.ts
 /**
@@ -8,16 +9,16 @@ import { t as ParamError } from "../params-DnqJBqLS.js";
  * `lambda = 256 / bitsPerKey`. This clustering average is why the blocked curve
  * is not linear in `log10(1/epsilon)`.
  */
-declare function blockedFprAt(bitsPerKey: number): number;
+export 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;
+export declare function blockedBitsPerKey(epsilon: number): number;
 /** Thrown when an operation requires two filters built with identical parameters. */
-declare class BlockedBloomParamMismatchError extends Error {
+export declare class BlockedBloomParamMismatchError extends Error {
   /** Discriminates this error from other `Error`s. */
   override readonly name = "BlockedBloomParamMismatchError";
 }
@@ -41,7 +42,7 @@ interface BlockedBloomParams {
  * filter.has("alice"); // true
  * ```
  */
-declare class BlockedBloomFilter {
+export declare class BlockedBloomFilter {
   #private;
   /**
    * Creates a filter sized for `n` expected keys at a target false-positive rate.
@@ -142,4 +143,4 @@ declare class BlockedBloomFilter {
   has(key: BytesLike): boolean;
 }
 //#endregion
-export { BadMagicError, BlockedBloomFilter, BlockedBloomParamMismatchError, type BlockedBloomParams, ChecksumError, type FilterJSON, ParamError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError, blockedBitsPerKey, blockedFprAt };
+export { BadMagicError, type BlockedBloomParams, ChecksumError, type FilterJSON, ParamError, ReservedBitsError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError };

package/dist/blocked/index.js

@@ -1,7 +1,10 @@
-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-D59Ri81a.js";
+import { a as hash32x2Into, u as reduce } from "../hasher-3Cyn7Yg-.js";
+import { a as TruncatedError, c as assertBodyLength, d as bytesEqual, f as fromJSONEnvelope, g as writeFrame, h as toJSONEnvelope, i as SerializationError, l as assertMinBodyLength, m as readHeader, n as ChecksumError, o as UnknownHashVariantError, r as ReservedBitsError, s as UnknownVersionError, t as BadMagicError, u as assertParamsPadding } from "../serialize-CMSYFym-.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 PARAMS_SIZE = 16;
+const PARAMS_FIELDS_END = 12;
 const SALT = Uint32Array.of(1203114875, 1150766481, 2284105051, 2729912477, 1884591559, 770785867, 2667333959, 1550580529);
 const scratch2 = new Uint32Array(2);
 const BLOCK_BITS = 256;
@@ -90,28 +93,29 @@ var BlockedBloomFilter = class BlockedBloomFilter {
 		const { type, flags, body } = readHeader(bytes);
 		if (type !== TYPE) throw new SerializationError(`expected DSTL type ${String(TYPE)}, got ${String(type)}`);
 		if ((flags & 15) !== 0) throw new UnknownHashVariantError(`unsupported hash variant ${String(flags & 15)}`);
-		assertMinBodyLength(body.length, 12, "blocked");
+		assertMinBodyLength(body.length, PARAMS_SIZE, "blocked");
+		assertParamsPadding(body, PARAMS_FIELDS_END, PARAMS_SIZE, "blocked");
 		const dv = new DataView(body.buffer, body.byteOffset, body.byteLength);
 		const numBlocks = dv.getUint32(0, true);
 		const seed = dv.getUint32(4, true);
 		const n = dv.getUint32(8, true);
 		if (numBlocks === 0 || n === 0) throw new SerializationError(`blocked frame declares numBlocks=${String(numBlocks)}, n=${String(n)}; both must be positive`);
-		assertBodyLength(body.length, 12 + numBlocks * 32, "blocked");
+		assertBodyLength(body.length, PARAMS_SIZE + numBlocks * 32, "blocked");
 		const f = BlockedBloomFilter.#fromNumBlocks(numBlocks, seed, n);
-		new Uint8Array(f.#lanes.buffer).set(body.subarray(12));
+		new Uint8Array(f.#lanes.buffer).set(body.subarray(PARAMS_SIZE));
 		return f;
 	}
 	toBytes() {
 		const lanes = new Uint8Array(this.#lanes.buffer, this.#lanes.byteOffset, this.#lanes.byteLength);
 		return writeFrame({
-			version: 4,
+			version: 5,
 			type: TYPE,
 			flags: 0
-		}, 12 + lanes.length, (body, dv) => {
+		}, PARAMS_SIZE, lanes.length, (body, dv) => {
 			dv.setUint32(0, this.#numBlocks, true);
 			dv.setUint32(4, this.#seed, true);
 			dv.setUint32(8, this.#n, true);
-			body.set(lanes, 12);
+			body.set(lanes, PARAMS_SIZE);
 		});
 	}
 	equals(other) {
@@ -156,4 +160,4 @@ function fillBlock(key, numBlocks, seed, outWords, outBits) {
 	}
 }
 //#endregion
-export { BadMagicError, BlockedBloomFilter, BlockedBloomParamMismatchError, ChecksumError, ParamError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError, blockedBitsPerKey, blockedFprAt };
+export { BadMagicError, BlockedBloomFilter, BlockedBloomParamMismatchError, ChecksumError, ParamError, ReservedBitsError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError, blockedBitsPerKey, blockedFprAt };

package/dist/bloom/index.cjs

@@ -1,40 +1,13 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_serialize = require("../serialize-Ul2LKFJU.cjs");
+const require_bitset = require("../bitset-QYGqxnEf.cjs");
+const require_hasher = require("../hasher-MhY7aQ8F.cjs");
+const require_serialize = require("../serialize-CHikZ4GH.cjs");
 const require_params = require("../params-UTZbJ22c.cjs");
 const require_sizing = require("../sizing-BLzZk2zr.cjs");
-//#region src/core/bitset.ts
-var BitSetRangeError = class extends RangeError {
-	name = "BitSetRangeError";
-};
-const MAX_BITS = 2 ** 32;
-var BitSet = class {
-	#bits;
-	constructor(nbits) {
-		if (nbits > MAX_BITS) throw new BitSetRangeError(`BitSet capacity ${String(nbits)} exceeds the 2^32-bit limit`);
-		this.#bits = new Uint8Array(Math.ceil(nbits / 8));
-	}
-	set(i) {
-		const idx = i >>> 3;
-		this.#bits[idx] = (this.#bits[idx] ?? 0) | 1 << (i & 7);
-	}
-	get(i) {
-		return ((this.#bits[i >>> 3] ?? 0) & 1 << (i & 7)) !== 0;
-	}
-	get bytes() {
-		return this.#bits;
-	}
-	count() {
-		let total = 0;
-		for (let byte of this.#bits) while (byte) {
-			byte &= byte - 1;
-			total++;
-		}
-		return total;
-	}
-};
-//#endregion
 //#region src/bloom/bloom.ts
 const TYPE = 1;
+const PARAMS_SIZE = 16;
+const PARAMS_FIELDS_END = 14;
 var BloomParamMismatchError = class extends Error {
 	name = "BloomParamMismatchError";
 };
@@ -64,20 +37,21 @@ var BloomFilter = class BloomFilter {
 		const { type, flags, body } = require_serialize.readHeader(bytes);
 		if (type !== TYPE) throw new require_serialize.SerializationError(`expected DSTL type ${String(TYPE)}, got ${String(type)}`);
 		if ((flags & 15) !== 0) throw new require_serialize.UnknownHashVariantError(`unsupported hash variant ${String(flags & 15)}`);
-		require_serialize.assertMinBodyLength(body.length, 14, "bloom");
+		require_serialize.assertMinBodyLength(body.length, PARAMS_SIZE, "bloom");
+		require_serialize.assertParamsPadding(body, PARAMS_FIELDS_END, PARAMS_SIZE, "bloom");
 		const dv = new DataView(body.buffer, body.byteOffset, body.byteLength);
 		const m = dv.getUint32(0, true);
 		const k = dv.getUint16(4, true);
 		const seed = dv.getUint32(6, true);
 		const n = dv.getUint32(10, true);
-		require_serialize.assertBodyLength(body.length, 14 + Math.ceil(m / 8), "bloom");
+		require_serialize.assertBodyLength(body.length, PARAMS_SIZE + Math.ceil(m / 8), "bloom");
 		const f = new BloomFilter({
 			m,
 			k,
 			seed,
 			n
 		});
-		f.#bits.bytes.set(body.subarray(14));
+		f.#bits.bytes.set(body.subarray(PARAMS_SIZE));
 		return f;
 	}
 	constructor({ m, k, seed = 0, n }) {
@@ -90,7 +64,7 @@ var BloomFilter = class BloomFilter {
 			require_params.assertPositiveInt(n, "n");
 			require_params.assertUint32(n, "n");
 		}
-		this.#bits = new BitSet(m);
+		this.#bits = new require_bitset.BitSet(m);
 		this.#m = m;
 		this.#k = k;
 		this.#seed = seed;
@@ -118,15 +92,15 @@ var BloomFilter = class BloomFilter {
 	toBytes() {
 		const payload = this.#bits.bytes;
 		return require_serialize.writeFrame({
-			version: 4,
+			version: 5,
 			type: TYPE,
 			flags: 0
-		}, 14 + payload.length, (body, dv) => {
+		}, PARAMS_SIZE, payload.length, (body, dv) => {
 			dv.setUint32(0, this.#m, true);
 			dv.setUint16(4, this.#k, true);
 			dv.setUint32(6, this.#seed, true);
 			dv.setUint32(10, this.#n, true);
-			body.set(payload, 14);
+			body.set(payload, PARAMS_SIZE);
 		});
 	}
 	equals(other) {
@@ -154,11 +128,11 @@ var BloomFilter = class BloomFilter {
 		return r;
 	}
 	add(key) {
-		require_serialize.probeInto(key, this.#k, this.#m, this.#seed, this.#scratch);
+		require_hasher.probeInto(key, this.#k, this.#m, this.#seed, this.#scratch);
 		for (let i = 0; i < this.#k; i++) this.#bits.set(this.#scratch[i] ?? 0);
 	}
 	has(key) {
-		require_serialize.probeInto(key, this.#k, this.#m, this.#seed, this.#scratch);
+		require_hasher.probeInto(key, this.#k, this.#m, this.#seed, this.#scratch);
 		for (let i = 0; i < this.#k; i++) if (!this.#bits.get(this.#scratch[i] ?? 0)) return false;
 		return true;
 	}
@@ -169,6 +143,7 @@ exports.BloomFilter = BloomFilter;
 exports.BloomParamMismatchError = BloomParamMismatchError;
 exports.ChecksumError = require_serialize.ChecksumError;
 exports.ParamError = require_params.ParamError;
+exports.ReservedBitsError = require_serialize.ReservedBitsError;
 exports.SerializationError = require_serialize.SerializationError;
 exports.TruncatedError = require_serialize.TruncatedError;
 exports.UnknownHashVariantError = require_serialize.UnknownHashVariantError;

package/dist/bloom/index.d.cts

@@ -1,9 +1,10 @@
-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-Bv1zWzrh.cjs";
+import { t as BytesLike } from "../bytes-DCuYtUVS.cjs";
+import { a as ReservedBitsError, c as UnknownHashVariantError, l as UnknownVersionError, n as ChecksumError, o as SerializationError, r as FilterJSON, s as TruncatedError, t as BadMagicError } from "../serialize--xR6vGSW.cjs";
 import { t as ParamError } from "../params-DnqJBqLS.cjs";
 import { r as bloomSizing, t as BloomSizing } from "../sizing-wYOW27eY.cjs";
 //#region src/bloom/bloom.d.ts
 /** Thrown when an operation requires two filters built with identical parameters. */
-declare class BloomParamMismatchError extends Error {
+export declare class BloomParamMismatchError extends Error {
   /** Discriminates this error from other `Error`s. */
   override readonly name = "BloomParamMismatchError";
 }
@@ -34,7 +35,7 @@ interface BloomParams {
  * filter.has("bob"); // false (or a ~1% false positive)
  * ```
  */
-declare class BloomFilter {
+export declare class BloomFilter {
   #private;
   /**
    * Creates a filter sized for `n` expected keys at a target false-positive rate.
@@ -143,4 +144,4 @@ declare class BloomFilter {
   has(key: BytesLike): boolean;
 }
 //#endregion
-export { BadMagicError, BloomFilter, BloomParamMismatchError, type BloomParams, type BloomSizing, ChecksumError, type FilterJSON, ParamError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError, bloomSizing };
+export { BadMagicError, type BloomParams, type BloomSizing, ChecksumError, type FilterJSON, ParamError, ReservedBitsError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError, bloomSizing };

package/dist/bloom/index.d.ts

@@ -1,9 +1,10 @@
-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-Bv1zWzrh.js";
+import { t as BytesLike } from "../bytes-DCuYtUVS.js";
+import { a as ReservedBitsError, c as UnknownHashVariantError, l as UnknownVersionError, n as ChecksumError, o as SerializationError, r as FilterJSON, s as TruncatedError, t as BadMagicError } from "../serialize--xR6vGSW.js";
 import { t as ParamError } from "../params-DnqJBqLS.js";
 import { r as bloomSizing, t as BloomSizing } from "../sizing-wYOW27eY.js";
 //#region src/bloom/bloom.d.ts
 /** Thrown when an operation requires two filters built with identical parameters. */
-declare class BloomParamMismatchError extends Error {
+export declare class BloomParamMismatchError extends Error {
   /** Discriminates this error from other `Error`s. */
   override readonly name = "BloomParamMismatchError";
 }
@@ -34,7 +35,7 @@ interface BloomParams {
  * filter.has("bob"); // false (or a ~1% false positive)
  * ```
  */
-declare class BloomFilter {
+export declare class BloomFilter {
   #private;
   /**
    * Creates a filter sized for `n` expected keys at a target false-positive rate.
@@ -143,4 +144,4 @@ declare class BloomFilter {
   has(key: BytesLike): boolean;
 }
 //#endregion
-export { BadMagicError, BloomFilter, BloomParamMismatchError, type BloomParams, type BloomSizing, ChecksumError, type FilterJSON, ParamError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError, bloomSizing };
+export { BadMagicError, type BloomParams, type BloomSizing, ChecksumError, type FilterJSON, ParamError, ReservedBitsError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError, bloomSizing };

package/dist/bloom/index.js

@@ -1,39 +1,12 @@
-import { a as UnknownHashVariantError, b as probeInto, 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 } from "../serialize-D59Ri81a.js";
+import { t as BitSet } from "../bitset-Cf2jwRJX.js";
+import { c as probeInto } from "../hasher-3Cyn7Yg-.js";
+import { a as TruncatedError, c as assertBodyLength, d as bytesEqual, f as fromJSONEnvelope, g as writeFrame, h as toJSONEnvelope, i as SerializationError, l as assertMinBodyLength, m as readHeader, n as ChecksumError, o as UnknownHashVariantError, r as ReservedBitsError, s as UnknownVersionError, t as BadMagicError, u as assertParamsPadding } from "../serialize-CMSYFym-.js";
 import { a as assertUint16, i as assertProbability, o as assertUint32, r as assertPositiveInt, t as ParamError } from "../params-CeajSrwv.js";
 import { t as bloomSizing } from "../sizing-BtUrtvF_.js";
-//#region src/core/bitset.ts
-var BitSetRangeError = class extends RangeError {
-	name = "BitSetRangeError";
-};
-const MAX_BITS = 2 ** 32;
-var BitSet = class {
-	#bits;
-	constructor(nbits) {
-		if (nbits > MAX_BITS) throw new BitSetRangeError(`BitSet capacity ${String(nbits)} exceeds the 2^32-bit limit`);
-		this.#bits = new Uint8Array(Math.ceil(nbits / 8));
-	}
-	set(i) {
-		const idx = i >>> 3;
-		this.#bits[idx] = (this.#bits[idx] ?? 0) | 1 << (i & 7);
-	}
-	get(i) {
-		return ((this.#bits[i >>> 3] ?? 0) & 1 << (i & 7)) !== 0;
-	}
-	get bytes() {
-		return this.#bits;
-	}
-	count() {
-		let total = 0;
-		for (let byte of this.#bits) while (byte) {
-			byte &= byte - 1;
-			total++;
-		}
-		return total;
-	}
-};
-//#endregion
 //#region src/bloom/bloom.ts
 const TYPE = 1;
+const PARAMS_SIZE = 16;
+const PARAMS_FIELDS_END = 14;
 var BloomParamMismatchError = class extends Error {
 	name = "BloomParamMismatchError";
 };
@@ -63,20 +36,21 @@ var BloomFilter = class BloomFilter {
 		const { type, flags, body } = readHeader(bytes);
 		if (type !== TYPE) throw new SerializationError(`expected DSTL type ${String(TYPE)}, got ${String(type)}`);
 		if ((flags & 15) !== 0) throw new UnknownHashVariantError(`unsupported hash variant ${String(flags & 15)}`);
-		assertMinBodyLength(body.length, 14, "bloom");
+		assertMinBodyLength(body.length, PARAMS_SIZE, "bloom");
+		assertParamsPadding(body, PARAMS_FIELDS_END, PARAMS_SIZE, "bloom");
 		const dv = new DataView(body.buffer, body.byteOffset, body.byteLength);
 		const m = dv.getUint32(0, true);
 		const k = dv.getUint16(4, true);
 		const seed = dv.getUint32(6, true);
 		const n = dv.getUint32(10, true);
-		assertBodyLength(body.length, 14 + Math.ceil(m / 8), "bloom");
+		assertBodyLength(body.length, PARAMS_SIZE + Math.ceil(m / 8), "bloom");
 		const f = new BloomFilter({
 			m,
 			k,
 			seed,
 			n
 		});
-		f.#bits.bytes.set(body.subarray(14));
+		f.#bits.bytes.set(body.subarray(PARAMS_SIZE));
 		return f;
 	}
 	constructor({ m, k, seed = 0, n }) {
@@ -117,15 +91,15 @@ var BloomFilter = class BloomFilter {
 	toBytes() {
 		const payload = this.#bits.bytes;
 		return writeFrame({
-			version: 4,
+			version: 5,
 			type: TYPE,
 			flags: 0
-		}, 14 + payload.length, (body, dv) => {
+		}, PARAMS_SIZE, payload.length, (body, dv) => {
 			dv.setUint32(0, this.#m, true);
 			dv.setUint16(4, this.#k, true);
 			dv.setUint32(6, this.#seed, true);
 			dv.setUint32(10, this.#n, true);
-			body.set(payload, 14);
+			body.set(payload, PARAMS_SIZE);
 		});
 	}
 	equals(other) {
@@ -163,4 +137,4 @@ var BloomFilter = class BloomFilter {
 	}
 };
 //#endregion
-export { BadMagicError, BloomFilter, BloomParamMismatchError, ChecksumError, ParamError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError, bloomSizing };
+export { BadMagicError, BloomFilter, BloomParamMismatchError, ChecksumError, ParamError, ReservedBitsError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError, bloomSizing };

package/dist/bytes-DCuYtUVS.d.cts

@@ -0,0 +1,4 @@
+//#region src/core/bytes.d.ts
+type BytesLike = string | Uint8Array | ArrayBuffer;
+//#endregion
+export { BytesLike as t };

package/dist/bytes-DCuYtUVS.d.ts

@@ -0,0 +1,4 @@
+//#region src/core/bytes.d.ts
+type BytesLike = string | Uint8Array | ArrayBuffer;
+//#endregion
+export { BytesLike as t };

package/dist/frame/index.cjs

@@ -0,0 +1,9 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_serialize = require("../serialize-CHikZ4GH.cjs");
+exports.BadMagicError = require_serialize.BadMagicError;
+exports.ChecksumError = require_serialize.ChecksumError;
+exports.ReservedBitsError = require_serialize.ReservedBitsError;
+exports.SerializationError = require_serialize.SerializationError;
+exports.TruncatedError = require_serialize.TruncatedError;
+exports.UnknownVersionError = require_serialize.UnknownVersionError;
+exports.readFrameAt = require_serialize.readFrameAt;

package/dist/frame/index.d.cts

@@ -0,0 +1,2 @@
+import { a as ReservedBitsError, i as Frame, l as UnknownVersionError, n as ChecksumError, o as SerializationError, s as TruncatedError, t as BadMagicError, u as readFrameAt } from "../serialize--xR6vGSW.cjs";
+export { BadMagicError, ChecksumError, type Frame, ReservedBitsError, SerializationError, TruncatedError, UnknownVersionError, readFrameAt };

package/dist/frame/index.d.ts

@@ -0,0 +1,2 @@
+import { a as ReservedBitsError, i as Frame, l as UnknownVersionError, n as ChecksumError, o as SerializationError, s as TruncatedError, t as BadMagicError, u as readFrameAt } from "../serialize--xR6vGSW.js";
+export { BadMagicError, ChecksumError, type Frame, ReservedBitsError, SerializationError, TruncatedError, UnknownVersionError, readFrameAt };