@forgeax/engine-render 0.1.6 → 0.1.19

package/src/__tests__/renderer-frame-transaction.integration.test.ts

@@ -0,0 +1,405 @@
+import { RenderGraphBuilder } from '@forgeax/engine-render-graph';
+import { type RhiCommandEncoder, type RhiDevice, RhiError } from '@forgeax/engine-rhi';
+import { RhiNullAdapter } from '@forgeax/engine-rhi-null';
+import { err } from '@forgeax/engine-types';
+import { describe, expect, it, vi } from 'vitest';
+import { executeRendererFrameTransaction } from '../assembly/renderer-frame-transaction';
+import { DeviceScope } from '../device/device-scope';
+import { selectEnvironment } from '../environment/frame';
+import { EnvironmentLifecycle } from '../environment/lifecycle';
+import { RhiErrorListenerRegistry } from '../lifecycle';
+import type { RenderFrameState } from '../record/frame-snapshot';
+import { executeCompiledFrameGraph } from '../record/typed-frame-graph';
+import { createRenderPipelineTarget, type RenderPipelineFrame } from '../render-pipeline';
+import {
+  commitTemporalGpuSubmit,
+  getTemporalBindGroupResources,
+  getTemporalGpuState,
+  getTemporalParamsBuffer,
+  stageTemporalGpuSubmit,
+} from '../temporal/gpu';
+import { createTemporalView } from '../temporal/view';
+import { addTypedTemporalResolvePass } from '../typed-render-graph-primitives';
+
+type Stage = 'build' | 'execute' | 'finish' | 'submit';
+
+type TemporalResolveFailure = 'params' | 'bind-group' | 'pipeline';
+
+function selectedEnvironment(sourceKey?: string) {
+  return selectEnvironment({
+    environments:
+      sourceKey === undefined ? [] : [{ kind: 'image' as const, entityKey: 1, sourceKey }],
+    fogs: [],
+    suns: [],
+    lane: 'direct',
+  }).unwrap();
+}
+
+function temporalResolveFrame(
+  device: RhiDevice,
+  scope: DeviceScope,
+  frameState: RenderFrameState,
+  pipeline: object | null,
+): RenderPipelineFrame {
+  return {
+    encoder: device.createCommandEncoder({ label: 'taa-resolve-transaction' }).unwrap(),
+    pipelineState: { format: 'rgba16float', colorAttachmentFormat: 'rgba16float' },
+    runtime: {
+      device,
+      deviceScope: scope,
+      errorRegistry: { fire: () => undefined },
+      getPostProcessPipeline: () => pipeline as never,
+    },
+    frameState,
+    view: undefined as never,
+    clear: [0, 0, 0, 1],
+    targetW: 8,
+    targetH: 8,
+    currentTexture: undefined as never,
+    camera: {
+      position: [0, 0, 2] as never,
+      world: new Float32Array(16),
+      fov: 1,
+      aspect: 1,
+      near: 0.1,
+      far: 100,
+      projection: 'perspective',
+      orthoLeft: -1,
+      orthoRight: 1,
+      orthoBottom: -1,
+      orthoTop: 1,
+      tonemap: 'none',
+      exposure: 1,
+      whitePoint: 1,
+      antialias: 'taa',
+      bloom: 'off',
+      bloomThreshold: 1,
+      bloomIntensity: 1,
+      bloomBlurRadius: 1,
+      clearColor: [0, 0, 0, 1],
+      temporal: frameState.lastSuccessfulTemporalView,
+    },
+    postProcessParams: new Map(),
+    msaaActive: false,
+    geometryColorResolveView: null,
+    ldrSpriteColorView: null,
+  } as RenderPipelineFrame;
+}
+
+async function buildTemporalResolveGraph(device: RhiDevice) {
+  const graph = new RenderGraphBuilder<RenderPipelineFrame>();
+  const descriptor = (format: 'rgba8unorm' | 'rgba16float') => ({
+    format,
+    size: { width: 8, height: 8 },
+  });
+  const targets = {
+    scene: createRenderPipelineTarget(graph, 'taa-scene', descriptor('rgba16float')).unwrap(),
+    currentTemporal: createRenderPipelineTarget(
+      graph,
+      'taa-current-temporal',
+      descriptor('rgba16float'),
+    ).unwrap(),
+    depth: createRenderPipelineTarget(graph, 'taa-depth', descriptor('rgba16float')).unwrap(),
+    historyColor: createRenderPipelineTarget(
+      graph,
+      'taa-history-color',
+      descriptor('rgba16float'),
+    ).unwrap(),
+    historyTemporal: createRenderPipelineTarget(
+      graph,
+      'taa-history-temporal',
+      descriptor('rgba16float'),
+    ).unwrap(),
+    writeColor: createRenderPipelineTarget(
+      graph,
+      'taa-write-color',
+      descriptor('rgba16float'),
+    ).unwrap(),
+    writeTemporal: createRenderPipelineTarget(
+      graph,
+      'taa-write-temporal',
+      descriptor('rgba16float'),
+    ).unwrap(),
+  };
+  const seed = [
+    targets.scene,
+    targets.currentTemporal,
+    targets.historyColor,
+    targets.historyTemporal,
+  ];
+  expect(
+    graph.addRasterPass('taa-seed', {
+      accesses: seed.map(({ view }) => ({ resource: view, usage: 'color-attachment' as const })),
+      colorAttachments: seed.map(({ view }) => ({
+        view,
+        loadOp: 'clear' as const,
+        storeOp: 'store' as const,
+        clearValue: { r: 0, g: 0, b: 0, a: 0 },
+      })),
+      encode: ({ pass }) => pass.draw(3, 1, 0, 0),
+    }).ok,
+  ).toBe(true);
+  expect(addTypedTemporalResolvePass(graph, targets).ok).toBe(true);
+  return graph.compile({ device, surfaceSize: { width: 8, height: 8 } }).unwrap();
+}
+
+describe('renderer successful-submit transaction', () => {
+  it.each<Stage>([
+    'build',
+    'execute',
+    'finish',
+    'submit',
+  ])('aborts atomically at %s', (failureAt) => {
+    let submits = 0;
+    let commits = 0;
+    const before = {
+      signature: 'stable',
+      revision: 7,
+      jitter: 3,
+      previous: 'old',
+      history: 4,
+      frameIndex: 9,
+    };
+    const result = executeRendererFrameTransaction({
+      build: () =>
+        failureAt === 'build'
+          ? { ok: false, stage: 'build' as const }
+          : { ok: true, value: before },
+      execute: () =>
+        failureAt === 'execute'
+          ? { ok: false, stage: 'execute' as const }
+          : { ok: true, value: undefined },
+      finish: () =>
+        failureAt === 'finish'
+          ? { ok: false, stage: 'finish' as const }
+          : { ok: true, value: undefined },
+      submit: () => {
+        submits += 1;
+        return failureAt === 'submit'
+          ? { ok: false, stage: 'submit' as const }
+          : { ok: true, value: undefined };
+      },
+      commit: () => {
+        commits += 1;
+      },
+    });
+    expect(result).toEqual({ ok: false, error: { stage: failureAt } });
+    expect(submits).toBe(failureAt === 'submit' ? 1 : 0);
+    expect(commits).toBe(0);
+    expect(before).toEqual({
+      signature: 'stable',
+      revision: 7,
+      jitter: 3,
+      previous: 'old',
+      history: 4,
+      frameIndex: 9,
+    });
+  });
+
+  it('publishes staged Environment, Fog, and Temporal state only after submit', () => {
+    const published: string[] = [];
+    const result = executeRendererFrameTransaction({
+      build: () => ({ ok: true, value: { environment: 'env:2', fog: 'fog:2', temporal: 'taa:2' } }),
+      execute: () => ({ ok: true, value: undefined }),
+      finish: () => ({ ok: true, value: undefined }),
+      submit: () => ({ ok: true, value: undefined }),
+      commit: (candidate) =>
+        published.push(`${candidate.environment}/${candidate.fog}/${candidate.temporal}`),
+    });
+    expect(result.ok).toBe(true);
+    expect(published).toEqual(['env:2/fog:2/taa:2']);
+  });
+
+  it('rejects a missing temporal write before queue.submit and cleans the candidate', async () => {
+    const device = (await new RhiNullAdapter().requestDevice()).unwrap();
+    const scope = DeviceScope.create(91, 'renderer');
+    const frameState = {
+      temporalGpuState: undefined,
+      activeTemporalGpuState: undefined,
+      retiringTemporalGpuStates: new Set(),
+      pendingTemporalCommit: { kind: 'none' },
+      environmentGeneration: undefined,
+      environmentLifecycle: undefined,
+    } as unknown as RenderFrameState;
+    const candidate = getTemporalGpuState(frameState, device, scope, 8, 8);
+    getTemporalBindGroupResources(candidate);
+    const graphBuilder = new RenderGraphBuilder<{ readonly encoder: RhiCommandEncoder }>();
+    expect(
+      graphBuilder.addCopyPass('temporal-readiness-probe', {
+        accesses: [],
+        encode: () => undefined,
+      }).ok,
+    ).toBe(true);
+    const compiled = graphBuilder.compile({
+      device,
+      surfaceSize: { width: 8, height: 8 },
+    });
+    expect(compiled.ok).toBe(true);
+    if (!compiled.ok) return;
+    frameState.compiledFrameGraph = compiled.value;
+    const submits = vi.spyOn(device.queue, 'submit');
+    const errors = new RhiErrorListenerRegistry();
+    const result = executeCompiledFrameGraph(
+      { device, errorRegistry: errors } as never,
+      frameState,
+      {
+        encoder: device.createCommandEncoder({ label: 'temporal-readiness-probe' }).unwrap(),
+      } as unknown as RenderPipelineFrame,
+      device.createCommandEncoder({ label: 'temporal-readiness-probe-submit' }).unwrap(),
+    );
+    expect(result).toBe(false);
+    expect(submits).not.toHaveBeenCalled();
+    expect(frameState.activeTemporalGpuState).toBeUndefined();
+    expect(frameState.temporalGpuState).toBeUndefined();
+    expect(candidate.childScope.resourceDelta()).toBe(0);
+    expect(candidate.childScope.state).toBe('retired');
+  });
+
+  it.each<TemporalResolveFailure>([
+    'params',
+    'bind-group',
+    'pipeline',
+  ])('rejects a real TAA resolve when %s fails and retries atomically', async (failureAt) => {
+    const device = (await new RhiNullAdapter().requestDevice()).unwrap();
+    const scope = DeviceScope.create(92, 'renderer');
+    const environmentLifecycle = new EnvironmentLifecycle(scope);
+    const activeEnvironment = environmentLifecycle.ensure(selectedEnvironment(), 'direct').unwrap();
+    environmentLifecycle.publish(activeEnvironment);
+    const environmentFrame = selectedEnvironment('environment:candidate');
+    const environmentGeneration = environmentLifecycle.ensure(environmentFrame, 'direct').unwrap();
+    const discardEnvironment = vi.spyOn(environmentLifecycle, 'discard');
+    const publishEnvironment = vi.spyOn(environmentLifecycle, 'publish');
+    const lastSuccessfulTemporalView = createTemporalView({
+      antialias: 'taa',
+      width: 4,
+      height: 4,
+      frameIndex: 6,
+      historyValid: true,
+    });
+    const frameState = {
+      temporalGpuState: undefined,
+      activeTemporalGpuState: undefined,
+      retiringTemporalGpuStates: new Set(),
+      pendingTemporalCommit: {
+        kind: 'taa',
+        view: createTemporalView({
+          antialias: 'taa',
+          width: 4,
+          height: 4,
+          frameIndex: 6,
+          historyValid: true,
+        }),
+      },
+      environmentGeneration,
+      environmentLifecycle,
+      successfulTemporalFrameIndex: 7,
+      lastSuccessfulTemporalView,
+    } as unknown as RenderFrameState;
+    const active = getTemporalGpuState(frameState, device, scope, 4, 4);
+    getTemporalBindGroupResources(active);
+    getTemporalParamsBuffer(active);
+    stageTemporalGpuSubmit(active);
+    expect(commitTemporalGpuSubmit(active)).toBe(true);
+    frameState.lastSuccessfulTemporalView = lastSuccessfulTemporalView;
+    frameState.activeTemporalGpuState = active;
+    frameState.temporalGpuState = undefined;
+    const candidate = getTemporalGpuState(frameState, device, scope, 8, 8);
+    getTemporalBindGroupResources(candidate);
+    getTemporalParamsBuffer(candidate);
+    const graph = await buildTemporalResolveGraph(device);
+    frameState.compiledFrameGraph = graph;
+
+    const failure = new RhiError({
+      code: 'webgpu-runtime-error',
+      expected: `TAA ${failureAt} operation succeeds`,
+      hint: 'repair the injected operation and retry the same frame',
+    });
+    const writeBuffer = vi.spyOn(device.queue, 'writeBuffer');
+    const createBindGroup = vi.spyOn(device, 'createBindGroup');
+    if (failureAt === 'params') {
+      const originalWriteBuffer = device.queue.writeBuffer;
+      writeBuffer.mockImplementation((buffer, offset, data, dataOffset, size) => {
+        if (buffer === candidate.paramsBuffer) return err(failure);
+        return originalWriteBuffer.call(device.queue, buffer, offset, data, dataOffset, size);
+      });
+    }
+    if (failureAt === 'bind-group') createBindGroup.mockReturnValue(err(failure));
+    const errors = new RhiErrorListenerRegistry();
+    const observed: unknown[] = [];
+    errors.add((error) => observed.push(error));
+    const submits = vi.spyOn(device.queue, 'submit');
+    const failedFrame = temporalResolveFrame(
+      device,
+      scope,
+      frameState,
+      failureAt === 'pipeline' ? null : {},
+    );
+    const failed = executeCompiledFrameGraph(
+      { device, errorRegistry: errors } as never,
+      frameState,
+      failedFrame,
+      failedFrame.encoder,
+    );
+    expect(failed).toBe(false);
+    expect(submits).not.toHaveBeenCalled();
+    expect(observed[0]).toMatchObject({ code: 'pass-encode-failed' });
+    const cause = (observed[0] as { detail?: { cause?: unknown } }).detail?.cause;
+    expect(cause).toBeInstanceOf(RhiError);
+    expect(cause).toMatchObject({
+      expected:
+        failureAt === 'params'
+          ? 'TAA resolve params upload succeeds'
+          : failureAt === 'bind-group'
+            ? 'TAA resolve bind group creation succeeds'
+            : 'TAA resolve pipeline is ready before frame encoding',
+    });
+    expect(frameState.activeTemporalGpuState).toBe(active);
+    expect(frameState.temporalGpuState).toBeUndefined();
+    expect(candidate.childScope.resourceDelta()).toBe(0);
+    expect(candidate.childScope.state).toBe('retired');
+    expect(frameState.successfulTemporalFrameIndex).toBe(7);
+    expect(active.childScope.state).toBe('active');
+
+    writeBuffer.mockRestore();
+    createBindGroup.mockRestore();
+    expect(frameState.environmentGeneration).toBeUndefined();
+    expect(discardEnvironment).toHaveBeenCalledTimes(1);
+    expect(publishEnvironment).not.toHaveBeenCalled();
+    expect(active.valid).toBe(true);
+    expect(active.readIndex).toBe(1);
+    expect(frameState.lastSuccessfulTemporalView).toBe(lastSuccessfulTemporalView);
+    expect(environmentLifecycle.inspect().activeSignature).toBe(activeEnvironment.signature);
+    expect(environmentLifecycle.inspect().lkgSignature).toBe(activeEnvironment.signature);
+    frameState.environmentGeneration = environmentLifecycle
+      .ensure(environmentFrame, 'direct')
+      .unwrap();
+    frameState.pendingTemporalCommit = {
+      kind: 'taa',
+      view: createTemporalView({
+        antialias: 'taa',
+        width: 8,
+        height: 8,
+        frameIndex: 7,
+        historyValid: true,
+      }),
+    };
+    const retryFrame = temporalResolveFrame(device, scope, frameState, {});
+    const retried = executeCompiledFrameGraph(
+      { device, errorRegistry: errors } as never,
+      frameState,
+      retryFrame,
+      retryFrame.encoder,
+    );
+    expect(retried).toBe(true);
+    expect(submits).toHaveBeenCalledTimes(1);
+    expect(frameState.activeTemporalGpuState).not.toBe(active);
+    expect(frameState.successfulTemporalFrameIndex).toBe(8);
+    expect(frameState.temporalGpuState).toBeUndefined();
+    expect(frameState.retiringTemporalGpuStates.size).toBe(1);
+    expect(publishEnvironment).toHaveBeenCalledTimes(1);
+    expect(discardEnvironment).toHaveBeenCalledTimes(1);
+    active.childScope.retire();
+    frameState.activeTemporalGpuState?.childScope.retire();
+    scope.dispose();
+  });
+});

