@forgeax/engine-render 0.1.2

package/src/dynamic-texture-store.ts

@@ -0,0 +1,111 @@
+import type { Result, RhiError, Texture, TextureView } from '@forgeax/engine-rhi';
+import { ok } from '@forgeax/engine-rhi';
+import type { Handle } from '@forgeax/engine-types';
+import { handleSlot } from '@forgeax/engine-types';
+
+export type CopyExternalImageSource = GPUCopyExternalImageSourceInfo['source'];
+
+const VIDEO_TEXTURE_USAGE = 0x2 | 0x4 | 0x10;
+const VIDEO_TEXTURE_FORMAT = 'rgba8unorm-srgb' as const;
+
+export interface DynamicTextureDevice {
+  createTexture(desc: {
+    readonly size: {
+      readonly width: number;
+      readonly height: number;
+      readonly depthOrArrayLayers: number;
+    };
+    readonly format: typeof VIDEO_TEXTURE_FORMAT;
+    readonly usage: number;
+    readonly label?: string;
+  }): Result<Texture, RhiError>;
+  createTextureView(texture: Texture, desc: Record<string, never>): Result<TextureView, RhiError>;
+  destroyTexture(texture: Texture): Result<void, RhiError>;
+  readonly queue: {
+    copyExternalImageToTexture(
+      source: { readonly source: CopyExternalImageSource; readonly flipY?: boolean },
+      destination: { readonly texture: Texture },
+      copySize: {
+        readonly width: number;
+        readonly height: number;
+        readonly depthOrArrayLayers: number;
+      },
+    ): Result<void, RhiError>;
+  };
+}
+
+interface TransientEntry {
+  texture: Texture;
+  view: TextureView;
+  width: number;
+  height: number;
+}
+
+/** Renderer-owned transient GPU texture cache for host-provided video frames. */
+export class DynamicTextureStore {
+  private device: DynamicTextureDevice | undefined = undefined;
+  private readonly entries = new Map<number, TransientEntry>();
+
+  configureGpuDevice(device: DynamicTextureDevice): void {
+    if (this.device !== undefined && this.device !== device) this.destroyAll();
+    this.device = device;
+  }
+
+  uploadFrame(
+    clip: Handle<'VideoAsset', 'shared'>,
+    source: CopyExternalImageSource,
+    width: number,
+    height: number,
+  ): Result<TextureView, RhiError> | undefined {
+    const device = this.device;
+    if (device === undefined || width <= 0 || height <= 0) return undefined;
+
+    const ensured = this.ensureEntry(device, handleSlot(clip), width, height);
+    if (!ensured.ok) return ensured;
+    const copyRes = device.queue.copyExternalImageToTexture(
+      { source, flipY: true },
+      { texture: ensured.value.texture },
+      { width, height, depthOrArrayLayers: 1 },
+    );
+    return copyRes.ok ? ok(ensured.value.view) : copyRes;
+  }
+
+  getView(clip: Handle<'VideoAsset', 'shared'>): TextureView | undefined {
+    return this.entries.get(handleSlot(clip))?.view;
+  }
+
+  destroyAll(): void {
+    const device = this.device;
+    for (const entry of this.entries.values()) device?.destroyTexture(entry.texture);
+    this.entries.clear();
+  }
+
+  private ensureEntry(
+    device: DynamicTextureDevice,
+    id: number,
+    width: number,
+    height: number,
+  ): Result<TransientEntry, RhiError> {
+    const existing = this.entries.get(id);
+    if (existing !== undefined && existing.width === width && existing.height === height) {
+      return ok(existing);
+    }
+    if (existing !== undefined) device.destroyTexture(existing.texture);
+
+    const texRes = device.createTexture({
+      size: { width, height, depthOrArrayLayers: 1 },
+      format: VIDEO_TEXTURE_FORMAT,
+      usage: VIDEO_TEXTURE_USAGE,
+      label: `video-transient-${id}`,
+    });
+    if (!texRes.ok) return texRes;
+    const viewRes = device.createTextureView(texRes.value, {});
+    if (!viewRes.ok) {
+      device.destroyTexture(texRes.value);
+      return viewRes;
+    }
+    const entry: TransientEntry = { texture: texRes.value, view: viewRes.value, width, height };
+    this.entries.set(id, entry);
+    return ok(entry);
+  }
+}

