@graphty/webgpu-graph-algorithms 0.0.0 → 0.2.0

package/dist/src/layouts/seed.js

@@ -0,0 +1,173 @@
+/**
+ * The CPU port's random number generator, bit for bit, and the NaN-row seeding both paths share (spec 7.2 "Initial
+ * positions", 9.3 seedPositions, 7.14 `pos`, 7.19 topology change): a seed gives the same start on the CPU and the
+ * GPU because both write the same f32 values in index order. The package carries its own copy of the LCG for its
+ * whole life (D27: it cannot import @graphty/layout); W1 cross-tests it against the real RandomNumberGenerator.
+ */
+import { WebGpuGraphError } from "../errors.js";
+/** The CPU port's LCG constants (layout/src/utils/random.ts): m = 2^35 - 31, a = 185852, c = 1. */
+export const LCG_M = 34359738337;
+/** The multiplier a of the port's LCG. */
+export const LCG_A = 185852;
+/** The increment c of the port's LCG. */
+export const LCG_C = 1;
+/**
+ * The port's RandomNumberGenerator, bit for bit: `seed || Math.floor(Math.random() * 1000000)` (seed 0 / null =
+ * unseeded, the quirk preserved), state = seed % m, next = (a * state + c) % m, value = state / m. The product
+ * a * state stays below 2^53 (a < 2^18, state < 2^35), so every step is exact in f64, as it is in the port.
+ */
+export class Lcg {
+    /**
+     * Creates the generator; a seed of 0, -0, NaN or null means unseeded (the port's `seed || random` quirk).
+     * @param seed - the seed, or null for a random seed
+     */
+    constructor(seed) {
+        this.seed = seed === null || seed === 0 || Number.isNaN(seed) ? Math.floor(Math.random() * 1000000) : seed;
+        this.state = this.seed % LCG_M;
+    }
+    /**
+     * Next value in [0, 1).
+     * @returns state / m after one LCG step
+     */
+    next() {
+        this.state = (LCG_A * this.state + LCG_C) % LCG_M;
+        return this.state / LCG_M;
+    }
+}
+/**
+ * The three center components of a CommonLayoutOptions.center (missing components are 0).
+ * @param center - the caller's center, or null
+ * @returns [x, y, z]; E_INVALID_ARGUMENT when a component is not finite
+ */
+function resolveCenter(center) {
+    const out = [0, 0, 0];
+    if (center === null) {
+        return out;
+    }
+    for (let axis = 0; axis < 3 && axis < center.length; axis++) {
+        const v = center[axis];
+        if (!Number.isFinite(v)) {
+            throw new WebGpuGraphError("E_INVALID_ARGUMENT", `center[${axis}] is not finite`, {
+                argument: "center",
+                value: v,
+                expected: "finite components",
+            });
+        }
+        out[axis] = v;
+    }
+    return out;
+}
+/**
+ * Seeds the unseeded rows of the owner's stride-3 SCENE array in index order (spec 9.3 seedPositions, 7.14 `pos`,
+ * 7.19 topology change): a row is unseeded when any of its `dim` components is not finite; every such component
+ * draws one LCG value; when NO row is fully finite the draw is uniform in [-1, 1) layout units per axis (`range:
+ * "fa2"`; `"fr"` is [0, 1)), otherwise uniform inside the [min, max] box of the finite components per axis,
+ * converted to layout units (an axis with no finite value falls back to the range box); the value is written as
+ * `v * scale + center[axis]`, which for scale 1 / center 0 is bit-identical to the port's `u * 2 - 1` (resp. `u`);
+ * in 2D the third component of a seeded row is written as center[2]. Finite components are never changed and a
+ * fully finite row is never touched. No random number is drawn when nothing needs seeding.
+ * PLAN DECISION 12 (P3-T1): the box is taken over every finite COMPONENT (the port's rule), not over the fully
+ * finite ROWS only; the two differ only when a partially finite row's finite axis lies outside the fully finite
+ * rows' box (pinned by test/layouts/seed.test.ts). PLAN DECISION 13: a 2D row whose x and y are finite is seeded
+ * whatever its z holds.
+ * @param s - the snapshot (nodeCount rows)
+ * @param positions - the owner's stride-3 scene-unit array, length 3 * nodeCount, modified in place
+ * @param seed - the LCG seed (0 / null = unseeded, the port's quirk)
+ * @param dim - 2 or 3
+ * @param scale - the scene scale (> 0)
+ * @param center - the scene center, or null for the origin
+ * @param range - "fa2" for [-1, 1), "fr" for [0, 1)
+ */
+export function seedPositions(s, positions, seed, dim, scale, center, range) {
+    const n = s.nodeCount;
+    if (dim !== 2 && dim !== 3) {
+        throw new WebGpuGraphError("E_INVALID_ARGUMENT", `dim must be 2 or 3, got ${String(dim)}`, {
+            argument: "dim",
+            value: dim,
+            expected: "2 or 3",
+        });
+    }
+    if (positions.length !== 3 * n) {
+        throw new WebGpuGraphError("E_INVALID_ARGUMENT", `positions has ${positions.length} entries, expected ${3 * n}`, {
+            argument: "positions",
+            value: positions.length,
+            expected: 3 * n,
+        });
+    }
+    if (!Number.isFinite(scale) || scale <= 0) {
+        throw new WebGpuGraphError("E_INVALID_ARGUMENT", `scale must be a finite number > 0, got ${scale}`, {
+            argument: "scale",
+            value: scale,
+            expected: "a finite number > 0",
+        });
+    }
+    const c = resolveCenter(center);
+    // classify the rows and collect the per-axis box of the finite components (scene units)
+    const lo = [Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY];
+    const hi = [Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY];
+    let finiteRows = 0;
+    let unseededRows = 0;
+    for (let i = 0; i < n; i++) {
+        let finite = true;
+        for (let axis = 0; axis < dim; axis++) {
+            const v = positions[3 * i + axis];
+            if (Number.isFinite(v)) {
+                if (v < lo[axis]) {
+                    lo[axis] = v;
+                }
+                if (v > hi[axis]) {
+                    hi[axis] = v;
+                }
+            }
+            else {
+                finite = false;
+            }
+        }
+        if (finite) {
+            finiteRows++;
+        }
+        else {
+            unseededRows++;
+        }
+    }
+    if (unseededRows === 0) {
+        return;
+    }
+    // the per-axis draw box in layout units
+    const rangeLo = range === "fr" ? 0 : -1;
+    const rangeHi = 1;
+    const boxLo = [rangeLo, rangeLo, rangeLo];
+    const boxHi = [rangeHi, rangeHi, rangeHi];
+    if (finiteRows > 0) {
+        for (let axis = 0; axis < dim; axis++) {
+            if (Number.isFinite(lo[axis]) && Number.isFinite(hi[axis])) {
+                boxLo[axis] = (lo[axis] - c[axis]) / scale;
+                boxHi[axis] = (hi[axis] - c[axis]) / scale;
+            }
+        }
+    }
+    const rng = new Lcg(seed);
+    for (let i = 0; i < n; i++) {
+        let unseeded = false;
+        for (let axis = 0; axis < dim; axis++) {
+            if (!Number.isFinite(positions[3 * i + axis])) {
+                unseeded = true;
+            }
+        }
+        if (!unseeded) {
+            continue;
+        }
+        for (let axis = 0; axis < dim; axis++) {
+            const at = 3 * i + axis;
+            if (!Number.isFinite(positions[at])) {
+                const u = rng.next();
+                const v = boxLo[axis] + u * (boxHi[axis] - boxLo[axis]);
+                positions[at] = v * scale + c[axis];
+            }
+        }
+        if (dim === 2) {
+            positions[3 * i + 2] = c[2];
+        }
+    }
+}
+//# sourceMappingURL=seed.js.map

