@series-inc/rundot-syncplay 5.26.0-beta.2 → 5.26.0-beta.3

package/core/native/mobile/syncplay_native_probe_abi.h

@@ -0,0 +1,41 @@
+#pragma once
+
+#include <stdint.h>
+
+#define RUNDOT_SYNCPLAY_NATIVE_PROBE_ABI_VERSION 1u
+#define RUNDOT_SYNCPLAY_NATIVE_PROBE_SCENARIO_BOX3D_V1 1u
+
+#define RUNDOT_SYNCPLAY_NATIVE_PROBE_STATUS_OK 0
+#define RUNDOT_SYNCPLAY_NATIVE_PROBE_STATUS_INVALID_ARGUMENT (-1)
+#define RUNDOT_SYNCPLAY_NATIVE_PROBE_STATUS_UNSUPPORTED_ABI (-2)
+#define RUNDOT_SYNCPLAY_NATIVE_PROBE_STATUS_UNSUPPORTED_SCENARIO (-3)
+#define RUNDOT_SYNCPLAY_NATIVE_PROBE_STATUS_INVALID_FRAMES (-4)
+#define RUNDOT_SYNCPLAY_NATIVE_PROBE_STATUS_BUSY (-5)
+#define RUNDOT_SYNCPLAY_NATIVE_PROBE_STATUS_STEP_FAILED (-6)
+#define RUNDOT_SYNCPLAY_NATIVE_PROBE_STATUS_INTERNAL (-7)
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef struct {
+  uint32_t abi_version;
+  uint32_t scenario_id;
+  uint32_t frames;
+} RundotSyncplayNativeProbeInput;
+
+typedef struct {
+  uint32_t abi_version;
+  int32_t status;
+  uint32_t completed_frames;
+  uint64_t elapsed_ns;
+  uint64_t final_checksum;
+} RundotSyncplayNativeProbeOutput;
+
+int32_t rundot_syncplay_native_probe_run(
+    const RundotSyncplayNativeProbeInput* input,
+    RundotSyncplayNativeProbeOutput* output);
+
+#ifdef __cplusplus
+}
+#endif

package/core/physics.d.ts

@@ -281,6 +281,13 @@ export interface KinetixPhysicsStepResult {
   readonly postPhysicsScheduledQueryResults: readonly { readonly id: string; readonly hits: readonly KinetixPhysicsHit[] }[];
   readonly broadphasePairs: number;
   readonly narrowphaseContacts: number;
+  /**
+   * Contacts the solver reported this step, read from its exported count rather
+   * than derived from `world.contactCache`. Watch it against
+   * `PHYSICS_CONTACT_TELEMETRY_CAP` for budget headroom before saturation
+   * becomes `KINETIX_PHYSICS_CONTACT_TELEMETRY_SATURATED`.
+   */
+  readonly contactTelemetryCount: number;
   readonly solverCorrections: number;
   readonly checksum: string;
 }
@@ -300,6 +307,47 @@ export interface KinetixPhysicsRecording {
   readonly finalChecksum: string;
 }
 