package/src/engine-metrics.ts

@@ -0,0 +1,89 @@
+import type { EngineMetrics } from '@forgeax/engine-types';
+
+// @forgeax/engine-runtime — EngineMetrics public API (feat-20260527-sprite-nineslice
+// M4 / w16). A per-Renderer counter Map exposed through `renderer.metrics` so AI
+// users observe runtime-time soft signals (e.g. nineslice scale too small,
+// nineslice tile mode without sampler repeat) without parsing console.warn text
+// or reaching into engine internals (charter F1 minimum surface, P3 machine-
+// readable signals over text logs).
+//
+// Surface — three methods:
+//
+//   | Method                         | Purpose                                     |
+//   |:-------------------------------|:--------------------------------------------|
+//   | `increment(name)`              | Bump the counter for `name` by 1.           |
+//   | `snapshot()`                   | Read all counters as an immutable object.   |
+//   | `reset()`                      | Drop every counter (test isolation hook).   |
+//
+// Naming convention (charter P5 consistent abstraction): counter keys use a
+// dot-delimited namespace `<feature>.<event>`. Two features own keys today:
+//
+//   - `nineslice.scale-too-small`           — Transform.scale below the four
+//     corner anchors at draw time (AC-16, w17 end-to-end test).
+//   - `nineslice.tile-needs-repeat-sampler` — sliceMode=1 (tile) bound to a
+//     sampler whose addressMode is not `'repeat'`; the visual silently
+//     degrades to clamp-stretch (D-9, w18 register-time soft-warn).
+//   - `render.instancing.foldedDraws`        — feat-20260622-chunk-gpu-
+//     instancing-sprite-tilemap M3 / D-3. Count of instanced drawIndexed
+//     calls the fold operator emits this frame; one increment per non-
+//     singleton head bucket retained after the M2 / w11 cap-fallback
+//     filter. NOT entity count, NOT pre-filter bucket count. AI users
+//     read it via `renderer.metrics.snapshot()['render.instancing.foldedDraws']`
+//     to verify fold actually reduced draw count under mode-0 (LAYER_Z)
+//     transparent sort. The key is exported as `FOLDED_DRAWS_METRIC_KEY`
+//     from `render-system-fold.ts` (single source of truth — engine
+//     calls increment via the helper, never the literal string).
+//   - `shadow.csm.*`                         — debug-only semantic census for
+//     directional shadow token construction and atlas cache hit/miss reasons.
+//     These counters are emitted only when RHI semantic observation is enabled;
+//     they are not a production performance or rendering contract.
+//
+// Multi-Renderer isolation (D-5 candidate 1): each Renderer instance owns its
+// own EngineMetrics; counters from one renderer never bleed into another.
+// `createRenderer.ts` constructs a fresh instance per call; tests that spin
+// up multiple renderers can read each `renderer.metrics.snapshot()` in
+// isolation.
+
+// The EngineMetrics interface (3-method contract, zero type dependencies) sank
+// into @forgeax/engine-types (feat-20260705-runtime-tier2-decomposition M1 / w2,
+// D-3). Re-exported here so existing `import { EngineMetrics } from
+// './engine-metrics'` consumers keep resolving; EngineMetricsImpl +
+// createEngineMetrics remain runtime-owned.
+export type { EngineMetrics };
+
+/**
+ * Default `EngineMetrics` implementation — a thin `Map<string, number>` with
+ * the three-method surface bolted on. The map is private; readers consume
+ * the snapshot accessor.
+ *
+ * @internal — instances are constructed by `createRenderer` and surfaced
+ * through `Renderer.metrics`; AI users do not import this class directly.
+ */
+export class EngineMetricsImpl implements EngineMetrics {
+  private readonly counters = new Map<string, number>();
+
+  increment(name: string): void {
+    this.counters.set(name, (this.counters.get(name) ?? 0) + 1);
+  }
+
+  snapshot(): Readonly<Record<string, number>> {
+    const out: Record<string, number> = {};
+    for (const [k, v] of this.counters) {
+      out[k] = v;
+    }
+    return Object.freeze(out);
+  }
+
+  reset(): void {
+    this.counters.clear();
+  }
+}
+
+/**
+ * Fresh `EngineMetrics` factory; the only construction path used by
+ * `createRenderer`. Keeping the constructor private (via the factory) leaves
+ * room to swap the backing store without touching call sites.
+ */
+export function createEngineMetrics(): EngineMetrics {
+  return new EngineMetricsImpl();
+}

