@forgeax/engine-render 0.1.7 → 0.1.19

package/src/assembly/host-contract.ts

@@ -6,6 +6,7 @@ import type { ObservationUnavailableError, RenderError } from '../errors/render'
 import type { RenderFeature, RenderFeatureDiagnostics } from '../features/types';
 import type { MeshMaterialBindingObservation } from '../mesh-material-bindings';
 import type { FrameObservation, FrameObservationOptions } from '../record/frame';
+import type { CurrentGraphTarget, GraphTargetCaptureRequest } from '../record/frame-snapshot';
 import type {
   DrawOwnerOptions,
   FrameObservationRequest,
@@ -81,6 +82,9 @@ export interface RendererLegacyHostAdapter {
   observeCurrentFrame(
     options: FrameObservationOptions,
   ): Promise<RenderResult<FrameObservation, ObservationUnavailableError>>;
+  /** @internal Test-only current compiled graph target diagnostic. */
+  getCurrentGraphTarget(name: string): CurrentGraphTarget | undefined;
+  requestGraphTargetCapture(request: GraphTargetCaptureRequest): void;
   onLost(listener: RendererLostListener): () => void;
   onError(listener: RendererErrorListener): () => void;
   health(): HealthSnapshot;

package/src/assembly/renderer-frame-transaction.ts

@@ -0,0 +1,75 @@
+/** Staged frame state committed only after the renderer submit barrier. */
+export interface RendererFrameTransaction<T> {
+  readonly candidate: T;
+  readonly commit: () => T;
+  readonly abort: () => void;
+}
+
+export function stageRendererFrame<T>(
+  candidate: T,
+  onAbort: () => void = () => undefined,
+): RendererFrameTransaction<T> {
+  let closed = false;
+  return {
+    candidate,
+    commit: () => {
+      if (closed) throw new Error('renderer frame transaction is closed');
+      closed = true;
+      return candidate;
+    },
+    abort: () => {
+      if (closed) return;
+      closed = true;
+      onAbort();
+    },
+  };
+}
+
+export type RendererFrameStage = 'build' | 'execute' | 'finish' | 'submit';
+
+export interface RendererFrameStageFailure {
+  readonly stage: RendererFrameStage;
+}
+
+export type RendererFrameStageResult<T> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly stage: RendererFrameStage };
+
+export interface RendererFrameTransactionSteps<T> {
+  readonly build: () => RendererFrameStageResult<T>;
+  readonly execute: (candidate: T) => RendererFrameStageResult<void>;
+  readonly finish: (candidate: T) => RendererFrameStageResult<void>;
+  readonly submit: (candidate: T) => RendererFrameStageResult<void>;
+  readonly commit: (candidate: T) => void;
+  readonly abort?: (failure: RendererFrameStageFailure) => void;
+}
+
+/**
+ * Run the four renderer stages behind one commit barrier. A stage can expose
+ * only a structured failure; the candidate is never published until submit
+ * has returned success, so a failed frame cannot advance last-known-good state.
+ */
+export function executeRendererFrameTransaction<T>(
+  steps: RendererFrameTransactionSteps<T>,
+):
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly error: RendererFrameStageFailure } {
+  const fail = (
+    stage: RendererFrameStage,
+  ): { readonly ok: false; readonly error: RendererFrameStageFailure } => {
+    const error = { stage } as const;
+    steps.abort?.(error);
+    return { ok: false, error };
+  };
+
+  const built = steps.build();
+  if (!built.ok) return fail('build');
+  const executed = steps.execute(built.value);
+  if (!executed.ok) return fail('execute');
+  const finished = steps.finish(built.value);
+  if (!finished.ok) return fail('finish');
+  const submitted = steps.submit(built.value);
+  if (!submitted.ok) return fail('submit');
+  steps.commit(built.value);
+  return { ok: true, value: built.value };
+}

package/src/assembly/renderer-inspection.ts

