@graphty/webgpu-graph-algorithms 0.5.1 → 0.6.0

package/dist/src/layouts/calibrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"calibrate.d.ts","sourceRoot":"","sources":["../../../src/layouts/calibrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAGhD,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAIhF,wGAAwG;AACxG,eAAO,MAAM,eAAe,EAAE,SAAS,MAAM,EAAoC,CAAC;AAqFlF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,sBAAsB,CAClC,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EACzC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACzC,MAAM,CAQR;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,CAAC,CAgC1G"}

package/dist/src/layouts/calibrate.js

@@ -0,0 +1,172 @@
+/**
+ * calibrateLayout (spec 2.2, 7.8, D26; contract 3.3): the layout-tier micro-benchmark a consumer runs ONCE, off the
+ * critical path, to measure the exact / grid crossover on the actual device. For every probed size it builds a seeded
+ * G(n, 10n) snapshot, runs ForceAtlas2 on the exact tier and on the grid tier -- one untimed `step(1)` after
+ * `load()` (which warms every pipeline through `PipelineCache.warm` of the model's specs, so the first timed step
+ * compiles nothing) and then TIMED_ITERATIONS timed `step(1)` calls whose `stats.msPerIteration` (the profiler's GPU
+ * time when "timestamp-query" was granted, else the batch wall time) are averaged -- and releases the probe.
+ *
+ * PLAN DECISION PD-23 (P4-T14): `src/` cannot import `test/helpers` or `benchmarks/`, so the probe graphs are built
+ * here from the package's own LCG (`Lcg`, seed.ts) with a fixed seed, and the spec 7.8 rule is re-implemented in
+ * `suggestedExactMaxNodes` below; its twin is `exactMaxNodesFromLadder` in benchmarks/layout-exact.bench.ts (the
+ * one copy the G3 / G4 records apply to the committed baselines), which test/layouts/calibrate.test.ts compares it
+ * with. The function reads `caps` for nothing: never `caps.software` (spec 7.8, Q-6), so on a software adapter it
+ * returns honest numbers a caller can compare in shape, never in value.
+ */
+import { fromEdgeArrays } from "@graphty/graph-format";
+import { WebGpuGraphError } from "../errors.js";
+import { assertDeviceComputes } from "../primitives/verify.js";
+import { createForceAtlas2 } from "./forceatlas2.js";
+import { Lcg } from "./seed.js";
+/** The default probe sizes (spec 2.2): the 8k-65k subset of the exact ladder of spec 7.8 / 10.4 T-4. */
+export const CALIBRATE_SIZES = [8192, 16384, 32768, 65536];
+/** The spec 7.8 per-iteration budget of the exact tier, milliseconds (the twin of EXACT_BUDGET_MS in benchmarks/layout-exact.bench.ts). */
+const BUDGET_MS = 4;
+/** Edges per node of every probe graph (E = 10n, the density of the exact ladder). */
+const EDGES_PER_NODE = 10;
+/** Timed iterations per size and tier (spec 2.2: "10 timed iterations"). */
+const TIMED_ITERATIONS = 10;
+/** The seed of every probe graph and of the simulation's own LCG. */
+const SEED = 12345;
+/**
+ * A seeded G(n, 10n) probe snapshot (self-loops and parallels allowed, unweighted, undirected).
+ * @param n - the node count
+ * @returns the snapshot
+ */
+function probeSnapshot(n) {
+    const m = EDGES_PER_NODE * n;
+    const rng = new Lcg(SEED);
+    const src = new Uint32Array(m);
+    const dst = new Uint32Array(m);
+    for (let e = 0; e < m; e++) {
+        src[e] = Math.floor(rng.next() * n);
+        dst[e] = Math.floor(rng.next() * n);
+    }
+    return fromEdgeArrays({ directed: false, nodeCount: n, src, dst }, { label: `calibrate/${n}` });
+}
+/**
+ * The mean ms per iteration of one tier at one size: one untimed step after load(), then TIMED_ITERATIONS timed
+ * steps (reheat() before each so a settled simulation never short-circuits). With the profiler (a device that granted
+ * "timestamp-query") the sample is the GPU time of the iteration's passes, the quantity the spec 7.8 rule reads; without
+ * it the sample is the step's wall time, which also carries the JS submit and the 12n-byte readback -- a fixed cost of
+ * ~1-2 ms on a discrete card that is the same for either tier, so the wall ratio understates the grid tier's
+ * advantage at every size and the crossover it suggests is, if anything, too high.
+ * @param ctx - the context
+ * @param snapshot - the probe snapshot
+ * @param tier - the repulsion tier to force
+ * @returns milliseconds per iteration
+ */
+async function probeTier(ctx, snapshot, tier) {
+    const n = snapshot.nodeCount;
+    const positions = new Float32Array(3 * n).fill(Number.NaN);
+    const sim = createForceAtlas2(ctx, {
+        dim: 2,
+        seed: SEED,
+        maxIter: 1000000,
+        iterationsPerStep: 1,
+        maxInFlight: 1,
+        repulsion: tier,
+        compat: "paper",
+    });
+    try {
+        sim.load(snapshot, positions);
+        await sim.step(1);
+        let total = 0;
+        for (let i = 0; i < TIMED_ITERATIONS; i++) {
+            sim.reheat();
+            const start = performance.now();
+            await sim.step(1);
+            const wall = performance.now() - start;
+            total += sim.stats.msPerIteration ?? wall;
+        }
+        return total / TIMED_ITERATIONS;
+    }
+    finally {
+        sim.dispose();
+    }
+}
+/**
+ * The largest power of two that is <= n (the twin of floorPow2 in benchmarks/layout-exact.bench.ts).
+ * @param n - a number >= 1
+ * @returns the largest power of two not above n
+ */
+function floorPow2(n) {
+    let p = 1;
+    while (p * 2 <= n) {
+        p *= 2;
+    }
+    return p;
+}
+/**
+ * The spec 7.8 rule over the probed sizes (the twin of exactMaxNodesFromLadder(rows, budget, gridRows) in
+ * benchmarks/layout-exact.bench.ts, which test/layouts/calibrate.test.ts compares it with): the largest probed n with
+ * exactMs(n) <= BUDGET_MS and exactMs(n) <= gridMs(n), rounded down to a power of two.
+ *
+ * CONTRACT DECISION (the review of P4-T14; spec 2.2 is silent): when NO probed size satisfies the rule -- the grid
+ * tier faster than the exact tier at every probe (the RTX 4070 SUPER with the default sizes: the grid beats the exact
+ * tier from 4k up), or every probe over the budget -- the benchmark twin throws and hands the value to an owner
+ * decision (spec 10.4), which a library call cannot do. The answer here is then the largest power of two STRICTLY
+ * BELOW the smallest probe (1 when the smallest probe is 1): the exact tier runs at no probed size, the unprobed range
+ * below keeps the exact tier (whose cost falls with n^2 and is the oracle), and the value is distinguishable from a
+ * rule answer, which is never below floorPow2(min(sizes)). A caller that wants the crossover itself probes smaller
+ * sizes (the T-4 ladder from 1k); one that wants the exact tier nowhere passes `repulsion: "grid"`.
+ * @param sizes - the probed sizes (integers >= 1)
+ * @param exactMs - ms per iteration of the exact tier per size
+ * @param gridMs - ms per iteration of the grid tier per size
+ * @returns the suggested exactMaxNodes
+ */
+export function suggestedExactMaxNodes(sizes, exactMs, gridMs) {
+    let best = 0;
+    for (const n of sizes) {
+        if (exactMs[n] <= BUDGET_MS && exactMs[n] <= gridMs[n] && n > best) {
+            best = n;
+        }
+    }
+    return floorPow2(best === 0 ? Math.max(1, Math.min(...sizes) - 1) : best);
+}
+/**
+ * Spec 2.2 calibrateLayout, verbatim: measures ms per iteration of the exact and the grid repulsion tier at every
+ * probed size on THIS device and suggests `exactMaxNodes` by the spec 7.8 rule (`suggestedExactMaxNodes` above, with
+ * its below-the-range answer when no probed size qualifies). Every probe graph is built here and released before the
+ * call returns; `firstCallMs` is the wall time of the whole call (pipeline compilation included the first time). The
+ * app passes `suggestedExactMaxNodes` through `createAccelerator(ctx, { layout: { exactMaxNodes } })`; the package
+ * never calls this implicitly and `"auto"` never depends on `caps.software`.
+ * @param ctx - the context (E_DISPOSED / E_DEVICE_LOST through assertReady)
+ * @param options - the probe sizes (positive integers; default CALIBRATE_SIZES)
+ * @returns the calibration record
+ */
+export async function calibrateLayout(ctx, options) {
+    ctx.assertReady();
+    await assertDeviceComputes(ctx);
+    const sizes = options?.sizes ?? CALIBRATE_SIZES;
+    if (!Array.isArray(sizes) || sizes.length === 0 || !sizes.every((n) => Number.isInteger(n) && n >= 1)) {
+        throw new WebGpuGraphError("E_INVALID_ARGUMENT", "sizes must be a non-empty list of integers >= 1", {
+            argument: "sizes",
+            value: sizes,
+            expected: "a non-empty list of integers >= 1",
+        });
+    }
+    const start = performance.now();
+    const exactMsPerIter = {};
+    const gridMsPerIter = {};
+    for (const n of sizes) {
+        const snapshot = probeSnapshot(n);
+        try {
+            exactMsPerIter[n] = await probeTier(ctx, snapshot, "exact");
+            gridMsPerIter[n] = await probeTier(ctx, snapshot, "grid");
+        }
+        finally {
+            ctx.release(snapshot);
+        }
+    }
+    const largest = Math.max(...sizes);
+    const pairs = largest * (largest - 1);
+    return {
+        pairsPerSecond: (pairs / exactMsPerIter[largest]) * 1000,
+        exactMsPerIter,
+        gridMsPerIter,
+        suggestedExactMaxNodes: suggestedExactMaxNodes(sizes, exactMsPerIter, gridMsPerIter),
+        firstCallMs: performance.now() - start,
+    };
+}
+//# sourceMappingURL=calibrate.js.map

