@forgeax/engine-render 0.1.2

package/src/__tests__/render-feature-retry.unit.test.ts

@@ -0,0 +1,128 @@
+import type { RhiCaps } from '@forgeax/engine-rhi';
+import { err, ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { RenderFeatureStageFailedError } from '../errors/render';
+import { createRenderFeatureHost, runRenderFeatureFrame } from '../features/host';
+import type { RenderFeature, RenderFeatureResourceHandle } from '../features/types';
+
+const caps = (compute: boolean): Readonly<RhiCaps> => ({ compute }) as unknown as RhiCaps;
+
+describe('render feature retry rules', () => {
+  it('retries ordinary failures on the next frame and keeps latest error structured', () => {
+    let attempts = 0;
+    const feature: RenderFeature<{ readonly frame: number }> = {
+      identity: 'synthetic.retry',
+      extract: ({ frameNumber }) => ok({ frame: frameNumber }),
+      prepare: () => {
+        attempts += 1;
+        if (attempts === 1) {
+          return err(
+            new RenderFeatureStageFailedError('synthetic.retry', 0, 'prepare', 'next-frame'),
+          );
+        }
+        return ok(undefined);
+      },
+      contribute: () => ok(undefined),
+    };
+    const host = createRenderFeatureHost([feature], caps(true)).unwrap();
+
+    const failed = runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 1,
+      caps: caps(true),
+    });
+    const error = failed.errors[0];
+    expect(error?.code).toBe('render-feature-stage-failed');
+    if (error?.code === 'render-feature-stage-failed') {
+      expect(error.detail).toMatchObject({
+        featureIdentity: 'synthetic.retry',
+        stage: 'prepare',
+        recovery: 'next-frame',
+      });
+    }
+
+    const retried = runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 2,
+      caps: caps(true),
+    });
+    expect(retried.errors).toEqual([]);
+    expect(host.diagnostics()[0]?.latestError).toBeUndefined();
+    expect(host.diagnostics()[0]?.status).toBe('active');
+  });
+
+  it('does not retry a disabled feature until recover makes its capability available', () => {
+    const feature: RenderFeature<{ readonly frame: number }> = {
+      identity: 'synthetic.capability-retry',
+      requiredCapabilities: ['compute'],
+      extract: ({ frameNumber }) => ok({ frame: frameNumber }),
+      prepare: () => ok(undefined),
+      contribute: () => ok(undefined),
+    };
+    const host = createRenderFeatureHost([feature], caps(false)).unwrap();
+
+    runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 1,
+      caps: caps(false),
+    });
+    expect(
+      runRenderFeatureFrame(host, {
+        worlds: [],
+        owner: 0,
+        frameNumber: 2,
+        caps: caps(true),
+      }).stageEvents,
+    ).toEqual([]);
+
+    expect(host.recover({ frameNumber: 3, caps: caps(true) })).toEqual(ok(undefined));
+    expect(
+      runRenderFeatureFrame(host, {
+        worlds: [],
+        owner: 0,
+        frameNumber: 3,
+        caps: caps(true),
+      }).stageEvents,
+    ).toHaveLength(3);
+  });
+
+  it('does not release a feature-owned resource during retry or diagnostics', () => {
+    let releaseCount = 0;
+    const feature: RenderFeature<{ readonly frame: number }> = {
+      identity: 'synthetic.release-once',
+      extract: ({ frameNumber }) => ok({ frame: frameNumber }),
+      prepare: () => ok(undefined),
+      contribute: () => ok(undefined),
+    };
+    const host = createRenderFeatureHost([feature], caps(true)).unwrap();
+    host.registerResource('synthetic.release-once', {
+      handle: { __renderFeatureResource: Symbol('release-once') } as RenderFeatureResourceHandle,
+      release: () => {
+        releaseCount += 1;
+        return ok(undefined);
+      },
+    });
+
+    runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 1,
+      caps: caps(true),
+    });
+    host.diagnostics();
+    host.diagnostics();
+    runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 2,
+      caps: caps(true),
+    });
+    expect(releaseCount).toBe(0);
+    expect(host.dispose()).toEqual(ok(undefined));
+    expect(host.dispose()).toEqual(ok(undefined));
+    expect(releaseCount).toBe(1);
+  });
+});

package/src/__tests__/render-feature-scheduling.unit.test.ts

