attention-manifest-protocol 0.4.0 → 0.4.2

package/lib/structure/bloomFilter.js

@@ -0,0 +1,177 @@
+import { hashBytes } from "./hash.js";
+import { assertFilterKey, filterKeyBytes } from "./filterKey.js";
+const DefaultFalsePositiveRate = 0.01;
+const DefaultMaxBits = 2 ** 31;
+const SecondHashSeed = 0x9e3779b97f4a7c15n;
+const LN2 = Math.LN2;
+/**
+ * A Bloom filter over string or `Uint8Array` keys.
+ *
+ * `size` counts calls to {@link add}, not distinct keys: a Bloom filter cannot
+ * know whether a key was already present. `setBits` and `fillRatio` expose the
+ * actual bit occupancy, which is the useful signal for saturation.
+ */
+export class BloomFilter {
+    /**
+     * Requested expected key count.
+     */
+    expectedItems;
+    /**
+     * Requested target false-positive rate.
+     */
+    falsePositiveRate;
+    /**
+     * Number of bits in the filter.
+     */
+    bitSize;
+    /**
+     * Number of double-hashed probes per key.
+     */
+    hashCount;
+    /**
+     * Number of bytes allocated for the bit array.
+     */
+    byteSize;
+    bits;
+    seed;
+    insertions = 0;
+    bitsSet = 0;
+    /**
+     * Build a filter sized for `expectedItems` at `falsePositiveRate`.
+     *
+     * @throws RangeError for non-positive/non-integer item counts, rates outside
+     * `(0, 1)`, or a computed bit count above `maxBits`.
+     */
+    constructor(options) {
+        if (options === null || typeof (options) !== "object") {
+            throw new TypeError("options must be an object");
+        }
+        if (!Number.isSafeInteger(options.expectedItems) || options.expectedItems <= 0) {
+            throw new RangeError("expectedItems must be a positive safe integer");
+        }
+        const rate = options.falsePositiveRate ?? DefaultFalsePositiveRate;
+        if (!Number.isFinite(rate) || rate <= 0 || rate >= 1) {
+            throw new RangeError("falsePositiveRate must be a finite number in (0, 1)");
+        }
+        const maxBits = options.maxBits ?? DefaultMaxBits;
+        if (!Number.isSafeInteger(maxBits) || maxBits <= 0) {
+            throw new RangeError("maxBits must be a positive safe integer");
+        }
+        const idealBits = Math.ceil((-options.expectedItems * Math.log(rate)) / (LN2 * LN2));
+        if (!Number.isSafeInteger(idealBits) || idealBits > maxBits) {
+            throw new RangeError(`filter would need ${`${idealBits}`} bits, exceeding maxBits ${maxBits}`);
+        }
+        this.expectedItems = options.expectedItems;
+        this.falsePositiveRate = rate;
+        this.bitSize = Math.max(1, idealBits);
+        this.hashCount = Math.max(1, Math.min(32, Math.round((this.bitSize / options.expectedItems) * LN2)));
+        this.byteSize = Math.ceil(this.bitSize / 8);
+        this.bits = new Uint8Array(this.byteSize);
+        this.seed = options.seed ?? 0n;
+    }
+    /**
+     * Insert a key.
+     *
+     * Duplicate insertion is harmless and increments {@link size}; the bit
+     * occupancy only changes for bits that were previously unset.
+     *
+     * @param key - String or byte key.
+     * @returns This filter, for chaining.
+     */
+    add(key) {
+        assertFilterKey(key);
+        const bytes = filterKeyBytes(key);
+        const primary = hashBytes(bytes, this.seed) % BigInt(this.bitSize);
+        const step = (hashBytes(bytes, this.seed ^ SecondHashSeed) | 1n) % BigInt(this.bitSize);
+        let position = primary;
+        for (let probe = 0; probe < this.hashCount; probe += 1) {
+            this.setBit(Number(position));
+            position = (position + step) % BigInt(this.bitSize);
+        }
+        this.insertions += 1;
+        return this;
+    }
+    /**
+     * Test a key.
+     *
+     * `false` means the key was definitely not inserted (or the filter was
+     * cleared). `true` may be a false positive.
+     */
+    has(key) {
+        assertFilterKey(key);
+        const bytes = filterKeyBytes(key);
+        const primary = hashBytes(bytes, this.seed) % BigInt(this.bitSize);
+        const step = (hashBytes(bytes, this.seed ^ SecondHashSeed) | 1n) % BigInt(this.bitSize);
+        let position = primary;
+        for (let probe = 0; probe < this.hashCount; probe += 1) {
+            if (!this.getBit(Number(position))) {
+                return false;
+            }
+            position = (position + step) % BigInt(this.bitSize);
+        }
+        return true;
+    }
+    /**
+     * Remove every key and reset all counters.
+     */
+    clear() {
+        this.bits.fill(0);
+        this.insertions = 0;
+        this.bitsSet = 0;
+    }
+    /**
+     * Number of `add` calls, including duplicates.
+     */
+    get size() {
+        return this.insertions;
+    }
+    /**
+     * Number of bits currently set to one.
+     */
+    get setBits() {
+        return this.bitsSet;
+    }
+    /**
+     * Fraction of bits set to one.
+     */
+    get fillRatio() {
+        return this.bitsSet / this.bitSize;
+    }
+    /**
+     * True when every bit is set and the filter is fully saturated.
+     */
+    get isSaturated() {
+        return this.bitsSet === this.bitSize;
+    }
+    /**
+     * Estimated current false-positive probability from the number of inserted
+     * keys: `(1 - e^(-k*n/m))^k`.
+     */
+    get estimatedFalsePositiveRate() {
+        if (this.insertions === 0) {
+            return 0;
+        }
+        const exponent = (-this.hashCount * this.insertions) / this.bitSize;
+        return (1 - Math.exp(exponent)) ** this.hashCount;
+    }
+    /**
+     * Set one bit, updating the occupancy counter only on a 0 -> 1 change.
+     */
+    setBit(index) {
+        const byteIndex = index >>> 3;
+        const mask = 1 << (index & 7);
+        const current = this.bits[byteIndex] ?? 0;
+        if ((current & mask) === 0) {
+            this.bits[byteIndex] = current | mask;
+            this.bitsSet += 1;
+        }
+    }
+    /**
+     * Read one bit.
+     */
+    getBit(index) {
+        const byteIndex = index >>> 3;
+        const mask = 1 << (index & 7);
+        return ((this.bits[byteIndex] ?? 0) & mask) !== 0;
+    }
+}

