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

package/src/__tests__/buffer-mapping.test-d.ts

@@ -0,0 +1,84 @@
+// RhiBuffer mapAsync / mapState surface + MappedBuffer brand method form.
+//
+// K-1 decision (plan-strategy §2): mapAsync mode parameter is the raw
+// GPUMapModeFlags bitmask (NOT a closed union 'read' | 'write'). spec mirror
+// stance (research §4.2 + W3C WebGPU §buffer-mapping spec anchor).
+//
+// D-P2 #6 (feat-20260511-rhi-spec-realign-aggressive M1): mapAsync resolves
+// to `Promise<Result<MappedBuffer, RhiError>>`; `getMappedRange` and `unmap`
+// migrated from `Buffer` -> `MappedBuffer` method form (this: MappedBuffer
+// implicit guard). The previous top-level Buffer.getMappedRange / Buffer.unmap
+// are removed.
+//
+// Charter: proposition 1 (progressive disclosure - one read shows the buffer
+// surface) + proposition 3 (machine-readable union > prose) + proposition 4
+// (explicit failure - state mismatch surfaces TS2339 at the call site, not
+// runtime panic).
+//
+// Anchors: requirements AC-11 (MappedBuffer brand) + research §4.1 / §4.2 /
+//          §4.4; plan-strategy §7.1 + D-P2 #6; plan-decisions OQ-5 (unmap +
+//          re-mapAsync re-attach path).
+
+/// <reference types="@webgpu/types" />
+
+import { describe, expectTypeOf, it } from 'vitest';
+import type { Buffer, MappedBuffer, Result, RhiError } 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('Buffer mapAsync surface + MappedBuffer brand methods', () => {
+  it('mapAsync(mode: GPUMapModeFlags, offset?, size?) returns Promise<Result<MappedBuffer, RhiError>>', () => {
+    type Method = Buffer['mapAsync'];
+    expectTypeOf<Method>().toBeFunction();
+    type Expected = (
+      mode: GPUMapModeFlags,
+      offset?: number | undefined,
+      size?: number | undefined,
+    ) => Promise<Result<MappedBuffer, RhiError>>;
+    expectTypeOf<Expected>().toMatchTypeOf<Method>();
+  });
+
+  it('mapAsync mode parameter is the raw GPUMapModeFlags bitmask (K-1 decision)', () => {
+    type ModeArg = Parameters<Buffer['mapAsync']>[0];
+    expectTypeOf<ModeArg>().toEqualTypeOf<GPUMapModeFlags>();
+    type ClosedUnion = 'read' | 'write';
+    type IsClosedUnion = ModeArg extends ClosedUnion ? true : false;
+    expectTypeOf<IsClosedUnion>().toEqualTypeOf<false>();
+  });
+
+  it('MappedBuffer.getMappedRange returns Result<ArrayBuffer, RhiError>', () => {
+    type Method = MappedBuffer['getMappedRange'];
+    expectTypeOf<Method>().toBeFunction();
+    type Expected = (
+      offset?: number | undefined,
+      size?: number | undefined,
+    ) => Result<ArrayBuffer, RhiError>;
+    expectTypeOf<Expected>().toMatchTypeOf<Method>();
+  });
+
+  it('MappedBuffer.unmap returns void (spec silent no-op)', () => {
+    type Method = MappedBuffer['unmap'];
+    expectTypeOf<Method>().toBeFunction();
+    type Expected = () => void;
+    expectTypeOf<Expected>().toMatchTypeOf<Method>();
+    type IsResultShape =
+      ReturnType<MappedBuffer['unmap']> extends Result<unknown, unknown> ? true : false;
+    expectTypeOf<IsResultShape>().toEqualTypeOf<false>();
+  });
+
+  it("mapState getter exposes the closed union 'unmapped' | 'pending' | 'mapped'", () => {
+    expectTypeOf<Buffer['mapState']>().toEqualTypeOf<'unmapped' | 'pending' | 'mapped'>();
+  });
+
+  it('mapState writes are rejected at compile time (readonly)', () => {
+    type Writable<T> = { -readonly [K in keyof T]: T[K] };
+    type IsReadonlyMapState = Equals<Buffer, Writable<Buffer>>;
+    expectTypeOf<IsReadonlyMapState>().toEqualTypeOf<false>();
+  });
+
+  it('MappedBuffer is a structural superset of Buffer (D-P2 #6 brand)', () => {
+    expectTypeOf<MappedBuffer>().toMatchTypeOf<Buffer>();
+  });
+});

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