@aardworx/wombat.rendering 0.9.11 → 0.9.12

package/src/runtime/derivedUniforms/index.ts

@@ -1,52 +1,68 @@
-// §7 derived-uniforms module — public surface.
+// §7 derived-uniforms module — public surface (v2: content-keyed rule registry,
+// chain flattening, codegen-emitted uber-kernel, one dispatch).
 //
-// Caller responsibilities (typically heapScene.ts):
+// Caller responsibilities (heapScene.ts):
 //
-//   1. Construct one DerivedUniformsScene per heap scene, one
-//      DerivedUniformsBucket per render bucket. The scene owns the
-//      shared constituents storage buffer + dirty bitmask + pipeline.
+//   1. Construct one DerivedUniformsScene per heap scene (owns the rule registry,
+//      the records buffer, the constituents heap + GPU buffer, the dispatcher).
 //   2. In the parent scene-object's `inputChanged(t, o)` router, call
-//      `scene.routeInputChanged(o)`. Returns true iff o matched.
-//   3. In each RO's add path: `registerRoDerivations(scene, bucket, req)`
-//      allocates constituent slots and pushes records into the bucket's
-//      records buffer. In remove path: `deregisterRoDerivations(...)`.
-//   4. In the per-frame compute prep, inside the parent sceneObj's
-//      `evaluateAlways(token, ...)` scope:
-//        const dirty = scene.constituents.pullDirty(token);
+//      `scene.routeInputChanged(o)` — returns true iff `o` is a tracked trafo aval.
+//   3. Per RO add: `registerRoDerivations(scene, owner, req)` — flattens + registers
+//      each rule, resolves its input leaves to constituent / host slots, pushes one
+//      record per derived uniform. Per RO remove: `deregisterRoDerivations(scene, reg)`.
+//   4. Per frame, inside the scene's `evaluateAlways(token, …)` scope:
+//        const dirty = scene.pullDirty(token);   // re-subscribes on changed trafo avals
 //        scene.uploadDirty(dirty);
-//        for each bucket: bucket.dispatcher.encode(enc);
-//      All steps are O(changed); on clean frames they no-op.
+//        scene.encode(enc);                       // one compute dispatch
+//      All O(changed); clean frames no-op.
 //
-// Identifying which uniform names are §7-owned: DERIVED_UNIFORM_NAMES.
+// The standard trafo recipes (ModelViewProjTrafo etc.) live in ./recipes as
+// `DerivedRule` constants — `STANDARD_DERIVED_RULES` / `isStandardDerivedName`.
 
 export {
-  RecipeId,
-  ALL_RECIPES, DERIVED_UNIFORM_NAMES,
-  recipeIdByName, recipeName, recipeInputs, recipeInputCount, recipeOutput,
-  type ConstituentRef, type RecipeOutput,
-} from "./recipes.js";
+  type DerivedRule, type IRFragment,
+  ruleFromIR, uniformRef, sameType, hashIR, isDerivedRule,
+} from "./rule.js";
 
 export {
-  ConstituentSlots, DF32_MAT4_BYTES,
-  type SlotIndex, type PairedSlots, type DerivationRecord, type SubscribeFn,
-} from "./slots.js";
+  derivedUniform, DerivedExpr, type DerivedScope,
+} from "./marker.js";
+
+export {
+  type RuleInput,
+  flatten, inputsOf,
+} from "./flatten.js";
+
+export {
+  DerivedUniformRegistry, type RuleEntry,
+} from "./registry.js";
+
+export {
+  RecordsBuffer, SlotTag,
+  makeHandle, handleTag, handlePayload,
+  type RecordOwner,
+} from "./records.js";
+
+export {
+  buildUberKernel, type UberKernel,
+} from "./codegen.js";
 
 export {
-  DerivedUniformsDispatcher, DerivedUniformsPipeline,
-  RecordsBuffer, uploadConstituentsRange,
+  DerivedUniformsDispatcher, uploadConstituentsRange,
   type DerivedUniformsResources,
 } from "./dispatch.js";
 
 export {
-  DerivedUniformsScene,
-  registerRoDerivations,
-  deregisterRoDerivations,
-  isDerivedUniformName,
-  type RoTrafoInputs,
-  type RoDerivedRequest,
-  type RoRegistration,
+  ConstituentSlots, DF32_MAT4_BYTES,
+  type SlotIndex, type PairedSlots, type SubscribeFn,
+} from "./slots.js";
+
+export {
+  DerivedUniformsScene, type DerivedUniformsSceneOptions,
+  registerRoDerivations, deregisterRoDerivations,
+  type RoDerivedRequest, type RoRegistration,
 } from "./sceneIntegration.js";
 
 export {
-  DERIVED_UBER_KERNEL_WGSL,
-} from "./uberKernel.wgsl.js";
+  STANDARD_DERIVED_RULES, STANDARD_TRAFO_LEAVES, isStandardDerivedName,
+} from "./recipes.js";

