@graphty/webgpu-graph-algorithms 0.0.0 → 0.2.0

package/dist/webgpu-graph-algorithms.js

@@ -0,0 +1,4454 @@
+import { W as WebGpuGraphError, M as MAX_WORKGROUPS_PER_DIM, a as WGSL_RESERVED_WORDS, S as STATE_HEADER_BYTES, B as BufferUsage, i as isWebGpuGraphError, d as deviceLostError, U as UNIFORM_SLOT_BYTES, F as FA2_DEFAULTS, b as MAX_ITERATIONS_PER_STEP, c as MAX_1D_ITEMS, h as hasErrorCode, e as FA2_FLAG_FIRST, P as PARTIAL_BYTES, L as LAYOUT_TUNING_DEFAULTS, T as TRACE_RECORD_BYTES } from "./chunks/context-E6iKaeuJ.js";
+import { A, E, G, f, g, j, k } from "./chunks/context-E6iKaeuJ.js";
+import { makeMask, maskTest, expandEdges } from "@graphty/graph-format";
+function perDimension(caps) {
+  return Math.min(MAX_WORKGROUPS_PER_DIM, caps.limits.maxComputeWorkgroupsPerDimension);
+}
+function assertCount(argument, value) {
+  if (!Number.isInteger(value) || value < 0) {
+    throw new WebGpuGraphError("E_INVALID_ARGUMENT", `${argument} must be a non-negative integer, got ${value}`, {
+      argument,
+      value,
+      expected: "a non-negative integer"
+    });
+  }
+}
+function assertWorkgroupSize(wg) {
+  let rest = wg;
+  while (Number.isInteger(rest) && rest > 1 && rest % 2 === 0) {
+    rest /= 2;
+  }
+  if (rest !== 1) {
+    throw new WebGpuGraphError("E_INVALID_ARGUMENT", `wg must be a power of two, got ${wg}`, {
+      argument: "wg",
+      value: wg,
+      expected: "a power of two >= 1"
+    });
+  }
+}
+function grid(groups, items, caps) {
+  const limit = perDimension(caps);
+  if (groups === 0) {
+    return { x: 0, y: 1, z: 1, items, stride: null };
+  }
+  if (groups <= limit) {
+    return { x: groups, y: 1, z: 1, items, stride: null };
+  }
+  const y = Math.ceil(groups / limit);
+  if (y > limit) {
+    throw new WebGpuGraphError(
+      "E_TOO_LARGE",
+      `${groups} workgroups exceed the 2D dispatch limit of ${limit * limit}`,
+      {
+        needed: groups,
+        limit: limit * limit,
+        path: "dispatch",
+        algorithm: null,
+        items
+      }
+    );
+  }
+  return { x: limit, y, z: 1, items, stride: null };
+}
+function plan1d(items, wg, caps) {
+  assertCount("items", items);
+  assertWorkgroupSize(wg);
+  return grid(Math.ceil(items / wg), items, caps);
+}
+const TYPE_INFO = Object.freeze({
+  u32: { size: 4, align: 4, width: 1, scalar: "u32" },
+  i32: { size: 4, align: 4, width: 1, scalar: "i32" },
+  f32: { size: 4, align: 4, width: 1, scalar: "f32" },
+  vec2f: { size: 8, align: 8, width: 2, scalar: "f32" },
+  vec2u: { size: 8, align: 8, width: 2, scalar: "u32" },
+  vec4f: { size: 16, align: 16, width: 4, scalar: "f32" },
+  vec4u: { size: 16, align: 16, width: 4, scalar: "u32" }
+});
+const STRUCT_ALIGN = 16;
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const U32_LIMIT = 4294967295;
+const I32_MIN = -2147483648;
+const I32_MAX = 2147483647;
+function roundUp(value, align) {
+  return Math.ceil(value / align) * align;
+}
+function assertIdentifier(argument, name) {
+  if (!IDENTIFIER.test(name) || WGSL_RESERVED_WORDS.includes(name)) {
+    throw new WebGpuGraphError("E_INVALID_ARGUMENT", `UniformBlock: "${name}" is not a usable WGSL identifier`, {
+      argument,
+      value: name,
+      expected: "a WGSL identifier that is not a reserved word"
+    });
+  }
+}
+function assertScalar(field, kind, value) {
+  if (typeof value !== "number") {
+    throw new WebGpuGraphError("E_INVALID_ARGUMENT", `UniformBlock: field "${field}" expects a number`, {
+      argument: field,
+      value,
+      expected: kind
+    });
+  }
+  if (kind === "u32" && !(Number.isInteger(value) && value >= 0 && value <= U32_LIMIT)) {
+    throw new WebGpuGraphError("E_INVALID_ARGUMENT", `UniformBlock: field "${field}" is not a u32`, {
+      argument: field,
+      value,
+      expected: "an integer in [0, 4294967295]"
+    });
+  }
+  if (kind === "i32" && !(Number.isInteger(value) && value >= I32_MIN && value <= I32_MAX)) {
+    throw new WebGpuGraphError("E_INVALID_ARGUMENT", `UniformBlock: field "${field}" is not an i32`, {
+      argument: field,
+      value,
+      expected: "an integer in [-2147483648, 2147483647]"
+    });
+  }
+}
+function setScalar(view, kind, offset, value) {
+  if (kind === "u32") {
+    view.setUint32(offset, value, true);
+  } else if (kind === "i32") {
+    view.setInt32(offset, value, true);
+  } else {
+    view.setFloat32(offset, value, true);
+  }
+}
+function getScalar(view, kind, offset) {
+  if (kind === "u32") {
+    return view.getUint32(offset, true);
+  }
+  if (kind === "i32") {
+    return view.getInt32(offset, true);
+  }
+  return view.getFloat32(offset, true);
+}
+class UniformBlock {
+  /**
+   * Declares a block; fields are laid out in order with 16-byte alignment for vec4 / the struct, 8 for vec2, 4 for
+   * scalars; the total is padded to 16 (uniform, storage) or to `padTo` when given.
+   * PLAN DECISION: rejects an empty field list and a struct or field name that is not a WGSL identifier or is a
+   * reserved word (spec 3.6: every throwing call leaves state unchanged; a reserved name would be invalid WGSL).
+   * PLAN DECISION: optional PARAMETERS (`options?` here, `byteOffset?` of write / read / readField) are spelled
+   * `?: T` rather than the contract's `?: T | undefined` because the root ESLint rule
+   * no-duplicate-type-constituents rejects the explicit undefined on an optional parameter; every call site is
+   * identical, and optional PROPERTIES keep `?: T | undefined`.
+   * @param name - the WGSL struct name
+   * @param fields - the fields in byte order
+   * @param options - the layout tag and the optional padding
+   * @param options.layout - "uniform" (default) or "storage"; the tag documents the address space, the layout is the same
+   * @param options.padTo - the byte length to pad to (a multiple of 16 not below the natural size)
+   * @returns the block
+   */
+  static define(name, fields, options) {
+    assertIdentifier("name", name);
+    if (fields.length === 0) {
+      throw new WebGpuGraphError("E_INVALID_ARGUMENT", `UniformBlock ${name}: a block needs at least one field`, {
+        argument: "fields",
+        value: fields.length,
+        expected: ">= 1 field"
+      });
+    }
+    const laidOut = [];
+    const table = /* @__PURE__ */ new Map();
+    let cursor = 0;
+    for (const [fieldName, type] of fields) {
+      assertIdentifier("fields", fieldName);
+      if (table.has(fieldName)) {
+        throw new WebGpuGraphError(
+          "E_INVALID_ARGUMENT",
+          `UniformBlock ${name}: duplicate field "${fieldName}"`,
+          {
+            argument: "fields",
+            value: fieldName,
+            expected: "unique field names"
+          }
+        );
+      }
+      const info = TYPE_INFO[type];
+      if (info === void 0) {
+        throw new WebGpuGraphError("E_INVALID_ARGUMENT", `UniformBlock ${name}: unknown field type "${type}"`, {
+          argument: "fields",
+          value: type,
+          expected: Object.keys(TYPE_INFO).join(" | ")
+        });
+      }
+      const offset = roundUp(cursor, info.align);
+      const field = { name: fieldName, type, offset, info };
+      laidOut.push(field);
+      table.set(fieldName, field);
+      cursor = offset + info.size;
+    }
+    const natural = roundUp(cursor, STRUCT_ALIGN);
+    const padTo = options?.padTo;
+    if (padTo !== void 0 && (!Number.isInteger(padTo) || padTo % STRUCT_ALIGN !== 0 || padTo < natural)) {
+      throw new WebGpuGraphError(
+        "E_INVALID_ARGUMENT",
+        `UniformBlock ${name}: padTo ${padTo} is not a multiple of 16 >= ${natural}`,
+        {
+          argument: "padTo",
+          value: padTo,
+          expected: `a multiple of ${STRUCT_ALIGN} not below ${natural}`
+        }
+      );
+    }
+    const byteLength = padTo ?? natural;
+    const lines = laidOut.map((field, index) => {
+      const last = index === laidOut.length - 1;
+      const end = field.offset + field.info.size;
+      const size = last && end < byteLength ? `@size(${byteLength - field.offset}) ` : "";
+      return `    ${size}${field.name}: ${field.type},`;
+    });
+    const wgsl = `struct ${name} {
+${lines.join("\n")}
+}`;
+    return new UniformBlock(name, options?.layout ?? "uniform", fields, byteLength, wgsl, laidOut, table);
+  }
+  /**
+   * Built by `define()` only.
+   * @param name - the struct name
+   * @param layout - the address-space tag
+   * @param fields - the declared fields
+   * @param byteLength - the padded byte length
+   * @param wgsl - the struct text
+   * @param laidOut - the laid-out fields in order
+   * @param table - the laid-out fields by name
+   */
+  constructor(name, layout, fields, byteLength, wgsl, laidOut, table) {
+    this.name = name;
+    this.layout = layout;
+    this.fields = Object.freeze(fields.map(([fieldName, type]) => Object.freeze([fieldName, type])));
+    this.byteLength = byteLength;
+    this.wgsl = wgsl;
+    this.laidOut = laidOut;
+    this.table = table;
+  }
+  /**
+   * Byte offset of a field; E_INVALID_ARGUMENT for an unknown field.
+   * @param field - the field name
+   * @returns the byte offset inside the block
+   */
+  offsetOf(field) {
+    return this.fieldLayout(field).offset;
+  }
+  /**
+   * Writes `values` at `byteOffset` (default 0); a missing field is written as 0; an unknown key is
+   * E_INVALID_ARGUMENT; a vector of the wrong width is E_INVALID_ARGUMENT. Always little-endian. Every byte of the
+   * block's region is written (padding as zero), so a written block is byte-exact.
+   * PLAN DECISION: every value is validated first (u32 / vec*u components integers in [0, 2^32 - 1], i32 in
+   * [-2^31, 2^31 - 1]) and only then is the region zeroed and written, so a rejected call leaves the view unchanged.
+   * @param view - the target view (the region must lie inside it)
+   * @param values - the field values
+   * @param byteOffset - the region's start inside the view
+   */
+  write(view, values, byteOffset) {
+    const base = this.regionStart(view, byteOffset);
+    for (const key of Object.keys(values)) {
+      if (!this.table.has(key)) {
+        throw new WebGpuGraphError("E_INVALID_ARGUMENT", `UniformBlock ${this.name}: unknown field "${key}"`, {
+          argument: "values",
+          value: key,
+          expected: this.laidOut.map((f2) => f2.name).join(", ")
+        });
+      }
+    }
+    const components = this.laidOut.map(
+      (field) => this.components(field, values[field.name])
+    );
+    for (let at = 0; at < this.byteLength; at += 4) {
+      view.setUint32(base + at, 0, true);
+    }
+    this.laidOut.forEach((field, index) => {
+      const lanes = components[index];
+      if (lanes === null) {
+        return;
+      }
+      lanes.forEach((component, lane) => {
+        setScalar(view, field.info.scalar, base + field.offset + 4 * lane, component);
+      });
+    });
+  }
+  /**
+   * The validated components of one field's value: null for an absent field, else `width` numbers.
+   * @param field - the laid-out field
+   * @param value - the value given for it (undefined when absent)
+   * @returns the components or null
+   */
+  components(field, value) {
+    if (value === void 0) {
+      return null;
+    }
+    const { scalar: scalar2, width } = field.info;
+    if (width === 1) {
+      assertScalar(field.name, scalar2, value);
+      return [value];
+    }
+    if (!Array.isArray(value) || value.length !== width) {
+      throw new WebGpuGraphError(
+        "E_INVALID_ARGUMENT",
+        `UniformBlock ${this.name}: field "${field.name}" expects ${width} components`,
+        {
+          argument: field.name,
+          value,
+          expected: `an array of ${width} numbers`
+        }
+      );
+    }
+    const lanes = [];
+    for (let lane = 0; lane < width; lane++) {
+      const component = value[lane];
+      assertScalar(field.name, scalar2, component);
+      lanes.push(component);
+    }
+    return lanes;
+  }
+  /**
+   * Reads every field at `byteOffset` (storage mode's reader; also used by tests on uniform blocks).
+   * @param view - the source view
+   * @param byteOffset - the region's start inside the view
+   * @returns the field values (vectors as arrays)
+   */
+  read(view, byteOffset) {
+    const base = this.regionStart(view, byteOffset);
+    const out = {};
+    for (const field of this.laidOut) {
+      out[field.name] = this.decode(view, field, base);
+    }
+    return out;
+  }
+  /**
+   * Reads one field.
+   * @param view - the source view
+   * @param field - the field name
+   * @param byteOffset - the region's start inside the view
+   * @returns the value (a number, or an array for a vector)
+   */
+  readField(view, field, byteOffset) {
+    const layout = this.fieldLayout(field);
+    return this.decode(view, layout, this.regionStart(view, byteOffset));
+  }
+  /**
+   * The laid-out field of a name.
+   * @param field - the field name
+   * @returns the layout
+   */
+  fieldLayout(field) {
+    const layout = this.table.get(field);
+    if (layout === void 0) {
+      throw new WebGpuGraphError("E_INVALID_ARGUMENT", `UniformBlock ${this.name}: unknown field "${field}"`, {
+        argument: "field",
+        value: field,
+        expected: this.laidOut.map((f2) => f2.name).join(", ")
+      });
+    }
+    return layout;
+  }
+  /**
+   * Validates the region `[byteOffset, byteOffset + byteLength)` against the view.
+   * @param view - the view
+   * @param byteOffset - the requested start (default 0)
+   * @returns the start
+   */
+  regionStart(view, byteOffset) {
+    const base = byteOffset ?? 0;
+    if (!Number.isInteger(base) || base < 0 || base + this.byteLength > view.byteLength) {
+      throw new WebGpuGraphError(
+        "E_INVALID_ARGUMENT",
+        `UniformBlock ${this.name}: region [${base}, ${base + this.byteLength}) is outside the view`,
+        {
+          argument: "byteOffset",
+          value: base,
+          expected: `0 <= byteOffset <= ${view.byteLength - this.byteLength}`
+        }
+      );
+    }
+    return base;
+  }
+  /**
+   * Decodes one field from a view.
+   * @param view - the source view
+   * @param field - the laid-out field
+   * @param base - the region start
+   * @returns the value
+   */
+  decode(view, field, base) {
+    const { scalar: scalar2, width } = field.info;
+    if (width === 1) {
+      return getScalar(view, scalar2, base + field.offset);
+    }
+    const lanes = [];
+    for (let lane = 0; lane < width; lane++) {
+      lanes.push(getScalar(view, scalar2, base + field.offset + 4 * lane));
+    }
+    return lanes;
+  }
+}
+const degreeWgsl = (
+  /* wgsl */
+  `
+@compute @workgroup_size(WG)
+fn degree(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let row = linear_id(wid, lid.x) + P.start;
+    if (row >= P.end) { return; }
+    let i = select(row, perm[row], USE_PERM);
+    let a0 = max(rowPtr[i], P.arcBase);
+    let a1 = min(rowPtr[i + 1u], P.arcEnd);
+    var d = 0u;
+    for (var arc = a0; arc < a1; arc = arc + 1u) {
+        let nbr = colIdx[arc - P.arcBase];               // \`target\` is a WGSL reserved word (spec 16.2); never use it as an identifier
+        d = d + select(0u, 1u, nbr < P.n);
+    }
+    out[i] = select(d, out[i] + d, P.accumulate == 1u);
+}
+`
+);
+const fa2AttractionWgsl = (
+  /* wgsl */
+  `fn store_force(i: u32, f: vec3f) {
+    force[3u * i] = f.x;
+    force[3u * i + 1u] = f.y;
+    force[3u * i + 2u] = f.z;
+}
+
+@compute @workgroup_size(WG)
+fn attraction(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let row = linear_id(wid, lid.x) + P.tierStart;
+    if (row >= P.tierEnd) { return; }                          // no barrier follows in this tier (3.5 rule 1)
+    let i = select(row, perm[row], USE_PERM);
+    let pi = pos[i];                                           // xyz + mass in one load (D23)
+    var f = vec3f(0.0);
+    for (var a = rowPtr[i]; a < rowPtr[i + 1u]; a = a + 1u) {
+        let j = colIdx[a];
+        if (j == i) { continue; }                              // a self-loop exerts no force
+        var w = 1.0;
+        if (HAS_WEIGHTS) { w = weights[a]; }
+        let d = pos[j].xyz - pi.xyz;                           // toward j
+        let len = max(length(d), FA2_DIST_FLOOR);
+        let mag = select(w, w * log(1.0 + len) / len, LINLOG); // linear: |F| = w len; linlog: |F| = w log(1 + len)
+        f = f + d * mag;
+    }
+    if (DISTRIBUTED) { f = f / pi.w; }
+    store_force(i, f);                                         // overwrites: attraction is the first writer of force each iteration
+}`
+);
+const fa2IntegrateWgsl = (
+  /* wgsl */
+  `fn load_force(i: u32) -> vec3f { return vec3f(force[3u * i], force[3u * i + 1u], force[3u * i + 2u]); }
+fn load_old(i: u32) -> vec3f { return vec3f(oldForce[3u * i], oldForce[3u * i + 1u], oldForce[3u * i + 2u]); }
+fn store_old(i: u32, f: vec3f) {
+    oldForce[3u * i] = f.x;
+    oldForce[3u * i + 1u] = f.y;
+    oldForce[3u * i + 2u] = f.z;
+}
+
+@compute @workgroup_size(WG)
+fn integrate(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let i = linear_id(wid, lid.x);
+    var dp = vec3f(0.0);
+    var p = vec4f(0.0);
+    var free = false;
+    var valid = false;
+    if (i < P.n) {
+        valid = true;
+        let f = load_force(i);
+        p = pos[i];
+        var swing_i = p.w * length(f);                                     // SWING_MODE 1: NetworkX's local swinging m |F| (layout.py line 1497)
+        if (SWING_MODE == 0u) { swing_i = p.w * length(f - load_old(i)); }  // paper: m |F(t) - F(t-1)|, recomputed inline (7.2)
+        let factor = S.speed / (1.0 + sqrt(S.speed * swing_i));
+        let fixed = mask_bit(fixedMask[i >> 5u], i);
+        dp = select(f * factor, vec3f(0.0), fixed);                        // no clamp on dp (D25)
+        if (P.dim == 2u) { dp.z = 0.0; }                                   // 2D never integrates z (7.13)
+        p = vec4f(p.xyz + dp, p.w);
+        pos[i] = p;
+        if (SWING_MODE == 0u) { store_old(i, f); }                         // fixed nodes too, so a later unpin sees no stale swing (7.11)
+        free = !fixed;
+    }
+    // uniform control flow from here (3.5 rule 1): partials A (sum p, sum |p - c|^2, min, max over valid rows) and C (sum |dp|, free count)
+    let c = S.centroid.xyz;
+    var sumv = vec4f(0.0);
+    var lo = vec4f(F32_MAX);
+    var hi = vec4f(-F32_MAX);
+    var dl = 0.0;
+    var fr = 0u;
+    if (valid) {
+        let q = p.xyz - c;
+        sumv = vec4f(p.xyz, dot(q, q));
+        lo = vec4f(p.xyz, 0.0);
+        hi = vec4f(p.xyz, dot(q, q));                                  // max.w carries max |p - c|^2 so K1 can write the exact layoutRadius (spec 3.3)
+    }
+    if (free) { dl = length(dp); fr = 1u; }
+    let tSum = wg_reduce_vec4(sumv, lid.x, 0u);
+    let tLo = wg_reduce_vec4(lo, lid.x, 1u);
+    let tHi = wg_reduce_vec4(hi, lid.x, 2u);
+    let tDl = wg_reduce_f32(dl, lid.x, 0u);
+    let tFr = wg_reduce_u32(fr, lid.x, 0u);
+    if (lid.x == 0u) {
+        let g = group_id(wid);
+        partials[g].sum = tSum;
+        partials[g].min = tLo;
+        partials[g].max = tHi;
+        partials[g].dispFree = vec2f(tDl, f32(tFr));
+    }
+}`
+);
+const fa2RepulsionExactWgsl = (
+  /* wgsl */
+  `
+var<workgroup> tile: array<vec4f, WG>;                         // xyz + mass, 4 KiB at WG = 256
+
+fn load_force(i: u32) -> vec3f { return vec3f(force[3u * i], force[3u * i + 1u], force[3u * i + 2u]); }
+fn store_force(i: u32, f: vec3f) {
+    force[3u * i] = f.x;
+    force[3u * i + 1u] = f.y;
+    force[3u * i + 2u] = f.z;
+}
+fn load_old(i: u32) -> vec3f { return vec3f(oldForce[3u * i], oldForce[3u * i + 1u], oldForce[3u * i + 2u]); }
+fn gravity_force(pi: vec4f) -> vec3f {                         // spec 7.9: centroid (GRAVITY_CENTER 0) or origin (1); regular or strong
+    var q = pi.xyz;
+    if (GRAVITY_CENTER == 0u) { q = pi.xyz - S.centroid.xyz; }
+    if (STRONG_GRAVITY) { return -P.gravity * pi.w * q; }
+    let d = length(q);
+    if (d > FA2_DIST_FLOOR) { return -P.gravity * pi.w * q / d; }
+    return vec3f(0.0);
+}
+
+@compute @workgroup_size(WG)
+fn repulsion(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let i = linear_id(wid, lid.x);
+    let valid = i < P.n;
+    var pi = vec4f(0.0);
+    if (valid) { pi = pos[i]; }
+    var f = vec3f(0.0);
+    let tiles = (P.n + WG - 1u) / WG;
+    for (var t = 0u; t < tiles; t = t + 1u) {
+        let j = t * WG + lid.x;
+        if (j < P.n) { tile[lid.x] = pos[j]; } else { tile[lid.x] = vec4f(0.0); }   // guarded fill; mass 0 marks the pad
+        workgroupBarrier();                                                       // uniform: every invocation reaches it
+        for (var s = 0u; s < WG; s = s + 1u) {
+            let o = tile[s];
+            let jj = t * WG + s;
+            if (o.w > 0.0 && jj != i) {                                           // mass > 0 for every real node, 0 for the pad
+                let d = pi.xyz - o.xyz;
+                var d2 = dot(d, d);
+                if (d2 < FA2_COINCIDENT_SQ) {                                     // coincident: antisymmetric unit kick of magnitude k m_i m_j / 0.01 (7.2)
+                    f = f + kick_dir(i, jj, P.dim) * (P.scalingRatio * pi.w * o.w / FA2_DIST_FLOOR);
+                    continue;
+                }
+                d2 = max(d2, FA2_DIST_FLOOR_SQ);                                  // d >= 0.01
+                let k = P.scalingRatio * pi.w * o.w;
+                f = f + d * (k / d2);                                             // |F| = k m_i m_j / d along d / d
+            }
+        }
+        workgroupBarrier();
+    }
+    // epilogue (7.9, 7.10): gravity and force += under the guard, the swing / traction reduction outside it
+    var sw = 0.0;
+    var tr = 0.0;
+    if (valid) {
+        f = f + gravity_force(pi);
+        let fnew = load_force(i) + f;
+        store_force(i, fnew);
+        if (SWING_MODE == 1u) {                                                   // NetworkX: positions and forces mixed, every node (7.2)
+            sw = pi.w * length(pi.xyz - fnew);
+            tr = 0.5 * pi.w * length(pi.xyz + fnew);
+        } else if (!mask_bit(fixedMask[i >> 5u], i)) {                            // paper: free nodes only (Gephi ForceAtlas2.java 283-293)
+            let fold = load_old(i);
+            sw = pi.w * length(fnew - fold);
+            tr = 0.5 * pi.w * length(fnew + fold);
+        }
+    }
+    let t = wg_reduce_vec4(vec4f(sw, tr, 0.0, 0.0), lid.x, 0u);                   // uniform control flow: 256 -> 1
+    if (lid.x == 0u) { partials[group_id(wid)].swingTraction = t.xy; }
+}
+`
+);
+const fa2SpeedFinalizeWgsl = (
+  /* wgsl */
+  `
+@compute @workgroup_size(WG)
+fn speed_finalize(@builtin(local_invocation_id) lid: vec3<u32>) {
+    let groups = (P.n + WG - 1u) / WG;
+    var st = vec2f(0.0);
+    for (var g = lid.x; g < groups; g = g + WG) { st = st + partials[g].swingTraction; }   // sequential per lane: deterministic
+    let t = wg_reduce_vec4(vec4f(st, 0.0, 0.0), lid.x, 0u);
+    if (lid.x == 0u) {
+        var swing = t.x;
+        var traction = t.y;
+        if (SWING_MODE == 1u) { swing = S.swing + t.x; traction = S.traction + t.y; }   // NetworkX accumulates across iterations from 1
+        let n = f32(P.n);
+        let optJitter = 0.05 * sqrt(n);
+        let minJitter = sqrt(optJitter);
+        let maxJitter = 10.0;
+        let tr = max(traction, 1.0e-30);                                             // guards the division only (7.10)
+        let other = min(maxJitter, optJitter * traction / (n * n));
+        var jitter = P.jitterTolerance * max(minJitter, other);
+        var eff = S.speedEfficiency;
+        if (swing > 2.0 * tr) {                                                      // swing / traction > 2 in the exact form (contract 4.5 CONTRACT DECISION K4-1: 2 x is exact, a WGSL f32 division is not)
+            if (eff > 0.05) { eff = eff * 0.5; }                                     // the CPU's conditional multiply (7.2)
+            jitter = max(jitter, P.jitterTolerance);
+        }
+        let targetSpeed = select(jitter * eff * traction / swing, 1.0e30, swing == 0.0);  // +Inf in the port; 1e30 gives the same min() below (\`target\` is reserved)
+        if (swing > jitter * traction) {
+            if (eff > 0.05) { eff = eff * 0.7; }
+        } else if (S.speed < 1000.0) {
+            eff = eff * 1.3;
+        }
+        S.speed = S.speed + min(targetSpeed - S.speed, 0.5 * S.speed);
+        S.speedEfficiency = eff;
+        S.swing = swing;
+        S.traction = traction;
+        T[P.iterationIndex].swing = swing;
+        T[P.iterationIndex].traction = traction;
+        T[P.iterationIndex].speed = S.speed;
+        T[P.iterationIndex].speedEfficiency = eff;
+    }
+}
+`
+);
+const fa2StatsFinalizeWgsl = (
+  /* wgsl */
+  `// K1: folds the previous integrate's partials into the state block (spec 7.4); one workgroup
+@compute @workgroup_size(WG)
+fn stats_finalize(@builtin(local_invocation_id) lid: vec3<u32>) {
+    let groups = (P.n + WG - 1u) / WG;
+    let fold = (P.flags & FA2_FLAG_FIRST) == 0u;    // the first iteration after load() keeps the host-written state
+    var sum = vec4f(0.0);
+    var lo = vec4f(F32_MAX);
+    var hi = vec4f(-F32_MAX);
+    var disp = 0.0;
+    var free = 0u;
+    if (fold) {
+        for (var g = lid.x; g < groups; g = g + WG) {   // sequential per lane in index order: deterministic
+            let q = partials[g];
+            sum = sum + q.sum;
+            lo = min(lo, q.min);
+            hi = max(hi, q.max);
+            disp = disp + q.dispFree.x;
+            free = free + u32(q.dispFree.y);
+        }
+    }
+    let tSum = wg_reduce_vec4(sum, lid.x, 0u);
+    let tLo = wg_reduce_vec4(lo, lid.x, 1u);
+    let tHi = wg_reduce_vec4(hi, lid.x, 2u);
+    let tDisp = wg_reduce_f32(disp, lid.x, 0u);
+    let tFree = wg_reduce_u32(free, lid.x, 0u);
+    if (lid.x == 0u) {
+        if (fold) {
+            let n = f32(P.n);
+            let c = tSum.xyz / n;
+            S.centroid = vec4f(c, 0.0);
+            S.rmsRadius = sqrt(max(tSum.w, 0.0) / n);                  // RMS radius about the previous centroid (7.17)
+            S.min = vec4f(tLo.xyz, 0.0);
+            S.max = vec4f(tHi.xyz, 0.0);
+            S.radius = sqrt(max(tHi.w, 0.0));                          // max |p - centroid| about the same previous centroid as rmsRadius (K5 puts |q|^2 in max.w)
+            let meanDisp = select(tDisp / f32(tFree), 0.0, tFree == 0u);  // all-fixed: 0, never NaN (7.4)
+            S.meanDisplacement = meanDisp;
+            S.settledCount = select(0u, S.settledCount + 1u, meanDisp <= P.settleThreshold * S.rmsRadius);
+        }
+        S.iteration = S.iteration + 1u;
+        T[P.iterationIndex].meanDisplacement = S.meanDisplacement;
+        T[P.iterationIndex].settledCount = S.settledCount;
+        T[P.iterationIndex].iteration = S.iteration;
+    }
+}`
+);
+const fa2ToSceneWgsl = (
+  /* wgsl */
+  `@compute @workgroup_size(WG)
+fn to_scene(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let i = linear_id(wid, lid.x);
+    if (i >= P.n) { return; }
+    let s = pos[i].xyz * P.scale + P.center.xyz;
+    scene[3u * i] = s.x;
+    scene[3u * i + 1u] = s.y;
+    scene[3u * i + 2u] = select(s.z, P.center.z, P.dim == 2u);       // 2D writes z = center.z on every readback (7.13)
+}`
+);
+const fillWgsl = (
+  /* wgsl */
+  `
+@compute @workgroup_size(WG)
+fn fill(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let i = linear_id(wid, lid.x);
+    if (i >= P.count) { return; }
+    dst[i] = select(P.value, i + P.value, P.mode == 1u);
+}
+`
+);
+const reduceWgsl = (
+  /* wgsl */
+  `
+// DTYPE 0 = f32, 1 = u32, 2 = vec4f (4 words per element); OP 0 = sum, 1 = min, 2 = max; FINAL = the one-workgroup level
+fn identity_f() -> f32 { if (OP == 1u) { return F32_MAX; } if (OP == 2u) { return -F32_MAX; } return 0.0; }
+fn identity_u() -> u32 { if (OP == 1u) { return U32_MAX; } return 0u; }        // U32_MAX from the prelude: the literal is forbidden in bodies (4.1)
+fn comb_f(a: f32, b: f32) -> f32 { if (OP == 1u) { return min(a, b); } if (OP == 2u) { return max(a, b); } return a + b; }
+fn comb_u(a: u32, b: u32) -> u32 { if (OP == 1u) { return min(a, b); } if (OP == 2u) { return max(a, b); } return a + b; }
+fn comb_v(a: vec4f, b: vec4f) -> vec4f { if (OP == 1u) { return min(a, b); } if (OP == 2u) { return max(a, b); } return a + b; }
+fn load_f(i: u32) -> f32 { return bitcast<f32>(src[i]); }
+fn load_v(i: u32) -> vec4f {
+    return vec4f(bitcast<f32>(src[4u * i]), bitcast<f32>(src[4u * i + 1u]), bitcast<f32>(src[4u * i + 2u]), bitcast<f32>(src[4u * i + 3u]));
+}
+fn store_f(i: u32, v: f32) { out[i] = bitcast<u32>(v); }
+fn store_v(i: u32, v: vec4f) {
+    out[4u * i] = bitcast<u32>(v.x);
+    out[4u * i + 1u] = bitcast<u32>(v.y);
+    out[4u * i + 2u] = bitcast<u32>(v.z);
+    out[4u * i + 3u] = bitcast<u32>(v.w);
+}
+
+@compute @workgroup_size(WG)
+fn reduce(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    var accF = identity_f();
+    var accU = identity_u();
+    var accV = vec4f(identity_f());
+    if (FINAL) {
+        for (var i = lid.x; i < P.count; i = i + WG) {           // sequential per lane in index order: deterministic
+            if (DTYPE == 0u) { accF = comb_f(accF, load_f(i)); }
+            else if (DTYPE == 1u) { accU = comb_u(accU, src[i]); }
+            else { accV = comb_v(accV, load_v(i)); }
+        }
+    } else {
+        let i = linear_id(wid, lid.x);
+        if (i < P.count) {
+            if (DTYPE == 0u) { accF = load_f(i); }
+            else if (DTYPE == 1u) { accU = src[i]; }
+            else { accV = load_v(i); }
+        }
+    }
+    // uniform control flow: the workgroup reduction of the selected dtype (DTYPE is a pipeline constant, so the branch is uniform)
+    var tF = 0.0;
+    var tU = 0u;
+    var tV = vec4f(0.0);
+    if (DTYPE == 0u) { tF = wg_reduce_f32(accF, lid.x, OP); }
+    else if (DTYPE == 1u) { tU = wg_reduce_u32(accU, lid.x, OP); }
+    else { tV = wg_reduce_vec4(accV, lid.x, OP); }
+    if (lid.x == 0u) {
+        let g = select(group_id(wid), 0u, FINAL);
+        let o = P.outOffset + g;
+        if (DTYPE == 0u) { store_f(o, tF); }
+        else if (DTYPE == 1u) { out[o] = tU; }
+        else { store_v(o, tV); }
+    }
+}
+`
+);
+const segmentedReduceWgsl = (
+  /* wgsl */
+  `
+fn identity() -> f32 { if (OP == 1u) { return F32_MAX; } if (OP == 2u) { return -F32_MAX; } return 0.0; }
+fn comb(a: f32, b: f32) -> f32 { if (OP == 1u) { return min(a, b); } if (OP == 2u) { return max(a, b); } return a + b; }
+
+@compute @workgroup_size(WG)
+fn segmented_reduce(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let row = linear_id(wid, lid.x) + P.start;
+    if (row >= P.end) { return; }
+    let i = select(row, perm[row], USE_PERM);
+    let a0 = max(rowPtr[i], P.arcBase);
+    let a1 = min(rowPtr[i + 1u], P.arcEnd);
+    var acc = identity();
+    for (var arc = a0; arc < a1; arc = arc + 1u) {
+        let nbr = colIdx[arc - P.arcBase];               // the neighbour index (\`target\` is a WGSL reserved word)
+        var weight = 1.0;
+        if (HAS_WEIGHTS) { weight = weights[arc - P.arcBase]; }
+        var v = 0.0;
+        //@@VALUE@@
+        acc = comb(acc, v);
+    }
+    out[i] = select(acc, comb(out[i], acc), P.accumulate == 1u);
+}
+`
+);
+const RANGE_PARAMS = UniformBlock.define("RangeParams", [
+  ["start", "u32"],
+  ["end", "u32"],
+  ["arcBase", "u32"],
+  ["arcEnd", "u32"],
+  ["accumulate", "u32"],
+  ["n", "u32"],
+  ["pad0", "u32"],
+  ["pad1", "u32"]
+]);
+const REDUCE_PARAMS = UniformBlock.define("ReduceParams", [
+  ["count", "u32"],
+  ["outOffset", "u32"],
+  ["level", "u32"],
+  ["pad0", "u32"]
+]);
+const FILL_PARAMS = UniformBlock.define("FillParams", [
+  ["count", "u32"],
+  ["value", "u32"],
+  ["mode", "u32"],
+  ["pad0", "u32"]
+]);
+const FA2_PARAMS = UniformBlock.define("Fa2Params", [
+  ["n", "u32"],
+  ["dim", "u32"],
+  ["flags", "u32"],
+  ["tierStart", "u32"],
+  ["tierEnd", "u32"],
+  ["iterationIndex", "u32"],
+  ["seed", "u32"],
+  ["nearMax", "u32"],
+  ["scalingRatio", "f32"],
+  ["gravity", "f32"],
+  ["jitterTolerance", "f32"],
+  ["scale", "f32"],
+  ["center", "vec4f"],
+  ["settleThreshold", "f32"],
+  ["extentFactor", "f32"],
+  ["gridMax", "u32"],
+  ["levels", "u32"],
+  ["pad", "vec4f"]
+]);
+const FA2_STATE = UniformBlock.define(
+  "Fa2State",
+  [
+    ["speed", "f32"],
+    ["speedEfficiency", "f32"],
+    ["swing", "f32"],
+    ["traction", "f32"],
+    ["centroid", "vec4f"],
+    ["rmsRadius", "f32"],
+    ["radius", "f32"],
+    ["meanDisplacement", "f32"],
+    ["iteration", "u32"],
+    ["min", "vec4f"],
+    ["max", "vec4f"],
+    ["gridMin", "vec4f"],
+    ["eps", "f32"],
+    ["settledCount", "u32"],
+    ["outsideGrid", "u32"],
+    ["maxCellOccupancy", "u32"],
+    ["reserved0", "vec4f"],
+    ["reserved1", "vec4f"],
+    ["reserved2", "vec4f"],
+    ["reserved3", "vec4f"],
+    ["reserved4", "vec4f"],
+    ["reserved5", "vec4f"],
+    ["reserved6", "vec4f"],
+    ["reserved7", "vec4f"],
+    ["reserved8", "vec4f"]
+  ],
+  { layout: "storage", padTo: STATE_HEADER_BYTES }
+);
+const FA2_TRACE = UniformBlock.define(
+  "Fa2Trace",
+  [
+    ["swing", "f32"],
+    ["traction", "f32"],
+    ["speed", "f32"],
+    ["speedEfficiency", "f32"],
+    ["meanDisplacement", "f32"],
+    ["settledCount", "u32"],
+    ["iteration", "u32"],
+    ["pad0", "u32"]
+  ],
+  { layout: "storage" }
+);
+const FA2_PARTIAL = UniformBlock.define(
+  "Fa2Partial",
+  [
+    ["sum", "vec4f"],
+    ["min", "vec4f"],
+    ["max", "vec4f"],
+    ["swingTraction", "vec2f"],
+    ["dispFree", "vec2f"]
+  ],
+  { layout: "storage" }
+);
+function decl(group, binding, name, kind, wgslType) {
+  return { group, binding, name, kind, wgslType };
+}
+const GRAPH_SLOTS = [
+  decl(0, 0, "rowPtr", "storage-ro", "array<u32>"),
+  decl(0, 1, "colIdx", "storage-ro", "array<u32>"),
+  decl(0, 2, "weights", "storage-ro", "array<f32>"),
+  decl(0, 3, "perm", "storage-ro", "array<u32>")
+];
+const DEGREE = {
+  id: "degree",
+  body: degreeWgsl,
+  entryPoint: "degree",
+  bindings: GRAPH_SLOTS.concat(decl(1, 0, "out", "storage", "array<u32>"), decl(2, 0, "P", "uniform", "RangeParams")),
+  overrideDecls: [],
+  uniforms: [RANGE_PARAMS],
+  needs: [],
+  snippetSlots: [],
+  phase: "P1"
+};
+const REDUCE = {
+  id: "reduce",
+  body: reduceWgsl,
+  entryPoint: "reduce",
+  bindings: [
+    decl(1, 0, "src", "storage-ro", "array<u32>"),
+    decl(1, 1, "out", "storage", "array<u32>"),
+    decl(2, 0, "P", "uniform", "ReduceParams")
+  ],
+  overrideDecls: [
+    { name: "OP", type: "u32", default: 0 },
+    { name: "DTYPE", type: "u32", default: 0 },
+    { name: "FINAL", type: "bool", default: false }
+  ],
+  uniforms: [REDUCE_PARAMS],
+  needs: ["subgroups"],
+  snippetSlots: [],
+  phase: "P1"
+};
+const FILL = {
+  id: "fill",
+  body: fillWgsl,
+  entryPoint: "fill",
+  bindings: [decl(1, 0, "dst", "storage", "array<u32>"), decl(2, 0, "P", "uniform", "FillParams")],
+  overrideDecls: [],
+  uniforms: [FILL_PARAMS],
+  needs: [],
+  snippetSlots: [],
+  phase: "P1"
+};
+const SEGMENTED_REDUCE = {
+  id: "segmented-reduce",
+  body: segmentedReduceWgsl,
+  entryPoint: "segmented_reduce",
+  bindings: GRAPH_SLOTS.concat(decl(1, 0, "out", "storage", "array<f32>"), decl(2, 0, "P", "uniform", "RangeParams")),
+  overrideDecls: [
+    { name: "OP", type: "u32", default: 0 },
+    { name: "TIER", type: "u32", default: 0 }
+  ],
+  uniforms: [RANGE_PARAMS],
+  needs: [],
+  snippetSlots: ["VALUE"],
+  phase: "P2"
+};
+const FA2_STATS_FINALIZE = {
+  id: "fa2-stats-finalize",
+  body: fa2StatsFinalizeWgsl,
+  entryPoint: "stats_finalize",
+  bindings: [
+    decl(1, 0, "partials", "storage-ro", "array<Fa2Partial>"),
+    decl(1, 1, "S", "storage", "Fa2State"),
+    decl(1, 2, "T", "storage", "array<Fa2Trace>"),
+    decl(2, 0, "P", "uniform", "Fa2Params")
+  ],
+  overrideDecls: [],
+  uniforms: [FA2_PARAMS, FA2_STATE, FA2_TRACE, FA2_PARTIAL],
+  needs: ["subgroups"],
+  snippetSlots: [],
+  phase: "P3"
+};
+const FA2_ATTRACTION = {
+  id: "fa2-attraction",
+  body: fa2AttractionWgsl,
+  entryPoint: "attraction",
+  bindings: GRAPH_SLOTS.concat(
+    decl(1, 0, "pos", "storage-ro", "array<vec4f>"),
+    decl(1, 1, "force", "storage", "array<f32>"),
+    decl(2, 0, "P", "uniform", "Fa2Params")
+  ),
+  overrideDecls: [
+    { name: "LINLOG", type: "bool", default: false },
+    { name: "DISTRIBUTED", type: "bool", default: false },
+    { name: "TIER", type: "u32", default: 0 }
+  ],
+  uniforms: [FA2_PARAMS],
+  needs: [],
+  snippetSlots: [],
+  phase: "P3"
+};
+const FA2_REPULSION_EXACT = {
+  id: "fa2-repulsion-exact",
+  body: fa2RepulsionExactWgsl,
+  entryPoint: "repulsion",
+  bindings: [
+    decl(1, 0, "pos", "storage-ro", "array<vec4f>"),
+    decl(1, 1, "S", "storage", "Fa2State"),
+    decl(1, 2, "force", "storage", "array<f32>"),
+    decl(1, 3, "oldForce", "storage-ro", "array<f32>"),
+    decl(1, 4, "fixedMask", "storage-ro", "array<u32>"),
+    decl(1, 5, "partials", "storage", "array<Fa2Partial>"),
+    decl(2, 0, "P", "uniform", "Fa2Params")
+  ],
+  overrideDecls: [
+    { name: "SWING_MODE", type: "u32", default: 0 },
+    { name: "STRONG_GRAVITY", type: "bool", default: false },
+    { name: "GRAVITY_CENTER", type: "u32", default: 0 }
+  ],
+  uniforms: [FA2_PARAMS, FA2_STATE, FA2_PARTIAL],
+  needs: ["subgroups"],
+  snippetSlots: [],
+  phase: "P1"
+};
+const FA2_SPEED_FINALIZE = {
+  id: "fa2-speed-finalize",
+  body: fa2SpeedFinalizeWgsl,
+  entryPoint: "speed_finalize",
+  bindings: [
+    decl(1, 0, "partials", "storage-ro", "array<Fa2Partial>"),
+    decl(1, 1, "S", "storage", "Fa2State"),
+    decl(1, 2, "T", "storage", "array<Fa2Trace>"),
+    decl(2, 0, "P", "uniform", "Fa2Params")
+  ],
+  overrideDecls: [{ name: "SWING_MODE", type: "u32", default: 0 }],
+  uniforms: [FA2_PARAMS, FA2_STATE, FA2_TRACE, FA2_PARTIAL],
+  needs: ["subgroups"],
+  snippetSlots: [],
+  phase: "P1"
+};
+const FA2_INTEGRATE = {
+  id: "fa2-integrate",
+  body: fa2IntegrateWgsl,
+  entryPoint: "integrate",
+  bindings: [
+    decl(1, 0, "force", "storage-ro", "array<f32>"),
+    decl(1, 1, "oldForce", "storage", "array<f32>"),
+    decl(1, 2, "fixedMask", "storage-ro", "array<u32>"),
+    decl(1, 3, "S", "storage", "Fa2State"),
+    decl(1, 4, "pos", "storage", "array<vec4f>"),
+    decl(1, 5, "partials", "storage", "array<Fa2Partial>"),
+    decl(2, 0, "P", "uniform", "Fa2Params")
+  ],
+  overrideDecls: [{ name: "SWING_MODE", type: "u32", default: 0 }],
+  uniforms: [FA2_PARAMS, FA2_STATE, FA2_PARTIAL],
+  needs: ["subgroups"],
+  snippetSlots: [],
+  phase: "P3"
+};
+const FA2_TO_SCENE = {
+  id: "fa2-to-scene",
+  body: fa2ToSceneWgsl,
+  entryPoint: "to_scene",
+  bindings: [
+    decl(1, 0, "pos", "storage-ro", "array<vec4f>"),
+    decl(1, 1, "scene", "storage", "array<f32>"),
+    decl(2, 0, "P", "uniform", "Fa2Params")
+  ],
+  overrideDecls: [],
+  uniforms: [FA2_PARAMS],
+  needs: [],
+  snippetSlots: [],
+  phase: "P3"
+};
+const REGISTRY = Object.freeze({
+  degree: DEGREE,
+  reduce: REDUCE,
+  fill: FILL,
+  "segmented-reduce": SEGMENTED_REDUCE,
+  "fa2-stats-finalize": FA2_STATS_FINALIZE,
+  "fa2-attraction": FA2_ATTRACTION,
+  "fa2-repulsion-exact": FA2_REPULSION_EXACT,
+  "fa2-speed-finalize": FA2_SPEED_FINALIZE,
+  "fa2-integrate": FA2_INTEGRATE,
+  "fa2-to-scene": FA2_TO_SCENE
+});
+const bodyOverrides = /* @__PURE__ */ new Map();
+function entryOf(id) {
+  const entry = REGISTRY[id];
+  if (entry === void 0) {
+    throw new WebGpuGraphError("E_INVALID_ARGUMENT", `unknown kernel id "${id}"`, {
+      argument: "id",
+      value: id,
+      expected: Object.keys(REGISTRY)
+    });
+  }
+  return entry;
+}
+function kernelSpec(id, overrides, snippets) {
+  const entry = entryOf(id);
+  return {
+    id: entry.id,
+    body: bodyOverrides.get(id) ?? entry.body,
+    bindings: entry.bindings,
+    overrideDecls: entry.overrideDecls,
+    overrides: overrides ?? {},
+    needs: entry.needs,
+    uniforms: entry.uniforms,
+    snippets
+  };
+}
+function graphBindings(core, perm, weights) {
+  const colIdx = core.colIdx ?? core.rowPtr;
+  const resolved = weights === void 0 ? core.weights : weights;
+  return {
+    rowPtr: core.rowPtr,
+    colIdx,
+    weights: resolved ?? colIdx,
+    perm: perm ?? core.rowPtr
+  };
+}
+function graphOverrides(core, perm, weights) {
+  const resolved = weights === void 0 ? core.weights : weights;
+  return { USE_PERM: perm !== null, HAS_WEIGHTS: resolved !== null };
+}
+function checkDest(dest, n) {
+  if (dest === void 0) {
+    return null;
+  }
+  if (dest instanceof Uint32Array && dest.length === n && dest.buffer instanceof ArrayBuffer) {
+    return dest;
+  }
+  throw new WebGpuGraphError(
+    "E_INVALID_ARGUMENT",
+    `degree: dest must be a Uint32Array of length ${n} over an ArrayBuffer`,
+    {
+      argument: "dest",
+      value: `${dest.constructor.name}(${dest.length})`,
+      expected: `Uint32Array(${n}) over an ArrayBuffer`
+    }
+  );
+}
+function coreOf(ctx, s) {
+  try {
+    return ctx.residency.core(s);
+  } catch (error) {
+    if (isWebGpuGraphError(error) && error.code === "E_TOO_LARGE" && error.details.path === "windowed") {
+      throw new WebGpuGraphError(
+        "E_TOO_LARGE",
+        "degree: the arc arrays need a windowed upload, which P1-P3 plan but do not execute",
+        { ...error.details, algorithm: "degree" }
+      );
+    }
+    throw error;
+  }
+}
+async function degree(ctx, s, options) {
+  ctx.assertReady();
+  const n = s.nodeCount;
+  const dest = checkDest(options?.dest, n);
+  if (options?.signal?.aborted) {
+    throw new WebGpuGraphError("E_ABORTED", "degree: the signal was aborted before any work started", {});
+  }
+  if (n === 0) {
+    options?.onProgress?.(1, 1);
+    return dest ?? new Uint32Array(0);
+  }
+  const core = coreOf(ctx, s);
+  if (s.arcCount === 0) {
+    const zeros = dest ?? new Uint32Array(n);
+    zeros.fill(0);
+    options?.onProgress?.(1, 1);
+    return zeros;
+  }
+  const byteLength = n * 4;
+  const out = ctx.pool.acquire(
+    byteLength,
+    BufferUsage.STORAGE | BufferUsage.COPY_SRC | BufferUsage.COPY_DST,
+    "degree/out"
+  );
+  const params = ctx.pool.acquire(
+    RANGE_PARAMS.byteLength,
+    BufferUsage.UNIFORM | BufferUsage.COPY_DST,
+    "degree/params"
+  );
+  try {
+    await ctx.allocator.check();
+    const kernel = await ctx.pipelines.kernel(kernelSpec("degree", graphOverrides(core, null)));
+    const bytes = new ArrayBuffer(RANGE_PARAMS.byteLength);
+    RANGE_PARAMS.write(new DataView(bytes), { start: 0, end: n, arcBase: 0, arcEnd: s.arcCount, accumulate: 0, n });
+    ctx.device.queue.writeBuffer(params, 0, bytes);
+    const outBinding = { buffer: out, offset: 0, size: byteLength, window: null };
+    const paramsBinding = { buffer: params, offset: 0, size: RANGE_PARAMS.byteLength, window: null };
+    const bound = kernel.bind({ ...graphBindings(core, null), out: outBinding, P: paramsBinding });
+    const encoder = ctx.device.createCommandEncoder({ label: "degree" });
+    const pass = encoder.beginComputePass({ label: "degree" });
+    kernel.dispatch(pass, bound, plan1d(n, ctx.workgroupSize, ctx.caps), [0]);
+    pass.end();
+    ctx.device.queue.submit([encoder.finish()]);
+    ctx.assertReady();
+    const result = await ctx.readback.read(out, byteLength, dest ?? void 0);
+    ctx.assertReady();
+    options?.onProgress?.(1, 1);
+    return dest ?? new Uint32Array(result);
+  } finally {
+    ctx.pool.release(params);
+    ctx.pool.release(out);
+  }
+}
+const LOSS_GRACE_MS = 2e3;
+async function settled(pending, graceMs) {
+  let timer;
+  const grace = new Promise((resolve) => {
+    timer = setTimeout(resolve, graceMs);
+  });
+  await Promise.race([
+    pending.then(
+      () => void 0,
+      () => void 0
+    ),
+    grace
+  ]);
+  clearTimeout(timer);
+}
+function messageOf(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  if (typeof error === "string") {
+    return error;
+  }
+  return `non-error thrown (${typeof error})`;
+}
+class CommandBatch {
+  /**
+   * Creates the encoder; the id comes from host.nextBatchId().
+   * @param host - the owner (the GpuContext)
+   * @param label - names the encoder, its passes and the E_VALIDATION details
+   * @param generation - the simulation generation the batch carries (default 0)
+   */
+  constructor(host, label, generation) {
+    this.requests = [];
+    this.openPass = null;
+    this.dispatchCount = 0;
+    this.stagingBytes = 0;
+    this.slot = null;
+    this.submitted = false;
+    this.host = host;
+    this.id = host.nextBatchId();
+    this.generation = generation ?? 0;
+    this.label = label;
+    this.encoder = host.device.createCommandEncoder({ label: `batch/${label}#${this.id}` });
+  }
+  /**
+   * Dispatch count recorded so far (tests bound it).
+   * @returns the number of dispatchWorkgroups / dispatchWorkgroupsIndirect calls on this batch's passes
+   */
+  get dispatches() {
+    return this.dispatchCount;
+  }
+  /**
+   * Begins a compute pass (ending the previous one); with a profiler present the pass carries timestampWrites and
+   * `label` names it in Profiler.resolveInto / timings.
+   * @param label - the pass name
+   * @returns the pass encoder kernels dispatch into
+   */
+  pass(label) {
+    this.assertOpen("pass");
+    this.endPass();
+    const descriptor = { label: `batch/${this.label}#${this.id}/${label}` };
+    const timestampWrites = this.host.profiler?.beginPass(label);
+    if (timestampWrites !== void 0) {
+      descriptor.timestampWrites = timestampWrites;
+    }
+    const pass = this.encoder.beginComputePass(descriptor);
+    this.countDispatches(pass);
+    this.openPass = pass;
+    return pass;
+  }
+  /** Ends the open pass, if any. */
+  endPass() {
+    if (this.openPass !== null) {
+      this.openPass.end();
+      this.openPass = null;
+    }
+  }
+  /**
+   * copyBufferToBuffer between two bindings (after endPass).
+   * @param src - the source range
+   * @param dst - the destination range
+   * @param byteLength - a positive multiple of 4 no larger than either binding
+   */
+  copy(src, dst, byteLength) {
+    this.assertOpen("copy");
+    this.checkByteLength(byteLength);
+    if (byteLength > src.size || byteLength > dst.size) {
+      throw new WebGpuGraphError(
+        "E_INVALID_ARGUMENT",
+        `copy of ${byteLength} bytes exceeds a binding (src ${src.size}, dst ${dst.size})`,
+        {
+          argument: "byteLength",
+          value: byteLength,
+          expected: `<= ${Math.min(src.size, dst.size)}`
+        }
+      );
+    }
+    this.endPass();
+    this.encoder.copyBufferToBuffer(src.buffer, src.offset, dst.buffer, dst.offset, byteLength);
+  }
+  /**
+   * Schedules a copy of `byteLength` bytes from `src` into the borrowed staging slot; the slot is borrowed at the
+   * first request and re-borrowed larger when the sum of requests outgrows it (nothing is recorded before submit).
+   * @param src - the source buffer
+   * @param srcOffset - a non-negative multiple of 4
+   * @param byteLength - a positive multiple of 4 with srcOffset + byteLength <= src.size
+   * @returns the request; `offset` is where the caller reads inside the readback bytes
+   */
+  readback(src, srcOffset, byteLength) {
+    this.assertOpen("readback");
+    this.checkByteLength(byteLength);
+    if (!Number.isInteger(srcOffset) || srcOffset < 0 || srcOffset % 4 !== 0 || srcOffset + byteLength > src.size) {
+      throw new WebGpuGraphError(
+        "E_INVALID_ARGUMENT",
+        `readback of [${srcOffset}, ${srcOffset + byteLength}) is outside the ${src.size}-byte source or not 4-aligned`,
+        {
+          argument: "srcOffset",
+          value: srcOffset,
+          expected: `a multiple of 4 with srcOffset + byteLength <= ${src.size}`
+        }
+      );
+    }
+    const request = { src, srcOffset, byteLength, offset: this.stagingBytes };
+    this.requests.push(request);
+    this.stagingBytes += byteLength;
+    this.ensureSlot(this.stagingBytes);
+    return request;
+  }
+  /**
+   * Records `resolveQuerySet` after ending the open pass; used by Profiler.resolveInto only.
+   * @internal
+   * @param querySet - the timestamp query set
+   * @param firstQuery - first query index
+   * @param queryCount - number of queries
+   * @param destination - a QUERY_RESOLVE | COPY_SRC buffer written at offset 0
+   */
+  resolveQuerySet(querySet, firstQuery, queryCount, destination) {
+    this.assertOpen("resolveQuerySet");
+    this.endPass();
+    this.encoder.resolveQuerySet(querySet, firstQuery, queryCount, destination, 0);
+  }
+  /**
+   * Ends passes, records the staging copies, submits, checks the pending-error slot (spec 5.7), returns the handle.
+   * A batch can be submitted once; submit() after device loss throws E_DEVICE_LOST.
+   * @returns the submitted-batch handle
+   */
+  submit() {
+    this.assertOpen("submit");
+    this.submitted = true;
+    this.endPass();
+    const { slot } = this;
+    const pendingBefore = this.host.takePendingError();
+    try {
+      this.host.assertReady();
+    } catch (error) {
+      this.releaseSlot();
+      throw error;
+    }
+    if (slot !== null) {
+      for (const request of this.requests) {
+        this.encoder.copyBufferToBuffer(
+          request.src,
+          request.srcOffset,
+          slot.buffer,
+          request.offset,
+          request.byteLength
+        );
+      }
+    }
+    const commandBuffer = this.encoder.finish({ label: `batch/${this.label}#${this.id}` });
+    this.host.device.queue.submit([commandBuffer]);
+    const pendingAfter = this.host.takePendingError();
+    const pending = pendingBefore ?? pendingAfter;
+    const state = { discarded: false };
+    const readback = pending === null ? this.awaitReadback(slot, state) : this.rejectReadback(pending);
+    return {
+      id: this.id,
+      generation: this.generation,
+      readback,
+      discard: () => {
+        state.discarded = true;
+      }
+    };
+  }
+  rejectReadback(pending) {
+    this.releaseSlot();
+    return Promise.reject(this.attribute(pending));
+  }
+  async awaitReadback(slot, state) {
+    if (slot === null) {
+      await this.host.allocator.check();
+      return new ArrayBuffer(0);
+    }
+    const total = this.stagingBytes;
+    let unregister = () => void 0;
+    const lost = new Promise((_resolve, reject) => {
+      unregister = this.host.onLost((info) => {
+        reject(deviceLostError(info));
+      });
+    });
+    void lost.catch(() => void 0);
+    const mapped = this.host.readback.mapSlot(slot, total);
+    void mapped.catch(() => void 0);
+    let bytes;
+    try {
+      await Promise.race([mapped, lost]);
+      this.host.assertReady();
+      bytes = state.discarded ? new ArrayBuffer(0) : slot.buffer.getMappedRange(0, total).slice(0);
+    } catch (error) {
+      await settled(mapped, LOSS_GRACE_MS);
+      this.releaseSlot();
+      throw await this.classify(error, lost);
+    } finally {
+      unregister();
+    }
+    this.releaseSlot();
+    await this.host.allocator.check();
+    return bytes;
+  }
+  async classify(error, lost) {
+    if (isWebGpuGraphError(error)) {
+      return error.code === "E_DEVICE_LOST" || error.code === "E_DISPOSED" ? error : this.attribute(error);
+    }
+    try {
+      this.host.assertReady();
+    } catch (state) {
+      if (isWebGpuGraphError(state)) {
+        return state.code === "E_DEVICE_LOST" || state.code === "E_DISPOSED" ? state : this.attribute(state);
+      }
+    }
+    let timer;
+    const grace = new Promise((resolve) => {
+      timer = setTimeout(() => {
+        resolve(null);
+      }, LOSS_GRACE_MS);
+    });
+    const late = await Promise.race([
+      lost.then(
+        () => null,
+        (reason) => reason
+      ),
+      grace
+    ]);
+    clearTimeout(timer);
+    if (isWebGpuGraphError(late)) {
+      return late;
+    }
+    const message = messageOf(error);
+    return new WebGpuGraphError(
+      "E_VALIDATION",
+      `mapAsync failed for batch ${this.id} "${this.label}": ${message}`,
+      {
+        label: this.label,
+        message,
+        batchId: this.id
+      }
+    );
+  }
+  attribute(error) {
+    return new WebGpuGraphError(error.code, `${error.message} (delivered to batch ${this.id} "${this.label}")`, {
+      ...error.details,
+      batchId: this.id,
+      batchLabel: this.label
+    });
+  }
+  ensureSlot(byteLength) {
+    if (this.slot !== null && this.slot.capacity >= byteLength) {
+      return;
+    }
+    this.releaseSlot();
+    this.slot = this.host.readback.borrowSlot(byteLength);
+  }
+  releaseSlot() {
+    if (this.slot === null) {
+      return;
+    }
+    const { slot } = this;
+    this.slot = null;
+    try {
+      this.host.readback.returnSlot(slot);
+    } catch (error) {
+      if (!isWebGpuGraphError(error) || error.code !== "E_DISPOSED") {
+        throw error;
+      }
+    }
+  }
+  countDispatches(pass) {
+    const direct = pass.dispatchWorkgroups.bind(pass);
+    const indirect = pass.dispatchWorkgroupsIndirect.bind(pass);
+    pass.dispatchWorkgroups = (x, y, z) => {
+      this.dispatchCount += 1;
+      direct(x, y, z);
+      return void 0;
+    };
+    pass.dispatchWorkgroupsIndirect = (buffer, offset) => {
+      this.dispatchCount += 1;
+      indirect(buffer, offset);
+      return void 0;
+    };
+  }
+  assertOpen(operation) {
+    if (this.submitted) {
+      throw new WebGpuGraphError(
+        "E_INVALID_ARGUMENT",
+        `${operation}() after submit() on batch ${this.id} "${this.label}"`,
+        {
+          argument: operation,
+          value: this.id,
+          expected: "a batch that has not been submitted"
+        }
+      );
+    }
+  }
+  checkByteLength(byteLength) {
+    if (!Number.isInteger(byteLength) || byteLength <= 0 || byteLength % 4 !== 0) {
+      throw new WebGpuGraphError(
+        "E_INVALID_ARGUMENT",
+        `byteLength ${byteLength} is not a positive multiple of 4`,
+        {
+          argument: "byteLength",
+          value: byteLength,
+          expected: "a positive multiple of 4"
+        }
+      );
+    }
+  }
+}
+class UniformRing {
+  /**
+   * Creates the ring buffer (`slots x UNIFORM_SLOT_BYTES` bytes, UNIFORM | COPY_DST) through the allocator.
+   * @param device - the device the buffer belongs to
+   * @param allocator - the context's OOM-scoped allocator (the buffer is destroyed through it)
+   * @param slots - number of slots; E_INVALID_ARGUMENT unless a positive integer
+   * @param label - the buffer label
+   */
+  constructor(device, allocator, slots, label) {
+    this.next = 0;
+    this.dirtyLo = -1;
+    this.dirtyHi = -1;
+    this.destroyed = false;
+    if (!Number.isInteger(slots) || slots < 1) {
+      throw new WebGpuGraphError(
+        "E_INVALID_ARGUMENT",
+        `UniformRing "${label}": slots must be a positive integer, got ${slots}`,
+        {
+          argument: "slots",
+          value: slots,
+          expected: "an integer >= 1"
+        }
+      );
+    }
+    this.device = device;
+    this.allocator = allocator;
+    this.slots = slots;
+    this.label = label;
+    this.shadow = new ArrayBuffer(slots * UNIFORM_SLOT_BYTES);
+    this.view = new DataView(this.shadow);
+    this.buffer = allocator.createBuffer({
+      label,
+      size: slots * UNIFORM_SLOT_BYTES,
+      usage: BufferUsage.UNIFORM | BufferUsage.COPY_DST
+    });
+  }
+  /**
+   * The whole-buffer binding a kernel binds once (size = the block's byteLength; the slot is the dynamic offset).
+   * @param block - the params block the kernel declares for this binding
+   * @returns the binding at offset 0 of the ring buffer
+   */
+  binding(block) {
+    this.assertLive();
+    this.assertFits(block);
+    return { buffer: this.buffer, offset: 0, size: block.byteLength, window: null };
+  }
+  /**
+   * Byte offset of a slot (the dynamic offset a dispatch passes for it).
+   * @param slot - a slot index in [0, slots)
+   * @returns slot x UNIFORM_SLOT_BYTES
+   */
+  offsetOf(slot) {
+    this.checkSlot(slot);
+    return slot * UNIFORM_SLOT_BYTES;
+  }
+  /**
+   * Reserves `count` contiguous slots for a batch, wrapping to 0 when the tail is too short; E_INVALID_ARGUMENT when count > slots.
+   * @param count - slots needed, in [1, slots]
+   * @returns the first slot of the reservation
+   */
+  reserve(count) {
+    this.assertLive();
+    if (!Number.isInteger(count) || count < 1 || count > this.slots) {
+      throw new WebGpuGraphError(
+        "E_INVALID_ARGUMENT",
+        `UniformRing "${this.label}": cannot reserve ${count} of ${this.slots} slots`,
+        {
+          argument: "count",
+          value: count,
+          expected: `an integer in [1, ${this.slots}]`
+        }
+      );
+    }
+    if (this.next + count > this.slots) {
+      this.next = 0;
+    }
+    const first = this.next;
+    this.next += count;
+    return first;
+  }
+  /**
+   * Writes one block's values into a slot of the host shadow; `flush()` sends the dirty range with one writeBuffer.
+   * @param slot - the slot to fill
+   * @param block - the block whose layout the bytes follow
+   * @param values - the field values (a missing field is written as 0 by the block)
+   */
+  write(slot, block, values) {
+    this.checkSlot(slot);
+    this.assertFits(block);
+    block.write(this.view, values, slot * UNIFORM_SLOT_BYTES);
+    if (this.dirtyLo < 0 || slot < this.dirtyLo) {
+      this.dirtyLo = slot;
+    }
+    if (slot > this.dirtyHi) {
+      this.dirtyHi = slot;
+    }
+  }
+  /**
+   * queue.writeBuffer of the dirty slots (called by the batch driver before submit): one call covering
+   * [lowest dirty slot, highest dirty slot]; nothing when no slot is dirty.
+   */
+  flush() {
+    this.assertLive();
+    if (this.dirtyLo < 0) {
+      return;
+    }
+    const begin = this.dirtyLo * UNIFORM_SLOT_BYTES;
+    const end = (this.dirtyHi + 1) * UNIFORM_SLOT_BYTES;
+    this.device.queue.writeBuffer(this.buffer, begin, this.shadow, begin, end - begin);
+    this.dirtyLo = -1;
+    this.dirtyHi = -1;
+  }
+  /** Destroys the buffer (through the allocator); idempotent. */
+  destroy() {
+    if (this.destroyed) {
+      return;
+    }
+    this.destroyed = true;
+    this.allocator.destroy(this.buffer);
+  }
+  assertLive() {
+    if (this.destroyed) {
+      throw new WebGpuGraphError("E_DISPOSED", `UniformRing "${this.label}" is destroyed`, { label: this.label });
+    }
+  }
+  checkSlot(slot) {
+    this.assertLive();
+    if (!Number.isInteger(slot) || slot < 0 || slot >= this.slots) {
+      throw new WebGpuGraphError(
+        "E_INVALID_ARGUMENT",
+        `UniformRing "${this.label}": slot ${slot} is outside [0, ${this.slots})`,
+        {
+          argument: "slot",
+          value: slot,
+          expected: `an integer in [0, ${this.slots})`
+        }
+      );
+    }
+  }
+  assertFits(block) {
+    if (block.byteLength > UNIFORM_SLOT_BYTES) {
+      throw new WebGpuGraphError(
+        "E_INVALID_ARGUMENT",
+        `UniformRing "${this.label}": block ${block.name} is ${block.byteLength} bytes, a slot holds ${UNIFORM_SLOT_BYTES}`,
+        { argument: "block", value: block.name, expected: `byteLength <= ${UNIFORM_SLOT_BYTES}` }
+      );
+    }
+  }
+}
+const LCG_M = 34359738337;
+const LCG_A = 185852;
+const LCG_C = 1;
+class Lcg {
+  /**
+   * Creates the generator; a seed of 0, -0, NaN or null means unseeded (the port's `seed || random` quirk).
+   * @param seed - the seed, or null for a random seed
+   */
+  constructor(seed) {
+    this.seed = seed === null || seed === 0 || Number.isNaN(seed) ? Math.floor(Math.random() * 1e6) : seed;
+    this.state = this.seed % LCG_M;
+  }
+  /**
+   * Next value in [0, 1).
+   * @returns state / m after one LCG step
+   */
+  next() {
+    this.state = (LCG_A * this.state + LCG_C) % LCG_M;
+    return this.state / LCG_M;
+  }
+}
+function resolveCenter(center) {
+  const out = [0, 0, 0];
+  if (center === null) {
+    return out;
+  }
+  for (let axis = 0; axis < 3 && axis < center.length; axis++) {
+    const v = center[axis];
+    if (!Number.isFinite(v)) {
+      throw new WebGpuGraphError("E_INVALID_ARGUMENT", `center[${axis}] is not finite`, {
+        argument: "center",
+        value: v,
+        expected: "finite components"
+      });
+    }
+    out[axis] = v;
+  }
+  return out;
+}
+function seedPositions(s, positions, seed, dim, scale, center, range) {
+  const n = s.nodeCount;
+  if (dim !== 2 && dim !== 3) {
+    throw new WebGpuGraphError("E_INVALID_ARGUMENT", `dim must be 2 or 3, got ${String(dim)}`, {
+      argument: "dim",
+      value: dim,
+      expected: "2 or 3"
+    });
+  }
+  if (positions.length !== 3 * n) {
+    throw new WebGpuGraphError(
+      "E_INVALID_ARGUMENT",
+      `positions has ${positions.length} entries, expected ${3 * n}`,
+      {
+        argument: "positions",
+        value: positions.length,
+        expected: 3 * n
+      }
+    );
+  }
+  if (!Number.isFinite(scale) || scale <= 0) {
+    throw new WebGpuGraphError("E_INVALID_ARGUMENT", `scale must be a finite number > 0, got ${scale}`, {
+      argument: "scale",
+      value: scale,
+      expected: "a finite number > 0"
+    });
+  }
+  const c = resolveCenter(center);
+  const lo = [Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY];
+  const hi = [Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY];
+  let finiteRows = 0;
+  let unseededRows = 0;
+  for (let i = 0; i < n; i++) {
+    let finite = true;
+    for (let axis = 0; axis < dim; axis++) {
+      const v = positions[3 * i + axis];
+      if (Number.isFinite(v)) {
+        if (v < lo[axis]) {
+          lo[axis] = v;
+        }
+        if (v > hi[axis]) {
+          hi[axis] = v;
+        }
+      } else {
+        finite = false;
+      }
+    }
+    if (finite) {
+      finiteRows++;
+    } else {
+      unseededRows++;
+    }
+  }
+  if (unseededRows === 0) {
+    return;
+  }
+  const rangeLo = range === "fr" ? 0 : -1;
+  const rangeHi = 1;
+  const boxLo = [rangeLo, rangeLo, rangeLo];
+  const boxHi = [rangeHi, rangeHi, rangeHi];
+  if (finiteRows > 0) {
+    for (let axis = 0; axis < dim; axis++) {
+      if (Number.isFinite(lo[axis]) && Number.isFinite(hi[axis])) {
+        boxLo[axis] = (lo[axis] - c[axis]) / scale;
+        boxHi[axis] = (hi[axis] - c[axis]) / scale;
+      }
+    }
+  }
+  const rng = new Lcg(seed);
+  for (let i = 0; i < n; i++) {
+    let unseeded = false;
+    for (let axis = 0; axis < dim; axis++) {
+      if (!Number.isFinite(positions[3 * i + axis])) {
+        unseeded = true;
+      }
+    }
+    if (!unseeded) {
+      continue;
+    }
+    for (let axis = 0; axis < dim; axis++) {
+      const at = 3 * i + axis;
+      if (!Number.isFinite(positions[at])) {
+        const u = rng.next();
+        const v = boxLo[axis] + u * (boxHi[axis] - boxLo[axis]);
+        positions[at] = v * scale + c[axis];
+      }
+    }
+    if (dim === 2) {
+      positions[3 * i + 2] = c[2];
+    }
+  }
+}
+const SHARED_PARAM_FIELDS = [
+  ["n", 1],
+  ["dim", 1],
+  ["flags", 1],
+  ["iterationIndex", 1],
+  ["seed", 1],
+  ["scale", 1],
+  ["center", 4],
+  ["settleThreshold", 1]
+];
+const SHARED_STATE_FIELDS = [
+  ["centroid", 4],
+  ["min", 4],
+  ["max", 4],
+  ["rmsRadius", 1],
+  ["radius", 1],
+  ["meanDisplacement", 1],
+  ["iteration", 1],
+  ["settledCount", 1]
+];
+const SHARED_BUFFER_NAMES = ["positions", "scenePositions", "fixed", "partials", "state", "trace"];
+const EPILOGUE_STAGE = "toScene";
+let simulationCounter = 0;
+function invalidArgument(argument, value, expected, message) {
+  return new WebGpuGraphError("E_INVALID_ARGUMENT", message, { argument, value, expected });
+}
+function disposedError(label) {
+  return new WebGpuGraphError("E_DISPOSED", `${label} is disposed`, { label });
+}
+function asError(err) {
+  if (err instanceof Error) {
+    return err;
+  }
+  return new Error(typeof err === "string" ? err : "unknown error");
+}
+function optionField(record, key) {
+  return record[key];
+}
+function fieldWidth(type) {
+  switch (type) {
+    case "u32":
+    case "i32":
+    case "f32":
+      return 1;
+    case "vec2f":
+    case "vec2u":
+      return 2;
+    case "vec4f":
+    case "vec4u":
+      return 4;
+    default:
+      throw invalidArgument("type", type, "a UniformFieldType", "unknown uniform field type");
+  }
+}
+function fieldTypeOrNull(block, field) {
+  for (const [name, type] of block.fields) {
+    if (name === field) {
+      return type;
+    }
+  }
+  return null;
+}
+function fieldTypeOf(block, field) {
+  const type = fieldTypeOrNull(block, field);
+  if (type === null) {
+    throw invalidArgument(
+      "field",
+      field,
+      block.fields.map((f2) => f2[0]),
+      `block ${block.name} has no field ${field}`
+    );
+  }
+  return type;
+}
+function requireFields(block, required, what) {
+  for (const [field, width] of required) {
+    const type = fieldTypeOrNull(block, field);
+    if (type === null) {
+      throw invalidArgument(
+        what,
+        field,
+        required.map((r) => r[0]),
+        `${what} block ${block.name} must declare ${field}`
+      );
+    }
+    if (fieldWidth(type) !== width) {
+      throw invalidArgument(
+        what,
+        field,
+        `a field of width ${width}`,
+        `${what}.${field} must have width ${width}`
+      );
+    }
+  }
+}
+function stableKey(record) {
+  return JSON.stringify(
+    Object.keys(record).sort().map((k2) => [k2, record[k2]])
+  );
+}
+function withMs(stats, msPerIteration) {
+  return { ...stats, msPerIteration };
+}
+function isSharedBuffer(buffer) {
+  return typeof SharedArrayBuffer !== "undefined" && buffer instanceof SharedArrayBuffer;
+}
+function scaleOf(options) {
+  const scale = options.scale ?? FA2_DEFAULTS.scale;
+  if (!Number.isFinite(scale) || scale <= 0) {
+    throw invalidArgument("scale", scale, "a finite number > 0", `scale must be a finite number > 0, got ${scale}`);
+  }
+  return scale;
+}
+function centerOf(options) {
+  const out = [0, 0, 0];
+  const { center } = options;
+  if (center === void 0) {
+    return out;
+  }
+  for (let axis = 0; axis < 3 && axis < center.length; axis++) {
+    const v = center[axis];
+    if (!Number.isFinite(v)) {
+      throw invalidArgument("center", v, "finite components", `center[${axis}] is not finite`);
+    }
+    out[axis] = v;
+  }
+  return out;
+}
+function tierFor(tuning, n) {
+  if (tuning.repulsion === "exact") {
+    return "exact";
+  }
+  if (tuning.repulsion === "grid") {
+    return "grid";
+  }
+  return n <= tuning.exactMaxNodes ? "exact" : "grid";
+}
+function wholeBinding(buffer, size) {
+  return { buffer, offset: 0, size, window: null };
+}
+class HeaderWriter {
+  /**
+   * Creates a writer over a model's state block with every field 0.
+   * @param block - the model's state block
+   */
+  constructor(block) {
+    this.shadow = /* @__PURE__ */ new Map();
+    this.queued = /* @__PURE__ */ new Map();
+    this.block = block;
+    this.reset();
+  }
+  /**
+   * Queues a field write and applies it to the shadow.
+   * @param field - the field name (E_INVALID_ARGUMENT when the block lacks it or the width differs)
+   * @param value - a number for a scalar field, an array of the vector's width otherwise
+   */
+  set(field, value) {
+    const width = fieldWidth(fieldTypeOf(this.block, field));
+    const ok = width === 1 ? typeof value === "number" : typeof value !== "number" && value.length === width;
+    if (!ok) {
+      throw invalidArgument(
+        "value",
+        value,
+        `a value of width ${width}`,
+        `state field ${field} takes a value of width ${width}`
+      );
+    }
+    this.shadow.set(field, value);
+    this.queued.set(field, value);
+  }
+  /**
+   * The host shadow of a field: the last value set, or the last landed header's value.
+   * @param field - the field name
+   * @returns the value
+   */
+  get(field) {
+    const value = this.shadow.get(field);
+    if (value === void 0) {
+      throw invalidArgument(
+        "field",
+        field,
+        this.block.fields.map((f2) => f2[0]),
+        `state block has no field ${field}`
+      );
+    }
+    return value;
+  }
+  /** Every field back to 0 and the queue cleared (load()). */
+  reset() {
+    this.shadow.clear();
+    this.queued.clear();
+    const zero = this.block.read(new DataView(new ArrayBuffer(this.block.byteLength)));
+    for (const [name, value] of Object.entries(zero)) {
+      this.shadow.set(name, value);
+    }
+  }
+  /**
+   * The byte image of the shadow (the block's own writer, D20).
+   * @returns block.byteLength bytes
+   */
+  headerBytes() {
+    const bytes = new ArrayBuffer(this.block.byteLength);
+    this.block.write(new DataView(bytes), Object.fromEntries(this.shadow));
+    return bytes;
+  }
+  /**
+   * Refreshes the shadow from a landed header; a field set since the last flush keeps its queued value.
+   * @param view - the landed header
+   */
+  absorb(view) {
+    for (const [name, value] of Object.entries(this.block.read(view))) {
+      if (!this.queued.has(name)) {
+        this.shadow.set(name, value);
+      }
+    }
+  }
+  /**
+   * The fields set since the last flush; clears the queue.
+   * @returns the field names
+   */
+  takeQueued() {
+    const fields = [...this.queued.keys()];
+    this.queued.clear();
+    return fields;
+  }
+  /** Drops the queue (after load() wrote the whole header). */
+  clearQueued() {
+    this.queued.clear();
+  }
+}
+function createPending(k2, generation) {
+  let resolveFn = () => void 0;
+  let rejectFn = () => void 0;
+  const promise = new Promise((resolve, reject) => {
+    resolveFn = resolve;
+    rejectFn = reject;
+  });
+  return {
+    k: k2,
+    generation,
+    promise,
+    resolve: () => {
+      resolveFn();
+    },
+    reject: (error) => {
+      rejectFn(error);
+    },
+    id: 0,
+    submitted: null,
+    stale: false,
+    startedAt: 0,
+    sceneOffset: 0,
+    stateOffset: 0,
+    profile: null
+  };
+}
+class ForceSimulation {
+  /**
+   * Creates a simulation over a context and a model (state "created"; load() makes it "loaded").
+   * @param ctx - the context (ready)
+   * @param model - the force model
+   * @param options - the option record (defaults applied by the caller's factory)
+   * @param tuning - the resolved GPU tuning
+   * @param resolve - how setParams merges a patch into the current record
+   */
+  constructor(ctx, model, options, tuning, resolve) {
+    this.overrideList = /* @__PURE__ */ new Map();
+    this.pending = [];
+    this.stateValue = "created";
+    this.generationValue = 0;
+    this.snapshot = null;
+    this.serial = null;
+    this.owner = null;
+    this.n = 0;
+    this.scale = 1;
+    this.center = [0, 0, 0];
+    this.buffers = null;
+    this.core = null;
+    this.resources = null;
+    this.weightsUpload = null;
+    this.ready = Promise.resolve();
+    this.submitChain = Promise.resolve();
+    this.fixedWords = new Uint32Array(0);
+    this.fixedDirty = false;
+    this.iterationsSubmitted = 0;
+    this.iterationsDoneValue = 0;
+    this.settledCountValue = 0;
+    this.settledValue = false;
+    this.firstPending = true;
+    this.statsValue = null;
+    this.lastSubmittedBatchIdValue = 0;
+    this.reheatedAfterBatchId = 0;
+    this.coalescedValue = 0;
+    this.torndown = false;
+    ctx.assertReady();
+    requireFields(model.params, SHARED_PARAM_FIELDS, "model.params");
+    requireFields(model.state, SHARED_STATE_FIELDS, "model.state");
+    if (model.params.byteLength > UNIFORM_SLOT_BYTES) {
+      throw invalidArgument(
+        "model.params",
+        model.params.byteLength,
+        `<= ${UNIFORM_SLOT_BYTES} bytes`,
+        "the params block must fit one ring slot"
+      );
+    }
+    if (model.state.byteLength > STATE_HEADER_BYTES) {
+      throw invalidArgument(
+        "model.state",
+        model.state.byteLength,
+        `<= ${STATE_HEADER_BYTES} bytes`,
+        "the state block must fit the state header"
+      );
+    }
+    if (model.stages.length === 0) {
+      throw invalidArgument(
+        "model.stages",
+        model.stages,
+        "at least one stage name",
+        "a model declares its stages"
+      );
+    }
+    const maxInFlight = options.maxInFlight ?? FA2_DEFAULTS.maxInFlight;
+    if (!Number.isInteger(maxInFlight) || maxInFlight < 1) {
+      throw invalidArgument(
+        "maxInFlight",
+        maxInFlight,
+        "an integer >= 1",
+        `maxInFlight must be an integer >= 1, got ${maxInFlight}`
+      );
+    }
+    const dim = options.dim ?? FA2_DEFAULTS.dim;
+    if (dim !== 2 && dim !== 3) {
+      throw invalidArgument("dim", dim, "2 or 3", `dim must be 2 or 3, got ${String(dim)}`);
+    }
+    scaleOf(options);
+    centerOf(options);
+    simulationCounter++;
+    this.ctx = ctx;
+    this.model = model;
+    this.tuning = tuning;
+    this.resolveOptions = resolve;
+    this.optionsValue = options;
+    this.maxInFlight = maxInFlight;
+    this.dimValue = dim;
+    this.tierValue = tuning.repulsion === "grid" ? "grid" : "exact";
+    this.label = `${model.kind}#${simulationCounter}`;
+    this.traceBytes = model.trace.byteLength;
+    this.writer = new HeaderWriter(model.state);
+    this.ring = new UniformRing(
+      ctx.device,
+      ctx.allocator,
+      (maxInFlight + 1) * MAX_ITERATIONS_PER_STEP,
+      `${this.label}/ring`
+    );
+    this.unregisterLost = ctx.onLost((info) => {
+      this.onDeviceLost(info);
+    });
+    if (ctx.debug.inspect) {
+      this.inspect = (name) => this.inspectBuffer(name);
+      this.debugRunStages = (upTo) => this.runStages(upTo);
+    }
+  }
+  // ---------------------------------------------------------------- read-only state
+  /**
+   * "created" | "loaded" | "disposed".
+   * @returns the state
+   */
+  get state() {
+    return this.stateValue;
+  }
+  /**
+   * The current options record (defaults applied).
+   * @returns the record
+   */
+  get options() {
+    return this.optionsValue;
+  }
+  /**
+   * The repulsion tier of the current load ("exact" until P4 lifts the grid tier).
+   * @returns the tier
+   */
+  get tier() {
+    return this.tierValue;
+  }
+  /**
+   * The generation counter bumped by every load() (stale readbacks are discarded).
+   * @internal
+   * @returns the generation
+   */
+  get generation() {
+    return this.generationValue;
+  }
+  /**
+   * Nodes of the current load (0 before load()).
+   * @returns the node count
+   */
+  get nodeCount() {
+    return this.n;
+  }
+  /**
+   * 2 or 3, fixed at construction (setParams({ dim }) is rejected, spec 7.13).
+   * @returns the dimension
+   */
+  get dim() {
+    return this.dimValue;
+  }
+  /**
+   * iterationsDone >= the budget OR settledCount >= settleWindow of the last completed batch (spec 7.17); true for an empty graph.
+   * @returns whether the layout is settled
+   */
+  get settled() {
+    return this.settledValue;
+  }
+  /**
+   * Batches created by step() and not yet landed (PLAN DECISION 7: counted from the step() call).
+   * @returns the count
+   */
+  get inFlight() {
+    return this.pending.length;
+  }
+  /**
+   * Iterations landed since load() or the last reheat().
+   * @returns the count
+   */
+  get iterationsDone() {
+    return this.iterationsDoneValue;
+  }
+  /**
+   * The stats of the last completed batch; before one lands, the host-written header decoded through the model
+   * with an empty trace and msPerIteration null.
+   * @returns the stats
+   */
+  get stats() {
+    if (this.statsValue !== null) {
+      return this.statsValue;
+    }
+    const header = new DataView(this.writer.headerBytes());
+    const trace = new DataView(new ArrayBuffer(0));
+    return withMs(this.model.readStats(header, trace), null);
+  }
+  /**
+   * The override list (spec 7.12): rows whose readback is skipped while a batch older than the write is in flight.
+   * @internal
+   * @returns row -> lastSubmittedBatchId at the write
+   */
+  get overrides() {
+    return this.overrideList;
+  }
+  /**
+   * The last submitted batch id.
+   * @internal
+   * @returns the id (0 before any submit)
+   */
+  get lastSubmittedBatchId() {
+    return this.lastSubmittedBatchIdValue;
+  }
+  /**
+   * Number of step() calls that returned an existing batch's promise instead of submitting (spec 7.19 item 3;
+   * read by test/helpers/frame-loop.ts).
+   * @internal
+   * @returns the count
+   */
+  get coalesced() {
+    return this.coalescedValue;
+  }
+  // ---------------------------------------------------------------- load
+  /**
+   * Uploads the snapshot's core, seeds the NaN rows of `positions`, repacks it into layout-unit vec4f with the
+   * mass in .w, writes the initial state, starts the model's compile + bind and enters "loaded" (spec 7.19; a
+   * load() during flight bumps the generation and discards the in-flight batches). Order of the checks (PLAN
+   * DECISION 16): E_DISPOSED, the context's assertReady, E_SNAPSHOT (directed), E_TOO_LARGE (nodeCount), the
+   * positions array, the tuning, then the core upload and model.inputs() BEFORE any state is touched.
+   * PLAN DECISION 10: nodeCount 0 loads with no GPU work at all. PLAN DECISION 11: the tier is resolved here
+   * and "grid" is E_UNSUPPORTED until P4. PLAN DECISION 17: a same-size load() keeps the buffers and re-zeroes
+   * partials, the trace region and every `zero: true` model buffer.
+   * @param snapshot - an undirected snapshot
+   * @param positions - the owner's stride-3 scene-unit array (NaN rows are seeded in place)
+   */
+  load(snapshot, positions) {
+    this.assertNotDisposed();
+    this.ctx.assertReady();
+    if (snapshot.directed) {
+      throw new WebGpuGraphError(
+        "E_SNAPSHOT",
+        "a layout needs an undirected snapshot: pass toUndirected().snapshot",
+        {
+          reason: "directed",
+          serial: snapshot.serial
+        }
+      );
+    }
+    const n = snapshot.nodeCount;
+    if (n > MAX_1D_ITEMS) {
+      throw new WebGpuGraphError(
+        "E_TOO_LARGE",
+        `${n} nodes exceed ${MAX_1D_ITEMS} (the third partials level is P4)`,
+        {
+          needed: n,
+          limit: MAX_1D_ITEMS,
+          path: "partials",
+          algorithm: this.model.kind
+        }
+      );
+    }
+    if (positions.length !== 3 * n) {
+      throw invalidArgument(
+        "positions",
+        positions.length,
+        3 * n,
+        `positions has ${positions.length} entries, expected ${3 * n}`
+      );
+    }
+    if (isSharedBuffer(positions.buffer)) {
+      throw invalidArgument(
+        "positions",
+        "SharedArrayBuffer",
+        "an ArrayBuffer-backed Float32Array",
+        "positions must not be backed by a SharedArrayBuffer"
+      );
+    }
+    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`, {
+        needed: positionsBytes,
+        limit: this.ctx.caps.limits.maxBufferSize,
+        path: "positions",
+        algorithm: this.model.kind
+      });
+    }
+    let core = null;
+    let inputs = null;
+    if (n > 0) {
+      core = this.ctx.residency.core(snapshot);
+      if (core.plan === "windowed") {
+        throw new WebGpuGraphError(
+          "E_TOO_LARGE",
+          "a windowed core cannot be walked by the layout kernels until P4",
+          {
+            needed: snapshot.arcCount,
+            limit: this.ctx.caps.limits.maxStorageBufferBindingSize,
+            path: "windowed",
+            algorithm: this.model.kind
+          }
+        );
+      }
+      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`
+        );
+      }
+    }
+    this.generationValue++;
+    this.discardPending();
+    const resized = this.buffers === null || n !== this.n || snapshot.serial !== this.serial;
+    this.snapshot = snapshot;
+    this.serial = snapshot.serial;
+    this.owner = positions;
+    this.n = n;
+    this.tierValue = tier;
+    this.scale = scale;
+    this.center = center;
+    this.core = core;
+    this.iterationsSubmitted = 0;
+    this.iterationsDoneValue = 0;
+    this.settledCountValue = 0;
+    this.firstPending = true;
+    this.statsValue = null;
+    this.writer.reset();
+    if (resized) {
+      this.destroyBuffers();
+      this.overrideList.clear();
+      this.fixedWords = makeMask(n);
+      this.fixedDirty = false;
+    }
+    if (n === 0 || core === null || inputs === null) {
+      this.weightsUpload = null;
+      this.resources = null;
+      this.ready = this.ready.catch(() => void 0);
+      this.settledValue = true;
+      this.stateValue = "loaded";
+      return;
+    }
+    const buffers = resized ? this.allocate(n) : this.requireBuffers();
+    if (!resized) {
+      this.clearKept(buffers);
+    }
+    this.buffers = buffers;
+    const range = this.model.kind === "fruchtermanReingold" ? "fr" : "fa2";
+    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);
+    this.resources = resources;
+    this.startBind(resources, overrides);
+    this.settledValue = false;
+    this.stateValue = "loaded";
+  }
+  // ---------------------------------------------------------------- step and the batch driver
+  /**
+   * Submits k iterations (spec 7.19 items 1-6): "created" -> E_NOT_LOADED; "disposed" -> E_DISPOSED; a released
+   * snapshot -> E_RELEASED; k outside [1, MAX_ITERATIONS_PER_STEP] -> E_INVALID_ARGUMENT; settled -> resolves at
+   * once; inFlight >= maxInFlight -> the OLDEST pending batch's promise (coalesced); else the batch is queued on
+   * the submit chain (after the bind promise and allocator.check()) and its promise resolves when its readback
+   * landed in the owner's array. The same promise object is returned for every coalesced call. PLAN DECISION 7:
+   * the batch counts in `inFlight` from this call, not from its submission.
+   * @param iterations - k (default options.iterationsPerStep, default 1)
+   * @returns resolves when the batch landed (or was discarded); rejects E_VALIDATION / E_DEVICE_LOST / E_OUT_OF_MEMORY / E_SHADER_COMPILE
+   */
+  step(iterations) {
+    if (this.stateValue === "created") {
+      return Promise.reject(
+        new WebGpuGraphError("E_NOT_LOADED", `${this.label}: load() first`, { state: "created" })
+      );
+    }
+    if (this.stateValue === "disposed") {
+      return Promise.reject(disposedError(this.label));
+    }
+    try {
+      this.ctx.assertReady();
+    } catch (err) {
+      return Promise.reject(asError(err));
+    }
+    const { snapshot } = this;
+    if (snapshot !== null && this.ctx.residency.isReleased(snapshot.serial)) {
+      return Promise.reject(
+        new WebGpuGraphError(
+          "E_RELEASED",
+          `snapshot ${snapshot.serial} was released while ${this.label} used it`,
+          {
+            serial: snapshot.serial
+          }
+        )
+      );
+    }
+    const k2 = iterations ?? this.optionsValue.iterationsPerStep ?? FA2_DEFAULTS.iterationsPerStep;
+    if (!Number.isInteger(k2) || k2 < 1 || k2 > MAX_ITERATIONS_PER_STEP) {
+      return Promise.reject(
+        invalidArgument(
+          "iterations",
+          k2,
+          `an integer in [1, ${MAX_ITERATIONS_PER_STEP}]`,
+          `step(${k2}): iterations must be an integer in [1, ${MAX_ITERATIONS_PER_STEP}]`
+        )
+      );
+    }
+    if (this.settledValue || this.n === 0) {
+      return Promise.resolve();
+    }
+    if (this.pending.length >= this.maxInFlight) {
+      this.coalescedValue++;
+      return this.pending[0].promise;
+    }
+    const record = createPending(k2, this.generationValue);
+    this.pending.push(record);
+    this.submitChain = this.submitChain.then(() => this.submitBatch(record));
+    return record.promise;
+  }
+  /**
+   * Resolves when nothing is in flight (every pending batch landed or was discarded).
+   * @returns the promise
+   */
+  async flush() {
+    while (this.pending.length > 0) {
+      await Promise.allSettled(this.pending.map((r) => r.promise));
+    }
+  }
+  /**
+   * Node batch driver: loops step(batch) until settled, the budget (`maxIter ?? options.maxIter`, PLAN DECISION
+   * 1) is reached or the signal aborts (E_ABORTED; the batch in flight at the abort is discarded, spec 5.7 / Q-15).
+   * @param options - maxIter, batch (default 8), signal
+   * @returns the stats of the last completed batch
+   */
+  async run(options) {
+    this.assertNotDisposed();
+    const batch = options?.batch ?? 8;
+    if (!Number.isInteger(batch) || batch < 1 || batch > MAX_ITERATIONS_PER_STEP) {
+      throw invalidArgument(
+        "batch",
+        batch,
+        `an integer in [1, ${MAX_ITERATIONS_PER_STEP}]`,
+        "run(): batch must be an integer in [1, MAX_ITERATIONS_PER_STEP]"
+      );
+    }
+    const budget = options?.maxIter ?? this.iterationBudget();
+    if (Number.isNaN(budget) || budget < 0) {
+      throw invalidArgument("maxIter", budget, "a number >= 0", "run(): maxIter must be >= 0");
+    }
+    const signal = options?.signal;
+    const onAbort = () => {
+      this.discardPending();
+    };
+    if (signal !== void 0) {
+      if (signal.aborted) {
+        throw this.abortedError();
+      }
+      signal.addEventListener("abort", onAbort, { once: true });
+    }
+    try {
+      while (!this.settled && this.iterationsDoneValue < budget) {
+        if (signal?.aborted === true) {
+          throw this.abortedError();
+        }
+        const k2 = Math.min(batch, budget - this.iterationsDoneValue);
+        await this.step(k2);
+      }
+      if (signal?.aborted === true) {
+        throw this.abortedError();
+      }
+      return this.stats;
+    } finally {
+      signal?.removeEventListener("abort", onAbort);
+    }
+  }
+  // ---------------------------------------------------------------- pins, drags, reheat, params
+  /**
+   * Copies the mask words (spec 7.12): E_INVALID_ARGUMENT when shorter than ceil(n / 32); the buffer is marked
+   * dirty and re-uploaded before the next submit; reheat() iff some bit went 1 -> 0 (an unpin). PLAN DECISION
+   * 18: the comparison is bit by bit below n (bits at or above n never count as an unpin).
+   * @param mask - the NodeMask (LSB-first words)
+   */
+  setFixed(mask) {
+    this.assertLoaded();
+    const { n } = this;
+    const words = Math.ceil(n / 32);
+    if (mask.length < words) {
+      throw invalidArgument(
+        "mask",
+        mask.length,
+        words,
+        `setFixed: the mask has ${mask.length} words, ${words} needed for ${n} nodes`
+      );
+    }
+    let unpinned = false;
+    for (let w = 0; w < words && !unpinned; w++) {
+      if (this.fixedWords[w] === mask[w]) {
+        continue;
+      }
+      const last = Math.min(n, w * 32 + 32);
+      for (let i = w * 32; i < last; i++) {
+        if (maskTest(this.fixedWords, i) && !maskTest(mask, i)) {
+          unpinned = true;
+          break;
+        }
+      }
+    }
+    this.fixedWords.set(mask.subarray(0, words));
+    this.fixedDirty = true;
+    if (unpinned) {
+      this.reheat();
+    }
+  }
+  /**
+   * Writes a scene-unit position (spec 7.12): into the owner's array at once, into the device (layout units, z 0
+   * in 2D, 12 bytes at 16 i, queue-ordered before the next submit), into the override list keyed by the last
+   * submitted batch id, then reheat(). PLAN DECISION 18: non-finite coordinates are E_INVALID_ARGUMENT.
+   * @param index - the node index (< n)
+   * @param x - scene x
+   * @param y - scene y
+   * @param z - scene z (ignored on the device in 2D)
+   */
+  setPosition(index, x, y, z) {
+    this.assertLoaded();
+    const { n } = this;
+    if (!Number.isInteger(index) || index < 0 || index >= n) {
+      throw invalidArgument(
+        "index",
+        index,
+        `an integer in [0, ${n})`,
+        `setPosition(${index}): index out of range`
+      );
+    }
+    if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z)) {
+      throw invalidArgument(
+        "position",
+        [x, y, z],
+        "finite coordinates",
+        "setPosition: coordinates must be finite"
+      );
+    }
+    const { owner, buffers } = this;
+    if (owner === null || buffers === null) {
+      throw new WebGpuGraphError("E_NOT_LOADED", `${this.label}: load() first`, { state: this.stateValue });
+    }
+    owner[3 * index] = x;
+    owner[3 * index + 1] = y;
+    owner[3 * index + 2] = z;
+    const [cx, cy, cz] = this.center;
+    const layout = new Float32Array([
+      (x - cx) / this.scale,
+      (y - cy) / this.scale,
+      this.dimValue === 2 ? 0 : (z - cz) / this.scale
+    ]);
+    this.ctx.device.queue.writeBuffer(buffers.positions, 16 * index, layout);
+    this.overrideList.set(index, this.lastSubmittedBatchIdValue);
+    this.reheat();
+  }
+  /**
+   * iterationsDone = 0, settledCount = 0 (a queued state write), model.onReheat(writer); nothing else (D8: the
+   * speed controller keeps its state). `settled` is recomputed at once (PLAN DECISION 8). Allowed before load().
+   * PLAN DECISION 21: the id of the last batch submitted so far is remembered; a batch with that id or an older
+   * one was computed from the pre-reheat counter, so its landed settledCount is taken as 0 (see onLanded) and a
+   * drag or unpin can never leave the simulation settled through a batch that was already in flight.
+   */
+  reheat() {
+    this.assertNotDisposed();
+    this.iterationsDoneValue = 0;
+    this.settledCountValue = 0;
+    this.reheatedAfterBatchId = this.lastSubmittedBatchIdValue;
+    this.writer.set("settledCount", 0);
+    this.model.onReheat(this.writer);
+    this.settledValue = this.computeSettled();
+  }
+  /**
+   * Live tuning (spec 3.3, 7.17): `dim` differing from the current -> E_INVALID_ARGUMENT; `maxInFlight` differing
+   * -> E_INVALID_ARGUMENT (the ring is sized by it); a non-null `nodeSize` -> E_UNSUPPORTED; the record is
+   * replaced through `resolve(patch, current)`; a change of the model's override set (a force LAW) recompiles
+   * and re-binds; scale / center changes reach the next batch through the shared params of every slot (the
+   * model's toScene reads them); then model.onSetParams(patch, writer) and reheat().
+   * @param patch - the fields to change
+   */
+  setParams(patch) {
+    this.assertNotDisposed();
+    const current = this.optionsValue;
+    const { dim, maxInFlight } = patch;
+    if (dim !== void 0 && dim !== this.dimValue) {
+      throw invalidArgument(
+        "dim",
+        dim,
+        this.dimValue,
+        "dim is fixed at construction; graphty-element re-creates the engine on a view-mode switch (spec 7.13)"
+      );
+    }
+    if (maxInFlight !== void 0 && maxInFlight !== this.maxInFlight) {
+      throw invalidArgument(
+        "maxInFlight",
+        maxInFlight,
+        this.maxInFlight,
+        "maxInFlight is fixed at construction (the uniform ring is sized by it)"
+      );
+    }
+    const nodeSize = optionField(patch, "nodeSize");
+    if (nodeSize !== void 0 && nodeSize !== null) {
+      throw new WebGpuGraphError("E_UNSUPPORTED", "nodeSize (adjustSizes) is deferred (spec 7.14)", {
+        option: "nodeSize",
+        hint: "leave nodeSize null; the size correction ships in a later slice"
+      });
+    }
+    const next = this.resolveOptions(patch, current);
+    const scale = scaleOf(next);
+    const center = centerOf(next);
+    const before = stableKey(this.model.overrides(current));
+    const after = stableKey(this.model.overrides(next));
+    this.optionsValue = next;
+    this.scale = scale;
+    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) };
+      this.startBind(resources, overrides);
+    }
+    this.model.onSetParams(patch, this.writer);
+    this.reheat();
+  }
+  // ---------------------------------------------------------------- dispose and device loss
+  /**
+   * Discards in-flight batches (their promises resolve), destroys every simulation buffer and the ring, trims
+   * the pool, unregisters the loss listener; state "disposed"; idempotent.
+   */
+  dispose() {
+    if (this.stateValue === "disposed") {
+      return;
+    }
+    this.stateValue = "disposed";
+    this.teardown();
+  }
+  // ---------------------------------------------------------------- private: the batch driver
+  /**
+   * The serialised submission of one pending batch: awaits the bind / warm promise and allocator.check(), then
+   * records and submits unless the record went stale meanwhile; wires the readback handlers. A record that went
+   * stale while waiting (a load() or dispose() superseded it) RESOLVES even when the wait rejected (PLAN
+   * DECISION 8: the rejection belongs to the superseded generation -- a bind that failed E_SHADER_COMPILE, or
+   * the ring's E_DISPOSED after dispose() tore it down under a running bind).
+   * @param record - the pending batch
+   */
+  async submitBatch(record) {
+    try {
+      await this.ready;
+      await this.ctx.allocator.check();
+    } catch (err) {
+      this.finish(record);
+      if (this.isStale(record)) {
+        record.resolve();
+        return;
+      }
+      if (hasErrorCode(err, "E_OUT_OF_MEMORY")) {
+        this.outOfMemory();
+      }
+      record.reject(asError(err));
+      return;
+    }
+    if (this.isStale(record)) {
+      this.finish(record);
+      record.resolve();
+      return;
+    }
+    let submitted;
+    try {
+      submitted = this.recordAndSubmit(record);
+    } catch (err) {
+      this.finish(record);
+      record.reject(asError(err));
+      return;
+    }
+    submitted.readback.then(
+      (bytes) => {
+        this.onLanded(record, bytes);
+      },
+      (err) => {
+        this.onFailed(record, err);
+      }
+    );
+  }
+  /**
+   * Flushes the host writes, fills k ring slots, records k iterations (only the last one runs the model's toScene
+   * epilogue, PLAN DECISION 2) + the two readbacks into one CommandBatch and submits it (spec 7.19 items 4-5).
+   * @param record - the pending batch
+   * @returns the submitted batch
+   */
+  recordAndSubmit(record) {
+    const buffers = this.requireBuffers();
+    const { k: k2 } = record;
+    const { device } = this.ctx;
+    if (this.fixedDirty) {
+      device.queue.writeBuffer(buffers.fixed, 0, this.fixedWords);
+      this.fixedDirty = false;
+    }
+    this.flushStateWrites(buffers.state);
+    const first = this.ring.reserve(k2);
+    for (let i = 0; i < k2; i++) {
+      const flags = i === 0 && this.firstPending ? FA2_FLAG_FIRST : 0;
+      this.ring.write(first + i, this.model.params, this.paramsForSlot(this.iterationsSubmitted + i, i, flags));
+    }
+    this.ring.flush();
+    const batch = new CommandBatch(this.ctx, `${this.label}/batch`, this.generationValue);
+    const beforeEpilogue = this.lastIterationStage();
+    for (let i = 0; i < k2; i++) {
+      this.model.recordIteration(batch, first + i, this.tierValue, i === k2 - 1 ? void 0 : beforeEpilogue);
+    }
+    batch.endPass();
+    const scene = batch.readback(buffers.scene, 0, 12 * this.n);
+    const state = batch.readback(buffers.state, 0, STATE_HEADER_BYTES + k2 * this.traceBytes);
+    const { profiler } = this.ctx;
+    const profile = profiler === null ? null : profiler.resolveInto(batch);
+    const submitted = batch.submit();
+    record.submitted = submitted;
+    record.id = submitted.id;
+    record.sceneOffset = scene.offset;
+    record.stateOffset = state.offset;
+    record.profile = profile;
+    record.startedAt = performance.now();
+    this.lastSubmittedBatchIdValue = submitted.id;
+    this.iterationsSubmitted += k2;
+    this.firstPending = false;
+    return submitted;
+  }
+  /**
+   * A landed readback (spec 7.19 item 6): stale -> discard; else the scene bytes go into the owner's array row by
+   * row (skipping overridden rows, clearing overrides older than this batch), the header refreshes the shadow,
+   * the stats are decoded through the model (msPerIteration from the profiler or the wall time, PLAN DECISION 3),
+   * iterationsDone += k and settled is recomputed -- with the landed settledCount taken as 0 when the batch was
+   * submitted before the last reheat() (PLAN DECISION 21; the header is still absorbed and the stats decoded).
+   * @param record - the pending batch
+   * @param bytes - the batch's readback bytes
+   */
+  onLanded(record, bytes) {
+    this.finish(record);
+    const { owner } = this;
+    if (this.isStale(record) || owner === null) {
+      record.resolve();
+      return;
+    }
+    try {
+      const { k: k2 } = record;
+      const { n } = this;
+      const needed = Math.max(
+        record.sceneOffset + 12 * n,
+        record.stateOffset + STATE_HEADER_BYTES + k2 * this.traceBytes
+      );
+      if (bytes.byteLength < needed) {
+        record.resolve();
+        return;
+      }
+      this.copyScene(owner, bytes, record);
+      const header = new DataView(bytes, record.stateOffset, STATE_HEADER_BYTES);
+      const trace = new DataView(bytes, record.stateOffset + STATE_HEADER_BYTES, k2 * this.traceBytes);
+      this.writer.absorb(header);
+      const settledCount = this.model.state.readField(header, "settledCount");
+      if (typeof settledCount !== "number") {
+        throw invalidArgument("settledCount", settledCount, "a scalar", "settledCount must be a scalar field");
+      }
+      const ms = this.batchMilliseconds(record, bytes);
+      this.statsValue = withMs(this.model.readStats(header, trace), ms / k2);
+      this.iterationsDoneValue += k2;
+      this.settledCountValue = record.id <= this.reheatedAfterBatchId ? 0 : settledCount;
+      this.settledValue = this.computeSettled();
+      record.resolve();
+    } catch (err) {
+      record.reject(asError(err));
+    }
+  }
+  /**
+   * A failed readback: a discarded batch's E_ABORTED resolves (PLAN DECISION 8); a lost device rejects
+   * E_DEVICE_LOST; everything else (E_VALIDATION, E_DISPOSED) rejects as is.
+   * @param record - the pending batch
+   * @param err - the rejection
+   */
+  onFailed(record, err) {
+    this.finish(record);
+    if (hasErrorCode(err, "E_ABORTED") && this.isStale(record)) {
+      record.resolve();
+      return;
+    }
+    if (this.ctx.state === "lost" && !hasErrorCode(err, "E_DEVICE_LOST")) {
+      record.reject(
+        new WebGpuGraphError("E_DEVICE_LOST", "the device was lost while the batch was in flight", {
+          reason: "unknown",
+          message: asError(err).message
+        })
+      );
+      return;
+    }
+    record.reject(asError(err));
+  }
+  /**
+   * Copies the scene bytes of a landed batch into the owner's array, honouring the override list (spec 7.12).
+   * @param owner - the owner's array
+   * @param bytes - the readback
+   * @param record - the batch
+   */
+  copyScene(owner, bytes, record) {
+    const { n } = this;
+    const scene = new Float32Array(bytes, record.sceneOffset, 3 * n);
+    if (this.overrideList.size === 0) {
+      owner.set(scene);
+      return;
+    }
+    for (let i = 0; i < n; i++) {
+      const after = this.overrideList.get(i);
+      if (after !== void 0 && after >= record.id) {
+        continue;
+      }
+      owner[3 * i] = scene[3 * i];
+      owner[3 * i + 1] = scene[3 * i + 1];
+      owner[3 * i + 2] = scene[3 * i + 2];
+    }
+    for (const [i, after] of this.overrideList) {
+      if (after < record.id) {
+        this.overrideList.delete(i);
+      }
+    }
+  }
+  /**
+   * The batch's duration in milliseconds: the profiler's pass timings summed when present, else wall time.
+   * @param record - the batch
+   * @param bytes - its readback (the profiler's resolve lands in it)
+   * @returns milliseconds
+   */
+  batchMilliseconds(record, bytes) {
+    const { profiler } = this.ctx;
+    if (profiler !== null && record.profile !== null) {
+      const timings = profiler.timings(bytes, record.profile);
+      if (timings.length > 0) {
+        let ns = 0;
+        for (const timing of timings) {
+          ns += timing.ns;
+        }
+        return ns / 1e6;
+      }
+    }
+    return performance.now() - record.startedAt;
+  }
+  /**
+   * Whether a record belongs to an earlier generation, was discarded, or the simulation left "loaded".
+   * @param record - the batch
+   * @returns true when its readback must be ignored
+   */
+  isStale(record) {
+    return record.stale || this.stateValue !== "loaded" || record.generation !== this.generationValue;
+  }
+  /**
+   * Removes a record from the pending list (idempotent).
+   * @param record - the batch
+   */
+  finish(record) {
+    const at = this.pending.indexOf(record);
+    if (at >= 0) {
+      this.pending.splice(at, 1);
+    }
+  }
+  /** Marks every pending batch stale and discards the submitted ones (their readbacks resolve empty or E_ABORTED). */
+  discardPending() {
+    for (const record of this.pending) {
+      record.stale = true;
+      record.submitted?.discard();
+    }
+  }
+  /** An OOM surfaced by allocator.check(): every simulation buffer is destroyed and the state returns to "created". */
+  outOfMemory() {
+    this.discardPending();
+    this.destroyBuffers();
+    this.ctx.allocator.reset();
+    this.settledValue = false;
+    this.stateValue = "created";
+  }
+  /**
+   * The E_ABORTED of run().
+   * @returns the error
+   */
+  abortedError() {
+    return new WebGpuGraphError("E_ABORTED", `${this.label}: run() aborted by the signal`, {
+      batchId: this.lastSubmittedBatchIdValue
+    });
+  }
+  // ---------------------------------------------------------------- private: params, state writes, toScene
+  /**
+   * The uniform values of one iteration slot: the model's values with the shared fields on top (PLAN DECISION 6).
+   * @param global - the global iteration index (iterationsSubmitted + i)
+   * @param index - the slot index within the batch (the trace slot)
+   * @param flags - FA2_FLAG_FIRST for the first iteration after load(), else 0
+   * @returns the values
+   */
+  paramsForSlot(global, index, flags) {
+    const [cx, cy, cz] = this.center;
+    const shared = {
+      n: this.n,
+      dim: this.dimValue,
+      flags,
+      iterationIndex: index,
+      seed: this.seedU32(),
+      scale: this.scale,
+      center: [cx, cy, cz, 0],
+      settleThreshold: this.settleThreshold()
+    };
+    return { ...this.model.paramsFor(global, this.optionsValue), ...shared };
+  }
+  /**
+   * The option seed as a u32 (0 when unseeded), the near-field hash seed of P4.
+   * @returns the seed
+   */
+  seedU32() {
+    const { seed } = this.optionsValue;
+    if (seed === null || seed === void 0 || !Number.isFinite(seed)) {
+      return 0;
+    }
+    return Math.floor(Math.abs(seed)) % 4294967296;
+  }
+  /**
+   * Writes the queued state fields, each as one writeBuffer of its own byte range (PLAN DECISION 5).
+   * @param state - the state buffer
+   */
+  flushStateWrites(state) {
+    const fields = this.writer.takeQueued();
+    if (fields.length === 0) {
+      return;
+    }
+    const bytes = this.writer.headerBytes();
+    const block = this.model.state;
+    for (const field of fields) {
+      const offset = block.offsetOf(field);
+      const size = 4 * fieldWidth(fieldTypeOf(block, field));
+      this.ctx.device.queue.writeBuffer(state, offset, bytes, offset, size);
+    }
+  }
+  /**
+   * The stage that precedes the toScene epilogue in model.stages (the `upTo` of every iteration but the last), or
+   * undefined when the model has no epilogue or lists it first (every iteration then records every stage).
+   * @returns the stage name or undefined
+   */
+  lastIterationStage() {
+    const at = this.model.stages.indexOf(EPILOGUE_STAGE);
+    if (at <= 0) {
+      return void 0;
+    }
+    return this.model.stages[at - 1];
+  }
+  /**
+   * The settle threshold of the current options (FA2_DEFAULTS when absent).
+   * @returns the threshold
+   */
+  settleThreshold() {
+    return this.optionsValue.settleThreshold ?? FA2_DEFAULTS.settleThreshold;
+  }
+  /**
+   * The settle window of the current options (FA2_DEFAULTS when absent).
+   * @returns the window
+   */
+  settleWindow() {
+    return this.optionsValue.settleWindow ?? FA2_DEFAULTS.settleWindow;
+  }
+  /**
+   * The iteration budget (PLAN DECISION 1): options.maxIter, else options.iterations, else no budget.
+   * @returns the budget
+   */
+  iterationBudget() {
+    const maxIter = optionField(this.optionsValue, "maxIter");
+    if (typeof maxIter === "number") {
+      return maxIter;
+    }
+    const iterations = optionField(this.optionsValue, "iterations");
+    if (typeof iterations === "number") {
+      return iterations;
+    }
+    return Number.POSITIVE_INFINITY;
+  }
+  /**
+   * The settle rule of spec 7.17 over the counters of the last completed batch.
+   * @returns whether the layout is settled
+   */
+  computeSettled() {
+    if (this.stateValue !== "loaded") {
+      return false;
+    }
+    return this.n === 0 || this.iterationsDoneValue >= this.iterationBudget() || this.settledCountValue >= this.settleWindow();
+  }
+  // ---------------------------------------------------------------- private: buffers, upload, bind
+  /**
+   * Allocates the shared buffers (spec 7.3 sizes) and the model's BufferSpecs through the allocator (every buffer
+   * labelled); a `zero: true` spec must carry COPY_DST so it can be re-zeroed when kept across loads (PLAN
+   * DECISION 17). The state buffer is STATE_HEADER_BYTES + MAX_ITERATIONS_PER_STEP x model.trace.byteLength:
+   * contract 3.13 writes TRACE_RECORD_BYTES (32, the FA2 record) for the last factor; the model's block is the
+   * same number for FA2 and is what the simulation decodes the trace with, so it is the general rule (PLAN
+   * DECISION 4) and the constant is not imported here.
+   * @param n - the node count (> 0)
+   * @returns the buffers and the name -> Binding map
+   */
+  allocate(n) {
+    const { allocator } = this.ctx;
+    const { label } = this;
+    const groups = Math.ceil(n / this.ctx.workgroupSize);
+    const traceRegionBytes = MAX_ITERATIONS_PER_STEP * this.traceBytes;
+    const storageRw = BufferUsage.STORAGE | BufferUsage.COPY_SRC | BufferUsage.COPY_DST;
+    const positions = allocator.createBuffer({ label: `${label}/positions`, size: 16 * n, usage: storageRw });
+    const scene = allocator.createBuffer({
+      label: `${label}/scenePositions`,
+      size: 12 * n,
+      usage: BufferUsage.STORAGE | BufferUsage.COPY_SRC
+    });
+    const fixed = allocator.createBuffer({
+      label: `${label}/fixed`,
+      size: 4 * Math.ceil(n / 32),
+      usage: storageRw
+    });
+    const partials = allocator.createBuffer({
+      label: `${label}/partials`,
+      size: PARTIAL_BYTES * groups,
+      usage: storageRw
+    });
+    const state = allocator.createBuffer({
+      label: `${label}/state`,
+      size: STATE_HEADER_BYTES + traceRegionBytes,
+      usage: storageRw
+    });
+    const bindings = /* @__PURE__ */ new Map();
+    bindings.set("positions", wholeBinding(positions, 16 * n));
+    bindings.set("scenePositions", wholeBinding(scene, 12 * n));
+    bindings.set("fixed", wholeBinding(fixed, 4 * Math.ceil(n / 32)));
+    bindings.set("partials", wholeBinding(partials, PARTIAL_BYTES * groups));
+    bindings.set("state", { buffer: state, offset: 0, size: STATE_HEADER_BYTES, window: null });
+    bindings.set("trace", { buffer: state, offset: STATE_HEADER_BYTES, size: traceRegionBytes, window: null });
+    const model = /* @__PURE__ */ new Map();
+    for (const spec of this.model.buffers(n, this.dimValue)) {
+      if (SHARED_BUFFER_NAMES.includes(spec.name) || bindings.has(spec.name)) {
+        throw invalidArgument(
+          "BufferSpec.name",
+          spec.name,
+          "a name no other buffer uses",
+          `BufferSpec "${spec.name}" reuses a buffer name`
+        );
+      }
+      if (!Number.isInteger(spec.byteLength) || spec.byteLength <= 0 || spec.byteLength % 4 !== 0) {
+        throw invalidArgument(
+          "BufferSpec.byteLength",
+          spec.byteLength,
+          "a positive multiple of 4",
+          `BufferSpec "${spec.name}" has byteLength ${spec.byteLength}`
+        );
+      }
+      if (spec.zero && (spec.usage & BufferUsage.COPY_DST) === 0) {
+        throw invalidArgument(
+          "BufferSpec.usage",
+          spec.usage,
+          "COPY_DST on a zero: true spec",
+          `BufferSpec "${spec.name}" is zero: true but lacks COPY_DST`
+        );
+      }
+      const buffer = allocator.createBuffer({
+        label: `${label}/${spec.name}`,
+        size: spec.byteLength,
+        usage: spec.usage
+      });
+      model.set(spec.name, { buffer, spec });
+      bindings.set(spec.name, wholeBinding(buffer, spec.byteLength));
+    }
+    return { positions, scene, fixed, partials, state, model, bindings, traceRegionBytes };
+  }
+  /**
+   * Re-zeroes the buffers a same-size load() keeps: partials, the trace region and every `zero: true` model buffer.
+   * @param buffers - the kept buffers
+   */
+  clearKept(buffers) {
+    const { device } = this.ctx;
+    const encoder = device.createCommandEncoder({ label: `${this.label}/clear` });
+    encoder.clearBuffer(buffers.partials);
+    encoder.clearBuffer(buffers.state, STATE_HEADER_BYTES, buffers.traceRegionBytes);
+    for (const { buffer, spec } of buffers.model.values()) {
+      if (spec.zero) {
+        encoder.clearBuffer(buffer);
+      }
+    }
+    device.queue.submit([encoder.finish()]);
+  }
+  /**
+   * Destroys every simulation buffer through the allocator (the ring lives on until dispose()). While batches are
+   * still in flight the destruction is DEFERRED until their readbacks have settled: the GPU may still be copying
+   * out of `scene` / `state` and Dawn's Metal backend (dawn-node 0.4.0 on macOS) has taken the worker process
+   * down when a buffer with pending work was destroyed (the Vulkan backends defer internally). The simulation
+   * drops its references at once either way, so nothing here is reachable afterwards.
+   */
+  destroyBuffers() {
+    const { buffers } = this;
+    if (buffers === null) {
+      return;
+    }
+    this.buffers = null;
+    this.resources = null;
+    const doomed = [buffers.positions, buffers.scene, buffers.fixed, buffers.partials, buffers.state];
+    for (const { buffer } of buffers.model.values()) {
+      doomed.push(buffer);
+    }
+    this.afterInFlight(() => {
+      const { allocator } = this.ctx;
+      for (const buffer of doomed) {
+        allocator.destroy(buffer);
+      }
+    });
+  }
+  /**
+   * Runs `action` now when no submitted batch is in flight, otherwise once every in-flight readback has settled
+   * (resolved, discarded or rejected -- the staging slot is returned and the GPU work is done either way).
+   * @param action - the destruction to run
+   */
+  afterInFlight(action) {
+    const waits = [];
+    for (const record of this.pending) {
+      if (record.submitted !== null) {
+        waits.push(record.submitted.readback.catch(() => void 0));
+      }
+    }
+    if (waits.length === 0) {
+      action();
+      return;
+    }
+    void Promise.all(waits).then(action, action);
+  }
+  /**
+   * The buffers of the current load.
+   * @returns the buffers; E_NOT_LOADED when there are none
+   */
+  requireBuffers() {
+    const { buffers } = this;
+    if (buffers === null) {
+      throw new WebGpuGraphError("E_NOT_LOADED", `${this.label}: load() first`, { state: this.stateValue });
+    }
+    return buffers;
+  }
+  /**
+   * Repacks the seeded scene array into layout-unit vec4f (mass in .w, z = 0 in 2D), uploads it, and writes the
+   * initial centroid / bbox / rmsRadius / radius (f64 over the f32 values uploaded) with iteration 0,
+   * settledCount 0, meanDisplacement 0 into the state header, then model.onLoad(writer) and one whole-header
+   * writeBuffer (spec 7.4, 7.17, 7.18).
+   * @param buffers - the buffers
+   * @param positions - the seeded owner array
+   * @param mass - the resolved masses
+   */
+  uploadPositions(buffers, positions, mass) {
+    const { n, scale } = this;
+    const [cx, cy, cz] = this.center;
+    const packed = new Float32Array(4 * n);
+    for (let i = 0; i < n; i++) {
+      packed[4 * i] = (positions[3 * i] - cx) / scale;
+      packed[4 * i + 1] = (positions[3 * i + 1] - cy) / scale;
+      packed[4 * i + 2] = this.dimValue === 2 ? 0 : (positions[3 * i + 2] - cz) / scale;
+      packed[4 * i + 3] = mass[i];
+    }
+    this.ctx.device.queue.writeBuffer(buffers.positions, 0, packed);
+    let sx = 0;
+    let sy = 0;
+    let sz = 0;
+    const lo = [Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY];
+    const hi = [Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY];
+    for (let i = 0; i < n; i++) {
+      const x = packed[4 * i];
+      const y = packed[4 * i + 1];
+      const z = packed[4 * i + 2];
+      sx += x;
+      sy += y;
+      sz += z;
+      lo[0] = Math.min(lo[0], x);
+      lo[1] = Math.min(lo[1], y);
+      lo[2] = Math.min(lo[2], z);
+      hi[0] = Math.max(hi[0], x);
+      hi[1] = Math.max(hi[1], y);
+      hi[2] = Math.max(hi[2], z);
+    }
+    const mx = sx / n;
+    const my = sy / n;
+    const mz = sz / n;
+    let sumSq = 0;
+    let maxSq = 0;
+    for (let i = 0; i < n; i++) {
+      const dx = packed[4 * i] - mx;
+      const dy = packed[4 * i + 1] - my;
+      const dz = packed[4 * i + 2] - mz;
+      const q = dx * dx + dy * dy + dz * dz;
+      sumSq += q;
+      maxSq = Math.max(maxSq, q);
+    }
+    const { writer } = this;
+    writer.set("iteration", 0);
+    writer.set("settledCount", 0);
+    writer.set("meanDisplacement", 0);
+    writer.set("centroid", [mx, my, mz, 0]);
+    writer.set("min", [lo[0], lo[1], lo[2], 0]);
+    writer.set("max", [hi[0], hi[1], hi[2], 0]);
+    writer.set("rmsRadius", Math.sqrt(sumSq / n));
+    writer.set("radius", Math.sqrt(maxSq));
+    this.model.onLoad(writer);
+    this.ctx.device.queue.writeBuffer(buffers.state, 0, writer.headerBytes());
+    writer.clearQueued();
+  }
+  /**
+   * The weights binding of a load (3.10): "arcs" -> core.weights, "none" -> null, "column" -> the expanded array
+   * registered with residency.array(expanded, "weights", snapshot), the previous array object reused when the
+   * column and its version are unchanged (so the upload cache finds it).
+   * @param snapshot - the snapshot
+   * @param core - its core
+   * @param resolved - model.inputs().weights
+   * @returns the binding for the group-0 weights slot, or null
+   */
+  resolveWeightsBinding(snapshot, core, resolved) {
+    if (resolved.source === "arcs") {
+      this.weightsUpload = null;
+      return core.weights;
+    }
+    if (resolved.source === "none" || resolved.data === null || resolved.column === null) {
+      this.weightsUpload = null;
+      return null;
+    }
+    const previous = this.weightsUpload;
+    const reusable = previous !== null && previous.serial === snapshot.serial && previous.column === resolved.column && previous.version === resolved.column.version && previous.data.length === resolved.data.length;
+    const data = reusable && previous !== null ? previous.data : resolved.data;
+    const upload = this.ctx.residency.array(data, "weights", snapshot);
+    this.weightsUpload = {
+      serial: snapshot.serial,
+      column: resolved.column,
+      version: resolved.column.version,
+      data,
+      upload
+    };
+    return upload.binding;
+  }
+  /**
+   * The ModelResources of a load.
+   * @param core - the core
+   * @param weights - the resolved weights binding
+   * @param buffers - the buffers
+   * @returns the resources
+   */
+  makeResources(core, weights, buffers) {
+    const { bindings } = buffers;
+    return {
+      device: this.ctx.device,
+      caps: this.ctx.caps,
+      pipelines: this.ctx.pipelines,
+      core,
+      perm: null,
+      weights,
+      n: this.n,
+      dim: this.dimValue,
+      tier: this.tierValue,
+      ring: this.ring,
+      buffer: (name) => {
+        const binding = bindings.get(name);
+        if (binding === void 0) {
+          throw invalidArgument("name", name, [...bindings.keys()], `no simulation buffer named "${name}"`);
+        }
+        return binding;
+      }
+    };
+  }
+  /**
+   * Chains the compile + bind promise the next step() awaits on the PREVIOUS one (PLAN DECISION 20: binds are
+   * serialised on `ready` for load() and setParams() alike, so a superseded load()'s bind either fails its
+   * generation check before model.bind() or completes before its successor's bind starts -- it can never bind
+   * the model to destroyed buffers AFTER the new bind finished). The previous promise's rejection is swallowed by
+   * the chain (it belonged to the superseded generation); this promise's rejection is kept for the next step()
+   * (the derived catch only silences the unhandled-rejection warning).
+   * @param resources - the resources
+   * @param overrides - the merged override set
+   */
+  startBind(resources, overrides) {
+    const generation = this.generationValue;
+    const run = () => this.compileAndBind(resources, overrides, generation);
+    const promise = this.ready.catch(() => void 0).then(run);
+    void promise.catch(() => void 0);
+    this.ready = promise;
+  }
+  /**
+   * warm(model.specs()) then model.bind(); the await re-checks that the load is current before binding.
+   * @param resources - the resources
+   * @param overrides - the merged override set
+   * @param generation - the generation the bind belongs to
+   */
+  async compileAndBind(resources, overrides, generation) {
+    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) {
+      return;
+    }
+    await this.model.bind(resources, overrides);
+  }
+  // ---------------------------------------------------------------- private: inspect and debug runs
+  /**
+   * inspect(name): flush, read the named buffer back, Uint32Array for "fixed" and "trace", Float32Array otherwise.
+   * @param name - a shared or BufferSpec name
+   * @returns the words
+   */
+  async inspectBuffer(name) {
+    this.assertLoaded();
+    const { buffers } = this;
+    const binding = buffers?.bindings.get(name);
+    if (buffers === null || binding === void 0) {
+      throw invalidArgument(
+        "name",
+        name,
+        buffers === null ? [] : [...buffers.bindings.keys()],
+        `inspect("${name}"): no such buffer`
+      );
+    }
+    await this.flush();
+    const bytes = await this.ctx.readback.read(binding.buffer, binding.size, void 0, binding.offset);
+    return name === "fixed" || name === "trace" ? new Uint32Array(bytes) : new Float32Array(bytes);
+  }
+  /**
+   * debugRunStages(upTo): one iteration truncated after a stage, submitted alone after flush(), awaited through
+   * a header readback; never advances the counters or the FA2_FLAG_FIRST flag (PLAN DECISION 9).
+   * @param upTo - a model stage name
+   */
+  async runStages(upTo) {
+    this.assertLoaded();
+    if (!this.model.stages.includes(upTo)) {
+      throw invalidArgument(
+        "upTo",
+        upTo,
+        [...this.model.stages],
+        `debugRunStages("${upTo}"): not a stage of ${this.model.kind}`
+      );
+    }
+    if (this.n === 0) {
+      return;
+    }
+    await this.flush();
+    await this.ready;
+    await this.ctx.allocator.check();
+    this.assertLoaded();
+    const buffers = this.requireBuffers();
+    const { device } = this.ctx;
+    if (this.fixedDirty) {
+      device.queue.writeBuffer(buffers.fixed, 0, this.fixedWords);
+      this.fixedDirty = false;
+    }
+    this.flushStateWrites(buffers.state);
+    const slot = this.ring.reserve(1);
+    this.ring.write(
+      slot,
+      this.model.params,
+      this.paramsForSlot(this.iterationsSubmitted, 0, this.firstPending ? FA2_FLAG_FIRST : 0)
+    );
+    this.ring.flush();
+    const batch = new CommandBatch(this.ctx, `${this.label}/debug`, this.generationValue);
+    this.model.recordIteration(batch, slot, this.tierValue, upTo);
+    batch.endPass();
+    batch.readback(buffers.state, 0, STATE_HEADER_BYTES);
+    const submitted = batch.submit();
+    this.lastSubmittedBatchIdValue = submitted.id;
+    await submitted.readback;
+  }
+  // ---------------------------------------------------------------- private: lifecycle
+  /**
+   * Device loss (spec 5.7): every pending promise rejects E_DEVICE_LOST, the simulation is disposed.
+   * @param info - the loss info
+   */
+  onDeviceLost(info) {
+    if (this.stateValue === "disposed") {
+      return;
+    }
+    const error = new WebGpuGraphError("E_DEVICE_LOST", `device lost (${info.reason}): ${info.message}`, {
+      reason: info.reason,
+      message: info.message
+    });
+    const pending = this.pending.splice(0);
+    this.stateValue = "disposed";
+    for (const record of pending) {
+      record.stale = true;
+      record.reject(error);
+    }
+    this.teardown();
+  }
+  /** Releases everything once: pending batches discarded, buffers and ring destroyed, pool trimmed, listener unregistered. */
+  teardown() {
+    if (this.torndown) {
+      return;
+    }
+    this.torndown = true;
+    this.discardPending();
+    this.destroyBuffers();
+    this.afterInFlight(() => {
+      this.ring.destroy();
+    });
+    if (this.ctx.state === "ready") {
+      this.ctx.pool.trim();
+    }
+    this.unregisterLost();
+    this.core = null;
+    this.snapshot = null;
+    this.owner = null;
+    this.weightsUpload = null;
+  }
+  /** E_DISPOSED after dispose() or device loss. */
+  assertNotDisposed() {
+    if (this.stateValue === "disposed") {
+      throw disposedError(this.label);
+    }
+  }
+  /** E_NOT_LOADED before load(), E_DISPOSED after dispose(). */
+  assertLoaded() {
+    if (this.stateValue === "created") {
+      throw new WebGpuGraphError("E_NOT_LOADED", `${this.label}: load() first`, { state: "created" });
+    }
+    this.assertNotDisposed();
+  }
+}
+const NODE_MASS_HINT = "write a role 'mass' node column (nodes.set(name, vec, { role: 'mass', replaceRole: true })) or pass a Float32Array; @graphty/layout's resolveNodeVector does this on the CPU path";
+function invalid$1(argument, value, expected, message) {
+  return new WebGpuGraphError("E_INVALID_ARGUMENT", message, { argument, value, expected });
+}
+function checkMass(mass, source) {
+  for (let i = 0; i < mass.length; i++) {
+    const v = mass[i];
+    if (!Number.isFinite(v) || v <= 0) {
+      throw new WebGpuGraphError(
+        "E_INVALID_ARGUMENT",
+        `${source}: mass[${i}] = ${v} is not a finite number > 0`,
+        {
+          argument: "nodeMass",
+          value: v,
+          index: i,
+          expected: "finite masses > 0"
+        }
+      );
+    }
+  }
+}
+function degreePlusOne(s) {
+  const n = s.nodeCount;
+  const degree2 = s.outDegree();
+  const out = new Float32Array(n);
+  for (let i = 0; i < n; i++) {
+    out[i] = degree2[i] + 1;
+  }
+  return out;
+}
+function massFromColumn(s, column) {
+  const { name } = column.meta;
+  if (column.meta.components !== 1) {
+    throw invalid$1(
+      "nodeMass",
+      name,
+      "a one-component numeric node column",
+      `node column "${name}" has ${column.meta.components} components; a mass column has one`
+    );
+  }
+  let values;
+  switch (column.dtype) {
+    case "f32":
+    case "f64": {
+      const view = s.nodes.gpuView(name);
+      const out2 = view instanceof Float32Array ? view : new Float32Array(view);
+      checkMass(out2, `node column "${name}"`);
+      return out2;
+    }
+    case "u32":
+    case "i32":
+      values = s.nodes.gpuView(name);
+      break;
+    case "u8":
+      values = column.data;
+      break;
+    default:
+      throw invalid$1(
+        "nodeMass",
+        name,
+        "a numeric node column (f32, f64, u32, i32, u8)",
+        `node column "${name}" is ${column.dtype}, not numeric`
+      );
+  }
+  const out = new Float32Array(s.nodeCount);
+  for (let i = 0; i < out.length; i++) {
+    out[i] = values[i];
+  }
+  checkMass(out, `node column "${name}"`);
+  return out;
+}
+function resolveNodeMass(s, spec) {
+  const n = s.nodeCount;
+  if (spec === null || spec === void 0) {
+    const column = s.nodes.byRole("mass");
+    if (column === null) {
+      return degreePlusOne(s);
+    }
+    return massFromColumn(s, column);
+  }
+  if (spec instanceof Float32Array) {
+    if (spec.length !== n) {
+      throw invalid$1("nodeMass", spec.length, `${n} values`, `nodeMass has ${spec.length} values, expected ${n}`);
+    }
+    checkMass(spec, "nodeMass");
+    return spec;
+  }
+  if (typeof spec === "string") {
+    const column = s.nodes.get(spec);
+    if (column === null) {
+      throw invalid$1(
+        "nodeMass",
+        spec,
+        "an existing numeric node column",
+        `nodeMass names node column "${spec}", which the snapshot does not hold`
+      );
+    }
+    return massFromColumn(s, column);
+  }
+  if (ArrayBuffer.isView(spec)) {
+    throw invalid$1(
+      "nodeMass",
+      "typed array",
+      "a Float32Array",
+      "nodeMass must be a Float32Array, a column name or null"
+    );
+  }
+  throw new WebGpuGraphError(
+    "E_UNSUPPORTED",
+    `nodeMass as a Record is not supported on the GPU path: ${NODE_MASS_HINT}`,
+    {
+      option: "nodeMass",
+      hint: NODE_MASS_HINT
+    }
+  );
+}
+function resolveWeights(s, spec) {
+  if (spec === true) {
+    return { data: s.weights, source: "arcs", column: null };
+  }
+  if (spec === false || spec === null || spec === void 0) {
+    return { data: null, source: "none", column: null };
+  }
+  if (typeof spec !== "string") {
+    throw invalid$1(
+      "weight",
+      spec,
+      "true, false, null or an edge column name",
+      "weight must be true, false, null or an edge column name"
+    );
+  }
+  const column = s.edges.get(spec);
+  if (column === null) {
+    throw invalid$1(
+      "weight",
+      spec,
+      "an existing numeric edge column",
+      `weight names edge column "${spec}", which the snapshot does not hold`
+    );
+  }
+  if (column.meta.components !== 1) {
+    throw invalid$1(
+      "weight",
+      spec,
+      "a one-component numeric edge column",
+      `edge column "${spec}" has ${column.meta.components} components; a weight column has one`
+    );
+  }
+  switch (column.dtype) {
+    case "f32":
+    case "f64":
+    case "u32":
+    case "i32": {
+      const view = s.edges.gpuView(spec);
+      const expanded = expandEdges(s, view);
+      const data = expanded instanceof Float32Array ? expanded : new Float32Array(expanded);
+      return { data, source: "column", column };
+    }
+    case "string":
+    case "list":
+    case "json":
+      s.edges.gpuView(spec);
+      throw invalid$1("weight", spec, "a numeric edge column", `edge column "${spec}" is ${column.dtype}`);
+    default:
+      throw invalid$1(
+        "weight",
+        spec,
+        "an f32 / f64 / u32 / i32 edge column",
+        `edge column "${spec}" is ${column.dtype}: its gpuView is packed words, not per-edge values`
+      );
+  }
+}
+class RepulsionExact {
+  /**
+   * Holds the two compiled kernels; create() is the only caller.
+   * @param repulsion - the K3 kernel
+   * @param speedFinalize - the K4 kernel
+   * @param caps - the device caps the dispatch planner reads
+   * @param overrides - the override set both kernels were compiled with
+   */
+  constructor(repulsion, speedFinalize, caps, overrides) {
+    this.boundRepulsion = null;
+    this.boundSpeedFinalize = null;
+    this.repulsion = repulsion;
+    this.speedFinalize = speedFinalize;
+    this.caps = caps;
+    this.overrides = Object.freeze({
+      SWING_MODE: overrides.SWING_MODE,
+      STRONG_GRAVITY: overrides.STRONG_GRAVITY,
+      GRAVITY_CENTER: overrides.GRAVITY_CENTER
+    });
+    this.finalizePlan = plan1d(speedFinalize.workgroupSize, speedFinalize.workgroupSize, caps);
+  }
+  /**
+   * Compiles both kernels through the cache (the twin is selected by caps.features).
+   * @param pipelines - the context's pipeline cache
+   * @param caps - the device caps the dispatch planner reads
+   * @param overrides - the SWING_MODE / STRONG_GRAVITY / GRAVITY_CENTER set of this stage
+   * @returns the stage, ready for bind()
+   */
+  static async create(pipelines, caps, overrides) {
+    const [repulsionSpec, finalizeSpec] = RepulsionExact.specs(overrides);
+    const repulsion = await pipelines.kernel(repulsionSpec);
+    const speedFinalize = await pipelines.kernel(finalizeSpec);
+    return new RepulsionExact(repulsion, speedFinalize, caps, overrides);
+  }
+  /**
+   * The two specs (for warm() and the compile matrix).
+   * @param overrides - the override set of the stage
+   * @returns the K3 spec then the K4 spec
+   */
+  static specs(overrides) {
+    return [
+      kernelSpec("fa2-repulsion-exact", {
+        SWING_MODE: overrides.SWING_MODE,
+        STRONG_GRAVITY: overrides.STRONG_GRAVITY,
+        GRAVITY_CENTER: overrides.GRAVITY_CENTER
+      }),
+      kernelSpec("fa2-speed-finalize", { SWING_MODE: overrides.SWING_MODE })
+    ];
+  }
+  /**
+   * Creates the bind groups once per load(): K3 takes pos, state (S), force, oldForce, fixedMask, partials and the
+   * params slot; K4 takes partials, state (S), trace (T) and the params slot (the 3.10.1 binding names). The state
+   * header and the trace region are two disjoint ranges of one buffer, which Kernel.bind() accepts (no writable alias).
+   * @param resources - the buffers of spec 7.3
+   */
+  bind(resources) {
+    this.boundRepulsion = this.repulsion.bind({
+      pos: resources.pos,
+      S: resources.state,
+      force: resources.force,
+      oldForce: resources.oldForce,
+      fixedMask: resources.fixedMask,
+      partials: resources.partials,
+      P: resources.params
+    });
+    this.boundSpeedFinalize = this.speedFinalize.bind({
+      partials: resources.partials,
+      S: resources.state,
+      T: resources.trace,
+      P: resources.params
+    });
+  }
+  /**
+   * Records K3 (plan1d(n)) then K4 (1 workgroup) with the params slot's dynamic offset.
+   * @param pass - the open compute pass of the batch
+   * @param n - the node count (rows [0, n) of pos / force)
+   * @param paramsOffset - the dynamic offset of this iteration's Fa2Params slot in the uniform ring
+   */
+  record(pass, n, paramsOffset) {
+    this.recordRepulsion(pass, n, paramsOffset);
+    this.recordSpeedFinalize(pass, paramsOffset);
+  }
+  /**
+   * Records K3 only (the inspect() stage split, spec 11.9 item 2).
+   * @param pass - the open compute pass
+   * @param n - the node count
+   * @param paramsOffset - the dynamic offset of the Fa2Params slot
+   * @internal
+   */
+  recordRepulsion(pass, n, paramsOffset) {
+    const bound = this.bound(this.boundRepulsion, "recordRepulsion");
+    const plan = plan1d(n, this.repulsion.workgroupSize, this.caps);
+    this.repulsion.dispatch(pass, bound, plan, [paramsOffset]);
+  }
+  /**
+   * Records K4 only.
+   * @param pass - the open compute pass
+   * @param paramsOffset - the dynamic offset of the Fa2Params slot
+   * @internal
+   */
+  recordSpeedFinalize(pass, paramsOffset) {
+    const bound = this.bound(this.boundSpeedFinalize, "recordSpeedFinalize");
+    this.speedFinalize.dispatch(pass, bound, this.finalizePlan, [paramsOffset]);
+  }
+  /**
+   * The bound kernel of a method, or E_NOT_LOADED when bind() has not run.
+   * @param bound - the cached BoundKernel, null before bind()
+   * @param method - the caller's name for the message
+   * @returns the bound kernel
+   */
+  bound(bound, method) {
+    if (bound === null) {
+      throw new WebGpuGraphError(
+        "E_NOT_LOADED",
+        `RepulsionExact.${method}(): bind() has not been called for this stage`,
+        {
+          state: "unbound"
+        }
+      );
+    }
+    return bound;
+  }
+}
+const FA2_STAGES = ["K1", "K2", "K3", "K4", "K5", "toScene"];
+const FORCE_BYTES_PER_NODE = 12;
+const FILL_PARAMS_BUFFER = "fillParams";
+const ONE_WORKGROUP = { x: 1, y: 1, z: 1, items: 1, stride: null };
+const K2_DEFAULTS = { LINLOG: false, DISTRIBUTED: false, TIER: 0, USE_PERM: false, HAS_WEIGHTS: false };
+const K5_DEFAULTS = { SWING_MODE: 0 };
+const U32_MODULUS = 4294967296;
+const DEFAULT_RESOLVED = Object.freeze({
+  ...FA2_DEFAULTS,
+  nodeMass: null,
+  nodeSize: null,
+  weight: null,
+  center: [0, 0, 0],
+  seed: null
+});
+function describeValue(value) {
+  if (value === null) {
+    return "null";
+  }
+  if (typeof value === "number" || typeof value === "boolean" || typeof value === "string") {
+    return String(value);
+  }
+  if (typeof value === "undefined") {
+    return "undefined";
+  }
+  if (typeof value === "object" && "length" in value && typeof value.length === "number") {
+    return `[${value.length} values]`;
+  }
+  return typeof value;
+}
+function invalid(argument, value, expected) {
+  return new WebGpuGraphError("E_INVALID_ARGUMENT", `${argument} must be ${expected}; got ${describeValue(value)}`, {
+    argument,
+    value,
+    expected
+  });
+}
+function pickNumber(name, given, fallback, check, expected) {
+  const value = given === void 0 ? fallback : given;
+  if (typeof value !== "number" || !Number.isFinite(value) || !check(value)) {
+    throw invalid(name, value, expected);
+  }
+  return value;
+}
+function pickBoolean(name, given, fallback) {
+  const value = given === void 0 ? fallback : given;
+  if (typeof value !== "boolean") {
+    throw invalid(name, value, "a boolean");
+  }
+  return value;
+}
+function pickDim(given, fallback) {
+  const value = given === void 0 ? fallback : given;
+  if (value !== 2 && value !== 3) {
+    throw invalid("dim", value, "2 or 3");
+  }
+  return value;
+}
+function pickCenter(given, fallback) {
+  if (given === void 0) {
+    return fallback;
+  }
+  const expected = "an array of 2 or 3 finite numbers";
+  const value = given;
+  if (typeof value !== "object" || value === null || !("length" in value)) {
+    throw invalid("center", given, expected);
+  }
+  const { length } = value;
+  if (length !== 2 && length !== 3) {
+    throw invalid("center", given, expected);
+  }
+  const x = given[0];
+  const y = given[1];
+  const z = length === 3 ? given[2] : 0;
+  if (typeof x !== "number" || typeof y !== "number" || typeof z !== "number" || !Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z)) {
+    throw invalid("center", given, expected);
+  }
+  return [x, y, z];
+}
+function pickSeed(given, fallback) {
+  if (given === void 0) {
+    return fallback;
+  }
+  const value = given;
+  if (value !== null && (typeof value !== "number" || !Number.isFinite(value))) {
+    throw invalid("seed", given, "a finite number or null");
+  }
+  return value;
+}
+function isPositiveInteger(value) {
+  return Number.isInteger(value) && value >= 1;
+}
+function seedWord(seed) {
+  if (seed === null) {
+    return 0;
+  }
+  return Math.floor(Math.abs(seed)) % U32_MODULUS;
+}
+function scalar(values, name) {
+  const value = values[name];
+  if (typeof value !== "number") {
+    throw invalid(name, value, "a scalar field");
+  }
+  return value;
+}
+function vector(values, name) {
+  const value = values[name];
+  if (typeof value === "number") {
+    throw invalid(name, value, "a vector field");
+  }
+  return value;
+}
+function subset(merged, defaults) {
+  const out = {};
+  for (const name of Object.keys(defaults)) {
+    out[name] = name in merged ? merged[name] : defaults[name];
+  }
+  return out;
+}
+function repulsionOverrides(merged) {
+  return {
+    SWING_MODE: merged.SWING_MODE === 1 ? 1 : 0,
+    STRONG_GRAVITY: merged.STRONG_GRAVITY === true,
+    GRAVITY_CENTER: merged.GRAVITY_CENTER === 1 ? 1 : 0
+  };
+}
+function resolveForceAtlas2Options(options, previous) {
+  const o = options ?? {};
+  const base = previous ?? DEFAULT_RESOLVED;
+  if (previous !== void 0 && o.maxInFlight !== void 0 && o.maxInFlight !== previous.maxInFlight) {
+    throw new WebGpuGraphError(
+      "E_INVALID_ARGUMENT",
+      `maxInFlight cannot change after creation (the uniform ring is sized by it): got ${describeValue(o.maxInFlight)}, current ${previous.maxInFlight}`,
+      { argument: "maxInFlight", value: o.maxInFlight, expected: previous.maxInFlight }
+    );
+  }
+  const nodeSize = o.nodeSize === void 0 ? base.nodeSize : o.nodeSize;
+  if (nodeSize !== null) {
+    throw new WebGpuGraphError(
+      "E_UNSUPPORTED",
+      "nodeSize (the adjustSizes correction) is not supported by the GPU ForceAtlas2 yet (spec 7.14)",
+      { option: "nodeSize", hint: "pass nodeSize: null; the size-aware repulsion is deferred (spec 7.2, Q-25)" }
+    );
+  }
+  const resolved = {
+    maxIter: pickNumber("maxIter", o.maxIter, base.maxIter, isPositiveInteger, "an integer >= 1"),
+    jitterTolerance: pickNumber("jitterTolerance", o.jitterTolerance, base.jitterTolerance, (v) => v > 0, "> 0"),
+    scalingRatio: pickNumber("scalingRatio", o.scalingRatio, base.scalingRatio, (v) => v > 0, "> 0"),
+    gravity: pickNumber("gravity", o.gravity, base.gravity, (v) => v >= 0, ">= 0"),
+    strongGravity: pickBoolean("strongGravity", o.strongGravity, base.strongGravity),
+    distributedAction: pickBoolean("distributedAction", o.distributedAction, base.distributedAction),
+    linlog: pickBoolean("linlog", o.linlog, base.linlog),
+    nodeMass: o.nodeMass === void 0 ? base.nodeMass : o.nodeMass,
+    nodeSize,
+    weight: o.weight === void 0 ? base.weight : o.weight,
+    dissuadeHubs: pickBoolean("dissuadeHubs", o.dissuadeHubs, base.dissuadeHubs),
+    dim: pickDim(o.dim, base.dim),
+    scale: pickNumber("scale", o.scale, base.scale, (v) => v > 0, "> 0"),
+    center: pickCenter(o.center, base.center),
+    seed: pickSeed(o.seed, base.seed),
+    settleThreshold: pickNumber("settleThreshold", o.settleThreshold, base.settleThreshold, (v) => v >= 0, ">= 0"),
+    settleWindow: pickNumber(
+      "settleWindow",
+      o.settleWindow,
+      base.settleWindow,
+      isPositiveInteger,
+      "an integer >= 1"
+    ),
+    iterationsPerStep: pickNumber(
+      "iterationsPerStep",
+      o.iterationsPerStep,
+      base.iterationsPerStep,
+      (v) => isPositiveInteger(v) && v <= MAX_ITERATIONS_PER_STEP,
+      `an integer in [1, ${MAX_ITERATIONS_PER_STEP}]`
+    ),
+    maxInFlight: pickNumber("maxInFlight", o.maxInFlight, base.maxInFlight, isPositiveInteger, "an integer >= 1")
+  };
+  return Object.freeze(resolved);
+}
+function resolveLayoutTuning(tuning) {
+  const t = tuning ?? {};
+  const repulsion = t.repulsion ?? LAYOUT_TUNING_DEFAULTS.repulsion;
+  if (repulsion !== "exact" && repulsion !== "grid" && repulsion !== "auto") {
+    throw invalid("repulsion", repulsion, '"exact", "grid" or "auto"');
+  }
+  const compat = t.compat ?? LAYOUT_TUNING_DEFAULTS.compat;
+  if (compat !== "paper" && compat !== "networkx") {
+    throw invalid("compat", compat, '"paper" or "networkx"');
+  }
+  const resolved = {
+    repulsion,
+    exactMaxNodes: pickNumber(
+      "exactMaxNodes",
+      t.exactMaxNodes,
+      LAYOUT_TUNING_DEFAULTS.exactMaxNodes,
+      isPositiveInteger,
+      "an integer >= 1"
+    ),
+    nearMax: pickNumber("nearMax", t.nearMax, LAYOUT_TUNING_DEFAULTS.nearMax, isPositiveInteger, "an integer >= 1"),
+    deterministic: pickBoolean("deterministic", t.deterministic, LAYOUT_TUNING_DEFAULTS.deterministic),
+    gridMax2D: pickNumber(
+      "gridMax2D",
+      t.gridMax2D,
+      LAYOUT_TUNING_DEFAULTS.gridMax2D,
+      isPositiveInteger,
+      "an integer >= 1"
+    ),
+    gridMax3D: pickNumber(
+      "gridMax3D",
+      t.gridMax3D,
+      LAYOUT_TUNING_DEFAULTS.gridMax3D,
+      isPositiveInteger,
+      "an integer >= 1"
+    ),
+    extentFactor: pickNumber(
+      "extentFactor",
+      t.extentFactor,
+      LAYOUT_TUNING_DEFAULTS.extentFactor,
+      (v) => v > 0,
+      "> 0"
+    ),
+    compat
+  };
+  return Object.freeze(resolved);
+}
+class ForceAtlas2Model {
+  /**
+   * Creates the model for one simulation.
+   * @param tuning - the resolved GPU-only tuning (compat selects SWING_MODE / GRAVITY_CENTER; repulsion and
+   *   exactMaxNodes the tier rule)
+   * @param resolved - the resolved option record at creation
+   */
+  constructor(tuning, resolved) {
+    this.kind = "forceatlas2";
+    this.stages = FA2_STAGES;
+    this.params = FA2_PARAMS;
+    this.state = FA2_STATE;
+    this.trace = FA2_TRACE;
+    this.resources = null;
+    this.bound = null;
+    this.resetOldForce = false;
+    this.openPass = null;
+    this.tuning = tuning;
+    this.current = resolved;
+  }
+  /**
+   * The SWING_MODE of this model: 1 in networkx mode (accumulated, position-mixed sums; m|F| local swing), else 0.
+   * @returns 0 or 1
+   */
+  get swingMode() {
+    return this.tuning.compat === "networkx" ? 1 : 0;
+  }
+  /**
+   * force 12n and oldForce 12n (zeroed) in BOTH swing modes (3.10.1: a writable slot is never aliased; mode 1 leaves
+   * oldForce unread and unwritten), plus the 256-byte FillParams uniform buffer the fill dispatches read. n = 0
+   * reports one node's worth of bytes so no zero-length buffer is ever created (spec 3.6).
+   * @param n - the node count
+   * @param _dim - the layout dimension (the force arrays are stride 3 in both)
+   * @returns the three model-owned buffer specs
+   */
+  buffers(n, _dim) {
+    const bytes = Math.max(1, n) * FORCE_BYTES_PER_NODE;
+    const usage = BufferUsage.STORAGE | BufferUsage.COPY_SRC | BufferUsage.COPY_DST;
+    return [
+      { name: "force", byteLength: bytes, usage, zero: true },
+      { name: "oldForce", byteLength: bytes, usage, zero: true },
+      {
+        name: FILL_PARAMS_BUFFER,
+        byteLength: UNIFORM_SLOT_BYTES,
+        usage: BufferUsage.UNIFORM | BufferUsage.COPY_DST,
+        zero: false
+      }
+    ];
+  }
+  /**
+   * { mass: resolveNodeMass(s, resolved.nodeMass), weights: resolveWeights(s, resolved.weight) } (3.13 inputs.ts),
+   * after the tier rule of spec 7.8 / lead f: `repulsion: "grid"` is E_UNSUPPORTED { feature: "repulsion.grid" }
+   * for any n and `"auto"` when n > exactMaxNodes (the grid tier lands in P4); `"exact"` always runs.
+   * @param s - the snapshot being loaded
+   * @param options - the simulation's current option record
+   * @returns the per-load inputs
+   */
+  inputs(s, options) {
+    const resolved = resolveForceAtlas2Options(options, this.current);
+    const { repulsion, exactMaxNodes } = this.tuning;
+    const n = s.nodeCount;
+    if (repulsion === "grid" || repulsion === "auto" && n > exactMaxNodes) {
+      throw new WebGpuGraphError(
+        "E_UNSUPPORTED",
+        repulsion === "grid" ? 'repulsion: "grid" is not available yet (the grid tier lands in P4)' : `the graph has ${n} nodes, above exactMaxNodes ${exactMaxNodes}, and the grid tier lands in P4`,
+        {
+          feature: "repulsion.grid",
+          hint: 'pass repulsion: "exact" (or raise exactMaxNodes) to run the exact tier at this size'
+        }
+      );
+    }
+    return { mass: resolveNodeMass(s, resolved.nodeMass), weights: resolveWeights(s, resolved.weight) };
+  }
+  /**
+   * { LINLOG, DISTRIBUTED, TIER: 0, SWING_MODE: compat === "networkx" ? 1 : 0, STRONG_GRAVITY, GRAVITY_CENTER:
+   * compat === "networkx" ? 1 : 0 }; USE_PERM / HAS_WEIGHTS are merged in by the simulation from ModelResources
+   * (3.10, never from core.hasWeights). A pure query: the simulation calls it with the current AND the next record
+   * inside setParams() to decide the recompile, so it never touches the model's record (PLAN DECISION 12).
+   * @param options - an option record (the simulation's current one, or the next one of a setParams patch)
+   * @returns the model's own override set
+   */
+  overrides(options) {
+    const resolved = resolveForceAtlas2Options(options, this.current);
+    const mode = this.swingMode;
+    return {
+      LINLOG: resolved.linlog,
+      DISTRIBUTED: resolved.distributedAction,
+      TIER: 0,
+      SWING_MODE: mode,
+      STRONG_GRAVITY: resolved.strongGravity,
+      GRAVITY_CENTER: mode
+    };
+  }
+  /**
+   * The seven module specs of an override set in dispatch order -- K1, K2, K3, K4, K5, toScene, fill -- each with
+   * only the override names its entry declares (K2 also USE_PERM / HAS_WEIGHTS), for warm() and the compile matrix.
+   * @param overrides - the merged override set (the model's plus USE_PERM / HAS_WEIGHTS)
+   * @param _subgroups - accepted for the ForceModel interface and unused: every reducing FA2 body carries
+   *   needs: ["subgroups"] in its registry entry and the composer picks the twin from caps.features (contract 4.3)
+   * @returns the specs
+   */
+  specs(overrides, _subgroups) {
+    const [repulsionSpec, speedSpec] = RepulsionExact.specs(repulsionOverrides(overrides));
+    return [
+      kernelSpec("fa2-stats-finalize"),
+      kernelSpec("fa2-attraction", subset(overrides, K2_DEFAULTS)),
+      repulsionSpec,
+      speedSpec,
+      kernelSpec("fa2-integrate", subset(overrides, K5_DEFAULTS)),
+      kernelSpec("fa2-to-scene"),
+      kernelSpec("fill")
+    ];
+  }
+  /**
+   * Compiles (through the cache) and binds every kernel against the buffers of this load(): K1, K2 (or the fill of
+   * force when arcCount === 0), K3 + K4 through RepulsionExact, K5, toScene, and the fill of oldForce; writes the
+   * FillParams { count: 3n, value: 0, mode: 0 } into the model's uniform buffer. With n === 0 nothing is bound.
+   * @param resources - the graph, the shared and model buffers, the ring and the cache
+   * @param overrides - the merged override set
+   */
+  async bind(resources, overrides) {
+    this.dropBound();
+    this.resources = resources;
+    const { n, pipelines, caps, core, perm, ring, device } = resources;
+    if (n === 0) {
+      return;
+    }
+    const [k1, k2, k5, toScene, fill] = await Promise.all([
+      pipelines.kernel(kernelSpec("fa2-stats-finalize")),
+      pipelines.kernel(kernelSpec("fa2-attraction", subset(overrides, K2_DEFAULTS))),
+      pipelines.kernel(kernelSpec("fa2-integrate", subset(overrides, K5_DEFAULTS))),
+      pipelines.kernel(kernelSpec("fa2-to-scene")),
+      pipelines.kernel(kernelSpec("fill"))
+    ]);
+    const repulsion = await RepulsionExact.create(pipelines, caps, repulsionOverrides(overrides));
+    if (this.resources !== resources) {
+      return;
+    }
+    const pos = resources.buffer("positions");
+    const scene = resources.buffer("scenePositions");
+    const fixed = resources.buffer("fixed");
+    const partials = resources.buffer("partials");
+    const state = resources.buffer("state");
+    const trace = resources.buffer("trace");
+    const force = resources.buffer("force");
+    const oldForce = resources.buffer("oldForce");
+    const fillParamsBuffer = resources.buffer(FILL_PARAMS_BUFFER);
+    const params = ring.binding(FA2_PARAMS);
+    const fillParams = {
+      buffer: fillParamsBuffer.buffer,
+      offset: fillParamsBuffer.offset,
+      size: FILL_PARAMS.byteLength,
+      window: null
+    };
+    const fillBytes = new ArrayBuffer(FILL_PARAMS.byteLength);
+    FILL_PARAMS.write(new DataView(fillBytes), { count: 3 * n, value: 0, mode: 0 });
+    device.queue.writeBuffer(fillParamsBuffer.buffer, fillParamsBuffer.offset, fillBytes);
+    const hasArcs = core.colIdx !== null;
+    repulsion.bind({ pos, state, trace, force, oldForce, fixedMask: fixed, partials, params });
+    const wg = k1.workgroupSize;
+    this.bound = {
+      n,
+      plan: plan1d(n, wg, caps),
+      fillPlan: plan1d(3 * n, wg, caps),
+      k1,
+      k1Bound: k1.bind({ partials, S: state, T: trace, P: params }),
+      k2,
+      k2Bound: hasArcs ? k2.bind({ ...graphBindings(core, perm, resources.weights), pos, force, P: params }) : null,
+      repulsion,
+      k5,
+      k5Bound: k5.bind({ force, oldForce, fixedMask: fixed, S: state, pos, partials, P: params }),
+      toScene,
+      toSceneBound: toScene.bind({ pos, scene, P: params }),
+      fill,
+      fillForceBound: hasArcs ? null : fill.bind({ dst: force, P: fillParams }),
+      fillOldBound: this.swingMode === 0 ? fill.bind({ dst: oldForce, P: fillParams }) : null
+    };
+  }
+  /**
+   * The Fa2Params values of one iteration (the simulation overwrites the shared fields n, dim, flags,
+   * iterationIndex, seed, scale, center and settleThreshold with the same values plus the flags).
+   * @param iteration - the trace slot of the iteration inside its batch
+   * @param options - the simulation's current option record
+   * @returns the uniform values
+   */
+  paramsFor(iteration, options) {
+    const { n } = this.requireResources();
+    const resolved = resolveForceAtlas2Options(options, this.current);
+    const { nearMax, extentFactor } = this.tuning;
+    return {
+      n,
+      dim: resolved.dim,
+      flags: 0,
+      tierStart: 0,
+      tierEnd: n,
+      iterationIndex: iteration,
+      seed: seedWord(resolved.seed),
+      nearMax,
+      scalingRatio: resolved.scalingRatio,
+      gravity: resolved.gravity,
+      jitterTolerance: resolved.jitterTolerance,
+      scale: resolved.scale,
+      center: [resolved.center[0], resolved.center[1], resolved.center[2], 0],
+      settleThreshold: resolved.settleThreshold,
+      extentFactor,
+      gridMax: 0,
+      levels: 0,
+      pad: [0, 0, 0, 0]
+    };
+  }
+  /**
+   * Records one iteration into the batch: K1, K2 (or the fill of force when arcCount === 0), K3, K4, K5 in the
+   * batch's ONE K1-K5 compute pass (opened by the first call of a batch and reused by every later call with the
+   * same batch.id, PLAN DECISION 2), then toScene in a second pass that ends it, stopping after stage `upTo` when
+   * given (spec 7.4; debugRunStages / inspect, spec 11.9 item 2). The simulation passes "K5" for iterations
+   * 0..k-2 and undefined for the last, so toScene runs once per batch. The first call after load() zeroes
+   * oldForce before K1 (paper mode). With n === 0 nothing is recorded (PLAN DECISION 9); a call before bind()
+   * completed is E_NOT_LOADED (never a silent no-op).
+   * @param batch - the batch being recorded
+   * @param slot - the UniformRing slot holding this iteration's Fa2Params
+   * @param tier - "exact" (the grid tier is E_UNSUPPORTED until P4; the simulation never passes "grid")
+   * @param upTo - a stage name to stop after; undefined records every stage including toScene
+   */
+  recordIteration(batch, slot, tier, upTo) {
+    if (tier === "grid") {
+      throw new WebGpuGraphError("E_UNSUPPORTED", "the grid repulsion tier lands in P4", {
+        feature: "repulsion.grid",
+        hint: 'pass repulsion: "exact"'
+      });
+    }
+    const resources = this.requireResources();
+    const stop = upTo === void 0 ? FA2_STAGES.length - 1 : this.stageIndex(upTo);
+    const { bound } = this;
+    if (bound === null) {
+      if (resources.n === 0) {
+        return;
+      }
+      throw new WebGpuGraphError(
+        "E_NOT_LOADED",
+        "the ForceAtlas2 model is not bound (bind() has not completed)",
+        {
+          state: "loaded"
+        }
+      );
+    }
+    const offset = resources.ring.offsetOf(slot);
+    const pass = this.openPass !== null && this.openPass.id === batch.id ? this.openPass.pass : batch.pass("fa2");
+    this.openPass = { id: batch.id, pass };
+    if (this.resetOldForce) {
+      this.resetOldForce = false;
+      if (bound.fillOldBound !== null) {
+        bound.fill.dispatch(pass, bound.fillOldBound, bound.fillPlan, [0]);
+      }
+    }
+    bound.k1.dispatch(pass, bound.k1Bound, ONE_WORKGROUP, [offset]);
+    if (stop < 1) {
+      return;
+    }
+    if (bound.k2Bound !== null) {
+      bound.k2.dispatch(pass, bound.k2Bound, bound.plan, [offset]);
+    } else if (bound.fillForceBound !== null) {
+      bound.fill.dispatch(pass, bound.fillForceBound, bound.fillPlan, [0]);
+    }
+    if (stop < 2) {
+      return;
+    }
+    bound.repulsion.recordRepulsion(pass, bound.n, offset);
+    if (stop < 3) {
+      return;
+    }
+    bound.repulsion.recordSpeedFinalize(pass, offset);
+    if (stop < 4) {
+      return;
+    }
+    bound.k5.dispatch(pass, bound.k5Bound, bound.plan, [offset]);
+    if (stop < 5) {
+      return;
+    }
+    this.openPass = null;
+    const scenePass = batch.pass("fa2-to-scene");
+    bound.toScene.dispatch(scenePass, bound.toSceneBound, bound.plan, [offset]);
+  }
+  /**
+   * speed = 1, speedEfficiency = 1, swing = 1, traction = 1 (mode 1 accumulates from 1; mode 0 overwrites them each
+   * iteration, the initial value is irrelevant); arms the oldForce reset of the next recordIteration.
+   * @param state - the state writer of the simulation
+   */
+  onLoad(state) {
+    state.set("speed", 1);
+    state.set("speedEfficiency", 1);
+    state.set("swing", 1);
+    state.set("traction", 1);
+    this.resetOldForce = true;
+  }
+  /**
+   * Mode 0: nothing (D8). Mode 1 (networkx): swing = traction = 1 (spec 7.2 "load() and reheat() reset them to 1").
+   * @param state - the state writer of the simulation
+   */
+  onReheat(state) {
+    if (this.swingMode === 1) {
+      state.set("swing", 1);
+      state.set("traction", 1);
+    }
+  }
+  /**
+   * Resets speed / speedEfficiency to 1 only when linlog, strongGravity or distributedAction changed (spec 7.17);
+   * a numeric tweak leaves the controller alone. The patch is validated by the same resolver the simulation uses
+   * and applied over the record of the constructor / the previous onSetParams -- the only place `current` moves
+   * (PLAN DECISION 12), so the comparison sees the record from BEFORE this setParams even though the simulation
+   * already queried overrides(next).
+   * @param patch - the setParams patch
+   * @param state - the state writer of the simulation
+   */
+  onSetParams(patch, state) {
+    const next = resolveForceAtlas2Options(patch, this.current);
+    const lawChanged = next.linlog !== this.current.linlog || next.strongGravity !== this.current.strongGravity || next.distributedAction !== this.current.distributedAction;
+    this.current = next;
+    if (lawChanged) {
+      state.set("speed", 1);
+      state.set("speedEfficiency", 1);
+    }
+  }
+  /**
+   * Decodes the state header and the k trace records of a completed batch (k = trace.byteLength / 32) into
+   * ForceAtlas2Stats: the exact tier with null grid fields; msPerIteration null (the simulation owns the clock).
+   * @param state - a DataView over the 256-byte state header
+   * @param trace - a DataView over the k Fa2Trace records of the batch
+   * @returns the stats
+   */
+  readStats(state, trace) {
+    const header = FA2_STATE.read(state);
+    const centroid = vector(header, "centroid");
+    const records = [];
+    const count = Math.floor(trace.byteLength / TRACE_RECORD_BYTES);
+    for (let i = 0; i < count; i++) {
+      const record = FA2_TRACE.read(trace, i * TRACE_RECORD_BYTES);
+      records.push({
+        swing: scalar(record, "swing"),
+        traction: scalar(record, "traction"),
+        speed: scalar(record, "speed"),
+        speedEfficiency: scalar(record, "speedEfficiency"),
+        meanDisplacement: scalar(record, "meanDisplacement"),
+        settledCount: scalar(record, "settledCount")
+      });
+    }
+    return {
+      iteration: scalar(header, "iteration"),
+      meanDisplacement: scalar(header, "meanDisplacement"),
+      rmsRadius: scalar(header, "rmsRadius"),
+      layoutRadius: scalar(header, "radius"),
+      centroid: [centroid[0], centroid[1], centroid[2]],
+      repulsionTier: "exact",
+      maxCellOccupancy: null,
+      outsideGrid: null,
+      msPerIteration: null,
+      swing: scalar(header, "swing"),
+      traction: scalar(header, "traction"),
+      speed: scalar(header, "speed"),
+      speedEfficiency: scalar(header, "speedEfficiency"),
+      trace: records
+    };
+  }
+  /**
+   * The resources of the last bind(), or E_NOT_LOADED before it.
+   * @returns the resources
+   */
+  requireResources() {
+    if (this.resources === null) {
+      throw new WebGpuGraphError("E_NOT_LOADED", "the ForceAtlas2 model has not been bound (load() first)", {
+        state: "created"
+      });
+    }
+    return this.resources;
+  }
+  /**
+   * The index of a stage name in FA2_STAGES, or E_INVALID_ARGUMENT.
+   * @param upTo - the stage name
+   * @returns its index
+   */
+  stageIndex(upTo) {
+    for (let i = 0; i < FA2_STAGES.length; i++) {
+      if (FA2_STAGES[i] === upTo) {
+        return i;
+      }
+    }
+    throw invalid("upTo", upTo, FA2_STAGES.join(" | "));
+  }
+  /**
+   * Drops the bind groups of the previous bind() (the buffers changed) so the cached kernels do not accumulate stale
+   * groups across reloads; K3 / K4 live inside RepulsionExact and keep the P1-T6 behaviour. Also forgets the pass
+   * of a batch recorded before the rebind.
+   */
+  dropBound() {
+    this.openPass = null;
+    const { bound } = this;
+    if (bound === null) {
+      return;
+    }
+    for (const kernel of [bound.k1, bound.k2, bound.k5, bound.toScene, bound.fill]) {
+      kernel.invalidate();
+    }
+    this.bound = null;
+  }
+}
+function resolvePatch(patch, current) {
+  return resolveForceAtlas2Options(patch, resolveForceAtlas2Options(current));
+}
+function createForceAtlas2(ctx, options) {
+  ctx.assertReady();
+  const resolved = resolveForceAtlas2Options(options);
+  const tuning = resolveLayoutTuning(options);
+  const model = new ForceAtlas2Model(tuning, resolved);
+  return new ForceSimulation(ctx, model, resolved, tuning, resolvePatch);
+}
+function copyBetweenness(defaults) {
+  const copy = { ...defaults };
+  if (defaults.sources !== void 0) {
+    copy.sources = Object.freeze([...defaults.sources]);
+  }
+  return Object.freeze(copy);
+}
+function copyAlgorithms(algorithms) {
+  const copy = { ...algorithms };
+  if (algorithms.betweenness !== void 0) {
+    copy.betweenness = copyBetweenness(algorithms.betweenness);
+  }
+  return Object.freeze(copy);
+}
+function freezeOptions(options) {
+  if (options === void 0) {
+    return Object.freeze({});
+  }
+  const copy = { ...options };
+  if (options.layout !== void 0) {
+    copy.layout = Object.freeze({ ...options.layout });
+  }
+  if (options.algorithms !== void 0) {
+    copy.algorithms = copyAlgorithms(options.algorithms);
+  }
+  return Object.freeze(copy);
+}
+function createAccelerator(ctx, options) {
+  ctx.assertReady();
+  const frozen = freezeOptions(options);
+  return {
+    kind: "webgpu",
+    ctx,
+    options: frozen,
+    /**
+     * The ForceAtlas2 simulation with this accelerator's layout tuning (spec 3.3; contract 3.14).
+     * @param o - the CPU option type (spec 9.3 ForceAtlas2Options); GPU tuning keys come from `options.layout`
+     * @returns a fresh simulation in state "created"
+     */
+    forceAtlas2(o) {
+      ctx.assertReady();
+      return createForceAtlas2(ctx, { ...o, ...frozen.layout });
+    },
+    /**
+     * Destroys every device buffer recorded for the snapshot (spec 4.5); delegates to ctx.release.
+     * @param s - the snapshot the app is done with
+     */
+    release(s) {
+      ctx.release(s);
+    },
+    /**
+     * Disposes the context (spec 2.8); delegates to ctx.dispose, idempotent.
+     */
+    dispose() {
+      ctx.dispose();
+    }
+  };
+}
+export {
+  A as ARC_WINDOW_ALIGN,
+  E as EXACT_MAX_NODES,
+  FA2_DEFAULTS,
+  G as GpuContext,
+  LAYOUT_TUNING_DEFAULTS,
+  MAX_1D_ITEMS,
+  MAX_WORKGROUPS_PER_DIM,
+  f as PASSTHROUGH_FORMAT_CODES,
+  g as STORAGE_ALIGN,
+  j as WORKGROUP_SIZE,
+  WebGpuGraphError,
+  createAccelerator,
+  createForceAtlas2,
+  degree,
+  hasErrorCode,
+  k as isSoftwareAdapter,
+  isWebGpuGraphError,
+  seedPositions
+};
+//# sourceMappingURL=webgpu-graph-algorithms.js.map