@forgeax/engine-runtime 0.1.2

package/src/systems/__tests__/_xorshift.ts

@@ -0,0 +1,83 @@
+// @forgeax/engine-runtime — deterministic 32-bit xorshift PRNG (M-4 / w26).
+//
+// Scope: M-4 transparent-sort.bench.ts (w27) needs reproducible 10k-entity
+// fixtures across runs / hosts / CI nodes. The vitest-bench iterations
+// repeatedly hash the same comparator path; a seeded PRNG turns the bench
+// number into a function of the algorithm rather than of the test data,
+// so a regression shows up as a clean delta in ns/op rather than noise.
+//
+// Why a hand-rolled xorshift instead of `seedrandom` (plan-strategy D-3):
+//   - zero new npm dep, zero lockfile drift, zero dependabot bun.lock
+//     parity churn
+//   - 32-bit xorshift is a 10-line industry-standard primitive
+//     (Marsaglia 2003); same deterministic guarantee for our use case
+//     (uniform-ish 32-bit ints feeding a JS-side floor / map)
+//   - bundle-size + bench gates stay pinned to the runtime surface that
+//     ships to AI users; a test-only helper that lives under `__tests__/`
+//     does not change either gate
+//
+// Algorithm (Marsaglia "Xorshift RNGs", 2003 §3, the 13/17/5 triplet):
+//   state := state XOR (state << 13)
+//   state := state XOR (state >>> 17)
+//   state := state XOR (state << 5)
+// The triplet (13, 17, 5) survives the BigCrush 32-bit suite for this
+// scope (uniform sampling of int32 ranges). Period 2^32 - 1; we only
+// need ~10^6 draws per bench iteration (10k entries x O(1) fields), so
+// the period is comfortably out of reach.
+//
+// charter mapping:
+//   F1 — JSDoc head + algorithm comment block keep the SSOT in the file
+//     header so future AI users see why this exists without a wiki round
+//     trip (charter "limited context" — the rationale lives inline)
+//   P3 — `seed === 0` is explicitly remapped (xorshift is a fixed point
+//     at 0, which would silently emit a constant 0 stream); the remap
+//     fails-loud at construction time rather than silently producing a
+//     degenerate sequence
+//
+// @new-surface — hand-rolled xorshift replaces the seedrandom dep
+//   (plan-strategy D-3); the helper lives under `__tests__/` so it never
+//   ships in the runtime bundle.
+// @derives — 32-bit xorshift industry-standard primitive (Marsaglia
+//   2003, "Xorshift RNGs", Journal of Statistical Software §3 triplet
+//   13/17/5).
+
+/**
+ * Deterministic 32-bit xorshift PRNG factory. Returns a closure that
+ * advances the internal state once per call and returns a uniform-ish
+ * `[0, 1)` float (the 32-bit state divided by `0x100000000`).
+ *
+ * Same seed -> same sequence on every host / runtime / Node version
+ * (the algorithm uses only 32-bit bitwise ops and Math-free arithmetic).
+ *
+ * @param seed - Initial 32-bit state. Defaults to `0xCAFE2026` (plan-
+ *   strategy D-3 SSOT). `seed === 0` is remapped to `1` because xorshift
+ *   is a fixed point at 0 (would emit a constant `0` stream forever);
+ *   the remap is the smallest deterministic perturbation that preserves
+ *   the period.
+ * @returns A `() => number` closure; each call returns one `[0, 1)`
+ *   sample and advances the internal state.
+ *
+ * @example deterministic bench fixture (w27 / transparent-sort.bench.ts)
+ *   const rng = createXorshift32(0xCAFE2026);
+ *   const layer = Math.floor(rng() * 2000) - 1000;  // [-1000, 1000]
+ *   const posY  = rng() * 100;                       // [0, 100)
+ *
+ * @example reproducibility check
+ *   const a = createXorshift32(42);
+ *   const b = createXorshift32(42);
+ *   a() === b();  // true — pure function of seed
+ */
+export function createXorshift32(seed = 0xcafe2026): () => number {
+  // `| 0` coerces to int32; the algorithm is defined over int32. The
+  // remap of seed=0 keeps the period definition (2^32 - 1) honest:
+  // xorshift's only degenerate fixed point is at 0.
+  let state = (seed | 0) === 0 ? 1 : seed | 0;
+  return (): number => {
+    state ^= state << 13;
+    state ^= state >>> 17;
+    state ^= state << 5;
+    // `>>> 0` reinterprets the int32 as a uint32 (0 .. 2^32 - 1);
+    // dividing by `0x100000000` (2^32) lands the result in [0, 1).
+    return (state >>> 0) / 0x100000000;
+  };
+}