package/dist/src/layouts/seed.js.map

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

package/dist/src/memory/buffer-pool.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Size-class pool of GPUBuffers by usage (spec 4.4): a request rounds up to a class (powers of two from 4 KiB to
+ * 64 MiB, then 16 MiB steps), an idle buffer of that (class, usage) is reused, otherwise one is created through the
+ * context's AllocationTracker (so the OOM scope of spec 5.7 and the resident accounting are shared with the
+ * residency); `release` keeps at most maxIdlePerClass idle buffers per (class, usage); `trim` destroys the idle
+ * ones (ctx.release and layouts on dispose); `destroyAll` everything (ctx.dispose). The Lease scope object arrives
+ * with P2-T1 (`lease()`, PLAN DECISION 1). Classes above maxBufferSize are never created: a request that fits the
+ * device but whose class overshoots gets the capped class (PLAN DECISION 14).
+ */
+import { type AllocationTracker } from "../device/error-scope.js";
+import { Lease } from "./lease.js";
+/** Size-class pool of GPUBuffers by usage (spec 4.4). */
+export declare class BufferPool {
+    private readonly allocator;
+    private readonly maxBufferSize;
+    private readonly maxIdlePerClass;
+    private readonly idle;
+    private readonly live;
+    private liveBytesValue;
+    private idleBytesValue;
+    private disposed;
+    /**
+     * Creates an empty pool.
+     * @param _device - the device (buffers are created through the allocator, which owns it; the parameter keeps
+     *   the contract's constructor shape)
+     * @param allocator - the context's OOM-scoped allocator
+     * @param maxBufferSize - the device's maxBufferSize (classes above it are never created)
+     * @param options - pool options
+     * @param options.maxIdlePerClass - idle buffers kept per (class, usage); default POOL_MAX_IDLE_PER_CLASS
+     */
+    constructor(_device: GPUDevice, allocator: AllocationTracker, maxBufferSize: number, options?: {
+        readonly maxIdlePerClass?: number | undefined;
+    });
+    /**
+     * The size class a byte length rounds up to: powers of two from 4 KiB to 64 MiB, then 16 MiB steps (pure).
+     * @param byteLength - a positive integer
+     * @returns the class in bytes
+     */
+    static sizeClass(byteLength: number): number;
+    /**
+     * Acquires a buffer of at least byteLength (an idle one of the class and usage, else a new one through the
+     * allocator); E_TOO_LARGE above maxBufferSize.
+     * @param byteLength - the bytes needed
+     * @param usage - the GPUBufferUsage flags
+     * @param label - the buffer label (a reused buffer is relabelled)
+     * @returns a buffer of the class size
+     */
+    acquire(byteLength: number, usage: number, label: string): GPUBuffer;
+    /**
+     * Returns a buffer to its class; destroys it when the class already holds maxIdlePerClass idle buffers. A no-op
+     * after destroyAll() (so a `finally` never masks the original error).
+     * @param buffer - a buffer acquired from this pool and not yet released
+     */
+    release(buffer: GPUBuffer): void;
+    /** Destroys every idle buffer. */
+    trim(): void;
+    /**
+     * A scope object that releases everything acquired through it (spec 4.4, P2).
+     * @returns a fresh lease over this pool
+     */
+    lease(): Lease;
+    /**
+     * Bytes of buffers acquired and not yet released (class sizes).
+     * @returns the live byte count
+     */
+    get liveBytes(): number;
+    /**
+     * Bytes of idle buffers (class sizes).
+     * @returns the idle byte count
+     */
+    get idleBytes(): number;
+}
+//# sourceMappingURL=buffer-pool.d.ts.map

