@graphty/webgpu-graph-algorithms 0.0.0 → 0.2.0

package/dist/src/kernel/wgsl.js

@@ -0,0 +1,390 @@
+/**
+ * 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 { workgroupSizeFor } from "../device/caps.js";
+import { ShaderStage } from "../device/webgpu-constants.js";
+import { WebGpuGraphError } from "../errors.js";
+import { PRELUDE_WGSL, REDUCE_HELPER_NAMES, REDUCE_HELPERS_SUBGROUP_WGSL, REDUCE_HELPERS_WORKGROUP_WGSL, WGSL_RESERVED_WORDS, wgslF32Literal, } from "./prelude.js";
+/** The names the prelude declares as overrides; spec.overrides may set them without an OverrideDecl. */
+export const STANDARD_OVERRIDES = ["WG", "USE_PERM", "HAS_WEIGHTS", "SUBGROUP_MIN", "SUBGROUP_MAX"];
+/** The type of each standard override (the prelude's declarations). */
+const STANDARD_OVERRIDE_TYPES = Object.freeze({
+    WG: "u32",
+    USE_PERM: "bool",
+    HAS_WEIGHTS: "bool",
+    SUBGROUP_MIN: "u32",
+    SUBGROUP_MAX: "u32",
+});
+/** The only feature a body may need (spec 3.5). */
+const KNOWN_NEEDS = Object.freeze(["subgroups"]);
+/** The smallest legal subgroup size; the scratch of 4.3 is sized by the MINIMUM size. */
+const SUBGROUP_FLOOR = 4;
+/** Builtin WGSL element types a binding may name without a struct declaration. */
+const BUILTIN_TYPES = new Set([
+    "u32",
+    "i32",
+    "f32",
+    "f16",
+    "bool",
+    "vec2f",
+    "vec3f",
+    "vec4f",
+    "vec2u",
+    "vec3u",
+    "vec4u",
+    "vec2i",
+    "vec3i",
+    "vec4i",
+    "vec2h",
+    "vec3h",
+    "vec4h",
+]);
+const TEMPLATED_BUILTIN = /^(vec[234]|mat[234]x[234]|atomic|array)</;
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** The `var<...>` form of each binding kind (contract 4.2). */
+const ADDRESS_SPACE = Object.freeze({
+    storage: "var<storage, read_write>",
+    "storage-ro": "var<storage, read>",
+    uniform: "var<uniform>",
+});
+/** The reserved words as a set (the frozen list stays the public form). */
+const RESERVED = new Set(WGSL_RESERVED_WORDS);
+const MARKER = /\/\/@@([A-Za-z0-9_]+)@@/;
+const IDENTIFIER_TOKENS = /(?<![A-Za-z0-9_])[A-Za-z_][A-Za-z0-9_]*/g;
+const COMPUTE_ATTRIBUTE = /@compute\b/g;
+const ENTRY_FN = /\bfn\s+([A-Za-z_][A-Za-z0-9_]*)/;
+/**
+ * The compose-time error of contract 3.9.
+ * @param id - the module id
+ * @param slot - what failed (`override:<key>`, `snippet:<key>`, `marker:<name>`, `body:<text>`, `binding:<name>`, `type:<name>`, `needs:<feature>`, `helper:<name>`, `reserved:<word>`, `entry`)
+ * @param message - the human-readable reason
+ * @returns the error (thrown by the caller)
+ */
+function composeError(id, slot, message) {
+    return new WebGpuGraphError("E_SHADER_COMPILE", `${id}: ${message}`, { id, stage: "compose", slot });
+}
+/**
+ * Removes block and line comments so a word inside a comment is never taken for an identifier.
+ * @param text - WGSL text
+ * @returns the text without comments
+ */
+function stripComments(text) {
+    return text.replace(/\/\*[\s\S]*?\*\//g, " ").replace(/\/\/[^\n]*/g, "");
+}
+/**
+ * The struct a binding's element type names, or null for a builtin type.
+ * @param wgslType - the binding's type text ("array<u32>", "array<Fa2Partial>", "Fa2State")
+ * @returns the struct name or null
+ */
+function structNameOf(wgslType) {
+    const trimmed = wgslType.trim();
+    const inner = trimmed.startsWith("array<")
+        ? trimmed.slice("array<".length).replace(/\s*(,[^>]*)?>\s*$/, "")
+        : trimmed;
+    if (BUILTIN_TYPES.has(inner) || TEMPLATED_BUILTIN.test(inner)) {
+        return null;
+    }
+    return inner;
+}
+/**
+ * Checks that an override value matches its declared type.
+ * PLAN DECISION: a value of the wrong type (a number for a bool, a bool / negative / fractional for a u32) is a
+ * compose-time `E_SHADER_COMPILE { slot: "override:<name>" }` instead of a GPUPipelineError on the first device.
+ * @param id - the module id
+ * @param name - the override name
+ * @param type - the declared type
+ * @param value - the value
+ */
+function assertOverrideValue(id, name, type, value) {
+    const ok = type === "bool"
+        ? typeof value === "boolean"
+        : typeof value === "number" &&
+            Number.isFinite(value) &&
+            (type === "f32" || (Number.isInteger(value) && value >= 0));
+    if (!ok) {
+        throw composeError(id, `override:${name}`, `override ${name} (${type}) cannot take the value ${String(value)}`);
+    }
+}
+/**
+ * The WGSL literal of an override default (u32 literals carry the `u` suffix, f32 literals a decimal point, bools true / false).
+ * @param decl - the override
+ * @returns the literal text
+ */
+function overrideLiteral(decl) {
+    if (decl.type === "bool") {
+        return decl.default ? "true" : "false";
+    }
+    const value = decl.default;
+    return decl.type === "u32" ? `${value}u` : wgslF32Literal(value);
+}
+/**
+ * The `var<...>` declaration of one binding (contract 4.2).
+ * @param decl - the binding
+ * @returns the declaration line
+ */
+function bindingLine(decl) {
+    const space = ADDRESS_SPACE[decl.kind];
+    return `@group(${decl.group}) @binding(${decl.binding}) ${space} ${decl.name}: ${decl.wgslType};`;
+}
+/**
+ * The entry-point name of a body, or null when the body does not carry exactly one `@compute` attribute followed by `fn <name>`.
+ * @param body - the kernel body
+ * @returns the name or null
+ */
+function findEntryPoint(body) {
+    const stripped = stripComments(body);
+    const matches = [...stripped.matchAll(COMPUTE_ATTRIBUTE)];
+    if (matches.length !== 1 || matches[0].index === undefined) {
+        return null;
+    }
+    const fn = ENTRY_FN.exec(stripped.slice(matches[0].index));
+    return fn === null ? null : fn[1];
+}
+/**
+ * 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 function entryPointOf(body) {
+    const name = findEntryPoint(body);
+    if (name === null) {
+        throw new WebGpuGraphError("E_SHADER_COMPILE", "a body must carry exactly one @compute attribute followed by `fn <name>`", {
+            id: null,
+            stage: "compose",
+            slot: "entry",
+        });
+    }
+    return name;
+}
+/**
+ * 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 function bindGroupLayoutDescriptors(spec) {
+    const maxGroup = spec.bindings.reduce((acc, b) => Math.max(acc, b.group), -1);
+    const blocks = new Map(spec.uniforms.map((block) => [block.name, block]));
+    const descriptors = [];
+    for (let group = 0; group <= maxGroup; group++) {
+        const entries = spec.bindings
+            .filter((b) => b.group === group)
+            .sort((a, b) => a.binding - b.binding)
+            .map((b) => {
+            if (b.kind === "uniform") {
+                const block = blocks.get(b.wgslType);
+                const buffer = { type: "uniform", hasDynamicOffset: true };
+                if (block !== undefined) {
+                    buffer.minBindingSize = block.byteLength;
+                }
+                return { binding: b.binding, visibility: ShaderStage.COMPUTE, buffer };
+            }
+            return {
+                binding: b.binding,
+                visibility: ShaderStage.COMPUTE,
+                buffer: { type: b.kind === "storage" ? "storage" : "read-only-storage" },
+            };
+        });
+        descriptors.push({ entries });
+    }
+    return descriptors;
+}
+/**
+ * The names of the bindings of one group in binding order.
+ * @param spec - the module
+ * @param group - the group index
+ * @returns the names
+ */
+export function bindingNames(spec, group) {
+    return spec.bindings
+        .filter((b) => b.group === group)
+        .sort((a, b) => a.binding - b.binding)
+        .map((b) => b.name);
+}
+/**
+ * Validates `spec.needs`, `spec.overrideDecls`, `spec.overrides` and `spec.bindings` (contract 3.9's compose-time checks).
+ * PLAN DECISION: an `overrideDecls` entry that redeclares a standard override, repeats a name or names a reserved
+ * word is `E_SHADER_COMPILE { slot: "override:<name>" }` (otherwise a duplicate-declaration error on the first device).
+ * @param spec - the module
+ */
+function validateDeclarations(spec) {
+    const { id } = spec;
+    for (const need of spec.needs) {
+        if (!KNOWN_NEEDS.includes(need)) {
+            throw composeError(id, `needs:${need}`, `unknown feature "${need}" in needs`);
+        }
+    }
+    const declared = new Map();
+    for (const decl of spec.overrideDecls) {
+        if (!IDENTIFIER.test(decl.name) || RESERVED.has(decl.name)) {
+            throw composeError(id, `override:${decl.name}`, `override name "${decl.name}" is not a usable identifier`);
+        }
+        if (STANDARD_OVERRIDES.includes(decl.name) || declared.has(decl.name)) {
+            throw composeError(id, `override:${decl.name}`, `override "${decl.name}" is declared twice (the prelude declares the standard ones)`);
+        }
+        assertOverrideValue(id, decl.name, decl.type, decl.default);
+        declared.set(decl.name, decl.type);
+    }
+    for (const [key, value] of Object.entries(spec.overrides)) {
+        const standard = STANDARD_OVERRIDE_TYPES[key];
+        const type = standard ?? declared.get(key);
+        if (type === undefined) {
+            throw composeError(id, `override:${key}`, `override "${key}" is neither a standard override nor declared in overrideDecls`);
+        }
+        assertOverrideValue(id, key, type, value);
+    }
+    const slots = new Set();
+    const names = new Set();
+    const blocks = new Set(spec.uniforms.map((block) => block.name));
+    for (const b of spec.bindings) {
+        if (!IDENTIFIER.test(b.name) || RESERVED.has(b.name)) {
+            throw composeError(id, `binding:${b.name}`, `binding name "${b.name}" is not a usable identifier`);
+        }
+        const slot = `${b.group}.${b.binding}`;
+        if (slots.has(slot)) {
+            throw composeError(id, `binding:${b.name}`, `two bindings share group ${b.group} binding ${b.binding}`);
+        }
+        if (names.has(b.name)) {
+            throw composeError(id, `binding:${b.name}`, `two bindings share the name "${b.name}"`);
+        }
+        slots.add(slot);
+        names.add(b.name);
+        const struct = structNameOf(b.wgslType);
+        if (struct !== null && !blocks.has(struct)) {
+            throw composeError(id, `type:${struct}`, `binding "${b.name}" names struct "${struct}" but no block in spec.uniforms declares it`);
+        }
+    }
+}
+/**
+ * Substitutes the snippets into the body (every `//@@NAME@@` marker replaced by `spec.snippets[NAME]`) and checks the markers.
+ * @param spec - the module
+ * @returns the substituted body
+ */
+function substituteSnippets(spec) {
+    const { id } = spec;
+    let { body } = spec;
+    for (const [key, snippet] of Object.entries(spec.snippets ?? {})) {
+        const marker = `//@@${key}@@`;
+        if (!body.includes(marker)) {
+            throw composeError(id, `snippet:${key}`, `snippet "${key}" has no ${marker} marker in the body`);
+        }
+        body = body.split(marker).join(snippet);
+    }
+    const left = MARKER.exec(body);
+    if (left !== null) {
+        throw composeError(id, `marker:${left[1]}`, `marker //@@${left[1]}@@ is not filled by any snippet`);
+    }
+    return body;
+}
+/**
+ * The textual checks on the substituted body: no `@group(`, no `override `, no reserved identifier, no helper call without `needs`.
+ * PLAN DECISION: a body calling a `wg_reduce_*` helper without `needs: ["subgroups"]` is
+ * `E_SHADER_COMPILE { slot: "helper:<name>" }` (otherwise an unresolved identifier on the first device).
+ * @param spec - the module
+ * @param body - the substituted body
+ */
+function validateBody(spec, body) {
+    const { id } = spec;
+    for (const forbidden of ["@group(", "override "]) {
+        if (body.includes(forbidden)) {
+            throw composeError(id, `body:${forbidden}`, `a body must not contain "${forbidden}" (the composer emits those lines)`);
+        }
+    }
+    const stripped = stripComments(body);
+    const helpers = REDUCE_HELPER_NAMES;
+    for (const match of stripped.matchAll(IDENTIFIER_TOKENS)) {
+        const word = match[0];
+        if (RESERVED.has(word)) {
+            throw composeError(id, `reserved:${word}`, `"${word}" is a WGSL reserved word (spec 16.2) and cannot be an identifier`);
+        }
+        if (helpers.includes(word) && !spec.needs.includes("subgroups")) {
+            throw composeError(id, `helper:${word}`, `the body calls ${word} but spec.needs does not list "subgroups"`);
+        }
+    }
+}
+/**
+ * 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 function composeWgsl(spec, caps) {
+    validateDeclarations(spec);
+    const entryPoint = findEntryPoint(spec.body);
+    if (entryPoint === null) {
+        throw composeError(spec.id, "entry", "a body must carry exactly one @compute attribute followed by `fn <name>`");
+    }
+    const body = substituteSnippets(spec);
+    validateBody(spec, body);
+    const wantsHelpers = spec.needs.includes("subgroups");
+    const subgroups = wantsHelpers && caps.features.has("subgroups");
+    const overrides = { ...spec.overrides };
+    if (overrides.WG === undefined) {
+        overrides.WG = workgroupSizeFor(caps);
+    }
+    if (subgroups) {
+        overrides.SUBGROUP_MAX = caps.subgroupMaxSize;
+        overrides.SUBGROUP_MIN = Math.max(SUBGROUP_FLOOR, caps.subgroupMinSize);
+    }
+    const parts = [];
+    if (subgroups) {
+        parts.push("enable subgroups;");
+    }
+    parts.push(PRELUDE_WGSL);
+    for (const decl of spec.overrideDecls) {
+        parts.push(`override ${decl.name}: ${decl.type} = ${overrideLiteral(decl)};`);
+    }
+    for (const block of spec.uniforms) {
+        parts.push(block.wgsl);
+    }
+    if (wantsHelpers) {
+        parts.push(subgroups ? REDUCE_HELPERS_SUBGROUP_WGSL : REDUCE_HELPERS_WORKGROUP_WGSL);
+    }
+    for (const decl of spec.bindings) {
+        parts.push(bindingLine(decl));
+    }
+    const head = parts.join("\n");
+    const code = `${head}\n${body}`;
+    return Object.freeze({
+        id: spec.id,
+        code,
+        bodyLine: head.split("\n").length + 1,
+        overrides: Object.freeze(overrides),
+        constants: Object.freeze(referencedOverrides(code, overrides)),
+        entryPoint,
+        subgroups,
+    });
+}
+/**
+ * The overrides whose names occur in the code outside comments and outside their own `override` declaration lines
+ * (the constants a pipeline may carry on every backend, see ComposedModule.constants).
+ * @param code - the composed module text
+ * @param overrides - the effective override values
+ * @returns the referenced subset, in the same order
+ */
+function referencedOverrides(code, overrides) {
+    const stripped = code
+        .replace(/\/\*[\s\S]*?\*\//g, " ")
+        .replace(/\/\/[^\n]*/g, " ")
+        .replace(/^\s*override\s+\w+\s*:[^\n]*$/gm, " ");
+    const referenced = {};
+    for (const [name, value] of Object.entries(overrides)) {
+        if (new RegExp(`\\b${name}\\b`).test(stripped)) {
+            referenced[name] = value;
+        }
+    }
+    return referenced;
+}
+//# sourceMappingURL=wgsl.js.map

package/dist/src/kernel/wgsl.js.map

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

package/dist/src/kernels.d.ts

@@ -0,0 +1,81 @@
+/**
+ * THE kernel registry (spec 3.5; contract 3.10): every WGSL module the package compiles, keyed by id, with the
+ * binding table, the override declarations, the generated uniform / storage blocks and the feature needs from
+ * which src/kernel/wgsl.ts emits the bind declarations and src/kernel/pipeline-cache.ts derives the explicit
+ * bind-group layouts. A variant cannot exist without an entry here: the compile tests, the bind-group-budget
+ * test and PipelineCache.warm() iterate this table. P1-T4 lands degree, reduce, fill, fa2-repulsion-exact (K3)
+ * and fa2-speed-finalize (K4) together with every generated block of contract 3.10.2; P2-T2 lands
+ * segmented-reduce; P3-T2 adds fa2-stats-finalize (K1), fa2-attraction (K2), fa2-integrate (K5) and
+ * fa2-to-scene. This file is the only importer of src/wgsl/** (spec 3.2; test/layers.test.ts).
+ */
+import { UniformBlock } from "./kernel/struct-block.js";
+import { type BindingDecl, type OverrideDecl, type WgslModuleSpec } from "./kernel/wgsl.js";
+import { type CoreBinding } from "./memory/residency.js";
+import { type Binding } from "./types/memory.js";
+/** Every module id of P1-P3 (P4+ ids are appended, never renamed). */
+export type KernelId = "degree" | "reduce" | "fill" | "segmented-reduce" | "fa2-stats-finalize" | "fa2-attraction" | "fa2-repulsion-exact" | "fa2-speed-finalize" | "fa2-integrate" | "fa2-to-scene";
+/** One registry entry: everything of a WgslModuleSpec except the per-variant overrides and snippets. */
+export interface KernelEntry {
+    readonly id: KernelId;
+    readonly body: string;
+    readonly entryPoint: string;
+    readonly bindings: readonly BindingDecl[];
+    readonly overrideDecls: readonly OverrideDecl[];
+    readonly uniforms: readonly UniformBlock[];
+    /** ["subgroups"] when the body calls a reduction helper (the twin axis), else []. */
+    readonly needs: readonly "subgroups"[];
+    /** The snippet marker names the body carries (segmented-reduce: ["VALUE"]). */
+    readonly snippetSlots: readonly string[];
+    /** The phase the entry landed in (documentation and the compile-matrix filter). */
+    readonly phase: "P1" | "P2" | "P3";
+}
+/** `RangeParams` (uniform, 32 B): rows `[start, end)` @0 / @4 of the dispatch, the bound arc window `[arcBase, arcEnd)` @8 / @12 (0 and arcCount when not windowed), `accumulate` @16 (1 combines into `out[i]` instead of overwriting: the P4 windowed loop), `n` @20 (the node count that bounds neighbour indices), `pad0` @24, `pad1` @28. */
+export declare const RANGE_PARAMS: UniformBlock;
+/** `ReduceParams` (uniform, 16 B): `count` @0 elements of the level, `outOffset` @4 (the element index the level writes at), `level` @8, `pad0` @12. */
+export declare const REDUCE_PARAMS: UniformBlock;
+/** `FillParams` (uniform, 16 B): `count` @0 words, `value` @4, `mode` @8 (0 = the constant `value`, 1 = iota `i + value`), `pad0` @12. */
+export declare const FILL_PARAMS: UniformBlock;
+/** `Fa2Params` (uniform, 96 B; spec 7.3): the per-iteration ForceAtlas2 parameters -- `n` @0, `dim` @4, `flags` @8 (bit 0 = FA2_FLAG_FIRST), `tierStart` @12, `tierEnd` @16, `iterationIndex` @20, `seed` @24, `nearMax` @28, `scalingRatio` @32, `gravity` @36, `jitterTolerance` @40, `scale` @44, `center` @48 (xyz, w 0), `settleThreshold` @64, `extentFactor` @68, `gridMax` @72, `levels` @76, `pad` @80 (reserved for the P4 GridSpec). */
+export declare const FA2_PARAMS: UniformBlock;
+/** `Fa2State` (storage, padded to STATE_HEADER_BYTES = 256; spec 7.3): the device-resident controller state the finalize kernels write and the host reads back for stats -- `speed` @0, `speedEfficiency` @4, `swing` @8, `traction` @12, `centroid` @16, `rmsRadius` @32, `radius` @36, `meanDisplacement` @40, `iteration` @44, `min` @48, `max` @64, `gridMin` @80 (P4), `eps` @96 (P4), `settledCount` @100, `outsideGrid` @104 (P4), `maxCellOccupancy` @108 (P4), `reserved0` .. `reserved8` @112 .. @240. */
+export declare const FA2_STATE: UniformBlock;
+/** `Fa2Trace` (storage record, 32 B; spec 7.3): one per-iteration trace record -- `swing` @0, `traction` @4, `speed` @8, `speedEfficiency` @12 (written by K4), `meanDisplacement` @16, `settledCount` @20, `iteration` @24 (written by K1), `pad0` @28; the trace region is `array<Fa2Trace>` at byte offset STATE_HEADER_BYTES of the state buffer. */
+export declare const FA2_TRACE: UniformBlock;
+/** `Fa2Partial` (storage record, 64 B; spec 7.3): one per-workgroup partial -- `sum` @0 (xyz = sum of positions, w = sum of |p - centroid|^2), `min` @16, `max` @32 (w = max of |p - centroid|^2, the exact layoutRadius source), written by K5; `swingTraction` @48 (written by K3's epilogue); `dispFree` @56 (x = sum |dp| over free rows, y = the free count as an f32 <= 256, written by K5). */
+export declare const FA2_PARTIAL: UniformBlock;
+/** THE registry (spec 3.5): every entry, keyed by id. */
+export declare const KERNELS: Readonly<Record<KernelId, KernelEntry>>;
+/**
+ * A WgslModuleSpec for a variant: the entry plus the overrides / snippets given; unknown override names are
+ * rejected at compose time. A body override installed by setKernelBodyOverride is used instead of the entry's
+ * body.
+ * @param id - the module id
+ * @param overrides - the override values of this variant (the five standard names and the entry's overrideDecls)
+ * @param snippets - the texts substituted at the body's `//@@NAME@@` markers
+ * @returns the spec the PipelineCache compiles
+ */
+export declare function kernelSpec(id: KernelId, overrides?: Readonly<Record<string, number | boolean>>, snippets?: Readonly<Record<string, string>>): WgslModuleSpec;
+/**
+ * The group-0 graph bindings of a core with the dummy rules applied (spec 3.5, 4.1): colIdx <- rowPtr when null,
+ * weights <- colIdx ?? rowPtr when null, perm <- rowPtr when null. `weights` is the binding to use in the weights
+ * slot: omitted -> core.weights (degree, segmented-reduce); a layout passes its RESOLVED weights
+ * (ModelResources.weights, 3.13), null meaning "attract with 1.0" even on a weighted snapshot.
+ * @param core - the resident core arrays of a snapshot
+ * @param perm - the degreeOrder row permutation, or null (rowPtr is bound as the dummy)
+ * @param weights - the weights binding to use; undefined takes the core's, null binds the colIdx dummy
+ * @returns the four bindings in slot order
+ */
+export declare function graphBindings(core: CoreBinding, perm: Binding | null, weights?: Binding | null): Readonly<Record<"rowPtr" | "colIdx" | "weights" | "perm", Binding>>;
+/**
+ * The override values graphBindings implies: USE_PERM = perm !== null, HAS_WEIGHTS = (weights === undefined ?
+ * core.weights : weights) !== null.
+ * @param core - the resident core arrays of a snapshot
+ * @param perm - the row permutation binding, or null
+ * @param weights - the weights binding to use; undefined takes the core's, null means "unweighted"
+ * @returns the two standard override values of the variant
+ */
+export declare function graphOverrides(core: CoreBinding, perm: Binding | null, weights?: Binding | null): Readonly<{
+    USE_PERM: boolean;
+    HAS_WEIGHTS: boolean;
+}>;
+//# sourceMappingURL=kernels.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"kernels.d.ts","sourceRoot":"","sources":["../../src/kernels.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAC5F,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAYjD,sEAAsE;AACtE,MAAM,MAAM,QAAQ,GACd,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,kBAAkB,GAClB,oBAAoB,GACpB,gBAAgB,GAChB,qBAAqB,GACrB,oBAAoB,GACpB,eAAe,GACf,cAAc,CAAC;AAErB,wGAAwG;AACxG,MAAM,WAAW,WAAW;IACxB,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAC;IAC1C,QAAQ,CAAC,aAAa,EAAE,SAAS,YAAY,EAAE,CAAC;IAChD,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;IAC3C,qFAAqF;IACrF,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IACvC,+EAA+E;IAC/E,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,mFAAmF;IACnF,QAAQ,CAAC,KAAK,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;CACtC;AAID,kVAAkV;AAClV,eAAO,MAAM,YAAY,EAAE,YASzB,CAAC;AAEH,wJAAwJ;AACxJ,eAAO,MAAM,aAAa,EAAE,YAK1B,CAAC;AAEH,0IAA0I;AAC1I,eAAO,MAAM,WAAW,EAAE,YAKxB,CAAC;AAEH,mbAAmb;AACnb,eAAO,MAAM,UAAU,EAAE,YAmBvB,CAAC;AAEH,ofAAof;AACpf,eAAO,MAAM,SAAS,EAAE,YA8BvB,CAAC;AAEF,yVAAyV;AACzV,eAAO,MAAM,SAAS,EAAE,YAavB,CAAC;AAEF,sYAAsY;AACtY,eAAO,MAAM,WAAW,EAAE,YAUzB,CAAC;AA2OF,yDAAyD;AACzD,eAAO,MAAM,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAuD,CAAC;AAsBpH;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CACtB,EAAE,EAAE,QAAQ,EACZ,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,EACtD,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAC5C,cAAc,CAYhB;AAkBD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CACzB,IAAI,EAAE,WAAW,EACjB,IAAI,EAAE,OAAO,GAAG,IAAI,EACpB,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,GACzB,QAAQ,CAAC,MAAM,CAAC,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,EAAE,OAAO,CAAC,CAAC,CASrE;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC1B,IAAI,EAAE,WAAW,EACjB,IAAI,EAAE,OAAO,GAAG,IAAI,EACpB,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,GACzB,QAAQ,CAAC;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,OAAO,CAAA;CAAE,CAAC,CAGvD"}