distillate 0.5.0 → 0.6.0

package/dist/bloom/index.cjs

@@ -1,18 +1,13 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_serialize = require("../serialize-fa-pEUGq.cjs");
-const require_params = require("../params-J8p3bKq5.cjs");
+const require_serialize = require("../serialize-BIIKUHH6.cjs");
+const require_params = require("../params--8CNXYWu.cjs");
 //#region src/core/bitset.ts
 var BitSetRangeError = class extends RangeError {
 	name = "BitSetRangeError";
 };
 const MAX_BITS = 2 ** 32;
-var BitSet = class BitSet {
+var BitSet = class {
 	#bits;
-	static fromBytes(bytes) {
-		const bs = new BitSet(bytes.length * 8);
-		bs.#bits.set(bytes);
-		return bs;
-	}
 	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));
@@ -82,9 +77,23 @@ var BloomFilter = class BloomFilter {
 	*/
 	static create(n, epsilon) {
 		require_params.assertPositiveInt(n, "n");
+		require_params.assertUint32(n, "n");
 		require_params.assertProbability(epsilon, "epsilon");
-		const f = new BloomFilter(optimal(n, epsilon));
-		f.#n = n;
+		return BloomFilter.#withN(optimal(n, epsilon), n);
+	}
+	/**
+	* Builds a filter from `keys`, sized for their count at the target
+	* false-positive rate. The ergonomic entry point when the key set is already
+	* in hand; use {@link BloomFilter.create} to size for a count known ahead.
+	*
+	* @param keys - The keys to insert.
+	* @param epsilon - Target false-positive rate, e.g. `0.01` for 1%.
+	* @returns A new filter containing every key.
+	*/
+	static from(keys, epsilon) {
+		const arr = [...keys];
+		const f = BloomFilter.create(Math.max(1, arr.length), epsilon);
+		for (const k of arr) f.add(k);
 		return f;
 	}
 	/**
@@ -96,7 +105,7 @@ var BloomFilter = class BloomFilter {
 	static fromBytes(bytes) {
 		const { type, flags, body } = require_serialize.readHeader(bytes);
 		if (type !== TYPE) throw new require_serialize.SerializationError(`expected AMQF type ${String(TYPE)}, got ${String(type)}`);
-		if ((flags & 15) !== 1) throw new require_serialize.UnknownHashVariantError(`unsupported hash variant ${String(flags & 15)}`);
+		if ((flags & 15) !== 0) throw new require_serialize.UnknownHashVariantError(`unsupported hash variant ${String(flags & 15)}`);
 		require_serialize.assertMinBodyLength(body.length, 14, "bloom");
 		const dv = new DataView(body.buffer, body.byteOffset, body.byteLength);
 		const m = dv.getUint32(0, true);
@@ -104,12 +113,11 @@ var BloomFilter = class BloomFilter {
 		const seed = dv.getUint32(6, true);
 		const n = dv.getUint32(10, true);
 		require_serialize.assertBodyLength(body.length, 14 + Math.ceil(m / 8), "bloom");
-		const f = new BloomFilter({
+		const f = BloomFilter.#withN({
 			m,
 			k,
 			seed
-		});
-		f.#n = n;
+		}, n);
 		f.#bits.bytes.set(body.subarray(14));
 		return f;
 	}
@@ -119,7 +127,9 @@ var BloomFilter = class BloomFilter {
 	*/
 	constructor({ m, k, seed = 0 }) {
 		require_params.assertPositiveInt(m, "m");
+		require_params.assertUint32(m, "m");
 		require_params.assertPositiveInt(k, "k");
+		require_params.assertUint16(k, "k");
 		require_params.assertUint32(seed, "seed");
 		this.#bits = new BitSet(m);
 		this.#m = m;
@@ -128,6 +138,11 @@ var BloomFilter = class BloomFilter {
 		this.#scratch = new Uint32Array(k);
 		this.#n = Math.round(m * Math.LN2 / k);
 	}
+	static #withN(params, n) {
+		const f = new BloomFilter(params);
+		f.#n = n;
+		return f;
+	}
 	/** Number of bits in the filter. */
 	get m() {
 		return this.#m;
@@ -165,18 +180,45 @@ var BloomFilter = class BloomFilter {
 	*/
 	toBytes() {
 		const payload = this.#bits.bytes;
-		const body = new Uint8Array(14 + payload.length);
-		const dv = new DataView(body.buffer, body.byteOffset, body.byteLength);
-		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);
-		return require_serialize.writeHeader({
-			version: 2,
+		return require_serialize.writeFrame({
+			version: 3,
 			type: TYPE,
-			flags: 1
-		}, body);
+			flags: 0
+		}, 14 + 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);
+		});
+	}
+	/**
+	* Tests structural equality: `true` when `other` serializes to identical
+	* bytes, meaning identical parameters and set bits.
+	*
+	* @param other - The filter to compare against.
+	* @returns `true` if the two filters are byte-for-byte identical.
+	*/
+	equals(other) {
+		return require_serialize.bytesEqual(this.toBytes(), other.toBytes());
+	}
+	/**
+	* Serializes the filter to a JSON-friendly envelope wrapping the base64 of
+	* {@link BloomFilter.toBytes}.
+	*
+	* @returns The envelope, readable by {@link BloomFilter.fromJSON}.
+	*/
+	toJSON() {
+		return require_serialize.toJSONEnvelope(this.toBytes());
+	}
+	/**
+	* Restores a filter from its {@link BloomFilter.toJSON} envelope.
+	*
+	* @param value - The JSON envelope.
+	* @returns The reconstructed filter.
+	*/
+	static fromJSON(value) {
+		return BloomFilter.fromBytes(require_serialize.fromJSONEnvelope(value));
 	}
 	/**
 	* Returns a new filter containing the union of this filter and `other`.
@@ -191,11 +233,11 @@ var BloomFilter = class BloomFilter {
 		const b = other.#bits.bytes;
 		const merged = new Uint8Array(a.length);
 		for (let i = 0; i < a.length; i++) merged[i] = (a[i] ?? 0) | (b[i] ?? 0);
-		const r = new BloomFilter({
+		const r = BloomFilter.#withN({
 			m: this.#m,
 			k: this.#k,
 			seed: this.#seed
-		});
+		}, this.#n);
 		r.#bits.bytes.set(merged);
 		return r;
 	}

package/dist/bloom/index.d.cts

@@ -1,4 +1,4 @@
-import { t as BytesLike } from "../bytes-DCuYtUVS.cjs";
+import { n as BytesLike, t as FilterJSON } from "../serialize-DRKh6QOr.cjs";
 import { t as ParamError } from "../params-DnqJBqLS.cjs";
 //#region src/bloom/bloom.d.ts
 /** Thrown when an operation requires two filters built with identical parameters. */
