@driftengine/physics 3.61.0

package/dist/events.d.ts

@@ -0,0 +1,43 @@
+/**
+ * What touched what, drained after the tick rather than raised during it.
+ *
+ * **Not callbacks during the solve.** A callback that mutates the world mid-tick is the classic
+ * footgun — a body removed inside one invalidates every index the solver is holding — and it is
+ * also what would break the executor, since a worker solving one island cannot safely call into a
+ * consumer's code that touches another. Events accumulate into a caller-owned buffer and the caller
+ * drains them when the tick is over and the world is coherent again.
+ *
+ * **Ordered by pair key**, so a replay sees them in the same order it recorded them.
+ *
+ * Physics may not use core's `MessageQueue`: §2 of the design forbids importing an engine package,
+ * and that constraint gives the right answer here anyway. A queue with backpressure is the wrong
+ * shape for per-tick events a caller drains completely, and completely is the only way to drain
+ * these — a dropped `exit` leaves a consumer believing something is still inside a trigger.
+ */
+export declare const EVENT_ENTER = 0;
+export declare const EVENT_STAY = 1;
+export declare const EVENT_EXIT = 2;
+export type EventKind = 0 | 1 | 2;
+export declare class ContactEvents {
+    /** `kind`, `bodyA`, `bodyB` per event, in that order. Read `count` triples. */
+    data: Int32Array;
+    count: number;
+    /** Pair keys touching at the end of the last tick, sorted. */
+    private current;
+    private currentCount;
+    private previous;
+    private previousCount;
+    constructor(capacity?: number);
+    /** Start a tick's collection. The previous tick's set becomes what this one is compared against. */
+    begin(): void;
+    /**
+     * Record a touching pair. **Keys must arrive ascending**, which the sorted pair list guarantees,
+     * because the enter and exit diff below is a merge of two sorted runs.
+     */
+    touching(key: number): void;
+    /** Diff this tick's set against the last and write enter, stay and exit. */
+    end(pairA: (key: number) => number, pairB: (key: number) => number): void;
+    /** Forget everything, for a world whose indices have moved under it. */
+    clear(): void;
+    private push;
+}

package/dist/events.js

