@loaders.gl/tile-converter 4.5.3 → 5.0.0-alpha.10

package/src/v5/point-cloud-source-encoder.ts

@@ -0,0 +1,105 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {
+  PointCloudBoundingVolume,
+  PointCloudCoordinateSystem,
+  PointCloudTilesetSource,
+  TilesetSpatialReference
+} from '@loaders.gl/tiles';
+import {encodePointCloudTile} from './point-cloud.js';
+import type {EncodePointCloudTileOptions} from './point-cloud.js';
+import {traversePointCloudSource} from '@loaders.gl/tile-converter/v5/core';
+import type {
+  PointCloudSourceTile,
+  TraversePointCloudSourceOptions
+} from '@loaders.gl/tile-converter/v5/core';
+
+/** Traversal and per-tile encoding options for a point-cloud source. */
+export type EncodePointCloudSourceOptions = TraversePointCloudSourceOptions & {
+  /** Select encoder options for each source tile with content, using its header and decoded data. */
+  readonly getTileEncodingOptions?: (
+    sourceTile: PointCloudSourceTile
+  ) => EncodePointCloudTileOptions;
+};
+
+/** A PNTS resource paired with the source placement metadata needed to package its tile. */
+export type EncodedPointCloudSourceTile = {
+  /** Stable source tile identifier. */
+  readonly id: string;
+  /** Original source hierarchy and bounds. */
+  readonly header: PointCloudSourceTile['header'];
+  /** Encoded point-cloud tile content. */
+  readonly pnts: ArrayBuffer;
+  /** Number of point records encoded. */
+  readonly pointCount: number;
+  /** Coordinate system used by the returned point positions. */
+  readonly coordinateSystem: PointCloudCoordinateSystem;
+  /** Origin to add to source-relative point positions. */
+  readonly cartographicOrigin: readonly number[];
+  /** Optional placement transform supplied by the point-cloud source. */
+  readonly modelMatrix?: readonly number[];
+  /** Optional source or target CRS metadata. */
+  readonly spatialReference?: TilesetSpatialReference;
+  /** Optional output-frame tile bounds supplied by the source. */
+  readonly spatialBoundingVolume?: PointCloudBoundingVolume;
+};
+
+/**
+ * Encodes a point-cloud source as a stream of PNTS resources, one for each non-empty source tile.
+ *
+ * @param source - An I3S, COPC, or compatible point-cloud tileset source.
+ * @param options - Optional traversal depth limit, cancellation signal, and per-tile encoder options.
+ * @returns Encoded source tiles in deterministic depth-first order.
+ */
+export async function* encodePointCloudSource(
+  source: PointCloudTilesetSource,
+  options: EncodePointCloudSourceOptions = {}
+): AsyncIterableIterator<EncodedPointCloudSourceTile> {
+  for await (const sourceTile of traversePointCloudSource(source, options)) {
+    const encodingOptions = sourceTile.content
+      ? options.getTileEncodingOptions?.(sourceTile)
+      : undefined;
+    const encodedTile = encodePointCloudSourceTile(sourceTile, encodingOptions);
+    if (encodedTile) {
+      yield encodedTile;
+    }
+  }
+}
+
+/**
+ * Encodes one decoded source tile as PNTS and retains its hierarchy and placement metadata.
+ *
+ * Positions use the source coordinate system, with an optional RTC center subtracted before float32
+ * encoding and stored in the PNTS feature table. Source placement metadata is retained so callers
+ * can assemble the output tileset. This function does not transform the source CRS.
+ *
+ * @param sourceTile - Tile header and decoded Arrow point content from `traversePointCloudSource`.
+ * @param options - Optional RTC center, batch-table values, and constant color override.
+ * @returns An encoded source tile, or null when the source tile has no content.
+ */
+export function encodePointCloudSourceTile(
+  sourceTile: PointCloudSourceTile,
+  options: EncodePointCloudTileOptions = {}
+): EncodedPointCloudSourceTile | null {
+  const {header, content} = sourceTile;
+  if (!content) {
+    return null;
+  }
+
+  return {
+    id: header.id,
+    header,
+    pnts: encodePointCloudTile(content.data, {
+      ...options,
+      constantRGBA: options.constantRGBA ?? content.constantRGBA
+    }),
+    pointCount: content.pointCount,
+    coordinateSystem: content.coordinateSystem,
+    cartographicOrigin: [...content.cartographicOrigin],
+    modelMatrix: content.modelMatrix ? Array.from(content.modelMatrix) : undefined,
+    spatialReference: content.spatialReference,
+    spatialBoundingVolume: content.spatialBoundingVolume || header.spatialBoundingVolume
+  };
+}