package/src/__tests__/renderer-lifecycle.integration.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'vitest';
 import { createRenderer as constructRenderer } from '../assembly/factory';
+import { executeRendererFrameTransaction } from '../assembly/renderer-frame-transaction';
 import { DeviceScope, LifecycleTransaction } from '../device/device-scope';
 import { RenderRecoveryError } from '../errors/recover';
 import { LifecycleConstructionError, type RenderError } from '../errors/render';
@@ -53,6 +54,27 @@ describe('renderer lifecycle', () => {
     expect(recoveryError.detail.receipt).toEqual(receipt);
     expect(recoveryError.hint).toContain('rebuild');
   });
+
+  it('retains the last successful state when a candidate fails', () => {
+    const state = { signature: 'env:1', revision: 1, frameIndex: 12, history: 'history:1' };
+    const result = executeRendererFrameTransaction({
+      build: () => ({
+        ok: true,
+        value: { signature: 'env:2', revision: 2, frameIndex: 13, history: 'history:2' },
+      }),
+      execute: () => ({ ok: true, value: undefined }),
+      finish: () => ({ ok: false, stage: 'finish' as const }),
+      submit: () => ({ ok: true, value: undefined }),
+      commit: (candidate) => Object.assign(state, candidate),
+    });
+    expect(result).toEqual({ ok: false, error: { stage: 'finish' } });
+    expect(state).toEqual({
+      signature: 'env:1',
+      revision: 1,
+      frameIndex: 12,
+      history: 'history:1',
+    });
+  });
 });
 
 import { rhi } from '@forgeax/engine-rhi-null';

