@aardworx/wombat.rendering 0.18.1 → 0.19.1

package/src/runtime/heapScene/pools.ts

@@ -112,9 +112,23 @@ export class UniformPool {
       return existing.ref;
     }
     const r = arena.alloc(dataBytes, chunkIdx);
-    // The alloc may have spilled into a different chunk if `chunkIdx`
-    // was full. Honour wherever it landed — addRO's chunk-routing
-    // commits the RO to the spill chunk too.
+    // `arena.alloc` may spill to a different chunk if `chunkIdx`'s
+    // GrowBuffer is at its maxCapacity. Callers (heapScene.addRO)
+    // bind a bucket's bind groups to a single chunk's buffer — a
+    // silent spill makes the bucket's drawHeader refs point into
+    // the wrong chunk's buffer (garbage reads / typeId corruption).
+    //
+    // Hard-fail with diagnostic info instead of returning quietly.
+    // The right long-term fix is for addRO to pre-probe the chunk,
+    // open a new bucket bound to the spill chunk, and re-route; but
+    // until that lands, a clear error beats unexplained artefacts.
+    if (r.chunkIdx !== chunkIdx) {
+      throw new Error(
+        `UniformPool.acquire: allocator spilled from chunk ${chunkIdx} to chunk ${r.chunkIdx} ` +
+        `(${dataBytes} bytes). Caller's bucket is bound to chunk ${chunkIdx}; this would silently ` +
+        `corrupt the drawHeader→arena reads. Open a new bucket bound to chunk ${r.chunkIdx} instead.`,
+      );
+    }
     const finalChunk = r.chunkIdx;
     const allocBytes = ALIGN16(ALLOC_HEADER_PAD_TO + dataBytes);
     const buf = new ArrayBuffer(allocBytes);
@@ -142,7 +156,17 @@ export class UniformPool {
     if (e === undefined) return;
     e.refcount--;
     if (e.refcount > 0) return;
-    arena.release(e.chunkIdx, e.ref, ALIGN16(ALLOC_HEADER_PAD_TO + e.dataBytes));
+    // BUG FIX: arena.release's third arg is `dataBytes` (raw), and the
+    // chunk's AttributeArena.release internally adds the header padding
+    // via `ALIGN16(ALLOC_HEADER_PAD_TO + dataBytes)`. We MUST pass the
+    // raw data size here — passing pre-aligned `allocBytes` (the old
+    // code) double-pads, freeing 16 extra bytes per release. The freed
+    // surplus then gets coalesced with the neighbouring scalar-uniform
+    // allocs (any 32 B u32/f32) into a single combined block, and the
+    // next attribute alloc handed out from that pool ends up STARTING
+    // 16 B inside the previous alloc → overlapping allocations →
+    // garbage `typeId`/`length` in the attribute header.
+    arena.release(e.chunkIdx, e.ref, e.dataBytes);
     byChunk!.delete(chunkIdx);
     if (byChunk!.size === 0) this.byAval.delete(av);
   }