package/src/runtime/derivedUniforms/marker.ts

@@ -0,0 +1,91 @@
+// §7 v2 — `derivedUniform((u) => …)` author-facing marker.
+//
+// A uniform binding is either a *value* (an `aval` / constant) or a *rule*
+// (`derivedUniform((u) => u.ViewTrafo.mul(u.ModelTrafo))`). A rule reads other
+// uniforms — `u.<Name>` is a leaf, and is resolved per RenderObject at registration
+// time (a `Trafo3d` aval ⇒ a df32 constituent slot; anything else ⇒ a host uniform).
+//
+// This builds the rule's IR by tracing: `u.<Name>` is a mat4 leaf (the trafo case —
+// the vast majority of derived uniforms), and the `DerivedExpr` methods compose them
+// (the result type follows from the ops, so `.upperLeft3x3()` yields a mat3 rule, etc.).
+// For non-mat4-leaf rules use `ruleFromIR` with hand-built IR, or — once it lands — the
+// build-time `derivedUniform(...)` vite marker, which reads leaf types from the program.
+
+import type { Expr, Type } from "@aardworx/wombat.shader/ir";
+import { ruleFromIR, uniformRef, type DerivedRule } from "./rule.js";
+
+const Tf32: Type = { kind: "Float", width: 32 };
+const mat = (n: 3 | 4): Type => ({ kind: "Matrix", element: Tf32, rows: n, cols: n });
+const vec = (n: 2 | 3 | 4): Type => ({ kind: "Vector", element: Tf32, dim: n });
+
+function transposed(t: Type): Type {
+  return t.kind === "Matrix" ? { kind: "Matrix", element: t.element, rows: t.cols, cols: t.rows } : t;
+}
+function constVec4(x: number, y: number, z: number, w: number): Expr {
+  const c = (v: number): Expr => ({ kind: "Const", type: Tf32, value: { kind: "Float", value: v } });
+  return { kind: "NewVector", components: [c(x), c(y), c(z), c(w)], type: vec(4) };
+}
+
+/** A traced expression in a `derivedUniform` builder. */
+export class DerivedExpr {
+  constructor(readonly ir: Expr) {}
+  get type(): Type { return this.ir.type; }
+
+  /** Matrix product `this · other` (also matrix·vector / vector·matrix by operand types). */
+  mul(other: DerivedExpr): DerivedExpr {
+    const a = this.ir.type, b = other.ir.type;
+    if (a.kind === "Matrix" && b.kind === "Matrix") {
+      return new DerivedExpr({ kind: "MulMatMat", lhs: this.ir, rhs: other.ir, type: { kind: "Matrix", element: a.element, rows: a.rows, cols: b.cols } });
+    }
+    if (a.kind === "Matrix" && b.kind === "Vector") {
+      return new DerivedExpr({ kind: "MulMatVec", lhs: this.ir, rhs: other.ir, type: { kind: "Vector", element: b.element, dim: a.rows } });
+    }
+    if (a.kind === "Vector" && b.kind === "Matrix") {
+      return new DerivedExpr({ kind: "MulVecMat", lhs: this.ir, rhs: other.ir, type: { kind: "Vector", element: a.element, dim: b.cols } });
+    }
+    return new DerivedExpr({ kind: "Mul", lhs: this.ir, rhs: other.ir, type: a.kind === "Float" ? b : a });
+  }
+  add(other: DerivedExpr): DerivedExpr { return new DerivedExpr({ kind: "Add", lhs: this.ir, rhs: other.ir, type: this.ir.type }); }
+  sub(other: DerivedExpr): DerivedExpr { return new DerivedExpr({ kind: "Sub", lhs: this.ir, rhs: other.ir, type: this.ir.type }); }
+  neg(): DerivedExpr { return new DerivedExpr({ kind: "Neg", value: this.ir, type: this.ir.type }); }
+
+  /** Inverse (of a constituent trafo this reads its stored backward half; otherwise unsupported in codegen). */
+  inverse(): DerivedExpr { return new DerivedExpr({ kind: "Inverse", value: this.ir, type: this.ir.type }); }
+  transpose(): DerivedExpr { return new DerivedExpr({ kind: "Transpose", value: this.ir, type: transposed(this.ir.type) }); }
+  /** Upper-left 3×3 (mat → mat3). */
+  upperLeft3x3(): DerivedExpr { return new DerivedExpr({ kind: "ConvertMatrix", value: this.ir, type: mat(3) }); }
+  /** This mat4 applied to the origin `(0,0,0,1)`, returning the resulting position (xyz). */
+  transformOrigin(): DerivedExpr {
+    const v4: Expr = { kind: "MulMatVec", lhs: this.ir, rhs: constVec4(0, 0, 0, 1), type: vec(4) };
+    return new DerivedExpr({ kind: "VecSwizzle", value: v4, comps: ["x", "y", "z"], type: vec(3) });
+  }
+  /** vecN swizzle, e.g. `.swizzle("xyz")`. */
+  swizzle(comps: string): DerivedExpr {
+    const c = comps.split("") as ("x" | "y" | "z" | "w")[];
+    return new DerivedExpr({ kind: "VecSwizzle", value: this.ir, comps: c, type: c.length === 1 ? Tf32 : vec(c.length as 2 | 3 | 4) });
+  }
+}
+
+/** The `u` passed to a `derivedUniform` builder. `u.<Name>` is a mat4 trafo leaf. */
+export type DerivedScope = { readonly [name: string]: DerivedExpr };
+
+function makeScope(): DerivedScope {
+  return new Proxy({} as DerivedScope, {
+    get(_t, key): DerivedExpr {
+      if (typeof key !== "string") throw new Error("derivedUniform: leaf names must be strings");
+      return new DerivedExpr(uniformRef(key, mat(4)));
+    },
+  });
+}
+
+/**
+ * Define a derived uniform. `derivedUniform(u => u.ViewTrafo.mul(u.ModelTrafo))` makes a
+ * rule that slots in wherever a uniform value goes — see this module's header.
+ */
+export function derivedUniform<T = unknown>(build: (u: DerivedScope) => DerivedExpr): DerivedRule<T> {
+  const result = build(makeScope());
+  if (!(result instanceof DerivedExpr)) {
+    throw new Error("derivedUniform: the builder must return a derived expression, e.g. u.ViewTrafo.mul(u.ModelTrafo)");
+  }
+  return ruleFromIR<T>(result.ir, result.ir.type);
+}

