@forgeax/engine-rhi 0.1.2

package/src/__tests__/errors-instancing.unit.test.ts

@@ -0,0 +1,167 @@
+// feat-20260622-chunk-gpu-instancing-sprite-tilemap M2 / w8 — RhiErrorCode
+// 21st member ('instancing-exceeds-uniform-cap') + .detail shape unit tests.
+//
+// Plan-strategy 2 D-2: closed RhiErrorCode add-only minor evolution; AC-05 (a)
+// surface — RhiInstancingExceedsUniformCapDetail tagged union member with
+// fields { requested: number, limit: 128, scope: 'sprite' | 'tilemap-chunk' }.
+//
+// AI-user contract (charter proposition 4 explicit failure + plan-strategy
+// 8.3 actionable hint): consumers narrow .detail through property access
+// (err.detail.requested / err.detail.limit / err.detail.scope) instead of
+// parsing err.message string. The 128-instance cap originates from the
+// uniform-fallback path's WebGL2 minimum 16384B UBO size — research N-1
+// observed value (128 * 64B = 8192B leaves headroom for the per-frame
+// material UBO slice). research F-4 + plan-decisions D-3 lock the limit.
+//
+// The runtime-shape assertions (sections 1 + 2) double as compile-time
+// guarantees: if the union member or detail shape regress, tsc + vitest
+// both flip red. Section 3 protects pre-existing 'limit-exceeded' detail
+// from incidental drift (LimitExceededDetail must keep
+// { maxStorageBufferBindingSize, requestedBytes } per
+// feat-20260513-instanced-mesh M5 reshape).
+
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import {
+  type LimitExceededDetail,
+  RhiError,
+  type RhiErrorCode,
+  type RhiErrorDetail,
+  type RhiInstancingExceedsUniformCapDetail,
+} from '../errors';
+
+describe('M2 / w8 — RhiErrorCode 21st member instancing-exceeds-uniform-cap', () => {
+  it('contains instancing-exceeds-uniform-cap in the closed RhiErrorCode union', () => {
+    expectTypeOf<'instancing-exceeds-uniform-cap'>().toMatchTypeOf<RhiErrorCode>();
+  });
+
+  it('exhaustive switch over all 21 members compiles without default fallback', () => {
+    function describeCode(code: RhiErrorCode): string {
+      switch (code) {
+        case 'adapter-unavailable':
+          return 'adapter';
+        case 'feature-not-enabled':
+          return 'feature';
+        case 'limit-exceeded':
+          return 'limit';
+        case 'shader-compile-failed':
+          return 'shader';
+        case 'rhi-not-available':
+          return 'reserved';
+        case 'webgpu-runtime-error':
+          return 'webgpu-runtime';
+        case 'command-encoder-finished':
+          return 'encoder-finished';
+        case 'render-pass-not-ended':
+          return 'pass-not-ended';
+        case 'queue-submit-failed':
+          return 'queue-submit';
+        case 'queue-write-buffer-out-of-bounds':
+          return 'queue-bounds';
+        case 'render-system-no-camera':
+          return 'no-camera';
+        case 'render-system-multi-camera':
+          return 'multi-camera';
+        case 'render-system-multi-light':
+          return 'multi-light';
+        case 'asset-not-registered':
+          return 'asset-miss';
+        case 'device-lost':
+          return 'device-lost';
+        case 'oom':
+          return 'oom';
+        case 'internal-error':
+          return 'internal-error';
+        case 'hierarchy-broken':
+          return 'hierarchy-broken';
+        case 'destroy-after-destroy':
+          return 'destroy-after-destroy';
+        case 'rhi-descriptor-invalid':
+          return 'descriptor-invalid';
+        case 'instancing-exceeds-uniform-cap':
+          return 'instancing-cap';
+        case 'render-system-empty-worlds':
+          return 'empty-worlds';
+        case 'render-system-owner-out-of-range':
+          return 'owner-oob';
+      }
+      // No default — tsc strict guards: union drift here triggers compile-time red.
+    }
+    expect(describeCode('instancing-exceeds-uniform-cap')).toBe('instancing-cap');
+  });
+});
+
+describe('M2 / w8 — RhiInstancingExceedsUniformCapDetail shape', () => {
+  it('detail equals { requested: number, limit: 128, scope: sprite|tilemap-chunk }', () => {
+    expectTypeOf<RhiInstancingExceedsUniformCapDetail>().toEqualTypeOf<{
+      readonly requested: number;
+      readonly limit: 128;
+      readonly scope: 'sprite' | 'tilemap-chunk';
+    }>();
+  });
+
+  it('detail is a member of the RhiErrorDetail discriminated union', () => {
+    const detail: RhiInstancingExceedsUniformCapDetail = {
+      requested: 200,
+      limit: 128,
+      scope: 'sprite',
+    };
+    const widened: RhiErrorDetail = detail;
+    expectTypeOf(widened).toMatchTypeOf<RhiErrorDetail>();
+  });
+
+  it('limit field is the literal 128, not a generic number', () => {
+    // tsc will reject `limit: 256` etc. — locked to the literal 128.
+    const detail: RhiInstancingExceedsUniformCapDetail = {
+      requested: 1024,
+      limit: 128,
+      scope: 'tilemap-chunk',
+    };
+    expect(detail.limit).toBe(128);
+    expectTypeOf<RhiInstancingExceedsUniformCapDetail['limit']>().toEqualTypeOf<128>();
+  });
+
+  it('scope field is the closed sprite | tilemap-chunk literal union', () => {
+    expectTypeOf<RhiInstancingExceedsUniformCapDetail['scope']>().toEqualTypeOf<
+      'sprite' | 'tilemap-chunk'
+    >();
+  });
+
+  it('AI-user property-access consumption path: read .requested / .limit / .scope', () => {
+    const err = new RhiError({
+      code: 'instancing-exceeds-uniform-cap',
+      expected: 'bucket instance count <= 128 (uniform fallback cap)',
+      hint: 'reduce bucket size, switch to a WebGPU-capable backend, or accept per-cell fallback',
+      detail: { requested: 256, limit: 128, scope: 'tilemap-chunk' },
+    });
+    expect(err.code).toBe('instancing-exceeds-uniform-cap');
+    if (err.code === 'instancing-exceeds-uniform-cap') {
+      // After narrowing on .code, .detail is reachable via property access
+      // — no string parsing of err.message.
+      const d = err.detail as RhiInstancingExceedsUniformCapDetail;
+      expect(d.requested).toBe(256);
+      expect(d.limit).toBe(128);
+      expect(d.scope).toBe('tilemap-chunk');
+    }
+    expect(err.expected.length).toBeGreaterThan(0);
+    expect(err.hint.length).toBeGreaterThan(0);
+  });
+});
+
+describe('M2 / w8 — pre-existing limit-exceeded detail unchanged', () => {
+  it('LimitExceededDetail keeps { maxStorageBufferBindingSize, requestedBytes }', () => {
+    expectTypeOf<LimitExceededDetail>().toEqualTypeOf<{
+      readonly maxStorageBufferBindingSize: number;
+      readonly requestedBytes: number;
+    }>();
+  });
+
+  it("'limit-exceeded' member remains in the closed union (no rename / reorder)", () => {
+    expectTypeOf<'limit-exceeded'>().toMatchTypeOf<RhiErrorCode>();
+  });
+
+  it('limit-exceeded and instancing-exceeds-uniform-cap are distinct members', () => {
+    type Le = Extract<RhiErrorCode, 'limit-exceeded'>;
+    type Ic = Extract<RhiErrorCode, 'instancing-exceeds-uniform-cap'>;
+    expectTypeOf<Le>().not.toEqualTypeOf<Ic>();
+  });
+});

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