package/src/environment/README.md

@@ -0,0 +1,76 @@
+# Environment rendering boundary
+
+> [!IMPORTANT]
+> This directory is the M0/M1 cohesion boundary for analytic sky and sun linkage. It contains no production registry, fallback renderer, or second material route.
+
+```mermaid
+flowchart LR
+  E[World environment facts] --> X[Render extraction]
+  X --> P[Prepare and record]
+  P --> G[Typed render graph]
+  G --> R[RHI capability gate]
+```
+
+## M0 owner boundary
+
+| Concern | Existing owner | M0 evidence |
+| --- | --- | --- |
+| World facts and light snapshots | `render-system-extract.ts` | `DirectionalLightSnapshot`, `SkylightSnapshot`, `SkyboxSnapshot`, `ExtractedFrame` |
+| Frame orchestration | `render-system.ts` | Extract, prepare, record driver |
+| Lighting bindings | `record/frame-lighting.ts` | Direct-light, IBL, and skybox binding preparation |
+| Graph execution | `record/typed-frame-graph.ts` | `executeCompiledFrameGraph` |
+| Temporal ownership | `temporal-frame-transaction.ts`, `temporal-view.ts` | TAA frame transaction and view state |
+| Pipeline placement | `urp-pipeline.ts`, `hdrp-pipeline.ts` | Typed shadow, skybox, and lighting passes |
+| Format capability | `rhi`, `rhi-webgpu`, `rhi-wgpu`, `rhi-null` | M0 capability matrix and raw probes |
+
+## Rules for the next milestones
+
+- Keep one environment fact source per World and one render projection per frame.
+- Reuse the existing extraction, prepare, record, graph, and temporal owners.
+- Treat capability absence as data; do not promote RhiNull structural evidence to a pixel claim.
+- Do not add a parallel atmosphere registry, fog stack, material path, or per-pass sun copy.
+- Re-run the U-11 ancestry and collision audit before integrating concurrent sunlit work.
+
+## M1 authoring contract
+
+`Atmosphere` has exactly five finite medium fields: `turbidity`, `rayleigh`,
+`mieCoefficient`, `mieDirectionalG`, and `sunAngularRadius`. The renderer-owned
+resource selector enforces cardinality-one per World; ECS component schemas do
+not carry cardinality policy. Sun direction, linear color, and illuminance remain on a
+co-located `DirectionalLight` entity.
+
+The resource-owner selector has one closed result: `none`, `image`, or
+`atmosphere`. A non-zero equirect handle is the image predicate; a solid-color
+`Skylight` uses `none` and is not an image conflict. Missing co-located Sun,
+multiple Atmosphere facts, and image/Atmosphere coexistence return structured
+closed `RenderError` values.
+
+`ExtractedFrame.environment` is the only environment input to `recordFrame`.
+The existing image lane is nested inside the union, so background and ambient
+consumers keep their current behavior without receiving parallel skybox and
+skylight arguments.
+
+M0 machine evidence is stored in the feature Harness directory as `owner-map.json`, `capability-matrix.json`, `cost-contract.json`, and `closure-matrix.json`.
+
+## M2 evaluator and admission contract
+
+The build-time shader source lives in `@forgeax/engine-shader` as one
+`atmosphere-preetham.wgsl` evaluator. `atmosphere-cubemap.wgsl` is its sole
+production caller; `atmosphere-background.wgsl` owns the independent sun-disc
+composition. The evaluator pins its algorithm revision and Perez table, clamps
+below-horizon directions, converts Yxy to linear-sRGB, and keeps radiance in the
+finite `rgba16float` domain. Runtime code does not import the compiler or Naga.
+
+`environmentSignature()` canonicalizes every output-affecting numeric fact to
+Float32 bits, including the five medium parameters, normalized Sun, quality,
+revision, resource-owner World/entity, device generation, and output format.
+Shadow-only facts are intentionally excluded. `deriveEnvironmentBundleDescriptors()`
+publishes the raw three-cube descriptor roster and `environmentBundleBytes()`
+recomputes inspection bytes from the 42 face records (`128^2*6`, `32^2*6`, and
+five prefilter mips) using the declared bytes-per-texel value.
+
+`admitAtmosphereCapability()` consumes the immutable M0 capability matrix only.
+Every render/sample/filter/mip/face operation must be `pass`; Browser,
+wgpu-webgl2, and structural RhiNull evidence therefore fail closed until their
+raw probes are available. Capability admission allocates no shader, pipeline, or
+bundle; producer-stage failures use `atmosphere-producer-failed` with a stage.