package/src/runtime/derivedUniforms/recipes.ts

@@ -1,159 +1,67 @@
-// §7 derived-uniform recipe table — leaf-only flavour.
+// §7 v2 — the standard trafo recipes, as DerivedRule constants.
 //
-// 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.
+// These replace the hardcoded RecipeId table. Each rule reads BASE-trafo leaves
+// (`Model` / `View` / `Proj` — the raw `aval<Trafo3d>`s the RO binds as
+// `ModelTrafo` / `ViewTrafo` / `ProjTrafo` uniforms) and produces the derived
+// uniform the shader reads (`ModelViewProjTrafo`, `NormalMatrix`, …). A leaf
+// wrapped in `Inverse(...)` selects that trafo's stored backward half (free).
 //
-// 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.
+// `Inverse`-of-a-product (e.g. `ModelViewProjTrafoInv`) is written as the product
+// of the inverted factors in reverse order — `(P·V·M)⁻¹ = M⁻¹·V⁻¹·P⁻¹` — so it
+// stays a constituent matmul chain the codegen recognizes.
 //
-// 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];
+// `NormalMatrix` is `(Model⁻¹)ᵀ` truncated to its upper-3×3 — declared as a mat3
+// output; the codegen's normal-matrix arm does the transpose + truncation.
+
+import type { Expr, Type } from "@aardworx/wombat.shader/ir";
+import { ruleFromIR, uniformRef, type DerivedRule } from "./rule.js";
+
+const Tf32: Type = { kind: "Float", width: 32 };
+const Tmat4: Type = { kind: "Matrix", element: Tf32, rows: 4, cols: 4 };
+const Tmat3: Type = { kind: "Matrix", element: Tf32, rows: 3, cols: 3 };
+
+const mat4 = (name: string): Expr => uniformRef(name, Tmat4);
+const inv = (v: Expr): Expr => ({ kind: "Inverse", value: v, type: Tmat4 });
+const mul = (lhs: Expr, rhs: Expr): Expr => ({ kind: "MulMatMat", lhs, rhs, type: Tmat4 });
+/** Left-fold `A·B·C·…` (multiplication order). */
+const chain = (...fs: Expr[]): Expr => fs.reduce((acc, f) => mul(acc, f));
+/** mat4 → mat3 truncation (upper-left 3×3). */
+const upper3 = (v: Expr): Expr => ({ kind: "ConvertMatrix", value: v, type: Tmat3 });
+const transpose = (v: Expr): Expr => ({ kind: "Transpose", value: v, type: Tmat4 });
+
+const Model = mat4("Model");
+const View = mat4("View");
+const Proj = mat4("Proj");
+
+/** Standard derived rules, keyed by the drawHeader uniform name each produces. */
+export const STANDARD_DERIVED_RULES: ReadonlyMap<string, DerivedRule> = new Map<string, DerivedRule>([
+  // Trafo passthroughs (collapse the df32 fwd/bwd half to an f32 mat4).
+  ["ModelTrafo", ruleFromIR(Model)],
+  ["ModelTrafoInv", ruleFromIR(inv(Model))],
+  ["ViewTrafo", ruleFromIR(View)],
+  ["ViewTrafoInv", ruleFromIR(inv(View))],
+  ["ProjTrafo", ruleFromIR(Proj)],
+  ["ProjTrafoInv", ruleFromIR(inv(Proj))],
+
+  // Composites. `mul(a,b)` ⇒ matrix product `a · b`.
+  ["ModelViewTrafo", ruleFromIR(chain(View, Model))],
+  ["ModelViewTrafoInv", ruleFromIR(chain(inv(Model), inv(View)))],
+  ["ModelViewProjTrafo", ruleFromIR(chain(Proj, View, Model))],
+  ["ModelViewProjTrafoInv", ruleFromIR(chain(inv(Model), inv(View), inv(Proj)))],
+  ["ViewProjTrafo", ruleFromIR(chain(Proj, View))],
+  ["ViewProjTrafoInv", ruleFromIR(chain(inv(View), inv(Proj)))],
+
+  // NormalMatrix = (Model⁻¹)ᵀ, upper-3×3.
+  ["NormalMatrix", ruleFromIR(upper3(transpose(inv(Model))), Tmat3)],
+]);
+
+/** Leaf name → the RO uniform (`spec.inputs[…]`) that supplies its `aval<Trafo3d>`. */
+export const STANDARD_TRAFO_LEAVES: ReadonlyMap<string, string> = new Map([
+  ["Model", "ModelTrafo"],
+  ["View", "ViewTrafo"],
+  ["Proj", "ProjTrafo"],
+]);
+
+export function isStandardDerivedName(name: string): boolean {
+  return STANDARD_DERIVED_RULES.has(name);
 }

