probe-filters 1.0.0

package/src/spatialFilter.js

@@ -0,0 +1,317 @@
+import { RangeFilter } from './rangeFilter.js';
+import { BinaryWriter, BinaryReader, MAGIC, wrapCRC32, unwrapCRC32 } from './serialization.js';
+
+function assertGridCoordinate(value, bitsPerCoordinate, label) {
+    const max = 2 ** bitsPerCoordinate;
+    if (!Number.isInteger(value) || value < 0 || value >= max) {
+        throw new Error(`${label} must be an integer in [0, ${max}).`);
+    }
+    return value >>> 0;
+}
+
+function parseFiniteCoordinate(value, label) {
+    const parsed = typeof value === 'string' ? Number(value) : value;
+    if (!Number.isFinite(parsed)) {
+        throw new Error(`${label} must be a finite numeric coordinate.`);
+    }
+    return parsed;
+}
+
+function clamp(value, min, max) {
+    return Math.max(min, Math.min(max, value));
+}
+
+function scaleToGrid(value, min, max, bitsPerCoordinate, label) {
+    const parsed = parseFiniteCoordinate(value, label);
+    if (parsed < min || parsed > max) {
+        throw new Error(`${label} must be in [${min}, ${max}].`);
+    }
+
+    const gridMax = (2 ** bitsPerCoordinate) - 1;
+    const unit = (parsed - min) / (max - min);
+    return clamp(Math.floor(unit * gridMax), 0, gridMax) >>> 0;
+}
+
+function makeCoordinateCodec(options) {
+    const bitsPerCoordinate = options.bitsPerCoordinate;
+    const system = options.coordinateSystem ?? 'uint';
+
+    if (options.coordinateCodec) {
+        return options.coordinateCodec;
+    }
+
+    const base = {
+        gridMax: (2 ** bitsPerCoordinate) - 1,
+    };
+
+    if (system === 'latlon') {
+        return {
+            ...base,
+            normalizePoint(point) {
+                if (!Array.isArray(point) || point.length !== 2) {
+                    throw new Error('Lat/lon points must be [lat, lon] pairs.');
+                }
+                return {
+                    x: scaleToGrid(point[1], -180, 180, bitsPerCoordinate, 'lon'),
+                    y: scaleToGrid(point[0], -90, 90, bitsPerCoordinate, 'lat'),
+                    raw: point,
+                };
+            },
+            normalizeBox(min, max) {
+                if (!Array.isArray(min) || !Array.isArray(max) || min.length !== 2 || max.length !== 2) {
+                    throw new Error('Lat/lon boxes must use [lat, lon] min/max pairs.');
+                }
+                const minLat = parseFiniteCoordinate(min[0], 'min lat');
+                const minLon = parseFiniteCoordinate(min[1], 'min lon');
+                const maxLat = parseFiniteCoordinate(max[0], 'max lat');
+                const maxLon = parseFiniteCoordinate(max[1], 'max lon');
+                if (minLat > maxLat || minLon > maxLon) {
+                    throw new Error('Lat/lon box min coordinates must be <= max coordinates.');
+                }
+                return {
+                    minX: scaleToGrid(minLon, -180, 180, bitsPerCoordinate, 'min lon'),
+                    minY: scaleToGrid(minLat, -90, 90, bitsPerCoordinate, 'min lat'),
+                    maxX: scaleToGrid(maxLon, -180, 180, bitsPerCoordinate, 'max lon'),
+                    maxY: scaleToGrid(maxLat, -90, 90, bitsPerCoordinate, 'max lat'),
+                };
+            },
+        };
+    }
+
+    if (system === 'float') {
+        const bounds = options.bounds ?? [[0, 0], [1, 1]];
+        const minB = bounds[0], maxB = bounds[1];
+        return {
+            ...base,
+            normalizePoint(point) {
+                if (!Array.isArray(point) || point.length !== 2) {
+                    throw new Error('Float spatial points must be [x, y] pairs.');
+                }
+                return {
+                    x: scaleToGrid(point[0], minB[0], maxB[0], bitsPerCoordinate, 'x'),
+                    y: scaleToGrid(point[1], minB[1], maxB[1], bitsPerCoordinate, 'y'),
+                    raw: point,
+                };
+            },
+            normalizeBox(min, max) {
+                if (!Array.isArray(min) || !Array.isArray(max) || min.length !== 2 || max.length !== 2) {
+                    throw new Error('Float spatial boxes must use [x, y] min/max pairs.');
+                }
+                const mx = parseFiniteCoordinate(min[0], 'min x');
+                const my = parseFiniteCoordinate(min[1], 'min y');
+                const Mx = parseFiniteCoordinate(max[0], 'max x');
+                const My = parseFiniteCoordinate(max[1], 'max y');
+                if (mx > Mx || my > My) {
+                    throw new Error('Float spatial box min coordinates must be <= max coordinates.');
+                }
+                return {
+                    minX: scaleToGrid(mx, minB[0], maxB[0], bitsPerCoordinate, 'min x'),
+                    minY: scaleToGrid(my, minB[1], maxB[1], bitsPerCoordinate, 'min y'),
+                    maxX: scaleToGrid(Mx, minB[0], maxB[0], bitsPerCoordinate, 'max x'),
+                    maxY: scaleToGrid(My, minB[1], maxB[1], bitsPerCoordinate, 'max y'),
+                };
+            },
+        };
+    }
+
+    return {
+        ...base,
+        normalizePoint(point) {
+            if (!Array.isArray(point) || point.length !== 2) {
+                throw new Error('Spatial points must be [x, y] pairs.');
+            }
+            const x = assertGridCoordinate(point[0], bitsPerCoordinate, 'x');
+            const y = assertGridCoordinate(point[1], bitsPerCoordinate, 'y');
+            return { x, y, raw: point };
+        },
+        normalizeBox(min, max) {
+            const a = this.normalizePoint(min);
+            const b = this.normalizePoint(max);
+            if (a.x > b.x || a.y > b.y) {
+                throw new Error('Spatial box min coordinates must be <= max coordinates.');
+            }
+            return { minX: a.x, minY: a.y, maxX: b.x, maxY: b.y };
+        },
+    };
+}
+
+export function morton2D(x, y, bitsPerCoordinate = 16) {
+    const nx = assertGridCoordinate(x, bitsPerCoordinate, 'x');
+    const ny = assertGridCoordinate(y, bitsPerCoordinate, 'y');
+    let code = 0;
+    for (let bit = 0; bit < bitsPerCoordinate; bit++) {
+        code |= ((nx >>> bit) & 1) << (2 * bit);
+        code |= ((ny >>> bit) & 1) << (2 * bit + 1);
+    }
+    return code >>> 0;
+}
+
+export function unmorton2D(code, bitsPerCoordinate = 16) {
+    const nc = code >>> 0;
+    let x = 0, y = 0;
+    for (let bit = 0; bit < bitsPerCoordinate; bit++) {
+        x |= ((nc >>> (2 * bit)) & 1) << bit;
+        y |= ((nc >>> (2 * bit + 1)) & 1) << bit;
+    }
+    return [x >>> 0, y >>> 0];
+}
+
+export function boxToMortonRanges(minX, maxX, minY, maxY, bitsPerCoordinate) {
+    const ranges = [];
+    const maxCoord = (1 << bitsPerCoordinate) - 1;
+
+    function walk(prefix, prefixBits, xLo, xHi, yLo, yHi) {
+        if (xLo > maxX || xHi < minX || yLo > maxY || yHi < minY) return;
+
+        if (xLo >= minX && xHi <= maxX && yLo >= minY && yHi <= maxY) {
+            const remaining = 2 * bitsPerCoordinate - prefixBits;
+            const lo = prefix << remaining;
+            const hi = lo | ((1 << remaining) - 1);
+            ranges.push([lo >>> 0, hi >>> 0]);
+            return;
+        }
+
+        if (prefixBits >= 2 * bitsPerCoordinate) return;
+
+        const xMid = (xLo + xHi) >> 1;
+        const yMid = (yLo + yHi) >> 1;
+        const np = prefixBits + 2;
+
+        walk((prefix << 2) | 0, np, xLo, xMid, yLo, yMid);
+        walk((prefix << 2) | 1, np, xMid + 1, xHi, yLo, yMid);
+        walk((prefix << 2) | 2, np, xLo, xMid, yMid + 1, yHi);
+        walk((prefix << 2) | 3, np, xMid + 1, xHi, yMid + 1, yHi);
+    }
+
+    walk(0, 0, 0, maxCoord, 0, maxCoord);
+    return ranges;
+}
+
+export class SpatialFilter {
+    constructor(options = {}) {
+        this.bitsPerCoordinate = options.bitsPerCoordinate ?? 16;
+        if (this.bitsPerCoordinate <= 0 || this.bitsPerCoordinate > 16) {
+            throw new Error('bitsPerCoordinate must be in [1, 16] for 32-bit Morton codes.');
+        }
+
+        this.maxShapeCells = options.maxShapeCells ?? 64;
+        this.codec = makeCoordinateCodec({ ...options, bitsPerCoordinate: this.bitsPerCoordinate });
+
+        this.rangeFilter = new RangeFilter(
+            options.rangeOptions ?? options.filterOptions ?? {
+                partitionSize: 16,
+                fingerprintBits: 8,
+                maxFingerprintBits: 16,
+            }
+        );
+    }
+
+    _mortonOfPoint(x, y) {
+        return morton2D(x, y, this.bitsPerCoordinate);
+    }
+
+    _mortonOfBox(box) {
+        return boxToMortonRanges(box.minX, box.maxX, box.minY, box.maxY, this.bitsPerCoordinate);
+    }
+
+    insert(point) {
+        const entry = this.codec.normalizePoint(point);
+        const code = this._mortonOfPoint(entry.x, entry.y);
+        this.rangeFilter.insert(code);
+    }
+
+    insertBox(min, max, _id = null) {
+        const box = this.codec.normalizeBox(min, max);
+        const ranges = this._mortonOfBox(box);
+        if (ranges.length > this.maxShapeCells) {
+            throw new Error(`Box covers ${ranges.length} Morton ranges; maxShapeCells is ${this.maxShapeCells}.`);
+        }
+        for (const [lo, hi] of ranges) {
+            for (let c = lo; c <= hi; c++) {
+                this.rangeFilter.insert(c);
+            }
+        }
+    }
+
+    insertCircle(center, radius, _id = null) {
+        const entry = this.codec.normalizePoint(center);
+        const r = parseFiniteCoordinate(radius, 'radius');
+        if (r < 0) throw new Error('radius must be non-negative.');
+        const gm = (1 << this.bitsPerCoordinate) - 1;
+        const box = {
+            minX: clamp(Math.floor(entry.x - r), 0, gm),
+            minY: clamp(Math.floor(entry.y - r), 0, gm),
+            maxX: clamp(Math.ceil(entry.x + r), 0, gm),
+            maxY: clamp(Math.ceil(entry.y + r), 0, gm),
+        };
+        this.insertBox([box.minX, box.minY], [box.maxX, box.maxY]);
+    }
+
+    query(point) {
+        const entry = this.codec.normalizePoint(point);
+        const code = this._mortonOfPoint(entry.x, entry.y);
+        return this.rangeFilter.queryRange(code, code);
+    }
+
+    delete(point) {
+        const entry = this.codec.normalizePoint(point);
+        const code = this._mortonOfPoint(entry.x, entry.y);
+        return this.rangeFilter.delete(code);
+    }
+
+    queryBox(min, max) {
+        const box = this.codec.normalizeBox(min, max);
+        const ranges = this._mortonOfBox(box);
+        for (const [lo, hi] of ranges) {
+            if (this.rangeFilter.queryRange(lo, hi)) return true;
+        }
+        return false;
+    }
+
+    adaptFalsePositiveBox(min, max) {
+        const box = this.codec.normalizeBox(min, max);
+        const ranges = this._mortonOfBox(box);
+        let adapted = false;
+        for (const [lo, hi] of ranges) {
+            if (this.rangeFilter.adaptFalsePositive(lo, hi)) adapted = true;
+        }
+        return adapted;
+    }
+
+    getStats() {
+        return {
+            ...this.rangeFilter.getStats(),
+            bitsPerCoordinate: this.bitsPerCoordinate,
+            gridSize: 2 ** this.bitsPerCoordinate,
+        };
+    }
+
+    serialize() {
+        const writer = new BinaryWriter();
+        writer.uint32(MAGIC.SPATIAL);
+        writer.uint32(this.bitsPerCoordinate);
+
+        const filterData = this.rangeFilter.serialize();
+        writer.bytes(new Uint8Array(filterData));
+
+        return wrapCRC32(writer.toArrayBuffer());
+    }
+
+    static deserialize(buffer, options = {}) {
+        buffer = unwrapCRC32(buffer);
+        const reader = new BinaryReader(buffer);
+        if (reader.uint32() !== MAGIC.SPATIAL) throw new Error('Not a SpatialFilter binary.');
+
+        const bitsPerCoordinate = reader.uint32();
+
+        const filter = new SpatialFilter({
+            bitsPerCoordinate,
+            ...options,
+        });
+
+        const filterData = reader.bytes();
+        filter.rangeFilter = RangeFilter.deserialize(filterData.buffer);
+
+        return filter;
+    }
+}

