@graphty/webgpu-graph-algorithms 0.0.0 → 0.2.0

package/dist/src/device/acquire.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Device acquisition (spec 2.2 steps 1-3, 2.6; contract 3.4): the adapter request, the software-adapter
+ * test, the adapter summary, the requiredLimits / requiredFeatures builders and the device request. Nothing
+ * above the device layer is constructed here (D26); src/context.ts sequences these calls. An adapter is
+ * consumed by its first requestDevice (WebGPU 3.5.1; Dawn-node rejects the second call with
+ * `OperationError: adapter is "consumed"`), so every device the package creates comes from a fresh adapter.
+ */
+import type { AdapterInfoLike, AdapterSummary, LimitPolicy, RaisableLimit } from "../types/context.js";
+/** The six raisable limits in the order create() requests them (spec 2.2). */
+export declare const RAISABLE_LIMITS: readonly RaisableLimit[];
+/**
+ * Software adapter test (spec 2.2 step 2): architecture "software" (Dawn llvmpipe) or "swiftshader", or
+ * isFallbackAdapter === true (Chromium); the ONE reader of these fields.
+ * @param info - the adapter info (structural, so tests can fake it)
+ * @returns true for a software adapter
+ */
+export declare function isSoftwareAdapter(info: AdapterInfoLike): boolean;
+/**
+ * The AdapterSummary of an adapter (info + features + limits); never requests a device.
+ * @param adapter - an adapter (unused or not; only its info, features and limits are read)
+ * @returns a frozen summary; `subgroupMinSize` / `subgroupMaxSize` are 0 when the info lacks them
+ */
+export declare function summarizeAdapter(adapter: GPUAdapter): AdapterSummary;
+/**
+ * Step 1 of create(): requestAdapter with the power preference; null -> E_NO_ADAPTER.
+ * @param gpu - navigator.gpu or the Dawn handle
+ * @param powerPreference - honoured by browsers, ignored by Dawn-node (spec 2.6)
+ * @returns an UNUSED adapter
+ */
+export declare function requestAdapter(gpu: GPU, powerPreference: GPUPowerPreference): Promise<GPUAdapter>;
+/**
+ * Step 3 of create(): the requiredLimits record for a policy, clamped to the adapter; an explicit value
+ * above the adapter -> E_NO_DEVICE { reason: "limit" } before any requestDevice call, so the failure is
+ * diagnosable.
+ * @param adapter - the adapter the device will come from
+ * @param policy - "default" (nothing), "raise" (every raisable limit at the adapter's value) or explicit values
+ * @returns the record to pass as requiredLimits
+ */
+export declare function buildRequiredLimits(adapter: GPUAdapter, policy: LimitPolicy): Record<string, number>;
+/**
+ * Step 3 of create(): the requiredFeatures list = required + (optional intersect adapter.features); a missing
+ * required feature -> E_NO_DEVICE { reason: "feature", requested: <name> }.
+ * @param adapter - the adapter the device will come from
+ * @param required - features the caller cannot do without
+ * @param optional - features requested only when the adapter has them
+ * @returns the deduplicated list, required first
+ */
+export declare function buildRequiredFeatures(adapter: GPUAdapter, required: readonly GPUFeatureName[], optional: readonly GPUFeatureName[]): GPUFeatureName[];
+/**
+ * Step 3 of create(): requestDevice; a rejection -> E_NO_DEVICE with the adapter summary ("consumed" when
+ * the adapter already created a device, detected by the OperationError message or a prior-use record).
+ * @param adapter - an UNUSED adapter
+ * @param descriptor - requiredLimits, requiredFeatures and the label
+ * @returns the device
+ */
+export declare function requestDevice(adapter: GPUAdapter, descriptor: GPUDeviceDescriptor): Promise<GPUDevice>;
+//# sourceMappingURL=acquire.d.ts.map

