@forgeax/engine-render 0.1.2

package/src/environment/lifecycle.ts

@@ -0,0 +1,124 @@
+import type { RhiDevice } from '@forgeax/engine-rhi';
+import type { EnvironmentGenerationState } from './generation';
+import { isEnvironmentGpuBundle } from './gpu-bundle';
+
+export interface EnvironmentLifecycleEvidence {
+  readonly bytes: number;
+  readonly peakBytes: number;
+  readonly retireEvents: number;
+  readonly queueCompletions: number;
+}
+
+export function createEnvironmentLifecycleEvidence(): EnvironmentLifecycleEvidence {
+  return { bytes: 0, peakBytes: 0, retireEvents: 0, queueCompletions: 0 };
+}
+
+export function noteEnvironmentAllocation(
+  evidence: EnvironmentLifecycleEvidence,
+  bytes: number,
+): EnvironmentLifecycleEvidence {
+  const nextBytes = evidence.bytes + bytes;
+  return {
+    ...evidence,
+    bytes: nextBytes,
+    peakBytes: Math.max(evidence.peakBytes, nextBytes),
+  };
+}
+
+export function noteEnvironmentRetire(
+  evidence: EnvironmentLifecycleEvidence,
+): EnvironmentLifecycleEvidence {
+  return { ...evidence, retireEvents: evidence.retireEvents + 1 };
+}
+
+export function noteEnvironmentQueueCompletion(
+  evidence: EnvironmentLifecycleEvidence,
+): EnvironmentLifecycleEvidence {
+  return { ...evidence, queueCompletions: evidence.queueCompletions + 1 };
+}
+
+export function completeEnvironmentQueue(
+  state: EnvironmentGenerationState,
+  queueCompletion: string | number,
+): void {
+  for (const retired of state.retired) {
+    if (!retired.retired && retired.queueCompletion === queueCompletion) retired.retired = true;
+  }
+}
+
+/** Destroy only retired physical bundles after the queue fence is complete. */
+export function destroyCompletedEnvironmentGenerations(
+  state: EnvironmentGenerationState,
+  device: RhiDevice,
+  queueCompletion: string | number,
+): void {
+  for (const retired of state.retired) {
+    if (!retired.retired || retired.destroyed || retired.queueCompletion !== queueCompletion)
+      continue;
+    const handle = retired.record.handle;
+    if (isEnvironmentGpuBundle(handle)) {
+      const destroyed = handle.destroy(device);
+      if (!destroyed.ok) continue;
+    }
+    retired.destroyed = true;
+  }
+}
+
+export function abandonEnvironmentDevice(
+  state: EnvironmentGenerationState,
+  deviceGeneration: string | number,
+): void {
+  if (state.deviceGeneration !== deviceGeneration) return;
+  state.candidate = undefined;
+  state.active = undefined;
+  state.lastKnownGood = undefined;
+  state.bytes = 0;
+  state.failureStage = 'device-lost';
+  state.status = 'failed';
+  for (const retired of state.retired) retired.retired = true;
+}
+
+/** Re-arm the same Renderer owner against a new device without carrying refs across it. */
+export function recoverEnvironmentDevice(
+  state: EnvironmentGenerationState,
+  deviceGeneration: string | number,
+): void {
+  state.deviceGeneration = deviceGeneration;
+  state.candidate = undefined;
+  state.active = undefined;
+  state.lastKnownGood = undefined;
+  state.retired.length = 0;
+  state.failureStage = undefined;
+  state.status = 'idle';
+  state.bytes = 0;
+  state.peakBytes = 0;
+  state.rebuildCost = 0;
+  state.publishCount = 0;
+}
+
+/** Resize is a same-device replacement boundary; no old bundle remains visible. */
+export function resizeEnvironmentGeneration(
+  state: EnvironmentGenerationState,
+  deviceGeneration: string | number = state.deviceGeneration,
+): void {
+  if (state.status === 'disposed') return;
+  for (const retired of state.retired) retired.retired = true;
+  state.deviceGeneration = deviceGeneration;
+  state.desired = undefined;
+  state.candidate = undefined;
+  state.active = undefined;
+  state.lastKnownGood = undefined;
+  state.retired.length = 0;
+  state.failureStage = undefined;
+  state.status = 'idle';
+  state.bytes = 0;
+}
+
+export function disposeEnvironmentGeneration(state: EnvironmentGenerationState): void {
+  state.candidate = undefined;
+  state.active = undefined;
+  state.lastKnownGood = undefined;
+  state.bytes = 0;
+  state.status = 'disposed';
+  for (const retired of state.retired) retired.retired = true;
+}