package/dist/src/layouts/calibrate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"calibrate.js","sourceRoot":"","sources":["../../../src/layouts/calibrate.ts"],"names":[],"mappings":"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"}

package/dist/src/layouts/force-simulation.d.ts

@@ -14,7 +14,9 @@ import { type PipelineCache } from "../kernel/pipeline-cache.js";
 import { type UniformBlock, type UniformValues } from "../kernel/struct-block.js";
 import { UniformRing } from "../kernel/uniform-ring.js";
 import { type WgslModuleSpec } from "../kernel/wgsl.js";
+import { type BufferPool } from "../memory/buffer-pool.js";
 import { type CoreBinding } from "../memory/residency.js";
+import { type DegreeTiers } from "../primitives/core-shape.js";
 import { type PlanCaps } from "../types/context.js";
 import { type GpuLayoutSimulation, type LayoutStatsBase, type ResolvedLayoutTuning, type RunOptions } from "../types/layout.js";
 import { type Binding } from "../types/memory.js";
@@ -40,7 +42,14 @@ export interface ModelResources {
     readonly caps: PlanCaps;
     readonly pipelines: PipelineCache;
     readonly core: CoreBinding;
+    /** `tiers.perm`, or null when no row has degree >= 32 (P4 PD-7: the rowPtr dummy is bound and USE_PERM is false). */
     readonly perm: Binding | null;
+    /**
+     * The degree tiers of the snapshot's degreeOrder view (the perm binding and the CPU-side segment offsets
+     * [0, hiEnd, midEnd, lowEnd, n]), or null when no row has degree >= 32 -- then every K2 dispatch is the
+     * thread-per-row TIER 0 over node indices, as before P4.
+     */
+    readonly tiers: DegreeTiers | null;
     /**
      * The RESOLVED weights binding (model.inputs(): source "arcs" -> core.weights (null on an unweighted snapshot),
      * "column" -> the registered ArrayBinding's binding, "none" -> null); group 0 is built as
@@ -51,6 +60,8 @@ export interface ModelResources {
     readonly dim: 2 | 3;
     readonly tier: "exact" | "grid";
     readonly ring: UniformRing;
+    /** The context's buffer pool (the grid stage's lease of sort scratch draws on it, P4 PD-11). */
+    readonly pool: BufferPool;
     /** A shared or model-owned buffer by name: "positions", "scenePositions", "fixed", "partials", "state", "trace", plus every BufferSpec name. */
     buffer(name: string): Binding;
 }
