@graphty/webgpu-graph-algorithms 0.0.0 → 0.2.0

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

@@ -0,0 +1,143 @@
+/**
+ * The staging ring of spec 4.4: a ring of MAP_READ | COPY_DST buffers (default DEFAULT_STAGING_SLOTS slots of 4 MiB,
+ * PLAN DECISION 15) through which every readback of the package flows. `read()` copies with its own encoder and
+ * submit, awaits mapAsync, copies out of the mapped range BEFORE unmap (the range is detached at unmap, design 10.7)
+ * and never polls onSubmittedWorkDone; requests above the slot size are chunked. Ownership is one-directional: the
+ * ring owns its buffers; a CommandBatch (P2) BORROWS one slot through borrowSlot, maps it through mapSlot and always
+ * returns it through returnSlot, which unmaps it. Slots at or above OOM_SCOPE_THRESHOLD_BYTES are created through the
+ * AllocationTracker (the out-of-memory scope of spec 5.7), the default-size ones directly on the device, so the
+ * allocator counts residency and pool buffers only. A mapAsync rejection is E_DEVICE_LOST (or E_DISPOSED after
+ * destroyAll).
+ *
+ * The one invariant every path keeps: a staging buffer whose mapAsync is PENDING is never unmapped and never
+ * destroyed. dawn-node 0.4.0 settles the pending promise synchronously on unmap() / destroy() and settles it a
+ * second time when Dawn's map callback arrives (a SIGSEGV in AsyncRunner::Reject); on the Vulkan backends the
+ * callback has already run inside device.destroy(), on Dawn's Metal backend it arrives after the device-lost
+ * fan-out, which is where the macOS host lane lost its vitest worker (CLAUDE.md "Verified Platform Facts"). The
+ * ring therefore tracks every map on its slots (mapPending) and defers an unmap, a return or a destroy that
+ * arrives during one to the moment the map settles.
+ */
+import { type AllocationTracker } from "../device/error-scope.js";
+/**
+ * One MAP_READ | COPY_DST staging buffer of the ring. Exported for the borrowers of borrowSlot / returnSlot
+ * (contract 3.8): P2-T1's CommandBatch imports it as a type; nothing at P1 imports it by name.
+ * @public
+ */
+export interface StagingSlot {
+    readonly index: number;
+    readonly buffer: GPUBuffer;
+    readonly capacity: number;
+}
+/** The staging ring (spec 4.4): default 3 slots; grows when every slot is busy; always unmaps and destroys its own buffers. */
+export declare class Readback {
+    private readonly device;
+    private readonly allocator;
+    private readonly slotBytes;
+    private readonly ring;
+    private disposed;
+    /**
+     * Creates the ring with `slots` slots of `slotBytes` each.
+     * @param device - the device the copies run on
+     * @param allocator - the context's OOM-scoped allocator (used for slots at or above OOM_SCOPE_THRESHOLD_BYTES)
+     * @param options - ring options
+     * @param options.slots - slots created up front; default DEFAULT_STAGING_SLOTS
+     * @param options.slotBytes - capacity of each slot and the chunk size of read(); default 4 MiB; a positive multiple of 4
+     */
+    constructor(device: GPUDevice, allocator: AllocationTracker, options?: {
+        readonly slots?: number | undefined;
+        readonly slotBytes?: number | undefined;
+    });
+    /**
+     * Copies `byteLength` bytes from `src` at `srcOffset` (own encoder, own submit), maps, copies out BEFORE unmap;
+     * resolves the bytes (a fresh ArrayBuffer, or `dest.buffer` after `dest.set` when given). Requests above the slot
+     * size are chunked.
+     * @param src - a COPY_SRC buffer
+     * @param byteLength - bytes to read (a positive multiple of 4, within src)
+     * @param dest - an optional destination view of at least byteLength bytes over a plain ArrayBuffer
+     * @param srcOffset - the byte offset in src (default 0; a multiple of 4)
+     * @returns the bytes read
+     */
+    read(src: GPUBuffer, byteLength: number, dest?: ArrayBufferView, srcOffset?: number): Promise<ArrayBuffer>;
+    /**
+     * Reads one u32 counter through the same ring.
+     * @param src - a COPY_SRC buffer
+     * @param byteOffset - the counter's byte offset (a multiple of 4)
+     * @returns the counter value
+     */
+    readU32(src: GPUBuffer, byteOffset: number): Promise<number>;
+    /**
+     * Borrows an unmapped slot of at least byteLength (grows the ring when none is free); the borrower ALWAYS
+     * returns it (spec 4.4).
+     * @param byteLength - the bytes the borrower will copy into the slot
+     * @returns the slot
+     */
+    borrowSlot(byteLength: number): StagingSlot;
+    /**
+     * mapAsync(READ) on a borrowed slot, tracked by the ring: the slot counts as borrowed, and is neither unmapped
+     * nor destroyed, until the map settles (see the file comment). Returns the runtime's own promise, untranslated:
+     * the borrower classifies a rejection (a CommandBatch races it against device loss, spec 5.7).
+     * @param slot - a slot borrowed from this ring and not yet returned
+     * @param byteLength - the bytes to map from offset 0
+     * @returns the mapAsync promise
+     */
+    mapSlot(slot: StagingSlot, byteLength: number): Promise<void>;
+    /**
+     * Returns a borrowed slot (unmapping it if mapped). A slot whose map through the ring is still pending stays
+     * borrowed until the map settles, when the ring unmaps and returns it; a borrower that maps a slot itself must
+     * unmap it before returning it (spec 4.4; `mapState` decides when the runtime exposes it, otherwise the ring's
+     * own record does). A no-op after destroyAll() (the ring is gone; a borrower's finally must never mask the
+     * E_DISPOSED / E_DEVICE_LOST of the read it was serving).
+     * @param slot - a slot borrowed from this ring and not yet returned
+     */
+    returnSlot(slot: StagingSlot): void;
+    /**
+     * The entry of a slot borrowed from this ring and not yet returned.
+     * @param slot - the slot
+     * @returns its entry
+     */
+    private borrowedEntry;
+    /**
+     * Unmaps a returned slot when it is mapped and frees it.
+     * @param entry - the slot's entry (no map pending)
+     */
+    private finishReturn;
+    /**
+     * Tracks one mapAsync on a slot: mapPending until it settles, then the deferred work -- the destruction
+     * destroyAll() left to the settle, or the return returnSlot() left to it. The handler is attached before the
+     * promise is handed out, so it runs before any borrower's continuation.
+     * @param entry - the slot's entry
+     * @param pending - the runtime's mapAsync promise
+     * @returns the same promise
+     */
+    private track;
+    /**
+     * Number of slots (grows).
+     * @returns the slot count
+     */
+    get slots(): number;
+    /**
+     * Slots currently borrowed.
+     * @returns the borrowed count
+     */
+    get borrowed(): number;
+    /**
+     * Destroys one slot's buffer through the allocator when it was created there.
+     * @param entry - the slot
+     */
+    private destroySlot;
+    /**
+     * Creates one slot at the end of the ring.
+     * @param capacity - the slot's byte capacity
+     * @returns the new entry
+     */
+    private addSlot;
+    /**
+     * mapAsync(READ) on a slot for read(); a rejection becomes E_DISPOSED (after destroyAll) or E_DEVICE_LOST.
+     * @param entry - the ring entry of the borrowed slot
+     * @param byteLength - the bytes to map
+     */
+    private map;
+    /** Throws E_DISPOSED after destroyAll(). */
+    private assertLive;
+}
+//# sourceMappingURL=readback.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"readback.d.ts","sourceRoot":"","sources":["../../../src/memory/readback.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAalE;;;;GAIG;AACH,MAAM,WAAW,WAAW;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC7B;AAwCD,+HAA+H;AAC/H,qBAAa,QAAQ;IACjB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoB;IAC9C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAmB;IACxC,OAAO,CAAC,QAAQ,CAAS;IAEzB;;;;;;;OAOG;gBAEC,MAAM,EAAE,SAAS,EACjB,SAAS,EAAE,iBAAiB,EAC5B,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE;IAkB9F;;;;;;;;;OASG;IACG,IAAI,CAAC,GAAG,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,eAAe,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAiDhH;;;;;OAKG;IACG,OAAO,CAAC,GAAG,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAKlE;;;;;OAKG;IACH,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,WAAW;IAkB3C;;;;;;;OAOG;IACH,OAAO,CAAC,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS7D;;;;;;;OAOG;IACH,UAAU,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI;IAYnC;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAQrB;;;OAGG;IACH,OAAO,CAAC,YAAY;IAWpB;;;;;;;OAOG;IACH,OAAO,CAAC,KAAK;IA4Bb;;;OAGG;IACH,IAAI,KAAK,IAAI,MAAM,CAElB;IAED;;;OAGG;IACH,IAAI,QAAQ,IAAI,MAAM,CAQrB;IAoBD;;;OAGG;IACH,OAAO,CAAC,WAAW;IAQnB;;;;OAIG;IACH,OAAO,CAAC,OAAO;IAqBf;;;;OAIG;YACW,GAAG;IAwBjB,4CAA4C;IAC5C,OAAO,CAAC,UAAU;CAKrB"}

