@aardworx/wombat.rendering 0.8.1 → 0.9.1

package/src/runtime/derivedUniforms/recipes.ts

@@ -0,0 +1,159 @@
+// §7 derived-uniform recipe table — leaf-only flavour.
+//
+// Every recipe is a self-contained leaf: reads constituents directly,
+// computes inline (one or two df32 muls + collapse), writes the final
+// f32 mat4/mat3 to the main heap drawHeader. No intermediates, no
+// layering, no dependents graph.
+//
+// Two consumers of the same df32 product (e.g. ModelViewTrafo and
+// ModelViewProjTrafo for the same RO) recompute Model·View twice —
+// trivial vs the encode-time savings of one flat dispatch.
+//
+// All df32 math runs through the verified primitives in
+// uberKernel.wgsl.ts; the final consumer-facing values are f32.
+
+/** Recipe IDs. Numeric values are stable — the kernel switches on them. */
+export const enum RecipeId {
+  /** Model.fwd → f32 mat4. */
+  ModelTrafo            = 0,
+  /** Model.bwd → f32 mat4. */
+  ModelTrafoInv         = 1,
+  /** (Model.bwd)ᵀ upper-3×3 → f32 mat3. */
+  NormalMatrix          = 2,
+
+  /** View.fwd · Model.fwd → f32 mat4. */
+  ModelViewTrafo        = 3,
+  /** Model.bwd · View.bwd → f32 mat4. */
+  ModelViewTrafoInv     = 4,
+  /** Proj.fwd · View.fwd · Model.fwd → f32 mat4. */
+  ModelViewProjTrafo    = 5,
+  /** Model.bwd · View.bwd · Proj.bwd → f32 mat4. */
+  ModelViewProjTrafoInv = 6,
+
+  /** View.fwd → f32 mat4. */
+  ViewTrafo             = 7,
+  /** View.bwd → f32 mat4. */
+  ViewTrafoInv          = 8,
+  /** Proj.fwd · View.fwd → f32 mat4. */
+  ViewProjTrafo         = 9,
+  /** View.bwd · Proj.bwd → f32 mat4. */
+  ViewProjTrafoInv      = 10,
+  /** Proj.fwd → f32 mat4. */
+  ProjTrafo             = 11,
+  /** Proj.bwd → f32 mat4. */
+  ProjTrafoInv          = 12,
+}
+
+/** Number of constituent inputs each recipe consumes (1, 2, or 3). */
+const INPUT_COUNT: Record<RecipeId, 1 | 2 | 3> = {
+  [RecipeId.ModelTrafo]:            1,
+  [RecipeId.ModelTrafoInv]:         1,
+  [RecipeId.NormalMatrix]:          1,
+  [RecipeId.ModelViewTrafo]:        2,
+  [RecipeId.ModelViewTrafoInv]:     2,
+  [RecipeId.ModelViewProjTrafo]:    3,
+  [RecipeId.ModelViewProjTrafoInv]: 3,
+  [RecipeId.ViewTrafo]:             1,
+  [RecipeId.ViewTrafoInv]:          1,
+  [RecipeId.ViewProjTrafo]:         2,
+  [RecipeId.ViewProjTrafoInv]:      2,
+  [RecipeId.ProjTrafo]:             1,
+  [RecipeId.ProjTrafoInv]:          1,
+};
+
+export function recipeInputCount(id: RecipeId): 1 | 2 | 3 {
+  return INPUT_COUNT[id];
+}
+
+/** Output shape — drives drawHeader byte allocation. */
+export type RecipeOutput = "mat4" | "mat3";
+
+const OUTPUT: Record<RecipeId, RecipeOutput> = {
+  [RecipeId.ModelTrafo]:            "mat4",
+  [RecipeId.ModelTrafoInv]:         "mat4",
+  [RecipeId.NormalMatrix]:          "mat3",
+  [RecipeId.ModelViewTrafo]:        "mat4",
+  [RecipeId.ModelViewTrafoInv]:     "mat4",
+  [RecipeId.ModelViewProjTrafo]:    "mat4",
+  [RecipeId.ModelViewProjTrafoInv]: "mat4",
+  [RecipeId.ViewTrafo]:             "mat4",
+  [RecipeId.ViewTrafoInv]:          "mat4",
+  [RecipeId.ViewProjTrafo]:         "mat4",
+  [RecipeId.ViewProjTrafoInv]:      "mat4",
+  [RecipeId.ProjTrafo]:             "mat4",
+  [RecipeId.ProjTrafoInv]:          "mat4",
+};
+
+export function recipeOutput(id: RecipeId): RecipeOutput {
+  return OUTPUT[id];
+}
+
+/** Which side (forward/backward) of which Trafo3d each input slot draws from. */
+export type ConstituentRef =
+  | "Model.fwd" | "Model.bwd"
+  | "View.fwd"  | "View.bwd"
+  | "Proj.fwd"  | "Proj.bwd";
+
+const INPUTS: Record<RecipeId, readonly ConstituentRef[]> = {
+  [RecipeId.ModelTrafo]:            ["Model.fwd"],
+  [RecipeId.ModelTrafoInv]:         ["Model.bwd"],
+  [RecipeId.NormalMatrix]:          ["Model.bwd"],
+  // df_mul args are ordered (outer, inner) so the math product
+  // matches Aardvark's `View.mul(Model).forward = View.fwd · Model.fwd`.
+  [RecipeId.ModelViewTrafo]:        ["View.fwd",  "Model.fwd"],
+  [RecipeId.ModelViewTrafoInv]:     ["Model.bwd", "View.bwd"],
+  [RecipeId.ModelViewProjTrafo]:    ["Proj.fwd",  "View.fwd", "Model.fwd"],
+  [RecipeId.ModelViewProjTrafoInv]: ["Model.bwd", "View.bwd", "Proj.bwd"],
+  [RecipeId.ViewTrafo]:             ["View.fwd"],
+  [RecipeId.ViewTrafoInv]:          ["View.bwd"],
+  [RecipeId.ViewProjTrafo]:         ["Proj.fwd",  "View.fwd"],
+  [RecipeId.ViewProjTrafoInv]:      ["View.bwd",  "Proj.bwd"],
+  [RecipeId.ProjTrafo]:             ["Proj.fwd"],
+  [RecipeId.ProjTrafoInv]:          ["Proj.bwd"],
+};
+
+export function recipeInputs(id: RecipeId): readonly ConstituentRef[] {
+  return INPUTS[id];
+}
+
+/** Public uniform name (one per recipe). */
+const NAME: Record<RecipeId, string> = {
+  [RecipeId.ModelTrafo]:            "ModelTrafo",
+  [RecipeId.ModelTrafoInv]:         "ModelTrafoInv",
+  [RecipeId.NormalMatrix]:          "NormalMatrix",
+  [RecipeId.ModelViewTrafo]:        "ModelViewTrafo",
+  [RecipeId.ModelViewTrafoInv]:     "ModelViewTrafoInv",
+  [RecipeId.ModelViewProjTrafo]:    "ModelViewProjTrafo",
+  [RecipeId.ModelViewProjTrafoInv]: "ModelViewProjTrafoInv",
+  [RecipeId.ViewTrafo]:             "ViewTrafo",
+  [RecipeId.ViewTrafoInv]:          "ViewTrafoInv",
+  [RecipeId.ViewProjTrafo]:         "ViewProjTrafo",
+  [RecipeId.ViewProjTrafoInv]:      "ViewProjTrafoInv",
+  [RecipeId.ProjTrafo]:             "ProjTrafo",
+  [RecipeId.ProjTrafoInv]:          "ProjTrafoInv",
+};
+
+/** All recipe IDs in switch order. */
+export const ALL_RECIPES: readonly RecipeId[] = [
+  RecipeId.ModelTrafo, RecipeId.ModelTrafoInv, RecipeId.NormalMatrix,
+  RecipeId.ModelViewTrafo, RecipeId.ModelViewTrafoInv,
+  RecipeId.ModelViewProjTrafo, RecipeId.ModelViewProjTrafoInv,
+  RecipeId.ViewTrafo, RecipeId.ViewTrafoInv,
+  RecipeId.ViewProjTrafo, RecipeId.ViewProjTrafoInv,
+  RecipeId.ProjTrafo, RecipeId.ProjTrafoInv,
+];
+
+const BY_NAME: ReadonlyMap<string, RecipeId> = new Map(
+  ALL_RECIPES.map(id => [NAME[id], id] as const),
+);
+
+export const DERIVED_UNIFORM_NAMES: ReadonlySet<string> =
+  new Set(ALL_RECIPES.map(id => NAME[id]));
+
+export function recipeIdByName(name: string): RecipeId | undefined {
+  return BY_NAME.get(name);
+}
+
+export function recipeName(id: RecipeId): string {
+  return NAME[id];
+}