package/src/temporalFilter.js

@@ -0,0 +1,259 @@
+import { PointFilter } from './pointFilter.js';
+import { BinaryWriter, BinaryReader, MAGIC, wrapCRC32, unwrapCRC32 } from './serialization.js';
+
+function assertPositiveFinite(value, label) {
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new Error(`${label} must be a positive finite number.`);
+    }
+    return value;
+}
+
+function assertNonNegativeFinite(value, label) {
+    if (!Number.isFinite(value) || value < 0) {
+        throw new Error(`${label} must be a non-negative finite number.`);
+    }
+    return value;
+}
+
+function normalizeTimestamp(value) {
+    if (!Number.isFinite(value)) {
+        throw new Error('timestampMs must be a finite number.');
+    }
+    return Math.floor(value);
+}
+
+export class TemporalFilter {
+    constructor(options = {}) {
+        this.bucketDurationMs = assertPositiveFinite(options.bucketDurationMs ?? 60000, 'bucketDurationMs');
+        this.retentionDurationMs = assertPositiveFinite(options.retentionDurationMs ?? (24 * 60 * 60 * 1000), 'retentionDurationMs');
+        this.maxBuckets = Math.max(1, Math.ceil(this.retentionDurationMs / this.bucketDurationMs));
+        this.filterOptions = options.filterOptions ?? {};
+        this.buckets = new Array(this.maxBuckets).fill(null).map(() => ({ bucketId: Number.NaN, filter: null }));
+        this.adaptedFalsePositiveQueries = new Set();
+    }
+
+    _bucketId(timestampMs) {
+        return Math.floor(timestampMs / this.bucketDurationMs);
+    }
+
+    _bucketIndex(bucketId) {
+        const mod = bucketId % this.maxBuckets;
+        return mod < 0 ? mod + this.maxBuckets : mod;
+    }
+
+    _latestBucketInHorizon(nowBucketId) {
+        return nowBucketId;
+    }
+
+    _oldestBucketInHorizon(nowBucketId) {
+        return nowBucketId - this.maxBuckets + 1;
+    }
+
+    _createBucket(bucketId) {
+        return {
+            bucketId,
+            filter: new PointFilter({ initialCapacity: 32, fingerprintSize: 8, ...this.filterOptions }),
+        };
+    }
+
+    _getOrCreateBucket(bucketId) {
+        const index = this._bucketIndex(bucketId);
+        const slot = this.buckets[index];
+
+        if (slot.filter && slot.bucketId === bucketId) {
+            return slot;
+        }
+
+        const fresh = this._createBucket(bucketId);
+        this.buckets[index] = fresh;
+        return fresh;
+    }
+
+    _queryBucket(key, bucketId) {
+        const slot = this.buckets[this._bucketIndex(bucketId)];
+        if (!slot.filter || slot.bucketId !== bucketId) return false;
+        return slot.filter.query(key);
+    }
+
+    _queryBucketSpan(key, startBucketId, endBucketId) {
+        for (let bucketId = startBucketId; bucketId <= endBucketId; bucketId++) {
+            if (this._queryBucket(key, bucketId)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    _queryRangeSignature(key, startBucketId, endBucketId) {
+        return `${String(key)}:${startBucketId}:${endBucketId}`;
+    }
+
+    _bucketRangeForWithinLast(durationMs, nowMs) {
+        const normalizedNow = normalizeTimestamp(nowMs);
+        const boundedDuration = assertNonNegativeFinite(durationMs, 'durationMs');
+        const nowBucketId = this._bucketId(normalizedNow);
+        const latest = this._latestBucketInHorizon(nowBucketId);
+        const oldest = this._oldestBucketInHorizon(nowBucketId);
+        const requestedStart = nowBucketId - Math.ceil(boundedDuration / this.bucketDurationMs);
+        const start = Math.max(oldest, requestedStart);
+        return { start, end: latest };
+    }
+
+    _bucketRangeForBetweenAges(minAgeMs, maxAgeMs, nowMs) {
+        const normalizedNow = normalizeTimestamp(nowMs);
+        const minAge = assertNonNegativeFinite(minAgeMs, 'minAgeMs');
+        const maxAge = assertNonNegativeFinite(maxAgeMs, 'maxAgeMs');
+        if (minAge > maxAge) {
+            throw new Error('minAgeMs must be <= maxAgeMs.');
+        }
+
+        const nowBucketId = this._bucketId(normalizedNow);
+        const oldest = this._oldestBucketInHorizon(nowBucketId);
+        const youngest = this._latestBucketInHorizon(nowBucketId);
+        const start = Math.max(oldest, nowBucketId - Math.ceil(maxAge / this.bucketDurationMs));
+        const end = Math.min(youngest, nowBucketId - Math.floor(minAge / this.bucketDurationMs));
+        return { start, end };
+    }
+
+    _adaptFalsePositiveOverRange(key, startBucketId, endBucketId) {
+        if (startBucketId > endBucketId) return false;
+
+        const signature = this._queryRangeSignature(key, startBucketId, endBucketId);
+        if (this.adaptedFalsePositiveQueries.has(signature) && !this._queryBucketSpan(key, startBucketId, endBucketId)) {
+            return false;
+        }
+
+        let adapted = false;
+        for (let bucketId = startBucketId; bucketId <= endBucketId; bucketId++) {
+            const slot = this.buckets[this._bucketIndex(bucketId)];
+            if (!slot.filter || slot.bucketId !== bucketId) continue;
+            adapted = slot.filter.rejuvenate(key) || adapted;
+        }
+
+        if (adapted && !this._queryBucketSpan(key, startBucketId, endBucketId)) {
+            this.adaptedFalsePositiveQueries.add(signature);
+        }
+
+        return adapted;
+    }
+
+    insertAt(key, timestampMs = Date.now()) {
+        const normalizedTimestamp = normalizeTimestamp(timestampMs);
+        const bucketId = this._bucketId(normalizedTimestamp);
+        this._getOrCreateBucket(bucketId).filter.insert(key);
+    }
+
+    queryWithinLast(key, durationMs, nowMs = Date.now()) {
+        const range = this._bucketRangeForWithinLast(durationMs, nowMs);
+        return this._queryBucketSpan(key, range.start, range.end);
+    }
+
+    queryAgo(key, ageMs, toleranceMs = this.bucketDurationMs, nowMs = Date.now()) {
+        const normalizedNow = normalizeTimestamp(nowMs);
+        const normalizedAge = assertNonNegativeFinite(ageMs, 'ageMs');
+        const normalizedTolerance = assertNonNegativeFinite(toleranceMs, 'toleranceMs');
+        const nowBucketId = this._bucketId(normalizedNow);
+        const centerBucket = nowBucketId - Math.ceil(normalizedAge / this.bucketDurationMs);
+        const toleranceBuckets = Math.floor(normalizedTolerance / this.bucketDurationMs);
+        const start = centerBucket - toleranceBuckets;
+        const end = centerBucket + toleranceBuckets;
+
+        return this.queryBetweenAges(
+            key,
+            Math.max(0, (nowBucketId - end) * this.bucketDurationMs),
+            Math.max(0, (nowBucketId - start) * this.bucketDurationMs),
+            nowMs
+        );
+    }
+
+    queryBetweenAges(key, minAgeMs, maxAgeMs, nowMs = Date.now()) {
+        const range = this._bucketRangeForBetweenAges(minAgeMs, maxAgeMs, nowMs);
+        if (range.start > range.end) return false;
+        return this._queryBucketSpan(key, range.start, range.end);
+    }
+
+    adaptFalsePositiveWithinLast(key, durationMs, nowMs = Date.now()) {
+        const range = this._bucketRangeForWithinLast(durationMs, nowMs);
+        return this._adaptFalsePositiveOverRange(key, range.start, range.end);
+    }
+
+    adaptFalsePositiveBetweenAges(key, minAgeMs, maxAgeMs, nowMs = Date.now()) {
+        const range = this._bucketRangeForBetweenAges(minAgeMs, maxAgeMs, nowMs);
+        if (range.start > range.end) return false;
+        return this._adaptFalsePositiveOverRange(key, range.start, range.end);
+    }
+
+    adaptFalsePositiveAgo(key, ageMs, toleranceMs = this.bucketDurationMs, nowMs = Date.now()) {
+        const normalizedNow = normalizeTimestamp(nowMs);
+        const normalizedAge = assertNonNegativeFinite(ageMs, 'ageMs');
+        const normalizedTolerance = assertNonNegativeFinite(toleranceMs, 'toleranceMs');
+        const nowBucketId = this._bucketId(normalizedNow);
+        const centerBucket = nowBucketId - Math.ceil(normalizedAge / this.bucketDurationMs);
+        const toleranceBuckets = Math.floor(normalizedTolerance / this.bucketDurationMs);
+        const minAge = Math.max(0, (nowBucketId - (centerBucket + toleranceBuckets)) * this.bucketDurationMs);
+        const maxAge = Math.max(0, (nowBucketId - (centerBucket - toleranceBuckets)) * this.bucketDurationMs);
+        return this.adaptFalsePositiveBetweenAges(key, minAge, maxAge, nowMs);
+    }
+
+    getStats(nowMs = Date.now()) {
+        const nowBucketId = this._bucketId(normalizeTimestamp(nowMs));
+        const oldest = this._oldestBucketInHorizon(nowBucketId);
+        let activeBuckets = 0;
+
+        for (const bucket of this.buckets) {
+            if (!bucket.filter) continue;
+            if (bucket.bucketId < oldest || bucket.bucketId > nowBucketId) continue;
+            activeBuckets++;
+        }
+
+        return {
+            bucketDurationMs: this.bucketDurationMs,
+            retentionDurationMs: this.retentionDurationMs,
+            maxBuckets: this.maxBuckets,
+            activeBuckets,
+        };
+    }
+
+    serialize() {
+        const writer = new BinaryWriter();
+        writer.uint32(MAGIC.TEMPORAL);
+        writer.float64(this.bucketDurationMs);
+        writer.float64(this.retentionDurationMs);
+        writer.uint32(this.maxBuckets);
+
+        const populated = this.buckets.filter(b => b.filter);
+        writer.uint32(populated.length);
+        for (const bucket of populated) {
+            writer.uint32(bucket.bucketId >>> 0);
+            const filterData = bucket.filter.serialize();
+            writer.bytes(new Uint8Array(filterData));
+        }
+        return wrapCRC32(writer.toArrayBuffer());
+    }
+
+    static deserialize(buffer, options = {}) {
+        buffer = unwrapCRC32(buffer);
+        const reader = new BinaryReader(buffer);
+        if (reader.uint32() !== MAGIC.TEMPORAL) throw new Error('Not a TemporalFilter binary.');
+
+        const filter = new TemporalFilter({
+            bucketDurationMs: reader.float64(),
+            retentionDurationMs: reader.float64(),
+            ...options,
+        });
+        filter.maxBuckets = reader.uint32();
+        if (filter.buckets.length !== filter.maxBuckets) {
+            filter.buckets = new Array(filter.maxBuckets).fill(null)
+                .map(() => ({ bucketId: Number.NaN, filter: null }));
+        }
+
+        const count = reader.uint32();
+        for (let i = 0; i < count; i++) {
+            const bucketId = reader.uint32();
+            const filterData = reader.bytes();
+            const f = PointFilter.deserialize(filterData.buffer);
+            filter.buckets[filter._bucketIndex(bucketId)] = { bucketId, filter: f };
+        }
+        return filter;
+    }
+}

package/src/zeno.js

@@ -0,0 +1,85 @@
+export function zenoGrowthFactor(growthCoefficient = 2) {
+    if (!Number.isInteger(growthCoefficient) || growthCoefficient <= 0) {
+        throw new Error('growthCoefficient must be a positive integer.');
+    }
+    return 2 ** (1 / growthCoefficient);
+}
+
+export function zenoStretchIndex(index, epoch, growthCoefficient = 2) {
+    if (!Number.isInteger(index) || index < 0) {
+        throw new Error('index must be a non-negative integer.');
+    }
+    if (!Number.isInteger(epoch) || epoch < 0 || epoch > growthCoefficient) {
+        throw new Error('epoch must be an integer in [0, growthCoefficient].');
+    }
+
+    return Math.floor(index * (2 ** (epoch / growthCoefficient)));
+}
+
+export function zenoShouldSacrifice(epoch, growthCoefficient = 2) {
+    return epoch > 0 && epoch % growthCoefficient === 0;
+}
+
+export function zenoDirectoryAddress(slot) {
+    if (!Number.isInteger(slot) || slot < 0) {
+        throw new Error('slot must be a non-negative integer.');
+    }
+
+    const j = slot + 1;
+    const level = Math.floor(Math.log2(j));
+    const floorHalf = level >>> 1;
+    const ceilHalf = (level + 1) >>> 1;
+    const blocksBeforeLevel = (2 ** floorHalf) * (2 + (level & 1)) - 2;
+    const blockInLevel = (j >>> ceilHalf) & ((2 ** floorHalf) - 1);
+    const offsetInBlock = j & ((2 ** ceilHalf) - 1);
+
+    return {
+        level,
+        blockIndex: blocksBeforeLevel + blockInLevel,
+        offset: offsetInBlock,
+        blocksBeforeLevel,
+        blockInLevel,
+    };
+}
+
+export class ZenoExpansionPolicy {
+    constructor(options = {}) {
+        this.growthCoefficient = options.growthCoefficient ?? 2;
+        this.expansionThreshold = options.expansionThreshold ?? 0.8;
+        this.epoch = 0;
+        this.period = 0;
+    }
+
+    nextCapacity(currentCapacity) {
+        if (!Number.isInteger(currentCapacity) || currentCapacity <= 0) {
+            throw new Error('currentCapacity must be a positive integer.');
+        }
+
+        const nextEpoch = this.epoch + 1;
+        if (zenoShouldSacrifice(nextEpoch, this.growthCoefficient)) {
+            return currentCapacity * 2;
+        }
+
+        return Math.ceil(currentCapacity * zenoGrowthFactor(this.growthCoefficient));
+    }
+
+    mapIndex(index) {
+        const nextEpoch = this.epoch + 1;
+        if (zenoShouldSacrifice(nextEpoch, this.growthCoefficient)) {
+            return { index: index * 2, sacrifice: true };
+        }
+
+        return {
+            index: zenoStretchIndex(index, nextEpoch % this.growthCoefficient, this.growthCoefficient),
+            sacrifice: false,
+        };
+    }
+
+    advance() {
+        this.epoch++;
+        if (this.epoch % this.growthCoefficient === 0) {
+            this.period++;
+            this.epoch = 0;
+        }
+    }
+}