@woosh/meep-engine 3.44.0 → 3.46.0

package/src/core/math/hash/xxh3_128.js

@@ -0,0 +1,341 @@
+import { XXH128Hash } from "./XXH128Hash.js";
+import { XXH3_SECRET } from "./XXH3_SECRET.js";
+import {
+    add64,
+    mul64,
+    mult32to64,
+    read_u32,
+    read_u64,
+    rotl32,
+    sub64,
+    swap32,
+    swap64,
+    u64,
+    XXH3_MIDSIZE_LASTOFFSET,
+    XXH3_MIDSIZE_MAX,
+    XXH3_MIDSIZE_STARTOFFSET,
+    XXH3_SECRET_SIZE_MIN,
+    xxh3_assert_arguments,
+    xxh3_avalanche,
+    xxh3_hash_long_loop,
+    xxh3_init_acc,
+    xxh3_long_secret,
+    xxh3_merge_accs,
+    xxh3_mix16b,
+    XXH_MASK_64,
+    XXH_PRIME32_2,
+    XXH_PRIME64_1,
+    XXH_PRIME64_2,
+    XXH_PRIME64_4,
+    XXH_PRIME_MX2,
+    XXH_SECRET_MERGEACCS_START,
+    XXH_STRIPE_LEN,
+    xorshift64,
+    xxh64_avalanche,
+} from "./xxh3_common.js";
+
+/**
+ * xxHash3, 128-bit output.
+ *
+ * A direct transcription of the reference implementation, verified against its published sanity
+ * vectors — see `xxh3_128.spec.js`. The low 64 bits are *not* in general equal to
+ * {@link xxh3_64} of the same input; they only coincide for inputs longer than
+ * {@link XXH3_MIDSIZE_MAX}, where both variants share the accumulator loop.
+ *
+ * @see https://github.com/Cyan4973/xxHash
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Full 64x64 -> 128 multiply. The halves are returned separately because every caller manipulates
+ * them independently before folding.
+ *
+ * @param {bigint} a
+ * @param {bigint} b
+ * @returns {XXH128Hash}
+ */
+function mult64to128(a, b) {
+    const product = a * b;
+
+    return new XXH128Hash(product & XXH_MASK_64, (product >> 64n) & XXH_MASK_64);
+}
+
+/**
+ * @param {Uint8Array} input 1..3 bytes
+ * @param {Uint8Array} secret
+ * @param {bigint} seed
+ * @returns {XXH128Hash}
+ */
+function len_1to3(input, secret, seed) {
+    const len = input.length;
+
+    const c1 = input[0];
+    const c2 = input[len >> 1];
+    const c3 = input[len - 1];
+
+    const combined_lo = BigInt(((c1 << 16) | (c2 << 24) | c3 | (len << 8)) >>> 0);
+    const combined_hi = rotl32(swap32(combined_lo), 13);
+
+    const bitflip_lo = add64(read_u32(secret, 0) ^ read_u32(secret, 4), seed);
+    const bitflip_hi = sub64(read_u32(secret, 8) ^ read_u32(secret, 12), seed);
+
+    return new XXH128Hash(
+        xxh64_avalanche(combined_lo ^ bitflip_lo),
+        xxh64_avalanche(combined_hi ^ bitflip_hi)
+    );
+}
+
+/**
+ * @param {Uint8Array} input 4..8 bytes
+ * @param {Uint8Array} secret
+ * @param {bigint} seed
+ * @returns {XXH128Hash}
+ */
+function len_4to8(input, secret, seed) {
+    const len = input.length;
+
+    const mixed_seed = seed ^ u64(swap32(seed) << 32n);
+
+    const input_lo = read_u32(input, 0);
+    const input_hi = read_u32(input, len - 4);
+
+    const input_64 = add64(input_lo, input_hi << 32n);
+    const bitflip = add64(read_u64(secret, 16) ^ read_u64(secret, 24), mixed_seed);
+    const keyed = input_64 ^ bitflip;
+
+    const m128 = mult64to128(keyed, add64(XXH_PRIME64_1, BigInt(len) << 2n));
+
+    m128.high64 = add64(m128.high64, u64(m128.low64 << 1n));
+    m128.low64 = m128.low64 ^ (m128.high64 >> 3n);
+
+    m128.low64 = xorshift64(m128.low64, 35);
+    m128.low64 = mul64(m128.low64, XXH_PRIME_MX2);
+    m128.low64 = xorshift64(m128.low64, 28);
+    m128.high64 = xxh3_avalanche(m128.high64);
+
+    return m128;
+}
+
+/**
+ * @param {Uint8Array} input 9..16 bytes
+ * @param {Uint8Array} secret
+ * @param {bigint} seed
+ * @returns {XXH128Hash}
+ */
+function len_9to16(input, secret, seed) {
+    const len = input.length;
+
+    const bitflip_lo = sub64(read_u64(secret, 32) ^ read_u64(secret, 40), seed);
+    const bitflip_hi = add64(read_u64(secret, 48) ^ read_u64(secret, 56), seed);
+
+    const input_lo = read_u64(input, 0);
+
+    let input_hi = read_u64(input, len - 8);
+
+    const m128 = mult64to128(input_lo ^ input_hi ^ bitflip_lo, XXH_PRIME64_1);
+
+    m128.low64 = add64(m128.low64, BigInt(len - 1) << 54n);
+
+    input_hi ^= bitflip_hi;
+
+    m128.high64 = add64(
+        m128.high64,
+        add64(input_hi, mult32to64(input_hi, XXH_PRIME32_2 - 1n))
+    );
+
+    m128.low64 = m128.low64 ^ swap64(m128.high64);
+
+    const h128 = mult64to128(m128.low64, XXH_PRIME64_2);
+
+    h128.high64 = add64(h128.high64, mul64(m128.high64, XXH_PRIME64_2));
+
+    h128.low64 = xxh3_avalanche(h128.low64);
+    h128.high64 = xxh3_avalanche(h128.high64);
+
+    return h128;
+}
+
+/**
+ * @param {Uint8Array} input 0..16 bytes
+ * @param {Uint8Array} secret
+ * @param {bigint} seed
+ * @returns {XXH128Hash}
+ */
+function len_0to16(input, secret, seed) {
+    const len = input.length;
+
+    if (len > 8) {
+        return len_9to16(input, secret, seed);
+    }
+
+    if (len >= 4) {
+        return len_4to8(input, secret, seed);
+    }
+
+    if (len > 0) {
+        return len_1to3(input, secret, seed);
+    }
+
+    const bitflip_lo = read_u64(secret, 64) ^ read_u64(secret, 72);
+    const bitflip_hi = read_u64(secret, 80) ^ read_u64(secret, 88);
+
+    return new XXH128Hash(
+        xxh64_avalanche(seed ^ bitflip_lo),
+        xxh64_avalanche(seed ^ bitflip_hi)
+    );
+}
+
+/**
+ * The 32-byte mixing step: two 16-byte windows, each folded into one half and cross-XOR'd into the
+ * other. Slower than the 64-bit path's `mix16B`, and better behaved when a product lands on zero.
+ *
+ * @param {XXH128Hash} acc mutated in place
+ * @param {Uint8Array} input
+ * @param {number} input_1
+ * @param {number} input_2
+ * @param {Uint8Array} secret
+ * @param {number} secret_offset
+ * @param {bigint} seed
+ */
+function mix32b(acc, input, input_1, input_2, secret, secret_offset, seed) {
+    acc.low64 = add64(acc.low64, xxh3_mix16b(input, input_1, secret, secret_offset, seed));
+    acc.low64 = acc.low64 ^ add64(read_u64(input, input_2), read_u64(input, input_2 + 8));
+
+    acc.high64 = add64(acc.high64, xxh3_mix16b(input, input_2, secret, secret_offset + 16, seed));
+    acc.high64 = acc.high64 ^ add64(read_u64(input, input_1), read_u64(input, input_1 + 8));
+}
+
+/**
+ * The shared tail of both mid-size paths.
+ *
+ * @param {XXH128Hash} acc
+ * @param {number} len
+ * @param {bigint} seed
+ * @returns {XXH128Hash}
+ */
+function finalize_midsize(acc, len, seed) {
+    const low64 = xxh3_avalanche(add64(acc.low64, acc.high64));
+
+    const high64 = xxh3_avalanche(add64(
+        add64(mul64(acc.low64, XXH_PRIME64_1), mul64(acc.high64, XXH_PRIME64_4)),
+        mul64(sub64(BigInt(len), seed), XXH_PRIME64_2)
+    ));
+
+    return new XXH128Hash(low64, sub64(0n, high64));
+}
+
+/**
+ * @param {Uint8Array} input 17..128 bytes
+ * @param {Uint8Array} secret
+ * @param {bigint} seed
+ * @returns {XXH128Hash}
+ */
+function len_17to128(input, secret, seed) {
+    const len = input.length;
+
+    const acc = new XXH128Hash(mul64(BigInt(len), XXH_PRIME64_1), 0n);
+
+    if (len > 32) {
+        if (len > 64) {
+            if (len > 96) {
+                mix32b(acc, input, 48, len - 64, secret, 96, seed);
+            }
+
+            mix32b(acc, input, 32, len - 48, secret, 64, seed);
+        }
+
+        mix32b(acc, input, 16, len - 32, secret, 32, seed);
+    }
+
+    mix32b(acc, input, 0, len - 16, secret, 0, seed);
+
+    return finalize_midsize(acc, len, seed);
+}
+
+/**
+ * @param {Uint8Array} input 129..240 bytes
+ * @param {Uint8Array} secret
+ * @param {bigint} seed
+ * @returns {XXH128Hash}
+ */
+function len_129to240(input, secret, seed) {
+    const len = input.length;
+
+    const acc = new XXH128Hash(mul64(BigInt(len), XXH_PRIME64_1), 0n);
+
+    for (let i = 32; i < 160; i += 32) {
+        mix32b(acc, input, i - 32, i - 16, secret, i - 32, seed);
+    }
+
+    acc.low64 = xxh3_avalanche(acc.low64);
+    acc.high64 = xxh3_avalanche(acc.high64);
+
+    for (let i = 160; i <= len; i += 32) {
+        mix32b(acc, input, i - 32, i - 16, secret, XXH3_MIDSIZE_STARTOFFSET + i - 160, seed);
+    }
+
+    mix32b(
+        acc,
+        input, len - 16, len - 32,
+        secret, XXH3_SECRET_SIZE_MIN - XXH3_MIDSIZE_LASTOFFSET - 16,
+        sub64(0n, seed)
+    );
+
+    return finalize_midsize(acc, len, seed);
+}
+
+/**
+ * @param {Uint8Array} input more than {@link XXH3_MIDSIZE_MAX} bytes
+ * @param {Uint8Array} secret
+ * @returns {XXH128Hash}
+ */
+function hash_long(input, secret) {
+    const acc = xxh3_init_acc();
+
+    xxh3_hash_long_loop(acc, input, secret);
+
+    const len = BigInt(input.length);
+
+    const low64 = xxh3_merge_accs(
+        acc,
+        secret, XXH_SECRET_MERGEACCS_START,
+        mul64(len, XXH_PRIME64_1)
+    );
+
+    const high64 = xxh3_merge_accs(
+        acc,
+        secret, secret.length - XXH_STRIPE_LEN - XXH_SECRET_MERGEACCS_START,
+        XXH_MASK_64 ^ mul64(len, XXH_PRIME64_2)
+    );
+
+    return new XXH128Hash(low64, high64);
+}
+
+/**
+ * Hash `input` to a 128-bit value.
+ *
+ * @param {Uint8Array} input bytes to hash; an empty array is valid
+ * @param {bigint} [seed] alters the whole hash; 0 selects the reference's unseeded behaviour
+ * @returns {XXH128Hash}
+ */
+export function xxh3_128(input, seed = 0n) {
+    xxh3_assert_arguments(input, seed);
+
+    const len = input.length;
+
+    if (len <= 16) {
+        return len_0to16(input, XXH3_SECRET, seed);
+    }
+
+    if (len <= 128) {
+        return len_17to128(input, XXH3_SECRET, seed);
+    }
+
+    if (len <= XXH3_MIDSIZE_MAX) {
+        return len_129to240(input, XXH3_SECRET, seed);
+    }
+
+    return hash_long(input, xxh3_long_secret(seed));
+}

