@aardworx/wombat.rendering 0.9.33 → 0.19.0

package/src/runtime/hybridScene.ts

@@ -85,6 +85,13 @@ export interface CompileHybridSceneOptions {
    * §7 derived-uniforms opt-in — pass-through to `BuildHeapSceneOptions`.
    */
   readonly enableDerivedUniforms?: boolean;
+  /**
+   * §3 — per-arena-chunk byte cap. Pass-through to
+   * `BuildHeapSceneOptions.maxChunkBytes`. Demo / test value
+   * (e.g. 4 MB) exercises multi-chunk routing without needing
+   * massive workloads.
+   */
+  readonly maxChunkBytes?: number;
 }
 
 export interface HybridScene {
@@ -117,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;
@@ -204,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
@@ -226,6 +242,7 @@ export function compileHybridScene(
     atlasPool,
     ...(opts.enableFamilyMerge === true ? { enableFamilyMerge: true } : {}),
     ...(opts.enableDerivedUniforms === false ? { enableDerivedUniforms: false } : {}),
+    ...(opts.maxChunkBytes !== undefined ? { maxChunkBytes: opts.maxChunkBytes } : {}),
   });
 
   // ─── Legacy subset → RenderTree → ScenePass ──────────────────────
@@ -260,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 {

package/src/runtime/index.ts

@@ -130,18 +130,21 @@ export {
 export {
   derivedMode,
   isDerivedModeRule,
-  flipCull,
-  gpuFlipCullByDeterminant,
   type DerivedModeRule,
-  type DerivedModeBuilder,
-  type GpuRuleSpec,
   type ModeAxis,
   type ModeValue,
 } from "./derivedModes/rule.js";
 
-export { GpuDerivedModesScene } from "./derivedModes/gpuDispatcher.js";
 export {
-  GPU_FLIP_CULL_BY_DET_WGSL,
-  CULL_TO_U32,
-  U32_TO_CULL,
-} from "./derivedModes/gpuKernel.js";
+  PARTITION_RECORD_PREFIX_U32,
+  partitionRecordU32,
+  partitionRecordBytes,
+} from "./derivedModes/partitionKernelLayout.js";
+export { GpuPartitionScene, type PartitionSceneSpec } from "./derivedModes/partitionDispatcher.js";
+export {
+  emitPartitionKernel,
+  substituteReadInput, substituteReadInputInStmt,
+  collectUniformReadsInStmt,
+  rewriteOutputsToSlotIndices,
+  type RuleCodegenSpec, type KernelCodegenSpec,
+} from "./derivedModes/kernelCodegen.js";

package/src/runtime/renderTask.ts

@@ -54,6 +54,11 @@ export interface RuntimeContext {
    * compiled against this context.
    */
   readonly enableDerivedUniforms?: boolean;
+  /**
+   * §3 — per-arena-chunk byte cap, propagated to every HybridScene
+   * compiled against this context. Default unset → adapter limit.
+   */
+  readonly maxChunkBytes?: number;
 }
 
 class RenderTask implements IRenderTask {
@@ -256,6 +261,7 @@ class RenderTask implements IRenderTask {
         ...(this.ctx.heapEnabled !== undefined ? { heapEnabled: this.ctx.heapEnabled } : {}),
         ...(this.ctx.enableFamilyMerge === true ? { enableFamilyMerge: true } : {}),
         ...(this.ctx.enableDerivedUniforms === false ? { enableDerivedUniforms: false } : {}),
+        ...(this.ctx.maxChunkBytes !== undefined ? { maxChunkBytes: this.ctx.maxChunkBytes } : {}),
       });
       this._scenes.set(cmd, s);
     }

package/src/runtime/runtime.ts

