@graphty/webgpu-graph-algorithms 0.6.27 → 0.6.28

package/src/browser/index.ts

@@ -6,7 +6,17 @@
 
 import { GpuContext } from "../context.js";
 import { WebGpuGraphError } from "../errors.js";
+import { manageAccelerator } from "../managed.js";
 import type { GpuContextOptions, ProbeResult } from "../types/context.js";
+import type { AcquireAcceleratorOptions, ManagedAccelerator } from "../types/managed.js";
+
+export type {
+    AcceleratorDeclined,
+    AcceleratorReady,
+    AcquireAcceleratorOptions,
+    AcquireResult,
+    ManagedAccelerator,
+} from "../types/managed.js";
 
 /** Options of the browser helpers (spec 3.4); a type alias, not an empty `extends` interface, which strictTypeChecked's no-empty-object-type (allowInterfaces "never") reports. */
 export type BrowserGpuOptions = Omit<GpuContextOptions, "gpu" | "device" | "runtime">;
@@ -55,3 +65,30 @@ export function requestGpuContext(options?: BrowserGpuOptions): Promise<GpuConte
     }
     return GpuContext.create({ powerPreference: "high-performance", ...options, gpu, runtime: "browser" });
 }
+
+/**
+ * The managed accelerator on navigator.gpu: probe, context, device self-check and accelerator on the first
+ * `current()`, a new device after a loss, disposal by `dispose()`. A software adapter is declined unless
+ * `acceptSoftware` is set. The same function as the `./acquire` subpath resolves to in a browser.
+ * @param options - see AcquireAcceleratorOptions; `adapter` is ignored here
+ * @returns the handle; nothing is probed until `current()` is called
+ */
+export function acquireAccelerator(options?: AcquireAcceleratorOptions): ManagedAccelerator {
+    return manageAccelerator(
+        {
+            probe: (o, rejectSoftware) => probeBrowserWebGpu({ powerPreference: o.powerPreference, rejectSoftware }),
+            open: (o, probe, rejectSoftware) =>
+                requestGpuContext({
+                    adapter: probe.adapter ?? undefined,
+                    powerPreference: o.powerPreference,
+                    rejectSoftware,
+                    warnUnreleasedSnapshots: o.warnUnreleasedSnapshots,
+                }),
+            noWebGpuFix: () =>
+                (globalThis as { isSecureContext?: boolean }).isSecureContext === false
+                    ? "serve the page over https or from localhost: WebGPU needs a secure context"
+                    : null,
+        },
+        options,
+    );
+}

package/src/constants.ts

@@ -43,7 +43,9 @@ export const UNIFORM_SLOT_BYTES = 256;
  * unbiasedness item) the same day by its re-scope to the whole-field ratio, and the far field's accuracy on those
  * fixtures is the follow-up -- because "auto" is the default every consumer sees and the exact tier is the accurate
  * one; the rule's answer on the dev box (1024) is recorded, not shipped, until that work closes and the value is
- * re-fixed. A
+ * re-fixed. Re-measured on 2026-10-02 after the grid tier's hub-cell centroid became a direct dispatch (issue #732):
+ * the rule still answers 1024 (exact 0.26 against grid 0.18 ms per iteration at 4,096 nodes), because the indirect
+ * dispatch's cost was Dawn's validation pass, which the profiler's per-pass times never included. A
  * consumer whose GPU differs (integrated, Apple, T4) passes its own value through
  * createAccelerator(ctx, { layout: { exactMaxNodes } }); calibrateLayout(ctx) measures it.
  */
@@ -261,8 +263,16 @@ export const SSSP_DELTA_FACTOR = 32;
 export const F32_INF_BITS = 0x7f800000;
 /** Design 8.4 "k planned from maxBufferSize and a 25% budget": the share of `maxBufferSize` one betweenness source batch may hold. WebGPU exposes no device memory size, so this is a fraction of the largest buffer, not a memory measurement. */
 export const BC_BATCH_BUDGET_FRACTION = 0.25;
