@forgeax/engine-render 0.1.23 → 0.1.25

package/src/points-lines/standard-owner.ts

@@ -0,0 +1,403 @@
+import { resolveAssetHandle } from '@forgeax/engine-assets-runtime';
+import { deriveVertexLayoutProjection } from '@forgeax/engine-geometry';
+import { err, ok } from '@forgeax/engine-rhi';
+import type { MaterialAsset, MeshAsset } from '@forgeax/engine-types';
+import { toShared } from '@forgeax/engine-types';
+import { PointsLinesMaterialUnsupportedError } from '../errors/render';
+import {
+  GPU_BUFFER_USAGE_COPY_DST,
+  GPU_BUFFER_USAGE_INDEX,
+  GPU_BUFFER_USAGE_VERTEX,
+} from '../gpu-usage';
+import type { ValidatedRenderable } from '../record/frame-snapshot';
+import type {
+  PointsLinesRecordOwner,
+  PointsLinesRecordSubmission,
+  RenderSystemInternals,
+} from '../record/render-context';
+import type { RecoveryPointsLinesCandidate } from '../render-system';
+import { admitPointsLines } from './admission';
+import { PointsLinesExpansionCache } from './expansion-cache';
+import type { PointsLinesInspection, PointsLinesSourceError } from './inspection';
+import { inspectPointsLines } from './inspection';
+import {
+  createPointsLinesLanePreparationAdapter,
+  type PointsLinesLanePreparationAdapter,
+} from './prepare';
+import {
+  createPointsLinesLaneAdapter,
+  type PointsLinesBackend,
+  type PointsLinesLane,
+} from './record';
+import type { PointsLinesRetainedSnapshot } from './snapshot';
+
+type PointsLinesGpuResources = {
+  readonly vertexBuffer: import('@forgeax/engine-rhi').Buffer;
+  readonly indexBuffer: import('@forgeax/engine-rhi').Buffer;
+};
+type PointsLinesPreparationAdapter = PointsLinesLanePreparationAdapter<PointsLinesGpuResources>;
+
+/**
+ * The Standard renderer's single Points/Lines prepare owner.
+ *
+ * The retained snapshot is the identity boundary; this owner only resolves
+ * the source assets, runs admission, and publishes the existing preparation
+ * and record contracts to the main geometry loop. The expansion cache is
+ * shared across lanes and this owner keeps the one prepared vertex/index
+ * resource pair for each retained identity.
+ */
+export class StandardPointsLinesOwner implements PointsLinesRecordOwner {
+  private readonly cache = new PointsLinesExpansionCache();
+  private readonly preparations = new Map<string, PointsLinesPreparationAdapter>();
+  private readonly active = new Map<string, PointsLinesInspection>();
+  private readonly layoutProjection = deriveVertexLayoutProjection({
+    position: new Float32Array(0),
+    normal: new Float32Array(0),
+    uv: new Float32Array(0),
+    tangent: new Float32Array(0),
+  });
+
+  constructor(private readonly internals: RenderSystemInternals) {}
+
+  beginFrame(): void {
+    this.active.clear();
+  }
+
+  prepare(entry: ValidatedRenderable, clustered: boolean): PointsLinesRecordSubmission | undefined {
+    return this.prepareWithMaps(entry, clustered, this.internals, this.preparations, this.active);
+  }
+
+  prepareRecoveryCandidate(
+    entries: readonly ValidatedRenderable[],
+    clustered: boolean,
+    runtime: RenderSystemInternals,
+  ): RecoveryPointsLinesCandidate | undefined {
+    const stagedPreparations = new Map<string, PointsLinesPreparationAdapter>();
+    const stagedInspections = new Map<string, PointsLinesInspection>();
+    let pointEntryCount = 0;
+    try {
+      for (const entry of entries) {
+        const snapshot = entry.source.pointsLines;
+        if (snapshot?.component === undefined) continue;
+        pointEntryCount += 1;
+        const prepared = this.prepareWithMaps(
+          entry,
+          clustered,
+          runtime,
+          stagedPreparations,
+          stagedInspections,
+        );
+        if (prepared === undefined) {
+          throw new Error(
+            `recovery Points/Lines preparation failed for ${snapshot.worldId}:${snapshot.entityKey}`,
+          );
+        }
+      }
+    } catch (cause) {
+      for (const preparation of stagedPreparations.values()) {
+        preparation.resetForDeviceLoss();
+      }
+      throw cause;
+    }
+    if (pointEntryCount === 0) return undefined;
+
+    let released = false;
+    let published = false;
+    const candidate: RecoveryPointsLinesCandidate = {
+      createRecoveryRoot: (scope) => ({
+        kind: 'buffer',
+        create: () => {
+          if (!scope.isAlive() || released) {
+            throw new Error('Points/Lines recovery candidate scope is not active.');
+          }
+          return candidate;
+        },
+        cleanup: () => candidate.release(),
+      }),
+      publish: () => {
+        if (released || published) return;
+        this.preparations.clear();
+        for (const [key, preparation] of stagedPreparations) {
+          this.preparations.set(key, preparation);
+        }
+        published = true;
+      },
+      release: () => {
+        if (released || published) return;
+        released = true;
+        for (const preparation of stagedPreparations.values()) {
+          preparation.resetForDeviceLoss();
+        }
+        stagedPreparations.clear();
+        stagedInspections.clear();
+      },
+    };
+    return candidate;
+  }
+
+  private prepareWithMaps(
+    entry: ValidatedRenderable,
+    clustered: boolean,
+    runtime: RenderSystemInternals,
+    preparations: Map<string, PointsLinesPreparationAdapter>,
+    inspections: Map<string, PointsLinesInspection>,
+  ): PointsLinesRecordSubmission | undefined {
+    const snapshot = entry.source.pointsLines;
+    if (snapshot === undefined || snapshot.component === undefined || entry.world === undefined) {
+      return undefined;
+    }
+    const key = `${snapshot.worldId}:${snapshot.entityKey}`;
+    const topology = snapshot.component === 'Points' ? 'point-list' : 'line-list';
+    const backend = this.backend(runtime);
+    const lane = backend === 'wgpu-webgl2' ? 'cpu-webgl2' : clustered ? 'clustered' : 'direct';
+    const meshResult = resolveAssetHandle<MeshAsset>(
+      entry.world,
+      toShared<'MeshAsset'>(entry.source.assetHandle),
+    );
+    const materialResult = resolveAssetHandle<MaterialAsset>(
+      entry.world,
+      toShared<'MaterialAsset'>(snapshot.materialHandle),
+    );
+    if (!meshResult.ok || !materialResult.ok) {
+      this.publishRefusal(
+        inspections,
+        snapshot,
+        new PointsLinesMaterialUnsupportedError({
+          entity: snapshot.entityKey,
+          material: 'unresolved',
+          pass: 'forward',
+          module: 'asset-resolution',
+          reason: 'source MeshAsset or MaterialAsset could not be resolved',
+        }),
+      );
+      return undefined;
+    }
+    const admission = admitPointsLines({
+      entity: snapshot.entityKey,
+      mesh: meshResult.value,
+      material: materialResult.value,
+      ...(snapshot.style?.kind === 'points'
+        ? {
+            points: {
+              sizePx: snapshot.style.sizePx,
+              shape: snapshot.style.shape === 'circle' ? 1 : 0,
+            },
+          }
+        : { lines: { widthPx: snapshot.style?.widthPx ?? 1 } }),
+    });
+    if (!admission.ok) {
+      this.publishRefusal(inspections, snapshot, admission.error);
+      return undefined;
+    }
+    const geometryKey = this.cache.getOrCreate(snapshot, meshResult.value).key;
+    const prepKey = `${geometryKey}:${lane}:${backend}`;
+    let preparation = preparations.get(prepKey);
+    if (preparation === undefined) {
+      // A new expansion is visible cold upload work. Candidate preparation
+      // uses an unarmed runtime and stages the result; the published runtime
+      // is armed, so a missing staged resource fails before any RHI create.
+      runtime.recoveryColdWorkGuard?.noteUploadColdWork();
+      preparation = this.createPreparation(runtime, geometryKey, lane, backend);
+      preparations.set(prepKey, preparation);
+    } else if (preparation.lastKnownGood()?.geometry.key !== geometryKey) {
+      runtime.recoveryColdWorkGuard?.noteUploadColdWork();
+    }
+    const prepared = preparation.prepare(snapshot, meshResult.value);
+    if (!prepared.ok) {
+      const lkg = preparation.lastKnownGood();
+      if (lkg !== undefined) {
+        const lkgPlan = createPointsLinesLaneAdapter(lane, backend).createRecordPlan(
+          lkg.snapshot,
+          lkg.geometry,
+        );
+        const state = preparation.inspect();
+        inspections.set(
+          key,
+          inspectPointsLines({
+            snapshot,
+            topology,
+            lane,
+            pointCount: lkg.geometry.pointCount,
+            segmentCount: lkg.geometry.segmentCount,
+            sourceBytes: lkg.geometry.sourceBytes,
+            derivedBytes: lkg.geometry.derivedBytes,
+            cache: { hit: true, rebuilds: state.rebuilds, evictions: 0 },
+            drawCount: lkgPlan.drawCount,
+            uploadBytes: 0,
+            lastKnownGood: true,
+            refusal: {
+              code: prepared.error.code,
+              expected: prepared.error.expected,
+              hint: prepared.error.hint,
+              detail: prepared.error.detail,
+              generation: prepared.error.detail.generation,
+              lastKnownGood: true,
+            },
+          }),
+        );
+        return {
+          plan: lkgPlan,
+          vertexBuffer: lkg.resource.vertexBuffer,
+          indexBuffer: lkg.resource.indexBuffer,
+          layoutProjection: this.layoutProjection,
+        };
+      }
+      this.publishRefusal(inspections, snapshot, prepared.error);
+      return undefined;
+    }
+    const plan = createPointsLinesLaneAdapter(lane, backend).createRecordPlan(
+      snapshot,
+      prepared.value.geometry,
+    );
+    const state = preparation.inspect();
+    inspections.set(
+      key,
+      inspectPointsLines({
+        snapshot,
+        topology,
+        lane,
+        pointCount: prepared.value.geometry.pointCount,
+        segmentCount: prepared.value.geometry.segmentCount,
+        sourceBytes: prepared.value.geometry.sourceBytes,
+        derivedBytes: prepared.value.geometry.derivedBytes,
+        cache: {
+          hit: prepared.value.uploadedBytes === 0,
+          rebuilds: state.rebuilds,
+          evictions: 0,
+        },
+        drawCount: plan.drawCount,
+        uploadBytes: prepared.value.uploadedBytes,
+        lastKnownGood: prepared.value.lastKnownGood,
+      }),
+    );
+    return {
+      plan,
+      vertexBuffer: prepared.value.resource.vertexBuffer,
+      indexBuffer: prepared.value.resource.indexBuffer,
+      layoutProjection: this.layoutProjection,
+    };
+  }
+
+  resetForDeviceLoss(): void {
+    for (const preparation of this.preparations.values()) preparation.resetForDeviceLoss();
+    this.active.clear();
+  }
+
+  abandonForDeviceLoss(): void {
+    for (const preparation of this.preparations.values()) {
+      preparation.abandonForDeviceLoss();
+    }
+    this.active.clear();
+  }
+
+  dispose(): void {
+    this.resetForDeviceLoss();
+    this.preparations.clear();
+  }
+
+  inspections(): readonly PointsLinesInspection[] {
+    return [...this.active.values()];
+  }
+
+  private backend(runtime: RenderSystemInternals): PointsLinesBackend {
+    switch (runtime.device.caps.backendKind) {
+      case 'wgpu-webgl2':
+        return 'wgpu-webgl2';
+      case 'null':
+        return 'null';
+      default:
+        return 'webgpu';
+    }
+  }
+
+  private publishRefusal(
+    inspections: Map<string, PointsLinesInspection>,
+    snapshot: PointsLinesRetainedSnapshot,
+    error: PointsLinesSourceError,
+  ): void {
+    inspections.set(
+      `${snapshot.worldId}:${snapshot.entityKey}`,
+      inspectPointsLines({
+        snapshot,
+        topology: snapshot.component === 'Points' ? 'point-list' : 'line-list',
+        lane: 'refused',
+        pointCount: 0,
+        segmentCount: 0,
+        sourceBytes: 0,
+        derivedBytes: 0,
+        cache: { hit: false, rebuilds: 0, evictions: 0 },
+        drawCount: 0,
+        uploadBytes: 0,
+        lastKnownGood: false,
+        refusal: {
+          code: error.code,
+          expected: error.expected,
+          hint: error.hint,
+          detail: error.detail,
+          generation: snapshot.meshGeneration,
+          lastKnownGood: false,
+        },
+      }),
+    );
+  }
+
+  private createPreparation(
+    runtime: RenderSystemInternals,
+    geometryKey: string,
+    lane: PointsLinesLane,
+    backend: PointsLinesBackend,
+  ): PointsLinesPreparationAdapter {
+    return createPointsLinesLanePreparationAdapter(lane, backend, {
+      cache: this.cache,
+      adapter: {
+        create: (geometry) => {
+          const vertex = runtime.device.createBuffer({
+            label: `points-lines-vertices:${geometryKey}`,
+            size: Math.max(4, geometry.vertices.byteLength),
+            usage: GPU_BUFFER_USAGE_VERTEX | GPU_BUFFER_USAGE_COPY_DST,
+            mappedAtCreation: false,
+          });
+          if (!vertex.ok) return err(vertex.error);
+          const index = runtime.device.createBuffer({
+            label: `points-lines-indices:${geometryKey}`,
+            size: Math.max(4, geometry.indices.byteLength),
+            usage: GPU_BUFFER_USAGE_INDEX | GPU_BUFFER_USAGE_COPY_DST,
+            mappedAtCreation: false,
+          });
+          if (!index.ok) {
+            runtime.device.destroyBuffer(vertex.value);
+            return err(index.error);
+          }
+          return ok({ vertexBuffer: vertex.value, indexBuffer: index.value });
+        },
+        upload: (resource, geometry) => {
+          if (geometry.vertices.byteLength > 0) {
+            const vertexWrite = runtime.device.queue.writeBuffer(
+              resource.vertexBuffer,
+              0,
+              geometry.vertices,
+            );
+            if (!vertexWrite.ok) return err(vertexWrite.error);
+          }
+          if (geometry.indices.byteLength > 0) {
+            const indexWrite = runtime.device.queue.writeBuffer(
+              resource.indexBuffer,
+              0,
+              geometry.indices,
+            );
+            if (!indexWrite.ok) return err(indexWrite.error);
+          }
+          return ok(geometry.derivedBytes);
+        },
+        validate: (_resource, geometry) =>
+          geometry.expandedVertexCount > 0 && geometry.expandedIndexCount > 0
+            ? ok(undefined)
+            : err(new Error('Points/Lines expansion contains no drawable triangles')),
+        destroy: (resource) => {
+          runtime.device.destroyBuffer(resource.vertexBuffer);
+          runtime.device.destroyBuffer(resource.indexBuffer);
+        },
+      },
+    });
+  }
+}

