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

package/src/__tests__/prepared-graphics-capability.unit.test.ts

@@ -0,0 +1,65 @@
+import type { RhiCaps } from '@forgeax/engine-rhi';
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { createRenderFeatureHost, runRenderFeatureFrame } from '../features/host';
+import type { RenderFeature } from '../features/types';
+
+const supportedCaps: Readonly<RhiCaps> = {
+  backendKind: 'null',
+  compute: true,
+  timestampQuery: false,
+  timestampPeriodNanoseconds: null,
+  indirectDrawing: false,
+  textureCompressionBc: false,
+} as RhiCaps;
+
+const missingCaps: Readonly<RhiCaps> = { ...supportedCaps, compute: false };
+
+function preparedFeature(): RenderFeature<{ readonly draw: boolean }> {
+  return {
+    identity: 'synthetic.capability',
+    requiredCapabilities: ['compute'],
+    extract: () => ok({ draw: true }),
+    plan: () => ok({ resources: [], passes: [] }),
+  };
+}
+
+describe('prepared graphics capability projection', () => {
+  it('projects supported capability into an accepted machine-readable operation', () => {
+    const host = createRenderFeatureHost([preparedFeature()]).unwrap();
+    const result = runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 1,
+      caps: supportedCaps,
+    });
+
+    expect(result.errors).toEqual([]);
+    expect(result.plans).toHaveLength(1);
+    expect(result.plans[0]?.plan).toEqual({ resources: [], passes: [] });
+    expect(host.diagnostics()[0]?.status).toBe('active');
+  });
+
+  it('returns a structured capability failure without a silent operation', () => {
+    const host = createRenderFeatureHost([preparedFeature()]).unwrap();
+    const result = runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 1,
+      caps: missingCaps,
+    });
+
+    expect(result.plans).toEqual([]);
+    expect(result.errors).toHaveLength(1);
+    expect(result.errors[0]).toMatchObject({
+      code: 'render-feature-capability-missing',
+      expected: expect.stringContaining('compute'),
+      hint: expect.stringContaining('disable'),
+      detail: {
+        featureIdentity: 'synthetic.capability',
+        capability: 'compute',
+      },
+    });
+    expect(host.diagnostics()[0]?.status).toBe('disabled');
+  });
+});

package/src/__tests__/prepared-graphics-generation.unit.test.ts