@@ -0,0 +1,199 @@
+// MVP-1.7 (type-level) — closed RhiErrorCode union completeness + exhaustive switch
+// without default fallback. Round 1 baseline: 6 members; extended to 10 members in
+// feat-20260508-rhi-surface-completion w7 (D-S3); extended to 14 members in
+// feat-20260509-ecs-render-bridge-mvp w6 (D-S7); extended to 17 members in
+// feat-20260511-rhi-spec-realign-aggressive w1 (red) -> w6 (green) per
+// plan-strategy D-P4 + requirements AC-04. Three new members map W3C WebGPU
+// 22.2 spec subtypes (device-lost / oom / internal-error) to the forgeax union.
+// Extended to 20 members in feat-20260619-wasm-fault-isolation M3 w7:
+// 'rhi-descriptor-invalid' for wgpu-wasm descriptor parse failures.
+//
+// 20 members:
+//   1) 'adapter-unavailable'              (Round 1 baseline)
+//   2) 'feature-not-enabled'              (Round 1 baseline)
+//   3) 'limit-exceeded'                   (Round 1 baseline)
+//   4) 'shader-compile-failed'            (Round 1 baseline)
+//   5) 'rhi-not-available'                (Round 1 baseline; @reserved + placeholder)
+//   6) 'webgpu-runtime-error'             (verify-gpu-smoke-gate K-9 sixth member)
+//   7) 'command-encoder-finished'         (rhi-surface-completion D-S3)
+//   8) 'render-pass-not-ended'            (rhi-surface-completion D-S3)
+//   9) 'queue-submit-failed'              (rhi-surface-completion D-S3)
+//  10) 'queue-write-buffer-out-of-bounds' (rhi-surface-completion D-S3)
+//  11) 'render-system-no-camera'          (ecs-render-bridge-mvp D-S7)
+//  12) 'render-system-multi-camera'       (ecs-render-bridge-mvp D-S7)
+//  13) 'render-system-multi-light'        (ecs-render-bridge-mvp D-S7)
+//  14) 'asset-not-registered'             (ecs-render-bridge-mvp D-S7)
+//  15) 'device-lost'                      (rhi-spec-realign-aggressive D-P4 / R-02 §2.1)
+//  16) 'oom'                              (rhi-spec-realign-aggressive D-P4 / R-02 §2.1)
+//  17) 'internal-error'                   (rhi-spec-realign-aggressive D-P4 / R-02 §2.1)
+//  18) 'hierarchy-broken'                 (asset-system-v1 w4 / D-P2 + requirements §9 row 8)
+//  19) 'destroy-after-destroy'            (feat-20260612-rhi-destroy-renderer-dispose-gpu-lifecycle M1 / D-6 + D-7)
+//  20) 'rhi-descriptor-invalid'           (feat-20260619-wasm-fault-isolation M3 w7 / D-1 + D-2 + D-8)
+//
+// charter mapping: proposition 4 (explicit failure via closed union) +
+// proposition 3 (machine-readable union > prose) — switch (err.code) without
+// default fallback; tsc strict mode rejects union drift at compile time.
+//
+// Related: requirements AC-04 (18-member union) + AC MVP-1.7 + AC-10 + AC-RSC-07;
+// plan-strategy D-P4 (.expected / .hint templates) + D-P2 (hierarchy-broken) +
+// S-6 (types/rhi single source) + 7.2 naming convention; research R-02 §2.1
+// (W3C spec 22.2 subtypes).
+
+import { describe, expectTypeOf, it } from 'vitest';
+import type { RhiError, RhiErrorCode } from '../errors';
+
+describe('MVP-1.7 — RhiErrorCode closed union 20 members', () => {
+  it('contains adapter-unavailable', () => {
+    expectTypeOf<'adapter-unavailable'>().toMatchTypeOf<RhiErrorCode>();
+  });
+
+  it('contains feature-not-enabled', () => {
+    expectTypeOf<'feature-not-enabled'>().toMatchTypeOf<RhiErrorCode>();
+  });
+
+  it('contains limit-exceeded', () => {
+    expectTypeOf<'limit-exceeded'>().toMatchTypeOf<RhiErrorCode>();
+  });
+
+  it('contains shader-compile-failed', () => {
+    expectTypeOf<'shader-compile-failed'>().toMatchTypeOf<RhiErrorCode>();
+  });
+
+  it('contains rhi-not-available (@reserved + placeholder methods)', () => {
+    expectTypeOf<'rhi-not-available'>().toMatchTypeOf<RhiErrorCode>();
+  });
+
+  it('contains webgpu-runtime-error (verify-gpu-smoke-gate K-9 sixth member)', () => {
+    expectTypeOf<'webgpu-runtime-error'>().toMatchTypeOf<RhiErrorCode>();
+  });
+
+  it('contains command-encoder-finished (D-S3 new member)', () => {
+    expectTypeOf<'command-encoder-finished'>().toMatchTypeOf<RhiErrorCode>();
+  });
+
+  it('contains render-pass-not-ended (D-S3 new member)', () => {
+    expectTypeOf<'render-pass-not-ended'>().toMatchTypeOf<RhiErrorCode>();
+  });
+
+  it('contains queue-submit-failed (D-S3 new member)', () => {
+    expectTypeOf<'queue-submit-failed'>().toMatchTypeOf<RhiErrorCode>();
+  });
+
+  it('contains queue-write-buffer-out-of-bounds (D-S3 new member)', () => {
+    expectTypeOf<'queue-write-buffer-out-of-bounds'>().toMatchTypeOf<RhiErrorCode>();
+  });
+
+  it('contains render-system-no-camera (D-S7 new member)', () => {
+    expectTypeOf<'render-system-no-camera'>().toMatchTypeOf<RhiErrorCode>();
+  });
+
+  it('contains render-system-multi-camera (D-S7 new member)', () => {
+    expectTypeOf<'render-system-multi-camera'>().toMatchTypeOf<RhiErrorCode>();
+  });
+
+  it('contains render-system-multi-light (D-S7 new member)', () => {
+    expectTypeOf<'render-system-multi-light'>().toMatchTypeOf<RhiErrorCode>();
+  });
+
+  it('contains asset-not-registered (D-S7 new member)', () => {
+    expectTypeOf<'asset-not-registered'>().toMatchTypeOf<RhiErrorCode>();
+  });
+
+  it('contains device-lost (D-P4 new member; spec 22.1 device lost)', () => {
+    expectTypeOf<'device-lost'>().toMatchTypeOf<RhiErrorCode>();
+  });
+
+  it('contains oom (D-P4 new member; spec 22.2 GPUOutOfMemoryError subtype)', () => {
+    expectTypeOf<'oom'>().toMatchTypeOf<RhiErrorCode>();
+  });
+
+  it('contains internal-error (D-P4 new member; spec 22.2 GPUInternalError subtype)', () => {
+    expectTypeOf<'internal-error'>().toMatchTypeOf<RhiErrorCode>();
+  });
+
+  it('contains hierarchy-broken (w4 asset-system-v1 D-P2 new member; propagateTransforms stale ChildOf ref)', () => {
+    expectTypeOf<'hierarchy-broken'>().toMatchTypeOf<RhiErrorCode>();
+  });
+
+  it('contains destroy-after-destroy (feat-20260612 M1 / D-6 + D-7; double destroy fail-fast)', () => {
+    expectTypeOf<'destroy-after-destroy'>().toMatchTypeOf<RhiErrorCode>();
+  });
+
+  it('contains rhi-descriptor-invalid (feat-20260619 M3 w7; wgpu-wasm descriptor parse failure)', () => {
+    expectTypeOf<'rhi-descriptor-invalid'>().toMatchTypeOf<RhiErrorCode>();
+  });
+
+  it('union remains closed: rejects non-member literal', () => {
+    // @ts-expect-error MVP-1.7: union is closed — 'not-a-real-code' is not a member.
+    const _bogus: RhiErrorCode = 'not-a-real-code';
+    void _bogus;
+  });
+
+  it('exhaustive switch with no default fallback for all members (charter proposition 4)', () => {
+    function describeCode(code: RhiErrorCode): string {
+      switch (code) {
+        case 'adapter-unavailable':
+          return 'adapter';
+        case 'feature-not-enabled':
+          return 'feature';
+        case 'limit-exceeded':
+          return 'limit';
+        case 'shader-compile-failed':
+          return 'shader';
+        case 'rhi-not-available':
+          return 'reserved';
+        case 'webgpu-runtime-error':
+          return 'webgpu-runtime';
+        case 'command-encoder-finished':
+          return 'encoder-finished';
+        case 'render-pass-not-ended':
+          return 'pass-not-ended';
+        case 'queue-submit-failed':
+          return 'queue-submit';
+        case 'queue-write-buffer-out-of-bounds':
+          return 'queue-bounds';
+        case 'render-system-no-camera':
+          return 'no-camera';
+        case 'render-system-multi-camera':
+          return 'multi-camera';
+        case 'render-system-multi-light':
+          return 'multi-light';
+        case 'asset-not-registered':
+          return 'asset-miss';
+        case 'device-lost':
+          return 'device-lost';
+        case 'oom':
+          return 'oom';
+        case 'internal-error':
+          return 'internal-error';
+        case 'hierarchy-broken':
+          return 'hierarchy-broken';
+        case 'destroy-after-destroy':
+          return 'destroy-after-destroy';
+        case 'rhi-descriptor-invalid':
+          return 'descriptor-invalid';
+        case 'instancing-exceeds-uniform-cap':
+          return 'instancing-cap';
+        case 'render-system-empty-worlds':
+          return 'empty-worlds';
+        case 'render-system-owner-out-of-range':
+          return 'owner-oob';
+      }
+      // No default — TS guards: union drift here triggers compile-time red.
+    }
+    expectTypeOf(describeCode).returns.toEqualTypeOf<string>();
+  });
+
+  it('RhiError.code literal type is exactly RhiErrorCode union', () => {
+    expectTypeOf<RhiError['code']>().toEqualTypeOf<RhiErrorCode>();
+  });
+
+  it('RhiError has readonly code / expected / hint fields', () => {
+    type ErrShape = {
+      readonly code: RhiErrorCode;
+      readonly expected: string;
+      readonly hint: string;
+    };
+    expectTypeOf<RhiError>().toMatchTypeOf<ErrShape>();
+  });
+});