@@ -0,0 +1,112 @@
+import type { CompiledRenderGraphInfo } from '@forgeax/engine-render-graph';
+import type { RhiCanvasSurfacePresentationProof, TextureFormat } from '@forgeax/engine-rhi';
+import {
+  type RenderOutputInspection,
+  type RenderStandardOutputColorInspection,
+  STANDARD_OUTPUT_TRANSFORM_FEATURE_ID,
+} from '../render-contract';
+
+/** Inputs owned by the renderer assembly for one detached output projection. */
+export interface RendererOutputInspectionInput {
+  readonly graph: CompiledRenderGraphInfo | undefined;
+  readonly surfaceAvailable: boolean;
+  readonly surfaceStorage: TextureFormat;
+  readonly surfaceDisplay: TextureFormat;
+  readonly surfaceProfile?: 'dual-view' | 'raw-only';
+  readonly rgba16floatRenderable: boolean;
+  readonly presentationProof?: RhiCanvasSurfacePresentationProof | undefined;
+}
+
+function isSrgbFormat(format: TextureFormat): boolean {
+  return format === 'rgba8unorm-srgb' || format === 'bgra8unorm-srgb';
+}
+
+function writesSurface(pass: CompiledRenderGraphInfo['passes'][number]): boolean {
+  return pass.accesses.some(
+    (access) =>
+      (access.resource === 'surface' || access.resource.startsWith('surface.')) &&
+      access.usage === 'color-attachment',
+  );
+}
+
+/**
+ * Project output facts from the committed graph and physical surface only.
+ * Profile fields are deliberately not consulted: a transform pass, a real
+ * intermediate target, and the final endpoint/domain are graph facts.
+ */
+export function projectRendererOutputInspection(
+  input: RendererOutputInspectionInput,
+): RenderOutputInspection {
+  const graph = input.graph;
+  const outputTransformPass = graph?.passes.find(
+    (pass) => pass.name === 'output-transform' || pass.name === 'present',
+  );
+  const surfaceResource = graph?.resources.find(
+    (resource) => resource.kind === 'texture' && resource.label === 'surface',
+  );
+  const writesFinalSurface = graph?.passes.some(writesSurface) === true;
+  const surfaceDomain =
+    surfaceResource?.descriptor?.kind === 'texture' ? surfaceResource.descriptor.domain : undefined;
+  const directEncodedSurface =
+    writesFinalSurface && surfaceDomain === 'display-encoded' && isSrgbFormat(input.surfaceDisplay);
+  const displayEncoded =
+    input.surfaceAvailable &&
+    writesFinalSurface &&
+    (outputTransformPass !== undefined || directEncodedSurface);
+  const intermediate = graph?.resources.find(
+    (resource) =>
+      resource.kind === 'texture' &&
+      resource.label === 'standard-output-color' &&
+      resource.descriptor?.kind === 'texture',
+  );
+  const standardOutputColor: RenderStandardOutputColorInspection | undefined =
+    intermediate?.descriptor?.kind === 'texture'
+      ? {
+          format: intermediate.descriptor.format,
+          ...(intermediate.descriptor.domain === undefined
+            ? {}
+            : { domain: intermediate.descriptor.domain }),
+          width: intermediate.descriptor.width,
+          height: intermediate.descriptor.height,
+          sampleCount: intermediate.descriptor.sampleCount,
+          usage: intermediate.derivedUsage,
+        }
+      : undefined;
+  const outputReady = input.surfaceAvailable && displayEncoded;
+
+  return {
+    ...(outputTransformPass === undefined
+      ? {}
+      : { outputTransform: STANDARD_OUTPUT_TRANSFORM_FEATURE_ID }),
+    displayEncoded,
+    ...(intermediate?.descriptor?.kind === 'texture'
+      ? { intermediateFormat: intermediate.descriptor.format }
+      : {}),
+    ...(input.surfaceProfile === undefined ? {} : { surfaceProfile: input.surfaceProfile }),
+    graphPassNames: graph?.passes.map((pass) => pass.name) ?? [],
+    ...(standardOutputColor === undefined ? {} : { standardOutputColor }),
+    surfaceStorage: input.surfaceStorage,
+    surfaceDisplay: input.surfaceDisplay,
+    endpoint: 'surface.storage.raw',
+    capability: outputReady
+      ? input.rgba16floatRenderable
+        ? 'rgba16float-renderable'
+        : 'surface-raw-endpoint'
+      : 'unavailable',
+    ...(input.presentationProof === undefined
+      ? {}
+      : { presentationProof: input.presentationProof }),
+    error: outputReady
+      ? undefined
+      : {
+          code: 'inspection-facts-unavailable',
+          expected: 'a committed graph writes an encoded surface endpoint',
+          hint: 'draw a frame before consuming output inspection facts',
+        },
+  };
+}
+
+/** Detached inspection projection helper; live renderer objects never cross this boundary. */
+export function detachRendererInspection<T extends object>(inspection: T): Readonly<T> {
+  return Object.freeze({ ...inspection });
+}

