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

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;
+  });
+});

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

@@ -0,0 +1,127 @@
+// w03 - RhiDevice.createTextureView type-level contract test (TDD red).
+//
+// Locks M1 createTextureView surface (plan-tasks w03 / requirements IN-1):
+//   RhiDevice.createTextureView(texture: Texture, desc: TextureViewDescriptor)
+//     -> Result<TextureView, RhiError>
+//
+// Field shape: TextureViewDescriptor = ExplicitUndefined<
+//   Pick<GPUTextureViewDescriptor,
+//     'format' | 'dimension' | 'usage' | 'aspect' | 'baseMipLevel' |
+//     'mipLevelCount' | 'baseArrayLayer' | 'arrayLayerCount' | 'label'
+//   >
+// >
+//
+// Red expected state: this file fails tsc -b until w06 ships
+//   (1) the `TextureViewDescriptor` type alias on `@forgeax/engine-rhi`,
+//   (2) the `RhiDevice.createTextureView` method signature.
+// Green expected state (after w06 commit): all expectTypeOf assertions pass.
+//
+// Anchors: requirements §IN-1 / §AC-01 / §AC-07(a); research §1.1 9 fields
+//          (excl swizzle feature-gate); plan-strategy §4.2 type layer + K-10;
+//          AI User Charter proposition 1 progressive disclosure +
+//          proposition 5 consistent abstraction (single createX entry).
+
+import { describe, expectTypeOf, it } from 'vitest';
+import type {
+  Result,
+  RhiDevice,
+  RhiError,
+  Texture,
+  TextureView,
+  TextureViewDescriptor,
+} 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('w03 type-level - TextureViewDescriptor field set === Pick<GPUTextureViewDescriptor, ...> (research §1.1 9 fields, swizzle excluded)', () => {
+  it('has exactly the 9 spec keys (label / format / dimension / usage / aspect / baseMipLevel / mipLevelCount / baseArrayLayer / arrayLayerCount)', () => {
+    type ExpectedKeys =
+      | 'label'
+      | 'format'
+      | 'dimension'
+      | 'usage'
+      | 'aspect'
+      | 'baseMipLevel'
+      | 'mipLevelCount'
+      | 'baseArrayLayer'
+      | 'arrayLayerCount';
+    expectTypeOf<keyof TextureViewDescriptor>().toEqualTypeOf<ExpectedKeys>();
+  });
+
+  it('format / dimension / usage value types align with spec', () => {
+    expectTypeOf<ValueOf<TextureViewDescriptor, 'format'>>().toEqualTypeOf<
+      ValueOf<GPUTextureViewDescriptor, 'format'>
+    >();
+    expectTypeOf<ValueOf<TextureViewDescriptor, 'dimension'>>().toEqualTypeOf<
+      ValueOf<GPUTextureViewDescriptor, 'dimension'>
+    >();
+    expectTypeOf<ValueOf<TextureViewDescriptor, 'usage'>>().toEqualTypeOf<
+      ValueOf<GPUTextureViewDescriptor, 'usage'>
+    >();
+  });
+
+  it('aspect / baseMipLevel / mipLevelCount / baseArrayLayer / arrayLayerCount value types align with spec', () => {
+    expectTypeOf<ValueOf<TextureViewDescriptor, 'aspect'>>().toEqualTypeOf<
+      ValueOf<GPUTextureViewDescriptor, 'aspect'>
+    >();
+    expectTypeOf<ValueOf<TextureViewDescriptor, 'baseMipLevel'>>().toEqualTypeOf<
+      ValueOf<GPUTextureViewDescriptor, 'baseMipLevel'>
+    >();
+    expectTypeOf<ValueOf<TextureViewDescriptor, 'mipLevelCount'>>().toEqualTypeOf<
+      ValueOf<GPUTextureViewDescriptor, 'mipLevelCount'>
+    >();
+    expectTypeOf<ValueOf<TextureViewDescriptor, 'baseArrayLayer'>>().toEqualTypeOf<
+      ValueOf<GPUTextureViewDescriptor, 'baseArrayLayer'>
+    >();
+    expectTypeOf<ValueOf<TextureViewDescriptor, 'arrayLayerCount'>>().toEqualTypeOf<
+      ValueOf<GPUTextureViewDescriptor, 'arrayLayerCount'>
+    >();
+  });
+
+  it('S-7 optional shape: every field uses `?: T | undefined` (omitted vs explicit-undefined both legal)', () => {
+    const _empty: TextureViewDescriptor = {};
+    const _explicit: TextureViewDescriptor = {
+      label: undefined,
+      format: undefined,
+      dimension: undefined,
+      usage: undefined,
+      aspect: undefined,
+      baseMipLevel: undefined,
+      mipLevelCount: undefined,
+      baseArrayLayer: undefined,
+      arrayLayerCount: undefined,
+    };
+    void _empty;
+    void _explicit;
+  });
+
+  it('swizzle is NOT exposed (research §1.1 OOS-MVP feature-gated)', () => {
+    type Keys = keyof TextureViewDescriptor;
+    type HasSwizzle = 'swizzle' extends Keys ? true : false;
+    expectTypeOf<HasSwizzle>().toEqualTypeOf<false>();
+  });
+});
+
+describe('w03 type-level - RhiDevice.createTextureView signature', () => {
+  it('returns Result<TextureView, RhiError>', () => {
+    type Sig = RhiDevice['createTextureView'];
+    type Ret = ReturnType<Sig>;
+    expectTypeOf<Ret>().toEqualTypeOf<Result<TextureView, RhiError>>();
+  });
+
+  it('takes (texture: Texture, desc: TextureViewDescriptor) as parameters', () => {
+    type Sig = RhiDevice['createTextureView'];
+    type Params = Parameters<Sig>;
+    expectTypeOf<Params>().toEqualTypeOf<[Texture, TextureViewDescriptor]>();
+  });
+});
+
+describe('w03 type-level - TextureView opaque handle does not expose raw GPU fields', () => {
+  it('TextureView is brand-only (no .gpuTextureView access)', () => {
+    const h = {} as TextureView;
+    // @ts-expect-error MVP-1.3: TextureView is opaque; gpuTextureView is not exposed.
+    h.gpuTextureView;
+  });
+});

package/src/__tests__/descriptor-mirror.test-d.ts

@@ -0,0 +1,284 @@
+// MVP-1.1 - 5 core descriptors mirror @webgpu/types (type-level red -> green).
+// Extended in feat-20260508-rhi-surface-completion w8 (D-S5) with 4 new
+// descriptors: CommandEncoderDescriptor / RenderPassColorAttachment /
+// RenderPassDepthStencilAttachment / RenderPassDescriptor.
+//
+// Mirror policy (decision S-7 + research F-3):
+// - Field NAMES align byte-for-byte with spec: keyof forgeax === locked key
+//   list === keyof Pick<spec, ...>.
+// - Field VALUE types (NonNullable) align with spec: forgeax[K] minus undefined
+//   === spec[K] minus undefined.
+// - Optional shape: forgeax writes `?: T | undefined` (decision S-7); spec
+//   v0.1.69 writes `?: T` (ecosystem upstream pending migration); the
+//   ExplicitUndefined mapped type bridges them, allowing
+//   `{ label: undefined }` writes (charter proposition 4: explicit failure /
+//   distinguish missing vs explicit-undefined).
+//
+// view narrow Path X (feat-20260510-rhi-resource-creation M2 / breakage point
+// #1): the `view` field on RenderPassColorAttachment /
+// RenderPassDepthStencilAttachment is NARROWED to the forgeax `TextureView`
+// brand (instead of the spec polymorphism `GPUTexture | GPUTextureView`).
+// This breaks field-type alignment but preserves field-name alignment (R12
+// lint scope). Charter proposition 5 (consistent abstraction) over
+// proposition 1 (strict spec shape) so AI users land on the single
+// constructable brand: `device.createTextureView(tex, {}).unwrap()`. The
+// earlier D-S5 tightening to `Texture` was retired with M1 of this closure.
+//
+// Related: requirements AC MVP-1.1 (5 descriptors + field-name byte-for-byte) +
+//          AC-RSC-08 (4 new descriptors + view tightening); plan-strategy 4.3
+//          key tests #1; 7 propositions 4 / 5; research F-1 / F-3 / F-7;
+//          plan-strategy 2 D-S3 / D-S5 / D-S7.
+
+import { describe, expectTypeOf, it } from 'vitest';
+import type {
+  BindGroupLayoutDescriptor,
+  BufferDescriptor,
+  CommandEncoderDescriptor,
+  PipelineLayout,
+  RenderPassColorAttachment,
+  RenderPassDepthStencilAttachment,
+  RenderPassDescriptor,
+  RenderPassTimestampWrites,
+  RenderPipelineDescriptor,
+  RenderPipelineFragmentState,
+  RenderPipelineVertexState,
+  SamplerDescriptor,
+  TextureDescriptor,
+  TextureFormat,
+  TextureView,
+} 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('MVP-1.1 - 5 descriptors mirror @webgpu/types', () => {
+  it('BufferDescriptor field set === Pick<GPUBufferDescriptor, ...>', () => {
+    type BufferKeys = 'label' | 'size' | 'usage' | 'mappedAtCreation';
+    expectTypeOf<keyof BufferDescriptor>().toEqualTypeOf<BufferKeys>();
+    expectTypeOf<ValueOf<BufferDescriptor, 'label'>>().toEqualTypeOf<
+      ValueOf<GPUBufferDescriptor, 'label'>
+    >();
+    expectTypeOf<ValueOf<BufferDescriptor, 'size'>>().toEqualTypeOf<
+      ValueOf<GPUBufferDescriptor, 'size'>
+    >();
+    expectTypeOf<ValueOf<BufferDescriptor, 'usage'>>().toEqualTypeOf<
+      ValueOf<GPUBufferDescriptor, 'usage'>
+    >();
+    expectTypeOf<ValueOf<BufferDescriptor, 'mappedAtCreation'>>().toEqualTypeOf<
+      ValueOf<GPUBufferDescriptor, 'mappedAtCreation'>
+    >();
+    // S-7: writing `{ label: undefined }` is legal under exactOptionalPropertyTypes.
+    const b: BufferDescriptor = { size: 16, usage: 0, label: undefined };
+    expectTypeOf(b).toMatchTypeOf<BufferDescriptor>();
+  });
+
+  it('TextureDescriptor field set === Pick<GPUTextureDescriptor, ...> (incl R8 Compatibility Mode)', () => {
+    type TextureKeys =
+      | 'label'
+      | 'size'
+      | 'mipLevelCount'
+      | 'sampleCount'
+      | 'dimension'
+      | 'format'
+      | 'usage'
+      | 'viewFormats'
+      | 'textureBindingViewDimension';
+    expectTypeOf<keyof TextureDescriptor>().toEqualTypeOf<TextureKeys>();
+    expectTypeOf<ValueOf<TextureDescriptor, 'format'>>().toEqualTypeOf<
+      ValueOf<GPUTextureDescriptor, 'format'>
+    >();
+    expectTypeOf<ValueOf<TextureDescriptor, 'usage'>>().toEqualTypeOf<
+      ValueOf<GPUTextureDescriptor, 'usage'>
+    >();
+    expectTypeOf<ValueOf<TextureDescriptor, 'textureBindingViewDimension'>>().toEqualTypeOf<
+      ValueOf<GPUTextureDescriptor, 'textureBindingViewDimension'>
+    >();
+    // Explicit `undefined` writes are legal (R8 Compatibility Mode follow-on).
+    const t: TextureDescriptor = {
+      size: [128, 128],
+      format: 'rgba8unorm',
+      usage: 0,
+      textureBindingViewDimension: undefined,
+    };
+    expectTypeOf(t).toMatchTypeOf<TextureDescriptor>();
+  });
+
+  it('SamplerDescriptor field set === Pick<GPUSamplerDescriptor, ...>', () => {
+    type SamplerKeys =
+      | 'label'
+      | 'addressModeU'
+      | 'addressModeV'
+      | 'addressModeW'
+      | 'magFilter'
+      | 'minFilter'
+      | 'mipmapFilter'
+      | 'lodMinClamp'
+      | 'lodMaxClamp'
+      | 'compare'
+      | 'maxAnisotropy';
+    expectTypeOf<keyof SamplerDescriptor>().toEqualTypeOf<SamplerKeys>();
+    expectTypeOf<ValueOf<SamplerDescriptor, 'compare'>>().toEqualTypeOf<
+      ValueOf<GPUSamplerDescriptor, 'compare'>
+    >();
+    expectTypeOf<ValueOf<SamplerDescriptor, 'magFilter'>>().toEqualTypeOf<
+      ValueOf<GPUSamplerDescriptor, 'magFilter'>
+    >();
+  });
+
+  it('BindGroupLayoutDescriptor field set === Pick<GPUBindGroupLayoutDescriptor, ...>', () => {
+    type BglKeys = 'label' | 'entries';
+    expectTypeOf<keyof BindGroupLayoutDescriptor>().toEqualTypeOf<BglKeys>();
+    expectTypeOf<ValueOf<BindGroupLayoutDescriptor, 'entries'>>().toEqualTypeOf<
+      ValueOf<GPUBindGroupLayoutDescriptor, 'entries'>
+    >();
+  });
+
+  it('RenderPipelineDescriptor field set === Pick<GPURenderPipelineDescriptor, ...>', () => {
+    type RppKeys =
+      | 'label'
+      | 'layout'
+      | 'vertex'
+      | 'primitive'
+      | 'depthStencil'
+      | 'multisample'
+      | 'fragment';
+    expectTypeOf<keyof RenderPipelineDescriptor>().toEqualTypeOf<RppKeys>();
+    expectTypeOf<
+      ValueOf<RenderPipelineDescriptor, 'vertex'>
+    >().toEqualTypeOf<RenderPipelineVertexState>();
+    expectTypeOf<
+      ValueOf<RenderPipelineDescriptor, 'fragment'>
+    >().toEqualTypeOf<RenderPipelineFragmentState>();
+    expectTypeOf<ValueOf<RenderPipelineDescriptor, 'layout'>>().toEqualTypeOf<
+      'auto' | PipelineLayout
+    >();
+  });
+});
+
+describe('M4 RHI descriptor mirror', () => {
+  it('uses the spec TextureFormat union for texture descriptors', () => {
+    expectTypeOf<NonNullable<TextureDescriptor['format']>>().toEqualTypeOf<TextureFormat>();
+    const invalid: TextureDescriptor = {
+      // @ts-expect-error -- RHI descriptors reject arbitrary format strings.
+      format: 'not-a-texture-format',
+      size: { width: 1, height: 1 },
+      usage: 0,
+    };
+    void invalid;
+  });
+});
+
+// w8: 4 new descriptors (D-S5) - field NAMES align byte-for-byte with spec;
+// the `view` field TYPE is tightened to `Texture` (spec has
+// `GPUTexture | GPUTextureView`).
+describe('w8 - 4 new descriptors mirror @webgpu/types (D-S5)', () => {
+  it('CommandEncoderDescriptor field set === Pick<GPUCommandEncoderDescriptor, label>', () => {
+    type CmdKeys = 'label';
+    expectTypeOf<keyof CommandEncoderDescriptor>().toEqualTypeOf<CmdKeys>();
+    expectTypeOf<ValueOf<CommandEncoderDescriptor, 'label'>>().toEqualTypeOf<
+      ValueOf<GPUCommandEncoderDescriptor, 'label'>
+    >();
+    const desc: CommandEncoderDescriptor = { label: 'frame-encoder' };
+    expectTypeOf(desc).toMatchTypeOf<CommandEncoderDescriptor>();
+  });
+
+  it('RenderPassColorAttachment field set === Pick + view aligned to TextureView (view narrow Path X)', () => {
+    type AttKeys = 'view' | 'depthSlice' | 'resolveTarget' | 'clearValue' | 'loadOp' | 'storeOp';
+    expectTypeOf<keyof RenderPassColorAttachment>().toEqualTypeOf<AttKeys>();
+    // view is the forgeax TextureView handle, NOT spec polymorphism.
+    // (feat-20260510-rhi-resource-creation M2 view narrow Path X / breakage
+    // point #1: the earlier D-S5 temporary tightening to Texture was
+    // retired once M1 shipped RhiDevice.createTextureView.)
+    expectTypeOf<RenderPassColorAttachment['view']>().toEqualTypeOf<TextureView>();
+    // resolveTarget shares the same view narrow alignment.
+    expectTypeOf<
+      NonNullable<RenderPassColorAttachment['resolveTarget']>
+    >().toEqualTypeOf<TextureView>();
+    // Other fields keep spec types.
+    expectTypeOf<ValueOf<RenderPassColorAttachment, 'loadOp'>>().toEqualTypeOf<
+      ValueOf<GPURenderPassColorAttachment, 'loadOp'>
+    >();
+    expectTypeOf<ValueOf<RenderPassColorAttachment, 'storeOp'>>().toEqualTypeOf<
+      ValueOf<GPURenderPassColorAttachment, 'storeOp'>
+    >();
+    expectTypeOf<ValueOf<RenderPassColorAttachment, 'clearValue'>>().toEqualTypeOf<
+      ValueOf<GPURenderPassColorAttachment, 'clearValue'>
+    >();
+  });
+
+  it('RenderPassDepthStencilAttachment field set === Pick + view aligned to TextureView (view narrow Path X)', () => {
+    type DsKeys =
+      | 'view'
+      | 'depthClearValue'
+      | 'depthLoadOp'
+      | 'depthStoreOp'
+      | 'depthReadOnly'
+      | 'stencilClearValue'
+      | 'stencilLoadOp'
+      | 'stencilStoreOp'
+      | 'stencilReadOnly';
+    expectTypeOf<keyof RenderPassDepthStencilAttachment>().toEqualTypeOf<DsKeys>();
+    expectTypeOf<RenderPassDepthStencilAttachment['view']>().toEqualTypeOf<TextureView>();
+    expectTypeOf<ValueOf<RenderPassDepthStencilAttachment, 'depthClearValue'>>().toEqualTypeOf<
+      ValueOf<GPURenderPassDepthStencilAttachment, 'depthClearValue'>
+    >();
+    expectTypeOf<ValueOf<RenderPassDepthStencilAttachment, 'depthLoadOp'>>().toEqualTypeOf<
+      ValueOf<GPURenderPassDepthStencilAttachment, 'depthLoadOp'>
+    >();
+  });
+
+  // w40 (M5) - BufferDescriptor.mappedAtCreation mirror extension. Pairs
+  // with K-7 (mappedAtCreation passthrough fix) by locking the type-level
+  // contract: forgeax field is `boolean | undefined` (forgeax
+  // ExplicitUndefined<...>) and the underlying value type matches
+  // @webgpu/types.GPUBufferDescriptor.mappedAtCreation byte-for-byte.
+  // Anchors: requirements §IN-5 F-4 / AC-05; research §4.3 +
+  // plan-strategy §4.2 type layer + K-10.
+  it('BufferDescriptor.mappedAtCreation field is `boolean | undefined` and matches GPUBufferDescriptor.mappedAtCreation', () => {
+    // Field is part of the Pick<> set (already covered above; re-anchor here
+    // so a future Pick<> edit that drops the field is caught by w40 too).
+    type HasMappedAtCreation = 'mappedAtCreation' extends keyof BufferDescriptor ? true : false;
+    expectTypeOf<HasMappedAtCreation>().toEqualTypeOf<true>();
+    // Underlying value type aligns with the spec.
+    expectTypeOf<ValueOf<BufferDescriptor, 'mappedAtCreation'>>().toEqualTypeOf<
+      ValueOf<GPUBufferDescriptor, 'mappedAtCreation'>
+    >();
+    // ExplicitUndefined<...> shape: the forgeax form accepts `boolean |
+    // undefined` writes (S-7 distinguishes missing vs explicit-undefined).
+    const m1: BufferDescriptor = { size: 16, usage: 0, mappedAtCreation: true };
+    expectTypeOf(m1).toMatchTypeOf<BufferDescriptor>();
+    const m2: BufferDescriptor = { size: 16, usage: 0, mappedAtCreation: false };
+    expectTypeOf(m2).toMatchTypeOf<BufferDescriptor>();
+    const m3: BufferDescriptor = { size: 16, usage: 0, mappedAtCreation: undefined };
+    expectTypeOf(m3).toMatchTypeOf<BufferDescriptor>();
+    const m4: BufferDescriptor = { size: 16, usage: 0 };
+    expectTypeOf(m4).toMatchTypeOf<BufferDescriptor>();
+    // Anti-form: passing a non-boolean must NOT type-check (commented out;
+    // uncommenting must turn tsc red, not throw at runtime):
+    //   const bad: BufferDescriptor = { size: 16, usage: 0, mappedAtCreation: 1 as never };
+  });
+
+  it('RenderPassDescriptor field set === Pick<GPURenderPassDescriptor, ...> (label inherited)', () => {
+    type RpKeys =
+      | 'label'
+      | 'colorAttachments'
+      | 'depthStencilAttachment'
+      | 'occlusionQuerySet'
+      | 'timestampWrites'
+      | 'maxDrawCount';
+    expectTypeOf<keyof RenderPassDescriptor>().toEqualTypeOf<RpKeys>();
+    // depthStencilAttachment uses the tightened type (not spec).
+    expectTypeOf<
+      NonNullable<RenderPassDescriptor['depthStencilAttachment']>
+    >().toEqualTypeOf<RenderPassDepthStencilAttachment>();
+    // timestampWrites uses the forgeax QuerySet brand; maxDrawCount keeps the
+    // spec type.
+    expectTypeOf<
+      ValueOf<RenderPassDescriptor, 'timestampWrites'>
+    >().toEqualTypeOf<RenderPassTimestampWrites>();
+    expectTypeOf<ValueOf<RenderPassDescriptor, 'maxDrawCount'>>().toEqualTypeOf<
+      ValueOf<GPURenderPassDescriptor, 'maxDrawCount'>
+    >();
+  });
+});