@forgeax/engine-rhi 0.1.2

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

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

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

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

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