@@ -0,0 +1,161 @@
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { createRenderFeatureHost, runRenderFeatureFrame } from '../features/host';
+import type {
+  RenderFeatureDrawRecord,
+  RenderFeatureGraphicsPassDescriptor,
+  RenderFeaturePreparedGraphicsState,
+  RenderFeaturePreparedRef,
+} from '../features/prepared-graphics';
+import { validateRenderFeatureGraphicsPass } from '../features/prepared-graphics';
+import { createPreparedGraphicsStore } from '../features/prepared-graphics-store';
+import { createRenderFeatureTarget } from '../features/targets';
+import type { RenderFeature } from '../features/types';
+
+function feature(): RenderFeature<{ readonly ready: true }> {
+  return {
+    identity: 'synthetic.generation',
+    extract: () => ok({ ready: true }),
+    plan: () => ok({ resources: [], passes: [] }),
+  };
+}
+
+function ref<Kind extends 'pipeline' | 'bindings'>(
+  kind: Kind,
+  generation = 5,
+): RenderFeaturePreparedRef<Kind> {
+  return { kind, generation };
+}
+
+const noVertexPipeline = ref('pipeline');
+const noVertexBindings = ref('bindings');
+const noVertexColor = createRenderFeatureTarget({
+  kind: 'scene-color',
+  format: 'rgba8unorm',
+  sampleCount: 1,
+});
+const noVertexDepth = createRenderFeatureTarget({
+  kind: 'scene-depth',
+  format: 'depth24plus',
+  sampleCount: 1,
+});
+
+const noVertexDraw: RenderFeatureDrawRecord = {
+  kind: 'draw',
+  pipeline: noVertexPipeline,
+  bindings: [noVertexBindings],
+  vertexData: [],
+  vertexLayout: 'none',
+  command: { vertexCount: 3, instanceCount: 1 },
+};
+
+const noVertexPass: RenderFeatureGraphicsPassDescriptor = {
+  attachments: {
+    colors: [
+      { resource: noVertexColor, format: noVertexColor.format, loadOp: 'load', storeOp: 'store' },
+    ],
+    depthStencil: {
+      resource: noVertexDepth,
+      format: noVertexDepth.format,
+      depthLoadOp: 'load',
+      depthStoreOp: 'store',
+    },
+  },
+  draws: [noVertexDraw],
+};
+
+const noVertexState: RenderFeaturePreparedGraphicsState = {
+  capabilityAvailable: true,
+  generation: 5,
+  attachments: [
+    { resource: noVertexColor, format: noVertexColor.format },
+    { resource: noVertexDepth, format: noVertexDepth.format },
+  ],
+  pipeline: noVertexPipeline,
+  bindings: [noVertexBindings],
+  vertexData: [],
+  indexData: [],
+};
+
+describe('prepared graphics generation ownership', () => {
+  it('accepts only the explicit no-vertex draw shape and fences its generation', () => {
+    const accepted = validateRenderFeatureGraphicsPass(
+      'synthetic.no-vertex',
+      noVertexPass,
+      noVertexState,
+    );
+    expect(accepted.ok).toBe(true);
+    if (accepted.ok) expect(accepted.value.acceptedDrawCount).toBe(1);
+
+    const { vertexLayout: _marker, ...drawWithoutMarker } = noVertexDraw;
+    void _marker;
+    const missingMarker = validateRenderFeatureGraphicsPass(
+      'synthetic.no-vertex',
+      { ...noVertexPass, draws: [drawWithoutMarker] },
+      noVertexState,
+    );
+    expect(missingMarker.ok).toBe(false);
+
+    const stalePipeline = validateRenderFeatureGraphicsPass('synthetic.no-vertex', noVertexPass, {
+      ...noVertexState,
+      pipeline: ref('pipeline', 6),
+      generation: 5,
+    });
+    expect(stalePipeline.ok).toBe(false);
+
+    const missingBindings = validateRenderFeatureGraphicsPass('synthetic.no-vertex', noVertexPass, {
+      ...noVertexState,
+      bindings: [],
+    });
+    expect(missingBindings.ok).toBe(false);
+  });
+
+  it('rejects stale generation and foreign owner or kind references', () => {
+    const store = createPreparedGraphicsStore();
+    const owner = store.beginFrame('synthetic.owner', 4);
+    const foreign = store.beginFrame('synthetic.foreign', 4);
+    const old = owner.prepare('pipeline', 'pipeline', { signature: 'pipeline:v1' });
+    const foreignRef = foreign.prepare('pipeline', 'pipeline', { signature: 'pipeline:v1' });
+    expect(old.ok).toBe(true);
+    expect(foreignRef.ok).toBe(true);
+    owner.commit();
+    foreign.commit();
+
+    const next = store.beginFrame('synthetic.owner', 5);
+    const nextRef = next.prepare('pipeline', 'pipeline', { signature: 'pipeline:v2' });
+    expect(nextRef.ok).toBe(true);
+    if (old.ok && foreignRef.ok && nextRef.ok) {
+      expect(next.owns(old.value)).toBe(false);
+      expect(next.owns(foreignRef.value)).toBe(false);
+      expect(nextRef.value).not.toBe(old.value);
+      expect(nextRef.value.generation).toBe(5);
+    }
+    expect(next.graphicsState(true, []).generation).toBe(5);
+  });
+
+  it('keeps registration while replacing prepared state after a pipeline generation switch', () => {
+    const host = createRenderFeatureHost([feature()]).unwrap();
+    const before = runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 1,
+      generation: 1,
+      caps: { backendKind: 'null' } as never,
+    });
+    const after = runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 2,
+      generation: 2,
+      caps: { backendKind: 'null' } as never,
+    });
+
+    expect(before.errors).toEqual([]);
+    expect(after.errors).toEqual([]);
+    expect(before.plans[0]?.plan).toEqual({ resources: [], passes: [] });
+    expect(after.plans[0]?.plan).toEqual({ resources: [], passes: [] });
+    expect(host.features).toHaveLength(1);
+    expect(host.features[0]?.identity).toBe('synthetic.generation');
+    expect(host.diagnostics()[0]?.status).toBe('active');
+  });
+});

