distillate 0.8.2 → 0.9.0

package/dist/hll/index.js

@@ -0,0 +1,353 @@
+import { _ as hash128KeyInto, a as UnknownHashVariantError, c as assertMinBodyLength, d as readHeader, f as toJSONEnvelope, i as TruncatedError, n as ChecksumError, o as UnknownVersionError, p as writeFrame, r as SerializationError, s as assertBodyLength, t as BadMagicError, u as fromJSONEnvelope } from "../serialize-D59Ri81a.js";
+import { o as assertUint32, t as ParamError } from "../params-CeajSrwv.js";
+import { n as hllSizing } from "../sizing-BtUrtvF_.js";
+//#region src/hll/estimate.ts
+const ALPHA_INF = .5 / Math.LN2;
+function sigma(x) {
+	if (x === 1) return Infinity;
+	let y = 1;
+	let z = x;
+	let previous;
+	do {
+		x *= x;
+		previous = z;
+		z += x * y;
+		y += y;
+	} while (z !== previous);
+	return z;
+}
+function tau(x) {
+	if (x === 0 || x === 1) return 0;
+	let y = 1;
+	let z = 1 - x;
+	let previous;
+	do {
+		x = Math.sqrt(x);
+		previous = z;
+		y *= .5;
+		const gap = 1 - x;
+		z -= gap * gap * y;
+	} while (z !== previous);
+	return z / 3;
+}
+function estimate(hist, p) {
+	const m = 2 ** p;
+	const q = 64 - p;
+	let z = m * tau((m - (hist[q + 1] ?? 0)) / m);
+	for (let k = q; k >= 1; k--) z = .5 * (z + (hist[k] ?? 0));
+	z += m * sigma((hist[0] ?? 0) / m);
+	return ALPHA_INF * m * m / z;
+}
+//#endregion
+//#region src/hll/fold.ts
+function foldRho(index, rho, d) {
+	const mid = index & (1 << d) - 1;
+	if (mid === 0) return d + rho;
+	return Math.clz32(mid) - 32 + d + 1;
+}
+function foldDense(src, srcP, dst, dstP) {
+	const d = srcP - dstP;
+	for (let i = 0; i < 2 ** srcP; i++) {
+		const rho = src.get(i);
+		if (rho === 0) continue;
+		dst.raise(i >>> d, foldRho(i, rho, d));
+	}
+}
+//#endregion
+//#region src/hll/registers.ts
+const WIDTH = 6;
+const MASK = 63;
+var Registers = class {
+	#bytes;
+	constructor(p) {
+		this.#bytes = new Uint8Array(WIDTH * 2 ** p / 8);
+	}
+	get bytes() {
+		return this.#bytes;
+	}
+	max() {
+		const bytes = this.#bytes;
+		let max = 0;
+		for (let at = 0; at < bytes.length; at += 3) {
+			const word = (bytes[at] ?? 0) | (bytes[at + 1] ?? 0) << 8 | (bytes[at + 2] ?? 0) << 16;
+			const a = word & MASK;
+			const b = word >>> 6 & MASK;
+			const c = word >>> 12 & MASK;
+			const d = word >>> 18 & MASK;
+			if (a > max) max = a;
+			if (b > max) max = b;
+			if (c > max) max = c;
+			if (d > max) max = d;
+		}
+		return max;
+	}
+	get(i) {
+		const bit = i * WIDTH;
+		const at = bit >>> 3;
+		return ((this.#bytes[at] ?? 0) | (this.#bytes[at + 1] ?? 0) << 8) >>> (bit & 7) & MASK;
+	}
+	raise(i, v) {
+		if (v > this.get(i)) this.set(i, v);
+	}
+	set(i, v) {
+		const bit = i * WIDTH;
+		const at = bit >>> 3;
+		const off = bit & 7;
+		const word = ((this.#bytes[at] ?? 0) | (this.#bytes[at + 1] ?? 0) << 8) & ~(MASK << off) | (v & MASK) << off;
+		this.#bytes[at] = word & 255;
+		if (at + 1 < this.#bytes.length) this.#bytes[at + 1] = word >>> 8 & 255;
+	}
+};
+const RHO_BITS = 6;
+const RHO_MASK = (1 << RHO_BITS) - 1;
+function encodeSparse(index, rho) {
+	return index << RHO_BITS | rho;
+}
+function sparseIndex(entry) {
+	return entry >>> RHO_BITS;
+}
+function sparseRho(entry) {
+	return entry & RHO_MASK;
+}
+function foldSparse(buf, len, fromP, registers, toP) {
+	const d = fromP - toP;
+	for (let i = 0; i < len; i++) {
+		const entry = buf[i] ?? 0;
+		const at = sparseIndex(entry) >>> 25 - fromP;
+		registers.raise(at >>> d, foldRho(at, sparseRho(entry), d));
+	}
+}
+function refoldSparse(entry, fromP, toP) {
+	const index = sparseIndex(entry);
+	return encodeSparse(index, foldRho(index >>> 25 - fromP, sparseRho(entry), fromP - toP));
+}
+function compact(buf, len) {
+	if (len === 0) return 0;
+	buf.subarray(0, len).sort();
+	let out = 0;
+	for (let i = 0; i < len; i++) {
+		const entry = buf[i] ?? 0;
+		const next = buf[i + 1] ?? 0;
+		if (i + 1 < len && sparseIndex(next) === sparseIndex(entry)) continue;
+		buf[out++] = entry;
+	}
+	return out;
+}
+//#endregion
+//#region src/hll/hll.ts
+const ERROR_CONSTANT = 1.04;
+const TYPE = 5;
+const PARAMS_SIZE = 6;
+const DENSE = 0;
+const SPARSE = 1;
+const ENTRY_SIZE = 4;
+function assertPrecision(p) {
+	if (!Number.isInteger(p) || p < 4 || p > 18) throw new ParamError(`p must be an integer in [${String(4)}, ${String(18)}], got ${String(p)}`);
+}
+function sparseCapacity(registers) {
+	return registers.bytes.length >> 2;
+}
+var HyperLogLog = class HyperLogLog {
+	#registers;
+	#p;
+	#seed;
+	#scratch = {
+		w0: 0,
+		w1: 0,
+		w2: 0,
+		w3: 0
+	};
+	#sparse;
+	#len = 0;
+	constructor({ p, seed = 0 }) {
+		assertPrecision(p);
+		assertUint32(seed, "seed");
+		this.#registers = new Registers(p);
+		this.#p = p;
+		this.#seed = seed;
+		this.#sparse = new Int32Array(sparseCapacity(this.#registers));
+	}
+	static create(relativeError) {
+		return new HyperLogLog(hllSizing(relativeError));
+	}
+	static from(keys, relativeError) {
+		const sketch = HyperLogLog.create(relativeError);
+		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, "hll");
+		const dv = new DataView(body.buffer, body.byteOffset, body.byteLength);
+		const p = body[0] ?? 0;
+		const encoding = body[1] ?? 0;
+		const seed = dv.getUint32(2, true);
+		if (encoding !== DENSE && encoding !== SPARSE) throw new SerializationError(`unknown hll encoding ${String(encoding)}`);
+		const sketch = new HyperLogLog({
+			p,
+			seed
+		});
+		const payload = body.length - PARAMS_SIZE;
+		const maxRho = 65 - p;
+		if (encoding === DENSE) {
+			assertBodyLength(body.length, PARAMS_SIZE + sketch.#registers.bytes.length, "hll");
+			sketch.#goDense();
+			sketch.#registers.bytes.set(body.subarray(PARAMS_SIZE));
+			const largest = sketch.#registers.max();
+			if (largest > maxRho) throw new SerializationError(`hll: register holds ${String(largest)}, above the maximum ${String(maxRho)} at p ${String(p)}`);
+			return sketch;
+		}
+		const capacity = sparseCapacity(sketch.#registers);
+		if (payload % ENTRY_SIZE !== 0 || payload / ENTRY_SIZE > capacity) throw new TruncatedError(`hll: sparse payload of ${String(payload)} bytes is not up to ${String(capacity)} whole entries`);
+		const entries = payload / ENTRY_SIZE;
+		const buffer = new Int32Array(capacity);
+		for (let i = 0; i < entries; i++) {
+			const entry = dv.getUint32(PARAMS_SIZE + i * ENTRY_SIZE, true);
+			if (entry > 2147483647) throw new SerializationError(`hll: sparse entry ${String(entry)} does not fit the 31-bit encoding`);
+			const rho = sparseRho(entry);
+			if (rho > maxRho) throw new SerializationError(`hll: sparse entry holds rho ${String(rho)}, above the maximum ${String(maxRho)} at p ${String(p)}`);
+			buffer[i] = entry;
+		}
+		sketch.#sparse = buffer;
+		sketch.#len = entries;
+		return sketch;
+	}
+	toBytes() {
+		const sparse = this.#sparse;
+		if (sparse !== null) {
+			const entries = compact(sparse, this.#len);
+			this.#len = entries;
+			return writeFrame({
+				version: 4,
+				type: TYPE,
+				flags: 0
+			}, PARAMS_SIZE + entries * ENTRY_SIZE, (body, dv) => {
+				body[0] = this.#p;
+				body[1] = SPARSE;
+				dv.setUint32(2, this.#seed, true);
+				for (let i = 0; i < entries; i++) dv.setUint32(PARAMS_SIZE + i * ENTRY_SIZE, sparse[i] ?? 0, true);
+			});
+		}
+		const payload = this.#registers.bytes;
+		return writeFrame({
+			version: 4,
+			type: TYPE,
+			flags: 0
+		}, PARAMS_SIZE + payload.length, (body, dv) => {
+			body[0] = this.#p;
+			body[1] = DENSE;
+			dv.setUint32(2, this.#seed, true);
+			body.set(payload, PARAMS_SIZE);
+		});
+	}
+	toJSON() {
+		return toJSONEnvelope(this.toBytes());
+	}
+	static fromJSON(value) {
+		return HyperLogLog.fromBytes(fromJSONEnvelope(value));
+	}
+	get p() {
+		return this.#p;
+	}
+	get seed() {
+		return this.#seed;
+	}
+	get standardError() {
+		return ERROR_CONSTANT / Math.sqrt(2 ** this.#p);
+	}
+	add(key) {
+		const s = this.#scratch;
+		hash128KeyInto(key, this.#seed, s);
+		const p = this.#p;
+		const tail = s.w0 << p >>> 0;
+		const rho = tail !== 0 ? Math.clz32(tail) + 1 : 32 - p + Math.clz32(s.w1) + 1;
+		const sparse = this.#sparse;
+		if (sparse === null) {
+			this.#registers.raise(s.w0 >>> 32 - p, rho);
+			return;
+		}
+		sparse[this.#len++] = encodeSparse(s.w0 >>> 7, rho);
+		if (this.#len === sparse.length) this.#collapse(sparse);
+	}
+	#collapse(sparse) {
+		const distinct = compact(sparse, this.#len);
+		this.#len = distinct;
+		const slack = Math.max(1, sparse.length >> 2);
+		if (distinct > sparse.length - slack) this.#goDense();
+	}
+	union(other) {
+		if (other.#seed !== this.#seed) throw new ParamError(`cannot merge sketches with different seeds, got ${String(this.#seed)} and ${String(other.#seed)}`);
+		const p = Math.min(this.#p, other.#p);
+		const merged = new HyperLogLog({
+			p,
+			seed: this.#seed
+		});
+		merged.#drain(this);
+		merged.#drain(other);
+		return merged;
+	}
+	#drain(src) {
+		const sparse = src.#sparse;
+		if (sparse === null) {
+			this.#goDense();
+			foldDense(src.#registers, src.#p, this.#registers, this.#p);
+			return;
+		}
+		const distinct = compact(sparse, src.#len);
+		src.#len = distinct;
+		for (let i = 0; i < distinct; i++) this.#absorb(refoldSparse(sparse[i] ?? 0, src.#p, this.#p));
+	}
+	#absorb(entry) {
+		const sparse = this.#sparse;
+		if (sparse === null) {
+			const index = sparseIndex(entry) >>> 25 - this.#p;
+			this.#registers.raise(index, sparseRho(entry));
+			return;
+		}
+		sparse[this.#len++] = entry;
+		if (this.#len === sparse.length) this.#collapse(sparse);
+	}
+	#goDense() {
+		const sparse = this.#sparse;
+		if (sparse === null) return;
+		foldSparse(sparse, this.#len, this.#p, this.#registers, this.#p);
+		this.#sparse = null;
+		this.#len = 0;
+	}
+	#dense() {
+		const sparse = this.#sparse;
+		if (sparse === null) return this.#registers;
+		const out = new Registers(this.#p);
+		foldSparse(sparse, this.#len, this.#p, out, this.#p);
+		return out;
+	}
+	equals(other) {
+		if (other.#p !== this.#p || other.#seed !== this.#seed) return false;
+		const mine = this.#dense().bytes;
+		const theirs = other.#dense().bytes;
+		for (let i = 0; i < mine.length; i++) if (mine[i] !== theirs[i]) return false;
+		return true;
+	}
+	count() {
+		const sparse = this.#sparse;
+		if (sparse !== null) {
+			const distinct = compact(sparse, this.#len);
+			this.#len = distinct;
+			const buckets = 2 ** 25;
+			return Math.round(buckets * Math.log(buckets / (buckets - distinct)));
+		}
+		const p = this.#p;
+		const q = 64 - p;
+		const m = 2 ** p;
+		const hist = new Int32Array(q + 2);
+		for (let i = 0; i < m; i++) {
+			const value = this.#registers.get(i);
+			hist[value] = (hist[value] ?? 0) + 1;
+		}
+		return Math.round(estimate(hist, p));
+	}
+};
+//#endregion
+export { BadMagicError, ChecksumError, HyperLogLog, ParamError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError, hllSizing };

package/dist/index.cjs

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

package/dist/index.js

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

package/dist/{serialize-ChyWpB9F.d.cts → serialize-Bv1zWzrh.d.cts}

@@ -15,19 +15,22 @@ declare class SerializationError extends Error {
   override readonly name: string;
 }
 /**
- * Thrown when a frame is shorter than its header plus trailer, or when its
- * body length does not match the length its declared params imply. The bytes
- * were cut short in transit or storage; re-fetch the whole frame.
+ * Thrown when a frame is shorter than its header plus trailer, when the body
+ * length its header declares disagrees with the bytes actually present, or
+ * when its body length does not match the length its declared params imply.
+ * The bytes were cut short in transit or storage; re-fetch the whole frame.
  */
 declare class TruncatedError extends SerializationError {
   /** Discriminates this error from other `Error`s. */
   override readonly name = "TruncatedError";
 }
 /**
- * Thrown when a frame does not start with the four-byte `AMQF` magic, so it
- * was never produced by `toBytes`. Check that the bytes really are a
- * distillate frame and not another payload, a text encoding of one, or a
- * slice taken at the wrong offset.
+ * Thrown when a frame does not start with the four-byte `DSTL` magic, so it
+ * was never produced by `toBytes`. Frames written before format version 4
+ * carry the older `AMQF` magic and are rejected here; re-serialize them with
+ * the version you run. Otherwise check that the bytes really are a distillate
+ * frame and not another payload, a text encoding of one, or a slice taken at
+ * the wrong offset.
  */
 declare class BadMagicError extends SerializationError {
   /** Discriminates this error from other `Error`s. */

package/dist/{serialize-ChyWpB9F.d.ts → serialize-Bv1zWzrh.d.ts}

@@ -15,19 +15,22 @@ declare class SerializationError extends Error {
   override readonly name: string;
 }
 /**
- * Thrown when a frame is shorter than its header plus trailer, or when its
- * body length does not match the length its declared params imply. The bytes
- * were cut short in transit or storage; re-fetch the whole frame.
+ * Thrown when a frame is shorter than its header plus trailer, when the body
+ * length its header declares disagrees with the bytes actually present, or
+ * when its body length does not match the length its declared params imply.
+ * The bytes were cut short in transit or storage; re-fetch the whole frame.
  */
 declare class TruncatedError extends SerializationError {
   /** Discriminates this error from other `Error`s. */
   override readonly name = "TruncatedError";
 }
 /**
- * Thrown when a frame does not start with the four-byte `AMQF` magic, so it
- * was never produced by `toBytes`. Check that the bytes really are a
- * distillate frame and not another payload, a text encoding of one, or a
- * slice taken at the wrong offset.
+ * Thrown when a frame does not start with the four-byte `DSTL` magic, so it
+ * was never produced by `toBytes`. Frames written before format version 4
+ * carry the older `AMQF` magic and are rejected here; re-serialize them with
+ * the version you run. Otherwise check that the bytes really are a distillate
+ * frame and not another payload, a text encoding of one, or a slice taken at
+ * the wrong offset.
  */
 declare class BadMagicError extends SerializationError {
   /** Discriminates this error from other `Error`s. */

package/dist/{serialize-BqIcsR2J.js → serialize-D59Ri81a.js}

@@ -305,21 +305,22 @@ function crc32(bytes) {
 	for (; i < len; i++) crc = (at(t, (crc ^ dv.getUint8(i)) & 255) ^ crc >>> 8) >>> 0;
 	return (crc ^ 4294967295) >>> 0;
 }
-const HEADER_SIZE = 8;
+const MAGIC = Uint8Array.of(68, 83, 84, 76);
+const HEADER_SIZE = 16;
+const BODY_LENGTH_OFFSET = 8;
 const TRAILER_SIZE = 4;
 function writeFrame(header, bodyLength, fill) {
 	const frame = new Uint8Array(HEADER_SIZE + bodyLength + TRAILER_SIZE);
-	frame[0] = 65;
-	frame[1] = 77;
-	frame[2] = 81;
-	frame[3] = 70;
+	const frameView = new DataView(frame.buffer, frame.byteOffset, frame.byteLength);
+	frame.set(MAGIC, 0);
 	frame[4] = header.version;
 	frame[5] = header.type;
 	frame[6] = header.flags;
 	frame[7] = 0;
+	frameView.setUint32(BODY_LENGTH_OFFSET, bodyLength, true);
 	fill(frame.subarray(HEADER_SIZE, HEADER_SIZE + bodyLength), new DataView(frame.buffer, HEADER_SIZE, bodyLength));
 	const crc = crc32(frame.subarray(0, HEADER_SIZE + bodyLength));
-	new DataView(frame.buffer, frame.byteOffset, frame.byteLength).setUint32(HEADER_SIZE + bodyLength, crc, true);
+	frameView.setUint32(HEADER_SIZE + bodyLength, crc, true);
 	return frame;
 }
 var SerializationError = class extends Error {
@@ -344,7 +345,7 @@ const JSON_TAG = "distillate";
 function toJSONEnvelope(bytes) {
 	return {
 		$: JSON_TAG,
-		v: 3,
+		v: 4,
 		data: toBase64(bytes)
 	};
 }
@@ -352,7 +353,7 @@ function fromJSONEnvelope(value) {
 	if (value === null || typeof value !== "object") throw new SerializationError("not a distillate filter JSON object");
 	const o = value;
 	if (o.$ !== JSON_TAG) throw new SerializationError(`expected "$":"${JSON_TAG}"`);
-	if (o.v !== 3) throw new UnknownVersionError(`unsupported JSON version ${String(o.v)}, expected ${String(3)}`);
+	if (o.v !== 4) throw new UnknownVersionError(`unsupported JSON version ${String(o.v)}, expected ${String(4)}`);
 	if (typeof o.data !== "string") throw new SerializationError("missing string \"data\"");
 	try {
 		return fromBase64(o.data);
@@ -372,16 +373,19 @@ function assertBodyLength(actual, expected, context) {
 	if (actual !== expected) throw new TruncatedError(`${context}: body of ${String(actual)} bytes does not match the declared params (expected ${String(expected)})`);
 }
 function readHeader(frame) {
-	if (frame.length < 12) throw new TruncatedError(`frame of ${String(frame.length)} bytes is shorter than the minimum ${String(12)}`);
-	if (frame[0] !== 65 || frame[1] !== 77 || frame[2] !== 81 || frame[3] !== 70) throw new BadMagicError("frame does not start with the AMQF magic");
+	if (frame.length < 20) throw new TruncatedError(`frame of ${String(frame.length)} bytes is shorter than the minimum ${String(20)}`);
+	for (let i = 0; i < MAGIC.length; i++) if (frame[i] !== MAGIC[i]) throw new BadMagicError("frame does not start with the DSTL magic");
 	const version = frame[4] ?? 0;
-	if (version !== 3) throw new UnknownVersionError(`unsupported format version ${String(version)}`);
-	if (new DataView(frame.buffer, frame.byteOffset, frame.byteLength).getUint32(frame.length - TRAILER_SIZE, true) !== crc32(frame.subarray(0, frame.length - TRAILER_SIZE))) throw new ChecksumError("frame CRC32 does not match its contents");
+	if (version !== 4) throw new UnknownVersionError(`unsupported format version ${String(version)}`);
+	const view = new DataView(frame.buffer, frame.byteOffset, frame.byteLength);
+	const bodyLength = view.getUint32(BODY_LENGTH_OFFSET, true);
+	if (HEADER_SIZE + bodyLength + TRAILER_SIZE !== frame.length) throw new TruncatedError(`frame declares a ${String(bodyLength)}-byte body but holds ${String(frame.length - HEADER_SIZE - TRAILER_SIZE)}`);
+	if (view.getUint32(frame.length - TRAILER_SIZE, true) !== crc32(frame.subarray(0, frame.length - TRAILER_SIZE))) throw new ChecksumError("frame CRC32 does not match its contents");
 	return {
 		version,
 		type: frame[5] ?? 0,
 		flags: frame[6] ?? 0,
-		body: frame.subarray(HEADER_SIZE, frame.length - TRAILER_SIZE)
+		body: frame.subarray(HEADER_SIZE, HEADER_SIZE + bodyLength)
 	};
 }
 //#endregion

package/dist/{serialize-CXnRWItH.cjs → serialize-Ul2LKFJU.cjs}

@@ -305,21 +305,22 @@ function crc32(bytes) {
 	for (; i < len; i++) crc = (at(t, (crc ^ dv.getUint8(i)) & 255) ^ crc >>> 8) >>> 0;
 	return (crc ^ 4294967295) >>> 0;
 }
-const HEADER_SIZE = 8;
+const MAGIC = Uint8Array.of(68, 83, 84, 76);
+const HEADER_SIZE = 16;
+const BODY_LENGTH_OFFSET = 8;
 const TRAILER_SIZE = 4;
 function writeFrame(header, bodyLength, fill) {
 	const frame = new Uint8Array(HEADER_SIZE + bodyLength + TRAILER_SIZE);
-	frame[0] = 65;
-	frame[1] = 77;
-	frame[2] = 81;
-	frame[3] = 70;
+	const frameView = new DataView(frame.buffer, frame.byteOffset, frame.byteLength);
+	frame.set(MAGIC, 0);
 	frame[4] = header.version;
 	frame[5] = header.type;
 	frame[6] = header.flags;
 	frame[7] = 0;
+	frameView.setUint32(BODY_LENGTH_OFFSET, bodyLength, true);
 	fill(frame.subarray(HEADER_SIZE, HEADER_SIZE + bodyLength), new DataView(frame.buffer, HEADER_SIZE, bodyLength));
 	const crc = crc32(frame.subarray(0, HEADER_SIZE + bodyLength));
-	new DataView(frame.buffer, frame.byteOffset, frame.byteLength).setUint32(HEADER_SIZE + bodyLength, crc, true);
+	frameView.setUint32(HEADER_SIZE + bodyLength, crc, true);
 	return frame;
 }
 var SerializationError = class extends Error {
@@ -344,7 +345,7 @@ const JSON_TAG = "distillate";
 function toJSONEnvelope(bytes) {
 	return {
 		$: JSON_TAG,
-		v: 3,
+		v: 4,
 		data: toBase64(bytes)
 	};
 }
@@ -352,7 +353,7 @@ function fromJSONEnvelope(value) {
 	if (value === null || typeof value !== "object") throw new SerializationError("not a distillate filter JSON object");
 	const o = value;
 	if (o.$ !== JSON_TAG) throw new SerializationError(`expected "$":"${JSON_TAG}"`);
-	if (o.v !== 3) throw new UnknownVersionError(`unsupported JSON version ${String(o.v)}, expected ${String(3)}`);
+	if (o.v !== 4) throw new UnknownVersionError(`unsupported JSON version ${String(o.v)}, expected ${String(4)}`);
 	if (typeof o.data !== "string") throw new SerializationError("missing string \"data\"");
 	try {
 		return fromBase64(o.data);
@@ -372,16 +373,19 @@ function assertBodyLength(actual, expected, context) {
 	if (actual !== expected) throw new TruncatedError(`${context}: body of ${String(actual)} bytes does not match the declared params (expected ${String(expected)})`);
 }
 function readHeader(frame) {
-	if (frame.length < 12) throw new TruncatedError(`frame of ${String(frame.length)} bytes is shorter than the minimum ${String(12)}`);
-	if (frame[0] !== 65 || frame[1] !== 77 || frame[2] !== 81 || frame[3] !== 70) throw new BadMagicError("frame does not start with the AMQF magic");
+	if (frame.length < 20) throw new TruncatedError(`frame of ${String(frame.length)} bytes is shorter than the minimum ${String(20)}`);
+	for (let i = 0; i < MAGIC.length; i++) if (frame[i] !== MAGIC[i]) throw new BadMagicError("frame does not start with the DSTL magic");
 	const version = frame[4] ?? 0;
-	if (version !== 3) throw new UnknownVersionError(`unsupported format version ${String(version)}`);
-	if (new DataView(frame.buffer, frame.byteOffset, frame.byteLength).getUint32(frame.length - TRAILER_SIZE, true) !== crc32(frame.subarray(0, frame.length - TRAILER_SIZE))) throw new ChecksumError("frame CRC32 does not match its contents");
+	if (version !== 4) throw new UnknownVersionError(`unsupported format version ${String(version)}`);
+	const view = new DataView(frame.buffer, frame.byteOffset, frame.byteLength);
+	const bodyLength = view.getUint32(BODY_LENGTH_OFFSET, true);
+	if (HEADER_SIZE + bodyLength + TRAILER_SIZE !== frame.length) throw new TruncatedError(`frame declares a ${String(bodyLength)}-byte body but holds ${String(frame.length - HEADER_SIZE - TRAILER_SIZE)}`);
+	if (view.getUint32(frame.length - TRAILER_SIZE, true) !== crc32(frame.subarray(0, frame.length - TRAILER_SIZE))) throw new ChecksumError("frame CRC32 does not match its contents");
 	return {
 		version,
 		type: frame[5] ?? 0,
 		flags: frame[6] ?? 0,
-		body: frame.subarray(HEADER_SIZE, frame.length - TRAILER_SIZE)
+		body: frame.subarray(HEADER_SIZE, HEADER_SIZE + bodyLength)
 	};
 }
 //#endregion

package/dist/sizing-BLzZk2zr.cjs

@@ -0,0 +1,28 @@
+const require_params = require("./params-UTZbJ22c.cjs");
+//#region src/core/sizing.ts
+function bloomSizing(n, epsilon) {
+	const m = Math.ceil(-n * Math.log(epsilon) / (Math.LN2 * Math.LN2));
+	return {
+		m,
+		k: Math.max(1, Math.round(m / n * Math.LN2))
+	};
+}
+function hllSizing(relativeError) {
+	require_params.assertProbability(relativeError, "relativeError");
+	const p = Math.max(4, Math.ceil(2 * Math.log2(1.04 / relativeError)));
+	if (p > 18) throw new require_params.ParamError(`relativeError ${String(relativeError)} needs precision ${String(p)}, above the maximum ${String(18)}`);
+	return { p };
+}
+//#endregion
+Object.defineProperty(exports, "bloomSizing", {
+	enumerable: true,
+	get: function() {
+		return bloomSizing;
+	}
+});
+Object.defineProperty(exports, "hllSizing", {
+	enumerable: true,
+	get: function() {
+		return hllSizing;
+	}
+});

package/dist/sizing-BtUrtvF_.js

@@ -0,0 +1,17 @@
+import { i as assertProbability, t as ParamError } from "./params-CeajSrwv.js";
+//#region src/core/sizing.ts
+function bloomSizing(n, epsilon) {
+	const m = Math.ceil(-n * Math.log(epsilon) / (Math.LN2 * Math.LN2));
+	return {
+		m,
+		k: Math.max(1, Math.round(m / n * Math.LN2))
+	};
+}
+function hllSizing(relativeError) {
+	assertProbability(relativeError, "relativeError");
+	const p = Math.max(4, Math.ceil(2 * Math.log2(1.04 / relativeError)));
+	if (p > 18) throw new ParamError(`relativeError ${String(relativeError)} needs precision ${String(p)}, above the maximum ${String(18)}`);
+	return { p };
+}
+//#endregion
+export { hllSizing as n, bloomSizing as t };

package/dist/sizing-wYOW27eY.d.cts

@@ -0,0 +1,22 @@
+//#region src/core/sizing.d.ts
+/** Bloom filter geometry: the `BloomParams` fields a sizing solve determines. */
+interface BloomSizing {
+  /** Number of bits in the filter. */
+  m: number;
+  /** Number of hash probes per key. */
+  k: number;
+}
+/** Optimal Bloom-filter sizing: `m` bits and `k` hashes for `n` items at target FPR `epsilon`. */
+declare function bloomSizing(n: number, epsilon: number): BloomSizing;
+/** HyperLogLog geometry: the `HllParams` fields a sizing solve determines. */
+interface HllSizing {
+  /** Precision: the sketch holds `2 ** p` registers. */
+  p: number;
+}
+/**
+ * Smallest precision whose standard error `1.04 / sqrt(2 ** p)` meets
+ * `relativeError`. Throws {@link ParamError} when even `HLL_MAX_P` cannot.
+ */
+declare function hllSizing(relativeError: number): HllSizing;
+//#endregion
+export { hllSizing as i, HllSizing as n, bloomSizing as r, BloomSizing as t };

package/dist/sizing-wYOW27eY.d.ts

@@ -0,0 +1,22 @@
+//#region src/core/sizing.d.ts
+/** Bloom filter geometry: the `BloomParams` fields a sizing solve determines. */
+interface BloomSizing {
+  /** Number of bits in the filter. */
+  m: number;
+  /** Number of hash probes per key. */
+  k: number;
+}
+/** Optimal Bloom-filter sizing: `m` bits and `k` hashes for `n` items at target FPR `epsilon`. */
+declare function bloomSizing(n: number, epsilon: number): BloomSizing;
+/** HyperLogLog geometry: the `HllParams` fields a sizing solve determines. */
+interface HllSizing {
+  /** Precision: the sketch holds `2 ** p` registers. */
+  p: number;
+}
+/**
+ * Smallest precision whose standard error `1.04 / sqrt(2 ** p)` meets
+ * `relativeError`. Throws {@link ParamError} when even `HLL_MAX_P` cannot.
+ */
+declare function hllSizing(relativeError: number): HllSizing;
+//#endregion
+export { hllSizing as i, HllSizing as n, bloomSizing as r, BloomSizing as t };