package/src/__tests__/scene-data-catalog.unit.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from 'vitest';
+import {
+  createSceneDataCatalog,
+  SCENE_DATA_TEMPORAL_V1_SCHEMA,
+} from '../temporal/scene-data-catalog';
+
+describe('SceneDataCatalog authorization', () => {
+  it('issues a frozen sampled-read token for the active plan generation', () => {
+    const catalog = createSceneDataCatalog({
+      featureIdentity: 'taa',
+      generation: 7,
+      planIdentity: 'plan-7',
+      rgba16floatRenderable: true,
+    });
+    const result = catalog.require(SCENE_DATA_TEMPORAL_V1_SCHEMA);
+    expect(Object.isFrozen(result)).toBe(true);
+    expect(result).toMatchObject({
+      kind: 'scene-data',
+      schema: SCENE_DATA_TEMPORAL_V1_SCHEMA,
+      access: 'sampled-read',
+      format: 'rgba16float',
+      sampleCount: 1,
+      extent: 'render-resolution',
+    });
+    expect(catalog.validate(result).ok).toBe(true);
+  });
+
+  it('rejects forged, stale, foreign, and write-shaped tokens', () => {
+    const catalog = createSceneDataCatalog({
+      featureIdentity: 'taa',
+      generation: 7,
+      planIdentity: 'plan-7',
+      rgba16floatRenderable: true,
+    });
+    const foreign = createSceneDataCatalog({
+      featureIdentity: 'motion-blur',
+      generation: 7,
+      planIdentity: 'plan-7',
+      rgba16floatRenderable: true,
+    });
+    const issued = catalog.require(SCENE_DATA_TEMPORAL_V1_SCHEMA);
+
+    expect(foreign.validate(issued).ok).toBe(false);
+    expect(catalog.validate({ ...issued }).ok).toBe(false);
+    expect(catalog.validate({ ...issued, access: 'write' } as never).ok).toBe(false);
+    expect(catalog.validate(issued, 8).ok).toBe(false);
+  });
+
+  it('reports capability absence without issuing a physical target', () => {
+    const catalog = createSceneDataCatalog({
+      featureIdentity: 'taa',
+      generation: 7,
+      planIdentity: 'plan-7',
+      rgba16floatRenderable: false,
+    });
+    expect(() => catalog.require(SCENE_DATA_TEMPORAL_V1_SCHEMA)).toThrow();
+    expect(catalog.inspect().status).toBe('unavailable');
+  });
+});