package/src/v5/point-cloud-source.ts

@@ -0,0 +1,84 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {
+  PointCloudTileContent,
+  PointCloudTileHeader,
+  PointCloudTilesetSource
+} from '@loaders.gl/tiles';
+
+/** A source tile and its decoded point content, including null content when no payload exists. */
+export type PointCloudSourceTile = {
+  /** Header with the source tile's hierarchy, bounds, and LOD metadata. */
+  readonly header: PointCloudTileHeader;
+  /** Arrow point data and its coordinate metadata, or null for an empty tile. */
+  readonly content: PointCloudTileContent | null;
+};
+
+/** Options for camera-independent point-cloud source traversal. */
+export type TraversePointCloudSourceOptions = {
+  /** Stop descending after this source tile level. Defaults to the complete hierarchy. */
+  readonly maxDepth?: number;
+  /** Cancel traversal between source operations. */
+  readonly signal?: AbortSignal;
+};
+
+/**
+ * Reads a point-cloud source in deterministic depth-first order, independent of a render camera.
+ * Each yielded value retains its tile header and Arrow content metadata so callers can apply the
+ * source coordinate frame and placement when encoding output tiles.
+ *
+ * @param source - An I3S, COPC, or compatible point-cloud tileset source.
+ * @param options - Optional depth limit and cancellation signal.
+ * @returns One header and decoded payload for each reachable source tile.
+ */
+export async function* traversePointCloudSource(
+  source: PointCloudTilesetSource,
+  options: TraversePointCloudSourceOptions = {}
+): AsyncIterableIterator<PointCloudSourceTile> {
+  const {maxDepth = Number.POSITIVE_INFINITY, signal} = options;
+  if (maxDepth !== Number.POSITIVE_INFINITY && (!Number.isSafeInteger(maxDepth) || maxDepth < 0)) {
+    throw new RangeError('Point-cloud source maxDepth must be a non-negative integer');
+  }
+
+  throwIfAborted(signal);
+  if (!source.isReady) {
+    await source.initialize();
+  }
+  throwIfAborted(signal);
+
+  const root = await source.getRootTile();
+  const pendingTiles = [root];
+  const visitedTileIds = new Set<string>();
+
+  while (pendingTiles.length > 0) {
+    throwIfAborted(signal);
+    const header = pendingTiles.pop()!;
+    if (visitedTileIds.has(header.id)) {
+      continue;
+    }
+    visitedTileIds.add(header.id);
+
+    const content = await source.loadTileContent(header);
+    throwIfAborted(signal);
+    yield {header, content};
+    throwIfAborted(signal);
+
+    if (header.level >= maxDepth) {
+      continue;
+    }
+    const children = await source.getChildren(header);
+    throwIfAborted(signal);
+    for (let index = children.length - 1; index >= 0; index--) {
+      pendingTiles.push(children[index]);
+    }
+  }
+}
+
+/** Throws the signal reason when traversal has been cancelled. */
+function throwIfAborted(signal?: AbortSignal): void {
+  if (signal?.aborted) {
+    throw signal.reason ?? new DOMException('The operation was aborted', 'AbortError');
+  }
+}

package/src/v5/point-cloud.ts