@@ -312,6 +336,8 @@ interface IndexPoolEntry {
 export class DrawHeap {
   private free: number[] = [];
   private nextSlot = 0;
+  /** DEBUG: tracks slot live/free state. true = live (in use). */
+  private readonly live = new Set<number>();
   constructor(private readonly buf: GrowBuffer, private readonly slotBytes: number) {}
   get buffer(): GPUBuffer { return this.buf.buffer; }
   /** Bytes per slot — caller multiplies by slot index for byte offsets. */
@@ -320,11 +346,21 @@ export class DrawHeap {
   get usedBytes(): number { return this.nextSlot * this.slotBytes; }
   alloc(): number {
     const slot = this.free.length > 0 ? this.free.pop()! : this.nextSlot++;
+    if (this.live.has(slot)) {
+      throw new Error(`DrawHeap.alloc: returned already-live slot ${slot}`);
+    }
+    this.live.add(slot);
     this.buf.ensureCapacity((slot + 1) * this.slotBytes);
     this.buf.setUsed(Math.max(this.buf.usedBytes, (slot + 1) * this.slotBytes));
     return slot;
   }
-  release(slot: number): void { this.free.push(slot); }
+  release(slot: number): void {
+    if (!this.live.has(slot)) {
+      throw new Error(`DrawHeap.release: slot ${slot} was not live — double-release or release-of-never-allocated.`);
+    }
+    this.live.delete(slot);
+    this.free.push(slot);
+  }
   onResize(cb: () => void): IDisposable { return this.buf.onResize(cb); }
   destroy(): void { this.buf.destroy(); }
 }
@@ -340,6 +376,11 @@ export class DrawHeap {
 export class AttributeArena {
   private cursor = 0;
   private readonly freelist = new 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 = new Map<number, number>();
   /** CPU shadow of the entire GPU buffer; writes go here first then
    *  flush() emits one writeBuffer per dirty contiguous range. */
   private shadow: Uint8Array;
@@ -356,6 +397,15 @@ export class AttributeArena {
   get buffer(): GPUBuffer { return this.buf.buffer; }
   get capacity(): number { return this.buf.capacity; }
   get usedBytes(): number { return this.cursor; }
+  /** 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 {
+    return new Uint32Array(this.shadow.buffer, this.shadow.byteOffset + off, count);
+  }
   write(dst: number, data: Uint8Array): void {
     this.shadow.set(data, dst);
     if (dst < this.dirtyMin) this.dirtyMin = dst;
@@ -383,13 +433,18 @@ export class AttributeArena {
   tryAlloc(dataBytes: number): number | undefined {
     const allocBytes = ALIGN16(ALLOC_HEADER_PAD_TO + dataBytes);
     const reused = this.freelist.alloc(allocBytes);
-    if (reused !== undefined) return reused;
+    if (reused !== undefined) {
+      this.recordAlloc(reused, allocBytes, "freelist");
+      return reused;
+    }
     const next = this.cursor + allocBytes;
     if (next > this.buf.maxCapacity) return undefined;
     this.cursor = next;
     this.buf.ensureCapacity(next);
     this.buf.setUsed(next);
-    return next - allocBytes;
+    const ref = next - allocBytes;
+    this.recordAlloc(ref, allocBytes, "bump");
+    return ref;
   }
   alloc(dataBytes: number): number {
     const r = this.tryAlloc(dataBytes);
@@ -402,6 +457,22 @@ export class AttributeArena {
   }
   release(ref: number, dataBytes: number): void {
     const allocBytes = ALIGN16(ALLOC_HEADER_PAD_TO + dataBytes);
+    const tracked = this.liveAllocs.get(ref);
+    if (tracked === undefined) {
+      throw new Error(
+        `AttributeArena.release: ref=${ref} (size=${allocBytes}) was not in liveAllocs — ` +
+        `double-free or release for an alloc that never happened. ` +
+        `Live alloc count=${this.liveAllocs.size}.`,
+      );
+    }
+    if (tracked !== allocBytes) {
+      throw new Error(
+        `AttributeArena.release: size mismatch at ref=${ref} — recorded=${tracked} but ` +
+        `release args→ allocBytes=${allocBytes} (dataBytes=${dataBytes}). ` +
+        `Caller is releasing the wrong size; this WILL corrupt the freelist via over- or under-shrinking.`,
+      );
+    }
+    this.liveAllocs.delete(ref);
     this.freelist.release(ref, allocBytes);
     // §5: shrink the bump cursor back if release exposed a free
     // tail touching it (cascading — `freelist.release` may have
@@ -414,6 +485,23 @@ export class AttributeArena {
       this.buf.setUsed(this.cursor);
     }
   }
+  /** Throws if the just-returned alloc overlaps any live allocation. */
+  private recordAlloc(off: number, size: number, source: string): void {
+    // Check against every existing live alloc — O(N). Cheap while N
+    // is small (per-tile demos run with ~hundreds of allocs). Wire
+    // off behind an env-flag if it ever becomes a hot path.
+    for (const [liveOff, liveSize] of this.liveAllocs) {
+      // [a, a+sa) vs [b, b+sb) overlap iff a < b+sb && b < a+sa
+      if (off < liveOff + liveSize && liveOff < off + size) {
+        throw new Error(
+          `AttributeArena.tryAlloc(${source}): returned [${off},${off + size}) ` +
+          `(size=${size}) overlaps live alloc at [${liveOff},${liveOff + liveSize}) ` +
+          `(size=${liveSize}). Allocator is handing out shared memory!`,
+        );
+      }
+    }
+    this.liveAllocs.set(off, size);
+  }
   onResize(cb: () => void): IDisposable { return this.buf.onResize(cb); }
   destroy(): void { this.buf.destroy(); }
 }
@@ -428,6 +516,8 @@ export class AttributeArena {
 export class IndexAllocator {
   private cursor = 0;     // in u32s, not bytes
   private readonly freelist = new Freelist();
+  /** DEBUG: live index allocations tracked by start element. */
+  private readonly liveAllocs = new Map<number, number>();
   private shadow: Uint8Array;
   private dirtyMin = Infinity;
   private dirtyMax = 0;
@@ -462,13 +552,30 @@ export class IndexAllocator {
    *  Used by `ChunkedIndexAllocator` to probe before spilling. */
   tryAlloc(elements: number): number | undefined {
     const reused = this.freelist.alloc(elements);
-    if (reused !== undefined) return reused;
+    if (reused !== undefined) {
+      this.recordAlloc(reused, elements, "freelist");
+      return reused;
+    }
     const nextElts = this.cursor + elements;
     if (nextElts * 4 > this.buf.maxCapacity) return undefined;
     this.cursor = nextElts;
     this.buf.ensureCapacity(nextElts * 4);
     this.buf.setUsed(nextElts * 4);
-    return nextElts - elements;
+    const off = nextElts - elements;
+    this.recordAlloc(off, elements, "bump");
+    return off;
+  }
+  private recordAlloc(off: number, size: number, source: string): void {
+    for (const [liveOff, liveSize] of this.liveAllocs) {
+      if (off < liveOff + liveSize && liveOff < off + size) {
+        throw new Error(
+          `IndexAllocator.tryAlloc(${source}): returned [${off},${off + size}) ` +
+          `(size=${size}) overlaps live alloc at [${liveOff},${liveOff + liveSize}) ` +
+          `(size=${liveSize}). Index allocator is handing out shared memory!`,
+        );
+      }
+    }
+    this.liveAllocs.set(off, size);
   }
   alloc(elements: number): number {
     const r = this.tryAlloc(elements);
@@ -478,10 +585,22 @@ export class IndexAllocator {
     return r;
   }
   release(off: number, elements: number): void {
+    const tracked = this.liveAllocs.get(off);
+    if (tracked === undefined) {
+      throw new Error(
+        `IndexAllocator.release: off=${off} (elements=${elements}) was not in ` +
+        `liveAllocs — double-free or release for an alloc that never happened. ` +
+        `Live alloc count=${this.liveAllocs.size}.`,
+      );
+    }
+    if (tracked !== elements) {
+      throw new Error(
+        `IndexAllocator.release: size mismatch at off=${off} — recorded=${tracked} ` +
+        `but release elements=${elements}. Will corrupt the freelist.`,
+      );
+    }
+    this.liveAllocs.delete(off);
     this.freelist.release(off, elements);
-    // §5: cursor-shrink mirror of AttributeArena.release. Cursor
-    // is in u32 elements here, and setUsed on the GrowBuffer
-    // expects bytes — multiply by 4.
     while (true) {
       const top = this.freelist.takeBlockEndingAt(this.cursor);
       if (top === undefined) break;

package/src/runtime/heapScene.ts

@@ -43,7 +43,7 @@
 // group's bind-group layout; the user's FS WGSL declares them.
 
 import { Trafo3d, V3d, V4f, M44d, type V2f } from "@aardworx/wombat.base";
-import type { ITexture } from "../core/texture.js";
+import type { HostTextureSource, ITexture } from "../core/texture.js";
 import type { ISampler } from "../core/sampler.js";
 import { AVal, AdaptiveObject, AdaptiveToken, HashTable } from "@aardworx/wombat.adaptive";
 import type { aval, aset, IAdaptiveObject, IDisposable, IHashSetReader } from "@aardworx/wombat.adaptive";
@@ -438,6 +438,18 @@ export interface HeapDrawSpec {
    * computes `indexCount * instanceCount` per record.
    */
   readonly instanceCount?: aval<number> | number;
+  /**
+   * Optional visibility gate. When ticks to `false`, this RO emits
+   * 0 vertices that frame — its drawTable record gets effective
+   * `indexCount = 0`, the scan kernel's prefix sum skips past it,
+   * and no fragment shader invocations fire. Pool allocations,
+   * arena uploads, and bucket membership all stay intact, so the
+   * `true → false → true` round-trip is a pair of small drawTable
+   * writes plus a scan-pass re-issue — no `addDraw`/`removeDraw`
+   * churn. Designed for `<Sg Active={cval}>` driven by LOD walkers
+   * that flip many tiles per camera move.
+   */
+  readonly active?: aval<boolean>;
   /**
    * Index buffer for this draw. Indices live in their own `INDEX`-
    * usage `GPUBuffer` (WebGPU forces this), separate from the arena.
@@ -633,6 +645,14 @@ export type HeapTextureSet =
        * reference.
        */
       readonly repack?: (newTex: ITexture) => import("./textureAtlas/atlasPool.js").AtlasAcquisition;
+      /**
+       * Host source captured at adapter time, used by the heap-side
+       * re-acquire path when the pool entry was evicted while this spec
+       * sat idle (heap remove → re-add). Without it, `AtlasPool.acquire`
+       * allocates a fresh sub-rect with no `source` and skips `upload()`,
+       * leaving the drawHeader pointing at uninitialized atlas pixels.
+       */
+      readonly host?: HostTextureSource;
     };
 
 /**
@@ -774,6 +794,90 @@ export function buildHeapScene(
   const modeAvalToDrawIds  = new Map<aval<unknown>, Set<number>>();
   const modeAvalCallbacks  = new Map<aval<unknown>, IDisposable>();
 
+  // ─── HeapDrawSpec.active subscription ────────────────────────────────
+  // Per-drawId state for the "skip without re-allocating" path. When a
+  // tile (or any RO) flips visibility many times per second (e.g. an
+  // LOD walker culling/uncrossing the frustum), pool churn would be
+  // prohibitive. Instead we keep the RO in the bucket and flip its
+  // drawTable record's `indexCount` field between the original count
+  // (visible) and 0 (hidden). The scan kernel's prefix sum naturally
+  // skips a record with 0 emit count, so this costs one drawTable
+  // write + a re-scan dispatch — no arena/freelist activity.
+  const drawIdToActiveAval = new Map<number, aval<boolean>>();
+  const drawIdToOrigIndexCount = new Map<number, number>();
+  const drawIdToActiveCallback = new Map<number, IDisposable>();
+  const activeAvalToDrawIds = new Map<aval<boolean>, Set<number>>();
+  const activeDirty = new Set<number>();
+
+  function subscribeActive(av: aval<boolean>, drawId: number): void {
+    let set = activeAvalToDrawIds.get(av);
+    if (set === undefined) {
+      set = new Set<number>();
+      activeAvalToDrawIds.set(av, set);
+    }
+    set.add(drawId);
+    const cb = addMarkingCallback(av, () => { activeDirty.add(drawId); });
+    drawIdToActiveCallback.set(drawId, cb);
+  }
+
+  function unsubscribeActive(drawId: number): void {
+    const av = drawIdToActiveAval.get(drawId);
+    if (av === undefined) return;
+    const cb = drawIdToActiveCallback.get(drawId);
+    cb?.dispose();
+    drawIdToActiveCallback.delete(drawId);
+    const set = activeAvalToDrawIds.get(av);
+    if (set !== undefined) {
+      set.delete(drawId);
+      if (set.size === 0) activeAvalToDrawIds.delete(av);
+    }
+    drawIdToActiveAval.delete(drawId);
+    drawIdToOrigIndexCount.delete(drawId);
+    activeDirty.delete(drawId);
+  }
+
+  /** Update the drawTable record's effective indexCount in place
+   *  (GPU-routed: masterShadow + partition re-dispatch; legacy:
+   *  drawTableShadow + scan re-dispatch). Common helper used by the
+   *  active-aval drain in `update()`. */
+  function setEffectiveIndexCount(drawId: number, newIndexCount: number): void {
+    const bucket = drawIdToBucket[drawId];
+    if (bucket === undefined) return;
+    if (bucket.gpuRouted) {
+      const partition = bucket.partitionScene!;
+      const recIdx = bucket.drawIdToRecord!.get(drawId);
+      if (recIdx === undefined) return;
+      const ru32 = partition.recordU32;
+      const oldIndexCount = partition.masterShadow[recIdx * ru32 + 3]!;
+      const instanceCount = partition.masterShadow[recIdx * ru32 + 4]!;
+      partition.masterShadow[recIdx * ru32 + 3] = newIndexCount >>> 0;
+      const delta = (newIndexCount - oldIndexCount) * instanceCount;
+      bucket.partitionDirty = true;
+      for (const s of bucket.slots) {
+        s.totalEmitEstimate = Math.max(0, s.totalEmitEstimate + delta);
+        s.scanDirty = true;
+      }
+    } else {
+      const slotIdx = drawIdToSlotIdx[drawId];
+      const slot = slotIdx !== undefined ? bucket.slots[slotIdx] : bucket.slots[0];
+      if (slot === undefined) return;
+      const localSlot = drawIdToLocalSlot[drawId];
+      if (localSlot === undefined) return;
+      const recIdx = slot.slotToRecord[localSlot];
+      if (recIdx === undefined || recIdx < 0) return;
+      const shadow = slot.drawTableShadow!;
+      const oldIndexCount = shadow[recIdx * RECORD_U32 + 3]!;
+      const instanceCount = shadow[recIdx * RECORD_U32 + 4]!;
+      shadow[recIdx * RECORD_U32 + 3] = newIndexCount >>> 0;
+      const byteOff = recIdx * RECORD_BYTES + 3 * 4;
+      if (byteOff < slot.drawTableDirtyMin) slot.drawTableDirtyMin = byteOff;
+      if (byteOff + 4 > slot.drawTableDirtyMax) slot.drawTableDirtyMax = byteOff + 4;
+      const delta = (newIndexCount - oldIndexCount) * instanceCount;
+      slot.totalEmitEstimate = Math.max(0, slot.totalEmitEstimate + delta);
+      slot.scanDirty = true;
+    }
+  }
+
   function subscribeModeLeaf(av: aval<unknown>, drawId: number): void {
     let set = modeAvalToDrawIds.get(av);
     if (set === undefined) {
@@ -2785,6 +2889,11 @@ export function buildHeapScene(
   // inside a single outer evaluateAlways and invoke addDrawImpl
   // directly with their token — collapsing 1000× nested
   // evaluateAlways into 1× outer.
+  // DEBUG counters.
+  let __addDrawCalls = 0;
+  let __removeDrawCalls = 0;
+  (sceneObj as unknown as { __addDrawCalls: () => number }).__addDrawCalls = () => __addDrawCalls;
+  (sceneObj as unknown as { __removeDrawCalls: () => number }).__removeDrawCalls = () => __removeDrawCalls;
   function addDraw(spec: HeapDrawSpec): number {
     let id = -1;
     sceneObj.evaluateAlways(AdaptiveToken.top, (tok) => {
@@ -2793,6 +2902,7 @@ export function buildHeapScene(
     return id;
   }
   function addDrawImpl(spec: HeapDrawSpec, outerTok: AdaptiveToken): number {
+    __addDrawCalls++;
     const drawId = nextDrawId++;
     // Family-merge (slice 3c): build the family lazily from this
     // single spec when no batched lazy-build occurred earlier (e.g.
@@ -2991,6 +3101,65 @@ export function buildHeapScene(
     packBucketHeader(bucket, localSlot, perDrawRefs, layoutId);
     if (bucket.isAtlasBucket && spec.textures !== undefined && spec.textures.kind === "atlas") {
       packAtlasTextureFields(bucket, localSlot, spec.textures);
+      // Pair this addDraw with one atlas refcount bump. The spec's
+      // release closure (stored below, fired in removeDraw) decrements
+      // exactly once per add/remove cycle; without this incRef the
+      // refcount underflows when the same cached spec is re-introduced
+      // across multiple aset add/remove cycles (e.g., a tile flipping
+      // in and out of the heap-eligible subset).
+      //
+      // Falls back to a full re-acquire if the entry was already
+      // evicted (incRef returns false): in that case the spec's stored
+      // (pageId, origin, size) are stale and the new acquire's values
+      // overwrite them before packAtlasTextureFields is re-called.
+      if (atlasPool !== undefined) {
+        const ok = atlasPool.incRef(spec.textures.poolRef);
+        if (!ok) {
+          // Entry was evicted while the cached spec was idle in heap-
+          // remove state. Acquire a fresh sub-rect, redirect the spec
+          // (and the per-aval cell behind its release closure) to the
+          // new ref, and re-emit the drawHeader fields.
+          // Pass the captured `host` as `source` so the pool's
+          // `finalize` re-runs `upload()` for the fresh sub-rect. Without
+          // this, AtlasPool.acquire allocates the rect and skips the
+          // upload (the `source.host !== undefined` branch in finalize),
+          // so the drawHeader points at uninitialized atlas pixels —
+          // exactly the "black rectangle holes" symptom on tiles that
+          // cycled out and back in across a long-enough gap to be
+          // evicted.
+          const reW = spec.textures.size.x;
+          const reH = spec.textures.size.y;
+          const host = spec.textures.host;
+          const acq = atlasPool.acquire(
+            spec.textures.page.format,
+            spec.textures.sourceAval as aval<ITexture>,
+            reW, reH,
+            {
+              wantsMips: spec.textures.numMips > 1,
+              ...(host !== undefined ? { source: { width: reW, height: reH, host } } : {}),
+            },
+          );
+          (spec.textures as { pageId: number }).pageId = acq.pageId;
+          (spec.textures as { origin: V2f }).origin = acq.origin;
+          (spec.textures as { size: V2f }).size = acq.size;
+          (spec.textures as { numMips: number }).numMips = acq.numMips;
+          (spec.textures as { page: AtlasPage }).page = acq.page;
+          (spec.textures as { poolRef: number }).poolRef = acq.ref;
+          // The release closure captures a per-aval cell whose `ref`
+          // must track the LATEST acquired sub-rect; otherwise the
+          // closure releases a long-evicted ref (no-op leak).
+          if (spec.textures.repack !== undefined) {
+            // repack updates the per-aval cell to the new ref as a
+            // side effect of its own atlas-mark drain path. Re-using
+            // it here would free the entry we just acquired; instead
+            // mirror the same effect with a tiny helper attached to
+            // the spec at adapter time (`__retarget`).
+          }
+          const retarget = (spec.textures as unknown as { __retarget?: (ref: number) => void }).__retarget;
+          if (retarget !== undefined) retarget(acq.ref);
+          packAtlasTextureFields(bucket, localSlot, spec.textures);
+        }
+      }
       bucket.localAtlasReleases[localSlot] = spec.textures.release;
       bucket.localAtlasTextures[localSlot] = spec.textures;
       // Reactivity wire-up: subscribe to `sourceAval` (so sceneObj.inputChanged
@@ -3099,6 +3268,23 @@ export function buildHeapScene(
     drawIdToSlotIdx[drawId]   = roSlotIdx;
     drawIdToIndexAval[drawId] = indicesAval;
 
+    // ─── HeapDrawSpec.active wire-up ──────────────────────────────────
+    // Track the visibility aval (if any) and apply its initial value
+    // immediately. After this point, ticks on the aval are routed via
+    // `subscribeActive` → `activeDirty` and drained in `update()`.
+    if (spec.active !== undefined) {
+      drawIdToActiveAval.set(drawId, spec.active);
+      drawIdToOrigIndexCount.set(drawId, idxAlloc.count);
+      const initial = spec.active.getValue(outerTok);
+      subscribeActive(spec.active, drawId);
+      if (initial === false) {
+        // Apply the off state synchronously so the very first frame
+        // already skips this RO (no flash of un-gated geometry while
+        // we wait for the next update tick).
+        setEffectiveIndexCount(drawId, 0);
+      }
+    }
+
     // ─── Reactive rebucket: track PS-modeKey changes ────────────────
     // When any mode-axis aval marks (e.g. cullCval.value = 'front'),
     // schedule this RO for rebucket on the next update(). Today's
@@ -3203,9 +3389,13 @@ export function buildHeapScene(
   }
 
   function removeDraw(drawId: number): void {
+    __removeDrawCalls++;
     const bucket    = drawIdToBucket[drawId];
     const localSlot = drawIdToLocalSlot[drawId];
     if (bucket === undefined || localSlot === undefined) return;
+    // Tear down `active` subscription (if any) so its callback won't
+    // fire after the underlying drawTable record is gone.
+    unsubscribeActive(drawId);
     // §7: deregister this RO's derivation records and release slots.
     if (derivedScene !== undefined) {
       const reg = derivedByDrawId.get(drawId);
@@ -3218,9 +3408,15 @@ export function buildHeapScene(
       const partition = bucket.partitionScene!;
       const recIdx = bucket.drawIdToRecord!.get(drawId);
       const removedEntry = bucket.localEntries[localSlot];
-      const removedCount = removedEntry !== undefined
-        ? removedEntry.indexCount * removedEntry.instanceCount
-        : 0;
+      // Read the EFFECTIVE indexCount from masterShadow (already 0 for
+      // an inactive draw via setEffectiveIndexCount). Using the original
+      // count from localEntries would double-subtract for inactive draws
+      // (whose contribution was already removed when active flipped false).
+      const effectiveIndexCount = recIdx !== undefined
+        ? partition.masterShadow[recIdx * partition.recordU32 + 3]!
+        : (removedEntry?.indexCount ?? 0);
+      const instanceCount = removedEntry?.instanceCount ?? 0;
+      const removedCount = effectiveIndexCount * instanceCount;
       if (recIdx !== undefined) {
         const moved = partition.removeRecord(recIdx);
         if (moved >= 0) {
@@ -3247,9 +3443,15 @@ export function buildHeapScene(
       const slotIdx = drawIdToSlotIdx[drawId];
       const slot = slotIdx !== undefined ? bucket.slots[slotIdx]! : bucket.slots[0]!;
       const removedEntry = bucket.localEntries[localSlot];
-      const removedCount = removedEntry !== undefined
-        ? removedEntry.indexCount * removedEntry.instanceCount
-        : 0;
+      const localSlotRec = slot.slotToRecord[localSlot];
+      // Effective (post-active) indexCount, read from shadow so that
+      // inactive draws contribute 0 here (their contribution was
+      // already removed when active flipped false).
+      const effectiveIndexCount = localSlotRec !== undefined && localSlotRec >= 0
+        ? slot.drawTableShadow![localSlotRec * RECORD_U32 + 3]!
+        : (removedEntry?.indexCount ?? 0);
+      const instanceCount = removedEntry?.instanceCount ?? 0;
+      const removedCount = effectiveIndexCount * instanceCount;
       slot.totalEmitEstimate = Math.max(0, slot.totalEmitEstimate - removedCount);
       // Swap-pop: move the last record into the freed slot, decrement
       // recordCount. firstEmit is GPU-rewritten by the next scan, so
@@ -3545,6 +3747,22 @@ export function buildHeapScene(
         allocDirty.clear();
       }
 
+      // 1c. HeapDrawSpec.active drain — flip drawTable.indexCount
+      //     between origIndexCount (visible) and 0 (hidden) for any RO
+      //     whose active aval ticked since last frame. Set is small in
+      //     steady state (only the ROs whose visibility actually
+      //     changed). No pool / arena / freelist activity.
+      if (activeDirty.size > 0) {
+        for (const did of activeDirty) {
+          const av = drawIdToActiveAval.get(did);
+          if (av === undefined) continue;
+          const a = av.getValue(tok);
+          const orig = drawIdToOrigIndexCount.get(did) ?? 0;
+          setEffectiveIndexCount(did, a ? orig : 0);
+        }
+        activeDirty.clear();
+      }
+
       // 1b. Atlas-texture aval reactivity: an `aval<ITexture>` that
       //     drives an atlas placement was marked. Repack the pool entry
       //     and rewrite the drawHeader fields of every (bucket, slot)
@@ -3994,7 +4212,26 @@ export function buildHeapScene(
             const length = arenaU32[refU32 + 1]!;
 
             if (!KNOWN_TYPE_IDS.has(typeId)) {
-              push(`bucket#${bucketIdx} slot=${slot} field='${f.name}' alloc@0x${ref.toString(16)} typeId=${typeId} unknown`);
+              // Dump the first 8 u32s of the alloc to help diagnose
+              // what wrote garbage onto the header. Also peek the
+              // FOUR u32s BEFORE the alloc to see if a neighbour
+              // overran into us.
+              const before = refU32 >= 4
+                ? `prev=[${arenaU32[refU32 - 4]},${arenaU32[refU32 - 3]},${arenaU32[refU32 - 2]},${arenaU32[refU32 - 1]}] `
+                : "";
+              const here = `here=[${arenaU32[refU32]},${arenaU32[refU32 + 1]},${arenaU32[refU32 + 2]},${arenaU32[refU32 + 3]},${arenaU32[refU32 + 4]},${arenaU32[refU32 + 5]},${arenaU32[refU32 + 6]},${arenaU32[refU32 + 7]}]`;
+              // Compare CPU shadow vs GPU read-back. Differ → GPU
+              // write corrupted; match → bug is in CPU-side write path
+              // OR the alloc never went through pool.acquire.
+              const shadowChunk = arena.attrs.chunk(0);
+              const shadowU32 = shadowChunk.peekShadowU32(ref, 8);
+              const shadowStr = `shadow=[${shadowU32[0]},${shadowU32[1]},${shadowU32[2]},${shadowU32[3]},${shadowU32[4]},${shadowU32[5]},${shadowU32[6]},${shadowU32[7]}]`;
+              const cpuMatches = shadowU32[0] === arenaU32[refU32]
+                && shadowU32[1] === arenaU32[refU32 + 1]
+                && shadowU32[2] === arenaU32[refU32 + 2]
+                && shadowU32[3] === arenaU32[refU32 + 3];
+              const verdict = cpuMatches ? "GPU=CPU (likely CPU-write bug)" : "GPU≠CPU (likely GPU-write corruption)";
+              push(`bucket#${bucketIdx} slot=${slot} field='${f.name}' alloc@0x${ref.toString(16)} typeId=${typeId} unknown ${verdict} ${before}${here} ${shadowStr}`);
               attrAllocsBad++;
               continue;
             }
@@ -4102,11 +4339,18 @@ export function buildHeapScene(
                 tilesBad++;
               }
             }
+            // The scan kernel intentionally writes `numRecords - 1` as the
+            // sentinel (not `numRecords`) — the render VS's binary search
+            // uses `hi = firstDrawInTile[_tileIdx + 1u]` as an *inclusive*
+            // upper bound, so the sentinel must point at the last valid
+            // record slot. See scanKernel.ts `buildTileIndex` for the
+            // full rationale.
+            const expectedSentinel = recordCount === 0 ? 0 : recordCount - 1;
             const sentinel = fdt[dc.numTiles]!;
             tilesChecked++;
-            if (sentinel !== recordCount) {
+            if (sentinel !== expectedSentinel) {
               push(`bucket#${bucketIdx} firstDrawInTile[${dc.numTiles}] sentinel ` +
-                `got=${sentinel} expected=${recordCount}`);
+                `got=${sentinel} expected=${expectedSentinel}`);
               tilesBad++;
             }
             dc.firstDrawInTile.unmap();
@@ -5018,5 +5262,7 @@ export function buildHeapScene(
     },
   };
 
-  return { frame, update, encodeIntoPass, encodeComputePrep, addDraw, removeDraw, stats, dispose, _debug } as HeapScene;
+  const __addDrawCallsGetter = (): number => __addDrawCalls;
+  const __removeDrawCallsGetter = (): number => __removeDrawCalls;
+  return { frame, update, encodeIntoPass, encodeComputePrep, addDraw, removeDraw, stats, dispose, _debug, __addDrawCalls: __addDrawCallsGetter, __removeDrawCalls: __removeDrawCallsGetter } as HeapScene;
 }

package/src/runtime/hybridScene.ts

@@ -124,6 +124,14 @@ export interface HybridScene {
    * pipelineState. Useful for status / dev-overlay text.
    */
   heapBucketCount(): number;
+  /** DEBUG: outstanding live ROs in the heap path. */
+  heapTotalDraws(): number;
+  /** DEBUG: cumulative addDraw invocations on the heap scene. */
+  __addDrawCalls(): number;
+  /** DEBUG: cumulative removeDraw invocations on the heap scene. */
+  __removeDrawCalls(): number;
+  /** DEBUG: current legacy-path RO count. */
+  __legacyCount(): number;
   /** Per-frame breakdown of §7 derived-uniforms work (CPU). */
   heapDerivedTimings(): {
     pullMs: number; uploadMs: number; encodeMs: number; records: number;
@@ -211,6 +219,7 @@ export function compileHybridScene(
   // comments) — the pool is wired here so the next PR can add Tier-S
   // classification without touching this file.
   const atlasPool = new AtlasPool(device);
+  (globalThis as { __atlasDebug?: AtlasPool }).__atlasDebug = atlasPool;
 
   // ─── Heap subset → HeapDrawSpec aset ─────────────────────────────
   // Memoize the adapter: aset removal must identify the SAME spec
@@ -268,6 +277,20 @@ export function compileHybridScene(
     heapBucketCount(): number {
       return heapScene.stats.groups;
     },
+    heapTotalDraws(): number {
+      return heapScene.stats.totalDraws;
+    },
+    __addDrawCalls(): number {
+      const fn = (heapScene as unknown as { __addDrawCalls?: () => number }).__addDrawCalls;
+      return fn ? fn() : -1;
+    },
+    __removeDrawCalls(): number {
+      const fn = (heapScene as unknown as { __removeDrawCalls?: () => number }).__removeDrawCalls;
+      return fn ? fn() : -1;
+    },
+    __legacyCount(): number {
+      return scenePass.collect().length;
+    },
     heapDerivedTimings() {
       const s = heapScene.stats;
       return {