package/src/__tests__/scene-data-consumer.integration.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'vitest';
+import {
+  createSceneDataCatalog,
+  type RenderFeaturePlan,
+  SCENE_DATA_TEMPORAL_V1_SCHEMA,
+  SceneDataUnavailableError,
+} from '../index';
+
+const availableOptions = {
+  featureIdentity: 'consumer::taa',
+  generation: 7,
+  planIdentity: 'consumer::taa:7',
+  lane: 'direct' as const,
+  rgba16floatRenderable: true,
+  producerPresent: true,
+  coverageComplete: true,
+};
+
+describe('public semantic scene-data consumer path', () => {
+  it('builds a sampled-only plan from the typed catalog token', () => {
+    const catalog = createSceneDataCatalog(availableOptions);
+    const target = catalog.require(SCENE_DATA_TEMPORAL_V1_SCHEMA);
+    const plan: RenderFeaturePlan = {
+      resources: [],
+      passes: [
+        {
+          kind: 'raster',
+          name: 'taa-resolve',
+          colorAttachments: [{ target: 'swapchain', loadOp: 'load', storeOp: 'store' }],
+          sampledTargets: [target],
+          draws: [],
+        },
+      ],
+    };
+
+    expect(catalog.validate(target).ok).toBe(true);
+    expect(plan.passes[0]).toMatchObject({ sampledTargets: [target] });
+    expect(catalog.inspect()).toMatchObject({
+      schema: SCENE_DATA_TEMPORAL_V1_SCHEMA,
+      status: 'available',
+      completeness: 'exact',
+    });
+    expect(JSON.stringify(plan)).not.toContain('rhi');
+  });
+
+  it('returns a bounded structured unavailable error for the recovery path', () => {
+    const catalog = createSceneDataCatalog({
+      ...availableOptions,
+      rgba16floatRenderable: false,
+      missingContributorIds: Array.from({ length: 34 }, (_, index) => `producer-${index}`),
+    });
+
+    expect(() => catalog.require(SCENE_DATA_TEMPORAL_V1_SCHEMA)).toThrow(SceneDataUnavailableError);
+    try {
+      catalog.require(SCENE_DATA_TEMPORAL_V1_SCHEMA);
+    } catch (error) {
+      expect(error).toBeInstanceOf(SceneDataUnavailableError);
+      if (error instanceof SceneDataUnavailableError) {
+        expect(error.code).toBe('scene-data-unavailable');
+        expect(error.detail.reason).toBe('capability-missing');
+        expect(error.detail.recovery).toBe('enable-capability');
+        expect(error.detail.missingContributorIds).toHaveLength(32);
+        expect(error.detail.omittedMissingContributorCount).toBe(2);
+      }
+    }
+  });
+});

