@forgeax/engine-render 0.1.27 → 0.1.29

package/src/instances.ts

@@ -1,25 +1,47 @@
-import type { World } from '@forgeax/engine-ecs';
 import type { RhiErrorCode } from '@forgeax/engine-rhi';
+import { err, ok, type Result } from '@forgeax/engine-types';
 
 const MATRIX_STRIDE = 16;
+const INITIAL_CAPACITY = 1;
 
 export type InstanceCollectionId = number & {
   readonly __forgeaxInstanceCollectionId: unique symbol;
 };
 
-export interface InstanceCollectionInfo {
+export interface InstanceCollectionData {
   readonly collectionId: InstanceCollectionId;
+}
+
+export interface InstanceCollectionInfo extends InstanceCollectionData {
   readonly count: number;
+  readonly capacity: number;
   readonly revision: number;
 }
 
-export interface InstanceUploadRange {
+export interface InstanceDirtyRange {
   start: number;
   end: number;
 }
 
+/**
+ * Choose the ranges that initialize one resident GPU allocation.
+ *
+ * A cache miss is not a delta upload: recovery, reassociation, and any other
+ * new resident has uninitialized device memory. The canonical collection must
+ * therefore be copied in full even when the current authoring revision only
+ * records a partial dirty range. Existing residents keep the narrower ranges.
+ */
+export function instanceUploadRangesForResident(
+  activeIsNew: boolean,
+  dirtyRanges: readonly InstanceDirtyRange[],
+  fullRange: InstanceDirtyRange,
+): readonly InstanceDirtyRange[] {
+  return activeIsNew ? [fullRange] : dirtyRanges;
+}
+
 export interface InstanceCollectionSnapshot extends InstanceCollectionInfo {
   readonly transforms: Float32Array;
+  readonly dirtyRanges: readonly InstanceDirtyRange[];
 }
 
 /** The renderer-owned submission lane selected for one collection. */
@@ -47,11 +69,29 @@ export interface InstanceCollectionFailureFacts {
   readonly recovery: string;
 }
 
+function instanceCollectionFailureFacts(
+  cause: string,
+  recovery: string,
+  requestedBytes = 0,
+  supportedBytes: number | undefined = undefined,
+  backend: InstanceBackendKind = 'unknown',
+): InstanceCollectionFailureFacts {
+  return {
+    requestedBytes,
+    supportedBytes,
+    backend,
+    owner: 'renderer.instances',
+    cause,
+    recovery,
+  };
+}
+
 /** Detached, bounded collection evidence exposed by Renderer.inspect(). */
 export interface InstanceCollectionInspection extends InstanceCollectionInfo {
   readonly residentGeneration: number | undefined;
   readonly lane: InstanceSubmissionLane;
-  readonly uploadRanges: readonly InstanceUploadRange[];
+  readonly dirtyRanges: readonly InstanceDirtyRange[];
+  readonly uploadRanges: readonly InstanceDirtyRange[];
   readonly uploadedBytes: number;
   readonly requestedBytes: number;
   readonly supportedBytes: number | undefined;
@@ -67,11 +107,85 @@ export interface InstanceCollectionInspection extends InstanceCollectionInfo {
     | undefined;
 }
 
-export interface InstanceResidency {
+export interface InstanceCollectionCreateInput {
+  readonly transforms: Float32Array;
+}
+
+export interface InstanceCollectionUpdateInput {
+  /** Matrix ordinal of the first matrix to replace. */
+  readonly start: number;
+  readonly transforms: Float32Array;
+}
+
+export interface InstanceCollectionInvalidDetail {
+  readonly collectionId?: number;
+  readonly operation: 'create' | 'replace' | 'update' | 'inspect' | 'release';
+  readonly expected: string;
+  readonly actual: number | string;
+}
+
+export type InstanceCollectionErrorCode =
+  | 'instance-collection-invalid'
+  | 'instance-collection-not-found'
+  | 'instance-collection-released';
+
+export class InstanceCollectionError extends Error {
+  readonly code: InstanceCollectionErrorCode;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: InstanceCollectionInvalidDetail | undefined;
+  readonly owner = 'renderer.instances' as const;
+  readonly recovery: string;
+  readonly facts: InstanceCollectionFailureFacts;
+
+  constructor(
+    code: InstanceCollectionErrorCode,
+    expected: string,
+    hint: string,
+    detail?: InstanceCollectionInvalidDetail,
+    facts?: InstanceCollectionFailureFacts,
+  ) {
+    super(`${code}: ${expected}`);
+    this.name = 'InstanceCollectionError';
+    this.code = code;
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = detail;
+    this.facts =
+      facts ??
+      instanceCollectionFailureFacts(
+        code,
+        hint,
+        detail?.operation === 'create' || detail?.operation === 'replace'
+          ? typeof detail.actual === 'number' && Number.isFinite(detail.actual)
+            ? detail.actual * Float32Array.BYTES_PER_ELEMENT
+            : 0
+          : 0,
+      );
+    this.recovery = this.facts.recovery;
+  }
+}
+
+export type InstanceCollectionResult<T> = Result<T, InstanceCollectionError>;
+
+interface CollectionRecord {
+  readonly id: InstanceCollectionId;
+  transforms: Float32Array;
+  count: number;
+  capacity: number;
+  revision: number;
+  dirtyRanges: InstanceDirtyRange[];
+  /** Last revision detached for extraction; repeated reads of that revision
+   * retain the same ranges for multiple entities sharing one collection. */
+  lastSnapshotRevision: number;
+  released: boolean;
+}
+
+interface CollectionResidency {
   readonly frameNumber: number;
   readonly residentGeneration: number | undefined;
   readonly lane: InstanceSubmissionLane;
-  readonly uploadRanges: readonly InstanceUploadRange[];
+  readonly uploadRanges: readonly InstanceDirtyRange[];
   readonly uploadedBytes: number;
   readonly requestedBytes: number;
   readonly supportedBytes: number | undefined;
@@ -79,7 +193,73 @@ export interface InstanceResidency {
   readonly error: InstanceCollectionInspection['error'];
 }
 
-function appendRange(ranges: InstanceUploadRange[], start: number, end: number): void {
+function nextCapacity(required: number): number {
+  let capacity = INITIAL_CAPACITY;
+  while (capacity < required) capacity *= 2;
+  return capacity;
+}
+
+function invalid(
+  operation: InstanceCollectionInvalidDetail['operation'],
+  expected: string,
+  actual: number | string,
+  collectionId?: number,
+  context?: {
+    readonly requestedBytes?: number;
+    readonly supportedBytes?: number;
+    readonly cause?: string;
+    readonly recovery?: string;
+  },
+): InstanceCollectionError {
+  const hint = 'repair the collection payload and retry the same authoring operation';
+  return new InstanceCollectionError(
+    'instance-collection-invalid',
+    expected,
+    hint,
+    { operation, expected, actual, ...(collectionId === undefined ? {} : { collectionId }) },
+    instanceCollectionFailureFacts(
+      context?.cause ?? `invalid-${operation}-authoring`,
+      context?.recovery ?? hint,
+      context?.requestedBytes ?? 0,
+      context?.supportedBytes,
+    ),
+  );
+}
+
+function validateTransforms(
+  operation: InstanceCollectionInvalidDetail['operation'],
+  transforms: Float32Array,
+  collectionId?: number,
+): InstanceCollectionError | undefined {
+  if (!(transforms instanceof Float32Array)) {
+    return invalid(operation, 'transforms is a Float32Array', typeof transforms, collectionId, {
+      cause: 'invalid-transform-type',
+    });
+  }
+  if (transforms.length % MATRIX_STRIDE !== 0) {
+    return invalid(
+      operation,
+      `transforms.length is a multiple of ${MATRIX_STRIDE}`,
+      transforms.length,
+      collectionId,
+      {
+        requestedBytes: transforms.byteLength,
+        cause: 'invalid-transform-stride',
+      },
+    );
+  }
+  for (const value of transforms) {
+    if (!Number.isFinite(value)) {
+      return invalid(operation, 'every transform value is finite', value, collectionId, {
+        requestedBytes: transforms.byteLength,
+        cause: 'invalid-transform-value',
+      });
+    }
+  }
+  return undefined;
+}
+
+function appendRange(ranges: InstanceDirtyRange[], start: number, end: number): void {
   if (start >= end) return;
   // Updates are allowed to arrive in any order. Insert at the first range
   // whose end reaches the new interval, then consume every range that starts
@@ -101,112 +281,312 @@ function appendRange(ranges: InstanceUploadRange[], start: number, end: number):
   ranges.splice(index, 0, { start, end });
 }
 
-interface CollectionRecord extends InstanceCollectionInfo {
-  readonly world: World;
-  readonly entity: number;
-  readonly transforms: Float32Array;
+function appendDirtyRange(record: CollectionRecord, start: number, end: number): void {
+  appendRange(record.dirtyRanges, start, end);
+}
+
+function missing(
+  operation: InstanceCollectionInvalidDetail['operation'],
+  id: InstanceCollectionId,
+): InstanceCollectionError {
+  return new InstanceCollectionError(
+    'instance-collection-not-found',
+    `instance collection ${Number(id)} is live and owned by this Renderer`,
+    'create a collection with renderer.instances.create or retain the original collection id',
+    { operation, expected: 'a live instance collection id', actual: Number(id), collectionId: id },
+  );
 }
 
-/** Rebuildable per-renderer projection. World remains the authoring authority. */
-export class InstanceProjectionStore {
+/**
+ * Renderer-owned canonical storage for explicit instance transforms.
+ *
+ * ECS carries only `Instances.collectionId`; this owner keeps the copied
+ * matrices, revision and dirty intervals independent of archetype capacity.
+ * Snapshots are detached before they cross into extraction, so callers cannot
+ * mutate the canonical source behind the revision protocol.
+ */
+export class InstanceCollectionStore {
   private nextId = 1;
-  private identities = new WeakMap<World, Map<number, InstanceCollectionId>>();
+  private epochValue = 0;
+  private disposed = false;
   private readonly records = new Map<InstanceCollectionId, CollectionRecord>();
+  private readonly residency = new Map<InstanceCollectionId, CollectionResidency>();
 
-  project(world: World, entity: number, transforms: ArrayLike<number>): InstanceCollectionSnapshot {
-    let entities = this.identities.get(world);
-    if (entities === undefined) {
-      entities = new Map();
-      this.identities.set(world, entities);
-    }
-    let collectionId = entities.get(entity);
-    if (collectionId === undefined) {
-      collectionId = this.nextId++ as InstanceCollectionId;
-      entities.set(entity, collectionId);
-    }
-    const previous = this.records.get(collectionId);
-    const unchanged =
-      previous !== undefined &&
-      previous.transforms.length === transforms.length &&
-      previous.transforms.every((value, index) => Object.is(value, transforms[index]));
-    const record: CollectionRecord = unchanged
-      ? previous
-      : {
-          collectionId,
-          world,
-          entity,
-          transforms: new Float32Array(transforms),
-          count: transforms.length / MATRIX_STRIDE,
-          revision: (previous?.revision ?? 0) + 1,
-        };
-    this.records.set(collectionId, record);
-    // Every consumer gets a complete snapshot. Reading never acknowledges an
-    // upload; each GPU resident records its own successfully uploaded revision.
-    return { ...this.info(record), transforms: record.transforms };
+  get epoch(): number {
+    return this.epochValue;
   }
 
-  retain(ids: ReadonlySet<InstanceCollectionId>): void {
-    for (const [id, record] of this.records) {
-      if (ids.has(id)) continue;
-      this.identities.get(record.world)?.delete(record.entity);
-      this.records.delete(id);
+  create(input: InstanceCollectionCreateInput): InstanceCollectionResult<InstanceCollectionInfo> {
+    if (this.disposed) {
+      return err(
+        new InstanceCollectionError(
+          'instance-collection-released',
+          'the Renderer-owned instance collection store is live',
+          'create a new Renderer before authoring instance collections',
+        ),
+      );
     }
+    const invalidPayload = validateTransforms('create', input.transforms);
+    if (invalidPayload !== undefined) return err(invalidPayload);
+    const id = this.nextId++ as InstanceCollectionId;
+    const count = input.transforms.length / MATRIX_STRIDE;
+    const record: CollectionRecord = {
+      id,
+      transforms: new Float32Array(input.transforms),
+      count,
+      capacity: nextCapacity(Math.max(INITIAL_CAPACITY, count)),
+      revision: 1,
+      dirtyRanges: count === 0 ? [] : [{ start: 0, end: count }],
+      lastSnapshotRevision: 0,
+      released: false,
+    };
+    this.records.set(id, record);
+    this.epochValue += 1;
+    return ok(this.info(record));
   }
 
-  /** Release one producer-owned collection when its render identity is removed. */
-  release(world: World, entity: number): void {
-    const entities = this.identities.get(world);
-    const collectionId = entities?.get(entity);
-    if (collectionId === undefined) return;
-    entities?.delete(entity);
-    this.records.delete(collectionId);
+  replace(
+    id: InstanceCollectionId,
+    transforms: Float32Array,
+  ): InstanceCollectionResult<InstanceCollectionInfo> {
+    const record = this.live('replace', id);
+    if (!record.ok) return record;
+    const invalidPayload = validateTransforms('replace', transforms, id);
+    if (invalidPayload !== undefined) return err(invalidPayload);
+    const count = transforms.length / MATRIX_STRIDE;
+    record.value.transforms = new Float32Array(transforms);
+    record.value.count = count;
+    record.value.capacity = Math.max(record.value.capacity, nextCapacity(Math.max(1, count)));
+    record.value.revision += 1;
+    record.value.dirtyRanges = count === 0 ? [] : [{ start: 0, end: count }];
+    record.value.lastSnapshotRevision = record.value.revision - 1;
+    this.epochValue += 1;
+    return ok(this.info(record.value));
   }
 
-  dispose(): void {
-    this.records.clear();
-    this.identities = new WeakMap();
+  update(
+    id: InstanceCollectionId,
+    input: InstanceCollectionUpdateInput,
+  ): InstanceCollectionResult<InstanceCollectionInfo> {
+    const record = this.live('update', id);
+    if (!record.ok) return record;
+    const invalidPayload = validateTransforms('update', input.transforms, id);
+    if (invalidPayload !== undefined) return err(invalidPayload);
+    if (!Number.isInteger(input.start) || input.start < 0) {
+      return err(
+        invalid('update', 'start is a non-negative matrix ordinal', input.start, id, {
+          requestedBytes: input.transforms.byteLength,
+          supportedBytes: record.value.capacity * MATRIX_STRIDE * Float32Array.BYTES_PER_ELEMENT,
+          cause: 'invalid-update-range-start',
+        }),
+      );
+    }
+    const span = input.transforms.length / MATRIX_STRIDE;
+    const attemptedEnd = input.start + span;
+    if (attemptedEnd > record.value.count) {
+      return err(
+        invalid(
+          'update',
+          `start + matrix count is <= collection count (${record.value.count})`,
+          attemptedEnd,
+          id,
+          {
+            requestedBytes: attemptedEnd * MATRIX_STRIDE * Float32Array.BYTES_PER_ELEMENT,
+            supportedBytes: record.value.count * MATRIX_STRIDE * Float32Array.BYTES_PER_ELEMENT,
+            cause: 'invalid-update-range-end',
+          },
+        ),
+      );
+    }
+    if (record.value.lastSnapshotRevision === record.value.revision) {
+      record.value.dirtyRanges = [];
+    }
+    record.value.transforms.set(input.transforms, input.start * MATRIX_STRIDE);
+    record.value.revision += 1;
+    appendDirtyRange(record.value, input.start, input.start + span);
+    this.epochValue += 1;
+    return ok(this.info(record.value));
+  }
+
+  inspect(id: InstanceCollectionId): InstanceCollectionResult<InstanceCollectionInfo> {
+    const record = this.live('inspect', id);
+    return record.ok ? ok(this.info(record.value)) : record;
   }
 
   /**
    * Return detached residency facts for every live collection.
    *
-   * @internal Joins CPU projection identity with the active device residency;
+   * @internal Record-stage evidence is reported through the two methods below;
    * callers only receive immutable PODs and never GPU handles.
    */
-  _inspections(
-    residency: ReadonlyMap<InstanceCollectionId, InstanceResidency> | undefined,
-    frameNumber: number,
-  ): readonly InstanceCollectionInspection[] {
+  _inspections(): readonly InstanceCollectionInspection[] {
     return Object.freeze(
-      [...this.records.values()].map((record) =>
-        this.projectInspection(record, residency?.get(record.collectionId), frameNumber),
-      ),
+      [...this.records.values()].map((record) => this.projectInspection(record)),
     );
   }
 
+  /** @internal Renderer record owner reports the accepted collection lane. */
+  _reportResidency(input: {
+    readonly collectionId: InstanceCollectionId;
+    readonly frameNumber: number;
+    readonly residentGeneration: number;
+    readonly lane: Exclude<InstanceSubmissionLane, 'unresident' | 'unavailable'>;
+    readonly uploadRanges: readonly InstanceDirtyRange[];
+    readonly uploadedBytes: number;
+    readonly requestedBytes: number;
+    readonly supportedBytes: number | undefined;
+    readonly backend: InstanceBackendKind;
+  }): void {
+    if (!this.records.has(input.collectionId)) return;
+    const previous = this.residency.get(input.collectionId);
+    const sameFrame =
+      previous !== undefined &&
+      previous.frameNumber === input.frameNumber &&
+      previous.error === undefined;
+    const uploadRanges = sameFrame
+      ? [...previous.uploadRanges].reduce(
+          (ranges, range) => {
+            appendRange(ranges, range.start, range.end);
+            return ranges;
+          },
+          input.uploadRanges.map((range) => ({ ...range })),
+        )
+      : input.uploadRanges.map((range) => ({ ...range }));
+    this.residency.set(input.collectionId, {
+      frameNumber: input.frameNumber,
+      residentGeneration: input.residentGeneration,
+      lane: input.lane,
+      uploadRanges,
+      uploadedBytes: sameFrame ? previous.uploadedBytes + input.uploadedBytes : input.uploadedBytes,
+      requestedBytes: input.requestedBytes,
+      supportedBytes: input.supportedBytes,
+      backend: input.backend,
+      error: undefined,
+    });
+  }
+
+  /** @internal Renderer record owner reports a typed admission failure. */
+  _reportFailure(input: {
+    readonly collectionId: InstanceCollectionId;
+    readonly code: InstanceCollectionFailureCode;
+    readonly expected: string;
+    readonly hint: string;
+    readonly facts: InstanceCollectionFailureFacts;
+  }): void {
+    if (!this.records.has(input.collectionId)) return;
+    this.residency.set(input.collectionId, {
+      frameNumber: -1,
+      residentGeneration: undefined,
+      lane: 'unavailable',
+      uploadRanges: [],
+      uploadedBytes: 0,
+      requestedBytes: input.facts.requestedBytes,
+      supportedBytes: input.facts.supportedBytes,
+      backend: input.facts.backend,
+      error: {
+        code: input.code,
+        expected: input.expected,
+        hint: input.hint,
+        detail: { ...input.facts },
+      },
+    });
+  }
+
+  /** @internal A lost device invalidates every renderer-owned GPU resident. */
+  _resetResidency(): void {
+    this.residency.clear();
+  }
+
+  snapshot(id: InstanceCollectionId): InstanceCollectionResult<InstanceCollectionSnapshot> {
+    const record = this.live('inspect', id);
+    if (!record.ok) return record;
+    const value = record.value;
+    value.lastSnapshotRevision = value.revision;
+    const result = {
+      ...this.info(value),
+      transforms: new Float32Array(value.transforms),
+      dirtyRanges: value.dirtyRanges.map((range) => ({ ...range })),
+    };
+    // Keep the current ranges stable for repeated reads by entities sharing
+    // this collection. The next authoring mutation starts a fresh interval
+    // set once this revision has been observed.
+    return ok(result);
+  }
+
+  release(id: InstanceCollectionId): InstanceCollectionResult<void> {
+    const record = this.records.get(id);
+    if (record === undefined) return err(missing('release', id));
+    if (record.released) {
+      return err(
+        new InstanceCollectionError(
+          'instance-collection-released',
+          `instance collection ${Number(id)} has not already been released`,
+          'do not reuse a released collection id; create a new collection',
+          {
+            operation: 'release',
+            expected: 'a live instance collection id',
+            actual: Number(id),
+            collectionId: id,
+          },
+        ),
+      );
+    }
+    record.released = true;
+    this.records.delete(id);
+    this.residency.delete(id);
+    this.epochValue += 1;
+    return ok(undefined);
+  }
+
+  /** Drop all canonical matrices during Renderer disposal. */
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    for (const record of this.records.values()) record.released = true;
+    this.records.clear();
+    this.residency.clear();
+    this.epochValue += 1;
+  }
+
+  private live(
+    operation: InstanceCollectionInvalidDetail['operation'],
+    id: InstanceCollectionId,
+  ): InstanceCollectionResult<CollectionRecord> {
+    if (!Number.isInteger(id) || id <= 0) {
+      return err(invalid(operation, 'collectionId is a positive integer', id, id));
+    }
+    if (this.disposed) {
+      return err(
+        new InstanceCollectionError(
+          'instance-collection-released',
+          'the Renderer-owned instance collection store is live',
+          'create a new Renderer before using instance collections',
+          { operation, expected: 'a live collection store', actual: 'disposed', collectionId: id },
+        ),
+      );
+    }
+    const record = this.records.get(id);
+    return record === undefined ? err(missing(operation, id)) : ok(record);
+  }
+
   private info(record: CollectionRecord): InstanceCollectionInfo {
     return Object.freeze({
-      collectionId: record.collectionId,
+      collectionId: record.id,
       count: record.count,
+      capacity: record.capacity,
       revision: record.revision,
     });
   }
 
-  private projectInspection(
-    record: CollectionRecord,
-    residency: InstanceResidency | undefined,
-    frameNumber: number,
-  ): InstanceCollectionInspection {
+  private projectInspection(record: CollectionRecord): InstanceCollectionInspection {
+    const residency = this.residency.get(record.id);
     return Object.freeze({
       ...this.info(record),
       residentGeneration: residency?.residentGeneration,
       lane: residency?.lane ?? 'unresident',
-      uploadRanges: Object.freeze(
-        residency?.frameNumber === frameNumber
-          ? residency.uploadRanges.map((range) => ({ ...range }))
-          : [],
-      ),
-      uploadedBytes: residency?.frameNumber === frameNumber ? residency.uploadedBytes : 0,
+      dirtyRanges: Object.freeze(record.dirtyRanges.map((range) => ({ ...range }))),
+      uploadRanges: Object.freeze(residency?.uploadRanges.map((range) => ({ ...range })) ?? []),
+      uploadedBytes: residency?.uploadedBytes ?? 0,
       requestedBytes: residency?.requestedBytes ?? record.count * MATRIX_STRIDE * 4,
       supportedBytes: residency?.supportedBytes,
       backend: residency?.backend ?? 'unknown',
@@ -215,74 +595,3 @@ export class InstanceProjectionStore {
     });
   }
 }
-
-/** @internal Renderer record owner reports the accepted collection lane. */
-export function recordInstanceResidency(
-  residency: Map<InstanceCollectionId, InstanceResidency>,
-  input: {
-    readonly collectionId: InstanceCollectionId;
-    readonly frameNumber: number;
-    readonly residentGeneration: number;
-    readonly lane: Exclude<InstanceSubmissionLane, 'unresident' | 'unavailable'>;
-    readonly uploadRanges: readonly InstanceUploadRange[];
-    readonly uploadedBytes: number;
-    readonly requestedBytes: number;
-    readonly supportedBytes: number | undefined;
-    readonly backend: InstanceBackendKind;
-  },
-): void {
-  const previous = residency.get(input.collectionId);
-  const sameFrame =
-    previous !== undefined &&
-    previous.frameNumber === input.frameNumber &&
-    previous.error === undefined;
-  const uploadRanges = sameFrame
-    ? [...previous.uploadRanges].reduce(
-        (ranges, range) => {
-          appendRange(ranges, range.start, range.end);
-          return ranges;
-        },
-        input.uploadRanges.map((range) => ({ ...range })),
-      )
-    : input.uploadRanges.map((range) => ({ ...range }));
-  residency.set(input.collectionId, {
-    frameNumber: input.frameNumber,
-    residentGeneration: input.residentGeneration,
-    lane: input.lane,
-    uploadRanges,
-    uploadedBytes: sameFrame ? previous.uploadedBytes + input.uploadedBytes : input.uploadedBytes,
-    requestedBytes: input.requestedBytes,
-    supportedBytes: input.supportedBytes,
-    backend: input.backend,
-    error: undefined,
-  });
-}
-
-/** @internal Renderer record owner reports a typed admission failure. */
-export function recordInstanceFailure(
-  residency: Map<InstanceCollectionId, InstanceResidency>,
-  input: {
-    readonly collectionId: InstanceCollectionId;
-    readonly code: InstanceCollectionFailureCode;
-    readonly expected: string;
-    readonly hint: string;
-    readonly facts: InstanceCollectionFailureFacts;
-  },
-): void {
-  residency.set(input.collectionId, {
-    frameNumber: -1,
-    residentGeneration: undefined,
-    lane: 'unavailable',
-    uploadRanges: [],
-    uploadedBytes: 0,
-    requestedBytes: input.facts.requestedBytes,
-    supportedBytes: input.facts.supportedBytes,
-    backend: input.facts.backend,
-    error: {
-      code: input.code,
-      expected: input.expected,
-      hint: input.hint,
-      detail: { ...input.facts },
-    },
-  });
-}