package/lib/structure/compare.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Ordering primitives shared by the ordered structures.
+ *
+ * A comparator returns a negative number when `a` sorts before `b`, zero when
+ * they are equivalent for the structure, and a positive number otherwise.
+ * The structures only require a total preorder; duplicate equivalence is
+ * resolved by the container (e.g. a search tree keeps one representative).
+ */
+/**
+ * Three-way comparison used by search trees, heaps and sorted helpers.
+ */
+export type Comparator<T> = (a: T, b: T) => number;
+/**
+ * Numeric comparison. NaN is rejected rather than silently sorted.
+ */
+export declare function compareNumbers(a: number, b: number): number;
+/**
+ * Lexicographic UTF-16 comparison, matching JavaScript's `<`.
+ */
+export declare function compareStrings(a: string, b: string): number;
+/**
+ * BigInt comparison, safe for values outside the number range.
+ */
+export declare function compareBigInts(a: bigint, b: bigint): number;
+/**
+ * Chronological comparison of two Dates (invalid dates are rejected).
+ */
+export declare function compareDates(a: Date, b: Date): number;
+/**
+ * Natural ordering for the primitive types this library supports.
+ *
+ * It deliberately throws for unsupported values instead of coercing them to
+ * strings: a search tree built on `"[object Object]"` order is a silent bug.
+ * Equal primitive values compare as `0`; `-0` and `0` are equivalent, and
+ * `NaN` is rejected.
+ */
+export declare function compareNatural<T>(a: T, b: T): number;
+/**
+ * Invert a comparator. Useful for max-heaps built on min-heap machinery.
+ */
+export declare function reverseComparator<T>(compare: Comparator<T>): Comparator<T>;
+/**
+ * Derive a comparator for `T` from a key selector and an optional key
+ * comparator. The selector is evaluated once per comparison; callers that need
+ * caching should build it outside the hot path.
+ */
+export declare function byKey<T, K>(select: (value: T) => K, compare?: Comparator<K>): Comparator<T>;
+/**
+ * Clamp a comparator result to the documented -1/0/1 shape.
+ */
+export declare function sign(value: number): -1 | 0 | 1;
+/**
+ * The default comparator used when a structure's options omit one.
+ */
+export declare const defaultCompare: Comparator<unknown>;

