distillate 0.11.0 → 0.12.0

package/README.md

@@ -6,7 +6,7 @@
 
 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.
+> **Pre-release (0.x).** The published structures are correct, tested, and benchmarked, but the public API may still change before `1.0`. Pin a version if you depend on it.
 
 ## Why
 
@@ -48,6 +48,7 @@ Each structure ships as its own subpath, so you only bundle what you import.
 | `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/cuckoo`   | Cuckoo         | seen this key?     | Keys come and go; the one filter with delete             |
 | `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
@@ -120,6 +121,25 @@ const precise = BinaryFuse16.from(["alice", "bob", "carol"]);
 
 Also: `toBytes` / `fromBytes`. No `add` / `delete`; rebuild `from` the new set to change membership.
 
+### Cuckoo (`distillate/cuckoo`)
+
+For a set that shrinks as well as grows: the one filter here with `delete`. Full API and trade-offs: [Cuckoo guide](https://distillate.akxp.net/guides/cuckoo/).
+
+```ts
+import { CuckooFilter } from "distillate/cuckoo";
+
+const sessions = CuckooFilter.create(100_000, 0.01);
+sessions.add("alice");
+sessions.has("alice"); // true
+
+sessions.delete("alice"); // true
+sessions.has("alice"); // false
+```
+
+Only delete keys you added: a key never added can share a fingerprint with one that was, and deleting it removes that one instead. An add into a full filter throws `CuckooFullError` and leaves the filter unchanged. It is larger than a Classic Bloom at common targets and smaller only at about 0.2% and below, so pick it for delete, not for space.
+
+Also: `from(keys, epsilon)`, `equals`, `rate`, `count`, `toBytes` / `fromBytes`, `toJSON` / `fromJSON`, `cuckooSizing(n, epsilon)`, and a `seed` option.
+
 ### HyperLogLog (`distillate/hll`)
 
 A **sketch**, not a filter: it counts distinct keys in space fixed by precision rather than by the answer, and cannot report whether it saw any particular key. 12 KiB counts a thousand distinct keys or a billion, at about 0.8% relative error. Full API and sizing: [HyperLogLog guide](https://distillate.akxp.net/guides/hll/).

package/dist/cuckoo/index.cjs

@@ -0,0 +1,278 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_hasher = require("../hasher-MhY7aQ8F.cjs");
+const require_serialize = require("../serialize-CHikZ4GH.cjs");
+const require_params = require("../params-UTZbJ22c.cjs");
+function cuckooSizing(n, epsilon) {
+	require_params.assertProbability(epsilon, "epsilon");
+	const f = Math.max(4, Math.ceil(Math.log2(8 / epsilon)));
+	if (f > 32) throw new require_params.ParamError(`epsilon ${String(epsilon)} needs a ${String(f)}-bit fingerprint, above the maximum ${String(32)} bits`);
+	const buckets = Math.ceil(n / 3.8) + Math.ceil(Math.sqrt(n));
+	return {
+		f,
+		buckets,
+		bitsPerKey: 4 * f * buckets / n
+	};
+}
+//#endregion
+//#region src/cuckoo/cuckoo.ts
+const TYPE = 7;
+const PARAMS_SIZE = 32;
+const PARAMS_FIELDS_END = 28;
+const padded8 = (length) => Math.ceil(length / 8) * 8;
+const wordBytes = (words) => new Uint8Array(words.buffer, words.byteOffset, words.byteLength);
+const SLOTS = 4;
+const MAX_KICKS = 500;
+const UNDO_SLOT = new Float64Array(MAX_KICKS);
+const UNDO_FP = new Uint32Array(MAX_KICKS);
+const HASH = {
+	w0: 0,
+	w1: 0,
+	w2: 0,
+	w3: 0
+};
+let restoring;
+var CuckooFullError = class extends Error {
+	name = "CuckooFullError";
+};
+var CuckooFilter = class CuckooFilter {
+	#n;
+	#epsilon;
+	#seed;
+	#f;
+	#buckets;
+	#mask;
+	#words;
+	#count = 0;
+	#fp = 0;
+	#i1 = 0;
+	#i2 = 0;
+	static create(n, epsilon, options = {}) {
+		return new CuckooFilter({
+			...options,
+			n,
+			epsilon
+		});
+	}
+	static from(keys, epsilon, options = {}) {
+		const seen = new Set();
+		const distinct = [];
+		for (const key of keys) {
+			require_hasher.hash128KeyInto(key, options.seed ?? 0, HASH);
+			const id = `${String(HASH.w0)},${String(HASH.w1)},${String(HASH.w2)},${String(HASH.w3)}`;
+			if (seen.has(id)) continue;
+			seen.add(id);
+			distinct.push(key);
+		}
+		const f = CuckooFilter.create(Math.max(1, distinct.length), epsilon, options);
+		for (const k of distinct) f.add(k);
+		return f;
+	}
+	static fromBytes(bytes) {
+		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, PARAMS_SIZE, "cuckoo");
+		require_serialize.assertParamsPadding(body, PARAMS_FIELDS_END, PARAMS_SIZE, "cuckoo");
+		const view = new DataView(body.buffer, body.byteOffset, body.byteLength);
+		const params = {
+			n: view.getUint32(0, true),
+			seed: view.getUint32(4, true),
+			epsilon: view.getFloat64(8, true)
+		};
+		let filter;
+		try {
+			const f = view.getUint32(16, true);
+			const buckets = view.getUint32(20, true);
+			if (f < 4 || f > 32) throw new require_serialize.SerializationError(`cuckoo: stored f ${String(f)} is outside 4..${String(32)}`);
+			if (buckets < 1) throw new require_serialize.SerializationError("cuckoo: stored buckets is 0");
+			const m = f * SLOTS * buckets;
+			if (m > 4294967295) throw new require_serialize.SerializationError(`cuckoo: stored geometry gives m ${String(m)} bits, more than 2^32 - 1`);
+			const words = Math.ceil(m / 32);
+			require_serialize.assertBodyLength(body.length, PARAMS_SIZE + padded8(4 * words), "cuckoo");
+			restoring = {
+				f,
+				buckets
+			};
+			try {
+				filter = new CuckooFilter(params);
+			} finally {
+				restoring = void 0;
+			}
+		} catch (err) {
+			if (err instanceof require_params.ParamError) throw new require_serialize.SerializationError(`cuckoo: ${err.message}`);
+			throw err;
+		}
+		const words = filter.#words;
+		for (let w = 0; w < words.length; w++) words[w] = view.getUint32(PARAMS_SIZE + 4 * w, true);
+		const tail = filter.m % 32;
+		if (tail !== 0 && (words[words.length - 1] ?? 0) >>> tail !== 0) throw new require_serialize.SerializationError("cuckoo: bits set past the last slot");
+		if (body.subarray(PARAMS_SIZE + 4 * words.length).some((b) => b !== 0)) throw new require_serialize.SerializationError("cuckoo: slot padding is not zero");
+		const count = view.getUint32(24, true);
+		let occupied = 0;
+		for (let j = 0; j < filter.capacity; j++) if (filter.#slot(j) !== 0) occupied++;
+		if (count !== occupied) throw new require_serialize.SerializationError(`cuckoo: count ${String(count)} does not match ${String(occupied)} occupied slots`);
+		filter.#count = count;
+		return filter;
+	}
+	static fromJSON(value) {
+		return CuckooFilter.fromBytes(require_serialize.fromJSONEnvelope(value));
+	}
+	constructor({ n, epsilon, seed = 0 }) {
+		require_params.assertPositiveInt(n, "n");
+		require_params.assertUint32(n, "n");
+		require_params.assertProbability(epsilon, "epsilon");
+		require_params.assertUint32(seed, "seed");
+		const { f, buckets } = restoring ?? cuckooSizing(n, epsilon);
+		require_params.assertUint32(f * SLOTS * buckets, "m");
+		this.#n = n;
+		this.#epsilon = epsilon;
+		this.#seed = seed;
+		this.#f = f;
+		this.#buckets = buckets;
+		this.#mask = 2 ** f - 1;
+		this.#words = new Uint32Array(Math.ceil(f * SLOTS * buckets / 32));
+	}
+	add(key) {
+		this.#hash(key);
+		if (this.#replace(this.#i1, 0, this.#fp) || this.#replace(this.#i2, 0, this.#fp)) {
+			this.#count++;
+			return;
+		}
+		let i = (HASH.w2 & 1) === 0 ? this.#i1 : this.#i2;
+		let x = (HASH.w3 | 1) >>> 0;
+		let fp = this.#fp;
+		for (let kick = 0; kick < MAX_KICKS; kick++) {
+			x ^= x << 13;
+			x >>>= 0;
+			x ^= x >>> 17;
+			x ^= x << 5;
+			x >>>= 0;
+			const j = i * SLOTS + (x & 3);
+			const victim = this.#slot(j);
+			UNDO_SLOT[kick] = j;
+			UNDO_FP[kick] = victim;
+			this.#setSlot(j, fp);
+			fp = victim;
+			i = this.#alt(i, fp);
+			if (this.#replace(i, 0, fp)) {
+				this.#count++;
+				return;
+			}
+		}
+		for (let kick = 499; kick >= 0; kick--) this.#setSlot(UNDO_SLOT[kick] ?? 0, UNDO_FP[kick] ?? 0);
+		throw new CuckooFullError(`cuckoo filter is full at ${String(this.#count)} of ${String(this.capacity)} slots`);
+	}
+	delete(key) {
+		this.#hash(key);
+		const removed = this.#replace(this.#i1, this.#fp, 0) || this.#i2 !== this.#i1 && this.#replace(this.#i2, this.#fp, 0);
+		if (removed) this.#count--;
+		return removed;
+	}
+	has(key) {
+		this.#hash(key);
+		return this.#find(this.#i1, this.#fp) >= 0 || this.#find(this.#i2, this.#fp) >= 0;
+	}
+	rate() {
+		const occupied = 8 * this.#count / this.capacity;
+		return 1 - (1 - 1 / this.#mask) ** occupied;
+	}
+	toBytes() {
+		const words = this.#words;
+		return require_serialize.writeFrame({
+			version: 5,
+			type: TYPE,
+			flags: 0
+		}, PARAMS_SIZE, padded8(4 * words.length), (_, view) => {
+			view.setUint32(0, this.#n, true);
+			view.setUint32(4, this.#seed, true);
+			view.setFloat64(8, this.#epsilon, true);
+			view.setUint32(16, this.#f, true);
+			view.setUint32(20, this.#buckets, true);
+			view.setUint32(24, this.#count, true);
+			words.forEach((word, w) => {
+				view.setUint32(PARAMS_SIZE + 4 * w, word, true);
+			});
+		});
+	}
+	equals(other) {
+		return this.#n === other.#n && this.#epsilon === other.#epsilon && this.#seed === other.#seed && this.#count === other.#count && require_serialize.bytesEqual(wordBytes(this.#words), wordBytes(other.#words));
+	}
+	toJSON() {
+		return require_serialize.toJSONEnvelope(this.toBytes());
+	}
+	#hash(key) {
+		require_hasher.hash128KeyInto(key, this.#seed, HASH);
+		this.#fp = HASH.w1 >>> 32 - this.#f || 1;
+		this.#i1 = require_hasher.reduce(HASH.w0, this.#buckets);
+		this.#i2 = this.#alt(this.#i1, this.#fp);
+	}
+	#alt(i, fp) {
+		const b = this.#buckets;
+		return ((Math.imul(fp, 1540483477) >>> 0) % b + b - i) % b;
+	}
+	#find(bucket, value) {
+		for (let j = bucket * SLOTS; j < bucket * SLOTS + SLOTS; j++) if (this.#slot(j) === value) return j;
+		return -1;
+	}
+	#replace(bucket, from, to) {
+		const j = this.#find(bucket, from);
+		if (j < 0) return false;
+		this.#setSlot(j, to);
+		return true;
+	}
+	#slot(j) {
+		const bit = j * this.#f;
+		const w = bit >>> 5;
+		const off = bit & 31;
+		let v = (this.#words[w] ?? 0) >>> off;
+		if (off + this.#f > 32) v |= (this.#words[w + 1] ?? 0) << 32 - off;
+		return (v & this.#mask) >>> 0;
+	}
+	#setSlot(j, fp) {
+		const bit = j * this.#f;
+		const w = bit >>> 5;
+		const off = bit & 31;
+		const words = this.#words;
+		words[w] = (words[w] ?? 0) & ~(this.#mask << off) | fp << off;
+		if (off + this.#f > 32) {
+			const shift = 32 - off;
+			words[w + 1] = (words[w + 1] ?? 0) & ~(this.#mask >>> shift) | fp >>> shift;
+		}
+	}
+	get count() {
+		return this.#count;
+	}
+	get capacity() {
+		return SLOTS * this.#buckets;
+	}
+	get buckets() {
+		return this.#buckets;
+	}
+	get fingerprintBits() {
+		return this.#f;
+	}
+	get m() {
+		return this.#f * this.capacity;
+	}
+	get bitsPerKey() {
+		return this.m / this.#n;
+	}
+	get seed() {
+		return this.#seed;
+	}
+	get epsilon() {
+		return this.#epsilon;
+	}
+};
+//#endregion
+exports.BadMagicError = require_serialize.BadMagicError;
+exports.ChecksumError = require_serialize.ChecksumError;
+exports.CuckooFilter = CuckooFilter;
+exports.CuckooFullError = CuckooFullError;
+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;
+exports.UnknownVersionError = require_serialize.UnknownVersionError;
+exports.cuckooSizing = cuckooSizing;

package/dist/cuckoo/index.d.cts

@@ -0,0 +1,164 @@
+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/cuckoo/cuckoo.d.ts
+/** Thrown when an add cannot find room; the filter is left exactly as it was. */
+export declare class CuckooFullError extends Error {
+  /** Discriminates this error from other `Error`s. */
+  override readonly name = "CuckooFullError";
+}
+/** Settings for a {@link CuckooFilter}. */
+interface CuckooParams {
+  /** Expected number of keys. */
+  n: number;
+  /** Target false-positive rate at `n` keys, e.g. `0.01` for 1%. */
+  epsilon: number;
+  /** Hash seed; defaults to `0`. */
+  seed?: number;
+}
+/** The optional settings {@link CuckooFilter.create} takes after `n` and `epsilon`. */
+type CuckooOptions = Omit<CuckooParams, "n" | "epsilon">;
+/**
+ * A cuckoo filter: a set with a tunable false-positive rate, zero false
+ * negatives, and delete. Keys are stored as short fingerprints in one of two
+ * candidate buckets (Fan et al., "Cuckoo Filter: Practically Better Than
+ * Bloom", 2014).
+ */
+export declare class CuckooFilter {
+  #private;
+  /**
+   * 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%.
+   * @param options - Optional seed.
+   * @returns A new, empty filter.
+   */
+  static create(n: number, epsilon: number, options?: CuckooOptions): CuckooFilter;
+  /**
+   * Builds a filter from the given keys; duplicates are ignored. It is sized
+   * for the distinct keys at the target false-positive rate, and holds each
+   * once, so a key listed twice needs one delete.
+   *
+   * @param keys - The keys to insert.
+   * @param epsilon - Target false-positive rate, e.g. `0.01` for 1%.
+   * @param options - Optional seed.
+   * @returns A new filter containing every key.
+   */
+  static from(keys: Iterable<BytesLike>, epsilon: number, options?: CuckooOptions): CuckooFilter;
+  /**
+   * Restores a filter from its {@link CuckooFilter.toBytes} serialization.
+   *
+   * @param bytes - The serialized filter.
+   * @returns The reconstructed filter.
+   */
+  static fromBytes(bytes: Uint8Array): CuckooFilter;
+  /**
+   * Restores a filter from its {@link CuckooFilter.toJSON} envelope.
+   *
+   * @param value - The parsed JSON envelope.
+   * @returns The reconstructed filter.
+   */
+  static fromJSON(value: unknown): CuckooFilter;
+  /**
+   * Constructs a filter from {@link CuckooParams}.
+   *
+   * @throws {@link ParamError} if a setting is invalid.
+   */
+  constructor({ n, epsilon, seed }: CuckooParams);
+  /**
+   * Adds `key`. Every call stores a fingerprint, including for a key already
+   * present, so each add needs its own delete.
+   *
+   * @throws {@link CuckooFullError} if the filter has no room for it.
+   */
+  add(key: BytesLike): void;
+  /**
+   * Removes one copy of `key`: the first slot holding its fingerprint in
+   * either candidate bucket.
+   *
+   * Only delete keys you added. A key never added can share a fingerprint and
+   * bucket with one that was, and deleting it removes that key's fingerprint
+   * instead, a false negative the filter cannot detect: it stores fingerprints,
+   * not keys, so it cannot tell the two apart.
+   *
+   * @returns `true` if a matching fingerprint was removed; `false`, with the
+   * filter unchanged, if there was none.
+   */
+  delete(key: BytesLike): boolean;
+  /**
+   * Tests whether `key` may be in the filter.
+   *
+   * @returns `false` if `key` is definitely absent; `true` if it was added
+   * (and not deleted) or on a false positive.
+   */
+  has(key: BytesLike): boolean;
+  /**
+   * Estimates the current false-positive rate from the load: a query compares
+   * its fingerprint against about `8 * count / capacity` occupied slots across
+   * its two buckets, each matching with probability `1 / (2^f - 1)`.
+   *
+   * @returns The estimated false-positive rate, `0` for an empty filter.
+   */
+  rate(): number;
+  /**
+   * Serializes the filter to a DSTL type 7 frame, readable by
+   * {@link CuckooFilter.fromBytes} and by any reader of the documented format.
+   *
+   * @returns The frame bytes.
+   */
+  toBytes(): Uint8Array;
+  /**
+   * Whether `other` holds the same settings and slots, so the two serialize to
+   * identical bytes. Which slot a key lands in depends on insertion order, so
+   * filters holding the same keys can still differ.
+   *
+   * @param other - The filter to compare against.
+   * @returns `true` if the two are indistinguishable.
+   */
+  equals(other: CuckooFilter): boolean;
+  /**
+   * Serializes the filter as a JSON envelope around its {@link CuckooFilter.toBytes} frame.
+   *
+   * @returns The JSON-safe envelope.
+   */
+  toJSON(): FilterJSON;
+  /** Fingerprints stored, one per add not undone by a delete. */
+  get count(): number;
+  /** Slots in the table, `4 * buckets`. */
+  get capacity(): number;
+  /** Number of 4-slot buckets. */
+  get buckets(): number;
+  /** Width of each stored fingerprint, in bits. */
+  get fingerprintBits(): number;
+  /** Total slot bits, `fingerprintBits * capacity`. */
+  get m(): number;
+  /** Slot bits per expected key, `m / n`. */
+  get bitsPerKey(): number;
+  /** Hash seed. */
+  get seed(): number;
+  /** Target false-positive rate at `n` keys. */
+  get epsilon(): number;
+}
+//#endregion
+//#region src/cuckoo/sizing.d.ts
+/** Cuckoo filter geometry: what a sizing solve determines. */
+interface CuckooSizing {
+  /** Fingerprint width in bits. */
+  f: number;
+  /** Number of 4-slot buckets. */
+  buckets: number;
+  /** Slot bits per expected key, `4 * f * buckets / n`. */
+  bitsPerKey: number;
+}
+/**
+ * Cuckoo geometry for `n` keys at target FPR `epsilon`: `f` bits from the
+ * `2b / epsilon` bound with 4-slot buckets, and enough buckets for 95% load
+ * plus `sqrt(n)` slack. At exactly 95%, small tables fail to take `n` keys at
+ * about 0.6% of sizes (a few buckets collect more keys than they hold, which
+ * more kicks do not fix); the slack removed every failure in about 170k
+ * prototype runs and still leaves a million-key filter at 94.6% load.
+ */
+export declare function cuckooSizing(n: number, epsilon: number): CuckooSizing;
+//#endregion
+export { BadMagicError, ChecksumError, type CuckooOptions, type CuckooParams, type CuckooSizing, type FilterJSON, ParamError, ReservedBitsError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError };

package/dist/cuckoo/index.d.ts

@@ -0,0 +1,164 @@
+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/cuckoo/cuckoo.d.ts
+/** Thrown when an add cannot find room; the filter is left exactly as it was. */
+export declare class CuckooFullError extends Error {
+  /** Discriminates this error from other `Error`s. */
+  override readonly name = "CuckooFullError";
+}
+/** Settings for a {@link CuckooFilter}. */
+interface CuckooParams {
+  /** Expected number of keys. */
+  n: number;
+  /** Target false-positive rate at `n` keys, e.g. `0.01` for 1%. */
+  epsilon: number;
+  /** Hash seed; defaults to `0`. */
+  seed?: number;
+}
+/** The optional settings {@link CuckooFilter.create} takes after `n` and `epsilon`. */
+type CuckooOptions = Omit<CuckooParams, "n" | "epsilon">;
+/**
+ * A cuckoo filter: a set with a tunable false-positive rate, zero false
+ * negatives, and delete. Keys are stored as short fingerprints in one of two
+ * candidate buckets (Fan et al., "Cuckoo Filter: Practically Better Than
+ * Bloom", 2014).
+ */
+export declare class CuckooFilter {
+  #private;
+  /**
+   * 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%.
+   * @param options - Optional seed.
+   * @returns A new, empty filter.
+   */
+  static create(n: number, epsilon: number, options?: CuckooOptions): CuckooFilter;
+  /**
+   * Builds a filter from the given keys; duplicates are ignored. It is sized
+   * for the distinct keys at the target false-positive rate, and holds each
+   * once, so a key listed twice needs one delete.
+   *
+   * @param keys - The keys to insert.
+   * @param epsilon - Target false-positive rate, e.g. `0.01` for 1%.
+   * @param options - Optional seed.
+   * @returns A new filter containing every key.
+   */
+  static from(keys: Iterable<BytesLike>, epsilon: number, options?: CuckooOptions): CuckooFilter;
+  /**
+   * Restores a filter from its {@link CuckooFilter.toBytes} serialization.
+   *
+   * @param bytes - The serialized filter.
+   * @returns The reconstructed filter.
+   */
+  static fromBytes(bytes: Uint8Array): CuckooFilter;
+  /**
+   * Restores a filter from its {@link CuckooFilter.toJSON} envelope.
+   *
+   * @param value - The parsed JSON envelope.
+   * @returns The reconstructed filter.
+   */
+  static fromJSON(value: unknown): CuckooFilter;
+  /**
+   * Constructs a filter from {@link CuckooParams}.
+   *
+   * @throws {@link ParamError} if a setting is invalid.
+   */
+  constructor({ n, epsilon, seed }: CuckooParams);
+  /**
+   * Adds `key`. Every call stores a fingerprint, including for a key already
+   * present, so each add needs its own delete.
+   *
+   * @throws {@link CuckooFullError} if the filter has no room for it.
+   */
+  add(key: BytesLike): void;
+  /**
+   * Removes one copy of `key`: the first slot holding its fingerprint in
+   * either candidate bucket.
+   *
+   * Only delete keys you added. A key never added can share a fingerprint and
+   * bucket with one that was, and deleting it removes that key's fingerprint
+   * instead, a false negative the filter cannot detect: it stores fingerprints,
+   * not keys, so it cannot tell the two apart.
+   *
+   * @returns `true` if a matching fingerprint was removed; `false`, with the
+   * filter unchanged, if there was none.
+   */
+  delete(key: BytesLike): boolean;
+  /**
+   * Tests whether `key` may be in the filter.
+   *
+   * @returns `false` if `key` is definitely absent; `true` if it was added
+   * (and not deleted) or on a false positive.
+   */
+  has(key: BytesLike): boolean;
+  /**
+   * Estimates the current false-positive rate from the load: a query compares
+   * its fingerprint against about `8 * count / capacity` occupied slots across
+   * its two buckets, each matching with probability `1 / (2^f - 1)`.
+   *
+   * @returns The estimated false-positive rate, `0` for an empty filter.
+   */
+  rate(): number;
+  /**
+   * Serializes the filter to a DSTL type 7 frame, readable by
+   * {@link CuckooFilter.fromBytes} and by any reader of the documented format.
+   *
+   * @returns The frame bytes.
+   */
+  toBytes(): Uint8Array;
+  /**
+   * Whether `other` holds the same settings and slots, so the two serialize to
+   * identical bytes. Which slot a key lands in depends on insertion order, so
+   * filters holding the same keys can still differ.
+   *
+   * @param other - The filter to compare against.
+   * @returns `true` if the two are indistinguishable.
+   */
+  equals(other: CuckooFilter): boolean;
+  /**
+   * Serializes the filter as a JSON envelope around its {@link CuckooFilter.toBytes} frame.
+   *
+   * @returns The JSON-safe envelope.
+   */
+  toJSON(): FilterJSON;
+  /** Fingerprints stored, one per add not undone by a delete. */
+  get count(): number;
+  /** Slots in the table, `4 * buckets`. */
+  get capacity(): number;
+  /** Number of 4-slot buckets. */
+  get buckets(): number;
+  /** Width of each stored fingerprint, in bits. */
+  get fingerprintBits(): number;
+  /** Total slot bits, `fingerprintBits * capacity`. */
+  get m(): number;
+  /** Slot bits per expected key, `m / n`. */
+  get bitsPerKey(): number;
+  /** Hash seed. */
+  get seed(): number;
+  /** Target false-positive rate at `n` keys. */
+  get epsilon(): number;
+}
+//#endregion
+//#region src/cuckoo/sizing.d.ts
+/** Cuckoo filter geometry: what a sizing solve determines. */
+interface CuckooSizing {
+  /** Fingerprint width in bits. */
+  f: number;
+  /** Number of 4-slot buckets. */
+  buckets: number;
+  /** Slot bits per expected key, `4 * f * buckets / n`. */
+  bitsPerKey: number;
+}
+/**
+ * Cuckoo geometry for `n` keys at target FPR `epsilon`: `f` bits from the
+ * `2b / epsilon` bound with 4-slot buckets, and enough buckets for 95% load
+ * plus `sqrt(n)` slack. At exactly 95%, small tables fail to take `n` keys at
+ * about 0.6% of sizes (a few buckets collect more keys than they hold, which
+ * more kicks do not fix); the slack removed every failure in about 170k
+ * prototype runs and still leaves a million-key filter at 94.6% load.
+ */
+export declare function cuckooSizing(n: number, epsilon: number): CuckooSizing;
+//#endregion
+export { BadMagicError, ChecksumError, type CuckooOptions, type CuckooParams, type CuckooSizing, type FilterJSON, ParamError, ReservedBitsError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError };

package/dist/cuckoo/index.js

@@ -0,0 +1,267 @@
+import { i as hash128KeyInto, 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, o as assertUint32, r as assertPositiveInt, t as ParamError } from "../params-CeajSrwv.js";
+function cuckooSizing(n, epsilon) {
+	assertProbability(epsilon, "epsilon");
+	const f = Math.max(4, Math.ceil(Math.log2(8 / epsilon)));
+	if (f > 32) throw new ParamError(`epsilon ${String(epsilon)} needs a ${String(f)}-bit fingerprint, above the maximum ${String(32)} bits`);
+	const buckets = Math.ceil(n / 3.8) + Math.ceil(Math.sqrt(n));
+	return {
+		f,
+		buckets,
+		bitsPerKey: 4 * f * buckets / n
+	};
+}
+//#endregion
+//#region src/cuckoo/cuckoo.ts
+const TYPE = 7;
+const PARAMS_SIZE = 32;
+const PARAMS_FIELDS_END = 28;
+const padded8 = (length) => Math.ceil(length / 8) * 8;
+const wordBytes = (words) => new Uint8Array(words.buffer, words.byteOffset, words.byteLength);
+const SLOTS = 4;
+const MAX_KICKS = 500;
+const UNDO_SLOT = new Float64Array(MAX_KICKS);
+const UNDO_FP = new Uint32Array(MAX_KICKS);
+const HASH = {
+	w0: 0,
+	w1: 0,
+	w2: 0,
+	w3: 0
+};
+let restoring;
+var CuckooFullError = class extends Error {
+	name = "CuckooFullError";
+};
+var CuckooFilter = class CuckooFilter {
+	#n;
+	#epsilon;
+	#seed;
+	#f;
+	#buckets;
+	#mask;
+	#words;
+	#count = 0;
+	#fp = 0;
+	#i1 = 0;
+	#i2 = 0;
+	static create(n, epsilon, options = {}) {
+		return new CuckooFilter({
+			...options,
+			n,
+			epsilon
+		});
+	}
+	static from(keys, epsilon, options = {}) {
+		const seen = new Set();
+		const distinct = [];
+		for (const key of keys) {
+			hash128KeyInto(key, options.seed ?? 0, HASH);
+			const id = `${String(HASH.w0)},${String(HASH.w1)},${String(HASH.w2)},${String(HASH.w3)}`;
+			if (seen.has(id)) continue;
+			seen.add(id);
+			distinct.push(key);
+		}
+		const f = CuckooFilter.create(Math.max(1, distinct.length), epsilon, options);
+		for (const k of distinct) f.add(k);
+		return f;
+	}
+	static fromBytes(bytes) {
+		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, PARAMS_SIZE, "cuckoo");
+		assertParamsPadding(body, PARAMS_FIELDS_END, PARAMS_SIZE, "cuckoo");
+		const view = new DataView(body.buffer, body.byteOffset, body.byteLength);
+		const params = {
+			n: view.getUint32(0, true),
+			seed: view.getUint32(4, true),
+			epsilon: view.getFloat64(8, true)
+		};
+		let filter;
+		try {
+			const f = view.getUint32(16, true);
+			const buckets = view.getUint32(20, true);
+			if (f < 4 || f > 32) throw new SerializationError(`cuckoo: stored f ${String(f)} is outside 4..${String(32)}`);
+			if (buckets < 1) throw new SerializationError("cuckoo: stored buckets is 0");
+			const m = f * SLOTS * buckets;
+			if (m > 4294967295) throw new SerializationError(`cuckoo: stored geometry gives m ${String(m)} bits, more than 2^32 - 1`);
+			const words = Math.ceil(m / 32);
+			assertBodyLength(body.length, PARAMS_SIZE + padded8(4 * words), "cuckoo");
+			restoring = {
+				f,
+				buckets
+			};
+			try {
+				filter = new CuckooFilter(params);
+			} finally {
+				restoring = void 0;
+			}
+		} catch (err) {
+			if (err instanceof ParamError) throw new SerializationError(`cuckoo: ${err.message}`);
+			throw err;
+		}
+		const words = filter.#words;
+		for (let w = 0; w < words.length; w++) words[w] = view.getUint32(PARAMS_SIZE + 4 * w, true);
+		const tail = filter.m % 32;
+		if (tail !== 0 && (words[words.length - 1] ?? 0) >>> tail !== 0) throw new SerializationError("cuckoo: bits set past the last slot");
+		if (body.subarray(PARAMS_SIZE + 4 * words.length).some((b) => b !== 0)) throw new SerializationError("cuckoo: slot padding is not zero");
+		const count = view.getUint32(24, true);
+		let occupied = 0;
+		for (let j = 0; j < filter.capacity; j++) if (filter.#slot(j) !== 0) occupied++;
+		if (count !== occupied) throw new SerializationError(`cuckoo: count ${String(count)} does not match ${String(occupied)} occupied slots`);
+		filter.#count = count;
+		return filter;
+	}
+	static fromJSON(value) {
+		return CuckooFilter.fromBytes(fromJSONEnvelope(value));
+	}
+	constructor({ n, epsilon, seed = 0 }) {
+		assertPositiveInt(n, "n");
+		assertUint32(n, "n");
+		assertProbability(epsilon, "epsilon");
+		assertUint32(seed, "seed");
+		const { f, buckets } = restoring ?? cuckooSizing(n, epsilon);
+		assertUint32(f * SLOTS * buckets, "m");
+		this.#n = n;
+		this.#epsilon = epsilon;
+		this.#seed = seed;
+		this.#f = f;
+		this.#buckets = buckets;
+		this.#mask = 2 ** f - 1;
+		this.#words = new Uint32Array(Math.ceil(f * SLOTS * buckets / 32));
+	}
+	add(key) {
+		this.#hash(key);
+		if (this.#replace(this.#i1, 0, this.#fp) || this.#replace(this.#i2, 0, this.#fp)) {
+			this.#count++;
+			return;
+		}
+		let i = (HASH.w2 & 1) === 0 ? this.#i1 : this.#i2;
+		let x = (HASH.w3 | 1) >>> 0;
+		let fp = this.#fp;
+		for (let kick = 0; kick < MAX_KICKS; kick++) {
+			x ^= x << 13;
+			x >>>= 0;
+			x ^= x >>> 17;
+			x ^= x << 5;
+			x >>>= 0;
+			const j = i * SLOTS + (x & 3);
+			const victim = this.#slot(j);
+			UNDO_SLOT[kick] = j;
+			UNDO_FP[kick] = victim;
+			this.#setSlot(j, fp);
+			fp = victim;
+			i = this.#alt(i, fp);
+			if (this.#replace(i, 0, fp)) {
+				this.#count++;
+				return;
+			}
+		}
+		for (let kick = 499; kick >= 0; kick--) this.#setSlot(UNDO_SLOT[kick] ?? 0, UNDO_FP[kick] ?? 0);
+		throw new CuckooFullError(`cuckoo filter is full at ${String(this.#count)} of ${String(this.capacity)} slots`);
+	}
+	delete(key) {
+		this.#hash(key);
+		const removed = this.#replace(this.#i1, this.#fp, 0) || this.#i2 !== this.#i1 && this.#replace(this.#i2, this.#fp, 0);
+		if (removed) this.#count--;
+		return removed;
+	}
+	has(key) {
+		this.#hash(key);
+		return this.#find(this.#i1, this.#fp) >= 0 || this.#find(this.#i2, this.#fp) >= 0;
+	}
+	rate() {
+		const occupied = 8 * this.#count / this.capacity;
+		return 1 - (1 - 1 / this.#mask) ** occupied;
+	}
+	toBytes() {
+		const words = this.#words;
+		return writeFrame({
+			version: 5,
+			type: TYPE,
+			flags: 0
+		}, PARAMS_SIZE, padded8(4 * words.length), (_, view) => {
+			view.setUint32(0, this.#n, true);
+			view.setUint32(4, this.#seed, true);
+			view.setFloat64(8, this.#epsilon, true);
+			view.setUint32(16, this.#f, true);
+			view.setUint32(20, this.#buckets, true);
+			view.setUint32(24, this.#count, true);
+			words.forEach((word, w) => {
+				view.setUint32(PARAMS_SIZE + 4 * w, word, true);
+			});
+		});
+	}
+	equals(other) {
+		return this.#n === other.#n && this.#epsilon === other.#epsilon && this.#seed === other.#seed && this.#count === other.#count && bytesEqual(wordBytes(this.#words), wordBytes(other.#words));
+	}
+	toJSON() {
+		return toJSONEnvelope(this.toBytes());
+	}
+	#hash(key) {
+		hash128KeyInto(key, this.#seed, HASH);
+		this.#fp = HASH.w1 >>> 32 - this.#f || 1;
+		this.#i1 = reduce(HASH.w0, this.#buckets);
+		this.#i2 = this.#alt(this.#i1, this.#fp);
+	}
+	#alt(i, fp) {
+		const b = this.#buckets;
+		return ((Math.imul(fp, 1540483477) >>> 0) % b + b - i) % b;
+	}
+	#find(bucket, value) {
+		for (let j = bucket * SLOTS; j < bucket * SLOTS + SLOTS; j++) if (this.#slot(j) === value) return j;
+		return -1;
+	}
+	#replace(bucket, from, to) {
+		const j = this.#find(bucket, from);
+		if (j < 0) return false;
+		this.#setSlot(j, to);
+		return true;
+	}
+	#slot(j) {
+		const bit = j * this.#f;
+		const w = bit >>> 5;
+		const off = bit & 31;
+		let v = (this.#words[w] ?? 0) >>> off;
+		if (off + this.#f > 32) v |= (this.#words[w + 1] ?? 0) << 32 - off;
+		return (v & this.#mask) >>> 0;
+	}
+	#setSlot(j, fp) {
+		const bit = j * this.#f;
+		const w = bit >>> 5;
+		const off = bit & 31;
+		const words = this.#words;
+		words[w] = (words[w] ?? 0) & ~(this.#mask << off) | fp << off;
+		if (off + this.#f > 32) {
+			const shift = 32 - off;
+			words[w + 1] = (words[w + 1] ?? 0) & ~(this.#mask >>> shift) | fp >>> shift;
+		}
+	}
+	get count() {
+		return this.#count;
+	}
+	get capacity() {
+		return SLOTS * this.#buckets;
+	}
+	get buckets() {
+		return this.#buckets;
+	}
+	get fingerprintBits() {
+		return this.#f;
+	}
+	get m() {
+		return this.#f * this.capacity;
+	}
+	get bitsPerKey() {
+		return this.m / this.#n;
+	}
+	get seed() {
+		return this.#seed;
+	}
+	get epsilon() {
+		return this.#epsilon;
+	}
+};
+//#endregion
+export { BadMagicError, ChecksumError, CuckooFilter, CuckooFullError, ParamError, ReservedBitsError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError, cuckooSizing };

package/dist/index.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 //#endregion
 //#region src/index.ts
-const VERSION = "0.11.0";
+const VERSION = "0.12.0";
 //#endregion
 exports.VERSION = VERSION;

package/dist/index.js

@@ -1,5 +1,5 @@
 //#endregion
 //#region src/index.ts
-const VERSION = "0.11.0";
+const VERSION = "0.12.0";
 //#endregion
 export { VERSION };

package/dist/scalable/index.cjs

@@ -156,8 +156,11 @@ var ScalableBloomFilter = class ScalableBloomFilter {
 	}
 	#adopt(stages) {
 		this.#stages.length = 0;
-		this.#stages.push(...stages);
-		const k = Math.max(...stages.map((s) => s.k));
+		let k = 0;
+		for (const s of stages) {
+			this.#stages.push(s);
+			if (s.k > k) k = s.k;
+		}
 		if (k > this.#probes.length) this.#probes = new Uint32Array(k);
 		return stages.reduce((_, s) => s);
 	}
@@ -201,13 +204,6 @@ var ScalableBloomFilter = class ScalableBloomFilter {
 	}
 	union(other) {
 		this.#assertMergeable(other);
-		const result = new ScalableBloomFilter({
-			n: this.#n,
-			epsilon: this.#epsilon,
-			growth: this.#growth,
-			tightening: this.#tightening,
-			seed: this.#seed
-		});
 		const [longer, shorter] = this.#stages.length >= other.#stages.length ? [this.#stages, other.#stages] : [other.#stages, this.#stages];
 		const stages = longer.map((stage, i) => {
 			const bits = new require_bitset.BitSet(stage.m);
@@ -226,8 +222,13 @@ var ScalableBloomFilter = class ScalableBloomFilter {
 				count: Math.min(stage.capacity, stage.count + (twin?.count ?? 0))
 			};
 		});
-		result.#newest = result.#adopt(stages);
-		return result;
+		return ScalableBloomFilter.#withStages({
+			n: this.#n,
+			epsilon: this.#epsilon,
+			growth: this.#growth,
+			tightening: this.#tightening,
+			seed: this.#seed
+		}, stages);
 	}
 	equals(other) {
 		if (this.#settingPairs(other).some(([, a, b]) => a !== b)) return false;
@@ -252,18 +253,24 @@ var ScalableBloomFilter = class ScalableBloomFilter {
 		const entries = readTable(view, stageCount);
 		const expected = entries.reduce((sum, e) => sum + padded8(Math.ceil(e.m / 8)), tableEnd);
 		require_serialize.assertBodyLength(body.length, expected, "scalable");
-		restoring = readStages(body, entries, tableEnd);
+		const stages = readStages(body, entries, tableEnd);
 		try {
-			return new ScalableBloomFilter({
+			return ScalableBloomFilter.#withStages({
 				n: view.getUint32(0, true),
 				seed: view.getUint32(4, true),
 				epsilon: view.getFloat64(8, true),
 				growth: view.getFloat64(16, true),
 				tightening: view.getFloat64(24, true)
-			});
+			}, stages);
 		} catch (err) {
 			if (err instanceof require_params.ParamError) throw new require_serialize.SerializationError(`scalable: ${err.message}`);
 			throw err;
+		}
+	}
+	static #withStages(params, stages) {
+		restoring = stages;
+		try {
+			return new ScalableBloomFilter(params);
 		} finally {
 			restoring = void 0;
 		}

package/dist/scalable/index.js

@@ -155,8 +155,11 @@ var ScalableBloomFilter = class ScalableBloomFilter {
 	}
 	#adopt(stages) {
 		this.#stages.length = 0;
-		this.#stages.push(...stages);
-		const k = Math.max(...stages.map((s) => s.k));
+		let k = 0;
+		for (const s of stages) {
+			this.#stages.push(s);
+			if (s.k > k) k = s.k;
+		}
 		if (k > this.#probes.length) this.#probes = new Uint32Array(k);
 		return stages.reduce((_, s) => s);
 	}
@@ -200,13 +203,6 @@ var ScalableBloomFilter = class ScalableBloomFilter {
 	}
 	union(other) {
 		this.#assertMergeable(other);
-		const result = new ScalableBloomFilter({
-			n: this.#n,
-			epsilon: this.#epsilon,
-			growth: this.#growth,
-			tightening: this.#tightening,
-			seed: this.#seed
-		});
 		const [longer, shorter] = this.#stages.length >= other.#stages.length ? [this.#stages, other.#stages] : [other.#stages, this.#stages];
 		const stages = longer.map((stage, i) => {
 			const bits = new BitSet(stage.m);
@@ -225,8 +221,13 @@ var ScalableBloomFilter = class ScalableBloomFilter {
 				count: Math.min(stage.capacity, stage.count + (twin?.count ?? 0))
 			};
 		});
-		result.#newest = result.#adopt(stages);
-		return result;
+		return ScalableBloomFilter.#withStages({
+			n: this.#n,
+			epsilon: this.#epsilon,
+			growth: this.#growth,
+			tightening: this.#tightening,
+			seed: this.#seed
+		}, stages);
 	}
 	equals(other) {
 		if (this.#settingPairs(other).some(([, a, b]) => a !== b)) return false;
@@ -251,18 +252,24 @@ var ScalableBloomFilter = class ScalableBloomFilter {
 		const entries = readTable(view, stageCount);
 		const expected = entries.reduce((sum, e) => sum + padded8(Math.ceil(e.m / 8)), tableEnd);
 		assertBodyLength(body.length, expected, "scalable");
-		restoring = readStages(body, entries, tableEnd);
+		const stages = readStages(body, entries, tableEnd);
 		try {
-			return new ScalableBloomFilter({
+			return ScalableBloomFilter.#withStages({
 				n: view.getUint32(0, true),
 				seed: view.getUint32(4, true),
 				epsilon: view.getFloat64(8, true),
 				growth: view.getFloat64(16, true),
 				tightening: view.getFloat64(24, true)
-			});
+			}, stages);
 		} catch (err) {
 			if (err instanceof ParamError) throw new SerializationError(`scalable: ${err.message}`);
 			throw err;
+		}
+	}
+	static #withStages(params, stages) {
+		restoring = stages;
+		try {
+			return new ScalableBloomFilter(params);
 		} finally {
 			restoring = void 0;
 		}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "distillate",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Probabilistic data structures for JavaScript. Space-efficient, approximate-membership filters (Bloom, Blocked Bloom, Binary Fuse) with tunable error and a portable binary format; zero dependencies, universal.",
   "keywords": [
     "bloom-filter",
@@ -79,6 +79,14 @@
       "import": "./dist/scalable/index.js",
       "require": "./dist/scalable/index.cjs"
     },
+    "./cuckoo": {
+      "types": {
+        "import": "./dist/cuckoo/index.d.ts",
+        "require": "./dist/cuckoo/index.d.cts"
+      },
+      "import": "./dist/cuckoo/index.js",
+      "require": "./dist/cuckoo/index.cjs"
+    },
     "./package.json": "./package.json"
   },
   "main": "./dist/index.cjs",