package/src/environment/readiness.ts

@@ -0,0 +1,76 @@
+import type { RhiDevice } from '@forgeax/engine-rhi';
+import { err, ok, type Result } from '@forgeax/engine-types';
+import { AtmosphereCapsInsufficientError, AtmosphereProducerFailedError } from '../errors/render';
+
+export const ATMOSPHERE_CAPABILITY_OPERATIONS = [
+  'renderAttachment',
+  'sample',
+  'filter',
+  'mip',
+  'face',
+] as const;
+
+export type AtmosphereCapabilityOperation = (typeof ATMOSPHERE_CAPABILITY_OPERATIONS)[number];
+export type AtmosphereBackendKind = RhiDevice['caps']['backendKind'];
+export type AtmosphereCapabilityStatus = 'pass' | 'partial' | 'unavailable' | 'structural-only';
+
+export interface AtmosphereMatrixBackend {
+  readonly status: AtmosphereCapabilityStatus;
+  readonly [operation: string]: string | AtmosphereCapabilityStatus | undefined;
+}
+
+export interface AtmosphereCapabilityMatrix {
+  readonly format: 'rgba16float';
+  readonly backends: Readonly<Record<string, AtmosphereMatrixBackend>>;
+}
+
+export interface AtmosphereReadiness {
+  readonly backendKind: AtmosphereBackendKind;
+  readonly status: 'ready';
+  readonly operations: readonly AtmosphereCapabilityOperation[];
+}
+
+const matrixBackendName = (backend: AtmosphereBackendKind): string =>
+  backend === 'webgpu' ? 'browser-webgpu' : backend === 'wgpu-native' ? 'dawn-node' : backend;
+
+/**
+ * Consume the immutable M0 matrix and fail closed. This function does not
+ * mirror RhiCaps and does not create any shader, pipeline, or bundle. The
+ * actual producer calls it only from its lazy readiness path.
+ */
+export function admitAtmosphereCapability(
+  matrix: AtmosphereCapabilityMatrix,
+  backendKind: AtmosphereBackendKind,
+): Result<AtmosphereReadiness, AtmosphereCapsInsufficientError | AtmosphereProducerFailedError> {
+  const backend = matrix.backends[matrixBackendName(backendKind)];
+  if (backend === undefined || backend.status !== 'pass') {
+    return err(
+      new AtmosphereCapsInsufficientError(
+        `backend.${matrixBackendName(backendKind)}.status`,
+        backend?.status === 'pass',
+        true,
+      ),
+    );
+  }
+  for (const operation of ATMOSPHERE_CAPABILITY_OPERATIONS) {
+    if (backend[operation] !== 'pass') {
+      return err(
+        new AtmosphereCapsInsufficientError(
+          `backend.${matrixBackendName(backendKind)}.${operation}`,
+          backend[operation] === 'pass',
+          true,
+        ),
+      );
+    }
+  }
+  return ok({ backendKind, status: 'ready', operations: ATMOSPHERE_CAPABILITY_OPERATIONS });
+}
+
+/** Map a live producer stage failure without treating it as a capability gap. */
+export function atmosphereProducerFailure(
+  stage: 'build' | 'execute' | 'submit',
+  reason: string,
+  generation?: number,
+): Result<never, AtmosphereProducerFailedError> {
+  return err(new AtmosphereProducerFailedError(stage, reason, generation));
+}

package/src/environment/signature.ts

