@forgeax/engine-rhi 0.1.2

package/src/__tests__/canvasContext.test-d.ts

@@ -0,0 +1,106 @@
+// w19 - RhiSurface + RhiCanvasContext type-level contract test (TDD red).
+//
+// Locks M3 CanvasContext surface (plan-tasks w19 / requirements IN-4 / AC-04;
+// plan-strategy K-4):
+//   RhiSurface — abstraction wrapping HTMLCanvasElement / OffscreenCanvas
+//   RhiCanvasContext.configure(desc): Result<void, RhiError>
+//   RhiCanvasContext.unconfigure(): void  (spec literal void return)
+//   RhiCanvasContext.getConfiguration(): CanvasConfiguration | undefined
+//   RhiCanvasContext.getCurrentTexture(): Result<Texture, RhiError> (K-4)
+//
+//   CanvasConfiguration = Pick<GPUCanvasConfiguration,
+//     'device' | 'format' | 'usage' | 'viewFormats' | 'colorSpace' |
+//     'toneMapping' | 'alphaMode'> (7 fields per spec §3.2)
+//
+// Red expected: tsc -b fails with TS2305 / TS2339 (missing RhiSurface /
+// RhiCanvasContext / CanvasConfiguration). Turns green after w21 ships.
+//
+// K-4 decision: getCurrentTexture returns Result<Texture, RhiError> (NOT
+// TextureView) — spec literal alignment; AI users go two-step:
+//   const tex = (canvasContext.getCurrentTexture()).unwrap();
+//   const view = device.createTextureView(tex, {}).unwrap();
+//
+// Anchors: requirements §IN-4 / §AC-04; research §3.1 4 methods + §3.2 7
+//          fields; plan-strategy §2 K-4 + §6 M3 + K-10.
+
+import { describe, expectTypeOf, it } from 'vitest';
+import type {
+  CanvasConfiguration,
+  Result,
+  RhiCanvasContext,
+  RhiError,
+  RhiSurface,
+  Texture,
+} from '../index';
+
+describe('w19 type-level - RhiSurface abstraction', () => {
+  it('RhiSurface is an abstraction over canvas surface (brand-only opaque)', () => {
+    // RhiSurface wraps HTMLCanvasElement / OffscreenCanvas; the abstraction
+    // is opaque from the AI-user perspective (spec couples context to canvas).
+    const s = {} as RhiSurface;
+    // @ts-expect-error MVP: RhiSurface is opaque; raw fields not exposed.
+    s.getContext;
+  });
+});
+
+describe('w19 type-level - CanvasConfiguration field set === Pick<GPUCanvasConfiguration, ...> (research §3.2 7 fields)', () => {
+  it('has exactly the 7 spec keys (device / format / usage / viewFormats / colorSpace / toneMapping / alphaMode)', () => {
+    type ExpectedKeys =
+      | 'device'
+      | 'format'
+      | 'usage'
+      | 'viewFormats'
+      | 'colorSpace'
+      | 'toneMapping'
+      | 'alphaMode';
+    expectTypeOf<keyof CanvasConfiguration>().toEqualTypeOf<ExpectedKeys>();
+  });
+
+  it('format is a GPUTextureFormat (forgeax form preserves spec field type)', () => {
+    type FormatField = NonNullable<CanvasConfiguration['format']>;
+    type SpecFormat = NonNullable<GPUCanvasConfiguration['format']>;
+    expectTypeOf<FormatField>().toEqualTypeOf<SpecFormat>();
+  });
+});
+
+describe('w19 type-level - RhiCanvasContext.configure signature', () => {
+  it('takes CanvasConfiguration and returns Result<void, RhiError>', () => {
+    type Sig = RhiCanvasContext['configure'];
+    type Ret = ReturnType<Sig>;
+    expectTypeOf<Ret>().toEqualTypeOf<Result<void, RhiError>>();
+    type Params = Parameters<Sig>;
+    expectTypeOf<Params>().toEqualTypeOf<[desc: CanvasConfiguration]>();
+  });
+});
+
+describe('w19 type-level - RhiCanvasContext.unconfigure signature (spec void return)', () => {
+  it('takes no arguments and returns void (spec literal alignment)', () => {
+    type Sig = RhiCanvasContext['unconfigure'];
+    type Ret = ReturnType<Sig>;
+    expectTypeOf<Ret>().toEqualTypeOf<void>();
+    type Params = Parameters<Sig>;
+    expectTypeOf<Params>().toEqualTypeOf<[]>();
+  });
+});
+
+describe('w19 type-level - RhiCanvasContext.getConfiguration signature', () => {
+  it('returns CanvasConfiguration | undefined (feature-detection entry)', () => {
+    type Sig = RhiCanvasContext['getConfiguration'];
+    type Ret = ReturnType<Sig>;
+    expectTypeOf<Ret>().toEqualTypeOf<CanvasConfiguration | undefined>();
+  });
+});
+
+describe('w19 type-level - RhiCanvasContext.getCurrentTexture signature (K-4)', () => {
+  it('returns Result<Texture, RhiError> (K-4: Texture brand, NOT TextureView)', () => {
+    type Sig = RhiCanvasContext['getCurrentTexture'];
+    type Ret = ReturnType<Sig>;
+    expectTypeOf<Ret>().toEqualTypeOf<Result<Texture, RhiError>>();
+  });
+
+  it('takes no arguments', () => {
+    type Sig = RhiCanvasContext['getCurrentTexture'];
+    type Params = Parameters<Sig>;
+    expectTypeOf<Params>().toEqualTypeOf<[]>();
+  });
+});

