wgblas 2.0.0 → 2.1.0

package/src/sdot/sdot.mjs

@@ -12,8 +12,9 @@ import { extractTimestamp } from "../util/benchmark.mjs";
 import { extractResult } from "../util/result.mjs";
 import { getPipeline } from "../util/pipeline.mjs";
 import { GpuVector } from "../classes/GpuVector.mjs";
+import { WGS } from "../util/constants.mjs";
+import { requireSameDevice } from "../util/device.mjs";
 
-const WGS = 64; //workgroup size
 
 export async function sdot(device, n, x, incx, y, incy) {
   const xIsGpu = x instanceof GpuVector;
@@ -21,6 +22,7 @@ export async function sdot(device, n, x, incx, y, incy) {
 
   if (!(device instanceof GPUDevice))
     throw new Error("device must be a GPUDevice.");
+  requireSameDevice(device, "sdot", { x, y });
   if (
     !Number.isInteger(n) ||
     !Number.isInteger(incx) ||
@@ -58,11 +60,11 @@ export async function sdot(device, n, x, incx, y, incy) {
   let readBuffer = null;
 
   try {
-    xBuffer = xIsGpu ? x._buf : uploadBuffer(x, "sdot-x", false);
-    yBuffer = yIsGpu ? y._buf : uploadBuffer(y, "sdot-y", false);
-    partialsBuffer = createStorageBuffer(2 * WGS * 4, "sdot-partials"); //to hold 2*WGS partial sums of f32
-    resultBuffer = createResultBuffer(4, "sdot-result"); //to hold the final float32 dot product
-    paramsBuffer = createParamsBuffer(
+    xBuffer = xIsGpu ? x._buf : uploadBuffer(device, x, "sdot-x", false);
+    yBuffer = yIsGpu ? y._buf : uploadBuffer(device, y, "sdot-y", false);
+    partialsBuffer = createStorageBuffer(device, 2 * WGS * 4, "sdot-partials"); //to hold 2*WGS partial sums of f32
+    resultBuffer = createResultBuffer(device, 4, "sdot-result"); //to hold the final float32 dot product
+    paramsBuffer = createParamsBuffer(device,
       [
         { value: n, type: "u32" },
         { value: incx, type: "u32" },
@@ -71,32 +73,32 @@ export async function sdot(device, n, x, incx, y, incy) {
       "sdot-params",
     );
 
-    const bgMain = createBindGroup(pipelineMain.getBindGroupLayout(0), [
+    const bgMain = createBindGroup(device, pipelineMain.getBindGroupLayout(0), [
       xBuffer,
       yBuffer,
       partialsBuffer,
       paramsBuffer,
     ]);
-    const { commandEncoder: enc1, ts: ts1 } = runComputePass(
+    const { commandEncoder: enc1, ts: ts1 } = runComputePass(device,
       pipelineMain,
       bgMain,
       2 * WGS,
     ); //dispatch 2*WGS workgroups
 
-    submit(enc1);
+    submit(device, enc1);
 
-    const bgReduce = createBindGroup(pipelineReduce.getBindGroupLayout(0), [
+    const bgReduce = createBindGroup(device, pipelineReduce.getBindGroupLayout(0), [
       partialsBuffer,
       resultBuffer,
     ]);
-    const { commandEncoder: enc2, ts: ts2 } = runComputePass(
+    const { commandEncoder: enc2, ts: ts2 } = runComputePass(device,
       pipelineReduce,
       bgReduce,
       1,
     ); // dispatch 1 workgroup to reduce the partial sums to a single result
-    readBuffer = stageReadback(enc2, resultBuffer);
+    readBuffer = stageReadback(device, enc2, resultBuffer);
 
-    submit(enc2);
+    submit(device, enc2);
 
     const resultPromise = extractResult(readBuffer, Float32Array);
     readBuffer = null; // ownership transferred — extractResult's own finally destroys it
@@ -117,7 +119,7 @@ export async function sdot(device, n, x, incx, y, incy) {
     if (partialsBuffer) destroyBuffers(partialsBuffer);
     if (resultBuffer) destroyBuffers(resultBuffer);
     if (paramsBuffer) destroyBuffers(paramsBuffer);
-    // Only reached if submit(enc2) threw before ownership was transferred above.
+    // Only reached if submit(device, enc2) threw before ownership was transferred above.
     if (readBuffer) destroyBuffers(readBuffer);
   }
 }

package/src/sgemm/sgemm.mjs

@@ -3,6 +3,8 @@ import {
   createParamsBuffer,
   stageReadback,
   destroyBuffers,
+  vec4ViewBinding,
+  vec4Usable,
 } from "../util/buffer.mjs";
 import { createBindGroup } from "../util/bindgroup.mjs";
 import { runComputePass, submit } from "../util/compute.mjs";
@@ -10,10 +12,10 @@ import { extractResult } from "../util/result.mjs";
 import { extractTimestamp } from "../util/benchmark.mjs";
 import { getPipeline } from "../util/pipeline.mjs";
 import { GpuMatrix } from "../classes/GpuMatrix.mjs";
+import { requireWorkgroupCount } from "../util/workgroup.mjs";
+import { BM_SMALL, BN_SMALL, BM_LARGE, BN_LARGE, LARGE_TILE_WORKGROUP_THRESHOLD } from "../util/constants.mjs";
+import { requireSameDevice } from "../util/device.mjs";
 
-const BM_SMALL = 32, BN_SMALL = 32; // sgemm_small.wgsl's block tile
-const BM_LARGE = 64, BN_LARGE = 64; // sgemm_large.wgsl's block tile
-const LARGE_TILE_WORKGROUP_THRESHOLD = 36; // large tile needs >= a 6x6 grid of its own tiles to beat the small tile
 
 export async function sgemm(
   device, transA, transB, m, n, k, alpha, A, lda, B, ldb, beta, C, ldc, layout = "row-major",
@@ -24,6 +26,7 @@ export async function sgemm(
 
   if (!(device instanceof GPUDevice))
     throw new Error("device must be a GPUDevice.");
+  requireSameDevice(device, "sgemm", { A, B, C });
   if (transA !== "no-transpose" && transA !== "transpose")
     throw new Error("transA must be 'no-transpose' or 'transpose'.");
   if (transB !== "no-transpose" && transB !== "transpose")
@@ -135,10 +138,16 @@ export async function sgemm(
 
   const pipeline = await getPipeline(device, useLargeTile ? "sgemm_large" : "sgemm_small");
 
-  const ABuffer = AIsGpu ? A._buf : uploadBuffer(A, "sgemm-A", false);
-  const BBuffer = BIsGpu ? B._buf : uploadBuffer(B, "sgemm-B", false);
-  const CBuffer = CIsGpu ? C._buf : uploadBuffer(C, "sgemm-C", true);
-  const paramsBuffer = createParamsBuffer(
+  const ABuffer = AIsGpu ? A._buf : uploadBuffer(device, A, "sgemm-A", false);
+  const BBuffer = BIsGpu ? B._buf : uploadBuffer(device, B, "sgemm-B", false);
+  const CBuffer = CIsGpu ? C._buf : uploadBuffer(device, C, "sgemm-C", true);
+  // Vectorized-load enablement — kernel-side view after the column-major swap.
+  // op(A) is m×k (no-trans) or k×m (trans); op(B) is k×n or n×k.
+  const aNot = transA === "no-transpose";
+  const bNot = transB === "no-transpose";
+  const useVecA = aNot && vec4Usable(ABuffer, lda, m, k); // transposed-A vec stores bank-conflict smem — measured slower than scalar
+  const useVecB = vec4Usable(BBuffer, ldb, bNot ? k : n, bNot ? n : k);
+  const paramsBuffer = createParamsBuffer(device,
     [
       { value: m,   type: "u32" },
       { value: n,   type: "u32" },
@@ -150,31 +159,35 @@ export async function sgemm(
       { value: ldc, type: "u32" },
       { value: transA === "transpose" ? 1 : 0, type: "u32" },
       { value: transB === "transpose" ? 1 : 0, type: "u32" },
+      { value: useVecA ? 1 : 0, type: "u32" },
+      { value: useVecB ? 1 : 0, type: "u32" },
     ],
     "sgemm-params",
   );
 
   try {
-    const bindGroup = createBindGroup(pipeline.getBindGroupLayout(0), [
+    const bindGroup = createBindGroup(device, pipeline.getBindGroupLayout(0), [
       ABuffer,
+      vec4ViewBinding(device, ABuffer),
       BBuffer,
+      vec4ViewBinding(device, BBuffer),
       CBuffer,
       paramsBuffer,
     ]);
 
     const wgCount = useLargeTile
       ? {
-        x: Math.min(largeWgX, device.limits.maxComputeWorkgroupsPerDimension),
-        y: Math.min(largeWgY, device.limits.maxComputeWorkgroupsPerDimension),
+        x: requireWorkgroupCount(device, largeWgX, "sgemm", "x"),
+        y: requireWorkgroupCount(device, largeWgY, "sgemm", "y"),
       }
       : {
-        x: Math.min(Math.ceil(n / BN_SMALL), device.limits.maxComputeWorkgroupsPerDimension),
-        y: Math.min(Math.ceil(m / BM_SMALL), device.limits.maxComputeWorkgroupsPerDimension),
+        x: requireWorkgroupCount(device, Math.ceil(n / BN_SMALL), "sgemm", "x"),
+        y: requireWorkgroupCount(device, Math.ceil(m / BM_SMALL), "sgemm", "y"),
       };
-    const { commandEncoder, ts } = runComputePass(pipeline, bindGroup, wgCount);
-    const readBuffer = CIsGpu ? null : stageReadback(commandEncoder, CBuffer);
+    const { commandEncoder, ts } = runComputePass(device, pipeline, bindGroup, wgCount);
+    const readBuffer = CIsGpu ? null : stageReadback(device, commandEncoder, CBuffer);
 
-    submit(commandEncoder);
+    submit(device, commandEncoder);
 
     const gpuTimeMs = await extractTimestamp(ts);
 

package/src/sgemmtr/sgemmtr.mjs

@@ -10,10 +10,10 @@ import { extractResult } from "../util/result.mjs";
 import { extractTimestamp } from "../util/benchmark.mjs";
 import { getPipeline } from "../util/pipeline.mjs";
 import { GpuMatrix } from "../classes/GpuMatrix.mjs";
+import { requireWorkgroupCount } from "../util/workgroup.mjs";
+import { BM_SMALL, BN_SMALL, BM_LARGE, BN_LARGE, LARGE_TILE_WORKGROUP_THRESHOLD } from "../util/constants.mjs";
+import { requireSameDevice } from "../util/device.mjs";
 
-const BM_SMALL = 32, BN_SMALL = 32; // sgemmtr_small.wgsl's block tile
-const BM_LARGE = 64, BN_LARGE = 64; // sgemmtr_large.wgsl's block tile
-const LARGE_TILE_WORKGROUP_THRESHOLD = 36; // same threshold sgemm uses — see sgemm.mjs
 
 export async function sgemmtr(
   device, uplo, transA, transB, m, n, k, alpha, A, lda, B, ldb, beta, C, ldc, layout = "row-major",
@@ -24,6 +24,7 @@ export async function sgemmtr(
 
   if (!(device instanceof GPUDevice))
     throw new Error("device must be a GPUDevice.");
+  requireSameDevice(device, "sgemmtr", { A, B, C });
   if (uplo !== "lower" && uplo !== "upper")
     throw new Error("uplo must be 'lower' or 'upper'.");
   if (transA !== "no-transpose" && transA !== "transpose")
@@ -142,10 +143,10 @@ export async function sgemmtr(
 
   const pipeline = await getPipeline(device, useLargeTile ? "sgemmtr_large" : "sgemmtr_small");
 
-  const ABuffer = AIsGpu ? A._buf : uploadBuffer(A, "sgemmtr-A", false);
-  const BBuffer = BIsGpu ? B._buf : uploadBuffer(B, "sgemmtr-B", false);
-  const CBuffer = CIsGpu ? C._buf : uploadBuffer(C, "sgemmtr-C", true);
-  const paramsBuffer = createParamsBuffer(
+  const ABuffer = AIsGpu ? A._buf : uploadBuffer(device, A, "sgemmtr-A", false);
+  const BBuffer = BIsGpu ? B._buf : uploadBuffer(device, B, "sgemmtr-B", false);
+  const CBuffer = CIsGpu ? C._buf : uploadBuffer(device, C, "sgemmtr-C", true);
+  const paramsBuffer = createParamsBuffer(device,
     [
       { value: m,   type: "u32" },
       { value: n,   type: "u32" },
@@ -163,7 +164,7 @@ export async function sgemmtr(
   );
 
   try {
-    const bindGroup = createBindGroup(pipeline.getBindGroupLayout(0), [
+    const bindGroup = createBindGroup(device, pipeline.getBindGroupLayout(0), [
       ABuffer,
       BBuffer,
       CBuffer,
@@ -172,17 +173,17 @@ export async function sgemmtr(
 
     const wgCount = useLargeTile
       ? {
-        x: Math.min(largeWgX, device.limits.maxComputeWorkgroupsPerDimension),
-        y: Math.min(largeWgY, device.limits.maxComputeWorkgroupsPerDimension),
+        x: requireWorkgroupCount(device, largeWgX, "sgemmtr", "x"),
+        y: requireWorkgroupCount(device, largeWgY, "sgemmtr", "y"),
       }
       : {
-        x: Math.min(Math.ceil(n / BN_SMALL), device.limits.maxComputeWorkgroupsPerDimension),
-        y: Math.min(Math.ceil(m / BM_SMALL), device.limits.maxComputeWorkgroupsPerDimension),
+        x: requireWorkgroupCount(device, Math.ceil(n / BN_SMALL), "sgemmtr", "x"),
+        y: requireWorkgroupCount(device, Math.ceil(m / BM_SMALL), "sgemmtr", "y"),
       };
-    const { commandEncoder, ts } = runComputePass(pipeline, bindGroup, wgCount);
-    const readBuffer = CIsGpu ? null : stageReadback(commandEncoder, CBuffer);
+    const { commandEncoder, ts } = runComputePass(device, pipeline, bindGroup, wgCount);
+    const readBuffer = CIsGpu ? null : stageReadback(device, commandEncoder, CBuffer);
 
-    submit(commandEncoder);
+    submit(device, commandEncoder);
 
     const gpuTimeMs = await extractTimestamp(ts);
 

package/src/sgemv/sgemv.mjs

@@ -9,9 +9,10 @@ import { runComputePass, submit } from "../util/compute.mjs";
 import { extractResult } from "../util/result.mjs";
 import { extractTimestamp } from "../util/benchmark.mjs";
 import { getPipeline } from "../util/pipeline.mjs";
-import { calcWorkgroups } from "../util/workgroup.mjs";
+import { requireWorkgroups } from "../util/workgroup.mjs";
 import { GpuVector } from "../classes/GpuVector.mjs";
 import { GpuMatrix } from "../classes/GpuMatrix.mjs";
+import { requireSameDevice } from "../util/device.mjs";
 
 export async function sgemv(device, trans, m, n, alpha, A, lda, x, incx, beta, y, incy, layout = "row-major") {
   const AIsGpu = A instanceof GpuMatrix;
@@ -20,6 +21,7 @@ export async function sgemv(device, trans, m, n, alpha, A, lda, x, incx, beta, y
 
   if (!(device instanceof GPUDevice))
     throw new Error("device must be a GPUDevice.");
+  requireSameDevice(device, "sgemv", { A, x, y });
   if (trans !== "no-transpose" && trans !== "transpose")
     throw new Error("trans must be 'no-transpose' or 'transpose'.");
   if (layout !== "row-major" && layout !== "column-major")
@@ -62,6 +64,8 @@ export async function sgemv(device, trans, m, n, alpha, A, lda, x, incx, beta, y
     );
   if (xIsGpu && x._buf === y._buf)
     throw new Error("x and y must not reference the same GPU buffer when both are GpuVectors.");
+  if (AIsGpu && yIsGpu && A._buf === y._buf)
+    throw new Error("A and y must not reference the same GPU buffer.");
   if (AIsGpu && lda !== A.lda)
     throw new Error("lda must match A.lda when A is a GpuMatrix.");
   if (AIsGpu && (A.rows < m || A.cols < n))
@@ -99,38 +103,46 @@ export async function sgemv(device, trans, m, n, alpha, A, lda, x, incx, beta, y
   const shaderName = isNoTrans ? "sgemv_n" : "sgemv_t";
   const pipeline   = await getPipeline(device, shaderName);
 
-  const ABuffer = AIsGpu ? A._buf : uploadBuffer(A, "sgemv-A", false);
-  const xBuffer = xIsGpu ? x._buf : uploadBuffer(x, "sgemv-x", false);
-  const yBuffer = yIsGpu ? y._buf : uploadBuffer(y, "sgemv-y", true);
-  const paramsBuffer = createParamsBuffer(
-    [
-      { value: m,     type: "u32" },
-      { value: n,     type: "u32" },
-      { value: alpha, type: "f32" },
-      { value: beta,  type: "f32" },
-      { value: incx,  type: "u32" },
-      { value: incy,  type: "u32" },
-      { value: lda,   type: "u32" },
-    ],
-    "sgemv-params",
-  );
+  let ABuffer = null;
+  let xBuffer = null;
+  let yBuffer = null;
+  let paramsBuffer = null;
 
   try {
-    const bindGroup = createBindGroup(pipeline.getBindGroupLayout(0), [
+    ABuffer = AIsGpu ? A._buf : uploadBuffer(device, A, "sgemv-A", false);
+    xBuffer = xIsGpu ? x._buf : uploadBuffer(device, x, "sgemv-x", false);
+    yBuffer = yIsGpu ? y._buf : uploadBuffer(device, y, "sgemv-y", true);
+    paramsBuffer = createParamsBuffer(device,
+      [
+        { value: m,     type: "u32" },
+        { value: n,     type: "u32" },
+        { value: alpha, type: "f32" },
+        { value: beta,  type: "f32" },
+        { value: incx,  type: "u32" },
+        { value: incy,  type: "u32" },
+        { value: lda,   type: "u32" },
+      ],
+      "sgemv-params",
+    );
+
+    const bindGroup = createBindGroup(device, pipeline.getBindGroupLayout(0), [
       ABuffer,
       xBuffer,
       yBuffer,
       paramsBuffer,
     ]);
 
-    // NoTrans: one workgroup per row (grid-stride handles overflow); Trans: one thread per output column.
+    // NoTrans: one workgroup per row — sgemv_n.wgsl is a grid-stride loop, so
+    // clamping here only costs parallelism. Trans: one thread per output
+    // column, and sgemv_t.wgsl indexes straight off global_invocation_id with
+    // no fallback, so an over-limit dispatch must be refused, not truncated.
     const wgCount = isNoTrans
       ? Math.min(m, device.limits.maxComputeWorkgroupsPerDimension)
-      : calcWorkgroups(yLen);
-    const { commandEncoder, ts } = runComputePass(pipeline, bindGroup, wgCount);
-    const readBuffer = yIsGpu ? null : stageReadback(commandEncoder, yBuffer);
+      : requireWorkgroups(device, "sgemv", yLen);
+    const { commandEncoder, ts } = runComputePass(device, pipeline, bindGroup, wgCount);
+    const readBuffer = yIsGpu ? null : stageReadback(device, commandEncoder, yBuffer);
 
-    submit(commandEncoder);
+    submit(device, commandEncoder);
 
     const gpuTimeMs = await extractTimestamp(ts);
 
@@ -143,10 +155,10 @@ export async function sgemv(device, trans, m, n, alpha, A, lda, x, incx, beta, y
     if (gpuTimeMs !== undefined) return { y: result, gpuTimeMs };
     return { y: result };
   } finally {
-    if (!AIsGpu) destroyBuffers(ABuffer);
-    if (!xIsGpu) destroyBuffers(xBuffer);
-    if (!yIsGpu) destroyBuffers(yBuffer);
-    destroyBuffers(paramsBuffer);
+    if (!AIsGpu && ABuffer) destroyBuffers(ABuffer);
+    if (!xIsGpu && xBuffer) destroyBuffers(xBuffer);
+    if (!yIsGpu && yBuffer) destroyBuffers(yBuffer);
+    if (paramsBuffer) destroyBuffers(paramsBuffer);
 
   }
 }

package/src/sger/sger.mjs

@@ -11,12 +11,14 @@ import { extractTimestamp } from "../util/benchmark.mjs";
 import { getPipeline } from "../util/pipeline.mjs";
 import { GpuVector } from "../classes/GpuVector.mjs";
 import { GpuMatrix } from "../classes/GpuMatrix.mjs";
+import { requireSameDevice } from "../util/device.mjs";
 
 export async function sger(device, m, n, alpha, x, incx, y, incy, A, lda, layout = "row-major") {
   const AIsGpu = A instanceof GpuMatrix;
 
   if (!(device instanceof GPUDevice))
     throw new Error("device must be a GPUDevice.");
+  requireSameDevice(device, "sger", { A, x, y });
   if (layout !== "row-major" && layout !== "column-major")
     throw new Error("layout must be 'row-major' or 'column-major'.");
   if (typeof alpha !== "number")
@@ -89,10 +91,10 @@ export async function sger(device, m, n, alpha, x, incx, y, incy, A, lda, layout
   let paramsBuffer = null;
 
   try {
-    xBuffer = xIsGpu ? x._buf : uploadBuffer(x, "sger-x", false);
-    yBuffer = yIsGpu ? y._buf : uploadBuffer(y, "sger-y", false);
-    ABuffer = AIsGpu ? A._buf : uploadBuffer(A, "sger-A", true);
-    paramsBuffer = createParamsBuffer(
+    xBuffer = xIsGpu ? x._buf : uploadBuffer(device, x, "sger-x", false);
+    yBuffer = yIsGpu ? y._buf : uploadBuffer(device, y, "sger-y", false);
+    ABuffer = AIsGpu ? A._buf : uploadBuffer(device, A, "sger-A", true);
+    paramsBuffer = createParamsBuffer(device,
       [
         { value: m,     type: "u32" },
         { value: n,     type: "u32" },
@@ -104,7 +106,7 @@ export async function sger(device, m, n, alpha, x, incx, y, incy, A, lda, layout
       "sger-params",
     );
 
-    const bindGroup = createBindGroup(pipeline.getBindGroupLayout(0), [
+    const bindGroup = createBindGroup(device, pipeline.getBindGroupLayout(0), [
       xBuffer,
       yBuffer,
       ABuffer,
@@ -114,10 +116,10 @@ export async function sger(device, m, n, alpha, x, incx, y, incy, A, lda, layout
     // One workgroup per row of A; clamped to device limit — the shader's
     // grid-stride loop handles remaining rows when m > dispatch count.
     const wgCount = Math.min(m, device.limits.maxComputeWorkgroupsPerDimension);
-    const { commandEncoder, ts } = runComputePass(pipeline, bindGroup, wgCount);
-    const readBuffer = AIsGpu ? null : stageReadback(commandEncoder, ABuffer);
+    const { commandEncoder, ts } = runComputePass(device, pipeline, bindGroup, wgCount);
+    const readBuffer = AIsGpu ? null : stageReadback(device, commandEncoder, ABuffer);
 
-    submit(commandEncoder);
+    submit(device, commandEncoder);
 
     const gpuTimeMs = await extractTimestamp(ts);
 

package/src/shaders/index.mjs

@@ -3,25 +3,175 @@
  *
  * `shaders/*.wgsl` — one WGSL compute shader per BLAS routine (sscal, saxpy, sdot, …).
  *
- * `shaders/browser-shaders.mjs` — the browser's runtime shader source. In Node.js, shaders are
- * read directly from disk via `readFileSync`. In the browser there is no filesystem, so this file
- * provides all shader strings inline. Vite bundles it by importing each `.wgsl` file as a string.
+ * `routineShaders` below is the single source of truth: routine name → the WGSL source(s)
+ * its `getPipeline()` calls actually reference, verified against every `src/<routine>/<routine>.mjs`
+ * rather than inferred from naming convention (see its doc comment for the exceptions). Each
+ * shader is imported right above the line that adds it — the import *is* the mapping entry, no
+ * separate block to cross-reference. `shaderSources`, the flat name → source registry the
+ * browser bundle's runtime lookup needs, is *derived* from `routineShaders` rather than
+ * hand-duplicated, so the two can never drift apart. In Node.js neither is read — shaders are
+ * `readFileSync` from disk directly; `scripts/build-browser.mjs` inlines this module into the
+ * browser's IIFE bundle via esbuild instead.
  *
  * ## Cross-shader patterns
  *
- * **Fixed workgroup size of 64.** Every shader declares `const WGS: u32 = 64` and
- * `@workgroup_size(64)`. 64 is the minimum `maxComputeInvocationsPerWorkgroup` guaranteed across
- * all WebGPU devices, so this works everywhere without querying device limits.
+ * **Single bind group.** Every shader with bindings uses `@group(0)` only — the JS side always
+ * calls `pipeline.getBindGroupLayout(0)`, no secondary groups to track. Binding order is
+ * consistent too: any read-only storage buffers come before read_write ones, with the
+ * `uniform Params` struct always last. `@binding` indices match the position of each resource in
+ * the array passed to `createBindGroup`, which appends `resultBuffer` last.
  *
- * **Single bind group.** All bindings use `@group(0)`. This means the JS side always calls
- * `pipeline.getBindGroupLayout(0)` — no secondary groups to track.
+ * **All counts and strides are `u32`.** `n`, `x_inc`, `y_inc`, and every other index/count field
+ * in a `Params` struct is unsigned, avoiding implicit sign-extension in index expressions like
+ * `id * params.x_inc`.
  *
- * The `@binding` indices must match the position of each resource in the array passed to
- * `createBindGroup` — it assigns `binding: 0, 1, 2 …` sequentially, with `resultBuffer` appended last.
- *
- * **All counts and strides are `u32`.** `n`, `x_inc`, `y_inc`, and any other index fields in the
- * `Params` uniform struct are unsigned. This avoids implicit sign-extension when they appear in
- * index expressions like `id * params.x_inc`.
+ * **Entry points don't have to be named `main`.** `loadShader` (`util/pipeline.mjs`)
+ * auto-detects the sole `@compute` function in a module instead of requiring a fixed name, so
+ * `dasum_main`, `strsv_invert_block_main`, etc. work without renaming.
  *
  * @module devdocs/shaders
  */
+
+/**
+ * Routine name → the WGSL source(s) its `getPipeline()` calls reference. Keys are the exact
+ * shader names `getPipeline(device, name)` is called with — most routines have one, some pick
+ * one of several conditionally (e.g. sgemv's `sgemv_n`/`sgemv_t`, by `trans`), and some have no
+ * dedicated shader at all:
+ *
+ * - `sgemmtr`/`ssyrk`/`ssyr2k` all dispatch through `sgemmtr_small`/`sgemmtr_large`.
+ * - `strsm` reuses `strsv_invert_block` and `sscal`, plus its own `block_transfer` and the
+ *   shared `sgemm_small`/`sgemm_large`.
+ * - `dasum`/`idamax` concatenate several f64 utility shaders with their own — see
+ *   `getPipeline`'s `shaderName: string[]` behaviour.
+ * - `random` has no entry — CPU-only, no `getPipeline()` call.
+ *
+ * Built up entry by entry so each import sits next to the mapping entry that uses it.
+ * @public
+ */
+export const routineShaders = {};
+
+import sscal from "./sscal.wgsl";
+routineShaders.sscal = { sscal };
+
+import sswap from "./sswap.wgsl";
+routineShaders.sswap = { sswap };
+
+import saxpy from "./saxpy.wgsl";
+routineShaders.saxpy = { saxpy };
+
+import scopy from "./scopy.wgsl";
+routineShaders.scopy = { scopy };
+
+import sdot from "./sdot.wgsl";
+import sum from "./reduction/sum.wgsl";
+routineShaders.sdot = { sdot, "reduction/sum": sum };
+
+import sasum from "./sasum.wgsl";
+routineShaders.sasum = { sasum, "reduction/sum": sum };
+
+import snrm2 from "./snrm2.wgsl";
+import scaledSum from "./reduction/scaledSum.wgsl";
+routineShaders.snrm2 = { snrm2, "reduction/scaledSum": scaledSum };
+
+import isamax from "./isamax.wgsl";
+import argmax from "./reduction/argmax.wgsl";
+routineShaders.isamax = { isamax, "reduction/argmax": argmax };
+
+import dekker from "./f64/dekker.wgsl";
+import ddAbs from "./f64/utils/abs.wgsl";
+import ddAddUtil from "./f64/utils/add.wgsl";
+import dasum from "./dasum.wgsl";
+import sumF64 from "./reduction/sumF64.wgsl";
+routineShaders.dasum = {
+  "f64/dekker": dekker,
+  "f64/utils/abs": ddAbs,
+  "f64/utils/add": ddAddUtil,
+  dasum,
+  "reduction/sumF64": sumF64,
+};
+
+import ddGreater from "./f64/utils/greater.wgsl";
+import ddEqual from "./f64/utils/equal.wgsl";
+import idamax from "./idamax.wgsl";
+import argmaxF64 from "./reduction/argmaxF64.wgsl";
+routineShaders.idamax = {
+  "f64/dekker": dekker,
+  "f64/utils/abs": ddAbs,
+  "f64/utils/greater": ddGreater,
+  "f64/utils/equal": ddEqual,
+  idamax,
+  "reduction/argmaxF64": argmaxF64,
+};
+
+import srot from "./srot.wgsl";
+routineShaders.srot = { srot };
+
+import srotm from "./srotm.wgsl";
+routineShaders.srotm = { srotm };
+
+import sgemv_n from "./sgemv_n.wgsl";
+import sgemv_t from "./sgemv_t.wgsl";
+routineShaders.sgemv = { sgemv_n, sgemv_t }; // one or the other, picked by trans
+
+import ssymv from "./ssymv.wgsl";
+routineShaders.ssymv = { ssymv };
+
+import strmv from "./strmv.wgsl";
+routineShaders.strmv = { strmv };
+
+import strsv_invert_block from "./strsv_invert_block.wgsl";
+import strsv_apply_inverse from "./strsv_apply_inverse.wgsl";
+import strsv_update from "./strsv_update.wgsl";
+routineShaders.strsv = {
+  strsv_invert_block,
+  strsv_apply_inverse,
+  strsv_update,
+};
+
+import sger from "./sger.wgsl";
+routineShaders.sger = { sger };
+
+import ssyr from "./ssyr.wgsl";
+routineShaders.ssyr = { ssyr };
+
+import ssyr2 from "./ssyr2.wgsl";
+routineShaders.ssyr2 = { ssyr2 };
+
+import sgemm_small from "./sgemm_small.wgsl";
+import sgemm_large from "./sgemm_large.wgsl";
+routineShaders.sgemm = { sgemm_small, sgemm_large }; // one or the other, picked by a tile-size threshold
+
+import sgemmtr_small from "./sgemmtr_small.wgsl";
+import sgemmtr_large from "./sgemmtr_large.wgsl";
+routineShaders.sgemmtr = { sgemmtr_small, sgemmtr_large };
+
+routineShaders.ssyrk = { sgemmtr_small, sgemmtr_large }; // no shader of its own — rides on sgemmtr's
+routineShaders.ssyr2k = { sgemmtr_small, sgemmtr_large }; // no shader of its own — rides on sgemmtr's
+
+import symmetrize from "./symmetrize.wgsl";
+routineShaders.ssymm = { sgemm_small, sgemm_large, symmetrize };
+
+import triangularize from "./triangularize.wgsl";
+routineShaders.strmm = { sgemm_small, sgemm_large, triangularize };
+
+import blockTransfer from "./block_transfer.wgsl";
+routineShaders.strsm = {
+  strsv_invert_block,
+  block_transfer: blockTransfer,
+  sscal,
+  sgemm_small,
+  sgemm_large,
+};
+
+/**
+ * Flat shader-name → WGSL source-string registry — what `getPipeline()`/`loadShader()` (see
+ * `util/pipeline.mjs`) actually look shaders up in, in the browser. Derived from
+ * `routineShaders` by merging every routine's shaders together; shared shaders (e.g.
+ * `"reduction/sum"`, used by two different routines above) collapse harmlessly here since
+ * every routine's copy is the same imported string, never independently authored text.
+ * @public
+ */
+export const shaderSources = Object.assign(
+  {},
+  ...Object.values(routineShaders),
+);