@forgeax/engine-render 0.1.2

package/src/__tests__/pipeline-error-policy-owner.unit.test.ts

@@ -0,0 +1,167 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import {
+  PipelineError,
+  type PipelineErrorCode,
+  type PipelineErrorDetail,
+  type PipelineErrorDetailFor,
+  type PipelineError as PipelineErrorType,
+} from '../pipeline-errors';
+
+const expectedCodes = [
+  'pipeline-already-registered',
+  'pipeline-not-found',
+  'vertex-color-variant-conflict',
+] as const satisfies readonly PipelineErrorCode[];
+type ExpectedCodeUnion = (typeof expectedCodes)[number];
+
+const evidence = [
+  {
+    code: 'pipeline-already-registered',
+    error: new PipelineError({
+      code: 'pipeline-already-registered',
+      detail: { id: 'forgeax::urp' },
+    }),
+    expected: 'each pipeline id is registered at most once',
+    hint: "pipeline id 'forgeax::urp' is already registered; same-id re-register is forbidden. Pick a distinct id (engine builtins use the forgeax:: prefix; user pipelines use <package>::<id>).",
+    message:
+      "pipeline: pipeline-already-registered (pipeline id 'forgeax::urp' is already registered; same-id re-register is forbidden. Pick a distinct id (engine builtins use the forgeax:: prefix; user pipelines use <package>::<id>).)",
+  },
+  {
+    code: 'pipeline-not-found',
+    error: new PipelineError({
+      code: 'pipeline-not-found',
+      detail: { handle: 42 },
+    }),
+    expected: 'installPipeline receives a handle to a registered pipeline',
+    hint: 'no pipeline is registered for handle 42. First registerPipeline(id, impl), then register a RenderPipelineAsset { kind:"render-pipeline", pipelineId: id } and install the returned handle.',
+    message:
+      'pipeline: pipeline-not-found (no pipeline is registered for handle 42. First registerPipeline(id, impl), then register a RenderPipelineAsset { kind:"render-pipeline", pipelineId: id } and install the returned handle.)',
+  },
+  {
+    code: 'vertex-color-variant-conflict',
+    error: new PipelineError({
+      code: 'vertex-color-variant-conflict',
+      detail: {
+        authored: true,
+        authoredValue: 'true',
+        projected: false,
+        variantSet: 'VERTEX_COLOR_AVAILABLE=true',
+      },
+    }),
+    expected: 'geometry projection and material variant agree on VERTEX_COLOR_AVAILABLE',
+    hint: "authored VERTEX_COLOR_AVAILABLE=true conflicts with geometry projection=false in variant set 'VERTEX_COLOR_AVAILABLE=true'. Remove the authored vertex-color axis and let geometry projection derive it.",
+    message:
+      "pipeline: vertex-color-variant-conflict (authored VERTEX_COLOR_AVAILABLE=true conflicts with geometry projection=false in variant set 'VERTEX_COLOR_AVAILABLE=true'. Remove the authored vertex-color axis and let geometry projection derive it.)",
+  },
+] as const;
+
+describe('PipelineError policy ownership', () => {
+  it('preserves the exact closed vocabulary and public type', () => {
+    expect(expectedCodes).toHaveLength(3);
+    expect(new Set(expectedCodes).size).toBe(3);
+    expectTypeOf<PipelineErrorCode>().toEqualTypeOf<ExpectedCodeUnion>();
+    expectTypeOf<ExpectedCodeUnion>().toEqualTypeOf<PipelineErrorCode>();
+
+    const acceptsCode = (code: PipelineErrorCode): PipelineErrorCode => code;
+    expect(acceptsCode(expectedCodes[0])).toBe('pipeline-already-registered');
+    // @ts-expect-error -- policy-derived closed union rejects unknown codes.
+    acceptsCode('pipeline-not-real');
+  });
+
+  it('preserves every expected value, dynamic hint, and message byte-for-byte', () => {
+    for (const { code, error, expected, hint, message } of evidence) {
+      expect(error.code).toBe(code);
+      expect(error.expected).toBe(expected);
+      expect(error.hint).toBe(hint);
+      expect(error.message).toBe(message);
+    }
+
+    const otherId = new PipelineError({
+      code: 'pipeline-already-registered',
+      detail: { id: 'game::custom' },
+    });
+    const otherHandle = new PipelineError({
+      code: 'pipeline-not-found',
+      detail: { handle: 9001 },
+    });
+    expect(otherId.hint).toBe(
+      "pipeline id 'game::custom' is already registered; same-id re-register is forbidden. Pick a distinct id (engine builtins use the forgeax:: prefix; user pipelines use <package>::<id>).",
+    );
+    expect(otherId.message).toBe(`pipeline: pipeline-already-registered (${otherId.hint})`);
+    expect(otherHandle.hint).toBe(
+      'no pipeline is registered for handle 9001. First registerPipeline(id, impl), then register a RenderPipelineAsset { kind:"render-pipeline", pipelineId: id } and install the returned handle.',
+    );
+    expect(otherHandle.message).toBe(`pipeline: pipeline-not-found (${otherHandle.hint})`);
+  });
+
+  it('preserves correlated constructor inference and detail aliases', () => {
+    expectTypeOf<PipelineErrorDetail>().toEqualTypeOf<PipelineErrorDetailFor<PipelineErrorCode>>();
+
+    const previouslyRegistered = new PipelineError({
+      code: 'pipeline-already-registered',
+      detail: { id: 'forgeax::urp' },
+    });
+    expectTypeOf(previouslyRegistered).toEqualTypeOf<
+      Extract<PipelineErrorType, { readonly code: 'pipeline-already-registered' }>
+    >();
+    expectTypeOf(previouslyRegistered.detail).toEqualTypeOf<
+      Extract<PipelineErrorType, { readonly code: 'pipeline-already-registered' }>['detail']
+    >();
+    expectTypeOf(previouslyRegistered.detail.id).toEqualTypeOf<string>();
+
+    const notFound = new PipelineError({
+      code: 'pipeline-not-found',
+      detail: { handle: 42 },
+    });
+    expectTypeOf(notFound).toEqualTypeOf<
+      Extract<PipelineErrorType, { readonly code: 'pipeline-not-found' }>
+    >();
+    expectTypeOf(notFound.detail).toEqualTypeOf<
+      Extract<PipelineErrorType, { readonly code: 'pipeline-not-found' }>['detail']
+    >();
+    expectTypeOf(notFound.detail.handle).toEqualTypeOf<number>();
+  });
+
+  it('preserves Error identity, stack, own-key order, and descriptors', () => {
+    const error = new PipelineError({
+      code: 'pipeline-already-registered',
+      detail: { id: 'forgeax::urp' },
+    });
+
+    expect(error).toBeInstanceOf(Error);
+    expect(error).toBeInstanceOf(PipelineError);
+    expect(error.name).toBe('PipelineError');
+    expect(typeof error.stack).toBe('string');
+    expect(error.stack).toContain(`PipelineError: ${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 ['name', 'code', 'expected', 'hint', 'detail'] as const) {
+      expect(descriptors[field]).toMatchObject({
+        configurable: true,
+        enumerable: true,
+        writable: 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__/pipeline-pass-trace.test.ts

@@ -0,0 +1,92 @@
+import { RenderGraphBuilder } from '@forgeax/engine-render-graph';
+import type { RhiDevice } from '@forgeax/engine-rhi';
+import { rhi } from '@forgeax/engine-rhi-null';
+import { ok } from '@forgeax/engine-types';
+import { beforeAll, describe, expect, it } from 'vitest';
+import { hdrpPipeline } from '../hdrp-pipeline';
+import type { RenderPipelineFrame, RenderPipelineTopology } from '../render-pipeline';
+import { createRenderPipelineTemporalContract } from '../render-pipeline';
+import { urpPipeline } from '../urp-pipeline';
+
+let device: RhiDevice;
+
+beforeAll(async () => {
+  const adapter = await rhi.requestAdapter();
+  if (!adapter.ok) throw adapter.error;
+  const created = await adapter.value.requestDevice();
+  if (!created.ok) throw created.error;
+  device = created.value;
+});
+
+function topology(pipelineId: 'forgeax::urp' | 'forgeax::hdrp'): RenderPipelineTopology {
+  return {
+    pipelineId,
+    config: undefined,
+    surface: {
+      width: 64,
+      height: 64,
+      storageFormat: 'bgra8unorm',
+      viewFormat: 'bgra8unorm-srgb',
+    },
+    camera: { tonemap: 'aces-filmic', antialias: 'fxaa', bloom: 'off' },
+    shadow: {
+      mapSize: 64,
+      cascadeCount: 1,
+      pointCount: 0,
+      pointFaceSize: 64,
+      spotCount: 0,
+    },
+    lane: {
+      compute: true,
+      storageBuffer: true,
+      multisample: false,
+      maxColorAttachments: 8,
+    },
+    featureTopologySignature: 'm4-contract',
+    gpuDrivenTopologySignature: '',
+    environment: { enabled: true, dirty: true },
+  };
+}
+
+describe('analytic environment compiled pass provenance', () => {
+  it.each([
+    ['forgeax::urp', urpPipeline, 'urp'],
+    ['forgeax::hdrp', hdrpPipeline, 'hdrp'],
+  ] as const)('records the %s producer and one background/disc pair', (id, pipeline, lane) => {
+    const input = topology(id);
+    const graph = new RenderGraphBuilder<RenderPipelineFrame>();
+    const temporal = createRenderPipelineTemporalContract({
+      enabled: false,
+      rgba16floatRenderable: true,
+      maxColorAttachments: 8,
+      project: () => ok({ resolvedColor: undefined as never }),
+    });
+    const built = pipeline.build(
+      {
+        graph,
+        environment: { enabled: true, dirty: true },
+        projectGpuDriven: () => ok(undefined),
+        contributeFeatures: () => ok(undefined),
+        resolveTemporal: temporal.resolve,
+      },
+      input,
+    );
+    expect(built.ok).toBe(true);
+    if (!built.ok) return;
+    expect(temporal.finish().ok).toBe(true);
+    const compiled = graph.compile({ device, surfaceSize: { width: 64, height: 64 } });
+    expect(compiled.ok).toBe(true);
+    if (!compiled.ok) return;
+    const names = compiled.value.inspect().passes.map((pass) => pass.name);
+    expect(names.filter((name) => name.startsWith(`${lane}.atmosphere-producer.`))).toHaveLength(
+      42,
+    );
+    expect(names.filter((name) => name.includes('sun-disc'))).toHaveLength(1);
+    expect(names.indexOf(`${lane}.atmosphere-producer.sky.mip-0.face-0`)).toBeGreaterThan(
+      names.indexOf(lane === 'urp' ? 'shadowCascade0' : 'shadowCascade0'),
+    );
+    expect(names.indexOf(`${lane}.sun-disc`)).toBeGreaterThan(
+      names.indexOf(`${lane}.atmosphere-producer.prefilter.mip-4.face-5`),
+    );
+  });
+});

package/src/__tests__/pipeline-stage-owner.test-d.ts

@@ -0,0 +1,13 @@
+import { expectTypeOf, it } from 'vitest';
+
+import type { PipelineStage, pipelineStages } from '../pipeline';
+
+const expectedPipelineStages = ['extract', 'prepare', 'record'] as const;
+type ExpectedPipelineStage = (typeof expectedPipelineStages)[number];
+
+it('derives the pipeline stage union from the ordered tuple owner', () => {
+  expectTypeOf<typeof pipelineStages>().toEqualTypeOf<typeof expectedPipelineStages>();
+  expectTypeOf<typeof expectedPipelineStages>().toEqualTypeOf<typeof pipelineStages>();
+  expectTypeOf<PipelineStage>().toEqualTypeOf<ExpectedPipelineStage>();
+  expectTypeOf<ExpectedPipelineStage>().toEqualTypeOf<PipelineStage>();
+});

package/src/__tests__/plugin.test.ts

@@ -0,0 +1,25 @@
+import { Context } from '@forgeax/engine-plugin';
+import { describe, expect, it, vi } from 'vitest';
+
+import type { RenderFeature } from '../features/types';
+import { rendererPlugin, renderFeaturePlugin } from '../plugin';
+import type { Renderer } from '../renderer';
+
+describe('render capability plugins', () => {
+  it('uninstalls a RenderFeature when its Fiber is disposed', async () => {
+    const installRenderFeature = vi.fn(async () => ({ ok: true as const, value: undefined }));
+    const uninstallRenderFeature = vi.fn(async () => ({ ok: true as const, value: undefined }));
+    const renderer = { installRenderFeature, uninstallRenderFeature } as unknown as Renderer;
+    const feature = { identity: 'test-feature' } as RenderFeature<unknown>;
+    const context = new Context();
+    await context.plugin(rendererPlugin(renderer));
+
+    const fiber = await context.plugin(renderFeaturePlugin(feature));
+    expect(installRenderFeature).toHaveBeenCalledWith(feature);
+    expect(uninstallRenderFeature).not.toHaveBeenCalled();
+
+    await fiber.dispose();
+    expect(uninstallRenderFeature).toHaveBeenCalledOnce();
+    expect(uninstallRenderFeature).toHaveBeenCalledWith(feature);
+  });
+});

package/src/__tests__/post-process-error-policy-owner.unit.test.ts

@@ -0,0 +1,208 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import {
+  PostProcessError as PublicPostProcessError,
+  type PostProcessErrorCode as PublicPostProcessErrorCode,
+} from '../index';
+import {
+  PostProcessError,
+  type PostProcessErrorCode,
+  type PostProcessErrorDetail,
+  type PostProcessErrorDetailFor,
+  type PostProcessError as PostProcessErrorType,
+} from '../post-process-errors';
+
+const expectedCodes = [
+  'post-process-already-registered',
+  'post-process-not-found',
+  'fullscreen-input-not-found',
+  'ssao-radius-non-positive',
+  'ssao-bias-negative',
+  'params-size-mismatch',
+  'params-update-size-mismatch',
+] as const satisfies readonly PostProcessErrorCode[];
+
+type ExpectedCodeUnion = (typeof expectedCodes)[number];
+
+const evidence = [
+  {
+    code: 'post-process-already-registered',
+    error: new PostProcessError({
+      code: 'post-process-already-registered',
+      detail: { id: 'pkg::duplicate' },
+    }),
+    expected: 'each post-process id is registered at most once',
+    hint: "post-process id 'pkg::duplicate' is already registered; same-id re-register is forbidden. Pick a distinct id (engine builtins use the forgeax:: prefix; user passes use <package>::<id>).",
+    message:
+      "post-process: post-process-already-registered (post-process id 'pkg::duplicate' is already registered; same-id re-register is forbidden. Pick a distinct id (engine builtins use the forgeax:: prefix; user passes use <package>::<id>).)",
+  },
+  {
+    code: 'post-process-not-found',
+    error: new PostProcessError({
+      code: 'post-process-not-found',
+      detail: { id: 'pkg::missing' },
+    }),
+    expected: 'addFullscreenPass references a registered post-process id',
+    hint: "no post-process is registered for id 'pkg::missing'. First call renderer.postProcess.register('pkg::missing', {source, reads?}), then reference it via addFullscreenPass({shader: id}).",
+    message:
+      "post-process: post-process-not-found (no post-process is registered for id 'pkg::missing'. First call renderer.postProcess.register('pkg::missing', {source, reads?}), then reference it via addFullscreenPass({shader: id}).)",
+  },
+  {
+    code: 'fullscreen-input-not-found',
+    error: new PostProcessError({
+      code: 'fullscreen-input-not-found',
+      detail: { readsKey: 'hdrColor', passName: 'post-pass' },
+    }),
+    expected: 'reads key must be a graph-declared colorTarget with TEXTURE_BINDING',
+    hint: "fullscreen pass 'post-pass' references reads key 'hdrColor' but that key is not declared as a graph color target, or the target is not sampleable as a texture. First call graph.addColorTarget('hdrColor', {format, size}) (or check spelling) before addFullscreenPass(g, 'post-pass', { shader, color, reads: ['hdrColor'] }). If 'hdrColor' is a depth target, ensure it has TEXTURE_BINDING usage (0x04) and is declared via graph.addColorTarget. Consider switching pipeline if your pipeline does not expose a sampleable depth target.",
+    message:
+      "post-process: fullscreen-input-not-found (fullscreen pass 'post-pass' references reads key 'hdrColor' but that key is not declared as a graph color target, or the target is not sampleable as a texture. First call graph.addColorTarget('hdrColor', {format, size}) (or check spelling) before addFullscreenPass(g, 'post-pass', { shader, color, reads: ['hdrColor'] }). If 'hdrColor' is a depth target, ensure it has TEXTURE_BINDING usage (0x04) and is declared via graph.addColorTarget. Consider switching pipeline if your pipeline does not expose a sampleable depth target.)",
+  },
+  {
+    code: 'ssao-radius-non-positive',
+    error: new PostProcessError({
+      code: 'ssao-radius-non-positive',
+      detail: { paramName: 'radius', value: -0.25 },
+    }),
+    expected: 'SSAO radius must be > 0',
+    hint: "SSAO parameter 'radius' is -0.25, must be greater than 0. Set config.ssao.radius to a positive value (default 0.5) or disable SSAO with config.ssao.enabled = false.",
+    message:
+      "post-process: ssao-radius-non-positive (SSAO parameter 'radius' is -0.25, must be greater than 0. Set config.ssao.radius to a positive value (default 0.5) or disable SSAO with config.ssao.enabled = false.)",
+  },
+  {
+    code: 'ssao-bias-negative',
+    error: new PostProcessError({
+      code: 'ssao-bias-negative',
+      detail: { paramName: 'bias', value: -0.1 },
+    }),
+    expected: 'SSAO bias must be >= 0',
+    hint: "SSAO parameter 'bias' is -0.1, must be >= 0. Set config.ssao.bias to a non-negative value (default 0.025) or disable SSAO.",
+    message:
+      "post-process: ssao-bias-negative (SSAO parameter 'bias' is -0.1, must be >= 0. Set config.ssao.bias to a non-negative value (default 0.025) or disable SSAO.)",
+  },
+  {
+    code: 'params-size-mismatch',
+    error: new PostProcessError({
+      code: 'params-size-mismatch',
+      detail: { byteSize: 8, actualLength: 4 },
+    }),
+    expected: 'params.byteSize >= 16 and defaultValue.length === byteSize',
+    hint: 'params.byteSize is 8 but defaultValue.length is 4. The UBO byteSize must be >= 16 B and defaultValue.length must equal byteSize. Pass a defaultValue Uint8Array whose .length matches byteSize exactly.',
+    message:
+      'post-process: params-size-mismatch (params.byteSize is 8 but defaultValue.length is 4. The UBO byteSize must be >= 16 B and defaultValue.length must equal byteSize. Pass a defaultValue Uint8Array whose .length matches byteSize exactly.)',
+  },
+  {
+    code: 'params-update-size-mismatch',
+    error: new PostProcessError({
+      code: 'params-update-size-mismatch',
+      detail: { byteSize: 16, actualLength: 12 },
+    }),
+    expected: 'PostProcessParams.data byteLength === registered params.byteSize',
+    hint: 'PostProcessParams.data byteLength is 12 but the registered params.byteSize is 16. The per-frame data-driven write must match the registered byteSize exactly; check the PostProcessParams.data you assign each frame.',
+    message:
+      'post-process: params-update-size-mismatch (PostProcessParams.data byteLength is 12 but the registered params.byteSize is 16. The per-frame data-driven write must match the registered byteSize exactly; check the PostProcessParams.data you assign each frame.)',
+  },
+];
+
+describe('PostProcessError policy ownership', () => {
+  it('preserves the exact seven-code vocabulary and public type', () => {
+    expect(expectedCodes).toHaveLength(7);
+    expect(new Set(expectedCodes).size).toBe(7);
+    expectTypeOf<PostProcessErrorCode>().toEqualTypeOf<ExpectedCodeUnion>();
+    expectTypeOf<ExpectedCodeUnion>().toEqualTypeOf<PostProcessErrorCode>();
+    expectTypeOf<PublicPostProcessErrorCode>().toEqualTypeOf<PostProcessErrorCode>();
+    expect(PublicPostProcessError).toBe(PostProcessError);
+
+    const acceptsCode = (code: PostProcessErrorCode): PostProcessErrorCode => code;
+    // @ts-expect-error -- the policy-derived closed union rejects unknown codes.
+    acceptsCode('post-process-not-real');
+  });
+
+  it('preserves every expected value, dynamic hint, and message byte-for-byte', () => {
+    for (const { code, error, expected, hint, message } of evidence) {
+      expect(error.code).toBe(code);
+      expect(error.expected).toBe(expected);
+      expect(error.hint).toBe(hint);
+      expect(error.message).toBe(message);
+    }
+  });
+
+  it('preserves correlated constructor inference for representative details', () => {
+    const previouslyRegistered = new PostProcessError({
+      code: 'post-process-already-registered',
+      detail: { id: 'pkg::duplicate' },
+    });
+    expectTypeOf(previouslyRegistered).toEqualTypeOf<
+      Extract<PostProcessErrorType, { readonly code: 'post-process-already-registered' }>
+    >();
+    expectTypeOf(previouslyRegistered.detail).toEqualTypeOf<
+      Extract<PostProcessErrorType, { readonly code: 'post-process-already-registered' }>['detail']
+    >();
+
+    const depthInput = new PostProcessError({
+      code: 'fullscreen-input-not-found',
+      detail: { readsKey: 'depth', passName: 'post-dof' },
+    });
+    expectTypeOf(depthInput).toEqualTypeOf<
+      Extract<PostProcessErrorType, { readonly code: 'fullscreen-input-not-found' }>
+    >();
+    expectTypeOf(depthInput.detail).toEqualTypeOf<
+      Extract<PostProcessErrorType, { readonly code: 'fullscreen-input-not-found' }>['detail']
+    >();
+    expectTypeOf<PostProcessErrorDetail>().toEqualTypeOf<
+      PostProcessErrorDetailFor<PostProcessErrorCode>
+    >();
+
+    const readDetail = (error: PostProcessErrorType): string => {
+      if (error.code === 'fullscreen-input-not-found') {
+        expectTypeOf(error.detail).toEqualTypeOf<
+          Extract<PostProcessErrorType, { readonly code: 'fullscreen-input-not-found' }>['detail']
+        >();
+        return `${error.detail.passName}:${error.detail.readsKey}`;
+      }
+      if (error.code === 'params-update-size-mismatch') {
+        expectTypeOf(error.detail).toEqualTypeOf<
+          Extract<PostProcessErrorType, { readonly code: 'params-update-size-mismatch' }>['detail']
+        >();
+        return `${error.detail.byteSize}:${error.detail.actualLength}`;
+      }
+      return error.code;
+    };
+
+    expect(readDetail(depthInput)).toBe('post-dof:depth');
+    expect(
+      readDetail(
+        new PostProcessError({
+          code: 'params-update-size-mismatch',
+          detail: { byteSize: 16, actualLength: 12 },
+        }),
+      ),
+    ).toBe('16:12');
+  });
+
+  it('preserves Error behavior, own-field order, and descriptors', () => {
+    const error = new PostProcessError({
+      code: 'params-update-size-mismatch',
+      detail: { byteSize: 16, actualLength: 12 },
+    });
+
+    expect(error).toBeInstanceOf(Error);
+    expect(error.name).toBe('PostProcessError');
+    expect(error.stack).toContain('PostProcessError');
+    expect(error.stack).toContain(error.message);
+    expect(Object.keys(error)).toEqual(['code', 'expected', 'hint', 'detail', 'name']);
+
+    for (const field of ['name', 'code', 'expected', 'hint', 'detail'] as const) {
+      expect(Object.getOwnPropertyDescriptor(error, field)).toMatchObject({
+        configurable: true,
+        enumerable: true,
+        writable: true,
+      });
+    }
+    expect(Object.getOwnPropertyDescriptor(error, 'stack')).toMatchObject({
+      configurable: true,
+      enumerable: false,
+    });
+    expect(typeof Object.getOwnPropertyDescriptor(error, 'stack')?.get).toBe('function');
+    expect(typeof Object.getOwnPropertyDescriptor(error, 'stack')?.set).toBe('function');
+  });
+});

package/src/__tests__/prepared-buffer-kind-owner.test-d.ts

@@ -0,0 +1,29 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import type { PreparedGraphicsKind } from '../features/prepared-graphics-store';
+import type { PreparedGraphicsResolvedResource } from '../prepare/prepared-graphics-resolver';
+
+type PreparedBufferKind = Exclude<PreparedGraphicsKind, 'pipeline' | 'bindings'>;
+type PreparedBufferResource = Extract<
+  PreparedGraphicsResolvedResource,
+  { readonly kind: PreparedBufferKind }
+>;
+
+const resolverSource = readFileSync(
+  new URL('../prepare/prepared-graphics-resolver.ts', import.meta.url),
+  'utf8',
+);
+
+describe('prepared buffer kind owner', () => {
+  it('keeps the buffer projection derived from PreparedGraphicsKind', () => {
+    expectTypeOf<PreparedBufferKind>().toEqualTypeOf<'vertex-data' | 'index-data'>();
+    expectTypeOf<PreparedBufferResource['kind']>().toEqualTypeOf<PreparedBufferKind>();
+    expectTypeOf<PreparedBufferKind>().toEqualTypeOf<PreparedBufferResource['kind']>();
+  });
+
+  it('keeps the projection local to the resolver owner', () => {
+    expect(resolverSource).toContain(
+      "type PreparedBufferKind = Exclude<PreparedGraphicsKind, 'pipeline' | 'bindings'>;",
+    );
+  });
+});

package/src/__tests__/prepared-graphics-backend-matrix.unit.test.ts

@@ -0,0 +1,129 @@
+import { describe, expect, it } from 'vitest';
+import type {
+  RenderFeatureGraphicsPassDescriptor,
+  RenderFeaturePreparedGraphicsState,
+  RenderFeaturePreparedRef,
+} from '../features/prepared-graphics';
+import { recordRenderFeatureGraphicsPass } from '../record/frame-targets';
+
+type MatrixResult = {
+  readonly acceptedCount: number;
+  readonly errorCode: string | null;
+  readonly operation: string | null;
+  readonly reason: string | null;
+  readonly generation: number;
+  readonly releaseCount: number;
+};
+
+const ref = <Kind extends RenderFeaturePreparedRef['kind']>(
+  kind: Kind,
+  generation = 1,
+): RenderFeaturePreparedRef<Kind> => ({ kind, generation });
+
+const pipeline = ref('pipeline');
+const bindings = ref('bindings');
+const vertices = ref('vertex-data');
+
+const pass: RenderFeatureGraphicsPassDescriptor = {
+  attachments: {
+    colors: [{ resource: 'color', format: 'rgba8unorm', loadOp: 'load', storeOp: 'store' }],
+  },
+  draws: [
+    {
+      kind: 'draw',
+      pipeline,
+      bindings: [bindings],
+      vertexData: [{ slot: 0, resource: vertices }],
+      command: { vertexCount: 3, instanceCount: 1 },
+    },
+  ],
+};
+
+const state: RenderFeaturePreparedGraphicsState = {
+  capabilityAvailable: true,
+  generation: 1,
+  attachments: [{ resource: 'color', format: 'rgba8unorm' }],
+  pipeline,
+  bindings: [bindings],
+  vertexData: [vertices],
+  indexData: [],
+};
+
+function runCase(
+  descriptor: RenderFeatureGraphicsPassDescriptor,
+  projectedState: RenderFeaturePreparedGraphicsState,
+): MatrixResult {
+  const result = recordRenderFeatureGraphicsPass(
+    'synthetic.backend-matrix',
+    descriptor,
+    projectedState,
+    { pipeline: 0, binding: 0, vertex: 0, index: 0, draw: 0 },
+  );
+  if (result.ok) {
+    return {
+      acceptedCount: result.value.acceptedDrawCount,
+      errorCode: null,
+      operation: null,
+      reason: null,
+      generation: projectedState.generation,
+      releaseCount: 0,
+    };
+  }
+  const detail = 'detail' in result.error ? result.error.detail : undefined;
+  return {
+    acceptedCount: 0,
+    errorCode: result.error.code,
+    operation: detail !== undefined && 'operation' in detail ? detail.operation : null,
+    reason: detail !== undefined && 'reason' in detail ? detail.reason : null,
+    generation: projectedState.generation,
+    releaseCount: 0,
+  };
+}
+
+const cases = [
+  { name: 'accepted', descriptor: pass, projectedState: state },
+  {
+    name: 'missing capability',
+    descriptor: pass,
+    projectedState: { ...state, capabilityAvailable: false },
+  },
+  {
+    name: 'stale generation',
+    descriptor: pass,
+    projectedState: { ...state, generation: 2 },
+  },
+] as const;
+
+describe('prepared graphics backend case matrix', () => {
+  it.each(cases)('keeps fixed comparison fields for $name', ({ descriptor, projectedState }) => {
+    const first = runCase(descriptor, projectedState);
+    const second = runCase(descriptor, projectedState);
+    expect(Object.keys(first)).toEqual([
+      'acceptedCount',
+      'errorCode',
+      'operation',
+      'reason',
+      'generation',
+      'releaseCount',
+    ]);
+    expect(second).toEqual(first);
+  });
+
+  it('distinguishes accepted work from disabled and stale work', () => {
+    const accepted = runCase(pass, state);
+    const disabled = runCase(pass, { ...state, capabilityAvailable: false });
+    const stale = runCase(pass, { ...state, generation: 2 });
+
+    expect(accepted).toMatchObject({ acceptedCount: 1, errorCode: null, generation: 1 });
+    expect(disabled).toMatchObject({
+      acceptedCount: 0,
+      errorCode: 'render-feature-preparation-failed',
+    });
+    expect(stale).toMatchObject({
+      acceptedCount: 0,
+      errorCode: 'render-feature-prepared-state-mismatch',
+    });
+    expect(disabled.releaseCount).toBe(0);
+    expect(stale.releaseCount).toBe(0);
+  });
+});