+/**
+ * Maximum flat geometry elements permitted on a single shape. A tripwire
+ * against obviously-wrong input, not a performance target — see
+ * SYNCPLAY-PHYSICS.md for the practical per-step budget, which is far lower.
+ * Exceeding it fails with `KINETIX_PHYSICS_SHAPE_GEOMETRY_TOO_LARGE <id> <n>`.
+ */
+export const PHYSICS_MAX_SHAPE_GEOMETRY_ELEMENTS: number;
+
+/**
+ * Contacts past this count are silently discarded by the C++ core, so the
+ * exported contact count saturates here and the bridge raises
+ * `KINETIX_PHYSICS_CONTACT_TELEMETRY_SATURATED` rather than returning a
+ * truncated cache.
+ */
+export const PHYSICS_CONTACT_TELEMETRY_CAP: number;
+
+export interface KinetixPhysicsContactBudget {
+  readonly limit: number;
+  readonly onOverflow: string;
+  readonly signal: string | null;
+}
+
+/** Post-step contact semantics, published for other runtimes of this core. */
+export interface KinetixPhysicsContactContract {
+  readonly entry: readonly string[];
+  readonly ordering: string;
+  readonly authority: {
+    readonly solid: 'cpp-telemetry';
+    readonly triggerOrSensor: 'js-detect-contacts';
+    readonly note: string;
+  };
+  readonly warmStart: string;
+  readonly budgets: {
+    readonly contactTelemetry: KinetixPhysicsContactBudget;
+    readonly broadphasePairs: KinetixPhysicsContactBudget;
+  };
+  readonly errors: readonly string[];
+}
+
+export const PHYSICS_CONTACT_CONTRACT: KinetixPhysicsContactContract;
+
 export function initPhysics(): Promise<void>;
 export function physicsReady(): boolean;
 export const physicsWasmMetadata: Readonly<{

package/core/scripts/build-mobile-native.mjs

@@ -0,0 +1,99 @@
+// Declares the exact portable C++ closure consumed by the standalone mobile
+// probe. This script is intentionally a manifest builder, not a native build
+// system: Xcode/CMake owns platform linking, while this list keeps both
+// bindings on the same reviewed source bytes.
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = resolve(fileURLToPath(new URL('../..', import.meta.url)));
+const nativeRoot = join(packageRoot, 'core', 'native');
+
+export const MOBILE_NATIVE_FILES = Object.freeze([
+  'mobile/syncplay_native_probe_abi.h',
+  'mobile/syncplay_native_probe.cpp',
+  'mobile/box3d_probe_scenario.hpp',
+  'mobile/box3d_probe_scenario.cpp',
+  'physics/physics.hpp',
+  'physics/physics.cpp',
+  'physics/abi.hpp',
+  'physics/abi.cpp',
+  'deterministic_math.hpp',
+  'deterministic_math.cpp',
+]);
+
+const sourceExtensions = new Set(['.cpp', '.hpp', '.h']);
+
+function fileDigest(bytes) {
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+function buildManifest() {
+  const files = MOBILE_NATIVE_FILES.map((relativePath) => {
+    if (relativePath.includes('..') || relativePath.startsWith('/')) {
+      throw new Error(`SYNCPLAY_MOBILE_NATIVE_PATH_INVALID ${relativePath}`);
+    }
+    const absolutePath = join(nativeRoot, relativePath);
+    if (!existsSync(absolutePath)) throw new Error(`SYNCPLAY_MOBILE_NATIVE_FILE_MISSING ${relativePath}`);
+    const bytes = readFileSync(absolutePath);
+    const extension = relativePath.slice(relativePath.lastIndexOf('.'));
+    if (!sourceExtensions.has(extension)) throw new Error(`SYNCPLAY_MOBILE_NATIVE_FILE_TYPE_INVALID ${relativePath}`);
+    return {
+      path: `core/native/${relativePath}`,
+      byteLength: bytes.byteLength,
+      sha256: fileDigest(bytes),
+    };
+  });
+  const hash = createHash('sha256');
+  for (const file of files) {
+    hash.update(file.path);
+    hash.update('\0');
+    hash.update(file.sha256);
+    hash.update('\0');
+  }
+  return {
+    schemaVersion: 1,
+    package: '@series-inc/rundot-syncplay',
+    sourceRoot: 'core/native',
+    files,
+    sourceDigest: hash.digest('hex'),
+  };
+}
+
+export function getMobileNativeSourceManifest() {
+  return buildManifest();
+}
+
+export function getMobileNativeSourcePaths() {
+  return MOBILE_NATIVE_FILES.map((relativePath) => join(nativeRoot, relativePath));
+}
+
+export function writeMobileNativeSourceManifest(outputPath) {
+  const manifest = buildManifest();
+  mkdirSync(dirname(outputPath), { recursive: true });
+  writeFileSync(outputPath, `${JSON.stringify(manifest, null, 2)}\n`);
+  return manifest;
+}
+
+function argumentValue(name) {
+  const index = process.argv.indexOf(name);
+  return index === -1 ? undefined : process.argv[index + 1];
+}
+
+function invokedDirectly() {
+  const entrypoint = process.argv[1];
+  if (!entrypoint) return false;
+  return resolve(entrypoint) === resolve(fileURLToPath(import.meta.url));
+}
+
+if (invokedDirectly()) {
+  const manifest = buildManifest();
+  const outputPath = argumentValue('--manifest');
+  if (outputPath) writeMobileNativeSourceManifest(resolve(outputPath));
+  if (process.argv.includes('--check')) {
+    console.log(`SYNCPLAY_MOBILE_NATIVE_SOURCE_OK digest=${manifest.sourceDigest}`);
+  } else {
+    console.log(JSON.stringify(manifest, null, 2));
+  }
+}

package/core/scripts/build-native.mjs

@@ -14,11 +14,25 @@ const SOURCES = [
   'kinetix-render-projection.cpp',
   'component_runtime.cpp',
   'deterministic_math.cpp',
+  'fixed_math.cpp',
   'physics/physics.cpp',
   'physics/abi.cpp',
+  'mobile/box3d_probe_scenario.cpp',
   'kinetix-native-main.cpp',
 ];
 
+// Headers are compiled into the binary too, but were never fingerprinted: a
+// header-only edit reused a stale cached binary, so the parity gates below
+// would have tested the wrong thing.
+const FINGERPRINT_FILES = [
+  ...SOURCES,
+  'mobile/box3d_probe_scenario.hpp',
+  'fixed_math.hpp',
+  'deterministic_math.hpp',
+  'physics/physics.hpp',
+  'physics/abi.hpp',
+];
+
 // -ffp-contract=off is load-bearing, not stylistic: it forbids the compiler from
 // fusing a*b+c into an FMA, which would change f64 results and break JS<->C++
 // determinism. Do not drop it when adding a compiler.
@@ -48,7 +62,7 @@ function buildFingerprint(compiler, version) {
   hash.update(version);
   hash.update('\0');
   hash.update(FLAGS.join(' '));
-  for (const source of SOURCES) {
+  for (const source of FINGERPRINT_FILES) {
     hash.update('\0');
     hash.update(source);
     hash.update(readFileSync(join(root, 'native', source)));

package/core/scripts/build-wasm-fixed-math.mjs

@@ -0,0 +1,58 @@
+// Mirrors build-native.mjs: probe, pin flags, fingerprint inputs, cache under
+// core/build/. Nothing is committed, so there is no drift gate to maintain.
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const root = join(import.meta.dirname, '..');
+const outDir = join(root, 'build');
+
+const SOURCES = [
+  join(root, 'bench', 'fixed-math-wasm.cpp'),
+  join(root, 'native', 'fixed_math.cpp'),
+];
+const FINGERPRINT_FILES = [...SOURCES, join(root, 'native', 'fixed_math.hpp')];
+
+// -ffp-contract=off is load-bearing for determinism. -flto is load-bearing for
+// speed: without it the kernel cannot inline across the shim boundary and the
+// lane measures roughly 2x slower for no semantic reason.
+const FLAGS = ['-std=c++20', '-O3', '-flto', '-ffp-contract=off'];
+
+function emccVersion() {
+  const probe = spawnSync('emcc', ['--version'], { encoding: 'utf8' });
+  return probe.status === 0 ? (probe.stdout ?? '') : null;
+}
+
+export function fixedMathWasmAvailable() {
+  return emccVersion() !== null;
+}
+
+export function buildFixedMathWasm() {
+  const version = emccVersion();
+  if (version === null) throw new Error('KINETIX_BENCH_NO_EMCC');
+
+  const hash = createHash('sha256');
+  hash.update(FLAGS.join(' '));
+  hash.update('\0');
+  hash.update(version);
+  for (const file of FINGERPRINT_FILES) {
+    hash.update('\0');
+    hash.update(readFileSync(file));
+  }
+  const output = join(outDir, `fixed-math-${hash.digest('hex').slice(0, 16)}.wasm`);
+  if (existsSync(output)) return output;
+
+  mkdirSync(outDir, { recursive: true });
+  const build = spawnSync('emcc', [
+    ...FLAGS,
+    `-I${join(root, 'native')}`,
+    ...SOURCES,
+    '--no-entry',
+    '-sSTANDALONE_WASM=1',
+    '-sEXPORTED_FUNCTIONS=["_bench_fixed_kernel"]',
+    '-o', output,
+  ], { encoding: 'utf8' });
+  if (build.status !== 0) throw new Error(`KINETIX_BENCH_WASM_BUILD_FAILED ${build.stderr}`);
+  return output;
+}

package/core/scripts/run-box3d-benchmark.mjs

@@ -7,6 +7,14 @@ import { performance } from 'node:perf_hooks';
 import { buildNative } from './build-native.mjs';
 import { createPhysicsWorld, initPhysics, stepPhysicsWorld } from '../src/physics/index.mjs';
 import { physicsWasmModuleBase64 } from '../src/physics/physics-wasm-module.generated.mjs';
+import {
+  benchmarkBodyOrder as probeBenchmarkBodyOrder,
+  bridgeBodyFields as probeBridgeBodyFields,
+  BOX3D_PROBE_STEP_OPTIONS,
+  commonBodyFields as probeCommonBodyFields,
+  hashFloat32Values as probeHashFloat32Values,
+  makeBodies as probeMakeBodies,
+} from '../src/physics/box3d-probe.mjs';
 
 const packageRoot = resolve(import.meta.dirname, '..');
 const benchmarkSource = join(packageRoot, 'bench', 'box3d-benchmark.c');
@@ -88,15 +96,7 @@ function hashFloat64Values(values) {
 }
 
 function hashFloat32Values(values) {
-  const view = new DataView(new ArrayBuffer(Float32Array.BYTES_PER_ELEMENT));
-  let hash = 1469598103934665603n;
-  const prime = 1099511628211n;
-  for (const value of values) {
-    view.setFloat32(0, value, true);
-    hash ^= BigInt(view.getUint32(0, true));
-    hash = BigInt.asUintN(64, hash * prime);
-  }
-  return hash.toString(16).padStart(16, '0');
+  return probeHashFloat32Values(values);
 }
 
 function parseBenchmarkOutput(output, label) {
@@ -134,99 +134,19 @@ function summarizeSamples(samples, label) {
 }
 
 function makeBodies(bodyCount) {
-  const bodies = [{
-    id: 'floor',
-    kind: 'static',
-    x: 0,
-    y: -32.5,
-    z: 0,
-    vx: 0,
-    vy: 0,
-    vz: 0,
-    linearDamping: 1,
-    angularDamping: 1,
-    shape: { type: 'sphere', radius: 32.5 },
-    layer: 1,
-    mask: 1,
-  }];
-  for (let index = 1; index < bodyCount; index += 1) {
-    const column = (index - 1) % 16;
-    const row = Math.floor((index - 1) / 16);
-    bodies.push({
-      id: `body-${String(index).padStart(6, '0')}`,
-      kind: 'dynamic',
-      x: column * 1.05 - 7.875,
-      y: 0.5 + row * 1.05,
-      z: 0,
-      vx: column % 2 === 0 ? 0.1 : -0.1,
-      vy: 0,
-      vz: 0,
-      linearDamping: 1,
-      angularDamping: 1,
-      // Match the Box3D harness (density=1.0, solid sphere r=0.5): mass = pi/6,
-      // isotropic inertia = 0.1*mass. Math.PI/6 rounds to the identical double as
-      // the native scene's pi/6, so all Kinetix lanes stay bit-identical.
-      mass: Math.PI / 6,
-      inertia: { xx: 0.1 * (Math.PI / 6), yy: 0.1 * (Math.PI / 6), zz: 0.1 * (Math.PI / 6) },
-      shape: { type: 'sphere', radius: 0.5 },
-      layer: 1,
-      mask: 1,
-    });
-  }
-  return bodies;
+  return probeMakeBodies(bodyCount);
 }
 
 function bridgeBodyFields(body) {
-  const fields = new Array(44).fill(0);
-  fields[0] = body.x;
-  fields[1] = body.y;
-  fields[2] = body.z;
-  fields[3] = body.vx;
-  fields[4] = body.vy;
-  fields[5] = body.vz;
-  fields[6] = body.shape.radius;
-  fields[7] = 0;
-  fields[8] = 0;
-  fields[9] = body.kind === 'dynamic' ? 1 : 0;
-  fields[10] = 1;
-  fields[11] = body.layer;
-  fields[12] = body.mask;
-  fields[13] = body.gravityScale ?? 1;
-  fields[14] = body.linearDamping ?? 1;
-  fields[18] = body.mass ?? 1;
-  fields[25] = 1;
-  fields[26] = body.angularDamping ?? 1;
-  fields[27] = body.friction ?? 0.6;
-  fields[31] = body.inertia?.xx ?? 1;
-  fields[32] = body.inertia?.yy ?? 1;
-  fields[33] = body.inertia?.zz ?? 1;
-  return fields;
+  return probeBridgeBodyFields(body);
 }
 
 function commonBodyFields(body) {
-  return [
-    body.x,
-    body.y,
-    body.z,
-    body.vx,
-    body.vy,
-    body.vz,
-    body.angularVel?.x ?? 0,
-    body.angularVel?.y ?? 0,
-    body.angularVel?.z ?? 0,
-    body.orientation?.x ?? 0,
-    body.orientation?.y ?? 0,
-    body.orientation?.z ?? 0,
-    body.orientation?.w ?? 1,
-  ];
+  return probeCommonBodyFields(body);
 }
 
 function benchmarkBodyOrder(bodies) {
-  return [...bodies].sort((left, right) => {
-    if (left.id === 'floor') return -1;
-    if (right.id === 'floor') return 1;
-    return left.id < right.id ? -1 : left.id > right.id ? 1 : 0;
-  });
+  return probeBenchmarkBodyOrder(bodies);
 }
 
 async function runWasm(bodyCount, frameCount) {
@@ -236,10 +156,7 @@ async function runWasm(bodyCount, frameCount) {
   const started = performance.now();
   for (let frame = 0; frame < frameCount; frame += 1) {
     world = stepPhysicsWorld(world, {
-      gravityY: -9.8,
-      dtTicks: 1 / 60,
-      substeps: 4,
-      velocityIterations: 4,
+      ...BOX3D_PROBE_STEP_OPTIONS,
       computeChecksum: false,
     }).world;
   }
@@ -264,29 +181,10 @@ async function runWasmCore(bodyCount, frameCount) {
   const bodies = makeBodies(bodyCount);
   bodies.forEach((body, index) => {
     const offset = index * 44;
-    const shape = body.shape;
-    data[offset] = body.x;
-    data[offset + 1] = body.y;
-    data[offset + 2] = body.z;
-    data[offset + 3] = body.vx;
-    data[offset + 4] = body.vy;
-    data[offset + 5] = body.vz;
-    data[offset + 6] = shape.radius;
-    data[offset + 7] = 0;
-    data[offset + 8] = 0;
-    data[offset + 9] = body.kind === 'dynamic' ? 1 : 0;
-    data[offset + 10] = 1;
-    data[offset + 11] = body.layer;
-    data[offset + 12] = body.mask;
-    data[offset + 13] = 1;
-    data[offset + 14] = 1;
-    data[offset + 18] = body.mass ?? 1;
-    data[offset + 25] = 1;
-    data[offset + 26] = 1;
-    data[offset + 27] = 0.6;
-    data[offset + 31] = body.inertia?.xx ?? 1;
-    data[offset + 32] = body.inertia?.yy ?? 1;
-    data[offset + 33] = body.inertia?.zz ?? 1;
+    const fields = bridgeBodyFields(body);
+    for (let field = 0; field < fields.length; field += 1) {
+      data[offset + field] = fields[field];
+    }
   });
   exports.rundot_kinetix_physics_set_geometry(0, 0);
   const started = performance.now();
@@ -294,10 +192,10 @@ async function runWasmCore(bodyCount, frameCount) {
     const status = exports.rundot_kinetix_physics_step(
       arenaOffset,
       bodyCount,
-      -9.8,
-      1 / 60,
-      4,
-      4,
+      BOX3D_PROBE_STEP_OPTIONS.gravityY,
+      BOX3D_PROBE_STEP_OPTIONS.dtTicks,
+      BOX3D_PROBE_STEP_OPTIONS.substeps,
+      BOX3D_PROBE_STEP_OPTIONS.velocityIterations,
     );
     if (status !== 0) throw new Error(`KINETIX_WASM_CORE_BENCHMARK_STEP_FAILED status=${status}`);
   }

package/core/src/physics/box3d-probe.mjs

@@ -0,0 +1,171 @@
+import { physicsWasmModuleBase64 } from './physics-wasm-module.generated.mjs';
+
+export const BOX3D_PROBE_ABI_VERSION = 1;
+export const BOX3D_PROBE_SCENARIO_ID = 1;
+export const BOX3D_PROBE_BODY_COUNT = 128;
+export const BOX3D_PROBE_SMOKE_FRAMES = 120;
+export const BOX3D_PROBE_PERF_FRAMES = 1200;
+export const BOX3D_PROBE_BODY_STRIDE = 44;
+
+export const BOX3D_PROBE_STEP_OPTIONS = Object.freeze({
+  gravityY: -9.8,
+  dtTicks: 1 / 60,
+  substeps: 4,
+  velocityIterations: 4,
+});
+
+export function makeBodies(bodyCount = BOX3D_PROBE_BODY_COUNT) {
+  if (!Number.isSafeInteger(bodyCount) || bodyCount < 2 || bodyCount > 100_000) {
+    throw new Error('SYNCPLAY_BOX3D_BODY_COUNT_INVALID');
+  }
+  const bodies = [{
+    id: 'floor',
+    kind: 'static',
+    x: 0,
+    y: -32.5,
+    z: 0,
+    vx: 0,
+    vy: 0,
+    vz: 0,
+    linearDamping: 1,
+    angularDamping: 1,
+    shape: { type: 'sphere', radius: 32.5 },
+    layer: 1,
+    mask: 1,
+  }];
+  for (let index = 1; index < bodyCount; index += 1) {
+    const column = (index - 1) % 16;
+    const row = Math.floor((index - 1) / 16);
+    const sphereMass = Math.PI / 6;
+    bodies.push({
+      id: `body-${String(index).padStart(6, '0')}`,
+      kind: 'dynamic',
+      x: column * 1.05 - 7.875,
+      y: 0.5 + row * 1.05,
+      z: 0,
+      vx: column % 2 === 0 ? 0.1 : -0.1,
+      vy: 0,
+      vz: 0,
+      linearDamping: 1,
+      angularDamping: 1,
+      mass: sphereMass,
+      inertia: { xx: 0.1 * sphereMass, yy: 0.1 * sphereMass, zz: 0.1 * sphereMass },
+      shape: { type: 'sphere', radius: 0.5 },
+      layer: 1,
+      mask: 1,
+    });
+  }
+  return bodies;
+}
+
+export function bridgeBodyFields(body) {
+  const fields = new Array(BOX3D_PROBE_BODY_STRIDE).fill(0);
+  fields[0] = body.x;
+  fields[1] = body.y;
+  fields[2] = body.z;
+  fields[3] = body.vx;
+  fields[4] = body.vy;
+  fields[5] = body.vz;
+  fields[6] = body.shape.radius;
+  fields[9] = body.kind === 'dynamic' ? 1 : 0;
+  fields[10] = 1;
+  fields[11] = body.layer;
+  fields[12] = body.mask;
+  fields[13] = body.gravityScale ?? 1;
+  fields[14] = body.linearDamping ?? 1;
+  fields[18] = body.mass ?? 1;
+  fields[25] = 1;
+  fields[26] = body.angularDamping ?? 1;
+  fields[27] = body.friction ?? 0.6;
+  fields[31] = body.inertia?.xx ?? 1;
+  fields[32] = body.inertia?.yy ?? 1;
+  fields[33] = body.inertia?.zz ?? 1;
+  return fields;
+}
+
+export function commonBodyFields(body) {
+  return [
+    body.x,
+    body.y,
+    body.z,
+    body.vx,
+    body.vy,
+    body.vz,
+    body.angularVel?.x ?? 0,
+    body.angularVel?.y ?? 0,
+    body.angularVel?.z ?? 0,
+    body.orientation?.x ?? 0,
+    body.orientation?.y ?? 0,
+    body.orientation?.z ?? 0,
+    body.orientation?.w ?? 1,
+  ];
+}
+
+export function benchmarkBodyOrder(bodies) {
+  return [...bodies].sort((left, right) => {
+    if (left.id === 'floor') return -1;
+    if (right.id === 'floor') return 1;
+    return left.id < right.id ? -1 : left.id > right.id ? 1 : 0;
+  });
+}
+
+export function hashFloat32Values(values) {
+  const view = new DataView(new ArrayBuffer(Float32Array.BYTES_PER_ELEMENT));
+  let hash = 1469598103934665603n;
+  const prime = 1099511628211n;
+  for (const value of values) {
+    view.setFloat32(0, value, true);
+    hash ^= BigInt(view.getUint32(0, true));
+    hash = BigInt.asUintN(64, hash * prime);
+  }
+  return hash.toString(16).padStart(16, '0');
+}
+
+export async function computeBox3dOracleChecksum(frameCount) {
+  if (!Number.isSafeInteger(frameCount) || frameCount < 1 || frameCount > BOX3D_PROBE_PERF_FRAMES) {
+    throw new Error('SYNCPLAY_BOX3D_FRAME_COUNT_INVALID');
+  }
+  const decodeBase64 = (value) => {
+    if (typeof atob === 'function') {
+      const decoded = atob(value);
+      const bytes = new Uint8Array(decoded.length);
+      for (let index = 0; index < decoded.length; index += 1) bytes[index] = decoded.charCodeAt(index);
+      return bytes;
+    }
+    if (typeof Buffer !== 'undefined') return Uint8Array.from(Buffer.from(value, 'base64'));
+    throw new Error('SYNCPLAY_BOX3D_ORACLE_BASE64_UNAVAILABLE');
+  };
+  const instantiated = await WebAssembly.instantiate(decodeBase64(physicsWasmModuleBase64), {});
+  const exports = instantiated instanceof WebAssembly.Instance ? instantiated.exports : instantiated.instance.exports;
+  const bodyCount = BOX3D_PROBE_BODY_COUNT;
+  const bodyBytes = bodyCount * BOX3D_PROBE_BODY_STRIDE * Float64Array.BYTES_PER_ELEMENT;
+  const arenaOffset = Math.ceil((exports.emscripten_stack_get_current() + 64) / 16) * 16;
+  if (arenaOffset + bodyBytes > exports.memory.buffer.byteLength) {
+    exports.memory.grow(Math.ceil((arenaOffset + bodyBytes - exports.memory.buffer.byteLength) / 65_536));
+  }
+  const data = new Float64Array(exports.memory.buffer, arenaOffset, bodyCount * BOX3D_PROBE_BODY_STRIDE);
+  makeBodies().forEach((body, index) => {
+    const fields = bridgeBodyFields(body);
+    for (let field = 0; field < fields.length; field += 1) {
+      data[index * BOX3D_PROBE_BODY_STRIDE + field] = fields[field];
+    }
+  });
+  exports.rundot_kinetix_physics_set_geometry(0, 0);
+  for (let frame = 0; frame < frameCount; frame += 1) {
+    const status = exports.rundot_kinetix_physics_step(
+      arenaOffset,
+      bodyCount,
+      BOX3D_PROBE_STEP_OPTIONS.gravityY,
+      BOX3D_PROBE_STEP_OPTIONS.dtTicks,
+      BOX3D_PROBE_STEP_OPTIONS.substeps,
+      BOX3D_PROBE_STEP_OPTIONS.velocityIterations,
+    );
+    if (status !== 0) throw new Error(`SYNCPLAY_BOX3D_ORACLE_STEP_FAILED ${status}`);
+  }
+  const fields = [];
+  for (let bodyIndex = 1; bodyIndex < bodyCount; bodyIndex += 1) {
+    const offset = bodyIndex * BOX3D_PROBE_BODY_STRIDE;
+    fields.push(...[0, 1, 2, 3, 4, 5, 19, 20, 21, 22, 23, 24, 25].map((field) => data[offset + field]));
+  }
+  return hashFloat32Values(fields);
+}