@aardworx/wombat.rendering 0.9.33 → 0.19.0

package/src/runtime/derivedUniforms/sceneIntegration.ts

@@ -1,15 +1,19 @@
 // §7 v2 — heap-scene integration.
 //
-// One DerivedUniformsScene per heap scene: owns the rule registry, the (single,
-// scene-wide) records buffer, the constituent-slots heap (df32 trafo halves), the
-// constituents GPU buffer, and the dispatcher. Per RO: flatten each rule against the
-// RO's rule set, register it, resolve every input leaf to a tagged slot handle
-// (constituent fwd/bwd / host drawHeader byte), and push one record.
+// One DerivedUniformsScene per heap scene: owns the rule registry, a per-chunk
+// records buffer (§3), the constituent-slots heap (df32 trafo halves, scene-
+// wide), the constituents GPU buffer, and the dispatcher.
+//
+// Multi-chunk (§3): each arena chunk has its own GPUBuffer for drawHeaders.
+// Derived-uniform records reference HostHeap slots by absolute byte offset
+// within ONE buffer — so a record must be bound to its bucket's chunk at
+// dispatch. We partition records by chunkIdx: one RecordsBuffer per chunk,
+// one dispatch per chunk binding that chunk's main heap.
 //
 // Per frame, inside the heap scene's `evaluateAlways(token, …)` scope:
 //   const dirty = scene.pullDirty(token);   // drains changed trafo avals (re-subscribes)
 //   scene.uploadDirty(dirty);               // O(changed) value uploads
-//   scene.encode(enc);                      // one compute dispatch
+//   scene.encode(enc);                      // one compute dispatch per chunk
 // Clean frames: zero CPU work, records buffer static.
 // See docs/derived-uniforms-extensible.md.
 