@@ -98,7 +109,17 @@ export interface ForceModel<Options, Stats extends LayoutStatsBase> {
     onReheat(state: StateWriter): void;
     onSetParams(patch: Partial<Options>, state: StateWriter): void;
     readStats(state: DataView, trace: DataView): Stats;
+    /** Releases what the model holds outside the simulation's buffers (the grid stage's lease, P4-T10); called by dispose() once every in-flight batch has settled. */
+    dispose?(): void;
 }
+/**
+ * The repulsion tier of a node count under a tuning (PLAN DECISION 11; spec 7.8: `"auto"` by `n` alone). Exported
+ * so a model's `buffers(n, dim)` decides the tier by the same rule `load()` applies (P4 PD-18).
+ * @param tuning - the resolved tuning
+ * @param n - the node count
+ * @returns "exact" or "grid"
+ */
+export declare function tierFor(tuning: ResolvedLayoutTuning, n: number): "exact" | "grid";
 /**
  * The shared layout state machine (spec 7.19): buffers, in-flight batches, readback, settle window, fixed mask,
  * setPosition overrides, trace, batch driver; consumes a ForceModel by composition.
@@ -146,6 +167,7 @@ export declare class ForceSimulation<Options extends CommonLayoutOptions & Simul
     private settledValue;
     private firstPending;
     private statsValue;
+    private lastPassTimingsValue;
     private lastSubmittedBatchIdValue;
     /** The id of the last batch submitted BEFORE the most recent reheat() (PLAN DECISION 21); 0 = none. */
     private reheatedAfterBatchId;