package/src/record/__tests__/frame-targets-recovery.unit.test.ts

@@ -0,0 +1,60 @@
+import type { RhiCanvasContext, RhiDevice, Texture, TextureView } from '@forgeax/engine-rhi';
+import { err, ok, RhiError } from '@forgeax/engine-rhi';
+import { describe, expect, it, vi } from 'vitest';
+import { acquireSwapChainTarget } from '../frame-targets';
+import type { PipelineState, RenderSystemInternals } from '../render-context';
+
+function device(): RhiDevice {
+  return {
+    caps: { backendKind: 'webgpu', storageBuffer: true },
+    limits: {},
+    createTextureView: vi.fn(() => ok({} as TextureView)),
+  } as unknown as RhiDevice;
+}
+
+function unavailableSurfaceError(): RhiError {
+  return new RhiError({
+    code: 'webgpu-runtime-error',
+    expected: 'the surface has a current texture',
+    hint: 'configure the surface and retry',
+  });
+}
+
+describe('acquireSwapChainTarget recovery', () => {
+  it('resolves the recorder device before reconfiguring a recovered surface', () => {
+    const recorderDevice = device();
+    const configuredDevice = device();
+    const texture = {} as Texture;
+    const getCurrentTexture = vi
+      .fn()
+      .mockReturnValueOnce(err(unavailableSurfaceError()))
+      .mockReturnValueOnce(ok(texture));
+    const configure = vi.fn(() => ok(undefined));
+    const context = { configure, getCurrentTexture } as unknown as RhiCanvasContext;
+    const resolveSurfaceDevice = vi.fn(() => ok(configuredDevice));
+    const internals = {
+      context,
+      device: recorderDevice,
+      canvas: { width: 800, height: 600 },
+      resolveSurfaceDevice,
+      errorRegistry: { fire: vi.fn() },
+      healthRegistry: { fire: vi.fn() },
+    } as unknown as RenderSystemInternals;
+    const pipelineState = {
+      device: recorderDevice,
+      format: 'bgra8unorm',
+      colorAttachmentFormat: 'bgra8unorm',
+      perPassResources: { configured: false },
+    } as unknown as PipelineState;
+
+    const result = acquireSwapChainTarget(internals, pipelineState);
+
+    expect(result).toMatchObject({ currentTexture: texture, targetW: 800, targetH: 600 });
+    expect(resolveSurfaceDevice).toHaveBeenCalledWith(recorderDevice);
+    expect(configure).toHaveBeenCalledWith(
+      expect.objectContaining({ device: configuredDevice, format: 'bgra8unorm' }),
+    );
+    expect(getCurrentTexture).toHaveBeenCalledTimes(2);
+    expect(pipelineState.perPassResources.configured).toBe(true);
+  });
+});