package/src/runtime/derivedUniforms/records.ts

@@ -0,0 +1,158 @@
+// §7 v2 — derived-uniform records buffer (CPU-side authoring; uploaded to a GPU storage buffer).
+//
+// One record per derived-uniform instance (one per (RenderObject, derived name)):
+//   [ rule_id, out_slot, in_slot[0], in_slot[1], … ]
+// `out_slot` / each `in_slot` is a tagged 32-bit handle (see resolveSource):
+//   top 3 bits = source binding, low 29 = payload (constituent slot index / drawHeader
+//   byte offset).
+//
+// Records are flattened (chains substituted away) ⇒ every record is independent ⇒ the
+// uber-kernel runs one thread per record, no levels. Layout is fixed-stride: STRIDE_U32 =
+// 2 + maxArity. If a higher-arity rule shows up the stride grows and `data` is re-packed
+// (rare; the kernel recompiles on that registry-version bump anyway). Fixed stride ⇒ no
+// separate offsets array, trivial swap-remove. See docs/derived-uniforms-extensible.md.
+
+/** Tagged-handle source bindings (top 3 bits of an in_slot / out_slot word). */
+export const enum SlotTag {
+  /** Constituent slot — a Trafo3d half in df32 storage. Payload = slot index. */
+  Constituent = 0,
+  /** A host uniform on the same RO — payload = its data byte offset in the main heap. Also used for the output.
+   *  There is no separate "global" tag: whether a uniform is global is a per-RO fact (the sg can override it
+   *  anywhere), so anything that isn't a constituent trafo resolves to this; a uniform that's the same on every
+   *  RO is the same aval ⇒ the UniformPool interns it to one heap slot anyway. */
+  HostHeap = 1,
+  // 2..7 reserved (per-instance attribute arena, indirect df32 pair, …)
+}
+
+const TAG_SHIFT = 29;
+const PAYLOAD_MASK = (1 << TAG_SHIFT) - 1; // 0x1FFFFFFF
+
+export function makeHandle(tag: SlotTag, payload: number): number {
+  if (payload < 0 || payload > PAYLOAD_MASK) {
+    throw new Error(`derived records: slot payload ${payload} out of range (max ${PAYLOAD_MASK})`);
+  }
+  return ((tag << TAG_SHIFT) | payload) >>> 0;
+}
+export function handleTag(h: number): SlotTag {
+  return (h >>> TAG_SHIFT) as SlotTag;
+}
+export function handlePayload(h: number): number {
+  return h & PAYLOAD_MASK;
+}
+
+/** Owner key — typically the RenderObject (or any stable object). */
+export type RecordOwner = object;
+
+const MIN_STRIDE_U32 = 5; // rule_id, out_slot, in0, in1, in2 — covers the 13 standard recipes
+
+export class RecordsBuffer {
+  private buf: Uint32Array;
+  private owners: (RecordOwner | undefined)[] = [];
+  private readonly byOwner = new Map<RecordOwner, Set<number>>();
+  private strideU32 = MIN_STRIDE_U32;
+  private count = 0;
+  /** Bumps whenever the byte layout changes shape (stride growth) so the dispatcher recompiles. */
+  layoutVersion = 0;
+  /** Bumps on every mutation (add / remove / stride growth) so the dispatcher knows to re-upload. */
+  generation = 0;
+
+  constructor(initialCapacityRecords = 256) {
+    this.buf = new Uint32Array(Math.max(1, initialCapacityRecords) * this.strideU32);
+  }
+
+  get recordCount(): number {
+    return this.count;
+  }
+  get strideWords(): number {
+    return this.strideU32;
+  }
+  get strideBytes(): number {
+    return this.strideU32 * 4;
+  }
+  /** The packed record data, exactly `recordCount * strideWords` long. Upload this. */
+  get data(): Uint32Array {
+    return this.buf.subarray(0, this.count * this.strideU32);
+  }
+
+  /** Append a record. Returns its index. `inSlots` length may exceed the current stride (triggers growth). */
+  add(owner: RecordOwner, ruleId: number, outSlot: number, inSlots: readonly number[]): number {
+    const need = 2 + inSlots.length;
+    if (need > this.strideU32) this.growStride(need);
+    this.ensureCapacity(this.count + 1);
+    const idx = this.count++;
+    const base = idx * this.strideU32;
+    this.buf[base] = ruleId >>> 0;
+    this.buf[base + 1] = outSlot >>> 0;
+    for (let i = 0; i < inSlots.length; i++) this.buf[base + 2 + i] = inSlots[i]! >>> 0;
+    for (let i = base + 2 + inSlots.length; i < base + this.strideU32; i++) this.buf[i] = 0;
+    this.owners[idx] = owner;
+    let set = this.byOwner.get(owner);
+    if (set === undefined) {
+      set = new Set();
+      this.byOwner.set(owner, set);
+    }
+    set.add(idx);
+    this.generation++;
+    return idx;
+  }
+
+  /** Remove every record owned by `owner` (swap-remove against the tail). */
+  removeAllForOwner(owner: RecordOwner): void {
+    const set = this.byOwner.get(owner);
+    if (set === undefined || set.size === 0) {
+      this.byOwner.delete(owner);
+      return;
+    }
+    // Process highest indices first so a swap can never move a not-yet-removed
+    // record of this owner that we still hold a stale index for.
+    const indices = [...set].sort((a, b) => b - a);
+    for (const idx of indices) this.removeAt(idx);
+    this.byOwner.delete(owner);
+    this.generation++;
+  }
+
+  private removeAt(idx: number): void {
+    const last = this.count - 1;
+    // The record currently at `idx` is the one being removed.
+    this.byOwner.get(this.owners[idx]!)?.delete(idx);
+    if (idx !== last) {
+      // Move the tail record's words into the hole, and re-home it.
+      const dst = idx * this.strideU32;
+      const src = last * this.strideU32;
+      this.buf.copyWithin(dst, src, src + this.strideU32);
+      const lastOwner = this.owners[last]!;
+      const lset = this.byOwner.get(lastOwner)!;
+      lset.delete(last);
+      lset.add(idx);
+      this.owners[idx] = lastOwner;
+    }
+    this.owners[last] = undefined;
+    this.owners.length = last;
+    this.count = last;
+  }
+
+  private ensureCapacity(records: number): void {
+    const needWords = records * this.strideU32;
+    if (needWords <= this.buf.length) return;
+    let cap = Math.max(1, this.buf.length);
+    while (cap < needWords) cap *= 2;
+    const next = new Uint32Array(cap);
+    next.set(this.buf);
+    this.buf = next;
+  }
+
+  private growStride(newStride: number): void {
+    const old = this.strideU32;
+    const next = new Uint32Array(Math.max(this.buf.length, this.count * newStride));
+    for (let i = 0; i < this.count; i++) {
+      const o = i * old;
+      const n = i * newStride;
+      next.set(this.buf.subarray(o, o + old), n);
+      // remaining words already zero
+    }
+    this.buf = next;
+    this.strideU32 = newStride;
+    this.layoutVersion++;
+    this.generation++;
+  }
+}