package/dist/src/memory/readback.js

@@ -0,0 +1,375 @@
+/**
+ * The staging ring of spec 4.4: a ring of MAP_READ | COPY_DST buffers (default DEFAULT_STAGING_SLOTS slots of 4 MiB,
+ * PLAN DECISION 15) through which every readback of the package flows. `read()` copies with its own encoder and
+ * submit, awaits mapAsync, copies out of the mapped range BEFORE unmap (the range is detached at unmap, design 10.7)
+ * and never polls onSubmittedWorkDone; requests above the slot size are chunked. Ownership is one-directional: the
+ * ring owns its buffers; a CommandBatch (P2) BORROWS one slot through borrowSlot, maps it through mapSlot and always
+ * returns it through returnSlot, which unmaps it. Slots at or above OOM_SCOPE_THRESHOLD_BYTES are created through the
+ * AllocationTracker (the out-of-memory scope of spec 5.7), the default-size ones directly on the device, so the
+ * allocator counts residency and pool buffers only. A mapAsync rejection is E_DEVICE_LOST (or E_DISPOSED after
+ * destroyAll).
+ *
+ * The one invariant every path keeps: a staging buffer whose mapAsync is PENDING is never unmapped and never
+ * destroyed. dawn-node 0.4.0 settles the pending promise synchronously on unmap() / destroy() and settles it a
+ * second time when Dawn's map callback arrives (a SIGSEGV in AsyncRunner::Reject); on the Vulkan backends the
+ * callback has already run inside device.destroy(), on Dawn's Metal backend it arrives after the device-lost
+ * fan-out, which is where the macOS host lane lost its vitest worker (CLAUDE.md "Verified Platform Facts"). The
+ * ring therefore tracks every map on its slots (mapPending) and defers an unmap, a return or a destroy that
+ * arrives during one to the moment the map settles.
+ */
+import { DEFAULT_STAGING_SLOTS, OOM_SCOPE_THRESHOLD_BYTES } from "../constants.js";
+import { BufferUsage, MapMode } from "../device/webgpu-constants.js";
+import { WebGpuGraphError } from "../errors.js";
+/** Default capacity of one staging slot (PLAN DECISION 15). */
+const DEFAULT_SLOT_BYTES = 4 * 1024 * 1024;
+/** Every staging buffer is MAP_READ | COPY_DST. */
+const STAGING_USAGE = BufferUsage.MAP_READ | BufferUsage.COPY_DST;
+/** Grown slots are sized in 256-byte steps. */
+const SLOT_GRANULE = 256;
+/**
+ * Whether an ArrayBuffer-like is a SharedArrayBuffer (checked by tag so the global need not exist).
+ * @param buffer - the buffer to test
+ * @returns true for a SharedArrayBuffer
+ */
+function isSharedBuffer(buffer) {
+    return Object.prototype.toString.call(buffer) === "[object SharedArrayBuffer]";
+}
+/**
+ * The E_INVALID_ARGUMENT error of a bad readback argument.
+ * @param argument - the argument name
+ * @param value - the value given
+ * @param expected - what was expected
+ * @returns the error to throw
+ */
+function invalid(argument, value, expected) {
+    return new WebGpuGraphError("E_INVALID_ARGUMENT", `${argument}: expected ${expected}`, {
+        argument,
+        value,
+        expected,
+    });
+}
+/** The staging ring (spec 4.4): default 3 slots; grows when every slot is busy; always unmaps and destroys its own buffers. */
+export class Readback {
+    /**
+     * Creates the ring with `slots` slots of `slotBytes` each.
+     * @param device - the device the copies run on
+     * @param allocator - the context's OOM-scoped allocator (used for slots at or above OOM_SCOPE_THRESHOLD_BYTES)
+     * @param options - ring options
+     * @param options.slots - slots created up front; default DEFAULT_STAGING_SLOTS
+     * @param options.slotBytes - capacity of each slot and the chunk size of read(); default 4 MiB; a positive multiple of 4
+     */
+    constructor(device, allocator, options) {
+        this.ring = [];
+        this.disposed = false;
+        const slotBytes = options?.slotBytes ?? DEFAULT_SLOT_BYTES;
+        if (!Number.isInteger(slotBytes) || slotBytes <= 0 || slotBytes % 4 !== 0) {
+            throw invalid("slotBytes", slotBytes, "a positive multiple of 4");
+        }
+        const slots = options?.slots ?? DEFAULT_STAGING_SLOTS;
+        if (!Number.isInteger(slots) || slots < 0) {
+            throw invalid("slots", slots, "a non-negative integer");
+        }
+        this.device = device;
+        this.allocator = allocator;
+        this.slotBytes = slotBytes;
+        for (let i = 0; i < slots; i++) {
+            this.addSlot(slotBytes);
+        }
+    }
+    /**
+     * Copies `byteLength` bytes from `src` at `srcOffset` (own encoder, own submit), maps, copies out BEFORE unmap;
+     * resolves the bytes (a fresh ArrayBuffer, or `dest.buffer` after `dest.set` when given). Requests above the slot
+     * size are chunked.
+     * @param src - a COPY_SRC buffer
+     * @param byteLength - bytes to read (a positive multiple of 4, within src)
+     * @param dest - an optional destination view of at least byteLength bytes over a plain ArrayBuffer
+     * @param srcOffset - the byte offset in src (default 0; a multiple of 4)
+     * @returns the bytes read
+     */
+    async read(src, byteLength, dest, srcOffset) {
+        this.assertLive();
+        const offset = srcOffset ?? 0;
+        if (!Number.isInteger(byteLength) || byteLength <= 0 || byteLength % 4 !== 0) {
+            throw invalid("byteLength", byteLength, "a positive multiple of 4");
+        }
+        if (!Number.isInteger(offset) || offset < 0 || offset % 4 !== 0) {
+            throw invalid("srcOffset", offset, "a non-negative multiple of 4");
+        }
+        if (offset + byteLength > src.size) {
+            throw invalid("byteLength", byteLength, `srcOffset + byteLength <= src.size (${src.size})`);
+        }
+        if ((src.usage & BufferUsage.COPY_SRC) === 0) {
+            throw invalid("src", src.label, "a buffer with COPY_SRC usage");
+        }
+        let out;
+        let outBytes;
+        if (dest === undefined) {
+            out = new ArrayBuffer(byteLength);
+            outBytes = new Uint8Array(out);
+        }
+        else {
+            if (isSharedBuffer(dest.buffer)) {
+                throw invalid("dest", "SharedArrayBuffer", "a view over a plain ArrayBuffer");
+            }
+            if (dest.byteLength < byteLength) {
+                throw invalid("dest", dest.byteLength, `at least ${byteLength} bytes`);
+            }
+            out = dest.buffer;
+            outBytes = new Uint8Array(out, dest.byteOffset, byteLength);
+        }
+        let done = 0;
+        while (done < byteLength) {
+            const chunk = Math.min(this.slotBytes, byteLength - done);
+            const slot = this.borrowSlot(chunk);
+            const entry = this.ring[slot.index];
+            try {
+                const encoder = this.device.createCommandEncoder({ label: "readback" });
+                encoder.copyBufferToBuffer(src, offset + done, slot.buffer, 0, chunk);
+                this.device.queue.submit([encoder.finish()]);
+                await this.map(entry, chunk);
+                outBytes.set(new Uint8Array(slot.buffer.getMappedRange(0, chunk)), done);
+            }
+            finally {
+                this.returnSlot(slot);
+            }
+            done += chunk;
+        }
+        return out;
+    }
+    /**
+     * Reads one u32 counter through the same ring.
+     * @param src - a COPY_SRC buffer
+     * @param byteOffset - the counter's byte offset (a multiple of 4)
+     * @returns the counter value
+     */
+    async readU32(src, byteOffset) {
+        const bytes = await this.read(src, 4, undefined, byteOffset);
+        return new Uint32Array(bytes)[0];
+    }
+    /**
+     * Borrows an unmapped slot of at least byteLength (grows the ring when none is free); the borrower ALWAYS
+     * returns it (spec 4.4).
+     * @param byteLength - the bytes the borrower will copy into the slot
+     * @returns the slot
+     */
+    borrowSlot(byteLength) {
+        this.assertLive();
+        if (!Number.isInteger(byteLength) || byteLength <= 0) {
+            throw invalid("byteLength", byteLength, "a positive integer");
+        }
+        // a free slot is unmapped by construction: returnSlot unmaps, and only a borrower maps
+        for (const entry of this.ring) {
+            if (!entry.borrowed && entry.slot.capacity >= byteLength) {
+                entry.borrowed = true;
+                return entry.slot;
+            }
+        }
+        const capacity = Math.max(this.slotBytes, Math.ceil(byteLength / SLOT_GRANULE) * SLOT_GRANULE);
+        const entry = this.addSlot(capacity);
+        entry.borrowed = true;
+        return entry.slot;
+    }
+    /**
+     * mapAsync(READ) on a borrowed slot, tracked by the ring: the slot counts as borrowed, and is neither unmapped
+     * nor destroyed, until the map settles (see the file comment). Returns the runtime's own promise, untranslated:
+     * the borrower classifies a rejection (a CommandBatch races it against device loss, spec 5.7).
+     * @param slot - a slot borrowed from this ring and not yet returned
+     * @param byteLength - the bytes to map from offset 0
+     * @returns the mapAsync promise
+     */
+    mapSlot(slot, byteLength) {
+        this.assertLive();
+        const entry = this.borrowedEntry(slot);
+        if (entry.mapPending || entry.mapped) {
+            throw invalid("slot", slot.index, "a borrowed slot that is not mapped and has no map pending");
+        }
+        return this.track(entry, slot.buffer.mapAsync(MapMode.READ, 0, byteLength));
+    }
+    /**
+     * Returns a borrowed slot (unmapping it if mapped). A slot whose map through the ring is still pending stays
+     * borrowed until the map settles, when the ring unmaps and returns it; a borrower that maps a slot itself must
+     * unmap it before returning it (spec 4.4; `mapState` decides when the runtime exposes it, otherwise the ring's
+     * own record does). A no-op after destroyAll() (the ring is gone; a borrower's finally must never mask the
+     * E_DISPOSED / E_DEVICE_LOST of the read it was serving).
+     * @param slot - a slot borrowed from this ring and not yet returned
+     */
+    returnSlot(slot) {
+        if (this.disposed) {
+            return;
+        }
+        const entry = this.borrowedEntry(slot);
+        if (entry.mapPending) {
+            entry.returnRequested = true;
+            return;
+        }
+        this.finishReturn(entry);
+    }
+    /**
+     * The entry of a slot borrowed from this ring and not yet returned.
+     * @param slot - the slot
+     * @returns its entry
+     */
+    borrowedEntry(slot) {
+        const entry = this.ring[slot.index];
+        if (entry === undefined || entry.slot !== slot || !entry.borrowed) {
+            throw invalid("slot", slot.index, "a slot borrowed from this ring and not yet returned");
+        }
+        return entry;
+    }
+    /**
+     * Unmaps a returned slot when it is mapped and frees it.
+     * @param entry - the slot's entry (no map pending)
+     */
+    finishReturn(entry) {
+        const state = entry.slot.buffer.mapState;
+        const mapped = state === undefined ? entry.mapped : state !== "unmapped";
+        if (mapped) {
+            entry.slot.buffer.unmap();
+        }
+        entry.mapped = false;
+        entry.borrowed = false;
+        entry.returnRequested = false;
+    }
+    /**
+     * Tracks one mapAsync on a slot: mapPending until it settles, then the deferred work -- the destruction
+     * destroyAll() left to the settle, or the return returnSlot() left to it. The handler is attached before the
+     * promise is handed out, so it runs before any borrower's continuation.
+     * @param entry - the slot's entry
+     * @param pending - the runtime's mapAsync promise
+     * @returns the same promise
+     */
+    track(entry, pending) {
+        entry.mapPending = true;
+        const settle = (mapped) => {
+            entry.mapPending = false;
+            entry.mapped = mapped;
+            if (this.disposed) {
+                if (mapped) {
+                    entry.slot.buffer.unmap();
+                }
+                this.destroySlot(entry);
+                entry.mapped = false;
+                return;
+            }
+            if (entry.returnRequested) {
+                this.finishReturn(entry);
+            }
+        };
+        void pending.then(() => {
+            settle(true);
+        }, () => {
+            settle(false);
+        });
+        return pending;
+    }
+    /**
+     * Number of slots (grows).
+     * @returns the slot count
+     */
+    get slots() {
+        return this.ring.length;
+    }
+    /**
+     * Slots currently borrowed.
+     * @returns the borrowed count
+     */
+    get borrowed() {
+        let count = 0;
+        for (const entry of this.ring) {
+            if (entry.borrowed) {
+                count++;
+            }
+        }
+        return count;
+    }
+    /**
+     * Destroys every staging buffer (ctx.dispose()); idempotent. A slot whose mapAsync is still pending is NOT
+     * destroyed here (the file comment: dawn-node 0.4.0 settles the promise twice); its destruction is deferred to
+     * the moment the map settles (track()), where a pending read() still rejects with E_DISPOSED as the contract
+     * promises.
+     * @internal
+     */
+    destroyAll() {
+        for (const entry of this.ring) {
+            if (entry.mapPending) {
+                continue;
+            }
+            this.destroySlot(entry);
+        }
+        this.ring.length = 0;
+        this.disposed = true;
+    }
+    /**
+     * Destroys one slot's buffer through the allocator when it was created there.
+     * @param entry - the slot
+     */
+    destroySlot(entry) {
+        if (entry.tracked) {
+            this.allocator.destroy(entry.slot.buffer);
+        }
+        else {
+            entry.slot.buffer.destroy();
+        }
+    }
+    /**
+     * Creates one slot at the end of the ring.
+     * @param capacity - the slot's byte capacity
+     * @returns the new entry
+     */
+    addSlot(capacity) {
+        const index = this.ring.length;
+        const descriptor = {
+            label: `readback:slot:${index}`,
+            size: capacity,
+            usage: STAGING_USAGE,
+        };
+        const tracked = capacity >= OOM_SCOPE_THRESHOLD_BYTES;
+        const buffer = tracked ? this.allocator.createBuffer(descriptor) : this.device.createBuffer(descriptor);
+        const entry = {
+            slot: Object.freeze({ index, buffer, capacity }),
+            borrowed: false,
+            mapped: false,
+            mapPending: false,
+            returnRequested: false,
+            tracked,
+        };
+        this.ring.push(entry);
+        return entry;
+    }
+    /**
+     * mapAsync(READ) on a slot for read(); a rejection becomes E_DISPOSED (after destroyAll) or E_DEVICE_LOST.
+     * @param entry - the ring entry of the borrowed slot
+     * @param byteLength - the bytes to map
+     */
+    async map(entry, byteLength) {
+        let mapped = false;
+        let failure = null;
+        try {
+            await this.track(entry, entry.slot.buffer.mapAsync(MapMode.READ, 0, byteLength));
+            mapped = true;
+        }
+        catch (err) {
+            failure = err;
+        }
+        if (this.disposed) {
+            // destroyAll() ran while the map was pending: track() finished the deferred destruction just before this
+            throw new WebGpuGraphError("E_DISPOSED", "the readback ring was disposed while a read was pending", {
+                label: "readback",
+            });
+        }
+        if (!mapped) {
+            const message = failure instanceof Error ? failure.message : String(failure);
+            throw new WebGpuGraphError("E_DEVICE_LOST", `mapAsync rejected: ${message}`, {
+                reason: "mapAsync",
+                message,
+            });
+        }
+    }
+    /** Throws E_DISPOSED after destroyAll(). */
+    assertLive() {
+        if (this.disposed) {
+            throw new WebGpuGraphError("E_DISPOSED", "the readback ring was disposed", { label: "readback" });
+        }
+    }
+}
+//# sourceMappingURL=readback.js.map

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

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

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