package/src/__tests__/caps-three-way.unit.test.ts

@@ -0,0 +1,144 @@
+// caps-three-way.unit.test.ts — M4 w23 (green after w25).
+//
+// Verifies the three-way texture compression cap contract on RhiCaps.
+// D-8: caps fields are derived from GPUAdapter.features Set via has(...).
+//
+// Scenarios:
+//   (a) bc-only  → textureCompressionBc=true, etc2/astc=false
+//   (b) etc2+astc → etc2/astc true, bc false
+//   (c) no compression → three-way all false
+//   (d) rhi-null → three-way all false (AC-06)
+
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import type { RhiCaps } from '../index';
+
+// ============================================================================
+// Type-level: RhiCaps has the three fields as readonly boolean
+// ============================================================================
+
+describe('RhiCaps — three-way texture compression (w25)', () => {
+  it('textureCompressionBc is readonly boolean', () => {
+    expectTypeOf<RhiCaps['textureCompressionBc']>().toEqualTypeOf<boolean>();
+  });
+
+  it('textureCompressionEtc2 is readonly boolean', () => {
+    expectTypeOf<RhiCaps['textureCompressionEtc2']>().toEqualTypeOf<boolean>();
+  });
+
+  it('textureCompressionAstc is readonly boolean', () => {
+    expectTypeOf<RhiCaps['textureCompressionAstc']>().toEqualTypeOf<boolean>();
+  });
+
+  it('textureCompressionBc/Etc2/Astc are readonly', () => {
+    type Check = {
+      readonly textureCompressionBc: boolean;
+      readonly textureCompressionEtc2: boolean;
+      readonly textureCompressionAstc: boolean;
+    };
+    expectTypeOf<
+      Pick<RhiCaps, 'textureCompressionBc' | 'textureCompressionEtc2' | 'textureCompressionAstc'>
+    >().toEqualTypeOf<Check>();
+  });
+
+  it('three fields are camelCase per D-8', () => {
+    const keys = [
+      'textureCompressionBc',
+      'textureCompressionEtc2',
+      'textureCompressionAstc',
+    ] as const;
+    for (const k of keys) {
+      expect(k).toMatch(/^textureCompression[A-Z]/);
+    }
+  });
+});
+
+// ============================================================================
+// Scenario tests: mock the Derive-from-features contract
+// ============================================================================
+
+/** Simulates Derive: given a Set of GPUFeatureName strings, produce the three caps. */
+function deriveThreeWayCaps(features: ReadonlySet<string>): {
+  textureCompressionBc: boolean;
+  textureCompressionEtc2: boolean;
+  textureCompressionAstc: boolean;
+} {
+  return {
+    textureCompressionBc: features.has('texture-compression-bc'),
+    textureCompressionEtc2: features.has('texture-compression-etc2'),
+    textureCompressionAstc: features.has('texture-compression-astc'),
+  };
+}
+
+describe('RhiCaps three-way — derive from features Set (Derive principle, D-8)', () => {
+  it('(a) bc-only: textureCompressionBc=true, etc2/astc=false', () => {
+    const caps = deriveThreeWayCaps(new Set(['texture-compression-bc']));
+    expect(caps.textureCompressionBc).toBe(true);
+    expect(caps.textureCompressionEtc2).toBe(false);
+    expect(caps.textureCompressionAstc).toBe(false);
+  });
+
+  it('(b) etc2-only: textureCompressionEtc2=true, bc/astc=false', () => {
+    const caps = deriveThreeWayCaps(new Set(['texture-compression-etc2']));
+    expect(caps.textureCompressionBc).toBe(false);
+    expect(caps.textureCompressionEtc2).toBe(true);
+    expect(caps.textureCompressionAstc).toBe(false);
+  });
+
+  it('(b-2) astc-only: textureCompressionAstc=true, bc/etc2=false', () => {
+    const caps = deriveThreeWayCaps(new Set(['texture-compression-astc']));
+    expect(caps.textureCompressionBc).toBe(false);
+    expect(caps.textureCompressionEtc2).toBe(false);
+    expect(caps.textureCompressionAstc).toBe(true);
+  });
+
+  it('(c) no compression features: three-way all false', () => {
+    const caps = deriveThreeWayCaps(new Set(['timestamp-query']));
+    expect(caps.textureCompressionBc).toBe(false);
+    expect(caps.textureCompressionEtc2).toBe(false);
+    expect(caps.textureCompressionAstc).toBe(false);
+    // Also works with empty set
+    const capsEmpty = deriveThreeWayCaps(new Set());
+    expect(capsEmpty.textureCompressionBc).toBe(false);
+    expect(capsEmpty.textureCompressionEtc2).toBe(false);
+    expect(capsEmpty.textureCompressionAstc).toBe(false);
+  });
+
+  it('(d) rhi-null contract: three-way all false (AC-06)', () => {
+    // rhi-null backend has no real GPU; its caps must truthfully report false.
+    // Verified here as the contract; actual null device verification is in w26.
+    const caps = deriveThreeWayCaps(new Set());
+    expect(caps.textureCompressionBc).toBe(false);
+    expect(caps.textureCompressionEtc2).toBe(false);
+    expect(caps.textureCompressionAstc).toBe(false);
+  });
+
+  it('bc+etc2+astc co-exist: all three true (e.g. Apple Silicon dual HW)', () => {
+    const caps = deriveThreeWayCaps(
+      new Set(['texture-compression-bc', 'texture-compression-etc2', 'texture-compression-astc']),
+    );
+    expect(caps.textureCompressionBc).toBe(true);
+    expect(caps.textureCompressionEtc2).toBe(true);
+    expect(caps.textureCompressionAstc).toBe(true);
+  });
+});
+
+// ============================================================================
+// Breaking: old textureCompression must be absent from RhiCaps after w25
+// ============================================================================
+
+describe('RhiCaps — old field removed (breaking, no compat alias)', () => {
+  it('old textureCompression single boolean is no longer a key of RhiCaps', () => {
+    // Type-level: 'textureCompression' extends keyof RhiCaps? must be false.
+    type HasOldTextureCompression = 'textureCompression' extends keyof RhiCaps ? true : false;
+    expectTypeOf<HasOldTextureCompression>().toEqualTypeOf<false>();
+  });
+
+  it('old name is not among the three-way keys', () => {
+    const threeWayKeys = [
+      'textureCompressionBc',
+      'textureCompressionEtc2',
+      'textureCompressionAstc',
+    ] as const;
+    expect(threeWayKeys).not.toContain('textureCompression');
+  });
+});