package/dist/src/memory/buffer-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buffer-pool.d.ts","sourceRoot":"","sources":["../../../src/memory/buffer-pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAElE,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAkBnC,yDAAyD;AACzD,qBAAa,UAAU;IACnB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoB;IAC9C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAkC;IACvD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAmC;IACxD,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,QAAQ,CAAS;IAEzB;;;;;;;;OAQG;gBAEC,OAAO,EAAE,SAAS,EAClB,SAAS,EAAE,iBAAiB,EAC5B,aAAa,EAAE,MAAM,EACrB,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE;IAO/D;;;;OAIG;IACH,MAAM,CAAC,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM;IAkB5C;;;;;;;OAOG;IACH,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS;IA2BpE;;;;OAIG;IACH,OAAO,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI;IA4BhC,kCAAkC;IAClC,IAAI,IAAI,IAAI;IAqBZ;;;OAGG;IACH,KAAK,IAAI,KAAK;IAId;;;OAGG;IACH,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED;;;OAGG;IACH,IAAI,SAAS,IAAI,MAAM,CAEtB;CACJ"}

package/dist/src/memory/buffer-pool.js

@@ -0,0 +1,170 @@
+/**
+ * Size-class pool of GPUBuffers by usage (spec 4.4): a request rounds up to a class (powers of two from 4 KiB to
+ * 64 MiB, then 16 MiB steps), an idle buffer of that (class, usage) is reused, otherwise one is created through the
+ * context's AllocationTracker (so the OOM scope of spec 5.7 and the resident accounting are shared with the
+ * residency); `release` keeps at most maxIdlePerClass idle buffers per (class, usage); `trim` destroys the idle
+ * ones (ctx.release and layouts on dispose); `destroyAll` everything (ctx.dispose). The Lease scope object arrives
+ * with P2-T1 (`lease()`, PLAN DECISION 1). Classes above maxBufferSize are never created: a request that fits the
+ * device but whose class overshoots gets the capped class (PLAN DECISION 14).
+ */
+import { POOL_LINEAR_STEP_BYTES, POOL_MAX_IDLE_PER_CLASS, POOL_MAX_POW2_CLASS_BYTES, POOL_MIN_CLASS_BYTES, } from "../constants.js";
+import { WebGpuGraphError } from "../errors.js";
+import { Lease } from "./lease.js";
+/**
+ * The idle-list key of a (class, usage) pair.
+ * @param sizeClass - the class in bytes
+ * @param usage - the GPUBufferUsage flags
+ * @returns the map key
+ */
+function classKey(sizeClass, usage) {
+    return `${sizeClass}:${usage}`;
+}
+/** Size-class pool of GPUBuffers by usage (spec 4.4). */
+export class BufferPool {
+    /**
+     * Creates an empty pool.
+     * @param _device - the device (buffers are created through the allocator, which owns it; the parameter keeps
+     *   the contract's constructor shape)
+     * @param allocator - the context's OOM-scoped allocator
+     * @param maxBufferSize - the device's maxBufferSize (classes above it are never created)
+     * @param options - pool options
+     * @param options.maxIdlePerClass - idle buffers kept per (class, usage); default POOL_MAX_IDLE_PER_CLASS
+     */
+    constructor(_device, allocator, maxBufferSize, options) {
+        this.idle = new Map();
+        this.live = new Map();
+        this.liveBytesValue = 0;
+        this.idleBytesValue = 0;
+        this.disposed = false;
+        this.allocator = allocator;
+        this.maxBufferSize = maxBufferSize - (maxBufferSize % 4);
+        this.maxIdlePerClass = options?.maxIdlePerClass ?? POOL_MAX_IDLE_PER_CLASS;
+    }
+    /**
+     * The size class a byte length rounds up to: powers of two from 4 KiB to 64 MiB, then 16 MiB steps (pure).
+     * @param byteLength - a positive integer
+     * @returns the class in bytes
+     */
+    static sizeClass(byteLength) {
+        if (!Number.isInteger(byteLength) || byteLength <= 0) {
+            throw new WebGpuGraphError("E_INVALID_ARGUMENT", "byteLength: expected a positive integer", {
+                argument: "byteLength",
+                value: byteLength,
+                expected: "a positive integer",
+            });
+        }
+        if (byteLength > POOL_MAX_POW2_CLASS_BYTES) {
+            return Math.ceil(byteLength / POOL_LINEAR_STEP_BYTES) * POOL_LINEAR_STEP_BYTES;
+        }
+        let sizeClass = POOL_MIN_CLASS_BYTES;
+        while (sizeClass < byteLength) {
+            sizeClass *= 2;
+        }
+        return sizeClass;
+    }
+    /**
+     * Acquires a buffer of at least byteLength (an idle one of the class and usage, else a new one through the
+     * allocator); E_TOO_LARGE above maxBufferSize.
+     * @param byteLength - the bytes needed
+     * @param usage - the GPUBufferUsage flags
+     * @param label - the buffer label (a reused buffer is relabelled)
+     * @returns a buffer of the class size
+     */
+    acquire(byteLength, usage, label) {
+        if (this.disposed) {
+            throw new WebGpuGraphError("E_DISPOSED", "the buffer pool was disposed", { label: "pool" });
+        }
+        const rounded = BufferPool.sizeClass(byteLength);
+        if (byteLength > this.maxBufferSize) {
+            throw new WebGpuGraphError("E_TOO_LARGE", `pool: ${byteLength} bytes exceed the device maxBufferSize of ${this.maxBufferSize} bytes`, { needed: byteLength, limit: this.maxBufferSize, path: "pool", algorithm: null });
+        }
+        const sizeClass = Math.min(rounded, this.maxBufferSize);
+        const key = classKey(sizeClass, usage);
+        const idle = this.idle.get(key);
+        let buffer = idle?.pop();
+        if (buffer === undefined) {
+            buffer = this.allocator.createBuffer({ label, size: sizeClass, usage });
+        }
+        else {
+            this.idleBytesValue -= sizeClass;
+            buffer.label = label;
+        }
+        this.live.set(buffer, { sizeClass, usage });
+        this.liveBytesValue += sizeClass;
+        return buffer;
+    }
+    /**
+     * Returns a buffer to its class; destroys it when the class already holds maxIdlePerClass idle buffers. A no-op
+     * after destroyAll() (so a `finally` never masks the original error).
+     * @param buffer - a buffer acquired from this pool and not yet released
+     */
+    release(buffer) {
+        if (this.disposed) {
+            return;
+        }
+        const entry = this.live.get(buffer);
+        if (entry === undefined) {
+            throw new WebGpuGraphError("E_INVALID_ARGUMENT", "buffer: not a live buffer of this pool", {
+                argument: "buffer",
+                value: buffer.label,
+                expected: "a buffer acquired from this pool and not yet released",
+            });
+        }
+        this.live.delete(buffer);
+        this.liveBytesValue -= entry.sizeClass;
+        const key = classKey(entry.sizeClass, entry.usage);
+        let idle = this.idle.get(key);
+        if (idle === undefined) {
+            idle = [];
+            this.idle.set(key, idle);
+        }
+        if (idle.length >= this.maxIdlePerClass) {
+            this.allocator.destroy(buffer);
+            return;
+        }
+        idle.push(buffer);
+        this.idleBytesValue += entry.sizeClass;
+    }
+    /** Destroys every idle buffer. */
+    trim() {
+        for (const buffers of this.idle.values()) {
+            for (const buffer of buffers) {
+                this.allocator.destroy(buffer);
+            }
+        }
+        this.idle.clear();
+        this.idleBytesValue = 0;
+    }
+    /** Destroys everything, idle and live (ctx.dispose()); idempotent. @internal */
+    destroyAll() {
+        this.trim();
+        for (const buffer of this.live.keys()) {
+            this.allocator.destroy(buffer);
+        }
+        this.live.clear();
+        this.liveBytesValue = 0;
+        this.disposed = true;
+    }
+    /**
+     * A scope object that releases everything acquired through it (spec 4.4, P2).
+     * @returns a fresh lease over this pool
+     */
+    lease() {
+        return new Lease(this);
+    }
+    /**
+     * Bytes of buffers acquired and not yet released (class sizes).
+     * @returns the live byte count
+     */
+    get liveBytes() {
+        return this.liveBytesValue;
+    }
+    /**
+     * Bytes of idle buffers (class sizes).
+     * @returns the idle byte count
+     */
+    get idleBytes() {
+        return this.idleBytesValue;
+    }
+}
+//# sourceMappingURL=buffer-pool.js.map