package/src/__tests__/prepared-graphics-lifecycle.unit.test.ts

@@ -0,0 +1,138 @@
+import type { RhiCaps } from '@forgeax/engine-rhi';
+import { err, ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import {
+  createRenderFeatureHost,
+  runRenderFeatureFrame,
+  settlePreparedGraphicsCompletion,
+} from '../features/host';
+import { createPreparedGraphicsStore } from '../features/prepared-graphics-store';
+import type { RenderFeature } from '../features/types';
+
+const caps = { backendKind: 'null' } as unknown as Readonly<RhiCaps>;
+
+function preparedFeature(): RenderFeature<{ readonly ready: true }> {
+  return {
+    identity: 'synthetic.lifecycle',
+    extract: () => ok({ ready: true }),
+    plan: () => ok({ resources: [], passes: [] }),
+  };
+}
+
+describe('prepared graphics lifecycle ownership', () => {
+  it('aborts partial preparation without changing committed state', () => {
+    const store = createPreparedGraphicsStore();
+    const initial = store.beginFrame('synthetic.lifecycle', 1);
+    initial.prepare('pipeline', 'pipeline', { signature: 'v1' });
+    initial.commit();
+
+    const failed = store.beginFrame('synthetic.lifecycle', 2);
+    failed.prepare('bindings', 'bindings', { signature: 'v2' });
+    failed.abort();
+
+    expect(store.snapshot('synthetic.lifecycle')).toMatchObject({
+      generation: 1,
+      items: [{ kind: 'pipeline', name: 'pipeline' }],
+    });
+    expect(failed.overlayItems()).toEqual([]);
+  });
+
+  it('re-prepares after recovery and makes repeated recovery idempotent', () => {
+    const host = createRenderFeatureHost([preparedFeature()]).unwrap();
+    const first = runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 1,
+      generation: 1,
+      caps,
+    });
+    expect(first.errors).toEqual([]);
+
+    expect(host.recover({ frameNumber: 2, caps })).toEqual(ok(undefined));
+    expect(host.recover({ frameNumber: 2, caps })).toEqual(ok(undefined));
+    const recovered = runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 3,
+      generation: 2,
+      caps,
+    });
+
+    expect(recovered.errors).toEqual([]);
+    expect(host.features[0]?.identity).toBe('synthetic.lifecycle');
+    expect(host.diagnostics()[0]?.status).toBe('active');
+  });
+
+  it('releases a prepared batch that never reached queue submission during recovery', () => {
+    const host = createRenderFeatureHost([preparedFeature()]).unwrap();
+    let releases = 0;
+    const lease = {
+      release: () => {
+        releases += 1;
+        return ok(undefined);
+      },
+    };
+    const batch = host.retainPreparedGraphics('synthetic.lifecycle', [lease]).unwrap();
+
+    expect(host.recover({ frameNumber: 5, caps })).toEqual(ok(undefined));
+    expect(releases).toBe(1);
+    expect(host.retirePreparedGraphics([batch])).toEqual(ok(undefined));
+    expect(releases).toBe(1);
+  });
+
+  it('keeps submitted batches alive through recovery and dispose until late completion', () => {
+    const host = createRenderFeatureHost([preparedFeature()]).unwrap();
+    let releases = 0;
+    const lease = {
+      release: () => {
+        releases += 1;
+        return ok(undefined);
+      },
+    };
+    const batch = host.retainPreparedGraphics('synthetic.lifecycle', [lease]).unwrap();
+
+    host.markPreparedGraphicsSubmitted([batch]);
+    expect(host.recover({ frameNumber: 6, caps })).toEqual(ok(undefined));
+    expect(releases).toBe(0);
+    expect(host.dispose()).toEqual(ok(undefined));
+    expect(releases).toBe(0);
+
+    expect(host.retirePreparedGraphics([batch])).toEqual(ok(undefined));
+    expect(host.retirePreparedGraphics([batch])).toEqual(ok(undefined));
+    expect(releases).toBe(1);
+  });
+
+  it('recovers submitted batches when queue completion rejects and reports release errors', async () => {
+    const host = createRenderFeatureHost([preparedFeature()]).unwrap();
+    let releases = 0;
+    const releaseError = new Error('prepared release failed');
+    const firstLease = {
+      release: () => {
+        releases += 1;
+        return ok(undefined);
+      },
+    };
+    const secondLease = {
+      release: () => {
+        releases += 1;
+        return err(releaseError as never);
+      },
+    };
+    const first = host.retainPreparedGraphics('synthetic.lifecycle', [firstLease]).unwrap();
+    const second = host.retainPreparedGraphics('synthetic.lifecycle', [secondLease]).unwrap();
+    host.markPreparedGraphicsSubmitted([first, second]);
+
+    const errors: unknown[] = [];
+    const completion = Promise.reject(new Error('queue completion unavailable'));
+    settlePreparedGraphicsCompletion(host, [first, second], completion, (error) => {
+      errors.push(error);
+    });
+    await completion.catch(() => undefined);
+    await Promise.resolve();
+
+    expect(releases).toBe(2);
+    expect(errors).toEqual([releaseError]);
+    expect(host.retirePreparedGraphics([first, second])).toEqual(ok(undefined));
+    expect(releases).toBe(2);
+  });
+});

