probe-filters 1.0.0

package/src/pointFilter.js

@@ -0,0 +1,871 @@
+/**
+ * PointFilter: An infinitely expandable filter with constant time operations.
+ * Based on the paper "Aleph Filter: To Infinity in Constant Time" by Dayan, Bercea, Pagh.
+ * PVLDB, 17(11): 3644 - 3656, 2024. doi:10.14778/3681954.3682027
+ */
+
+import { PackedBitset } from './packedBitset.js';
+import { BinaryWriter, BinaryReader, MAGIC, wrapCRC32, unwrapCRC32 } from './serialization.js';
+
+const EMPTY = 0;
+const OCCUPIED = 1;
+const VOID = 2;
+const TOMBSTONE = 3;
+const NO_CANONICAL = 0xffffffff;
+
+export function djb2(key, seed = 0) {
+    let h = (5381 + seed) | 0;
+    const l = key.length;
+    for (let i = 0; i < l; i++) h = ((h << 5) + h + key.charCodeAt(i)) | 0;
+    h ^= h >>> 16;
+    h = Math.imul(h, 0x85ebca6b);
+    h ^= h >>> 13;
+    h = Math.imul(h, 0xc2b2ae35);
+    h ^= h >>> 16;
+    return h >>> 0;
+}
+
+export class PointFilter {
+    constructor(options = {}) {
+        this.options = {
+            initialCapacity: 256,
+            fingerprintSize: 12,
+            estimatedMaxNFactor: null,
+            hashFunction: djb2,
+            expansionThreshold: 0.9,
+            ...options,
+        };
+
+        if (Math.log2(this.options.initialCapacity) % 1 !== 0) {
+            throw new Error("initialCapacity must be a power of 2.");
+        }
+        if (this.options.initialCapacity <= 0 || this.options.initialCapacity > 0x40000000) {
+            throw new Error("initialCapacity must fit in a 32-bit typed-array address space.");
+        }
+        if (this.options.fingerprintSize <= 0) {
+            throw new Error("fingerprintSize must be positive.");
+        }
+
+        const initialAddressBits = Math.log2(this.options.initialCapacity);
+        if (initialAddressBits + this.options.fingerprintSize > 32) {
+            throw new Error("initialCapacity and fingerprintSize must fit in one 32-bit hash.");
+        }
+
+        this.currentCapacity = this.options.initialCapacity;
+        this.numElements = 0;
+        this.currentExpansionLevel = 0;
+        this.bitsForSlotAddress = initialAddressBits;
+        this.currentFingerprintLengthForNewEntries = this.options.fingerprintSize;
+        this.fingerprintMasks = new Uint32Array(33);
+        this.fingerprintMasks[0] = 0;
+        for (let bits = 1; bits <= 32; bits++) {
+            this.fingerprintMasks[bits] = bits === 32 ? 0xffffffff : ((2 ** bits) - 1) >>> 0;
+        }
+        this._scratchCanonicalSlots = null;
+        this._scratchFingerprints = null;
+        this._scratchStates = null;
+        this._scratchFingerprintLengths = null;
+        this._scratchMotherHashes = null;
+        this._scratchOrder = null;
+
+        this.secondaryHashTable = {
+            slots: [],
+            capacity: this.options.initialCapacity / 2,
+            numElements: 0,
+        };
+        this.auxiliaryHashTables = [];
+        this.deletionQueue = [];
+        this.rejuvenationQueue = [];
+
+        this._allocateStorage(this.currentCapacity);
+    }
+
+    _allocateStorage(capacity) {
+        this.fingerprints = new Uint32Array(capacity);
+        this.canonicalSlots = new Uint32Array(capacity);
+        this.canonicalSlots.fill(NO_CANONICAL);
+        this.states = new Uint8Array(capacity);
+        this.fingerprintLengths = new Uint8Array(capacity);
+        this.motherHashes = new Uint32Array(capacity);
+        this.occupied = new PackedBitset(capacity);
+        this.shifted = new PackedBitset(capacity);
+        this.continuation = new PackedBitset(capacity);
+        this.runends = new PackedBitset(capacity);
+        this.runCounts = new Uint32Array(capacity);
+        this.blockOffsets = new Uint8Array(Math.ceil(capacity / 64));
+
+        this.mainHashTable = {
+            fingerprints: this.fingerprints,
+            canonicalSlots: this.canonicalSlots,
+            states: this.states,
+            fingerprintLengths: this.fingerprintLengths,
+            motherHashes: this.motherHashes,
+            occupied: this.occupied,
+            shifted: this.shifted,
+            continuation: this.continuation,
+            runends: this.runends,
+            runCounts: this.runCounts,
+            blockOffsets: this.blockOffsets,
+            capacity,
+        };
+    }
+
+    _isLiveEntry(index) {
+        return this.states[index] !== EMPTY && this.states[index] !== TOMBSTONE;
+    }
+
+    _rebuildPackedMetadata() {
+        this.occupied.clear();
+        this.shifted.clear();
+        this.continuation.clear();
+        this.runends.clear();
+        this.runCounts.fill(0);
+        this.blockOffsets.fill(0);
+
+        for (let index = 0; index < this.currentCapacity; index++) {
+            if (!this._isLiveEntry(index)) continue;
+
+            const canonicalSlot = this.canonicalSlots[index];
+            if (canonicalSlot === NO_CANONICAL) continue;
+
+            this.occupied.set(canonicalSlot, 1);
+            this.runCounts[canonicalSlot]++;
+            this.shifted.set(index, canonicalSlot !== index);
+
+            const previous = (index - 1 + this.currentCapacity) % this.currentCapacity;
+            if (this._isLiveEntry(previous) && this.canonicalSlots[previous] === canonicalSlot) {
+                this.continuation.set(index, 1);
+            }
+
+            const next = (index + 1) % this.currentCapacity;
+            if (!this._isLiveEntry(next) || this.canonicalSlots[next] !== canonicalSlot) {
+                this.runends.set(index, 1);
+            }
+        }
+
+        for (let block = 0; block < this.blockOffsets.length; block++) {
+            const blockStart = block * 64;
+            let offset = 0;
+            while (blockStart + offset < this.currentCapacity && offset < 255 && this.shifted.get(blockStart + offset) === 1) {
+                offset++;
+            }
+            this.blockOffsets[block] = offset;
+        }
+    }
+
+    _ensureCompactionScratch(capacity) {
+        if (this._scratchCanonicalSlots && this._scratchCanonicalSlots.length >= capacity) {
+            return;
+        }
+
+        this._scratchCanonicalSlots = new Uint32Array(capacity);
+        this._scratchFingerprints = new Uint32Array(capacity);
+        this._scratchStates = new Uint8Array(capacity);
+        this._scratchFingerprintLengths = new Uint8Array(capacity);
+        this._scratchMotherHashes = new Uint32Array(capacity);
+        this._scratchOrder = new Uint32Array(capacity);
+    }
+
+    _collectLiveEntriesIntoScratch() {
+        this._ensureCompactionScratch(this.currentCapacity);
+
+        let count = 0;
+        for (let index = 0; index < this.currentCapacity; index++) {
+            if (!this._isLiveEntry(index)) continue;
+
+            this._scratchCanonicalSlots[count] = this.canonicalSlots[index];
+            this._scratchFingerprints[count] = this.fingerprints[index];
+            this._scratchStates[count] = this.states[index];
+            this._scratchFingerprintLengths[count] = this.fingerprintLengths[index];
+            this._scratchMotherHashes[count] = this.motherHashes[index];
+            this._scratchOrder[count] = count;
+            count++;
+        }
+
+        return count;
+    }
+
+    _clearStorage() {
+        this.fingerprints.fill(0);
+        this.canonicalSlots.fill(NO_CANONICAL);
+        this.states.fill(EMPTY);
+        this.fingerprintLengths.fill(0);
+        this.motherHashes.fill(0);
+        this.runCounts.fill(0);
+    }
+
+    _compactRuns() {
+        const count = this._collectLiveEntriesIntoScratch();
+        const order = this._scratchOrder.subarray(0, count);
+
+        order.sort((a, b) => {
+            const canonicalA = this._scratchCanonicalSlots[a];
+            const canonicalB = this._scratchCanonicalSlots[b];
+            if (canonicalA !== canonicalB) return canonicalA - canonicalB;
+
+            const stateA = this._scratchStates[a];
+            const stateB = this._scratchStates[b];
+            if (stateA !== stateB) return stateA - stateB;
+
+            const fingerprintA = this._scratchFingerprints[a];
+            const fingerprintB = this._scratchFingerprints[b];
+            if (fingerprintA !== fingerprintB) return fingerprintA - fingerprintB;
+
+            return this._scratchFingerprintLengths[b] - this._scratchFingerprintLengths[a];
+        });
+
+        this._clearStorage();
+
+        for (let orderIndex = 0; orderIndex < count; orderIndex++) {
+            const scratchIndex = order[orderIndex];
+            const canonicalSlot = this._scratchCanonicalSlots[scratchIndex];
+            let placed = false;
+            for (let distance = 0; distance < this.currentCapacity; distance++) {
+                const index = (canonicalSlot + distance) % this.currentCapacity;
+                if (this.states[index] === EMPTY) {
+                    this._writeSlot(
+                        index,
+                        canonicalSlot,
+                        this._scratchFingerprints[scratchIndex],
+                        this._scratchStates[scratchIndex],
+                        this._scratchFingerprintLengths[scratchIndex],
+                        this._scratchMotherHashes[scratchIndex]
+                    );
+                    placed = true;
+                    break;
+                }
+            }
+            if (!placed) {
+                throw new Error('Filter is full while compacting RSQF runs.');
+            }
+        }
+
+        this._rebuildPackedMetadata();
+    }
+
+    _runEndByRank(canonicalSlot) {
+        if (this.occupied.get(canonicalSlot) === 0) return -1;
+
+        let runStart = -1;
+        for (let distance = 0; distance < this.currentCapacity; distance++) {
+            const index = (canonicalSlot + distance) % this.currentCapacity;
+            if (this._isLiveEntry(index) && this.canonicalSlots[index] === canonicalSlot) {
+                runStart = index;
+                break;
+            }
+        }
+
+        if (runStart === -1) return -1;
+
+        let current = runStart;
+        for (let steps = 0; steps < this.currentCapacity; steps++) {
+            const next = (current + 1) % this.currentCapacity;
+            if (!this._isLiveEntry(next) || this.canonicalSlots[next] !== canonicalSlot) {
+                return current;
+            }
+            current = next;
+        }
+
+        return runStart;
+    }
+
+    _runStartByRank(canonicalSlot) {
+        if (this.occupied.get(canonicalSlot) === 0) return -1;
+
+        for (let distance = 0; distance < this.currentCapacity; distance++) {
+            const index = (canonicalSlot + distance) % this.currentCapacity;
+            if (this._isLiveEntry(index) && this.canonicalSlots[index] === canonicalSlot) {
+                return index;
+            }
+        }
+
+        return -1;
+    }
+
+    _forEachSlotInRun(canonicalSlot, visitor) {
+        const runStart = this._runStartByRank(canonicalSlot);
+        if (runStart === -1) return false;
+
+        let current = runStart;
+        for (let steps = 0; steps < this.currentCapacity; steps++) {
+            if (visitor(current) === true) return true;
+            if (this.runends.get(current) === 1) break;
+            current = (current + 1) % this.currentCapacity;
+        }
+
+        return false;
+    }
+
+    metadataBitsPerSlot() {
+        return 2.125;
+    }
+
+    debugMetadata(index) {
+        return {
+            occupied: this.occupied.get(index),
+            shifted: this.shifted.get(index),
+            continuation: this.continuation.get(index),
+            runend: this.runends.get(index),
+            blockOffset: this.blockOffsets[index >>> 6],
+        };
+    }
+
+    validatePackedInvariants() {
+        for (let index = 0; index < this.currentCapacity; index++) {
+            if (this._isLiveEntry(index) && this.canonicalSlots[index] !== NO_CANONICAL && this.occupied.get(this.canonicalSlots[index]) !== 1) {
+                return false;
+            }
+
+            if (this.runends.get(index) === 1 && !this._isLiveEntry(index)) {
+                return false;
+            }
+        }
+
+        for (let index = 0; index < this.currentCapacity; index++) {
+            if (this.occupied.get(index) === 0) continue;
+            const runStart = this._runStartByRank(index);
+            const runEnd = this._runEndByRank(index);
+            if (runStart === -1 || runEnd === -1) return false;
+
+            let foundEntry = false;
+            let current = runStart;
+            for (let steps = 0; steps < this.currentCapacity; steps++) {
+                if (!this._isLiveEntry(current)) return false;
+                if (this.canonicalSlots[current] === index) foundEntry = true;
+                if (current === runEnd) break;
+                current = (current + 1) % this.currentCapacity;
+            }
+            if (!foundEntry) return false;
+        }
+
+        return true;
+    }
+
+    _getMotherHash(element) {
+        return this.options.hashFunction(String(element), 0) >>> 0;
+    }
+
+    _getSlotAndFingerprint(motherHash, currentFingerprintBits, currentAddressBits) {
+        const addressSpace = 2 ** currentAddressBits;
+        const canonicalSlot = motherHash % addressSpace;
+        const shiftedHash = Math.floor(motherHash / addressSpace);
+        const fingerprintSpace = 2 ** currentFingerprintBits;
+        const fingerprint = shiftedHash % fingerprintSpace;
+
+        return { canonicalSlot, fingerprint };
+    }
+
+    _fingerprintMatches(index, queryFingerprint) {
+        const state = this.states[index];
+        if (state === VOID) return true;
+
+        const length = this.fingerprintLengths[index];
+        if (length === 0) return false;
+
+        const mask = this.fingerprintMasks[length];
+        return this.fingerprints[index] === (queryFingerprint & mask);
+    }
+
+    _findSlot(canonicalSlot, fingerprint, allowVoid = true) {
+        let found = -1;
+
+        this._forEachSlotInRun(canonicalSlot, (index) => {
+            const state = this.states[index];
+
+            if ((allowVoid && state === VOID) || this._fingerprintMatches(index, fingerprint)) {
+                found = index;
+                return true;
+            }
+
+            return false;
+        });
+
+        return { found, insertionPoint: found === -1 ? this._findReusableSlot(canonicalSlot) : -1 };
+    }
+
+    _findReusableSlot(canonicalSlot) {
+        for (let distance = 0; distance < this.currentCapacity; distance++) {
+            const index = (canonicalSlot + distance) % this.currentCapacity;
+            if (this.states[index] === EMPTY || this.states[index] === TOMBSTONE) {
+                return index;
+            }
+        }
+        return -1;
+    }
+
+    _setOccupiedFromCount(canonicalSlot) {
+        this.occupied.set(canonicalSlot, this.runCounts[canonicalSlot] > 0 ? 1 : 0);
+    }
+
+    _copySlot(fromIndex, toIndex) {
+        this.fingerprints[toIndex] = this.fingerprints[fromIndex];
+        this.canonicalSlots[toIndex] = this.canonicalSlots[fromIndex];
+        this.states[toIndex] = this.states[fromIndex];
+        this.fingerprintLengths[toIndex] = this.fingerprintLengths[fromIndex];
+        this.motherHashes[toIndex] = this.motherHashes[fromIndex];
+    }
+
+    _clearSlot(index) {
+        this.fingerprints[index] = 0;
+        this.canonicalSlots[index] = NO_CANONICAL;
+        this.states[index] = EMPTY;
+        this.fingerprintLengths[index] = 0;
+        this.motherHashes[index] = 0;
+    }
+
+    _findRunInsertIndex(canonicalSlot) {
+        if (this.occupied.get(canonicalSlot) === 1) {
+            const ownRunEnd = this._runEndByRank(canonicalSlot);
+            if (ownRunEnd !== -1) {
+                return (ownRunEnd + 1) % this.currentCapacity;
+            }
+            return canonicalSlot;
+        }
+
+        for (let distance = 1; distance <= this.currentCapacity; distance++) {
+            const previousCanonical = (canonicalSlot - distance + this.currentCapacity) % this.currentCapacity;
+            if (this.occupied.get(previousCanonical) === 0) continue;
+
+            const previousRunEnd = this._runEndByRank(previousCanonical);
+            if (previousRunEnd !== -1) {
+                return (previousRunEnd + 1) % this.currentCapacity;
+            }
+        }
+
+        return canonicalSlot;
+    }
+
+    _shiftRightForInsertion(targetIndex) {
+        const reusableIndex = this._findReusableSlot(targetIndex);
+        if (reusableIndex === -1) return -1;
+
+        let hole = reusableIndex;
+        while (hole !== targetIndex) {
+            const previous = (hole - 1 + this.currentCapacity) % this.currentCapacity;
+            this._copySlot(previous, hole);
+            hole = previous;
+        }
+
+        this._clearSlot(targetIndex);
+        return reusableIndex;
+    }
+
+    _shiftLeftAfterDeletion(deletedIndex) {
+        let hole = deletedIndex;
+        let next = (hole + 1) % this.currentCapacity;
+
+        while (this._isLiveEntry(next)) {
+            this._copySlot(next, hole);
+            hole = next;
+            next = (next + 1) % this.currentCapacity;
+        }
+
+        this._clearSlot(hole);
+        return hole;
+    }
+
+    _forEachIndexInWrappedRange(startIndex, endIndex, visitor) {
+        let current = startIndex;
+        for (let steps = 0; steps < this.currentCapacity; steps++) {
+            visitor(current);
+            if (current === endIndex) return;
+            current = (current + 1) % this.currentCapacity;
+        }
+    }
+
+    _recomputeMetadataIndex(index) {
+        if (!this._isLiveEntry(index)) {
+            this.shifted.set(index, 0);
+            this.continuation.set(index, 0);
+            this.runends.set(index, 0);
+            return;
+        }
+
+        const canonicalSlot = this.canonicalSlots[index];
+        this.shifted.set(index, canonicalSlot !== index ? 1 : 0);
+
+        const previous = (index - 1 + this.currentCapacity) % this.currentCapacity;
+        const continuation = this._isLiveEntry(previous) && this.canonicalSlots[previous] === canonicalSlot;
+        this.continuation.set(index, continuation ? 1 : 0);
+
+        const next = (index + 1) % this.currentCapacity;
+        const runEnd = !this._isLiveEntry(next) || this.canonicalSlots[next] !== canonicalSlot;
+        this.runends.set(index, runEnd ? 1 : 0);
+    }
+
+    _recomputeBlockOffset(block) {
+        const blockStart = block * 64;
+        let offset = 0;
+        while (blockStart + offset < this.currentCapacity && offset < 255 && this.shifted.get(blockStart + offset) === 1) {
+            offset++;
+        }
+        this.blockOffsets[block] = offset;
+    }
+
+    _recomputeMetadataWindow(startIndex, endIndex) {
+        this._forEachIndexInWrappedRange(startIndex, endIndex, (index) => {
+            this._recomputeMetadataIndex(index);
+        });
+
+        const startBlock = startIndex >>> 6;
+        const endBlock = endIndex >>> 6;
+        if (startBlock <= endBlock) {
+            for (let block = startBlock; block <= endBlock; block++) {
+                this._recomputeBlockOffset(block);
+            }
+        } else {
+            for (let block = startBlock; block < this.blockOffsets.length; block++) {
+                this._recomputeBlockOffset(block);
+            }
+            for (let block = 0; block <= endBlock; block++) {
+                this._recomputeBlockOffset(block);
+            }
+        }
+    }
+
+    _writeSlot(index, canonicalSlot, fingerprint, state, fingerprintLength, motherHash = 0) {
+        this.fingerprints[index] = fingerprint >>> 0;
+        this.canonicalSlots[index] = canonicalSlot >>> 0;
+        this.states[index] = state;
+        this.fingerprintLengths[index] = fingerprintLength;
+        this.motherHashes[index] = motherHash >>> 0;
+    }
+
+    _performInsertion(canonicalSlot, fingerprint, state = OCCUPIED, fingerprintLength = this.currentFingerprintLengthForNewEntries, motherHash = 0) {
+        const { found } = this._findLongestMatchingSlot(canonicalSlot, fingerprint, false, motherHash);
+        if (found !== -1 && this.motherHashes[found] === (motherHash >>> 0)) {
+            return false;
+        }
+
+        let insertionPoint = this._findRunInsertIndex(canonicalSlot);
+        let reusableIndex = this._shiftRightForInsertion(insertionPoint);
+
+        if (reusableIndex === -1) {
+            this.expand();
+            insertionPoint = this._findRunInsertIndex(canonicalSlot);
+            reusableIndex = this._shiftRightForInsertion(insertionPoint);
+            if (reusableIndex === -1) {
+                throw new Error("Filter is full after expansion.");
+            }
+        }
+
+        this._writeSlot(insertionPoint, canonicalSlot, fingerprint, state, fingerprintLength, motherHash);
+        this.runCounts[canonicalSlot]++;
+        this._setOccupiedFromCount(canonicalSlot);
+
+        const windowStart = (insertionPoint - 1 + this.currentCapacity) % this.currentCapacity;
+        const windowEnd = (reusableIndex + 1) % this.currentCapacity;
+        this._recomputeMetadataWindow(windowStart, windowEnd);
+
+        this.numElements++;
+        return true;
+    }
+
+    _performInsertionNoCompact(canonicalSlot, fingerprint, state = OCCUPIED, fingerprintLength = this.currentFingerprintLengthForNewEntries, motherHash = 0) {
+        const insertionPoint = this._findReusableSlot(canonicalSlot);
+        if (insertionPoint === -1) {
+            throw new Error("Filter is full while batching expansion insertions.");
+        }
+
+        this._writeSlot(insertionPoint, canonicalSlot, fingerprint, state, fingerprintLength, motherHash);
+        this.runCounts[canonicalSlot]++;
+        this._setOccupiedFromCount(canonicalSlot);
+        this.numElements++;
+        return true;
+    }
+
+    insert(element) {
+        if ((this.numElements + 1) / this.currentCapacity >= this.options.expansionThreshold) {
+            this.expand();
+        }
+
+        const motherHash = this._getMotherHash(element);
+        const fingerprintBits = Math.min(this.currentFingerprintLengthForNewEntries, 32 - this.bitsForSlotAddress);
+        if (fingerprintBits <= 0) {
+            throw new Error("Cannot insert with zero fingerprint bits under the 32-bit hash constraint.");
+        }
+
+        const addressSpace = 2 ** this.bitsForSlotAddress;
+        const canonicalSlot = motherHash % addressSpace;
+        const shiftedHash = Math.floor(motherHash / addressSpace);
+        const fingerprintSpace = 2 ** fingerprintBits;
+        const fingerprint = shiftedHash % fingerprintSpace;
+
+        this._performInsertion(canonicalSlot, fingerprint, OCCUPIED, fingerprintBits, motherHash);
+    }
+
+    query(element) {
+        const motherHash = this._getMotherHash(element);
+        const fingerprintBits = Math.min(this.options.fingerprintSize, 32 - this.bitsForSlotAddress);
+        if (fingerprintBits < 0) return false;
+        const addressSpace = 2 ** this.bitsForSlotAddress;
+        const canonicalSlot = motherHash % addressSpace;
+        const shiftedHash = Math.floor(motherHash / addressSpace);
+        const fingerprintSpace = 2 ** fingerprintBits;
+        const fingerprint = shiftedHash % fingerprintSpace;
+        return this._queryWithParams(canonicalSlot, fingerprint);
+    }
+
+    _queryWithParams(canonicalSlot, fingerprint) {
+        return this._findSlot(canonicalSlot, fingerprint, true).found !== -1;
+    }
+
+    delete(element) {
+        const motherHash = this._getMotherHash(element);
+        const fingerprintBits = Math.min(this.options.fingerprintSize, 32 - this.bitsForSlotAddress);
+        if (fingerprintBits < 0) return false;
+        const addressSpace = 2 ** this.bitsForSlotAddress;
+        const canonicalSlot = motherHash % addressSpace;
+        const shiftedHash = Math.floor(motherHash / addressSpace);
+        const fingerprintSpace = 2 ** fingerprintBits;
+        const fingerprint = shiftedHash % fingerprintSpace;
+        return this._deleteWithParams(canonicalSlot, fingerprint, motherHash);
+    }
+
+    _deleteWithParams(canonicalSlot, fingerprint, motherHash = 0) {
+        const { found } = this._findLongestMatchingSlot(canonicalSlot, fingerprint, true, motherHash);
+        if (found === -1) {
+            return false;
+        }
+
+        if (this.states[found] === VOID) {
+            this.deletionQueue.push(motherHash >>> 0);
+        }
+
+        this.runCounts[canonicalSlot]--;
+        this._setOccupiedFromCount(canonicalSlot);
+
+        const leftBoundary = found;
+        const rightBoundary = this._shiftLeftAfterDeletion(found);
+        const windowStart = (leftBoundary - 1 + this.currentCapacity) % this.currentCapacity;
+        const windowEnd = (rightBoundary + 1) % this.currentCapacity;
+        this._recomputeMetadataWindow(windowStart, windowEnd);
+
+        this.numElements--;
+
+        return true;
+    }
+
+    _findLongestMatchingSlot(canonicalSlot, fingerprint, allowVoid = true, motherHash = null) {
+        let found = -1;
+        let bestLength = -1;
+        let foundExactMotherHash = false;
+        let insertionPoint = -1;
+        const normalizedMotherHash = motherHash === null ? null : motherHash >>> 0;
+
+        this._forEachSlotInRun(canonicalSlot, (index) => {
+            const state = this.states[index];
+            const exactMotherHash = normalizedMotherHash !== null && this.motherHashes[index] === normalizedMotherHash;
+
+            if (state === VOID && allowVoid && (!foundExactMotherHash || exactMotherHash) && bestLength < 0) {
+                found = index;
+                bestLength = 0;
+                foundExactMotherHash = exactMotherHash;
+                return false;
+            }
+
+            if (state === OCCUPIED && this._fingerprintMatches(index, fingerprint) &&
+                ((exactMotherHash && !foundExactMotherHash) || (!foundExactMotherHash && this.fingerprintLengths[index] > bestLength))) {
+                found = index;
+                bestLength = this.fingerprintLengths[index];
+                foundExactMotherHash = exactMotherHash;
+            }
+
+            return false;
+        });
+
+        return { found, insertionPoint };
+    }
+
+    expand() {
+        const oldFingerprints = this.fingerprints;
+        const oldCanonicalSlots = this.canonicalSlots;
+        const oldStates = this.states;
+        const oldFingerprintLengths = this.fingerprintLengths;
+        const oldMotherHashes = this.motherHashes;
+        const oldCapacity = this.currentCapacity;
+        const oldBitsForSlotAddress = this.bitsForSlotAddress;
+        const deletedVoidHashes = new Set(this.deletionQueue);
+
+        if (oldBitsForSlotAddress >= 31) {
+            throw new Error("Cannot expand further within the 32-bit address constraint.");
+        }
+
+        this.currentCapacity *= 2;
+        this.bitsForSlotAddress++;
+        this.currentExpansionLevel++;
+        this._allocateStorage(this.currentCapacity);
+        this.numElements = 0;
+
+        for (let slotIndex = 0; slotIndex < oldCapacity; slotIndex++) {
+            const state = oldStates[slotIndex];
+            if (state === EMPTY || state === TOMBSTONE) {
+                continue;
+            }
+            if (deletedVoidHashes.has(oldMotherHashes[slotIndex])) {
+                continue;
+            }
+
+            const oldCanonical = oldCanonicalSlots[slotIndex];
+            if (oldCanonical === NO_CANONICAL) {
+                continue;
+            }
+
+            if (state === VOID || oldFingerprintLengths[slotIndex] === 0) {
+                this._performInsertionNoCompact(oldCanonical, 0, VOID, 0, oldMotherHashes[slotIndex]);
+                this._performInsertionNoCompact(oldCanonical + oldCapacity, 0, VOID, 0, oldMotherHashes[slotIndex]);
+                continue;
+            }
+
+            const oldFingerprint = oldFingerprints[slotIndex] >>> 0;
+            const newAddressBit = oldFingerprint & 1;
+            const newCanonical = oldCanonical + (newAddressBit * oldCapacity);
+            const newFingerprint = oldFingerprint >>> 1;
+            const newLength = oldFingerprintLengths[slotIndex] - 1;
+
+            if (newLength === 0) {
+                this._performInsertionNoCompact(newCanonical, 0, VOID, 0, oldMotherHashes[slotIndex]);
+            } else {
+                this._performInsertionNoCompact(newCanonical, newFingerprint, OCCUPIED, newLength, oldMotherHashes[slotIndex]);
+            }
+        }
+
+        this.deletionQueue = [];
+        this._compactRuns();
+    }
+
+    rejuvenate(element) {
+        const motherHash = this._getMotherHash(element);
+        const fingerprintBits = Math.min(this.options.fingerprintSize, 32 - this.bitsForSlotAddress);
+        if (fingerprintBits < 0) return false;
+        const addressSpace = 2 ** this.bitsForSlotAddress;
+        const canonicalSlot = motherHash % addressSpace;
+        const shiftedHash = Math.floor(motherHash / addressSpace);
+        const fingerprintSpace = 2 ** fingerprintBits;
+        const fingerprint = shiftedHash % fingerprintSpace;
+        return this._rejuvenateWithParams(canonicalSlot, fingerprint, motherHash);
+    }
+
+    _rejuvenateWithParams(canonicalSlot, fingerprint, motherHash) {
+        const { found } = this._findLongestMatchingSlot(canonicalSlot, fingerprint, true, motherHash);
+        if (found === -1) {
+            return false;
+        }
+
+        const fullFingerprintBits = Math.min(this.options.fingerprintSize, 32 - this.bitsForSlotAddress);
+        if (fullFingerprintBits <= 0) {
+            return false;
+        }
+
+        const { fingerprint: fullFingerprint } = this._getSlotAndFingerprint(
+            motherHash,
+            fullFingerprintBits,
+            this.bitsForSlotAddress
+        );
+
+        this.fingerprints[found] = fullFingerprint >>> 0;
+        this.states[found] = OCCUPIED;
+        this.fingerprintLengths[found] = fullFingerprintBits;
+        this.motherHashes[found] = motherHash >>> 0;
+        this.rejuvenationQueue.push(motherHash >>> 0);
+        return true;
+    }
+
+    getStats() {
+        return {
+            capacity: this.currentCapacity,
+            numElements: this.numElements,
+            expansionLevel: this.currentExpansionLevel,
+            bitsForSlotAddress: this.bitsForSlotAddress,
+            fingerprintSize: this.options.fingerprintSize,
+            currentFingerprintLength: this.currentFingerprintLengthForNewEntries,
+            loadFactor: this.numElements / this.currentCapacity,
+            deletionQueueSize: this.deletionQueue.length,
+            rejuvenationQueueSize: this.rejuvenationQueue.length,
+        };
+    }
+
+    serialize() {
+        const writer = new BinaryWriter();
+        writer.uint32(MAGIC.POINT);
+        writer.uint32(this.currentCapacity);
+        writer.uint32(this.numElements);
+        writer.uint32(this.bitsForSlotAddress);
+        writer.uint32(this.options.fingerprintSize);
+        writer.uint32(this.currentFingerprintLengthForNewEntries);
+        writer.uint32(this.deletionQueue.length);
+        for (const entry of this.deletionQueue) writer.uint32(entry);
+        writer.uint32(this.rejuvenationQueue.length);
+        for (const entry of this.rejuvenationQueue) writer.uint32(entry);
+
+        const live = [];
+        for (let i = 0; i < this.currentCapacity; i++) {
+            if (this._isLiveEntry(i)) live.push(i);
+        }
+
+        writer.uint32(live.length);
+        writer.uint8(this.currentCapacity <= 0xffff ? 2 : 4);
+        for (const index of live) {
+            if (this.currentCapacity <= 0xffff) writer.uint16(index);
+            else writer.uint32(index);
+            writer.uint8((this.states[index] << 6) | this.fingerprintLengths[index]);
+            writer.uint32(this.motherHashes[index]);
+        }
+        return wrapCRC32(writer.toArrayBuffer());
+    }
+
+    static deserialize(buffer, options = {}) {
+        buffer = unwrapCRC32(buffer);
+        const reader = new BinaryReader(buffer);
+        const magic = reader.uint32();
+        if (magic !== MAGIC.POINT) throw new Error('Not a PointFilter binary.');
+
+        const capacity = reader.uint32();
+        const numElements = reader.uint32();
+        const bitsForSlotAddress = reader.uint32();
+        const fingerprintSize = reader.uint32();
+        const currentFingerprintLength = reader.uint32();
+
+        const initialCapacity = 2 ** Math.ceil(Math.log2(capacity));
+        const filter = new PointFilter({
+            initialCapacity,
+            fingerprintSize,
+            ...options,
+        });
+        filter.currentCapacity = capacity;
+        filter.numElements = numElements;
+        filter.currentFingerprintLengthForNewEntries = currentFingerprintLength;
+        filter.bitsForSlotAddress = bitsForSlotAddress;
+
+        if (capacity !== initialCapacity) {
+            filter._allocateStorage(capacity);
+        }
+
+        const dqLen = reader.uint32();
+        filter.deletionQueue = [];
+        for (let i = 0; i < dqLen; i++) filter.deletionQueue.push(reader.uint32());
+
+        const rqLen = reader.uint32();
+        filter.rejuvenationQueue = [];
+        for (let i = 0; i < rqLen; i++) filter.rejuvenationQueue.push(reader.uint32());
+
+        const liveCount = reader.uint32();
+        const indexBytes = reader.uint8();
+        if (indexBytes !== 2 && indexBytes !== 4) throw new Error('Unsupported PointFilter index width.');
+        for (let i = 0; i < liveCount; i++) {
+            const index = indexBytes === 2 ? reader.uint16() : reader.uint32();
+            const meta = reader.uint8();
+            const state = meta >>> 6;
+            const fingerprintLength = meta & 0x3f;
+            const motherHash = reader.uint32();
+            filter.states[index] = state;
+            filter.fingerprintLengths[index] = fingerprintLength;
+            filter.motherHashes[index] = motherHash;
+            filter.canonicalSlots[index] = motherHash & (capacity - 1);
+            filter.fingerprints[index] = (motherHash >>> bitsForSlotAddress) & filter.fingerprintMasks[fingerprintLength];
+        }
+        filter._rebuildPackedMetadata();
+
+        return filter;
+    }
+}