package/src/runtime/derivedUniforms/sceneIntegration.ts

@@ -0,0 +1,239 @@
+// §7 → heap scene integration helper.
+//
+// Subscription model. Standard adaptive idiom: calling `av.getValue(t)`
+// inside an `evaluateAlways(t, ...)` scope (re-)adds the evaluating
+// object to `av.outputs`. We don't manage subscription manually.
+//
+// Per frame, the heap scene's `update()` runs `evaluateAlways` once on
+// the parent scene-object (as it already does). Inside that scope:
+//   1. `scene.constituents.pullDirty(token)` drains the dirty queue.
+//      For each dirty aval, it calls `getValue(token)` — which both
+//      gives us the new value AND re-establishes our subscription on
+//      that specific aval. O(changed). Avals that didn't change keep
+//      us in their outputs from earlier evaluations.
+//   2. `scene.uploadDirty(dirtySlots)` — O(changed) value uploads +
+//      O(changed) bitmask flips.
+//   3. Per bucket: `bucket.dispatcher.encode(enc)`. The kernel
+//      early-returns on records whose inputs are all clean.
+//
+// On clean frames pullDirty/uploadDirty are no-ops. The records
+// buffer is static. CPU steady-state cost: zero.
+
+import type { aval, IAdaptiveObject } from "@aardworx/wombat.adaptive";
+import type { Trafo3d } from "@aardworx/wombat.base";
+import {
+  ConstituentSlots,
+  DF32_MAT4_BYTES,
+  type DerivationRecord, type PairedSlots, type SlotIndex,
+  type SubscribeFn,
+} from "./slots.js";
+import {
+  RecipeId, recipeIdByName, recipeInputs, recipeInputCount,
+  DERIVED_UNIFORM_NAMES,
+  type ConstituentRef,
+} from "./recipes.js";
+import {
+  DerivedUniformsDispatcher, DerivedUniformsPipeline,
+  uploadConstituentsRange,
+} from "./dispatch.js";
+
+/** Scene-wide §7 state. One per heap scene. Owns the single records
+ *  buffer + dispatcher — all buckets share constituents, dirty mask,
+ *  AND main heap (arena.attrs.buffer), so per-bucket records would
+ *  just multiply dispatch overhead for no reason. */
+export class DerivedUniformsScene {
+  readonly device: GPUDevice;
+  readonly constituents: ConstituentSlots;
+  readonly pipeline:     DerivedUniformsPipeline;
+  readonly dispatcher:   DerivedUniformsDispatcher;
+  /** Constituents storage GPU buffer (df32 mat4 array). */
+  constituentsBuf: GPUBuffer;
+  /** Caller-owned main heap (arena.attrs.buffer). Updated via
+   *  `rebindMainHeap` on arena resize. */
+  private mainHeapRef: { current: GPUBuffer };
+  /** Bumped each time a shared GPU buffer is replaced. */
+  bufferEpoch = 0;
+
+  constructor(
+    device:      GPUDevice,
+    mainHeapBuf: GPUBuffer,
+    opts?:       { initialConstituentSlots?: number; initialRecordCapacity?: number },
+  ) {
+    this.device = device;
+    const initial = opts?.initialConstituentSlots ?? 64;
+    const subscribe: SubscribeFn = () => {};
+    this.constituents = new ConstituentSlots(subscribe, initial);
+    this.pipeline     = new DerivedUniformsPipeline(device);
+    this.constituentsBuf = device.createBuffer({
+      label: "derivedUniforms.constituents",
+      size:  initial * DF32_MAT4_BYTES,
+      usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+    });
+    this.mainHeapRef = { current: mainHeapBuf };
+    this.dispatcher = new DerivedUniformsDispatcher(
+      device,
+      this.pipeline,
+      {
+        constituentsBuf: () => this.constituentsBuf,
+        mainHeapBuf:     () => this.mainHeapRef.current,
+      },
+      opts?.initialRecordCapacity ?? 64,
+    );
+  }
+
+  rebindMainHeap(mainHeapBuf: GPUBuffer): void {
+    this.mainHeapRef.current = mainHeapBuf;
+  }
+
+  ensureConstituentsCapacity(requiredBytes: number): void {
+    if (requiredBytes <= this.constituentsBuf.size) return;
+    let cap = this.constituentsBuf.size;
+    while (cap < requiredBytes) cap *= 2;
+    this.constituentsBuf.destroy();
+    this.constituentsBuf = this.device.createBuffer({
+      label: "derivedUniforms.constituents",
+      size:  cap,
+      usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+    });
+    this.bufferEpoch++;
+    // The fresh buffer is zero-initialized; the previous contents are
+    // gone. Re-upload everything we've ever packed (slot 0..slotCount).
+    // Without this, slots that were last written before the grow read
+    // zero on the GPU — every df_mul on them produces NaN.
+    const slotCount = this.constituents.slotCount;
+    if (slotCount > 0) {
+      const mirror = this.constituents.cpuMirror;
+      this.device.queue.writeBuffer(
+        this.constituentsBuf, 0,
+        mirror.buffer, mirror.byteOffset,
+        slotCount * DF32_MAT4_BYTES,
+      );
+    }
+  }
+
+  /** Routed from heap scene's `inputChanged(t, o)`. Returns true iff
+   *  `o` matched a known constituent aval. */
+  routeInputChanged(o: IAdaptiveObject): boolean {
+    if (!this.constituents.has(o)) return false;
+    this.constituents.markDirty(o);
+    return true;
+  }
+
+  /** Apply the dirty set: upload changed constituent values. O(changed). */
+  uploadDirty(dirty: ReadonlySet<SlotIndex>): void {
+    if (dirty.size === 0) return;
+    this.ensureConstituentsCapacity(this.constituents.slotCount * DF32_MAT4_BYTES);
+    uploadConstituentsRange(
+      this.device, this.constituentsBuf, this.constituents.cpuMirror, dirty,
+    );
+  }
+
+  dispose(): void {
+    this.dispatcher.dispose();
+    this.constituentsBuf.destroy();
+  }
+}
+
+// ─── Per-RO registration ──────────────────────────────────────────────
+
+export interface RoTrafoInputs {
+  readonly modelTrafo?: aval<Trafo3d> | undefined;
+  readonly viewTrafo?:  aval<Trafo3d> | undefined;
+  readonly projTrafo?:  aval<Trafo3d> | undefined;
+}
+
+export interface RoDerivedRequest {
+  readonly trafos:           RoTrafoInputs;
+  readonly requiredNames:    readonly string[];
+  readonly byteOffsetByName: ReadonlyMap<string, number>;
+  readonly drawHeaderBaseByte: number;
+}
+
+export interface RoRegistration {
+  /** Per-record handles (RecordsBuffer ids) — passed back to deregister. */
+  readonly recordIds: readonly number[];
+  readonly constituentAvals: readonly aval<Trafo3d>[];
+}
+
+/** Register all derived-uniform records for one RO. */
+export function registerRoDerivations(
+  scene:  DerivedUniformsScene,
+  req:    RoDerivedRequest,
+): RoRegistration {
+  if (req.requiredNames.length === 0) {
+    return { recordIds: [], constituentAvals: [] };
+  }
+
+  const acquiredAvals: aval<Trafo3d>[] = [];
+  const pairFor = new Map<"Model" | "View" | "Proj", PairedSlots>();
+  const TRAFO_FIELD: Record<"Model" | "View" | "Proj", keyof RoTrafoInputs> = {
+    Model: "modelTrafo", View: "viewTrafo", Proj: "projTrafo",
+  };
+  const acquirePair = (key: "Model" | "View" | "Proj"): PairedSlots => {
+    let p = pairFor.get(key);
+    if (p !== undefined) return p;
+    const av = req.trafos[TRAFO_FIELD[key]];
+    if (av === undefined) {
+      throw new Error(
+        `derivedUniforms: RO requires '${key}' trafo but trafos.${TRAFO_FIELD[key]} is undefined`,
+      );
+    }
+    p = scene.constituents.acquire(av);
+    pairFor.set(key, p);
+    acquiredAvals.push(av);
+    return p;
+  };
+
+  const resolveConstituent = (ref: ConstituentRef): SlotIndex => {
+    switch (ref) {
+      case "Model.fwd": return acquirePair("Model").fwd;
+      case "Model.bwd": return acquirePair("Model").inv;
+      case "View.fwd":  return acquirePair("View" ).fwd;
+      case "View.bwd":  return acquirePair("View" ).inv;
+      case "Proj.fwd":  return acquirePair("Proj" ).fwd;
+      case "Proj.bwd":  return acquirePair("Proj" ).inv;
+    }
+  };
+
+  const recordIds: number[] = [];
+  for (const name of req.requiredNames) {
+    const id = recipeIdByName(name);
+    if (id === undefined) {
+      throw new Error(`derivedUniforms: unknown derived name '${name}'`);
+    }
+    const off = req.byteOffsetByName.get(name);
+    if (off === undefined) {
+      throw new Error(
+        `derivedUniforms: '${name}' has no byte offset in drawHeader for this RO`,
+      );
+    }
+    const refs = recipeInputs(id);
+    const slots = refs.map(resolveConstituent);
+    const inCount = recipeInputCount(id);
+    const rec: DerivationRecord = {
+      recipe:  id as number,
+      in0:     slots[0]!,
+      in1:     inCount >= 2 ? slots[1]! : (0 as SlotIndex),
+      in2:     inCount >= 3 ? slots[2]! : (0 as SlotIndex),
+      outByte: req.drawHeaderBaseByte + off,
+    };
+    recordIds.push(scene.dispatcher.records.add(rec));
+  }
+
+  return { recordIds, constituentAvals: acquiredAvals };
+}
+
+export function deregisterRoDerivations(
+  scene: DerivedUniformsScene,
+  reg:   RoRegistration,
+): void {
+  for (const id of reg.recordIds) scene.dispatcher.records.remove(id);
+  for (const av of reg.constituentAvals) scene.constituents.release(av);
+}
+
+export function isDerivedUniformName(name: string): boolean {
+  return DERIVED_UNIFORM_NAMES.has(name);
+}
+
+// Re-export RecipeId for callers (e.g. heapScene's drawHeader walk).
+export { RecipeId };

