@graphty/webgpu-graph-algorithms 0.0.0 → 0.2.1

package/dist/node.d.ts

@@ -0,0 +1 @@
+export * from "./src/node/index.js";

package/dist/node.js

@@ -0,0 +1,131 @@
+import { W as WebGpuGraphError, G as GpuContext } from "./chunks/context-E6iKaeuJ.js";
+const INSTALL_HINT = "install the optional peer dependency webgpu@0.4.0";
+function isDawnModule(loaded) {
+  return typeof loaded === "object" && loaded !== null && typeof loaded.create === "function";
+}
+function messageOf(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+class DawnHandle {
+  /**
+   * Wraps a GPU object.
+   * @param gpu - the object dawn.create() returned
+   */
+  constructor(gpu) {
+    this.ref = gpu;
+  }
+  /**
+   * The GPU object; E_DISPOSED after dispose().
+   * @returns the GPU object
+   */
+  get gpu() {
+    if (this.ref === null) {
+      throw new WebGpuGraphError("E_DISPOSED", "the Dawn GPU handle was disposed", { label: "NodeGpuHandle" });
+    }
+    return this.ref;
+  }
+  /** Drops the reference; idempotent. */
+  dispose() {
+    this.ref = null;
+  }
+}
+function dawnFlags(options) {
+  const flags = [];
+  if (options === void 0) {
+    return flags;
+  }
+  if (options.adapter !== void 0 && options.adapter !== "") {
+    flags.push(`adapter=${options.adapter}`);
+  } else if (options.software === true) {
+    flags.push("adapter=llvmpipe");
+  }
+  if (options.backend !== void 0) {
+    flags.push(`backend=${options.backend}`);
+  }
+  if (options.dawnFeatures !== void 0 && options.dawnFeatures.length > 0) {
+    flags.push(`enable-dawn-features=${options.dawnFeatures.join(",")}`);
+  }
+  return flags;
+}
+async function createNodeGpu(options) {
+  const load = options?.loadModule ?? (() => import("webgpu"));
+  let loaded;
+  try {
+    loaded = await load();
+  } catch (err) {
+    const reason = messageOf(err);
+    throw new WebGpuGraphError(
+      "E_NO_WEBGPU",
+      `the webgpu (Dawn) native module did not load: ${reason}; ${INSTALL_HINT}`,
+      { reason, hint: INSTALL_HINT }
+    );
+  }
+  if (!isDawnModule(loaded)) {
+    const reason = "the webgpu module exports no create() function";
+    throw new WebGpuGraphError("E_NO_WEBGPU", `${reason}; ${INSTALL_HINT}`, { reason, hint: INSTALL_HINT });
+  }
+  if (options?.installGlobals !== false && typeof loaded.globals === "object" && loaded.globals !== null) {
+    Object.assign(globalThis, loaded.globals);
+  }
+  let gpu;
+  try {
+    gpu = loaded.create(dawnFlags(options));
+  } catch (err) {
+    const reason = `dawn.create() threw: ${messageOf(err)}`;
+    throw new WebGpuGraphError("E_NO_WEBGPU", `${reason}; ${INSTALL_HINT}`, { reason, hint: INSTALL_HINT });
+  }
+  return new DawnHandle(gpu);
+}
+function contextOptionsOf(options) {
+  return {
+    powerPreference: options.powerPreference,
+    rejectSoftware: options.rejectSoftware,
+    limits: options.limits,
+    optionalFeatures: options.optionalFeatures,
+    requiredFeatures: options.requiredFeatures,
+    label: options.label,
+    onError: options.onError,
+    warnUnreleasedSnapshots: options.warnUnreleasedSnapshots
+  };
+}
+async function createNodeGpuContext(options) {
+  const handle = await createNodeGpu(options);
+  let ctx;
+  try {
+    ctx = await GpuContext.create({ ...contextOptionsOf(options ?? {}), gpu: handle.gpu, runtime: "node" });
+  } catch (err) {
+    handle.dispose();
+    throw err;
+  }
+  const { lost } = ctx;
+  ctx.attachDisposer(() => {
+    void lost.then(() => {
+      handle.dispose();
+    });
+  });
+  return ctx;
+}
+async function probeNodeWebGpu(options) {
+  let handle;
+  try {
+    handle = await createNodeGpu(options);
+  } catch (err) {
+    return { ok: false, code: "E_NO_WEBGPU", reason: messageOf(err), adapter: null, summary: null };
+  }
+  try {
+    return await GpuContext.probe({
+      gpu: handle.gpu,
+      powerPreference: options?.powerPreference ?? "high-performance",
+      rejectSoftware: options?.rejectSoftware
+    });
+  } finally {
+    handle.dispose();
+  }
+}
+export {
+  createNodeGpu,
+  createNodeGpuContext,
+  dawnFlags,
+  probeNodeWebGpu
+};
+//# sourceMappingURL=node.js.map

package/dist/node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.js","sources":["../src/node/index.ts"],"sourcesContent":["/// <reference types=\"@webgpu/types\" preserve=\"true\" />\n/**\n * The ./node entry (spec 2.1, 2.3, 3.4; contract 3.7): Dawn through the optional peer dependency `webgpu`. The\n * ONLY file of the package that names the \"webgpu\" module, and only inside `await import(\"webgpu\")` in a\n * function body, so the root and browser bundles never carry the specifier (spec 2.5; test/build-output.test.ts,\n * test/layers.test.ts). P0-T3 wrote createNodeGpu, dawnFlags and their types; P1-T1 adds createNodeGpuContext,\n * probeNodeWebGpu and the `extends Omit<GpuContextOptions, ...>` clause of NodeGpuOptions.\n *\n * Rule of spec 2.5 item 5 (also in CLAUDE.md): \"./node\" is imported only by Node entry points and tests.\n */\n\nimport { GpuContext } from \"../context.js\";\nimport { WebGpuGraphError } from \"../errors.js\";\nimport type { GpuContextOptions, ProbeResult } from \"../types/context.js\";\n\n/** Options of the Node helpers (spec 3.4). */\nexport interface NodeGpuOptions extends Omit<GpuContextOptions, \"gpu\" | \"adapter\" | \"device\" | \"runtime\"> {\n    /** Dawn `adapter=<substring>`: a substring of the adapter name (`llvmpipe`, `4070`); an empty string is ignored; wins over `software`. */\n    readonly adapter?: string | undefined;\n    /** Dawn `backend=<name>`; `null` compiles pipelines and runs nothing (spec 5.1; the compile tests use it). */\n    readonly backend?: \"vulkan\" | \"d3d12\" | \"d3d11\" | \"metal\" | \"opengl\" | \"opengles\" | \"null\" | undefined;\n    /** Dawn toggles, emitted as `enable-dawn-features=a,b`. */\n    readonly dawnFeatures?: readonly string[] | undefined;\n    /** Shorthand for `adapter=llvmpipe` (Linux / Mesa specific, spec 2.3); ignored when `adapter` is given. */\n    readonly software?: boolean | undefined;\n    /** Install dawn.globals on globalThis (default true; spec 2.1 rule 2) so user code sees GPUBufferUsage and friends. */\n    readonly installGlobals?: boolean | undefined;\n    /**\n     * Test seam: replaces `() => import(\"webgpu\")` so a missing / broken module can be simulated.\n     * @internal\n     */\n    readonly loadModule?: (() => Promise<unknown>) | undefined;\n}\n\n/** The Dawn GPU handle (spec 2.3): dispose() drops the reference so the process can exit. */\nexport interface NodeGpuHandle {\n    /** The GPU of `dawn.create(flags)`; reading it after dispose() throws E_DISPOSED. */\n    readonly gpu: GPU;\n    /** Drops the GPU reference; idempotent. */\n    dispose(): void;\n}\n\n/** The install hint of E_NO_WEBGPU (spec 2.5 item 4); P-ENV re-pins the version together with the devDependency. */\nconst INSTALL_HINT = \"install the optional peer dependency webgpu@0.4.0\";\n\n/** The shape of the `webgpu` module (its types.d.ts: create(options: string[]): GPU; globals: Object). */\ninterface DawnModule {\n    create(options: string[]): GPU;\n    globals?: unknown;\n}\n\n/**\n * Whether a loaded module is usable as Dawn.\n * @param loaded - the module namespace\n * @returns true when it has a create() function\n */\nfunction isDawnModule(loaded: unknown): loaded is DawnModule {\n    return (\n        typeof loaded === \"object\" && loaded !== null && typeof (loaded as { create?: unknown }).create === \"function\"\n    );\n}\n\n/**\n * The message of a thrown value.\n * @param err - what was caught\n * @returns the Error message, or the value as a string\n */\nfunction messageOf(err: unknown): string {\n    return err instanceof Error ? err.message : String(err);\n}\n\n/** The handle returned by createNodeGpu(): `gpu` is a getter so dispose() can drop the reference. */\nclass DawnHandle implements NodeGpuHandle {\n    private ref: GPU | null;\n\n    /**\n     * Wraps a GPU object.\n     * @param gpu - the object dawn.create() returned\n     */\n    constructor(gpu: GPU) {\n        this.ref = gpu;\n    }\n\n    /**\n     * The GPU object; E_DISPOSED after dispose().\n     * @returns the GPU object\n     */\n    get gpu(): GPU {\n        if (this.ref === null) {\n            throw new WebGpuGraphError(\"E_DISPOSED\", \"the Dawn GPU handle was disposed\", { label: \"NodeGpuHandle\" });\n        }\n        return this.ref;\n    }\n\n    /** Drops the reference; idempotent. */\n    dispose(): void {\n        this.ref = null;\n    }\n}\n\n/**\n * The Dawn flag list a NodeGpuOptions maps to (exported for the tests and scripts/gpu-report.js):\n * adapter=<s>, backend=<s>, enable-dawn-features=a,b, and software -> adapter=llvmpipe; an explicit non-empty\n * `adapter` wins over `software`; an empty feature list emits nothing.\n * @param options - the Node options, or undefined for no flags\n * @returns the strings for dawn.create(), in the order adapter, backend, features\n */\nexport function dawnFlags(options: NodeGpuOptions | undefined): string[] {\n    const flags: string[] = [];\n    if (options === undefined) {\n        return flags;\n    }\n    if (options.adapter !== undefined && options.adapter !== \"\") {\n        flags.push(`adapter=${options.adapter}`);\n    } else if (options.software === true) {\n        flags.push(\"adapter=llvmpipe\");\n    }\n    if (options.backend !== undefined) {\n        flags.push(`backend=${options.backend}`);\n    }\n    if (options.dawnFeatures !== undefined && options.dawnFeatures.length > 0) {\n        flags.push(`enable-dawn-features=${options.dawnFeatures.join(\",\")}`);\n    }\n    return flags;\n}\n\n/**\n * import(\"webgpu\"), install dawn.globals unless installGlobals === false, dawn.create(flags) (spec 2.3).\n * @param options - adapter / backend / dawnFeatures / software / installGlobals (and the test seam)\n * @returns the handle; `dispose()` drops the GPU reference so the process can exit\n * @throws WebGpuGraphError E_NO_WEBGPU { reason, hint } when the module does not load (missing, or its glibc is too old), has no create(), or create(flags) throws\n */\nexport async function createNodeGpu(options?: NodeGpuOptions): Promise<NodeGpuHandle> {\n    const load = options?.loadModule ?? ((): Promise<unknown> => import(\"webgpu\"));\n    let loaded: unknown;\n    try {\n        loaded = await load();\n    } catch (err) {\n        const reason = messageOf(err);\n        throw new WebGpuGraphError(\n            \"E_NO_WEBGPU\",\n            `the webgpu (Dawn) native module did not load: ${reason}; ${INSTALL_HINT}`,\n            { reason, hint: INSTALL_HINT },\n        );\n    }\n    if (!isDawnModule(loaded)) {\n        const reason = \"the webgpu module exports no create() function\";\n        throw new WebGpuGraphError(\"E_NO_WEBGPU\", `${reason}; ${INSTALL_HINT}`, { reason, hint: INSTALL_HINT });\n    }\n    if (options?.installGlobals !== false && typeof loaded.globals === \"object\" && loaded.globals !== null) {\n        Object.assign(globalThis, loaded.globals);\n    }\n    let gpu: GPU;\n    try {\n        gpu = loaded.create(dawnFlags(options));\n    } catch (err) {\n        const reason = `dawn.create() threw: ${messageOf(err)}`;\n        throw new WebGpuGraphError(\"E_NO_WEBGPU\", `${reason}; ${INSTALL_HINT}`, { reason, hint: INSTALL_HINT });\n    }\n    return new DawnHandle(gpu);\n}\n\n/**\n * The GpuContextOptions part of a NodeGpuOptions, copied key by key so the Node-only `adapter` string never\n * reaches GpuContext.create as a GPUAdapter.\n * @param options - the Node options\n * @returns the context options without gpu / adapter / device / runtime\n */\nfunction contextOptionsOf(options: NodeGpuOptions): Omit<GpuContextOptions, \"gpu\" | \"adapter\" | \"device\" | \"runtime\"> {\n    return {\n        powerPreference: options.powerPreference,\n        rejectSoftware: options.rejectSoftware,\n        limits: options.limits,\n        optionalFeatures: options.optionalFeatures,\n        requiredFeatures: options.requiredFeatures,\n        label: options.label,\n        onError: options.onError,\n        warnUnreleasedSnapshots: options.warnUnreleasedSnapshots,\n    };\n}\n\n/**\n * createNodeGpu + GpuContext.create({ gpu, runtime: \"node\", ...options }); ctx.dispose() also disposes the\n * handle, and a create() failure disposes it before rethrowing. The handle is dropped once `ctx.lost` has\n * settled, never before: under webgpu@0.4.0 a GPU object collected while the device it created is still\n * tearing down (its lost / work-done callbacks in flight) crashes or deadlocks the process (PLAN DECISION,\n * P1-T1; measured with tmp/p1t1/gc-race2.mjs), and device.destroy() reports the loss right away.\n * @param options - the Node options\n * @returns the context\n */\nexport async function createNodeGpuContext(options?: NodeGpuOptions): Promise<GpuContext> {\n    const handle = await createNodeGpu(options);\n    let ctx: GpuContext;\n    try {\n        ctx = await GpuContext.create({ ...contextOptionsOf(options ?? {}), gpu: handle.gpu, runtime: \"node\" });\n    } catch (err) {\n        handle.dispose();\n        throw err;\n    }\n    const { lost } = ctx;\n    ctx.attachDisposer(() => {\n        void lost.then(() => {\n            handle.dispose();\n        });\n    });\n    return ctx;\n}\n\n/**\n * createNodeGpu + GpuContext.probe + dispose; never throws (a load failure is { code: \"E_NO_WEBGPU\" }).\n * @param options - the Node options\n * @returns the probe result\n */\nexport async function probeNodeWebGpu(options?: NodeGpuOptions): Promise<ProbeResult> {\n    let handle: NodeGpuHandle;\n    try {\n        handle = await createNodeGpu(options);\n    } catch (err) {\n        return { ok: false, code: \"E_NO_WEBGPU\", reason: messageOf(err), adapter: null, summary: null };\n    }\n    try {\n        return await GpuContext.probe({\n            gpu: handle.gpu,\n            powerPreference: options?.powerPreference ?? \"high-performance\",\n            rejectSoftware: options?.rejectSoftware,\n        });\n    } finally {\n        handle.dispose();\n    }\n}\n"],"names":[],"mappings":"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"}

package/dist/src/accelerator.d.ts

@@ -0,0 +1,26 @@
+/**
+ * createAccelerator (spec 3.3, 9; contract 3.14): the injectable object that satisfies the CPU packages'
+ * AlgorithmAccelerator and LayoutAccelerator interfaces STRUCTURALLY (spec 9.2, 9.3; the mirrors of
+ * src/types/accelerator.ts until W1, D27). At P3 it carries `forceAtlas2`, `release` and `dispose` and nothing
+ * else: the CPU-side dispatchers (`accelerated()`, `createSimulation()`) test `acc.pageRank !== undefined` and
+ * route to the CPU when the member is absent (spec 2.4 row "method missing"), so a method the GPU does not
+ * implement must not exist here -- never a throwing stub. The algorithm members arrive one per shipped algorithm
+ * from P7; `fruchtermanReingold` / `springElectrical` with P5.
+ */
+import { type GpuContext } from "./context.js";
+import { type AcceleratorOptions, type GpuAccelerator } from "./types/accelerator.js";
+/**
+ * Spec 3.3 createAccelerator, verbatim: the object implementing AlgorithmAccelerator & LayoutAccelerator
+ * structurally; at P3 it carries forceAtlas2, release and dispose. One per call (the app creates one and injects
+ * it, spec 2.4); `kind` is "webgpu"; `options` is a frozen deep copy; `forceAtlas2(o)` is
+ * `createForceAtlas2(ctx, { ...o, ...options.layout })`, so the GPU tuning given here wins over anything the
+ * CPU-typed option object carries (spec 3.3: tuning never comes from the caller of the accelerator method);
+ * `release(s)` is `ctx.release(s)`; `dispose()` is `ctx.dispose()`.
+ * @param ctx - the context every simulation the accelerator creates runs on
+ * @param options - GPU-only defaults inherited by every simulation (`layout`) and, from P9, the algorithm defaults
+ * @returns the injectable accelerator
+ * @throws E_DISPOSED / E_DEVICE_LOST from `ctx.assertReady()` (here and inside `forceAtlas2()`); `forceAtlas2()`
+ *   also throws what createForceAtlas2 throws (E_UNSUPPORTED for `nodeSize`, E_INVALID_ARGUMENT for a bad range)
+ */
+export declare function createAccelerator(ctx: GpuContext, options?: AcceleratorOptions): GpuAccelerator;
+//# sourceMappingURL=accelerator.d.ts.map

package/dist/src/accelerator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accelerator.d.ts","sourceRoot":"","sources":["../../src/accelerator.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C,OAAO,EAAE,KAAK,kBAAkB,EAAE,KAAK,cAAc,EAAE,MAAM,wBAAwB,CAAC;AA2DtF;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,cAAc,CA8B/F"}

package/dist/src/accelerator.js

@@ -0,0 +1,101 @@
+/**
+ * createAccelerator (spec 3.3, 9; contract 3.14): the injectable object that satisfies the CPU packages'
+ * AlgorithmAccelerator and LayoutAccelerator interfaces STRUCTURALLY (spec 9.2, 9.3; the mirrors of
+ * src/types/accelerator.ts until W1, D27). At P3 it carries `forceAtlas2`, `release` and `dispose` and nothing
+ * else: the CPU-side dispatchers (`accelerated()`, `createSimulation()`) test `acc.pageRank !== undefined` and
+ * route to the CPU when the member is absent (spec 2.4 row "method missing"), so a method the GPU does not
+ * implement must not exist here -- never a throwing stub. The algorithm members arrive one per shipped algorithm
+ * from P7; `fruchtermanReingold` / `springElectrical` with P5.
+ */
+import { createForceAtlas2 } from "./layouts/forceatlas2.js";
+/**
+ * Frozen copy of the betweenness defaults; `sources` is copied into a fresh frozen array so a later mutation of
+ * the caller's list is never seen by the accelerator.
+ * @param defaults - the caller's record
+ * @returns the frozen copy
+ */
+function copyBetweenness(defaults) {
+    const copy = { ...defaults };
+    if (defaults.sources !== undefined) {
+        copy.sources = Object.freeze([...defaults.sources]);
+    }
+    return Object.freeze(copy);
+}
+/**
+ * Frozen copy of the algorithms record, one level deeper for `betweenness`.
+ * @param algorithms - the caller's record
+ * @returns the frozen copy
+ */
+function copyAlgorithms(algorithms) {
+    const copy = { ...algorithms };
+    if (algorithms.betweenness !== undefined) {
+        copy.betweenness = copyBetweenness(algorithms.betweenness);
+    }
+    return Object.freeze(copy);
+}
+/**
+ * The frozen deep copy of the accelerator options (spec 3.3 GpuAccelerator.options: "the tuning defaults given
+ * to createAccelerator; frozen"; contract 3.14): the record, its `layout` tuning, its `algorithms` record, the
+ * `betweenness` record and the `sources` list are each fresh frozen objects, so neither the caller's later edits
+ * nor a consumer's writes can change what the accelerator's simulations inherit.
+ * @param options - the caller's options, or undefined
+ * @returns the frozen copy (an empty frozen record when nothing was given)
+ */
+function freezeOptions(options) {
+    if (options === undefined) {
+        return Object.freeze({});
+    }
+    const copy = { ...options };
+    if (options.layout !== undefined) {
+        copy.layout = Object.freeze({ ...options.layout });
+    }
+    if (options.algorithms !== undefined) {
+        copy.algorithms = copyAlgorithms(options.algorithms);
+    }
+    return Object.freeze(copy);
+}
+/**
+ * Spec 3.3 createAccelerator, verbatim: the object implementing AlgorithmAccelerator & LayoutAccelerator
+ * structurally; at P3 it carries forceAtlas2, release and dispose. One per call (the app creates one and injects
+ * it, spec 2.4); `kind` is "webgpu"; `options` is a frozen deep copy; `forceAtlas2(o)` is
+ * `createForceAtlas2(ctx, { ...o, ...options.layout })`, so the GPU tuning given here wins over anything the
+ * CPU-typed option object carries (spec 3.3: tuning never comes from the caller of the accelerator method);
+ * `release(s)` is `ctx.release(s)`; `dispose()` is `ctx.dispose()`.
+ * @param ctx - the context every simulation the accelerator creates runs on
+ * @param options - GPU-only defaults inherited by every simulation (`layout`) and, from P9, the algorithm defaults
+ * @returns the injectable accelerator
+ * @throws E_DISPOSED / E_DEVICE_LOST from `ctx.assertReady()` (here and inside `forceAtlas2()`); `forceAtlas2()`
+ *   also throws what createForceAtlas2 throws (E_UNSUPPORTED for `nodeSize`, E_INVALID_ARGUMENT for a bad range)
+ */
+export 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();
+        },
+    };
+}
+//# sourceMappingURL=accelerator.js.map

