distillate 0.9.0 → 0.10.0

package/README.md

@@ -135,6 +135,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/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-D8LCBTOM.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, c as reduce } from "../hasher-DVWXS_vJ.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,5 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_serialize = require("../serialize-Ul2LKFJU.cjs");
+const require_hasher = require("../hasher-D8LCBTOM.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
@@ -35,6 +36,8 @@ var BitSet = class {
 //#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 +67,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 }) {
@@ -118,15 +122,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 +158,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 +173,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,4 +1,5 @@
-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 { s as probeInto } from "../hasher-DVWXS_vJ.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
@@ -34,6 +35,8 @@ var BitSet = class {
 //#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 +66,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 +121,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 +167,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 };

package/dist/frame/index.js

@@ -0,0 +1,2 @@
+import { a as TruncatedError, i as SerializationError, n as ChecksumError, p as readFrameAt, r as ReservedBitsError, s as UnknownVersionError, t as BadMagicError } from "../serialize-CMSYFym-.js";
+export { BadMagicError, ChecksumError, ReservedBitsError, SerializationError, TruncatedError, UnknownVersionError, readFrameAt };

package/dist/fuse/index.cjs

@@ -1,9 +1,11 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_serialize = require("../serialize-Ul2LKFJU.cjs");
+const require_hasher = require("../hasher-D8LCBTOM.cjs");
+const require_serialize = require("../serialize-CHikZ4GH.cjs");
 //#region src/fuse/fuse.ts
 const ARITY = 3;
 const TYPE_FUSE8 = 3;
 const TYPE_FUSE16 = 4;
+const PARAMS_SIZE = 16;
 var BinaryFuseBuildError = class extends Error {
 	name = "BinaryFuseBuildError";
 };
@@ -16,14 +18,14 @@ const scratchHash = {
 function mixSeed(lo, hi, seed) {
 	const l = (lo >>> 0) + (seed >>> 0);
 	const carry = l > 4294967295 ? 1 : 0;
-	require_serialize.fmix64(l >>> 0, hi + carry >>> 0);
+	require_hasher.fmix64(l >>> 0, hi + carry >>> 0);
 }
 function mulhi64(lo, hi, n) {
-	require_serialize.mul64(hi, 0, n, 0);
-	const aLo = require_serialize.RLO;
-	const aHi = require_serialize.RHI;
-	require_serialize.mul64(lo, 0, n, 0);
-	const bHi = require_serialize.RHI;
+	require_hasher.mul64(hi, 0, n, 0);
+	const aLo = require_hasher.RLO;
+	const aHi = require_hasher.RHI;
+	require_hasher.mul64(lo, 0, n, 0);
+	const bHi = require_hasher.RHI;
 	return aHi + ((aLo >>> 0) + (bHi >>> 0) > 4294967295 ? 1 : 0) >>> 0;
 }
 function positionsInto(mlo, mhi, seg, segMask, segCountLen, out) {
@@ -44,10 +46,10 @@ function computeParams(size) {
 	const segMask = seg - 1;
 	const sizeFactor = Math.max(1.125, .875 + .25 * Math.log(1e6) / Math.log(Math.max(size, 2)));
 	const capacity = Math.round(size * sizeFactor);
-	let segCount = Math.floor((capacity + seg - 1) / seg) - (ARITY - 1);
+	let segCount = Math.floor((capacity + seg - 1) / seg) - 2;
 	if (segCount <= 0) segCount = 1;
 	let arrayLength = (segCount + ARITY - 1) * seg;
-	segCount = Math.floor((arrayLength + seg - 1) / seg) - (ARITY - 1);
+	segCount = Math.floor((arrayLength + seg - 1) / seg) - 2;
 	if (segCount <= 0) segCount = 1;
 	arrayLength = (segCount + ARITY - 1) * seg;
 	return {
@@ -79,8 +81,8 @@ function buildFingerprints(fp, hashes, params, maxAttempts = 100) {
 		xorHi.fill(0);
 		for (let i = 0; i < size; i++) {
 			mixSeed(hashes[2 * i] ?? 0, hashes[2 * i + 1] ?? 0, seed);
-			const mlo = require_serialize.RLO;
-			const mhi = require_serialize.RHI;
+			const mlo = require_hasher.RLO;
+			const mhi = require_hasher.RHI;
 			positionsInto(mlo, mhi, seg, segMask, segCountLen, pos);
 			for (let j = 0; j < 3; j++) {
 				const p = pos[j] ?? 0;
@@ -132,7 +134,7 @@ function buildState(keys, alloc) {
 	const hashList = [];
 	const seen = new Set();
 	for (const key of keys) {
-		require_serialize.hash128KeyInto(key, 0, scratchHash);
+		require_hasher.hash128KeyInto(key, 0, scratchHash);
 		const lo = scratchHash.w0 >>> 0;
 		const hi = scratchHash.w1 >>> 0;
 		const id = `${String(lo)},${String(hi)}`;
@@ -161,7 +163,7 @@ function fuseStateFromBytes(bytes, expectedType) {
 	const { type, flags, body } = require_serialize.readHeader(bytes);
 	if (type !== expectedType) throw new require_serialize.SerializationError(`expected DSTL type ${String(expectedType)}, got ${String(type)}`);
 	if ((flags & 15) !== 0) throw new require_serialize.UnknownHashVariantError(`unsupported hash variant ${String(flags & 15)}`);
-	require_serialize.assertMinBodyLength(body.length, 16, "fuse");
+	require_serialize.assertMinBodyLength(body.length, PARAMS_SIZE, "fuse");
 	const dv = new DataView(body.buffer, body.byteOffset, body.byteLength);
 	const seed = dv.getUint32(0, true);
 	const seg = dv.getUint32(4, true);
@@ -171,8 +173,8 @@ function fuseStateFromBytes(bytes, expectedType) {
 	if (segCountLen % seg !== 0) throw new require_serialize.SerializationError(`fuse segment count length ${String(segCountLen)} is not a multiple of segment length ${String(seg)}`);
 	const bpe = expectedType === TYPE_FUSE8 ? 1 : 2;
 	const expectedArrayLength = size === 0 ? 0 : segCountLen + 2 * seg;
-	require_serialize.assertBodyLength(body.length, 16 + expectedArrayLength * bpe, "fuse");
-	const laneBytes = body.subarray(16);
+	require_serialize.assertBodyLength(body.length, PARAMS_SIZE + expectedArrayLength * bpe, "fuse");
+	const laneBytes = body.subarray(PARAMS_SIZE);
 	const arrayLength = laneBytes.length / bpe;
 	const fp = bpe === 1 ? new Uint8Array(arrayLength) : new Uint16Array(arrayLength);
 	new Uint8Array(fp.buffer).set(laneBytes);
@@ -215,24 +217,25 @@ var BinaryFuse = class {
 	}
 	toBytes() {
 		const laneBytes = new Uint8Array(this.#fp.buffer, this.#fp.byteOffset, this.#fp.byteLength);
+		const type = this.#fp.BYTES_PER_ELEMENT === 1 ? TYPE_FUSE8 : TYPE_FUSE16;
 		return require_serialize.writeFrame({
-			version: 4,
-			type: this.#fp.BYTES_PER_ELEMENT === 1 ? TYPE_FUSE8 : TYPE_FUSE16,
+			version: 5,
+			type,
 			flags: 0
-		}, 16 + laneBytes.length, (body, dv) => {
+		}, PARAMS_SIZE, laneBytes.length, (body, dv) => {
 			dv.setUint32(0, this.#seed, true);
 			dv.setUint32(4, this.#seg, true);
 			dv.setUint32(8, this.#segCountLen, true);
 			dv.setUint32(12, this.#size, true);
-			body.set(laneBytes, 16);
+			body.set(laneBytes, PARAMS_SIZE);
 		});
 	}
 	has(key) {
 		if (this.#fp.length === 0) return false;
-		require_serialize.hash128KeyInto(key, 0, scratchHash);
+		require_hasher.hash128KeyInto(key, 0, scratchHash);
 		mixSeed(scratchHash.w0 >>> 0, scratchHash.w1 >>> 0, this.#seed);
-		const mlo = require_serialize.RLO;
-		const mhi = require_serialize.RHI;
+		const mlo = require_hasher.RLO;
+		const mhi = require_hasher.RHI;
 		positionsInto(mlo, mhi, this.#seg, this.#segMask, this.#segCountLen, this.#pos);
 		const mask = fpMask(this.#fp);
 		const p0 = this.#pos[0] ?? 0;
@@ -275,6 +278,7 @@ exports.BinaryFuse16 = BinaryFuse16;
 exports.BinaryFuse8 = BinaryFuse8;
 exports.BinaryFuseBuildError = BinaryFuseBuildError;
 exports.ChecksumError = require_serialize.ChecksumError;
+exports.ReservedBitsError = require_serialize.ReservedBitsError;
 exports.SerializationError = require_serialize.SerializationError;
 exports.TruncatedError = require_serialize.TruncatedError;
 exports.UnknownHashVariantError = require_serialize.UnknownHashVariantError;

package/dist/fuse/index.d.cts

@@ -1,7 +1,8 @@
-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";
 //#region src/fuse/fuse.d.ts
 /** Thrown when binary fuse construction fails to converge on the key set. */
-declare class BinaryFuseBuildError extends Error {
+export declare class BinaryFuseBuildError extends Error {
   /** Discriminates this error from other `Error`s. */
   override readonly name = "BinaryFuseBuildError";
 }
@@ -20,7 +21,7 @@ interface FuseParams {
  * @param width - Fingerprint width in bits: `8` for {@link BinaryFuse8}, `16` for {@link BinaryFuse16}.
  * @returns Bits per key (`0` for an empty filter).
  */
-declare function fuseBitsPerKey(n: number, width: 8 | 16): number;
+export declare function fuseBitsPerKey(n: number, width: 8 | 16): number;
 interface FuseState {
   fp: Uint8Array | Uint16Array;
   seed: number;
@@ -81,7 +82,7 @@ declare abstract class BinaryFuse {
  * filter.size; // 3
  * ```
  */
-declare class BinaryFuse8 extends BinaryFuse {
+export declare class BinaryFuse8 extends BinaryFuse {
   /**
    * Builds a filter from the given keys; duplicates are ignored.
    *
@@ -115,7 +116,7 @@ declare class BinaryFuse8 extends BinaryFuse {
  * filter.has("alice"); // true
  * ```
  */
-declare class BinaryFuse16 extends BinaryFuse {
+export declare class BinaryFuse16 extends BinaryFuse {
   /**
    * Builds a filter from the given keys; duplicates are ignored.
    *
@@ -140,4 +141,4 @@ declare class BinaryFuse16 extends BinaryFuse {
   static fromJSON(value: unknown): BinaryFuse16;
 }
 //#endregion
-export { BadMagicError, BinaryFuse16, BinaryFuse8, BinaryFuseBuildError, ChecksumError, type FilterJSON, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError, fuseBitsPerKey };
+export { BadMagicError, ChecksumError, type FilterJSON, ReservedBitsError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError };