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

package/src/__tests__/opaque-handle.test-d.ts

@@ -0,0 +1,121 @@
+// MVP-1.3 — 14 opaque handle types do not surface internal GPU fields
+// (type-level red → green).
+//
+// Shape: 14 typed `Id<T>` brand-only types; user attempts to access
+// `.gpuBuffer` / `.__brand` etc. → TypeScript compile-time red signal
+// (auto-guarded by `@ts-expect-error`).
+//
+// Red expected state (at the M1 t7 commit): t10 has not declared these types
+// → `tsc -b` reports a 'no exported member' red.
+// Green expected state (after the M1 t10 commit): the 14 handle types are
+// exported and brand-only → all 14 `ts-expect-error` directive blocks fire
+// (attempts to access internal fields fail).
+//
+// Anchors: requirements §AC MVP-1.3 + §AI User Affordances / resource handles
+//          opaque; plan-strategy §4.3 key-test-point table row 2; §7
+//          proposition 4 / proposition 5; research §F-1 + §R5 (`__brand` is
+//          the d.ts nominal-typing workaround).
+
+import { describe, it } from 'vitest';
+import type {
+  BindGroup,
+  BindGroupLayout,
+  Buffer,
+  CommandBuffer,
+  CommandEncoder,
+  ComputePipeline,
+  Fence,
+  PipelineLayout,
+  QuerySet,
+  RenderPipeline,
+  Sampler,
+  ShaderModule,
+  Texture,
+  TextureView,
+} from '../index';
+
+describe('MVP-1.3 — 14 opaque handle types reject access to internal GPU fields', () => {
+  it('Buffer rejects access to the internal GPU object', () => {
+    const h = {} as Buffer;
+    // @ts-expect-error MVP-1.3: Buffer is opaque; gpuBuffer is not exposed.
+    h.gpuBuffer;
+  });
+
+  it('Texture rejects access to the internal GPU object', () => {
+    const h = {} as Texture;
+    // @ts-expect-error MVP-1.3: Texture is opaque; gpuTexture is not exposed.
+    h.gpuTexture;
+  });
+
+  it('TextureView rejects access to the internal GPU object', () => {
+    const h = {} as TextureView;
+    // @ts-expect-error MVP-1.3: TextureView is opaque; gpuTextureView is not exposed.
+    h.gpuTextureView;
+  });
+
+  it('Sampler rejects access to the internal GPU object', () => {
+    const h = {} as Sampler;
+    // @ts-expect-error MVP-1.3: Sampler is opaque; gpuSampler is not exposed.
+    h.gpuSampler;
+  });
+
+  it('BindGroup rejects access to the internal GPU object', () => {
+    const h = {} as BindGroup;
+    // @ts-expect-error MVP-1.3: BindGroup is opaque; gpuBindGroup is not exposed.
+    h.gpuBindGroup;
+  });
+
+  it('BindGroupLayout rejects access to the internal GPU object', () => {
+    const h = {} as BindGroupLayout;
+    // @ts-expect-error MVP-1.3: BindGroupLayout is opaque; gpuBindGroupLayout is not exposed.
+    h.gpuBindGroupLayout;
+  });
+
+  it('PipelineLayout rejects access to the internal GPU object', () => {
+    const h = {} as PipelineLayout;
+    // @ts-expect-error MVP-1.3: PipelineLayout is opaque; gpuPipelineLayout is not exposed.
+    h.gpuPipelineLayout;
+  });
+
+  it('RenderPipeline rejects access to the internal GPU object', () => {
+    const h = {} as RenderPipeline;
+    // @ts-expect-error MVP-1.3: RenderPipeline is opaque; gpuRenderPipeline is not exposed.
+    h.gpuRenderPipeline;
+  });
+
+  it('ComputePipeline rejects access to the internal GPU object', () => {
+    const h = {} as ComputePipeline;
+    // @ts-expect-error MVP-1.3: ComputePipeline is opaque; gpuComputePipeline is not exposed.
+    h.gpuComputePipeline;
+  });
+
+  it('ShaderModule rejects access to the internal GPU object', () => {
+    const h = {} as ShaderModule;
+    // @ts-expect-error MVP-1.3: ShaderModule is opaque; gpuShaderModule is not exposed.
+    h.gpuShaderModule;
+  });
+
+  it('QuerySet rejects access to the internal GPU object', () => {
+    const h = {} as QuerySet;
+    // @ts-expect-error MVP-1.3: QuerySet is opaque; gpuQuerySet is not exposed.
+    h.gpuQuerySet;
+  });
+
+  it('Fence rejects access to the internal sync object', () => {
+    const h = {} as Fence;
+    // @ts-expect-error MVP-1.3: Fence is opaque; internal sync handle is not exposed.
+    h.gpuFence;
+  });
+
+  it('CommandEncoder rejects access to the internal GPU object', () => {
+    const h = {} as CommandEncoder;
+    // @ts-expect-error MVP-1.3: CommandEncoder is opaque; gpuCommandEncoder is not exposed.
+    h.gpuCommandEncoder;
+  });
+
+  it('CommandBuffer rejects access to the internal GPU object', () => {
+    const h = {} as CommandBuffer;
+    // @ts-expect-error MVP-1.3: CommandBuffer is opaque; gpuCommandBuffer is not exposed.
+    h.gpuCommandBuffer;
+  });
+});

package/src/__tests__/owner-out-of-range-role.test.ts

@@ -0,0 +1,84 @@
+// feat-20260709-editor-world-partition-editorworld-super-composite / M1 / w3
+// (RED — impl lands in w6/w7). Contract test for the `role` field added to the
+// `render-system-owner-out-of-range` structured error detail.
+//
+// Today the draw entry validates a SINGLE `owner` index and, on out-of-range,
+// returns `RhiError { code: 'render-system-owner-out-of-range', detail: {
+// owner, worldCount } }` (errors.ts validateDrawArgs). This feature splits the
+// single owner into `cameraOwner` + `resourceOwner`, so a validation failure
+// must say WHICH index was out of range. w7 extends the detail to
+// `{ role: 'camera' | 'resource', owner, worldCount }`; w6 threads two indices
+// through the draw entry and validates cameraOwner BEFORE resourceOwner.
+//
+// This test pins the future contract as the SSOT for w6/w7. The rhi package is
+// World-free (it owns the RhiErrorCode closed union, architecture-principles §1
+// SSOT) and cannot import the runtime Renderer — so, exactly like the existing
+// draw-validation-errors.test.ts, the contract is exercised through the pure
+// `validateDrawArgs` primitive rather than through `renderer.draw` itself. The
+// future primitive shape is `validateDrawArgs(worldCount, { cameraOwner,
+// resourceOwner })`. Until w6/w7 evolve the signature + detail, these calls are
+// a type/shape mismatch and this file is RED (test-first).
+//
+// No new error code is added (D-3: 0 new error codes) — only `.detail` grows a
+// `role` discriminator.
+//
+// Anchors:
+//   requirements AC-08 (out-of-range/missing returns a structured error aligned
+//     with the existing `render-system-owner-out-of-range` + `.detail`)
+//   plan-strategy §3.3 interface example (err.detail === { role: 'resource',
+//     owner: 3, worldCount: 2 }) + §2 D-3
+//   research F2.3 (existing .detail = { owner, worldCount }; add role field)
+
+import { describe, expect, it } from 'vitest';
+import { validateDrawArgs } from '../errors';
+
+// The role-carrying detail w7 will attach to the existing code. Declared
+// locally so this test states the future contract independent of the
+// (not-yet-updated) RhiOwnerOutOfRangeDetail export.
+interface OwnerOutOfRangeRoleDetail {
+  readonly role: 'camera' | 'resource';
+  readonly owner: number;
+  readonly worldCount: number;
+}
+
+describe('owner-out-of-range role detail (w3, AC-08)', () => {
+  it("cameraOwner out of range -> code render-system-owner-out-of-range, detail.role === 'camera'", () => {
+    // worldCount=2, cameraOwner=99 is out of range; resourceOwner=0 is valid.
+    const r = validateDrawArgs(2, { cameraOwner: 99, resourceOwner: 0 });
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.error.code).toBe('render-system-owner-out-of-range');
+      const d = r.error.detail as OwnerOutOfRangeRoleDetail;
+      expect(d.role).toBe('camera');
+      expect(d.owner).toBe(99);
+      expect(d.worldCount).toBe(2);
+    }
+  });
+
+  it("resourceOwner out of range -> code render-system-owner-out-of-range, detail.role === 'resource'", () => {
+    // worldCount=2, cameraOwner=0 is valid; resourceOwner=99 is out of range.
+    const r = validateDrawArgs(2, { cameraOwner: 0, resourceOwner: 99 });
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.error.code).toBe('render-system-owner-out-of-range');
+      const d = r.error.detail as OwnerOutOfRangeRoleDetail;
+      expect(d.role).toBe('resource');
+      expect(d.owner).toBe(99);
+      expect(d.worldCount).toBe(2);
+    }
+  });
+
+  it("both indices out of range -> reports the FIRST offender (camera), detail.role === 'camera'", () => {
+    // Both out of range. D-3 / w6 orders the check cameraOwner-before-resource,
+    // so the reported role is 'camera' (the first offender) with its own index.
+    const r = validateDrawArgs(2, { cameraOwner: 7, resourceOwner: 8 });
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.error.code).toBe('render-system-owner-out-of-range');
+      const d = r.error.detail as OwnerOutOfRangeRoleDetail;
+      expect(d.role).toBe('camera');
+      expect(d.owner).toBe(7);
+      expect(d.worldCount).toBe(2);
+    }
+  });
+});

package/src/__tests__/queue-writes.test-d.ts

@@ -0,0 +1,108 @@
+// AC-08 (Q5) — RhiQueue.writeTexture + copyExternalImageToTexture Pick<spec>
+// narrow type-layer assertions.
+//
+// D-P5 (plan-strategy §spec-rename) — the spec evolved field-info wrappers;
+// pre-rename names (authored Jan 2024, retired Apr 2026) are no longer
+// present in @webgpu/types 0.1.69 and the rhi interface now uses the
+// authoritative new names (GPUCopyExternalImageSourceInfo +
+// GPUCopyExternalImageDestInfo per W3C WebGPU CR Apr 2026); any regression
+// would surface as TS2304 at type lookup. Historical rename context lives
+// in .forgeax-harness/forgeax-loop/feat-20260511-asset-system-v1/research.md
+// D-P5 + requirements research Finding 1(a) + Finding 3(a); the pre-rename
+// names are deliberately NOT quoted here so the `GPUImg*` grep gate
+// (feat-20260511-asset-system-v1 / w32) returns 0 hits repo-wide.
+//
+// w17 contract:
+//   (a) writeTexture(destination, data, dataLayout, size) where:
+//       destination is Pick<GPUTexelCopyTextureInfo, ...> (NOT verbatim spec);
+//       dataLayout is Pick<GPUTexelCopyBufferLayout, ...>.
+//   (b) copyExternalImageToTexture(source, destination, copySize) where:
+//       source is Pick<GPUCopyExternalImageSourceInfo, ...> (spec rename);
+//       destination is the opaque-handle ExternalImageTextureDestination.
+//   (c) r12-lint Pick<GPU*Descriptor count >= 20 follow-on (verified by w22
+//       gate, not this test-d).
+//
+// Charter: proposition 4 (explicit failure - excess fields trip TS2375 at the
+// call site) + proposition 5 (consistent abstraction - dual backends mirror
+// the same Pick<> narrowing). Anchors: requirements AC-08; research R-04
+// §4.1-§4.3; plan-strategy D-P5 spec rename critical fact.
+
+/// <reference types="@webgpu/types" />
+
+import { describe, expectTypeOf, it } from 'vitest';
+import type {
+  Buffer,
+  ExternalImageTextureDestination,
+  Result,
+  RhiError,
+  RhiQueue,
+  Texture,
+  TextureView,
+  TextureWriteDestination,
+} from '../index';
+
+/** Strict structural equality helper. */
+type Equals<X, Y> =
+  (<T>() => T extends X ? 1 : 2) extends <T>() => T extends Y ? 1 : 2 ? true : false;
+
+describe('AC-08 — RhiQueue.writeTexture Pick<spec> narrow', () => {
+  it('writeTexture method exists on RhiQueue', () => {
+    type Method = RhiQueue['writeTexture'];
+    expectTypeOf<Method>().toBeFunction();
+  });
+
+  it('writeTexture destination keeps the opaque Texture resource boundary', () => {
+    type DestParam = Parameters<RhiQueue['writeTexture']>[0];
+    type ExpectedShape = TextureWriteDestination;
+    // Strict equality — the descriptor has exactly the four spec fields, but
+    // its resource is the RHI-opaque Texture rather than GPUTexture.
+    type IsExact = Equals<DestParam, ExpectedShape>;
+    expectTypeOf<IsExact>().toEqualTypeOf<true>();
+  });
+
+  it('writeTexture dataLayout param strictly equals Pick<GPUTexelCopyBufferLayout, ...>', () => {
+    type LayoutParam = Parameters<RhiQueue['writeTexture']>[2];
+    type ExpectedShape = Pick<GPUTexelCopyBufferLayout, 'offset' | 'bytesPerRow' | 'rowsPerImage'>;
+    type IsExact = Equals<LayoutParam, ExpectedShape>;
+    expectTypeOf<IsExact>().toEqualTypeOf<true>();
+  });
+
+  it('writeTexture returns Result<void, RhiError>', () => {
+    type Ret = ReturnType<RhiQueue['writeTexture']>;
+    type IsResult = Equals<Ret, Result<void, RhiError>>;
+    expectTypeOf<IsResult>().toEqualTypeOf<true>();
+  });
+});
+
+describe('AC-08 — RhiQueue.copyExternalImageToTexture Pick<spec> narrow + spec rename', () => {
+  it('copyExternalImageToTexture method exists on RhiQueue', () => {
+    type Method = RhiQueue['copyExternalImageToTexture'];
+    expectTypeOf<Method>().toBeFunction();
+  });
+
+  it('source param strictly equals Pick<GPUCopyExternalImageSourceInfo, ...> (spec rename D-P5)', () => {
+    type SourceParam = Parameters<RhiQueue['copyExternalImageToTexture']>[0];
+    type ExpectedShape = Pick<GPUCopyExternalImageSourceInfo, 'source' | 'origin' | 'flipY'>;
+    type IsExact = Equals<SourceParam, ExpectedShape>;
+    expectTypeOf<IsExact>().toEqualTypeOf<true>();
+  });
+
+  it('destination param keeps the RHI Texture opaque (D-P5)', () => {
+    type DestParam = Parameters<RhiQueue['copyExternalImageToTexture']>[1];
+    type IsExact = Equals<DestParam, ExternalImageTextureDestination>;
+    expectTypeOf<IsExact>().toEqualTypeOf<true>();
+  });
+
+  it('copyExternalImageToTexture returns Result<void, RhiError>', () => {
+    type Ret = ReturnType<RhiQueue['copyExternalImageToTexture']>;
+    type IsResult = Equals<Ret, Result<void, RhiError>>;
+    expectTypeOf<IsResult>().toEqualTypeOf<true>();
+  });
+});
+
+// Sanity peg — keep Buffer / Texture / TextureView in scope so they don't get
+// stripped by tree-shake import elision (the rhi entry rolls these up so
+// downstream consumers can grep on the forgeax handle names).
+type _Peg = { b: Buffer; t: Texture; tv: TextureView };
+declare const _peg: _Peg;
+void _peg;

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

@@ -0,0 +1,202 @@
+// w4 type-level - RhiRenderPassEncoder spec method-set alignment (research F-2 /
+// plan-strategy D-S4: 17 spec stable + 1 setBindGroup overload + 3 placeholder).
+//
+// Asserts (RED until w5 lands the impl):
+//   - 17 spec stable methods exist on RhiRenderPassEncoder
+//   - setBindGroup has both overloads (a) array form (b) Uint32Array form
+//   - 3 placeholder methods (executeBundles / beginOcclusionQuery /
+//     endOcclusionQuery) are present in the interface and return
+//     Result<void, RhiError> (so AI users can route 'rhi-not-available' at
+//     runtime; charter proposition 4 explicit failure).
+//   - setImmediates (PROPOSED) is NOT exposed (per D-S4 explicit non-receipt;
+//     charter proposition 4: untested features hide behind caps, not surfaces).
+//
+// Method NAMES align byte-for-byte with `@webgpu/types`
+// GPURenderPassEncoder + GPURenderCommandsMixin + GPUBindingCommandsMixin +
+// GPUDebugCommandsMixin (research F-2).
+//
+// Charter mapping: proposition 1 (progressive disclosure: AI sees the full
+// spec surface in one read) + proposition 5 (consistent abstraction: spec
+// stable methods land here regardless of capability).
+
+import { describe, expectTypeOf, it } from 'vitest';
+import type {
+  BindGroup,
+  Buffer,
+  RenderPassColorAttachment,
+  RenderPassDepthStencilAttachment,
+  Result,
+  RhiError,
+  RhiRenderPassEncoder,
+  Texture,
+  TextureView,
+} from '../index';
+
+describe('w4 - RhiRenderPassEncoder spec method set (17 stable + 1 overload + 3 placeholders)', () => {
+  // 7 already-shipped methods (Round 1 baseline; locked in this closure):
+  it('keeps existing setPipeline / setIndexBuffer / setVertexBuffer', () => {
+    expectTypeOf<RhiRenderPassEncoder['setPipeline']>().toBeFunction();
+    expectTypeOf<RhiRenderPassEncoder['setIndexBuffer']>().toBeFunction();
+    expectTypeOf<RhiRenderPassEncoder['setVertexBuffer']>().toBeFunction();
+  });
+
+  it('keeps existing draw / drawIndexed / end', () => {
+    expectTypeOf<RhiRenderPassEncoder['draw']>().toBeFunction();
+    expectTypeOf<RhiRenderPassEncoder['drawIndexed']>().toBeFunction();
+    expectTypeOf<RhiRenderPassEncoder['end']>().toBeFunction();
+  });
+
+  // 10 new spec stable methods (research F-2; D-S4 IN list):
+  it('exposes setViewport(x, y, w, h, minDepth, maxDepth)', () => {
+    expectTypeOf<RhiRenderPassEncoder['setViewport']>().toBeFunction();
+    type Expected = (
+      x: number,
+      y: number,
+      w: number,
+      h: number,
+      minDepth: number,
+      maxDepth: number,
+    ) => void;
+    expectTypeOf<Expected>().toMatchTypeOf<RhiRenderPassEncoder['setViewport']>();
+  });
+
+  it('exposes setScissorRect(x, y, w, h)', () => {
+    expectTypeOf<RhiRenderPassEncoder['setScissorRect']>().toBeFunction();
+  });
+
+  it('exposes setBlendConstant(color)', () => {
+    expectTypeOf<RhiRenderPassEncoder['setBlendConstant']>().toBeFunction();
+  });
+
+  it('exposes setStencilReference(reference)', () => {
+    expectTypeOf<RhiRenderPassEncoder['setStencilReference']>().toBeFunction();
+  });
+
+  it('exposes drawIndirect(buffer, offset)', () => {
+    expectTypeOf<RhiRenderPassEncoder['drawIndirect']>().toBeFunction();
+  });
+
+  it('exposes drawIndexedIndirect(buffer, offset)', () => {
+    expectTypeOf<RhiRenderPassEncoder['drawIndexedIndirect']>().toBeFunction();
+  });
+
+  it('exposes pushDebugGroup / popDebugGroup / insertDebugMarker (DebugCommandsMixin)', () => {
+    expectTypeOf<RhiRenderPassEncoder['pushDebugGroup']>().toBeFunction();
+    expectTypeOf<RhiRenderPassEncoder['popDebugGroup']>().toBeFunction();
+    expectTypeOf<RhiRenderPassEncoder['insertDebugMarker']>().toBeFunction();
+  });
+
+  // setBindGroup has 2 overloads per spec:
+  it('setBindGroup overload (a): array form (existing)', () => {
+    type ArrayForm = (
+      index: number,
+      bindGroup: BindGroup,
+      dynamicOffsets?: readonly number[] | undefined,
+    ) => void;
+    type HasArrayOverload = RhiRenderPassEncoder['setBindGroup'] extends ArrayForm ? true : false;
+    expectTypeOf<HasArrayOverload>().toEqualTypeOf<true>();
+  });
+
+  it('setBindGroup overload (b): Uint32Array slice form (new in this closure)', () => {
+    type SliceForm = (
+      index: number,
+      bindGroup: BindGroup,
+      dynamicOffsetsData: Uint32Array,
+      dynamicOffsetsDataStart: number,
+      dynamicOffsetsDataLength: number,
+    ) => void;
+    type HasSliceOverload = RhiRenderPassEncoder['setBindGroup'] extends SliceForm ? true : false;
+    expectTypeOf<HasSliceOverload>().toEqualTypeOf<true>();
+  });
+
+  // 3 placeholders: signature lives in the interface; shim returns Result.err
+  // ({ code: 'rhi-not-available' }) at runtime per D-S4.
+  it('exposes executeBundles (placeholder; capability-gated by RenderBundle)', () => {
+    type Method = RhiRenderPassEncoder['executeBundles'];
+    expectTypeOf<Method>().toBeFunction();
+    expectTypeOf<Method>().returns.toEqualTypeOf<Result<void, RhiError>>();
+  });
+
+  it('exposes beginOcclusionQuery (placeholder; capability-gated by QuerySet)', () => {
+    type Method = RhiRenderPassEncoder['beginOcclusionQuery'];
+    expectTypeOf<Method>().toBeFunction();
+    expectTypeOf<Method>().returns.toEqualTypeOf<Result<void, RhiError>>();
+  });
+
+  it('exposes endOcclusionQuery (placeholder; capability-gated by QuerySet)', () => {
+    type Method = RhiRenderPassEncoder['endOcclusionQuery'];
+    expectTypeOf<Method>().toBeFunction();
+    expectTypeOf<Method>().returns.toEqualTypeOf<Result<void, RhiError>>();
+  });
+
+  it('does NOT expose setImmediates (PROPOSED; D-S4 explicit non-receipt)', () => {
+    // Type-level guard: the field must NOT exist on the interface so that
+    // AI users see a tsc red signal if they attempt to call it.
+    type HasSetImmediates = 'setImmediates' extends keyof RhiRenderPassEncoder ? true : false;
+    expectTypeOf<HasSetImmediates>().toEqualTypeOf<false>();
+  });
+
+  // Buffer reference smoke (sanity: arg types use forgeax opaque handles).
+  it('drawIndirect uses forgeax Buffer (opaque handle, not raw GPUBuffer)', () => {
+    type Method = RhiRenderPassEncoder['drawIndirect'];
+    type Expected = (indirectBuffer: Buffer, indirectOffset: number) => void;
+    expectTypeOf<Expected>().toMatchTypeOf<Method>();
+  });
+});
+
+// w14 - view narrow Path X breakage point #1 (requirements IN-2 / AC-02 /
+// research 8.2): the 4 view fields move from `Texture` (D-S5 temporary
+// tightening) to `TextureView` (the spec-aligned target after M1 shipped
+// `device.createTextureView`).
+//
+// Field count breakdown (research 8.2 IMPORTANT box):
+//   - 1 direct: RenderPassColorAttachment.view
+//   - 1 direct: RenderPassColorAttachment.resolveTarget?
+//   - 1 direct: RenderPassDepthStencilAttachment.view
+//   - 1 indirect: RenderPassDescriptor.colorAttachments[N].view propagates
+//     through the element type of RenderPassColorAttachment (covered by the
+//     direct assertion on RenderPassColorAttachment.view).
+//
+// Red expected state: this block fails tsc -b before w15 lands the narrow
+//   (current types are `Texture`; `expectAssignable<TextureView>` fails because
+//   Texture and TextureView are disjoint brand types).
+// Green expected state (after w15 commit): all expectTypeOf assertions pass.
+//
+// Charter mapping: proposition 4 (explicit failure: AI users get a tsc red
+// signal at the call site instead of a runtime swap) + proposition 5
+// (consistent abstraction: the field type matches what `createTextureView`
+// returns).
+describe('w14 - view narrow Path X (breakage point #1): RenderPassColorAttachment.view / .resolveTarget / RenderPassDepthStencilAttachment.view = TextureView', () => {
+  it('RenderPassColorAttachment.view is TextureView (not Texture)', () => {
+    type ViewField = RenderPassColorAttachment['view'];
+    expectTypeOf<ViewField>().toEqualTypeOf<TextureView>();
+  });
+
+  it('RenderPassColorAttachment.view rejects Texture brand', () => {
+    type ViewField = RenderPassColorAttachment['view'];
+    type TextureAssignsToView = Texture extends ViewField ? true : false;
+    expectTypeOf<TextureAssignsToView>().toEqualTypeOf<false>();
+  });
+
+  it('RenderPassColorAttachment.resolveTarget is TextureView | undefined (not Texture | undefined)', () => {
+    type ResolveTargetField = RenderPassColorAttachment['resolveTarget'];
+    expectTypeOf<ResolveTargetField>().toEqualTypeOf<TextureView | undefined>();
+  });
+
+  it('RenderPassColorAttachment.resolveTarget rejects Texture brand', () => {
+    type ResolveTargetField = NonNullable<RenderPassColorAttachment['resolveTarget']>;
+    type TextureAssignsToResolveTarget = Texture extends ResolveTargetField ? true : false;
+    expectTypeOf<TextureAssignsToResolveTarget>().toEqualTypeOf<false>();
+  });
+
+  it('RenderPassDepthStencilAttachment.view is TextureView (not Texture)', () => {
+    type ViewField = RenderPassDepthStencilAttachment['view'];
+    expectTypeOf<ViewField>().toEqualTypeOf<TextureView>();
+  });
+
+  it('RenderPassDepthStencilAttachment.view rejects Texture brand', () => {
+    type ViewField = RenderPassDepthStencilAttachment['view'];
+    type TextureAssignsToView = Texture extends ViewField ? true : false;
+    expectTypeOf<TextureAssignsToView>().toEqualTypeOf<false>();
+  });
+});

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