@@ -37,6 +37,16 @@ declare class BloomFilter {
    * @returns A new, empty filter.
    */
   static create(n: number, epsilon: number): BloomFilter;
+  /**
+   * Builds a filter from `keys`, sized for their count at the target
+   * false-positive rate. The ergonomic entry point when the key set is already
+   * in hand; use {@link BloomFilter.create} to size for a count known ahead.
+   *
+   * @param keys - The keys to insert.
+   * @param epsilon - Target false-positive rate, e.g. `0.01` for 1%.
+   * @returns A new filter containing every key.
+   */
+  static from(keys: Iterable<BytesLike>, epsilon: number): BloomFilter;
   /**
    * Restores a filter from its {@link BloomFilter.toBytes} serialization.
    *
@@ -73,6 +83,28 @@ declare class BloomFilter {
    * @returns The serialized filter, readable by {@link BloomFilter.fromBytes}.
    */
   toBytes(): Uint8Array;
+  /**
+   * Tests structural equality: `true` when `other` serializes to identical
+   * bytes, meaning identical parameters and set bits.
+   *
+   * @param other - The filter to compare against.
+   * @returns `true` if the two filters are byte-for-byte identical.
+   */
+  equals(other: BloomFilter): boolean;
+  /**
+   * Serializes the filter to a JSON-friendly envelope wrapping the base64 of
+   * {@link BloomFilter.toBytes}.
+   *
+   * @returns The envelope, readable by {@link BloomFilter.fromJSON}.
+   */
+  toJSON(): FilterJSON;
+  /**
+   * Restores a filter from its {@link BloomFilter.toJSON} envelope.
+   *
+   * @param value - The JSON envelope.
+   * @returns The reconstructed filter.
+   */
+  static fromJSON(value: unknown): BloomFilter;
   /**
    * Returns a new filter containing the union of this filter and `other`.
    *
@@ -96,4 +128,4 @@ declare class BloomFilter {
   has(key: BytesLike): boolean;
 }
 //#endregion
-export { BloomFilter, BloomParamMismatchError, type BloomParams, ParamError };
+export { BloomFilter, BloomParamMismatchError, type BloomParams, type FilterJSON, ParamError };

package/dist/bloom/index.d.ts

@@ -1,4 +1,4 @@
-import { t as BytesLike } from "../bytes-DCuYtUVS.js";
+import { n as BytesLike, t as FilterJSON } from "../serialize-DRKh6QOr.js";
 import { t as ParamError } from "../params-DnqJBqLS.js";
 //#region src/bloom/bloom.d.ts
 /** Thrown when an operation requires two filters built with identical parameters. */
@@ -37,6 +37,16 @@ declare class BloomFilter {
    * @returns A new, empty filter.
    */
   static create(n: number, epsilon: number): BloomFilter;
+  /**
+   * Builds a filter from `keys`, sized for their count at the target
+   * false-positive rate. The ergonomic entry point when the key set is already
+   * in hand; use {@link BloomFilter.create} to size for a count known ahead.
+   *
+   * @param keys - The keys to insert.
+   * @param epsilon - Target false-positive rate, e.g. `0.01` for 1%.
+   * @returns A new filter containing every key.
+   */
+  static from(keys: Iterable<BytesLike>, epsilon: number): BloomFilter;
   /**
    * Restores a filter from its {@link BloomFilter.toBytes} serialization.
    *
@@ -73,6 +83,28 @@ declare class BloomFilter {
    * @returns The serialized filter, readable by {@link BloomFilter.fromBytes}.
    */
   toBytes(): Uint8Array;
+  /**
+   * Tests structural equality: `true` when `other` serializes to identical
+   * bytes, meaning identical parameters and set bits.
+   *
+   * @param other - The filter to compare against.
+   * @returns `true` if the two filters are byte-for-byte identical.
+   */
+  equals(other: BloomFilter): boolean;
+  /**
+   * Serializes the filter to a JSON-friendly envelope wrapping the base64 of
+   * {@link BloomFilter.toBytes}.
+   *
+   * @returns The envelope, readable by {@link BloomFilter.fromJSON}.
+   */
+  toJSON(): FilterJSON;
+  /**
+   * Restores a filter from its {@link BloomFilter.toJSON} envelope.
+   *
+   * @param value - The JSON envelope.
+   * @returns The reconstructed filter.
+   */
+  static fromJSON(value: unknown): BloomFilter;
   /**
    * Returns a new filter containing the union of this filter and `other`.
    *
@@ -96,4 +128,4 @@ declare class BloomFilter {
   has(key: BytesLike): boolean;
 }
 //#endregion
-export { BloomFilter, BloomParamMismatchError, type BloomParams, ParamError };
+export { BloomFilter, BloomParamMismatchError, type BloomParams, type FilterJSON, ParamError };

package/dist/bloom/index.js

@@ -1,17 +1,12 @@
-import { a as readHeader, i as assertMinBodyLength, n as UnknownHashVariantError, o as writeHeader, p as probeInto, r as assertBodyLength, t as SerializationError } from "../serialize-BQ2UzZqq.js";
-import { a as assertUint32, i as assertProbability, r as assertPositiveInt, t as ParamError } from "../params-ChTRNxM9.js";
+import { a as bytesEqual, c as toJSONEnvelope, g as probeInto, i as assertMinBodyLength, l as writeFrame, n as UnknownHashVariantError, o as fromJSONEnvelope, r as assertBodyLength, s as readHeader, t as SerializationError } from "../serialize-BnwtzcMw.js";
+import { a as assertUint16, i as assertProbability, o as assertUint32, r as assertPositiveInt, t as ParamError } from "../params-BrWuBC2A.js";
 //#region src/core/bitset.ts
 var BitSetRangeError = class extends RangeError {
 	name = "BitSetRangeError";
 };
 const MAX_BITS = 2 ** 32;
-var BitSet = class BitSet {
+var BitSet = class {
 	#bits;
-	static fromBytes(bytes) {
-		const bs = new BitSet(bytes.length * 8);
-		bs.#bits.set(bytes);
-		return bs;
-	}
 	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));
@@ -81,9 +76,23 @@ var BloomFilter = class BloomFilter {
 	*/
 	static create(n, epsilon) {
 		assertPositiveInt(n, "n");
+		assertUint32(n, "n");
 		assertProbability(epsilon, "epsilon");
-		const f = new BloomFilter(optimal(n, epsilon));
-		f.#n = n;
+		return BloomFilter.#withN(optimal(n, epsilon), n);
+	}
+	/**
+	* Builds a filter from `keys`, sized for their count at the target
+	* false-positive rate. The ergonomic entry point when the key set is already
+	* in hand; use {@link BloomFilter.create} to size for a count known ahead.
+	*
+	* @param keys - The keys to insert.
+	* @param epsilon - Target false-positive rate, e.g. `0.01` for 1%.
+	* @returns A new filter containing every key.
+	*/
+	static from(keys, epsilon) {
+		const arr = [...keys];
+		const f = BloomFilter.create(Math.max(1, arr.length), epsilon);
+		for (const k of arr) f.add(k);
 		return f;
 	}
 	/**
@@ -95,7 +104,7 @@ var BloomFilter = class BloomFilter {
 	static fromBytes(bytes) {
 		const { type, flags, body } = readHeader(bytes);
 		if (type !== TYPE) throw new SerializationError(`expected AMQF type ${String(TYPE)}, got ${String(type)}`);
-		if ((flags & 15) !== 1) throw new UnknownHashVariantError(`unsupported hash variant ${String(flags & 15)}`);
+		if ((flags & 15) !== 0) throw new UnknownHashVariantError(`unsupported hash variant ${String(flags & 15)}`);
 		assertMinBodyLength(body.length, 14, "bloom");
 		const dv = new DataView(body.buffer, body.byteOffset, body.byteLength);
 		const m = dv.getUint32(0, true);
@@ -103,12 +112,11 @@ var BloomFilter = class BloomFilter {
 		const seed = dv.getUint32(6, true);
 		const n = dv.getUint32(10, true);
 		assertBodyLength(body.length, 14 + Math.ceil(m / 8), "bloom");
-		const f = new BloomFilter({
+		const f = BloomFilter.#withN({
 			m,
 			k,
 			seed
-		});
-		f.#n = n;
+		}, n);
 		f.#bits.bytes.set(body.subarray(14));
 		return f;
 	}
@@ -118,7 +126,9 @@ var BloomFilter = class BloomFilter {
 	*/
 	constructor({ m, k, seed = 0 }) {
 		assertPositiveInt(m, "m");
+		assertUint32(m, "m");
 		assertPositiveInt(k, "k");
+		assertUint16(k, "k");
 		assertUint32(seed, "seed");
 		this.#bits = new BitSet(m);
 		this.#m = m;
@@ -127,6 +137,11 @@ var BloomFilter = class BloomFilter {
 		this.#scratch = new Uint32Array(k);
 		this.#n = Math.round(m * Math.LN2 / k);
 	}
+	static #withN(params, n) {
+		const f = new BloomFilter(params);
+		f.#n = n;
+		return f;
+	}
 	/** Number of bits in the filter. */
 	get m() {
 		return this.#m;
@@ -164,18 +179,45 @@ var BloomFilter = class BloomFilter {
 	*/
 	toBytes() {
 		const payload = this.#bits.bytes;
-		const body = new Uint8Array(14 + payload.length);
-		const dv = new DataView(body.buffer, body.byteOffset, body.byteLength);
-		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);
-		return writeHeader({
-			version: 2,
+		return writeFrame({
+			version: 3,
 			type: TYPE,
-			flags: 1
-		}, body);
+			flags: 0
+		}, 14 + 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);
+		});
+	}
+	/**
+	* Tests structural equality: `true` when `other` serializes to identical
+	* bytes, meaning identical parameters and set bits.
+	*
+	* @param other - The filter to compare against.
+	* @returns `true` if the two filters are byte-for-byte identical.
+	*/
+	equals(other) {
+		return bytesEqual(this.toBytes(), other.toBytes());
+	}
+	/**
+	* Serializes the filter to a JSON-friendly envelope wrapping the base64 of
+	* {@link BloomFilter.toBytes}.
+	*
+	* @returns The envelope, readable by {@link BloomFilter.fromJSON}.
+	*/
+	toJSON() {
+		return toJSONEnvelope(this.toBytes());
+	}
+	/**
+	* Restores a filter from its {@link BloomFilter.toJSON} envelope.
+	*
+	* @param value - The JSON envelope.
+	* @returns The reconstructed filter.
+	*/
+	static fromJSON(value) {
+		return BloomFilter.fromBytes(fromJSONEnvelope(value));
 	}
 	/**
 	* Returns a new filter containing the union of this filter and `other`.
@@ -190,11 +232,11 @@ var BloomFilter = class BloomFilter {
 		const b = other.#bits.bytes;
 		const merged = new Uint8Array(a.length);
 		for (let i = 0; i < a.length; i++) merged[i] = (a[i] ?? 0) | (b[i] ?? 0);
-		const r = new BloomFilter({
+		const r = BloomFilter.#withN({
 			m: this.#m,
 			k: this.#k,
 			seed: this.#seed
-		});
+		}, this.#n);
 		r.#bits.bytes.set(merged);
 		return r;
 	}

package/dist/fuse/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_serialize = require("../serialize-fa-pEUGq.cjs");
+const require_serialize = require("../serialize-BIIKUHH6.cjs");
 //#region src/fuse/fuse.ts
 const ARITY = 3;
 const TYPE_FUSE8 = 3;
@@ -10,10 +10,10 @@ var BinaryFuseBuildError = class extends Error {
 	name = "BinaryFuseBuildError";
 };
 const scratchHash = {
-	h1lo: 0,
-	h1hi: 0,
-	h2lo: 0,
-	h2hi: 0
+	w0: 0,
+	w1: 0,
+	w2: 0,
+	w3: 0
 };
 function mixSeed(lo, hi, seed) {
 	const l = (lo >>> 0) + (seed >>> 0);
@@ -136,8 +136,8 @@ function buildState(keys, alloc) {
 	const seen = /* @__PURE__ */ new Set();
 	for (const key of keys) {
 		require_serialize.hash128KeyInto(key, 0, scratchHash);
-		const lo = scratchHash.h1lo >>> 0;
-		const hi = scratchHash.h1hi >>> 0;
+		const lo = scratchHash.w0 >>> 0;
+		const hi = scratchHash.w1 >>> 0;
 		const id = `${String(lo)},${String(hi)}`;
 		if (seen.has(id)) continue;
 		seen.add(id);
@@ -161,14 +161,17 @@ function buildState(keys, alloc) {
 	};
 }
 function fuseStateFromBytes(bytes, expectedType) {
-	const { type, body } = require_serialize.readHeader(bytes);
+	const { type, flags, body } = require_serialize.readHeader(bytes);
 	if (type !== expectedType) throw new require_serialize.SerializationError(`expected AMQF 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");
 	const dv = new DataView(body.buffer, body.byteOffset, body.byteLength);
 	const seed = dv.getUint32(0, true);
 	const seg = dv.getUint32(4, true);
 	const segCountLen = dv.getUint32(8, true);
 	const size = dv.getUint32(12, true);
+	if (seg === 0 || (seg & seg - 1) !== 0 || seg > 1 << 18) throw new require_serialize.SerializationError(`invalid fuse segment length ${String(seg)}`);
+	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");
@@ -212,6 +215,10 @@ var BinaryFuse = class {
 	get size() {
 		return this.#size;
 	}
+	/** Hash seed selected during construction (may differ from 0 after a peel retry). */
+	get seed() {
+		return this.#seed;
+	}
 	/** Actual bits stored per key (`0` for an empty filter). */
 	get bitsPerKey() {
 		return this.#size === 0 ? 0 : this.#fp.byteLength * 8 / this.#size;
@@ -223,18 +230,17 @@ var BinaryFuse = class {
 	*/
 	toBytes() {
 		const laneBytes = new Uint8Array(this.#fp.buffer, this.#fp.byteOffset, this.#fp.byteLength);
-		const body = new Uint8Array(16 + laneBytes.length);
-		const dv = new DataView(body.buffer);
-		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);
-		return require_serialize.writeHeader({
-			version: 2,
+		return require_serialize.writeFrame({
+			version: 3,
 			type: this.#fp.BYTES_PER_ELEMENT === 1 ? TYPE_FUSE8 : TYPE_FUSE16,
 			flags: 0
-		}, body);
+		}, 16 + 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);
+		});
 	}
 	/**
 	* Tests whether a key is in the set.
@@ -245,7 +251,7 @@ var BinaryFuse = class {
 	has(key) {
 		if (this.#fp.length === 0) return false;
 		require_serialize.hash128KeyInto(key, 0, scratchHash);
-		mixSeed(scratchHash.h1lo >>> 0, scratchHash.h1hi >>> 0, this.#seed);
+		mixSeed(scratchHash.w0 >>> 0, scratchHash.w1 >>> 0, this.#seed);
 		const mlo = require_serialize.RLO;
 		const mhi = require_serialize.RHI;
 		positionsInto(mlo, mhi, this.#seg, this.#segMask, this.#segCountLen, this.#pos);
@@ -255,6 +261,26 @@ var BinaryFuse = class {
 		const p2 = this.#pos[2] ?? 0;
 		return ((mlo ^ mhi) & mask) === (((this.#fp[p0] ?? 0) ^ (this.#fp[p1] ?? 0) ^ (this.#fp[p2] ?? 0)) & mask);
 	}
+	/**
+	* Tests structural equality: `true` when `other` serializes to identical
+	* bytes. A {@link BinaryFuse8} and a {@link BinaryFuse16} are never equal,
+	* since their frames carry different type bytes.
+	*
+	* @param other - The filter to compare against.
+	* @returns `true` if the two filters are byte-for-byte identical.
+	*/
+	equals(other) {
+		return require_serialize.bytesEqual(this.toBytes(), other.toBytes());
+	}
+	/**
+	* Serializes the filter to a JSON-friendly envelope wrapping the base64 of
+	* the `toBytes` frame.
+	*
+	* @returns The envelope, readable by the matching `fromJSON`.
+	*/
+	toJSON() {
+		return require_serialize.toJSONEnvelope(this.toBytes());
+	}
 };
 /**
 * A static 8-bit binary fuse filter: built once from a key set, then immutable.
@@ -287,6 +313,15 @@ var BinaryFuse8 = class BinaryFuse8 extends BinaryFuse {
 	static fromBytes(bytes) {
 		return new BinaryFuse8(fuseStateFromBytes(bytes, TYPE_FUSE8));
 	}
+	/**
+	* Restores a filter from its {@link BinaryFuse8.toJSON} envelope.
+	*
+	* @param value - The JSON envelope.
+	* @returns The reconstructed filter.
+	*/
+	static fromJSON(value) {
+		return BinaryFuse8.fromBytes(require_serialize.fromJSONEnvelope(value));
+	}
 };
 /**
 * A static 16-bit binary fuse filter: like {@link BinaryFuse8} but twice the
@@ -318,6 +353,15 @@ var BinaryFuse16 = class BinaryFuse16 extends BinaryFuse {
 	static fromBytes(bytes) {
 		return new BinaryFuse16(fuseStateFromBytes(bytes, TYPE_FUSE16));
 	}
+	/**
+	* Restores a filter from its {@link BinaryFuse16.toJSON} envelope.
+	*
+	* @param value - The JSON envelope.
+	* @returns The reconstructed filter.
+	*/
+	static fromJSON(value) {
+		return BinaryFuse16.fromBytes(require_serialize.fromJSONEnvelope(value));
+	}
 };
 //#endregion
 exports.BinaryFuse16 = BinaryFuse16;

package/dist/fuse/index.d.cts

@@ -1,4 +1,4 @@
-import { t as BytesLike } from "../bytes-DCuYtUVS.cjs";
+import { n as BytesLike, t as FilterJSON } from "../serialize-DRKh6QOr.cjs";
 //#region src/fuse/fuse.d.ts
 /** Thrown when binary fuse construction fails to converge on the key set. */
 declare class BinaryFuseBuildError extends Error {
@@ -26,6 +26,8 @@ declare abstract class BinaryFuse {
   protected constructor(state: FuseState);
   /** Number of distinct keys the filter was built from. */
   get size(): number;
+  /** Hash seed selected during construction (may differ from 0 after a peel retry). */
+  get seed(): number;
   /** Actual bits stored per key (`0` for an empty filter). */
   get bitsPerKey(): number;
   /**
@@ -41,6 +43,22 @@ declare abstract class BinaryFuse {
    * @returns `true` if present (possibly a false positive); `false` guarantees absence.
    */
   has(key: BytesLike): boolean;
+  /**
+   * Tests structural equality: `true` when `other` serializes to identical
+   * bytes. A {@link BinaryFuse8} and a {@link BinaryFuse16} are never equal,
+   * since their frames carry different type bytes.
+   *
+   * @param other - The filter to compare against.
+   * @returns `true` if the two filters are byte-for-byte identical.
+   */
+  equals(other: BinaryFuse8 | BinaryFuse16): boolean;
+  /**
+   * Serializes the filter to a JSON-friendly envelope wrapping the base64 of
+   * the `toBytes` frame.
+   *
+   * @returns The envelope, readable by the matching `fromJSON`.
+   */
+  toJSON(): FilterJSON;
 }
 /**
  * A static 8-bit binary fuse filter: built once from a key set, then immutable.
@@ -69,6 +87,13 @@ declare class BinaryFuse8 extends BinaryFuse {
    * @returns The reconstructed filter.
    */
   static fromBytes(bytes: Uint8Array): BinaryFuse8;
+  /**
+   * Restores a filter from its {@link BinaryFuse8.toJSON} envelope.
+   *
+   * @param value - The JSON envelope.
+   * @returns The reconstructed filter.
+   */
+  static fromJSON(value: unknown): BinaryFuse8;
 }
 /**
  * A static 16-bit binary fuse filter: like {@link BinaryFuse8} but twice the
@@ -96,6 +121,13 @@ declare class BinaryFuse16 extends BinaryFuse {
    * @returns The reconstructed filter.
    */
   static fromBytes(bytes: Uint8Array): BinaryFuse16;
+  /**
+   * Restores a filter from its {@link BinaryFuse16.toJSON} envelope.
+   *
+   * @param value - The JSON envelope.
+   * @returns The reconstructed filter.
+   */
+  static fromJSON(value: unknown): BinaryFuse16;
 }
 //#endregion
-export { BinaryFuse16, BinaryFuse8, BinaryFuseBuildError };
+export { BinaryFuse16, BinaryFuse8, BinaryFuseBuildError, type FilterJSON };