package/src/assembly/renderer-lifecycle.ts

@@ -0,0 +1,6 @@
+import type { RendererState } from '../render-contract';
+
+/** Lifecycle states that may accept a new frame operation. */
+export function isRendererStateOperational(state: RendererState): boolean {
+  return state === 'alive';
+}

package/src/components/__tests__/motion-blur.unit.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest';
+import { MotionBlur } from '../motion-blur';
+
+describe('MotionBlur component schema', () => {
+  it('is a single-semantic component with bounded authoring fields', () => {
+    expect(MotionBlur.name).toBe('MotionBlur');
+    expect(MotionBlur.fields).toMatchObject({
+      shutterAngle: { type: 'f32', default: 180 },
+      maxRadiusPixels: { type: 'f32', default: 32 },
+      sampleCount: { type: 'f32', default: 8 },
+    });
+    expect(MotionBlur.fields).not.toHaveProperty('enabled');
+  });
+});

package/src/components/__tests__/schema-contract.unit.test.ts

@@ -1,10 +1,15 @@
 import { describe, expect, it } from 'vitest';
-import { Camera, DirectionalLight, MeshFilter } from '../index';
+import { ANTIALIAS_TAA, Atmosphere, Camera, DirectionalLight, Fog, MeshFilter } from '../index';
 
 describe('canonical render schema owners', () => {
   it('keeps mesh, light, and camera facts on their component owners', () => {
     expect(MeshFilter.fields.assetHandle.type).toBe('shared<MeshAsset>');
     expect(DirectionalLight.fields.direction.type).toBe('array<f32, 3>');
     expect(Camera.fields.projection.default).toBe(0);
+    expect(Camera.fields.antialias.default).toBe(0);
+    expect(Camera.fields.historyVersion.default).toBe(0);
+    expect(ANTIALIAS_TAA).toBe(3);
+    expect(Atmosphere.fields.turbidity.type).toBe('f32');
+    expect(Fog.fields.density.type).toBe('f32');
   });
 });

package/src/components/atmosphere.ts

@@ -0,0 +1,10 @@
+import { defineComponent } from '@forgeax/engine-ecs';
+
+/** Analytic atmosphere authoring facts; the directional light supplies the sun. */
+export const Atmosphere = defineComponent('Atmosphere', {
+  turbidity: { type: 'f32', default: 2 },
+  rayleigh: { type: 'f32', default: 1 },
+  mieCoefficient: { type: 'f32', default: 0.005 },
+  mieDirectionalG: { type: 'f32', default: 0.8 },
+  sunAngularRadius: { type: 'f32', default: 0.004675 },
+});

package/src/components/camera.ts