package/src/__tests__/caps.test-d.ts

@@ -0,0 +1,83 @@
+// Type-level — RhiCaps capability layer field-set + readonly boolean shape.
+//
+// Baseline fields (round 1 + rhi-resource-creation + M4 three-way caps):
+//   1) compute / 2) timestampQuery / 3) indirectDrawing
+//   4-6) textureCompressionBc / textureCompressionEtc2 / textureCompressionAstc
+//     (M4 breaking change: single textureCompression boolean replaced with
+//      three-way per-compression-format caps, derived from adapter.features)
+//   7) multiDrawIndirect (reserved) / 8) pushConstants (reserved) /
+//   9) textureBindingArray (reserved)
+//
+// Extended in feat-20260511-rhi-spec-realign-aggressive w2 (red) ->
+// w7 (green) per plan-strategy D-P3 + requirements AC-05 + research R-03 §3.1
+// 4-field mapping matrix:
+//  10) samplerAliasing       — spec mandatory; both backends true
+//  11) firstInstanceIndirect — gated by 'indirect-first-instance' feature
+//  12) storageBuffer         — limits.maxStorageBuffersPerShaderStage > 0
+//  13) storageTexture        — limits.maxStorageTexturesPerShaderStage > 0
+//
+// 3 reserved fields (#7/#8/#9) JSDoc wording amended in w8 from
+// `@reserved-for-wgpu-wasm` to `@reserved-for-wgpu-native-only` (AC-06): on
+// the browser path both rhi-webgpu and rhi-wgpu wasm always return false; only
+// wgpu native (Tauri / native runtime) flips them.
+//
+// charter mapping: proposition 4 (explicit failure — caps.X = false is a
+// signal, not an exception) + proposition 5 (consistent abstraction —
+// browsers + native share one cap surface, differences are discoverable not
+// hidden).
+
+import { describe, expectTypeOf, it } from 'vitest';
+import type { RhiCaps } from '../index';
+
+describe('RhiCaps — field shape', () => {
+  it('contains baseline boolean fields', () => {
+    expectTypeOf<RhiCaps['compute']>().toEqualTypeOf<boolean>();
+    expectTypeOf<RhiCaps['timestampQuery']>().toEqualTypeOf<boolean>();
+    expectTypeOf<RhiCaps['indirectDrawing']>().toEqualTypeOf<boolean>();
+    expectTypeOf<RhiCaps['textureCompressionBc']>().toEqualTypeOf<boolean>();
+    expectTypeOf<RhiCaps['textureCompressionEtc2']>().toEqualTypeOf<boolean>();
+    expectTypeOf<RhiCaps['textureCompressionAstc']>().toEqualTypeOf<boolean>();
+    expectTypeOf<RhiCaps['multiDrawIndirect']>().toEqualTypeOf<boolean>();
+    expectTypeOf<RhiCaps['pushConstants']>().toEqualTypeOf<boolean>();
+    expectTypeOf<RhiCaps['textureBindingArray']>().toEqualTypeOf<boolean>();
+  });
+
+  it('contains D-P3 boolean fields (samplerAliasing / firstInstanceIndirect / storageBuffer / storageTexture)', () => {
+    expectTypeOf<RhiCaps['samplerAliasing']>().toEqualTypeOf<boolean>();
+    expectTypeOf<RhiCaps['firstInstanceIndirect']>().toEqualTypeOf<boolean>();
+    expectTypeOf<RhiCaps['storageBuffer']>().toEqualTypeOf<boolean>();
+    expectTypeOf<RhiCaps['storageTexture']>().toEqualTypeOf<boolean>();
+  });
+
+  // feat-20260612-hdrp-deferred-shading-learn-render-5-8 M1 / w2:
+  // RhiCaps.maxColorAttachments field existence + type = number.
+  it('contains maxColorAttachments: number field', () => {
+    expectTypeOf<RhiCaps['maxColorAttachments']>().toEqualTypeOf<number>();
+  });
+
+  it('maxColorAttachments is readonly', () => {
+    type Check = { readonly maxColorAttachments: number };
+    expectTypeOf<Pick<RhiCaps, 'maxColorAttachments'>>().toEqualTypeOf<Check>();
+  });
+
+  it('all fields are readonly', () => {
+    type ReadonlyKeys = {
+      readonly compute: boolean;
+      readonly timestampQuery: boolean;
+      readonly timestampPeriodNanoseconds: number | null;
+      readonly indirectDrawing: boolean;
+      readonly textureCompressionBc: boolean;
+      readonly textureCompressionEtc2: boolean;
+      readonly textureCompressionAstc: boolean;
+      readonly multiDrawIndirect: boolean;
+      readonly pushConstants: boolean;
+      readonly textureBindingArray: boolean;
+      readonly samplerAliasing: boolean;
+      readonly firstInstanceIndirect: boolean;
+      readonly storageBuffer: boolean;
+      readonly storageTexture: boolean;
+      readonly maxColorAttachments: number;
+    };
+    expectTypeOf<RhiCaps>().toMatchTypeOf<ReadonlyKeys>();
+  });
+});