package/src/__tests__/prepared-graphics-pipeline-warmup.unit.test.ts

@@ -0,0 +1,29 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+const ownerSource = readFileSync(new URL('../render-system.ts', import.meta.url), 'utf8');
+
+describe('prepared graphics material pipeline warmup', () => {
+  it('does not substitute an unrelated unlit pipeline while the authored shader warms', () => {
+    const start = ownerSource.indexOf('const preparedPipeline =');
+    const end = ownerSource.indexOf('resolveBindings:', start);
+    const owner = ownerSource.slice(start, end);
+
+    expect(owner).toContain('const pipeline = preparedPipeline ?? null');
+    expect(owner).not.toContain('unlitPipeline');
+    expect(owner).toContain('err(makePreparedPipelinePendingError())');
+  });
+
+  it('keeps view-only material bindings on the canonical view group with depth', () => {
+    const declaration = ownerSource.indexOf('const preparedViewOnlyPipelines');
+    const classification = ownerSource.indexOf('preparedViewOnlyPipelines.add', declaration);
+    const bindingResolution = ownerSource.indexOf(
+      'preparedViewOnlyPipelines.has(pipeline as object)',
+      classification,
+    );
+
+    expect(declaration).toBeGreaterThan(-1);
+    expect(classification).toBeGreaterThan(declaration);
+    expect(bindingResolution).toBeGreaterThan(classification);
+  });
+});

package/src/__tests__/prepared-graphics-resolver.unit.test.ts

