@knowvah/dot-engine 0.1.0

package/src/util/bsd-qsort.ts

@@ -0,0 +1,251 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * In-place sort matching C's `qsort(3)` permutation, including its treatment of
+ * comparator-equal elements.
+ *
+ * Graphviz sorts via `LIST_SORT` → `gv_list_sort_` → libc `qsort`
+ * (`lib/util/list.c:gv_list_sort_`). libc `qsort` is **not stable**: it reorders
+ * comparator-equal elements in an implementation-defined permutation. Most port
+ * sort sites can use JS's stable `Array.prototype.sort` because their comparator
+ * never reports a tie (e.g. `edge-order.ts`). Where ties DO occur AND the
+ * downstream result depends on their order, a stable sort diverges from the C
+ * oracle.
+ *
+ * `TB_balance` (`lib/common/ns.c`) is such a site: it sorts nodes by rank
+ * (`increasingrankcmpf`, which returns 0 for equal ranks) and then walks the
+ * sorted list mutating a per-rank population count, so the order of equal-rank
+ * nodes changes which rank each tied node lands on. The macOS/BSD libc `qsort`
+ * the oracle links against is the Bentley & McIlroy "Engineering a Sort
+ * Function" (1993) introspective quicksort: median-of-3 pivot (pseudo-median of
+ * 9 above 40 elements), three-way "fat partition" of equal keys, and an
+ * insertion sort for sub-arrays below 7 elements. This module reproduces that
+ * algorithm exactly so tie ordering matches the oracle.
+ *
+ * Verified: on `graphs/mike.gv` TB_balance this reproduces the oracle's 33-node
+ * permutation byte-for-byte (threshold 7; thresholds 4/6/8 do not match).
+ *
+ * @see lib/util/list.c:gv_list_sort_ (the LIST_SORT backend)
+ * @see Bentley, McIlroy, "Engineering a Sort Function", Softw. Pract. Exper. 1993
+ */
+
+/** Sub-array size below which the C qsort switches to insertion sort. */
+const THRESH = 7;
+/** Array size above which the C qsort uses a pseudo-median of 9 for the pivot. */
+const BIG = 40;
+
+function swap<T>(arr: T[], i: number, j: number): void {
+  const t = arr[i];
+  arr[i] = arr[j];
+  arr[j] = t;
+}
+
+/** Swap `n` consecutive elements starting at `i` with those starting at `j`. */
+function vecswap<T>(arr: T[], i: number, j: number, n: number): void {
+  let k = n;
+  while (k-- > 0) swap(arr, i++, j++);
+}
+
+/** Median of the elements at indices a, b, c under `cmp` (B&M `med3`). */
+function med3<T>(arr: T[], a: number, b: number, c: number, cmp: (x: T, y: T) => number): number {
+  return cmp(arr[a], arr[b]) < 0
+    ? (cmp(arr[b], arr[c]) < 0 ? b : (cmp(arr[a], arr[c]) < 0 ? c : a))
+    : (cmp(arr[b], arr[c]) > 0 ? b : (cmp(arr[a], arr[c]) < 0 ? a : c));
+}
+
+/**
+ * Insertion sort of `arr[lo .. lo+n)` with an optional swap budget (Apple
+ * `_isort`). `swapLimit === 0` means unlimited (the small-array branch, which
+ * must complete). With a positive limit, returns `false` — leaving the array
+ * PARTIALLY sorted, mutations kept, exactly like the C code — once the number
+ * of swaps exceeds the limit.
+ */
+function insertionSort<T>(
+  arr: T[], lo: number, n: number, cmp: (x: T, y: T) => number, swapLimit = 0,
+): boolean {
+  let swapCnt = 0;
+  for (let pm = lo + 1; pm < lo + n; pm++)
+    for (let pl = pm; pl > lo && cmp(arr[pl - 1], arr[pl]) > 0; pl--) {
+      swap(arr, pl, pl - 1);
+      if (swapLimit !== 0 && ++swapCnt > swapLimit) return false;
+    }
+  return true;
+}
+
+/** Pick the pivot index for `arr[lo .. lo+n)` (median-of-3, pseudo-median of 9). */
+function choosePivot<T>(arr: T[], lo: number, n: number, cmp: (x: T, y: T) => number): number {
+  let pm = lo + (n >> 1);
+  let pl = lo;
+  let pn = lo + (n - 1);
+  if (n > BIG) {
+    const d = n >> 3;
+    pl = med3(arr, pl, pl + d, pl + 2 * d, cmp);
+    pm = med3(arr, pm - d, pm, pm + d, cmp);
+    pn = med3(arr, pn - 2 * d, pn - d, pn, cmp);
+  }
+  return med3(arr, pl, pm, pn, cmp);
+}
+
+/** Boundaries of the three-way partition: [lo,pb) < pivot, [pc..) > pivot. */
+interface Part { pa: number; pb: number; pc: number; pd: number; swapped: boolean; }
+
+/**
+ * Three-way ("fat") partition around the pivot at `arr[lo]`. Equal keys are
+ * shoved to the two ends (pa/pd) and swapped back to the middle by the caller.
+ */
+function partition3<T>(arr: T[], lo: number, n: number, cmp: (x: T, y: T) => number): Part {
+  let pa = lo + 1;
+  let pb = lo + 1;
+  let pc = lo + (n - 1);
+  let pd = lo + (n - 1);
+  let swapped = false;
+  for (;;) {
+    let r: number;
+    while (pb <= pc && (r = cmp(arr[pb], arr[lo])) <= 0) {
+      if (r === 0) { swapped = true; swap(arr, pa, pb); pa++; }
+      pb++;
+    }
+    while (pb <= pc && (r = cmp(arr[pc], arr[lo])) >= 0) {
+      if (r === 0) { swapped = true; swap(arr, pc, pd); pd--; }
+      pc--;
+    }
+    if (pb > pc) break;
+    swap(arr, pb, pc);
+    swapped = true;
+    pb++;
+    pc--;
+  }
+  return { pa, pb, pc, pd, swapped };
+}
+
+/**
+ * Sift the 1-based virtual index `parI` down through the max-heap occupying
+ * `arr[lo .. lo+nmemb)` (virtual indices `1..nmemb`, `at(i) = arr[lo+i-1]`) to
+ * restore heap order. Ported from the `CREATE` macro's loop body.
+ * @see apple-oss-distributions/Libc stdlib/FreeBSD/heapsort.c:CREATE
+ */
+function heapSiftDown<T>(
+  arr: T[], lo: number, nmemb: number, parI: number, cmp: (a: T, b: T) => number,
+): void {
+  const at = (i: number) => arr[lo + i - 1];
+  for (;;) {
+    let childI = parI * 2;
+    if (childI > nmemb) return;
+    if (childI < nmemb && cmp(at(childI), at(childI + 1)) < 0) childI++;
+    if (cmp(at(childI), at(parI)) <= 0) return;
+    const tmp = arr[lo + parI - 1];
+    arr[lo + parI - 1] = arr[lo + childI - 1];
+    arr[lo + childI - 1] = tmp;
+    parI = childI;
+  }
+}
+
+/**
+ * Remove the heap root (already saved by the caller into `k`) from the
+ * `nmemb`-element heap in `arr[lo .. lo+nmemb)`, then re-insert `k`. Ported
+ * from the `SELECT` macro: first follow the larger-child path down from the
+ * root copying child values up into their parent's slot (a "hole" moves
+ * down without full swaps), then walk the hole back up toward the root to
+ * find `k`'s resting place.
+ * @see apple-oss-distributions/Libc stdlib/FreeBSD/heapsort.c:SELECT
+ */
+function heapSelect<T>(
+  arr: T[], lo: number, nmemb: number, k: T, cmp: (a: T, b: T) => number,
+): void {
+  const at = (i: number) => arr[lo + i - 1];
+  let parI = 1;
+  let childI: number;
+  for (;;) {
+    childI = parI * 2;
+    if (childI > nmemb) break;
+    if (childI < nmemb && cmp(at(childI), at(childI + 1)) < 0) childI++;
+    arr[lo + parI - 1] = arr[lo + childI - 1];
+    parI = childI;
+  }
+  for (;;) {
+    childI = parI;
+    parI = childI >> 1;
+    if (childI === 1 || cmp(k, at(parI)) < 0) {
+      arr[lo + childI - 1] = k;
+      return;
+    }
+    arr[lo + childI - 1] = arr[lo + parI - 1];
+  }
+}
+
+/**
+ * BSD heapsort — the fallback Apple libc `_qsort` dispatches to when
+ * introsort's recursion-depth budget (`2*(fls(n)-1)`) is exhausted, guarding
+ * against adversarial inputs that defeat median-of-3 pivot selection. Not
+ * observed to trigger on this corpus (all inputs stay within budget), but
+ * CLAUDE.md requires porting every branch a faithful port can reach.
+ *
+ * @see apple-oss-distributions/Libc stdlib/FreeBSD/heapsort.c:heapsort
+ */
+export function heapSort<T>(arr: T[], lo: number, n: number, cmp: (a: T, b: T) => number): void {
+  if (n <= 1) return;
+  for (let l = n >> 1; l >= 1; l--) heapSiftDown(arr, lo, n, l, cmp);
+  for (let nmemb = n; nmemb > 1; nmemb--) {
+    const k = arr[lo + nmemb - 1];
+    arr[lo + nmemb - 1] = arr[lo];
+    heapSelect(arr, lo, nmemb - 1, k, cmp);
+  }
+}
+
+/** Sort `arr[lo .. lo+n)` in place (Apple Libc `_qsort` body, R4 prototype). */
+function qsortRange<T>(
+  arr: T[], lo: number, n: number, cmp: (x: T, y: T) => number, depthLimit: number,
+): void {
+  for (;;) {
+    if (depthLimit-- <= 0) {
+      // We've hit our recursion limit, switch to heapsort.
+      // @see apple-oss-distributions/Libc stdlib/FreeBSD/qsort.c (depth_limit check)
+      heapSort(arr, lo, n, cmp);
+      return;
+    }
+    if (n <= THRESH) { insertionSort(arr, lo, n, cmp); return; }
+    swap(arr, lo, choosePivot(arr, lo, n, cmp)); // pivot to front
+    const { pa, pb, pc, pd, swapped } = partition3(arr, lo, n, cmp);
+    const pn = lo + n;
+    let r = Math.min(pa - lo, pb - pa);
+    vecswap(arr, lo, pb - r, r);
+    r = Math.min(pd - pc, pn - pd - 1);
+    vecswap(arr, pb, pn - r, r);
+    // Apple: a swap-free partition pass means "nearly sorted" — try a bounded
+    // insertion sort over the whole range; bail back to quicksort (keeping the
+    // partial mutations!) once swaps exceed 1 + n/4.
+    if (!swapped) {
+      const limit = 1 + Math.floor(n / 4);
+      if (insertionSort(arr, lo, n, cmp, limit)) return;
+    }
+    const leftN = pb - pa;  // count of elements < pivot
+    const rightN = pd - pc; // count of elements > pivot
+    if (leftN <= rightN) {
+      if (leftN > 1) qsortRange(arr, lo, leftN, cmp, depthLimit);
+      if (rightN > 1) { lo = pn - rightN; n = rightN; continue; }
+    } else {
+      if (rightN > 1) qsortRange(arr, pn - rightN, rightN, cmp, depthLimit);
+      if (leftN > 1) { n = leftN; continue; }
+    }
+    return;
+  }
+}
+
+/**
+ * Sort `arr` in place, reproducing libc `qsort`'s permutation of
+ * comparator-equal elements (Bentley–McIlroy quicksort). Use this instead of
+ * `Array.prototype.sort` only where the C oracle's `qsort` tie ordering is
+ * load-bearing; elsewhere the stable native sort is preferred.
+ *
+ * @param arr Array sorted in place (also returned for convenience).
+ * @param cmp Comparator returning <0, 0, or >0 — matching the C comparator's
+ *   sign, including 0 for elements the C comparator treats as equal.
+ */
+export function gvQsort<T>(arr: T[], cmp: (a: T, b: T) => number): T[] {
+  // DEPTH(n) = 2 * (fls(n) - 1); fls(n) = 32 - clz32(n) for n > 0.
+  if (arr.length > 1) {
+    const depth = 2 * (32 - Math.clz32(arr.length) - 1);
+    qsortRange(arr, 0, arr.length, cmp, depth);
+  }
+  return arr;
+}