package/src/runtime/derivedUniforms/slotId.ts

@@ -0,0 +1,35 @@
+// Slot-ID encoding for the §7 uber kernel.
+//
+// One u32 namespace covers both the Constituents heap (df32 trafos
+// uploaded from CPU) and the Intermediates heap (df32 outputs of
+// layer-1 recipes). The high bit selects the heap; the low 31 bits are
+// the linear index within that heap. Each slot holds one mat4 in df32
+// = 16 vec2<f32> = 128 bytes.
+//
+// Uber-kernel side: a single helper reads from either heap based on
+// the flag — see `read_mat4_df` in the WGSL source.
+
+/** Branded u32 — top bit selects heap, low 31 bits are slot index. */
+export type SlotId = number & { readonly __slotId: unique symbol };
+
+const FLAG_INTERMEDIATE = 0x80000000;
+
+export const SlotId = {
+  /** Encode a Constituents-heap slot. */
+  constituent(idx: number): SlotId {
+    return (idx & 0x7FFFFFFF) as SlotId;
+  },
+  /** Encode an Intermediates-heap slot. */
+  intermediate(idx: number): SlotId {
+    return ((idx & 0x7FFFFFFF) | FLAG_INTERMEDIATE) >>> 0 as SlotId;
+  },
+  isIntermediate(s: SlotId): boolean {
+    return (s & FLAG_INTERMEDIATE) !== 0;
+  },
+  index(s: SlotId): number {
+    return s & 0x7FFFFFFF;
+  },
+};
+
+/** Bytes per df32 mat4 slot: 16 entries × 2 floats × 4 bytes. */
+export const DF32_MAT4_BYTES = 128;

