distillate 0.11.0 → 0.13.0

package/dist/countmin/index.js

@@ -0,0 +1,182 @@
+import { a as hash32x2Into, s as probeAt } 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 { o as assertUint32, r as assertPositiveInt, t as ParamError } from "../params-CeajSrwv.js";
+import { n as countMinSizing } from "../sizing-D3-_7pdP.js";
+//#region src/countmin/countmin.ts
+const TYPE = 8;
+const PARAMS_SIZE = 16;
+const PARAMS_FIELDS_END = 12;
+const counterBytes = (counters) => new Uint8Array(counters.buffer, counters.byteOffset, counters.byteLength);
+function rowSum(counters, width, depth) {
+	let expected = 0;
+	for (let r = 0; r < depth; r++) {
+		let sum = 0;
+		const from = r * width;
+		for (let c = from; c < from + width; c++) sum += counters[c] ?? 0;
+		if (sum > Number.MAX_SAFE_INTEGER) throw new SerializationError(`countmin: row ${String(r)} sums to ${String(sum)}, past the safe integer range`);
+		if (r === 0) expected = sum;
+		else if (sum !== expected) throw new SerializationError(`countmin: row ${String(r)} sums to ${String(sum)}, but row 0 sums to ${String(expected)}`);
+	}
+	return expected;
+}
+var CountMinParamMismatchError = class extends Error {
+	name = "CountMinParamMismatchError";
+};
+var CountMinOverflowError = class extends RangeError {
+	name = "CountMinOverflowError";
+};
+var CountMinSketch = class CountMinSketch {
+	#counters;
+	#width;
+	#depth;
+	#seed;
+	#words = new Uint32Array(2);
+	#positions;
+	#total = 0;
+	static create(epsilon, delta, options = {}) {
+		return new CountMinSketch({
+			...options,
+			...countMinSizing(epsilon, delta)
+		});
+	}
+	static from(keys, epsilon, delta, options = {}) {
+		const sketch = CountMinSketch.create(epsilon, delta, options);
+		for (const key of keys) sketch.add(key);
+		return sketch;
+	}
+	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, "countmin");
+		assertParamsPadding(body, PARAMS_FIELDS_END, PARAMS_SIZE, "countmin");
+		const view = new DataView(body.buffer, body.byteOffset, body.byteLength);
+		const width = view.getUint32(0, true);
+		const depth = view.getUint32(4, true);
+		const seed = view.getUint32(8, true);
+		assertBodyLength(body.length, PARAMS_SIZE + 4 * width * depth, "countmin");
+		let sketch;
+		try {
+			sketch = new CountMinSketch({
+				width,
+				depth,
+				seed
+			});
+		} catch (err) {
+			if (err instanceof ParamError) throw new SerializationError(`countmin: ${err.message}`);
+			throw err;
+		}
+		const counters = sketch.#counters;
+		for (let i = 0; i < counters.length; i++) counters[i] = view.getUint32(PARAMS_SIZE + 4 * i, true);
+		sketch.#total = rowSum(counters, width, depth);
+		return sketch;
+	}
+	constructor({ width, depth, seed = 0 }) {
+		assertPositiveInt(width, "width");
+		assertUint32(width, "width");
+		assertPositiveInt(depth, "depth");
+		assertUint32(depth, "depth");
+		assertUint32(seed, "seed");
+		if (width * depth > 4294967295) throw new ParamError(`width ${String(width)} by depth ${String(depth)} needs ${String(width * depth)} counters, above the maximum ${String(4294967295)}`);
+		this.#counters = new Uint32Array(width * depth);
+		this.#positions = new Uint32Array(depth);
+		this.#width = width;
+		this.#depth = depth;
+		this.#seed = seed;
+	}
+	get width() {
+		return this.#width;
+	}
+	get depth() {
+		return this.#depth;
+	}
+	get seed() {
+		return this.#seed;
+	}
+	get total() {
+		return this.#total;
+	}
+	get epsilon() {
+		return Math.E / this.#width;
+	}
+	get delta() {
+		return Math.exp(-this.#depth);
+	}
+	error() {
+		return this.epsilon * this.#total;
+	}
+	#positionAt(row) {
+		return row * this.#width + probeAt(this.#words[0] ?? 0, this.#words[1] ?? 0, row, this.#width);
+	}
+	add(key, count = 1) {
+		assertPositiveInt(count, "count");
+		if (this.#total + count > Number.MAX_SAFE_INTEGER) throw new CountMinOverflowError(`adding ${String(count)} would carry the total past ${String(Number.MAX_SAFE_INTEGER)}`);
+		hash32x2Into(key, this.#seed, this.#words);
+		const headroom = 4294967295 - count;
+		for (let r = 0; r < this.#depth; r++) {
+			const at = this.#positionAt(r);
+			if ((this.#counters[at] ?? 0) > headroom) throw new CountMinOverflowError(`adding ${String(count)} would carry a counter past ${String(4294967295)}`);
+			this.#positions[r] = at;
+		}
+		for (let r = 0; r < this.#depth; r++) {
+			const at = this.#positions[r] ?? 0;
+			this.#counters[at] = (this.#counters[at] ?? 0) + count;
+		}
+		this.#total += count;
+	}
+	union(other) {
+		if (this.#width !== other.#width || this.#depth !== other.#depth || this.#seed !== other.#seed) throw new CountMinParamMismatchError("cannot union Count-Min sketches whose parameters do not match");
+		if (this.#total + other.#total > Number.MAX_SAFE_INTEGER) throw new CountMinOverflowError(`union would carry the total past ${String(Number.MAX_SAFE_INTEGER)}`);
+		const mine = this.#counters;
+		const theirs = other.#counters;
+		const merged = new CountMinSketch({
+			width: this.#width,
+			depth: this.#depth,
+			seed: this.#seed
+		});
+		const into = merged.#counters;
+		for (let i = 0; i < into.length; i++) {
+			const sum = (mine[i] ?? 0) + (theirs[i] ?? 0);
+			if (sum > 4294967295) throw new CountMinOverflowError(`union would carry a counter to ${String(sum)}, past ${String(4294967295)}`);
+			into[i] = sum;
+		}
+		merged.#total = this.#total + other.#total;
+		return merged;
+	}
+	toBytes() {
+		const counters = this.#counters;
+		return writeFrame({
+			version: 5,
+			type: TYPE,
+			flags: 0
+		}, PARAMS_SIZE, 4 * counters.length, (_, view) => {
+			view.setUint32(0, this.#width, true);
+			view.setUint32(4, this.#depth, true);
+			view.setUint32(8, this.#seed, true);
+			counters.forEach((c, i) => {
+				view.setUint32(PARAMS_SIZE + 4 * i, c, true);
+			});
+		});
+	}
+	equals(other) {
+		if (this.#width !== other.#width || this.#depth !== other.#depth || this.#seed !== other.#seed) return false;
+		return bytesEqual(counterBytes(this.#counters), counterBytes(other.#counters));
+	}
+	toJSON() {
+		return toJSONEnvelope(this.toBytes());
+	}
+	static fromJSON(value) {
+		return CountMinSketch.fromBytes(fromJSONEnvelope(value));
+	}
+	count(key) {
+		hash32x2Into(key, this.#seed, this.#words);
+		let min = Infinity;
+		for (let r = 0; r < this.#depth; r++) {
+			const at = this.#counters[this.#positionAt(r)] ?? 0;
+			if (at < min) min = at;
+		}
+		return min;
+	}
+};
+//#endregion
+export { BadMagicError, ChecksumError, CountMinOverflowError, CountMinParamMismatchError, CountMinSketch, ParamError, ReservedBitsError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError, countMinSizing };

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 && this.#f === other.#f && this.#buckets === other.#buckets && 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 };