@aardworx/wombat.rendering 0.8.0 → 0.9.0

package/src/runtime/derivedUniforms/uberKernel.wgsl.ts

@@ -0,0 +1,220 @@
+// §7 derived-uniforms uber kernel — single flat dispatch over leaves.
+//
+// Records are static-ish (only edited on RO add/remove). Each thread
+// processes one record:
+//   1. Load record (recipe_id, in0, in1, in2, out_byte).
+//   2. Switch on recipe_id, compute inline (df_mul + collapse), write
+//      f32 mat4/mat3 to MainHeap at out_byte.
+//
+// No dirty test on the kernel: when constituents don't change, the
+// kernel rewrites identical bits. Saves a CPU writeBuffer + a binding
+// per dispatch. GPU does ~64 FLOPs per record × N records — trivial at
+// the scales this runs at.
+//
+// df32 primitives mirror examples/df32-precision/. Two opacity hooks:
+//   - bitcast<f32>(bits & MASK) for Veltkamp split (integer ops, no
+//     algebraic identity).
+//   - fma(1.0, x, -y) for compensated subtractions.
+
+export const DERIVED_UBER_KERNEL_WGSL = /* wgsl */ `
+
+// ─── Bindings ─────────────────────────────────────────────────────
+@group(0) @binding(0) var<storage, read>       Constituents: array<vec2<f32>>;
+@group(0) @binding(1) var<storage, read_write> MainHeap:     array<f32>;
+
+struct Record {
+  recipe_id: u32,
+  in0:       u32,    // constituent slot index
+  in1:       u32,    // constituent slot index, 0 if unused
+  in2:       u32,    // constituent slot index, 0 if unused
+  out_byte:  u32,    // byte offset in MainHeap
+  _pad:      u32,    // bumps stride to 24 (defensively 16-aligned)
+}
+@group(0) @binding(2) var<storage, read>       Records: array<Record>;
+
+// Live record count. arrayLength(Records) reports the GPU buffer's
+// capacity (rounded up by allocator growth), not the live count —
+// trailing slots hold stale data from swap-removed records. Threads
+// past Count.count would read stale records and trample random
+// MainHeap bytes.
+struct CountUniform { count: u32 }
+@group(0) @binding(3) var<uniform>             Count: CountUniform;
+
+// ─── df32 primitives ──────────────────────────────────────────────
+
+fn split12(a: f32) -> vec2<f32> {
+  let hi = bitcast<f32>(bitcast<u32>(a) & 0xFFFFE000u);
+  let lo = a - hi;
+  return vec2<f32>(hi, lo);
+}
+
+fn two_sum(a: f32, b: f32) -> vec2<f32> {
+  let s  = a + b;
+  let bb = fma(1.0, s, -a);
+  let t1 = fma(1.0, s, -bb);
+  let t2 = fma(1.0, a, -t1);
+  let t3 = fma(1.0, b, -bb);
+  return vec2<f32>(s, t2 + t3);
+}
+
+fn quick_two_sum(a: f32, b: f32) -> vec2<f32> {
+  let s = a + b;
+  let t = fma(1.0, s, -a);
+  return vec2<f32>(s, fma(1.0, b, -t));
+}
+
+fn two_prod(a: f32, b: f32) -> vec2<f32> {
+  let p = a * b;
+  let A = split12(a);
+  let B = split12(b);
+  let err = ((A.x * B.x - p) + A.x * B.y + A.y * B.x) + A.y * B.y;
+  return vec2<f32>(p, err);
+}
+
+fn df_add(a: vec2<f32>, b: vec2<f32>) -> vec2<f32> {
+  let s = two_sum(a.x, b.x);
+  let t = two_sum(a.y, b.y);
+  let s3 = quick_two_sum(s.x, s.y + t.x);
+  return quick_two_sum(s3.x, s3.y + t.y);
+}
+
+fn df_mul(a: vec2<f32>, b: vec2<f32>) -> vec2<f32> {
+  let p      = two_prod(a.x, b.x);
+  let cross1 = fma(a.x, b.y, p.y);
+  let cross  = fma(a.y, b.x, cross1);
+  return quick_two_sum(p.x, cross);
+}
+
+// ─── Constituents access ──────────────────────────────────────────
+//
+// One slot = 16 vec2<f32> = one df32 mat4 in row-major order
+// (matching Aardvark M44d convention). Element (row, col) of slot k
+// lives at vec2 index k*16 + row*4 + col.
+
+fn read_entry(slot: u32, row: u32, col: u32) -> vec2<f32> {
+  return Constituents[slot * 16u + row * 4u + col];
+}
+
+// (A · B) entry (r, c) in df32, both A and B in constituents.
+fn df_mul_entry(a_slot: u32, b_slot: u32, r: u32, c: u32) -> vec2<f32> {
+  var acc = vec2<f32>(0.0, 0.0);
+  for (var k: u32 = 0u; k < 4u; k = k + 1u) {
+    acc = df_add(acc, df_mul(read_entry(a_slot, r, k), read_entry(b_slot, k, c)));
+  }
+  return acc;
+}
+
+// Compute one full row of (A · B), returns 4 df32 entries.
+fn df_mul_row(a_slot: u32, b_slot: u32, r: u32) -> array<vec2<f32>, 4> {
+  var out: array<vec2<f32>, 4>;
+  for (var c: u32 = 0u; c < 4u; c = c + 1u) {
+    out[c] = df_mul_entry(a_slot, b_slot, r, c);
+  }
+  return out;
+}
+
+// Triple product (A · B · C) entry (r, c). Uses 4 df_muls per entry
+// — recomputes the inner row each call. Acceptable: at most one
+// such recipe per RO and only on dirty frames.
+fn df_mul3_entry(a_slot: u32, b_slot: u32, c_slot: u32, r: u32, c: u32) -> vec2<f32> {
+  // (A·B·C)[r,c] = sum_k (A·B)[r,k] · C[k,c]
+  var acc = vec2<f32>(0.0, 0.0);
+  for (var k: u32 = 0u; k < 4u; k = k + 1u) {
+    let ab_rk = df_mul_entry(a_slot, b_slot, r, k);
+    acc = df_add(acc, df_mul(ab_rk, read_entry(c_slot, k, c)));
+  }
+  return acc;
+}
+
+// ─── Writers ──────────────────────────────────────────────────────
+//
+// Mat4: 16 contiguous f32s, row-major.
+// Mat3: 3 rows × 4-stride (std140 mat3<f32>), 12 f32s; last column
+//       per row left untouched.
+
+fn write_mat4_entry(out_byte: u32, row: u32, col: u32, val: f32) {
+  MainHeap[(out_byte >> 2u) + row * 4u + col] = val;
+}
+
+fn write_mat3_entry(out_byte: u32, row: u32, col: u32, val: f32) {
+  MainHeap[(out_byte >> 2u) + row * 4u + col] = val;
+}
+
+// ─── Recipe arms ──────────────────────────────────────────────────
+
+fn run_collapse_mat4(in0: u32, out_byte: u32) {
+  for (var r: u32 = 0u; r < 4u; r = r + 1u) {
+    for (var c: u32 = 0u; c < 4u; c = c + 1u) {
+      let e = read_entry(in0, r, c);
+      write_mat4_entry(out_byte, r, c, e.x + e.y);
+    }
+  }
+}
+
+// NormalMatrix: (M⁻¹)ᵀ upper-3×3.
+//   NM[i, j] = MInv[j, i]
+fn run_collapse_mat3_normal(in0: u32, out_byte: u32) {
+  for (var i: u32 = 0u; i < 3u; i = i + 1u) {
+    for (var j: u32 = 0u; j < 3u; j = j + 1u) {
+      let e = read_entry(in0, j, i);
+      write_mat3_entry(out_byte, i, j, e.x + e.y);
+    }
+  }
+}
+
+fn run_dfmul2_collapse(in0: u32, in1: u32, out_byte: u32) {
+  for (var r: u32 = 0u; r < 4u; r = r + 1u) {
+    for (var c: u32 = 0u; c < 4u; c = c + 1u) {
+      let e = df_mul_entry(in0, in1, r, c);
+      write_mat4_entry(out_byte, r, c, e.x + e.y);
+    }
+  }
+}
+
+fn run_dfmul3_collapse(in0: u32, in1: u32, in2: u32, out_byte: u32) {
+  for (var r: u32 = 0u; r < 4u; r = r + 1u) {
+    for (var c: u32 = 0u; c < 4u; c = c + 1u) {
+      let e = df_mul3_entry(in0, in1, in2, r, c);
+      write_mat4_entry(out_byte, r, c, e.x + e.y);
+    }
+  }
+}
+
+// ─── Entry ────────────────────────────────────────────────────────
+
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
+  if (gid.x >= Count.count) { return; }
+  let r = Records[gid.x];
+  switch r.recipe_id {
+    case 0u: { run_collapse_mat4(r.in0, r.out_byte); }            // ModelTrafo
+    case 1u: { run_collapse_mat4(r.in0, r.out_byte); }            // ModelTrafoInv
+    case 2u: { run_collapse_mat3_normal(r.in0, r.out_byte); }     // NormalMatrix
+    case 3u: { run_dfmul2_collapse(r.in0, r.in1, r.out_byte); }   // ModelViewTrafo
+    case 4u: { run_dfmul2_collapse(r.in0, r.in1, r.out_byte); }   // ModelViewTrafoInv
+    case 5u: { run_dfmul3_collapse(r.in0, r.in1, r.in2, r.out_byte); } // ModelViewProjTrafo
+    case 6u: { run_dfmul3_collapse(r.in0, r.in1, r.in2, r.out_byte); } // ModelViewProjTrafoInv
+    case 7u: { run_collapse_mat4(r.in0, r.out_byte); }            // ViewTrafo
+    case 8u: { run_collapse_mat4(r.in0, r.out_byte); }            // ViewTrafoInv
+    case 9u: { run_dfmul2_collapse(r.in0, r.in1, r.out_byte); }   // ViewProjTrafo
+    case 10u:{ run_dfmul2_collapse(r.in0, r.in1, r.out_byte); }   // ViewProjTrafoInv
+    case 11u:{ run_collapse_mat4(r.in0, r.out_byte); }            // ProjTrafo
+    case 12u:{ run_collapse_mat4(r.in0, r.out_byte); }            // ProjTrafoInv
+    default: { return; }
+  }
+}
+
+`;
+
+/** Records are 5× u32 = 20 bytes. WGSL storage struct alignment of
+ *  4 means the array stride is 20 bytes. */
+export const RECORD_STRIDE_BYTES = 24;
+export const RECORD_STRIDE_U32 = 6;
+
+export const RECORD_FIELD = {
+  recipe_id: 0,
+  in0:       1,
+  in1:       2,
+  in2:       3,
+  out_byte:  4,
+} as const;