package/src/record/__tests__/main-pass-geometry.unit.test.ts

@@ -1,5 +1,8 @@
 import { describe, expect, it } from 'vitest';
-import { geometryRenderStateForPass } from '../main-pass-geometry';
+import {
+  geometryRenderStateForPass,
+  requestsStandardTransmissionVariant,
+} from '../main-pass-geometry';
 
 describe('geometry pass render state', () => {
   it('keeps the main depth authority while admitting equal temporal depth', () => {
@@ -45,3 +48,25 @@ describe('geometry pass render state', () => {
     expect(accepted).toEqual([visibleDepth]);
   });
 });
+
+describe('Standard transmission variant selection', () => {
+  it('uses authored transmission presence instead of the canonical reserved schema', () => {
+    const baseOnly = {
+      materialShaderId: 'forgeax::default-standard-pbr',
+      paramSnapshot: { alphaCutoff: 0.25 },
+    } as const;
+    const transmission = {
+      materialShaderId: 'forgeax::default-standard-pbr',
+      paramSnapshot: { transmission: 0 },
+    } as const;
+
+    expect(requestsStandardTransmissionVariant(baseOnly)).toBe(false);
+    expect(requestsStandardTransmissionVariant(transmission)).toBe(true);
+    expect(
+      requestsStandardTransmissionVariant({
+        materialShaderId: 'custom::standard',
+        paramSnapshot: { transmission: 1 },
+      }),
+    ).toBe(false);
+  });
+});

package/src/record/__tests__/mesh-ssbo.unit.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest';
+import { getOrCreateFromChain } from '../mesh-ssbo';
+
+describe('mesh bind-group cache chains', () => {
+  it('keeps variable-depth material resource chains isolated', () => {
+    const root = new WeakMap<object, unknown>();
+    const shared = { shared: true };
+    const coatSampler = { coatSampler: true };
+    const coatTexture = { coatTexture: true };
+    const counts = { createBindGroup: 0, keys: [] as string[] };
+    const long = getOrCreateFromChain(
+      root,
+      [shared, coatSampler, coatTexture],
+      'material-shared',
+      () => ({ id: 'long' }) as never,
+      counts,
+    );
+    const short = getOrCreateFromChain(
+      root,
+      [shared, coatSampler],
+      'material-shared',
+      () => ({ id: 'short' }) as never,
+      counts,
+    );
+
+    expect(
+      getOrCreateFromChain(
+        root,
+        [shared, coatSampler],
+        'material-shared',
+        () => ({ id: 'unexpected' }) as never,
+        counts,
+      ),
+    ).toBe(short);
+    expect(long).not.toBe(short);
+    expect(counts.createBindGroup).toBe(2);
+  });
+});

package/src/record/__tests__/recovery-pipeline.unit.test.ts

@@ -0,0 +1,124 @@
+import { deriveVertexLayoutProjection } from '@forgeax/engine-geometry';
+import { describe, expect, it } from 'vitest';
+import { makeZeroCameraFallbackSnapshot, type ValidatedRenderable } from '../frame-snapshot';
+import {
+  createRecoveryColdWorkGuard,
+  prepareRecoveryPipelineReadiness,
+} from '../recovery-pipeline';
+import type { PipelineState, RenderSystemInternals } from '../render-context';
+
+function probeRenderable(probe: boolean): ValidatedRenderable {
+  const material = {
+    baseColor: [1, 1, 1],
+    metallic: 0,
+    roughness: 1,
+    materialShaderId: 'forgeax::default-standard-pbr',
+  } as never;
+  return {
+    source: {
+      material,
+      materials: [material],
+      ...(probe ? { probeBlendRecord: {} } : {}),
+    },
+    mesh: {
+      layoutProjection: deriveVertexLayoutProjection({
+        position: new Float32Array(0),
+        normal: new Float32Array(0),
+        uv: new Float32Array(0),
+        tangent: new Float32Array(0),
+      }),
+      indexFormat: 'uint32',
+      submeshes: [
+        {
+          indexOffset: 0,
+          indexCount: 3,
+          vertexCount: 3,
+          topology: 'triangle-list',
+          materialSlot: 0,
+        },
+      ],
+    },
+  } as never;
+}
+
+function recoveryReadinessFor(
+  renderable: ValidatedRenderable,
+  reflectionFallbackAvailable = false,
+) {
+  const pipeline = {} as never;
+  const internals = {
+    device: { caps: { backendKind: 'webgpu', storageBuffer: true } },
+    getMaterialShaderPipelineEntry: (..._args: unknown[]) => ({
+      pipeline,
+      group2Contract: 'cluster' as const,
+    }),
+  } as unknown as RenderSystemInternals;
+  const pipelineState = {
+    colorAttachmentFormat: 'bgra8unorm',
+  } as unknown as PipelineState;
+  return prepareRecoveryPipelineReadiness({
+    internals,
+    pipelineState,
+    camera: makeZeroCameraFallbackSnapshot(),
+    standardLighting: { kind: 'no-local-lights' } as never,
+    validated: [renderable],
+    dispatch: [],
+    shadowCastersActive: false,
+    splitLdrSprite: false,
+    reflectionFallbackAvailable,
+  });
+}
+
+describe('recovery first-frame cold-work guard', () => {
+  it('prepares the probe-enabled Standard PBR variant used by the live record path', () => {
+    const readiness = recoveryReadinessFor(probeRenderable(true));
+    const standardPbr = readiness.pipelineSpecs.find(
+      (spec) => spec.shader.id === 'forgeax::default-standard-pbr',
+    );
+
+    expect(standardPbr?.shader.variantSet).toContain('PROBE_BLEND_AVAILABLE=true');
+  });
+
+  it('does not add the probe ABI to a Standard PBR renderable without a record', () => {
+    const readiness = recoveryReadinessFor(probeRenderable(false));
+    const standardPbr = readiness.pipelineSpecs.find(
+      (spec) => spec.shader.id === 'forgeax::default-standard-pbr',
+    );
+
+    expect(standardPbr?.shader.variantSet).not.toContain('PROBE_BLEND_AVAILABLE=true');
+  });
+
+  it('prepares the Standard PBR reflection fallback MRT variant', () => {
+    const readiness = recoveryReadinessFor(probeRenderable(false), true);
+    const standardPbr = readiness.pipelineSpecs.find(
+      (spec) => spec.shader.id === 'forgeax::default-standard-pbr',
+    );
+
+    expect(standardPbr?.shader.variantSet).toContain('REFLECTION_FALLBACK_AVAILABLE=true');
+    expect(standardPbr?.attachments.colorFormats).toEqual(['rgba16float', 'rgba16float']);
+  });
+
+  it('accepts a prepared candidate with no first-frame cold work', () => {
+    const guard = createRecoveryColdWorkGuard();
+
+    guard.arm();
+    expect(() => guard.finish()).not.toThrow();
+    expect(() => guard.finish()).not.toThrow();
+  });
+
+  it.each([
+    [
+      'pipeline',
+      (guard: ReturnType<typeof createRecoveryColdWorkGuard>) => guard.notePipelineColdWork(),
+    ],
+    [
+      'upload',
+      (guard: ReturnType<typeof createRecoveryColdWorkGuard>) => guard.noteUploadColdWork(),
+    ],
+  ] as const)('hard-fails a first-frame %s miss before submission', (_kind, note) => {
+    const guard = createRecoveryColdWorkGuard();
+
+    guard.arm();
+    expect(() => note(guard)).toThrow(/recovery first frame performed cold/);
+  });
+});