package/src/__tests__/limit-exceeded-detail.test-d.ts

@@ -0,0 +1,33 @@
+// feat-20260513-instanced-mesh M5 (T-M5-2): LimitExceededDetail field
+// reshape — type-level assertions (vitest typecheck layer, *.test-d.ts).
+//
+// Companion to `limit-exceeded-detail.test.ts` (runtime). Vitest's
+// typecheck pass (vitest 4.x default `typecheck.include === **/*.test-d.{ts,tsx}`)
+// runs `expectTypeOf` here against the source LimitExceededDetail type;
+// a legacy regression that re-introduces `renderableCount` / `limit`
+// fields would flip these red.
+//
+// Plan rationale: requirements AC-15 (LimitExceededDetail field reshape
+// evolution major) + plan-strategy D-3 (rename + replace, AGENTS.md
+// Change stance — optimal > compatible).
+
+import { describe, expectTypeOf, it } from 'vitest';
+import type { LimitExceededDetail, RhiErrorDetail } from '../errors';
+
+describe('feat-20260513-instanced-mesh T-M5-2 LimitExceededDetail (type-level)', () => {
+  it('equals the new { maxStorageBufferBindingSize, requestedBytes } shape', () => {
+    expectTypeOf<LimitExceededDetail>().toEqualTypeOf<{
+      readonly maxStorageBufferBindingSize: number;
+      readonly requestedBytes: number;
+    }>();
+  });
+
+  it('is a member of the RhiErrorDetail discriminated union', () => {
+    const detail: LimitExceededDetail = {
+      maxStorageBufferBindingSize: 256,
+      requestedBytes: 4096,
+    };
+    const widened: RhiErrorDetail = detail;
+    expectTypeOf(widened).toMatchTypeOf<RhiErrorDetail>();
+  });
+});

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

