@forgeax/engine-render 0.1.23 → 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,6 +51,63 @@ 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 === generation.generation &&
@@ -56,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 {
@@ -157,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 {
@@ -237,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/recover.ts

@@ -6,10 +6,13 @@
 // `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(
@@ -40,6 +43,15 @@ export function ssrAdmissionRecoveryAction(error: SsrAdmissionError): SsrOwnerRe
   }
 }
 
+/** 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) ─────────
 
 /**
@@ -73,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',
@@ -127,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',
@@ -141,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;
 }
 
@@ -165,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;
@@ -1359,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': {