-/** Design 10.1's betweenness column: the most sources one betweenness batch runs together. */
-export const BC_MAX_BATCH = 64;
+/**
+ * The most sources one betweenness batch runs together. 256 rather than design 10.1's 64 (issue #733): a batch's
+ * cost is dominated by its per-level submits and readbacks, not by its width, so a quarter of the batches runs an
+ * exact call on random graphs of 1k / 2k / 4k nodes (4 edges per node, RTX 4070 SUPER) 2.8x / 2.5x / 1.8x faster
+ * with the frontier forward form and 1.9x / 1.6x / 1.5x with the per-batch choice, with bit-identical vertex and
+ * edge scores (the gathers add every source's dependency in source order whatever the batching). The memory budget
+ * still decides k above about 16k nodes at default limits, so large graphs are unchanged. Forward levels per submit
+ * stay at `MAX_LEVELS_PER_SUBMIT`: the parameter ring is sized for it.
+ */
+export const BC_MAX_BATCH = 256;
 /** Design 8.4 (McLaughlin-Bader): a betweenness batch runs the edge-parallel forward pass when the previous batch's level count is below `BC_EDGE_PARALLEL_GAMMA * log2(n)`. The design names the rule and no value; 2 is unmeasured and a benchmark run re-fixes it. */
 export const BC_EDGE_PARALLEL_GAMMA = 2;
 /**

package/src/kernels.ts

@@ -12,7 +12,7 @@
  * dedupe-claim and dedupe-filter; P8-T4 adds frontier-finalize with the FrontierCounters and FrontierParams blocks;
  * P8-T5 adds advance-expand; P8-T6 adds bfs-contract and sssp-pred; P8-T7 adds bfs-fused; P8-T8 adds bfs-bottom-up,
  * bfs-bitset-build and bfs-unvisited-flags; P8-T9 adds sssp-relax; P8-T10 adds bf-relax with the BfParams and BfFlags
- * blocks; P8-T11 adds closeness-sweep and closeness-reduce; P9 (betweenness) adds bc-finalize, bc-forward,
+ * blocks; closeness adds closeness-level and closeness-rowsum with the ClosenessParams block; P9 (betweenness) adds bc-finalize, bc-forward,
  * bc-backward, bc-gather, bc-edge-gather, bc-forward-edge and bc-count (issue #719) with the BcParams block; all-pairs shortest paths
  * (design 8.7) adds apsp-init and apsp-fw with the ApspParams block. P11 (the structure and community phase, plan
  * design/webgpu/plans/2026-09-23-webgpu-p11-structure-and-community.md) adds the graph build on the device (coo-emit,
@@ -45,8 +45,8 @@ import { bfsContractWgsl } from "./wgsl/bfs-contract.wgsl.js";
 import { bfsFusedWgsl } from "./wgsl/bfs-fused.wgsl.js";
 import { bfsNextDegreeWgsl } from "./wgsl/bfs-next-degree.wgsl.js";
 import { bfsUnvisitedFlagsWgsl } from "./wgsl/bfs-unvisited-flags.wgsl.js";
-import { closenessReduceWgsl } from "./wgsl/closeness-reduce.wgsl.js";
-import { closenessSweepWgsl } from "./wgsl/closeness-sweep.wgsl.js";
+import { closenessLevelWgsl } from "./wgsl/closeness-level.wgsl.js";
+import { closenessRowsumWgsl } from "./wgsl/closeness-rowsum.wgsl.js";
 import { compactScatterWgsl } from "./wgsl/compact-scatter.wgsl.js";
 import { cooEmitWgsl } from "./wgsl/coo-emit.wgsl.js";
 import { cooScatterWgsl } from "./wgsl/coo-scatter.wgsl.js";
@@ -139,8 +139,8 @@ export type KernelId =
     | "bfs-next-degree"
     | "sssp-relax"
     | "bf-relax"
-    | "closeness-sweep"
-    | "closeness-reduce"
+    | "closeness-level"
+    | "closeness-rowsum"
     | "bc-finalize"
     | "bc-forward"
     | "bc-backward"
@@ -482,8 +482,7 @@ export const FRONTIER_COUNTERS: UniformBlock = UniformBlock.define(
  * `arcEnd` @44 (the bound arc window), `predKind` @48 (0 arc, 1 node), `bitsBase` @52, `source` @56, `stride` @60
  * (a grid-stride plan's stride), `firstOfSubmit` @64 (the boundary's index inside its submit, clamped to 1: both
  * the unvisited-count and the unvisited-degree-sum subtraction run at >= 1, issue #391), `iteration` @68 (an
- * `sssp-pred` hop pass, P8-T9), `perNode` @72 (`closeness-sweep`: 1 also folds every claim into the per-node
- * distance sums of a sampled run), `pad2` @76. The `slotBase` field that once addressed the selector's indirect slots went with
+ * `sssp-pred` hop pass, P8-T9), `pad3` @72, `pad2` @76. The `slotBase` field that once addressed the selector's indirect slots went with
  * the slots (2026-09-25); `pad2` keeps the block an explicit 80 bytes, the way every block here is padded.
  */
 export const FRONTIER_PARAMS: UniformBlock = UniformBlock.define("FrontierParams", [
@@ -505,7 +504,7 @@ export const FRONTIER_PARAMS: UniformBlock = UniformBlock.define("FrontierParams
     ["stride", "u32"],
     ["firstOfSubmit", "u32"],
     ["iteration", "u32"],
-    ["perNode", "u32"],
+    ["pad3", "u32"],
     ["pad2", "u32"],
 ]);
 
@@ -521,6 +520,35 @@ export const BC_PARAMS: UniformBlock = UniformBlock.define("BcParams", [
     ["pad1", "u32"],
 ]);
 
+/**
+ * `ClosenessParams` (uniform, 64 B): the params of `closeness-level` and `closeness-rowsum` -- `role` @0 (level: 0 a
+ * level, 1 the seed's clear, 2 the seed's sources; rowsum: 0 integer, 1 f32, 2 harmonic), `n` @4, `words` @8 (32-bit
+ * words per node, so `32 x words` sources per batch), `base` @12 (the words of one `bits` region), `total` @16 (the
+ * words the clear zeroes), `level` @20, `row` @24 (the level's row of the submit's count table), `ctrl` @28 (the word
+ * of the control ring in `table`), `count` @32 (the batch's sources), `source` @36 (its first source, or its first
+ * word of the source list), `sourcesAt` @40 (the word of a sampled run's source list in `table`, 0 for the exact
+ * run), `pullAt` @44 (the frontier arcs above which a level pulls), `perNode` @48 (1: a sampled run's per-node
+ * distance sums), `arcCount` @52 (the arcs a push level covers), `pullOk` @56 (1: a level may pull), `pad0` @60.
+ */
+export const CLOSENESS_PARAMS: UniformBlock = UniformBlock.define("ClosenessParams", [
+    ["role", "u32"],
+    ["n", "u32"],
+    ["words", "u32"],
+    ["base", "u32"],
+    ["total", "u32"],
+    ["level", "u32"],
+    ["row", "u32"],
+    ["ctrl", "u32"],
+    ["count", "u32"],
+    ["source", "u32"],
+    ["sourcesAt", "u32"],
+    ["pullAt", "u32"],
+    ["perNode", "u32"],
+    ["arcCount", "u32"],
+    ["pullOk", "u32"],
+    ["pad0", "u32"],
+]);
+
 /** `BfParams` (uniform, 16 B; P8-T10): `edgeCount` @0 (the logical edges of the `edgeList` view), `stride` @4 (the grid-stride plan's stride), `maxRetries` @8 (PD-12's compare-exchange bound), `cutoffBits` @12 (the f32 bit pattern of the CPU port's `cutoff`, `+Inf` when absent). */
 export const BF_PARAMS: UniformBlock = UniformBlock.define("BfParams", [
     ["edgeCount", "u32"],
@@ -1085,7 +1113,7 @@ const GRID_CENTROID: KernelEntry = {
     phase: "P4",
 };
 
-/** `grid-centroid-hub` (G4b, spec 7.7; P4-T9, PD-13, DEP-P4-L): one workgroup per hub cell, dispatched indirectly, a WG-strided sum through `wg_reduce_vec4` guarded by `h < hubCount[0]`; 6 storage bindings (`hubCount` is a read-only view of `hubCounters`). */
+/** `grid-centroid-hub` (G4b, spec 7.7; P4-T9, PD-13, DEP-P4-L): one workgroup per word of `hubList`, dispatched directly, a WG-strided sum through `wg_reduce_vec4` guarded by `h < hubCount[0]`; 6 storage bindings (`hubCount` is a read-only view of `hubCounters`). */
 const GRID_CENTROID_HUB: KernelEntry = {
     id: "grid-centroid-hub",
     body: gridCentroidHubWgsl,
@@ -1425,41 +1453,42 @@ const BF_RELAX: KernelEntry = {
     phase: "P8",
 };
 
-/** `closeness-sweep` (design 8.4 "32 sources per u32 word"; P8-T11, PD-13 / DEP-P8-E): one level of the bit-parallel multi-source BFS -- `advance-expand`'s block-mapped strip over the compacted frontier list with the claim inline (`atomicOr` on the visited word of the four-region `bits` buffer, the won bits into the level's next region and the flags region, one workgroup-memory tally per source flushed by one `atomicAdd` per source per workgroup into `perSource`); 8 storage bindings (the four graph slots, `frontierList` read-only, `counters`, `bits` and `perSource` as `array<atomic<u32>>`) -- exactly at the budget; the inlined Hillis-Steele scan, so `needs: []`. */
-const CLOSENESS_SWEEP: KernelEntry = {
-    id: "closeness-sweep",
-    body: closenessSweepWgsl,
-    entryPoint: "closeness_sweep",
-    bindings: GRAPH_SLOTS.concat(
-        decl(1, 0, "frontierList", "storage-ro", "array<u32>"),
-        decl(1, 1, "counters", "storage", "array<atomic<u32>>"),
-        decl(1, 2, "bits", "storage", "array<atomic<u32>>"),
-        decl(1, 3, "perSource", "storage", "array<atomic<u32>>"),
-        decl(2, 0, "P", "uniform", "FrontierParams"),
-    ),
+/** `closeness-level` (design 8.4 "32 sources per u32 word"): one level of closeness's bit-parallel multi-source BFS in one dispatch, `32 x P.words` sources per batch -- role 0 the level (push over the out-arcs or pull over the in-arcs, push one invocation per arc, pull one per node, chosen per level on the device from the frontier's arcs against `P.pullAt`, the pull with an early exit once every source has reached the node), role 1 and role 2 the batch's seed; 6 storage bindings (the forward and the reverse CSR as group-1 state, `bits` and `table` as `array<atomic<u32>>`). */
+const CLOSENESS_LEVEL: KernelEntry = {
+    id: "closeness-level",
+    body: closenessLevelWgsl,
+    entryPoint: "closeness_level",
+    bindings: [
+        decl(1, 0, "rowPtr", "storage-ro", "array<u32>"),
+        decl(1, 1, "colIdx", "storage-ro", "array<u32>"),
+        decl(1, 2, "inRowPtr", "storage-ro", "array<u32>"),
+        decl(1, 3, "inColIdx", "storage-ro", "array<u32>"),
+        decl(1, 4, "bits", "storage", "array<atomic<u32>>"),
+        decl(1, 5, "table", "storage", "array<atomic<u32>>"),
+        decl(2, 0, "P", "uniform", "ClosenessParams"),
+    ],
     overrideDecls: [],
-    uniforms: [FRONTIER_PARAMS],
+    uniforms: [CLOSENESS_PARAMS],
     needs: [],
     snippetSlots: [],
     phase: "P8",
 };
 
-/** `closeness-reduce` (design 8.4, 9.7; P8-T11, PD-13): the one-lane bookkeeping of the sweep -- role 0 the level boundary (`done` from the previous level's compacted count, `newCount` folded into `reached` and the 64-bit `sum` at `level + 1` with the 16-bit split product and the carry, `level` advanced), role 1 the seed of a batch (the sources' bits into `visited` and the level-0 frontier region, their flags, `counters[0] = k`, `level = U32_MAX`), role 2 the same seed from a sampled run's source list; 3 storage bindings (`counters` and `perSource` as `array<atomic<u32>>`, `bits` plain: one lane writes the seed). */
-const CLOSENESS_REDUCE: KernelEntry = {
-    id: "closeness-reduce",
-    body: closenessReduceWgsl,
-    entryPoint: "closeness_reduce",
+/** `closeness-rowsum` (design 8.7): closeness from a finished all-pairs matrix, one workgroup per row -- the off-diagonal finite entries summed as integers (`P.role` 0), as f32 (1) or as reciprocals (2, harmonic), by a tree reduction; 2 storage bindings (`dist` read-only, `out`). */
+const CLOSENESS_ROWSUM: KernelEntry = {
+    id: "closeness-rowsum",
+    body: closenessRowsumWgsl,
+    entryPoint: "closeness_rowsum",
     bindings: [
-        decl(1, 0, "counters", "storage", "array<atomic<u32>>"),
-        decl(1, 1, "perSource", "storage", "array<atomic<u32>>"),
-        decl(1, 2, "bits", "storage", "array<u32>"),
-        decl(2, 0, "P", "uniform", "FrontierParams"),
+        decl(1, 0, "dist", "storage-ro", "array<f32>"),
+        decl(1, 1, "out", "storage", "array<u32>"),
+        decl(2, 0, "P", "uniform", "ClosenessParams"),
     ],
     overrideDecls: [],
-    uniforms: [FRONTIER_PARAMS],
+    uniforms: [CLOSENESS_PARAMS],
     needs: [],
     snippetSlots: [],
-    phase: "P8",
+    phase: "P9",
 };
 
 /** `bc-finalize` (design 8.4, 5.4): the one-lane bookkeeping of a betweenness batch -- role 1 seeds it (depth 0 and one path for the k seed entries of the claim log, `stackTop = k`, `level = U32_MAX`), role 0 is the level boundary (`ends[level + 1] = stackTop`, `frontierCount`, `done` on an empty level); 6 storage bindings (the counters block as `array<atomic<u32>>`, `ends`, `S` read-only, `depthK`, `sigmaK` and `levelMax` plain: one lane writes the seed; `SCALED` seeds f32 bits). The design's finalize row has 2; `ends` is the third (the level boundary), and the seed's `S`, `depthK`, `sigmaK` and `levelMax` make it six. */
@@ -1845,7 +1874,7 @@ const MST_LINK: KernelEntry = {
  * and `"fa2-to-scene"`; M8b-T3 landed the seven P7 entries and P4 its thirteen; P8-T3 landed the three compact /
  * dedupe entries, P8-T4 `"frontier-finalize"`, P8-T5 `"advance-expand"`, P8-T6 `"bfs-contract"` and `"sssp-pred"` and
  * P8-T7 `"bfs-fused"`, P8-T8 `"bfs-bottom-up"`, `"bfs-bitset-build"` and `"bfs-unvisited-flags"`, P8-T9
- * `"sssp-relax"`, P8-T10 `"bf-relax"` and P8-T11 `"closeness-sweep"` and `"closeness-reduce"`, betweenness the
+ * `"sssp-relax"`, P8-T10 `"bf-relax"`, closeness `"closeness-level"` and `"closeness-rowsum"`, betweenness the
  * six `"bc-*"` entries, all-pairs shortest paths `"apsp-init"` and `"apsp-fw"`, and P11 its seven (the graph
  * build, the group-by-key, label propagation's step and triangle counting) plus Boruvka's `"mst-best"` and
  * `"mst-link"`, so every member of `KernelId`
@@ -1896,8 +1925,8 @@ const REGISTRY: Readonly<Partial<Record<KernelId, KernelEntry>>> = Object.freeze
     "bfs-next-degree": BFS_NEXT_DEGREE,
     "sssp-relax": SSSP_RELAX,
     "bf-relax": BF_RELAX,
-    "closeness-sweep": CLOSENESS_SWEEP,
-    "closeness-reduce": CLOSENESS_REDUCE,
+    "closeness-level": CLOSENESS_LEVEL,
+    "closeness-rowsum": CLOSENESS_ROWSUM,
     "bc-finalize": BC_FINALIZE,
     "bc-forward": BC_FORWARD,
     "bc-backward": BC_BACKWARD,

package/src/layouts/force-simulation.ts

@@ -183,7 +183,6 @@ const U32_BUFFER_NAMES: ReadonlySet<string> = new Set([
     "cellStart",
     "hubList",
     "hubCounters",
-    "hubArgs",
 ]);
 
 /** The per-batch epilogue stage: iterations 0..k-2 stop after the stage that precedes it (PLAN DECISION 2). */

package/src/layouts/forceatlas2.ts

@@ -520,7 +520,6 @@ export class ForceAtlas2Model implements ForceModel<ForceAtlas2Options, ForceAtl
             cellStart: resources.buffer("cellStart"),
             hubList: resources.buffer("hubList"),
             hubCounters,
-            hubArgs: resources.buffer("hubArgs"),
             pyramid: resources.buffer("pyramid"),
         });
         const wg = k1.workgroupSize;

package/src/layouts/fruchterman-reingold.ts

@@ -513,7 +513,6 @@ export class FruchtermanReingoldModel implements ForceModel<FruchtermanReingoldO
             cellStart: resources.buffer("cellStart"),
             hubList: resources.buffer("hubList"),
             hubCounters,
-            hubArgs: resources.buffer("hubArgs"),
             pyramid: resources.buffer("pyramid"),
         });
         const wg = k1.workgroupSize;

package/src/layouts/repulsion-grid.ts

@@ -15,7 +15,7 @@ import { GRID_HUB_CELL } from "../constants.js";
 import { BufferUsage } from "../device/webgpu-constants.js";
 import { WebGpuGraphError } from "../errors.js";
 import { plan1d } from "../kernel/dispatch.js";
-import { type BoundKernel, INDIRECT_ARGS_STRIDE, type Kernel } from "../kernel/kernel.js";
+import { type BoundKernel, type Kernel } from "../kernel/kernel.js";
 import { type PipelineCache } from "../kernel/pipeline-cache.js";
 import { type UniformBlock, type UniformValues } from "../kernel/struct-block.js";
 import { type WgslModuleSpec } from "../kernel/wgsl.js";
@@ -56,7 +56,6 @@ export interface RepulsionGridResources extends RepulsionExactResources {
     readonly cellStart: Binding;
     readonly hubList: Binding;
     readonly hubCounters: Binding;
-    readonly hubArgs: Binding;
     readonly pyramid: Binding;
 }
 
@@ -216,8 +215,7 @@ export class RepulsionGrid {
 
     /**
      * The model-owned buffers of the grid tier (spec 7.3; PD-11): `cellKey` / `cellVal` / `sortedKey` / `sortedIdx`
-     * 4n, `cellHist` / `cellStart` 4 histWords (cells + 2^dim + 1) zeroed, `hubList` one word per possible hub cell, `hubArgs` one
-     * indirect slot, `pyramid` 16 B per pyramid cell zeroed. `hubCounters` (16 B, zeroed) is the MODEL's on every
+     * 4n, `cellHist` / `cellStart` 4 histWords (cells + 2^dim + 1) zeroed, `hubList` one word per possible hub cell, `pyramid` 16 B per pyramid cell zeroed. `hubCounters` (16 B, zeroed) is the MODEL's on every
      * tier (PD-14: K1 binds it on the exact tier too). n = 0 reports one node's worth of bytes (spec 3.6).
      * @param n - the node count
      * @param spec - the grid
@@ -238,7 +236,6 @@ export class RepulsionGrid {
                 usage: STORAGE_RW,
                 zero: false,
             },
-            { name: "hubArgs", byteLength: INDIRECT_ARGS_STRIDE, usage: STORAGE_RW | BufferUsage.INDIRECT, zero: true },
             { name: "pyramid", byteLength: gridPyramidBytes(spec), usage: STORAGE_RW, zero: true },
         ];
     }
@@ -261,7 +258,6 @@ export class RepulsionGrid {
             kernelSpec("histogram"),
             kernelSpec("fill"),
             kernelSpec("grid-centroid"),
-            kernelSpec("indirect-finalize"),
             kernelSpec("grid-centroid-hub"),
             kernelSpec("grid-downsample"),
             farFieldSpec(overrides),
@@ -348,7 +344,6 @@ export class RepulsionGrid {
             pyramid: r.pyramid,
             hubList: r.hubList,
             hubCounters: r.hubCounters,
-            hubArgs: r.hubArgs,
         });
         this.bound = {
             far: this.far.bind({

package/src/layouts/spring-electrical.ts

@@ -483,7 +483,6 @@ export class SpringElectricalModel implements ForceModel<SpringElectricalOptions
             cellStart: resources.buffer("cellStart"),
             hubList: resources.buffer("hubList"),
             hubCounters,
-            hubArgs: resources.buffer("hubArgs"),
             pyramid: resources.buffer("pyramid"),
         });
         const wg = k1.workgroupSize;

package/src/managed.ts

@@ -0,0 +1,172 @@
+/**
+ * The managed accelerator behind `acquireAccelerator` (the `./acquire` subpath, and the same function on `./browser`
+ * and `./node`): probe, context, device self-check, accelerator, re-acquisition after device loss, disposal. The
+ * runtime-specific half (how to probe and how to open a context) comes from the entry that calls `manageAccelerator`;
+ * everything else is here once, so no consumer writes it.
+ *
+ * Every decline is decided before any work runs: a caller with a CPU implementation runs it and reports the reason.
+ * A failure of work that already started on the device is never caught here; it reaches the caller of that work.
+ */
+
+import { createAccelerator } from "./accelerator.js";
+import type { GpuContext } from "./context.js";
+import { isWebGpuGraphError, WebGpuGraphError } from "./errors.js";
+import { verifyDevice } from "./primitives/verify.js";
+import type { GpuAccelerator } from "./types/accelerator.js";
+import type { DeviceCheck, ProbeResult } from "./types/context.js";
+import type {
+    AcceleratorDeclined,
+    AcquireAcceleratorOptions,
+    AcquireResult,
+    ManagedAccelerator,
+} from "./types/managed.js";
+
+/**
+ * How one runtime finds a device; supplied by the browser and Node entries.
+ * @internal
+ */
+export interface AcceleratorPlatform {
+    /** Probes without creating a device; never throws. */
+    probe(options: AcquireAcceleratorOptions, rejectSoftware: boolean): Promise<ProbeResult>;
+    /** Opens a context on the probed adapter. */
+    open(options: AcquireAcceleratorOptions, probe: ProbeResult, rejectSoftware: boolean): Promise<GpuContext>;
+    /** What the user can do about E_NO_WEBGPU on this runtime, or null. */
+    noWebGpuFix(): string | null;
+    /** Test seam: replaces `verifyDevice`. */
+    readonly verify?: ((ctx: GpuContext) => Promise<DeviceCheck>) | undefined;
+}
+
+/** The fix of a declined software adapter, on every runtime. */
+const SOFTWARE_FIX = "pass acceptSoftware: true to use the software adapter (usually slower than the CPU)";
+
+const DECLINE_CODES: ReadonlySet<string> = new Set(["E_NO_WEBGPU", "E_NO_ADAPTER", "E_SOFTWARE_ONLY"]);
+
+/**
+ * A decline record.
+ * @param platform - the runtime, for the E_NO_WEBGPU fix
+ * @param code - the decline code
+ * @param reason - the reason in words
+ * @param rest - the adapter and the check, when known
+ * @returns the record
+ */
+function declined(
+    platform: AcceleratorPlatform,
+    code: AcceleratorDeclined["code"],
+    reason: string,
+    rest: Partial<Pick<AcceleratorDeclined, "adapter" | "check">> = {},
+): AcceleratorDeclined {
+    let fix: string | null = null;
+    if (code === "E_SOFTWARE_ONLY") {
+        fix = SOFTWARE_FIX;
+    } else if (code === "E_NO_WEBGPU") {
+        fix = platform.noWebGpuFix();
+    }
+    return { ok: false, code, reason, fix, adapter: rest.adapter ?? null, check: rest.check ?? null };
+}
+
+/**
+ * One acquisition: probe, open, self-check, accelerator. The context is disposed on every path that does not hand
+ * it over.
+ * @param platform - the runtime
+ * @param options - the caller's options
+ * @returns the accelerator, or why there is none
+ */
+async function acquireOnce(platform: AcceleratorPlatform, options: AcquireAcceleratorOptions): Promise<AcquireResult> {
+    const rejectSoftware = options.acceptSoftware !== true;
+    const probe = await platform.probe(options, rejectSoftware);
+    if (!probe.ok || probe.code !== "OK") {
+        const code = probe.code === "OK" ? "E_NO_ADAPTER" : probe.code;
+        return declined(platform, code, probe.reason ?? code, { adapter: probe.summary });
+    }
+    let ctx: GpuContext;
+    try {
+        ctx = await platform.open(options, probe, rejectSoftware);
+    } catch (err) {
+        // the adapter can change between the probe and the device request (a GPU process restart)
+        if (isWebGpuGraphError(err) && DECLINE_CODES.has(err.code)) {
+            return declined(platform, err.code as AcceleratorDeclined["code"], err.message, { adapter: probe.summary });
+        }
+        throw err;
+    }
+    let accelerator: GpuAccelerator;
+    try {
+        const check = await (platform.verify ?? verifyDevice)(ctx);
+        if (check.mismatch !== null) {
+            ctx.dispose();
+            const where = check.mismatch.poison
+                ? `${check.mismatch.where} was never written`
+                : `${check.mismatch.where} came back as ${String(check.mismatch.actual)} where ${String(check.mismatch.expected)} was required`;
+            return declined(
+                platform,
+                "E_DEVICE_INCORRECT",
+                `the ${check.vendor} device computed a known prefix sum incorrectly: ${where}`,
+                { adapter: probe.summary, check },
+            );
+        }
+        accelerator = createAccelerator(ctx, options.accelerator);
+    } catch (err) {
+        ctx.dispose();
+        throw err;
+    }
+    return { ok: true, code: "OK", accelerator };
+}
+
+/**
+ * The managed accelerator over one runtime.
+ * @param platform - how this runtime probes and opens a context
+ * @param options - the caller's options
+ * @returns the handle
+ * @internal
+ */
+export function manageAccelerator(
+    platform: AcceleratorPlatform,
+    options: AcquireAcceleratorOptions = {},
+): ManagedAccelerator {
+    let pending: Promise<AcquireResult> | null = null;
+    let ready: GpuAccelerator | null = null;
+    let disposed = false;
+    const disposedError = (): WebGpuGraphError =>
+        new WebGpuGraphError("E_DISPOSED", "the managed accelerator was disposed", { label: "acquireAccelerator" });
+    return {
+        current(): Promise<AcquireResult> {
+            if (disposed) {
+                return Promise.reject(disposedError());
+            }
+            if (ready !== null && ready.ctx.state !== "ready") {
+                // lost, or disposed by its holder: the next answer is a new device
+                ready = null;
+                pending = null;
+            }
+            if (pending === null) {
+                const attempt = acquireOnce(platform, options).then(
+                    (result) => {
+                        if (!result.ok) {
+                            return result;
+                        }
+                        if (disposed) {
+                            result.accelerator.dispose();
+                            throw disposedError();
+                        }
+                        ready = result.accelerator;
+                        return result;
+                    },
+                    (err: unknown) => {
+                        // not a decline: the next call tries again rather than remembering a transient failure
+                        if (pending === attempt) {
+                            pending = null;
+                        }
+                        throw err;
+                    },
+                );
+                pending = attempt;
+            }
+            return pending;
+        },
+        dispose(): void {
+            disposed = true;
+            ready?.dispose();
+            ready = null;
+            pending = null;
+        },
+    };
+}

package/src/node/index.ts

@@ -11,7 +11,17 @@
 
 import { GpuContext } from "../context.js";
 import { WebGpuGraphError } from "../errors.js";
+import { manageAccelerator } from "../managed.js";
 import type { GpuContextOptions, ProbeResult } from "../types/context.js";
+import type { AcquireAcceleratorOptions, ManagedAccelerator } from "../types/managed.js";
+
+export type {
+    AcceleratorDeclined,
+    AcceleratorReady,
+    AcquireAcceleratorOptions,
+    AcquireResult,
+    ManagedAccelerator,
+} from "../types/managed.js";
 
 /** Options of the Node helpers (spec 3.4). */
 export interface NodeGpuOptions extends Omit<GpuContextOptions, "gpu" | "adapter" | "device" | "runtime"> {
@@ -252,3 +262,29 @@ export async function probeNodeWebGpu(options?: NodeGpuOptions): Promise<ProbeRe
         handle.dispose();
     }
 }
+
+/**
+ * The managed accelerator on Dawn: probe, context, device self-check and accelerator on the first `current()`, a
+ * new device after a loss, disposal by `dispose()`. Without the optional `webgpu` package `current()` declines with
+ * E_NO_WEBGPU and the install command as its fix; a software adapter is declined unless `acceptSoftware` is set.
+ * The same function as the `./acquire` subpath resolves to under Node.
+ * @param options - see AcquireAcceleratorOptions; `adapter` picks the Dawn adapter by name
+ * @returns the handle; nothing is loaded or probed until `current()` is called
+ */
+export function acquireAccelerator(options?: AcquireAcceleratorOptions): ManagedAccelerator {
+    return manageAccelerator(
+        {
+            probe: (o, rejectSoftware) =>
+                probeNodeWebGpu({ adapter: o.adapter, powerPreference: o.powerPreference, rejectSoftware }),
+            open: (o, _probe, rejectSoftware) =>
+                createNodeGpuContext({
+                    adapter: o.adapter,
+                    powerPreference: o.powerPreference,
+                    rejectSoftware,
+                    warnUnreleasedSnapshots: o.warnUnreleasedSnapshots,
+                }),
+            noWebGpuFix: () => INSTALL_HINT,
+        },
+        options,
+    );
+}