@@ -171,7 +193,7 @@ export declare class ForceSimulation<Options extends CommonLayoutOptions & Simul
      */
     get options(): Options;
     /**
-     * The repulsion tier of the current load ("exact" until P4 lifts the grid tier).
+     * The repulsion tier of the current load (spec 7.8).
      * @returns the tier
      */
     get tier(): "exact" | "grid";
@@ -322,7 +344,10 @@ export declare class ForceSimulation<Options extends CommonLayoutOptions & Simul
      */
     private copyScene;
     /**
-     * The batch's duration in milliseconds: the profiler's pass timings summed when present, else wall time.
+     * The batch's duration in milliseconds: the profiler's pass timings summed when present and complete, else wall
+     * time. The profiler budgets PROFILER_QUERY_SLOTS / 2 passes per batch; the grid tier records three passes per
+     * iteration (P4 PD-16), so a grid batch above (PROFILER_QUERY_SLOTS / 2 - 1) / 3 iterations is timed partially:
+     * its rows stay in `lastPassTimings` but the duration is the wall time, never the sum of a prefix.
      * @param record - the batch
      * @param bytes - its readback (the profiler's resolve lands in it)
      * @returns milliseconds
@@ -450,6 +475,7 @@ export declare class ForceSimulation<Options extends CommonLayoutOptions & Simul
     /**
      * The ModelResources of a load.
      * @param core - the core
+     * @param tiers - the degree tiers, or null when no row has degree >= 32
      * @param weights - the resolved weights binding
      * @param buffers - the buffers
      * @returns the resources
@@ -467,14 +493,23 @@ export declare class ForceSimulation<Options extends CommonLayoutOptions & Simul
      */
     private startBind;
     /**
-     * warm(model.specs()) then model.bind(); the await re-checks that the load is current before binding.
+     * assertDeviceComputes() then warm(model.specs()) then model.bind(); the await re-checks that the load is
+     * current before binding.
+     *
+     * The device self-check sits HERE rather than in submitBatch (its first home) because this promise is the one
+     * submitBatch already awaits before every batch: the check is therefore settled before the simulation can
+     * submit a single iteration, yet costs the frame loop nothing per batch. An extra await on the per-batch path
+     * moves the moment a submission becomes visible to a step() issued in the same tick, which is precisely what
+     * coalescing is measured on (test/layouts/frame-loop.test.ts, "a coalesced step() returns the same promise").
+     * A device that computes incorrectly rejects this promise, so the first step() rejects E_DEVICE_INCORRECT
+     * before any position is written; a check that could not RUN rejects with its own error, unchanged.
      * @param resources - the resources
      * @param overrides - the merged override set
      * @param generation - the generation the bind belongs to
      */
     private compileAndBind;
     /**
-     * inspect(name): flush, read the named buffer back, Uint32Array for "fixed" and "trace", Float32Array otherwise.
+     * inspect(name): flush, read the named buffer back, Uint32Array for the u32 buffers (U32_BUFFER_NAMES), Float32Array otherwise.
      * @param name - a shared or BufferSpec name
      * @returns the words
      */