@@ -41,6 +41,12 @@ export interface RuntimeOptions {
    * ProjTrafo as `aval<Trafo3d>` for any derived they consume.
    */
   readonly enableDerivedUniforms?: boolean;
+  /**
+   * §3 — per-arena-chunk byte cap for the heap path. Threaded into
+   * `HybridSceneOptions.maxChunkBytes`. Pass a small value (e.g. 4 MB)
+   * from a demo / test to exercise multi-chunk routing.
+   */
+  readonly maxChunkBytes?: number;
 }
 
 /**
@@ -77,6 +83,7 @@ export class Runtime {
       ...(opts.heapEnabled !== undefined ? { heapEnabled: opts.heapEnabled } : {}),
       ...(opts.enableFamilyMerge === true ? { enableFamilyMerge: true } : {}),
       ...(opts.enableDerivedUniforms === false ? { enableDerivedUniforms: false } : {}),
+      ...(opts.maxChunkBytes !== undefined ? { maxChunkBytes: opts.maxChunkBytes } : {}),
     };
     // `device.lost` is a real-WebGPU promise; mock devices may not
     // expose it. Treat as "never lost" in that case.

package/src/runtime/textureAtlas/atlasPool.ts

@@ -611,6 +611,25 @@ export class AtlasPool {
     this.lru.set(e.ref, e);
   }
 
+  /**
+   * Bump refcount on an entry that's already live (used by the heap
+   * path when a cached HeapDrawSpec is re-introduced: the spec already
+   * carries `poolRef` from the original acquire, but every add/remove
+   * cycle fires the release closure once — without a matching incRef
+   * the refcount underflows and the entry gets actuallyFree'd while
+   * live drawHeaders still reference it).
+   *
+   * Returns `true` if the bump was applied; `false` if the entry has
+   * been evicted in the meantime (caller must fall back to re-acquire).
+   */
+  incRef(ref: number): boolean {
+    const e = this.entriesByRef.get(ref);
+    if (e === undefined) return false;
+    if (e.refcount === 0) this.lru.delete(e.ref);
+    e.refcount++;
+    return true;
+  }
+
   /**
    * Drop an LRU entry for real: remove its packer slot, drop the entry
    * from every lookup map. Caller must guarantee `refcount === 0`.

package/src/runtime/derivedModes/gpuDispatcher.ts

@@ -1,226 +0,0 @@
-// Scene-level dispatcher for the v1 GPU-evaluated derived-mode rule
-// (flip-cull-by-determinant; see ./gpuKernel.ts).
-//
-// Lifecycle
-// =========
-//
-//   - Construct once per heap scene with the device.
-//   - registerRo(drawId, modelRef, declaredCull): register an RO that
-//     has the GPU flip-cull rule. modelRef = byte offset into the
-//     arena where the RO's ModelTrafo mat4 lives.
-//   - deregisterRo(drawId): unregister on removeDraw.
-//   - markDirty(): caller hints that an input changed; the next
-//     `dispatch()` will run the kernel.
-//   - dispatch(arenaBuf, enc): if dirty, encode the compute pass into
-//     `enc`. Always copies the output buffer into a staging buffer for
-//     CPU readback.
-//   - finish(): mapAsync the staging buffer and resolve with the
-//     per-RO output array. The scene calls this AFTER submit and
-//     before deciding rebuckets. The promise resolves on the next
-//     microtask after the GPU completes the copy.
-//
-// The buffers grow lazily (pow2) as ROs are added.
-
-import { GPU_FLIP_CULL_BY_DET_WGSL, CULL_TO_U32 } from "./gpuKernel.js";
-import type { CullMode } from "../pipelineCache/index.js";
-import type { aval } from "@aardworx/wombat.adaptive";
-import { AdaptiveToken } from "@aardworx/wombat.adaptive";
-
-const NO_RULE = 0xFFFFFFFF;
-
-interface RoEntry {
-  /** Byte offset of the RO's ModelTrafo mat4 in the arena. */
-  modelRef: number;
-  /** SG-declared cull mode — either a plain value or an aval whose
-   *  current value the dispatcher reads each frame. */
-  declared: CullMode | aval<CullMode>;
-}
-
-const WG_SIZE = 64;
-const POW2 = (n: number): number => { let p = 1; while (p < n) p <<= 1; return Math.max(64, p); };
-
-export class GpuDerivedModesScene {
-  readonly device: GPUDevice;
-
-  private readonly entries: (RoEntry | undefined)[] = [];
-  private liveCount = 0;
-  private dirty = false;
-
-  // GPU resources — lazily allocated on first registerRo.
-  private inputBuf:   GPUBuffer | null = null;
-  private outputBuf:  GPUBuffer | null = null;
-  private stagingBuf: GPUBuffer | null = null;
-  private paramsBuf:  GPUBuffer | null = null;
-  private pipeline:   GPUComputePipeline | null = null;
-  private bindGroup:  GPUBindGroup | null = null;
-  private layout:     GPUBindGroupLayout | null = null;
-  /** Capacity in number of u32 entries (= numROs the buffers can hold). */
-  private capacity = 0;
-  /** Last-known arena buffer, used to detect bind-group invalidation. */
-  private arenaBuf: GPUBuffer | null = null;
-  /** True while the staging buffer's mapAsync is in flight. We must
-   *  not enqueue a new copyBufferToBuffer into it until it's been
-   *  unmapped (mapAsync resolved + unmap called). */
-  private readbackInFlight = false;
-
-  /** Per-RO last-known output. CPU mirror, populated by finish(). */
-  readonly lastOutput: Uint32Array;
-
-  constructor(device: GPUDevice) {
-    this.device = device;
-    this.lastOutput = new Uint32Array(0);
-  }
-
-  get registered(): number { return this.liveCount; }
-
-  registerRo(
-    drawId: number,
-    modelRef: number,
-    declared: CullMode | aval<CullMode>,
-  ): void {
-    this.entries[drawId] = { modelRef, declared };
-    this.liveCount++;
-    this.dirty = true;
-  }
-
-  deregisterRo(drawId: number): void {
-    if (this.entries[drawId] === undefined) return;
-    this.entries[drawId] = undefined;
-    this.liveCount--;
-    this.dirty = true;
-  }
-
-  markDirty(): void { this.dirty = true; }
-  consumeDirty(): boolean { const was = this.dirty; this.dirty = false; return was; }
-
-  private ensureResources(arenaBuf: GPUBuffer, numROs: number): void {
-    const needCap = POW2(Math.max(1, numROs));
-    if (this.outputBuf === null || needCap > this.capacity) {
-      this.inputBuf  ?.destroy();
-      this.outputBuf ?.destroy();
-      this.stagingBuf?.destroy();
-      const bytes = needCap * 4;
-      this.inputBuf   = this.device.createBuffer({ size: bytes, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST, label: "gpuDerivedModes/in" });
-      this.outputBuf  = this.device.createBuffer({ size: bytes, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST, label: "gpuDerivedModes/out" });
-      this.stagingBuf = this.device.createBuffer({ size: bytes, usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST, label: "gpuDerivedModes/staging" });
-      (this as { lastOutput: Uint32Array }).lastOutput = new Uint32Array(needCap);
-      this.capacity = needCap;
-      this.bindGroup = null;
-    }
-    if (this.paramsBuf === null) {
-      this.paramsBuf = this.device.createBuffer({ size: 16, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST, label: "gpuDerivedModes/params" });
-    }
-    if (this.layout === null) {
-      this.layout = this.device.createBindGroupLayout({
-        label: "gpuDerivedModes/bgl",
-        entries: [
-          { binding: 0, visibility: GPUShaderStage.COMPUTE, buffer: { type: "read-only-storage" } },
-          { binding: 1, visibility: GPUShaderStage.COMPUTE, buffer: { type: "read-only-storage" } },
-          { binding: 2, visibility: GPUShaderStage.COMPUTE, buffer: { type: "storage" } },
-          { binding: 3, visibility: GPUShaderStage.COMPUTE, buffer: { type: "uniform" } },
-        ],
-      });
-    }
-    if (this.pipeline === null) {
-      const module = this.device.createShaderModule({ code: GPU_FLIP_CULL_BY_DET_WGSL, label: "gpuDerivedModes/module" });
-      this.pipeline = this.device.createComputePipeline({
-        label: "gpuDerivedModes/pipeline",
-        layout: this.device.createPipelineLayout({ bindGroupLayouts: [this.layout] }),
-        compute: { module, entryPoint: "evaluate" },
-      });
-    }
-    if (this.bindGroup === null || this.arenaBuf !== arenaBuf) {
-      this.bindGroup = this.device.createBindGroup({
-        label: "gpuDerivedModes/bindGroup",
-        layout: this.layout,
-        entries: [
-          { binding: 0, resource: { buffer: arenaBuf } },
-          { binding: 1, resource: { buffer: this.inputBuf!  } },
-          { binding: 2, resource: { buffer: this.outputBuf! } },
-          { binding: 3, resource: { buffer: this.paramsBuf! } },
-        ],
-      });
-      this.arenaBuf = arenaBuf;
-    }
-  }
-
-  /** Upload current per-RO input refs + params; called when dirty. */
-  private uploadInputs(numROs: number): void {
-    const refs = new Uint32Array(this.capacity).fill(NO_RULE);
-    let declaredU32: number = CULL_TO_U32.back;
-    for (let i = 0; i < numROs; i++) {
-      const e = this.entries[i];
-      if (e !== undefined) {
-        refs[i] = e.modelRef;
-        // Resolve the declared each dispatch. v1 supports one shared
-        // declared per kernel (single uniform in the WGSL). Last
-        // registered entry's declared wins. For the typical SG shape
-        // where a single `<Sg CullMode={cv}>` wraps every leaf, every
-        // entry's declared is the same aval — so picking the last is
-        // equivalent to picking any. If the user genuinely binds
-        // distinct declareds across the scene, an axis-domain
-        // analyzer would be the correct generalization.
-        const d = e.declared;
-        const v = typeof d === "string"
-          ? d
-          : (d as aval<CullMode>).getValue(AdaptiveToken.top);
-        declaredU32 = CULL_TO_U32[v];
-      }
-    }
-    this.device.queue.writeBuffer(this.inputBuf!, 0, refs.buffer, refs.byteOffset, refs.byteLength);
-    const params = new Uint32Array([numROs, declaredU32, 0, 0]);
-    this.device.queue.writeBuffer(this.paramsBuf!, 0, params.buffer, params.byteOffset, params.byteLength);
-  }
-
-  /**
-   * Encode the compute dispatch + the staging copy into `enc`. Caller
-   * is responsible for `device.queue.submit([enc.finish()])`. Returns
-   * the number of ROs the kernel was dispatched against.
-   */
-  dispatch(arenaBuf: GPUBuffer, numROs: number, enc: GPUCommandEncoder): number {
-    this.ensureResources(arenaBuf, numROs);
-    // If the previous frame's readback hasn't resolved yet, we can
-    // still dispatch the compute (writes to outputBuf), but we must
-    // skip the staging copy — otherwise WebGPU rejects the submit
-    // with "buffer used in submit while mapped". Cheap to skip: the
-    // next dispatch will re-copy when staging is unmapped.
-    this.uploadInputs(numROs);
-    const pass = enc.beginComputePass({ label: "gpuDerivedModes/pass" });
-    pass.setPipeline(this.pipeline!);
-    pass.setBindGroup(0, this.bindGroup!);
-    pass.dispatchWorkgroups(Math.ceil(numROs / WG_SIZE));
-    pass.end();
-    if (!this.readbackInFlight) {
-      const bytes = numROs * 4;
-      enc.copyBufferToBuffer(this.outputBuf!, 0, this.stagingBuf!, 0, bytes);
-      this.readbackInFlight = true;
-    }
-    return numROs;
-  }
-
-  /**
-   * mapAsync the staging buffer + copy values into `lastOutput`.
-   * Resolves on the GPU finishing the copy. Caller diffs lastOutput
-   * against its own cached values to find changed ROs.
-   */
-  async finish(numROs: number): Promise<void> {
-    if (this.stagingBuf === null || numROs === 0) return;
-    if (!this.readbackInFlight) return; // dispatch skipped the copy; nothing to read
-    const bytes = numROs * 4;
-    try {
-      await this.stagingBuf.mapAsync(GPUMapMode.READ, 0, bytes);
-      const view = new Uint32Array(this.stagingBuf.getMappedRange(0, bytes).slice(0));
-      this.stagingBuf.unmap();
-      (this as { lastOutput: Uint32Array }).lastOutput.set(view, 0);
-    } finally {
-      this.readbackInFlight = false;
-    }
-  }
-
-  dispose(): void {
-    this.inputBuf  ?.destroy();
-    this.outputBuf ?.destroy();
-    this.stagingBuf?.destroy();
-    this.paramsBuf ?.destroy();
-  }
-}

