@aardworx/wombat.rendering 0.9.33 → 0.19.0

package/dist/runtime/heapScene/chunkedArena.js.map

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

package/dist/runtime/heapScene/freelist.d.ts

@@ -0,0 +1,55 @@
+/**
+ * A best-fit free-block manager. All offsets and sizes are in the
+ * caller's units (bytes for the attribute arena, u32 elements for
+ * the index allocator); the freelist doesn't interpret them.
+ */
+export declare class Freelist {
+    /** size → set of starting offsets currently free at that size. */
+    private readonly bySize;
+    /** Sorted ascending list of every size present in `bySize`. */
+    private readonly sizes;
+    /** off → size, for the right-coalesce probe in `release`. */
+    private readonly byStart;
+    /** off+size (= end offset) → off, for the left-coalesce probe. */
+    private readonly byEnd;
+    /** Number of distinct free blocks currently tracked. */
+    get blockCount(): number;
+    /**
+     * Return any offset of a free block whose size is ≥ `size`, splitting
+     * off any leftover bytes back into the freelist. Returns `undefined`
+     * when no block fits.
+     */
+    alloc(size: number): number | undefined;
+    /**
+     * Reintroduce a `(off, size)` block, coalescing with any immediate
+     * neighbour on the left (some other block ending at `off`) or right
+     * (some other block starting at `off + size`).
+     */
+    release(off: number, size: number): void;
+    /**
+     * Take and remove the free block whose end offset is exactly
+     * `endOff`, if any exists. Used by `AttributeArena` /
+     * `IndexAllocator` to shrink the bump cursor back when releases
+     * expose a free tail (§5 — cursor-shrink hygiene for long-lived
+     * high-churn scenes).
+     */
+    takeBlockEndingAt(endOff: number): {
+        off: number;
+        size: number;
+    } | undefined;
+    /** Drop every block. */
+    clear(): void;
+    /** Snapshot for tests / debugging — sorted by offset. */
+    toArray(): Array<{
+        off: number;
+        size: number;
+    }>;
+    /** Internal consistency check (paranoia mode). Walks the freelist
+     *  and asserts no two blocks overlap. O(N log N). Cheap enough to
+     *  run after every alloc/release while debugging an allocator
+     *  invariant violation. Throws with the offending pair on failure. */
+    assertInvariants(where: string): void;
+    private addBlock;
+    private removeBlock;
+}
+//# sourceMappingURL=freelist.d.ts.map

package/dist/runtime/heapScene/freelist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"freelist.d.ts","sourceRoot":"","sources":["../../../src/runtime/heapScene/freelist.ts"],"names":[],"mappings":"AA+BA;;;;GAIG;AACH,qBAAa,QAAQ;IACnB,kEAAkE;IAClE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;IACzD,+DAA+D;IAC/D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;IACtC,6DAA6D;IAC7D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IACrD,kEAAkE;IAClE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA6B;IAEnD,wDAAwD;IACxD,IAAI,UAAU,IAAI,MAAM,CAA8B;IAEtD;;;;OAIG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAavC;;;;OAIG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAqBxC;;;;;;OAMG;IACH,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS;IAQ5E,wBAAwB;IACxB,KAAK,IAAI,IAAI;IAOb,yDAAyD;IACzD,OAAO,IAAI,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAO/C;;;0EAGsE;IACtE,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IA+BrC,OAAO,CAAC,QAAQ;IAahB,OAAO,CAAC,WAAW;CAYpB"}

package/dist/runtime/heapScene/freelist.js