@@ -0,0 +1,123 @@
+// w17 - RhiInstance + RhiAdapter type-level contract test (TDD red).
+//
+// Locks M3 break-point #2 surface (plan-tasks w17 / requirements IN-4 / AC-04;
+// plan-strategy K-5 + K-6):
+//   RhiInstance.requestAdapter(opts?): Promise<Result<RhiAdapter, RhiError>>
+//   RhiAdapter.features: ReadonlySet<GPUFeatureName>  (Round 3 fix-up F-P1-2:
+//     was ReadonlyArray<string>; aligned with RhiDevice.features for cross-
+//     tier shape uniformity — AI users use `.has(name)` on both layers)
+//   RhiAdapter.limits: Readonly<Record<string, number>>
+//   RhiAdapter.requestDevice(opts?): Promise<Result<RhiDevice, RhiError>>
+//
+// Strict two-step path mirrors wgpu / Dawn source (research §6); break-point
+// #2 deprecates the top-level `rhi.requestDevice(opts)` factory in favour of
+// `rhi.requestAdapter() -> adapter.requestDevice(opts)`.
+//
+// Red expected: tsc -b fails with TS2305 / TS2339 (missing RhiInstance /
+// RhiAdapter / RequestAdapterOptions / RequestDeviceOptions). Turns green
+// after w18 ships.
+//
+// F-1 ai-user-review absorption: readonly REVERSE assertions ensure mutation
+// of `features[0]` / `limits['x']` is rejected at compile time (charter
+// proposition 4 explicit failure + proposition 5 consistent abstraction).
+//
+// Anchors: requirements §IN-4 / §AC-04 / break-point #2; research §6.1 + §6.2
+//          + §6.3 wgpu / Dawn strict two-step source; plan-strategy §2 K-5 +
+//          K-6 + §6 M3 + K-10.
+
+import { describe, expectTypeOf, it } from 'vitest';
+import type {
+  RequestAdapterOptions,
+  RequestDeviceOptions,
+  Result,
+  RhiAdapter,
+  RhiDevice,
+  RhiError,
+  RhiInstance,
+} from '../index';
+
+describe('w17 type-level - RhiInstance.requestAdapter signature (K-5 / break-point #2)', () => {
+  it('returns Promise<Result<RhiAdapter, RhiError>>', () => {
+    type Sig = RhiInstance['requestAdapter'];
+    type Ret = ReturnType<Sig>;
+    expectTypeOf<Ret>().toEqualTypeOf<Promise<Result<RhiAdapter, RhiError>>>();
+  });
+
+  it('takes optional RequestAdapterOptions + compatibleSurface parameters', () => {
+    type Sig = RhiInstance['requestAdapter'];
+    type Params = Parameters<Sig>;
+    expectTypeOf<Params>().toEqualTypeOf<
+      [
+        opts?: RequestAdapterOptions | undefined,
+        compatibleSurface?: HTMLCanvasElement | OffscreenCanvas | undefined,
+      ]
+    >();
+  });
+});
+
+describe('w17 type-level - RhiAdapter.features is ReadonlySet<GPUFeatureName> (K-5 / F-P1-2)', () => {
+  it('features field type is ReadonlySet<GPUFeatureName>', () => {
+    expectTypeOf<RhiAdapter['features']>().toEqualTypeOf<ReadonlySet<GPUFeatureName>>();
+  });
+
+  it('mutating features.add(...) is rejected at compile time (F-1 readonly REVERSE)', () => {
+    const adapter = {} as RhiAdapter;
+    // @ts-expect-error F-1 ai-user-review: ReadonlySet rejects .add()
+    adapter.features.add('timestamp-query');
+  });
+
+  it('mutating features.delete(...) is rejected at compile time (F-1)', () => {
+    const adapter = {} as RhiAdapter;
+    // @ts-expect-error F-1 ai-user-review: ReadonlySet rejects .delete()
+    adapter.features.delete('timestamp-query');
+  });
+
+  it('mutating features.clear() is rejected at compile time (F-1)', () => {
+    const adapter = {} as RhiAdapter;
+    // @ts-expect-error F-1 ai-user-review: ReadonlySet rejects .clear()
+    adapter.features.clear();
+  });
+
+  it('reassigning features whole set is rejected at compile time (F-1)', () => {
+    const adapter = {} as RhiAdapter;
+    // @ts-expect-error features is a readonly property
+    adapter.features = new Set();
+  });
+
+  it('.has(name) is the supported read API (cross-tier uniform with RhiDevice.features)', () => {
+    const adapter = {} as RhiAdapter;
+    expectTypeOf(adapter.features.has('timestamp-query')).toEqualTypeOf<boolean>();
+  });
+});
+
+describe('w17 type-level - RhiAdapter.limits is Readonly<Record<string, number>> (K-5)', () => {
+  it('limits field type is Readonly<Record<string, number>>', () => {
+    expectTypeOf<RhiAdapter['limits']>().toEqualTypeOf<Readonly<Record<string, number>>>();
+  });
+
+  it('mutating limits["x"] is rejected at compile time (F-1 readonly REVERSE)', () => {
+    const adapter = {} as RhiAdapter;
+    // @ts-expect-error F-1 ai-user-review: limits['x'] write is rejected by TS
+    adapter.limits.x = 0;
+  });
+
+  it('reassigning limits whole record is rejected at compile time (F-1)', () => {
+    const adapter = {} as RhiAdapter;
+    // @ts-expect-error limits is a readonly property
+    adapter.limits = { x: 0 };
+  });
+});
+
+describe('w17 type-level - RhiAdapter.requestDevice signature (K-6)', () => {
+  it('returns Promise<Result<RhiDevice, RhiError>> (NOT a tuple)', () => {
+    type Sig = RhiAdapter['requestDevice'];
+    type Ret = ReturnType<Sig>;
+    expectTypeOf<Ret>().toEqualTypeOf<Promise<Result<RhiDevice, RhiError>>>();
+  });
+
+  it('takes an optional RequestDeviceOptions parameter', () => {
+    type Sig = RhiAdapter['requestDevice'];
+    type Params = Parameters<Sig>;
+    expectTypeOf<Params>().toEqualTypeOf<[opts?: RequestDeviceOptions | undefined]>();
+  });
+});