@@ -33,16 +37,20 @@ export class DerivedUniformsScene {
   readonly device: GPUDevice;
   readonly constituents: ConstituentSlots;
   readonly registry = new DerivedUniformRegistry();
-  /** Single scene-wide records buffer — all buckets share constituents AND the main heap, so per-bucket records would just multiply dispatch overhead. */
-  readonly records = new RecordsBuffer();
+  /** Per-chunk records buffers (§3). Constituents + registry are
+   *  scene-wide; records partition by chunk so each dispatch binds
+   *  the right chunk's main heap. */
+  private readonly recordsByChunk = new Map<number, RecordsBuffer>();
   readonly dispatcher: DerivedUniformsDispatcher;
   /** Constituents storage GPU buffer (`array<vec2<f32>>` — df32 mat4 halves). */
   constituentsBuf: GPUBuffer;
-  private readonly mainHeapRef: { current: GPUBuffer };
+  /** Per-chunk main-heap GPUBuffer getters. Populated as chunks are
+   *  registered via `setMainHeapForChunk` from the scene factory. */
+  private readonly mainHeapByChunk = new Map<number, () => GPUBuffer>();
   /** Bumped each time a shared GPU buffer is replaced. */
   bufferEpoch = 0;
 
-  constructor(device: GPUDevice, mainHeapBuf: GPUBuffer, opts?: DerivedUniformsSceneOptions) {
+  constructor(device: GPUDevice, opts?: DerivedUniformsSceneOptions) {
     this.device = device;
     const initial = opts?.initialConstituentSlots ?? 64;
     this.constituents = new ConstituentSlots(() => {}, initial);
@@ -51,15 +59,34 @@ export class DerivedUniformsScene {
       size: initial * DF32_MAT4_BYTES,
       usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
     });
-    this.mainHeapRef = { current: mainHeapBuf };
     this.dispatcher = new DerivedUniformsDispatcher(device, {
       constituentsBuf: () => this.constituentsBuf,
-      mainHeapBuf: () => this.mainHeapRef.current,
     });
   }
 
-  rebindMainHeap(mainHeapBuf: GPUBuffer): void {
-    this.mainHeapRef.current = mainHeapBuf;
+  /** Register (or replace) the GPUBuffer getter for a chunk's main
+   *  heap. Called by the scene factory at construction and whenever
+   *  a new chunk opens or an existing chunk's buffer reallocates. */
+  setMainHeapForChunk(chunkIdx: number, getter: () => GPUBuffer): void {
+    this.mainHeapByChunk.set(chunkIdx, getter);
+  }
+
+  /** Get-or-create the records buffer for `chunkIdx`. */
+  recordsFor(chunkIdx: number): RecordsBuffer {
+    let r = this.recordsByChunk.get(chunkIdx);
+    if (r === undefined) {
+      r = new RecordsBuffer();
+      this.recordsByChunk.set(chunkIdx, r);
+    }
+    return r;
+  }
+
+  /** Total record count summed across every chunk's records buffer.
+   *  Used by the scene's stats / diagnostics. */
+  get totalRecordCount(): number {
+    let n = 0;
+    for (const r of this.recordsByChunk.values()) n += r.recordCount;
+    return n;
   }
 
   ensureConstituentsCapacity(requiredBytes: number): void {
@@ -102,9 +129,23 @@ export class DerivedUniformsScene {
     uploadConstituentsRange(this.device, this.constituentsBuf, this.constituents.cpuMirror, dirty);
   }
 
-  /** Run the uber-kernel. No-op if there are no records. */
+  /** Run the uber-kernel once per chunk that holds records. No-op
+   *  when no chunk has records. Each dispatch binds that chunk's
+   *  main heap buffer. */
   encode(enc: GPUCommandEncoder): boolean {
-    return this.dispatcher.encode(enc, this.registry, this.records);
+    let any = false;
+    for (const [chunkIdx, records] of this.recordsByChunk) {
+      if (records.recordCount === 0) continue;
+      const heapGetter = this.mainHeapByChunk.get(chunkIdx);
+      if (heapGetter === undefined) {
+        throw new Error(
+          `derivedUniforms.encode: no main-heap binding registered for chunkIdx=${chunkIdx}. ` +
+          `Call setMainHeapForChunk(idx, getter) when each chunk opens.`,
+        );
+      }
+      if (this.dispatcher.encodeChunk(enc, this.registry, records, heapGetter)) any = true;
+    }
+    return any;
   }
 
   dispose(): void {
@@ -126,6 +167,9 @@ export interface RoDerivedRequest {
   readonly outputOffset: (name: string) => number | undefined;
   /** Absolute byte offset of this RO's drawHeader within the main heap. */
   readonly drawHeaderBaseByte: number;
+  /** §3: which arena chunk this RO lives in. Records are partitioned
+   *  by chunk so each dispatch binds the right main-heap buffer. */
+  readonly chunkIdx: number;
 }
 
 export interface RoRegistration {
@@ -134,6 +178,8 @@ export interface RoRegistration {
   readonly constituentAvals: readonly aval<Trafo3d>[];
   /** Flattened-rule hashes — for `registry.release` on teardown. */
   readonly ruleHashes: readonly string[];
+  /** Chunk this registration was placed into — used by deregister. */
+  readonly chunkIdx: number;
 }
 
 export function registerRoDerivations(
@@ -141,7 +187,8 @@ export function registerRoDerivations(
   owner: object,
   req: RoDerivedRequest,
 ): RoRegistration {
-  if (req.rules.size === 0) return { owner, constituentAvals: [], ruleHashes: [] };
+  if (req.rules.size === 0) return { owner, constituentAvals: [], ruleHashes: [], chunkIdx: req.chunkIdx };
+  const records = scene.recordsFor(req.chunkIdx);
 
   const acquiredAvals: aval<Trafo3d>[] = [];
   const ruleHashes: string[] = [];
@@ -192,14 +239,14 @@ export function registerRoDerivations(
     if (outOff === undefined) {
       throw new Error(`derivedUniforms: no drawHeader slot for derived uniform '${outName}' on this RO`);
     }
-    scene.records.add(owner, id, makeHandle(SlotTag.HostHeap, req.drawHeaderBaseByte + outOff), inSlots);
+    records.add(owner, id, makeHandle(SlotTag.HostHeap, req.drawHeaderBaseByte + outOff), inSlots);
   }
   scene.ensureConstituentsCapacity(scene.constituents.slotCount * DF32_MAT4_BYTES);
-  return { owner, constituentAvals: acquiredAvals, ruleHashes };
+  return { owner, constituentAvals: acquiredAvals, ruleHashes, chunkIdx: req.chunkIdx };
 }
 
 export function deregisterRoDerivations(scene: DerivedUniformsScene, reg: RoRegistration): void {
-  scene.records.removeAllForOwner(reg.owner);
+  scene.recordsFor(reg.chunkIdx).removeAllForOwner(reg.owner);
   for (const h of reg.ruleHashes) scene.registry.release(h);
   for (const av of reg.constituentAvals) scene.constituents.release(av);
 }

package/src/runtime/heapAdapter.ts

@@ -288,6 +288,19 @@ export function renderObjectToHeapSpec(
       // every release closure reads the cell and frees the LATEST
       // sub-rect — no leaks even when multiple ROs are bucket-shared.
       const cell = currentRefCellFor(texAvalTyped, acq.ref);
+      // The pool.acquire above bumped refcount to 1; release it
+      // immediately so the entry's refcount tracks ACTUAL drawHeader
+      // usage, not adapter-call count. heapScene.addDraw bumps refcount
+      // via incRef per cycle (paired with our release closure). Without
+      // this drop, every cached HeapDrawSpec (re-introduced across
+      // aset add/remove cycles) leaves the atlas entry pinned forever.
+      pool.release(acq.ref);
+      // Heap-side re-acquire hook (attached after the literal so the
+      // strict HeapTextureSet typing stays clean): if the entry was
+      // evicted between heap remove/add cycles, addDraw acquires a
+      // fresh sub-rect and uses this to redirect our per-aval cell to
+      // the new ref, so the release closure stops freeing the long-
+      // evicted one.
       textures = {
         kind: "atlas",
         format: atlasFormat,
@@ -312,6 +325,7 @@ export function renderObjectToHeapSpec(
           return next;
         },
       };
+      (textures as unknown as { __retarget: (r: number) => void }).__retarget = (r: number) => { cell.ref = r; };
     } else {
       // Tier-L fallback: keep the existing standalone path, which
       // requires a resolved GPUTexture/GPUSampler.
@@ -350,5 +364,8 @@ export function renderObjectToHeapSpec(
     indices,
     ...(textures !== undefined ? { textures } : {}),
     ...(ro.modeRules !== undefined ? { modeRules: ro.modeRules } : {}),
+    // Pass `active` through unforced so the heap path can subscribe
+    // and react to flips without re-running the spec adapter.
+    ...(ro.active !== undefined ? { active: ro.active } : {}),
   };
 }

package/src/runtime/heapEligibility.ts

@@ -51,6 +51,19 @@ import { asAttributeProvider } from "../core/provider.js";
  */
 const LEGACY_MAX_DIM = 4096;
 
+/**
+ * Total per-RO payload (attribute + instance + index bytes) above
+ * which the heap path ejects the RO to the legacy renderer. The
+ * heap path's value is collapsing many small ROs into one
+ * drawIndirect; a single-RO bucket emits the same drawIndexed it
+ * would have under legacy, AND a multi-MB allocation forces the
+ * arena's pow2 GrowBuffer to allocate (and re-copy on grow) a
+ * giant contiguous GPUBuffer. Default 16 MB — picked so typical
+ * UI/SG geometry (a few hundred kB) sails through and only
+ * terrain/photogrammetry/dense-pointcloud meshes eject.
+ */
+const HEAP_PAYLOAD_EJECT_BYTES = 16 * 1024 * 1024;
+
 const isHostBuffer = (b: IBuffer): boolean => b.kind === "host";
 // Samplers: accept both descriptor-form (`kind: "host"`) and resolved
 // (`kind: "gpu"`). The heap atlas path uses ONE shared GPU sampler for
@@ -204,7 +217,15 @@ export function isHeapEligible(ro: RenderObject): aval<boolean> {
   // can flip; if they violate heap constraints the RO routes to the
   // legacy path that frame).
   return AVal.custom(token => {
-    for (const av of buffers)  if (!isHostBuffer(av.getValue(token)))         return false;
+    let payloadBytes = 0;
+    for (const av of buffers) {
+      const b = av.getValue(token);
+      if (!isHostBuffer(b)) return false;
+      payloadBytes += b.sizeBytes;
+      // Early-out if any single RO already busts the budget — avoids
+      // walking the rest of the buffer list for a guaranteed reject.
+      if (payloadBytes > HEAP_PAYLOAD_EJECT_BYTES) return false;
+    }
     for (const av of textures) if (!isHeapServableTexture(av.getValue(token))) return false;
     for (const av of samplers) if (!isHeapServableSampler(av.getValue(token))) return false;
     const dc = ro.drawCall.getValue(token);

package/src/runtime/heapScene/chunkedArena.ts

@@ -0,0 +1,238 @@
+// Multi-chunk arena allocators — §3 of `docs/heap-future-work.md`.
+//
+// Each chunk owns a separate GPUBuffer with its own pow2-grow + best-
+// fit Freelist. When the newest chunk hits its per-chunk cap, the
+// allocator opens a fresh chunk and routes subsequent allocations
+// there. Each (chunkIdx, offset) is the address; refs in master
+// records / drawHeaders carry only the offset — chunkIdx is implicit
+// in which chunk's bind group the current draw call is using.
+//
+// Cap policy: `maxChunkBytes` ≤ `device.limits.maxStorageBufferBindingSize`
+// per chunk. Default: `min(adapter, DEFAULT_MAX_BUFFER_BYTES)`. Tests
+// can pass a tiny cap (e.g. 4 MB) to exercise multi-chunk behaviour
+// without massive workloads.
+
+import type { IDisposable } from "@aardworx/wombat.adaptive";
+import { GrowBuffer, DEFAULT_MAX_BUFFER_BYTES } from "./growBuffer.js";
+import { AttributeArena, IndexAllocator } from "./pools.js";
+
+/** Address inside a chunked arena. */
+export interface ChunkedRef {
+  readonly chunkIdx: number;
+  readonly off: number;
+}
+
+/**
+ * Multi-chunk wrapper around `AttributeArena`. Each chunk is one
+ * GrowBuffer / Freelist pair, capped at `maxChunkBytes`. Caller
+ * tracks chunkIdx alongside the offset — refs in shaders are just
+ * the offset, because shaders bind one chunk at a time.
+ */
+export class ChunkedAttributeArena {
+  private readonly _chunks: AttributeArena[] = [];
+  private readonly onChunkAddedCbs = new Set<(chunkIdx: number) => void>();
+
+  constructor(
+    private readonly device: GPUDevice,
+    private readonly label: string,
+    private readonly usage: GPUBufferUsageFlags,
+    private readonly initialChunkBytes: number,
+    private readonly maxChunkBytes: number = DEFAULT_MAX_BUFFER_BYTES,
+  ) {
+    this.openChunk();
+  }
+
+  get chunkCount(): number { return this._chunks.length; }
+  get chunks(): ReadonlyArray<AttributeArena> { return this._chunks; }
+  chunk(i: number): AttributeArena { return this._chunks[i]!; }
+
+  /**
+   * Allocate `dataBytes` of attribute storage. Tries the `hint`
+   * chunk first when given (caller passes the RO's chunk to keep all
+   * uniforms in the same buffer); falls back to the newest chunk;
+   * opens a new chunk when none fits.
+   */
+  alloc(dataBytes: number, hint?: number): ChunkedRef {
+    if (hint !== undefined && hint >= 0 && hint < this._chunks.length) {
+      const off = this._chunks[hint]!.tryAlloc(dataBytes);
+      if (off !== undefined) return { chunkIdx: hint, off };
+    }
+    // Newest-first ordering keeps freshly-opened chunks busy and
+    // older chunks naturally drain as their ROs release (helping
+    // future drop-empty-chunks cleanup land cheaply).
+    for (let i = this._chunks.length - 1; i >= 0; i--) {
+      if (i === hint) continue;
+      const off = this._chunks[i]!.tryAlloc(dataBytes);
+      if (off !== undefined) return { chunkIdx: i, off };
+    }
+    const newIdx = this.openChunk();
+    const off = this._chunks[newIdx]!.tryAlloc(dataBytes);
+    if (off === undefined) {
+      throw new Error(
+        `ChunkedAttributeArena '${this.label}': allocation of ${dataBytes}B exceeds maxChunkBytes ${this.maxChunkBytes}`,
+      );
+    }
+    return { chunkIdx: newIdx, off };
+  }
+
+  release(chunkIdx: number, off: number, dataBytes: number): void {
+    const c = this._chunks[chunkIdx];
+    if (c === undefined) return;
+    c.release(off, dataBytes);
+  }
+
+  /** Push the dirty CPU shadow of every chunk to its GPU buffer. */
+  flush(device: GPUDevice): void {
+    for (const c of this._chunks) c.flush(device);
+  }
+
+  /** Write into a specific chunk's CPU shadow. */
+  write(chunkIdx: number, dst: number, data: Uint8Array): void {
+    this._chunks[chunkIdx]!.write(dst, data);
+  }
+
+  /** Subscribe to "a new chunk was opened" events. Used by the
+   *  bucket-rebuild path to widen its per-chunk bookkeeping. */
+  onChunkAdded(cb: (chunkIdx: number) => void): IDisposable {
+    this.onChunkAddedCbs.add(cb);
+    return { dispose: () => { this.onChunkAddedCbs.delete(cb); } };
+  }
+
+  /** Subscribe to "any chunk resized (incl. brand-new chunk)" events.
+   *  Wires the callback to every current chunk's `onResize` AND
+   *  fires it for each future-added chunk after subscribing.
+   *  Used by the scene-level rebuild path that follows arena growth. */
+  onAnyResize(cb: (chunkIdx: number) => void): IDisposable {
+    const disposables: IDisposable[] = [];
+    for (let i = 0; i < this._chunks.length; i++) {
+      const idx = i;
+      disposables.push(this._chunks[i]!.onResize(() => cb(idx)));
+    }
+    disposables.push(this.onChunkAdded((idx) => {
+      disposables.push(this._chunks[idx]!.onResize(() => cb(idx)));
+      // Also fire once for the new chunk so listeners can wire bind
+      // groups to it.
+      cb(idx);
+    }));
+    return { dispose: () => { for (const d of disposables) d.dispose(); } };
+  }
+
+  /** Total bytes used across all chunks (high-watermark sum). */
+  totalUsedBytes(): number {
+    let s = 0;
+    for (const c of this._chunks) s += c.usedBytes;
+    return s;
+  }
+
+  destroy(): void {
+    for (const c of this._chunks) c.destroy();
+    this._chunks.length = 0;
+  }
+
+  private openChunk(): number {
+    const idx = this._chunks.length;
+    const buf = new GrowBuffer(
+      this.device, `${this.label}/c${idx}`, this.usage,
+      this.initialChunkBytes, this.maxChunkBytes,
+    );
+    this._chunks.push(new AttributeArena(buf));
+    for (const cb of this.onChunkAddedCbs) cb(idx);
+    return idx;
+  }
+}
+
+/** Multi-chunk wrapper around `IndexAllocator`. Element-bump units
+ *  are u32. Same chunk-open / hint / fallback semantics as
+ *  `ChunkedAttributeArena`. */
+export class ChunkedIndexAllocator {
+  private readonly _chunks: IndexAllocator[] = [];
+  private readonly onChunkAddedCbs = new Set<(chunkIdx: number) => void>();
+
+  constructor(
+    private readonly device: GPUDevice,
+    private readonly label: string,
+    private readonly usage: GPUBufferUsageFlags,
+    private readonly initialChunkBytes: number,
+    private readonly maxChunkBytes: number = DEFAULT_MAX_BUFFER_BYTES,
+  ) {
+    this.openChunk();
+  }
+
+  get chunkCount(): number { return this._chunks.length; }
+  get chunks(): ReadonlyArray<IndexAllocator> { return this._chunks; }
+  chunk(i: number): IndexAllocator { return this._chunks[i]!; }
+
+  alloc(elements: number, hint?: number): ChunkedRef {
+    if (hint !== undefined && hint >= 0 && hint < this._chunks.length) {
+      const off = this._chunks[hint]!.tryAlloc(elements);
+      if (off !== undefined) return { chunkIdx: hint, off };
+    }
+    for (let i = this._chunks.length - 1; i >= 0; i--) {
+      if (i === hint) continue;
+      const off = this._chunks[i]!.tryAlloc(elements);
+      if (off !== undefined) return { chunkIdx: i, off };
+    }
+    const newIdx = this.openChunk();
+    const off = this._chunks[newIdx]!.tryAlloc(elements);
+    if (off === undefined) {
+      throw new Error(
+        `ChunkedIndexAllocator '${this.label}': allocation of ${elements} elements exceeds maxChunkBytes/4 ${this.maxChunkBytes / 4}`,
+      );
+    }
+    return { chunkIdx: newIdx, off };
+  }
+
+  release(chunkIdx: number, off: number, elements: number): void {
+    const c = this._chunks[chunkIdx];
+    if (c === undefined) return;
+    c.release(off, elements);
+  }
+
+  flush(device: GPUDevice): void {
+    for (const c of this._chunks) c.flush(device);
+  }
+
+  write(chunkIdx: number, dst: number, data: Uint8Array): void {
+    this._chunks[chunkIdx]!.write(dst, data);
+  }
+
+  onChunkAdded(cb: (chunkIdx: number) => void): IDisposable {
+    this.onChunkAddedCbs.add(cb);
+    return { dispose: () => { this.onChunkAddedCbs.delete(cb); } };
+  }
+
+  onAnyResize(cb: (chunkIdx: number) => void): IDisposable {
+    const disposables: IDisposable[] = [];
+    for (let i = 0; i < this._chunks.length; i++) {
+      const idx = i;
+      disposables.push(this._chunks[i]!.onResize(() => cb(idx)));
+    }
+    disposables.push(this.onChunkAdded((idx) => {
+      disposables.push(this._chunks[idx]!.onResize(() => cb(idx)));
+      cb(idx);
+    }));
+    return { dispose: () => { for (const d of disposables) d.dispose(); } };
+  }
+
+  totalUsedElements(): number {
+    let s = 0;
+    for (const c of this._chunks) s += c.usedElements;
+    return s;
+  }
+
+  destroy(): void {
+    for (const c of this._chunks) c.destroy();
+    this._chunks.length = 0;
+  }
+
+  private openChunk(): number {
+    const idx = this._chunks.length;
+    const buf = new GrowBuffer(
+      this.device, `${this.label}/c${idx}`, this.usage,
+      this.initialChunkBytes, this.maxChunkBytes,
+    );
+    this._chunks.push(new IndexAllocator(buf));
+    for (const cb of this.onChunkAddedCbs) cb(idx);
+    return idx;
+  }
+}

package/src/runtime/heapScene/freelist.ts

@@ -0,0 +1,196 @@
+// 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. */
+  private readonly bySize = new Map<number, Set<number>>();
+  /** Sorted ascending list of every size present in `bySize`. */
+  private readonly sizes: number[] = [];
+  /** off → size, for the right-coalesce probe in `release`. */
+  private readonly byStart = new Map<number, number>();
+  /** off+size (= end offset) → off, for the left-coalesce probe. */
+  private readonly byEnd = new Map<number, number>();
+
+  /** Number of distinct free blocks currently tracked. */
+  get blockCount(): number { 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: number): number | undefined {
+    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 as number;
+    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: number, size: number): void {
+    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: number): { off: number; size: number } | undefined {
+    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(): void {
+    this.bySize.clear();
+    this.sizes.length = 0;
+    this.byStart.clear();
+    this.byEnd.clear();
+  }
+
+  /** Snapshot for tests / debugging — sorted by offset. */
+  toArray(): Array<{ off: number; size: number }> {
+    const out: Array<{ off: number; size: number }> = [];
+    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: string): void {
+    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}`,
+        );
+      }
+    }
+  }
+
+  private addBlock(off: number, size: number): void {
+    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);
+  }
+
+  private removeBlock(off: number, size: number): void {
+    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: ReadonlyArray<number>, target: number): number {
+  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;
+}