@forgeax/engine-render 0.1.2

package/src/extract/visibility.ts

@@ -0,0 +1,120 @@
+import { Entity, type EntityHandle, type World } from '@forgeax/engine-ecs';
+import {
+  projectHierarchy,
+  type SceneHierarchyDiagnostic,
+  type SceneHierarchySnapshot,
+} from '@forgeax/engine-scene';
+import {
+  Visibility,
+  type VisibilityState,
+  VisibilityStateValue,
+  visibilityStateFromU32,
+} from '../components/visibility';
+
+export type VisibilitySource = 'default' | 'self' | 'parent';
+
+export interface VisibilityResolution {
+  /** The component value authored on this entity before inheritance. */
+  readonly intent: VisibilityState;
+  /** The state consumed by render candidates after parent resolution. */
+  readonly effective: 'hidden' | 'visible';
+  /** Explains whether the effective state came from self, parent, or default. */
+  readonly source: VisibilitySource;
+}
+
+export interface VisibilitySnapshot {
+  readonly diagnostics: readonly SceneHierarchyDiagnostic[];
+  readonly hasAnyIntent: boolean;
+  readonly hasAnyHiddenIntent: boolean;
+  get(entity: EntityHandle): VisibilityResolution | undefined;
+  /** Resolve effective visibility for a render candidate, including inherited defaults. */
+  effective(entity: EntityHandle): 'hidden' | 'visible';
+}
+
+interface ResolutionState {
+  readonly intent: VisibilityState;
+  readonly effective: 'hidden' | 'visible';
+  readonly source: VisibilitySource;
+}
+
+/**
+ * Resolve author intent against the scene-owned valid parent projection.
+ * Diagnostics are preserved for callers to repair hierarchy input before retry.
+ */
+export function resolveVisibility(
+  world: World,
+  hierarchy: SceneHierarchySnapshot = projectHierarchy(world),
+): VisibilitySnapshot {
+  const query = world.query({ read: [Entity], optional: [Visibility] });
+  let intentCount = 0;
+  let hasAnyHiddenIntent = false;
+  if (query.ok) {
+    for (const row of query.value) {
+      const visibility = row.get(Visibility);
+      if (visibility === undefined) continue;
+      intentCount += 1;
+      if (visibility.state === VisibilityStateValue.hidden) {
+        hasAnyHiddenIntent = true;
+      }
+    }
+  }
+
+  let resolveEntity: ((entity: EntityHandle) => ResolutionState | undefined) | undefined;
+  let hasIntent: ((entity: EntityHandle) => boolean) | undefined;
+  const ensureResolver = (): void => {
+    if (resolveEntity !== undefined) return;
+    const intentByEntity = new Map<EntityHandle, VisibilityState>();
+    if (query.ok) {
+      for (const row of query.value) {
+        const raw = row.get(Visibility);
+        const intent = raw === undefined ? undefined : visibilityStateFromU32(raw.state);
+        if (intent !== undefined) {
+          intentByEntity.set(row.entity, intent);
+        }
+      }
+    }
+    hasIntent = (entity: EntityHandle): boolean => intentByEntity.has(entity);
+    const resolved = new Map<EntityHandle, ResolutionState>();
+    const resolving = new Set<EntityHandle>();
+    resolveEntity = (entity: EntityHandle): ResolutionState | undefined => {
+      const existing = resolved.get(entity);
+      if (existing !== undefined) return existing;
+      if (resolving.has(entity)) return undefined;
+
+      const intent = intentByEntity.get(entity) ?? 'inherited';
+      resolving.add(entity);
+
+      let result: ResolutionState;
+      if (intent === 'hidden') {
+        result = { intent, effective: 'hidden', source: 'self' };
+      } else if (intent === 'visible') {
+        result = { intent, effective: 'visible', source: 'self' };
+      } else {
+        const parent = hierarchy.getParent(entity);
+        const parentResult = parent === undefined ? undefined : resolveEntity?.(parent);
+        result =
+          parentResult === undefined
+            ? { intent, effective: 'visible', source: 'default' }
+            : { intent, effective: parentResult.effective, source: 'parent' };
+      }
+
+      resolving.delete(entity);
+      resolved.set(entity, result);
+      return result;
+    };
+  };
+
+  return {
+    diagnostics: hierarchy.diagnostics,
+    hasAnyIntent: intentCount > 0,
+    hasAnyHiddenIntent,
+    get(entity: EntityHandle): VisibilityResolution | undefined {
+      ensureResolver();
+      return hasIntent?.(entity) ? resolveEntity?.(entity) : undefined;
+    },
+    effective(entity: EntityHandle): 'hidden' | 'visible' {
+      ensureResolver();
+      return resolveEntity?.(entity)?.effective ?? 'visible';
+    },
+  };
+}

