@forgeax/engine-render 0.1.2

package/src/errors/render.ts

@@ -0,0 +1,1244 @@
+// @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 {
+  RenderFeatureCapabilityMissingDetail,
+  RenderFeatureDrawRecordingFailedDetail,
+  RenderFeaturePassOrderConflictDetail,
+  RenderFeaturePreparationFailedDetail,
+  RenderFeaturePreparedStateMismatchDetail,
+  RenderFeatureRecovery,
+  RenderFeatureRegistrationConflictDetail,
+  RenderFeatureStage,
+  RenderFeatureStageFailedDetail,
+} from '../features/types';
+import type { MaterialRenderError } from '../renderer/material/pipeline-projection';
+
+// -- Scene Fog owner errors --------------------------------------------------
+
+/** Bounded identity facts for a resource-owner Fog cardinality conflict. */
+export interface FogOwnerConflictDetail {
+  readonly resourceOwner: number;
+  readonly entities: readonly number[];
+  readonly omitted: number;
+}
+
+/** The resource owner contains more than one Fog authoring entity. */
+export class FogOwnerConflictError extends Error {
+  readonly code = 'fog-owner-conflict' as const;
+  readonly expected = 'resourceOwner contains zero or one Fog entity';
+  readonly hint =
+    'remove every Fog entity except one from the resourceOwner World, then retry draw';
+  readonly detail: FogOwnerConflictDetail;
+
+  constructor(resourceOwner: number, entities: readonly number[], omitted: number) {
+    super(
+      `Fog owner conflict in resourceOwner ${resourceOwner}: ${entities.length + omitted} entities`,
+    );
+    this.name = 'FogOwnerConflictError';
+    this.detail = {
+      resourceOwner,
+      entities: [...entities],
+      omitted,
+    };
+  }
+}
+
+/** Structured detail for one invalid Fog field. */
+export interface FogParametersInvalidDetail {
+  readonly entity: number;
+  readonly field: string;
+  readonly expected: string;
+  readonly actual: unknown;
+}
+
+/** A resource-owner Fog entity contains an invalid authored parameter. */
+export class FogParametersInvalidError extends Error {
+  readonly code = 'fog-parameters-invalid' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: FogParametersInvalidDetail;
+
+  constructor(entity: number, field: string, expected: string, actual: unknown) {
+    super(`Fog.${field} is invalid on entity ${entity}`);
+    this.name = 'FogParametersInvalidError';
+    this.expected = expected;
+    this.hint = `set Fog.${field} to ${expected} on entity ${entity}, then retry draw`;
+    this.detail = { entity, field, expected, actual };
+  }
+}
+
+// ── 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 };
+  }
+}
+
+// ── HdrpCapsInsufficientError ──────────────────────────────────────────────
+
+/**
+ * Detail for `RuntimeErrorCode 'hdrp-caps-insufficient'`.
+ *
+ * Emitted at install time when `device.caps.maxStorageBuffersPerShaderStage < 4`.
+ */
+export interface HdrpCapsInsufficientDetail {
+  readonly capName: string;
+  readonly actual: number;
+  readonly required: number;
+}
+
+/**
+ * Structured error for HDRP storage-buffer capability gate failure (AC-17/AC-18).
+ *
+ * Emitted at `installPipeline(hdrpAsset)` time — synchronous throw.
+ *   - `.code = 'hdrp-caps-insufficient'` (closed RuntimeErrorCode)
+ *   - `.expected` — describes the required capability
+ *   - `.hint` — 'fall back to URP by not calling installPipeline'
+ *   - `.detail = { capName, actual, required }`
+ */
+export class HdrpCapsInsufficientError extends Error {
+  readonly code = 'hdrp-caps-insufficient' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: HdrpCapsInsufficientDetail;
+
+  constructor(capName: string, actual: number, required: number) {
+    const expected = `${capName} >= ${required}`;
+    const hint =
+      `${capName} = ${actual} (need >= ${required}); ` +
+      'this device does not have enough storage buffer slots for HDRP cluster-forward rendering. ' +
+      'Fall back to URP by not calling installPipeline(hdrpAsset)';
+    super(`HDRP caps insufficient: ${capName} = ${actual} (need >= ${required})`);
+    this.name = 'HdrpCapsInsufficientError';
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = { capName, actual, required };
+  }
+}
+
+// ── 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 at `installPipeline(hdrpAsset)` time when `device.caps.maxColorAttachments < 4`,
+ * 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 at `installPipeline(hdrpAsset)` time — 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 (install-time caps check, 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 };
+  }
+}
+
+// ── GbufferRtAllocFailedError ──────────────────────────────────────────────
+
+/**
+ * Detail for `RuntimeErrorCode 'gbuffer-rt-alloc-failed'`.
+ *
+ * Emitted at runtime when a g-buffer color target pool allocation fails
+ * (OOM or backend resource limit). The attachmentIndex identifies which
+ * g-buffer slot failed.
+ */
+export interface GbufferRtAllocFailedDetail {
+  readonly attachmentIndex: number;
+  readonly requestedBytes: number;
+}
+
+/**
+ * Structured error for g-buffer color-target pool allocation failure.
+ *
+ * Emitted at runtime during g-buffer pass setup.
+ *   - `.code = 'gbuffer-rt-alloc-failed'` (closed RuntimeErrorCode)
+ *   - `.expected` — 'g-buffer color target allocation succeeded'
+ *   - `.hint` — actionable recovery steps (check GPU memory / reduce resolution)
+ *   - `.detail = { attachmentIndex, requestedBytes }`
+ *
+ * @note This error is declared in M1 but only triggered in M2 (g-buffer RT
+ *   allocation path). The union member exists for compile-time narrowing now.
+ */
+export class GbufferRtAllocFailedError extends Error {
+  readonly code = 'gbuffer-rt-alloc-failed' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: GbufferRtAllocFailedDetail;
+
+  constructor(attachmentIndex: number, requestedBytes: number) {
+    const expected = 'g-buffer color target allocation succeeded';
+    const hint =
+      `g-buffer color target (attachment ${attachmentIndex}, ${requestedBytes} bytes) allocation failed. ` +
+      'Common causes: (a) GPU memory pressure; (b) framebuffer resolution too large; ' +
+      '(c) RHI backend limits hit. Check device.limits and reduce frame resolution.';
+    super(`g-buffer RT alloc failed: attachment[${attachmentIndex}] = ${requestedBytes} bytes`);
+    this.name = 'GbufferRtAllocFailedError';
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = { attachmentIndex, requestedBytes };
+  }
+}
+
+// ── GbufferAttachmentCountMismatchError ────────────────────────────────────
+
+/**
+ * Detail for `RuntimeErrorCode 'gbuffer-attachment-count-mismatch'`.
+ *
+ * Emitted at install-time when the g-buffer attachment count declared
+ * in the pipeline schema does not equal 3.
+ */
+export interface GbufferAttachmentCountMismatchDetail {
+  readonly actual: number;
+  readonly expected: number;
+}
+
+/**
+ * Structured error for g-buffer attachment count mismatch.
+ *
+ * Emitted at `installPipeline(hdrpAsset)` time via topology validation.
+ *   - `.code = 'gbuffer-attachment-count-mismatch'` (closed RuntimeErrorCode)
+ *   - `.expected` — 'exactly 3 g-buffer color attachments'
+ *   - `.hint` — check pipeline internal schema or custom g-buffer override
+ *   - `.detail = { actual, expected }`
+ *
+ * @note This error is declared in M1 but only triggered in M2 (g-buffer
+ *   topology validation). The union member exists for compile-time narrowing now.
+ */
+export class GbufferAttachmentCountMismatchError extends Error {
+  readonly code = 'gbuffer-attachment-count-mismatch' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: GbufferAttachmentCountMismatchDetail;
+
+  constructor(actual: number) {
+    const _expected = 3;
+    const _expectedStr = `exactly ${_expected} g-buffer color attachments`;
+    const hint =
+      `HDRP deferred expects ${_expected} g-buffer color attachments, got ${actual}. ` +
+      'Check hdrp-pipeline internal schema or custom g-buffer override.';
+    super(`g-buffer attachment count mismatch: got ${actual}, expected ${_expected}`);
+    this.name = 'GbufferAttachmentCountMismatchError';
+    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;
+  }
+}
+
+// ── 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 ---------------------------------------------------
+
+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 TaaCapsInsufficientDetail {
+  readonly rgba16floatRenderable: boolean;
+  readonly maxColorAttachments: number;
+  readonly recovery: 'enable-temporal-capabilities';
+}
+
+/** The active device cannot support the renderer-owned temporal attachments. */
+export class TaaCapsInsufficientError extends Error {
+  readonly code = 'taa-caps-insufficient' as const;
+  readonly expected = 'rgba16floatRenderable and maxColorAttachments >= 2';
+  readonly hint =
+    'select a device with rgba16float render targets and at least two color attachments, then rebuild the renderer';
+  readonly detail: TaaCapsInsufficientDetail;
+
+  constructor(rgba16floatRenderable: boolean, maxColorAttachments: number) {
+    super(
+      `TAA capabilities insufficient: rgba16floatRenderable=${rgba16floatRenderable}, maxColorAttachments=${maxColorAttachments}`,
+    );
+    this.name = 'TaaCapsInsufficientError';
+    this.detail = {
+      rgba16floatRenderable,
+      maxColorAttachments,
+      recovery: 'enable-temporal-capabilities',
+    };
+  }
+}
+
+export type TemporalUnsupportedReason =
+  | 'resolve-count'
+  | 'scene-color-domain'
+  | 'scene-color-sample-count'
+  | 'scene-depth-sample-count'
+  | 'temporal-attachment-missing'
+  | 'temporal-attachment-format'
+  | 'temporal-attachment-sample-count'
+  | 'resolve-resources-missing'
+  | 'resolve-frame-missing';
+
+export interface TemporalUnsupportedDetail {
+  readonly reason: TemporalUnsupportedReason;
+  readonly actual: string;
+  readonly recovery: 'fix-temporal-pipeline-topology';
+}
+
+/** A pipeline violated the single renderer-owned temporal resolve seam. */
+export class TemporalUnsupportedError extends Error {
+  readonly code = 'temporal-unsupported' as const;
+  readonly expected: string;
+  readonly hint =
+    'call resolveTemporal exactly once after temporal raster and pass single-sample rgba16float scene and temporal targets';
+  readonly detail: TemporalUnsupportedDetail;
+
+  constructor(reason: TemporalUnsupportedReason, expected: string, actual: string) {
+    super(`temporal pipeline unsupported: ${reason}; expected ${expected}, got ${actual}`);
+    this.name = 'TemporalUnsupportedError';
+    this.expected = expected;
+    this.detail = { reason, actual, recovery: 'fix-temporal-pipeline-topology' };
+  }
+}
+
+// -- Analytic sky authoring/source errors ----------------------------------
+
+export type AtmosphereField =
+  | 'turbidity'
+  | 'rayleigh'
+  | 'mieCoefficient'
+  | 'mieDirectionalG'
+  | 'sunAngularRadius';
+
+export interface AtmosphereParameterInvalidDetail {
+  readonly field: AtmosphereField;
+  readonly value: number;
+  readonly min: number;
+  readonly max: number;
+  readonly minExclusive: boolean;
+}
+
+/** A finite Atmosphere field is outside its authoring range. */
+export class AtmosphereParameterInvalidError extends Error {
+  readonly code = 'atmosphere-parameter-invalid' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: AtmosphereParameterInvalidDetail;
+
+  constructor(
+    field: AtmosphereField,
+    value: number,
+    min: number,
+    max: number,
+    minExclusive = false,
+  ) {
+    const lower = minExclusive ? `>${min}` : `>=${min}`;
+    super(`Atmosphere.${field} must be ${lower} and <=${max}; got ${value}`);
+    this.name = 'AtmosphereParameterInvalidError';
+    this.expected = `${field} ${lower} and <=${max}`;
+    this.hint = `set Atmosphere.${field} to a finite value in the accepted range; got ${value}`;
+    this.detail = { field, value, min, max, minExclusive };
+  }
+}
+
+export interface AtmosphereCardinalityInvalidDetail {
+  readonly count: number;
+  readonly max: 1;
+  readonly entities: readonly number[];
+}
+
+/** More than one Atmosphere authoring component exists in one resource World. */
+export class AtmosphereCardinalityInvalidError extends Error {
+  readonly code = 'atmosphere-cardinality-invalid' as const;
+  readonly expected = 'exactly one Atmosphere component in the resourceOwner World';
+  readonly hint = 'remove extra Atmosphere entities and keep one analytic source';
+  readonly detail: AtmosphereCardinalityInvalidDetail;
+
+  constructor(count: number, entities: readonly number[]) {
+    super(`Atmosphere cardinality exceeded: ${count} entities (max 1)`);
+    this.name = 'AtmosphereCardinalityInvalidError';
+    this.detail = { count, max: 1, entities: [...entities] };
+  }
+}
+
+export interface AtmosphereSunMissingDetail {
+  readonly atmosphereEntity: number;
+}
+
+/** An Atmosphere entity is not a Sun unless its same entity carries DirectionalLight. */
+export class AtmosphereSunMissingError extends Error {
+  readonly code = 'atmosphere-sun-missing' as const;
+  readonly expected = 'Atmosphere and DirectionalLight share one entity';
+  readonly hint = 'add a valid DirectionalLight to the Atmosphere entity';
+  readonly detail: AtmosphereSunMissingDetail;
+
+  constructor(atmosphereEntity: number) {
+    super(`Atmosphere entity ${atmosphereEntity} has no co-located DirectionalLight`);
+    this.name = 'AtmosphereSunMissingError';
+    this.detail = { atmosphereEntity };
+  }
+}
+
+export interface EnvironmentSourceConflictDetail {
+  readonly atmosphereEntities: readonly number[];
+  readonly imageEntities: readonly number[];
+}
+
+/** Image and analytic environment facts cannot silently choose a precedence. */
+export class EnvironmentSourceConflictError extends Error {
+  readonly code = 'environment-source-conflict' as const;
+  readonly expected = 'exactly one image or atmosphere environment source';
+  readonly hint = 'remove either the image environment or the Atmosphere source';
+  readonly detail: EnvironmentSourceConflictDetail;
+
+  constructor(atmosphereEntities: readonly number[], imageEntities: readonly number[]) {
+    super('image and Atmosphere environment sources cannot coexist');
+    this.name = 'EnvironmentSourceConflictError';
+    this.detail = {
+      atmosphereEntities: [...atmosphereEntities],
+      imageEntities: [...imageEntities],
+    };
+  }
+}
+
+export interface AtmosphereCapsInsufficientDetail {
+  readonly capability: string;
+  readonly actual: boolean | number;
+  readonly required: boolean | number;
+}
+
+/** The selected device cannot render the required HDR atmosphere resources. */
+export class AtmosphereCapsInsufficientError extends Error {
+  readonly code = 'atmosphere-caps-insufficient' as const;
+  readonly expected: string;
+  readonly hint = 'select a backend with the required HDR render and sample capabilities';
+  readonly detail: AtmosphereCapsInsufficientDetail;
+
+  constructor(capability: string, actual: boolean | number, required: boolean | number) {
+    super(`Atmosphere capability ${capability} is insufficient: ${actual}; required ${required}`);
+    this.name = 'AtmosphereCapsInsufficientError';
+    this.expected = `${capability} >= ${required}`;
+    this.detail = { capability, actual, required };
+  }
+}
+
+export interface AtmosphereProducerFailedDetail {
+  readonly stage: 'build' | 'execute' | 'submit';
+  readonly reason: string;
+  readonly generation?: number;
+}
+
+/** The candidate atmosphere producer did not complete atomically. */
+export class AtmosphereProducerFailedError extends Error {
+  readonly code = 'atmosphere-producer-failed' as const;
+  readonly expected = 'candidate atmosphere generation builds, executes, and submits atomically';
+  readonly hint =
+    'retain the last-known-good generation, inspect the stage, and retry after repair';
+  readonly detail: AtmosphereProducerFailedDetail;
+
+  constructor(stage: AtmosphereProducerFailedDetail['stage'], reason: string, generation?: number) {
+    super(`Atmosphere producer ${stage} failed: ${reason}`);
+    this.name = 'AtmosphereProducerFailedError';
+    this.detail = { stage, reason, ...(generation === undefined ? {} : { generation }) };
+  }
+}
+
+/**
+ * Render-owned projection of a failed material readiness result.
+ *
+ * The readiness owner supplies the structured fields; render adds only the
+ * stable draw dedupe key. This is a diagnostic fact, not a second error or
+ * material registry.
+ */
+export interface MaterialDrawDiagnostic {
+  readonly key: string;
+  readonly code: MaterialRenderError['error']['code'];
+  readonly materialGuid: string;
+  readonly specializationKey: string;
+  readonly publicationGeneration?: number;
+  readonly expected: string;
+  readonly actual?: string;
+  readonly hint: string;
+  readonly retryable: boolean;
+  readonly recoveryActions: readonly string[];
+}
+
+export function materialDrawDiagnostic(error: MaterialRenderError): MaterialDrawDiagnostic {
+  const detail = error.error.detail;
+  const generation = detail.publicationGeneration;
+  return {
+    key: `${detail.guid}::${detail.specializationKey}::${generation ?? 'unknown'}`,
+    code: error.error.code,
+    materialGuid: detail.guid,
+    specializationKey: detail.specializationKey,
+    ...(generation === undefined ? {} : { publicationGeneration: generation }),
+    expected: error.error.expected,
+    ...(detail.actual === undefined ? {} : { actual: detail.actual }),
+    hint: error.error.hint,
+    retryable: error.error.retryable,
+    recoveryActions: error.error.recoveryActions,
+  };
+}
+
+export class MeshSsboCeilingReachedError extends Error {
+  readonly code = 'mesh-ssbo-ceiling-reached' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: {
+    readonly requested: number;
+    readonly capacity: number;
+    readonly ceiling: number;
+  };
+
+  constructor(requested: number, capacity: number, ceiling: number) {
+    super(`mesh SSBO request ${requested} exceeds device ceiling ${ceiling}`);
+    this.name = 'MeshSsboCeilingReachedError';
+    this.expected = `mesh SSBO capacity remains within ${ceiling} bytes`;
+    this.hint = 'reduce per-frame renderable count or split the workload across frames';
+    this.detail = { requested, capacity, ceiling };
+  }
+}
+
+export class MeshSsboCapacityExceededError extends Error {
+  readonly code = 'mesh-ssbo-capacity-exceeded' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: {
+    readonly requested: number;
+    readonly capacity: number;
+    readonly ceiling: number;
+  };
+
+  constructor(requested: number, capacity: number, ceiling: number) {
+    super(`mesh SSBO capacity ${capacity} cannot satisfy request ${requested}`);
+    this.name = 'MeshSsboCapacityExceededError';
+    this.expected = `mesh SSBO capacity >= ${requested} slots`;
+    this.hint = 'reduce per-frame renderable count or split the workload across frames';
+    this.detail = { requested, capacity, ceiling };
+  }
+}
+
+// -- 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 =
+  | FogOwnerConflictError
+  | FogParametersInvalidError
+  | ObservationUnavailableError
+  | TaaCapsInsufficientError
+  | TemporalUnsupportedError
+  | AtmosphereCardinalityInvalidError
+  | AtmosphereSunMissingError
+  | EnvironmentSourceConflictError
+  | AtmosphereParameterInvalidError
+  | AtmosphereCapsInsufficientError
+  | AtmosphereProducerFailedError
+  | ShadowInvalidConfigError
+  | EquirectProjectionFailedError
+  | HdrpCapsInsufficientError
+  | HdrpLightBudgetExceededError
+  | HdrpIndexListOverflowError
+  | HdrpDeferredCapsInsufficientError
+  | GbufferRtAllocFailedError
+  | GbufferAttachmentCountMismatchError
+  | PointShadowAtlasUninitializedError
+  | PointShadowAtlasBoundsViolationError
+  | VideoUploadUnsupportedError
+  | VertexStorageBufferUnavailableError
+  | SkinPaletteOverflowError
+  | SkinMaterialMismatchError
+  | MaterialSkinAttrMissingError
+  | RenderFeatureRegistrationConflictError
+  | RenderFeatureStageFailedError
+  | RenderFeatureCapabilityMissingError
+  | RenderFeaturePassOrderConflictError
+  | RenderFeaturePreparationFailedError
+  | RenderFeaturePreparedStateMismatchError
+  | RenderFeatureDrawRecordingFailedError;