package/src/runtime/derivedUniforms/registry.ts

@@ -0,0 +1,77 @@
+// §7 v2 — derived-uniform rule registry.
+//
+// Content-hash–keyed table of FLATTENED rules. `register` dedups on the
+// flattened IR's hash, assigns a monotonic id (never reused), and bumps
+// `version` whenever a new unique rule appears so the dispatcher knows to
+// recompile its uber-kernel. v0 never sweeps dead entries (a stale rule's
+// switch arm just goes unused — bytes per rule). See
+// docs/derived-uniforms-extensible.md § "Registry" / "Lifecycle".
+
+import type { Expr, Type } from "@aardworx/wombat.shader/ir";
+import type { DerivedRule } from "./rule.js";
+import { inputsOf, type RuleInput } from "./flatten.js";
+
+export interface RuleEntry {
+  /** Monotonic id — the value the uber-kernel `switch`es on. Never reused. */
+  readonly id: number;
+  /** Flattened IR (reads only non-derived inputs). */
+  readonly ir: Expr;
+  readonly outputType: Type;
+  /** Distinct inputs of `ir`, sorted by name — defines the switch-arm argument order. */
+  readonly inputs: readonly RuleInput[];
+  refcount: number;
+}
+
+export class DerivedUniformRegistry {
+  private readonly byHash = new Map<string, RuleEntry>();
+  private readonly byId = new Map<number, RuleEntry>();
+  private nextId = 0;
+  /** Bumps on every `register` that finds a NEW hash. */
+  version = 0;
+
+  /**
+   * Register a flattened rule. Returns its stable id. Idempotent per hash
+   * (just bumps the refcount); a new hash allocates an id and bumps `version`.
+   */
+  register(rule: DerivedRule): number {
+    const cached = this.byHash.get(rule.hash);
+    if (cached !== undefined) {
+      cached.refcount++;
+      return cached.id;
+    }
+    const entry: RuleEntry = {
+      id: this.nextId++,
+      ir: rule.ir,
+      outputType: rule.outputType,
+      inputs: inputsOf(rule.ir),
+      refcount: 1,
+    };
+    this.byHash.set(rule.hash, entry);
+    this.byId.set(entry.id, entry);
+    this.version++;
+    return entry.id;
+  }
+
+  /** Drop one reference. v0: never sweeps — kept for forward-compat with v1 GC. */
+  release(hash: string): void {
+    const entry = this.byHash.get(hash);
+    if (entry !== undefined && entry.refcount > 0) entry.refcount--;
+  }
+
+  get(id: number): RuleEntry | undefined {
+    return this.byId.get(id);
+  }
+
+  getByHash(hash: string): RuleEntry | undefined {
+    return this.byHash.get(hash);
+  }
+
+  /** All entries in id order — the codegen's switch-arm list. */
+  entries(): RuleEntry[] {
+    return [...this.byId.values()].sort((a, b) => a.id - b.id);
+  }
+
+  get size(): number {
+    return this.byId.size;
+  }
+}