package/src/runtime/derivedUniforms/slots.ts

@@ -0,0 +1,155 @@
+// §7 constituent slot allocator + derivation record store.
+//
+// One refcounted heap of df32 mat4 slots, keyed by `aval<Trafo3d>`.
+// Each acquired aval gets an adjacent (fwd, inv) slot pair on the
+// constituents heap. The pull phase reads each tracked aval through
+// `getValue(token)` and re-packs the slot pair only if the returned
+// Trafo3d differs from the previously cached value (reference identity
+// — Trafo3d is immutable).
+//
+// Lifetime is RO-driven: addDraw → acquire(...), removeDraw → release.
+
+import type { aval, AdaptiveToken, IAdaptiveObject } from "@aardworx/wombat.adaptive";
+import type { M44d, Trafo3d } from "@aardworx/wombat.base";
+
+/** Slot index — pure linear index into the constituents heap. */
+export type SlotIndex = number & { readonly __slotIndex: unique symbol };
+
+/** Bytes per df32 mat4 slot: 16 entries × 2 floats × 4 bytes. */
+export const DF32_MAT4_BYTES = 128;
+
+/** Forward + inverse slot indices for one Trafo3d aval. */
+export interface PairedSlots {
+  readonly fwd: SlotIndex;
+  readonly inv: SlotIndex;
+}
+
+/** Caller-provided hook: register the parent scene-object as a
+ *  downstream output of `av`. Without this, the framework never
+ *  delivers `inputChanged` and our dirty queue stays empty. */
+export type SubscribeFn = (av: aval<unknown>) => void;
+
+/** A single derivation request: "run this recipe over these constituent
+ *  slots, write its output to `out_byte` in main heap." Identity-tracked
+ *  so add/remove can locate the row in the records buffer. */
+export interface DerivationRecord {
+  readonly recipe:  number;            // RecipeId
+  readonly in0:     SlotIndex;
+  readonly in1:     SlotIndex;         // 0 if unused
+  readonly in2:     SlotIndex;         // 0 if unused
+  readonly outByte: number;
+}
+
+class IndexPool {
+  private next = 0;
+  private free: number[] = [];
+  alloc(): number { return this.free.pop() ?? this.next++; }
+  release(idx: number): void { this.free.push(idx); }
+  get highWaterMark(): number { return this.next; }
+}
+
+interface ConstituentEntry {
+  readonly slots: PairedSlots;
+  refs: number;
+}
+
+function packEntry(mirror: Float32Array, off: number, v: number): void {
+  const hi = Math.fround(v);
+  mirror[off]     = hi;
+  mirror[off + 1] = Math.fround(v - hi);
+}
+
+function packMat4ToSlot(mirror: Float32Array, slotIdx: number, m: M44d): void {
+  const base = slotIdx * 32;
+  packEntry(mirror, base + 0,  m.M00); packEntry(mirror, base + 2,  m.M01);
+  packEntry(mirror, base + 4,  m.M02); packEntry(mirror, base + 6,  m.M03);
+  packEntry(mirror, base + 8,  m.M10); packEntry(mirror, base + 10, m.M11);
+  packEntry(mirror, base + 12, m.M12); packEntry(mirror, base + 14, m.M13);
+  packEntry(mirror, base + 16, m.M20); packEntry(mirror, base + 18, m.M21);
+  packEntry(mirror, base + 20, m.M22); packEntry(mirror, base + 22, m.M23);
+  packEntry(mirror, base + 24, m.M30); packEntry(mirror, base + 26, m.M31);
+  packEntry(mirror, base + 28, m.M32); packEntry(mirror, base + 30, m.M33);
+}
+
+export class ConstituentSlots {
+  private readonly pool = new IndexPool();
+  private readonly byAval = new Map<aval<Trafo3d>, ConstituentEntry>();
+  private readonly dirtyAvals = new Set<aval<Trafo3d>>();
+  private mirror: Float32Array;
+  private readonly subscribe: SubscribeFn;
+
+  constructor(subscribe: SubscribeFn, initialCapacity = 64) {
+    this.subscribe = subscribe;
+    this.mirror = new Float32Array(initialCapacity * 32);
+  }
+
+  acquire(av: aval<Trafo3d>): PairedSlots {
+    let entry = this.byAval.get(av);
+    if (entry === undefined) {
+      const fwd = this.pool.alloc() as SlotIndex;
+      const inv = this.pool.alloc() as SlotIndex;
+      entry = { slots: { fwd, inv }, refs: 0 };
+      this.byAval.set(av, entry);
+      this.ensureCapacity(this.pool.highWaterMark);
+      this.subscribe(av);
+      this.dirtyAvals.add(av);
+    }
+    entry.refs++;
+    return entry.slots;
+  }
+
+  release(av: aval<Trafo3d>): void {
+    const entry = this.byAval.get(av);
+    if (entry === undefined) {
+      throw new Error("ConstituentSlots.release: aval was never acquired");
+    }
+    entry.refs--;
+    if (entry.refs === 0) {
+      this.pool.release(entry.slots.fwd);
+      this.pool.release(entry.slots.inv);
+      this.byAval.delete(av);
+      this.dirtyAvals.delete(av);
+    }
+  }
+
+  has(o: IAdaptiveObject): boolean {
+    return this.byAval.has(o as unknown as aval<Trafo3d>);
+  }
+  markDirty(o: IAdaptiveObject): void {
+    const av = o as unknown as aval<Trafo3d>;
+    if (this.byAval.has(av)) this.dirtyAvals.add(av);
+  }
+
+  /** Drain the dirty queue: pack each marked aval's value into the
+   *  mirror, return the affected slot indices. O(changed). The
+   *  returned Set is OWNED by ConstituentSlots and reused frame to
+   *  frame — callers must not retain it past the current frame. */
+  pullDirty(token: AdaptiveToken): Set<SlotIndex> {
+    this.dirtyOut.clear();
+    for (const av of this.dirtyAvals) {
+      const entry = this.byAval.get(av);
+      if (entry === undefined) continue;
+      const value = av.getValue(token);
+      packMat4ToSlot(this.mirror, entry.slots.fwd, value.forward);
+      packMat4ToSlot(this.mirror, entry.slots.inv, value.backward);
+      this.dirtyOut.add(entry.slots.fwd);
+      this.dirtyOut.add(entry.slots.inv);
+    }
+    this.dirtyAvals.clear();
+    return this.dirtyOut;
+  }
+  private readonly dirtyOut = new Set<SlotIndex>();
+
+  get cpuMirror(): Float32Array { return this.mirror; }
+  get slotCount(): number { return this.pool.highWaterMark; }
+
+  private ensureCapacity(slots: number): void {
+    const need = slots * 32;
+    if (need <= this.mirror.length) return;
+    let cap = this.mirror.length;
+    while (cap < need) cap *= 2;
+    const grown = new Float32Array(cap);
+    grown.set(this.mirror);
+    this.mirror = grown;
+  }
+}