package/src/environment/__tests__/failure-injection.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest';
+import { beginEnvironmentGeneration, createEnvironmentGenerationState } from '../generation';
+import { createEnvironmentProducerGraph, executeEnvironmentProducerTransaction } from '../graph';
+import { deriveEnvironmentBundleDescriptors } from '../signature';
+
+describe('analytic environment internal failure injection', () => {
+  it.each([
+    'readiness',
+    'build',
+    'execute',
+    'finish',
+    'submit',
+  ] as const)('keeps a failed candidate out of active state at %s', (stage) => {
+    const state = createEnvironmentGenerationState('device');
+    const events: string[] = [];
+    if (stage === 'readiness' || stage === 'build') {
+      const attempt = beginEnvironmentGeneration(state, { signature: stage, bytes: 1 });
+      attempt.fail(stage);
+      expect(state.active).toBeUndefined();
+      expect(state.status).toBe('failed');
+      return;
+    }
+    const graph = createEnvironmentProducerGraph({
+      descriptors: deriveEnvironmentBundleDescriptors(
+        { skySize: 128, irradianceSize: 32, prefilterMips: 5 },
+        'rgba16float',
+      ),
+      generation: 1,
+      dirty: true,
+    });
+    const result = executeEnvironmentProducerTransaction({
+      graph,
+      dirty: true,
+      environment: {
+        abort: (failure) => events.push(`environment:${failure}`),
+        publish: () => events.push('environment:publish'),
+      },
+      temporal: {
+        abort: (failure) => events.push(`temporal:${failure}`),
+        publish: () => events.push('temporal:publish'),
+      },
+      execute: () => stage !== 'execute',
+      finish: () => stage !== 'finish',
+      submit: () => stage !== 'submit',
+    });
+    expect(result.abortedStage).toBe(stage);
+    expect(state.active).toBeUndefined();
+    expect(events).toHaveLength(2);
+  });
+});

