@graphty/webgpu-graph-algorithms 0.0.0 → 0.2.0

package/dist/src/kernel/uniform-ring.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The UniformRing of spec 5.3: one UNIFORM buffer holding UNIFORM_SLOT_BYTES-stride slots for the
+ * per-iteration params of a batch. A batch reserves k contiguous slots, writes their values into the
+ * host shadow, flushes them with ONE queue.writeBuffer and records k dispatches that select their slot
+ * through a dynamic offset -- no per-iteration writeBuffer and no host round trip. The stride is 256
+ * because minUniformBufferOffsetAlignment is 256 on every runtime the package targets (the Dawn-node
+ * ADAPTER advertises 64, which the package never requests; spec 2.6).
+ */
+import type { AllocationTracker } from "../device/error-scope.js";
+import type { Binding } from "../types/memory.js";
+import type { UniformBlock, UniformValues } from "./struct-block.js";
+/** One UNIFORM buffer with UNIFORM_SLOT_BYTES-stride slots for the per-iteration params of a batch (spec 5.3). */
+export declare class UniformRing {
+    /** Number of slots. */
+    readonly slots: number;
+    private readonly device;
+    private readonly allocator;
+    private readonly buffer;
+    private readonly label;
+    private readonly shadow;
+    private readonly view;
+    private next;
+    private dirtyLo;
+    private dirtyHi;
+    private destroyed;
+    /**
+     * Creates the ring buffer (`slots x UNIFORM_SLOT_BYTES` bytes, UNIFORM | COPY_DST) through the allocator.
+     * @param device - the device the buffer belongs to
+     * @param allocator - the context's OOM-scoped allocator (the buffer is destroyed through it)
+     * @param slots - number of slots; E_INVALID_ARGUMENT unless a positive integer
+     * @param label - the buffer label
+     */
+    constructor(device: GPUDevice, allocator: AllocationTracker, slots: number, label: string);
+    /**
+     * The whole-buffer binding a kernel binds once (size = the block's byteLength; the slot is the dynamic offset).
+     * @param block - the params block the kernel declares for this binding
+     * @returns the binding at offset 0 of the ring buffer
+     */
+    binding(block: UniformBlock): Binding;
+    /**
+     * Byte offset of a slot (the dynamic offset a dispatch passes for it).
+     * @param slot - a slot index in [0, slots)
+     * @returns slot x UNIFORM_SLOT_BYTES
+     */
+    offsetOf(slot: number): number;
+    /**
+     * Reserves `count` contiguous slots for a batch, wrapping to 0 when the tail is too short; E_INVALID_ARGUMENT when count > slots.
+     * @param count - slots needed, in [1, slots]
+     * @returns the first slot of the reservation
+     */
+    reserve(count: number): number;
+    /**
+     * Writes one block's values into a slot of the host shadow; `flush()` sends the dirty range with one writeBuffer.
+     * @param slot - the slot to fill
+     * @param block - the block whose layout the bytes follow
+     * @param values - the field values (a missing field is written as 0 by the block)
+     */
+    write(slot: number, block: UniformBlock, values: UniformValues): void;
+    /**
+     * queue.writeBuffer of the dirty slots (called by the batch driver before submit): one call covering
+     * [lowest dirty slot, highest dirty slot]; nothing when no slot is dirty.
+     */
+    flush(): void;
+    /** Destroys the buffer (through the allocator); idempotent. */
+    destroy(): void;
+    private assertLive;
+    private checkSlot;
+    private assertFits;
+}
+//# sourceMappingURL=uniform-ring.d.ts.map

package/dist/src/kernel/uniform-ring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uniform-ring.d.ts","sourceRoot":"","sources":["../../../src/kernel/uniform-ring.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAGlE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAErE,kHAAkH;AAClH,qBAAa,WAAW;IACpB,uBAAuB;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoB;IAC9C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAW;IAChC,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,OAAO,CAAM;IACrB,OAAO,CAAC,OAAO,CAAM;IACrB,OAAO,CAAC,SAAS,CAAS;IAE1B;;;;;;OAMG;gBACS,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,iBAAiB,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;IAyBzF;;;;OAIG;IACH,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO;IAMrC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAK9B;;;;OAIG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAqB9B;;;;;OAKG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,GAAG,IAAI;IAYrE;;;OAGG;IACH,KAAK,IAAI,IAAI;IAYb,+DAA+D;IAC/D,OAAO,IAAI,IAAI;IAQf,OAAO,CAAC,UAAU;IAMlB,OAAO,CAAC,SAAS;IAejB,OAAO,CAAC,UAAU;CASrB"}

