attention-manifest-protocol 0.4.0 → 0.4.2

package/lib/structure/cuckooFilter.js

@@ -0,0 +1,267 @@
+import { hashBytes } from "./hash.js";
+import { assertFilterKey, filterKeyBytes } from "./filterKey.js";
+const DEFAULT_BUCKET_SIZE = 4;
+const DEFAULT_FINGERPRINT_BITS = 8;
+const DEFAULT_MAX_KICKS = 500;
+const FINGERPRINT_SEED = 0xd1b54a32d192ed03n;
+const MIN_FINGERPRINT_BITS = 4;
+const MAX_FINGERPRINT_BITS = 30;
+/**
+ * A cuckoo filter over string or `Uint8Array` keys.
+ *
+ * `capacity` is the number of fingerprint slots, not the requested value: it is
+ * `bucketCount * bucketSize`, rounded up from the constructor's `capacity`.
+ * `loadFactor` is the fraction of those slots currently occupied.
+ */
+export class CuckooFilter {
+    /**
+     * Requested key capacity before bucket rounding.
+     */
+    requestedCapacity;
+    /**
+     * Fingerprints per bucket.
+     */
+    bucketSize;
+    /**
+     * Number of buckets (a power of two).
+     */
+    bucketCount;
+    /**
+     * Total fingerprint slots: `bucketCount * bucketSize`.
+     */
+    capacity;
+    /**
+     * Fingerprint width in bits.
+     */
+    fingerprintBits;
+    /**
+     * Maximum number of displacements per insertion.
+     */
+    maxKicks;
+    buckets;
+    seed;
+    indexMask;
+    fingerprintMask;
+    initialRng;
+    rngState;
+    count = 0;
+    /**
+     * Create an empty filter.
+     *
+     * @throws RangeError for non-positive capacity, an invalid bucket/fingerprint
+     * size, a negative kick limit, or a bucket array too large to index safely.
+     */
+    constructor(options) {
+        if (options === null || typeof (options) !== "object") {
+            throw new TypeError("options must be an object");
+        }
+        if (!Number.isSafeInteger(options.capacity) || options.capacity <= 0) {
+            throw new RangeError("capacity must be a positive safe integer");
+        }
+        const bucketSize = options.bucketSize ?? DEFAULT_BUCKET_SIZE;
+        if (!Number.isSafeInteger(bucketSize) || bucketSize <= 0 || bucketSize > 32) {
+            throw new RangeError("bucketSize must be an integer in [1, 32]");
+        }
+        const fingerprintBits = options.fingerprintBits ?? DEFAULT_FINGERPRINT_BITS;
+        if (!Number.isSafeInteger(fingerprintBits) || fingerprintBits < MIN_FINGERPRINT_BITS || fingerprintBits > MAX_FINGERPRINT_BITS) {
+            throw new RangeError(`fingerprintBits must be an integer in [${MIN_FINGERPRINT_BITS}, ${MAX_FINGERPRINT_BITS}]`);
+        }
+        const maxKicks = options.maxKicks ?? DEFAULT_MAX_KICKS;
+        if (!Number.isSafeInteger(maxKicks) || maxKicks < 0) {
+            throw new RangeError("maxKicks must be a non-negative safe integer");
+        }
+        let bucketCount = 1;
+        while (bucketCount * bucketSize < options.capacity) {
+            bucketCount *= 2;
+            if (bucketCount > 2 ** 30) {
+                throw new RangeError("capacity is too large for a cuckoo filter");
+            }
+        }
+        this.requestedCapacity = options.capacity;
+        this.bucketSize = bucketSize;
+        this.bucketCount = bucketCount;
+        this.capacity = bucketCount * bucketSize;
+        this.fingerprintBits = fingerprintBits;
+        this.maxKicks = maxKicks;
+        this.seed = options.seed ?? 0n;
+        this.indexMask = bucketCount - 1;
+        this.fingerprintMask = (1n << BigInt(fingerprintBits)) - 1n;
+        this.buckets = Array.from({ length: bucketCount }, () => []);
+        const seeded = Number((options.seed ?? 0n) & 0xffffffffn);
+        this.initialRng = seeded === 0 ? 0x9e37_79b9 : seeded;
+        this.rngState = this.initialRng;
+    }
+    /**
+     * Insert a key.
+     *
+     * @returns `true` if the fingerprint was stored, `false` if the kick chain
+     * was exhausted. A failed insertion is rolled back and leaves the filter
+     * unchanged.
+     */
+    add(key) {
+        assertFilterKey(key);
+        const { index, fingerprint } = this.locate(key);
+        const first = index;
+        const second = this.alternate(first, fingerprint);
+        let currentFingerprint = fingerprint;
+        let currentIndex = this.pickBucket(first, second);
+        const history = [];
+        for (let kick = 0; kick <= this.maxKicks; kick += 1) {
+            const bucket = this.buckets[currentIndex];
+            if (bucket.length < this.bucketSize) {
+                bucket.push(currentFingerprint);
+                this.count += 1;
+                return true;
+            }
+            if (kick === this.maxKicks) {
+                break;
+            }
+            const slot = this.randomInt(bucket.length);
+            const displaced = bucket[slot] ?? 0;
+            history.push({ bucket: currentIndex, slot, displaced });
+            bucket[slot] = currentFingerprint;
+            currentFingerprint = displaced;
+            currentIndex = this.alternate(currentIndex, currentFingerprint);
+        }
+        /**
+         * Undo every displacement. The last displaced fingerprint was never
+         * stored, and every earlier one is restored to the slot it came from.
+         */
+        for (let index_ = history.length - 1; index_ >= 0; index_ -= 1) {
+            const record = history[index_];
+            if (record === (void 0)) {
+                continue;
+            }
+            this.buckets[record.bucket][record.slot] = record.displaced;
+        }
+        return false;
+    }
+    /**
+     * Test whether a key may be present.
+     */
+    has(key) {
+        assertFilterKey(key);
+        const { index, fingerprint } = this.locate(key);
+        if (this.buckets[index].includes(fingerprint)) {
+            return true;
+        }
+        const alternate = this.alternate(index, fingerprint);
+        return alternate !== index && this.buckets[alternate].includes(fingerprint);
+    }
+    /**
+     * Remove one occurrence of a key.
+     *
+     * @returns `true` if a matching fingerprint was removed, `false` otherwise.
+     * A `false` result is exact only for a key that was never inserted; a
+     * different key can share the same fingerprint, so deletion is best-effort
+     * with respect to collisions.
+     */
+    delete(key) {
+        assertFilterKey(key);
+        const { index, fingerprint } = this.locate(key);
+        const first = this.removeFingerprint(index, fingerprint);
+        if (first) {
+            this.count -= 1;
+            return true;
+        }
+        const alternate = this.alternate(index, fingerprint);
+        if (alternate !== index && this.removeFingerprint(alternate, fingerprint)) {
+            this.count -= 1;
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Remove every key and reset the random kick state.
+     */
+    clear() {
+        for (const bucket of this.buckets) {
+            bucket.length = 0;
+        }
+        this.count = 0;
+        this.rngState = this.initialRng;
+    }
+    /**
+     * Number of stored fingerprints.
+     */
+    get size() {
+        return this.count;
+    }
+    /**
+     * Fraction of fingerprint slots occupied.
+     */
+    get loadFactor() {
+        return this.count / this.capacity;
+    }
+    /**
+     * True when every fingerprint slot is occupied.
+     */
+    get isFull() {
+        return this.count === this.capacity;
+    }
+    /**
+     * Approximate false-positive probability for a non-full filter:
+     * `2 * bucketSize / 2^fingerprintBits`.
+     */
+    get falsePositiveRate() {
+        return Math.min(1, (2 * this.bucketSize) / 2 ** this.fingerprintBits);
+    }
+    /**
+     * Hash a key once, yielding its first bucket and compact fingerprint.
+     */
+    locate(key) {
+        const hash = hashBytes(filterKeyBytes(key), this.seed);
+        const index = Number(hash & BigInt(this.indexMask));
+        let fingerprint = Number((hash >> 32n) & this.fingerprintMask);
+        if (fingerprint === 0) {
+            fingerprint = 1;
+        }
+        return { index, fingerprint };
+    }
+    /**
+     * The other candidate bucket for a fingerprint in `index`.
+     */
+    alternate(index, fingerprint) {
+        const bytes = Uint8Array.of(fingerprint & 0xff, (fingerprint >>> 8) & 0xff, (fingerprint >>> 16) & 0xff, (fingerprint >>> 24) & 0xff);
+        const hashed = Number(hashBytes(bytes, this.seed ^ FINGERPRINT_SEED) & BigInt(this.indexMask));
+        return (index ^ hashed) & this.indexMask;
+    }
+    /**
+     * Choose an initial bucket, preferring one with room.
+     */
+    pickBucket(first, second) {
+        if (this.buckets[first].length < this.bucketSize) {
+            return first;
+        }
+        if (this.buckets[second].length < this.bucketSize) {
+            return second;
+        }
+        return this.randomInt(2) === 0 ? first : second;
+    }
+    /**
+     * Remove the first matching fingerprint from one bucket.
+     */
+    removeFingerprint(index, fingerprint) {
+        const bucket = this.buckets[index];
+        const slot = bucket.indexOf(fingerprint);
+        if (slot < 0) {
+            return false;
+        }
+        const last = bucket.pop();
+        if (slot < bucket.length && last !== (void 0)) {
+            bucket[slot] = last;
+        }
+        return true;
+    }
+    /**
+     * Xorshift32 in [0, bound); deterministic for a given seed and insertion order.
+     */
+    randomInt(bound) {
+        let value = this.rngState;
+        value ^= value << 13;
+        value ^= value >>> 17;
+        value ^= value << 5;
+        this.rngState = value >>> 0;
+        return this.rngState % bound;
+    }
+}

package/lib/structure/deque.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Array-backed double-ended queue.
+ *
+ * Values live in a circular buffer addressed by a head index and a count, so
+ * both the front and back of the logical sequence can be updated in O(1)
+ * amortized time without moving the other values. The buffer is not required
+ * to have a power-of-two length; it doubles when full and halves after a pop
+ * leaves it at most quarter full. Popped slots are cleared so the ring does not
+ * retain references to removed values.
+ */
+/**
+ * A double-ended queue.
+ *
+ * Values can be added and removed at either end. `popFront`, `popBack`,
+ * `peekFront`, and `peekBack` return `undefined` when the deque is empty rather
+ * than throwing. Since `undefined` is also a valid stored value, use
+ * {@link size} or {@link isEmpty} when presence must be distinguished from
+ * absence.
+ *
+ * Iteration is front-to-back.
+ *
+ * @example
+ * ```ts
+ * const deque = new Deque([2, 3]);
+ * deque.pushFront(1).pushBack(4);
+ * [...deque]; // [1, 2, 3, 4]
+ * ```
+ */
+export declare class Deque<T> implements Iterable<T> {
+    private items;
+    private head;
+    private count;
+    /**
+     * Create a deque, optionally seeded from `values`.
+     *
+     * Values are pushed onto the back in iteration order, so the last value
+     * becomes the back.
+     *
+     * @param values - Values to insert, in order.
+     */
+    constructor(values?: Iterable<T>);
+    /**
+     * Number of values currently in the deque.
+     */
+    get size(): number;
+    /**
+     * Whether the deque contains no values.
+     */
+    get isEmpty(): boolean;
+    /**
+     * Add a value at the front of the deque.
+     *
+     * @param value - Value to insert.
+     * @returns This deque, for chaining.
+     */
+    pushFront(value: T): this;
+    /**
+     * Add a value at the back of the deque.
+     *
+     * @param value - Value to insert.
+     * @returns This deque, for chaining.
+     */
+    pushBack(value: T): this;
+    /**
+     * Alias of {@link pushBack}.
+     *
+     * @param value - Value to insert at the back.
+     * @returns This deque, for chaining.
+     */
+    push(value: T): this;
+    /**
+     * Remove and return the value at the front of the deque.
+     *
+     * @returns The former front value, or `undefined` if the deque is empty.
+     */
+    popFront(): T | undefined;
+    /**
+     * Remove and return the value at the back of the deque.
+     *
+     * @returns The former back value, or `undefined` if the deque is empty.
+     */
+    popBack(): T | undefined;
+    /**
+     * Return the value at the front without removing it.
+     *
+     * @returns The front value, or `undefined` if the deque is empty.
+     */
+    peekFront(): T | undefined;
+    /**
+     * Return the value at the back without removing it.
+     *
+     * @returns The back value, or `undefined` if the deque is empty.
+     */
+    peekBack(): T | undefined;
+    /**
+     * Remove every value and reset the ring to its initial capacity.
+     */
+    clear(): void;
+    /**
+     * Snapshot the deque from front to back.
+     *
+     * @returns A new array whose first item is the front of the deque.
+     */
+    toArray(): T[];
+    /**
+     * Iterate front to back over a snapshot taken when the iterator is created.
+     */
+    [Symbol.iterator](): Generator<T, void, unknown>;
+    /**
+     * Copy the live values into a fresh ring, front to back.
+     */
+    private resize;
+    /**
+     * Halve an oversized ring after a pop leaves it at most quarter full.
+     */
+    private shrinkIfSparse;
+}

package/lib/structure/deque.js

@@ -0,0 +1,205 @@
+/**
+ * Array-backed double-ended queue.
+ *
+ * Values live in a circular buffer addressed by a head index and a count, so
+ * both the front and back of the logical sequence can be updated in O(1)
+ * amortized time without moving the other values. The buffer is not required
+ * to have a power-of-two length; it doubles when full and halves after a pop
+ * leaves it at most quarter full. Popped slots are cleared so the ring does not
+ * retain references to removed values.
+ */
+import { generatorFrom } from "./iterator.js";
+const INITIAL_CAPACITY = 8;
+/**
+ * A double-ended queue.
+ *
+ * Values can be added and removed at either end. `popFront`, `popBack`,
+ * `peekFront`, and `peekBack` return `undefined` when the deque is empty rather
+ * than throwing. Since `undefined` is also a valid stored value, use
+ * {@link size} or {@link isEmpty} when presence must be distinguished from
+ * absence.
+ *
+ * Iteration is front-to-back.
+ *
+ * @example
+ * ```ts
+ * const deque = new Deque([2, 3]);
+ * deque.pushFront(1).pushBack(4);
+ * [...deque]; // [1, 2, 3, 4]
+ * ```
+ */
+export class Deque {
+    items = new Array(INITIAL_CAPACITY);
+    head = 0;
+    count = 0;
+    /**
+     * Create a deque, optionally seeded from `values`.
+     *
+     * Values are pushed onto the back in iteration order, so the last value
+     * becomes the back.
+     *
+     * @param values - Values to insert, in order.
+     */
+    constructor(values) {
+        if (values === (void 0)) {
+            return;
+        }
+        for (const value of values) {
+            this.pushBack(value);
+        }
+    }
+    /**
+     * Number of values currently in the deque.
+     */
+    get size() {
+        return this.count;
+    }
+    /**
+     * Whether the deque contains no values.
+     */
+    get isEmpty() {
+        return this.count === 0;
+    }
+    /**
+     * Add a value at the front of the deque.
+     *
+     * @param value - Value to insert.
+     * @returns This deque, for chaining.
+     */
+    pushFront(value) {
+        if (this.count === this.items.length) {
+            this.resize(this.items.length * 2);
+        }
+        this.head = (this.head - 1 + this.items.length) % this.items.length;
+        this.items[this.head] = value;
+        this.count += 1;
+        return this;
+    }
+    /**
+     * Add a value at the back of the deque.
+     *
+     * @param value - Value to insert.
+     * @returns This deque, for chaining.
+     */
+    pushBack(value) {
+        if (this.count === this.items.length) {
+            this.resize(this.items.length * 2);
+        }
+        const tail = (this.head + this.count) % this.items.length;
+        this.items[tail] = value;
+        this.count += 1;
+        return this;
+    }
+    /**
+     * Alias of {@link pushBack}.
+     *
+     * @param value - Value to insert at the back.
+     * @returns This deque, for chaining.
+     */
+    push(value) {
+        return this.pushBack(value);
+    }
+    /**
+     * Remove and return the value at the front of the deque.
+     *
+     * @returns The former front value, or `undefined` if the deque is empty.
+     */
+    popFront() {
+        if (this.count === 0) {
+            return undefined;
+        }
+        const value = this.items[this.head];
+        this.items[this.head] = undefined;
+        this.head = (this.head + 1) % this.items.length;
+        this.count -= 1;
+        this.shrinkIfSparse();
+        return value;
+    }
+    /**
+     * Remove and return the value at the back of the deque.
+     *
+     * @returns The former back value, or `undefined` if the deque is empty.
+     */
+    popBack() {
+        if (this.count === 0) {
+            return undefined;
+        }
+        const tail = (this.head + this.count - 1) % this.items.length;
+        const value = this.items[tail];
+        this.items[tail] = undefined;
+        this.count -= 1;
+        this.shrinkIfSparse();
+        return value;
+    }
+    /**
+     * Return the value at the front without removing it.
+     *
+     * @returns The front value, or `undefined` if the deque is empty.
+     */
+    peekFront() {
+        if (this.count === 0) {
+            return undefined;
+        }
+        return this.items[this.head];
+    }
+    /**
+     * Return the value at the back without removing it.
+     *
+     * @returns The back value, or `undefined` if the deque is empty.
+     */
+    peekBack() {
+        if (this.count === 0) {
+            return undefined;
+        }
+        return this.items[(this.head + this.count - 1) % this.items.length];
+    }
+    /**
+     * Remove every value and reset the ring to its initial capacity.
+     */
+    clear() {
+        this.items = new Array(INITIAL_CAPACITY);
+        this.head = 0;
+        this.count = 0;
+    }
+    /**
+     * Snapshot the deque from front to back.
+     *
+     * @returns A new array whose first item is the front of the deque.
+     */
+    toArray() {
+        const values = new Array(this.count);
+        for (let index = 0; index < this.count; index += 1) {
+            values[index] = this.items[(this.head + index) % this.items.length];
+        }
+        return values;
+    }
+    /**
+     * Iterate front to back over a snapshot taken when the iterator is created.
+     */
+    [Symbol.iterator]() {
+        return generatorFrom(this.toArray());
+    }
+    /**
+     * Copy the live values into a fresh ring, front to back.
+     */
+    resize(capacity) {
+        const next = new Array(capacity);
+        for (let index = 0; index < this.count; index += 1) {
+            next[index] = this.items[(this.head + index) % this.items.length];
+        }
+        this.items = next;
+        this.head = 0;
+    }
+    /**
+     * Halve an oversized ring after a pop leaves it at most quarter full.
+     */
+    shrinkIfSparse() {
+        if (this.items.length <= INITIAL_CAPACITY) {
+            return;
+        }
+        if (this.count > this.items.length / 4) {
+            return;
+        }
+        this.resize(this.items.length / 2);
+    }
+}

package/lib/structure/filterKey.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Key encoding shared by the probabilistic filters.
+ *
+ * Filters operate on bytes. Strings are encoded as UTF-8, and an existing
+ * `Uint8Array` is used as-is (not copied), so callers must not mutate a key
+ * buffer while it is being inserted or queried.
+ */
+/**
+ * A key accepted by {@link BloomFilter} and {@link CuckooFilter}.
+ */
+export type FilterKey = string | Uint8Array;
+/**
+ * UTF-8 bytes for a string, or the original byte view for a `Uint8Array`.
+ */
+export declare const filterKeyBytes: (key: FilterKey) => Uint8Array;
+/**
+ * Reject non-string/non-byte values early with a useful error.
+ */
+export declare const assertFilterKey: (key: unknown) => asserts key is FilterKey;

package/lib/structure/filterKey.js

@@ -0,0 +1,28 @@
+/**
+ * Key encoding shared by the probabilistic filters.
+ *
+ * Filters operate on bytes. Strings are encoded as UTF-8, and an existing
+ * `Uint8Array` is used as-is (not copied), so callers must not mutate a key
+ * buffer while it is being inserted or queried.
+ */
+const Encoder = new TextEncoder();
+/**
+ * UTF-8 bytes for a string, or the original byte view for a `Uint8Array`.
+ */
+export const filterKeyBytes = (key) => {
+    if (typeof (key) === "string") {
+        return Encoder.encode(key);
+    }
+    if (key instanceof Uint8Array) {
+        return key;
+    }
+    throw new TypeError("filter keys must be strings or Uint8Array values");
+};
+/**
+ * Reject non-string/non-byte values early with a useful error.
+ */
+export const assertFilterKey = (key) => {
+    if (typeof (key) !== "string" && !(key instanceof Uint8Array)) {
+        throw new TypeError("filter keys must be strings or Uint8Array values");
+    }
+};