@@ -0,0 +1,95 @@
+/**
+ * What touched what, drained after the tick rather than raised during it.
+ *
+ * **Not callbacks during the solve.** A callback that mutates the world mid-tick is the classic
+ * footgun — a body removed inside one invalidates every index the solver is holding — and it is
+ * also what would break the executor, since a worker solving one island cannot safely call into a
+ * consumer's code that touches another. Events accumulate into a caller-owned buffer and the caller
+ * drains them when the tick is over and the world is coherent again.
+ *
+ * **Ordered by pair key**, so a replay sees them in the same order it recorded them.
+ *
+ * Physics may not use core's `MessageQueue`: §2 of the design forbids importing an engine package,
+ * and that constraint gives the right answer here anyway. A queue with backpressure is the wrong
+ * shape for per-tick events a caller drains completely, and completely is the only way to drain
+ * these — a dropped `exit` leaves a consumer believing something is still inside a trigger.
+ */
+export const EVENT_ENTER = 0;
+export const EVENT_STAY = 1;
+export const EVENT_EXIT = 2;
+export class ContactEvents {
+    /** `kind`, `bodyA`, `bodyB` per event, in that order. Read `count` triples. */
+    data;
+    count = 0;
+    /** Pair keys touching at the end of the last tick, sorted. */
+    current;
+    currentCount = 0;
+    previous;
+    previousCount = 0;
+    constructor(capacity = 64) {
+        this.data = new Int32Array(capacity * 3);
+        this.current = new Uint32Array(capacity);
+        this.previous = new Uint32Array(capacity);
+    }
+    /** Start a tick's collection. The previous tick's set becomes what this one is compared against. */
+    begin() {
+        const swap = this.previous;
+        this.previous = this.current;
+        this.previousCount = this.currentCount;
+        this.current = swap;
+        this.currentCount = 0;
+        this.count = 0;
+    }
+    /**
+     * Record a touching pair. **Keys must arrive ascending**, which the sorted pair list guarantees,
+     * because the enter and exit diff below is a merge of two sorted runs.
+     */
+    touching(key) {
+        if (this.currentCount === this.current.length) {
+            const wider = new Uint32Array(this.current.length * 2);
+            wider.set(this.current);
+            this.current = wider;
+        }
+        this.current[this.currentCount++] = key;
+    }
+    /** Diff this tick's set against the last and write enter, stay and exit. */
+    end(pairA, pairB) {
+        let i = 0;
+        let j = 0;
+        while (i < this.currentCount || j < this.previousCount) {
+            const now = i < this.currentCount ? (this.current[i] ?? 0) : Infinity;
+            const was = j < this.previousCount ? (this.previous[j] ?? 0) : Infinity;
+            if (now === was) {
+                this.push(EVENT_STAY, now, pairA, pairB);
+                i++;
+                j++;
+            }
+            else if (now < was) {
+                this.push(EVENT_ENTER, now, pairA, pairB);
+                i++;
+            }
+            else {
+                this.push(EVENT_EXIT, was, pairA, pairB);
+                j++;
+            }
+        }
+    }
+    /** Forget everything, for a world whose indices have moved under it. */
+    clear() {
+        this.count = 0;
+        this.currentCount = 0;
+        this.previousCount = 0;
+    }
+    push(kind, key, pairA, pairB) {
+        if ((this.count + 1) * 3 > this.data.length) {
+            const wider = new Int32Array(this.data.length * 2);
+            wider.set(this.data);
+            this.data = wider;
+        }
+        const at = this.count * 3;
+        this.data[at] = kind;
+        this.data[at + 1] = pairA(key);
+        this.data[at + 2] = pairB(key);
+        this.count++;
+    }
+}