package/src/environment/__tests__/generation-red.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'vitest';
+import {
+  beginEnvironmentGeneration,
+  createEnvironmentGenerationState,
+  publishEnvironmentGeneration,
+} from '../generation';
+import {
+  abandonEnvironmentDevice,
+  completeEnvironmentQueue,
+  disposeEnvironmentGeneration,
+} from '../lifecycle';
+
+describe('analytic environment generation red gate', () => {
+  it('keeps the first failed generation without an active bundle', () => {
+    const state = createEnvironmentGenerationState('device-a');
+    const attempt = beginEnvironmentGeneration(state, {
+      signature: 'first',
+      bytes: 1_883_136,
+    });
+
+    attempt.fail('build');
+
+    expect(state.active).toBeUndefined();
+    expect(state.lastKnownGood).toBeUndefined();
+    expect(state.status).toBe('failed');
+  });
+
+  it('retains the last-known-good bundle when a replacement fails', () => {
+    const state = createEnvironmentGenerationState('device-a');
+    const first = beginEnvironmentGeneration(state, { signature: 'first', bytes: 1 });
+    publishEnvironmentGeneration(state, first.complete('bundle-1'));
+    const replacement = beginEnvironmentGeneration(state, { signature: 'replacement', bytes: 2 });
+
+    replacement.fail('execute');
+
+    expect(state.active?.handle).toBe('bundle-1');
+    expect(state.lastKnownGood?.handle).toBe('bundle-1');
+  });
+
+  it('retires replaced handles only after queue completion', () => {
+    const state = createEnvironmentGenerationState('device-a');
+    const first = beginEnvironmentGeneration(state, { signature: 'first', bytes: 1 });
+    publishEnvironmentGeneration(state, first.complete({ handle: 'bundle-1' }));
+    const replacement = beginEnvironmentGeneration(state, { signature: 'replacement', bytes: 2 });
+    publishEnvironmentGeneration(state, replacement.complete('bundle-2'), 'queue-2');
+
+    expect(state.retired).toHaveLength(1);
+    expect(state.retired[0]?.retired).toBe(false);
+    completeEnvironmentQueue(state, 'queue-2');
+    expect(state.retired[0]?.retired).toBe(true);
+  });
+
+  it('abandons device-owned handles and disposal is terminal', () => {
+    const state = createEnvironmentGenerationState('device-a');
+    const first = beginEnvironmentGeneration(state, { signature: 'first', bytes: 1 });
+    publishEnvironmentGeneration(state, first.complete('bundle-1'));
+
+    abandonEnvironmentDevice(state, 'device-a');
+    expect(state.active).toBeUndefined();
+    expect(state.lastKnownGood).toBeUndefined();
+    disposeEnvironmentGeneration(state);
+    expect(state.status).toBe('disposed');
+  });
+});

package/src/environment/__tests__/generation.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from 'vitest';
+import {
+  beginEnvironmentGeneration,
+  createEnvironmentGenerationState,
+  publishEnvironmentGeneration,
+} from '../generation';
+import {
+  abandonEnvironmentDevice,
+  disposeEnvironmentGeneration,
+  recoverEnvironmentDevice,
+} from '../lifecycle';
+
+describe('analytic environment generation state', () => {
+  it('freezes the desired snapshot and rejects cross-device candidates', () => {
+    const state = createEnvironmentGenerationState(7);
+    const attempt = beginEnvironmentGeneration(state, { signature: 's1', bytes: 8 });
+    expect(Object.isFrozen(state.desired)).toBe(true);
+    const candidate = attempt.complete('gpu-handle');
+    expect(() =>
+      publishEnvironmentGeneration(state, { ...candidate, deviceGeneration: 8 }),
+    ).toThrow('another device');
+  });
+
+  it('clears all generation references on device loss and dispose', () => {
+    const state = createEnvironmentGenerationState(1);
+    const attempt = beginEnvironmentGeneration(state, { signature: 's1', bytes: 8 });
+    publishEnvironmentGeneration(state, attempt.complete('gpu-handle'));
+    abandonEnvironmentDevice(state, 1);
+    expect(state.active).toBeUndefined();
+    expect(state.lastKnownGood).toBeUndefined();
+    recoverEnvironmentDevice(state, 2);
+    expect(state.status).toBe('idle');
+    expect(state.deviceGeneration).toBe(2);
+    disposeEnvironmentGeneration(state);
+    expect(state.status).toBe('disposed');
+  });
+});

