@forgeax/engine-render 0.1.23 → 0.1.25

package/src/assembly/webgpu-vertex-layouts.ts

@@ -0,0 +1,132 @@
+import type { GpuVertexBufferLayoutEntry } from '@forgeax/engine-geometry';
+import type { VertexAttributeMap } from '@forgeax/engine-types';
+
+// feat-20260611-fox-skinning-vertex-attribute-chain M4 / w16 (D-4): a single
+// shared empty ArrayBuffer used by the pipeline builder to synthesize the
+// pbr-skin attribute map when no caller-supplied attributes are available.
+// `deriveVertexBufferLayout` is the SSOT for the layout and reads only key
+// presence, so a zero-byte buffer per key preserves the six-attribute stride.
+export const PBR_SKIN_SENTINEL_ATTR_BUFFER = new ArrayBuffer(0);
+
+/** Default 4-attribute vertex layout used as fallback when meshAttributes is undefined. */
+export const DEFAULT_VERTEX_ATTRS: VertexAttributeMap = {
+  position: new Float32Array(0),
+  normal: new Float32Array(0),
+  uv: new Float32Array(0),
+  tangent: new Float32Array(0),
+};
+
+export const PREPARED_INSTANCE_VERTEX_ATTRS: VertexAttributeMap = {
+  position: new Float32Array(0),
+  normal: new Float32Array(0),
+  uv: new Float32Array(0),
+  tangent: new Float32Array(0),
+  uv1: new Float32Array(0),
+};
+
+export const PREPARED_MATERIAL_INSTANCE_VERTEX_ATTRS: VertexAttributeMap = {
+  position: new Float32Array(0),
+  normal: new Float32Array(0),
+  uv: new Float32Array(0),
+  tangent: new Float32Array(0),
+  skinIndex: new Uint16Array(0),
+  skinWeight: new Float32Array(0),
+};
+
+export const POSITION_SIZE_COLOR_INSTANCE_VERTEX_BUFFERS = [
+  {
+    arrayStride: 9 * 4,
+    stepMode: 'instance' as const,
+    attributes: [
+      { shaderLocation: 0, offset: 0, format: 'float32x3' as const },
+      { shaderLocation: 1, offset: 3 * 4, format: 'float32x2' as const },
+      { shaderLocation: 2, offset: 5 * 4, format: 'float32x4' as const },
+    ],
+  },
+] satisfies readonly GPUVertexBufferLayout[];
+
+export const BILLBOARD_MATERIAL_INSTANCE_VERTEX_BUFFERS = [
+  {
+    arrayStride: 31 * 4,
+    stepMode: 'instance' as const,
+    attributes: [
+      { shaderLocation: 0, offset: 0, format: 'float32x3' as const },
+      { shaderLocation: 1, offset: 3 * 4, format: 'float32x2' as const },
+      { shaderLocation: 2, offset: 5 * 4, format: 'float32x2' as const },
+      { shaderLocation: 3, offset: 7 * 4, format: 'float32x4' as const },
+      { shaderLocation: 4, offset: 11 * 4, format: 'float32x4' as const },
+      { shaderLocation: 5, offset: 15 * 4, format: 'float32x4' as const },
+      { shaderLocation: 6, offset: 19 * 4, format: 'float32x4' as const },
+      { shaderLocation: 7, offset: 23 * 4, format: 'float32x4' as const },
+      { shaderLocation: 8, offset: 27 * 4, format: 'float32x4' as const },
+    ],
+  },
+] satisfies readonly GPUVertexBufferLayout[];
+
+export const TOPOLOGY_SEGMENT_INSTANCE_VERTEX_BUFFERS = [
+  {
+    arrayStride: 12 * 4,
+    stepMode: 'instance' as const,
+    attributes: [
+      { shaderLocation: 0, offset: 0, format: 'float32x3' as const },
+      { shaderLocation: 1, offset: 3 * 4, format: 'float32x3' as const },
+      { shaderLocation: 2, offset: 6 * 4, format: 'float32x4' as const },
+      { shaderLocation: 3, offset: 10 * 4, format: 'float32x2' as const },
+    ],
+  },
+] satisfies readonly GPUVertexBufferLayout[];
+
+export const MESH_GEOMETRY_MATERIAL_INSTANCE_VERTEX_BUFFERS = [
+  {
+    arrayStride: 12 * 4,
+    stepMode: 'vertex' as const,
+    attributes: [
+      { shaderLocation: 0, offset: 0, format: 'float32x3' as const },
+      { shaderLocation: 1, offset: 3 * 4, format: 'float32x3' as const },
+      { shaderLocation: 2, offset: 6 * 4, format: 'float32x2' as const },
+      { shaderLocation: 3, offset: 8 * 4, format: 'float32x4' as const },
+    ],
+  },
+  {
+    arrayStride: 28 * 4,
+    stepMode: 'instance' as const,
+    attributes: [
+      { shaderLocation: 4, offset: 0, format: 'float32x3' as const },
+      { shaderLocation: 5, offset: 3 * 4, format: 'float32x3' as const },
+      { shaderLocation: 6, offset: 6 * 4, format: 'float32x3' as const },
+      { shaderLocation: 7, offset: 9 * 4, format: 'float32x3' as const },
+      { shaderLocation: 8, offset: 12 * 4, format: 'float32x4' as const },
+      { shaderLocation: 9, offset: 16 * 4, format: 'float32x4' as const },
+      { shaderLocation: 10, offset: 20 * 4, format: 'float32x4' as const },
+      { shaderLocation: 11, offset: 24 * 4, format: 'float32x4' as const },
+    ],
+  },
+] satisfies readonly GPUVertexBufferLayout[];
+
+function toGpuVertexFormat(
+  format: GpuVertexBufferLayoutEntry['attributes'][number]['format'],
+): GPUVertexFormat {
+  switch (format) {
+    case 'float32x2':
+    case 'float32x3':
+    case 'float32x4':
+    case 'uint16x4':
+      return format;
+    default:
+      throw new Error(`Unsupported geometry vertex format: ${format}`);
+  }
+}
+
+export function toGpuVertexBufferLayouts(
+  entries: readonly GpuVertexBufferLayoutEntry[],
+): readonly GPUVertexBufferLayout[] {
+  return entries.map((entry) => ({
+    arrayStride: entry.arrayStride,
+    ...(entry.stepMode === undefined ? {} : { stepMode: entry.stepMode }),
+    attributes: entry.attributes.map((attribute) => ({
+      shaderLocation: attribute.shaderLocation,
+      offset: attribute.offset,
+      format: toGpuVertexFormat(attribute.format),
+    })),
+  }));
+}