package/dist/executor.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Who runs the islands, and the gate that proves it does not matter.
+ *
+ * **No two islands share a body.** That is the definition, so solving them in any order, or
+ * simultaneously, produces bit-identical state provided each island's internal order is fixed —
+ * which it is, by body index. Parallelism across islands therefore carries no determinism risk at
+ * all, and the deployment constraint that gates a worker pool decides only *which character runs*.
+ *
+ * `ShuffledExecutor` exists to assert exactly that. It solves in reverse order, and a gate runs one
+ * scene through both characters and compares the state. One `solveIsland`, two characters, and a test
+ * proving they agree — which is what the rule about two implementations drifting actually asks for,
+ * since it forbids two implementations of one decision rather than two characters of one.
+ *
+ * **A worker pool over `SharedArrayBuffer` shipped 2026-09-05**, and what it measured is not what
+ * the plan for it predicted. `workerPool.ts` is the pool, `stage.ts` is the mirror it works in, and
+ * `islandWorker.ts` is the far end. A consumer opts in with `new PhysicsWorld({ workers: 4, pool:
+ * createIslandPool })` and gets serial physics with a sentence in `parallelism.reason` wherever that
+ * cannot be honoured.
+ *
+ * **The deployment constraint is real and unchanged.** On a page that is not cross-origin isolated
+ * `SharedArrayBuffer` is not defined at all; with `Cross-Origin-Opener-Policy: same-origin` and
+ * `Cross-Origin-Embedder-Policy: require-corp` it exists, and `Atomics.wait` still answers
+ * `TypeError: Atomics.wait cannot be called in this context` on the main thread. So the caller
+ * blocks where it may and spins where it may not, deciding by trying it rather than by sniffing for
+ * `window`, and it claims its own share first so the spin covers the imbalance and not the solve.
+ * `require-corp` still lands on the consumer's whole site, which is why this is a switch they throw.
+ *
+ * **What the pool is worth, measured on a 24-core desktop, 256 islands of ten boxes:**
+ *
+ * | workers | 1 | 2 | 4 | 8 |
+ * |---|---|---|---|---|
+ * | speedup | 1.05x | 1.22x | 1.26x | 1.39x |
+ *
+ * The old note here predicted 2x to 4x from Amdahl and the solve share. **It is 1.4x at eight
+ * workers**, and the staging copy accounts for 1.7% of that gap and no more. Nothing has measured
+ * what accounts for the rest, so nothing here names a cause. Two bounds do hold and both are
+ * scene-dependent: Amdahl's, from the solve share `island-bench.ts` prints, and `total island cost /
+ * largest island cost`, which is why a hundred jointed boxes gain nothing at any worker count.
+ *
+ * **`DisjointExecutor` below is the reason any of this is safe**, and it is worth more than the pool:
+ * it fails when two islands write one body, which is the assumption a pool cannot survive losing and
+ * which no other test in this package would notice.
+ */
+import type { BodySet } from './bodies.ts';
+import type { IslandSolveState } from './islandSolve.ts';
+/** Something that can advance one island through a whole tick. */
+export interface IslandSolver {
+    solveIsland(island: number): void;
+    /**
+     * The same solve as flat state, for a character that works somewhere else.
+     *
+     * `SerialExecutor` and `ShuffledExecutor` call `solveIsland` and never read this. A staged or
+     * pooled character cannot: it solves a mirror of this state in shared memory, so it needs the state
+     * and not the method that closes over the live one. Optional because `Executor` is a seam a
+     * consumer may implement, and a character of their own owes nothing here.
+     */
+    readonly solveState?: IslandSolveState;
+}
+export interface Executor {
+    /** A name, so a figure taken from a benchmark says which character produced it. */
+    readonly name: string;
+    run(count: number, solver: IslandSolver): void;
+    /**
+     * Release whatever the character holds. A pool terminates its workers.
+     *
+     * Optional, and declared here rather than tested for with `instanceof`, because reaching the pool
+     * class from `world.ts` would put the whole pool in every consumer's bundle — including the ones
+     * that never ask for a worker. Measured at 2,629 bytes gzipped, which is the difference between
+     * this seam being a seam and being a static dependency.
+     */
+    dispose?(): void;
+    /**
+     * Set once a character has given up and gone serial, with a sentence saying why. Null while healthy.
+     */
+    readonly failure?: string | null;
+}
+export declare class SerialExecutor implements Executor {
+    readonly name = "serial";
+    run(count: number, solver: IslandSolver): void;
+}
+/**
+ * Reverse order, and it is a gate rather than a character anybody should choose.
+ *
+ * Reversal rather than a random permutation because `Math.random` is banned on this path and a
+ * seeded generator would be one more thing whose sequence has to be frozen. Reversal is the
+ * strongest single permutation available for free: it moves every element.
+ */
+export declare class ShuffledExecutor implements Executor {
+    readonly name = "shuffled";
+    run(count: number, solver: IslandSolver): void;
+}
+/** Which body two islands both wrote, and which two they were. */
+export interface IslandOverlap {
+    body: number;
+    first: number;
+    second: number;
+}
+/**
+ * The premise, turned into something that fails.
+ *
+ * **A worker pool is safe here because two islands never write the same body**, and that is an
+ * argument about four guards rather than a property anything checks. `applyImpulse` and
+ * `applyLinear` write only where `invMass > 0`; `applyAngular` writes only where the body is
+ * dynamic; `integrateVelocities` and `integratePositions` walk `bodyOrder`, which `island.ts` fills
+ * with dynamic indices alone. A static floor under two towers is read by both and written by
+ * neither.
+ *
+ * **One unguarded write to a static body would break the pool and nothing else.** Serial physics
+ * would stay correct, every existing test would stay green, and the pool would produce a state that
+ * depends on which worker got there first — on some ticks, on some machines. That is a defect that
+ * ships green, so this character exists to make it a red test instead of a bug report.
+ *
+ * It compares **bits** and not values, because the question is whether a write happened at all and
+ * `-0` over `0` is a write. It needs no threads and no timing, so it cannot be flaky in either
+ * direction: the overlap it reports is a real one and its silence is a real absence.
+ *
+ * **A gate and not a character.** Cost is one pass over every body per island, so a scene of a thousand
+ * singletons costs a million lane compares a tick. `SerialExecutor` remains the default.
+ */
+export declare class DisjointExecutor implements Executor {
+    readonly name = "disjoint";
+    /** Set by `run` when two islands wrote one body. Null after a clean tick. */
+    overlap: IslandOverlap | null;
+    private lanes;
+    private snapshot;
+    private owner;
+    private readonly bodies;
+    constructor(bodies: BodySet);
+    run(count: number, solver: IslandSolver): void;
+    /**
+     * Rebuild the bit views, every run.
+     *
+     * `BodySet.grow` replaces the arrays outright, so a view held from a previous tick can be over a
+     * buffer nothing writes any more — which would read as a tick where no island wrote anything, the
+     * one failure this class must not have. Thirteen typed-array constructions a tick is nothing a
+     * gate needs to avoid.
+     */
+    private bind;
+    private capture;
+    /**
+     * Whoever changed a body's bits owns it, and a second owner is the finding.
+     *
+     * The first overlap is kept rather than the last, so a run reports where the invariant broke
+     * first instead of wherever the scan happened to end.
+     */
+    private claim;
+}

package/dist/executor.js

@@ -0,0 +1,173 @@
+/**
+ * Who runs the islands, and the gate that proves it does not matter.
+ *
+ * **No two islands share a body.** That is the definition, so solving them in any order, or
+ * simultaneously, produces bit-identical state provided each island's internal order is fixed —
+ * which it is, by body index. Parallelism across islands therefore carries no determinism risk at
+ * all, and the deployment constraint that gates a worker pool decides only *which character runs*.
+ *
+ * `ShuffledExecutor` exists to assert exactly that. It solves in reverse order, and a gate runs one
+ * scene through both characters and compares the state. One `solveIsland`, two characters, and a test
+ * proving they agree — which is what the rule about two implementations drifting actually asks for,
+ * since it forbids two implementations of one decision rather than two characters of one.
+ *
+ * **A worker pool over `SharedArrayBuffer` shipped 2026-09-05**, and what it measured is not what
+ * the plan for it predicted. `workerPool.ts` is the pool, `stage.ts` is the mirror it works in, and
+ * `islandWorker.ts` is the far end. A consumer opts in with `new PhysicsWorld({ workers: 4, pool:
+ * createIslandPool })` and gets serial physics with a sentence in `parallelism.reason` wherever that
+ * cannot be honoured.
+ *
+ * **The deployment constraint is real and unchanged.** On a page that is not cross-origin isolated
+ * `SharedArrayBuffer` is not defined at all; with `Cross-Origin-Opener-Policy: same-origin` and
+ * `Cross-Origin-Embedder-Policy: require-corp` it exists, and `Atomics.wait` still answers
+ * `TypeError: Atomics.wait cannot be called in this context` on the main thread. So the caller
+ * blocks where it may and spins where it may not, deciding by trying it rather than by sniffing for
+ * `window`, and it claims its own share first so the spin covers the imbalance and not the solve.
+ * `require-corp` still lands on the consumer's whole site, which is why this is a switch they throw.
+ *
+ * **What the pool is worth, measured on a 24-core desktop, 256 islands of ten boxes:**
+ *
+ * | workers | 1 | 2 | 4 | 8 |
+ * |---|---|---|---|---|
+ * | speedup | 1.05x | 1.22x | 1.26x | 1.39x |
+ *
+ * The old note here predicted 2x to 4x from Amdahl and the solve share. **It is 1.4x at eight
+ * workers**, and the staging copy accounts for 1.7% of that gap and no more. Nothing has measured
+ * what accounts for the rest, so nothing here names a cause. Two bounds do hold and both are
+ * scene-dependent: Amdahl's, from the solve share `island-bench.ts` prints, and `total island cost /
+ * largest island cost`, which is why a hundred jointed boxes gain nothing at any worker count.
+ *
+ * **`DisjointExecutor` below is the reason any of this is safe**, and it is worth more than the pool:
+ * it fails when two islands write one body, which is the assumption a pool cannot survive losing and
+ * which no other test in this package would notice.
+ */
+export class SerialExecutor {
+    name = 'serial';
+    run(count, solver) {
+        for (let i = 0; i < count; i++)
+            solver.solveIsland(i);
+    }
+}
+/**
+ * Reverse order, and it is a gate rather than a character anybody should choose.
+ *
+ * Reversal rather than a random permutation because `Math.random` is banned on this path and a
+ * seeded generator would be one more thing whose sequence has to be frozen. Reversal is the
+ * strongest single permutation available for free: it moves every element.
+ */
+export class ShuffledExecutor {
+    name = 'shuffled';
+    run(count, solver) {
+        for (let i = count - 1; i >= 0; i--)
+            solver.solveIsland(i);
+    }
+}
+/**
+ * The premise, turned into something that fails.
+ *
+ * **A worker pool is safe here because two islands never write the same body**, and that is an
+ * argument about four guards rather than a property anything checks. `applyImpulse` and
+ * `applyLinear` write only where `invMass > 0`; `applyAngular` writes only where the body is
+ * dynamic; `integrateVelocities` and `integratePositions` walk `bodyOrder`, which `island.ts` fills
+ * with dynamic indices alone. A static floor under two towers is read by both and written by
+ * neither.
+ *
+ * **One unguarded write to a static body would break the pool and nothing else.** Serial physics
+ * would stay correct, every existing test would stay green, and the pool would produce a state that
+ * depends on which worker got there first — on some ticks, on some machines. That is a defect that
+ * ships green, so this character exists to make it a red test instead of a bug report.
+ *
+ * It compares **bits** and not values, because the question is whether a write happened at all and
+ * `-0` over `0` is a write. It needs no threads and no timing, so it cannot be flaky in either
+ * direction: the overlap it reports is a real one and its silence is a real absence.
+ *
+ * **A gate and not a character.** Cost is one pass over every body per island, so a scene of a thousand
+ * singletons costs a million lane compares a tick. `SerialExecutor` remains the default.
+ */
+export class DisjointExecutor {
+    name = 'disjoint';
+    /** Set by `run` when two islands wrote one body. Null after a clean tick. */
+    overlap = null;
+    lanes = [];
+    snapshot = new Uint32Array(0);
+    owner = new Int32Array(0);
+    bodies;
+    constructor(bodies) {
+        this.bodies = bodies;
+    }
+    run(count, solver) {
+        const n = this.bodies.count;
+        this.bind(n);
+        this.owner.fill(-1, 0, n);
+        this.overlap = null;
+        for (let island = 0; island < count; island++) {
+            this.capture(n);
+            solver.solveIsland(island);
+            this.claim(island, n);
+        }
+    }
+    /**
+     * Rebuild the bit views, every run.
+     *
+     * `BodySet.grow` replaces the arrays outright, so a view held from a previous tick can be over a
+     * buffer nothing writes any more — which would read as a tick where no island wrote anything, the
+     * one failure this class must not have. Thirteen typed-array constructions a tick is nothing a
+     * gate needs to avoid.
+     */
+    bind(n) {
+        const b = this.bodies;
+        const bits = (a) => new Uint32Array(a.buffer, a.byteOffset, a.length);
+        this.lanes = [
+            bits(b.posX),
+            bits(b.posY),
+            bits(b.posZ),
+            bits(b.rotX),
+            bits(b.rotY),
+            bits(b.rotZ),
+            bits(b.rotW),
+            bits(b.velX),
+            bits(b.velY),
+            bits(b.velZ),
+            bits(b.angX),
+            bits(b.angY),
+            bits(b.angZ),
+        ];
+        const wanted = this.lanes.length * n;
+        if (this.snapshot.length < wanted)
+            this.snapshot = new Uint32Array(wanted);
+        if (this.owner.length < n)
+            this.owner = new Int32Array(n);
+    }
+    capture(n) {
+        for (let l = 0; l < this.lanes.length; l++) {
+            const lane = this.lanes[l];
+            const at = l * n;
+            for (let i = 0; i < n; i++)
+                this.snapshot[at + i] = lane[i];
+        }
+    }
+    /**
+     * Whoever changed a body's bits owns it, and a second owner is the finding.
+     *
+     * The first overlap is kept rather than the last, so a run reports where the invariant broke
+     * first instead of wherever the scan happened to end.
+     */
+    claim(island, n) {
+        for (let i = 0; i < n; i++) {
+            let wrote = false;
+            for (let l = 0; l < this.lanes.length && !wrote; l++) {
+                const lane = this.lanes[l];
+                if (lane[i] !== this.snapshot[l * n + i])
+                    wrote = true;
+            }
+            if (!wrote)
+                continue;
+            const held = this.owner[i] ?? -1;
+            if (held >= 0 && held !== island) {
+                this.overlap ??= { body: i, first: held, second: island };
+                continue;
+            }
+            this.owner[i] = island;
+        }
+    }
+}

package/dist/faces.d.ts

@@ -0,0 +1,26 @@
+import type { ConvexShape } from './shape.ts';
+/**
+ * A shape's faces, as planes and as ordered vertex loops.
+ *
+ * **`faceNormals` is not this, and the two are deliberately separate.** That array is deduped
+ * *directions* — a box has three, because a plane and its opposite are one separating axis — which
+ * is exactly what SAT wants and exactly what clipping cannot use. A contact manifold needs the
+ * reference face's plane and the incident face's ordered loop, so a box needs six of each.
+ *
+ * CSR rather than an array of arrays: traversal allocates nothing, and a shape built of typed
+ * arrays alone is structured-cloneable, so it survives a `postMessage` into a worker.
+ *
+ * **What this gives up** is memory on every shape, whether or not anything clips it: four floats
+ * per face plus one index per face vertex. **What would make it wrong** is a consumer building tens
+ * of thousands of shapes for broad-phase-only use, at which point the answer is a builder flag
+ * rather than a second shape type.
+ */
+/** How many faces the shape has. Zero for a sphere or a capsule, which have none. */
+export declare function faceCount(shape: ConvexShape): number;
+/**
+ * Fill `out` with the vertex indices of one face, wound counter-clockwise seen from outside.
+ *
+ * Returns how many were written. `out` must hold at least that many; a face cannot have more
+ * vertices than the shape has, so `new Uint16Array(shape.vertices.length / 3)` always suffices.
+ */
+export declare function faceVertices(shape: ConvexShape, face: number, out: Uint16Array): number;

package/dist/faces.js

@@ -0,0 +1,34 @@
+/**
+ * A shape's faces, as planes and as ordered vertex loops.
+ *
+ * **`faceNormals` is not this, and the two are deliberately separate.** That array is deduped
+ * *directions* — a box has three, because a plane and its opposite are one separating axis — which
+ * is exactly what SAT wants and exactly what clipping cannot use. A contact manifold needs the
+ * reference face's plane and the incident face's ordered loop, so a box needs six of each.
+ *
+ * CSR rather than an array of arrays: traversal allocates nothing, and a shape built of typed
+ * arrays alone is structured-cloneable, so it survives a `postMessage` into a worker.
+ *
+ * **What this gives up** is memory on every shape, whether or not anything clips it: four floats
+ * per face plus one index per face vertex. **What would make it wrong** is a consumer building tens
+ * of thousands of shapes for broad-phase-only use, at which point the answer is a builder flag
+ * rather than a second shape type.
+ */
+/** How many faces the shape has. Zero for a sphere or a capsule, which have none. */
+export function faceCount(shape) {
+    return shape.faceVertexStart.length === 0 ? 0 : shape.faceVertexStart.length - 1;
+}
+/**
+ * Fill `out` with the vertex indices of one face, wound counter-clockwise seen from outside.
+ *
+ * Returns how many were written. `out` must hold at least that many; a face cannot have more
+ * vertices than the shape has, so `new Uint16Array(shape.vertices.length / 3)` always suffices.
+ */
+export function faceVertices(shape, face, out) {
+    const start = shape.faceVertexStart[face] ?? 0;
+    const end = shape.faceVertexStart[face + 1] ?? start;
+    const n = end - start;
+    for (let i = 0; i < n; i++)
+        out[i] = shape.faceVertexIndices[start + i] ?? 0;
+    return n;
+}

package/dist/fingerprint.d.ts

@@ -0,0 +1,61 @@
+import type { BodySet } from './bodies.ts';
+import type { ColliderSet } from './colliderSet.ts';
+/**
+ * A stable hash of the static geometry a simulation ran against.
+ *
+ * A recording made of a deterministic simulation is only replayable against the
+ * world it was recorded in. When world generation changes — a fixed bug, a
+ * retuned curve, a new build — recordings from before it desync, and they do it
+ * *silently*: the run is reproduced faithfully against geometry that is no longer
+ * there, so what appears on screen is a body moving through empty space with
+ * nothing to explain it.
+ *
+ * Storing this alongside a recording lets a caller compare the world it has
+ * against the world the recording was made in, and refuse rather than guess.
+ *
+ * **Determinism is the whole contract.** The same colliders must give the same
+ * string on every machine and in every build, so this reads the raw bytes of the
+ * bounds array: a float's decimal rendering is a platform question and its bit
+ * pattern is not. Nothing here iterates a `Map` or a `Set`, both of which would
+ * make the answer depend on insertion order.
+ *
+ * **No tolerance, deliberately.** A sub-millimetre difference changes the answer.
+ * Whether a given difference *matters* is the caller's judgement, and a hash that
+ * quietly rounded would take that judgement away from every caller at once.
+ *
+ * FNV-1a over 64 bits, carried as two 32-bit halves because JavaScript's bitwise
+ * operators are 32-bit and a single accumulator would silently lose the top half.
+ * Not a cryptographic hash: this detects change, it does not resist forgery, and
+ * a caller that needs the second property needs `crypto.subtle` and an await.
+ *
+ * **On a set that has been mutated, this answers "the same set with the same history" and not
+ * "the same world".** A set can take and drop groups now, and a slot freed by one region is
+ * refilled by another, so the same geometry sits at different indices depending on the path
+ * driven to reach it.
+ *
+ * *Replay is not what that costs.* The same inputs drive the same path, which produces the same
+ * load order and so the same slots, and a recording replays against the set it was recorded
+ * against exactly as it always did. What it costs is comparing two *sessions* that arrived at the
+ * same world by different routes.
+ *
+ * **`fingerprintBodies`'s escape hatch does not transfer**, which is worth saying because the two
+ * functions are otherwise the same construction. There, a caller wanting the multiset sorts what
+ * it feeds in, because it hands over an array. Here a caller hands over an object whose slot order
+ * is a load history they neither chose nor can observe, so there is nothing for them to sort. A
+ * canonical variant hashing live slots sorted by their packed bytes would answer the cross-session
+ * question and is about fifteen lines; it is not here because nothing is asking it yet.
+ */
+export declare function fingerprintColliders(set: ColliderSet): string;
+/**
+ * A stable hash of every body's state, for comparing one run against another.
+ *
+ * The same FNV-1a construction and the same reasoning as `fingerprintColliders`: the raw bytes of a
+ * float, because its decimal rendering is a platform question and its bit pattern is not. No
+ * tolerance, deliberately — whether a difference *matters* is the caller's judgement, and a hash
+ * that quietly rounded would take that judgement away from every caller at once.
+ *
+ * **Order matters here and that is the point.** Two runs of the same scene must agree body for
+ * body. A caller comparing scenes *built* in different orders wants the multiset instead, and has
+ * to sort what it feeds in — see the permutation gate beside the solver baseline, which does.
+ */
+export declare function fingerprintBodies(bodies: BodySet): string;