@@ -349,7 +349,8 @@ export const Camera = defineComponent('Camera', {
 // token's schema, which is itself derived from Camera.fields[k].type (D-A7).
 // This replaces the hand-maintained CameraDataPod interface — the field set
 // lives exclusively in the Camera component definition above.
-type CameraPod = ShapeOf<SchemaOf<typeof Camera>>;
+export type CameraData = ShapeOf<SchemaOf<typeof Camera>>;
+type CameraPod = CameraData;
 
 // ─── Camera factory functions (w13 SSOT refactoring) ─────────────────────
 //

package/src/components/fog.ts

@@ -0,0 +1,9 @@
+import { defineComponent } from '@forgeax/engine-ecs';
+
+/** Optional height-aware aerial fog, independent from environment source. */
+export const Fog = defineComponent('Fog', {
+  color: { type: 'array<f32, 3>', default: new Float32Array([0.5, 0.5, 0.5]) },
+  density: { type: 'f32', default: 0.01 },
+  heightFalloff: { type: 'f32', default: 0 },
+  maxOpacity: { type: 'f32', default: 1 },
+});

package/src/components/index.ts

@@ -1,10 +1,13 @@
+export * from './atmosphere';
 export * from './camera';
 export * from './directional-light';
+export * from './fog';
 export { Instances, type InstancesData } from './instances';
 export { Layer } from './layer';
 export { Lines } from './lines';
 export * from './mesh-filter';
 export * from './mesh-renderer';
+export { MotionBlur } from './motion-blur';
 export { PointLight } from './point-light';
 export { PointLightShadow } from './point-light-shadow';
 export {

package/src/components/motion-blur.ts

@@ -0,0 +1,8 @@
+import { defineComponent } from '@forgeax/engine-ecs';
+
+/** Active-camera motion blur authoring data; presence enables the feature. */
+export const MotionBlur = defineComponent('MotionBlur', {
+  shutterAngle: { type: 'f32', default: 180 },
+  maxRadiusPixels: { type: 'f32', default: 32 },
+  sampleCount: { type: 'f32', default: 8 },
+});

package/src/construct-renderer.ts

@@ -1,5 +1,5 @@
 import type { AssetRegistry } from '@forgeax/engine-assets-runtime';
-import type { RhiBackendPack } from './assembly/backend-contract';
+import { EngineEnvironmentError, type RhiBackendPack } from './assembly/backend-contract';
 import type { BundlerOptions } from './assembly/factory';
 import { createRenderer, exposeRenderer } from './assembly/factory';
 import type {
@@ -30,12 +30,46 @@ export interface RendererHostAssembly {
   readonly assets: AssetRegistry;
 }
 
+function describeRendererInitializationFailure(error: unknown): string {
+  const candidate = error as unknown as {
+    readonly code?: unknown;
+    readonly hint?: unknown;
+    readonly detail?: unknown;
+  };
+  const detail = candidate.detail;
+  if (typeof detail === 'object' && detail !== null && 'compilerMessages' in detail) {
+    const messages = (detail as { readonly compilerMessages?: unknown }).compilerMessages;
+    if (Array.isArray(messages)) {
+      const compilerMessages = messages.map((message) => {
+        const value = message as {
+          readonly message?: unknown;
+          readonly type?: unknown;
+          readonly lineNum?: unknown;
+          readonly linePos?: unknown;
+          readonly offset?: unknown;
+          readonly length?: unknown;
+        };
+        return {
+          message: value.message,
+          type: value.type,
+          lineNum: value.lineNum,
+          linePos: value.linePos,
+          offset: value.offset,
+          length: value.length,
+        };
+      });
+      return `${String(candidate.code)}: ${String(candidate.hint)}; detail=${JSON.stringify({ compilerMessages })}`;
+    }
+  }
+  return `${String(candidate.code)}: ${String(candidate.hint)}; detail=${JSON.stringify(detail)}`;
+}
+
 export async function constructRendererHost(
   canvas: unknown,
   options?: RendererOptions,
   bundler?: BundlerOptions,
   backend?: RhiBackendPack,
-): Promise<RenderResult<RendererHostAssembly, RenderError>> {
+): Promise<RenderResult<RendererHostAssembly, RenderError | EngineEnvironmentError>> {
   try {
     const implementation = await createRenderer(canvas, options, bundler, backend);
     const ready = await implementation.initialization;
@@ -44,7 +78,7 @@ export async function constructRendererHost(
         ok: false,
         error: new RendererContractFailureError(
           'construct',
-          `${ready.error.code}: ${ready.error.hint}`,
+          describeRendererInitializationFailure(ready.error),
         ),
       };
     }
@@ -58,6 +92,9 @@ export async function constructRendererHost(
       },
     };
   } catch (cause) {
+    if (cause instanceof EngineEnvironmentError) {
+      return { ok: false, error: cause };
+    }
     const detail = cause instanceof Error ? cause.message : String(cause);
     return {
       ok: false,

package/src/device/device-scope.ts

@@ -77,6 +77,15 @@ export class DeviceScope {
     return [...this.children];
   }
 
+  /** Create a renderer-owned child scope without exposing a second device owner. */
+  createChild(owner: string): DeviceScope {
+    if (this.lifecycleState !== 'active') {
+      throw new Error('Cannot create a child DeviceScope from an inactive scope.');
+    }
+    if (owner.length === 0) throw new TypeError('DeviceScope child owner must not be empty.');
+    return new DeviceScope(this.generation, owner, this);
+  }
+
   ref<T>(kind: DeviceResourceKind, value: T): ResourceRef<T> {
     const ref = new DeviceResourceRef(kind, this.owner, this.generation, value);
     this.resources.push({ ref: ref as DeviceResourceRef<unknown>, cleanup: () => undefined });
@@ -128,8 +137,13 @@ export class DeviceScope {
     return resources;
   }
 
+  /** Mark an active child as retiring without releasing in-flight resources. */
+  beginRetire(): void {
+    if (this.lifecycleState === 'active') this.lifecycleState = 'retiring';
+  }
+
   retire(): void {
-    if (this.lifecycleState !== 'active') return;
+    if (this.lifecycleState !== 'active' && this.lifecycleState !== 'retiring') return;
     this.lifecycleState = 'retiring';
     this._clearResources();
     this.lifecycleState = 'retired';

package/src/environment/frame.ts

@@ -0,0 +1,185 @@
+import { err, ok, type Result } from '@forgeax/engine-types';
+import { EnvironmentSourceConflictError, FogCardinalityError } from '../errors/render';
+import type {
+  EnvironmentCandidate,
+  EnvironmentFrame,
+  EnvironmentSource,
+  FogCandidate,
+  FogFrame,
+} from '../extract/environment';
+import { validateAtmosphereParameters } from '../extract/environment';
+import { environmentFactSignatures } from './signature';
+
+export type { EnvironmentCandidate, EnvironmentFrame, EnvironmentSource, FogCandidate, FogFrame };
+
+export interface SunCandidate {
+  readonly entityKey: number;
+  readonly direction: readonly [number, number, number];
+  readonly color: readonly [number, number, number];
+  readonly intensity: number;
+}
+
+export interface EnvironmentSelectionInput {
+  readonly environments: readonly EnvironmentCandidate[];
+  readonly fogs: readonly FogCandidate[];
+  readonly suns: readonly SunCandidate[];
+  readonly lane: 'direct' | 'clustered';
+}
+
+export interface EnvironmentSelectionParameterDetail {
+  readonly field: string;
+  readonly value: number;
+}
+
+export class EnvironmentSelectionParameterError extends Error {
+  readonly code = 'environment-selection-invalid' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: EnvironmentSelectionParameterDetail;
+
+  constructor(field: string, value: number, expected: string) {
+    super(`environment selection field ${field} is invalid`);
+    this.name = 'EnvironmentSelectionParameterError';
+    this.expected = expected;
+    this.hint = `set ${field} to a finite value satisfying ${expected}`;
+    this.detail = { field, value };
+  }
+}
+
+export interface SunCardinalityDetail {
+  readonly field: 'sun';
+  readonly value: number;
+}
+
+export class SunCardinalityError extends Error {
+  readonly code = 'sun-cardinality' as const;
+  readonly expected = 'atmosphere has exactly one sun owner';
+  readonly hint = 'add exactly one DirectionalLight sun for the atmosphere owner';
+  readonly detail: SunCardinalityDetail;
+
+  constructor(value: number) {
+    super(`atmosphere sun cardinality is ${value}`);
+    this.name = 'SunCardinalityError';
+    this.detail = { field: 'sun', value };
+  }
+}
+
+export interface EnvironmentSelectionErrorDetail {
+  readonly owners?: readonly {
+    readonly kind: 'image' | 'atmosphere';
+    readonly entityKey: number;
+    readonly sourceKey: string;
+  }[];
+  readonly field?: string;
+  readonly value?: number;
+  readonly count?: number;
+}
+
+export interface EnvironmentSelectionError {
+  readonly code:
+    | 'environment-source-conflict'
+    | 'fog-cardinality'
+    | 'environment-selection-invalid'
+    | 'atmosphere-invalid-parameter'
+    | 'sun-cardinality';
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: EnvironmentSelectionErrorDetail;
+}
+
+export interface SelectedEnvironmentFrame extends EnvironmentFrame {
+  readonly sun: SunCandidate | undefined;
+  readonly lane: 'direct' | 'clustered';
+}
+
+function freezeCandidate<T extends object>(candidate: T): T {
+  return Object.freeze(candidate);
+}
+
+function freezeFog(candidate: FogCandidate): FogFrame {
+  return Object.freeze({
+    ...candidate,
+    color: Object.freeze([...candidate.color] as unknown as FogFrame['color']),
+  });
+}
+
+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,
+): Result<SelectedEnvironmentFrame, EnvironmentSelectionError> {
+  if (input.environments.length > 1) {
+    return err(
+      new EnvironmentSourceConflictError(
+        [...input.environments]
+          .sort((left, right) => left.entityKey - right.entityKey)
+          .map(({ kind, entityKey, sourceKey }) => ({ kind, entityKey, sourceKey })),
+      ),
+    );
+  }
+  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'),
+    );
+  }
+  const selected = input.environments[0];
+  if (selected?.kind === 'atmosphere') {
+    const invalid = validateAtmosphereParameters(selected.atmosphere);
+    if (invalid !== undefined) return err(invalid);
+  }
+  if (selected?.kind === 'atmosphere' && input.suns.length !== 1) {
+    return err(new SunCardinalityError(input.suns.length));
+  }
+  const source: EnvironmentSource =
+    selected === undefined
+      ? { kind: 'none' }
+      : selected.kind === 'atmosphere'
+        ? {
+            kind: 'atmosphere',
+            entityKey: selected.entityKey,
+            sourceKey: selected.sourceKey,
+            atmosphere: Object.freeze({ ...selected.atmosphere }),
+          }
+        : {
+            kind: 'image',
+            entityKey: selected.entityKey,
+            sourceKey: selected.sourceKey,
+          };
+  const sun = input.suns[0] === undefined ? undefined : freezeCandidate({ ...input.suns[0] });
+  const fog = selectedFog === undefined ? undefined : freezeFog(selectedFog);
+  const signatureInput = {
+    environments: selected === undefined ? [] : [selected],
+    fogs: selectedFog === undefined ? [] : [selectedFog],
+    suns: input.suns,
+  };
+  const signatures = environmentFactSignatures(signatureInput);
+  const result = {
+    source: Object.freeze(source),
+    fog,
+    ...signatures,
+    revision: 0,
+    sun,
+  } as SelectedEnvironmentFrame;
+  Object.defineProperty(result, 'lane', { value: input.lane, enumerable: false });
+  return ok(Object.freeze(result));
+}

package/src/environment/generation.ts

@@ -0,0 +1,23 @@
+import type { DeviceScope } from '../device/device-scope';
+import type { EnvironmentFrame } from './frame';
+
+export interface EnvironmentGeneration {
+  readonly signature: string;
+  readonly generation: number;
+  readonly lane: 'direct' | 'clustered';
+  readonly scope: DeviceScope;
+  readonly liveHandle: object;
+  readonly resourceCount: number;
+  readonly resourceBytes: number;
+  retired: boolean;
+}
+
+export interface EnvironmentGenerationFailure {
+  readonly failureAt?: 'prepare' | 'build' | 'execute' | 'finish' | 'submit';
+}
+
+export interface EnvironmentGenerationState {
+  readonly frame: EnvironmentFrame;
+  readonly scope: DeviceScope;
+  readonly generation: number;
+}

package/src/environment/graph.ts

@@ -0,0 +1,9 @@
+import type { EnvironmentFrame } from './frame';
+
+/** Both Standard lanes consume the same selected CPU environment facts. */
+export function sharedEnvironmentFrame(
+  frame: EnvironmentFrame,
+  _lane: 'direct' | 'clustered',
+): EnvironmentFrame {
+  return frame;
+}