package/dist/src/accelerator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"accelerator.js","sourceRoot":"","sources":["../../src/accelerator.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAW7D;;;;;GAKG;AACH,SAAS,eAAe,CAAC,QAA6B;IAClD,MAAM,IAAI,GAAwE,EAAE,GAAG,QAAQ,EAAE,CAAC;IAClG,IAAI,QAAQ,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QACjC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;IACxD,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC/B,CAAC;AAED;;;;GAIG;AACH,SAAS,cAAc,CAAC,UAA6B;IACjD,MAAM,IAAI,GAAsD,EAAE,GAAG,UAAU,EAAE,CAAC;IAClF,IAAI,UAAU,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QACvC,IAAI,CAAC,WAAW,GAAG,eAAe,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;IAC/D,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC/B,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,aAAa,CAAC,OAAuC;IAC1D,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC7B,CAAC;IACD,MAAM,IAAI,GAAyF,EAAE,GAAG,OAAO,EAAE,CAAC;IAClH,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC/B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACvD,CAAC;IACD,IAAI,OAAO,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;QACnC,IAAI,CAAC,UAAU,GAAG,cAAc,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IACzD,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC/B,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAe,EAAE,OAA4B;IAC3E,GAAG,CAAC,WAAW,EAAE,CAAC;IAClB,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IACtC,OAAO;QACH,IAAI,EAAE,QAAQ;QACd,GAAG;QACH,OAAO,EAAE,MAAM;QACf;;;;WAIG;QACH,WAAW,CAAC,CAAsB;YAC9B,GAAG,CAAC,WAAW,EAAE,CAAC;YAClB,OAAO,iBAAiB,CAAC,GAAG,EAAE,EAAE,GAAG,CAAC,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;QAC9D,CAAC;QACD;;;WAGG;QACH,OAAO,CAAC,CAAgB;YACpB,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QACnB,CAAC;QACD;;WAEG;QACH,OAAO;YACH,GAAG,CAAC,OAAO,EAAE,CAAC;QAClB,CAAC;KACJ,CAAC;AACN,CAAC"}

