@forgeax/engine-render 0.1.4 → 0.1.6

package/src/errors/render.ts

@@ -13,70 +13,37 @@
 // SpotLight / PointLightShadow component validators (forward cross-directory
 // import, no cycle -- research Finding C2).
 
+import type { DeviceResourceKind, DeviceScopeReceipt } from '../device/resource-types';
 import type {
-  RenderFeatureCapabilityMissingDetail,
-  RenderFeatureDrawRecordingFailedDetail,
-  RenderFeaturePassOrderConflictDetail,
-  RenderFeaturePreparationFailedDetail,
-  RenderFeaturePreparedStateMismatchDetail,
+  PreparedKind,
+  RenderFeatureCapabilityKey,
   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;
+} 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;
 }
 
-/** 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;
+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(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 };
+  constructor(detail: LifecycleConstructionFailureDetail) {
+    super(`lifecycle-construction-failed: ${detail.resourceKind} lifecycle transaction failed`);
+    this.name = 'LifecycleConstructionError';
+    this.detail = detail;
   }
 }
 
@@ -217,48 +184,6 @@ export class EquirectProjectionFailedError extends Error {
   }
 }
 
-// ── 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 ───────────────────────────────────────────
 
 /**
@@ -348,7 +273,7 @@ export class HdrpIndexListOverflowError extends Error {
 /**
  * Detail for `RuntimeErrorCode 'hdrp-deferred-caps-insufficient'`.
  *
- * Emitted at `installPipeline(hdrpAsset)` time when `device.caps.maxColorAttachments < 4`,
+ * 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 {
@@ -359,13 +284,13 @@ export interface HdrpDeferredCapsInsufficientDetail {
 /**
  * Structured error for deferred-path capability gate failure.
  *
- * Emitted at `installPipeline(hdrpAsset)` time — synchronous throw.
+ * 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 (install-time caps check, no silent fallback)
+ * @see plan-strategy D-5 (capability validation, no silent fallback)
  */
 export class HdrpDeferredCapsInsufficientError extends Error {
   readonly code = 'hdrp-deferred-caps-insufficient' as const;
@@ -389,97 +314,6 @@ export class HdrpDeferredCapsInsufficientError extends Error {
   }
 }
 
-// ── 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 ─────────────────────────────────────
 
 /**
@@ -618,6 +452,33 @@ export class VertexStorageBufferUnavailableError extends Error {
   }
 }
 
+// ── 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. */
@@ -704,6 +565,157 @@ export class MaterialSkinAttrMissingError extends Error {
 
 // -- 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`,
@@ -919,283 +931,176 @@ export class ObservationUnavailableError extends Error {
   }
 }
 
-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;
+export interface FrameReceiptStaleDetail {
+  readonly frameId: number;
+  readonly receiptGeneration: number;
+  readonly currentGeneration: number;
 }
 
-/** 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 };
-  }
-}
+/** 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;
 
-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 };
+  constructor(detail: FrameReceiptStaleDetail) {
+    super('frame receipt belongs to a retired device generation');
+    this.name = 'FrameReceiptStaleError';
+    this.detail = detail;
   }
 }
 
-export interface EnvironmentSourceConflictDetail {
-  readonly atmosphereEntities: readonly number[];
-  readonly imageEntities: readonly number[];
+export interface RendererContractFailureDetail {
+  readonly operation: 'construct' | 'attach' | 'draw' | 'observe';
+  readonly cause: string;
 }
 
-/** 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],
-    };
+/** 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 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;
+export interface RendererOperationCause {
+  readonly code: string;
   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[];
+  readonly detail?: unknown;
 }
 
-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 interface RendererOperationDetailByCode {
+  readonly 'world-lease-invalid': {
+    readonly operation: 'attach' | 'draw';
+    readonly cause: RendererOperationCause;
   };
-}
-
-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;
+  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[];
   };
-
-  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;
+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: {
-    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 };
+  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];
+
 // -- RenderErrorCode / RenderError closed unions --------------------------------
 
 /**
@@ -1209,29 +1114,21 @@ export type RenderErrorCode = RenderError['code'];
  * `RenderErrorCode` discriminant on `.code`.
  */
 export type RenderError =
-  | FogOwnerConflictError
-  | FogParametersInvalidError
+  | LifecycleConstructionError
+  | RendererExpectedOperationError
+  | FrameReceiptStaleError
+  | RendererContractFailureError
   | ObservationUnavailableError
-  | TaaCapsInsufficientError
-  | TemporalUnsupportedError
-  | AtmosphereCardinalityInvalidError
-  | AtmosphereSunMissingError
-  | EnvironmentSourceConflictError
-  | AtmosphereParameterInvalidError
-  | AtmosphereCapsInsufficientError
-  | AtmosphereProducerFailedError
   | ShadowInvalidConfigError
   | EquirectProjectionFailedError
-  | HdrpCapsInsufficientError
   | HdrpLightBudgetExceededError
   | HdrpIndexListOverflowError
   | HdrpDeferredCapsInsufficientError
-  | GbufferRtAllocFailedError
-  | GbufferAttachmentCountMismatchError
   | PointShadowAtlasUninitializedError
   | PointShadowAtlasBoundsViolationError
   | VideoUploadUnsupportedError
   | VertexStorageBufferUnavailableError
+  | VertexColorVariantConflictError
   | SkinPaletteOverflowError
   | SkinMaterialMismatchError
   | MaterialSkinAttrMissingError