package/src/runtime/flattenTree.ts

@@ -0,0 +1,46 @@
+// flattenTree — reactive `RenderTree → aset<RenderObject>`.
+//
+// Inside a single Render command, draw order is not load-bearing
+// (formal contract: an `aset` of objects, not a sequence). The two
+// node-kinds `Ordered` and `Unordered` collapse to the same flat
+// set — anything ordering-sensitive belongs at the Command level
+// (separate Render passes, in the Command list's declared order).
+//
+// Reactive variants (`Adaptive`, `OrderedFromList`, `UnorderedFromSet`)
+// stay reactive: marks propagate through `bind` / `collect`, and the
+// resulting aset reflects current tree state without a manual rebuild.
+//
+// `OrderedFromList`'s `alist<RenderTree>` is converted via
+// `AListBridges.toASet` — this drops index/order info, which we
+// wouldn't honor anyway.
+
+import { ASet, type aset } from "@aardworx/wombat.adaptive";
+import { AListBridges } from "@aardworx/wombat.adaptive";
+import type { RenderObject } from "../core/renderObject.js";
+import type { RenderTree } from "../core/renderTree.js";
+
+export function flattenRenderTree(tree: RenderTree): aset<RenderObject> {
+  switch (tree.kind) {
+    case "Empty":
+      return ASet.empty<RenderObject>();
+    case "Leaf":
+      return ASet.single(tree.object);
+    case "Ordered":
+    case "Unordered": {
+      // N-ary union via `unionMany(aset<aset<T>>)`. The naïve
+      // `children.reduce(ASet.union)` builds a 2N-deep nested-union
+      // tree; the reader's traversal recurses through it and blows
+      // the stack at ~2K leaves. `unionMany` is O(1)-deep regardless.
+      const children = tree.children.map(flattenRenderTree);
+      if (children.length === 0) return ASet.empty<RenderObject>();
+      if (children.length === 1) return children[0]!;
+      return ASet.unionMany(ASet.ofArray(children));
+    }
+    case "Adaptive":
+      return ASet.bind(flattenRenderTree, tree.tree);
+    case "OrderedFromList":
+      return ASet.collect(flattenRenderTree, AListBridges.toASet(tree.children));
+    case "UnorderedFromSet":
+      return ASet.collect(flattenRenderTree, tree.children);
+  }
+}