package/dist/src/kernel/uniform-ring.js

@@ -0,0 +1,146 @@
+/**
+ * The UniformRing of spec 5.3: one UNIFORM buffer holding UNIFORM_SLOT_BYTES-stride slots for the
+ * per-iteration params of a batch. A batch reserves k contiguous slots, writes their values into the
+ * host shadow, flushes them with ONE queue.writeBuffer and records k dispatches that select their slot
+ * through a dynamic offset -- no per-iteration writeBuffer and no host round trip. The stride is 256
+ * because minUniformBufferOffsetAlignment is 256 on every runtime the package targets (the Dawn-node
+ * ADAPTER advertises 64, which the package never requests; spec 2.6).
+ */
+import { UNIFORM_SLOT_BYTES } from "../constants.js";
+import { BufferUsage } from "../device/webgpu-constants.js";
+import { WebGpuGraphError } from "../errors.js";
+/** One UNIFORM buffer with UNIFORM_SLOT_BYTES-stride slots for the per-iteration params of a batch (spec 5.3). */
+export class UniformRing {
+    /**
+     * Creates the ring buffer (`slots x UNIFORM_SLOT_BYTES` bytes, UNIFORM | COPY_DST) through the allocator.
+     * @param device - the device the buffer belongs to
+     * @param allocator - the context's OOM-scoped allocator (the buffer is destroyed through it)
+     * @param slots - number of slots; E_INVALID_ARGUMENT unless a positive integer
+     * @param label - the buffer label
+     */
+    constructor(device, allocator, slots, label) {
+        this.next = 0;
+        this.dirtyLo = -1;
+        this.dirtyHi = -1;
+        this.destroyed = false;
+        if (!Number.isInteger(slots) || slots < 1) {
+            throw new WebGpuGraphError("E_INVALID_ARGUMENT", `UniformRing "${label}": slots must be a positive integer, got ${slots}`, {
+                argument: "slots",
+                value: slots,
+                expected: "an integer >= 1",
+            });
+        }
+        this.device = device;
+        this.allocator = allocator;
+        this.slots = slots;
+        this.label = label;
+        this.shadow = new ArrayBuffer(slots * UNIFORM_SLOT_BYTES);
+        this.view = new DataView(this.shadow);
+        this.buffer = allocator.createBuffer({
+            label,
+            size: slots * UNIFORM_SLOT_BYTES,
+            usage: BufferUsage.UNIFORM | BufferUsage.COPY_DST,
+        });
+    }
+    /**
+     * The whole-buffer binding a kernel binds once (size = the block's byteLength; the slot is the dynamic offset).
+     * @param block - the params block the kernel declares for this binding
+     * @returns the binding at offset 0 of the ring buffer
+     */
+    binding(block) {
+        this.assertLive();
+        this.assertFits(block);
+        return { buffer: this.buffer, offset: 0, size: block.byteLength, window: null };
+    }
+    /**
+     * Byte offset of a slot (the dynamic offset a dispatch passes for it).
+     * @param slot - a slot index in [0, slots)
+     * @returns slot x UNIFORM_SLOT_BYTES
+     */
+    offsetOf(slot) {
+        this.checkSlot(slot);
+        return slot * UNIFORM_SLOT_BYTES;
+    }
+    /**
+     * Reserves `count` contiguous slots for a batch, wrapping to 0 when the tail is too short; E_INVALID_ARGUMENT when count > slots.
+     * @param count - slots needed, in [1, slots]
+     * @returns the first slot of the reservation
+     */
+    reserve(count) {
+        this.assertLive();
+        if (!Number.isInteger(count) || count < 1 || count > this.slots) {
+            throw new WebGpuGraphError("E_INVALID_ARGUMENT", `UniformRing "${this.label}": cannot reserve ${count} of ${this.slots} slots`, {
+                argument: "count",
+                value: count,
+                expected: `an integer in [1, ${this.slots}]`,
+            });
+        }
+        if (this.next + count > this.slots) {
+            this.next = 0;
+        }
+        const first = this.next;
+        this.next += count;
+        return first;
+    }
+    /**
+     * Writes one block's values into a slot of the host shadow; `flush()` sends the dirty range with one writeBuffer.
+     * @param slot - the slot to fill
+     * @param block - the block whose layout the bytes follow
+     * @param values - the field values (a missing field is written as 0 by the block)
+     */
+    write(slot, block, values) {
+        this.checkSlot(slot);
+        this.assertFits(block);
+        block.write(this.view, values, slot * UNIFORM_SLOT_BYTES);
+        if (this.dirtyLo < 0 || slot < this.dirtyLo) {
+            this.dirtyLo = slot;
+        }
+        if (slot > this.dirtyHi) {
+            this.dirtyHi = slot;
+        }
+    }
+    /**
+     * queue.writeBuffer of the dirty slots (called by the batch driver before submit): one call covering
+     * [lowest dirty slot, highest dirty slot]; nothing when no slot is dirty.
+     */
+    flush() {
+        this.assertLive();
+        if (this.dirtyLo < 0) {
+            return;
+        }
+        const begin = this.dirtyLo * UNIFORM_SLOT_BYTES;
+        const end = (this.dirtyHi + 1) * UNIFORM_SLOT_BYTES;
+        this.device.queue.writeBuffer(this.buffer, begin, this.shadow, begin, end - begin);
+        this.dirtyLo = -1;
+        this.dirtyHi = -1;
+    }
+    /** Destroys the buffer (through the allocator); idempotent. */
+    destroy() {
+        if (this.destroyed) {
+            return;
+        }
+        this.destroyed = true;
+        this.allocator.destroy(this.buffer);
+    }
+    assertLive() {
+        if (this.destroyed) {
+            throw new WebGpuGraphError("E_DISPOSED", `UniformRing "${this.label}" is destroyed`, { label: this.label });
+        }
+    }
+    checkSlot(slot) {
+        this.assertLive();
+        if (!Number.isInteger(slot) || slot < 0 || slot >= this.slots) {
+            throw new WebGpuGraphError("E_INVALID_ARGUMENT", `UniformRing "${this.label}": slot ${slot} is outside [0, ${this.slots})`, {
+                argument: "slot",
+                value: slot,
+                expected: `an integer in [0, ${this.slots})`,
+            });
+        }
+    }
+    assertFits(block) {
+        if (block.byteLength > UNIFORM_SLOT_BYTES) {
+            throw new WebGpuGraphError("E_INVALID_ARGUMENT", `UniformRing "${this.label}": block ${block.name} is ${block.byteLength} bytes, a slot holds ${UNIFORM_SLOT_BYTES}`, { argument: "block", value: block.name, expected: `byteLength <= ${UNIFORM_SLOT_BYTES}` });
+        }
+    }
+}
+//# sourceMappingURL=uniform-ring.js.map