package/src/__tests__/scene-data-contract.test-d.ts

@@ -0,0 +1,35 @@
+import { expectTypeOf } from 'vitest';
+import type { RenderFeaturePlan, RenderFeaturePlanContext, SceneDataTarget } from '../index';
+import { SCENE_DATA_TEMPORAL_V1_SCHEMA, type SceneDataSchemaId } from '../temporal/scene-data';
+
+declare const context: RenderFeaturePlanContext;
+const target = context.sceneData.require(SCENE_DATA_TEMPORAL_V1_SCHEMA);
+
+expectTypeOf(target).toEqualTypeOf<SceneDataTarget<typeof SCENE_DATA_TEMPORAL_V1_SCHEMA>>();
+expectTypeOf<SceneDataSchemaId>().toEqualTypeOf<typeof SCENE_DATA_TEMPORAL_V1_SCHEMA>();
+expectTypeOf(context.sceneData).toHaveProperty('require');
+
+const plan: RenderFeaturePlan = {
+  resources: [],
+  passes: [
+    {
+      kind: 'raster',
+      name: 'temporal-consumer',
+      colorAttachments: [{ target: 'scene-color', loadOp: 'load', storeOp: 'store' }],
+      sampledTargets: [target],
+      draws: [],
+    },
+  ],
+};
+
+void plan;
+
+const sampledRead = { target };
+void sampledRead;
+
+// @ts-expect-error unknown schema ids are not part of the closed v1 contract
+context.sceneData.require('forgeax::scene-data::unknown-v1');
+
+// @ts-expect-error a scene-data token is not a render attachment target
+const attachmentTarget: 'scene-color' = target;
+void attachmentTarget;