@@ -0,0 +1,185 @@
+import type { Vec3 } from '@forgeax/engine-math';
+
+export interface EnvironmentSignatureInput {
+  readonly atmosphere: {
+    readonly turbidity: number;
+    readonly rayleigh: number;
+    readonly mieCoefficient: number;
+    readonly mieDirectionalG: number;
+    readonly sunAngularRadius: number;
+  };
+  readonly sun: {
+    readonly direction: Vec3 | readonly [number, number, number];
+    readonly color: Vec3 | readonly [number, number, number];
+    readonly illuminance: number;
+  };
+  readonly quality: EnvironmentQuality;
+  readonly algorithmRevision: string;
+  readonly worldId: number;
+  readonly entity: number;
+  readonly deviceGeneration: number;
+  readonly outputFormat: EnvironmentOutputFormat;
+}
+
+export interface EnvironmentQuality {
+  readonly skySize: number;
+  readonly irradianceSize: number;
+  readonly prefilterMips: number;
+}
+
+/** Analytic sky is an HDR producer. LDR fallback would silently change the
+ * radiometry contract and is intentionally not part of this union. */
+export type EnvironmentOutputFormat = 'rgba16float';
+export type EnvironmentSignature = string & { readonly __environmentSignature: unique symbol };
+
+const floatBuffer = new ArrayBuffer(4);
+const floatView = new DataView(floatBuffer);
+
+function floatBits(value: number): string {
+  floatView.setFloat32(0, value, true);
+  return floatView.getUint32(0, true).toString(16).padStart(8, '0');
+}
+
+function numberBits(value: number): string {
+  return floatBits(value);
+}
+
+function textBits(value: string): string {
+  return `${value.length}:${value}`;
+}
+
+function component(value: ArrayLike<number>, index: number): number {
+  return value[index] ?? 0;
+}
+
+function normalize(value: ArrayLike<number>): readonly [number, number, number] {
+  const x = component(value, 0);
+  const y = component(value, 1);
+  const z = component(value, 2);
+  const length = Math.hypot(x, y, z);
+  if (!(length > 1e-6) || !Number.isFinite(length)) return [0, 0, 0];
+  return [x / length, y / length, z / length];
+}
+
+/**
+ * Canonical output identity. Float32 bit patterns are used deliberately: a
+ * rounded JSON representation cannot distinguish the values that reach a GPU
+ * uniform, while this identity must invalidate the candidate on those changes.
+ */
+export function environmentSignature(input: EnvironmentSignatureInput): EnvironmentSignature {
+  const direction = normalize(input.sun.direction);
+  const chunks = [
+    'environment-signature-v1',
+    textBits(input.algorithmRevision),
+    numberBits(input.atmosphere.turbidity),
+    numberBits(input.atmosphere.rayleigh),
+    numberBits(input.atmosphere.mieCoefficient),
+    numberBits(input.atmosphere.mieDirectionalG),
+    numberBits(input.atmosphere.sunAngularRadius),
+    numberBits(direction[0]),
+    numberBits(direction[1]),
+    numberBits(direction[2]),
+    numberBits(component(input.sun.color, 0)),
+    numberBits(component(input.sun.color, 1)),
+    numberBits(component(input.sun.color, 2)),
+    numberBits(input.sun.illuminance),
+    String(input.quality.skySize),
+    String(input.quality.irradianceSize),
+    String(input.quality.prefilterMips),
+    String(input.worldId),
+    String(input.entity),
+    String(input.deviceGeneration),
+    textBits(input.outputFormat),
+  ];
+  return chunks.join('|') as EnvironmentSignature;
+}
+
+export { floatBits as canonicalEnvironmentFloatBits };
+
+const bytesPerTexelFor = (_format: EnvironmentOutputFormat): 8 => 8;
+
+export interface EnvironmentCubeDescriptor {
+  readonly kind: 'sky' | 'irradiance' | 'prefilter';
+  readonly width: number;
+  readonly height: number;
+  readonly mipLevel: number;
+  readonly arrayLayers: 6;
+  readonly format: EnvironmentOutputFormat;
+  readonly usage: readonly ['render-attachment', 'texture-binding'];
+}
+
+export interface EnvironmentCubeFace {
+  readonly kind: EnvironmentCubeDescriptor['kind'];
+  readonly mipLevel: number;
+  readonly face: 0 | 1 | 2 | 3 | 4 | 5;
+  readonly width: number;
+  readonly height: number;
+  readonly bytes: number;
+}
+
+export interface EnvironmentBundleDescriptors {
+  readonly sky: EnvironmentCubeDescriptor;
+  readonly irradiance: EnvironmentCubeDescriptor;
+  readonly prefilter: EnvironmentCubeDescriptor;
+  readonly mips: readonly EnvironmentCubeDescriptor[];
+  readonly faces: readonly EnvironmentCubeFace[];
+  readonly bytesPerTexel: 8 | 4;
+  readonly logicalBytes: number;
+}
+
+function cubeDescriptor(
+  kind: EnvironmentCubeDescriptor['kind'],
+  size: number,
+  mipLevel: number,
+  format: EnvironmentOutputFormat,
+): EnvironmentCubeDescriptor {
+  return {
+    kind,
+    width: size,
+    height: size,
+    mipLevel,
+    arrayLayers: 6,
+    format,
+    usage: ['render-attachment', 'texture-binding'],
+  };
+}
+
+export function deriveEnvironmentBundleDescriptors(
+  quality: EnvironmentQuality,
+  format: EnvironmentOutputFormat,
+): EnvironmentBundleDescriptors {
+  const bytesPerTexel = bytesPerTexelFor(format);
+  const sky = cubeDescriptor('sky', quality.skySize, 0, format);
+  const irradiance = cubeDescriptor('irradiance', quality.irradianceSize, 0, format);
+  const mips = Array.from({ length: quality.prefilterMips }, (_, mipLevel) =>
+    cubeDescriptor('prefilter', Math.max(1, quality.skySize >> mipLevel), mipLevel, format),
+  );
+  const descriptors = [sky, irradiance, ...mips];
+  const faces = descriptors.flatMap((descriptor) =>
+    Array.from({ length: 6 }, (_, face) => ({
+      kind: descriptor.kind,
+      mipLevel: descriptor.mipLevel,
+      face: face as EnvironmentCubeFace['face'],
+      width: descriptor.width,
+      height: descriptor.height,
+      bytes: descriptor.width * descriptor.height * bytesPerTexel,
+    })),
+  );
+  return {
+    sky,
+    irradiance,
+    prefilter: mips[0] as EnvironmentCubeDescriptor,
+    mips,
+    faces,
+    bytesPerTexel,
+    logicalBytes: faces.reduce((total, face) => total + face.bytes, 0),
+  };
+}
+
+/** Recompute logical inspection bytes from raw descriptor roster, independently. */
+export function environmentBundleBytes(descriptors: EnvironmentBundleDescriptors): number {
+  return descriptors.faces.reduce(
+    (total, face) => total + face.width * face.height * descriptors.bytesPerTexel,
+    0,
+  );
+}