package/dist/src/kernel/uniform-ring.js.map

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

package/dist/src/kernel/wgsl.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The WGSL composer (spec 3.5; contract 3.9, 4.2): ONE declaration per module (`WgslModuleSpec`) generates
+ * everything the host and the shader must agree on -- the `@group / @binding` block, the `override` lines, the
+ * struct texts, the explicit bind-group layouts and the bind() record keys -- by string concatenation in the fixed
+ * order of contract 4.2. Every disagreement that would otherwise be a GPUPipelineError on the first device that
+ * creates the variant is a compose-time `E_SHADER_COMPILE { stage: "compose" }` on every device.
+ *
+ * PLAN DECISION: this file imports `workgroupSizeFor` from `../device/caps.js` (one copy of the WG rule) and
+ * `ShaderStage` from `../device/webgpu-constants.js` (spec 2.1 rule 1: the core never reads the `GPUShaderStage`
+ * global at module top level); `../constants.js` is not imported because every constant the composer emits reaches
+ * it through `./prelude.js`. The layer rule (contract 2.4: device < context < memory < kernel) allows both edges.
+ */
+import { type PlanCaps } from "../types/context.js";
+import { type UniformBlock } from "./struct-block.js";
+/** One storage or uniform binding of a module (spec 3.5). `wgslType` is the element / struct type text ("array<u32>", "array<vec4f>", "Fa2State"). */
+export interface BindingDecl {
+    readonly group: 0 | 1 | 2 | 3;
+    readonly binding: number;
+    readonly name: string;
+    readonly kind: "storage" | "storage-ro" | "uniform";
+    readonly wgslType: string;
+}
+/** One module-specific override (spec 3.5); the five standard ones (WG, USE_PERM, HAS_WEIGHTS, SUBGROUP_MIN, SUBGROUP_MAX) come from the prelude and are never listed here. */
+export interface OverrideDecl {
+    readonly name: string;
+    readonly type: "u32" | "bool" | "f32";
+    readonly default: number | boolean;
+}
+/** Spec 3.5 WgslModuleSpec, verbatim. `needs: ["subgroups"]` means "this body calls a wg_reduce_* helper": the composer splices the subgroup helper block when the device has the feature and the workgroup-memory twin otherwise. */
+export interface WgslModuleSpec {
+    readonly id: string;
+    readonly body: string;
+    readonly bindings: readonly BindingDecl[];
+    readonly overrideDecls: readonly OverrideDecl[];
+    readonly overrides: Readonly<Record<string, number | boolean>>;
+    readonly needs: readonly "subgroups"[];
+    readonly uniforms: readonly UniformBlock[];
+    readonly snippets?: Readonly<Record<string, string>> | undefined;
+}
+/** The names the prelude declares as overrides; spec.overrides may set them without an OverrideDecl. */
+export declare const STANDARD_OVERRIDES: readonly ["WG", "USE_PERM", "HAS_WEIGHTS", "SUBGROUP_MIN", "SUBGROUP_MAX"];
+/** What composeWgsl returns: the text, the body's first line in it (for compilation-info formatting), the effective overrides (WG, SUBGROUP_MIN, SUBGROUP_MAX filled) and the features to enable. */
+export interface ComposedModule {
+    readonly id: string;
+    readonly code: string;
+    readonly bodyLine: number;
+    readonly overrides: Readonly<Record<string, number | boolean>>;
+    /**
+     * The subset of `overrides` the composed code REFERENCES outside its own declaration -- what the pipeline
+     * descriptor's `constants` carries. WebKit (Safari) fails pipeline creation with "Compute library failed
+     * creation" when a constant is supplied for an override the entry point never reads (HAS_WEIGHTS in `degree`,
+     * TIER in the thread-per-row tiers); Dawn tolerates it. The cache key still uses `overrides` (contract 3.9).
+     */
+    readonly constants: Readonly<Record<string, number | boolean>>;
+    readonly entryPoint: string;
+    readonly subgroups: boolean;
+}
+/**
+ * The entry-point name of a body: the identifier after `fn` on the line following `@compute` (every body has exactly one entry point).
+ * PLAN DECISION: a body without exactly one `@compute` entry point is `E_SHADER_COMPILE { stage: "compose", slot: "entry" }`.
+ * @param body - the kernel body
+ * @returns the entry-point function name
+ */
+export declare function entryPointOf(body: string): string;
+/**
+ * The bind-group-layout descriptors derived from spec.bindings: one per group 0..maxGroup (empty groups get an empty entry list); uniform decls carry hasDynamicOffset true (spec 5.1).
+ * PLAN DECISION: a uniform decl whose struct is one of `spec.uniforms` also carries `minBindingSize = block.byteLength`,
+ * so a wrong-size uniform binding fails at createBindGroup (synchronously, with the bind group's label in the message)
+ * instead of at the first dispatch (verified on Dawn 0.4.0: without it the error names only the pipeline).
+ * @param spec - the module
+ * @returns the descriptors in group order
+ */
+export declare function bindGroupLayoutDescriptors(spec: WgslModuleSpec): GPUBindGroupLayoutDescriptor[];
+/**
+ * The names of the bindings of one group in binding order.
+ * @param spec - the module
+ * @param group - the group index
+ * @returns the names
+ */
+export declare function bindingNames(spec: WgslModuleSpec, group: number): readonly string[];
+/**
+ * String concatenation of spec 3.5: prelude (constants, standard overrides, helpers), module overrides, struct texts, the bind declarations, then the body with snippets substituted (4.2 gives the exact emitted format).
+ * @param spec - the module
+ * @param caps - the device capabilities (WG, the subgroup sizes and the feature set)
+ * @returns the composed module
+ */
+export declare function composeWgsl(spec: WgslModuleSpec, caps: PlanCaps): ComposedModule;
+//# sourceMappingURL=wgsl.d.ts.map

package/dist/src/kernel/wgsl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wgsl.d.ts","sourceRoot":"","sources":["../../../src/kernel/wgsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AASpD,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD,sJAAsJ;AACtJ,MAAM,WAAW,WAAW;IACxB,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,YAAY,GAAG,SAAS,CAAC;IACpD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC7B;AACD,+KAA+K;AAC/K,MAAM,WAAW,YAAY;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CACtC;AACD,sOAAsO;AACtO,MAAM,WAAW,cAAc;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAC;IAC1C,QAAQ,CAAC,aAAa,EAAE,SAAS,YAAY,EAAE,CAAC;IAChD,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAC/D,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;IAC3C,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,CAAC;CACpE;AACD,wGAAwG;AACxG,eAAO,MAAM,kBAAkB,4EAA6E,CAAC;AAC7G,qMAAqM;AACrM,MAAM,WAAW,cAAc;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAC/D;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAC/D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC/B;AAiJD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAcjD;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,cAAc,GAAG,4BAA4B,EAAE,CA0B/F;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAKnF;AA8HD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,QAAQ,GAAG,cAAc,CAkDhF"}