@@ -0,0 +1,122 @@
+import type { RhiCaps } from '@forgeax/engine-rhi';
+import { err, ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { RenderFeatureStageFailedError } from '../errors/render';
+import { createRenderFeatureHost, runRenderFeatureFrame } from '../features/host';
+import type { RenderFeature } from '../features/types';
+
+const caps = {
+  backendKind: 'null',
+  compute: true,
+  timestampQuery: true,
+  timestampPeriodNanoseconds: null,
+  indirectDrawing: true,
+  textureCompressionBc: false,
+  textureCompressionEtc2: false,
+  textureCompressionAstc: false,
+  multiDrawIndirect: false,
+  pushConstants: false,
+  textureBindingArray: false,
+  samplerAliasing: true,
+  firstInstanceIndirect: true,
+  storageBuffer: true,
+  storageTexture: true,
+  rgba16floatRenderable: true,
+  rg11b10ufloatRenderable: true,
+  float32Filterable: true,
+  maxColorAttachments: 8,
+} satisfies RhiCaps;
+
+function feature(
+  identity: string,
+  events: string[],
+  failStage?: 'extract' | 'prepare' | 'contribute',
+) {
+  const value = { identity };
+  return {
+    identity,
+    extract: () => {
+      events.push(`${identity}:extract`);
+      return failStage === 'extract'
+        ? err(new RenderFeatureStageFailedError(identity, 0, 'extract', 'next-frame'))
+        : ok(value);
+    },
+    prepare: () => {
+      events.push(`${identity}:prepare`);
+      return failStage === 'prepare'
+        ? err(new RenderFeatureStageFailedError(identity, 0, 'prepare', 'next-frame'))
+        : ok(undefined);
+    },
+    contribute: () => {
+      events.push(`${identity}:contribute`);
+      return failStage === 'contribute'
+        ? err(new RenderFeatureStageFailedError(identity, 0, 'contribute', 'next-frame'))
+        : ok(undefined);
+    },
+  } satisfies RenderFeature<typeof value>;
+}
+
+describe('render feature stage scheduling', () => {
+  it('runs each feature once in registration and stage order', () => {
+    const events: string[] = [];
+    const host = createRenderFeatureHost([
+      feature('synthetic.first', events),
+      feature('synthetic.second', events),
+    ]).unwrap();
+
+    const result = runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 7,
+      caps,
+    });
+
+    expect(result.events).toEqual([
+      'synthetic.first:extract',
+      'synthetic.first:prepare',
+      'synthetic.first:contribute',
+      'synthetic.second:extract',
+      'synthetic.second:prepare',
+      'synthetic.second:contribute',
+    ]);
+  });
+
+  it.each([
+    'extract',
+    'prepare',
+    'contribute',
+  ] as const)('isolates a %s failure from the healthy feature', (failStage) => {
+    const events: string[] = [];
+    const host = createRenderFeatureHost([
+      feature('synthetic.failed', events, failStage),
+      feature('synthetic.healthy', events),
+    ]).unwrap();
+
+    const result = runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 8,
+      caps,
+    });
+
+    expect(result.errors).toHaveLength(1);
+    const error = result.errors[0];
+    expect(error?.code).toBe('render-feature-stage-failed');
+    if (error?.code === 'render-feature-stage-failed') {
+      expect(error.detail).toMatchObject({
+        featureIdentity: 'synthetic.failed',
+        stage: failStage,
+      });
+    }
+    expect(events).toContain('synthetic.healthy:extract');
+    expect(events).toContain('synthetic.healthy:prepare');
+    expect(events).toContain('synthetic.healthy:contribute');
+    const failedEvents = events.filter((event) => event.startsWith('synthetic.failed:'));
+    const failedStageIndex = ['extract', 'prepare', 'contribute'].indexOf(failStage);
+    expect(failedEvents).toEqual(
+      ['extract', 'prepare', 'contribute']
+        .slice(0, failedStageIndex + 1)
+        .map((stage) => `synthetic.failed:${stage}`),
+    );
+  });
+});

package/src/__tests__/render-feature-stage-failed-policy-owner.unit.test.ts