@@ -0,0 +1,65 @@
+// Type-level — MappedBuffer brand + method form (this: MappedBuffer guard).
+//
+// Introduced in feat-20260511-rhi-spec-realign-aggressive w4 (red) -> w10
+// (green) per requirements AC-11 + plan-strategy §7.1 MappedBuffer + D-P2
+// break-point #6 (brand + method form merged into one row).
+//
+// Shape:
+//   - `MappedBuffer = Buffer & { readonly __mapped: void }`
+//   - `buffer.mapAsync(mode, ...)` returns `Promise<Result<MappedBuffer,
+//     RhiError>>` — success branch carries the branded handle the caller
+//     subsequently consumes for getMappedRange / unmap.
+//   - `MappedBuffer.getMappedRange(...)` / `MappedBuffer.unmap()` are method
+//     forms on the brand (`this: MappedBuffer` implicit guard); the previous
+//     top-level `Buffer.getMappedRange` / `Buffer.unmap` are removed.
+//
+// charter mapping: proposition 4 (TS compile-time guard against calling
+// getMappedRange on an un-mapped Buffer) + proposition 5 (consistent
+// abstraction — the brand encodes state at the type level, no runtime
+// re-validation needed at every call site).
+//
+// Related Rust analogue: `wgpu::BufferSlice<'_>` ownership/borrow tracking;
+// forgeax uses a brand instead of lifetimes because TS lacks affine types.
+
+import { describe, expectTypeOf, it } from 'vitest';
+import type { Buffer, MappedBuffer, Result, RhiError } from '../index';
+
+describe('MappedBuffer brand — type-level state machine', () => {
+  it('mapAsync resolves to Promise<Result<MappedBuffer, RhiError>>', () => {
+    type MapAsyncRet = ReturnType<Buffer['mapAsync']>;
+    expectTypeOf<MapAsyncRet>().toEqualTypeOf<Promise<Result<MappedBuffer, RhiError>>>();
+  });
+
+  it('MappedBuffer is a structural superset of Buffer (Buffer & { __mapped })', () => {
+    expectTypeOf<MappedBuffer>().toMatchTypeOf<Buffer>();
+    // Negative direction — plain Buffer is NOT a MappedBuffer (brand guard).
+    // @ts-expect-error TS2345 — Buffer is missing the __mapped brand.
+    const _bogus: MappedBuffer = undefined as unknown as Buffer;
+    void _bogus;
+  });
+
+  it('getMappedRange is a method on MappedBuffer (not on Buffer)', () => {
+    type GMR = MappedBuffer['getMappedRange'];
+    expectTypeOf<GMR>().toMatchTypeOf<
+      (offset?: number, size?: number) => Result<ArrayBuffer, RhiError>
+    >();
+  });
+
+  it('unmap is a method on MappedBuffer (not on Buffer)', () => {
+    type Unmap = MappedBuffer['unmap'];
+    expectTypeOf<Unmap>().toMatchTypeOf<() => void>();
+  });
+
+  it('AI user pattern: const r = await buf.mapAsync(...); if (r.ok) mappedBuffer.getMappedRange()', async () => {
+    const buffer = undefined as unknown as Buffer;
+    const r = await buffer.mapAsync(1);
+    if (r.ok) {
+      const mappedBuffer: MappedBuffer = r.value;
+      // method-form: mappedBuffer.getMappedRange and mappedBuffer.unmap exist
+      const range = mappedBuffer.getMappedRange();
+      expectTypeOf(range).toEqualTypeOf<Result<ArrayBuffer, RhiError>>();
+      const u = mappedBuffer.unmap();
+      expectTypeOf<typeof u>().toEqualTypeOf<void>();
+    }
+  });
+});

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