package/src/runtime/heapAdapter.ts

@@ -0,0 +1,314 @@
+// heapAdapter — `RenderObject → HeapDrawSpec`.
+//
+// Reactive: returns the same `HeapDrawSpec` shape the heap path
+// already accepts. Per-input wiring:
+//
+//   - vertexAttributes   → spec.inputs[name] = BufferView (heap path
+//                          handles BufferView ingest natively, pivots
+//                          the pool aval-key onto the underlying
+//                          `aval<IBuffer>` for share-by-identity).
+//   - uniforms           → spec.inputs[name] = aval<unknown>.
+//   - textures/samplers  → folded into a HeapTextureSet (single pair
+//                          v1; the eligibility classifier already
+//                          rejects multi-binding ROs).
+//   - indices            → BufferView's `aval<IBuffer>` mapped to
+//                          `aval<Uint32Array>` for the heap path's
+//                          IndexPool.
+//   - effect             → passed through.
+//   - pipelineState      → passed through (heap path bucket-keys it).
+//
+// Drawcall wedges (instanceCount > 1, baseVertex/firstIndex/
+// firstInstance != 0, non-indexed) are screened out by
+// `isHeapEligible`; this adapter is the partner that converts the
+// heap-eligible subset. If we see something we can't handle, throw —
+// that's a classifier/adapter mismatch, a bug.
+//
+// No multi-binding texture API yet: `ro.textures.count <= 1` and
+// `ro.samplers.count <= 1` are classifier invariants.
+
+import { type aval, type AdaptiveToken } from "@aardworx/wombat.adaptive";
+import type { IBuffer, HostBufferSource } from "../core/buffer.js";
+import type { BufferView } from "../core/bufferView.js";
+import { ITexture, type HostTextureSource } from "../core/texture.js";
+import { ISampler } from "../core/sampler.js";
+import type { RenderObject } from "../core/renderObject.js";
+import type { HeapDrawSpec, HeapTextureSet } from "./heapScene.js";
+import { AtlasPool } from "./textureAtlas/atlasPool.js";
+
+/**
+ * View `HostBufferSource` as `Uint32Array`. Index buffers are u32 in
+ * the heap path; non-u32 indices would have to be transcoded (out
+ * of scope — eligibility doesn't currently inspect index format).
+ */
+function asUint32(data: HostBufferSource): Uint32Array {
+  if (data instanceof Uint32Array) return data;
+  if (ArrayBuffer.isView(data)) {
+    return new Uint32Array(data.buffer, data.byteOffset, data.byteLength / 4);
+  }
+  return new Uint32Array(data);
+}
+
+// IndexPool keys on aval identity → ROs sharing the same
+// `ro.indices.buffer` must produce the SAME downstream
+// `aval<Uint32Array>`. A fresh `.map(…)` per RO would defeat the
+// pool's identity-based sharing and balloon GPU memory (e.g. 11K
+// spheres each allocating their own copy of the 6144-index buffer
+// → 270 MB).
+const indicesAvalCache = new WeakMap<aval<IBuffer>, aval<Uint32Array>>();
+
+// Per-aval shared "current pool ref" cell. ROs that share an
+// `aval<ITexture>` (and therefore one AtlasPool entry) all read
+// through the same cell; `repack` updates `cell.ref` so every
+// `release` closure frees the latest sub-rect after a swap.
+const currentRefCellCache = new WeakMap<aval<ITexture>, { ref: number }>();
+function currentRefCellFor(av: aval<ITexture>, initial: number): { ref: number } {
+  let c = currentRefCellCache.get(av);
+  if (c === undefined) {
+    c = { ref: initial };
+    currentRefCellCache.set(av, c);
+  }
+  return c;
+}
+function indicesAvalFor(ibAval: aval<IBuffer>): aval<Uint32Array> {
+  let av = indicesAvalCache.get(ibAval);
+  if (av === undefined) {
+    av = ibAval.map((ib: IBuffer) => {
+      if (ib.kind !== "host") {
+        throw new Error("heapAdapter: index buffer flipped to native GPUBuffer; classifier should have caught this");
+      }
+      return asUint32(ib.data);
+    });
+    indicesAvalCache.set(ibAval, av);
+  }
+  return av;
+}
+
+/**
+ * Pull `(format, width, height, mipLevelCount)` out of an ITexture so
+ * we can run Tier-S eligibility against it. Both variants expose this:
+ *
+ *   - `kind: "host"` with a `raw` source carries the fields directly
+ *     (`width`, `height`, `format`, optional `mipLevelCount`).
+ *   - `kind: "host"` with an `external` source (`ImageBitmap`,
+ *     `HTMLCanvasElement`, `ImageData`, …) reads `.width`/`.height`
+ *     off the image and uses the source's `format` override (default
+ *     `rgba8unorm`); `generateMips` triggers a >1 mip count.
+ *   - `kind: "gpu"` reads `.format`/`.width`/`.height`/`.mipLevelCount`
+ *     off the resolved `GPUTexture`. Width/height come from the WebGPU
+ *     texture surface; no host source is exposed (the pool can't
+ *     CPU-downscale, so mip generation defers to the existing GPU
+ *     mip chain when wantsMips is true).
+ *
+ * Returns `null` for sources we can't measure (e.g. an `external`
+ * source without dimensions — `HTMLVideoElement` whose readyState
+ * hasn't given us a video frame yet).
+ */
+interface TextureDescriptor {
+  format: GPUTextureFormat;
+  width: number;
+  height: number;
+  mipLevelCount: number;
+  host?: HostTextureSource;
+}
+function describeTexture(t: ITexture): TextureDescriptor | null {
+  if (t.kind === "gpu") {
+    const tex = t.texture;
+    return {
+      format: tex.format,
+      width: tex.width,
+      height: tex.height,
+      mipLevelCount: tex.mipLevelCount,
+    };
+  }
+  const src = t.source;
+  if (src.kind === "raw") {
+    return {
+      format: src.format,
+      width: src.width,
+      height: src.height,
+      mipLevelCount: src.mipLevelCount ?? 1,
+      host: src,
+    };
+  }
+  // external — read width/height off the source. Most types have it,
+  // HTMLVideoElement uses `videoWidth/videoHeight`.
+  const ext = src.source as unknown;
+  let w = 0, h = 0;
+  if (typeof HTMLVideoElement !== "undefined" && ext instanceof HTMLVideoElement) {
+    w = ext.videoWidth; h = ext.videoHeight;
+  } else if (
+    typeof ImageData !== "undefined" && ext instanceof ImageData
+  ) {
+    w = ext.width; h = ext.height;
+  } else {
+    const any = ext as { width?: number; height?: number };
+    w = any.width ?? 0;
+    h = any.height ?? 0;
+  }
+  if (w <= 0 || h <= 0) return null;
+  return {
+    format: src.format ?? "rgba8unorm",
+    width: w,
+    height: h,
+    mipLevelCount: src.generateMips ? Math.floor(Math.log2(Math.max(w, h))) + 1 : 1,
+    host: src,
+  };
+}
+
+/**
+ * Convert a heap-eligible `RenderObject` into a `HeapDrawSpec`. The
+ * caller (hybrid render task) is responsible for ensuring eligibility
+ * before calling — this adapter throws on any disagreement.
+ *
+ * The `token` is used once to read `drawCall` and the (single) texture
+ * + sampler avals at addDraw time. Per-frame data updates flow
+ * through the heap path's pool/repack machinery via the returned
+ * spec's avals — this function does not subscribe to anything.
+ */
+export function renderObjectToHeapSpec(
+  ro: RenderObject,
+  token: AdaptiveToken,
+  pool?: AtlasPool,
+): HeapDrawSpec {
+  // 1. Inputs map: vertex attributes (BufferView) + uniforms.
+  const inputs: { [name: string]: aval<unknown> | unknown } = {};
+  ro.vertexAttributes.iter((name, bv: BufferView) => { inputs[name] = bv; });
+  ro.uniforms.iter((name, av) => { inputs[name] = av; });
+
+  // 1b. Instance attributes — same shape, threaded via the heap path's
+  //     per-RO instancing fast path (one record / one drawIndirect for
+  //     `instanceCount > 1`, with per-instance attribute reads indexed
+  //     by the in-RO instance idx).
+  let instanceAttributes: { [name: string]: aval<unknown> | unknown } | undefined;
+  if (ro.instanceAttributes !== undefined && ro.instanceAttributes.count > 0) {
+    instanceAttributes = {};
+    ro.instanceAttributes.iter((name, bv: BufferView) => {
+      instanceAttributes![name] = bv;
+    });
+  }
+
+  // 2. Indices: BufferView → aval<Uint32Array>. Map the underlying
+  //    IBuffer aval; the heap path's IndexPool will key on this aval.
+  if (ro.indices === undefined) {
+    throw new Error("heapAdapter: RenderObject without indices not supported (heap is indexed-only)");
+  }
+  const indices: aval<Uint32Array> = indicesAvalFor(ro.indices.buffer);
+
+  // 3. Texture/sampler: single-pair v1. Classifier already capped
+  //    counts at 1 each.
+  let textures: HeapTextureSet | undefined;
+  if (ro.textures.count === 1 && ro.samplers.count === 1) {
+    let texAval: aval<unknown> | undefined;
+    let texVal: ITexture | undefined;
+    let samplerAval: aval<unknown> | undefined;
+    let samplerVal: ISampler | undefined;
+    ro.textures.iter((_n, av) => {
+      texAval = av;
+      texVal = av.getValue(token) as ITexture;
+    });
+    ro.samplers.iter((_n, av) => {
+      samplerAval = av;
+      samplerVal = av.getValue(token) as ISampler;
+    });
+    void samplerAval;
+    if (texVal === undefined || samplerVal === undefined) {
+      throw new Error("heapAdapter: missing texture/sampler value");
+    }
+
+    // Inspect format/dimensions/mipLevels from ITexture. Both
+    // variants expose enough to classify:
+    //   - kind: "host" → carries width/height/format on the source
+    //     descriptor (raw) or implicit (external; default rgba8unorm).
+    //   - kind: "gpu"  → resolved GPUTexture exposes .format/.width/
+    //     .height/.mipLevelCount.
+    const dims = describeTexture(texVal);
+
+    // Tier-S routing: pool present, format eligible, dims ≤ cap. Mips
+    // are honoured if the source advertises them.
+    const atlasFormat = dims === null ? null : AtlasPool.eligibleFormat(dims.format);
+    if (
+      pool !== undefined &&
+      dims !== null &&
+      atlasFormat !== null &&
+      AtlasPool.eligibleSize(dims.width, dims.height)
+    ) {
+      const wantsMips = dims.mipLevelCount > 1;
+      const acq = pool.acquire(
+        atlasFormat,
+        texAval as aval<ITexture>,
+        dims.width,
+        dims.height,
+        {
+          wantsMips,
+          ...(dims.host !== undefined ? { source: { width: dims.width, height: dims.height, host: dims.host } } : {}),
+        },
+      );
+      const texAvalTyped = texAval as aval<ITexture>;
+      // Per-aval shared current-ref cell so all ROs sharing a single
+      // `aval<ITexture>` see the same "live" pool ref. After a repack
+      // 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);
+      textures = {
+        kind: "atlas",
+        format: atlasFormat,
+        pageId: acq.pageId,
+        origin: acq.origin,
+        size: acq.size,
+        numMips: acq.numMips,
+        sampler: samplerVal,
+        page: acq.page,
+        poolRef: acq.ref,
+        release: () => pool.release(cell.ref),
+        // Reactivity hooks: heapScene subscribes to `sourceAval`; on
+        // mark, drains via `repack(newTex)` — the pool frees the old
+        // sub-rect, acquires a new one, and the heap path rewrites
+        // the drawHeader fields. Mirrors UniformPool.repack(av, val).
+        sourceAval: texAvalTyped,
+        repack: (newTex: ITexture) => {
+          const next = pool.repack(texAvalTyped, newTex, {
+            wantsMips: dims.mipLevelCount > 1,
+          });
+          cell.ref = next.ref;
+          return next;
+        },
+      };
+    } else {
+      // Tier-L fallback: keep the existing standalone path, which
+      // requires a resolved GPUTexture/GPUSampler.
+      if (texVal.kind !== "gpu") {
+        throw new Error("heapAdapter: standalone path requires ITexture.kind === 'gpu'");
+      }
+      if (samplerVal.kind !== "gpu") {
+        throw new Error("heapAdapter: standalone path requires ISampler.kind === 'gpu'");
+      }
+      textures = {
+        kind: "standalone",
+        texture: ITexture.fromGPU(texVal.texture),
+        sampler: ISampler.fromGPU(samplerVal.sampler),
+      };
+    }
+  } else if (ro.textures.count > 0 || ro.samplers.count > 0) {
+    throw new Error(
+      `heapAdapter: RO has ${ro.textures.count} texture(s) and ${ro.samplers.count} sampler(s); ` +
+      `single-pair only in v1 (classifier should have caught this)`,
+    );
+  }
+
+  // 4. DrawCall: read once. Classifier validates fields are heap-
+  //    compatible (indexed, instanceCount=1, zero offsets).
+  const dc = ro.drawCall.getValue(token);
+  if (dc.kind !== "indexed") {
+    throw new Error("heapAdapter: non-indexed drawCall; classifier should have caught this");
+  }
+
+  return {
+    effect: ro.effect,
+    pipelineState: ro.pipelineState,
+    inputs,
+    ...(instanceAttributes !== undefined ? { instanceAttributes } : {}),
+    ...(dc.instanceCount > 1 ? { instanceCount: dc.instanceCount } : {}),
+    indices,
+    ...(textures !== undefined ? { textures } : {}),
+  };
+}