package/src/runtime/derivedModes/gpuKernel.ts

@@ -1,98 +0,0 @@
-// GPU-evaluated derived-mode rules — minimum viable kernel.
-//
-// CPU eval (Task 2 Phase 1-3, 0.9.17) runs rule closures in JS. For
-// rules whose inputs live GPU-side (per-RO trafos, etc.) JS evaluation
-// fans out CPU work that's wasted: the trafo bytes are right there in
-// the arena. This module runs the rule on the GPU instead, in one
-// dispatch over all dirty ROs per frame.
-//
-// v1 scope is deliberately narrow: ONE hard-coded WGSL kernel for
-// "flip cullMode by sign of det(upper3x3 of an arena mat4)". Picked
-// because it's the motivating case from docs/derived-modes.md and
-// proves the GPU-eval path end-to-end. Generalizes via a traced IR
-// builder in v2 (see derived-mode-rules-plan.md Phase 5).
-//
-// Architecture
-// ============
-//
-//   - One **module-wide** `GpuDerivedModesScene` per heap scene. Holds:
-//       * `roOutputBuf`  — `array<u32>` sized to scene.numROs.
-//                          Each entry = the rule's modeKey contribution.
-//       * `roInputBuf`   — `array<u32>` (one ref-into-arena per RO)
-//                          telling the kernel where to read the input.
-//       * `stagingBuf`   — MAP_READ + COPY_DST mirror of roOutputBuf,
-//                          for the per-frame readback.
-//   - Dispatch each frame in `update()`, ONLY when something dirty.
-//   - `mapAsync(staging)` resolves on a microtask; the CPU diffs the
-//     buffer against `roLastKey[]`. Any change → mark drawId dirty;
-//     the existing rebucket flow does the rest.
-//
-// The dirty gate keeps steady-state cost ≈ 0 — when no input aval
-// marks AND no RO add/remove, we skip the dispatch + readback.
-
-export const GPU_FLIP_CULL_BY_DET_WGSL = /* wgsl */ `
-// Per-RO record. Index i corresponds to drawId i in the scene's
-// flat RO table.
-struct GpuRuleParams {
-  numROs:     u32,
-  declared:   u32,   // 0 = none, 1 = front, 2 = back  (must match CULL_MODE[] order in bitfield.ts)
-  _pad0:      u32,
-  _pad1:      u32,
-};
-
-@group(0) @binding(0) var<storage, read>       arena:        array<u32>;
-// One per-RO entry: byte offset within the arena of the ROs ModelTrafo
-// allocation header. Data is at offset + 16 (ALLOC_HEADER_PAD_TO).
-// 0xFFFFFFFFu means "this RO does NOT have a flip-cull-by-det rule".
-@group(0) @binding(1) var<storage, read>       roInputRefs:  array<u32>;
-@group(0) @binding(2) var<storage, read_write> roOutputs:    array<u32>;
-@group(0) @binding(3) var<uniform>             uIn:          GpuRuleParams;
-
-// Read a row-major mat4 from the arena at byte offset \`refBytes + 16\`
-// (header is 16 bytes wide due to ALLOC_HEADER_PAD_TO). Returns the
-// 3×3 upper-left in row-major order: [m00,m01,m02, m10,m11,m12, m20,m21,m22].
-fn loadUpper3x3(refBytes: u32) -> array<f32, 9> {
-  let baseU32 = (refBytes + 16u) >> 2u;
-  // The arena is a Float32 storage of mat4 in row-major, 16 floats.
-  // Read 9 of them.
-  return array<f32, 9>(
-    bitcast<f32>(arena[baseU32 + 0u]),  bitcast<f32>(arena[baseU32 + 1u]),  bitcast<f32>(arena[baseU32 + 2u]),
-    bitcast<f32>(arena[baseU32 + 4u]),  bitcast<f32>(arena[baseU32 + 5u]),  bitcast<f32>(arena[baseU32 + 6u]),
-    bitcast<f32>(arena[baseU32 + 8u]),  bitcast<f32>(arena[baseU32 + 9u]),  bitcast<f32>(arena[baseU32 + 10u]),
-  );
-}
-
-fn det3x3(m: array<f32, 9>) -> f32 {
-  return m[0] * (m[4] * m[8] - m[5] * m[7])
-       - m[1] * (m[3] * m[8] - m[5] * m[6])
-       + m[2] * (m[3] * m[7] - m[4] * m[6]);
-}
-
-// Mirror of bitfield.ts CULL_MODE[] order: 0=none, 1=front, 2=back.
-fn flipCull(c: u32) -> u32 {
-  if (c == 1u) { return 2u; } // front -> back
-  if (c == 2u) { return 1u; } // back  -> front
-  return c;                   // none
-}
-
-@compute @workgroup_size(64)
-fn evaluate(@builtin(global_invocation_id) gid: vec3<u32>) {
-  let i = gid.x;
-  if (i >= uIn.numROs) { return; }
-  let refByte = roInputRefs[i];
-  if (refByte == 0xFFFFFFFFu) {
-    // No rule on this RO; leave existing output untouched. Allows a
-    // single kernel dispatch to skip non-participating ROs.
-    return;
-  }
-  let m = loadUpper3x3(refByte);
-  let d = det3x3(m);
-  let declared = uIn.declared;
-  let outVal = select(declared, flipCull(declared), d < 0.0);
-  roOutputs[i] = outVal;
-}
-`;
-
-/** Map between bitfield.ts's CULL_MODE order and the kernel's u32 enum. */
-export const CULL_TO_U32 = { "none": 0, "front": 1, "back": 2 } as const;
-export const U32_TO_CULL = ["none", "front", "back"] as const;