package/src/systems/__tests__/argsort-in-place.test.ts

@@ -0,0 +1,155 @@
+// argsortInPlace unit tests (feat-20260608-tilemap-object-layer-rendering
+// M3 / m3-t1). The named export will land in m3-t2; until then every
+// import below resolves to `undefined` and the suite is red.
+//
+// Spec (plan-strategy §D-3 + reference backup commit 31d96d75):
+//   `argsortInPlace(keys: Float64Array, indices: Int32Array): void` reorders
+//   `indices` in place so that `keys[indices[i]]` is non-decreasing. The key
+//   array is treated as immutable; only `indices` is mutated. The sort is:
+//
+//     - stable (equal-key entries preserve their original `indices` order),
+//     - NaN-safe (NaN keys land at the tail in stable order),
+//     - IEEE-754 unsigned-monotonic encoded so `+0` and `-0` compare equal,
+//     - zero-allocation per call (module-scoped scratch buffers grow on
+//       demand; AC-17 budget is a separate bench, not this suite),
+//     - safe at the empty / single-entry boundaries.
+//
+// Charter mapping: P3 (NaN / out-of-range entries deterministic, no silent
+// throws) + P4 (single sort primitive shared with the sprite bucket via
+// `transparent-sort.ts`).
+
+import { describe, expect, it } from 'vitest';
+import { argsortInPlace } from '../transparent-sort';
+
+describe('argsortInPlace - 11-bit radix LSD over IEEE-754 unsigned-monotonic', () => {
+  it('basic ascending: distinct positive keys land in ascending key order', () => {
+    const keys = new Float64Array([3.1, 1.2, 2.7, 0.5, 9.0]);
+    const indices = new Int32Array([0, 1, 2, 3, 4]);
+
+    argsortInPlace(keys, indices);
+
+    expect(Array.from(indices)).toEqual([3, 1, 2, 0, 4]);
+  });
+
+  it('all-equal keys: stable sort preserves the original index order', () => {
+    const keys = new Float64Array([5, 5, 5, 5, 5]);
+    const indices = new Int32Array([0, 1, 2, 3, 4]);
+
+    argsortInPlace(keys, indices);
+
+    expect(Array.from(indices)).toEqual([0, 1, 2, 3, 4]);
+  });
+
+  it('negative + zero + positive: IEEE-754 unsigned-monotonic sorts correctly', () => {
+    const keys = new Float64Array([-3.5, 0, 2.1, -1.0, 7.2, -0.0]);
+    const indices = new Int32Array([0, 1, 2, 3, 4, 5]);
+
+    argsortInPlace(keys, indices);
+
+    // -3.5, -1.0, 0/-0 (stable -> [1, 5]), 2.1, 7.2
+    expect(Array.from(indices)).toEqual([0, 3, 1, 5, 2, 4]);
+  });
+
+  it('-0 and +0 are equal under the unsigned-monotonic encoding (stable tie)', () => {
+    const keys = new Float64Array([0, -0, 0, -0]);
+    const indices = new Int32Array([0, 1, 2, 3]);
+
+    argsortInPlace(keys, indices);
+
+    expect(Array.from(indices)).toEqual([0, 1, 2, 3]);
+  });
+
+  it('NaN keys land at the tail in stable order', () => {
+    const keys = new Float64Array([2, Number.NaN, 0, Number.NaN, -1]);
+    const indices = new Int32Array([0, 1, 2, 3, 4]);
+
+    argsortInPlace(keys, indices);
+
+    expect(indices[0]).toBe(4);
+    expect(indices[1]).toBe(2);
+    expect(indices[2]).toBe(0);
+    expect(indices[3]).toBe(1);
+    expect(indices[4]).toBe(3);
+  });
+
+  it('n=0: no-op, returns immediately without throwing', () => {
+    const keys = new Float64Array(0);
+    const indices = new Int32Array(0);
+
+    expect(() => argsortInPlace(keys, indices)).not.toThrow();
+    expect(indices.length).toBe(0);
+  });
+
+  it('n=1: no-op, single-entry indices unchanged', () => {
+    const keys = new Float64Array([42]);
+    const indices = new Int32Array([0]);
+
+    argsortInPlace(keys, indices);
+
+    expect(Array.from(indices)).toEqual([0]);
+  });
+
+  it('mutates indices in place, does not reallocate the caller buffer', () => {
+    const keys = new Float64Array([5, 2, 9, 1]);
+    const indices = new Int32Array([0, 1, 2, 3]);
+    const indicesBuffer = indices.buffer;
+    const indicesByteLength = indices.byteLength;
+
+    argsortInPlace(keys, indices);
+
+    expect(indices.buffer).toBe(indicesBuffer);
+    expect(indices.byteLength).toBe(indicesByteLength);
+    expect(Array.from(indices)).toEqual([3, 1, 0, 2]);
+  });
+
+  it('does not mutate the keys input', () => {
+    const keys = new Float64Array([3, 1, 2]);
+    const original = Array.from(keys);
+    const indices = new Int32Array([0, 1, 2]);
+
+    argsortInPlace(keys, indices);
+
+    expect(Array.from(keys)).toEqual(original);
+  });
+
+  it('large N (5000): radix LSD result equals comparator-based reference', () => {
+    const n = 5000;
+    const keys = new Float64Array(n);
+    const indices = new Int32Array(n);
+    let seed = 1337;
+    const next = (): number => {
+      seed = (seed * 1664525 + 1013904223) | 0;
+      return ((seed >>> 0) / 0xffffffff) * 200 - 100;
+    };
+    for (let i = 0; i < n; i++) {
+      keys[i] = next();
+      indices[i] = i;
+    }
+
+    const referenceIndices = Array.from(indices).sort((a, b) => {
+      const ka = keys[a] as number;
+      const kb = keys[b] as number;
+      if (ka < kb) return -1;
+      if (ka > kb) return 1;
+      return a - b;
+    });
+
+    argsortInPlace(keys, indices);
+
+    expect(Array.from(indices)).toEqual(referenceIndices);
+  });
+
+  it('subarray slice as indices: sorts only the visible window', () => {
+    const keys = new Float64Array([10, 20, 5, 15, 30]);
+    const buffer = new Int32Array([0, 1, 2, 3, 4]);
+    const window = buffer.subarray(1, 4); // entries 1, 2, 3 (keys 20, 5, 15)
+
+    argsortInPlace(keys, window);
+
+    // Original entries by key ascending: 5 (->2), 15 (->3), 20 (->1)
+    expect(Array.from(window)).toEqual([2, 3, 1]);
+    // Outside-window slots untouched.
+    expect(buffer[0]).toBe(0);
+    expect(buffer[4]).toBe(4);
+  });
+});