package/src/__tests__/command-encoder-spec-alignment.test-d.ts

@@ -0,0 +1,117 @@
+// w2 type-level - RhiCommandEncoder spec method-set alignment with
+// `@webgpu/types` GPUCommandEncoder (research F-1 / plan-strategy D-S4).
+//
+// Asserts (will be RED until w3 lands the impl):
+// - 12 spec methods (9 direct + 3 GPUDebugCommandsMixin) exist on RhiCommandEncoder
+// - `copyBufferToBuffer` exposes both spec overloads (3-arg shorthand + 5-arg full form)
+// - `finish()` returns Result<CommandBuffer, RhiError>
+// - method NAMES align byte-for-byte with `@webgpu/types` GPUCommandEncoder
+//
+// Charter mapping: proposition 1 (progressive disclosure) + proposition 3
+// (machine-readable union > prose) + proposition 5 (consistent abstraction).
+
+import { describe, expectTypeOf, it } from 'vitest';
+import type {
+  Buffer,
+  CommandBuffer,
+  QuerySet,
+  Result,
+  RhiCommandEncoder,
+  RhiError,
+} from '../index';
+
+describe('w2 - RhiCommandEncoder spec method set (12 methods)', () => {
+  it('exposes beginRenderPass(desc): RhiRenderPassEncoder', () => {
+    expectTypeOf<RhiCommandEncoder['beginRenderPass']>().toBeFunction();
+  });
+
+  it('exposes beginComputePass(desc?): RhiComputePassEncoder', () => {
+    expectTypeOf<RhiCommandEncoder['beginComputePass']>().toBeFunction();
+  });
+
+  it('exposes copyBufferToBuffer (5-arg full form per spec)', () => {
+    // 5-arg overload must be callable (research F-1 finding):
+    //   copyBufferToBuffer(src, srcOffset, dst, dstOffset, size): void
+    type FullForm = (
+      source: Buffer,
+      sourceOffset: number,
+      destination: Buffer,
+      destinationOffset: number,
+      size: number,
+    ) => void;
+    type CallSignature5 = RhiCommandEncoder['copyBufferToBuffer'] extends FullForm ? true : false;
+    expectTypeOf<CallSignature5>().toEqualTypeOf<true>();
+  });
+
+  it('exposes copyBufferToBuffer (3-arg shorthand overload per spec)', () => {
+    // 3-arg overload (size optional):
+    //   copyBufferToBuffer(src, dst, size?): void
+    type Shorthand = (source: Buffer, destination: Buffer, size?: number | undefined) => void;
+    type CallSignature3 = RhiCommandEncoder['copyBufferToBuffer'] extends Shorthand ? true : false;
+    expectTypeOf<CallSignature3>().toEqualTypeOf<true>();
+  });
+
+  it('exposes copyBufferToTexture(source, destination, copySize)', () => {
+    expectTypeOf<RhiCommandEncoder['copyBufferToTexture']>().toBeFunction();
+  });
+
+  it('exposes copyTextureToBuffer(source, destination, copySize)', () => {
+    expectTypeOf<RhiCommandEncoder['copyTextureToBuffer']>().toBeFunction();
+  });
+
+  it('exposes copyTextureToTexture(source, destination, copySize)', () => {
+    expectTypeOf<RhiCommandEncoder['copyTextureToTexture']>().toBeFunction();
+  });
+
+  it('exposes clearBuffer(buffer, offset?, size?)', () => {
+    type Method = RhiCommandEncoder['clearBuffer'];
+    expectTypeOf<Method>().toBeFunction();
+    type Expected = (
+      buffer: Buffer,
+      offset?: number | undefined,
+      size?: number | undefined,
+    ) => void;
+    expectTypeOf<Expected>().toMatchTypeOf<Method>();
+  });
+
+  it('exposes resolveQuerySet (capability-gated placeholder per D-S4)', () => {
+    type Method = RhiCommandEncoder['resolveQuerySet'];
+    expectTypeOf<Method>().toBeFunction();
+    type Expected = (
+      querySet: QuerySet,
+      firstQuery: number,
+      queryCount: number,
+      destination: Buffer,
+      destinationOffset: number,
+    ) => Result<void, RhiError>;
+    expectTypeOf<Expected>().toMatchTypeOf<Method>();
+  });
+
+  it('exposes pushDebugGroup(label) (GPUDebugCommandsMixin)', () => {
+    expectTypeOf<RhiCommandEncoder['pushDebugGroup']>().toBeFunction();
+  });
+
+  it('exposes popDebugGroup() (GPUDebugCommandsMixin)', () => {
+    expectTypeOf<RhiCommandEncoder['popDebugGroup']>().toBeFunction();
+  });
+
+  it('exposes insertDebugMarker(label) (GPUDebugCommandsMixin)', () => {
+    expectTypeOf<RhiCommandEncoder['insertDebugMarker']>().toBeFunction();
+  });
+
+  it('finish() returns Result<CommandBuffer, RhiError>', () => {
+    expectTypeOf<RhiCommandEncoder['finish']>().returns.toEqualTypeOf<
+      Result<CommandBuffer, RhiError>
+    >();
+  });
+
+  // w38 (M5 / K-3): writeTimestamp on the CommandEncoder entry only.
+  // CPE/RPE inside-pass timestamp writes are deferred to
+  // feat-future-rhi-perf-timestamp-pass per K-3 decision.
+  it('exposes writeTimestamp(querySet, queryIndex): void (K-3 CommandEncoder-only)', () => {
+    type Method = RhiCommandEncoder['writeTimestamp'];
+    expectTypeOf<Method>().toBeFunction();
+    type Expected = (querySet: QuerySet, queryIndex: number) => void;
+    expectTypeOf<Expected>().toMatchTypeOf<Method>();
+  });
+});

