@forgeax/engine-render-graph 0.0.0-dev.8d955ade1c79

package/src/compiled-graph.ts

@@ -0,0 +1,383 @@
+import type {
+  Buffer,
+  RenderPassColorAttachment,
+  RenderPassDepthStencilAttachment,
+  RhiComputePassEncoder,
+  RhiDevice,
+  Texture,
+  TextureView,
+} from '@forgeax/engine-rhi';
+import { err, ok, RenderGraphError, type Result } from './errors.js';
+import type {
+  CompiledPass,
+  CompiledResource,
+  CompiledView,
+  ResourceHandleData,
+} from './kernel-internal.js';
+import { handleData } from './kernel-internal.js';
+import type {
+  CompiledRenderGraph,
+  CompiledRenderGraphInfo,
+  GraphBuffer,
+  GraphResourceResolver,
+  GraphTexture,
+  GraphTextureView,
+  RenderGraphFrame,
+  RenderGraphPassRunner,
+} from './types.js';
+
+interface FrameResources {
+  readonly buffers: ReadonlyMap<number, Buffer>;
+  readonly textures: ReadonlyMap<number, Texture>;
+  readonly views: ReadonlyMap<number, TextureView>;
+}
+
+function resolutionError(label: string, cause?: unknown): RenderGraphError {
+  return new RenderGraphError({
+    code: 'resource-resolution-failed',
+    expected: `resource '${label}' resolves to a live RHI handle for this frame`,
+    hint: `repair the imported owner for '${label}' before executing the graph`,
+    detail: { resourceLabel: label, ...(cause === undefined ? {} : { accesses: [String(cause)] }) },
+  });
+}
+
+export class CompiledRenderGraphImpl<FrameCtx extends RenderGraphFrame>
+  implements CompiledRenderGraph<FrameCtx>
+{
+  private retired = false;
+  private retireResult: Promise<Result<void, RenderGraphError>> | undefined;
+
+  constructor(
+    private readonly generation: number,
+    private readonly owner: object,
+    private readonly device: RhiDevice,
+    private readonly resources: ReadonlyMap<number, CompiledResource<FrameCtx>>,
+    private readonly views: ReadonlyMap<number, CompiledView<FrameCtx>>,
+    private readonly passes: readonly CompiledPass<FrameCtx>[],
+    private readonly info: CompiledRenderGraphInfo,
+  ) {}
+
+  inspect(): CompiledRenderGraphInfo {
+    return this.info;
+  }
+
+  execute(frame: FrameCtx, runPass?: RenderGraphPassRunner): Result<void, RenderGraphError> {
+    if (this.retired) {
+      return err(
+        new RenderGraphError({
+          code: 'compiled-graph-retired',
+          expected: 'a compiled graph executes only before retire()',
+          hint: 'publish and execute the replacement compiled graph',
+          detail: { generation: this.generation },
+        }),
+      );
+    }
+
+    const resolved = this.resolveFrameResources(frame);
+    if (!resolved.ok) return resolved;
+
+    for (const [executionIndex, pass] of this.passes.entries()) {
+      const resolver = this.createPassResolver(pass, resolved.value);
+      try {
+        if (pass.pass.descriptor.executeIf?.(frame) === false) continue;
+        let encodeResult: Result<void, RenderGraphError> = ok(undefined);
+        const encode = () => {
+          switch (pass.pass.kind) {
+            case 'raster': {
+              const descriptor = pass.pass.descriptor;
+              const colorAttachments: RenderPassColorAttachment[] = [];
+              for (const attachment of descriptor.colorAttachments) {
+                const view = resolver.textureView(attachment.view);
+                if (!view.ok) {
+                  encodeResult = view;
+                  return;
+                }
+                const resolveTarget =
+                  attachment.resolveTarget === undefined
+                    ? undefined
+                    : resolver.textureView(attachment.resolveTarget);
+                if (resolveTarget !== undefined && !resolveTarget.ok) {
+                  encodeResult = resolveTarget;
+                  return;
+                }
+                const clearValue =
+                  typeof attachment.clearValue === 'function'
+                    ? attachment.clearValue(frame)
+                    : attachment.clearValue;
+                colorAttachments.push({
+                  view: view.value,
+                  ...(resolveTarget === undefined ? {} : { resolveTarget: resolveTarget.value }),
+                  ...(clearValue === undefined ? {} : { clearValue }),
+                  loadOp: attachment.loadOp,
+                  storeOp: attachment.storeOp,
+                  ...(attachment.depthSlice === undefined
+                    ? {}
+                    : { depthSlice: attachment.depthSlice }),
+                });
+              }
+              let depthStencilAttachment: RenderPassDepthStencilAttachment | undefined;
+              if (descriptor.depthStencilAttachment !== undefined) {
+                const attachment = descriptor.depthStencilAttachment;
+                const view = resolver.textureView(attachment.view);
+                if (!view.ok) {
+                  encodeResult = view;
+                  return;
+                }
+                depthStencilAttachment = {
+                  view: view.value,
+                  ...(attachment.depthClearValue === undefined
+                    ? {}
+                    : { depthClearValue: attachment.depthClearValue }),
+                  ...(attachment.depthLoadOp === undefined
+                    ? {}
+                    : { depthLoadOp: attachment.depthLoadOp }),
+                  ...(attachment.depthStoreOp === undefined
+                    ? {}
+                    : { depthStoreOp: attachment.depthStoreOp }),
+                  ...(attachment.depthReadOnly === undefined
+                    ? {}
+                    : { depthReadOnly: attachment.depthReadOnly }),
+                  ...(attachment.stencilClearValue === undefined
+                    ? {}
+                    : { stencilClearValue: attachment.stencilClearValue }),
+                  ...(attachment.stencilLoadOp === undefined
+                    ? {}
+                    : { stencilLoadOp: attachment.stencilLoadOp }),
+                  ...(attachment.stencilStoreOp === undefined
+                    ? {}
+                    : { stencilStoreOp: attachment.stencilStoreOp }),
+                  ...(attachment.stencilReadOnly === undefined
+                    ? {}
+                    : { stencilReadOnly: attachment.stencilReadOnly }),
+                };
+              }
+              const encoder = frame.encoder.beginRenderPass({
+                label: pass.name,
+                colorAttachments,
+                ...(depthStencilAttachment === undefined ? {} : { depthStencilAttachment }),
+              });
+              try {
+                descriptor.encode({ pass: encoder, frame, resources: resolver });
+              } finally {
+                encoder.end();
+              }
+              break;
+            }
+            case 'compute': {
+              const begin = pass.pass.descriptor.begin?.(frame);
+              let encoder: RhiComputePassEncoder;
+              try {
+                encoder = frame.encoder.beginComputePass({ ...(begin ?? {}), label: pass.name });
+              } catch (cause) {
+                pass.pass.descriptor.onBeginError?.(frame, cause);
+                throw cause;
+              }
+              try {
+                pass.pass.descriptor.encode({ pass: encoder, frame, resources: resolver });
+              } finally {
+                encoder.end();
+              }
+              pass.pass.descriptor.after?.(frame);
+              break;
+            }
+            case 'copy':
+              pass.pass.descriptor.encode({ encoder: frame.encoder, frame, resources: resolver });
+              break;
+          }
+        };
+        if (runPass === undefined) {
+          encode();
+        } else {
+          runPass({ name: pass.name, kind: pass.pass.kind, executionIndex }, encode);
+        }
+        if (!encodeResult.ok) return encodeResult;
+      } catch (cause) {
+        return err(
+          new RenderGraphError({
+            code: 'pass-encode-failed',
+            expected: `pass '${pass.name}' encodes without throwing`,
+            hint: 'inspect detail.cause and repair the pass-owned RHI command',
+            detail: { passName: pass.name, passKind: pass.pass.kind, cause },
+          }),
+        );
+      }
+    }
+    return ok(undefined);
+  }
+
+  retire(): Promise<Result<void, RenderGraphError>> {
+    if (this.retireResult !== undefined) return this.retireResult;
+    this.retired = true;
+    this.retireResult = this.finishRetire();
+    return this.retireResult;
+  }
+
+  private async finishRetire(): Promise<Result<void, RenderGraphError>> {
+    try {
+      await this.device.queue.onSubmittedWorkDone();
+    } catch (cause) {
+      return err(
+        new RenderGraphError({
+          code: 'resource-retire-failed',
+          expected: 'the GPU submission fence resolves before graph resources retire',
+          hint: 'recover the device before retiring the replacement generation',
+          detail: { generation: this.generation, cause },
+        }),
+      );
+    }
+
+    let firstFailure: RenderGraphError | undefined;
+    for (const compiled of this.resources.values()) {
+      if (compiled.record.origin === 'imported') continue;
+      if (compiled.texture === undefined && compiled.buffer === undefined) continue;
+      try {
+        const destroyed =
+          compiled.record.kind === 'texture'
+            ? this.device.destroyTexture(compiled.texture as Texture)
+            : this.device.destroyBuffer(compiled.buffer as Buffer);
+        if (!destroyed.ok && firstFailure === undefined) {
+          firstFailure = new RenderGraphError({
+            code: 'resource-retire-failed',
+            expected: `graph-created resource '${compiled.record.label}' retires exactly once`,
+            hint: 'inspect detail.cause for the RHI destroy refusal',
+            detail: {
+              generation: this.generation,
+              resourceLabel: compiled.record.label,
+              cause: destroyed.error,
+            },
+          });
+        }
+      } catch (cause) {
+        firstFailure ??= new RenderGraphError({
+          code: 'resource-retire-failed',
+          expected: `graph-created resource '${compiled.record.label}' retires exactly once`,
+          hint: 'inspect detail.cause for the RHI destroy failure',
+          detail: { generation: this.generation, resourceLabel: compiled.record.label, cause },
+        });
+      }
+    }
+    return firstFailure === undefined ? ok(undefined) : err(firstFailure);
+  }
+
+  private resolveFrameResources(frame: FrameCtx): Result<FrameResources, RenderGraphError> {
+    const buffers = new Map<number, Buffer>();
+    const textures = new Map<number, Texture>();
+    const views = new Map<number, TextureView>();
+
+    for (const compiled of this.resources.values()) {
+      if (compiled.usage === 0) continue;
+      try {
+        if (compiled.record.kind === 'texture') {
+          const texture =
+            compiled.record.origin === 'created'
+              ? compiled.texture
+              : compiled.record.resolve(frame);
+          if (texture === undefined) return err(resolutionError(compiled.record.label));
+          textures.set(compiled.record.id, texture);
+        } else {
+          const buffer =
+            compiled.record.origin === 'created' ? compiled.buffer : compiled.record.resolve(frame);
+          if (buffer === undefined) return err(resolutionError(compiled.record.label));
+          buffers.set(compiled.record.id, buffer);
+        }
+      } catch (cause) {
+        return err(resolutionError(compiled.record.label, cause));
+      }
+    }
+
+    for (const compiledView of this.views.values()) {
+      if (this.resources.get(compiledView.record.textureId)?.usage === 0) continue;
+      if (compiledView.record.resolve !== undefined) {
+        try {
+          views.set(compiledView.record.id, compiledView.record.resolve(frame));
+        } catch (cause) {
+          return err(resolutionError(compiledView.record.label, cause));
+        }
+        continue;
+      }
+      if (compiledView.view !== undefined) {
+        views.set(compiledView.record.id, compiledView.view);
+        continue;
+      }
+      const texture = textures.get(compiledView.record.textureId);
+      if (texture === undefined) return err(resolutionError(compiledView.record.label));
+      const created = this.device.createTextureView(texture, compiledView.record.descriptor);
+      if (!created.ok) return err(resolutionError(compiledView.record.label, created.error));
+      views.set(compiledView.record.id, created.value);
+    }
+    return ok({ buffers, textures, views });
+  }
+
+  private createPassResolver(
+    pass: CompiledPass<FrameCtx>,
+    frameResources: FrameResources,
+  ): GraphResourceResolver {
+    const lookup = (
+      resource: GraphBuffer | GraphTexture | GraphTextureView,
+      expectedKind: ResourceHandleData['kind'],
+    ): Result<ResourceHandleData, RenderGraphError> => {
+      const data = handleData(resource);
+      const resourceId = data?.kind === 'texture-view' ? data.textureId : data?.id;
+      if (data === undefined || data.owner !== this.owner || data.kind !== expectedKind) {
+        return err(
+          new RenderGraphError({
+            code: 'foreign-resource-handle',
+            expected: `pass '${pass.name}' resolves a handle owned by this compiled graph`,
+            hint: 'use only handles created by the builder that declared this pass',
+            detail: { passName: pass.name },
+          }),
+        );
+      }
+      if (resourceId === undefined || !pass.resourceIds.has(resourceId)) {
+        const label = this.resources.get(resourceId ?? -1)?.record.label;
+        return err(
+          new RenderGraphError({
+            code: 'resource-not-declared-by-pass',
+            expected: `pass '${pass.name}' resolves only resources present in its accesses`,
+            hint: 'add the resource access to this pass before resolving it',
+            detail: { passName: pass.name, resourceLabel: label },
+          }),
+        );
+      }
+      if (data.kind === 'texture-view' && !pass.viewIds.has(data.id)) {
+        const label = this.views.get(data.id)?.record.label;
+        return err(
+          new RenderGraphError({
+            code: 'resource-not-declared-by-pass',
+            expected: `pass '${pass.name}' resolves only texture views present in its accesses`,
+            hint: 'add this exact texture view to the pass accesses',
+            detail: { passName: pass.name, resourceLabel: label },
+          }),
+        );
+      }
+      return ok(data);
+    };
+
+    return {
+      buffer: (resource) => {
+        const data = lookup(resource, 'buffer');
+        if (!data.ok) return data;
+        const buffer = frameResources.buffers.get(data.value.id);
+        return buffer === undefined
+          ? err(resolutionError(this.resources.get(data.value.id)?.record.label ?? 'buffer'))
+          : ok(buffer);
+      },
+      texture: (resource) => {
+        const data = lookup(resource, 'texture');
+        if (!data.ok) return data;
+        const texture = frameResources.textures.get(data.value.id);
+        return texture === undefined
+          ? err(resolutionError(this.resources.get(data.value.id)?.record.label ?? 'texture'))
+          : ok(texture);
+      },
+      textureView: (resource) => {
+        const data = lookup(resource, 'texture-view');
+        if (!data.ok) return data;
+        const view = frameResources.views.get(data.value.id);
+        return view === undefined
+          ? err(resolutionError(this.views.get(data.value.id)?.record.label ?? 'texture view'))
+          : ok(view);
+      },
+    };
+  }
+}