package/dist/src/device/acquire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"acquire.d.ts","sourceRoot":"","sources":["../../../src/device/acquire.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEvG,8EAA8E;AAC9E,eAAO,MAAM,eAAe,EAAE,SAAS,aAAa,EAOlD,CAAC;AA0DH;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAShE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,UAAU,GAAG,cAAc,CAqBpE;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,GAAG,EAAE,eAAe,EAAE,kBAAkB,GAAG,OAAO,CAAC,UAAU,CAAC,CAavG;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA2BpG;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACjC,OAAO,EAAE,UAAU,EACnB,QAAQ,EAAE,SAAS,cAAc,EAAE,EACnC,QAAQ,EAAE,SAAS,cAAc,EAAE,GACpC,cAAc,EAAE,CAoBlB;AAiBD;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,mBAAmB,GAAG,OAAO,CAAC,SAAS,CAAC,CAmB5G"}

package/dist/src/device/acquire.js

@@ -0,0 +1,232 @@
+/**
+ * Device acquisition (spec 2.2 steps 1-3, 2.6; contract 3.4): the adapter request, the software-adapter
+ * test, the adapter summary, the requiredLimits / requiredFeatures builders and the device request. Nothing
+ * above the device layer is constructed here (D26); src/context.ts sequences these calls. An adapter is
+ * consumed by its first requestDevice (WebGPU 3.5.1; Dawn-node rejects the second call with
+ * `OperationError: adapter is "consumed"`), so every device the package creates comes from a fresh adapter.
+ */
+import { WebGpuGraphError } from "../errors.js";
+/** The six raisable limits in the order create() requests them (spec 2.2). */
+export const RAISABLE_LIMITS = Object.freeze([
+    "maxBufferSize",
+    "maxStorageBufferBindingSize",
+    "maxStorageBuffersPerShaderStage",
+    "maxComputeWorkgroupStorageSize",
+    "maxComputeInvocationsPerWorkgroup",
+    "maxComputeWorkgroupSizeX",
+]);
+/**
+ * The WebGPU limit names summarizeAdapter reads (the GPUSupportedLimits members of @webgpu/types 0.1.72).
+ * A fixed list because Chromium exposes the limits as prototype getters (Object.keys is empty) and Dawn-node as an
+ * addon object; reading each name works identically on both, and a name the runtime lacks is simply absent.
+ */
+const LIMIT_NAMES = [
+    "maxTextureDimension1D",
+    "maxTextureDimension2D",
+    "maxTextureDimension3D",
+    "maxTextureArrayLayers",
+    "maxBindGroups",
+    "maxBindGroupsPlusVertexBuffers",
+    "maxBindingsPerBindGroup",
+    "maxDynamicUniformBuffersPerPipelineLayout",
+    "maxDynamicStorageBuffersPerPipelineLayout",
+    "maxSampledTexturesPerShaderStage",
+    "maxSamplersPerShaderStage",
+    "maxStorageBuffersPerShaderStage",
+    "maxStorageBuffersInVertexStage",
+    "maxStorageBuffersInFragmentStage",
+    "maxStorageTexturesPerShaderStage",
+    "maxStorageTexturesInVertexStage",
+    "maxStorageTexturesInFragmentStage",
+    "maxUniformBuffersPerShaderStage",
+    "maxUniformBufferBindingSize",
+    "maxStorageBufferBindingSize",
+    "minUniformBufferOffsetAlignment",
+    "minStorageBufferOffsetAlignment",
+    "maxVertexBuffers",
+    "maxBufferSize",
+    "maxVertexAttributes",
+    "maxVertexBufferArrayStride",
+    "maxInterStageShaderVariables",
+    "maxColorAttachments",
+    "maxColorAttachmentBytesPerSample",
+    "maxComputeWorkgroupStorageSize",
+    "maxComputeInvocationsPerWorkgroup",
+    "maxComputeWorkgroupSizeX",
+    "maxComputeWorkgroupSizeY",
+    "maxComputeWorkgroupSizeZ",
+    "maxComputeWorkgroupsPerDimension",
+    "maxImmediateSize",
+];
+/** Adapters that created a device through requestDevice(): a second create({ adapter }) fails without a round trip. */
+const consumedAdapters = new WeakSet();
+/**
+ * The message of a thrown value.
+ * @param err - what was caught
+ * @returns the Error message, or the value as a string
+ */
+function messageOf(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Software adapter test (spec 2.2 step 2): architecture "software" (Dawn llvmpipe) or "swiftshader", or
+ * isFallbackAdapter === true (Chromium); the ONE reader of these fields.
+ * @param info - the adapter info (structural, so tests can fake it)
+ * @returns true for a software adapter
+ */
+export function isSoftwareAdapter(info) {
+    // "software" = Dawn-node on llvmpipe, "swiftshader" = Chromium's fallback, "warp" = Dawn's D3D12 backend on
+    // Microsoft's WARP rasterizer (the Windows host lane: vendor "microsoft", isFallbackAdapter absent under Dawn-node).
+    return (info.architecture === "software" ||
+        info.architecture === "swiftshader" ||
+        info.architecture === "warp" ||
+        info.isFallbackAdapter === true);
+}
+/**
+ * The AdapterSummary of an adapter (info + features + limits); never requests a device.
+ * @param adapter - an adapter (unused or not; only its info, features and limits are read)
+ * @returns a frozen summary; `subgroupMinSize` / `subgroupMaxSize` are 0 when the info lacks them
+ */
+export function summarizeAdapter(adapter) {
+    const { info } = adapter;
+    const source = adapter.limits;
+    const limits = {};
+    for (const name of LIMIT_NAMES) {
+        const value = source[name];
+        if (typeof value === "number") {
+            limits[name] = value;
+        }
+    }
+    return Object.freeze({
+        vendor: info.vendor,
+        architecture: info.architecture,
+        device: info.device,
+        description: info.description,
+        software: isSoftwareAdapter(info),
+        subgroupMinSize: info.subgroupMinSize ?? 0,
+        subgroupMaxSize: info.subgroupMaxSize ?? 0,
+        features: Object.freeze(Array.from(adapter.features).sort()),
+        limits: Object.freeze(limits),
+    });
+}
+/**
+ * Step 1 of create(): requestAdapter with the power preference; null -> E_NO_ADAPTER.
+ * @param gpu - navigator.gpu or the Dawn handle
+ * @param powerPreference - honoured by browsers, ignored by Dawn-node (spec 2.6)
+ * @returns an UNUSED adapter
+ */
+export async function requestAdapter(gpu, powerPreference) {
+    let adapter;
+    try {
+        adapter = await gpu.requestAdapter({ powerPreference });
+    }
+    catch (err) {
+        const reason = `requestAdapter() threw: ${messageOf(err)}`;
+        throw new WebGpuGraphError("E_NO_ADAPTER", reason, { reason });
+    }
+    if (adapter === null) {
+        const reason = "requestAdapter() returned null: no usable WebGPU adapter";
+        throw new WebGpuGraphError("E_NO_ADAPTER", reason, { reason });
+    }
+    return adapter;
+}
+/**
+ * Step 3 of create(): the requiredLimits record for a policy, clamped to the adapter; an explicit value
+ * above the adapter -> E_NO_DEVICE { reason: "limit" } before any requestDevice call, so the failure is
+ * diagnosable.
+ * @param adapter - the adapter the device will come from
+ * @param policy - "default" (nothing), "raise" (every raisable limit at the adapter's value) or explicit values
+ * @returns the record to pass as requiredLimits
+ */
+export function buildRequiredLimits(adapter, policy) {
+    const limits = {};
+    if (policy === "default") {
+        return limits;
+    }
+    if (policy === "raise") {
+        for (const name of RAISABLE_LIMITS) {
+            limits[name] = adapter.limits[name];
+        }
+        return limits;
+    }
+    for (const name of RAISABLE_LIMITS) {
+        const requested = policy[name];
+        if (requested === undefined) {
+            continue;
+        }
+        const available = adapter.limits[name];
+        if (requested > available) {
+            throw new WebGpuGraphError("E_NO_DEVICE", `requested ${name} = ${requested} exceeds the adapter's ${available}`, { reason: "limit", adapter: summarizeAdapter(adapter), limit: name, requested, available });
+        }
+        limits[name] = requested;
+    }
+    return limits;
+}
+/**
+ * Step 3 of create(): the requiredFeatures list = required + (optional intersect adapter.features); a missing
+ * required feature -> E_NO_DEVICE { reason: "feature", requested: <name> }.
+ * @param adapter - the adapter the device will come from
+ * @param required - features the caller cannot do without
+ * @param optional - features requested only when the adapter has them
+ * @returns the deduplicated list, required first
+ */
+export function buildRequiredFeatures(adapter, required, optional) {
+    const features = [];
+    for (const feature of required) {
+        if (!adapter.features.has(feature)) {
+            throw new WebGpuGraphError("E_NO_DEVICE", `required feature "${feature}" is not supported by the adapter`, {
+                reason: "feature",
+                adapter: summarizeAdapter(adapter),
+                requested: feature,
+            });
+        }
+        if (!features.includes(feature)) {
+            features.push(feature);
+        }
+    }
+    for (const feature of optional) {
+        if (adapter.features.has(feature) && !features.includes(feature)) {
+            features.push(feature);
+        }
+    }
+    return features;
+}
+/**
+ * The E_NO_DEVICE of a consumed adapter; the runtime's text lives in the error message only (contract 3.1
+ * documents `details` as { reason, adapter, limit?, requested?, available? }).
+ * @param adapter - the adapter that already created a device
+ * @param message - the runtime's rejection message when there was a round trip
+ * @returns E_NO_DEVICE { reason: "consumed", adapter }
+ */
+function consumedError(adapter, message) {
+    return new WebGpuGraphError("E_NO_DEVICE", `the adapter already created a device (an adapter is consumed by one requestDevice, spec 2.2 step 1): ${message}`, { reason: "consumed", adapter: summarizeAdapter(adapter) });
+}
+/**
+ * Step 3 of create(): requestDevice; a rejection -> E_NO_DEVICE with the adapter summary ("consumed" when
+ * the adapter already created a device, detected by the OperationError message or a prior-use record).
+ * @param adapter - an UNUSED adapter
+ * @param descriptor - requiredLimits, requiredFeatures and the label
+ * @returns the device
+ */
+export async function requestDevice(adapter, descriptor) {
+    if (consumedAdapters.has(adapter)) {
+        throw consumedError(adapter, "recorded by this package");
+    }
+    let device;
+    try {
+        device = await adapter.requestDevice(descriptor);
+    }
+    catch (err) {
+        const message = messageOf(err);
+        if (/consumed|already been used/i.test(message)) {
+            throw consumedError(adapter, message);
+        }
+        throw new WebGpuGraphError("E_NO_DEVICE", `requestDevice() rejected: ${message}`, {
+            reason: "requestDevice",
+            adapter: summarizeAdapter(adapter),
+        });
+    }
+    consumedAdapters.add(adapter);
+    return device;
+}
+//# sourceMappingURL=acquire.js.map

package/dist/src/device/acquire.js.map

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

package/dist/src/device/caps.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Capability capture (spec 2.2 step 4, 3.3, 5.1, 5.2; contract 3.4): the GpuCaps record of a DEVICE (its
+ * limits and features, never the adapter's), the zero-cost variant for an adopted device, the two planner
+ * facts asserted at create(), and the workgroup size a device runs.
+ */
+import type { AdapterInfoLike, GpuCaps, PlanCaps } from "../types/context.js";
+/**
+ * Step 4 of create(): the GpuCaps of a DEVICE (device.limits, never adapter.limits) with the adapter info
+ * and the runtime tag. The subgroup sizes are the adapter's only when the device has the "subgroups"
+ * feature, else 0 (spec 3.3).
+ * @param device - the device the caps describe
+ * @param info - the adapter's info (vendor, architecture, subgroup sizes)
+ * @param runtime - the tag the creating entry sets ("unknown" for consumers of the core)
+ * @param wgslFeatures - navigator.gpu.wgslLanguageFeatures or the Dawn equivalent (informational)
+ * @returns the capability record
+ */
+export declare function captureCaps(device: GPUDevice, info: AdapterInfoLike, runtime: "browser" | "node" | "unknown", wgslFeatures: Iterable<string>): GpuCaps;
+/**
+ * GpuContext.from(device, info?): caps from device.limits / device.features and the partial info given;
+ * software false and runtime "unknown" unless given; the subgroup sizes are honoured only when the device
+ * has the feature.
+ * @param device - the adopted device
+ * @param info - what the caller knows about the adapter, if anything
+ * @returns the capability record
+ */
+export declare function capsFromDevice(device: GPUDevice, info: Partial<GpuCaps> | undefined): GpuCaps;
+/**
+ * The workgroup size a device runs: min(WORKGROUP_SIZE, caps.limits.maxComputeInvocationsPerWorkgroup) rounded
+ * down to a power of two (spec 5.1; the formula of contract 3.2 / 3.4). maxComputeWorkgroupSizeX is not a term:
+ * every adapter supports its 256 default (WebGPU 3.6.2), so the result never exceeds it. Rounds down by doubling
+ * (no bitwise operator).
+ * @param caps - the capability record (a GpuCaps is a PlanCaps)
+ * @returns the workgroup size
+ */
+export declare function workgroupSizeFor(caps: PlanCaps): number;
+/**
+ * Asserts the two facts the planners bake in: maxComputeWorkgroupsPerDimension === MAX_WORKGROUPS_PER_DIM
+ * (the prelude's linear_id and plan1d / plan2d use the constant) and WG is a power of two >= 64 (spec 2.2,
+ * 5.2). The limit is never requested, so a device reports the spec default whatever its adapter says.
+ * @param caps - the capability record of the device
+ */
+export declare function assertPlanLimits(caps: GpuCaps): void;
+//# sourceMappingURL=caps.d.ts.map

package/dist/src/device/caps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"caps.d.ts","sourceRoot":"","sources":["../../../src/device/caps.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAG9E;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CACvB,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS,EACvC,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,GAC/B,OAAO,CAgBT;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,SAAS,GAAG,OAAO,CAgB7F;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAOvD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CA4BpD"}

package/dist/src/device/caps.js

@@ -0,0 +1,104 @@
+/**
+ * Capability capture (spec 2.2 step 4, 3.3, 5.1, 5.2; contract 3.4): the GpuCaps record of a DEVICE (its
+ * limits and features, never the adapter's), the zero-cost variant for an adopted device, the two planner
+ * facts asserted at create(), and the workgroup size a device runs.
+ */
+import { MAX_WORKGROUPS_PER_DIM, WORKGROUP_SIZE } from "../constants.js";
+import { WebGpuGraphError } from "../errors.js";
+import { isSoftwareAdapter } from "./acquire.js";
+/**
+ * Step 4 of create(): the GpuCaps of a DEVICE (device.limits, never adapter.limits) with the adapter info
+ * and the runtime tag. The subgroup sizes are the adapter's only when the device has the "subgroups"
+ * feature, else 0 (spec 3.3).
+ * @param device - the device the caps describe
+ * @param info - the adapter's info (vendor, architecture, subgroup sizes)
+ * @param runtime - the tag the creating entry sets ("unknown" for consumers of the core)
+ * @param wgslFeatures - navigator.gpu.wgslLanguageFeatures or the Dawn equivalent (informational)
+ * @returns the capability record
+ */
+export function captureCaps(device, info, runtime, wgslFeatures) {
+    const features = new Set(device.features);
+    const subgroups = features.has("subgroups");
+    return {
+        limits: device.limits,
+        features,
+        wgslFeatures: new Set(wgslFeatures),
+        subgroupMinSize: subgroups ? (info.subgroupMinSize ?? 0) : 0,
+        subgroupMaxSize: subgroups ? (info.subgroupMaxSize ?? 0) : 0,
+        software: isSoftwareAdapter(info),
+        runtime,
+        vendor: info.vendor,
+        architecture: info.architecture,
+        device: info.device,
+        description: info.description,
+    };
+}
+/**
+ * GpuContext.from(device, info?): caps from device.limits / device.features and the partial info given;
+ * software false and runtime "unknown" unless given; the subgroup sizes are honoured only when the device
+ * has the feature.
+ * @param device - the adopted device
+ * @param info - what the caller knows about the adapter, if anything
+ * @returns the capability record
+ */
+export function capsFromDevice(device, info) {
+    const features = new Set(device.features);
+    const subgroups = features.has("subgroups");
+    return {
+        limits: device.limits,
+        features,
+        wgslFeatures: info?.wgslFeatures ?? new Set(),
+        subgroupMinSize: subgroups ? (info?.subgroupMinSize ?? 0) : 0,
+        subgroupMaxSize: subgroups ? (info?.subgroupMaxSize ?? 0) : 0,
+        software: info?.software ?? false,
+        runtime: info?.runtime ?? "unknown",
+        vendor: info?.vendor ?? "",
+        architecture: info?.architecture ?? "",
+        device: info?.device ?? "",
+        description: info?.description ?? "",
+    };
+}
+/**
+ * The workgroup size a device runs: min(WORKGROUP_SIZE, caps.limits.maxComputeInvocationsPerWorkgroup) rounded
+ * down to a power of two (spec 5.1; the formula of contract 3.2 / 3.4). maxComputeWorkgroupSizeX is not a term:
+ * every adapter supports its 256 default (WebGPU 3.6.2), so the result never exceeds it. Rounds down by doubling
+ * (no bitwise operator).
+ * @param caps - the capability record (a GpuCaps is a PlanCaps)
+ * @returns the workgroup size
+ */
+export function workgroupSizeFor(caps) {
+    const cap = Math.min(WORKGROUP_SIZE, caps.limits.maxComputeInvocationsPerWorkgroup);
+    let size = 1;
+    while (size * 2 <= cap) {
+        size *= 2;
+    }
+    return size;
+}
+/**
+ * Asserts the two facts the planners bake in: maxComputeWorkgroupsPerDimension === MAX_WORKGROUPS_PER_DIM
+ * (the prelude's linear_id and plan1d / plan2d use the constant) and WG is a power of two >= 64 (spec 2.2,
+ * 5.2). The limit is never requested, so a device reports the spec default whatever its adapter says.
+ * @param caps - the capability record of the device
+ */
+export function assertPlanLimits(caps) {
+    const perDim = caps.limits.maxComputeWorkgroupsPerDimension;
+    if (perDim !== MAX_WORKGROUPS_PER_DIM) {
+        throw new WebGpuGraphError("E_NO_DEVICE", `maxComputeWorkgroupsPerDimension is ${perDim}; the dispatch planner and the WGSL prelude bake ${MAX_WORKGROUPS_PER_DIM}`, {
+            reason: "maxComputeWorkgroupsPerDimension",
+            adapter: null,
+            requested: MAX_WORKGROUPS_PER_DIM,
+            available: perDim,
+        });
+    }
+    const wg = workgroupSizeFor(caps);
+    if (wg < 64) {
+        throw new WebGpuGraphError("E_NO_DEVICE", `the device allows a workgroup of ${wg} invocations; the kernels need a power of two >= 64`, {
+            reason: "limit",
+            adapter: null,
+            limit: "maxComputeInvocationsPerWorkgroup",
+            requested: 64,
+            available: wg,
+        });
+    }
+}
+//# sourceMappingURL=caps.js.map

package/dist/src/device/caps.js.map

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

package/dist/src/device/error-scope.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Error scopes (spec 5.7; contract 3.4): a validation scope that turns a captured GPUValidationError into
+ * E_VALIDATION { label, message }, the compilation-info formatter with body-relative line numbers, and the
+ * AllocationTracker that wraps large createBuffer calls in an out-of-memory scope and keeps the resident-byte
+ * bookkeeping the residency, the pool and the staging ring share (it is owned by the context).
+ */
+/**
+ * Runs `fn` inside pushErrorScope("validation"); a captured error becomes E_VALIDATION { label, message }
+ * thrown from the returned promise (spec 5.7). An error `fn` itself throws is rethrown unchanged after the
+ * scope is popped, so the device's scope stack stays balanced.
+ * @param device - the device
+ * @param label - names the operation in the error (every object the package creates is labelled)
+ * @param fn - the work; may return a promise
+ * @returns the value of `fn`
+ */
+export declare function withValidationScope<T>(device: GPUDevice, label: string, fn: () => Promise<T> | T): Promise<T>;
+/**
+ * Formats GPUCompilationInfo messages with line numbers relative to the kernel BODY: `preludeLines` (the
+ * lines the composer emitted before the body) is subtracted, a message located inside those lines is
+ * reported as `prelude:<line>`, and a message without a location (lineNum 0) carries no position (spec 5.1).
+ * @param info - the compilation info of the shader module
+ * @param preludeLines - the number of emitted lines before the body's first line
+ * @returns one string per message: `<type> <line>:<column> <message>`
+ */
+export declare function formatCompilationInfo(info: GPUCompilationInfo, preludeLines: number): string[];
+/**
+ * Creates buffers, wrapping sizes >= OOM_SCOPE_THRESHOLD_BYTES in an "out-of-memory" scope whose pop is
+ * collected; `check()` surfaces the first OOM (spec 4.4, 5.7). Owned by the context, shared by the
+ * residency and the pool.
+ */
+export declare class AllocationTracker {
+    private readonly device;
+    private readonly threshold;
+    private readonly live;
+    private residentBytes;
+    private pending;
+    private failure;
+    private serial;
+    /**
+     * Creates a tracker over one device.
+     * @param device - the device buffers are created on
+     * @param thresholdBytes - the byte size from which createBuffer runs inside an out-of-memory scope (default OOM_SCOPE_THRESHOLD_BYTES)
+     */
+    constructor(device: GPUDevice, thresholdBytes?: number);
+    /**
+     * createBuffer with the scope rule; every buffer is labelled (an unlabelled descriptor becomes `buffer-<n>`).
+     * @param descriptor - the buffer descriptor
+     * @returns the buffer
+     */
+    createBuffer(descriptor: GPUBufferDescriptor): GPUBuffer;
+    /**
+     * Destroys a buffer created here and decrements `resident`; a buffer the tracker does not know is destroyed
+     * without touching the bookkeeping, so destroying twice is harmless.
+     * @param buffer - the buffer to destroy
+     */
+    destroy(buffer: GPUBuffer): void;
+    /**
+     * Awaits every outstanding scope pop; the first OOM -> E_OUT_OF_MEMORY { requested, resident, label }; later
+     * calls after a failure throw the same error again until `reset()`.
+     */
+    check(): Promise<void>;
+    /** Forgets a recorded OOM after the caller released what it allocated. */
+    reset(): void;
+    /**
+     * Bytes of live buffers created through this tracker.
+     * @returns the resident byte count
+     */
+    get resident(): number;
+    /**
+     * Number of live buffers created through this tracker.
+     * @returns the live buffer count
+     */
+    get liveBuffers(): number;
+}
+//# sourceMappingURL=error-scope.d.ts.map

package/dist/src/device/error-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-scope.d.ts","sourceRoot":"","sources":["../../../src/device/error-scope.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAcnH;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,EAAE,CAW9F;AAED;;;;GAIG;AACH,qBAAa,iBAAiB;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAgC;IACrD,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,OAAO,CAAuB;IACtC,OAAO,CAAC,OAAO,CAAiC;IAChD,OAAO,CAAC,MAAM,CAAK;IAEnB;;;;OAIG;gBACS,MAAM,EAAE,SAAS,EAAE,cAAc,CAAC,EAAE,MAAM;IAKtD;;;;OAIG;IACH,YAAY,CAAC,UAAU,EAAE,mBAAmB,GAAG,SAAS;IAqCxD;;;;OAIG;IACH,OAAO,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI;IAShC;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAU5B,0EAA0E;IAC1E,KAAK,IAAI,IAAI;IAIb;;;OAGG;IACH,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED;;;OAGG;IACH,IAAI,WAAW,IAAI,MAAM,CAExB;CACJ"}