package/src/__tests__/createComputePipeline.test-d.ts

@@ -0,0 +1,149 @@
+// w07 - RhiDevice.createComputePipeline type-level contract test (TDD red).
+//
+// Locks M1 createComputePipeline surface (plan-tasks w07 / requirements IN-1):
+//   RhiDevice.createComputePipeline(desc: ComputePipelineDescriptor)
+//     -> Result<ComputePipeline, RhiError>
+//
+// Field shape (research §1.2 IDL):
+//   ComputePipelineDescriptor = ExplicitUndefined<
+//     Pick<GPUComputePipelineDescriptor, 'label' | 'layout' | 'compute'>
+//   > with the spec polymorphism `(GPUAutoLayoutMode or GPUPipelineLayout)`
+//   tightened to the forgeax union `'auto' | PipelineLayout` (D-S5 pattern),
+//   and `compute.module` tightened to the forgeax `ShaderModule` opaque handle.
+//
+// Red expected: tsc -b fails with TS2724 (missing ComputePipelineDescriptor)
+// + TS2339 (createComputePipeline missing on RhiDevice). Turns green after
+// w09 ships interface + shim.
+//
+// Anchors: requirements §IN-1 / §AC-01; research §1.2 IDL + 'auto' vs
+//          explicit PipelineLayout double form; plan-strategy §4.2 + K-10.
+
+import { describe, expectTypeOf, it } from 'vitest';
+import type {
+  ComputePipeline,
+  ComputePipelineDescriptor,
+  PipelineLayout,
+  Result,
+  RhiDevice,
+  RhiError,
+  ShaderModule,
+} from '../index';
+
+/** Strip undefined from an optional field; bridges forgeax `?: T | undefined`
+ *  and spec `?: T` while comparing value types. */
+type ValueOf<T, K extends keyof T> = NonNullable<T[K]>;
+
+describe('w07 type-level - ComputePipelineDescriptor field set === Pick<GPUComputePipelineDescriptor, ...>', () => {
+  it('has exactly the keys label / layout / compute', () => {
+    type ExpectedKeys = 'label' | 'layout' | 'compute';
+    expectTypeOf<keyof ComputePipelineDescriptor>().toEqualTypeOf<ExpectedKeys>();
+  });
+
+  it('label field type aligns with spec (string | undefined)', () => {
+    type LabelForgeaX = NonNullable<ComputePipelineDescriptor['label']>;
+    type LabelSpec = NonNullable<GPUComputePipelineDescriptor['label']>;
+    expectTypeOf<LabelForgeaX>().toEqualTypeOf<LabelSpec>();
+  });
+});
+
+describe("w07 type-level - layout union 'auto' | PipelineLayout", () => {
+  it("layout: 'auto' literal is a legal assignment", () => {
+    const psm = {} as ShaderModule;
+    const _auto: ComputePipelineDescriptor = {
+      layout: 'auto',
+      compute: { module: psm },
+    };
+    void _auto;
+  });
+
+  it('layout: PipelineLayout brand is a legal assignment', () => {
+    const psm = {} as ShaderModule;
+    const pl = {} as PipelineLayout;
+    const _explicit: ComputePipelineDescriptor = {
+      layout: pl,
+      compute: { module: psm },
+    };
+    void _explicit;
+  });
+
+  it("layout type is exactly 'auto' | PipelineLayout (no spec polymorphism leak)", () => {
+    type Layout = ComputePipelineDescriptor['layout'];
+    expectTypeOf<Layout>().toEqualTypeOf<'auto' | PipelineLayout>();
+  });
+});
+
+describe('w07 type-level - compute nested dictionary mirrors GPUProgrammableStage', () => {
+  it('compute.module is the forgeax ShaderModule opaque handle (not GPUShaderModule)', () => {
+    type ModuleForgeaX = ComputePipelineDescriptor['compute']['module'];
+    expectTypeOf<ModuleForgeaX>().toEqualTypeOf<ShaderModule>();
+  });
+
+  it('compute.entryPoint is optional string | undefined', () => {
+    const psm = {} as ShaderModule;
+    const _withEntry: ComputePipelineDescriptor = {
+      layout: 'auto',
+      compute: { module: psm, entryPoint: 'cs_main' },
+    };
+    const _withoutEntry: ComputePipelineDescriptor = {
+      layout: 'auto',
+      compute: { module: psm },
+    };
+    const _explicitUndef: ComputePipelineDescriptor = {
+      layout: 'auto',
+      compute: { module: psm, entryPoint: undefined },
+    };
+    void _withEntry;
+    void _withoutEntry;
+    void _explicitUndef;
+  });
+
+  it('compute.constants is optional Record<string, number>', () => {
+    const psm = {} as ShaderModule;
+    const _withConsts: ComputePipelineDescriptor = {
+      layout: 'auto',
+      compute: { module: psm, constants: { foo: 1.0, bar: 2.5 } },
+    };
+    void _withConsts;
+  });
+});
+
+describe('w07 type-level - RhiDevice.createComputePipeline signature', () => {
+  it('returns Result<ComputePipeline, RhiError>', () => {
+    type Sig = RhiDevice['createComputePipeline'];
+    type Ret = ReturnType<Sig>;
+    expectTypeOf<Ret>().toEqualTypeOf<Result<ComputePipeline, RhiError>>();
+  });
+
+  it('takes a ComputePipelineDescriptor as the sole parameter', () => {
+    type Sig = RhiDevice['createComputePipeline'];
+    type Params = Parameters<Sig>;
+    expectTypeOf<Params>().toEqualTypeOf<[ComputePipelineDescriptor]>();
+  });
+});
+
+describe('w07 type-level - ComputePipeline opaque handle does not expose raw GPU fields', () => {
+  it('ComputePipeline is brand-only (no .gpuComputePipeline access)', () => {
+    const h = {} as ComputePipeline;
+    // @ts-expect-error MVP-1.3: ComputePipeline is opaque; raw fields not exposed.
+    h.gpuComputePipeline;
+  });
+
+  it('S-7 optional shape: label uses `?: T | undefined`', () => {
+    const psm = {} as ShaderModule;
+    const _omitted: ComputePipelineDescriptor = {
+      layout: 'auto',
+      compute: { module: psm },
+    };
+    const _explicit: ComputePipelineDescriptor = {
+      label: undefined,
+      layout: 'auto',
+      compute: { module: psm },
+    };
+    void _omitted;
+    void _explicit;
+    type LabelType = ComputePipelineDescriptor['label'];
+    expectTypeOf<NonNullable<LabelType>>().toEqualTypeOf<
+      ValueOf<GPUComputePipelineDescriptor, 'label'>
+    >();
+  });
+});

