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

package/src/__tests__/morph-culling-reentry.dawn.test.ts

@@ -0,0 +1,157 @@
+import { RenderGraphBuilder } from '@forgeax/engine-render-graph';
+import type { RhiCommandEncoder } from '@forgeax/engine-rhi';
+import { createShaderModule, rhi } from '@forgeax/engine-rhi-webgpu';
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import {
+  createRenderFeatureHost,
+  getRenderFeaturePlanExecutionProjection,
+  runRenderFeatureFrame,
+} from '../features/host';
+import {
+  createBuiltinMorphFeature,
+  createMorphReentryState,
+  deriveMorphBounds,
+  MORPH_COMPUTE_WGSL,
+  morphCullDecision,
+  stepMorphReentry,
+} from '../features/morph/morph-feature';
+import { createRenderFeatureGpuWorkOwner } from '../features/prepared-gpu-work';
+import { RenderFeatureComputeGraphProjection } from '../features/render-graph-compute';
+
+const baseBounds = {
+  min: [-1, -1, -1] as const,
+  max: [1, 1, 1] as const,
+};
+
+describe('Morph GPU culling and re-entry', () => {
+  it('expands bounds from weighted target deltas before culling', () => {
+    const bounds = deriveMorphBounds(
+      baseBounds,
+      [{ min: [-2, 0, 0], max: [3, 0, 0] }],
+      new Float32Array([0.5]),
+    );
+
+    expect(bounds).toEqual({ min: [-2, -1, -1], max: [2.5, 1, 1] });
+    expect(
+      morphCullDecision({
+        weights: new Float32Array([0.5]),
+        expectedWeightCount: 1,
+        baseAabbIntersectsFrustum: false,
+      }),
+    ).toBe('draw');
+  });
+
+  it('clears stale weights when a culled instance re-enters', () => {
+    const state = createMorphReentryState();
+    expect(
+      stepMorphReentry(state, {
+        frameNumber: 1,
+        visible: true,
+        generation: 0,
+        weights: new Float32Array([0.25]),
+      }),
+    ).toMatchObject({ reentered: false, clearStale: false });
+    expect(
+      stepMorphReentry(state, {
+        frameNumber: 2,
+        visible: false,
+        generation: 0,
+        weights: new Float32Array([0]),
+      }),
+    ).toMatchObject({ reentered: false, clearStale: false });
+    expect(
+      stepMorphReentry(state, {
+        frameNumber: 3,
+        visible: true,
+        generation: 0,
+        weights: new Float32Array([0.75]),
+      }),
+    ).toMatchObject({ reentered: true, clearStale: true, weights: [0.75] });
+  });
+
+  it('declares compute and storage capability ownership and records 300 frame phases', () => {
+    let frameNumber = 0;
+    const feature = createBuiltinMorphFeature({
+      collect: () => [
+        {
+          identity: 'format-tier1.face',
+          vertexCount: 3,
+          targetBounds: [{ min: [-2, 0, 0], max: [3, 0, 0] }],
+          baseBounds,
+          weights: new Float32Array([frameNumber >= 200 ? 1 : 0]),
+          baseAabbIntersectsFrustum: frameNumber < 100 || frameNumber >= 200,
+        },
+      ],
+    });
+
+    expect(feature.requiredCapabilities).toEqual(['compute', 'storageBuffer']);
+    let culledFrames = 0;
+    let reentries = 0;
+    for (frameNumber = 0; frameNumber < 300; frameNumber++) {
+      const extracted = feature.extract({ worlds: [], owner: 0, frameNumber });
+      expect(extracted.ok).toBe(true);
+      if (!extracted.ok) continue;
+      culledFrames += extracted.value.culledCount;
+      reentries += extracted.value.reentryCount;
+    }
+
+    expect(culledFrames).toBe(100);
+    expect(reentries).toBe(1);
+  });
+
+  it('submits one real Dawn compute frame through the Morph feature seam', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const shader = (await createShaderModule(device, { code: MORPH_COMPUTE_WGSL })).unwrap();
+    const owner = createRenderFeatureGpuWorkOwner({
+      getDevice: () => device,
+      getShaderModuleFactory: () => ({ createShaderModule: () => ok(shader) }),
+    });
+    const feature = createBuiltinMorphFeature({
+      collect: () => [
+        {
+          identity: 'dawn-triangle',
+          vertexCount: 3,
+          baseBounds,
+          targetBounds: [{ min: [-1, 0, 0], max: [1, 0, 0] }],
+          weights: new Float32Array([0.5]),
+          baseAabbIntersectsFrustum: true,
+          basePositions: new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]),
+          targetDeltas: new Float32Array([0, 0, 0, 0.1, 0, 0, 0, 0.1, 0]),
+        },
+      ],
+    });
+    const host = createRenderFeatureHost([feature]);
+    expect(host.ok).toBe(true);
+    if (!host.ok) return;
+    const frame = runRenderFeatureFrame(host.value, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 1,
+      caps: device.caps,
+      gpuWork: owner,
+    });
+    expect(frame.errors).toEqual([]);
+    const contribution =
+      frame.plans[0] === undefined
+        ? undefined
+        : getRenderFeaturePlanExecutionProjection(frame.plans[0]);
+    const encoder = device.createCommandEncoder({ label: 'dawn-morph-frame' }).unwrap();
+    const work = contribution?.passes[0]?.resolvedGpuCompute;
+    expect(work).toBeDefined();
+    if (work === undefined) return;
+    const graph = new RenderGraphBuilder<{ readonly encoder: RhiCommandEncoder }>();
+    const projection = new RenderFeatureComputeGraphProjection(graph);
+    expect(projection.addPass('forgeax.morph.compute', 'forgeax.morph', 0, work).ok).toBe(true);
+    const compiled = graph.compile({ device, surfaceSize: { width: 1, height: 1 } }).unwrap();
+    expect(compiled.execute({ encoder }).ok).toBe(true);
+    const commandBuffer = encoder.finish();
+    expect(commandBuffer.ok).toBe(true);
+    if (!commandBuffer.ok) return;
+    expect(device.queue.submit([commandBuffer.value]).ok).toBe(true);
+    await device.queue.onSubmittedWorkDone();
+    expect((await compiled.retire()).ok).toBe(true);
+    expect(host.value.dispose().ok).toBe(true);
+  });
+});