package/dist/src/memory/buffer-pool.js.map

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

package/dist/src/memory/lease.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The Lease scope object of spec 4.4: every buffer an algorithm acquires through it goes back to the
+ * BufferPool in ONE `release()` call placed in the algorithm's `finally` block, so scratch never
+ * outlives the call that took it (a `try / finally`, not `Symbol.dispose`, until the monorepo's
+ * TypeScript target supports `using`). Persistent buffers (layout state) are owned by the simulation
+ * object instead and freed by its `dispose()`.
+ */
+import type { BufferPool } from "./buffer-pool.js";
+/** Scope object algorithms use: every buffer acquired through it is released by `release()` in a finally block (spec 4.4). */
+export declare class Lease {
+    private readonly pool;
+    private readonly buffers;
+    private released;
+    /**
+     * Creates a lease over a pool; `pool.lease()` is the usual way to get one.
+     * @param pool - the pool every acquisition of this lease goes through
+     */
+    constructor(pool: BufferPool);
+    /**
+     * pool.acquire(byteLength, STORAGE | COPY_SRC | COPY_DST, label).
+     * @param byteLength - bytes needed; the pool rounds up to its size class
+     * @param label - the buffer label
+     * @returns the buffer, returned to the pool by `release()`
+     */
+    storage(byteLength: number, label: string): GPUBuffer;
+    /**
+     * pool.acquire(byteLength, UNIFORM | COPY_DST, label).
+     * @param byteLength - bytes needed; the pool rounds up to its size class
+     * @param label - the buffer label
+     * @returns the buffer, returned to the pool by `release()`
+     */
+    uniform(byteLength: number, label: string): GPUBuffer;
+    /**
+     * pool.acquire with explicit usage.
+     * @param byteLength - bytes needed; the pool rounds up to its size class
+     * @param usage - the GPUBufferUsage bits
+     * @param label - the buffer label
+     * @returns the buffer, returned to the pool by `release()`
+     */
+    acquire(byteLength: number, usage: number, label: string): GPUBuffer;
+    /**
+     * Releases every buffer acquired through this lease; idempotent. A pool that `ctx.dispose()` already
+     * destroyed has nothing left to take back, so its E_DISPOSED is swallowed here: the lease sits in a
+     * `finally` block and must never mask the error that unwound the algorithm.
+     */
+    release(): void;
+    /**
+     * Live buffers of this lease.
+     * @returns the number of buffers acquired through the lease and not yet released
+     */
+    get count(): number;
+}
+//# sourceMappingURL=lease.d.ts.map