@@ -0,0 +1,285 @@
+import { type BindGroup, type RenderPipeline, RhiError } from '@forgeax/engine-rhi';
+import { rhi } from '@forgeax/engine-rhi-null';
+import { err, ok, type Result } from '@forgeax/engine-types';
+import { describe, expect, it, vi } from 'vitest';
+import type { RenderFeatureGpuBufferRef } from '../features/prepared-gpu-work';
+import {
+  createPreparedGraphicsStore,
+  type PreparedGraphicsItem,
+} from '../features/prepared-graphics-store';
+import { createRenderFeatureTarget } from '../features/targets';
+import {
+  createPreparedGraphicsResolver,
+  type PreparedGraphicsResolverInput,
+} from '../prepare/prepared-graphics-resolver';
+
+async function device() {
+  const adapter = (await rhi.requestAdapter()).unwrap();
+  return (await adapter.requestDevice()).unwrap();
+}
+
+function resultMap(items: readonly PreparedGraphicsItem[]): Map<object, PreparedGraphicsItem> {
+  return new Map(items.map((item) => [item.reference, item]));
+}
+
+function failure<T>(result: Result<T, unknown>): {
+  readonly code: string;
+  readonly detail?: { readonly reason: string };
+} {
+  if (result.ok) throw new Error('expected a resolver failure');
+  return result.error as {
+    readonly code: string;
+    readonly detail?: { readonly reason: string };
+  };
+}
+
+describe('prepared graphics resolver', () => {
+  it('lets the render owner decide whether a scene target is a deferred binding', async () => {
+    const currentDevice = await device();
+    const store = createPreparedGraphicsStore();
+    const transaction = store.beginFrame('resolver.scene-target', 1);
+    const pipeline = transaction.prepare('pipeline', 'forward', {
+      shader: 'synthetic::view-only',
+      vertexLayout: 'position',
+      colorFormats: ['rgba8unorm'],
+    });
+    const bindings = transaction.prepare('bindings', 'view', {
+      pipeline: pipeline.unwrap(),
+      values: {
+        sceneDepth: createRenderFeatureTarget({
+          kind: 'scene-depth',
+          format: 'depth24plus-stencil8',
+          sampleCount: 1,
+        }),
+      },
+    });
+    transaction.commit().unwrap();
+    const lookup = resultMap(store.snapshot('resolver.scene-target').items);
+    const resolvedView = {} as BindGroup;
+    const resolveBindings = vi.fn(() => ok(resolvedView));
+    const resolver = createPreparedGraphicsResolver({
+      device: currentDevice,
+      generation: 1,
+      capabilityAvailable: true,
+      lookup: (reference) => lookup.get(reference),
+      resolvePipeline: () => ok({} as RenderPipeline),
+      resolveBindings,
+    });
+
+    const result = resolver.resolve(bindings.unwrap());
+
+    expect(result.ok && result.value.handle).toBe(resolvedView);
+    expect(resolveBindings).toHaveBeenCalledOnce();
+  });
+
+  it('releases producer binding resources exactly once', async () => {
+    const currentDevice = await device();
+    const store = createPreparedGraphicsStore();
+    const transaction = store.beginFrame('resolver.binding-lifetime', 1);
+    const pipeline = transaction.prepare('pipeline', 'forward', {
+      shader: 'synthetic::forward',
+      vertexLayout: 'position',
+      colorFormats: ['rgba8unorm'],
+    });
+    const bindings = transaction.prepare('bindings', 'material', {
+      pipeline: pipeline.unwrap(),
+      values: { group: 1 },
+    });
+    transaction.commit().unwrap();
+    const lookup = resultMap(store.snapshot('resolver.binding-lifetime').items);
+    const release = vi.fn(() => ok(undefined));
+    const resolver = createPreparedGraphicsResolver({
+      device: currentDevice,
+      generation: 1,
+      capabilityAvailable: true,
+      lookup: (reference) => lookup.get(reference),
+      resolvePipeline: () => ok({} as RenderPipeline),
+      resolveBindings: () => ok({ handle: {} as BindGroup, release }),
+    });
+
+    expect(resolver.resolve(bindings.unwrap()).ok).toBe(true);
+    expect(resolver.release().ok).toBe(true);
+    expect(resolver.release().ok).toBe(true);
+    expect(release).toHaveBeenCalledTimes(1);
+  });
+
+  it('maps normalized operations to current-device handles without using refs as handles', async () => {
+    const currentDevice = await device();
+    const store = createPreparedGraphicsStore();
+    const transaction = store.beginFrame('resolver.feature', 7);
+    const pipeline = transaction.prepare('pipeline', 'forward', {
+      shader: 'synthetic::forward',
+      vertexLayout: 'position',
+      colorFormats: ['rgba8unorm'],
+    });
+    const bindings = transaction.prepare('bindings', 'forward', {
+      pipeline: pipeline.unwrap(),
+      values: { tint: [1, 0, 0, 1] },
+    });
+    const vertex = transaction.prepare('vertex-data', 'triangle', {
+      layout: 'position',
+      data: new Float32Array([0, 1, 2]),
+    });
+    const index = transaction.prepare('index-data', 'triangle', {
+      format: 'uint16',
+      data: new Uint16Array([0, 1, 2]),
+    });
+    const externalBuffer = currentDevice.createBuffer({ size: 16, usage: 56 }).unwrap();
+    const externalRef = Object.freeze({
+      name: 'external-geometry',
+      generation: 7,
+    }) as RenderFeatureGpuBufferRef;
+    const externalVertex = transaction.prepare('vertex-data', 'external-vertices', {
+      layout: 'position',
+      buffer: externalRef,
+    });
+    const externalIndex = transaction.prepare('index-data', 'external-indices', {
+      format: 'uint16',
+      buffer: externalRef,
+    });
+    expect(transaction.commit().ok).toBe(true);
+
+    const items = store.snapshot('resolver.feature').items;
+    const lookup = resultMap(items);
+    const shader = (await rhi.createShaderModule(currentDevice, { code: 'synthetic' })).unwrap();
+    const input: PreparedGraphicsResolverInput = {
+      device: currentDevice,
+      generation: 7,
+      capabilityAvailable: true,
+      lookup: (ref) => lookup.get(ref),
+      resolvePipeline: () =>
+        currentDevice.createRenderPipeline({
+          layout: 'auto',
+          vertex: { module: shader, entryPoint: 'main', buffers: [] },
+          fragment: { module: shader, entryPoint: 'main', targets: [] },
+        }) as Result<RenderPipeline, never>,
+      resolveBindings: () => {
+        const layout = currentDevice.createBindGroupLayout({ entries: [] }).unwrap();
+        return currentDevice.createBindGroup({ layout, entries: [] }) as Result<BindGroup, never>;
+      },
+      resolveGpuBuffer: (reference) =>
+        reference === externalRef
+          ? { buffer: externalBuffer, size: 64, physicalUsage: 0x0020 }
+          : undefined,
+    };
+    const resolver = createPreparedGraphicsResolver(input);
+    const pipelineRef = pipeline.unwrap();
+    const bindingsRef = bindings.unwrap();
+    const vertexRef = vertex.unwrap();
+    const indexRef = index.unwrap();
+    const resolvedPipeline = resolver.resolve(pipelineRef);
+    const resolvedBindings = resolver.resolve(bindingsRef);
+    const resolvedVertex = resolver.resolve(vertexRef);
+    const resolvedIndex = resolver.resolve(indexRef);
+    const resolvedExternalVertex = resolver.resolve(externalVertex.unwrap());
+    const resolvedExternalIndex = resolver.resolve(externalIndex.unwrap());
+
+    expect(resolvedPipeline.ok).toBe(true);
+    expect(resolvedBindings.ok).toBe(true);
+    expect(resolvedVertex.ok).toBe(true);
+    expect(resolvedIndex.ok).toBe(true);
+    expect(resolvedExternalVertex.ok && resolvedExternalVertex.value.handle).toBe(externalBuffer);
+    expect(resolvedExternalIndex.ok && resolvedExternalIndex.value.handle).toBe(externalBuffer);
+    expect(resolvedPipeline.ok && resolvedPipeline.value.handle).not.toBe(pipelineRef);
+    expect(resolvedBindings.ok && resolvedBindings.value.handle).not.toBe(bindingsRef);
+    expect(resolvedVertex.ok && resolvedVertex.value.handle).not.toBe(vertexRef);
+    expect(resolvedIndex.ok && resolvedIndex.value.handle).not.toBe(indexRef);
+  });
+
+  it('rejects capability, resolution, stale, and forged refs before record mutation', async () => {
+    const currentDevice = await device();
+    const store = createPreparedGraphicsStore();
+    const transaction = store.beginFrame('resolver.failure', 3);
+    const pipeline = transaction.prepare('pipeline', 'forward', {
+      shader: 'synthetic::forward',
+      vertexLayout: 'position',
+      colorFormats: ['rgba8unorm'],
+    });
+    expect(transaction.commit().ok).toBe(true);
+    const lookup = resultMap(store.snapshot('resolver.failure').items);
+    let resolveCalls = 0;
+    const base: PreparedGraphicsResolverInput = {
+      device: currentDevice,
+      generation: 3,
+      capabilityAvailable: true,
+      lookup: (ref) => lookup.get(ref),
+      resolvePipeline: () => {
+        resolveCalls += 1;
+        return ok({} as RenderPipeline);
+      },
+      resolveBindings: () => ok({} as BindGroup),
+    };
+
+    const pipelineRef = pipeline.unwrap();
+    const unavailable = createPreparedGraphicsResolver({
+      ...base,
+      capabilityAvailable: false,
+    }).resolve(pipelineRef);
+    expect(unavailable.ok).toBe(false);
+    expect(failure(unavailable).code).toBe('render-feature-preparation-failed');
+    expect(resolveCalls).toBe(0);
+
+    const stale = createPreparedGraphicsResolver({ ...base, generation: 4 }).resolve(pipelineRef);
+    expect(stale.ok).toBe(false);
+    const staleError = failure(stale);
+    expect(staleError.code).toBe('render-feature-prepared-state-mismatch');
+    expect(staleError.detail?.reason).toBe('generation-mismatch');
+    expect(resolveCalls).toBe(0);
+
+    const forged = createPreparedGraphicsResolver(base).resolve({
+      kind: 'pipeline',
+      generation: 3,
+    });
+    expect(forged.ok).toBe(false);
+    const forgedError = failure(forged);
+    expect(forgedError.code).toBe('render-feature-prepared-state-mismatch');
+    expect(forgedError.detail?.reason).toBe('missing-prepared-state');
+    expect(resolveCalls).toBe(0);
+
+    const failed = createPreparedGraphicsResolver({
+      ...base,
+      resolvePipeline: () => {
+        resolveCalls += 1;
+        return ok(undefined as never);
+      },
+    }).resolve(pipelineRef);
+    expect(failed.ok).toBe(false);
+    expect(failure(failed).code).toBe('render-feature-preparation-failed');
+    expect(resolveCalls).toBe(1);
+  });
+
+  it('preserves asynchronous pipeline warm-up as the graph-level pending reason', async () => {
+    const currentDevice = await device();
+    const store = createPreparedGraphicsStore();
+    const transaction = store.beginFrame('resolver.warmup', 5);
+    const pipeline = transaction.prepare('pipeline', 'forward', {
+      shader: 'synthetic::forward',
+      vertexLayout: 'position',
+      colorFormats: ['rgba8unorm'],
+    });
+    expect(transaction.commit().ok).toBe(true);
+    const lookup = resultMap(store.snapshot('resolver.warmup').items);
+
+    const pending = createPreparedGraphicsResolver({
+      device: currentDevice,
+      generation: 5,
+      capabilityAvailable: true,
+      lookup: (ref) => lookup.get(ref),
+      resolvePipeline: () =>
+        err(
+          new RhiError({
+            code: 'rhi-not-available',
+            expected: 'asynchronous shader module warm-up to finish',
+            hint: 'retry on the next frame',
+          }),
+        ),
+      resolveBindings: () => ok({} as BindGroup),
+    }).resolve(pipeline.unwrap());
+
+    expect(pending.ok).toBe(false);
+    expect(failure(pending)).toMatchObject({
+      code: 'render-feature-preparation-failed',
+      detail: { reason: 'pipeline-pending' },
+    });
+  });
+});