@@ -0,0 +1,188 @@
+// Freelist — best-fit free-block manager used by AttributeArena and
+// IndexAllocator. Replaces the earlier `{off,size}[]` sorted-by-off
+// freelist (whose alloc was O(N) first-fit and release was O(log N)
+// binary-search-then-coalesce).
+//
+// Design:
+//
+//   bySize:  size  → Set<off>                — exact-size buckets
+//   sizes:   sorted ascending array of distinct sizes   — for lower_bound
+//   byStart: off   → size                    — for right-coalesce
+//   byEnd:   off+size → off                  — for left-coalesce
+//
+// `alloc(size)`  → lower_bound(sizes, size) picks the smallest bucket
+//                 with size ≥ requested. O(log K) lookup over distinct
+//                 sizes K (typically dozens), then constant-time pop
+//                 from the size's offset set. If the bucket size
+//                 exceeds the request, the remainder reinserts at
+//                 (off+size, leftover).
+// `release(o,s)` → check `byEnd[o]` (left neighbour ends here) and
+//                 `byStart[o+s]` (right neighbour starts here) for
+//                 O(1) adjacency lookups. Coalesce both sides then
+//                 reinsert one merged block.
+//
+// On realistic heap-renderer workloads the number of *distinct*
+// free-block sizes is typically much smaller than the number of
+// blocks (allocations cluster around the schema's drawHeader
+// fields: mat4=64B, vec4=16B, …), so the K-sized sorted array's
+// splice cost stays cheap even at thousands of live free blocks.
+// For truly heterogeneous workloads, swap `sizes` for a balanced
+// tree — none of the API changes.
+/**
+ * A best-fit free-block manager. All offsets and sizes are in the
+ * caller's units (bytes for the attribute arena, u32 elements for
+ * the index allocator); the freelist doesn't interpret them.
+ */
+export class Freelist {
+    /** size → set of starting offsets currently free at that size. */
+    bySize = new Map();
+    /** Sorted ascending list of every size present in `bySize`. */
+    sizes = [];
+    /** off → size, for the right-coalesce probe in `release`. */
+    byStart = new Map();
+    /** off+size (= end offset) → off, for the left-coalesce probe. */
+    byEnd = new Map();
+    /** Number of distinct free blocks currently tracked. */
+    get blockCount() { return this.byStart.size; }
+    /**
+     * Return any offset of a free block whose size is ≥ `size`, splitting
+     * off any leftover bytes back into the freelist. Returns `undefined`
+     * when no block fits.
+     */
+    alloc(size) {
+        const idx = lowerBound(this.sizes, size);
+        if (idx >= this.sizes.length)
+            return undefined;
+        const foundSize = this.sizes[idx];
+        const set = this.bySize.get(foundSize);
+        // Set iteration order is insertion order — using the first inserted
+        // gives deterministic alloc patterns under matched test workloads.
+        const off = set.values().next().value;
+        this.removeBlock(off, foundSize);
+        if (foundSize > size)
+            this.addBlock(off + size, foundSize - size);
+        return off;
+    }
+    /**
+     * Reintroduce a `(off, size)` block, coalescing with any immediate
+     * neighbour on the left (some other block ending at `off`) or right
+     * (some other block starting at `off + size`).
+     */
+    release(off, size) {
+        let mergeOff = off;
+        let mergeSize = size;
+        // Left neighbour: a block whose end offset is exactly `off`.
+        const leftStart = this.byEnd.get(mergeOff);
+        if (leftStart !== undefined) {
+            const leftSize = this.byStart.get(leftStart);
+            this.removeBlock(leftStart, leftSize);
+            mergeOff = leftStart;
+            mergeSize += leftSize;
+        }
+        // Right neighbour: a block whose start offset is exactly `off + size`.
+        const rightStart = mergeOff + mergeSize;
+        const rightSize = this.byStart.get(rightStart);
+        if (rightSize !== undefined) {
+            this.removeBlock(rightStart, rightSize);
+            mergeSize += rightSize;
+        }
+        this.addBlock(mergeOff, mergeSize);
+    }
+    /**
+     * Take and remove the free block whose end offset is exactly
+     * `endOff`, if any exists. Used by `AttributeArena` /
+     * `IndexAllocator` to shrink the bump cursor back when releases
+     * expose a free tail (§5 — cursor-shrink hygiene for long-lived
+     * high-churn scenes).
+     */
+    takeBlockEndingAt(endOff) {
+        const off = this.byEnd.get(endOff);
+        if (off === undefined)
+            return undefined;
+        const size = this.byStart.get(off);
+        this.removeBlock(off, size);
+        return { off, size };
+    }
+    /** Drop every block. */
+    clear() {
+        this.bySize.clear();
+        this.sizes.length = 0;
+        this.byStart.clear();
+        this.byEnd.clear();
+    }
+    /** Snapshot for tests / debugging — sorted by offset. */
+    toArray() {
+        const out = [];
+        for (const [off, size] of this.byStart)
+            out.push({ off, size });
+        out.sort((a, b) => a.off - b.off);
+        return out;
+    }
+    /** Internal consistency check (paranoia mode). Walks the freelist
+     *  and asserts no two blocks overlap. O(N log N). Cheap enough to
+     *  run after every alloc/release while debugging an allocator
+     *  invariant violation. Throws with the offending pair on failure. */
+    assertInvariants(where) {
+        const blocks = this.toArray();
+        for (let i = 1; i < blocks.length; i++) {
+            const a = blocks[i - 1];
+            const b = blocks[i];
+            if (a.off + a.size > b.off) {
+                throw new Error(`Freelist@${where}: overlapping free blocks ` +
+                    `(${a.off},${a.size}) and (${b.off},${b.size}) — ` +
+                    `${a.off}+${a.size}=${a.off + a.size} > ${b.off}`);
+            }
+        }
+        for (const [off, size] of this.byStart) {
+            const endLookup = this.byEnd.get(off + size);
+            if (endLookup !== off) {
+                throw new Error(`Freelist@${where}: byStart/byEnd desync — byStart[${off}]=${size} ` +
+                    `but byEnd[${off + size}]=${endLookup} (expected ${off})`);
+            }
+            const sizeSet = this.bySize.get(size);
+            if (sizeSet === undefined || !sizeSet.has(off)) {
+                throw new Error(`Freelist@${where}: byStart/bySize desync — byStart[${off}]=${size} ` +
+                    `but bySize[${size}] does not contain ${off}`);
+            }
+        }
+    }
+    addBlock(off, size) {
+        let set = this.bySize.get(size);
+        if (set === undefined) {
+            set = new Set();
+            this.bySize.set(size, set);
+            const idx = lowerBound(this.sizes, size);
+            this.sizes.splice(idx, 0, size);
+        }
+        set.add(off);
+        this.byStart.set(off, size);
+        this.byEnd.set(off + size, off);
+    }
+    removeBlock(off, size) {
+        const set = this.bySize.get(size);
+        if (set === undefined)
+            return;
+        set.delete(off);
+        if (set.size === 0) {
+            this.bySize.delete(size);
+            const idx = lowerBound(this.sizes, size);
+            if (this.sizes[idx] === size)
+                this.sizes.splice(idx, 1);
+        }
+        this.byStart.delete(off);
+        this.byEnd.delete(off + size);
+    }
+}
+/** Index of the first element of `arr` that is `>= target`. */
+function lowerBound(arr, target) {
+    let lo = 0, hi = arr.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        if (arr[mid] < target)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    return lo;
+}
+//# sourceMappingURL=freelist.js.map