package/src/environment/__tests__/graph-transaction.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it } from 'vitest';
+import { createEnvironmentProducerGraph, executeEnvironmentProducerTransaction } from '../graph';
+import { deriveEnvironmentBundleDescriptors } from '../signature';
+
+const graph = (dirty: boolean) =>
+  createEnvironmentProducerGraph({
+    descriptors: deriveEnvironmentBundleDescriptors(
+      { skySize: 128, irradianceSize: 32, prefilterMips: 5 },
+      'rgba16float',
+    ),
+    generation: 1,
+    dirty,
+  });
+
+function attempt() {
+  const events: string[] = [];
+  return {
+    events,
+    abort: (stage: string) => events.push(`abort:${stage}`),
+    publish: () => events.push('publish'),
+  };
+}
+
+describe('analytic environment producer graph transaction', () => {
+  it('declares three imported resources and exactly 42 dirty raster passes', () => {
+    const dirty = graph(true);
+    const steady = graph(false);
+    expect(dirty.importedResources.map((resource) => resource.kind)).toEqual([
+      'sky',
+      'irradiance',
+      'prefilter',
+    ]);
+    expect(dirty.passes).toHaveLength(42);
+    expect(dirty.passes.filter((pass) => pass.executeIf({ environmentDirty: true }))).toHaveLength(
+      42,
+    );
+    expect(
+      steady.passes.filter((pass) => pass.executeIf({ environmentDirty: false })),
+    ).toHaveLength(0);
+  });
+
+  it.each([
+    'execute',
+    'finish',
+    'submit',
+  ] as const)('aborts both transactions on %s failure', (stage) => {
+    const environment = attempt();
+    const temporal = attempt();
+    const trace = executeEnvironmentProducerTransaction({
+      graph: graph(true),
+      dirty: true,
+      environment,
+      temporal,
+      execute: () => stage !== 'execute',
+      finish: () => stage !== 'finish',
+      submit: () => stage !== 'submit',
+    });
+    expect(trace.abortedStage).toBe(stage);
+    expect(environment.events).toEqual([`abort:${stage}`]);
+    expect(temporal.events).toEqual([`abort:${stage}`]);
+  });
+
+  it('uses one encoder, finish, and submit and publishes atomically', () => {
+    const environment = attempt();
+    const temporal = attempt();
+    const trace = executeEnvironmentProducerTransaction({
+      graph: graph(true),
+      dirty: true,
+      environment,
+      temporal,
+      execute: () => true,
+      finish: () => true,
+      submit: () => true,
+    });
+    expect(trace).toMatchObject({
+      encoderCount: 1,
+      finishCount: 1,
+      submitCount: 1,
+      executedPassCount: 42,
+      published: true,
+    });
+    expect(environment.events).toEqual(['publish']);
+    expect(temporal.events).toEqual(['publish']);
+  });
+});

package/src/environment/__tests__/inspection-red.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest';
+import {
+  beginEnvironmentGeneration,
+  createEnvironmentGenerationState,
+  publishEnvironmentGeneration,
+} from '../generation';
+import { inspectEnvironmentGeneration, projectFogEnvironment } from '../inspection';
+
+describe('analytic environment bounded inspection red gate', () => {
+  it('projects the five lifecycle states without handles or mutable caches', () => {
+    const state = createEnvironmentGenerationState('device-a');
+    expect(inspectEnvironmentGeneration(state).state).toBe('off');
+
+    const first = beginEnvironmentGeneration(state, { signature: 'first', bytes: 64 });
+    expect(inspectEnvironmentGeneration(state).state).toBe('building');
+    publishEnvironmentGeneration(state, first.complete('gpu-handle'));
+    expect(inspectEnvironmentGeneration(state).state).toBe('ready');
+
+    const replacement = beginEnvironmentGeneration(state, { signature: 'replacement', bytes: 96 });
+    replacement.fail('execute');
+    const lastKnownGood = inspectEnvironmentGeneration(state, {
+      sourceWorldId: 7,
+      sourceEntity: 9,
+      taa: { activeSignature: 'first', publishCount: 1, resetCount: 1 },
+      rebuild: { passCount: 42, timeMs: 3.5 },
+    });
+    expect(lastKnownGood.state).toBe('last-known-good');
+    expect(lastKnownGood.source).toEqual({ worldId: 7, entity: 9 });
+    expect(lastKnownGood.failure?.stage).toBe('execute');
+    expect(lastKnownGood.rebuild).toEqual({ passCount: 42, timeMs: 3.5 });
+    expect(lastKnownGood).not.toHaveProperty('handle');
+    expect(lastKnownGood).not.toHaveProperty('cache');
+
+    const failed = createEnvironmentGenerationState('device-a');
+    const failedAttempt = beginEnvironmentGeneration(failed, { signature: 'failed', bytes: 1 });
+    failedAttempt.fail('build');
+    expect(inspectEnvironmentGeneration(failed).state).toBe('failed');
+  });
+
+  it('keeps fog as a readonly projection rather than a component or pass owner', () => {
+    const projection = projectFogEnvironment({
+      activeSignature: 'environment-signature',
+      sunDirection: [0, 1, 0],
+      illuminance: 12,
+    });
+    expect(projection).toEqual({
+      activeSignature: 'environment-signature',
+      sunDirection: [0, 1, 0],
+      illuminance: 12,
+    });
+    expect(JSON.stringify(projection)).not.toMatch(/(pass|uniform|component|handle)/i);
+  });
+});

