@forgeax/engine-render 0.1.20 → 0.1.23

package/src/environment/frame.ts

@@ -7,7 +7,7 @@ import type {
   FogCandidate,
   FogFrame,
 } from '../extract/environment';
-import { validateAtmosphereParameters } from '../extract/environment';
+import { validateAtmosphereParameters, validateFogParameters } from '../extract/environment';
 import { environmentFactSignatures } from './signature';
 
 export type { EnvironmentCandidate, EnvironmentFrame, EnvironmentSource, FogCandidate, FogFrame };
@@ -103,19 +103,6 @@ function freezeFog(candidate: FogCandidate): FogFrame {
   });
 }
 
-function validFog(candidate: FogCandidate): boolean {
-  return (
-    candidate.color.every(Number.isFinite) &&
-    Number.isFinite(candidate.density) &&
-    candidate.density >= 0 &&
-    Number.isFinite(candidate.heightFalloff) &&
-    candidate.heightFalloff >= 0 &&
-    Number.isFinite(candidate.maxOpacity) &&
-    candidate.maxOpacity >= 0 &&
-    candidate.maxOpacity <= 1
-  );
-}
-
 /** Select one immutable frame fact set for both Standard lighting lanes. */
 export function selectEnvironment(
   input: EnvironmentSelectionInput,
@@ -131,16 +118,11 @@ export function selectEnvironment(
   }
   if (input.fogs.length > 1) return err(new FogCardinalityError(input.fogs.length));
   const selectedFog = input.fogs[0];
-  if (selectedFog !== undefined && !validFog(selectedFog)) {
-    const field =
-      !Number.isFinite(selectedFog.density) || selectedFog.density < 0
-        ? 'density'
-        : !Number.isFinite(selectedFog.heightFalloff) || selectedFog.heightFalloff < 0
-          ? 'heightFalloff'
-          : 'maxOpacity';
-    return err(
-      new EnvironmentSelectionParameterError(field, selectedFog[field], 'finite and in range'),
-    );
+  if (selectedFog !== undefined) {
+    const issue = validateFogParameters(selectedFog);
+    if (issue !== undefined) {
+      return err(new EnvironmentSelectionParameterError(issue.field, issue.value, issue.expected));
+    }
   }
   const selected = input.environments[0];
   if (selected?.kind === 'atmosphere') {

package/src/environment/lifecycle.ts

@@ -42,7 +42,11 @@ export class EnvironmentLifecycle {
   }
 
   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 {
@@ -62,6 +66,18 @@ export class EnvironmentLifecycle {
     });
   }
 
+  /** Retain a structured authoring failure while the active/LKG frame stays live. */
+  recordSelectionFailure(error: {
+    readonly code: string;
+    readonly detail: Readonly<Record<string, unknown>>;
+  }): void {
+    this.lastCandidateFailure = Object.freeze({
+      stage: 'prepare',
+      code: error.code,
+      detail: Object.freeze({ ...error.detail }),
+    });
+  }
+
   recordStageFailure(
     stage: EnvironmentInspectionFailure['stage'],
     generation: EnvironmentGeneration,
@@ -94,6 +110,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));

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

@@ -7,6 +7,38 @@
 // channel (see render-contract.ts RendererError composition).
 
 import type { DeviceScopeReceipt } from '../device/resource-types';
+import type { ReflectionFallbackRecoveryAction } from '../inspection-types';
+import type { SsrAdmissionError, SsrOwnerRecoveryAction } from '../ssr/errors';
+
+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';
+  }
+}
 
 // ── RecoverError (feat-20260621-renderer-health-recover-skeleton M1) ─────────