package/dist/src/memory/lease.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease.d.ts","sourceRoot":"","sources":["../../../src/memory/lease.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,8HAA8H;AAC9H,qBAAa,KAAK;IACd,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,QAAQ,CAAS;IAEzB;;;OAGG;gBACS,IAAI,EAAE,UAAU;IAI5B;;;;;OAKG;IACH,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS;IAIrD;;;;;OAKG;IACH,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS;IAIrD;;;;;;OAMG;IACH,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS;IASpE;;;;OAIG;IACH,OAAO,IAAI,IAAI;IAkBf;;;OAGG;IACH,IAAI,KAAK,IAAI,MAAM,CAElB;CACJ"}

package/dist/src/memory/lease.js

@@ -0,0 +1,85 @@
+/**
+ * The Lease scope object of spec 4.4: every buffer an algorithm acquires through it goes back to the
+ * BufferPool in ONE `release()` call placed in the algorithm's `finally` block, so scratch never
+ * outlives the call that took it (a `try / finally`, not `Symbol.dispose`, until the monorepo's
+ * TypeScript target supports `using`). Persistent buffers (layout state) are owned by the simulation
+ * object instead and freed by its `dispose()`.
+ */
+import { BufferUsage } from "../device/webgpu-constants.js";
+import { hasErrorCode, WebGpuGraphError } from "../errors.js";
+/** Scope object algorithms use: every buffer acquired through it is released by `release()` in a finally block (spec 4.4). */
+export class Lease {
+    /**
+     * Creates a lease over a pool; `pool.lease()` is the usual way to get one.
+     * @param pool - the pool every acquisition of this lease goes through
+     */
+    constructor(pool) {
+        this.buffers = new Set();
+        this.released = false;
+        this.pool = pool;
+    }
+    /**
+     * pool.acquire(byteLength, STORAGE | COPY_SRC | COPY_DST, label).
+     * @param byteLength - bytes needed; the pool rounds up to its size class
+     * @param label - the buffer label
+     * @returns the buffer, returned to the pool by `release()`
+     */
+    storage(byteLength, label) {
+        return this.acquire(byteLength, BufferUsage.STORAGE | BufferUsage.COPY_SRC | BufferUsage.COPY_DST, label);
+    }
+    /**
+     * pool.acquire(byteLength, UNIFORM | COPY_DST, label).
+     * @param byteLength - bytes needed; the pool rounds up to its size class
+     * @param label - the buffer label
+     * @returns the buffer, returned to the pool by `release()`
+     */
+    uniform(byteLength, label) {
+        return this.acquire(byteLength, BufferUsage.UNIFORM | BufferUsage.COPY_DST, label);
+    }
+    /**
+     * pool.acquire with explicit usage.
+     * @param byteLength - bytes needed; the pool rounds up to its size class
+     * @param usage - the GPUBufferUsage bits
+     * @param label - the buffer label
+     * @returns the buffer, returned to the pool by `release()`
+     */
+    acquire(byteLength, usage, label) {
+        if (this.released) {
+            throw new WebGpuGraphError("E_DISPOSED", `lease already released: cannot acquire "${label}"`, { label });
+        }
+        const buffer = this.pool.acquire(byteLength, usage, label);
+        this.buffers.add(buffer);
+        return buffer;
+    }
+    /**
+     * Releases every buffer acquired through this lease; idempotent. A pool that `ctx.dispose()` already
+     * destroyed has nothing left to take back, so its E_DISPOSED is swallowed here: the lease sits in a
+     * `finally` block and must never mask the error that unwound the algorithm.
+     */
+    release() {
+        if (this.released) {
+            return;
+        }
+        this.released = true;
+        const owned = [...this.buffers];
+        this.buffers.clear();
+        for (const buffer of owned) {
+            try {
+                this.pool.release(buffer);
+            }
+            catch (error) {
+                if (!hasErrorCode(error, "E_DISPOSED")) {
+                    throw error;
+                }
+            }
+        }
+    }
+    /**
+     * Live buffers of this lease.
+     * @returns the number of buffers acquired through the lease and not yet released
+     */
+    get count() {
+        return this.buffers.size;
+    }
+}
+//# sourceMappingURL=lease.js.map

