@graphty/webgpu-graph-algorithms 0.2.1 → 0.3.0

package/README.md

@@ -287,32 +287,39 @@ are the T-table of plan section 10.4. A missed target is re-fixed by a recorded
 
 ### The dev box (nvidia-lovelace-driver580)
 
-Measured on nvidia-lovelace-driver580 (NVIDIA: 580.173.02 580.173.2.0), session 2026-09-16T02:07:45.933Z, medians of 5 runs; Chromium: nvidia / lovelace (nvidia-lovelace-driver0, the description is redacted by Chromium), session 2026-09-16T02:18:11.896Z.
-
-| Id  | What                                                                                         | Target              | Measured             |
-| --- | -------------------------------------------------------------------------------------------- | ------------------- | -------------------- |
-| T-1 | Upload of the 100k / 1M weighted hot prefix (16.4 MB); 1M / 10M (164 MB)                     | <= 10 ms; <= 100 ms | 6.032 ms; 127.531 ms |
-| T-2 | `degree` + 400 KB readback at 100k (core resident), Node                                     | <= 2 ms             | 0.878 ms             |
-| T-3 | Empty submit + 4-byte `readU32` round trip, Dawn                                             | <= 0.1 ms           | 0.170 ms             |
-| T-4 | ForceAtlas2 exact tier, GPU time per iteration (profiler) at 10k; at 16k                     | <= 1 ms; <= 2 ms    | 0.586 ms; 1.052 ms   |
-| T-5 | ForceAtlas2 per-frame cost, `step(1)` + the 12n readback at 10k, Chromium (Node in brackets) | <= 6 ms             | 2.400 ms (0.738 ms)  |
-
-Two rows miss their target in this session: the 1M / 10M upload (127.5 ms against 100 ms, the open owner decision of
-`docs/decisions/G1.md` section 7) and the empty-submit round trip (0.170 ms against 0.1 ms: the row is measured after the
-`upload` group, whose CPU-heavy setup lets the SM clock fall to its idle state; the same row measures 0.041-0.074 ms at
-the working clock -- finding G3-F2 of `docs/decisions/G3.md` section 10).
+Measured on nvidia-lovelace-driver580 (NVIDIA: 580.173.02 580.173.2.0), session 2026-09-20T01:06:48.656Z, medians of 5 runs; Chromium: nvidia / lovelace (nvidia-lovelace-driver0, the description is redacted by Chromium), session 2026-09-16T02:18:11.896Z.
+
+| Id  | What                                                                                                                                     | Target              | Measured               |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | ---------------------- |
+| T-1 | Upload of the 100k / 1M weighted hot prefix (16.4 MB); 1M / 10M (164 MB)                                                                 | <= 10 ms; <= 100 ms | 5.980 ms; 125.738 ms   |
+| T-2 | `degree` + 400 KB readback at 100k (core resident), Node                                                                                 | <= 2 ms             | 0.870 ms               |
+| T-3 | Empty submit + 4-byte `readU32` round trip, Dawn                                                                                         | <= 0.1 ms           | 0.181 ms               |
+| T-4 | ForceAtlas2 exact tier, GPU time per iteration (profiler) at 10k; at 16k                                                                 | <= 1 ms; <= 2 ms    | 0.586 ms; 1.053 ms     |
+| T-5 | ForceAtlas2 per-frame cost, `step(1)` + the 12n readback at 10k, Chromium (Node in brackets)                                             | <= 6 ms             | 2.400 ms (0.726 ms)    |
+| T-8 | PageRank, 100 iterations, wall end to end including the upload, at 100k / 1M; at 1M / 10M                                                | <= 150 ms; <= 1.5 s | 17.204 ms; 198.645 ms  |
+| T-9 | Weakly connected components (Afforest), wall end to end including the upload and the label readback, at 1M / 10M (100k / 1M in brackets) | <= 100 ms           | 145.970 ms (12.613 ms) |
+
+Three rows miss their target in this session: the 1M / 10M upload (125.7 ms against 100 ms, the open owner decision of
+`docs/decisions/G1.md` section 7), the empty-submit round trip (0.181 ms against 0.1 ms: the row is measured after the
+`upload` group, whose CPU-heavy setup lets the SM clock fall to its idle state; the same row measures 0.041-0.075 ms at
+the working clock -- finding G3-F2 of `docs/decisions/G3.md` section 10), and WCC at 1M / 10M (146.0 ms against
+100 ms: the row is wall end to end from a released core, so it carries the same 164 MB upload T-1 times at 125.7 ms;
+with the core resident the same call takes 11-16 ms). The T-9 target is therefore below
+the T-1 upload it includes, an owner decision for `docs/decisions/G7.md`. The `pagerank` rows run all 100 iterations
+(`tolerance: 0`): at the NetworkX tolerance of 1e-6 the seeded G(n, m) input converges from the uniform start in one to
+four iterations, which would time one pull and call it a hundred.
 
 The exact curve (the `layout-exact` group: 2D, E = 10n, seeded G(n, m), one simulation per rung; ms / iteration from the profiler):
 
 | n     | ms / iteration | step(1) wall (ms) | pairs / s |
 | ----- | -------------- | ----------------- | --------- |