package/src/__tests__/scene-data-inspection.unit.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest';
+import {
+  createSceneDataCatalog,
+  SCENE_DATA_TEMPORAL_V1_SCHEMA,
+} from '../temporal/scene-data-catalog';
+
+describe('SceneData inspection', () => {
+  it('serializes bounded schema and availability facts only', () => {
+    const catalog = createSceneDataCatalog({
+      featureIdentity: 'taa',
+      generation: 3,
+      planIdentity: 'plan-3',
+      rgba16floatRenderable: true,
+      missingContributorIds: Array.from({ length: 40 }, (_, index) => `contributor-${index}`),
+    });
+    const inspection = catalog.inspect();
+    expect(inspection.schema).toBe(SCENE_DATA_TEMPORAL_V1_SCHEMA);
+    expect(inspection.missingContributorIds).toHaveLength(32);
+    expect(inspection.omittedMissingContributorCount).toBe(8);
+    expect(JSON.stringify(inspection)).not.toMatch(/graph|rhi|g-buffer|raw/i);
+  });
+
+  it('keeps the unavailable reason closed for exhaustive consumers', () => {
+    const catalog = createSceneDataCatalog({
+      featureIdentity: 'taa',
+      generation: 3,
+      planIdentity: 'plan-3',
+      rgba16floatRenderable: false,
+    });
+    const inspection = catalog.inspect();
+    if (inspection.status === 'unavailable') {
+      switch (inspection.reason) {
+        case 'capability-missing':
+        case 'producer-missing':
+        case 'coverage-incomplete':
+        case 'renderer-recovering':
+          break;
+      }
+    }
+  });
+});

package/src/__tests__/scene-data-public-surface.test-d.ts

@@ -0,0 +1,34 @@
+import { expectTypeOf } from 'vitest';
+import {
+  type RenderFeaturePlan,
+  SCENE_DATA_TEMPORAL_V1_SCHEMA,
+  type SceneDataTarget,
+  type SceneDataUnavailableDetail,
+  SceneDataUnavailableError,
+} from '../index';
+
+expectTypeOf(SCENE_DATA_TEMPORAL_V1_SCHEMA).toEqualTypeOf<'forgeax::scene-data::temporal-v1'>();
+expectTypeOf(SceneDataUnavailableError).toMatchTypeOf<
+  new (
+    detail: SceneDataUnavailableDetail,
+  ) => SceneDataUnavailableError
+>();
+
+const target = {} as SceneDataTarget;
+const plan: RenderFeaturePlan = {
+  resources: [],
+  passes: [
+    {
+      kind: 'raster',
+      name: 'taa',
+      colorAttachments: [],
+      sampledTargets: [target],
+      draws: [],
+    },
+  ],
+};
+void plan;
+
+// @ts-expect-error The public target is opaque and cannot be forged structurally.
+const forgedTarget: SceneDataTarget = {};
+void forgedTarget;