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

package/src/errors/render.ts

@@ -0,0 +1,1284 @@
+// @forgeax/engine-render -- render cluster error classes.
+//
+// feat-20260704-runtime-tier1-decomposition M2 / w8 (D-3): the monolithic
+// errors.ts RuntimeErrorCode / RuntimeError top-level aggregate unions are
+// decomposed into five per-cluster files (render / asset / skin / recover /
+// environment). Each cluster owns a closed *ErrorCode code union + a closed
+// *Error class union; error class names, .code literals, and .detail shapes
+// are preserved byte-for-byte (OOS-4: zero semantic change).
+//
+// The render cluster holds the shadow / HDRP cluster-forward + deferred /
+// g-buffer / point-shadow-atlas / video-upload / vertex-storage-buffer render
+// path errors. ShadowInvalidConfigError is consumed by the DirectionalLight /
+// SpotLight / PointLightShadow component validators (forward cross-directory
+// import, no cycle -- research Finding C2).
+
+import type { DeviceResourceKind, DeviceScopeReceipt } from '../device/resource-types';
+import type {
+  PreparedKind,
+  RenderFeatureCapabilityKey,
+  RenderFeatureRecovery,
+  RenderFeatureStage,
+} from '../features/vocabulary';
+
+export interface LifecycleConstructionFailureDetail {
+  readonly owner: string;
+  readonly generation: number;
+  readonly operation: 'create' | 'dispose';
+  readonly resourceKind: DeviceResourceKind;
+  readonly cause: unknown;
+  readonly cleanupFailures: readonly {
+    readonly resourceKind: DeviceResourceKind;
+    readonly cause: unknown;
+  }[];
+  readonly receipt: DeviceScopeReceipt;
+}
+
+export class LifecycleConstructionError extends Error {
+  readonly code = 'lifecycle-construction-failed' as const;
+  readonly expected = 'all DeviceScope resources establish and terminate in order';
+  readonly hint = 'inspect detail and cleanupFailures, then recover or rebuild the DeviceScope';
+  readonly detail: LifecycleConstructionFailureDetail;
+
+  constructor(detail: LifecycleConstructionFailureDetail) {
+    super(`lifecycle-construction-failed: ${detail.resourceKind} lifecycle transaction failed`);
+    this.name = 'LifecycleConstructionError';
+    this.detail = detail;
+  }
+}
+
+// ── ShadowInvalidConfigError ──────────────────────────────────────────────
+
+/**
+ * Detail for `RuntimeErrorCode 'shadow-invalid-config'`.
+ *
+ * Emitted by `DirectionalLight.validate` shadow-field path when a field value violates
+ * runtime constraints (e.g. mapSize < 1, cascadeCount not in {1..4}).
+ * AI users access `.detail.field` / `.detail.value` / `.detail.min` /
+ * `.detail.max` via property access — no string parsing.
+ *
+ * `max` is `undefined` for lower-bound-only validations (e.g. mapSize < 1).
+ * feat-20260613-csm: max added for upper-bound cascade validations
+ * (cascadeCount max=4, splitLambda max=1, cascadeBlend max=0.5).
+ */
+export interface ShadowInvalidConfigDetail {
+  readonly field: string;
+  readonly value: number;
+  readonly min: number;
+  readonly max?: number;
+}
+
+/**
+ * Structured error for shadow component config validation failures.
+ *
+ * Emitted by `DirectionalLight.validate()` shadow-field path (mapSize / cascadeCount /
+ * splitLambda / cascadeBlend / shadowDistance) and `PointLightShadow.validate()`
+ * (mapSize / farPlane > nearPlane / pcfKernelSize); both shadow component
+ * types share this single error class so `switch (err.code)` on
+ * `RuntimeErrorCode` only needs one branch (charter P4 — closed-union SSOT).
+ * Four-field surface per AGENTS.md error model:
+ *   - `.code = 'shadow-invalid-config'` (closed RuntimeErrorCode)
+ *   - `.expected` — expected-state description (programmatic predicate form)
+ *   - `.hint` — actionable recovery guidance (imperative; AI users paste into
+ *     spawn calls). Integer-typed fields (e.g. `cascadeCount`, `pcfKernelSize`)
+ *     get an "integer in [min, max]" hint; otherwise "[min, max]" range or
+ *     "<comparator> min".
+ *   - `.detail = { field, value, min, max? }` — structured values (charter P4)
+ *
+ * 4th constructor parameter is a union over the two range shapes:
+ *   - `number` — `max` for a closed `[min, max]` range (CSM cascadeCount /
+ *     splitLambda / cascadeBlend). hint uses "in [min, max]"; integer-typed
+ *     fields get "integer in [min, max]".
+ *   - `'>' | '>='` — comparator for an open lower-bound predicate. `'>'` is
+ *     used when `min` carries dynamic context (e.g. `farPlane > nearPlane` —
+ *     the surfaced hint reads "must be > nearPlane" so AI users setting
+ *     farPlane=nearPlane don't re-fail the spawn loop with the wrong cue).
+ *   - `undefined` — defaults to `'>='`. Callsites for mapSize < 1 validation
+ *     stay backward-compatible (3-arg form).
+ */
+export class ShadowInvalidConfigError extends Error {
+  readonly code = 'shadow-invalid-config' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: ShadowInvalidConfigDetail;
+
+  constructor(field: string, value: number, min: number, maxOrComparator?: number | '>' | '>=') {
+    const isComparator = maxOrComparator === '>' || maxOrComparator === '>=';
+    const max = !isComparator && typeof maxOrComparator === 'number' ? maxOrComparator : undefined;
+    const comparator: '>' | '>=' = isComparator ? (maxOrComparator as '>' | '>=') : '>=';
+    // Integer-typed fields get an "integer in [min, max]" hint when a range
+    // is supplied. Expand this set as new integer-typed shadow fields land.
+    const isInteger = field === 'cascadeCount' || field === 'pcfKernelSize';
+    // pcfKernelSize must be odd (kernel is symmetric around the center tap).
+    // Naming "odd" in the hint stops an AI retry from looping min->min+1 (4->6).
+    const isOdd = field === 'pcfKernelSize';
+    const hint =
+      max !== undefined
+        ? isInteger
+          ? `set ${field} to an integer in [${min}, ${max}]; got ${value}`
+          : `set ${field} to a value in [${min}, ${max}]; got ${value}`
+        : isOdd
+          ? `set ${field} to an odd integer ${comparator} ${min}; got ${value}`
+          : `set ${field} to a value ${comparator} ${min}; got ${value}`;
+    const expected =
+      max !== undefined ? `${field} in [${min}, ${max}]` : `${field} ${comparator} ${min}`;
+    super(
+      max !== undefined
+        ? `shadow component .${field} must be in [${min}, ${max}], got ${value}`
+        : `shadow component .${field} must be ${comparator} ${min}, got ${value}`,
+    );
+    this.name = 'ShadowInvalidConfigError';
+    this.hint = hint;
+    this.expected = expected;
+    this.detail = { field, value, min, ...(max !== undefined ? { max } : {}) };
+  }
+}
+
+// ── EquirectProjectionFailedError ────────────────────────────────────────────
+
+/**
+ * Detail for `RuntimeErrorCode 'equirect-projection-failed'`.
+ *
+ * Emitted when the equirect-to-cubemap IBL projection fails for the equirect
+ * handle referenced by a `Skylight` / `SkyboxBackground` component. The handle
+ * id is carried so AI users can trace which equirect source failed projection.
+ * Degradation: the record arm records `status:'failed'`, binds the white-cube
+ * fallback, fires this error ONCE, and does NOT retry the projection.
+ *
+ * feat-20260630 D-5: structured error with detail carrying the handle id.
+ */
+export interface EquirectProjectionFailedDetail {
+  readonly handle: number;
+}
+
+/**
+ * Structured error for a failed equirect-to-cubemap IBL projection.
+ *
+ * Emitted by the record stage when the internal cubemap projection for an
+ * equirect handle returns a failure (or records `status:'failed'`). Four-field
+ * surface per AGENTS.md error model:
+ *   - `.code = 'equirect-projection-failed'` (closed RuntimeErrorCode)
+ *   - `.expected` — equirect-to-cubemap projection + IBL precompute succeeds
+ *   - `.hint` — declare `Skylight{equirect}` with a valid HDR equirect source;
+ *     check `device.caps.rgba16floatRenderable`. The projection is internal —
+ *     there is no user upload call to retry
+ *   - `.detail = { handle }` — the numeric equirect handle id for diagnostics
+ */
+export class EquirectProjectionFailedError extends Error {
+  readonly code = 'equirect-projection-failed' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: EquirectProjectionFailedDetail;
+
+  constructor(handle: number) {
+    const expected = `equirect handle ${handle} projects to a GPU cubemap + IBL precompute`;
+    const hint =
+      `equirect handle ${handle} referenced by Skylight/SkyboxBackground failed projection; ` +
+      `declare Skylight{equirect} with a valid HDR equirect source and check device.caps.rgba16floatRenderable. ` +
+      `The projection is internal (no user upload call); the record arm does not retry`;
+    super(`equirect handle ${handle} cubemap projection failed`);
+    this.name = 'EquirectProjectionFailedError';
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = { handle };
+  }
+}
+
+// ── HdrpLightBudgetExceededError ───────────────────────────────────────────
+
+/**
+ * Detail for `RuntimeErrorCode 'hdrp-light-budget-exceeded'`.
+ *
+ * Emitted per-frame (once-per-frame fire) when light count exceeds HDRP budget.
+ */
+export interface HdrpLightBudgetExceededDetail {
+  readonly actual: number;
+  readonly budget: number;
+}
+
+/**
+ * Structured error for HDRP light budget exceeded (AC-06/AC-07).
+ *
+ * Emitted per-frame in recordFrame when the total punctual light count
+ * exceeds the HDRP budget (256). Fail-soft: fire once per frame, truncate to 256.
+ *   - `.code = 'hdrp-light-budget-exceeded'` (closed RuntimeErrorCode)
+ *   - `.expected` — 'light count <= 256'
+ *   - `.hint` — 'reduce world light count or increase budget (OOS-hdrp-larger-budget)'
+ *   - `.detail = { actual, budget }`
+ */
+export class HdrpLightBudgetExceededError extends Error {
+  readonly code = 'hdrp-light-budget-exceeded' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: HdrpLightBudgetExceededDetail;
+
+  constructor(actual: number, budget: number) {
+    const expected = `light count <= ${budget}`;
+    const hint =
+      `${actual} lights exceed HDRP budget ${budget}; ` +
+      'truncating to 256. Reduce light count or wait for OOS-hdrp-larger-budget';
+    super(`HDRP light budget exceeded: ${actual} > ${budget}`);
+    this.name = 'HdrpLightBudgetExceededError';
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = { actual, budget };
+  }
+}
+
+// ── HdrpIndexListOverflowError ─────────────────────────────────────────────
+
+/**
+ * Detail for `RuntimeErrorCode 'hdrp-index-list-overflow'`.
+ *
+ * Emitted per-frame (once-per-frame fire) when the cluster binner overflows
+ * the light index list capacity (65536). Upgraded from ClusterBinError.
+ */
+export interface HdrpIndexListOverflowDetail {
+  readonly actual: number;
+  readonly capacity: number;
+}
+
+/**
+ * Structured error for HDRP cluster binner index list overflow (AC-24).
+ *
+ * Emitted per-frame in recordFrame when the CPU binner returns
+ * `ClusterBinError('index-overflow')`. Fail-soft: fire once per frame,
+ * continue rendering with what fit.
+ *   - `.code = 'hdrp-index-list-overflow'` (closed RuntimeErrorCode)
+ *   - `.expected` — 'light index list entries <= 65536'
+ *   - `.hint` — 'reduce lights, shrink cluster grid, or increase capacity'
+ *   - `.detail = { actual, capacity }`
+ */
+export class HdrpIndexListOverflowError extends Error {
+  readonly code = 'hdrp-index-list-overflow' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: HdrpIndexListOverflowDetail;
+
+  constructor(actual: number, capacity: number) {
+    const expected = `light index list entries <= ${capacity}`;
+    const hint =
+      `cluster binner overflow: writeCount ${actual} exceeds capacity ${capacity}; ` +
+      'reduce lights, shrink cluster grid, or increase LIGHT_INDEX_LIST_CAPACITY';
+    super(`HDRP index list overflow: ${actual} > ${capacity}`);
+    this.name = 'HdrpIndexListOverflowError';
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = { actual, capacity };
+  }
+}
+
+// ── HdrpDeferredCapsInsufficientError ──────────────────────────────────────
+
+/**
+ * Detail for `RuntimeErrorCode 'hdrp-deferred-caps-insufficient'`.
+ *
+ * Emitted when the Standard clustered lane has fewer than 4 color attachments,
+ * meaning the deferred path cannot allocate 3 g-buffer color targets + depth.
+ */
+export interface HdrpDeferredCapsInsufficientDetail {
+  readonly actual: number;
+  readonly expected: number;
+}
+
+/**
+ * Structured error for deferred-path capability gate failure.
+ *
+ * Emitted during Standard clustered lane validation — synchronous throw.
+ *   - `.code = 'hdrp-deferred-caps-insufficient'` (closed RuntimeErrorCode)
+ *   - `.expected` — 'maxColorAttachments >= 4'
+ *   - `.hint` — actionable guidance to upgrade browser or select URP
+ *   - `.detail = { actual, expected }`
+ *
+ * @see plan-strategy D-5 (capability validation, no silent fallback)
+ */
+export class HdrpDeferredCapsInsufficientError extends Error {
+  readonly code = 'hdrp-deferred-caps-insufficient' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: HdrpDeferredCapsInsufficientDetail;
+
+  constructor(actual: number) {
+    const _expected = 4;
+    const _expectedStr = `maxColorAttachments >= ${_expected}`;
+    const hint =
+      `WebGPU maxColorAttachments = ${actual} (need >= ${_expected}). ` +
+      'Upgrade browser to latest Chrome/Edge/Safari, or use URP (forgeax::urp) instead of HDRP.';
+    super(
+      `HDRP deferred caps insufficient: maxColorAttachments = ${actual} (need >= ${_expected})`,
+    );
+    this.name = 'HdrpDeferredCapsInsufficientError';
+    this.expected = _expectedStr;
+    this.hint = hint;
+    this.detail = { actual, expected: _expected };
+  }
+}
+
+// ── PointShadowAtlasUninitializedError ─────────────────────────────────────
+
+/**
+ * Structured error for `ShadowAtlas.faceView` called before `ensure()`
+ * allocated the cube_array texture. Replaces the prior bare
+ * `throw new Error()` (Round-2 F-4: P3 closed-union compliance).
+ *
+ *   - `.code = 'point-shadow-atlas-uninitialized'`
+ *   - `.expected` — call `ensure()` before iterating face views
+ *   - `.hint` — gate `faceView` on `isAllocated()` or call `ensure()` once
+ *     in the per-frame extract step before recording the 6 x N caster passes
+ *   - `.detail = undefined` (no per-call data needed)
+ */
+export class PointShadowAtlasUninitializedError extends Error {
+  readonly code = 'point-shadow-atlas-uninitialized' as const;
+  readonly expected: string;
+  readonly hint: string;
+
+  constructor() {
+    const expected = 'ShadowAtlas.ensure() invoked before faceView()';
+    const hint =
+      'Gate faceView on isAllocated() or call ensure() once in the per-frame extract step before iterating face views';
+    super('ShadowAtlas.faceView called before ensure(); the cube_array texture is not allocated');
+    this.name = 'PointShadowAtlasUninitializedError';
+    this.expected = expected;
+    this.hint = hint;
+  }
+}
+
+// ── PointShadowAtlasBoundsViolationError ───────────────────────────────────
+
+/**
+ * Detail for `RuntimeErrorCode 'point-shadow-atlas-bounds-violation'`.
+ *
+ * Emitted by `ShadowAtlas.faceView` when `layer` falls outside `[0, layers)`
+ * or `face` falls outside `[0, 6)`. Both axes are reported as
+ * `{ axis, value, max }` so AI users discriminate without parsing the message.
+ */
+export interface PointShadowAtlasBoundsViolationDetail {
+  readonly axis: 'layer' | 'face';
+  readonly value: number;
+  readonly max: number;
+}
+
+/**
+ * Structured error for `ShadowAtlas.faceView(layer, face)` arguments outside
+ * the allocated atlas range. Replaces the prior bare `throw new Error()`
+ * (Round-2 F-4: P3 closed-union compliance).
+ *
+ *   - `.code = 'point-shadow-atlas-bounds-violation'`
+ *   - `.expected` — `0 <= layer < layers && 0 <= face < 6`
+ *   - `.hint` — clamp `shadowAtlasLayer` or face index before calling
+ *     `faceView`; the cap on layers is `PointLightShadow` cardinality (4)
+ *   - `.detail = { axis, value, max }` — discriminates layer vs face
+ */
+export class PointShadowAtlasBoundsViolationError extends Error {
+  readonly code = 'point-shadow-atlas-bounds-violation' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: PointShadowAtlasBoundsViolationDetail;
+
+  constructor(axis: 'layer' | 'face', value: number, max: number) {
+    const expected = `0 <= ${axis} < ${max}`;
+    const hint =
+      axis === 'layer'
+        ? `clamp PointLight.shadowAtlasLayer to [0, ${max}); the cap on layers equals PointLightShadow cardinality (4)`
+        : `clamp face index to [0, ${max}); cube faces are indexed 0..5 in +X/-X/+Y/-Y/+Z/-Z order`;
+    super(`ShadowAtlas.faceView ${axis} out of range: ${value} (must be in [0, ${max}))`);
+    this.name = 'PointShadowAtlasBoundsViolationError';
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = { axis, value, max };
+  }
+}
+
+// ── VideoUploadUnsupportedError ─────────────────────────────────────────
+
+/**
+ * Structured error for `RuntimeErrorCode 'video-upload-unsupported'`
+ * (feat-20260623-world-space-video-asset M3 / w11 — AC-10).
+ *
+ * Fired by the per-frame record stage (`videoTextureView`) when a VideoPlayer
+ * entity can reach neither video upload path this frame: the general
+ * `copyExternalImageToTexture` path (no host HTMLVideoElement resolved via
+ * `VideoElementProvider`) AND the high-perf `GPUExternalTexture` path
+ * (capability absent). The engine surfaces this explicit failure rather than
+ * silently rendering a stale/garbage texture (charter P3, plan-strategy D-6).
+ *   - `.code = 'video-upload-unsupported'`
+ *   - `.expected` — at least one upload path available (host element or
+ *     GPUExternalTexture capability)
+ *   - `.hint` — actionable recovery: use a static texture or switch backend
+ *   - `.detail` — undefined (no narrowed detail variant)
+ */
+export class VideoUploadUnsupportedError extends Error {
+  readonly code = 'video-upload-unsupported' as const;
+  readonly expected: string;
+  readonly hint: string;
+
+  constructor() {
+    const expected =
+      'at least one video upload path available: a host HTMLVideoElement (general copyExternalImageToTexture path) or GPUExternalTexture capability (high-perf path)';
+    const hint =
+      'this backend exposes no usable video upload path; render a static texture instead, or switch to a WebGPU backend that supports video texture upload';
+    super('video upload unsupported — no general or high-perf path available');
+    this.name = 'VideoUploadUnsupportedError';
+    this.expected = expected;
+    this.hint = hint;
+  }
+}
+
+// ── VertexStorageBufferUnavailableError ─────────────────────────────────
+
+/**
+ * Structured error for missing vertex-stage storage buffer capability.
+ *
+ * Emitted at createRenderer time (cap-gate).
+ *   - `.code = 'vertex-storage-buffer-unavailable'`
+ *   - `.expected` — device.caps supports vertex-stage storage buffer
+ *   - `.hint` — switch to a WebGPU adapter with vertex storage buffer support or use uniform-buffer fallback (OOS-uniform-palette)
+ *   - `.detail` — undefined (no narrowed detail variant)
+ */
+export class VertexStorageBufferUnavailableError extends Error {
+  readonly code = 'vertex-storage-buffer-unavailable' as const;
+  readonly expected: string;
+  readonly hint: string;
+
+  constructor() {
+    const expected =
+      'device.caps supports vertex-stage storage buffer (maxStorageBuffersPerShaderStage >= 1)';
+    const hint =
+      'this device does not support vertex-stage storage buffers; skinning requires vertex-stage storage buffer access (OOS-uniform-palette fallback not implemented)';
+    super('vertex-stage storage buffer unavailable — skinning cannot operate');
+    this.name = 'VertexStorageBufferUnavailableError';
+    this.expected = expected;
+    this.hint = hint;
+  }
+}
+
+// ── VertexColorVariantConflictError ───────────────────────────────────────
+
+export interface VertexColorVariantConflictDetail {
+  readonly authored: true;
+  readonly authoredValue: string;
+  readonly projected: boolean;
+}
+
+/** The authored color axis disagrees with the canonical geometry projection. */
+export class VertexColorVariantConflictError extends Error {
+  readonly code = 'vertex-color-variant-conflict' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: VertexColorVariantConflictDetail;
+
+  constructor(authoredValue: string, projected: boolean) {
+    const expected = `VERTEX_COLOR_AVAILABLE=${projected ? 'true' : 'false'}`;
+    const hint =
+      'derive the shader variant from the mesh VertexLayoutProjection; COLOR_0 presence is a geometry fact';
+    super(`authored vertex-color variant ${authoredValue} disagrees with projected ${expected}`);
+    this.name = 'VertexColorVariantConflictError';
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = { authored: true, authoredValue, projected };
+  }
+}
+
+// ── Skin palette/material validation errors ────────────────────────────────
+
+/** Detail for a palette buffer that exceeds the device storage limit. */
+export interface SkinPaletteOverflowDetail {
+  readonly requestedBytes: number;
+  readonly limit: number;
+}
+
+/**
+ * Structured render error for a skin palette allocation that exceeds the
+ * device storage-buffer binding limit. The allocator that emits this error
+ * lives in render, so the error belongs to the render union rather than the
+ * renderer-independent skinning binding package.
+ */
+export class SkinPaletteOverflowError extends Error {
+  readonly code = 'skin-palette-overflow' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: SkinPaletteOverflowDetail;
+
+  constructor(requestedBytes: number, limit: number) {
+    const expected = `skinned joint palette (${requestedBytes} B) fits within device.limits.maxStorageBufferBindingSize (${limit} B)`;
+    const hint =
+      'palette buffer exceeds device maxStorageBufferBindingSize; reduce skinned entity count or split into multiple palette buffers (OOS-skin-palette-batch)';
+    super(`skin palette buffer needs ${requestedBytes} B, exceeds device limit ${limit} B`);
+    this.name = 'SkinPaletteOverflowError';
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = { requestedBytes, limit };
+  }
+}
+
+/** Detail for a skinned entity using a non-skin material shader. */
+export interface SkinMaterialMismatchDetail {
+  readonly entity: number;
+  readonly actualShader: string | undefined;
+}
+
+/** Structured render error for a Skin/non-skin-material mismatch. */
+export class SkinMaterialMismatchError extends Error {
+  readonly code = 'skin-material-mismatch' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: SkinMaterialMismatchDetail;
+
+  constructor(entity: number, actualShader: string | undefined) {
+    const expected = "Skin entity's first material program module === 'forgeax::pbr-skin'";
+    const hint = `entity ${entity} has Skin but the first material program module is ${actualShader ?? '<empty>'}; load the mesh via the gltf importer (cooker auto-routes 'forgeax::pbr-skin' for skinned primitives), or remove the Skin component to render the entity unskinned with Materials.standard / Materials.unlit`;
+    super(
+      `Skin / material mismatch on entity ${entity}: expected forgeax::pbr-skin, got ${actualShader ?? '<empty>'}`,
+    );
+    this.name = 'SkinMaterialMismatchError';
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = { entity, actualShader };
+  }
+}
+
+/** Detail for a pbr-skin material whose mesh lacks skin attributes. */
+export interface MaterialSkinAttrMissingDetail {
+  readonly entity: number;
+  readonly missing: 'skinIndex' | 'skinWeight' | 'both';
+}
+
+/** Structured render error for a pbr-skin material/mesh attribute mismatch. */
+export class MaterialSkinAttrMissingError extends Error {
+  readonly code = 'material-skin-attr-missing' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: MaterialSkinAttrMissingDetail;
+
+  constructor(entity: number, missing: 'skinIndex' | 'skinWeight' | 'both') {
+    const expected = 'pbr-skin material requires mesh.attributes.skinIndex + skinWeight';
+    const hint = `entity ${entity} uses forgeax::pbr-skin but its MeshAsset is missing ${missing}; switch the entity to a skinned glTF mesh authored with JOINTS_0 + WEIGHTS_0, or change the material to a non-skin shader via Materials.standard / Materials.unlit`;
+    super(
+      `material/skin attribute mismatch on entity ${entity}: pbr-skin material with mesh missing ${missing}`,
+    );
+    this.name = 'MaterialSkinAttrMissingError';
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = { entity, missing };
+  }
+}
+
+// -- RenderFeature errors ---------------------------------------------------
+
+export type RenderFeatureErrorCode =
+  | 'render-feature-registration-conflict'
+  | 'render-feature-stage-failed'
+  | 'render-feature-capability-missing'
+  | 'render-feature-pass-order-conflict'
+  | 'render-feature-preparation-failed'
+  | 'render-feature-prepared-state-mismatch'
+  | 'render-feature-draw-recording-failed';
+
+export interface RenderFeatureRegistrationConflictDetail {
+  readonly featureIdentity: string;
+  readonly order: number;
+  readonly conflictingOrder: number;
+}
+
+export interface RenderFeatureCleanupFailure {
+  readonly featureIdentity: string;
+  readonly order: number;
+  readonly code: string;
+}
+
+export interface RenderFeatureStageFailedDetail {
+  readonly featureIdentity: string;
+  readonly order: number;
+  readonly stage: RenderFeatureStage;
+  readonly recovery: RenderFeatureRecovery;
+  readonly cleanupFailures?: readonly RenderFeatureCleanupFailure[];
+}
+
+export interface RenderFeatureCapabilityMissingDetail {
+  readonly featureIdentity: string;
+  readonly order: number;
+  readonly capability: RenderFeatureCapabilityKey;
+}
+
+export interface RenderFeaturePassOrderConflictDetail {
+  readonly featureIdentity: string;
+  readonly order: number;
+  readonly passIdentity: string;
+  readonly dependencyIdentity: string;
+}
+
+export interface RenderFeaturePreparationFailedDetail {
+  readonly featureIdentity: string;
+  readonly order: number;
+  readonly stage: 'prepare';
+  readonly operation: string;
+  readonly resourceKind: PreparedKind;
+  readonly resourceName: string;
+  readonly reason: string;
+  readonly recovery: RenderFeatureRecovery;
+}
+
+export type RenderFeaturePreparedStateMismatchDetail =
+  | {
+      readonly featureIdentity: string;
+      readonly order: number;
+      readonly stage: 'contribute';
+      readonly operation: string;
+      readonly resourceKind: PreparedKind;
+      readonly reason: 'missing-prepared-state';
+      readonly missingResource: string;
+      readonly recovery: RenderFeatureRecovery;
+    }
+  | {
+      readonly featureIdentity: string;
+      readonly order: number;
+      readonly stage: 'contribute';
+      readonly operation: string;
+      readonly resourceKind: PreparedKind;
+      readonly reason: 'foreign-feature';
+      readonly expectedFeatureIdentity: string;
+      readonly actualFeatureIdentity: string;
+      readonly recovery: RenderFeatureRecovery;
+    }
+  | {
+      readonly featureIdentity: string;
+      readonly order: number;
+      readonly stage: 'contribute';
+      readonly operation: string;
+      readonly resourceKind: PreparedKind;
+      readonly reason: 'foreign-kind';
+      readonly expectedKind: PreparedKind;
+      readonly actualKind: PreparedKind;
+      readonly recovery: RenderFeatureRecovery;
+    }
+  | {
+      readonly featureIdentity: string;
+      readonly order: number;
+      readonly stage: 'contribute';
+      readonly operation: string;
+      readonly resourceKind: PreparedKind;
+      readonly reason: 'generation-mismatch';
+      readonly expectedGeneration: number;
+      readonly actualGeneration: number;
+      readonly recovery: RenderFeatureRecovery;
+    }
+  | {
+      readonly featureIdentity: string;
+      readonly order: number;
+      readonly stage: 'contribute';
+      readonly operation: string;
+      readonly resourceKind: PreparedKind;
+      readonly reason: 'layout-mismatch';
+      readonly expectedLayout: string;
+      readonly actualLayout: string;
+      readonly recovery: RenderFeatureRecovery;
+    }
+  | {
+      readonly featureIdentity: string;
+      readonly order: number;
+      readonly stage: 'contribute';
+      readonly operation: string;
+      readonly resourceKind: PreparedKind;
+      readonly reason: 'format-mismatch';
+      readonly expectedFormat: string;
+      readonly actualFormat: string;
+      readonly recovery: RenderFeatureRecovery;
+    };
+
+export interface RenderFeatureDrawRecordingFailedDetail {
+  readonly featureIdentity: string;
+  readonly order: number;
+  readonly stage: 'record';
+  readonly operation: string;
+  readonly resourceKind: PreparedKind;
+  readonly reason: string;
+  readonly backendReason: string;
+  readonly recovery: RenderFeatureRecovery;
+}
+
+export type RenderFeatureErrorDetailByCode = {
+  'render-feature-registration-conflict': RenderFeatureRegistrationConflictDetail;
+  'render-feature-stage-failed': RenderFeatureStageFailedDetail;
+  'render-feature-capability-missing': RenderFeatureCapabilityMissingDetail;
+  'render-feature-pass-order-conflict': RenderFeaturePassOrderConflictDetail;
+  'render-feature-preparation-failed': RenderFeaturePreparationFailedDetail;
+  'render-feature-prepared-state-mismatch': RenderFeaturePreparedStateMismatchDetail;
+  'render-feature-draw-recording-failed': RenderFeatureDrawRecordingFailedDetail;
+};
+
+/** Machine-readable four-field diagnostic exposed by every feature error. */
+export type RenderFeatureErrorDescriptor = {
+  [Code in RenderFeatureErrorCode]: {
+    readonly code: Code;
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: RenderFeatureErrorDetailByCode[Code];
+  };
+}[RenderFeatureErrorCode];
+
+const renderFeatureRecoveryHintByRecovery = {
+  'next-frame': (featureIdentity: string, stage: RenderFeatureStage) =>
+    `correct '${featureIdentity}' ${stage} data and retry on the next frame`,
+  'renderer-recover': (featureIdentity: string, _stage: RenderFeatureStage) =>
+    `wait for renderer recovery before retrying '${featureIdentity}'`,
+  registration: (featureIdentity: string, _stage: RenderFeatureStage) =>
+    `correct '${featureIdentity}' registration before retrying`,
+} satisfies Record<
+  RenderFeatureRecovery,
+  (featureIdentity: string, stage: RenderFeatureStage) => string
+>;
+
+export class RenderFeatureRegistrationConflictError extends Error {
+  readonly code = 'render-feature-registration-conflict' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: RenderFeatureRegistrationConflictDetail;
+
+  constructor(featureIdentity: string, order: number, conflictingOrder: number) {
+    const expected = `feature identity '${featureIdentity}' is unique`;
+    const hint = `rename '${featureIdentity}' or remove the duplicate feature before registration`;
+    super(`render feature registration conflict for '${featureIdentity}'`);
+    this.name = 'RenderFeatureRegistrationConflictError';
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = { featureIdentity, order, conflictingOrder };
+  }
+}
+
+export class RenderFeatureStageFailedError extends Error {
+  readonly code = 'render-feature-stage-failed' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: RenderFeatureStageFailedDetail;
+
+  constructor(
+    featureIdentity: string,
+    order: number,
+    stage: RenderFeatureStage,
+    recovery: RenderFeatureRecovery,
+  ) {
+    const expected = `feature '${featureIdentity}' completes its ${stage} stage without an error`;
+    const hint = renderFeatureRecoveryHintByRecovery[recovery](featureIdentity, stage);
+    super(`render feature '${featureIdentity}' failed during ${stage}`);
+    this.name = 'RenderFeatureStageFailedError';
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = { featureIdentity, order, stage, recovery };
+  }
+}
+
+export class RenderFeatureCapabilityMissingError extends Error {
+  readonly code = 'render-feature-capability-missing' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: RenderFeatureCapabilityMissingDetail;
+
+  constructor(
+    featureIdentity: string,
+    order: number,
+    capability: RenderFeatureCapabilityMissingDetail['capability'],
+  ) {
+    const expected = `device capability '${capability}' is available for feature '${featureIdentity}'`;
+    const hint = `disable '${featureIdentity}' or use a device with '${capability}' capability`;
+    super(`render feature '${featureIdentity}' requires missing capability '${capability}'`);
+    this.name = 'RenderFeatureCapabilityMissingError';
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = { featureIdentity, order, capability };
+  }
+}
+
+export class RenderFeaturePassOrderConflictError extends Error {
+  readonly code = 'render-feature-pass-order-conflict' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: RenderFeaturePassOrderConflictDetail;
+
+  constructor(
+    featureIdentity: string,
+    order: number,
+    passIdentity: string,
+    dependencyIdentity: string,
+  ) {
+    const expected = `feature pass '${passIdentity}' follows dependency '${dependencyIdentity}'`;
+    const hint = `reorder '${featureIdentity}' passes so '${passIdentity}' follows '${dependencyIdentity}'`;
+    super(`render feature '${featureIdentity}' pass order conflict`);
+    this.name = 'RenderFeaturePassOrderConflictError';
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = { featureIdentity, order, passIdentity, dependencyIdentity };
+  }
+}
+
+export class RenderFeaturePreparationFailedError extends Error {
+  readonly code = 'render-feature-preparation-failed' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: RenderFeaturePreparationFailedDetail;
+
+  constructor(
+    featureIdentity: string,
+    order: number,
+    operation: string,
+    resourceKind: RenderFeaturePreparationFailedDetail['resourceKind'],
+    resourceName: string,
+    reason: string,
+    recovery: RenderFeatureRecovery,
+  ) {
+    const expected = `${resourceKind} '${resourceName}' is prepared during ${operation}`;
+    const hint = `repair '${resourceName}' and retry feature '${featureIdentity}' on ${recovery}`;
+    super(`render feature '${featureIdentity}' preparation failed for '${resourceName}'`);
+    this.name = 'RenderFeaturePreparationFailedError';
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = {
+      featureIdentity,
+      order,
+      stage: 'prepare',
+      operation,
+      resourceKind,
+      resourceName,
+      reason,
+      recovery,
+    };
+  }
+}
+
+export class RenderFeaturePreparedStateMismatchError extends Error {
+  readonly code = 'render-feature-prepared-state-mismatch' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: RenderFeaturePreparedStateMismatchDetail;
+
+  constructor(detail: RenderFeaturePreparedStateMismatchDetail) {
+    const expected = `${detail.resourceKind} state is compatible for '${detail.operation}'`;
+    const hint = `repair '${detail.reason}' for feature '${detail.featureIdentity}' and retry`;
+    super(`render feature '${detail.featureIdentity}' prepared state mismatch`);
+    this.name = 'RenderFeaturePreparedStateMismatchError';
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = detail;
+  }
+}
+
+export class RenderFeatureDrawRecordingFailedError extends Error {
+  readonly code = 'render-feature-draw-recording-failed' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: RenderFeatureDrawRecordingFailedDetail;
+
+  constructor(
+    featureIdentity: string,
+    order: number,
+    operation: string,
+    resourceKind: RenderFeatureDrawRecordingFailedDetail['resourceKind'],
+    reason: string,
+    backendReason: string,
+    recovery: RenderFeatureRecovery,
+  ) {
+    const expected = `${resourceKind} recording succeeds for '${operation}'`;
+    const hint = `repair '${reason}' and retry feature '${featureIdentity}' after ${recovery}`;
+    super(`render feature '${featureIdentity}' draw recording failed`);
+    this.name = 'RenderFeatureDrawRecordingFailedError';
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = {
+      featureIdentity,
+      order,
+      stage: 'record',
+      operation,
+      resourceKind,
+      reason,
+      backendReason,
+      recovery,
+    };
+  }
+}
+
+// ── ObservationUnavailableError ───────────────────────────────────────────
+
+export type ObservationUnavailableReason =
+  | 'no-frame'
+  | 'resource'
+  | 'copy-src'
+  | 'stale'
+  | 'identity'
+  | 'format'
+  | 'readback-failed';
+
+export interface ObservationUnavailableDetail {
+  readonly reason: ObservationUnavailableReason;
+  readonly recovery: 'draw-current-frame' | 'enable-copy-src' | 'retry-readback';
+}
+
+/** A producer-owned current-frame observation could not be made available. */
+export class ObservationUnavailableError extends Error {
+  readonly code = 'observation-unavailable' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: ObservationUnavailableDetail;
+
+  constructor(reason: ObservationUnavailableReason, hint: string) {
+    let recovery: ObservationUnavailableDetail['recovery'];
+    if (reason === 'copy-src') recovery = 'enable-copy-src';
+    else if (reason === 'resource' || reason === 'readback-failed') recovery = 'retry-readback';
+    else recovery = 'draw-current-frame';
+    super(`current-frame observation unavailable: ${reason}`);
+    this.name = 'ObservationUnavailableError';
+    this.expected = 'a fresh producer-owned rgba16float current-frame observation';
+    this.hint = hint;
+    this.detail = { reason, recovery };
+  }
+}
+
+export interface FrameReceiptStaleDetail {
+  readonly frameId: number;
+  readonly receiptGeneration: number;
+  readonly currentGeneration: number;
+}
+
+/** Receipt-bound observation failed closed at a generation fence. */
+export class FrameReceiptStaleError extends Error {
+  readonly code = 'frame-receipt-stale' as const;
+  readonly expected = 'the observation receipt belongs to the active device generation';
+  readonly hint = 'draw a new frame and call observe with its returned FrameReceipt';
+  readonly detail: FrameReceiptStaleDetail;
+
+  constructor(detail: FrameReceiptStaleDetail) {
+    super('frame receipt belongs to a retired device generation');
+    this.name = 'FrameReceiptStaleError';
+    this.detail = detail;
+  }
+}
+
+export interface RendererContractFailureDetail {
+  readonly operation: 'construct' | 'attach' | 'draw' | 'observe';
+  readonly cause: string;
+}
+
+/** Structured boundary failure while adapting an owner contract. */
+export class RendererContractFailureError extends Error {
+  readonly code = 'renderer-contract-failed' as const;
+  readonly expected = 'renderer owner contracts remain valid at the public boundary';
+  readonly hint = 'repair the owner contract and retry the operation';
+  readonly detail: RendererContractFailureDetail;
+
+  constructor(operation: RendererContractFailureDetail['operation'], cause: string) {
+    super(`renderer ${operation} contract failed: ${cause}`);
+    this.name = 'RendererContractFailureError';
+    this.detail = { operation, cause };
+  }
+}
+
+export interface RendererOperationCause {
+  readonly code: string;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail?: unknown;
+}
+
+export interface RendererOperationDetailByCode {
+  readonly 'world-lease-invalid': {
+    readonly operation: 'attach' | 'draw';
+    readonly cause: RendererOperationCause;
+  };
+  readonly 'frame-input-invalid': {
+    readonly operation: 'draw' | 'set-profile';
+    readonly cause: RendererOperationCause;
+  };
+  readonly 'scene-projection-failed': {
+    readonly operation: 'draw';
+    readonly cause: RendererOperationCause;
+  };
+  readonly 'asset-binding-failed': {
+    readonly operation: 'draw';
+    readonly cause: RendererOperationCause;
+  };
+  readonly 'feature-plan-failed': {
+    readonly operation: 'draw';
+    readonly cause: RendererOperationCause;
+  };
+  readonly 'graph-build-failed': {
+    readonly operation: 'draw' | 'set-profile';
+    readonly cause: RendererOperationCause;
+  };
+  readonly 'device-operation-failed': {
+    readonly operation: 'draw' | 'complete-frame' | 'renderer-event';
+    readonly frameId?: number;
+    readonly deviceGeneration?: number;
+    readonly cause: RendererOperationCause;
+  };
+  readonly 'surface-unavailable': {
+    readonly operation: 'release-surface' | 'restore-surface';
+    readonly cause: RendererOperationCause;
+  };
+  readonly 'renderer-state-invalid': {
+    readonly operation: 'draw' | 'set-profile' | 'recover' | 'dispose';
+    readonly state: string;
+    readonly cause?: RendererOperationCause;
+  };
+  readonly 'recovery-failed': {
+    readonly operation: 'recover';
+    readonly oldGeneration: number;
+    readonly cause: RendererOperationCause;
+  };
+  readonly 'cleanup-failed': {
+    readonly operation: 'dispose';
+    readonly causes: readonly RendererOperationCause[];
+  };
+}
+
+export type RendererOperationErrorCode = keyof RendererOperationDetailByCode;
+
+const RENDERER_OPERATION_ERROR_POLICY = {
+  'world-lease-invalid': {
+    expected: 'every render World is represented by a live lease owned by this Renderer',
+    hint: 'attach the World to this Renderer and use the returned lease',
+  },
+  'frame-input-invalid': {
+    expected: 'the frame input references attached leases and a valid immutable RenderProfile',
+    hint: 'repair the frame input and retry draw or setProfile',
+  },
+  'scene-projection-failed': {
+    expected: 'the attached World projects into the renderer-owned RenderScene',
+    hint: 'inspect the structured cause, repair the World publication, and retry draw',
+  },
+  'asset-binding-failed': {
+    expected: 'all frame assets resolve to valid renderer-owned bindings',
+    hint: 'inspect the structured cause, rebuild or cold-cook the asset, and retry draw',
+  },
+  'feature-plan-failed': {
+    expected: 'every installed RenderFeature produces a valid declarative plan',
+    hint: 'inspect the feature cause, repair its plan, and retry draw',
+  },
+  'graph-build-failed': {
+    expected: 'the Standard graph builds from the active profile and feature plans',
+    hint: 'inspect the graph cause, repair the profile or plan, and retry',
+  },
+  'device-operation-failed': {
+    expected: 'the active device generation completes the renderer-owned operation',
+    hint: 'inspect renderer state and the structured cause, then retry or recover',
+  },
+  'surface-unavailable': {
+    expected: 'the presentation surface accepts the requested lifecycle operation',
+    hint: 'inspect renderer state, then restore the surface or create a new Renderer',
+  },
+  'renderer-state-invalid': {
+    expected: 'the Renderer is in a state that accepts the requested operation',
+    hint: 'inspect renderer state and choose retry, restoreSurface, recover, or stop',
+  },
+  'recovery-failed': {
+    expected: 'one recovery attempt publishes a complete replacement device generation',
+    hint: 'inspect the structured cause and retry recover after the host-selected delay',
+  },
+  'cleanup-failed': {
+    expected: 'Renderer disposal completes every registered cleanup in reverse ownership order',
+    hint: 'inspect the ordered cleanup causes; the Renderer remains disposed and must not be reused',
+  },
+} as const satisfies Readonly<
+  Record<RendererOperationErrorCode, { readonly expected: string; readonly hint: string }>
+>;
+
+/** Public renderer-operation failure with a code-narrowed structured detail. */
+export class RendererOperationError<Code extends RendererOperationErrorCode> extends Error {
+  readonly code: Code;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: RendererOperationDetailByCode[Code];
+
+  constructor(code: Code, detail: RendererOperationDetailByCode[Code]) {
+    const policy = RENDERER_OPERATION_ERROR_POLICY[code];
+    super(`${code}: ${policy.expected}`);
+    this.name = 'RendererOperationError';
+    this.code = code;
+    this.expected = policy.expected;
+    this.hint = policy.hint;
+    this.detail = detail;
+  }
+}
+
+export type RendererExpectedOperationError = {
+  readonly [Code in RendererOperationErrorCode]: RendererOperationError<Code>;
+}[RendererOperationErrorCode];
+
+// -- Points/Lines admission errors -------------------------------------------
+
+export interface PointsLinesInvalidStyleDetail {
+  readonly entity: number;
+  readonly component: 'Points' | 'Lines' | 'Points/Lines';
+  readonly field: string;
+  readonly value: number | string | undefined;
+  readonly expected: string;
+}
+
+export class PointsLinesInvalidStyleError extends Error {
+  readonly code = 'points-lines-invalid-style' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: PointsLinesInvalidStyleDetail;
+
+  constructor(detail: PointsLinesInvalidStyleDetail) {
+    super(`invalid ${detail.component} style at ${detail.field}`);
+    this.name = 'PointsLinesInvalidStyleError';
+    this.expected = detail.expected;
+    this.hint = `repair entity ${detail.entity} ${detail.component}.${detail.field} and retry admission`;
+    this.detail = detail;
+  }
+}
+
+export interface PointsLinesTopologyMismatchDetail {
+  readonly entity: number;
+  readonly submesh: number;
+  readonly expected: string;
+  readonly actual: string;
+}
+
+export class PointsLinesTopologyMismatchError extends Error {
+  readonly code = 'points-lines-topology-mismatch' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: PointsLinesTopologyMismatchDetail;
+
+  constructor(detail: PointsLinesTopologyMismatchDetail) {
+    super(`Points/Lines topology mismatch at submesh ${detail.submesh}`);
+    this.name = 'PointsLinesTopologyMismatchError';
+    this.expected = `submesh ${detail.submesh} topology is ${detail.expected}`;
+    this.hint = `rebuild entity ${detail.entity} with ${detail.expected} geometry before retrying Points/Lines admission`;
+    this.detail = detail;
+  }
+}
+
+export interface PointsLinesStyleUnsupportedDetail {
+  readonly lane: string;
+  readonly field: string;
+  readonly member: string;
+  readonly supported: readonly string[];
+}
+
+export class PointsLinesStyleUnsupportedError extends Error {
+  readonly code = 'points-lines-style-unsupported' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: PointsLinesStyleUnsupportedDetail;
+
+  constructor(detail: PointsLinesStyleUnsupportedDetail) {
+    super(`unsupported Points/Lines ${detail.field} member ${detail.member}`);
+    this.name = 'PointsLinesStyleUnsupportedError';
+    this.expected = `${detail.field} is one of ${detail.supported.join(', ')}`;
+    this.hint = `use a supported Points/Lines ${detail.field} member or wait for a later milestone`;
+    this.detail = detail;
+  }
+}
+
+export interface PointsLinesMaterialUnsupportedDetail {
+  readonly entity: number;
+  readonly material: string;
+  readonly pass: string;
+  readonly module: string;
+  readonly reason: string;
+}
+
+export class PointsLinesMaterialUnsupportedError extends Error {
+  readonly code = 'points-lines-material-unsupported' as const;
+  readonly expected = 'one engine-owned unlit forward MaterialAsset pass';
+  readonly hint: string;
+  readonly detail: PointsLinesMaterialUnsupportedDetail;
+
+  constructor(detail: PointsLinesMaterialUnsupportedDetail) {
+    super(`Points/Lines material is unsupported on entity ${detail.entity}`);
+    this.name = 'PointsLinesMaterialUnsupportedError';
+    this.hint = `use Materials.unlit without a shadow-caster pass for entity ${detail.entity}`;
+    this.detail = detail;
+  }
+}
+
+export interface PointsLinesBudgetExceededDetail {
+  readonly lane: string;
+  readonly requested: number;
+  readonly limit: number;
+  readonly unit: 'points' | 'segments' | 'vertices' | 'indices' | 'bytes' | 'draws';
+}
+
+export class PointsLinesBudgetExceededError extends Error {
+  readonly code = 'points-lines-budget-exceeded' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: PointsLinesBudgetExceededDetail;
+
+  constructor(detail: PointsLinesBudgetExceededDetail) {
+    super(`Points/Lines ${detail.unit} budget exceeded`);
+    this.name = 'PointsLinesBudgetExceededError';
+    this.expected = `${detail.unit} <= ${detail.limit}`;
+    this.hint = `reduce Points/Lines ${detail.unit} or split the entity into bounded equivalent batches`;
+    this.detail = detail;
+  }
+}
+
+export interface PointsLinesPrepareFailedDetail {
+  readonly owner: string;
+  readonly generation: number;
+  readonly stage: 'prepare';
+  readonly cause: string;
+  readonly lastKnownGood: boolean;
+}
+
+export class PointsLinesPrepareFailedError extends Error {
+  readonly code = 'points-lines-prepare-failed' as const;
+  readonly expected = 'the complete Points/Lines candidate validates before publication';
+  readonly hint: string;
+  readonly detail: PointsLinesPrepareFailedDetail;
+
+  constructor(detail: PointsLinesPrepareFailedDetail) {
+    super(`Points/Lines prepare failed at generation ${detail.generation}`);
+    this.name = 'PointsLinesPrepareFailedError';
+    this.hint = detail.lastKnownGood
+      ? 'retain the last known good candidate, repair the producer, and retry prepare'
+      : 'repair the producer and retry prepare; the failed first candidate produces zero draw';
+    this.detail = detail;
+  }
+}
+
+// -- RenderErrorCode / RenderError closed unions --------------------------------
+
+/**
+ * Closed union of render-cluster error codes. AI users perform exhaustive
+ * `switch (err.code)` without default; TS guards completeness.
+ */
+export type RenderErrorCode = RenderError['code'];
+
+/**
+ * Closed union of the render-cluster structured error classes, each carrying a
+ * `RenderErrorCode` discriminant on `.code`.
+ */
+export type RenderError =
+  | LifecycleConstructionError
+  | RendererExpectedOperationError
+  | FrameReceiptStaleError
+  | RendererContractFailureError
+  | ObservationUnavailableError
+  | ShadowInvalidConfigError
+  | EquirectProjectionFailedError
+  | HdrpLightBudgetExceededError
+  | HdrpIndexListOverflowError
+  | HdrpDeferredCapsInsufficientError
+  | PointShadowAtlasUninitializedError
+  | PointShadowAtlasBoundsViolationError
+  | VideoUploadUnsupportedError
+  | VertexStorageBufferUnavailableError
+  | VertexColorVariantConflictError
+  | SkinPaletteOverflowError
+  | SkinMaterialMismatchError
+  | MaterialSkinAttrMissingError
+  | RenderFeatureRegistrationConflictError
+  | RenderFeatureStageFailedError
+  | RenderFeatureCapabilityMissingError
+  | RenderFeaturePassOrderConflictError
+  | RenderFeaturePreparationFailedError
+  | RenderFeaturePreparedStateMismatchError
+  | RenderFeatureDrawRecordingFailedError
+  | PointsLinesInvalidStyleError
+  | PointsLinesTopologyMismatchError
+  | PointsLinesStyleUnsupportedError
+  | PointsLinesMaterialUnsupportedError
+  | PointsLinesBudgetExceededError
+  | PointsLinesPrepareFailedError;