@@ -0,0 +1,271 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {Tile3DWriter, TILE3D_TYPE} from '@loaders.gl/3d-tiles';
+import type {Mesh, MeshArrowTable, MeshAttribute} from '@loaders.gl/schema';
+import {convertTableToMesh} from '@loaders.gl/schema-utils';
+import {TileConversionError} from '@loaders.gl/tile-converter/v5/core';
+
+/** Options for encoding one Arrow or mesh point batch as a 3D Tiles point tile. */
+export interface EncodePointCloudTileOptions {
+  /** Optional origin subtracted from absolute positions and stored as the PNTS RTC_CENTER. */
+  readonly rtcCenter?: readonly [number, number, number];
+  /** Optional source-wide RGBA color stored as the PNTS CONSTANT_RGBA property. */
+  readonly constantRGBA?: readonly number[];
+  /** Optional per-point values indexed by the tile's `BATCH_ID` attribute. */
+  readonly batchTableJson?: Readonly<Record<string, readonly (string | number)[]>>;
+}
+
+/**
+ * Encodes one mesh or Mesh Arrow point batch as a PNTS resource.
+ *
+ * The input position field must be named `POSITION` and contain xyz values. `COLOR_0` or `COLOR`
+ * is written when present; `constantRGBA` supplies a fallback PNTS `CONSTANT_RGBA` feature-table
+ * property. `NORMAL` and `BATCH_ID` are also written when present. Arrow batches should be passed
+ * one at a time so callers can bound memory and apply their own tiling and output policy.
+ * Unsupported attributes, including a second color attribute, fail instead of being discarded.
+ *
+ * @param pointBatch - Point data produced by a LAS, COPC, I3S, or other point source.
+ * @param options - Optional RTC center and batch-table values.
+ * @returns A 3D Tiles PNTS resource.
+ */
+export function encodePointCloudTile(
+  pointBatch: Mesh | MeshArrowTable,
+  options: EncodePointCloudTileOptions = {}
+): ArrayBuffer {
+  const mesh = 'attributes' in pointBatch ? pointBatch : convertTableToMesh(pointBatch);
+  validatePointAttributes(mesh.attributes);
+  const positionAttribute = mesh.attributes.POSITION;
+  if (!positionAttribute || positionAttribute.size !== 3) {
+    throw new TileConversionError(
+      'POINT_CLOUD_POSITION_REQUIRED',
+      'Point cloud batches must contain a three-component POSITION attribute'
+    );
+  }
+
+  const positions = getPositionValues(positionAttribute, options.rtcCenter);
+  const pointCount = positions.length / 3;
+  if (pointCount === 0 || !Number.isInteger(pointCount)) {
+    throw new TileConversionError(
+      'POINT_CLOUD_POSITION_COUNT_INVALID',
+      'Point cloud POSITION must contain one or more xyz triples'
+    );
+  }
+
+  const colors = getColorAttribute(mesh.attributes.COLOR_0 || mesh.attributes.COLOR, pointCount);
+  const constantRGBA = colors ? null : getConstantRgba(options.constantRGBA);
+  const normals = getNormalAttribute(mesh.attributes.NORMAL, pointCount);
+  const batchIds = getBatchIds(mesh.attributes.BATCH_ID, pointCount);
+  const batchTableJson = validateBatchTable(options.batchTableJson, batchIds);
+
+  return Tile3DWriter.encodeSync(
+    {
+      type: TILE3D_TYPE.POINT_CLOUD,
+      featureTableJson:
+        options.rtcCenter || constantRGBA
+          ? {
+              ...(options.rtcCenter ? {RTC_CENTER: [...options.rtcCenter]} : {}),
+              ...(constantRGBA ? {CONSTANT_RGBA: constantRGBA} : {})
+            }
+          : undefined,
+      batchTableJson,
+      attributes: {positions, colors, normals, batchIds}
+    },
+    {}
+  );
+}
+
+/** Rejects attributes that this PNTS encoder would otherwise silently discard. */
+function validatePointAttributes(attributes: Mesh['attributes']): void {
+  const supportedAttributes = new Set([
+    'POSITION',
+    'NORMAL',
+    'BATCH_ID',
+    attributes.COLOR_0 ? 'COLOR_0' : 'COLOR'
+  ]);
+  const unsupportedAttributes = Object.keys(attributes).filter(
+    name => !supportedAttributes.has(name)
+  );
+  if (unsupportedAttributes.length > 0) {
+    throw new TileConversionError(
+      'POINT_CLOUD_ATTRIBUTE_UNSUPPORTED',
+      `PNTS encoding does not support these point attributes: ${unsupportedAttributes.join(', ')}`
+    );
+  }
+}
+
+/** Validates an optional source-wide PNTS RGBA color. */
+function getConstantRgba(
+  constantRGBA?: readonly number[]
+): [number, number, number, number] | null {
+  if (!constantRGBA) {
+    return null;
+  }
+  if (
+    constantRGBA.length !== 4 ||
+    constantRGBA.some(value => !Number.isInteger(value) || value < 0 || value > 255)
+  ) {
+    throw new TileConversionError(
+      'POINT_CLOUD_CONSTANT_RGBA_INVALID',
+      'Point cloud constantRGBA must contain four unsigned byte values'
+    );
+  }
+  return [constantRGBA[0], constantRGBA[1], constantRGBA[2], constantRGBA[3]];
+}
+
+/** Decodes positions and offsets them relative to the optional RTC center. */
+function getPositionValues(
+  attribute: MeshAttribute,
+  rtcCenter?: readonly [number, number, number]
+): Float32Array {
+  if (rtcCenter && (rtcCenter.length !== 3 || rtcCenter.some(value => !Number.isFinite(value)))) {
+    throw new TileConversionError(
+      'POINT_CLOUD_RTC_CENTER_INVALID',
+      'Point cloud RTC_CENTER must contain three finite values'
+    );
+  }
+  const values = attribute.value;
+  const result = new Float32Array(values.length);
+  const transform = attribute.transform;
+  for (let index = 0; index < values.length; index++) {
+    const component = index % 3;
+    const value = values[index];
+    const absoluteValue =
+      transform?.type === 'quantization'
+        ? transform.origin[component] + (value / (2 ** transform.bits - 1)) * transform.range
+        : value;
+    result[index] = absoluteValue - (rtcCenter?.[component] ?? 0);
+  }
+  return result;
+}
+
+/** Converts an optional mesh color attribute into the byte colors accepted by PNTS. */
+function getColorAttribute(
+  attribute: MeshAttribute | undefined,
+  pointCount: number
+): {type: number; value: Uint8Array; size: number; normalized: boolean} | null {
+  if (!attribute) {
+    return null;
+  }
+  if (attribute.size !== 3 && attribute.size !== 4) {
+    throw new TileConversionError(
+      'POINT_CLOUD_COLOR_SIZE_UNSUPPORTED',
+      'Point cloud color attributes must contain three or four components'
+    );
+  }
+  if (attribute.value.length !== pointCount * attribute.size) {
+    throw new TileConversionError(
+      'POINT_CLOUD_COLOR_COUNT_MISMATCH',
+      'Point cloud color count does not match the POSITION count'
+    );
+  }
+
+  const colors = new Uint8Array(attribute.value.length);
+  const maximum = getIntegerColorMaximum(attribute.value);
+  for (let index = 0; index < attribute.value.length; index++) {
+    const value = attribute.value[index];
+    const scaledValue = maximum ? (value / maximum) * 255 : value <= 1 ? value * 255 : value;
+    if (!Number.isFinite(scaledValue) || scaledValue < 0 || scaledValue > 255) {
+      throw new TileConversionError(
+        'POINT_CLOUD_COLOR_VALUE_INVALID',
+        'Point cloud color components must be finite values from 0 through 255'
+      );
+    }
+    colors[index] = Math.round(scaledValue);
+  }
+  return {type: 5121, value: colors, size: attribute.size, normalized: false};
+}
+
+/** Returns the maximum value represented by an integer color component array. */
+function getIntegerColorMaximum(values: ArrayLike<number>): number | null {
+  if (values instanceof Uint8Array || values instanceof Uint8ClampedArray) {
+    return 255;
+  }
+  if (values instanceof Uint16Array) {
+    return 65_535;
+  }
+  if (values instanceof Uint32Array) {
+    return 4_294_967_295;
+  }
+  return null;
+}
+
+/** Returns float normals and rejects unsupported component shapes. */
+function getNormalAttribute(
+  attribute: MeshAttribute | undefined,
+  pointCount: number
+): {type: number; value: Float32Array; size: number} | null {
+  if (!attribute) {
+    return null;
+  }
+  if (attribute.size !== 3 || attribute.value.length !== pointCount * 3) {
+    throw new TileConversionError(
+      'POINT_CLOUD_NORMAL_COUNT_MISMATCH',
+      'Point cloud normals must contain one xyz triple per position'
+    );
+  }
+  return {type: 5126, value: Float32Array.from(attribute.value), size: 3};
+}
+
+/** Validates optional stable feature IDs for the PNTS uint16 batch-ID field. */
+function getBatchIds(attribute: MeshAttribute | undefined, pointCount: number): Uint16Array | null {
+  if (!attribute) {
+    return null;
+  }
+  if (attribute.size !== 1 || attribute.value.length !== pointCount) {
+    throw new TileConversionError(
+      'POINT_CLOUD_BATCH_ID_COUNT_MISMATCH',
+      'Point cloud BATCH_ID must contain one value per position'
+    );
+  }
+  const batchIds = new Uint16Array(pointCount);
+  for (let index = 0; index < pointCount; index++) {
+    const batchId = attribute.value[index];
+    if (!Number.isInteger(batchId) || batchId < 0 || batchId > 65_535) {
+      throw new TileConversionError(
+        'POINT_CLOUD_BATCH_ID_OUT_OF_RANGE',
+        'Point cloud BATCH_ID values must be unsigned 16-bit integers'
+      );
+    }
+    batchIds[index] = batchId;
+  }
+  return batchIds;
+}
+
+/** Checks that each batch-table property is indexable by the batch IDs used by this tile. */
+function validateBatchTable(
+  batchTableJson: EncodePointCloudTileOptions['batchTableJson'],
+  batchIds: Uint16Array | null
+): Record<string, (string | number)[]> | undefined {
+  if (!batchTableJson) {
+    if (batchIds) {
+      throw new TileConversionError(
+        'POINT_CLOUD_BATCH_TABLE_REQUIRED',
+        'BATCH_ID values require matching batchTableJson properties'
+      );
+    }
+    return undefined;
+  }
+  if (!batchIds) {
+    throw new TileConversionError(
+      'POINT_CLOUD_BATCH_ID_REQUIRED',
+      'batchTableJson requires a BATCH_ID attribute'
+    );
+  }
+  let batchLength = 0;
+  for (const batchId of batchIds) {
+    batchLength = Math.max(batchLength, batchId + 1);
+  }
+  const normalizedBatchTable: Record<string, (string | number)[]> = {};
+  for (const [name, values] of Object.entries(batchTableJson)) {
+    if (values.length !== batchLength) {
+      throw new TileConversionError(
+        'POINT_CLOUD_BATCH_TABLE_LENGTH_MISMATCH',
+        `Batch table property "${name}" must contain ${batchLength} values`
+      );
+    }
+    normalizedBatchTable[name] = [...values];
+  }
+  return normalizedBatchTable;
+}

