@forgeax/engine-render 0.1.21 → 0.1.24

package/src/environment/lifecycle.ts

@@ -1,7 +1,7 @@
 import { err, ok, type Result } from '@forgeax/engine-types';
-import type { DeviceScope } from '../device/device-scope';
+import type { DeviceScope, LifecycleResourceSpec } from '../device/device-scope';
 import { EnvironmentGenerationFailedError } from '../errors/render';
-import type { EnvironmentFrame } from './frame';
+import { type EnvironmentFrame, SKYLIGHT_RECOVERY_FALLBACK } from './frame';
 import type { EnvironmentGeneration, EnvironmentGenerationFailure } from './generation';
 import { sharedEnvironmentFrame } from './graph';
 import {
@@ -20,8 +20,11 @@ interface RetiredGeneration {
   readonly generation: EnvironmentGeneration;
 }
 
+let nextEnvironmentToken = 1;
+
 /** Owns candidate, active, LKG, and DeviceScope generation transitions. */
 export class EnvironmentLifecycle {
+  private readonly token = nextEnvironmentToken++;
   private currentScope: DeviceScope;
   private nextGeneration = 0;
   private active: EnvironmentGeneration | undefined;
@@ -31,6 +34,13 @@ export class EnvironmentLifecycle {
   private readonly retired: RetiredGeneration[] = [];
   private readonly leaseCounts = new Map<number, number>();
   private lastCandidateFailure: EnvironmentInspectionFailure | undefined;
+  private recovery:
+    | {
+        readonly deviceGeneration: number;
+        readonly frame: EnvironmentFrame;
+        readonly lane: 'direct' | 'clustered';
+      }
+    | undefined;
 
   constructor(scope: DeviceScope) {
     this.currentScope = scope;
@@ -41,8 +51,69 @@ export class EnvironmentLifecycle {
     this.currentScope = scope;
   }
 
+  resetForRecover(deviceGeneration: number): void {
+    if (!Number.isSafeInteger(deviceGeneration) || deviceGeneration < 0) {
+      throw new RangeError('deviceGeneration must be a non-negative safe integer.');
+    }
+    const frame = this.active === undefined ? undefined : this.frames.get(this.active.signature);
+    if (frame !== undefined) {
+      this.recovery = Object.freeze({
+        deviceGeneration,
+        frame,
+        lane: this.active?.lane ?? 'direct',
+      });
+    }
+  }
+
+  /**
+   * Create an environment owner for a recovery candidate without moving the
+   * active owner's scope or generation maps. Only the selected CPU frame and
+   * its lane are shared; every candidate generation/frame map starts empty.
+   */
+  createRecoveryCandidate(scope: DeviceScope): EnvironmentLifecycle {
+    const candidate = new EnvironmentLifecycle(scope);
+    const activeFrame =
+      this.recovery?.frame ??
+      (this.active === undefined ? undefined : this.frames.get(this.active.signature));
+    if (activeFrame !== undefined) {
+      candidate.recovery = Object.freeze({
+        deviceGeneration: scope.generation,
+        frame: activeFrame,
+        lane: this.recovery?.lane ?? this.active?.lane ?? 'direct',
+      });
+    }
+    candidate.lastCandidateFailure = this.lastCandidateFailure;
+    return candidate;
+  }
+
+  /** True when a CPU environment frame is available for candidate recovery. */
+  hasRecoveryFrame(): boolean {
+    return (
+      this.recovery?.frame !== undefined ||
+      (this.active !== undefined && this.frames.has(this.active.signature))
+    );
+  }
+
+  createRecoveryRoot(scope: DeviceScope): LifecycleResourceSpec<unknown> {
+    return {
+      kind: 'texture',
+      create: async () => {
+        const recovered = await this.recover(scope);
+        if (!recovered.ok) throw recovered.error;
+        return recovered.value;
+      },
+      cleanup: (value) => {
+        this.discard(value as EnvironmentGeneration);
+      },
+    };
+  }
+
   isActive(generation: EnvironmentGeneration): boolean {
-    return this.active === generation;
+    return (
+      this.active?.generation === generation.generation &&
+      this.active.signature === generation.signature &&
+      this.active.scope === generation.scope
+    );
   }
 
   discard(generation: EnvironmentGeneration): void {
@@ -52,6 +123,14 @@ export class EnvironmentLifecycle {
     this.frames.delete(generation.signature);
     generation.retired = true;
     generation.scope.retire();
+    if (this.recovery?.frame.signature === generation.signature) this.recovery = undefined;
+    if (this.candidates.size === 0) this.recovery = undefined;
+  }
+
+  /** Drop every uncommitted generation owned by an abandoned candidate. */
+  discardRecoveryCandidates(): void {
+    for (const generation of [...this.candidates.values()]) this.discard(generation);
+    this.recovery = undefined;
   }
 
   recordCandidateFailure(error: EnvironmentGenerationFailedError): void {
@@ -106,6 +185,9 @@ export class EnvironmentLifecycle {
         ),
       );
     }
+    if (this.active?.signature === frame.signature && this.active.scope.isAlive()) {
+      return ok(this.active.lane === lane ? this.active : this.laneView(this.active, lane));
+    }
     const existing = this.candidates.get(frame.signature);
     if (existing?.scope.isAlive()) {
       return ok(existing.lane === lane ? existing : this.laneView(existing, lane));
@@ -150,6 +232,28 @@ export class EnvironmentLifecycle {
     }
     this.active = generation;
     this.lkg = generation;
+    this.recovery = undefined;
+  }
+
+  /** Close the old active generation before a replacement owner is installed. */
+  retireActiveForReplacement(): void {
+    const active = this.active;
+    if (active === undefined) return;
+    this.active = undefined;
+    if (this.lkg === active) this.lkg = undefined;
+    active.retired = true;
+    active.scope.retire();
+    this.recovery = undefined;
+  }
+
+  /** Close an already-published generation when its owning scope retires. */
+  retirePublishedGeneration(generation: EnvironmentGeneration): void {
+    if (this.active !== generation) return;
+    this.active = undefined;
+    if (this.lkg === generation) this.lkg = undefined;
+    generation.retired = true;
+    generation.scope.retire();
+    this.recovery = undefined;
   }
 
   acquire(): EnvironmentLease {
@@ -230,24 +334,33 @@ export class EnvironmentLifecycle {
       ...(this.lastCandidateFailure === undefined
         ? {}
         : { lastCandidateFailure: this.lastCandidateFailure }),
+      ...(this.recovery === undefined
+        ? {}
+        : {
+            recovery: {
+              token: this.token,
+              deviceGeneration: this.recovery.deviceGeneration,
+              status: 'uninitialized' as const,
+              fallback: SKYLIGHT_RECOVERY_FALLBACK.kind,
+            },
+          }),
     });
   }
 
   async recover(
     scope: DeviceScope,
   ): Promise<Result<EnvironmentGeneration, EnvironmentGenerationFailedError>> {
-    if (this.active === undefined)
-      return err(new EnvironmentGenerationFailedError('none', 'prepare'));
     this.currentScope = scope;
     const previous = this.active;
-    this.candidates.delete(previous.signature);
-    const previousFrame = this.frames.get(previous.signature);
+    const previousFrame =
+      this.recovery?.frame ??
+      (previous === undefined ? undefined : this.frames.get(previous.signature));
     if (previousFrame === undefined) {
       return err(new EnvironmentGenerationFailedError('none', 'prepare'));
     }
     const result = await this.ensure(
-      sharedEnvironmentFrame(previousFrame, previous.lane),
-      previous.lane,
+      sharedEnvironmentFrame(previousFrame, previous?.lane ?? 'direct'),
+      this.recovery?.lane ?? previous?.lane ?? 'direct',
     );
     if (!result.ok) return result;
     return ok(result.value);

package/src/errors/gpu-driven.ts

@@ -0,0 +1,92 @@
+import type { MaterialShaderArtifactReceipt } from '@forgeax/engine-shader';
+
+export type GpuDrivenPreparationErrorCode =
+  | 'missing-material-receipt'
+  | 'missing-uv'
+  | 'reflection-mismatch'
+  | 'vertex-input-mismatch'
+  | 'alpha-mask-mismatch'
+  | 'resource-not-ready'
+  | 'stale-generation'
+  | 'skin-receipt-mismatch';
+
+export type GpuDrivenPreparationReason =
+  | 'material-receipt-missing'
+  | 'uv-set-missing'
+  | 'reflection-receipt-mismatch'
+  | 'vertex-semantic-mismatch'
+  | 'alpha-mask-receipt-missing'
+  | 'material-resource-missing'
+  | 'generation-stale'
+  | 'skin-address-missing';
+
+export interface GpuDrivenPreparationErrorDetail {
+  readonly reason: GpuDrivenPreparationReason;
+  readonly owner: 'material' | 'geometry' | 'skin' | 'generation';
+  readonly expected?: string;
+  readonly actual?: string;
+  readonly expectedGeneration?: number;
+  readonly actualGeneration?: number;
+}
+
+const ERROR_POLICY: Readonly<
+  Record<GpuDrivenPreparationErrorCode, { readonly expected: string; readonly hint: string }>
+> = {
+  'missing-material-receipt': {
+    expected: 'a producer-owned Standard PBR material receipt is present',
+    hint: 'cook and load the Standard PBR artifact, then retry preparation',
+  },
+  'missing-uv': {
+    expected: 'the geometry exposes every UV set named by the material receipt',
+    hint: 'repair the geometry UV semantic or route the draw to the CPU semantic lane',
+  },
+  'reflection-mismatch': {
+    expected: 'the loaded reflection receipt matches the artifact layout identity',
+    hint: 'rebuild the material artifact and reflection from one source, then retry',
+  },
+  'vertex-input-mismatch': {
+    expected: 'geometry vertex semantics match the material reflection receipt',
+    hint: 'repair the geometry vertex semantic layout or route the draw to the CPU lane',
+  },
+  'alpha-mask-mismatch': {
+    expected: 'the Alpha Mask cutoff is present in the material receipt',
+    hint: 'declare alphaCutoff in the Standard PBR material schema and recook it',
+  },
+  'resource-not-ready': {
+    expected: 'all material resource slots have resolved handles',
+    hint: 'resolve the declared texture and sampler resources before recording',
+  },
+  'stale-generation': {
+    expected: 'receipt and prepared inputs belong to the requested generation',
+    hint: 'discard stale GPU facts, rebuild the producer receipt, and retry the same draw',
+  },
+  'skin-receipt-mismatch': {
+    expected: 'skinned geometry has a current palette address receipt',
+    hint: 'rebuild the Skin palette receipt for this generation before recording',
+  },
+};
+
+export class GpuDrivenPreparationError extends Error {
+  readonly code: GpuDrivenPreparationErrorCode;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: GpuDrivenPreparationErrorDetail;
+
+  constructor(code: GpuDrivenPreparationErrorCode, detail: GpuDrivenPreparationErrorDetail) {
+    const policy = ERROR_POLICY[code];
+    super(`[GpuDrivenPreparationError ${code}] ${policy.expected}`);
+    this.name = 'GpuDrivenPreparationError';
+    this.code = code;
+    this.expected = policy.expected;
+    this.hint = policy.hint;
+    this.detail = detail;
+  }
+}
+
+export interface GpuDrivenPreparedMaterial {
+  readonly receipt: MaterialShaderArtifactReceipt;
+  readonly resourceSlots: MaterialShaderArtifactReceipt['resourceSlots'];
+  readonly uvSets: MaterialShaderArtifactReceipt['uvSets'];
+  readonly vertexInputs: MaterialShaderArtifactReceipt['vertexInputs'];
+  readonly alphaMask: MaterialShaderArtifactReceipt['alphaMask'];
+}

package/src/errors/index.ts

@@ -1,3 +1,4 @@
 export * from './ecs-validation';
+export * from './gpu-driven';
 export * from './recover';
 export * from './render';

package/src/errors/recover.ts

@@ -6,7 +6,51 @@
 // `recover(): Promise<Result<void, RecoverFailure>>`, NOT the onError fanout
 // channel (see render-contract.ts RendererError composition).
 
-import type { DeviceScopeReceipt } from '../device/resource-types';
+import type { RecoveryGuidance, RecoveryPhase } from '../assembly/renderer-lifecycle';
+import type { DeviceResourceKind, DeviceScopeReceipt } from '../device/resource-types';
+import type { ReflectionFallbackRecoveryAction } from '../inspection-types';
+import type { SsrAdmissionError, SsrOwnerRecoveryAction } from '../ssr/errors';
+
+export type { RecoveryGuidance, RecoveryPhase } from '../assembly/renderer-lifecycle';
+export { RECOVERY_PHASES } from '../assembly/renderer-lifecycle';
+export type { ReflectionFallbackRecoveryAction } from '../inspection-types';
+
+export function reflectionFallbackRecoveryAction(
+  source: 'probe' | 'skylight' | 'neutral',
+  hasLastKnownGood: boolean,
+): ReflectionFallbackRecoveryAction {
+  if (source === 'probe' && hasLastKnownGood) return 'use-LKG';
+  if (source === 'skylight') return 'use-Skylight';
+  return 'use-neutral';
+}
+
+/**
+ * Maps a detached admission failure to the owning producer action. This is
+ * an instruction projection only; SSR never performs the recovery itself.
+ */
+export function ssrAdmissionRecoveryAction(error: SsrAdmissionError): SsrOwnerRecoveryAction {
+  switch (error.code) {
+    case 'ssr-not-requested':
+    case 'ssr-receipt-stale':
+      return 'retry';
+    case 'ssr-reflection-fallback-unavailable':
+      return error.detail.action;
+    case 'ssr-format-unavailable':
+    case 'ssr-temporal-unavailable':
+      return error.detail.action;
+    case 'ssr-receipt-identity-mismatch':
+      return 'rebuild';
+  }
+}
+
+/** Closed outcome vocabulary shared by recovery inspection and errors. */
+export type RecoveryOutcome = 'none' | 'succeeded' | 'failed' | 'disposed';
+
+/**
+ * `RecoveryPhase` is the stable lower-case hyphenated phase union used by
+ * inspect/recovery detail. `RecoveryGuidance` is the closed next-action union:
+ * retry the attempt, repair its owner, or rebuild the Renderer.
+ */
 
 // ── RecoverError (feat-20260621-renderer-health-recover-skeleton M1) ─────────
 
@@ -41,13 +85,13 @@ const RECOVER_ERROR_POLICY = {
   'recover-not-needed': {
     message: 'recover-not-needed: renderer is not in a degraded state',
     expected:
-      'renderer is healthy; call health() first to confirm degraded state before calling recover()',
-    hint: 'call health() first to confirm degraded state before calling recover()',
+      'renderer is healthy; use state() or inspect() to confirm degraded state before calling recover()',
+    hint: 'use state() or inspect().state to confirm degraded state before calling recover()',
   },
   'recover-not-implemented': {
     message: 'recover-not-implemented: self-heal recovery is not yet implemented',
     expected: 'recovery is not yet implemented; self-heal lands in S5',
-    hint: 'self-heal recovery lands in S5; health().reason still reflects the degraded state',
+    hint: 'self-heal recovery lands in S5; inspect().state still reflects the lifecycle state',
   },
   'recover-adapter-unavailable': {
     message: 'recover-adapter-unavailable: requestAdapter returned no adapter during rebuild',
@@ -95,6 +139,60 @@ export class RecoverError extends Error {
   }
 }
 
+export interface RecoveryFailureDetail {
+  /** The bounded phase that produced this failure. */
+  readonly phase: RecoveryPhase;
+  /** Active generation before the attempt; it changes only on publish. */
+  readonly oldGeneration: number;
+  /** Candidate generation; it changes only on publish. */
+  readonly candidateGeneration: number;
+  /** Monotonic explicit recovery attempt number. */
+  readonly attempt: number;
+  /** Wall-clock duration of this bounded attempt. */
+  readonly elapsedMs: number;
+  /** Whether the caller may explicitly retry without recreating the Renderer. */
+  readonly retryable: boolean;
+  /** Next action selected by the recovery owner. */
+  readonly guidance: RecoveryGuidance;
+  /** Producer or lifecycle owner that must be inspected first. */
+  readonly owner: string;
+  /** Structured resource category, never a raw GPU handle. */
+  readonly resourceKind: DeviceResourceKind;
+  /** Terminal outcome of this attempt. */
+  readonly lastOutcome: Exclude<RecoveryOutcome, 'none' | 'succeeded'>;
+  /** Number of candidate roots committed before publication. */
+  readonly rehydratedRoots: number;
+  /** Number of late notifications ignored from retired generations. */
+  readonly staleLossEvents: number;
+  /** Original structured cause retained for diagnostics. */
+  readonly cause: unknown;
+  /** Cleanup failures that prevented a complete candidate publication. */
+  readonly cleanupFailures: readonly unknown[];
+  /** Detached lifecycle receipt for the failed candidate. */
+  readonly receipt: DeviceScopeReceipt;
+}
+
+/** Stable structured failure returned by one bounded recovery attempt. */
+export class RecoveryFailedError extends Error {
+  readonly code = 'recovery-failed' as const;
+  readonly expected = 'one recovery attempt publishes a complete replacement device generation';
+  readonly hint = 'inspect detail and follow its guidance';
+  readonly detail: RecoveryFailureDetail;
+
+  constructor(detail: RecoveryFailureDetail) {
+    super('renderer recovery failed');
+    this.name = 'RecoveryFailedError';
+    this.detail = Object.freeze({
+      ...detail,
+      cleanupFailures: Object.freeze([...detail.cleanupFailures]),
+    });
+  }
+}
+
+export function createRecoveryFailedError(detail: RecoveryFailureDetail): RecoveryFailedError {
+  return new RecoveryFailedError(detail);
+}
+
 const RENDER_RECOVERY_ERROR_POLICY = {
   'recover-lifecycle-failed': {
     expected: 'the replacement DeviceScope must publish only after lifecycle cleanup succeeds',
@@ -109,10 +207,15 @@ const RENDER_RECOVERY_ERROR_POLICY = {
 export type RenderRecoveryErrorCode = keyof typeof RENDER_RECOVERY_ERROR_POLICY;
 
 export interface RenderRecoveryFailureDetail {
+  /** Producer/lifecycle owner whose recovery operation failed. */
   readonly owner: string;
+  /** Device generation associated with the failed recovery operation. */
   readonly generation: number;
+  /** Closed operation kind; no implicit background retry is represented. */
   readonly recovery: 'recover' | 'rebuild' | 'stop';
+  /** Lifecycle receipt retained as structured evidence, not a live handle. */
   readonly receipt: DeviceScopeReceipt;
+  /** Original structured cause for the failed operation. */
   readonly cause: unknown;
 }
 
@@ -133,7 +236,7 @@ export class RenderRecoveryError extends Error {
   }
 }
 
-export type RecoverFailure = RecoverError | RenderRecoveryError;
+export type RecoverFailure = RecoverError | RenderRecoveryError | RecoveryFailedError;
 
 export type IblCapabilityLossCode = 'ibl-hdr-capability-loss';
 

package/src/errors/render.ts

@@ -27,6 +27,11 @@ import type {
 } from '../features/vocabulary';
 import type { SceneDataLane, SceneDataSchemaId } from '../temporal/scene-data';
 import type { TransmissionCapabilityFact } from '../transmission/backdrop';
+import type { RecoveryOutcome, RecoveryPhase } from './recover';
+
+// Public render errors keep one machine-readable order: closed `code`,
+// expected state, actionable `hint`, then typed `detail`. Consumers branch on
+// that shape and never use Error.message as a protocol.
 
 export interface LifecycleConstructionFailureDetail {
   readonly owner: string;
@@ -116,6 +121,60 @@ export function createRenderSurfaceError(
   return new RenderSurfaceError(`surface-${kind}-failed` as SurfaceFailureCode, detail);
 }
 
+export type LightResourceFailureReason = 'asset' | 'format' | 'capability' | 'capacity';
+
+export interface LightResourceUnavailableDetail {
+  readonly entity: number;
+  readonly feature: 'ies' | 'cookie' | 'probe';
+  readonly generation: number;
+  readonly sourceKey: string;
+  readonly reason: LightResourceFailureReason;
+}
+
+export class LightResourceUnavailableError extends Error {
+  readonly code = 'light-resource-unavailable' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: LightResourceUnavailableDetail;
+
+  constructor(
+    detail: LightResourceUnavailableDetail,
+    expected: string,
+    actual: string,
+    hint: string,
+  ) {
+    super(`light-resource-unavailable: ${detail.feature} ${actual}`);
+    this.name = 'LightResourceUnavailableError';
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = detail;
+  }
+}
+
+export function createLightResourceUnavailable(input: {
+  readonly entity: number;
+  readonly feature: LightResourceUnavailableDetail['feature'];
+  readonly generation: number;
+  readonly sourceKey: string;
+  readonly reason: LightResourceFailureReason;
+  readonly expected: string;
+  readonly actual: string;
+  readonly hint: string;
+}): LightResourceUnavailableError {
+  return new LightResourceUnavailableError(
+    {
+      entity: input.entity,
+      feature: input.feature,
+      generation: input.generation,
+      sourceKey: input.sourceKey,
+      reason: input.reason,
+    },
+    input.expected,
+    input.actual,
+    input.hint,
+  );
+}
+
 export interface TemporalFrameSubmitDetail {
   readonly reason: 'queue-submit-failed';
 }
@@ -132,7 +191,6 @@ export class TemporalFrameSubmitError extends Error {
     this.detail = { reason };
   }
 }
-
 // ── ShadowInvalidConfigError ──────────────────────────────────────────────
 
 /**
@@ -1306,7 +1364,19 @@ export interface RendererOperationDetailByCode {
   };
   readonly 'recovery-failed': {
     readonly operation: 'recover';
+    readonly phase: RecoveryPhase;
     readonly oldGeneration: number;
+    readonly candidateGeneration: number;
+    readonly attempt: number;
+    readonly elapsedMs: number;
+    readonly retryable: boolean;
+    readonly guidance: 'retry' | 'repair-owner' | 'rebuild-renderer';
+    readonly owner: string;
+    readonly resourceKind: string;
+    readonly lastOutcome: RecoveryOutcome;
+    readonly rehydratedRoots: number;
+    readonly staleLossEvents: number;
+    readonly cleanupFailures: readonly RendererOperationCause[];
     readonly cause: RendererOperationCause;
   };
   readonly 'cleanup-failed': {
@@ -1821,6 +1891,7 @@ export type RenderError =
   | PointsLinesMaterialUnsupportedError
   | PointsLinesBudgetExceededError
   | PointsLinesPrepareFailedError
+  | LightResourceUnavailableError
   | RenderTargetDescriptorInvalidError
   | RenderTargetCapabilityMissingError
   | RenderTargetStateInvalidError

package/src/extract/camera.ts

@@ -1,7 +1,7 @@
 import type { EntityHandle, World } from '@forgeax/engine-ecs';
 import { readRenderArrayView } from '@forgeax/engine-ecs/projection';
 import { mat4, vec3 } from '@forgeax/engine-math';
-import { Transform } from '@forgeax/engine-scene';
+import { GlobalTransform } from '@forgeax/engine-scene';
 import {
   antialiasFromF32,
   bloomEnabledFromF32,
@@ -14,7 +14,7 @@ import type { CameraSnapshot } from '../render-contract';
 import { getActiveCamera, selectActiveCameraIndex } from '../systems/active-camera';
 
 function readWorldMatrix(world: World, entity: EntityHandle): Float32Array | undefined {
-  const view = readRenderArrayView(world, entity, Transform, 'world');
+  const view = readRenderArrayView(world, entity, GlobalTransform, 'world');
   return view === undefined ? undefined : new Float32Array(view);
 }
 
@@ -23,7 +23,7 @@ export function extractCameraSnapshots(world: World): CameraSnapshot[] {
   const cameras: CameraSnapshot[] = [];
   const cameraEntities: number[] = [];
   const cameraQuery = world
-    .query({ read: [Camera], optional: [MotionBlur], with: [Transform] })
+    .query({ read: [Camera], optional: [MotionBlur], with: [GlobalTransform] })
     .unwrap();
   for (const row of cameraQuery) {
     const cam = row.get(Camera);