package/src/__tests__/morph-feature-gpu-work.integration.test.ts

@@ -0,0 +1,80 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { rhi } from '@forgeax/engine-rhi-null';
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import {
+  createRenderFeatureHost,
+  getRenderFeaturePlanExecutionProjection,
+  runRenderFeatureFrame,
+} from '../features/host';
+import { createBuiltinMorphFeature, MORPH_COMPUTE_WGSL } from '../features/morph/morph-feature';
+import {
+  createRenderFeatureGpuWorkOwner,
+  encodeRenderFeatureGpuComputePass,
+} from '../features/prepared-gpu-work';
+
+describe('Morph RenderFeature GPU work', () => {
+  it('exposes morph work through the declarative plan owner', () => {
+    const source = readFileSync(
+      resolve(import.meta.dirname, '../features/morph/morph-feature.ts'),
+      'utf8',
+    );
+    expect(source).toContain('RenderFeaturePlan');
+    expect(source).not.toMatch(/GPUCommandEncoder|queue\.submit|encoder\.finish/);
+  });
+
+  it('projects the plan into one executable compute pass', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const shader = (await rhi.createShaderModule(device, { code: MORPH_COMPUTE_WGSL })).unwrap();
+    const owner = createRenderFeatureGpuWorkOwner({
+      getDevice: () => device,
+      getShaderModuleFactory: () => ({ createShaderModule: () => ok(shader) }),
+    });
+    const feature = createBuiltinMorphFeature({
+      collect: () => [
+        {
+          identity: 'triangle',
+          vertexCount: 3,
+          baseBounds: { min: [-1, -1, -1], max: [1, 1, 1] },
+          targetBounds: [{ min: [-1, 0, 0], max: [1, 0, 0] }],
+          weights: new Float32Array([0.5]),
+          baseAabbIntersectsFrustum: true,
+          basePositions: new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]),
+          targetDeltas: new Float32Array([0, 0, 0, 0.1, 0, 0, 0, 0.1, 0]),
+        },
+      ],
+    });
+    const host = createRenderFeatureHost([feature]);
+    expect(host.ok).toBe(true);
+    if (!host.ok) return;
+    const frame = runRenderFeatureFrame(host.value, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 1,
+      caps: device.caps,
+      gpuWork: owner,
+    });
+    expect(frame.errors).toEqual([]);
+    expect(frame.plans).toHaveLength(1);
+    const contribution =
+      frame.plans[0] === undefined
+        ? undefined
+        : getRenderFeaturePlanExecutionProjection(frame.plans[0]);
+    expect(contribution?.passes).toHaveLength(1);
+    expect(contribution?.passes[0]?.gpuCompute?.program).toBeDefined();
+    expect(contribution?.passes[0]?.resolvedGpuCompute).toBeDefined();
+    expect(MORPH_COMPUTE_WGSL).toContain('@compute');
+
+    const encoder = device.createCommandEncoder({ label: 'morph-feature' }).unwrap();
+    const work = contribution?.passes[0]?.resolvedGpuCompute;
+    expect(work).toBeDefined();
+    if (work === undefined) return;
+    const pass = encoder.beginComputePass({ label: 'forgeax.morph.compute' });
+    encodeRenderFeatureGpuComputePass(pass, work);
+    pass.end();
+    expect(encoder.finish().ok).toBe(true);
+    expect(host.value.dispose().ok).toBe(true);
+  });
+});

