@forgeax/engine-render 0.1.28 → 0.1.30

package/src/ssr/history.ts

@@ -0,0 +1,436 @@
+import type {
+  Buffer,
+  RhiDevice,
+  RhiError,
+  RhiQueue,
+  Texture,
+  TextureDescriptor,
+  TextureView,
+} from '@forgeax/engine-rhi';
+import { err, ok, type Result } from '@forgeax/engine-types';
+import type { DeviceScope } from '../device/device-scope';
+import {
+  GPU_TEXTURE_USAGE_COPY_DST,
+  GPU_TEXTURE_USAGE_COPY_SRC,
+  GPU_TEXTURE_USAGE_RENDER_ATTACHMENT,
+  GPU_TEXTURE_USAGE_STORAGE_BINDING,
+  GPU_TEXTURE_USAGE_TEXTURE_BINDING,
+} from '../gpu-texture-usage';
+import { GPU_BUFFER_USAGE_COPY_DST, GPU_BUFFER_USAGE_UNIFORM } from '../gpu-usage';
+
+export const SSR_HISTORY_FORMAT = 'rgba16float' as const;
+export type SsrHistoryResetReason =
+  | 'first-enable'
+  | 'resize'
+  | 'camera-cut'
+  | 'history-version'
+  | 'coverage-loss'
+  | 'reflection-generation'
+  | 'device-recovery'
+  | 'disable';
+export type SsrHistoryFailureStage = 'build' | 'encode' | 'finish' | 'submit';
+export type SsrHistoryState =
+  | 'first-frame'
+  | 'stable'
+  | 'reset'
+  | 'aborted'
+  | 'retiring'
+  | 'retired'
+  | 'disposed';
+
+export interface SsrHistorySlot {
+  readonly texture: Texture;
+  readonly view: TextureView;
+  readonly surfaceTexture: Texture;
+  readonly surfaceView: TextureView;
+}
+export interface SsrHistoryResources {
+  readonly width: number;
+  readonly height: number;
+  readonly halfWidth: number;
+  readonly halfHeight: number;
+  readonly bytes: number;
+  readonly descriptor: TextureDescriptor;
+  readonly slots: readonly [SsrHistorySlot, SsrHistorySlot];
+  /** One renderer-owned parameter block shared by the temporal resolve. */
+  readonly paramsBuffer: Buffer;
+  readonly childScope: DeviceScope;
+}
+export interface SsrHistoryCandidate {
+  readonly readSlot: 0 | 1 | null;
+  readonly writeSlot: 0 | 1;
+  readonly historyValid: boolean;
+}
+export interface SsrHistoryInspection {
+  readonly state: SsrHistoryState;
+  readonly width: number;
+  readonly height: number;
+  readonly halfWidth: number;
+  readonly halfHeight: number;
+  readonly format: typeof SSR_HISTORY_FORMAT;
+  readonly historyCount: 0 | 2;
+  readonly historyValid: boolean;
+  readonly readSlot: 0 | 1 | null;
+  readonly writeSlot: 0 | 1;
+  readonly activeBytes: number;
+  readonly candidateBytes: number;
+  readonly retiringBytes: number;
+  readonly resetCount: number;
+  readonly resetReason: SsrHistoryResetReason | undefined;
+  readonly lastFailure: SsrHistoryFailureStage | undefined;
+}
+export interface SsrHistoryError {
+  readonly code:
+    | 'ssr-history-unavailable'
+    | 'ssr-history-active'
+    | 'ssr-history-not-active'
+    | 'ssr-history-retired';
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail?: Readonly<{
+    readonly stage?: SsrHistoryFailureStage;
+    readonly reason?: SsrHistoryResetReason;
+  }>;
+}
+
+const HISTORY_USAGE =
+  GPU_TEXTURE_USAGE_COPY_SRC |
+  GPU_TEXTURE_USAGE_COPY_DST |
+  GPU_TEXTURE_USAGE_TEXTURE_BINDING |
+  GPU_TEXTURE_USAGE_STORAGE_BINDING |
+  GPU_TEXTURE_USAGE_RENDER_ATTACHMENT;
+
+function positiveDimension(value: number, field: string): number {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new RangeError(`${field} must be a positive safe integer.`);
+  }
+  return value;
+}
+
+function createResources(
+  device: RhiDevice,
+  scope: DeviceScope,
+  width: number,
+  height: number,
+): Result<SsrHistoryResources, RhiError> {
+  const halfWidth = Math.max(1, Math.floor(width / 2));
+  const halfHeight = Math.max(1, Math.floor(height / 2));
+  const descriptor: TextureDescriptor = {
+    label: 'ssr-history-rgba16float',
+    size: { width: halfWidth, height: halfHeight, depthOrArrayLayers: 1 },
+    format: SSR_HISTORY_FORMAT,
+    usage: HISTORY_USAGE,
+    mipLevelCount: 1,
+    sampleCount: 1,
+    dimension: '2d',
+    viewFormats: undefined,
+    textureBindingViewDimension: undefined,
+  };
+  const childScope = scope.createChild(`${scope.owner}:ssr-history`);
+  const slots: SsrHistorySlot[] = [];
+  for (const index of [0, 1] as const) {
+    const texture = device.createTexture({
+      ...descriptor,
+      label: `ssr-history-rgba16float-${index}`,
+    });
+    if (!texture.ok) {
+      childScope.abandon();
+      return texture;
+    }
+    childScope._adopt('texture', texture.value, (value) => {
+      device.destroyTexture(value);
+    });
+    const view = device.createTextureView(texture.value, {
+      label: `ssr-history-rgba16float-${index}.view`,
+      dimension: '2d',
+      baseMipLevel: 0,
+      mipLevelCount: 1,
+      baseArrayLayer: 0,
+      arrayLayerCount: 1,
+    });
+    if (!view.ok) {
+      childScope.abandon();
+      return view;
+    }
+    const surfaceTexture = device.createTexture({
+      ...descriptor,
+      label: `ssr-history-surface-${index}`,
+      format: 'rgba8unorm',
+    });
+    if (!surfaceTexture.ok) {
+      childScope.abandon();
+      return surfaceTexture;
+    }
+    childScope._adopt('texture', surfaceTexture.value, (value) => {
+      device.destroyTexture(value);
+    });
+    const surfaceView = device.createTextureView(surfaceTexture.value, { dimension: '2d' });
+    if (!surfaceView.ok) {
+      childScope.abandon();
+      return surfaceView;
+    }
+    slots.push({
+      texture: texture.value,
+      view: view.value,
+      surfaceTexture: surfaceTexture.value,
+      surfaceView: surfaceView.value,
+    });
+  }
+  const params = device.createBuffer({
+    label: 'ssr-temporal-params',
+    size: 32,
+    usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
+    mappedAtCreation: false,
+  });
+  if (!params.ok) {
+    childScope.abandon();
+    return params;
+  }
+  childScope._adopt('buffer', params.value, (value) => {
+    device.destroyBuffer(value);
+  });
+  const cleared = device.queue.writeBuffer(params.value, 0, new Uint8Array(32));
+  if (!cleared.ok) {
+    childScope.abandon();
+    return cleared;
+  }
+  return ok({
+    width,
+    height,
+    halfWidth,
+    halfHeight,
+    bytes: halfWidth * halfHeight * 12 * 2,
+    descriptor,
+    slots: slots as [SsrHistorySlot, SsrHistorySlot],
+    paramsBuffer: params.value,
+    childScope,
+  });
+}
+
+function failure(
+  code: SsrHistoryError['code'],
+  expected: string,
+  hint: string,
+  detail?: SsrHistoryError['detail'],
+): SsrHistoryError {
+  return { code, expected, hint, ...(detail === undefined ? {} : { detail }) };
+}
+
+/** Owns only SSR's two physical history slots; the shared coordinator owns epochs. */
+export class SsrHistoryOwner {
+  private activeResources: SsrHistoryResources | undefined;
+  private readonly retiringResources = new Set<SsrHistoryResources>();
+  private retirementFencePending = false;
+  private activeCandidate: SsrHistoryCandidate | undefined;
+  private readIndex: 0 | 1 = 0;
+  private valid = false;
+  private state: SsrHistoryState = 'first-frame';
+  private resetReason: SsrHistoryResetReason | undefined = 'first-enable';
+  private lastFailure: SsrHistoryFailureStage | undefined;
+  private resetCount = 0;
+
+  private constructor(
+    private readonly device: RhiDevice,
+    private readonly scope: DeviceScope,
+    resources: SsrHistoryResources,
+  ) {
+    this.activeResources = resources;
+  }
+
+  static create(input: {
+    readonly device: RhiDevice;
+    readonly scope: DeviceScope;
+    readonly width: number;
+    readonly height: number;
+  }): Result<SsrHistoryOwner, RhiError> {
+    const width = positiveDimension(input.width, 'width');
+    const height = positiveDimension(input.height, 'height');
+    const resources = createResources(input.device, input.scope, width, height);
+    return resources.ok
+      ? ok(new SsrHistoryOwner(input.device, input.scope, resources.value))
+      : resources;
+  }
+
+  get resources(): SsrHistoryResources {
+    if (this.activeResources === undefined) throw new Error('SSR history resources are retired.');
+    return this.activeResources;
+  }
+
+  beginFrame(): Result<SsrHistoryCandidate, SsrHistoryError> {
+    if (
+      this.activeResources === undefined ||
+      this.state === 'retired' ||
+      this.state === 'disposed'
+    ) {
+      return err(
+        failure(
+          'ssr-history-retired',
+          'SSR history resources are active',
+          'recreate the renderer-owned SSR history after device recovery',
+        ),
+      );
+    }
+    if (this.activeCandidate !== undefined) {
+      return err(
+        failure(
+          'ssr-history-active',
+          'one SSR history candidate is active',
+          'commit or abort the active SSR history candidate before beginning another',
+        ),
+      );
+    }
+    const writeSlot: 0 | 1 = this.valid ? (this.readIndex === 0 ? 1 : 0) : 0;
+    const candidate = Object.freeze({
+      readSlot: this.valid ? this.readIndex : null,
+      writeSlot,
+      historyValid: this.valid && this.resetReason === undefined,
+    }) as SsrHistoryCandidate;
+    this.activeCandidate = candidate;
+    this.state = this.valid ? 'stable' : this.state === 'aborted' ? 'aborted' : 'first-frame';
+    this.lastFailure = undefined;
+    return ok(candidate);
+  }
+
+  commitFrame(candidate: SsrHistoryCandidate): Result<void, SsrHistoryError> {
+    if (this.activeCandidate !== candidate) {
+      return err(
+        failure(
+          'ssr-history-not-active',
+          'commit the candidate returned by beginFrame',
+          'keep one candidate from beginFrame until the shared queue submit succeeds',
+        ),
+      );
+    }
+    this.readIndex = candidate.writeSlot;
+    this.valid = true;
+    this.activeCandidate = undefined;
+    this.state = 'stable';
+    this.resetReason = undefined;
+    this.lastFailure = undefined;
+    return ok(undefined);
+  }
+
+  abortFrame(candidate: SsrHistoryCandidate, stage: SsrHistoryFailureStage): void {
+    if (this.activeCandidate !== candidate) return;
+    this.activeCandidate = undefined;
+    this.state = 'aborted';
+    this.lastFailure = stage;
+  }
+
+  reset(reason: SsrHistoryResetReason): void {
+    this.activeCandidate = undefined;
+    this.valid = false;
+    this.readIndex = 0;
+    this.resetReason = reason;
+    this.lastFailure = undefined;
+    this.resetCount += 1;
+    if (this.activeResources !== undefined) this.state = 'reset';
+  }
+
+  resize(width: number, height: number): Result<void, RhiError> {
+    const next = createResources(
+      this.device,
+      this.scope,
+      positiveDimension(width, 'width'),
+      positiveDimension(height, 'height'),
+    );
+    if (!next.ok) return next;
+    if (this.activeResources !== undefined) this.retiringResources.add(this.activeResources);
+    this.activeResources = next.value;
+    this.activeCandidate = undefined;
+    this.valid = false;
+    this.readIndex = 0;
+    this.resetReason = 'resize';
+    this.lastFailure = undefined;
+    this.resetCount += 1;
+    this.state = 'reset';
+    return ok(undefined);
+  }
+
+  /** Retire pending allocations after the queue's already-submitted work. */
+  retireAfterFence(queue: RhiQueue, onFailure: (cause: unknown) => void): void {
+    if (this.retirementFencePending) return;
+    if (this.retiringResources.size === 0 && this.activeResources !== undefined) {
+      this.retiringResources.add(this.activeResources);
+      this.activeCandidate = undefined;
+      this.valid = false;
+      this.state = 'retiring';
+    }
+    const pending = [...this.retiringResources];
+    for (const resources of pending) resources.childScope.beginRetire();
+    if (pending.length === 0) return;
+    this.retirementFencePending = true;
+    const finish = (): void => {
+      this.retirementFencePending = false;
+      for (const resources of pending) {
+        this.retiringResources.delete(resources);
+        resources.childScope.retire();
+        if (this.activeResources === resources) this.activeResources = undefined;
+      }
+      if (this.activeResources === undefined && this.retiringResources.size === 0) {
+        this.state = 'retired';
+      }
+      // A second resize may have added the then-active resources while this
+      // fence was pending. Chain another fence so every retired generation is
+      // eventually drained without making the record stage own a retirement
+      // ledger.
+      if (this.retiringResources.size > 0) this.retireAfterFence(queue, onFailure);
+    };
+    void queue.onSubmittedWorkDone().then(finish, (cause) => {
+      onFailure(cause);
+      finish();
+    });
+  }
+
+  retire(): void {
+    this.retirementFencePending = false;
+    this.activeCandidate = undefined;
+    if (this.activeResources !== undefined) {
+      this.activeResources.childScope.retire();
+      this.activeResources = undefined;
+    }
+    for (const resources of this.retiringResources) resources.childScope.retire();
+    this.retiringResources.clear();
+    this.valid = false;
+    this.state = 'retired';
+  }
+
+  dispose(): void {
+    if (this.state === 'disposed') return;
+    this.retire();
+    this.state = 'disposed';
+  }
+
+  inspect(): SsrHistoryInspection {
+    const active = this.activeResources;
+    return Object.freeze({
+      state: this.state,
+      width: active?.width ?? 0,
+      height: active?.height ?? 0,
+      halfWidth: active?.halfWidth ?? 0,
+      halfHeight: active?.halfHeight ?? 0,
+      format: SSR_HISTORY_FORMAT,
+      historyCount: active === undefined ? 0 : 2,
+      historyValid: this.valid,
+      readSlot: active === undefined ? null : this.valid ? this.readIndex : null,
+      writeSlot: active === undefined ? 0 : this.valid ? (this.readIndex === 0 ? 1 : 0) : 0,
+      activeBytes: active?.bytes ?? 0,
+      candidateBytes: 0,
+      retiringBytes: [...this.retiringResources]
+        .filter((entry) => entry !== active)
+        .reduce((sum, entry) => sum + entry.bytes, 0),
+      resetCount: this.resetCount,
+      resetReason: this.resetReason,
+      lastFailure: this.lastFailure,
+    });
+  }
+}
+
+export function createSsrHistoryOwner(input: {
+  readonly device: RhiDevice;
+  readonly scope: DeviceScope;
+  readonly width: number;
+  readonly height: number;
+}): Result<SsrHistoryOwner, RhiError> {
+  return SsrHistoryOwner.create(input);
+}