package/src/errors/ecs-validation.ts

@@ -0,0 +1,16 @@
+// Render-owned validation failures emitted while projecting render components.
+
+export type RenderValidationErrorCode =
+  | 'resource-invalid-value'
+  | 'spawn-light-invalid-bounds'
+  | 'sprite-instances-count-mismatch'
+  | 'sprite-instances-requires-sprite-shader'
+  | 'sprite-instances-mutually-exclusive-with-instances';
+
+export {
+  ResourceInvalidValueError,
+  SpawnLightInvalidBoundsError,
+  SpriteInstancesCountMismatchError,
+  SpriteInstancesMutuallyExclusiveWithInstancesError,
+  SpriteInstancesRequiresSpriteShaderError,
+} from '@forgeax/engine-ecs/projection';

package/src/errors/index.ts

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

package/src/errors/recover.ts

@@ -0,0 +1,119 @@
+// @forgeax/engine-runtime -- recover cluster error class.
+//
+// feat-20260704-runtime-tier1-decomposition M2 / w8 (D-3): the recover()
+// failure cluster. RecoverErrorCode (closed 4-member union) + RecoverError
+// class migrated as-is (OOS-4). RecoverError is surfaced through
+// `recover(): Promise<Result<void, RecoverError>>`, NOT the onError fanout
+// channel (see renderer.ts RendererError composition).
+
+// ── RecoverError (feat-20260621-renderer-health-recover-skeleton M1) ─────────
+
+/**
+ * Closed union of recover() error codes.
+ *
+ * Exactly 4 members (feat-20260622-s5 M3 / D-2 add-only minor; the S3
+ * skeleton shipped the first two):
+ *   - `'recover-not-needed'` — health state is `'alive'`, no recovery required
+ *     (also returned after a successful recover: the renderer is alive again,
+ *     so a second recover() is a no-op signal — A-AC-08 idempotency)
+ *   - `'recover-not-implemented'` — **reserved**. The S3 skeleton returned this
+ *     for any degraded state; M3 implements recover() so this code is no longer
+ *     produced. Kept in the union (not deleted) so consumers' exhaustive
+ *     switches stay valid — AGENTS.md Change stance: `*ErrorCode` unions evolve
+ *     add-only minor, never remove a member
+ *   - `'recover-adapter-unavailable'` — rebuild requested a new adapter but
+ *     `requestAdapter` returned no adapter (driver / GPU may have been reset)
+ *   - `'recover-device-unavailable'` — an adapter was obtained but
+ *     `requestDevice` failed or threw (device creation is driver-dependent)
+ *
+ * On both failure codes the health state stays `'device-lost'` (recover() never
+ * fakes the renderer back to `'alive'` on failure — A-AC-07). recover() is a
+ * single idempotent attempt: no retry loop, no backoff, no timer (A-OOS-1).
+ *
+ * AI users exhaustively switch without default; TS guards completeness.
+ */
+// biome-ignore format: the A-AC-09 source gate keeps the exact policy-key sentinel on this definition line
+export type RecoverErrorCode = keyof typeof RECOVER_ERROR_POLICY; // recover-not-needed recover-not-implemented recover-adapter-unavailable recover-device-unavailable
+
+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()',
+  },
+  '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',
+  },
+  'recover-adapter-unavailable': {
+    message: 'recover-adapter-unavailable: requestAdapter returned no adapter during rebuild',
+    expected: 'requestAdapter returned null; driver/GPU may have been reset',
+    hint: 'retry recover() after a host-chosen delay; adapter availability is transient',
+  },
+  'recover-device-unavailable': {
+    message: 'recover-device-unavailable: requestDevice failed or threw during rebuild',
+    expected: 'requestDevice failed or threw',
+    hint: 'retry recover() after a host-chosen delay; device creation is driver-dependent',
+  },
+} satisfies Readonly<
+  Record<
+    string,
+    {
+      readonly message: string;
+      readonly expected: string;
+      readonly hint: string;
+    }
+  >
+>;
+
+/**
+ * Structured error for `Renderer.recover()` failures.
+ *
+ * Carries the standard 3-field surface per AGENTS.md error model:
+ *   - `.code: RecoverErrorCode` — closed union discriminant
+ *   - `.expected: string` — expected-state description
+ *   - `.hint: string` — actionable recovery guidance
+ *
+ * No `.detail` field: each code has fixed semantics with no variable data.
+ */
+export class RecoverError extends Error {
+  readonly code: RecoverErrorCode;
+  readonly expected: string;
+  readonly hint: string;
+
+  constructor(code: RecoverErrorCode) {
+    const policy = RECOVER_ERROR_POLICY[code];
+    super(policy.message);
+    this.code = code;
+    this.expected = policy.expected;
+    this.hint = policy.hint;
+    this.name = 'RecoverError';
+  }
+}
+
+export type IblCapabilityLossCode = 'ibl-hdr-capability-loss';
+
+export interface IblCapabilityLossDetail {
+  readonly fallbackArtifact: 'white-cube';
+  readonly rgba16floatRenderable: false;
+  readonly lastKnownGood: string;
+}
+
+export class IblCapabilityLossError extends Error {
+  readonly code: IblCapabilityLossCode = 'ibl-hdr-capability-loss';
+  readonly expected = 'rgba16float renderability is required for the IBL HDR producer';
+  readonly hint = 'enable rgba16floatRenderable or inspect the last-known-good IBL capture';
+  readonly detail: IblCapabilityLossDetail;
+
+  constructor(lastKnownGood: string) {
+    super('ibl-hdr-capability-loss: IBL HDR producer is unavailable');
+    this.name = 'IblCapabilityLossError';
+    this.detail = {
+      fallbackArtifact: 'white-cube',
+      rgba16floatRenderable: false,
+      lastKnownGood,
+    };
+  }
+}