@woosh/meep-engine 3.45.0 → 3.47.0

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));
+}

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

@@ -0,0 +1,224 @@
+/**
+ * Truncate to 64 bits.
+ * @param {bigint} v
+ * @returns {bigint}
+ */
+export function u64(v: bigint): bigint;
+/**
+ * @param {bigint} a
+ * @param {bigint} b
+ * @returns {bigint}
+ */
+export function mul64(a: bigint, b: bigint): bigint;
+/**
+ * @param {bigint} a
+ * @param {bigint} b
+ * @returns {bigint}
+ */
+export function add64(a: bigint, b: bigint): bigint;
+/**
+ * Two's-complement 64-bit subtraction.
+ * @param {bigint} a
+ * @param {bigint} b
+ * @returns {bigint}
+ */
+export function sub64(a: bigint, b: bigint): bigint;
+/**
+ * @param {bigint} v
+ * @param {number} bits
+ * @returns {bigint}
+ */
+export function rotl64(v: bigint, bits: number): bigint;
+/**
+ * Rotate within 32 bits, as the reference's `XXH_rotl32`.
+ * @param {bigint} v
+ * @param {number} bits
+ * @returns {bigint}
+ */
+export function rotl32(v: bigint, bits: number): bigint;
+/**
+ * @param {bigint} v
+ * @param {number} bits
+ * @returns {bigint}
+ */
+export function xorshift64(v: bigint, bits: number): bigint;
+/**
+ * Byte-reverse a 32-bit value, as the reference's `XXH_swap32`.
+ * @param {bigint} v
+ * @returns {bigint}
+ */
+export function swap32(v: bigint): bigint;
+/**
+ * Byte-reverse a 64-bit value, as the reference's `XXH_swap64`.
+ * @param {bigint} v
+ * @returns {bigint}
+ */
+export function swap64(v: bigint): bigint;
+/**
+ * Widening 32x32 -> 64 multiply of the low halves of both operands, as the reference's
+ * `XXH_mult32to64`.
+ *
+ * @param {bigint} a
+ * @param {bigint} b
+ * @returns {bigint}
+ */
+export function mult32to64(a: bigint, b: bigint): bigint;
+/**
+ * 64x64 -> 128 multiply, folded down by XOR of the two halves.
+ *
+ * @param {bigint} a
+ * @param {bigint} b
+ * @returns {bigint}
+ */
+export function mul128_fold64(a: bigint, b: bigint): bigint;
+/**
+ * The fast finalizing mix, for input whose bits are already partially mixed.
+ * @param {bigint} h64
+ * @returns {bigint}
+ */
+export function xxh3_avalanche(h64: bigint): bigint;
+/**
+ * The stronger finalizing mix (after Pelle Evensen's rrmxmx), for input that has not been mixed yet.
+ * @param {bigint} h64
+ * @param {number} len
+ * @returns {bigint}
+ */
+export function xxh3_rrmxmx(h64: bigint, len: number): bigint;
+/**
+ * XXH64's finalizing mix, which XXH3 reuses for its shortest inputs.
+ * @param {bigint} hash
+ * @returns {bigint}
+ */
+export function xxh64_avalanche(hash: bigint): bigint;
+/**
+ * Read a little-endian u32 at `offset`.
+ *
+ * @param {Uint8Array} bytes
+ * @param {number} offset
+ * @returns {bigint}
+ */
+export function read_u32(bytes: Uint8Array, offset: number): bigint;
+/**
+ * Read a little-endian u64 at `offset`.
+ *
+ * @param {Uint8Array} bytes
+ * @param {number} offset
+ * @returns {bigint}
+ */
+export function read_u64(bytes: Uint8Array, offset: number): bigint;
+/**
+ * Write a little-endian u64 at `offset`.
+ *
+ * @param {Uint8Array} bytes
+ * @param {number} offset
+ * @param {bigint} value
+ */
+export function write_u64(bytes: Uint8Array, offset: number, value: bigint): void;
+/**
+ * The 16-byte mixing step shared by every mid-size path.
+ *
+ * @param {Uint8Array} input
+ * @param {number} input_offset
+ * @param {Uint8Array} secret
+ * @param {number} secret_offset
+ * @param {bigint} seed
+ * @returns {bigint}
+ */
+export function xxh3_mix16b(input: Uint8Array, input_offset: number, secret: Uint8Array, secret_offset: number, seed: bigint): bigint;
+/**
+ * Derive a 192-byte secret from `seed`, as the reference's `XXH3_initCustomSecret`. This is what
+ * makes a seeded hash of a long input differ from the unseeded one.
+ *
+ * @param {bigint} seed
+ * @returns {Uint8Array} freshly allocated, {@link XXH3_SECRET}'s length
+ */
+export function xxh3_init_custom_secret(seed: bigint): Uint8Array;
+/**
+ * Run the whole long-input accumulator loop: whole blocks with a scramble after each, then the
+ * trailing partial block, then the (possibly overlapping) final stripe.
+ *
+ * @param {BigUint64Array} acc
+ * @param {Uint8Array} input
+ * @param {Uint8Array} secret
+ */
+export function xxh3_hash_long_loop(acc: BigUint64Array, input: Uint8Array, secret: Uint8Array): void;
+/**
+ * Fold the eight lanes down to one 64-bit value.
+ *
+ * @param {BigUint64Array} acc
+ * @param {Uint8Array} secret
+ * @param {number} secret_offset
+ * @param {bigint} start
+ * @returns {bigint}
+ */
+export function xxh3_merge_accs(acc: BigUint64Array, secret: Uint8Array, secret_offset: number, start: bigint): bigint;
+/**
+ * The accumulator lanes' initial state.
+ * @returns {BigUint64Array} freshly allocated, {@link XXH_ACC_NB} lanes
+ */
+export function xxh3_init_acc(): BigUint64Array;
+/**
+ * The secret a seeded hash of a long input runs against: the default one for seed 0, a derived one
+ * otherwise. Shared by both variants so they agree on the seed-0 shortcut.
+ *
+ * @param {bigint} seed
+ * @returns {Uint8Array}
+ */
+export function xxh3_long_secret(seed: bigint): Uint8Array;
+/**
+ * Common argument checks for the public entry points.
+ *
+ * @param {Uint8Array} input
+ * @param {bigint} seed
+ */
+export function xxh3_assert_arguments(input: Uint8Array, seed: bigint): void;
+/**
+ * The pieces of xxHash3 that the 64-bit and 128-bit variants share: the primes, the mixing stages,
+ * and the long-input accumulator loop. Everything here is a direct transcription of the reference
+ * implementation's scalar path — the vectorized paths produce identical results by construction, so
+ * the scalar one is the whole specification.
+ *
+ * Arithmetic is `BigInt` masked to 64 bits after every operation. This is a build-time hash (asset
+ * identity, container checksums), never a per-frame one, so clarity against the reference wins over
+ * the 32-bit-lane decomposition a runtime implementation would need.
+ *
+ * @see https://github.com/Cyan4973/xxHash/blob/dev/xxhash.h
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * @readonly
+ * @type {bigint}
+ */
+export const XXH_MASK_64: bigint;
+export const XXH_PRIME32_1: 2654435761n;
+export const XXH_PRIME32_2: 2246822519n;
+export const XXH_PRIME32_3: 3266489917n;
+export const XXH_PRIME64_1: 11400714785074694791n;
+export const XXH_PRIME64_2: 14029467366897019727n;
+export const XXH_PRIME64_3: 1609587929392839161n;
+export const XXH_PRIME64_4: 9650029242287828579n;
+export const XXH_PRIME64_5: 2870177450012600261n;
+export const XXH_PRIME_MX1: 1609587791953885689n;
+export const XXH_PRIME_MX2: 11507291218515648293n;
+/**
+ * Shortest secret any variant accepts, and the anchor for the mid-size tail offsets.
+ * @readonly
+ * @type {number}
+ */
+export const XXH3_SECRET_SIZE_MIN: number;
+/**
+ * Longest input still handled by the "mid size" single-shot paths.
+ * @readonly
+ * @type {number}
+ */
+export const XXH3_MIDSIZE_MAX: number;
+export const XXH3_MIDSIZE_STARTOFFSET: 3;
+export const XXH3_MIDSIZE_LASTOFFSET: 17;
+export const XXH_STRIPE_LEN: 64;
+export const XXH_SECRET_CONSUME_RATE: 8;
+export const XXH_ACC_NB: 8;
+export const XXH_SECRET_LASTACC_START: 7;
+export const XXH_SECRET_MERGEACCS_START: 11;
+//# sourceMappingURL=xxh3_common.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"xxh3_common.d.ts","sourceRoot":"","sources":["../../../../../src/core/math/hash/xxh3_common.js"],"names":[],"mappings":"AA+DA;;;;GAIG;AACH,uBAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;GAIG;AACH,yBAJW,MAAM,KACN,MAAM,GACJ,MAAM,CAIlB;AAED;;;;GAIG;AACH,yBAJW,MAAM,KACN,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;GAKG;AACH,yBAJW,MAAM,KACN,MAAM,GACJ,MAAM,CAIlB;AAED;;;;GAIG;AACH,0BAJW,MAAM,QACN,MAAM,GACJ,MAAM,CAMlB;AAED;;;;;GAKG;AACH,0BAJW,MAAM,QACN,MAAM,GACJ,MAAM,CAOlB;AAED;;;;GAIG;AACH,8BAJW,MAAM,QACN,MAAM,GACJ,MAAM,CAIlB;AAED;;;;GAIG;AACH,0BAHW,MAAM,GACJ,MAAM,CAMlB;AAED;;;;GAIG;AACH,0BAHW,MAAM,GACJ,MAAM,CAWlB;AAED;;;;;;;GAOG;AACH,8BAJW,MAAM,KACN,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;GAMG;AACH,iCAJW,MAAM,KACN,MAAM,GACJ,MAAM,CAMlB;AAED;;;;GAIG;AACH,oCAHW,MAAM,GACJ,MAAM,CASlB;AAED;;;;;GAKG;AACH,iCAJW,MAAM,OACN,MAAM,GACJ,MAAM,CAUlB;AAED;;;;GAIG;AACH,sCAHW,MAAM,GACJ,MAAM,CAWlB;AAED;;;;;;GAMG;AACH,gCAJW,UAAU,UACV,MAAM,GACJ,MAAM,CASlB;AAED;;;;;;GAMG;AACH,gCAJW,UAAU,UACV,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;GAMG;AACH,iCAJW,UAAU,UACV,MAAM,SACN,MAAM,QAShB;AAED;;;;;;;;;GASG;AACH,mCAPW,UAAU,gBACV,MAAM,UACN,UAAU,iBACV,MAAM,QACN,MAAM,GACJ,MAAM,CAUlB;AAED;;;;;;GAMG;AACH,8CAHW,MAAM,GACJ,UAAU,CAgBtB;AA6DD;;;;;;;GAOG;AACH,yCAJW,cAAc,SACd,UAAU,UACV,UAAU,QAwBpB;AAED;;;;;;;;GAQG;AACH,qCANW,cAAc,UACd,UAAU,iBACV,MAAM,SACN,MAAM,GACJ,MAAM,CAalB;AAED;;;GAGG;AACH,iCAFa,cAAc,CAe1B;AAED;;;;;;GAMG;AACH,uCAHW,MAAM,GACJ,UAAU,CAQtB;AAED;;;;;GAKG;AACH,6CAHW,UAAU,QACV,MAAM,QAOhB;AAxdD;;;;;;;;;;;;;;GAcG;AAEH;;;GAGG;AACH,0BAFU,MAAM,CAE+B;AAI/C,wCAAyC;AACzC,wCAAyC;AACzC,wCAAyC;AAEzC,kDAAiD;AACjD,kDAAiD;AACjD,iDAAiD;AACjD,iDAAiD;AACjD,iDAAiD;AAEjD,iDAAiD;AACjD,kDAAiD;AAEjD;;;;GAIG;AACH,mCAFU,MAAM,CAEwB;AAExC;;;;GAIG;AACH,+BAFU,MAAM,CAEoB;AAEpC,yCAA0C;AAC1C,yCAA0C;AAE1C,gCAAiC;AACjC,wCAAyC;AACzC,2BAA4B;AAC5B,yCAA0C;AAC1C,4CAA6C"}