package/dist/src/algorithms/degree.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `degree(ctx, s)` -- the walking-skeleton algorithm, kept public as a diagnostic (spec 3.3, 11.5): the out-degree of
+ * every node computed on the device by the row-walking `degree` kernel (4.5) over the resident core of the snapshot,
+ * with the group-0 dummy-binding pattern of spec 3.5 (`colIdx` in the `weights` slot when the snapshot is unweighted,
+ * `rowPtr` in the `perm` slot because P1-P3 pass no row permutation, so `USE_PERM` is false). The result equals
+ * `snapshot.outDegree()`; the point of the kernel is to prove the upload, bind, dispatch and readback path end to end
+ * on every adapter (bitwise identical across adapters, spec 11.5), not to be faster than the CPU (the README says
+ * so).
+ *
+ * Contract (3.12): `ctx.assertReady()` first; `nodeCount === 0` returns an empty `Uint32Array` (or `dest`) with no
+ * GPU work (spec 5.6: there is no work, which is not a fallback); an already-aborted `signal` is `E_ABORTED` before
+ * any work; `dest` must be a `Uint32Array` of length n over an `ArrayBuffer`; a windowed core is `E_TOO_LARGE
+ * { path: "windowed", algorithm: "degree" }` until P4 executes windows -- `residency.core()` (3.8) throws that error
+ * itself with `algorithm: null` before it would ever return a windowed `CoreBinding`, so `degree` catches it and
+ * re-throws the same error with `algorithm: "degree"` (the 3.12 detail) instead of testing `core.plan`, which never
+ * observes "windowed" in P1-P3; `arcCount === 0` skips the dispatch (only `rowPtr` is resident)
+ * and the result is zeros; otherwise ONE dispatch over rows [0, n) with `accumulate = 0` (every row is written, so no
+ * fill precedes it), a readback into the result, `onProgress(1, 1)`, and the scratch returned in a finally. Two runs
+ * are bitwise identical (spec 11.9 item 4).
+ */
+import { type GraphSnapshot, type U32 } from "@graphty/graph-format";
+import { type GpuContext } from "../context.js";
+import { type GpuRunOptions } from "../types/run.js";
+/**
+ * The walking-skeleton kernel, kept public as a diagnostic (spec 3.3): out-degree per node through the row-walking
+ * gather with the USE_PERM dummy pattern; equals snapshot.outDegree().
+ * @param ctx - the context whose device runs the kernel
+ * @param s - the snapshot (uploaded through ctx.residency, or found there)
+ * @param options - dest / signal / onProgress (spec 3.3). PLAN DECISION: spelled `?: GpuRunOptions` rather than the
+ *   contract's `?: GpuRunOptions | undefined` because the root ESLint rule no-duplicate-type-constituents rejects the
+ *   explicit undefined on an optional parameter (the call signature is identical; P1-T3 made the same choice).
+ * @returns the out-degree of every node, index-aligned (`dest` itself when given)
+ */
+export declare function degree(ctx: GpuContext, s: GraphSnapshot, options?: GpuRunOptions): Promise<U32>;
+//# sourceMappingURL=degree.d.ts.map