package/dist/runtime/heapScene/freelist.js.map

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

package/dist/runtime/heapScene/growBuffer.d.ts

@@ -12,6 +12,17 @@ export declare const ALIGN16: (n: number) => number;
  * it allocates, and `ensureCapacity` grows when required. This
  * separates allocation policy from grow policy.
  */
+/**
+ * Default chunk capacity cap when none is provided. We pick 256 MB as
+ * a safety ceiling that's well within typical adapter
+ * `maxStorageBufferBindingSize` (WebGPU spec minimum is 128 MB; most
+ * desktop GPUs expose 2 GiB+, mobile/integrated ≥ 256 MB). Callers
+ * that know the adapter limit should pass it explicitly so chunks
+ * can grow to whatever the hardware supports — see §3 in
+ * `docs/heap-future-work.md` and `runtime/heapScene.ts`'s scene
+ * factory where the device limit is threaded in.
+ */
+export declare const DEFAULT_MAX_BUFFER_BYTES: number;
 export declare class GrowBuffer {
     private readonly device;
     private readonly label;
@@ -20,13 +31,23 @@ export declare class GrowBuffer {
     private cap;
     private used;
     private readonly listeners;
-    constructor(device: GPUDevice, label: string, usage: GPUBufferUsageFlags, initialBytes: number);
+    private readonly maxBytes;
+    constructor(device: GPUDevice, label: string, usage: GPUBufferUsageFlags, initialBytes: number, maxBytes?: number);
     get buffer(): GPUBuffer;
     get capacity(): number;
+    get maxCapacity(): number;
     get usedBytes(): number;
     setUsed(n: number): void;
     onResize(cb: () => void): IDisposable;
-    /** Ensure the buffer is at least `bytes` capacity. Grows by pow2 + copies live tail. */
+    /**
+     * Ensure the buffer is at least `bytes` capacity. Grows by pow2 +
+     * copies live tail. Throws if `bytes` exceeds the configured
+     * `maxBytes` cap — caller is expected to either open a new chunk
+     * (full §3 multi-draw-call path, deferred) or reject the
+     * allocation upstream (see `isHeapEligible`'s §2 large-object
+     * eject, which keeps multi-MB single ROs out of the heap arena
+     * entirely).
+     */
     ensureCapacity(bytes: number): void;
     destroy(): void;
 }

package/dist/runtime/heapScene/growBuffer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"growBuffer.d.ts","sourceRoot":"","sources":["../../../src/runtime/heapScene/growBuffer.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAE7D,eAAO,MAAM,gBAAgB,QAAY,CAAC;AAE1C,eAAO,MAAM,IAAI,GAAI,GAAG,MAAM,KAAG,MAEhC,CAAC;AAEF,eAAO,MAAM,OAAO,GAAI,GAAG,MAAM,WAAmB,CAAC;AAErD;;;;;;;;;GASG;AACH,qBAAa,UAAU;IAMnB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAPxB,OAAO,CAAC,GAAG,CAAY;IACvB,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyB;gBAEhC,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,mBAAmB,EAC3C,YAAY,EAAE,MAAM;IAStB,IAAI,MAAM,IAAI,SAAS,CAAqB;IAC5C,IAAI,QAAQ,IAAI,MAAM,CAAqB;IAC3C,IAAI,SAAS,IAAI,MAAM,CAAsB;IAC7C,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,WAAW;IAIrC,wFAAwF;IACxF,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAkBnC,OAAO,IAAI,IAAI;CAChB"}
+{"version":3,"file":"growBuffer.d.ts","sourceRoot":"","sources":["../../../src/runtime/heapScene/growBuffer.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAE7D,eAAO,MAAM,gBAAgB,QAAY,CAAC;AAE1C,eAAO,MAAM,IAAI,GAAI,GAAG,MAAM,KAAG,MAEhC,CAAC;AAEF,eAAO,MAAM,OAAO,GAAI,GAAG,MAAM,WAAmB,CAAC;AAErD;;;;;;;;;GASG;AACH;;;;;;;;;GASG;AACH,eAAO,MAAM,wBAAwB,QAAoB,CAAC;AAE1D,qBAAa,UAAU;IAOnB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK;IARxB,OAAO,CAAC,GAAG,CAAY;IACvB,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyB;IACnD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAEf,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,mBAAmB,EAC3C,YAAY,EAAE,MAAM,EACpB,QAAQ,GAAE,MAAiC;IAe7C,IAAI,MAAM,IAAI,SAAS,CAAqB;IAC5C,IAAI,QAAQ,IAAI,MAAM,CAAqB;IAC3C,IAAI,WAAW,IAAI,MAAM,CAA0B;IACnD,IAAI,SAAS,IAAI,MAAM,CAAsB;IAC7C,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,WAAW;IAIrC;;;;;;;;OAQG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IA0BnC,OAAO,IAAI,IAAI;CAChB"}

package/dist/runtime/heapScene/growBuffer.js

@@ -23,6 +23,17 @@ export const ALIGN16 = (n) => (n + 15) & ~15;
  * it allocates, and `ensureCapacity` grows when required. This
  * separates allocation policy from grow policy.
  */
+/**
+ * Default chunk capacity cap when none is provided. We pick 256 MB as
+ * a safety ceiling that's well within typical adapter
+ * `maxStorageBufferBindingSize` (WebGPU spec minimum is 128 MB; most
+ * desktop GPUs expose 2 GiB+, mobile/integrated ≥ 256 MB). Callers
+ * that know the adapter limit should pass it explicitly so chunks
+ * can grow to whatever the hardware supports — see §3 in
+ * `docs/heap-future-work.md` and `runtime/heapScene.ts`'s scene
+ * factory where the device limit is threaded in.
+ */
+export const DEFAULT_MAX_BUFFER_BYTES = 256 * 1024 * 1024;
 export class GrowBuffer {
     device;
     label;
@@ -31,11 +42,16 @@ export class GrowBuffer {
     cap;
     used = 0;
     listeners = new Set();
-    constructor(device, label, usage, initialBytes) {
+    maxBytes;
+    constructor(device, label, usage, initialBytes, maxBytes = DEFAULT_MAX_BUFFER_BYTES) {
         this.device = device;
         this.label = label;
         this.usage = usage;
         this.cap = Math.max(MIN_BUFFER_BYTES, POW2(initialBytes));
+        this.maxBytes = Math.max(this.cap, maxBytes);
+        if (this.cap > this.maxBytes) {
+            throw new Error(`GrowBuffer '${label}': initial capacity ${this.cap} exceeds maxBytes ${this.maxBytes}`);
+        }
         this.buf = device.createBuffer({
             size: this.cap,
             usage: usage | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC,
@@ -44,17 +60,33 @@ export class GrowBuffer {
     }
     get buffer() { return this.buf; }
     get capacity() { return this.cap; }
+    get maxCapacity() { return this.maxBytes; }
     get usedBytes() { return this.used; }
     setUsed(n) { this.used = n; }
     onResize(cb) {
         this.listeners.add(cb);
         return { dispose: () => { this.listeners.delete(cb); } };
     }
-    /** Ensure the buffer is at least `bytes` capacity. Grows by pow2 + copies live tail. */
+    /**
+     * Ensure the buffer is at least `bytes` capacity. Grows by pow2 +
+     * copies live tail. Throws if `bytes` exceeds the configured
+     * `maxBytes` cap — caller is expected to either open a new chunk
+     * (full §3 multi-draw-call path, deferred) or reject the
+     * allocation upstream (see `isHeapEligible`'s §2 large-object
+     * eject, which keeps multi-MB single ROs out of the heap arena
+     * entirely).
+     */
     ensureCapacity(bytes) {
         if (bytes <= this.cap)
             return;
-        const newCap = POW2(bytes);
+        if (bytes > this.maxBytes) {
+            throw new Error(`GrowBuffer '${this.label}': requested ${bytes} bytes exceeds maxBytes ${this.maxBytes}. ` +
+                `This is the adapter's per-binding storage limit — landing larger workloads needs the ` +
+                `multi-chunk path (§3 in docs/heap-future-work.md) or upstream eviction via §2.`);
+        }
+        let newCap = POW2(bytes);
+        if (newCap > this.maxBytes)
+            newCap = this.maxBytes;
         const newBuf = this.device.createBuffer({
             size: newCap,
             usage: this.usage | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC,

package/dist/runtime/heapScene/growBuffer.js.map

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

package/dist/runtime/heapScene/pools.d.ts

@@ -2,6 +2,7 @@ import type { aval, IDisposable } from "@aardworx/wombat.adaptive";
 import type { BufferView } from "../../core/bufferView.js";
 import type { HostBufferSource } from "../../core/buffer.js";
 import { GrowBuffer } from "./growBuffer.js";
+import { ChunkedAttributeArena, ChunkedIndexAllocator } from "./chunkedArena.js";
 /** Per-allocation header: (u32 typeId, u32 length). Data follows
  *  the header aligned up to 16 bytes (so positions/normals/etc. line
  *  up for future vec4 reads). */
@@ -13,44 +14,56 @@ export declare const ENC_V3F_TIGHT = 1;
  *  the shader doesn't branch on this. */
 export declare const SEM_POSITIONS = 1;
 export declare const SEM_NORMALS = 2;
+/**
+ * One pool entry tracks a single (aval, chunkIdx) pair. Refs are
+ * byte offsets within the chunk's GPUBuffer; chunkIdx is implicit
+ * in which chunk's bind group is active at draw time (shaders
+ * never decode it).
+ */
 interface PoolEntry {
-    /** Byte offset into the arena. Data starts at ref + ALLOC_HEADER_PAD_TO. */
+    readonly chunkIdx: number;
     readonly ref: number;
     readonly dataBytes: number;
     readonly typeId: number;
-    /** Packer used to refresh the data region on aval marks. */
     readonly pack: (val: unknown, dst: Float32Array, off: number) => void;
     refcount: number;
 }
 /**
- * Aval-keyed pool of arena allocations. One allocation per unique
- * aval (object identity). Two draws referencing the same aval share
- * the allocation; their DrawHeaders carry the same u32 ref. Holds
- * uniforms (fixed-size scalars/vectors/matrices) AND attribute arrays
- * (variable-size). The caller decides `dataBytes` + `length` per
- * acquisition — the pool just keys on aval identity and refcounts.
- *
- * Sharing emerges from aval identity — no separate "frequency"
- * declaration needed. A `cval` shared by all draws → 1 alloc.
- * A static positions array shared across instanced draws → 1 alloc.
- * Same code path either way.
+ * `(aval, chunkIdx)`-keyed pool of chunked-arena allocations. An
+ * aval that's referenced from multiple chunks (e.g. two ROs sharing
+ * a uniform but landing in different chunks) gets one entry per
+ * chunk — accepted duplication cost of the multi-draw-call
+ * per-chunk render path (§3). Within a single chunk, ROs sharing
+ * an aval still share the underlying allocation.
  */
 export declare class UniformPool {
     private readonly byAval;
-    has(av: aval<unknown>): boolean;
-    entry(av: aval<unknown>): PoolEntry | undefined;
+    has(av: aval<unknown>, chunkIdx: number): boolean;
+    /** True when the pool holds at least one entry for `av` in any
+     *  chunk. Used by the scene's `inputChanged` dispatch to decide
+     *  whether a marking aval is one of our tracked allocations. */
+    hasAny(av: aval<unknown>): boolean;
+    entry(av: aval<unknown>, chunkIdx: number): PoolEntry | undefined;
+    /** First chunk this aval is allocated in, if any. Used by `addRO`
+     *  to prefer co-locating a new RO with its already-allocated
+     *  shared inputs (avoids unnecessary duplication). */
+    firstChunkContaining(av: aval<unknown>): number | undefined;
     /**
-     * Acquire (or share) an allocation for `aval`. Caller passes the
-     * pre-read `value` (so the pool doesn't need a token) plus the
-     * (`dataBytes`, `typeId`, `length`, `pack`) describing how to lay
-     * it out. If a new allocation is made, the value is packed and
-     * uploaded immediately.
+     * Acquire (or share) an allocation for `aval` in `chunkIdx`.
+     * Returns the byte offset within that chunk's GPUBuffer. If a
+     * fresh allocation is made, the value is packed + uploaded
+     * immediately into the chunk's CPU shadow.
      */
-    acquire(device: GPUDevice, arena: AttributeArena, av: aval<unknown>, value: unknown, dataBytes: number, typeId: number, length: number, pack: (val: unknown, dst: Float32Array, off: number) => void): number;
-    /** Decrement refcount; if zero, free the arena allocation. */
-    release(arena: AttributeArena, av: aval<unknown>): void;
-    /** Re-pack one entry's data region into the arena's CPU shadow. */
-    repack(device: GPUDevice, arena: AttributeArena, av: aval<unknown>, val: unknown): void;
+    acquire(device: GPUDevice, arena: ChunkedAttributeArena, av: aval<unknown>, chunkIdx: number, value: unknown, dataBytes: number, typeId: number, length: number, pack: (val: unknown, dst: Float32Array, off: number) => void): number;
+    release(arena: ChunkedAttributeArena, av: aval<unknown>, chunkIdx: number): void;
+    /** Re-pack one entry's data region into every chunk that holds
+     *  this aval. When an aval is shared across N chunks (each chunk
+     *  has its own duplicate alloc), every duplicate needs the
+     *  refresh so all the chunks' ROs see the new value. */
+    repack(device: GPUDevice, arena: ChunkedAttributeArena, av: aval<unknown>, val: unknown): void;
+    /** Total bytes touched by `repack` for this aval — sum across
+     *  chunks. Used by the dirty-bytes diagnostics. */
+    totalDataBytes(av: aval<unknown>): number;
 }
 /**
  * Aval-keyed pool over the `IndexAllocator`. Two draws referencing
@@ -65,16 +78,21 @@ export declare class UniformPool {
  * `Uint32Array` view collapse to one allocation.
  */
 export declare class IndexPool {
+    /** Per-aval, per-chunk bookkeeping. Same aval acquired in two
+     *  chunks gets two entries (accepted §3 duplication). */
     private readonly byAval;
+    /** Per-chunk constant-aval value-dedup (§5b in-chunk). */
     private readonly byValueKey;
     private readonly bufferIds;
     private nextBufferId;
     private bufferIdOf;
-    acquire(device: GPUDevice, indices: IndexAllocator, av: aval<Uint32Array>, arr: Uint32Array): {
+    firstChunkContaining(av: aval<Uint32Array>): number | undefined;
+    acquire(device: GPUDevice, indices: ChunkedIndexAllocator, av: aval<Uint32Array>, chunkIdx: number, arr: Uint32Array): {
+        chunkIdx: number;
         firstIndex: number;
         count: number;
     };
-    release(indices: IndexAllocator, av: aval<Uint32Array>): void;
+    release(indices: ChunkedIndexAllocator, av: aval<Uint32Array>, chunkIdx: number): void;
 }
 /**
  * Slot-indexed allocator over a GrowBuffer. `slotBytes` is set per-
@@ -87,6 +105,8 @@ export declare class DrawHeap {
     private readonly slotBytes;
     private free;
     private nextSlot;
+    /** DEBUG: tracks slot live/free state. true = live (in use). */
+    private readonly live;
     constructor(buf: GrowBuffer, slotBytes: number);
     get buffer(): GPUBuffer;
     /** Bytes per slot — caller multiplies by slot index for byte offsets. */
@@ -107,7 +127,12 @@ export declare class DrawHeap {
 export declare class AttributeArena {
     private readonly buf;
     private cursor;
-    private freeList;
+    private readonly freelist;
+    /** DEBUG: tracks every live allocation by start byte → size. Set
+     *  on alloc, cleared on release. Used by `assertNoOverlap()` to
+     *  detect allocator returning overlapping ranges. Enabled in
+     *  development; cheap (one Map insert/delete per alloc). */
+    private readonly liveAllocs;
     /** CPU shadow of the entire GPU buffer; writes go here first then
      *  flush() emits one writeBuffer per dirty contiguous range. */
     private shadow;
@@ -117,34 +142,42 @@ export declare class AttributeArena {
     get buffer(): GPUBuffer;
     get capacity(): number;
     get usedBytes(): number;
+    /** Read 4 u32s from the CPU shadow starting at byte `off`. Used by
+     *  the validator to compare against the GPU's read-back values:
+     *  if CPU shadow is correct but GPU shows garbage → the corruption
+     *  came from a GPU-side write (a compute kernel writing to a wrong
+     *  byte). If both differ from what pool.acquire wrote → CPU-side
+     *  write path is the culprit. */
+    peekShadowU32(off: number, count: number): Uint32Array;
     write(dst: number, data: Uint8Array): void;
     flush(device: GPUDevice): void;
     /**
      * Allocate space for one attribute. Returns the byte ref (offset
      * to the header — data lives at ref + 16).
      */
+    /** Non-throwing alloc — returns `undefined` when the request
+     *  would exceed the underlying GrowBuffer's `maxCapacity` cap.
+     *  Used by `ChunkedAttributeArena` to probe before spilling to
+     *  the next chunk. */
+    tryAlloc(dataBytes: number): number | undefined;
     alloc(dataBytes: number): number;
     release(ref: number, dataBytes: number): void;
+    /** Throws if the just-returned alloc overlaps any live allocation. */
+    private recordAlloc;
     onResize(cb: () => void): IDisposable;
     destroy(): void;
 }
-/**
- * Insert `{off, size}` into a free-list kept sorted by `off`, then
- * coalesce with the two immediate neighbours.
- */
-export declare function insertSortedFreeBlock(freeList: {
-    off: number;
-    size: number;
-}[], off: number, size: number): void;
 /**
  * Element-bump allocator over an index GrowBuffer (units = u32). Each
  * draw's index range is allocated as one block; on release the block
- * is returned to a free list and can be reused first-fit.
+ * is returned to a Freelist and can be reused best-fit.
  */
 export declare class IndexAllocator {
     private readonly buf;
     private cursor;
-    private freeList;
+    private readonly freelist;
+    /** DEBUG: live index allocations tracked by start element. */
+    private readonly liveAllocs;
     private shadow;
     private dirtyMin;
     private dirtyMax;
@@ -153,6 +186,11 @@ export declare class IndexAllocator {
     get usedElements(): number;
     write(dstByteOffset: number, data: Uint8Array): void;
     flush(device: GPUDevice): void;
+    /** Non-throwing alloc — returns `undefined` when the request
+     *  would exceed the underlying GrowBuffer's `maxCapacity` cap.
+     *  Used by `ChunkedIndexAllocator` to probe before spilling. */
+    tryAlloc(elements: number): number | undefined;
+    private recordAlloc;
     alloc(elements: number): number;
     release(off: number, elements: number): void;
     onResize(cb: () => void): IDisposable;
@@ -161,13 +199,17 @@ export declare class IndexAllocator {
 /**
  * Global arena state: attribute / uniform data lives in `attrs`
  * (multi-typed-view storage); indices live in `indices` (separate
- * INDEX-usage buffer).
+ * INDEX-usage buffer). Both are chunked: each chunk owns a separate
+ * GPUBuffer + Freelist. Refs that downstream code stores are byte
+ * offsets within a chunk; the chunk identity is carried alongside
+ * (via bucket.chunkIdx in heapScene) and made implicit at draw
+ * time by which chunk's bind group is active.
  */
 export interface ArenaState {
-    readonly attrs: AttributeArena;
-    readonly indices: IndexAllocator;
+    readonly attrs: ChunkedAttributeArena;
+    readonly indices: ChunkedIndexAllocator;
 }
-export declare function buildArenaState(device: GPUDevice, attrBytesHint: number, idxBytesHint: number, label: string, idxExtraUsage?: GPUBufferUsageFlags): ArenaState;
+export declare function buildArenaState(device: GPUDevice, attrBytesHint: number, idxBytesHint: number, label: string, idxExtraUsage?: GPUBufferUsageFlags, maxChunkBytes?: number | undefined): ArenaState;
 export declare function arenaBytes(arena: ArenaState): number;
 /** Upload a single attribute — header (typeId, length) + data — into the arena at byte offset `ref`. */
 export declare function writeAttribute(device: GPUDevice, buf: GPUBuffer, ref: number, typeId: number, length: number, data: Float32Array): void;