distillate 0.10.0 → 0.11.0

package/README.md

@@ -42,12 +42,13 @@ Every push runs a CI smoke matrix that imports the built package on Node 22/24,
 
 Each structure ships as its own subpath, so you only bundle what you import.
 
-| Import               | Structure     | Answers            | Use for                                                  |
-| -------------------- | ------------- | ------------------ | -------------------------------------------------------- |
-| `distillate/bloom`   | Classic Bloom | seen this key?     | Familiar default, migration from `bloom-filters`         |
-| `distillate/blocked` | Blocked Bloom | seen this key?     | Faster lookups and a lower FPR for a small space premium |
-| `distillate/fuse`    | Binary Fuse   | seen this key?     | Static set built once and queried a lot; least space     |
-| `distillate/hll`     | HyperLogLog   | how many distinct? | Counting distinct users, IPs, or keys in fixed space     |
+| Import                | Structure      | Answers            | Use for                                                  |
+| --------------------- | -------------- | ------------------ | -------------------------------------------------------- |
+| `distillate/bloom`    | Classic Bloom  | seen this key?     | Familiar default, migration from `bloom-filters`         |
+| `distillate/scalable` | Scalable Bloom | seen this key?     | Key count unknown or growing; keeps its FPR bound        |
+| `distillate/blocked`  | Blocked Bloom  | seen this key?     | Faster lookups and a lower FPR for a small space premium |
+| `distillate/fuse`     | Binary Fuse    | seen this key?     | Static set built once and queried a lot; least space     |
+| `distillate/hll`      | HyperLogLog    | how many distinct? | Counting distinct users, IPs, or keys in fixed space     |
 
 The filters are mutable except Binary Fuse, which is built once from the whole
 key set. HyperLogLog is not a filter: it counts distinct keys and cannot report
@@ -69,6 +70,24 @@ const restored = BloomFilter.fromBytes(bytes);
 
 Also: `union(other)` (merge equal-parameter filters), `bitsPerKey`, and a low-level `new BloomFilter({ m, k, seed })`.
 
