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

package/src/__tests__/draw-validation-errors.test.ts

@@ -0,0 +1,155 @@
+// feat-20260708-composited-multi-world-rendering M3 / m3-t1 — AC-10 two new
+// RhiErrorCode members + the pure draw-args validation helper.
+//
+// Plan-strategy 2 D-5: renderer.draw(worlds, { cameraOwner, resourceOwner }) validates its inputs at
+// the entry (before any extract) and returns Result.err on:
+//   - empty worlds array        -> 'render-system-empty-worlds'
+//   - owner index out of range  -> 'render-system-owner-out-of-range'
+//                                  (.detail = { owner, worldCount })
+//
+// The two codes are NOT mutually exclusive: an empty array with an out-of-range
+// owner surfaces the empty-worlds code first (entry check short-circuits before
+// the owner-range check). requirements AC-10: illegal input is a structured,
+// property-accessible failure (.code / .hint / .detail) — never silent.
+//
+// Why the validation lives in @forgeax/engine-rhi (World-free primitives, not
+// @forgeax/engine-runtime): rhi owns the RhiErrorCode closed union (SSOT), and
+// this package depends only on @forgeax/engine-types — it cannot import the
+// runtime Renderer. `validateDrawArgs(worldCount, owner)` takes plain numbers
+// (no World, no math), so it belongs with the codes it emits; createRenderer's
+// draw entry calls it (D-5 "validate at the draw entry"). This keeps the code
+// + validation + test in one package (architecture-principles §1 SSOT + §3
+// Schema as Contract: the validator is the machine-checkable contract).
+//
+// AC-01 single path: only the explicit camera/resource owner form exists; there
+// is no draw(world) overload. AC-02's owner-required compile-time narrowing is
+// verified at the real hello-triangle callsite (m3-t2), not here.
+
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import {
+  RhiError,
+  type RhiErrorCode,
+  type RhiErrorDetail,
+  type RhiOwnerOutOfRangeDetail,
+  validateDrawArgs,
+} from '../errors';
+
+describe('M3 / m3-t1 — two new RhiErrorCode members', () => {
+  it("contains 'render-system-empty-worlds' in the closed RhiErrorCode union", () => {
+    expectTypeOf<'render-system-empty-worlds'>().toMatchTypeOf<RhiErrorCode>();
+  });
+
+  it("contains 'render-system-owner-out-of-range' in the closed RhiErrorCode union", () => {
+    expectTypeOf<'render-system-owner-out-of-range'>().toMatchTypeOf<RhiErrorCode>();
+  });
+
+  it('the two new members are distinct from each other', () => {
+    type Empty = Extract<RhiErrorCode, 'render-system-empty-worlds'>;
+    type Oob = Extract<RhiErrorCode, 'render-system-owner-out-of-range'>;
+    expectTypeOf<Empty>().not.toEqualTypeOf<Oob>();
+  });
+
+  it('exhaustive switch reaches both new members without a default arm', () => {
+    // A narrow switch over just the two new members: tsc proves both literals
+    // are members of the union (otherwise the case labels would not compile);
+    // the runtime assertion proves the mapping is reachable.
+    function describeNew(
+      code: 'render-system-empty-worlds' | 'render-system-owner-out-of-range',
+    ): string {
+      switch (code) {
+        case 'render-system-empty-worlds':
+          return 'empty';
+        case 'render-system-owner-out-of-range':
+          return 'oob';
+      }
+    }
+    expect(describeNew('render-system-empty-worlds')).toBe('empty');
+    expect(describeNew('render-system-owner-out-of-range')).toBe('oob');
+  });
+});
+
+describe('M3 / m3-t1 — RhiOwnerOutOfRangeDetail shape', () => {
+  // feat-20260709-editor-world-partition M1 / w7: the detail grew a `role`
+  // discriminator when the single draw owner was split into cameraOwner +
+  // resourceOwner (plan-strategy §2 D-3; new SSOT contract in
+  // owner-out-of-range-role.test.ts). This precursor shape assertion is
+  // migrated to the two-index form — no new error code, only `.detail` grows.
+  it('detail equals { role, owner: number, worldCount: number }', () => {
+    expectTypeOf<RhiOwnerOutOfRangeDetail>().toEqualTypeOf<{
+      readonly role: 'camera' | 'resource';
+      readonly owner: number;
+      readonly worldCount: number;
+    }>();
+  });
+
+  it('detail is a member of the RhiErrorDetail discriminated union', () => {
+    const detail: RhiOwnerOutOfRangeDetail = { role: 'resource', owner: 2, worldCount: 1 };
+    const widened: RhiErrorDetail = detail;
+    expectTypeOf(widened).toMatchTypeOf<RhiErrorDetail>();
+  });
+});
+
+describe('M3 / m3-t1 — validateDrawArgs (D-5 draw entry validation)', () => {
+  it('empty worlds -> err render-system-empty-worlds with a non-empty hint', () => {
+    const r = validateDrawArgs(0, { cameraOwner: 0, resourceOwner: 0 });
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.error.code).toBe('render-system-empty-worlds');
+      expect(r.error.hint.length).toBeGreaterThan(0);
+      // AI users recover from the hint text (charter P3 actionable hint).
+      expect(r.error.hint).toContain('at least one world');
+      // empty-worlds carries no detail (the failure is fully described by .code).
+      expect(r.error.detail).toBeUndefined();
+    }
+  });
+
+  it('owner out of range (owner >= worldCount) -> err with detail { owner, worldCount }', () => {
+    const r = validateDrawArgs(1, { cameraOwner: 1, resourceOwner: 0 });
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.error.code).toBe('render-system-owner-out-of-range');
+      expect(r.error.hint.length).toBeGreaterThan(0);
+      expect(r.error.hint).toContain('0..worlds.length-1');
+      // .detail is reachable via property access after narrowing on .code.
+      const d = r.error.detail as RhiOwnerOutOfRangeDetail;
+      expect(d.owner).toBe(1);
+      expect(d.worldCount).toBe(1);
+    }
+  });
+
+  it('owner out of range (owner < 0) -> err render-system-owner-out-of-range', () => {
+    const r = validateDrawArgs(2, { cameraOwner: -1, 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 RhiOwnerOutOfRangeDetail;
+      expect(d.owner).toBe(-1);
+      expect(d.worldCount).toBe(2);
+    }
+  });
+
+  it('two codes are non-exclusive: empty array + out-of-range owner short-circuits to empty-worlds', () => {
+    // Entry check order: the empty-worlds guard runs first, so an empty array
+    // with a nonsense owner (5) never reaches the owner-range branch (D-5).
+    const r = validateDrawArgs(0, { cameraOwner: 5, resourceOwner: 5 });
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.error.code).toBe('render-system-empty-worlds');
+    }
+  });
+
+  it('valid args (owner within [0, worldCount)) -> ok', () => {
+    expect(validateDrawArgs(1, { cameraOwner: 0, resourceOwner: 0 }).ok).toBe(true);
+    expect(validateDrawArgs(3, { cameraOwner: 0, resourceOwner: 0 }).ok).toBe(true);
+    expect(validateDrawArgs(3, { cameraOwner: 2, resourceOwner: 2 }).ok).toBe(true);
+  });
+
+  it('returned errors are RhiError instances (structured, not thrown strings)', () => {
+    const r = validateDrawArgs(1, { cameraOwner: 9, resourceOwner: 0 });
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.error).toBeInstanceOf(RhiError);
+      expect(r.error.expected.length).toBeGreaterThan(0);
+    }
+  });
+});

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