package/dist/src/algorithms/degree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"degree.d.ts","sourceRoot":"","sources":["../../../src/algorithms/degree.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,GAAG,EAAE,MAAM,uBAAuB,CAAC;AAErE,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAOhD,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAiDrD;;;;;;;;;GASG;AACH,wBAAsB,MAAM,CAAC,GAAG,EAAE,UAAU,EAAE,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,CAoDrG"}

package/dist/src/algorithms/degree.js

@@ -0,0 +1,119 @@
+/**
+ * `degree(ctx, s)` -- the walking-skeleton algorithm, kept public as a diagnostic (spec 3.3, 11.5): the out-degree of
+ * every node computed on the device by the row-walking `degree` kernel (4.5) over the resident core of the snapshot,
+ * with the group-0 dummy-binding pattern of spec 3.5 (`colIdx` in the `weights` slot when the snapshot is unweighted,
+ * `rowPtr` in the `perm` slot because P1-P3 pass no row permutation, so `USE_PERM` is false). The result equals
+ * `snapshot.outDegree()`; the point of the kernel is to prove the upload, bind, dispatch and readback path end to end
+ * on every adapter (bitwise identical across adapters, spec 11.5), not to be faster than the CPU (the README says
+ * so).
+ *
+ * Contract (3.12): `ctx.assertReady()` first; `nodeCount === 0` returns an empty `Uint32Array` (or `dest`) with no
+ * GPU work (spec 5.6: there is no work, which is not a fallback); an already-aborted `signal` is `E_ABORTED` before
+ * any work; `dest` must be a `Uint32Array` of length n over an `ArrayBuffer`; a windowed core is `E_TOO_LARGE
+ * { path: "windowed", algorithm: "degree" }` until P4 executes windows -- `residency.core()` (3.8) throws that error
+ * itself with `algorithm: null` before it would ever return a windowed `CoreBinding`, so `degree` catches it and
+ * re-throws the same error with `algorithm: "degree"` (the 3.12 detail) instead of testing `core.plan`, which never
+ * observes "windowed" in P1-P3; `arcCount === 0` skips the dispatch (only `rowPtr` is resident)
+ * and the result is zeros; otherwise ONE dispatch over rows [0, n) with `accumulate = 0` (every row is written, so no
+ * fill precedes it), a readback into the result, `onProgress(1, 1)`, and the scratch returned in a finally. Two runs
+ * are bitwise identical (spec 11.9 item 4).
+ */
+import { BufferUsage } from "../device/webgpu-constants.js";
+import { isWebGpuGraphError, WebGpuGraphError } from "../errors.js";
+import { plan1d } from "../kernel/dispatch.js";
+import { graphBindings, graphOverrides, kernelSpec, RANGE_PARAMS } from "../kernels.js";
+/**
+ * Validates `options.dest` for a result of `n` elements.
+ * @param dest - the caller's destination array, if any
+ * @param n - the node count
+ * @returns the destination as a U32, or null when none was given
+ */
+function checkDest(dest, n) {
+    if (dest === undefined) {
+        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`,
+    });
+}
+/**
+ * Uploads (or finds) the core through the residency; a windowed plan, which the residency reports as `E_TOO_LARGE
+ * { path: "windowed", algorithm: null }` (3.8), is re-thrown with `algorithm: "degree"` (3.12) and its other details
+ * (`needed`, `limit`, `path`) kept. Every other error passes through untouched.
+ * @param ctx - the context whose residency holds the core
+ * @param s - the snapshot
+ * @returns the resident core binding (arena or perArray)
+ */
+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;
+    }
+}
+/**
+ * The walking-skeleton kernel, kept public as a diagnostic (spec 3.3): out-degree per node through the row-walking
+ * gather with the USE_PERM dummy pattern; equals snapshot.outDegree().
+ * @param ctx - the context whose device runs the kernel
+ * @param s - the snapshot (uploaded through ctx.residency, or found there)
+ * @param options - dest / signal / onProgress (spec 3.3). PLAN DECISION: spelled `?: GpuRunOptions` rather than the
+ *   contract's `?: GpuRunOptions | undefined` because the root ESLint rule no-duplicate-type-constituents rejects the
+ *   explicit undefined on an optional parameter (the call signature is identical; P1-T3 made the same choice).
+ * @returns the out-degree of every node, index-aligned (`dest` itself when given)
+ */
+export 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 ?? undefined);
+        ctx.assertReady();
+        options?.onProgress?.(1, 1);
+        return dest ?? new Uint32Array(result);
+    }
+    finally {
+        ctx.pool.release(params);
+        ctx.pool.release(out);
+    }
+}
+//# sourceMappingURL=degree.js.map

package/dist/src/algorithms/degree.js.map

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

package/dist/src/browser/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The ./browser entry (spec 2.1, 2.3, 3.4; contract 3.6): the only directory of the package allowed to read
+ * navigator.gpu. probeBrowserWebGpu never throws; requestGpuContext tags the context runtime "browser".
+ */
+/// <reference types="@webgpu/types" preserve="true" />
+import { GpuContext } from "../context.js";
+import type { GpuContextOptions, ProbeResult } from "../types/context.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">;
+/**
+ * navigator.gpu absent -> { ok: false, code: "E_NO_WEBGPU" }; else GpuContext.probe. Never throws.
+ * @param options - the power preference and the software policy
+ * @returns the probe result
+ */
+export declare function probeBrowserWebGpu(options?: BrowserGpuOptions): Promise<ProbeResult>;
+/**
+ * GpuContext.create({ gpu: navigator.gpu, powerPreference: "high-performance", runtime: "browser", ...options });
+ * pass `{ adapter: probe.adapter }` to reuse the probed adapter; create() honours rejectSoftware.
+ * @param options - see BrowserGpuOptions
+ * @returns the context
+ */
+export declare function requestGpuContext(options?: BrowserGpuOptions): Promise<GpuContext>;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/browser/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/browser/index.ts"],"names":[],"mappings":"AACA;;;GAGG;;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAE1E,mLAAmL;AACnL,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAAC,iBAAiB,EAAE,KAAK,GAAG,QAAQ,GAAG,SAAS,CAAC,CAAC;AAetF;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CAMpF;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,UAAU,CAAC,CAWlF"}

package/dist/src/browser/index.js

@@ -0,0 +1,48 @@
+/// <reference types="@webgpu/types" preserve="true" />
+/**
+ * The ./browser entry (spec 2.1, 2.3, 3.4; contract 3.6): the only directory of the package allowed to read
+ * navigator.gpu. probeBrowserWebGpu never throws; requestGpuContext tags the context runtime "browser".
+ */
+import { GpuContext } from "../context.js";
+import { WebGpuGraphError } from "../errors.js";
+/**
+ * navigator.gpu, or undefined when the runtime has no navigator or no WebGPU (Node 22 has a navigator
+ * without gpu; browsers without WebGPU have navigator.gpu undefined).
+ * @returns the GPU object or undefined
+ */
+function navigatorGpu() {
+    if (typeof navigator === "undefined") {
+        return undefined;
+    }
+    const candidate = navigator;
+    return candidate.gpu;
+}
+/**
+ * navigator.gpu absent -> { ok: false, code: "E_NO_WEBGPU" }; else GpuContext.probe. Never throws.
+ * @param options - the power preference and the software policy
+ * @returns the probe result
+ */
+export function probeBrowserWebGpu(options) {
+    return GpuContext.probe({
+        gpu: navigatorGpu(),
+        powerPreference: options?.powerPreference ?? "high-performance",
+        rejectSoftware: options?.rejectSoftware,
+    });
+}
+/**
+ * GpuContext.create({ gpu: navigator.gpu, powerPreference: "high-performance", runtime: "browser", ...options });
+ * pass `{ adapter: probe.adapter }` to reuse the probed adapter; create() honours rejectSoftware.
+ * @param options - see BrowserGpuOptions
+ * @returns the context
+ */
+export function requestGpuContext(options) {
+    const gpu = navigatorGpu();
+    if (gpu === undefined && options?.adapter === undefined) {
+        return Promise.reject(new WebGpuGraphError("E_NO_WEBGPU", "navigator.gpu is undefined: this browser or context has no WebGPU", {
+            reason: "navigator.gpu is undefined",
+            hint: "WebGPU needs a supporting browser and a secure context (https or localhost)",
+        }));
+    }
+    return GpuContext.create({ powerPreference: "high-performance", ...options, gpu, runtime: "browser" });
+}
+//# sourceMappingURL=index.js.map

package/dist/src/browser/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/browser/index.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAMhD;;;;GAIG;AACH,SAAS,YAAY;IACjB,IAAI,OAAO,SAAS,KAAK,WAAW,EAAE,CAAC;QACnC,OAAO,SAAS,CAAC;IACrB,CAAC;IACD,MAAM,SAAS,GAAuC,SAAS,CAAC;IAChE,OAAO,SAAS,CAAC,GAAG,CAAC;AACzB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAA2B;IAC1D,OAAO,UAAU,CAAC,KAAK,CAAC;QACpB,GAAG,EAAE,YAAY,EAAE;QACnB,eAAe,EAAE,OAAO,EAAE,eAAe,IAAI,kBAAkB;QAC/D,cAAc,EAAE,OAAO,EAAE,cAAc;KAC1C,CAAC,CAAC;AACP,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAA2B;IACzD,MAAM,GAAG,GAAG,YAAY,EAAE,CAAC;IAC3B,IAAI,GAAG,KAAK,SAAS,IAAI,OAAO,EAAE,OAAO,KAAK,SAAS,EAAE,CAAC;QACtD,OAAO,OAAO,CAAC,MAAM,CACjB,IAAI,gBAAgB,CAAC,aAAa,EAAE,mEAAmE,EAAE;YACrG,MAAM,EAAE,4BAA4B;YACpC,IAAI,EAAE,6EAA6E;SACtF,CAAC,CACL,CAAC;IACN,CAAC;IACD,OAAO,UAAU,CAAC,MAAM,CAAC,EAAE,eAAe,EAAE,kBAAkB,EAAE,GAAG,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC;AAC3G,CAAC"}