@@ -0,0 +1,83 @@
+/**
+ * The upload cache of spec 4.1 / 4.3 / 4.5: every core array, view array, column and ad hoc array a kernel binds
+ * lives on the device exactly once per snapshot core, keyed on the typed-array object (or the Column object for
+ * columns, PLAN DECISION 8), recorded per serial so `release(snapshot)` destroys every buffer of a snapshot and its
+ * withColumns() siblings, and tombstoned so a live user learns of the release through `isReleased` (spec 4.5).
+ * Uploads follow the pure planner of ./upload-plan.ts: the arena path writes ONE buffer with ONE writeBuffer of the
+ * hot prefix (or the full arena when a cold segment is needed and fits) and binds segments at
+ * `segment.byteOffset - arena.byteOffset`; the perArray path writes one buffer per array; a windowed plan is
+ * E_TOO_LARGE until P4 executes windows (PLAN DECISION 2). Identity permutations are never materialised: presence is
+ * decided from counts and flags, and the arcToEdge / edgeToArc getters are read only when a segment exists. Nothing
+ * is freed by garbage collection; the once-only warning above warnUnreleasedSnapshots names the missing release.
+ */
+import { type Column, type GpuEligibility, type GraphSnapshot } from "@graphty/graph-format";
+import { type ArcWindow, type Binding } from "../types/memory.js";
+/**
+ * The core arrays of a snapshot on the device (spec 4.1); a null member is absent (zero-length, unweighted or an
+ * identity permutation) and is bound as a dummy by the kernel layer (3.9). `Binding` itself is declared in
+ * src/types/memory.ts (3.3). Exported by contract 3.8: P1-T4's graphBindings / graphOverrides and every later
+ * kernel driver take it; nothing at P1-T2 imports it by name.
+ * @public
+ */
+export interface CoreBinding {
+    readonly serial: number;
+    readonly plan: "arena" | "perArray" | "windowed";
+    readonly rowPtr: Binding;
+    readonly colIdx: Binding | null;
+    readonly weights: Binding | null;
+    readonly arcToEdge: Binding | null;
+    readonly edgeToArc: Binding | null;
+    readonly windows: readonly ArcWindow[] | null;
+    readonly hasWeights: boolean;
+}
+/**
+ * A view's arrays on the device plus the CPU-side scalars (degreeOrder's segmentOffsets) (spec 4.3). Exported by
+ * contract 3.8: the degreeOrder permutation of P4's kernels is a ViewBinding; nothing at P1-T2 imports it by name.
+ * @public
+ */
+export interface ViewBinding {
+    readonly view: "reverse" | "coo" | "edgeList" | "outDegree" | "inDegree" | "degreeOrder" | "reverseDegreeOrder" | "mate";
+    readonly bindings: Readonly<Record<string, Binding>>;
+    readonly scalars: Readonly<Record<string, readonly number[]>>;
+}
+/**
+ * A column's gpuView() on the device (spec 4.3). Exported by contract 3.8: P3's layout inputs register columns
+ * through it; nothing at P1-T2 imports it by name.
+ * @public
+ */
+export interface ColumnBinding {
+    readonly binding: Binding;
+    readonly column: Column;
+    readonly version: number;
+    readonly eligibility: GpuEligibility;
+    readonly components: number;
+}
+/**
+ * An ad hoc array on the device (spec 4.1 last row); `destroy()` is the caller's when no owner was given. Exported
+ * by contract 3.8: P3's model resolves column inputs to a registered ArrayBinding; nothing at P1-T2 imports it by
+ * name.
+ * @public
+ */
+export interface ArrayBinding {
+    readonly binding: Binding;
+    readonly byteLength: number;
+    readonly owner: GraphSnapshot | null;
+    destroy(): void;
+}
+/**
+ * stats() shape (spec 4.1). Exported by contract 3.8 for the callers of ctx.residency.stats(); nothing at P1-T2
+ * imports it by name.
+ * @public
+ */
+export interface ResidencyStats {
+    readonly buffers: number;
+    readonly bytes: number;
+    readonly snapshots: number;
+    readonly perSnapshot: readonly {
+        readonly serial: number;
+        readonly label: string | null;
+        readonly bytes: number;
+        readonly buffers: number;
+    }[];
+}
+//# sourceMappingURL=residency.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"residency.d.ts","sourceRoot":"","sources":["../../../src/memory/residency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAEH,KAAK,MAAM,EAEX,KAAK,cAAc,EACnB,KAAK,aAAa,EAErB,MAAM,uBAAuB,CAAC;AAM/B,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAYlE;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,UAAU,GAAG,UAAU,CAAC;IACjD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,SAAS,SAAS,EAAE,GAAG,IAAI,CAAC;IAC9C,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAChC;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IACxB,QAAQ,CAAC,IAAI,EACT,SAAS,GAAG,KAAK,GAAG,UAAU,GAAG,WAAW,GAAG,UAAU,GAAG,aAAa,GAAG,oBAAoB,GAAG,MAAM,CAAC;IAC9G,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACrD,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC;CACjE;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,cAAc,CAAC;IACrC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;IACrC,OAAO,IAAI,IAAI,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,SAAS;QAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;QAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;KAC5B,EAAE,CAAC;CACP"}