package/dist/src/memory/lease.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease.js","sourceRoot":"","sources":["../../../src/memory/lease.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAG9D,8HAA8H;AAC9H,MAAM,OAAO,KAAK;IAKd;;;OAGG;IACH,YAAY,IAAgB;QAPX,YAAO,GAAG,IAAI,GAAG,EAAa,CAAC;QACxC,aAAQ,GAAG,KAAK,CAAC;QAOrB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACrB,CAAC;IAED;;;;;OAKG;IACH,OAAO,CAAC,UAAkB,EAAE,KAAa;QACrC,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,WAAW,CAAC,OAAO,GAAG,WAAW,CAAC,QAAQ,GAAG,WAAW,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAC9G,CAAC;IAED;;;;;OAKG;IACH,OAAO,CAAC,UAAkB,EAAE,KAAa;QACrC,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,WAAW,CAAC,OAAO,GAAG,WAAW,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IACvF,CAAC;IAED;;;;;;OAMG;IACH,OAAO,CAAC,UAAkB,EAAE,KAAa,EAAE,KAAa;QACpD,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAChB,MAAM,IAAI,gBAAgB,CAAC,YAAY,EAAE,2CAA2C,KAAK,GAAG,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QAC7G,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;QAC3D,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACzB,OAAO,MAAM,CAAC;IAClB,CAAC;IAED;;;;OAIG;IACH,OAAO;QACH,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAChB,OAAO;QACX,CAAC;QACD,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACrB,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;QAChC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACrB,KAAK,MAAM,MAAM,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,CAAC;gBACD,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YAC9B,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACb,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,YAAY,CAAC,EAAE,CAAC;oBACrC,MAAM,KAAK,CAAC;gBAChB,CAAC;YACL,CAAC;QACL,CAAC;IACL,CAAC;IAED;;;OAGG;IACH,IAAI,KAAK;QACL,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;IAC7B,CAAC;CACJ"}