-| 1024  | 0.096          | 0.228             | 1.09e+10  |
-| 4096  | 0.255          | 0.415             | 6.58e+10  |
-| 8192  | 0.478          | 0.630             | 1.40e+11  |
-| 10000 | 0.586          | 0.738             | 1.71e+11  |
-| 16384 | 1.052          | 1.226             | 2.55e+11  |
-| 32768 | 2.560          | 2.787             | 4.19e+11  |
-| 65536 | 8.405          | 8.862             | 5.11e+11  |
+| 1024  | 0.087          | 0.224             | 1.20e+10  |
+| 4096  | 0.255          | 0.381             | 6.58e+10  |
+| 8192  | 0.478          | 0.612             | 1.40e+11  |
+| 10000 | 0.586          | 0.726             | 1.71e+11  |
+| 16384 | 1.053          | 1.207             | 2.55e+11  |
+| 32768 | 2.561          | 2.757             | 4.19e+11  |
+| 65536 | 8.402          | 8.705             | 5.11e+11  |
 
 The end-to-end run of `benchmarks/layout-run.ts --nodes 100000 --edges 1000000` (the exact tier at 100k, 100
 iterations, batches of 8) takes 18.971 ms per iteration on the same card, uploads and readbacks included (16.975 ms of
@@ -327,27 +334,29 @@ T-4 and T-5 and misses T-1 (both uploads), T-2 and T-3, which is the class diffe
 cloud vCPU (host-side copies and submit latency), not a regression: the exact tier's `ms / iteration` is 1.7x the
 RTX 4070 SUPER's at 10k and 3.0x at 65k.
 
-Measured on gpu-linux-t4 (NVIDIA: 580.126.20 580.126.20.0), session 2026-09-18T07:03:17.146Z, medians of 5 runs; Chromium: nvidia / turing (nvidia-turing-driver0, the description is redacted by Chromium), session 2026-09-18T07:02:07.834Z.
+Measured on gpu-linux-t4 (NVIDIA: 580.126.20 580.126.20.0), session 2026-09-20T02:29:33.210Z (run 35483512705), medians of 5 runs; Chromium: nvidia / turing (nvidia-turing-driver0, the description is redacted by Chromium), session 2026-09-20T02:28:10.676Z.
 
-| Id  | What                                                                                         | Target              | Measured              |
-| --- | -------------------------------------------------------------------------------------------- | ------------------- | --------------------- |
-| T-1 | Upload of the 100k / 1M weighted hot prefix (16.4 MB); 1M / 10M (164 MB)                     | <= 10 ms; <= 100 ms | 14.458 ms; 257.954 ms |
-| T-2 | `degree` + 400 KB readback at 100k (core resident), Node                                     | <= 2 ms             | 2.298 ms              |
-| T-3 | Empty submit + 4-byte `readU32` round trip, Dawn                                             | <= 0.1 ms           | 0.171 ms              |
-| T-4 | ForceAtlas2 exact tier, GPU time per iteration (profiler) at 10k; at 16k                     | <= 1 ms; <= 2 ms    | 0.977 ms; 1.879 ms    |
-| T-5 | ForceAtlas2 per-frame cost, `step(1)` + the 12n readback at 10k, Chromium (Node in brackets) | <= 6 ms             | 2.600 ms (1.357 ms)   |
+| Id  | What                                                                                                                                     | Target              | Measured               |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | ---------------------- |
+| T-1 | Upload of the 100k / 1M weighted hot prefix (16.4 MB); 1M / 10M (164 MB)                                                                 | <= 10 ms; <= 100 ms | 14.338 ms; 256.418 ms  |
+| T-2 | `degree` + 400 KB readback at 100k (core resident), Node                                                                                 | <= 2 ms             | 2.957 ms               |
+| T-3 | Empty submit + 4-byte `readU32` round trip, Dawn                                                                                         | <= 0.1 ms           | 1.296 ms               |
+| T-4 | ForceAtlas2 exact tier, GPU time per iteration (profiler) at 10k; at 16k                                                                 | <= 1 ms; <= 2 ms    | 0.972 ms; 1.953 ms     |
+| T-5 | ForceAtlas2 per-frame cost, `step(1)` + the 12n readback at 10k, Chromium (Node in brackets)                                             | <= 6 ms             | 2.600 ms (1.359 ms)    |
+| T-8 | PageRank, 100 iterations, wall end to end including the upload, at 100k / 1M; at 1M / 10M                                                | <= 150 ms; <= 1.5 s | 45.461 ms; 1092.799 ms |
+| T-9 | Weakly connected components (Afforest), wall end to end including the upload and the label readback, at 1M / 10M (100k / 1M in brackets) | <= 100 ms           | 293.079 ms (28.544 ms) |
 
 The exact curve (the `layout-exact` group: 2D, E = 10n, seeded G(n, m), one simulation per rung; ms / iteration from the profiler):
 
 | n     | ms / iteration | step(1) wall (ms) | pairs / s |
 | ----- | -------------- | ----------------- | --------- |
-| 1024  | 0.334          | 0.977             | 3.13e+9   |
-| 4096  | 0.426          | 0.881             | 3.93e+10  |
-| 8192  | 0.801          | 1.184             | 8.38e+10  |
-| 10000 | 0.977          | 1.357             | 1.02e+11  |
-| 16384 | 1.879          | 2.317             | 1.43e+11  |
-| 32768 | 6.534          | 7.241             | 1.64e+11  |
-| 65536 | 24.883         | 25.955            | 1.73e+11  |
+| 1024  | 0.340          | 0.711             | 3.08e+9   |
+| 4096  | 0.431          | 0.814             | 3.90e+10  |
+| 8192  | 0.797          | 1.172             | 8.42e+10  |
+| 10000 | 0.972          | 1.359             | 1.03e+11  |
+| 16384 | 1.953          | 2.383             | 1.37e+11  |
+| 32768 | 6.861          | 7.394             | 1.57e+11  |
+| 65536 | 25.236         | 26.366            | 1.70e+11  |
 
 ## Development
 

package/dist/browser.js

@@ -1,4 +1,4 @@
-import { G as GpuContext, W as WebGpuGraphError } from "./chunks/context-E6iKaeuJ.js";
+import { G as GpuContext, W as WebGpuGraphError } from "./chunks/context-CRbw2Wyo.js";
 function navigatorGpu() {
   if (typeof navigator === "undefined") {
     return void 0;

package/dist/chunks/{context-E6iKaeuJ.js → context-CRbw2Wyo.js}

@@ -2457,22 +2457,38 @@ class GraphResidency {
     });
   }
   /**
-   * Uploads (or finds) a view; P1-P3 support outDegree / inDegree / degreeOrder / reverseDegreeOrder; the others
-   * -> E_UNSUPPORTED until P7. packViews is accepted and ignored until P7 (a `true` request is E_UNSUPPORTED
-   * { option: "packViews" }, PLAN DECISION 9).
+   * Uploads (or finds) a view: outDegree / inDegree / degreeOrder / reverseDegreeOrder upload one array each;
+   * reverse and edgeList (P7) upload their arrays perArray, never into the arena, and are memoised per record so
+   * a second call uploads nothing (spec 4.3). coo and mate -> E_UNSUPPORTED until P11. packViews concatenates a
+   * reverse or edgeList view into ONE buffer at STORAGE_ALIGN offsets; on any other view `true` is E_UNSUPPORTED
+   * { option: "packViews" }.
    * @param s - the snapshot
    * @param name - the view
    * @param options - view options
-   * @param options.packViews - P7's packed reverse upload; `true` is E_UNSUPPORTED until then
+   * @param options.packViews - pack the reverse / edgeList arrays into one buffer (a no-op on an undirected reverse)
    * @returns the view binding
    */
   view(s, name, options) {
     this.assertLive();
     assertAttached(s);
-    if (options?.packViews === true) {
-      throw new WebGpuGraphError("E_UNSUPPORTED", "packViews is not supported before the P7 view uploads", {
+    const packed = options?.packViews === true;
+    if (name === "reverse" || name === "edgeList") {
+      this.assertNotReleased(s);
+      this.assertNonEmpty(s);
+      const memoKey = packed ? `${name}:packed` : name;
+      const record2 = this.ensureRecord(s);
+      const memo = record2.views.get(memoKey);
+      if (memo !== void 0) {
+        return memo;
+      }
+      const built = name === "reverse" ? this.buildReverse(s, record2, packed) : this.buildEdgeList(s, record2, packed);
+      record2.views.set(memoKey, built);
+      return built;
+    }
+    if (packed) {
+      throw new WebGpuGraphError("E_UNSUPPORTED", "packViews applies to the reverse and edgeList views only", {
         option: "packViews",
-        hint: "omit packViews; the four reverse arrays are uploaded separately"
+        hint: `the ${name} view uploads one array`
       });
     }
     let array;
@@ -2509,13 +2525,11 @@ class GraphResidency {
         scalars = { segmentOffsets: Array.from(order.segmentOffsets) };
         break;
       }
-      case "reverse":
       case "coo":
-      case "edgeList":
       case "mate":
-        throw new WebGpuGraphError("E_UNSUPPORTED", `the ${name} view is not uploaded before P7`, {
+        throw new WebGpuGraphError("E_UNSUPPORTED", `the ${name} view is not uploaded before P11`, {
           feature: `view:${name}`,
-          hint: "P1-P3 upload outDegree, inDegree, degreeOrder and reverseDegreeOrder"
+          hint: "outDegree, inDegree, degreeOrder, reverseDegreeOrder, reverse and edgeList are uploaded"
         });
       default:
         throw invalid("name", name, "a view name");
@@ -2529,6 +2543,146 @@ class GraphResidency {
       scalars: Object.freeze(scalars)
     });
   }
+  /**
+   * The reverse adjacency's bindings. On an UNDIRECTED snapshot graph-format invariant I7 makes reverse() return
+   * the FORWARD arrays, so the core bindings ARE the reverse bindings and nothing is uploaded -- delegating to
+   * core() rather than re-uploading the arrays is what makes that true on the arena plan as well, where the
+   * per-array WeakMap key resolves to the whole-arena resident (spec 4.3 lines 1182-1186). `fwdArc` is never
+   * uploaded (spec 13 row P7). `packed` is ignored when undirected: there is nothing to pack.
+   * @param s - the snapshot
+   * @param record - its residency record
+   * @param packed - concatenate the arrays into one buffer (directed only)
+   * @returns the view binding
+   */
+  buildReverse(s, record, packed) {
+    const rev = s.reverse();
+    if (!s.directed) {
+      const core = this.core(s, ["rowPtr", "colIdx", "weights"]);
+      const bindings2 = { rowPtr: core.rowPtr };
+      if (core.colIdx !== null) {
+        bindings2.colIdx = core.colIdx;
+      }
+      if (core.weights !== null) {
+        bindings2.weights = core.weights;
+      }
+      return Object.freeze({
+        view: "reverse",
+        bindings: Object.freeze(bindings2),
+        scalars: Object.freeze({ arcCount: [rev.arcCount], directed: [0] })
+      });
+    }
+    const arrays = [
+      ["rowPtr", rev.rowPtr],
+      ["colIdx", rev.colIdx]
+    ];
+    if (rev.weights !== null) {
+      arrays.push(["weights", rev.weights]);
+    }
+    const bindings = packed ? this.packArrays(
+      record,
+      arrays,
+      this.packKey(record, "reverse:packed"),
+      `residency:view:${record.serial}:reverse:packed`
+    ) : this.separateArrays(record, arrays, `residency:view:${record.serial}:reverse`);
+    return Object.freeze({
+      view: "reverse",
+      bindings,
+      scalars: Object.freeze({ arcCount: [rev.arcCount], directed: [1] })
+    });
+  }
+  /**
+   * The each-edge-once binding an edge-parallel kernel uses on directed and undirected snapshots alike (spec 8.1
+   * row 2); `arc` is not uploaded (no kernel of P7 reads it).
+   * @param s - the snapshot
+   * @param record - its residency record
+   * @param packed - concatenate into one buffer
+   * @returns the view binding
+   */
+  buildEdgeList(s, record, packed) {
+    const list = s.edgeList();
+    const arrays = [
+      ["src", list.src],
+      ["dst", list.dst]
+    ];
+    if (list.weights !== null) {
+      arrays.push(["weights", list.weights]);
+    }
+    const bindings = packed ? this.packArrays(
+      record,
+      arrays,
+      this.packKey(record, "edgeList:packed"),
+      `residency:view:${record.serial}:edgeList:packed`
+    ) : this.separateArrays(record, arrays, `residency:view:${record.serial}:edgeList`);
+    return Object.freeze({
+      view: "edgeList",
+      bindings,
+      scalars: Object.freeze({ edgeCount: [s.edgeCount] })
+    });
+  }
+  /**
+   * One resident per array (spec 4.3: views upload in perArray mode, never into the arena).
+   * @param record - the owning record
+   * @param arrays - the named arrays
+   * @param label - the buffer label prefix
+   * @returns the bindings by name
+   */
+  separateArrays(record, arrays, label) {
+    const bindings = {};
+    for (const [name, array] of arrays) {
+      const resident = this.upload(record, array, array, `${label}:${name}`);
+      bindings[name] = { buffer: resident.buffer, offset: 0, size: resident.byteLength, window: null };
+    }
+    return Object.freeze(bindings);
+  }
+  /**
+   * The arrays concatenated into ONE buffer at STORAGE_ALIGN-aligned offsets (spec 4.3 packViews): one
+   * createBuffer and one writeBuffer instead of three of each, which is what the option buys. The resident is
+   * keyed on `key`, a marker object owned by the record (packKey), NOT on one of the snapshot's arrays: upload()
+   * returns an existing resident whenever the key matches and the serial matches, without comparing byte
+   * lengths, so keying the packed buffer on `rev.rowPtr` would make the packed and the unpacked view of one
+   * snapshot collide -- whichever was built second would get the other's buffer. The record still owns the
+   * resident, so release(s) destroys it with the rest. Offsets are STORAGE_ALIGN-aligned because Kernel.bind
+   * rejects any other offset synchronously (E_INVALID_ARGUMENT { argument: "offset" }).
+   * @param record - the owning record
+   * @param arrays - the named arrays, in buffer order
+   * @param key - the marker object the resident is keyed on
+   * @param label - the buffer label
+   * @returns the bindings by name, all into the one buffer
+   */
+  packArrays(record, arrays, key, label) {
+    const offsets = [];
+    let total = 0;
+    for (const [, array] of arrays) {
+      offsets.push(total);
+      total += Math.ceil(array.byteLength / STORAGE_ALIGN) * STORAGE_ALIGN;
+    }
+    const staging = new Uint8Array(total);
+    arrays.forEach(([, array], i) => {
+      staging.set(new Uint8Array(array.buffer, array.byteOffset, array.byteLength), offsets[i]);
+    });
+    const resident = this.upload(record, key, staging, label);
+    const bindings = {};
+    arrays.forEach(([name, array], i) => {
+      bindings[name] = { buffer: resident.buffer, offset: offsets[i], size: array.byteLength, window: null };
+    });
+    return Object.freeze(bindings);
+  }
+  /**
+   * The upload key of a packed view: a marker object allocated once per record and memo name, never one of the
+   * snapshot's arrays.
+   * @param record - the owning record
+   * @param memoKey - the `views` memo key of this packed view
+   * @returns the stable marker object
+   */
+  packKey(record, memoKey) {
+    const existing = record.packKeys.get(memoKey);
+    if (existing !== void 0) {
+      return existing;
+    }
+    const created = {};
+    record.packKeys.set(memoKey, created);
+    return created;
+  }
   /**
    * gpuView(name) + column.version; re-uploads in place when the version changed and the byte length did not
    * (spec 4.3). CONTRACT DECISION: `owner` is required so release(owner) can find the buffer (a table has no
@@ -2764,6 +2918,8 @@ class GraphResidency {
   forget(record) {
     record.released = true;
     record.bindings.clear();
+    record.views.clear();
+    record.packKeys.clear();
     record.arena = null;
     record.plan = null;
     this.bySerial.delete(record.serial);
@@ -2789,6 +2945,8 @@ class GraphResidency {
         plan: null,
         arena: null,
         bindings: /* @__PURE__ */ new Map(),
+        views: /* @__PURE__ */ new Map(),
+        packKeys: /* @__PURE__ */ new Map(),
         released: false
       };
       this.bySerial.set(s.serial, record);
@@ -3122,15 +3280,16 @@ export {
   UNIFORM_SLOT_BYTES as U,
   WebGpuGraphError as W,
   WGSL_RESERVED_WORDS as a,
-  MAX_ITERATIONS_PER_STEP as b,
-  MAX_1D_ITEMS as c,
+  U32_MAX as b,
+  MAX_ITERATIONS_PER_STEP as c,
   deviceLostError as d,
-  FA2_FLAG_FIRST as e,
-  PASSTHROUGH_FORMAT_CODES as f,
-  STORAGE_ALIGN as g,
+  MAX_1D_ITEMS as e,
+  FA2_FLAG_FIRST as f,
+  PASSTHROUGH_FORMAT_CODES as g,
   hasErrorCode as h,
   isWebGpuGraphError as i,
-  WORKGROUP_SIZE as j,
-  isSoftwareAdapter as k
+  STORAGE_ALIGN as j,
+  WORKGROUP_SIZE as k,
+  isSoftwareAdapter as l
 };
-//# sourceMappingURL=context-E6iKaeuJ.js.map
+//# sourceMappingURL=context-CRbw2Wyo.js.map