package/src/core/math/hash/xxh3_64.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Hash `input` to a 64-bit value.
+ *
+ * @param {Uint8Array} input bytes to hash; an empty array is valid
+ * @param {bigint} [seed] alters the whole hash; 0 selects the reference's unseeded behaviour
+ * @returns {bigint} in `[0, 2^64)`
+ */
+export function xxh3_64(input: Uint8Array, seed?: bigint): bigint;
+//# sourceMappingURL=xxh3_64.d.ts.map

package/src/core/math/hash/xxh3_64.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xxh3_64.d.ts","sourceRoot":"","sources":["../../../../../src/core/math/hash/xxh3_64.js"],"names":[],"mappings":"AAuNA;;;;;;GAMG;AACH,+BAJW,UAAU,SACV,MAAM,GACJ,MAAM,CAoBlB"}

package/src/core/math/hash/xxh3_64.js

@@ -0,0 +1,241 @@
+import { XXH3_SECRET } from "./XXH3_SECRET.js";
+import {
+    add64,
+    mul128_fold64,
+    mul64,
+    read_u32,
+    read_u64,
+    sub64,
+    swap32,
+    swap64,
+    u64,
+    XXH3_MIDSIZE_LASTOFFSET,
+    XXH3_MIDSIZE_MAX,
+    XXH3_MIDSIZE_STARTOFFSET,
+    XXH3_SECRET_SIZE_MIN,
+    xxh3_assert_arguments,
+    xxh3_avalanche,
+    xxh3_hash_long_loop,
+    xxh3_init_acc,
+    xxh3_long_secret,
+    xxh3_merge_accs,
+    xxh3_mix16b,
+    xxh3_rrmxmx,
+    XXH_PRIME64_1,
+    XXH_SECRET_MERGEACCS_START,
+    xxh64_avalanche,
+} from "./xxh3_common.js";
+
+/**
+ * xxHash3, 64-bit output.
+ *
+ * A direct transcription of the reference implementation, verified against its published sanity
+ * vectors — see `xxh3_64.spec.js`. Same bytes and same seed always produce the same value, on every
+ * platform, which is what makes it usable as a content address.
+ *
+ * @see https://github.com/Cyan4973/xxHash
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * @param {Uint8Array} input 1..3 bytes
+ * @param {Uint8Array} secret
+ * @param {bigint} seed
+ * @returns {bigint}
+ */
+function len_1to3(input, secret, seed) {
+    const len = input.length;
+
+    const c1 = input[0];
+    const c2 = input[len >> 1];
+    const c3 = input[len - 1];
+
+    const combined = BigInt(
+        (((c1 << 16) | (c2 << 24) | c3 | (len << 8)) >>> 0)
+    );
+
+    const bitflip = add64(read_u32(secret, 0) ^ read_u32(secret, 4), seed);
+
+    return xxh64_avalanche(combined ^ bitflip);
+}
+
+/**
+ * @param {Uint8Array} input 4..8 bytes
+ * @param {Uint8Array} secret
+ * @param {bigint} seed
+ * @returns {bigint}
+ */
+function len_4to8(input, secret, seed) {
+    const len = input.length;
+
+    const mixed_seed = seed ^ u64(swap32(seed) << 32n);
+
+    const input1 = read_u32(input, 0);
+    const input2 = read_u32(input, len - 4);
+
+    const bitflip = sub64(read_u64(secret, 8) ^ read_u64(secret, 16), mixed_seed);
+    const input64 = add64(input2, input1 << 32n);
+
+    return xxh3_rrmxmx(input64 ^ bitflip, len);
+}
+
+/**
+ * @param {Uint8Array} input 9..16 bytes
+ * @param {Uint8Array} secret
+ * @param {bigint} seed
+ * @returns {bigint}
+ */
+function len_9to16(input, secret, seed) {
+    const len = input.length;
+
+    const bitflip1 = add64(read_u64(secret, 24) ^ read_u64(secret, 32), seed);
+    const bitflip2 = sub64(read_u64(secret, 40) ^ read_u64(secret, 48), seed);
+
+    const input_lo = read_u64(input, 0) ^ bitflip1;
+    const input_hi = read_u64(input, len - 8) ^ bitflip2;
+
+    const acc = add64(
+        add64(BigInt(len), add64(swap64(input_lo), input_hi)),
+        mul128_fold64(input_lo, input_hi)
+    );
+
+    return xxh3_avalanche(acc);
+}
+
+/**
+ * @param {Uint8Array} input 0..16 bytes
+ * @param {Uint8Array} secret
+ * @param {bigint} seed
+ * @returns {bigint}
+ */
+function len_0to16(input, secret, seed) {
+    const len = input.length;
+
+    if (len > 8) {
+        return len_9to16(input, secret, seed);
+    }
+
+    if (len >= 4) {
+        return len_4to8(input, secret, seed);
+    }
+
+    if (len > 0) {
+        return len_1to3(input, secret, seed);
+    }
+
+    return xxh64_avalanche(seed ^ (read_u64(secret, 56) ^ read_u64(secret, 64)));
+}
+
+/**
+ * @param {Uint8Array} input 17..128 bytes
+ * @param {Uint8Array} secret
+ * @param {bigint} seed
+ * @returns {bigint}
+ */
+function len_17to128(input, secret, seed) {
+    const len = input.length;
+
+    let acc = mul64(BigInt(len), XXH_PRIME64_1);
+
+    if (len > 32) {
+        if (len > 64) {
+            if (len > 96) {
+                acc = add64(acc, xxh3_mix16b(input, 48, secret, 96, seed));
+                acc = add64(acc, xxh3_mix16b(input, len - 64, secret, 112, seed));
+            }
+
+            acc = add64(acc, xxh3_mix16b(input, 32, secret, 64, seed));
+            acc = add64(acc, xxh3_mix16b(input, len - 48, secret, 80, seed));
+        }
+
+        acc = add64(acc, xxh3_mix16b(input, 16, secret, 32, seed));
+        acc = add64(acc, xxh3_mix16b(input, len - 32, secret, 48, seed));
+    }
+
+    acc = add64(acc, xxh3_mix16b(input, 0, secret, 0, seed));
+    acc = add64(acc, xxh3_mix16b(input, len - 16, secret, 16, seed));
+
+    return xxh3_avalanche(acc);
+}
+
+/**
+ * @param {Uint8Array} input 129..240 bytes
+ * @param {Uint8Array} secret
+ * @param {bigint} seed
+ * @returns {bigint}
+ */
+function len_129to240(input, secret, seed) {
+    const len = input.length;
+
+    let acc = mul64(BigInt(len), XXH_PRIME64_1);
+
+    const round_count = (len / 16) | 0;
+
+    for (let i = 0; i < 8; i++) {
+        acc = add64(acc, xxh3_mix16b(input, 16 * i, secret, 16 * i, seed));
+    }
+
+    let acc_end = xxh3_mix16b(
+        input, len - 16,
+        secret, XXH3_SECRET_SIZE_MIN - XXH3_MIDSIZE_LASTOFFSET,
+        seed
+    );
+
+    acc = xxh3_avalanche(acc);
+
+    for (let i = 8; i < round_count; i++) {
+        acc_end = add64(acc_end, xxh3_mix16b(
+            input, 16 * i,
+            secret, 16 * (i - 8) + XXH3_MIDSIZE_STARTOFFSET,
+            seed
+        ));
+    }
+
+    return xxh3_avalanche(add64(acc, acc_end));
+}
+
+/**
+ * @param {Uint8Array} input more than {@link XXH3_MIDSIZE_MAX} bytes
+ * @param {Uint8Array} secret
+ * @returns {bigint}
+ */
+function hash_long(input, secret) {
+    const acc = xxh3_init_acc();
+
+    xxh3_hash_long_loop(acc, input, secret);
+
+    return xxh3_merge_accs(
+        acc,
+        secret, XXH_SECRET_MERGEACCS_START,
+        mul64(BigInt(input.length), XXH_PRIME64_1)
+    );
+}
+
+/**
+ * Hash `input` to a 64-bit value.
+ *
+ * @param {Uint8Array} input bytes to hash; an empty array is valid
+ * @param {bigint} [seed] alters the whole hash; 0 selects the reference's unseeded behaviour
+ * @returns {bigint} in `[0, 2^64)`
+ */
+export function xxh3_64(input, seed = 0n) {
+    xxh3_assert_arguments(input, seed);
+
+    const len = input.length;
+
+    if (len <= 16) {
+        return len_0to16(input, XXH3_SECRET, seed);
+    }
+
+    if (len <= 128) {
+        return len_17to128(input, XXH3_SECRET, seed);
+    }
+
+    if (len <= XXH3_MIDSIZE_MAX) {
+        return len_129to240(input, XXH3_SECRET, seed);
+    }
+
+    return hash_long(input, xxh3_long_secret(seed));
+}