package/src/ssr/hiz.ts

@@ -0,0 +1,124 @@
+import type { GraphExtent } from '@forgeax/engine-render-graph';
+
+/** The one depth format owned by the SSR spatial producer. */
+export const SSR_HIZ_FORMAT = 'r32float' as const;
+
+export interface SsrHiZExtent {
+  readonly width: number;
+  readonly height: number;
+}
+
+export interface SsrHiZLevelPlan extends SsrHiZExtent {
+  readonly level: number;
+}
+
+export interface SsrHiZPlan {
+  readonly extent: SsrHiZExtent;
+  readonly format: typeof SSR_HIZ_FORMAT;
+  readonly mipLevelCount: number;
+  readonly levels: readonly SsrHiZLevelPlan[];
+  readonly graphSize: GraphExtent;
+}
+
+function validExtent(extent: SsrHiZExtent): boolean {
+  return (
+    Number.isInteger(extent.width) &&
+    Number.isInteger(extent.height) &&
+    extent.width > 0 &&
+    extent.height > 0
+  );
+}
+
+function requireExtent(extent: SsrHiZExtent): void {
+  if (!validExtent(extent)) {
+    throw new RangeError('SSR Hi-Z extent must contain positive integer width and height');
+  }
+}
+
+/** Derive the physical WebGPU floor-halved mip extent, clamped to one texel. */
+export function nextSsrHiZMipExtent(extent: SsrHiZExtent): SsrHiZExtent {
+  requireExtent(extent);
+  return {
+    width: Math.max(1, Math.floor(extent.width / 2)),
+    height: Math.max(1, Math.floor(extent.height / 2)),
+  };
+}
+
+/** Derive the complete current-view Hi-Z descriptor without allocating a resource. */
+export function buildSsrHiZPlan(extent: SsrHiZExtent): SsrHiZPlan {
+  requireExtent(extent);
+  const levels: SsrHiZLevelPlan[] = [];
+  let current = { width: extent.width, height: extent.height };
+  let level = 0;
+  while (true) {
+    levels.push({ level, ...current });
+    if (current.width === 1 && current.height === 1) break;
+    current = nextSsrHiZMipExtent(current);
+    level += 1;
+  }
+  return Object.freeze({
+    extent: Object.freeze({ width: extent.width, height: extent.height }),
+    format: SSR_HIZ_FORMAT,
+    mipLevelCount: levels.length,
+    levels: Object.freeze(levels.map((entry) => Object.freeze(entry))),
+    graphSize: Object.freeze({ width: extent.width, height: extent.height }),
+  });
+}
+
+/** Map an invalid or empty depth sample to the Hi-Z empty-pixel sentinel. */
+export function normalizeSsrHiZDepth(value: number): number {
+  return Number.isFinite(value) && value > 0 ? value : Number.POSITIVE_INFINITY;
+}
+
+function ssrHiZCoverageStart(index: number, sourceSize: number, destinationSize: number): number {
+  return Math.floor((index * sourceSize) / destinationSize);
+}
+
+function ssrHiZCoverageEnd(index: number, sourceSize: number, destinationSize: number): number {
+  return Math.min(
+    sourceSize,
+    Math.floor(((index + 1) * sourceSize + destinationSize - 1) / destinationSize),
+  );
+}
+
+/**
+ * Reduce one mip level with the physical mip's complete coverage footprint.
+ *
+ * WebGPU mip dimensions are floor-halved, so a 3-wide source has a 1-wide
+ * destination. The destination cells therefore use integer normalized
+ * boundaries with a conservative ceil on the end boundary instead of
+ * assuming a fixed 2x2 footprint. Adjacent cells overlap at odd boundaries;
+ * this keeps boundary and trailing source columns/rows in the hierarchy.
+ * The empty sentinel is infinity and therefore never wins over a finite
+ * positive view-space depth. Invalid input samples are treated as empty so a
+ * malformed depth cannot introduce NaN into the hierarchy.
+ */
+export function reduceSsrHiZLevel(
+  source: ArrayLike<number>,
+  sourceExtent: SsrHiZExtent,
+): Float32Array {
+  requireExtent(sourceExtent);
+  const expectedLength = sourceExtent.width * sourceExtent.height;
+  if (source.length !== expectedLength) {
+    throw new RangeError(`SSR Hi-Z source length must equal ${expectedLength}`);
+  }
+  const destination = nextSsrHiZMipExtent(sourceExtent);
+  const reduced = new Float32Array(destination.width * destination.height);
+  for (let y = 0; y < destination.height; y += 1) {
+    for (let x = 0; x < destination.width; x += 1) {
+      let minimum = Number.POSITIVE_INFINITY;
+      const startY = ssrHiZCoverageStart(y, sourceExtent.height, destination.height);
+      const endY = ssrHiZCoverageEnd(y, sourceExtent.height, destination.height);
+      const startX = ssrHiZCoverageStart(x, sourceExtent.width, destination.width);
+      const endX = ssrHiZCoverageEnd(x, sourceExtent.width, destination.width);
+      for (let sampleY = startY; sampleY < endY; sampleY += 1) {
+        for (let sampleX = startX; sampleX < endX; sampleX += 1) {
+          const sample = normalizeSsrHiZDepth(source[sampleY * sourceExtent.width + sampleX] ?? 0);
+          minimum = Math.min(minimum, sample);
+        }
+      }
+      reduced[y * destination.width + x] = minimum;
+    }
+  }
+  return reduced;
+}