package/src/systems/__tests__/transparent-sort.bench.ts

@@ -0,0 +1,218 @@
+// transparent-sort.bench.ts -- transparent-bucket sort 10k-entity p95 gate
+// (feat-20260520-2d-sprite-layer-mvp / M-4 / w27; AC-14).
+//
+// Scope (3 cases x 100 iterations each):
+//   - mode=0 layer-z   (horizontal side-scroller; sortValue = posZ)
+//   - mode=1 layer-y   (JRPG Y-sort foot pivot; sortValue = -(posY - pivotY * sizeY))
+//   - mode=2 layer-yz  (Don't-Starve / isometric blend;
+//                        sortValue = (posY - pivotY * sizeY) + yzAlpha * posZ)
+//
+// AC-14 contract (3 reproducibility anchors):
+//   1. deterministic seed via `createXorshift32(0xCAFE2026)` so the
+//      bench number is a function of the algorithm, not the test data
+//      (w26 + plan-strategy D-3 SSOT, zero npm dep).
+//   2. >= 100 iterations -> tinybench reports a stable p95 across the
+//      whole sample window; `BENCH_OPTS_RUNTIME` pins iterations: 100
+//      so KUBEELA_BENCH=fast does not silently shrink the sample below
+//      the AC floor.
+//   3. Working baseline (implementation phase, R1 F-2 audit trail):
+//      p95 ~ 3 ms / 10k entities on GitHub Actions ubuntu-latest 6 vCPU.
+//      Root cause is V8 closure overhead in Array.prototype.sort + JS
+//      comparator (10k * log2(10k) ~ 140k comparator invocations per
+//      iteration; each crosses the JS<->C++ bridge ~ 20-30 ns).
+//      package.json forgeax.metrics.bench.baseline.threshold = 5 ms
+//      (5_000_000 ns/op) tracks this working baseline.
+//
+//      plan-strategy §2 D-3's 0.5 ms p95 target is DEFERRED to
+//      `feat-future-transparent-sort-radix` (todos.json todo-140).
+//      The future algorithm rewrite (composite-key BigInt64Array.sort
+//      over `(layer << 32) | (sortValueQuantizedInt32 ^ 0x80000000)`,
+//      or a radix sort over the same packed int64) replaces the JS
+//      comparator with a typed-array sort that stays inside C++ and
+//      should clear the 0.5 ms bar. Until that lands, the bench guards
+//      the 5 ms working ceiling — a regression past 5 ms still fails
+//      `pnpm metrics:run` and surfaces a real perf cliff.
+//
+//      Closed-loop trail: ImplementReviewer R1 F-2 (judged "defer +
+//      todo + JSDoc audit trail") in
+//      `.forgeax-harness/forgeax-loop/feat-20260520-2d-sprite-layer-
+//      mvp/implement-review.md` §5 closes here.
+//
+// Fixture shape (10k entries; structurally identical to a real M-4 record
+// stage transparent bucket but with synthetic numbers):
+//   - layer    ~ uniform i32 in [-1000, 1000]
+//   - posX/Y/Z ~ uniform f64 in [0, 100)
+//   - pivotY   ~ uniform f64 in [0, 1]   (matches SpriteMaterialAsset.pivot[1] range)
+//   - sizeY    ~ uniform f64 in [0.5, 2] (matches world-scale-ish sprites)
+//   - sortKey  -- undefined for the base bench; the AC-14 measurement
+//                 does NOT inject overrides because the comparator must
+//                 evaluate the mode formula for every entry to measure
+//                 the worst case.
+//
+// Anchor: requirements §3 AC-14 + plan-strategy §2 D-3 / §5.4 verdict
+// gate / §7 M-4 acceptanceCheck. The active threshold SSOT lives in
+// packages/runtime/package.json#forgeax.metrics.bench.baseline.threshold
+// (5_000_000 ns/op working baseline; R1 F-2 defer note above).
+
+import { World } from '@forgeax/engine-ecs';
+import {
+  setTransparentSortConfig,
+  TRANSPARENT_SORT_MODE_LAYER_Y,
+  TRANSPARENT_SORT_MODE_LAYER_YZ,
+  TRANSPARENT_SORT_MODE_LAYER_Z,
+} from '@forgeax/engine-render/internal';
+import { bench, describe } from 'vitest';
+import type { TransparentEntry } from '../transparent-sort';
+import { transparentSortEntries } from '../transparent-sort';
+import { createXorshift32 } from './_xorshift';
+
+// AC-14 sample size + iterations (plan-strategy D-3 SSOT). Vitest 4.x
+// forwards `iterations` straight to tinybench so the p95 statistic is
+// computed from a >= 100-sample window.
+const N_ENTITIES = 10_000;
+const BENCH_OPTS_RUNTIME = { iterations: 100 } as const;
+
+// Build the synthetic fixture once outside the bench body so allocation
+// cost stays out of the comparator-loop hot path (the math bench files
+// use the same closure pattern via vec3.create(...) above the bench
+// block). The same fixture is shared across all 3 mode benches so a
+// regression in one mode is directly comparable to the others.
+function buildEntries(): readonly TransparentEntry[] {
+  const rng = createXorshift32(0xcafe2026);
+  const out: TransparentEntry[] = new Array(N_ENTITIES);
+  for (let i = 0; i < N_ENTITIES; i++) {
+    const layer = Math.floor(rng() * 2001) - 1000;
+    out[i] = {
+      entityIndex: i,
+      materialHandle: 1024 + (i % 256),
+      layer,
+      posX: rng() * 100,
+      posY: rng() * 100,
+      posZ: rng() * 100,
+      pivotY: rng(),
+      sizeY: 0.5 + rng() * 1.5,
+    };
+  }
+  return out;
+}
+
+const ENTRIES = buildEntries();
+
+// Separate RNG for the mode=3 bench so the camera position does not
+// consume entropy from the entry pool. A second entries fixture with
+// a different seed avoids JIT-coupling the mode=3 bench noise to the
+// mode=0/1/2 bench noise.
+function buildEntriesDist(): readonly TransparentEntry[] {
+  const rng = createXorshift32(0x2dda7a6e);
+  const out: TransparentEntry[] = new Array(N_ENTITIES);
+  for (let i = 0; i < N_ENTITIES; i++) {
+    const layer = Math.floor(rng() * 2001) - 1000;
+    out[i] = {
+      entityIndex: i,
+      materialHandle: 1024 + (i % 256),
+      layer,
+      posX: rng() * 100,
+      posY: rng() * 100,
+      posZ: rng() * 100,
+      pivotY: rng(),
+      sizeY: 0.5 + rng() * 1.5,
+    };
+  }
+  return out;
+}
+
+const ENTRIES_DIST = buildEntriesDist();
+
+// independent RNG for per-iteration camera positions
+const rngDist = createXorshift32(0x9a88_e5b3);
+
+function makeWorld(mode: number): World {
+  const world = new World();
+  const r = setTransparentSortConfig(world, { mode, yzAlpha: 1.0 });
+  if (!r.ok) {
+    // Should be unreachable -- the three constants are by construction
+    // members of the valid {0, 1, 2} set. If this fires the fixture
+    // setup is broken at the harness level; bail loudly so a bench
+    // regression report is not silently meaningless.
+    throw new Error(`[transparent-sort.bench] setTransparentSortConfig failed: ${r.error.code}`);
+  }
+  return world;
+}
+
+describe('transparent-sort 10k entities', () => {
+  const worldZ = makeWorld(TRANSPARENT_SORT_MODE_LAYER_Z);
+  const worldY = makeWorld(TRANSPARENT_SORT_MODE_LAYER_Y);
+  const worldYZ = makeWorld(TRANSPARENT_SORT_MODE_LAYER_YZ);
+  const worldDist = makeWorld(3);
+  // Sink pattern (wiki/vitest-bench section 7.1): forces JIT to keep the
+  // sort result reachable; an unread return value is a dead-store
+  // candidate and the optimiser may then short-circuit the comparator
+  // visits inside Array.prototype.sort. The `_sink` prefix tags it
+  // explicitly as "write-only inside the loop, read once at teardown"
+  // so biome's noUnusedVariables rule does not flag it (we DO read it
+  // once below to satisfy lint + keep V8 from dead-storing).
+  let _sink = 0;
+
+  bench(
+    'mode=0 layer-z (horizontal)',
+    () => {
+      const out = transparentSortEntries(ENTRIES, worldZ);
+      // `?.entityIndex ?? 0` keeps the read total under
+      // noUncheckedIndexedAccess; `| 0` is the canonical int32 sink.
+      _sink ^= (out[0]?.entityIndex ?? 0) | 0;
+    },
+    BENCH_OPTS_RUNTIME,
+  );
+
+  bench(
+    'mode=1 layer-y (JRPG)',
+    () => {
+      const out = transparentSortEntries(ENTRIES, worldY);
+      _sink ^= (out[0]?.entityIndex ?? 0) | 0;
+    },
+    BENCH_OPTS_RUNTIME,
+  );
+
+  bench(
+    "mode=2 layer-yz (isometric / Don't-Starve)",
+    () => {
+      const out = transparentSortEntries(ENTRIES, worldYZ);
+      _sink ^= (out[0]?.entityIndex ?? 0) | 0;
+    },
+    BENCH_OPTS_RUNTIME,
+  );
+
+  // ─── w3: mode=3 distance bench (TDD red phase) ─────────────────────
+
+  // Red: setTransparentSortConfig rejects mode=3 (not yet in VALID_MODES).
+  // When green, the extra cost of 3 squared-distance ops per entry should
+  // add <0.05ms vs the ~3ms p95 baseline on 10k entries (research E4(c)).
+
+  bench(
+    'mode=3 distance (back-to-front squared-distance)',
+    () => {
+      const cameraPos: readonly [number, number, number] = [
+        rngDist() * 100,
+        rngDist() * 100,
+        rngDist() * 100,
+      ];
+      // Red: 3-arg signature does not exist yet; cast bridges the red gap.
+      const out = (
+        transparentSortEntries as (
+          entries: readonly TransparentEntry[],
+          world: World,
+          cameraPos?: readonly [number, number, number],
+        ) => readonly TransparentEntry[]
+      )(ENTRIES_DIST, worldDist, cameraPos);
+      _sink ^= (out[0]?.entityIndex ?? 0) | 0;
+    },
+    BENCH_OPTS_RUNTIME,
+  );
+
+  // Single teardown-time read keeps `_sink` from being a strict
+  // write-only target (lint + JIT both observe the value); the read
+  // path lives inside an arrow predicate so tinybench's harness
+  // never invokes it during the measurement window. Sink pattern
+  // (wiki/vitest-bench section 7.1).
+  void [() => _sink];
+});