@@ -0,0 +1,146 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import { type RenderError, RenderFeatureStageFailedError } from '../errors/render';
+import type {
+  RenderFeatureErrorDescriptor,
+  RenderFeatureRecovery,
+  RenderFeatureStage,
+  RenderFeatureStageFailedDetail,
+} from '../features/types';
+import { RenderFeatureStageFailedError as PublicRenderFeatureStageFailedError } from '../index';
+import { RenderFeatureStageFailedError as InternalRenderFeatureStageFailedError } from '../internal';
+
+const evidence = [
+  {
+    featureIdentity: 'synthetic.next-frame',
+    order: 3,
+    stage: 'prepare',
+    recovery: 'next-frame',
+    expected: "feature 'synthetic.next-frame' completes its prepare stage without an error",
+    hint: "correct 'synthetic.next-frame' prepare data and retry on the next frame",
+    message: "render feature 'synthetic.next-frame' failed during prepare",
+  },
+  {
+    featureIdentity: 'synthetic.renderer-recover',
+    order: 4,
+    stage: 'record',
+    recovery: 'renderer-recover',
+    expected: "feature 'synthetic.renderer-recover' completes its record stage without an error",
+    hint: "wait for renderer recovery before retrying 'synthetic.renderer-recover'",
+    message: "render feature 'synthetic.renderer-recover' failed during record",
+  },
+  {
+    featureIdentity: 'synthetic.registration',
+    order: 5,
+    stage: 'recover',
+    recovery: 'registration',
+    expected: "feature 'synthetic.registration' completes its recover stage without an error",
+    hint: "correct 'synthetic.registration' registration before retrying",
+    message: "render feature 'synthetic.registration' failed during recover",
+  },
+] as const satisfies readonly {
+  readonly featureIdentity: string;
+  readonly order: number;
+  readonly stage: RenderFeatureStage;
+  readonly recovery: RenderFeatureRecovery;
+  readonly expected: string;
+  readonly hint: string;
+  readonly message: string;
+}[];
+
+describe('RenderFeatureStageFailedError policy ownership', () => {
+  it('keeps one owner for direct, public, and internal constructors', () => {
+    expect(PublicRenderFeatureStageFailedError).toBe(RenderFeatureStageFailedError);
+    expect(InternalRenderFeatureStageFailedError).toBe(RenderFeatureStageFailedError);
+  });
+
+  it('preserves every recovery diagnostic and its type correlation', () => {
+    expect(evidence.map(({ recovery }) => recovery)).toEqual([
+      'next-frame',
+      'renderer-recover',
+      'registration',
+    ]);
+    expect(new Set(evidence.map(({ recovery }) => recovery)).size).toBe(3);
+
+    for (const row of evidence) {
+      const error = new RenderFeatureStageFailedError(
+        row.featureIdentity,
+        row.order,
+        row.stage,
+        row.recovery,
+      );
+
+      expectTypeOf(error).toEqualTypeOf<
+        Extract<RenderError, { readonly code: 'render-feature-stage-failed' }>
+      >();
+      expectTypeOf(error.detail).toEqualTypeOf<RenderFeatureStageFailedDetail>();
+      expectTypeOf(error.detail.recovery).toEqualTypeOf<RenderFeatureRecovery>();
+      expectTypeOf<
+        Extract<RenderFeatureErrorDescriptor, { readonly code: 'render-feature-stage-failed' }>
+      >().toMatchTypeOf<{
+        readonly code: 'render-feature-stage-failed';
+        readonly expected: string;
+        readonly hint: string;
+        readonly detail: RenderFeatureStageFailedDetail;
+      }>();
+
+      expect(error.code).toBe('render-feature-stage-failed');
+      expect(error.expected).toBe(row.expected);
+      expect(error.hint).toBe(row.hint);
+      expect(error.message).toBe(row.message);
+      expect(error.detail).toEqual({
+        featureIdentity: row.featureIdentity,
+        order: row.order,
+        stage: row.stage,
+        recovery: row.recovery,
+      });
+    }
+  });
+
+  it('preserves Error identity, stack, own-key order, and descriptors', () => {
+    const error = new RenderFeatureStageFailedError(
+      'synthetic.descriptors',
+      6,
+      'dispose',
+      'renderer-recover',
+    );
+
+    expect(error).toBeInstanceOf(Error);
+    expect(error).toBeInstanceOf(RenderFeatureStageFailedError);
+    expect(error).toBeInstanceOf(PublicRenderFeatureStageFailedError);
+    expect(error).toBeInstanceOf(InternalRenderFeatureStageFailedError);
+    expect(error.name).toBe('RenderFeatureStageFailedError');
+    expect(typeof error.stack).toBe('string');
+    expect(error.stack).toContain(`RenderFeatureStageFailedError: ${error.message}`);
+    expect(Object.keys(error)).toEqual(['code', 'expected', 'hint', 'detail', 'name']);
+    expect(Object.getOwnPropertyNames(error)).toEqual([
+      'stack',
+      'message',
+      'code',
+      'expected',
+      'hint',
+      'detail',
+      'name',
+    ]);
+
+    const descriptors = Object.getOwnPropertyDescriptors(error);
+    for (const field of ['code', 'expected', 'hint', 'detail', 'name'] as const) {
+      expect(descriptors[field]).toEqual({
+        value: error[field],
+        writable: true,
+        enumerable: true,
+        configurable: true,
+      });
+    }
+    expect(descriptors.message).toMatchObject({
+      configurable: true,
+      enumerable: false,
+      writable: true,
+    });
+    expect(descriptors.stack).toMatchObject({
+      configurable: true,
+      enumerable: false,
+    });
+    expect(typeof descriptors.stack?.get).toBe('function');
+    expect(typeof descriptors.stack?.set).toBe('function');
+  });
+});