package/src/v5/resource-manifest.ts

@@ -0,0 +1,213 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {TileConversionError} from './conversion-api.js';
+import type {TileConversionReport, TileConversionSink} from './conversion-api.js';
+
+const TILE_RESOURCE_MANIFEST_VERSION = 1;
+
+/** Durable record for one successfully written, deterministic output resource. */
+export interface TileResourceManifestEntry {
+  /** Stable resource identifier supplied by the output profile. */
+  readonly resourceId: string;
+  /** Byte length of the output resource. */
+  readonly byteLength: number;
+  /** Stable caller-computed content fingerprint, such as a SHA-256 digest. */
+  readonly fingerprint: string;
+}
+
+/** Versioned progress record used to resume deterministic output packaging. */
+export interface TileResourceManifest {
+  /** Manifest format version. */
+  readonly version: 1;
+  /** True only after the destination and report have been finalized successfully. */
+  readonly complete: boolean;
+  /** Resources durably written before interruption or completion. */
+  readonly resources: readonly TileResourceManifestEntry[];
+  /** Conversion summary saved after successful destination finalization. */
+  readonly report?: TileConversionReport;
+}
+
+/** Application-owned persistence for a conversion manifest. */
+export interface TileResourceManifestStore {
+  /** Loads the previous manifest, or returns null when starting a new conversion. */
+  load(): Promise<TileResourceManifest | null>;
+  /** Atomically replaces the saved manifest with the supplied snapshot. */
+  save(manifest: TileResourceManifest): Promise<void>;
+}
+
+/** Options for decorating a resource sink with restart-safe manifest tracking. */
+export interface ManifestBackedTileConversionSinkOptions<TResource> {
+  /** Output destination with deterministic, idempotent resource writes. */
+  readonly sink: TileConversionSink<TResource>;
+  /** Persistence adapter for snapshots written after each resource. */
+  readonly manifestStore: TileResourceManifestStore;
+  /** Stable profile-specific path or resource key. */
+  readonly getResourceId: (resource: TResource) => string;
+  /** Byte length used to detect changed content under an existing resource ID. */
+  readonly measureResourceBytes: (resource: TResource) => number;
+  /** Stable fingerprint used to detect changed content under an existing resource ID. */
+  readonly fingerprintResource: (resource: TResource) => string;
+}
+
+/**
+ * Creates a sink that skips matching checkpointed resources when a process restarts.
+ *
+ * The destination must write resources idempotently by the ID returned from `getResourceId`.
+ * The manifest is persisted after every successful write; the store should replace snapshots
+ * atomically. Existing IDs must retain their byte length and fingerprint or the resumed job fails
+ * rather than silently mixing output from different conversion inputs. Writes are serialized even
+ * when callers issue them concurrently. Reports count resources processed by the current run,
+ * including writes skipped because the matching resource was already present. A graceful abort
+ * clears the manifest checkpoint before asking the destination to clean partial output, so the
+ * next run starts cleanly. A process interruption that does not call `abort` can resume from its
+ * last saved checkpoint.
+ *
+ * @param options - Destination, manifest store, stable IDs, byte measurement, and fingerprinting.
+ * @returns A `TileConversionSink` with resumable per-resource progress.
+ */
+export async function createManifestBackedTileConversionSink<TResource>(
+  options: ManifestBackedTileConversionSinkOptions<TResource>
+): Promise<TileConversionSink<TResource>> {
+  const priorManifest = await options.manifestStore.load();
+  const resources = new Map<string, TileResourceManifestEntry>();
+  if (priorManifest) {
+    validateManifest(priorManifest);
+    for (const entry of priorManifest.resources) {
+      resources.set(entry.resourceId, entry);
+    }
+  }
+
+  let writeChain: Promise<void> = Promise.resolve();
+  let writeFailed = false;
+  let writeFailure: unknown;
+  let closed = false;
+
+  const persistManifest = async (complete: boolean, report?: TileConversionReport) => {
+    await options.manifestStore.save({
+      version: TILE_RESOURCE_MANIFEST_VERSION,
+      complete,
+      resources: [...resources.values()].sort((left, right) =>
+        left.resourceId < right.resourceId ? -1 : left.resourceId > right.resourceId ? 1 : 0
+      ),
+      ...(report ? {report} : {})
+    });
+  };
+
+  const writeResource = async (resource: TResource, signal?: AbortSignal): Promise<void> => {
+    if (closed) {
+      throw new TileConversionError('RESOURCE_SINK_CLOSED', 'Cannot write after sink finalization');
+    }
+    if (writeFailed) {
+      throw writeFailure;
+    }
+    const entry = createManifestEntry(options, resource);
+    const priorEntry = resources.get(entry.resourceId);
+    if (priorEntry) {
+      if (
+        priorEntry.byteLength !== entry.byteLength ||
+        priorEntry.fingerprint !== entry.fingerprint
+      ) {
+        throw new TileConversionError(
+          'RESOURCE_RESUME_MISMATCH',
+          `Resource "${entry.resourceId}" changed since the saved manifest`
+        );
+      }
+      return;
+    }
+
+    await options.sink.write(resource, signal);
+    resources.set(entry.resourceId, entry);
+    await persistManifest(false);
+  };
+
+  return {
+    write(resource, signal) {
+      const operation = writeChain.then(() => writeResource(resource, signal));
+      writeChain = operation.catch(error => {
+        writeFailed = true;
+        writeFailure = error;
+      });
+      return operation;
+    },
+    async finalize(report) {
+      await writeChain;
+      if (writeFailed) {
+        throw writeFailure;
+      }
+      if (closed) {
+        throw new TileConversionError('RESOURCE_SINK_CLOSED', 'Sink has already been finalized');
+      }
+      await options.sink.finalize(report);
+      await persistManifest(true, report);
+      closed = true;
+    },
+    async abort(reason) {
+      await writeChain;
+      if (closed) return;
+      closed = true;
+      resources.clear();
+      await persistManifest(false);
+      await options.sink.abort(reason);
+    }
+  };
+}
+
+/** Creates and validates the deterministic manifest entry for an output resource. */
+function createManifestEntry<TResource>(
+  options: ManifestBackedTileConversionSinkOptions<TResource>,
+  resource: TResource
+): TileResourceManifestEntry {
+  const resourceId = options.getResourceId(resource);
+  const byteLength = options.measureResourceBytes(resource);
+  const fingerprint = options.fingerprintResource(resource);
+  if (
+    typeof resourceId !== 'string' ||
+    resourceId.length === 0 ||
+    typeof fingerprint !== 'string' ||
+    fingerprint.length === 0 ||
+    !Number.isSafeInteger(byteLength) ||
+    byteLength < 0
+  ) {
+    throw new TileConversionError(
+      'INVALID_RESOURCE_MANIFEST_ENTRY',
+      'Resource manifest entries require an ID, a fingerprint, and a non-negative safe byte length'
+    );
+  }
+  return {resourceId, byteLength, fingerprint};
+}
+
+/** Checks a loaded manifest before trusting it for restart decisions. */
+function validateManifest(manifest: TileResourceManifest): void {
+  if (
+    typeof manifest !== 'object' ||
+    manifest === null ||
+    manifest.version !== TILE_RESOURCE_MANIFEST_VERSION ||
+    typeof manifest.complete !== 'boolean' ||
+    !Array.isArray(manifest.resources)
+  ) {
+    throw new TileConversionError(
+      'UNSUPPORTED_RESOURCE_MANIFEST',
+      `Unsupported or malformed resource manifest version: ${String(manifest.version)}`
+    );
+  }
+  const resourceIds = new Set<string>();
+  for (const entry of manifest.resources) {
+    if (
+      typeof entry?.resourceId !== 'string' ||
+      entry.resourceId.length === 0 ||
+      typeof entry?.fingerprint !== 'string' ||
+      entry.fingerprint.length === 0 ||
+      !Number.isSafeInteger(entry.byteLength) ||
+      entry.byteLength < 0 ||
+      resourceIds.has(entry.resourceId)
+    ) {
+      throw new TileConversionError(
+        'INVALID_RESOURCE_MANIFEST',
+        'Resource manifest contains an invalid or duplicate entry'
+      );
+    }
+    resourceIds.add(entry.resourceId);
+  }
+}