package/src/assets/asset-decoders.ts

@@ -6,6 +6,8 @@ import {
   err,
   MATERIAL_TEXTURE_SLOTS,
   type MaterialAsset,
+  type MaterialChildAsset,
+  type MaterialRootAsset,
   ok,
   type RenderPipelineAsset,
   type SamplerAsset,
@@ -31,6 +33,12 @@ function validMaterial(value: unknown): value is MaterialAsset {
   }
   if (value.passes !== undefined && !Array.isArray(value.passes)) return false;
   if (value.parameters !== undefined && !Array.isArray(value.parameters)) return false;
+  if (
+    value.parent !== undefined &&
+    ['colorSpace', 'passes', 'parameters'].some((field) => Object.hasOwn(value, field))
+  ) {
+    return false;
+  }
   return value.values === undefined || record(value.values);
 }
 
@@ -60,16 +68,22 @@ function resolveMaterialWireRefs(
   if (refs.length === 0) return ok(value);
 
   let changed = false;
-  let parent = value.parent;
+  const wire = value as unknown as { readonly parent?: unknown };
+  let parent = wire.parent;
   if (typeof parent === 'number') {
     const resolved = resolveMaterialWireRef(parent, refs, 'parent', guid);
     if (!resolved.ok) return resolved;
-    parent = resolved.value as unknown as MaterialAsset['parent'];
+    parent = resolved.value;
     changed = true;
   }
 
   if (value.values === undefined) {
-    return changed ? ok({ ...value, ...(parent === undefined ? {} : { parent }) }) : ok(value);
+    if (!changed) return ok(value);
+    if (parent !== undefined) {
+      const child = value as MaterialChildAsset;
+      return ok({ ...child, parent: parent as unknown as MaterialChildAsset['parent'] });
+    }
+    return ok(value);
   }
 
   const textureFields = new Set(
@@ -105,7 +119,16 @@ function resolveMaterialWireRefs(
       values[field] = rewritten as unknown as NonNullable<MaterialAsset['values']>[string];
     }
   }
-  return ok(changed ? { ...value, ...(parent === undefined ? {} : { parent }), values } : value);
+  if (!changed) return ok(value);
+  if (parent !== undefined) {
+    const child = value as MaterialChildAsset;
+    return ok({
+      ...child,
+      parent: parent as unknown as MaterialChildAsset['parent'],
+      values,
+    });
+  }
+  return ok({ ...value, values } as MaterialRootAsset);
 }
 
 export const materialContribution: AssetDecoderContribution<MaterialAsset, 'material'> = {

package/src/components/camera.ts

@@ -14,7 +14,7 @@
 //                      outside M3 scope — the short-name mat4.perspective
 //                      already writes [0, 1] NDC, matching the ortho branch.
 //   projection === 1 → orthographic path; RenderSystem builds
-//                      mat4.orthographic(out, left, right, bottom, top,
+//                      mat4.orthographic(out, left, right, top, bottom,
 //                      near, far) (WebGPU [0, 1] NDC; same z convention).
 //
 // Naming convention: forgeax uses the bare `Camera` name (no `Component`

package/src/components/instances.ts

@@ -1,206 +1,23 @@
-// @forgeax/engine-render - Instances component (per-entity instanced-draw transforms).
-//
-// Two sources, one component (feat-20260622-chunk-gpu-instancing-sprite-tilemap
-// / AC-09; charter P4 consistent abstraction + charter P1 progressive disclosure).
-// The `Instances` ECS component has exactly TWO sources of `transforms` data, and
-// AI users should hold the boundary explicitly to avoid misreading the ECS view:
-//
-//   Source 1 (EXPLICIT, the only source that lands in ECS) — AI user opt-in.
-//     The AI user hand-attaches `Instances { transforms }` onto an entity at
-//     spawn / set time for high-performance instanced draw. `world.get(e,
-//     Instances)` returns the AI user's payload verbatim (a `Float32Array`
-//     snapshot of column-major mat4 instances; stride = 16). This is the sole
-//     code path through which `Instances` ever appears on an entity.
-//
-//   Source 2 (TRANSPARENT, never written back into ECS) — engine record-stage
-//     fold. When the AI user spawns N independent sprite / tilemap-cell
-//     entities sharing the same (Layer.value, posZ, materialHandle) sort
-//     equivalence class, the engine record stage transparently folds the
-//     equivalent run into ONE `drawIndexed(indexCount, count)` using an
-//     INTERNAL transient buffer (see `render-system-record.ts` fold operator
-//     + `render.instancing.foldedDraws` metric, and the `RhiError
-//     'instancing-exceeds-uniform-cap'` fallback). The fold operator does
-//     NOT auto-inject `Instances` onto those entities — `world.get(e,
-//     Instances)` on a folded entity returns `Result.err` exactly as before.
-//     The ECS view is preserved bit-for-bit (per-cell / per-sprite entity
-//     retained, query / despawn / picking unchanged); the optimisation is
-//     invisible at the component layer (charter P4: consistent abstraction —
-//     the high-performance path is opt-in via Source 1, the default spawn
-//     shape stays untouched).
-//
-// AI user reading this header: do NOT expect engine-side fold to materialise
-// as an `Instances` row on your entity. Read the metric (foldedDraws) or the
-// RhiError code to observe fold behaviour; never gate logic on a runtime
-// `world.get(e, Instances)` lookup after spawn.
-//
-// Schema: 1 array<f32> field `transforms` carrying packed column-major mat4
-// instance transforms (16 f32 per instance, stride = 16). Stride is enforced
-// through a TWO-LAYER contract:
-//
-//   1. AI user set-site: spawn / `world.set` / `world.push` callers pass a
-//      `Float32Array` (or numeric array) whose `length` is a non-zero
-//      multiple of 16. The set site is the AI user's responsibility -- the
-//      engine cannot prove the column-major mat4 packing without the
-//      caller's intent.
-//   2. RenderSystem extract entry: `render-system-extract.ts` performs a
-//      defensive `transforms.length % 16 === 0` check on every
-//      `world.get(e, Instances).transforms` snapshot at frame extract time;
-//      violations route a structured `InstanceTransformsStrideMismatchError`
-//      (`code: 'instance-transforms-stride-mismatch'`,
-//      `detail: { actualLength, expectedStride: 16 }`) through the World
-//      Layer-3 ErrorHandler and the renderable is skipped (fail-fast: the
-//      malformed length never reaches the GPU upload path).
-//
-// feat-20260515-buffer-array-vocab-collapse M3 / w16 (decision §2.3 stride
-// responsibility migration): the legacy component-level
-// stride-declaration option (`{ transforms: 16 }` keyed on the retired
-// per-component stride defineComponent option key) was retired because:
-//   - The ECS layer no longer carries a per-component stride schema (M2 /
-//     w9 dropped the option from `DefineComponentOptions` -- the SSOT
-//     moved to the RenderSystem entry + AI user set site).
-//   - Centralising the check at the consumer (RenderSystem extract) rather
-//     than the producer (ECS write paths) lets the GPU upload path stay
-//     trust-the-snapshot; AI users get one structured error per offending
-//     frame rather than one per write.
-//
-// feat-20260514-ecs-children-instances-managed-buffer-array M3 / w14:
-// migrated from the legacy `{ buffer: 'ref', count: 'u32' }` pair (which
-// cross-coupled with the now-deleted `AssetRegistry.createInstancedBuffer`
-// pipeline + the `InstancedBufferAsset` POD) to the ECS-managed array path.
-// Resize is a `world.push(e, Instances, 'transforms', value)` away (one f32
-// at a time) plus a future `world.grow` if a bulk-resize affordance is
-// added.
-//
-// Storage buffer cap-gate (D-5 OOS-08 follow-up):
-//   - The runtime RenderSystem consumer (`render-system-record.ts`) checks
-//     `device.caps.storageBuffer` before binding the per-entity transforms;
-//     `caps.storageBuffer === false` (backend lacking storage buffer support,
-//     e.g. rhi-wgpu webgl backend) routes a `RhiError` ('feature-not-enabled').
-//     A future loop owns the per-draw fallback path.
-//
-// Group transform chained semantics (charter proposition 5 mental migration):
-//   - When the same entity carries both `Transform` (entity_world) and
-//     `Instances` (per-instance local transforms), the vertex shader
-//     composes per instance:
-//
-//       world_position[i] = entity_world * instances_local[i] * vertex_position
-//
-//   - `Instances.transforms[i*16..i*16+15]` is interpreted as a local-space
-//     transform under the entity, exactly like a child entity's `Transform`
-//     under `ChildOf { parent }` in the hierarchy system. AI users reuse
-//     the `parent x local` intuition without a new concept. Set the
-//     entity's `Transform` to identity to make `instances_local[i]`
-//     directly world-space.
-//
-// 4-segment minimum contract (read this header before reaching for
-// the source body):
-//
-// ===== (a) single-component import + spawn example =====
-//
-//   import {
-//     createRenderer, HANDLE_CUBE,
-//     MeshFilter, MeshRenderer, Transform,
-//     Instances, type InstancesData,
-//   } from '@forgeax/engine-render';
-//
-//   // 1 entity rendering N instanced cubes (16N packed f32, column-major mat4):
-//   const transforms = new Float32Array(N * 16);
-//   // ... fill column-major mat4 columns per instance ...
-//   world.spawn(
-//     { component: MeshFilter,    data: { assetHandle: HANDLE_CUBE } },
-//     { component: MeshRenderer,  data: {} },
-//     { component: Instances,     data: { transforms } },
-//   );
-//
-// ===== (b) packed mat4 layout =====
-//
-//   const transforms = new Float32Array(N * 16); // column-major mat4 per instance
-//   // instance i occupies floats [i*16 .. i*16+15]:
-//   //   [m00 m10 m20 m30   <- column 0
-//   //    m01 m11 m21 m31   <- column 1
-//   //    m02 m12 m22 m32   <- column 2
-//   //    m03 m13 m23 m33]  <- column 3 (translation in m03/m13/m23)
-//
-// `transforms.length` MUST be a non-zero multiple of 16. AI users gate at
-// the set / push site; the RenderSystem extract entry holds the second
-// defensive (AC-06: detail carries `{ expectedStride: 16, actualLength }`).
-// The instance count is the live snapshot length / 16.
-//
-// ===== (c) error code consumption (typed property access, no message regex) =====
-//
-//   // Stride violation surfaces through the engine-ecs Layer-3 ErrorHandler
-//   // when extract reads a malformed snapshot:
-//   //   on('error', (err) => {
-//   //     if (err.code === 'instance-transforms-stride-mismatch') {
-//   //       // err.detail.expectedStride === 16
-//   //       // err.detail.actualLength === <user-supplied length>
-//   //     }
-//   //   });
-//   //
-//   // RenderSystem cap-gate (D-5) -> RhiError 'feature-not-enabled' on the
-//   // RhiErrorListenerRegistry channel:
-//   //   on('error', (err) => {
-//   //     if (err.code === 'feature-not-enabled') {
-//   //       console.warn(err.expected, err.hint);
-//   //     }
-//   //   });
-//
-// charter mapping: proposition 1 (single import surface
-// `import { Instances, type InstancesData } from '@forgeax/engine-render'`);
-// proposition 3 (machine-readable schema > prose:
-// `{ transforms: 'array<f32>' }` is the SSOT, stride 16 documented here +
-// enforced at the RenderSystem entry);
-// proposition 4 (explicit failure: stride violation routes a structured
-// EcsError, not a silent half-row); proposition 5 (consistent abstraction:
-// Instances mirrors Children -- both ride the array-vocab path).
-//
-// Anchors: requirements §AC-06 (stride 16 + RenderSystem upload path);
-// plan-strategy §2.3 (stride responsibility migration to RenderSystem entry
-// defensive + AI user set site) + §3.3 stride error path; plan-decisions
-// D-1 / D-5.
-// OOS-09 (no addChild Commands API) does not apply here; OOS-01 (no
-// dangling-entity sweep) does not apply (Instances stores f32 not entity).
-
 import { defineComponent } from '@forgeax/engine-ecs';
 
 /**
- * Per-entity instanced-draw transforms (ECS component).
- *
- * Carries a variable-length `array<f32>` of column-major mat4 instance
- * transforms (16 f32 per instance, stride = 16; documented above and
- * enforced at the RenderSystem extract entry, NOT at the ECS write paths).
- *
- * The runtime RenderSystem consumer materialises a fresh `Float32Array`
- * snapshot on every `world.get(e, Instances).transforms` access (D-4
- * no-cache), reads the live count from the snapshot's `length`, and
- * uploads the bytes to a per-entity GPU storage buffer in the record stage
- * (`render-system-record.ts`).
+ * World-owned local transforms for one explicit instanced renderable.
+ * Packed column-major mat4 values compose as entityWorld * instanceLocal.
+ * ECS owns copying, mutation and entity lifetime, including large arrays.
+ * Renderer extraction derives its own snapshot and GPU residency; neither
+ * authoring nor glTF SceneAsset lowering requires a Renderer identity.
  *
- * @example Spawn an entity rendering 10000 instanced cubes:
- *   const transforms = new Float32Array(10000 * 16);
- *   // ... fill column-major mat4 columns ...
- *   world.spawn(
- *     { component: MeshFilter,   data: { assetHandle: HANDLE_CUBE } },
- *     { component: MeshRenderer, data: { ... } },
- *     { component: Instances,    data: { transforms } },
- *   );
+ * @example
+ * const transforms = new Float32Array(20_000 * 16);
+ * for (let i = 0; i < 20_000; i++) {
+ *   transforms[i * 16] = transforms[i * 16 + 5] =
+ *     transforms[i * 16 + 10] = transforms[i * 16 + 15] = 1;
+ * }
+ * const entity = world.spawn({ component: Instances, data: { transforms } }).unwrap();
+ * world.set(entity, Instances, { transforms }).unwrap();
  */
 export const Instances = defineComponent('Instances', {
   transforms: { type: 'array<f32>' },
 });
 
-/**
- * Type-level hint for `data` at the `Instances` spawn site.
- *
- * The runtime ECS column shape for `array<f32>` accepts a `Float32Array`
- * payload at spawn / set time (the bytes are copied into the BufferPool
- * slot). The `transforms` field is documented as `Float32Array` here so
- * AI-user IDE autocomplete picks up the typed-array shape.
- *
- * @example
- *   import type { InstancesData } from '@forgeax/engine-render';
- *   const data: InstancesData = { transforms: new Float32Array(N * 16) };
- */
-export type InstancesData = {
-  readonly transforms: Float32Array;
-};
+export type InstancesData = { readonly transforms: Float32Array };

package/src/debug-draw-glue.ts

@@ -23,8 +23,8 @@ export function addTypedDebugOverlayPass(
           projection,
           frame.camera.orthoLeft,
           frame.camera.orthoRight,
-          frame.camera.orthoBottom,
           frame.camera.orthoTop,
+          frame.camera.orthoBottom,
           frame.camera.near,
           frame.camera.far,
         );

package/src/device/device-scope.ts

@@ -46,6 +46,17 @@ interface OwnedResource {
   readonly cleanup: (value: unknown) => void | Promise<void>;
 }
 
+function idempotentCleanup<T>(
+  cleanup: (value: T) => void | Promise<void>,
+): (value: T) => void | Promise<void> {
+  let cleaned = false;
+  return (value: T) => {
+    if (cleaned) return;
+    cleaned = true;
+    return cleanup(value);
+  };
+}
+
 export class DeviceScope {
   readonly generation: number;
   readonly owner: string;
@@ -117,7 +128,7 @@ export class DeviceScope {
     const ref = new DeviceResourceRef(kind, this.owner, this.generation, value);
     this.resources.push({
       ref: ref as DeviceResourceRef<unknown>,
-      cleanup: cleanup as (resource: unknown) => void | Promise<void>,
+      cleanup: idempotentCleanup(cleanup) as (resource: unknown) => void | Promise<void>,
     });
     return ref;
   }
@@ -142,9 +153,21 @@ export class DeviceScope {
     if (this.lifecycleState === 'active') this.lifecycleState = 'retiring';
   }
 
+  private clearChildren(): void {
+    for (const child of [...this.children].reverse()) {
+      child.retire();
+    }
+  }
+
+  private detachChild(child: DeviceScope): void {
+    const index = this.children.indexOf(child);
+    if (index >= 0) this.children.splice(index, 1);
+  }
+
   retire(): void {
     if (this.lifecycleState !== 'active' && this.lifecycleState !== 'retiring') return;
     this.lifecycleState = 'retiring';
+    this.clearChildren();
     this._clearResources();
     this.lifecycleState = 'retired';
   }
@@ -152,12 +175,14 @@ export class DeviceScope {
   abandon(): void {
     if (this.lifecycleState !== 'active') return;
     this.lifecycleState = 'abandoned';
+    this.clearChildren();
     this._clearResources();
   }
 
   dispose(): void {
     if (this.lifecycleState === 'disposed') return;
     this.lifecycleState = 'disposed';
+    this.clearChildren();
     this._clearResources();
   }
 
@@ -177,6 +202,9 @@ export class DeviceScope {
       replacement.dispose();
       return transaction.failure('dispose');
     }
+    // The replacement is now the new owner. Detach it before retiring the
+    // old parent so parent cleanup cannot retire the just-published child.
+    this.detachChild(replacement);
     this.retire();
     return ok(replacement);
   }
@@ -217,6 +245,7 @@ export interface LifecycleTransactionOptions {
 interface CreatedResource {
   readonly spec: LifecycleResourceSpec<unknown>;
   readonly value: unknown;
+  readonly cleanup: (value: unknown) => void | Promise<void>;
 }
 
 export class LifecycleTransaction {
@@ -250,10 +279,10 @@ export class LifecycleTransaction {
         }
         const value = await spec.create();
         if (!this.scope.isAlive()) {
-          await this.cleanupOne(spec, value, created);
+          await this.cleanupOne(value, created, idempotentCleanup(spec.cleanup));
           return this.failure('dispose');
         }
-        created.push({ spec, value });
+        created.push({ spec, value, cleanup: idempotentCleanup(spec.cleanup) });
       } catch (cause) {
         const cleanupFailures = await this.cleanupCreated(created);
         return this.failure('create', spec.kind, cleanupFailures, cause);
@@ -296,7 +325,7 @@ export class LifecycleTransaction {
       const item = created[index];
       if (item === undefined) continue;
       try {
-        await item.spec.cleanup(item.value);
+        await item.cleanup(item.value);
       } catch (cause) {
         failures.push({ resourceKind: item.spec.kind, cause });
       }
@@ -305,13 +334,13 @@ export class LifecycleTransaction {
   }
 
   private async cleanupOne(
-    spec: LifecycleResourceSpec<unknown>,
     value: unknown,
     created: readonly CreatedResource[],
+    cleanup: (value: unknown) => void | Promise<void>,
   ): Promise<void> {
     await this.cleanupCreated(created);
     try {
-      await spec.cleanup(value);
+      await cleanup(value);
     } catch {
       // The terminal dispose result is intentionally bounded; prior cleanup
       // evidence remains in the transaction failure shape.