+### Scalable Bloom (`distillate/scalable`)
+
+For when you cannot say how many keys are coming. It grows by opening larger, tighter Bloom stages as keys arrive, and keeps its false-positive rate under the target however many open. Full API and trade-offs: [Scalable Bloom guide](https://distillate.akxp.net/guides/scalable/).
+
+```ts
+import { ScalableBloomFilter } from "distillate/scalable";
+
+const seen = ScalableBloomFilter.create(10, 0.01); // first stage, target FPR
+for (let i = 0; i < 30; i++) seen.add(`key-${String(i)}`);
+
+seen.stages; // 2
+seen.has("key-29"); // true
+```
+
+A key already held is not counted again, so duplicates never use up capacity. It costs more bits per key than a Classic Bloom sized for a known `n`; if you know `n`, use that.
+
+Also: `from(keys, epsilon)`, `union`, `equals`, `rate`, `toBytes` / `fromBytes`, `toJSON` / `fromJSON`, and `growth` / `tightening` / `seed` options.
+
 ### Blocked Bloom (`distillate/blocked`)
 
 ```ts

package/dist/bitset-Cf2jwRJX.js

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

package/dist/bitset-QYGqxnEf.cjs

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

package/dist/blocked/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_hasher = require("../hasher-D8LCBTOM.cjs");
+const require_hasher = require("../hasher-MhY7aQ8F.cjs");
 const require_serialize = require("../serialize-CHikZ4GH.cjs");
 const require_params = require("../params-UTZbJ22c.cjs");
 //#region src/blocked/blocked.ts

package/dist/blocked/index.js

@@ -1,4 +1,4 @@
-import { a as hash32x2Into, c as reduce } from "../hasher-DVWXS_vJ.js";
+import { a as hash32x2Into, u as reduce } from "../hasher-3Cyn7Yg-.js";
 import { a as TruncatedError, c as assertBodyLength, d as bytesEqual, f as fromJSONEnvelope, g as writeFrame, h as toJSONEnvelope, i as SerializationError, l as assertMinBodyLength, m as readHeader, n as ChecksumError, o as UnknownHashVariantError, r as ReservedBitsError, s as UnknownVersionError, t as BadMagicError, u as assertParamsPadding } from "../serialize-CMSYFym-.js";
 import { i as assertProbability, n as assertPositiveFinite, o as assertUint32, r as assertPositiveInt, t as ParamError } from "../params-CeajSrwv.js";
 //#region src/blocked/blocked.ts

package/dist/bloom/index.cjs

@@ -1,39 +1,9 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_hasher = require("../hasher-D8LCBTOM.cjs");
+const require_bitset = require("../bitset-QYGqxnEf.cjs");
+const require_hasher = require("../hasher-MhY7aQ8F.cjs");
 const require_serialize = require("../serialize-CHikZ4GH.cjs");
 const require_params = require("../params-UTZbJ22c.cjs");
 const require_sizing = require("../sizing-BLzZk2zr.cjs");
-//#region src/core/bitset.ts
-var BitSetRangeError = class extends RangeError {
-	name = "BitSetRangeError";
-};
-const MAX_BITS = 2 ** 32;
-var BitSet = class {
-	#bits;
-	constructor(nbits) {
-		if (nbits > MAX_BITS) throw new BitSetRangeError(`BitSet capacity ${String(nbits)} exceeds the 2^32-bit limit`);
-		this.#bits = new Uint8Array(Math.ceil(nbits / 8));
-	}
-	set(i) {
-		const idx = i >>> 3;
-		this.#bits[idx] = (this.#bits[idx] ?? 0) | 1 << (i & 7);
-	}
-	get(i) {
-		return ((this.#bits[i >>> 3] ?? 0) & 1 << (i & 7)) !== 0;
-	}
-	get bytes() {
-		return this.#bits;
-	}
-	count() {
-		let total = 0;
-		for (let byte of this.#bits) while (byte) {
-			byte &= byte - 1;
-			total++;
-		}
-		return total;
-	}
-};
-//#endregion
 //#region src/bloom/bloom.ts
 const TYPE = 1;
 const PARAMS_SIZE = 16;
@@ -94,7 +64,7 @@ var BloomFilter = class BloomFilter {
 			require_params.assertPositiveInt(n, "n");
 			require_params.assertUint32(n, "n");
 		}
-		this.#bits = new BitSet(m);
+		this.#bits = new require_bitset.BitSet(m);
 		this.#m = m;
 		this.#k = k;
 		this.#seed = seed;

package/dist/bloom/index.js

@@ -1,38 +1,8 @@
-import { s as probeInto } from "../hasher-DVWXS_vJ.js";
+import { t as BitSet } from "../bitset-Cf2jwRJX.js";
+import { c as probeInto } from "../hasher-3Cyn7Yg-.js";
 import { a as TruncatedError, c as assertBodyLength, d as bytesEqual, f as fromJSONEnvelope, g as writeFrame, h as toJSONEnvelope, i as SerializationError, l as assertMinBodyLength, m as readHeader, n as ChecksumError, o as UnknownHashVariantError, r as ReservedBitsError, s as UnknownVersionError, t as BadMagicError, u as assertParamsPadding } from "../serialize-CMSYFym-.js";
 import { a as assertUint16, i as assertProbability, o as assertUint32, r as assertPositiveInt, t as ParamError } from "../params-CeajSrwv.js";
 import { t as bloomSizing } from "../sizing-BtUrtvF_.js";
-//#region src/core/bitset.ts
-var BitSetRangeError = class extends RangeError {
-	name = "BitSetRangeError";
-};
-const MAX_BITS = 2 ** 32;
-var BitSet = class {
-	#bits;
-	constructor(nbits) {
-		if (nbits > MAX_BITS) throw new BitSetRangeError(`BitSet capacity ${String(nbits)} exceeds the 2^32-bit limit`);
-		this.#bits = new Uint8Array(Math.ceil(nbits / 8));
-	}
-	set(i) {
-		const idx = i >>> 3;
-		this.#bits[idx] = (this.#bits[idx] ?? 0) | 1 << (i & 7);
-	}
-	get(i) {
-		return ((this.#bits[i >>> 3] ?? 0) & 1 << (i & 7)) !== 0;
-	}
-	get bytes() {
-		return this.#bits;
-	}
-	count() {
-		let total = 0;
-		for (let byte of this.#bits) while (byte) {
-			byte &= byte - 1;
-			total++;
-		}
-		return total;
-	}
-};
-//#endregion
 //#region src/bloom/bloom.ts
 const TYPE = 1;
 const PARAMS_SIZE = 16;

package/dist/fuse/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_hasher = require("../hasher-D8LCBTOM.cjs");
+const require_hasher = require("../hasher-MhY7aQ8F.cjs");
 const require_serialize = require("../serialize-CHikZ4GH.cjs");
 //#region src/fuse/fuse.ts
 const ARITY = 3;

package/dist/fuse/index.js

@@ -1,4 +1,4 @@
-import { i as hash128KeyInto, n as RLO, o as mul64, r as fmix64, t as RHI } from "../hasher-DVWXS_vJ.js";
+import { i as hash128KeyInto, n as RLO, o as mul64, r as fmix64, t as RHI } 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 } from "../serialize-CMSYFym-.js";
 //#region src/fuse/fuse.ts
 const ARITY = 3;

package/dist/{hasher-DVWXS_vJ.js → hasher-3Cyn7Yg-.js}

@@ -216,14 +216,15 @@ function hash32x2Into(key, seed, out) {
 	out[0] = LANES.w0;
 	out[1] = LANES.w1;
 }
+function probeAt(a, b, i, range) {
+	return reduce(a + Math.imul(i, b) + i * i >>> 0, range);
+}
+function probeLanesInto(a, b, count, range, out) {
+	for (let i = 0; i < count; i++) out[i] = probeAt(a, b, i, range);
+}
 function probeInto(key, count, range, seed, out) {
 	keyToLanes(key, seed);
-	const a = LANES.w0;
-	const b = LANES.w1;
-	for (let i = 0; i < count; i++) {
-		const x = a + Math.imul(i, b) + i * i >>> 0;
-		out[i] = reduce(x, range);
-	}
+	probeLanesInto(LANES.w0, LANES.w1, count, range, out);
 }
 //#endregion
-export { hash32x2Into as a, reduce as c, hash128KeyInto as i, RLO as n, mul64 as o, fmix64 as r, probeInto as s, RHI as t };
+export { hash32x2Into as a, probeInto as c, hash128KeyInto as i, probeLanesInto as l, RLO as n, mul64 as o, fmix64 as r, probeAt as s, RHI as t, reduce as u };

package/dist/{hasher-D8LCBTOM.cjs → hasher-MhY7aQ8F.cjs}

@@ -216,14 +216,15 @@ function hash32x2Into(key, seed, out) {
 	out[0] = LANES.w0;
 	out[1] = LANES.w1;
 }
+function probeAt(a, b, i, range) {
+	return reduce(a + Math.imul(i, b) + i * i >>> 0, range);
+}
+function probeLanesInto(a, b, count, range, out) {
+	for (let i = 0; i < count; i++) out[i] = probeAt(a, b, i, range);
+}
 function probeInto(key, count, range, seed, out) {
 	keyToLanes(key, seed);
-	const a = LANES.w0;
-	const b = LANES.w1;
-	for (let i = 0; i < count; i++) {
-		const x = a + Math.imul(i, b) + i * i >>> 0;
-		out[i] = reduce(x, range);
-	}
+	probeLanesInto(LANES.w0, LANES.w1, count, range, out);
 }
 //#endregion
 Object.defineProperty(exports, "RHI", {
@@ -262,12 +263,24 @@ Object.defineProperty(exports, "mul64", {
 		return mul64;
 	}
 });
+Object.defineProperty(exports, "probeAt", {
+	enumerable: true,
+	get: function() {
+		return probeAt;
+	}
+});
 Object.defineProperty(exports, "probeInto", {
 	enumerable: true,
 	get: function() {
 		return probeInto;
 	}
 });
+Object.defineProperty(exports, "probeLanesInto", {
+	enumerable: true,
+	get: function() {
+		return probeLanesInto;
+	}
+});
 Object.defineProperty(exports, "reduce", {
 	enumerable: true,
 	get: function() {

package/dist/hll/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_hasher = require("../hasher-D8LCBTOM.cjs");
+const require_hasher = require("../hasher-MhY7aQ8F.cjs");
 const require_serialize = require("../serialize-CHikZ4GH.cjs");
 const require_params = require("../params-UTZbJ22c.cjs");
 const require_sizing = require("../sizing-BLzZk2zr.cjs");

package/dist/hll/index.js

@@ -1,4 +1,4 @@
-import { i as hash128KeyInto } from "../hasher-DVWXS_vJ.js";
+import { i as hash128KeyInto } from "../hasher-3Cyn7Yg-.js";
 import { a as TruncatedError, c as assertBodyLength, 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, t as ParamError } from "../params-CeajSrwv.js";
 import { n as hllSizing } from "../sizing-BtUrtvF_.js";

package/dist/index.cjs

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

package/dist/index.js

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

package/dist/scalable/index.cjs

@@ -0,0 +1,340 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_bitset = require("../bitset-QYGqxnEf.cjs");
+const require_hasher = require("../hasher-MhY7aQ8F.cjs");
+const require_serialize = require("../serialize-CHikZ4GH.cjs");
+const require_params = require("../params-UTZbJ22c.cjs");
+const require_sizing = require("../sizing-BLzZk2zr.cjs");
+//#region src/scalable/scalable.ts
+const MAX_BITS = 4294967295;
+const TYPE = 6;
+const PARAMS_SIZE = 40;
+const ENTRY_SIZE = 16;
+const padded8 = (bytes) => Math.ceil(bytes / 8) * 8;
+let restoring;
+var ScalableParamMismatchError = class extends Error {
+	name = "ScalableParamMismatchError";
+};
+function readTable(view, stageCount) {
+	const entries = [];
+	for (let i = 0; i < stageCount; i++) {
+		const at = PARAMS_SIZE + ENTRY_SIZE * i;
+		const entry = {
+			m: view.getUint32(at, true),
+			k: view.getUint16(at + 4, true),
+			capacity: view.getUint32(at + 8, true),
+			count: view.getUint32(at + 12, true)
+		};
+		if (view.getUint16(at + 6, true) !== 0) throw new require_serialize.SerializationError(`scalable: stage ${String(i)} table padding is not zero`);
+		if (entry.m === 0 || entry.k === 0 || entry.capacity === 0) throw new require_serialize.SerializationError(`scalable: stage ${String(i)} declares m=${String(entry.m)}, k=${String(entry.k)}, capacity=${String(entry.capacity)}; all must be positive`);
+		if (entry.count > entry.capacity) throw new require_serialize.SerializationError(`scalable: stage ${String(i)} holds ${String(entry.count)} keys, above its capacity of ${String(entry.capacity)}`);
+		entries.push(entry);
+	}
+	return entries;
+}
+function readStages(body, entries, start) {
+	let at = start;
+	return entries.map((entry, i) => {
+		const length = Math.ceil(entry.m / 8);
+		const bits = new require_bitset.BitSet(entry.m);
+		bits.bytes.set(body.subarray(at, at + length));
+		for (let j = at + length; j < at + padded8(length); j++) if (body[j] !== 0) throw new require_serialize.SerializationError(`scalable: stage ${String(i)} bit padding is not zero`);
+		at += padded8(length);
+		return {
+			...entry,
+			bits
+		};
+	});
+}
+var ScalableBloomFilter = class ScalableBloomFilter {
+	#n;
+	#epsilon;
+	#growth;
+	#tightening;
+	#seed;
+	#stages = [];
+	#hash = {
+		w0: 0,
+		w1: 0,
+		w2: 0,
+		w3: 0
+	};
+	#probes = new Uint32Array(0);
+	#newest;
+	static create(n, epsilon, options = {}) {
+		return new ScalableBloomFilter({
+			...options,
+			n,
+			epsilon
+		});
+	}
+	static from(keys, epsilon, options = {}) {
+		const arr = [...keys];
+		const f = ScalableBloomFilter.create(Math.max(1, arr.length), epsilon, options);
+		for (const key of arr) f.add(key);
+		return f;
+	}
+	constructor({ n, epsilon, growth = 2, tightening = .85, seed = 0 }) {
+		require_params.assertPositiveInt(n, "n");
+		require_params.assertUint32(n, "n");
+		require_params.assertProbability(epsilon, "epsilon");
+		if (!Number.isFinite(growth) || growth <= 1) throw new require_params.ParamError(`growth must be a finite number greater than 1, got ${String(growth)}`);
+		require_params.assertProbability(tightening, "tightening");
+		require_params.assertUint32(seed, "seed");
+		this.#n = n;
+		this.#epsilon = epsilon;
+		this.#growth = growth;
+		this.#tightening = tightening;
+		this.#seed = seed;
+		if (restoring) {
+			this.#newest = this.#adopt(restoring);
+			return;
+		}
+		const first = this.#geometry(0);
+		if (first.m > MAX_BITS) throw new require_params.ParamError(`the first stage needs ${String(first.m)} bits, more than ${String(MAX_BITS)}`);
+		this.#newest = this.#open(first);
+	}
+	#geometry(i) {
+		const capacity = Math.ceil(this.#n * this.#growth ** i);
+		const target = this.#epsilon * (1 - this.#tightening) * this.#tightening ** i;
+		return {
+			capacity,
+			...require_sizing.bloomSizing(capacity, target)
+		};
+	}
+	#open({ capacity, m, k }) {
+		const stage = {
+			bits: new require_bitset.BitSet(m),
+			m,
+			k,
+			capacity,
+			count: 0
+		};
+		this.#stages.push(stage);
+		if (k > this.#probes.length) this.#probes = new Uint32Array(k);
+		return stage;
+	}
+	#settingPairs(other) {
+		return [
+			[
+				"n",
+				this.#n,
+				other.#n
+			],
+			[
+				"epsilon",
+				this.#epsilon,
+				other.#epsilon
+			],
+			[
+				"growth",
+				this.#growth,
+				other.#growth
+			],
+			[
+				"tightening",
+				this.#tightening,
+				other.#tightening
+			],
+			[
+				"seed",
+				this.#seed,
+				other.#seed
+			]
+		];
+	}
+	#assertMergeable(other) {
+		for (const [name, a, b] of this.#settingPairs(other)) if (a !== b) throw new ScalableParamMismatchError(`cannot union scalable Bloom filters whose ${name} differs (${String(a)} vs ${String(b)})`);
+		this.#stages.forEach((s, i) => {
+			const t = other.#stages[i];
+			if (!t) return;
+			for (const field of [
+				"m",
+				"k",
+				"capacity"
+			]) if (s[field] !== t[field]) throw new ScalableParamMismatchError(`cannot union scalable Bloom filters whose stage ${String(i)} ${field} differs (${String(s[field])} vs ${String(t[field])})`);
+		});
+	}
+	#adopt(stages) {
+		this.#stages.length = 0;
+		this.#stages.push(...stages);
+		const k = Math.max(...stages.map((s) => s.k));
+		if (k > this.#probes.length) this.#probes = new Uint32Array(k);
+		return stages.reduce((_, s) => s);
+	}
+	#probe(stage) {
+		require_hasher.probeLanesInto(this.#hash.w0, this.#hash.w1, stage.k, stage.m, this.#probes);
+	}
+	#holds(stage) {
+		const { w0, w1 } = this.#hash;
+		for (let i = 0; i < stage.k; i++) if (!stage.bits.get(require_hasher.probeAt(w0, w1, i, stage.m))) return false;
+		return true;
+	}
+	#anyHolds() {
+		for (let i = this.#stages.length - 1; i >= 0; i--) {
+			const stage = this.#stages[i];
+			if (stage && this.#holds(stage)) return true;
+		}
+		return false;
+	}
+	add(key) {
+		require_hasher.hash128KeyInto(key, this.#seed, this.#hash);
+		if (this.#anyHolds()) return;
+		if (this.#newest.count >= this.#newest.capacity) {
+			const i = this.#stages.length;
+			const next = this.#geometry(i);
+			if (next.m > MAX_BITS) throw new RangeError(`stage ${String(i)} needs ${String(next.m)} bits, more than ${String(MAX_BITS)}; the filter cannot grow further`);
+			this.#newest = this.#open(next);
+		}
+		const stage = this.#newest;
+		this.#probe(stage);
+		for (let i = 0; i < stage.k; i++) stage.bits.set(this.#probes[i] ?? 0);
+		stage.count++;
+	}
+	has(key) {
+		require_hasher.hash128KeyInto(key, this.#seed, this.#hash);
+		return this.#anyHolds();
+	}
+	rate() {
+		let miss = 1;
+		for (const s of this.#stages) miss *= 1 - (s.bits.count() / s.m) ** s.k;
+		return 1 - miss;
+	}
+	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);
+			bits.bytes.set(stage.bits.bytes);
+			const twin = shorter[i];
+			if (twin) {
+				const out = bits.bytes;
+				const bytes = twin.bits.bytes;
+				for (let j = 0; j < out.length; j++) out[j] = (out[j] ?? 0) | (bytes[j] ?? 0);
+			}
+			return {
+				bits,
+				m: stage.m,
+				k: stage.k,
+				capacity: stage.capacity,
+				count: Math.min(stage.capacity, stage.count + (twin?.count ?? 0))
+			};
+		});
+		result.#newest = result.#adopt(stages);
+		return result;
+	}
+	equals(other) {
+		if (this.#settingPairs(other).some(([, a, b]) => a !== b)) return false;
+		if (this.#stages.length !== other.#stages.length) return false;
+		return this.#stages.every((s, i) => {
+			const t = other.#stages[i];
+			if (!t) return false;
+			return s.m === t.m && s.k === t.k && s.capacity === t.capacity && s.count === t.count && require_serialize.bytesEqual(s.bits.bytes, t.bits.bytes);
+		});
+	}
+	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, "scalable");
+		require_serialize.assertParamsPadding(body, 36, PARAMS_SIZE, "scalable");
+		const view = new DataView(body.buffer, body.byteOffset, body.byteLength);
+		const stageCount = view.getUint32(32, true);
+		if (stageCount === 0) throw new require_serialize.SerializationError("scalable: frame declares no stages");
+		const tableEnd = PARAMS_SIZE + ENTRY_SIZE * stageCount;
+		require_serialize.assertMinBodyLength(body.length, tableEnd, "scalable");
+		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);
+		try {
+			return new ScalableBloomFilter({
+				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)
+			});
+		} catch (err) {
+			if (err instanceof require_params.ParamError) throw new require_serialize.SerializationError(`scalable: ${err.message}`);
+			throw err;
+		} finally {
+			restoring = void 0;
+		}
+	}
+	toBytes() {
+		const payload = this.#stages.reduce((sum, s) => sum + ENTRY_SIZE + padded8(s.bits.bytes.length), 0);
+		return require_serialize.writeFrame({
+			version: 5,
+			type: TYPE,
+			flags: 0
+		}, PARAMS_SIZE, payload, (body, view) => {
+			view.setUint32(0, this.#n, true);
+			view.setUint32(4, this.#seed, true);
+			view.setFloat64(8, this.#epsilon, true);
+			view.setFloat64(16, this.#growth, true);
+			view.setFloat64(24, this.#tightening, true);
+			view.setUint32(32, this.#stages.length, true);
+			let at = PARAMS_SIZE + ENTRY_SIZE * this.#stages.length;
+			this.#stages.forEach((s, i) => {
+				const entry = PARAMS_SIZE + ENTRY_SIZE * i;
+				view.setUint32(entry, s.m, true);
+				view.setUint16(entry + 4, s.k, true);
+				view.setUint32(entry + 8, s.capacity, true);
+				view.setUint32(entry + 12, s.count, true);
+				body.set(s.bits.bytes, at);
+				at += padded8(s.bits.bytes.length);
+			});
+		});
+	}
+	toJSON() {
+		return require_serialize.toJSONEnvelope(this.toBytes());
+	}
+	static fromJSON(value) {
+		return ScalableBloomFilter.fromBytes(require_serialize.fromJSONEnvelope(value));
+	}
+	get count() {
+		return this.#stages.reduce((sum, s) => sum + s.count, 0);
+	}
+	get capacity() {
+		return this.#stages.reduce((sum, s) => sum + s.capacity, 0);
+	}
+	get stages() {
+		return this.#stages.length;
+	}
+	get m() {
+		return this.#stages.reduce((sum, s) => sum + s.m, 0);
+	}
+	get bitsPerKey() {
+		return this.m / this.capacity;
+	}
+	get seed() {
+		return this.#seed;
+	}
+	get epsilon() {
+		return this.#epsilon;
+	}
+	get growth() {
+		return this.#growth;
+	}
+	get tightening() {
+		return this.#tightening;
+	}
+};
+//#endregion
+exports.BadMagicError = require_serialize.BadMagicError;
+exports.ChecksumError = require_serialize.ChecksumError;
+exports.ParamError = require_params.ParamError;
+exports.ReservedBitsError = require_serialize.ReservedBitsError;
+exports.ScalableBloomFilter = ScalableBloomFilter;
+exports.ScalableParamMismatchError = ScalableParamMismatchError;
+exports.SerializationError = require_serialize.SerializationError;
+exports.TruncatedError = require_serialize.TruncatedError;
+exports.UnknownHashVariantError = require_serialize.UnknownHashVariantError;
+exports.UnknownVersionError = require_serialize.UnknownVersionError;