package/src/__tests__/morph-feature-plan.unit.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest';
+import { createBuiltinMorphFeature } from '../features/morph/morph-feature';
+import { freezeRenderFeaturePlan } from '../features/plan';
+
+describe('morph RenderFeature plan', () => {
+  it('declares compute descriptors and a vertex-consumable output', () => {
+    const feature = createBuiltinMorphFeature({
+      collect: () => [
+        {
+          identity: 'face',
+          vertexCount: 3,
+          baseBounds: { min: [-1, -1, -1], max: [1, 1, 1] },
+          targetBounds: [{ min: [0, 0, 0], max: [1, 1, 1] }],
+          weights: [0.5],
+          baseAabbIntersectsFrustum: true,
+          basePositions: [0, 0, 0, 1, 0, 0, 0, 1, 0],
+          targetDeltas: [0, 0, 1, 0, 0, 1, 0, 0, 1],
+        },
+      ],
+    });
+    const extracted = feature.extract({ worlds: [], owner: 0, frameNumber: 1 });
+    expect(extracted.ok).toBe(true);
+    if (!extracted.ok) return;
+    const planned = feature.plan(extracted.value, {
+      caps: {} as never,
+      frame: { frameNumber: 1 },
+      generation: 1,
+      targets: [],
+    });
+
+    expect(planned.ok).toBe(true);
+    if (!planned.ok) return;
+    expect(freezeRenderFeaturePlan(feature.identity, planned.value).ok).toBe(true);
+    expect(planned.value.resources).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ kind: 'compute-program' }),
+        expect.objectContaining({
+          kind: 'buffer',
+          name: 'morph.draw-0.output',
+          usage: ['storage', 'vertex', 'copy-src'],
+        }),
+        expect.objectContaining({ kind: 'compute-bindings' }),
+        expect.objectContaining({ kind: 'vertex-data', buffer: 'morph.draw-0.output' }),
+      ]),
+    );
+    expect(planned.value.passes).toEqual([
+      expect.objectContaining({
+        kind: 'compute',
+        dispatches: [expect.objectContaining({ entryPoint: 'morph_main' })],
+      }),
+    ]);
+  });
+});

package/src/__tests__/morph-visual-evidence.integration.test.ts