package/src/errors.ts

@@ -0,0 +1,205 @@
+// @forgeax/engine-render-graph/src/errors.ts — RenderGraphError closed-union
+// error model + Result<T, E>.
+//
+// Shape (plan-strategy D-3):
+// - RenderGraphErrorCode, RenderGraphErrorDetail, and the constructor argument
+//   union derive from one private code-to-detail map.
+// - RenderGraphError extends Error { readonly code; readonly expected;
+//   readonly hint; readonly detail } — four-field structured error surface,
+//   aligned with RhiError (research Finding 8).
+// - RenderGraphErrorDetail is projected from that map; the
+//   constructor arguments correlate each code with its accepted detail:
+//   - 'dangling-read' / 'unknown-resource' -> { resourceKey, passName }
+//   - 'cap-missing' -> { cap, passName }
+//   - 'duplicate-resource' -> { resourceKey }
+//   - 'alias-source-missing' -> { aliasKey, sourceKey }
+// - Result<T, E=RenderGraphError> = binary tag union ('ok' / 'err') +
+//   ok() / err() factories, aligned with RhiError Result (research Finding 8).
+//
+// Related: plan-strategy D-3; research Finding 8; AC-15.
+
+/**
+ * Private code-to-detail authority for the complete RenderGraphError surface.
+ *
+ * The two resource-key errors intentionally share DanglingReadDetail. Keeping
+ * that fact in this map lets the public code and detail unions, plus the
+ * constructor arguments, derive from one authority without
+ * exporting a framework or runtime registry.
+ */
+interface RenderGraphErrorDetailByCode {
+  'dangling-read': DanglingReadDetail;
+  'cap-missing': CapMissingDetail;
+  'duplicate-resource': DuplicateResourceDetail;
+  'alias-source-missing': AliasSourceDetail;
+  'unknown-resource': DanglingReadDetail;
+  'resource-alloc-failed': ResourceAllocFailedDetail;
+  'invalid-format': InvalidFormatDetail;
+  'observation-absent': ObservationDetail;
+  'observation-invalid-format': ObservationDetail;
+  'observation-invalid-size': ObservationDetail;
+  'observation-missing-copy-src': ObservationDetail;
+  'observation-stale': ObservationDetail;
+  'observation-retired': ObservationDetail;
+  'invalid-color-domain': ColorDomainDetail;
+  'missing-color-domain': ColorDomainDetail;
+  'color-domain-mismatch': ColorDomainDetail;
+  'duplicate-pass-name': DeclarationDetail;
+  'duplicate-resource-label': DeclarationDetail;
+  'builder-sealed': DeclarationDetail;
+  'foreign-resource-handle': ResourceAccessDetail;
+  'resource-not-declared-by-pass': ResourceAccessDetail;
+  'uninitialized-read': ResourceAccessDetail;
+  'access-conflict': ResourceAccessDetail;
+  'capability-missing': CapabilityDetail;
+  'resource-descriptor-invalid': DescriptorDetail;
+  'import-usage-mismatch': DescriptorDetail;
+  'resource-allocation-failed': ResourceAllocFailedDetail;
+  'resource-resolution-failed': ResourceAccessDetail;
+  'pass-encode-failed': PassFailureDetail;
+  'compiled-graph-retired': LifecycleDetail;
+  'resource-retire-failed': LifecycleDetail;
+}
+
+/** Closed RenderGraphErrorCode union derived from the private detail map. */
+export type RenderGraphErrorCode = keyof RenderGraphErrorDetailByCode;
+
+/** Detail union projected from the private code-to-detail map. */
+export type RenderGraphErrorDetail = RenderGraphErrorDetailByCode[RenderGraphErrorCode];
+
+/**
+ * Constructor arguments correlated by code. `detail` remains optional to
+ * preserve the existing envelope behavior for callers that only need the
+ * top-level fields.
+ */
+type RenderGraphErrorConstructorArgs = {
+  [Code in RenderGraphErrorCode]: {
+    code: Code;
+    expected: string;
+    hint: string;
+    detail?: RenderGraphErrorDetailByCode[Code] | undefined;
+  };
+}[RenderGraphErrorCode];
+
+/** Detail variant for dangling-read and unknown-resource errors. */
+export interface DanglingReadDetail {
+  readonly resourceKey: string;
+  readonly passName: string;
+}
+
+/** Detail variant for cap-missing errors. */
+export interface CapMissingDetail {
+  readonly cap: 'compute' | 'storageBuffer';
+  readonly passName: string;
+}
+
+/** Detail variant for duplicate-resource errors. */
+export interface DuplicateResourceDetail {
+  readonly resourceKey: string;
+}
+
+/** Detail variant for aliases whose source is not a registered color target. */
+export interface AliasSourceDetail {
+  readonly aliasKey: string;
+  readonly sourceKey: string;
+}
+
+/** Detail variant for resource-alloc-failed errors. */
+export interface ResourceAllocFailedDetail {
+  readonly resourceKey: string;
+  readonly passName?: string | undefined;
+  readonly rhiCode?: string | undefined;
+}
+
+/** Detail variant for invalid-format errors. */
+export interface InvalidFormatDetail {
+  readonly resourceKey: string;
+  readonly format: string;
+  readonly expected: readonly string[];
+}
+
+/** Generic current-frame observation failures. */
+export interface ObservationDetail {
+  readonly frameId?: number | undefined;
+  readonly expected?: string | undefined;
+}
+
+export interface ColorDomainDetail {
+  readonly value?: string | undefined;
+  readonly resourceKey?: string | undefined;
+  readonly sourceDomain?: string | undefined;
+  readonly destinationDomain?: string | undefined;
+}
+
+export interface DeclarationDetail {
+  readonly passName?: string | undefined;
+  readonly resourceLabel?: string | undefined;
+}
+
+export interface ResourceAccessDetail {
+  readonly passName?: string | undefined;
+  readonly resourceLabel?: string | undefined;
+  readonly usage?: string | undefined;
+  readonly accesses?: readonly string[] | undefined;
+}
+
+export interface CapabilityDetail extends ResourceAccessDetail {
+  readonly capability: 'compute' | 'storage-buffer' | 'storage-texture' | 'indirect';
+}
+
+export interface DescriptorDetail {
+  readonly resourceLabel: string;
+  readonly field: string;
+  readonly expected: string;
+  readonly actual?: string | number | undefined;
+}
+
+export interface PassFailureDetail {
+  readonly passName: string;
+  readonly passKind: 'raster' | 'compute' | 'copy';
+  readonly cause: unknown;
+}
+
+export interface LifecycleDetail {
+  readonly generation: number;
+  readonly resourceLabel?: string | undefined;
+  readonly cause?: unknown;
+}
+
+/**
+ * Structured RenderGraph error.
+ *
+ * Four readonly fields aligned with AGENTS.md "Errors are structured"
+ * and RhiError (research Finding 8):
+ * - `.code` — closed union member (L1 key signal).
+ * - `.expected` — expected-state description (L2 detail).
+ * - `.hint` — actionable recovery guidance (L2 detail).
+ * - `.detail` — narrowed payload per code variant.
+ */
+export class RenderGraphError extends Error {
+  readonly code: RenderGraphErrorCode;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: RenderGraphErrorDetail | undefined;
+
+  constructor(args: RenderGraphErrorConstructorArgs) {
+    super(`[RenderGraphError ${args.code}] expected: ${args.expected}; hint: ${args.hint}`);
+    this.name = 'RenderGraphError';
+    this.code = args.code;
+    this.expected = args.expected;
+    this.hint = args.hint;
+    this.detail = args.detail;
+  }
+}
+
+// Result<T, E> + ok / err + ResultOk / ResultErr live in `@forgeax/engine-types`
+// (tweak-20260612-result-into-types). Consolidated upstream from this and 4
+// other packages' duplicate definitions; the barrel here re-exports them so
+// existing `import { err, ok, Result } from '@forgeax/engine-render-graph'`
+// consumers stay unchanged.
+export {
+  err,
+  ok,
+  type Result,
+  type ResultErr,
+  type ResultOk,
+} from '@forgeax/engine-types';