package/src/util/index.ts

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: EPL-2.0
+/**
+ * Public re-exports for src/util.
+ */
+export { AgBuffer } from "./agxbuf.js";
+export { List } from "./list.js";
+export { gvXmlEscape } from "./xml.js";
+export type { XmlFlags } from "./xml.js";
+export {
+  isExactlyZero,
+  isExactlyEqual,
+  fcmp,
+  imax,
+  imin,
+  d2i,
+  d2f,
+  gvStrtod,
+} from "./math.js";
+export {
+  rkNewState,
+  rkSeed,
+  rkRandom,
+  rkInterval,
+} from "./mt19937.js";
+export type { RkState } from "./mt19937.js";

package/src/util/list.ts

@@ -0,0 +1,122 @@
+// SPDX-License-Identifier: EPL-2.0
+/**
+ * Generic doubly-linked list, replacing the C LIST macro.
+ *
+ * The C LIST macro is a type-generic ring-buffer backed dynamic array.
+ * For the TypeScript port we expose the same logical API using a simple
+ * doubly-linked node structure. The ring-buffer internals need not be
+ * replicated; only the observable contract matters.
+ *
+ * @see lib/util/list.h
+ */
+
+interface ListNode<T> {
+  value: T;
+  prev: ListNode<T> | null;
+  next: ListNode<T> | null;
+}
+
+/**
+ * Type-generic doubly-linked list.
+ *
+ * Matches the observable behaviour of the C LIST macro:
+ *   push / pop  — operate on the back (LIST_APPEND / LIST_POP_BACK)
+ *   unshift / shift — operate on the front (LIST_PREPEND / LIST_POP_FRONT)
+ *   remove      — linear scan by identity (LIST_REMOVE)
+ *   Symbol.iterator — logical order, front to back
+ */
+export class List<T> {
+  private _head: ListNode<T> | null = null;
+  private _tail: ListNode<T> | null = null;
+  private _size: number = 0;
+
+  /** Append item to back. @see lib/util/list.h:LIST_APPEND */
+  push(item: T): void {
+    const node: ListNode<T> = { value: item, prev: this._tail, next: null };
+    if (this._tail !== null) {
+      this._tail.next = node;
+    } else {
+      this._head = node;
+    }
+    this._tail = node;
+    this._size++;
+  }
+
+  /** Remove and return the last item, or undefined if empty.
+   *  @see lib/util/list.h:LIST_POP_BACK */
+  pop(): T | undefined {
+    if (this._tail === null) return undefined;
+    const value = this._tail.value;
+    this._unlink(this._tail);
+    return value;
+  }
+
+  /** Remove and return the first item, or undefined if empty.
+   *  @see lib/util/list.h:LIST_POP_FRONT */
+  shift(): T | undefined {
+    if (this._head === null) return undefined;
+    const value = this._head.value;
+    this._unlink(this._head);
+    return value;
+  }
+
+  /** Prepend item to front. @see lib/util/list.h:LIST_PREPEND */
+  unshift(item: T): void {
+    const node: ListNode<T> = { value: item, prev: null, next: this._head };
+    if (this._head !== null) {
+      this._head.prev = node;
+    } else {
+      this._tail = node;
+    }
+    this._head = node;
+    this._size++;
+  }
+
+  /**
+   * Remove the first occurrence of item (by reference equality).
+   * Returns true if found and removed.
+   * @see lib/util/list.h:LIST_REMOVE
+   */
+  remove(item: T): boolean {
+    for (let n = this._head; n !== null; n = n.next) {
+      if (n.value === item) {
+        this._unlink(n);
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /** Iterate items in logical order (front to back). */
+  [Symbol.iterator](): Iterator<T> {
+    let current = this._head;
+    return {
+      next(): IteratorResult<T> {
+        if (current === null) return { value: undefined as unknown as T, done: true };
+        const value = current.value;
+        current = current.next;
+        return { value, done: false };
+      },
+    };
+  }
+
+  /** Number of items in the list. @see lib/util/list.h:LIST_SIZE */
+  get size(): number {
+    return this._size;
+  }
+
+  /** Detach a node from the list. */
+  private _unlink(node: ListNode<T>): void {
+    if (node.prev !== null) {
+      node.prev.next = node.next;
+    } else {
+      this._head = node.next;
+    }
+    if (node.next !== null) {
+      node.next.prev = node.prev;
+    } else {
+      this._tail = node.prev;
+    }
+    this._size--;
+  }
+}

package/src/util/math.ts

@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: EPL-2.0
+/**
+ * Arithmetic helper functions.
+ *
+ * @see lib/util/gv_math.h
+ */
+
+// INT32 limits used by d2i (mirrors C INT_MAX / INT_MIN for 32-bit int)
+const INT32_MAX = 2_147_483_647;
+const INT32_MIN = -2_147_483_648;
+
+// FLT_MAX: largest finite single-precision float
+const FLT_MAX = 3.4028234663852886e+38;
+
+/**
+ * Bit-exact zero check via DataView (mirrors C memcmp against 0).
+ * -0.0 returns false; +0.0 returns true.
+ *
+ * CRITICAL (AD-9): must use bit-level comparison, NOT === 0.
+ * @see lib/util/gv_math.h:is_exactly_zero
+ */
+export function isExactlyZero(v: number): boolean {
+  const buf = new ArrayBuffer(8);
+  new DataView(buf).setFloat64(0, v, false);
+  const bytes = new Uint8Array(buf);
+  return bytes.every((b) => b === 0);
+}
+
+/**
+ * Bit-exact equality via DataView (mirrors C memcmp).
+ * Distinguishes +0.0 from -0.0.
+ *
+ * CRITICAL (AD-9): must use bit-level comparison, NOT ===.
+ * @see lib/util/gv_math.h:is_exactly_equal
+ */
+export function isExactlyEqual(a: number, b: number): boolean {
+  const buf = new ArrayBuffer(16);
+  const dv = new DataView(buf);
+  dv.setFloat64(0, a, false);
+  dv.setFloat64(8, b, false);
+  const bytes = new Uint8Array(buf);
+  for (let i = 0; i < 8; i++) {
+    if (bytes[i] !== bytes[i + 8]) return false;
+  }
+  return true;
+}
+
+/**
+ * Three-way double comparator.
+ * Returns -1 if a<b, 0 if a==b, 1 if a>b (numerical, not bit-exact).
+ * @see lib/util/gv_math.h:fcmp
+ */
+export function fcmp(a: number, b: number): -1 | 0 | 1 {
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}
+
+/**
+ * Integer maximum.
+ * @see lib/util/gv_math.h:imax
+ */
+export function imax(a: number, b: number): number {
+  return a > b ? a : b;
+}
+
+/**
+ * Integer minimum.
+ * @see lib/util/gv_math.h:imin
+ */
+export function imin(a: number, b: number): number {
+  return a < b ? a : b;
+}
+
+/**
+ * Convert double to int32, clamping to [INT_MIN, INT_MAX].
+ * @see lib/util/gv_math.h:d2i
+ */
+export function d2i(v: number): number {
+  if (v > INT32_MAX) return INT32_MAX;
+  if (v < INT32_MIN) return INT32_MIN;
+  return Math.trunc(v);
+}
+
+/**
+ * Round-trip through Float32Array to get float32 precision,
+ * clamping to [-FLT_MAX, FLT_MAX].
+ * @see lib/util/gv_math.h:d2f
+ */
+export function d2f(v: number): number {
+  if (v > FLT_MAX) return FLT_MAX;
+  if (v < -FLT_MAX) return -FLT_MAX;
+  const f32 = new Float32Array(1);
+  f32[0] = v;
+  return f32[0];
+}
+
+/**
+ * Parse a string to a number. Returns NaN for non-numeric strings.
+ * Wraps parseFloat, matching C strtod behaviour for well-formed input.
+ */
+export function gvStrtod(s: string): number {
+  return parseFloat(s);
+}

package/src/util/mt19937.ts

@@ -0,0 +1,143 @@
+// SPDX-License-Identifier: EPL-2.0
+/**
+ * MT19937 Mersenne Twister — port of Random Kit 1.3.
+ *
+ * Must produce bit-identical output to the C reference for any seed.
+ * All arithmetic is kept in 32-bit unsigned space via >>> 0.
+ *
+ * @see lib/neatogen/randomkit.c
+ * @see lib/neatogen/randomkit.h
+ */
+
+/** Number of state words. @see randomkit.h:RK_STATE_LEN */
+const RK_STATE_LEN = 624;
+
+/** Twist constants. @see randomkit.c */
+const N = 624;
+const M = 397;
+const MATRIX_A = 0x9908b0df;
+const UPPER_MASK = 0x80000000;
+const LOWER_MASK = 0x7fffffff;
+
+/** Initialisation multiplier (Knuth PRNG). @see randomkit.c:rk_seed */
+const INIT_MULT = 1812433253;
+
+/**
+ * Mersenne Twister state.
+ * @see randomkit.h:rk_state_
+ */
+export interface RkState {
+  /** 624-element state array (uint32). */
+  mt: Uint32Array;
+  /** Current position in the state array; RK_STATE_LEN means "needs twist". */
+  mti: number;
+}
+
+/** Allocate a fresh, uninitialised state. */
+export function rkNewState(): RkState {
+  return { mt: new Uint32Array(RK_STATE_LEN), mti: RK_STATE_LEN };
+}
+
+/**
+ * Seed the RNG with a 32-bit unsigned integer.
+ * @see randomkit.c:rk_seed
+ */
+export function rkSeed(seed: number, state: RkState): void {
+  let s = (seed >>> 0) & 0xffffffff;
+  for (let pos = 0; pos < RK_STATE_LEN; pos++) {
+    state.mt[pos] = s;
+    s = rkSeedStep(s, pos);
+  }
+  state.mti = RK_STATE_LEN;
+}
+
+/**
+ * One step of Knuth's PRNG used during seeding.
+ * Kept separate to stay within CCN limit.
+ */
+function rkSeedStep(s: number, pos: number): number {
+  // (1812433253 * (s ^ (s >> 30)) + pos + 1) & 0xffffffff
+  const xor = (s ^ (s >>> 30)) >>> 0;
+  // multiply as 32-bit: split into hi/lo to avoid float precision loss
+  const lo = (INIT_MULT * (xor & 0xffff)) >>> 0;
+  const hi = (INIT_MULT * (xor >>> 16)) >>> 0;
+  return (lo + ((hi << 16) >>> 0) + pos + 1) >>> 0;
+}
+
+/**
+ * Generate the next 32-bit pseudo-random value.
+ * @see randomkit.c:rk_random
+ */
+export function rkRandom(state: RkState): number {
+  if (state.mti === RK_STATE_LEN) {
+    rkTwist(state);
+  }
+  let y = state.mt[state.mti++];
+  y = rkTemper(y);
+  return y >>> 0;
+}
+
+/**
+ * MT19937 twist operation — refill the state array.
+ * @see randomkit.c:rk_random (inner if block)
+ */
+function rkTwist(state: RkState): void {
+  const mt = state.mt;
+  let i = 0;
+  for (; i < N - M; i++) {
+    const y = ((mt[i] & UPPER_MASK) | (mt[i + 1] & LOWER_MASK)) >>> 0;
+    mt[i] = (mt[i + M] ^ (y >>> 1) ^ ((y & 1) * MATRIX_A)) >>> 0;
+  }
+  for (; i < N - 1; i++) {
+    const y = ((mt[i] & UPPER_MASK) | (mt[i + 1] & LOWER_MASK)) >>> 0;
+    mt[i] = (mt[i + (M - N)] ^ (y >>> 1) ^ ((y & 1) * MATRIX_A)) >>> 0;
+  }
+  const y = ((mt[N - 1] & UPPER_MASK) | (mt[0] & LOWER_MASK)) >>> 0;
+  mt[N - 1] = (mt[M - 1] ^ (y >>> 1) ^ ((y & 1) * MATRIX_A)) >>> 0;
+  state.mti = 0;
+}
+
+/**
+ * MT19937 tempering transformation.
+ * @see randomkit.c:rk_random (Tempering block)
+ */
+function rkTemper(y: number): number {
+  let v = y >>> 0;
+  v ^= v >>> 11;
+  v ^= (v << 7) & 0x9d2c5680;
+  v ^= (v << 15) & 0xefc60000;
+  v ^= v >>> 18;
+  return v >>> 0;
+}
+
+/**
+ * Return a random value in [0, max] inclusive.
+ * Uses rejection sampling to avoid modulo bias.
+ * On this platform ULONG_MAX == 0xffffffff (32-bit path).
+ *
+ * @see randomkit.c:rk_interval
+ */
+export function rkInterval(max: number, state: RkState): number {
+  const m = max >>> 0;
+  if (m === 0) return 0;
+  const mask = buildMask(m);
+  let value: number;
+  do {
+    value = (rkRandom(state) & mask) >>> 0;
+  } while (value > m);
+  return value;
+}
+
+/**
+ * Build the smallest all-ones bitmask >= max.
+ * @see randomkit.c:rk_interval (mask computation)
+ */
+function buildMask(max: number): number {
+  let mask = max >>> 0;
+  mask |= mask >>> 1;
+  mask |= mask >>> 2;
+  mask |= mask >>> 4;
+  mask |= mask >>> 8;
+  mask |= mask >>> 16;
+  return mask >>> 0;
+}