@@ -0,0 +1,80 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const repoRoot = resolve(fileURLToPath(new URL('../../../../', import.meta.url)));
+const evidencePath = resolve(
+  repoRoot,
+  'apps/hello/format-tier1/evidence/morph-visual-evidence.json',
+);
+const matrixPath = resolve(repoRoot, 'apps/hello/format-tier1/evidence/format-support-matrix.json');
+
+describe('Morph Dawn evidence contract', () => {
+  it('binds the 300-frame GPU result to the immutable source and readback', async () => {
+    const [evidence, matrix] = await Promise.all([
+      readFile(evidencePath, 'utf8').then(
+        (source) =>
+          JSON.parse(source) as {
+            schemaVersion?: string;
+            featureId?: string;
+            source?: { csvSha256?: string; firstTierRows?: number[]; sourceCodeSha?: string };
+            environment?: { backend?: string };
+            requiredFrames?: number;
+            framesObserved?: number;
+            phases?: {
+              standardFrames?: number;
+              baseWeightFrames?: number;
+              zeroWeightFrames?: number;
+              animatedFrames?: number;
+            };
+            readback?: { status?: string; path?: string; maxAbsError?: number };
+            screenshot?: { status?: string; path?: string | null; reason?: string };
+            falsifiers?: { zeroWeights?: string; standardLane?: string; staleWeights?: string };
+            observed?: string;
+            producer?: { status?: string; kind?: string };
+            verdict?: string;
+            confidence?: string;
+            capabilityRefusal?: unknown;
+          },
+      ),
+      readFile(matrixPath, 'utf8').then(
+        (source) =>
+          JSON.parse(source) as {
+            source?: { firstTierRows?: number[] };
+          },
+      ),
+    ]);
+
+    expect(evidence.schemaVersion).toBe('morph-visual-evidence/1');
+    expect(evidence.featureId).toBe('feat-20260812-format-classification-tier1');
+    expect(evidence.source?.csvSha256).toBe(
+      'a87159400f5de776ce46304540999c2e7f84cec07defceaa661d0a0926a9c2d5',
+    );
+    expect(matrix.source?.firstTierRows).toEqual([8, 18, 26]);
+    expect(evidence.source?.sourceCodeSha).toMatch(/^[a-f0-9]{40,64}$/);
+    expect(evidence.environment?.backend).toBe('dawn');
+    expect(evidence.requiredFrames).toBe(300);
+    expect(evidence.framesObserved).toBe(300);
+    expect(evidence.phases).toEqual({
+      standardFrames: 300,
+      baseWeightFrames: 100,
+      zeroWeightFrames: 100,
+      animatedFrames: 100,
+    });
+    expect(evidence.readback?.status).toBe('pass');
+    expect(evidence.readback?.path).toContain('observe(FrameReceipt)');
+    expect(evidence.readback?.maxAbsError).toBeNull();
+    expect(evidence.screenshot).toBeUndefined();
+    expect(evidence.falsifiers).toEqual({
+      zeroWeights: 'pass',
+      standardLane: 'pass',
+      staleWeights: 'pass',
+    });
+    expect(evidence.observed).toEqual(expect.any(String));
+    expect(evidence.producer).toMatchObject({ status: 'pass', kind: 'imported-loadByGuid' });
+    expect(evidence.verdict).toBe('pass');
+    expect(evidence.confidence).toBe('high');
+    expect(evidence.capabilityRefusal).toBeUndefined();
+  });
+});

package/src/__tests__/nineslice-handle-surface.unit.test.ts

@@ -0,0 +1,19 @@
+import { readFileSync } from 'node:fs';
+
+import { describe, expect, it } from 'vitest';
+
+const frameSource = readFileSync(new URL('../record/frame.ts', import.meta.url), 'utf8');
+const materialSource = readFileSync(
+  new URL('../record/main-pass-material.ts', import.meta.url),
+  'utf8',
+);
+
+describe('9-slice handle ownership', () => {
+  it('derives the lookup key from the canonical asset-runtime handle', () => {
+    expect(frameSource).toContain('handleSlot(HANDLE_NINESLICE_QUAD)');
+    expect(frameSource).toContain('r.assetHandle > handleSlot(HANDLE_NINESLICE_QUAD)');
+    expect(frameSource).not.toMatch(/BUILTIN_MESH_ID_MAX/);
+    expect(materialSource).not.toMatch(/NINESLICE_QUAD_RAW_ID\s*=/);
+    expect(materialSource).not.toMatch(/BUILTIN_MESH_ID_MAX\s*=/);
+  });
+});

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

@@ -0,0 +1,201 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+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: 'typed fullscreen plan references a registered post-process id',
+    hint: "no post-process is registered for id 'pkg::missing'. Register 'pkg::missing' with the feature host ({source, reads?}), then reference it from a typed fullscreen RenderFeaturePlan.",
+    message:
+      "post-process: post-process-not-found (no post-process is registered for id 'pkg::missing'. Register 'pkg::missing' with the feature host ({source, reads?}), then reference it from a typed fullscreen RenderFeaturePlan.)",
+  },
+  {
+    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 declare graph color target 'hdrColor' with its format and size (or check spelling) before the typed fullscreen pass 'post-pass' reads it. 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 declare graph color target 'hdrColor' with its format and size (or check spelling) before the typed fullscreen pass 'post-pass' reads it. 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 owned by this policy', () => {
+    expect(expectedCodes).toHaveLength(7);
+    expect(new Set(expectedCodes).size).toBe(7);
+    expectTypeOf<PostProcessErrorCode>().toEqualTypeOf<ExpectedCodeUnion>();
+    expectTypeOf<ExpectedCodeUnion>().toEqualTypeOf<PostProcessErrorCode>();
+    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'>;",
+    );
+  });
+});