package/src/features/graph-contribution.ts

@@ -0,0 +1,577 @@
+import type {
+  ComputePassDescriptor,
+  PassDescriptor,
+  RenderGraph,
+  ResolveContext,
+  ResourceDescriptor,
+} from '@forgeax/engine-render-graph';
+import { err, ok, type Result } from '@forgeax/engine-types';
+import {
+  type RenderError,
+  RenderFeatureDrawRecordingFailedError,
+  RenderFeaturePassOrderConflictError,
+  RenderFeaturePreparationFailedError,
+  RenderFeatureStageFailedError,
+} from '../errors/render';
+import type { PreparedGraphicsResolvedSnapshot } from '../prepare/prepared-graphics-resolver';
+import type {
+  RenderFeatureGpuComputePassDescriptor,
+  RenderFeatureResolvedGpuComputePass,
+} from './prepared-gpu-work';
+import { encodeRenderFeatureGpuComputePass } from './prepared-gpu-work';
+import type {
+  RenderFeatureGraphicsContributionStaging,
+  RenderFeatureGraphicsPassDescriptor,
+  RenderFeaturePreparedGraphicsState,
+} from './prepared-graphics';
+import {
+  isRenderFeatureTargetHandle,
+  type RenderFeatureTargetHandle,
+  renderFeatureAttachmentResource,
+} from './targets';
+import type { RenderFeaturePassContext } from './types';
+
+export interface RenderFeaturePassDependency {
+  readonly featureIdentity: string;
+  readonly passIdentity: string;
+}
+
+export interface RenderFeaturePassOptions {
+  readonly dependsOn?: readonly RenderFeaturePassDependency[];
+}
+
+export interface RenderFeatureContributionResource {
+  readonly name: string;
+  readonly descriptor: ResourceDescriptor;
+}
+
+export interface RenderFeatureContributionPass<Ctx = RenderFeaturePassContext> {
+  readonly featureIdentity: string;
+  readonly order: number;
+  readonly name: string;
+  readonly descriptor: PassDescriptor<Ctx>;
+  readonly dependsOn: readonly string[];
+  readonly graphics?: RenderFeatureGraphicsPassDescriptor;
+  readonly graphicsState?: RenderFeaturePreparedGraphicsState;
+  readonly resolvedGraphics?: PreparedGraphicsResolvedSnapshot;
+  readonly gpuCompute?: RenderFeatureGpuComputePassDescriptor;
+  readonly resolvedGpuCompute?: RenderFeatureResolvedGpuComputePass;
+}
+
+export interface RenderFeatureGraphContribution<Ctx = RenderFeaturePassContext> {
+  readonly featureIdentity: string;
+  readonly order: number;
+  readonly resources: readonly RenderFeatureContributionResource[];
+  readonly passes: readonly RenderFeatureContributionPass<Ctx>[];
+  readonly topologySignature: string;
+}
+
+export interface RenderFeatureContributionStaging<Ctx = RenderFeaturePassContext>
+  extends RenderFeatureGraphicsContributionStaging {
+  readonly resources: readonly RenderFeatureContributionResource[];
+  readonly passes: readonly RenderFeatureContributionPass<Ctx>[];
+  addResource(name: string, descriptor: ResourceDescriptor): Result<void, RenderError>;
+  addPass(
+    name: string,
+    descriptor: PassDescriptor<Ctx>,
+    options?: RenderFeaturePassOptions,
+  ): Result<void, RenderError>;
+  addComputePass(
+    name: string,
+    descriptor: RenderFeatureGpuComputePassDescriptor,
+    options?: RenderFeaturePassOptions,
+  ): Result<void, RenderError>;
+  commit(): Result<RenderFeatureGraphContribution<Ctx>, RenderError>;
+  abort(): void;
+}
+
+export type RenderFeatureGraphicsValidator = (
+  descriptor: RenderFeatureGraphicsPassDescriptor,
+  resources: readonly RenderFeatureContributionResource[],
+) => Result<RenderFeaturePreparedGraphicsState, RenderError>;
+
+export type RenderFeatureGraphicsResolver = (
+  descriptor: RenderFeatureGraphicsPassDescriptor,
+) => Result<PreparedGraphicsResolvedSnapshot, RenderError>;
+
+export type RenderFeatureGpuComputeResolver = (
+  descriptor: RenderFeatureGpuComputePassDescriptor,
+) => Result<RenderFeatureResolvedGpuComputePass, RenderError>;
+
+function qualify(identity: string, name: string): string {
+  return `${identity}::${name}`;
+}
+
+function qualifyAttachment(identity: string, resource: string | RenderFeatureTargetHandle): string {
+  const name = renderFeatureAttachmentResource(resource);
+  return name === 'swapchain' || isRenderFeatureTargetHandle(resource)
+    ? name
+    : qualify(identity, name);
+}
+
+function failed(identity: string, order: number): RenderFeatureStageFailedError {
+  return new RenderFeatureStageFailedError(identity, order, 'contribute', 'next-frame');
+}
+
+function signature<Ctx>(
+  resources: readonly RenderFeatureContributionResource[],
+  passes: readonly RenderFeatureContributionPass<Ctx>[],
+): string {
+  return JSON.stringify({
+    resources: resources.map((resource) => [resource.name, resource.descriptor]),
+    passes: passes.map((pass) => [
+      pass.name,
+      pass.descriptor.reads,
+      pass.descriptor.writes,
+      pass.dependsOn,
+      pass.graphics,
+      pass.gpuCompute === undefined
+        ? undefined
+        : {
+            programGeneration: pass.gpuCompute.program.generation,
+            bindingsGeneration: pass.gpuCompute.bindings.generation,
+            dispatches: pass.gpuCompute.dispatches.map((dispatch) =>
+              dispatch.workgroups === undefined
+                ? {
+                    entryPoint: dispatch.entryPoint,
+                    indirect: {
+                      buffer: dispatch.indirect.buffer.name,
+                      generation: dispatch.indirect.buffer.generation,
+                      offset: dispatch.indirect.offset,
+                    },
+                    bindingsGeneration: dispatch.bindings?.generation,
+                  }
+                : {
+                    entryPoint: dispatch.entryPoint,
+                    workgroups: dispatch.workgroups,
+                    bindingsGeneration: dispatch.bindings?.generation,
+                  },
+            ),
+          },
+      pass.resolvedGpuCompute?.buffers.map((buffer) => ({
+        name: buffer.name,
+        size: buffer.size,
+        physicalUsage: buffer.physicalUsage,
+        access: buffer.access,
+      })),
+    ]),
+  });
+}
+
+class ContributionStaging<Ctx> implements RenderFeatureContributionStaging<Ctx> {
+  private aborted = false;
+  private committed = false;
+  private readonly resourceEntries: RenderFeatureContributionResource[] = [];
+  private readonly passEntries: RenderFeatureContributionPass<Ctx>[] = [];
+
+  constructor(
+    private readonly identity: string,
+    private readonly order: number,
+    private readonly validateGraphics?: RenderFeatureGraphicsValidator,
+    private readonly resolveGraphics?: RenderFeatureGraphicsResolver,
+    private readonly resolveGpuCompute?: RenderFeatureGpuComputeResolver,
+  ) {}
+
+  get resources(): readonly RenderFeatureContributionResource[] {
+    return this.resourceEntries;
+  }
+
+  get passes(): readonly RenderFeatureContributionPass<Ctx>[] {
+    return this.passEntries;
+  }
+
+  addResource(name: string, descriptor: ResourceDescriptor): Result<void, RenderError> {
+    if (
+      this.aborted ||
+      this.committed ||
+      this.resourceEntries.some((entry) => entry.name === qualify(this.identity, name))
+    ) {
+      return err(failed(this.identity, this.order));
+    }
+    this.resourceEntries.push({ name: qualify(this.identity, name), descriptor });
+    return ok(undefined);
+  }
+
+  addPass(
+    name: string,
+    descriptor: PassDescriptor<Ctx>,
+    options: RenderFeaturePassOptions = {},
+  ): Result<void, RenderError> {
+    const qualifiedName = qualify(this.identity, name);
+    if (
+      this.aborted ||
+      this.committed ||
+      this.passEntries.some((entry) => entry.name === qualifiedName)
+    ) {
+      return err(failed(this.identity, this.order));
+    }
+    const dependencies = (options.dependsOn ?? []).map((dependency) =>
+      qualify(dependency.featureIdentity, dependency.passIdentity),
+    );
+    this.passEntries.push({
+      featureIdentity: this.identity,
+      order: this.order,
+      name: qualifiedName,
+      descriptor: {
+        ...descriptor,
+        reads: descriptor.reads.map((read) => qualify(this.identity, read)),
+        writes: descriptor.writes.map((write) => qualify(this.identity, write)),
+      },
+      dependsOn: dependencies,
+    });
+    return ok(undefined);
+  }
+
+  addGraphicsPass(
+    name: string,
+    descriptor: RenderFeatureGraphicsPassDescriptor,
+    options: RenderFeaturePassOptions = {},
+  ): Result<void, RenderError> {
+    const qualifiedName = qualify(this.identity, name);
+    if (
+      this.aborted ||
+      this.committed ||
+      descriptor.draws.length === 0 ||
+      this.passEntries.some((entry) => entry.name === qualifiedName)
+    ) {
+      return this.aborted ||
+        this.committed ||
+        this.passEntries.some((entry) => entry.name === qualifiedName)
+        ? err(failed(this.identity, this.order))
+        : ok(undefined);
+    }
+    const graphicsState = this.validateGraphics?.(descriptor, this.resourceEntries);
+    if (graphicsState !== undefined && !graphicsState.ok) {
+      return err(graphicsState.error);
+    }
+    const resolvedGraphics = this.resolveGraphics?.(descriptor);
+    if (resolvedGraphics !== undefined && !resolvedGraphics.ok) {
+      if (
+        resolvedGraphics.error instanceof RenderFeaturePreparationFailedError &&
+        resolvedGraphics.error.detail.reason === 'pipeline-pending'
+      ) {
+        return ok(undefined);
+      }
+      return err(resolvedGraphics.error);
+    }
+    const qualifiedResources = descriptor.attachments.colors.map((attachment) =>
+      qualifyAttachment(this.identity, attachment.resource),
+    );
+    const qualifiedDepth =
+      descriptor.attachments.depthStencil === undefined
+        ? undefined
+        : qualifyAttachment(this.identity, descriptor.attachments.depthStencil.resource);
+    const sampledTargets = (descriptor.sampledTargets ?? []).map((sampled) =>
+      renderFeatureAttachmentResource(sampled),
+    );
+    const contributionPass: RenderFeatureContributionPass<Ctx> = {
+      featureIdentity: this.identity,
+      order: this.order,
+      name: qualifiedName,
+      descriptor: {
+        reads: [...(qualifiedDepth === undefined ? [] : [qualifiedDepth]), ...sampledTargets],
+        writes: qualifiedResources,
+      },
+      dependsOn: (options.dependsOn ?? []).map((dependency) =>
+        qualify(dependency.featureIdentity, dependency.passIdentity),
+      ),
+      graphics: descriptor,
+      ...(graphicsState?.ok === true ? { graphicsState: graphicsState.value } : {}),
+      ...(resolvedGraphics?.ok === true ? { resolvedGraphics: resolvedGraphics.value } : {}),
+    };
+    this.passEntries.push(contributionPass);
+    return ok(undefined);
+  }
+
+  addComputePass(
+    name: string,
+    descriptor: RenderFeatureGpuComputePassDescriptor,
+    options: RenderFeaturePassOptions = {},
+  ): Result<void, RenderError> {
+    const qualifiedName = qualify(this.identity, name);
+    if (
+      this.aborted ||
+      this.committed ||
+      descriptor.dispatches.length === 0 ||
+      this.passEntries.some((entry) => entry.name === qualifiedName)
+    ) {
+      return err(failed(this.identity, this.order));
+    }
+    const resolved = this.resolveGpuCompute?.(descriptor);
+    if (resolved === undefined || !resolved.ok) {
+      return resolved === undefined ? err(failed(this.identity, this.order)) : resolved;
+    }
+    this.passEntries.push({
+      featureIdentity: this.identity,
+      order: this.order,
+      name: qualifiedName,
+      descriptor: { reads: [], writes: [] },
+      dependsOn: (options.dependsOn ?? []).map((dependency) =>
+        qualify(dependency.featureIdentity, dependency.passIdentity),
+      ),
+      gpuCompute: descriptor,
+      resolvedGpuCompute: resolved.value,
+    });
+    return ok(undefined);
+  }
+
+  commit(): Result<RenderFeatureGraphContribution<Ctx>, RenderError> {
+    if (this.aborted || this.committed) return err(failed(this.identity, this.order));
+    this.committed = true;
+    return ok({
+      featureIdentity: this.identity,
+      order: this.order,
+      resources: Object.freeze([...this.resourceEntries]),
+      passes: Object.freeze([...this.passEntries]),
+      topologySignature: signature(this.resourceEntries, this.passEntries),
+    });
+  }
+
+  abort(): void {
+    if (this.committed) return;
+    this.aborted = true;
+    this.resourceEntries.length = 0;
+    this.passEntries.length = 0;
+  }
+}
+
+export function createRenderFeatureContributionStaging<Ctx = RenderFeaturePassContext>(
+  featureIdentity: string,
+  order: number,
+  validateGraphics?: RenderFeatureGraphicsValidator,
+  resolveGraphics?: RenderFeatureGraphicsResolver,
+  resolveGpuCompute?: RenderFeatureGpuComputeResolver,
+): RenderFeatureContributionStaging<Ctx> {
+  return new ContributionStaging(
+    featureIdentity,
+    order,
+    validateGraphics,
+    resolveGraphics,
+    resolveGpuCompute,
+  );
+}
+
+export function mergeRenderFeatureContributions<Ctx>(
+  contributions: readonly RenderFeatureGraphContribution<Ctx>[],
+): Result<RenderFeatureGraphContribution<Ctx>, RenderError> {
+  const ordered = [...contributions].sort((left, right) => left.order - right.order);
+  const byIdentity = new Map(
+    ordered.map((contribution) => [contribution.featureIdentity, contribution]),
+  );
+  for (const contribution of ordered) {
+    const localPasses = new Map(contribution.passes.map((pass, index) => [pass.name, index]));
+    for (const pass of contribution.passes) {
+      for (const dependency of pass.dependsOn) {
+        const separator = dependency.lastIndexOf('::');
+        const dependencyFeature = separator < 0 ? dependency : dependency.slice(0, separator);
+        const dependencyContribution = byIdentity.get(dependencyFeature);
+        const dependencyIndex = dependencyContribution?.passes.findIndex(
+          (entry) => entry.name === dependency,
+        );
+        const isLaterFeature =
+          dependencyContribution !== undefined && dependencyContribution.order > contribution.order;
+        const isLaterLocalPass =
+          dependencyContribution === contribution &&
+          dependencyIndex !== undefined &&
+          dependencyIndex >= (localPasses.get(pass.name) ?? 0);
+        if (dependencyContribution === undefined || isLaterFeature || isLaterLocalPass) {
+          return err(
+            new RenderFeaturePassOrderConflictError(
+              contribution.featureIdentity,
+              contribution.order,
+              pass.name,
+              dependency,
+            ),
+          );
+        }
+      }
+    }
+  }
+  const resources = ordered.flatMap((contribution) => contribution.resources);
+  const passes = ordered.flatMap((contribution) => contribution.passes);
+  return ok({
+    featureIdentity: 'render-feature-aggregate',
+    order: -1,
+    resources,
+    passes,
+    topologySignature: signature(resources, passes),
+  });
+}
+
+export interface RenderFeatureGraphComposition<
+  GraphCtx = unknown,
+  FeatureCtx = RenderFeaturePassContext,
+> {
+  readonly graph: RenderGraph<GraphCtx>;
+  readonly topologySignature: string;
+  readonly passNames: readonly string[];
+  readonly executeCount: number;
+  update(contributions: readonly RenderFeatureGraphContribution<FeatureCtx>[]): {
+    readonly topologyChanged: boolean;
+  };
+}
+
+function toDelegate<FeatureCtx>(
+  execute: PassDescriptor<FeatureCtx>['execute'],
+): ((context: FeatureCtx) => void) | undefined {
+  if (execute === undefined) return undefined;
+  return (context) => (execute as (value: FeatureCtx) => void)(context);
+}
+
+export type RenderFeatureGraphPassProjector<GraphCtx, FeatureCtx> = (
+  context: GraphCtx,
+  pass: RenderFeatureContributionPass<FeatureCtx>,
+  resolveContext: ResolveContext,
+  execute: (context: FeatureCtx) => void,
+) => void;
+
+export type RenderFeatureGraphErrorReporter = (
+  featureIdentity: string,
+  order: number,
+  failure: unknown,
+) => void;
+
+export function composeRenderFeatureGraph<GraphCtx, FeatureCtx = RenderFeaturePassContext>(
+  graph: RenderGraph<GraphCtx>,
+  contributions: readonly RenderFeatureGraphContribution<FeatureCtx>[],
+  project: RenderFeatureGraphPassProjector<GraphCtx, FeatureCtx> = (
+    context,
+    _pass,
+    _resolveContext,
+    execute,
+  ) => execute(context as unknown as FeatureCtx),
+  reportError?: RenderFeatureGraphErrorReporter,
+): Result<RenderFeatureGraphComposition<GraphCtx, FeatureCtx>, RenderError> {
+  const merged = mergeRenderFeatureContributions(contributions);
+  if (!merged.ok) return merged;
+  const proxies = merged.value.passes.map((pass) => ({
+    name: pass.name,
+    pass,
+    delegate: toDelegate(pass.descriptor.execute),
+  }));
+  const existingPasses = graph.listPasses();
+  const featureWrites = new Set(merged.value.passes.flatMap((pass) => pass.descriptor.writes));
+  const insertBefore = existingPasses.find((pass) =>
+    pass.reads.some((resource) => featureWrites.has(resource)),
+  )?.name;
+  for (const resource of merged.value.resources) {
+    const added = graph.addResource(resource.name, resource.descriptor);
+    if (!added.ok) return err(failed(merged.value.featureIdentity, merged.value.order));
+  }
+  const computeResources = new Map<object, string>();
+  for (const pass of merged.value.passes) {
+    for (const [index, buffer] of (pass.resolvedGpuCompute?.buffers ?? []).entries()) {
+      if (computeResources.has(buffer.buffer)) continue;
+      const name = `${pass.name}::buffer-${index}`;
+      const added = graph.addResource(name, { kind: 'buffer', lifetime: 'persistent' });
+      if (!added.ok) return err(failed(pass.featureIdentity, pass.order));
+      computeResources.set(buffer.buffer, name);
+    }
+  }
+  let executeCount = 0;
+  let observedExecution = false;
+  for (const [index, pass] of merged.value.passes.entries()) {
+    const proxy = proxies[index];
+    if (proxy === undefined) continue;
+    const resolvedCompute = pass.resolvedGpuCompute;
+    if (resolvedCompute !== undefined) {
+      const reads = resolvedCompute.buffers
+        .map((buffer) => computeResources.get(buffer.buffer))
+        .filter((name): name is string => name !== undefined);
+      const writes = resolvedCompute.buffers
+        .filter((buffer) => buffer.access === 'storage-read-write')
+        .map((buffer) => computeResources.get(buffer.buffer))
+        .filter((name): name is string => name !== undefined);
+      const descriptor: ComputePassDescriptor<GraphCtx> = {
+        reads,
+        writes,
+        encode: ({ pass: computePass }) => {
+          if (!observedExecution) {
+            observedExecution = true;
+            executeCount += 1;
+          }
+          try {
+            const current = proxy.pass.resolvedGpuCompute;
+            if (current === undefined) throw failed(proxy.pass.featureIdentity, proxy.pass.order);
+            encodeRenderFeatureGpuComputePass(computePass, current);
+          } catch (failure) {
+            reportError?.(
+              proxy.pass.featureIdentity,
+              proxy.pass.order,
+              failure instanceof Error && typeof (failure as Partial<RenderError>).code === 'string'
+                ? failure
+                : new RenderFeatureDrawRecordingFailedError(
+                    proxy.pass.featureIdentity,
+                    proxy.pass.order,
+                    proxy.pass.name,
+                    'bindings',
+                    'backend-recording-failed',
+                    failure instanceof Error ? failure.message : String(failure),
+                    'renderer-recover',
+                  ),
+            );
+          }
+        },
+      };
+      if (insertBefore === undefined) graph.addComputePass(pass.name, descriptor);
+      else graph._addComputePassBefore(pass.name, insertBefore, descriptor);
+      continue;
+    }
+    const descriptor: PassDescriptor<GraphCtx> = {
+      ...pass.descriptor,
+      execute: (ctx: GraphCtx, resolveCtx: ResolveContext) => {
+        if (!observedExecution) {
+          observedExecution = true;
+          executeCount += 1;
+        }
+        try {
+          project(ctx, proxy.pass, resolveCtx, (featureContext) =>
+            proxy.delegate?.(featureContext),
+          );
+        } catch (failure) {
+          reportError?.(
+            pass.featureIdentity,
+            pass.order,
+            failure instanceof Error && typeof (failure as Partial<RenderError>).code === 'string'
+              ? failure
+              : new RenderFeatureDrawRecordingFailedError(
+                  pass.featureIdentity,
+                  pass.order,
+                  pass.name,
+                  proxy.pass.gpuCompute === undefined ? 'pipeline' : 'bindings',
+                  'backend-recording-failed',
+                  failure instanceof Error ? failure.message : String(failure),
+                  'renderer-recover',
+                ),
+          );
+        }
+      },
+    };
+    if (insertBefore === undefined) graph.addPass(pass.name, descriptor);
+    else graph._addPassBefore(pass.name, insertBefore, descriptor);
+  }
+  let currentSignature = merged.value.topologySignature;
+  return ok({
+    graph,
+    topologySignature: currentSignature,
+    passNames: Object.freeze(merged.value.passes.map((pass) => pass.name)),
+    get executeCount() {
+      return executeCount;
+    },
+    update(next) {
+      const nextMerged = mergeRenderFeatureContributions(next);
+      if (!nextMerged.ok || nextMerged.value.topologySignature !== currentSignature) {
+        return { topologyChanged: true };
+      }
+      for (const [index, pass] of nextMerged.value.passes.entries()) {
+        const proxy = proxies[index];
+        if (proxy !== undefined) {
+          proxy.pass = pass;
+          proxy.delegate = toDelegate(pass.descriptor.execute);
+        }
+      }
+      currentSignature = nextMerged.value.topologySignature;
+      return { topologyChanged: false };
+    },
+  });
+}