package/src/__tests__/render-feature-stage-fault-recovery.unit.test.ts

@@ -0,0 +1,236 @@
+import type { RhiCaps, RhiDevice } from '@forgeax/engine-rhi';
+import { err, ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import {
+  type RenderError,
+  RenderFeatureDrawRecordingFailedError,
+  RenderFeaturePreparationFailedError,
+  RenderFeatureStageFailedError,
+} from '../errors/render';
+import {
+  createRenderFeatureHost,
+  type RenderFeatureHost,
+  runRenderFeatureFrame,
+} from '../features/host';
+import type { RenderFeature } from '../features/types';
+import { createPreparedGraphicsResolver } from '../prepare/prepared-graphics-resolver';
+import { recordResolvedRenderFeatureGraphicsPass } from '../record/frame-targets';
+
+const caps = { backendKind: 'null' } as unknown as Readonly<RhiCaps>;
+
+type Fault = 'create' | 'prepared-resource' | 'draw-recording';
+
+function healthyFeature(probe: { prepare: number; contribute: number }): RenderFeature<{
+  readonly ready: true;
+}> {
+  return {
+    identity: 'synthetic.m10.healthy',
+    extract: () => ok({ ready: true }),
+    prepare: () => {
+      probe.prepare += 1;
+      return ok(undefined);
+    },
+    contribute: (_data, context) => {
+      probe.contribute += 1;
+      context.staging.addResource('target', { kind: 'texture', lifetime: 'transient' });
+      return context.staging.addPass('pass', { reads: [], writes: ['target'] });
+    },
+  };
+}
+
+function faultyFeature(
+  fault: Fault,
+  probe: { prepare: number; contribute: number },
+): { readonly feature: RenderFeature<{ readonly ready: true }>; readonly repair: () => void } {
+  let repaired = false;
+  const identity = `synthetic.m10.${fault}`;
+  const failure = (): RenderError => {
+    switch (fault) {
+      case 'create':
+        return new RenderFeatureStageFailedError(identity, 1, 'prepare', 'next-frame');
+      case 'prepared-resource':
+        return new RenderFeaturePreparationFailedError(
+          identity,
+          1,
+          'prepareVertexData',
+          'vertex-data',
+          `${identity}::triangle`,
+          'backend-upload-failed',
+          'next-frame',
+        );
+      case 'draw-recording':
+        return new RenderFeatureDrawRecordingFailedError(
+          identity,
+          1,
+          'recordDraw',
+          'vertex-data',
+          'backend-recording-failed',
+          'synthetic backend rejected setVertexBuffer',
+          'next-frame',
+        );
+    }
+  };
+  return {
+    feature: {
+      identity,
+      extract: () => ok({ ready: true }),
+      prepare: () => {
+        probe.prepare += 1;
+        if (!repaired && fault !== 'draw-recording') return err(failure());
+        return ok(undefined);
+      },
+      contribute: (_data, context) => {
+        probe.contribute += 1;
+        if (!repaired && fault === 'draw-recording') return err(failure());
+        context.staging.addResource('target', { kind: 'texture', lifetime: 'transient' });
+        return context.staging.addPass('pass', { reads: [], writes: ['target'] });
+      },
+    },
+    repair: () => {
+      repaired = true;
+    },
+  };
+}
+
+function frame(host: RenderFeatureHost, frameNumber: number) {
+  return runRenderFeatureFrame(host, {
+    worlds: [],
+    owner: 0,
+    frameNumber,
+    caps,
+  });
+}
+
+describe('RenderFeature stage fault recovery lifecycle', () => {
+  it.each<Fault>([
+    'create',
+    'prepared-resource',
+    'draw-recording',
+  ])('keeps a healthy sibling visible and clears feature-local %s diagnostics after repair', (fault) => {
+    const healthyProbe = { prepare: 0, contribute: 0 };
+    const faultyProbe = { prepare: 0, contribute: 0 };
+    const faulty = faultyFeature(fault, faultyProbe);
+    const healthy = healthyFeature(healthyProbe);
+    const host = createRenderFeatureHost([healthy, faulty.feature], caps).unwrap();
+    let releaseCount = 0;
+    host.registerResource(`synthetic.m10.${fault}`, {
+      handle: { __renderFeatureResource: Symbol(fault) } as never,
+      release: () => {
+        releaseCount += 1;
+        return ok(undefined);
+      },
+    });
+
+    const first = frame(host, 1);
+    const firstError = first.errors.find((error) => {
+      switch (error.code) {
+        case 'render-feature-stage-failed':
+        case 'render-feature-preparation-failed':
+        case 'render-feature-draw-recording-failed':
+          return error.detail.featureIdentity.includes(fault);
+        default:
+          return false;
+      }
+    });
+    expect(firstError).toBeDefined();
+    expect(firstError).toMatchObject({
+      code:
+        fault === 'create'
+          ? 'render-feature-stage-failed'
+          : fault === 'prepared-resource'
+            ? 'render-feature-preparation-failed'
+            : 'render-feature-draw-recording-failed',
+      detail: { featureIdentity: `synthetic.m10.${fault}`, order: 1 },
+    });
+    expect(firstError?.hint.length).toBeGreaterThan(0);
+    expect(first.contributions.map((entry) => entry.featureIdentity)).toEqual([
+      'synthetic.m10.healthy',
+    ]);
+    expect(host.diagnostics().map((entry) => entry.status)).toEqual(['active', 'failed']);
+    expect(host.diagnostics()[1]?.latestError).toMatchObject({
+      detail: { featureIdentity: `synthetic.m10.${fault}` },
+    });
+
+    faulty.repair();
+    const second = frame(host, 2);
+    expect(second.errors).toEqual([]);
+    expect(second.contributions.map((entry) => entry.featureIdentity)).toEqual([
+      'synthetic.m10.healthy',
+      `synthetic.m10.${fault}`,
+    ]);
+    expect(host.diagnostics().map((entry) => entry.status)).toEqual(['active', 'active']);
+    expect(host.diagnostics()[1]?.latestError).toBeUndefined();
+    expect(healthyProbe.contribute).toBe(2);
+    expect(faultyProbe.prepare).toBe(2);
+    expect(faultyProbe.contribute).toBe(fault === 'draw-recording' ? 2 : 1);
+
+    expect(host.dispose()).toEqual(ok(undefined));
+    expect(host.dispose()).toEqual(ok(undefined));
+    expect(releaseCount).toBe(1);
+    expect(host.diagnostics().map((entry) => entry.status)).toEqual(['disposed', 'disposed']);
+  });
+
+  it('keeps the owning identity and order on prepared-state and record failures', () => {
+    const resolver = createPreparedGraphicsResolver({
+      device: {} as RhiDevice,
+      featureIdentity: 'synthetic.m10.resolver',
+      generation: 2,
+      capabilityAvailable: true,
+      featureOrder: 7,
+      lookup: () => undefined,
+      resolvePipeline: () => ok({} as never),
+      resolveBindings: () => ok(undefined),
+    });
+    const missing = resolver.resolve({ kind: 'vertex-data', generation: 2 });
+    expect(missing).toMatchObject({
+      ok: false,
+      error: {
+        code: 'render-feature-prepared-state-mismatch',
+        detail: { featureIdentity: 'synthetic.m10.resolver', order: 7 },
+      },
+    });
+
+    const pipeline = { kind: 'pipeline' as const, generation: 0 };
+    const bindings = { kind: 'bindings' as const, generation: 0 };
+    const vertices = { kind: 'vertex-data' as const, generation: 0 };
+    const recorded = recordResolvedRenderFeatureGraphicsPass(
+      'synthetic.m10.record-order',
+      {
+        attachments: {
+          colors: [
+            { resource: 'swapchain', format: 'rgba8unorm', loadOp: 'load', storeOp: 'store' },
+          ],
+        },
+        draws: [
+          {
+            kind: 'draw',
+            pipeline,
+            bindings: [bindings],
+            vertexData: [{ slot: 0, resource: vertices }],
+            command: { vertexCount: 3, instanceCount: 1 },
+          },
+        ],
+      },
+      {
+        capabilityAvailable: true,
+        generation: 0,
+        attachments: [{ resource: 'swapchain', format: 'rgba8unorm' }],
+        pipeline,
+        pipelines: [pipeline],
+        bindings: [bindings],
+        vertexData: [vertices],
+        indexData: [],
+      },
+      { generation: 0, resolve: () => undefined },
+      { pipeline: 0, binding: 0, vertex: 0, index: 0, draw: 0 },
+      4,
+    );
+    expect(recorded).toMatchObject({
+      ok: false,
+      error: {
+        code: 'render-feature-stage-failed',
+        detail: { featureIdentity: 'synthetic.m10.record-order', order: 4, stage: 'record' },
+      },
+    });
+  });
+});