package/src/ssr/inspection.ts

@@ -0,0 +1,124 @@
+// @forgeax/engine-render - bounded SSR spatial inspection projection.
+
+import type { ScreenSpaceReflectionData } from '../components/screen-space-reflection';
+import type { ReflectionFallbackSource } from '../inspection-types';
+import type { SsrSpatialAdmission, SsrSpatialLane, SsrSpatialWork } from './admission';
+import type { SsrConfigInvalidError, SsrUnavailableError } from './errors';
+import type { SsrHistoryState } from './history';
+
+export type SsrSpatialInspectionFailure = SsrConfigInvalidError | SsrUnavailableError;
+
+export interface SsrSpatialHistoryInspection {
+  readonly state: 'not-owned' | SsrHistoryState;
+  readonly bytes: number;
+  readonly resetCount: number;
+}
+
+export interface SsrSpatialInspectionProjection {
+  readonly status?: SsrSpatialInspection['status'];
+  readonly coverage?: Partial<SsrSpatialInspection['coverage']>;
+  readonly history?: SsrSpatialHistoryInspection;
+  readonly passRoster?: readonly string[];
+  readonly fallbackSource?: ReflectionFallbackSource;
+  readonly failure?: SsrSpatialInspectionFailure;
+}
+
+/** Keep the public projection bounded even if a graph owner supplies a bad list. */
+export const SSR_INSPECTION_MAX_PASSES = 64 as const;
+
+function nonNegativeSafeInteger(name: string, value: number): number {
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new Error(`${name} must be a non-negative safe integer`);
+  }
+  return value;
+}
+
+function copyHistory(history: SsrSpatialHistoryInspection): SsrSpatialHistoryInspection {
+  nonNegativeSafeInteger('SSR inspection history.bytes', history.bytes);
+  nonNegativeSafeInteger('SSR inspection history.resetCount', history.resetCount);
+  return Object.freeze({
+    state: history.state,
+    bytes: history.bytes,
+    resetCount: history.resetCount,
+  });
+}
+
+function copyCoverage(
+  coverage: Partial<SsrSpatialInspection['coverage']> | undefined,
+): SsrSpatialInspection['coverage'] {
+  const result = {
+    hitCount: coverage?.hitCount ?? null,
+    fallbackCount: coverage?.fallbackCount ?? null,
+    excludedCount: coverage?.excludedCount ?? null,
+  };
+  for (const [key, value] of Object.entries(result)) {
+    if (value !== null) nonNegativeSafeInteger(`SSR inspection coverage.${key}`, value);
+  }
+  return Object.freeze(result);
+}
+
+function copyPassRoster(passRoster: readonly string[] | undefined): readonly string[] {
+  return Object.freeze(
+    [...(passRoster ?? [])].slice(0, SSR_INSPECTION_MAX_PASSES).map((name, index) => {
+      if (typeof name !== 'string' || name.length === 0) {
+        throw new Error(`SSR inspection passRoster[${index}] must be a non-empty string`);
+      }
+      return name;
+    }),
+  );
+}
+
+export interface SsrSpatialInspection {
+  readonly status: 'not-requested' | 'requested' | 'admitted' | 'fallback-only' | 'structural-only';
+  readonly lane: SsrSpatialLane;
+  readonly config: ScreenSpaceReflectionData | undefined;
+  readonly viewRange: number;
+  readonly coverage: {
+    /** Null means no GPU coverage measurement is available for this frame. */
+    readonly hitCount: number | null;
+    readonly fallbackCount: number | null;
+    readonly excludedCount: number | null;
+  };
+  readonly history: SsrSpatialHistoryInspection;
+  readonly work: SsrSpatialWork;
+  readonly passRoster: readonly string[];
+  readonly fallbackSource: ReflectionFallbackSource | undefined;
+  readonly failure: SsrSpatialInspectionFailure | undefined;
+}
+
+/** Project only detached, bounded facts from the spatial admission result. */
+export function projectSsrSpatialInspection(
+  admission: SsrSpatialAdmission,
+  projection: SsrSpatialInspectionProjection = {},
+): SsrSpatialInspection {
+  const config = admission.config;
+  return Object.freeze({
+    status: projection.status ?? admission.status,
+    lane: admission.lane,
+    config:
+      config === undefined
+        ? undefined
+        : Object.freeze({
+            maxDistance: config.maxDistance,
+            thickness: config.thickness,
+            maxRoughness: config.maxRoughness,
+          }),
+    viewRange: admission.viewRange,
+    coverage: copyCoverage(projection.coverage),
+    history: copyHistory(
+      projection.history ?? {
+        state: 'not-owned' as const,
+        bytes: 0,
+        resetCount: 0,
+      },
+    ),
+    work: Object.freeze({ ...admission.work }),
+    passRoster: copyPassRoster(projection.passRoster),
+    fallbackSource: projection.fallbackSource,
+    failure: projection.failure ?? admission.failure,
+  });
+}
+
+export function serializeSsrSpatialInspection(inspection: SsrSpatialInspection): string {
+  return JSON.stringify(inspection);
+}