package/dist/src/layouts/force-simulation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"force-simulation.d.ts","sourceRoot":"","sources":["../../../src/layouts/force-simulation.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"force-simulation.d.ts","sourceRoot":"","sources":["../../../src/layouts/force-simulation.ts"],"names":[],"mappings":"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"}

package/dist/src/layouts/force-simulation.js

@@ -14,6 +14,8 @@ import { hasErrorCode, WebGpuGraphError } from "../errors.js";
 import { CommandBatch } from "../kernel/batch.js";
 import { UniformRing } from "../kernel/uniform-ring.js";
 import { graphOverrides } from "../kernels.js";
+import { degreeTiersOf } from "../primitives/core-shape.js";
+import { assertDeviceComputes } from "../primitives/verify.js";
 import { seedPositions } from "./seed.js";
 // ============================================================ module-private helpers
 /** The shared params fields (name, width) every model params block must declare (PLAN DECISION 4). */
@@ -40,6 +42,20 @@ const SHARED_STATE_FIELDS = [
 ];
 /** The names of the shared buffers a BufferSpec may not reuse. */
 const SHARED_BUFFER_NAMES = ["positions", "scenePositions", "fixed", "partials", "state", "trace"];
+/** The buffers inspect() returns as Uint32Array: the mask, the trace records and the grid tier's index / count arrays (P4). */
+const U32_BUFFER_NAMES = new Set([
+    "fixed",
+    "trace",
+    "cellKey",
+    "cellVal",
+    "sortedKey",
+    "sortedIdx",
+    "cellHist",
+    "cellStart",
+    "hubList",
+    "hubCounters",
+    "hubArgs",
+]);
 /** The per-batch epilogue stage: iterations 0..k-2 stop after the stage that precedes it (PLAN DECISION 2). */
 const EPILOGUE_STAGE = "toScene";
 let simulationCounter = 0;
@@ -207,12 +223,13 @@ function centerOf(options) {
     return out;
 }
 /**
- * The repulsion tier of a node count under a tuning (PLAN DECISION 11).
+ * The repulsion tier of a node count under a tuning (PLAN DECISION 11; spec 7.8: `"auto"` by `n` alone). Exported
+ * so a model's `buffers(n, dim)` decides the tier by the same rule `load()` applies (P4 PD-18).
  * @param tuning - the resolved tuning
  * @param n - the node count
  * @returns "exact" or "grid"
  */
-function tierFor(tuning, n) {
+export function tierFor(tuning, n) {
     if (tuning.repulsion === "exact") {
         return "exact";
     }
@@ -385,6 +402,7 @@ export class ForceSimulation {
         this.settledValue = false;
         this.firstPending = true;
         this.statsValue = null;
+        this.lastPassTimingsValue = null;
         this.lastSubmittedBatchIdValue = 0;
         /** The id of the last batch submitted BEFORE the most recent reheat() (PLAN DECISION 21); 0 = none. */
         this.reheatedAfterBatchId = 0;
@@ -450,12 +468,22 @@ export class ForceSimulation {
         return this.optionsValue;
     }
     /**
-     * The repulsion tier of the current load ("exact" until P4 lifts the grid tier).
+     * The repulsion tier of the current load (spec 7.8).
      * @returns the tier
      */
     get tier() {
         return this.tierValue;
     }
+    /**
+     * The profiler's per-pass timings of the last landed batch (pass order; the grid tier's `fa2-k1` /
+     * `fa2-attraction` / `fa2-grid` / `fa2-to-scene` rows give T-7's attraction figure, P4 PD-16), or null before a
+     * batch landed or without `timestamp-query`.
+     * @internal
+     * @returns the timings
+     */
+    get lastPassTimings() {
+        return this.lastPassTimingsValue;
+    }
     /**
      * The generation counter bumped by every load() (stale readbacks are discarded).
      * @internal
@@ -577,12 +605,6 @@ export class ForceSimulation {
         const scale = scaleOf(this.optionsValue);
         const center = centerOf(this.optionsValue);
         const tier = tierFor(this.tuning, n);
-        if (tier === "grid") {
-            throw new WebGpuGraphError("E_UNSUPPORTED", `the grid repulsion tier lands at P4 (n = ${n}, exactMaxNodes = ${this.tuning.exactMaxNodes})`, {
-                feature: "repulsion.grid",
-                hint: 'pass repulsion: "exact" or raise exactMaxNodes',
-            });
-        }
         const positionsBytes = 16 * n;
         if (positionsBytes > this.ctx.caps.limits.maxBufferSize) {
             throw new WebGpuGraphError("E_TOO_LARGE", `${positionsBytes} bytes of positions exceed maxBufferSize`, {
@@ -593,6 +615,7 @@ export class ForceSimulation {
             });
         }
         let core = null;
+        let tiers = null;
         let inputs = null;
         if (n > 0) {
             core = this.ctx.residency.core(snapshot);
@@ -604,6 +627,11 @@ export class ForceSimulation {
                     algorithm: this.model.kind,
                 });
             }
+            // PD-7 (the 7.3 rule): the permutation is bound iff a row of degree >= 32 exists; the view is uploaded
+            // only then, so a low-degree snapshot compiles and runs the same pipelines as before P4
+            if (snapshot.degreeOrder().segmentOffsets[2] > 0) {
+                tiers = degreeTiersOf(this.ctx.residency.view(snapshot, "degreeOrder"));
+            }
             inputs = this.model.inputs(snapshot, this.optionsValue);
             if (inputs.mass.length !== n) {
                 throw invalidArgument("nodeMass", inputs.mass.length, n, `the model resolved ${inputs.mass.length} masses for ${n} nodes`);
@@ -661,8 +689,11 @@ export class ForceSimulation {
         seedPositions(snapshot, positions, this.optionsValue.seed ?? null, this.dimValue, scale, center, range);
         this.uploadPositions(buffers, positions, inputs.mass);
         const weights = this.resolveWeightsBinding(snapshot, core, inputs.weights);
-        const overrides = { ...this.model.overrides(this.optionsValue), ...graphOverrides(core, null, weights) };
-        const resources = this.makeResources(core, weights, buffers);
+        const overrides = {
+            ...this.model.overrides(this.optionsValue),
+            ...graphOverrides(core, tiers?.perm ?? null, weights),
+        };
+        const resources = this.makeResources(core, tiers, weights, buffers);
         this.resources = resources;
         this.startBind(resources, overrides);
         this.settledValue = false;
@@ -885,7 +916,10 @@ export class ForceSimulation {
         this.center = center;
         const { resources, core } = this;
         if (this.stateValue === "loaded" && resources !== null && core !== null && before !== after) {
-            const overrides = { ...this.model.overrides(next), ...graphOverrides(core, null, resources.weights) };
+            const overrides = {
+                ...this.model.overrides(next),
+                ...graphOverrides(core, resources.perm, resources.weights),
+            };
             this.startBind(resources, overrides);
         }
         this.model.onSetParams(patch, this.writer);
@@ -1088,7 +1122,10 @@ export class ForceSimulation {
         }
     }
     /**
-     * The batch's duration in milliseconds: the profiler's pass timings summed when present, else wall time.
+     * The batch's duration in milliseconds: the profiler's pass timings summed when present and complete, else wall
+     * time. The profiler budgets PROFILER_QUERY_SLOTS / 2 passes per batch; the grid tier records three passes per
+     * iteration (P4 PD-16), so a grid batch above (PROFILER_QUERY_SLOTS / 2 - 1) / 3 iterations is timed partially:
+     * its rows stay in `lastPassTimings` but the duration is the wall time, never the sum of a prefix.
      * @param record - the batch
      * @param bytes - its readback (the profiler's resolve lands in it)
      * @returns milliseconds
@@ -1097,7 +1134,8 @@ export class ForceSimulation {
         const { profiler } = this.ctx;
         if (profiler !== null && record.profile !== null) {
             const timings = profiler.timings(bytes, record.profile);
-            if (timings.length > 0) {
+            this.lastPassTimingsValue = timings;
+            if (timings.length > 0 && !profiler.partial(record.profile)) {
                 let ns = 0;
                 for (const timing of timings) {
                     ns += timing.ns;
@@ -1493,23 +1531,26 @@ export class ForceSimulation {
     /**
      * The ModelResources of a load.
      * @param core - the core
+     * @param tiers - the degree tiers, or null when no row has degree >= 32
      * @param weights - the resolved weights binding
      * @param buffers - the buffers
      * @returns the resources
      */
-    makeResources(core, weights, buffers) {
+    makeResources(core, tiers, weights, buffers) {
         const { bindings } = buffers;
         return {
             device: this.ctx.device,
             caps: this.ctx.caps,
             pipelines: this.ctx.pipelines,
             core,
-            perm: null,
+            perm: tiers?.perm ?? null,
+            tiers,
             weights,
             n: this.n,
             dim: this.dimValue,
             tier: this.tierValue,
             ring: this.ring,
+            pool: this.ctx.pool,
             buffer: (name) => {
                 const binding = bindings.get(name);
                 if (binding === undefined) {
@@ -1537,12 +1578,22 @@ export class ForceSimulation {
         this.ready = promise;
     }
     /**
-     * warm(model.specs()) then model.bind(); the await re-checks that the load is current before binding.
+     * assertDeviceComputes() then warm(model.specs()) then model.bind(); the await re-checks that the load is
+     * current before binding.
+     *
+     * The device self-check sits HERE rather than in submitBatch (its first home) because this promise is the one
+     * submitBatch already awaits before every batch: the check is therefore settled before the simulation can
+     * submit a single iteration, yet costs the frame loop nothing per batch. An extra await on the per-batch path
+     * moves the moment a submission becomes visible to a step() issued in the same tick, which is precisely what
+     * coalescing is measured on (test/layouts/frame-loop.test.ts, "a coalesced step() returns the same promise").
+     * A device that computes incorrectly rejects this promise, so the first step() rejects E_DEVICE_INCORRECT
+     * before any position is written; a check that could not RUN rejects with its own error, unchanged.
      * @param resources - the resources
      * @param overrides - the merged override set
      * @param generation - the generation the bind belongs to
      */
     async compileAndBind(resources, overrides, generation) {
+        await assertDeviceComputes(this.ctx);
         const subgroups = this.ctx.caps.features.has("subgroups");
         await this.ctx.pipelines.warm(this.model.specs(overrides, subgroups));
         if (this.stateValue !== "loaded" || generation !== this.generationValue) {
@@ -1552,7 +1603,7 @@ export class ForceSimulation {
     }
     // ---------------------------------------------------------------- private: inspect and debug runs
     /**
-     * inspect(name): flush, read the named buffer back, Uint32Array for "fixed" and "trace", Float32Array otherwise.
+     * inspect(name): flush, read the named buffer back, Uint32Array for the u32 buffers (U32_BUFFER_NAMES), Float32Array otherwise.
      * @param name - a shared or BufferSpec name
      * @returns the words
      */
@@ -1565,7 +1616,7 @@ export class ForceSimulation {
         }
         await this.flush();
         const bytes = await this.ctx.readback.read(binding.buffer, binding.size, undefined, binding.offset);
-        return name === "fixed" || name === "trace" ? new Uint32Array(bytes) : new Float32Array(bytes);
+        return U32_BUFFER_NAMES.has(name) ? new Uint32Array(bytes) : new Float32Array(bytes);
     }
     /**
      * debugRunStages(upTo): one iteration truncated after a stage, submitted alone after flush(), awaited through
@@ -1633,6 +1684,7 @@ export class ForceSimulation {
         this.destroyBuffers();
         this.afterInFlight(() => {
             this.ring.destroy();
+            this.model.dispose?.();
         });
         if (this.ctx.state === "ready") {
             this.ctx.pool.trim();