package/src/__tests__/createQuerySet.test-d.ts

@@ -0,0 +1,81 @@
+// w10 - RhiDevice.createQuerySet type-level contract test (TDD red).
+//
+// Locks M1 createQuerySet surface (plan-tasks w10 / requirements IN-1):
+//   RhiDevice.createQuerySet(desc: QuerySetDescriptor)
+//     -> Result<QuerySet, RhiError>
+//
+// Field shape (research §1.3 IDL):
+//   QuerySetDescriptor = ExplicitUndefined<
+//     Pick<GPUQuerySetDescriptor, 'label' | 'type' | 'count'>
+//   >
+//   type: 'occlusion' | 'timestamp' (closed union, GPUQueryType).
+//
+// Red expected: tsc -b fails with TS2305 (missing QuerySetDescriptor) +
+// TS2339 (createQuerySet missing on RhiDevice). Turns green after w12 ships.
+//
+// Anchors: requirements §IN-1 / §AC-01; research §1.3 IDL + Pick set;
+//          plan-strategy §4.2 + K-10.
+
+import { describe, expectTypeOf, it } from 'vitest';
+import type { QuerySet, QuerySetDescriptor, Result, RhiDevice, RhiError } from '../index';
+
+/** Strip undefined from an optional field; bridges forgeax `?: T | undefined`
+ *  and spec `?: T` while comparing value types. */
+type ValueOf<T, K extends keyof T> = NonNullable<T[K]>;
+
+describe('w10 type-level - QuerySetDescriptor field set === Pick<GPUQuerySetDescriptor, ...>', () => {
+  it('has exactly the keys label / type / count', () => {
+    type ExpectedKeys = 'label' | 'type' | 'count';
+    expectTypeOf<keyof QuerySetDescriptor>().toEqualTypeOf<ExpectedKeys>();
+  });
+
+  it('label field type aligns with spec (string | undefined)', () => {
+    type LabelForgeaX = NonNullable<QuerySetDescriptor['label']>;
+    type LabelSpec = NonNullable<GPUQuerySetDescriptor['label']>;
+    expectTypeOf<LabelForgeaX>().toEqualTypeOf<LabelSpec>();
+  });
+
+  it("type field is a closed union 'occlusion' | 'timestamp' (GPUQueryType)", () => {
+    type TypeForgeaX = ValueOf<QuerySetDescriptor, 'type'>;
+    expectTypeOf<TypeForgeaX>().toEqualTypeOf<ValueOf<GPUQuerySetDescriptor, 'type'>>();
+    // Sentinel assignment: both literal members are accepted.
+    const _occ: QuerySetDescriptor = { type: 'occlusion', count: 4 };
+    const _ts: QuerySetDescriptor = { type: 'timestamp', count: 4 };
+    void _occ;
+    void _ts;
+  });
+
+  it('count field is GPUSize32 (number)', () => {
+    type CountForgeaX = ValueOf<QuerySetDescriptor, 'count'>;
+    expectTypeOf<CountForgeaX>().toEqualTypeOf<ValueOf<GPUQuerySetDescriptor, 'count'>>();
+  });
+
+  it('S-7 optional shape: label uses `?: T | undefined`', () => {
+    const _omitted: QuerySetDescriptor = { type: 'occlusion', count: 0 };
+    const _explicit: QuerySetDescriptor = { label: undefined, type: 'occlusion', count: 0 };
+    void _omitted;
+    void _explicit;
+  });
+});
+
+describe('w10 type-level - RhiDevice.createQuerySet signature', () => {
+  it('returns Result<QuerySet, RhiError>', () => {
+    type Sig = RhiDevice['createQuerySet'];
+    type Ret = ReturnType<Sig>;
+    expectTypeOf<Ret>().toEqualTypeOf<Result<QuerySet, RhiError>>();
+  });
+
+  it('takes a QuerySetDescriptor as the sole parameter', () => {
+    type Sig = RhiDevice['createQuerySet'];
+    type Params = Parameters<Sig>;
+    expectTypeOf<Params>().toEqualTypeOf<[QuerySetDescriptor]>();
+  });
+});
+
+describe('w10 type-level - QuerySet opaque handle does not expose raw GPU fields', () => {
+  it('QuerySet is brand-only (no .gpuQuerySet access)', () => {
+    const h = {} as QuerySet;
+    // @ts-expect-error MVP-1.3: QuerySet is opaque; raw fields not exposed.
+    h.gpuQuerySet;
+  });
+});