package/src/environment/__tests__/lifecycle-evidence.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+import {
+  beginEnvironmentGeneration,
+  createEnvironmentGenerationState,
+  publishEnvironmentGeneration,
+} from '../generation';
+import {
+  completeEnvironmentQueue,
+  createEnvironmentLifecycleEvidence,
+  noteEnvironmentAllocation,
+  noteEnvironmentQueueCompletion,
+  noteEnvironmentRetire,
+} from '../lifecycle';
+
+describe('analytic environment raw lifecycle evidence', () => {
+  it('keeps bytes and peak recomputable from candidate plus active', () => {
+    let evidence = createEnvironmentLifecycleEvidence();
+    evidence = noteEnvironmentAllocation(evidence, 1_883_136);
+    evidence = noteEnvironmentAllocation(evidence, 1_883_136);
+    evidence = noteEnvironmentRetire(evidence);
+    evidence = noteEnvironmentQueueCompletion(evidence);
+    expect(evidence).toEqual({
+      bytes: 3_766_272,
+      peakBytes: 3_766_272,
+      retireEvents: 1,
+      queueCompletions: 1,
+    });
+  });
+
+  it('records queue completion as the retirement boundary', () => {
+    const state = createEnvironmentGenerationState('device');
+    const first = beginEnvironmentGeneration(state, { signature: 'first', bytes: 1 });
+    publishEnvironmentGeneration(state, first.complete('first-handle'));
+    const second = beginEnvironmentGeneration(state, { signature: 'second', bytes: 1 });
+    publishEnvironmentGeneration(state, second.complete('second-handle'), 'queue-2');
+    expect(state.retired[0]?.retired).toBe(false);
+    completeEnvironmentQueue(state, 'queue-2');
+    expect(state.retired[0]?.retired).toBe(true);
+  });
+});

package/src/environment/__tests__/pipeline-topology.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest';
+import { createEnvironmentPipelineTopology } from '../../render-pipeline';
+
+describe('analytic environment pipeline topology', () => {
+  it('keeps URP shadows, producer, background/disc, and forward order', () => {
+    expect(createEnvironmentPipelineTopology('urp')).toEqual([
+      'urp.shadow',
+      'urp.atmosphere-producer',
+      'urp.environment-background',
+      'urp.sun-disc',
+      'urp.forward',
+    ]);
+  });
+
+  it('keeps HDRP membership/shadows, producer, deferred lighting, and depth-aware background order', () => {
+    expect(createEnvironmentPipelineTopology('hdrp')).toEqual([
+      'hdrp.membership',
+      'hdrp.shadow',
+      'hdrp.atmosphere-producer',
+      'hdrp.g-buffer',
+      'hdrp.lighting',
+      'hdrp.environment-background-depth-aware',
+      'hdrp.sun-disc',
+      'hdrp.forward',
+    ]);
+  });
+
+  it('does not put the sun disc into the sky cube', () => {
+    const topology = createEnvironmentPipelineTopology('urp');
+    expect(topology).not.toContain('urp.sky-cube-with-disc');
+    expect(topology.filter((name) => name.includes('sun-disc'))).toHaveLength(1);
+  });
+});