package/lib/structure/compare.js

@@ -0,0 +1,96 @@
+/**
+ * Ordering primitives shared by the ordered structures.
+ *
+ * A comparator returns a negative number when `a` sorts before `b`, zero when
+ * they are equivalent for the structure, and a positive number otherwise.
+ * The structures only require a total preorder; duplicate equivalence is
+ * resolved by the container (e.g. a search tree keeps one representative).
+ */
+/**
+ * Numeric comparison. NaN is rejected rather than silently sorted.
+ */
+export function compareNumbers(a, b) {
+    if (Number.isNaN(a) || Number.isNaN(b)) {
+        throw new TypeError("cannot order NaN");
+    }
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/**
+ * Lexicographic UTF-16 comparison, matching JavaScript's `<`.
+ */
+export function compareStrings(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/**
+ * BigInt comparison, safe for values outside the number range.
+ */
+export function compareBigInts(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/**
+ * Chronological comparison of two Dates (invalid dates are rejected).
+ */
+export function compareDates(a, b) {
+    const left = a.getTime();
+    const right = b.getTime();
+    if (!Number.isFinite(left) || !Number.isFinite(right)) {
+        throw new TypeError("cannot order an invalid Date");
+    }
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+/**
+ * Natural ordering for the primitive types this library supports.
+ *
+ * It deliberately throws for unsupported values instead of coercing them to
+ * strings: a search tree built on `"[object Object]"` order is a silent bug.
+ * Equal primitive values compare as `0`; `-0` and `0` are equivalent, and
+ * `NaN` is rejected.
+ */
+export function compareNatural(a, b) {
+    if (typeof (a) === "number" && typeof (b) === "number") {
+        return compareNumbers(a, b);
+    }
+    if (typeof (a) === "bigint" && typeof (b) === "bigint") {
+        return compareBigInts(a, b);
+    }
+    if (typeof (a) === "string" && typeof (b) === "string") {
+        return compareStrings(a, b);
+    }
+    if (typeof (a) === "boolean" && typeof (b) === "boolean") {
+        return a === b ? 0 : a ? 1 : -1;
+    }
+    if (a instanceof Date && b instanceof Date) {
+        return compareDates(a, b);
+    }
+    if (Object.is(a, b)) {
+        return 0;
+    }
+    throw new TypeError(`no natural ordering for ${typeof (a)}; supply a Comparator<T>`);
+}
+/**
+ * Invert a comparator. Useful for max-heaps built on min-heap machinery.
+ */
+export function reverseComparator(compare) {
+    return (a, b) => {
+        const result = compare(a, b);
+        return result === 0 ? 0 : -result;
+    };
+}
+/**
+ * Derive a comparator for `T` from a key selector and an optional key
+ * comparator. The selector is evaluated once per comparison; callers that need
+ * caching should build it outside the hot path.
+ */
+export function byKey(select, compare = compareNatural) {
+    return (a, b) => compare(select(a), select(b));
+}
+/**
+ * Clamp a comparator result to the documented -1/0/1 shape.
+ */
+export function sign(value) {
+    return value < 0 ? -1 : value > 0 ? 1 : 0;
+}
+/**
+ * The default comparator used when a structure's options omit one.
+ */
+export const defaultCompare = (a, b) => compareNatural(a, b);

package/lib/structure/cuckooFilter.d.ts

@@ -0,0 +1,149 @@
+import type { FilterKey } from "./filterKey.js";
+/**
+ * A cuckoo filter with two candidate buckets and compact fingerprints.
+ *
+ * Unlike a Bloom filter, a cuckoo filter supports deletion of individual keys.
+ * Each key is reduced to a small fingerprint and two bucket indices; insertion
+ * places the fingerprint in either bucket, kicking existing fingerprints to
+ * their alternate bucket when both are full. A bounded kick chain is fully
+ * rolled back if it cannot find a free slot, so a failed `add` never silently
+ * loses a previously accepted key.
+ *
+ * False positives are possible (a different key may share both buckets and the
+ * fingerprint); false negatives are not, provided the same key bytes are used
+ * for insert, lookup, and delete. Duplicate keys are allowed.
+ */
+/**
+ * Construction options for {@link CuckooFilter}.
+ */
+export interface CuckooFilterOptions {
+    /**
+     * Requested key capacity; the actual slot count rounds up to a power of two.
+     */
+    capacity: number;
+    /**
+     * Fingerprints per bucket. Defaults to `4`.
+     */
+    bucketSize?: number;
+    /**
+     * Fingerprint width in bits, 4..30. Defaults to `8`.
+     */
+    fingerprintBits?: number;
+    /**
+     * Maximum kick chain before insertion fails and rolls back. Defaults to `500`.
+     */
+    maxKicks?: number;
+    /**
+     * Domain seed for key and fingerprint hashing. Defaults to `0n`.
+     */
+    seed?: bigint;
+}
+/**
+ * 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 declare class CuckooFilter {
+    /**
+     * Requested key capacity before bucket rounding.
+     */
+    readonly requestedCapacity: number;
+    /**
+     * Fingerprints per bucket.
+     */
+    readonly bucketSize: number;
+    /**
+     * Number of buckets (a power of two).
+     */
+    readonly bucketCount: number;
+    /**
+     * Total fingerprint slots: `bucketCount * bucketSize`.
+     */
+    readonly capacity: number;
+    /**
+     * Fingerprint width in bits.
+     */
+    readonly fingerprintBits: number;
+    /**
+     * Maximum number of displacements per insertion.
+     */
+    readonly maxKicks: number;
+    private readonly buckets;
+    private readonly seed;
+    private readonly indexMask;
+    private readonly fingerprintMask;
+    private readonly initialRng;
+    private rngState;
+    private count;
+    /**
+     * 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: CuckooFilterOptions);
+    /**
+     * 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: FilterKey): boolean;
+    /**
+     * Test whether a key may be present.
+     */
+    has(key: FilterKey): boolean;
+    /**
+     * 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: FilterKey): boolean;
+    /**
+     * Remove every key and reset the random kick state.
+     */
+    clear(): void;
+    /**
+     * Number of stored fingerprints.
+     */
+    get size(): number;
+    /**
+     * Fraction of fingerprint slots occupied.
+     */
+    get loadFactor(): number;
+    /**
+     * True when every fingerprint slot is occupied.
+     */
+    get isFull(): boolean;
+    /**
+     * Approximate false-positive probability for a non-full filter:
+     * `2 * bucketSize / 2^fingerprintBits`.
+     */
+    get falsePositiveRate(): number;
+    /**
+     * Hash a key once, yielding its first bucket and compact fingerprint.
+     */
+    private locate;
+    /**
+     * The other candidate bucket for a fingerprint in `index`.
+     */
+    private alternate;
+    /**
+     * Choose an initial bucket, preferring one with room.
+     */
+    private pickBucket;
+    /**
+     * Remove the first matching fingerprint from one bucket.
+     */
+    private removeFingerprint;
+    /**
+     * Xorshift32 in [0, bound); deterministic for a given seed and insertion order.
+     */
+    private randomInt;
+}