@pixel-point/toolcraft 0.0.15 → 0.0.17

package/templates/runtime/model-import/topology/model-topology-resources.ts

@@ -0,0 +1,126 @@
+import type { ToolcraftModelImportLimits } from "../../schema/types";
+import type { ToolcraftModelDocument } from "../canonical/model-document";
+import { normalizeToolcraftModelImportLimits } from "../model-import-limits";
+import { safeAdd, safeMultiply } from "./model-topology-math";
+
+export type ToolcraftTopologyResourceCounts = Readonly<{
+  decodedBytes: number;
+  nodeCount: number;
+  primitiveCount: number;
+  triangleCount: number;
+  vertexCount: number;
+}>;
+
+export type ToolcraftModelResourceEstimate = Readonly<{
+  decodedBytes: number;
+  estimatedPeakWorkerBytes: number;
+  estimatedRepairBytes: number;
+}>;
+
+export type ToolcraftModelTopologyResourcePreflight =
+  ToolcraftTopologyResourceCounts & ToolcraftModelResourceEstimate;
+
+/*
+ * Conservative 64-bit JS-engine working-set assumptions. Per triangle this
+ * covers two potentially overlapping analyses during candidate proof. Each
+ * analysis retains source and filtered triangle records, six directed and six
+ * worst-case undirected numeric-key edge slots across both graphs, duplicate
+ * string keys/maps, adjacency, fan, component, and winding structures. The
+ * candidate geometry and plan arrays are additional. Node/primitive entries
+ * cover copied hierarchy and plan metadata. Three decoded-size workspaces
+ * cover digest joins plus source/candidate geometry overlap. Saturation turns
+ * any arithmetic uncertainty into rejection.
+ */
+const SIMULTANEOUS_GRAPH_ANALYSES = 2;
+const TRIANGLE_WORK_BYTES = SIMULTANEOUS_GRAPH_ANALYSES * (
+  2 * 128 +
+  6 * 80 +
+  6 * 128 +
+  192 +
+  512
+) +
+  3 * Uint32Array.BYTES_PER_ELEMENT;
+const VERTEX_WORK_BYTES =
+  SIMULTANEOUS_GRAPH_ANALYSES * 384 +
+  6 * Float32Array.BYTES_PER_ELEMENT;
+const NODE_WORK_BYTES = 512;
+const PRIMITIVE_WORK_BYTES = 1_024;
+const DECODED_WORKSPACE_COPIES = 3;
+
+function boundedCount(value: number): number {
+  return Number.isSafeInteger(value) && value >= 0
+    ? value
+    : Number.MAX_SAFE_INTEGER;
+}
+
+export function resolveTopologyLimits(
+  requested: Partial<ToolcraftModelImportLimits> | undefined,
+): Readonly<ToolcraftModelImportLimits> {
+  return Object.freeze(normalizeToolcraftModelImportLimits(requested));
+}
+
+export function estimateToolcraftTopologyResources(
+  counts: ToolcraftTopologyResourceCounts,
+): ToolcraftModelResourceEstimate {
+  const decodedBytes = boundedCount(counts.decodedBytes);
+  let estimatedRepairBytes = safeMultiply(
+    boundedCount(counts.triangleCount),
+    TRIANGLE_WORK_BYTES,
+  );
+  estimatedRepairBytes = safeAdd(estimatedRepairBytes, safeMultiply(
+    boundedCount(counts.vertexCount),
+    VERTEX_WORK_BYTES,
+  ));
+  estimatedRepairBytes = safeAdd(estimatedRepairBytes, safeMultiply(
+    boundedCount(counts.nodeCount),
+    NODE_WORK_BYTES,
+  ));
+  estimatedRepairBytes = safeAdd(estimatedRepairBytes, safeMultiply(
+    boundedCount(counts.primitiveCount),
+    PRIMITIVE_WORK_BYTES,
+  ));
+  estimatedRepairBytes = safeAdd(estimatedRepairBytes, safeMultiply(
+    decodedBytes,
+    DECODED_WORKSPACE_COPIES,
+  ));
+  return Object.freeze({
+    decodedBytes,
+    estimatedPeakWorkerBytes: safeAdd(decodedBytes, estimatedRepairBytes),
+    estimatedRepairBytes,
+  });
+}
+
+export function preflightToolcraftModelTopologyResources(
+  document: ToolcraftModelDocument,
+): ToolcraftModelTopologyResourcePreflight {
+  let decodedBytes = 0;
+  let triangleCount = 0;
+  let vertexCount = 0;
+
+  for (let index = 0; index < document.primitives.length; index += 1) {
+    const primitive = document.primitives[index]!;
+    if (primitive.positions instanceof Float32Array) {
+      decodedBytes = safeAdd(decodedBytes, primitive.positions.byteLength);
+      vertexCount = safeAdd(vertexCount, Math.floor(primitive.positions.length / 3));
+    }
+    if (primitive.indices instanceof Uint32Array) {
+      decodedBytes = safeAdd(decodedBytes, primitive.indices.byteLength);
+      triangleCount = safeAdd(triangleCount, Math.floor(primitive.indices.length / 3));
+    }
+    if (primitive.normals instanceof Float32Array) {
+      decodedBytes = safeAdd(decodedBytes, primitive.normals.byteLength);
+    }
+  }
+
+  const counts: ToolcraftTopologyResourceCounts = {
+    decodedBytes,
+    nodeCount: boundedCount(document.nodes.length),
+    primitiveCount: boundedCount(document.primitives.length),
+    triangleCount,
+    vertexCount,
+  };
+  return Object.freeze({
+    ...counts,
+    ...estimateToolcraftTopologyResources(counts),
+  });
+}

package/templates/runtime/model-import/topology/model-topology-test-support.ts

@@ -0,0 +1,163 @@
+import type {
+  ToolcraftModelBounds,
+  ToolcraftModelDocumentV1,
+  ToolcraftModelNode,
+  ToolcraftModelPrimitive,
+} from "../canonical/model-document";
+
+const IDENTITY_MATRIX = [
+  1, 0, 0, 0,
+  0, 1, 0, 0,
+  0, 0, 1, 0,
+  0, 0, 0, 1,
+] as const;
+
+export function boundsForPositions(positions: Float32Array): ToolcraftModelBounds {
+  const min: [number, number, number] = [
+    positions[0]!, positions[1]!, positions[2]!,
+  ];
+  const max: [number, number, number] = [...min];
+
+  for (let offset = 3; offset < positions.length; offset += 3) {
+    for (let axis = 0; axis < 3; axis += 1) {
+      min[axis] = Math.min(min[axis], positions[offset + axis]!);
+      max[axis] = Math.max(max[axis], positions[offset + axis]!);
+    }
+  }
+
+  return { max, min };
+}
+
+export function createTopologyPrimitive(
+  overrides: Partial<ToolcraftModelPrimitive> = {},
+): ToolcraftModelPrimitive {
+  const positions = overrides.positions ?? new Float32Array([
+    0, 0, 0,
+    1, 0, 0,
+    0, 1, 0,
+    0, 0, 1,
+  ]);
+
+  return {
+    bounds: overrides.bounds ?? boundsForPositions(positions),
+    id: overrides.id ?? "primitive-1",
+    indices: overrides.indices ?? new Uint32Array([
+      0, 2, 1,
+      0, 1, 3,
+      0, 3, 2,
+      1, 2, 3,
+    ]),
+    normals: Object.prototype.hasOwnProperty.call(overrides, "normals")
+      ? overrides.normals
+      : new Float32Array(positions.length).fill(1),
+    positions,
+  };
+}
+
+export function createTopologyDocument(
+  primitives: readonly ToolcraftModelPrimitive[] = [createTopologyPrimitive()],
+  nodeOverrides: Partial<ToolcraftModelNode> = {},
+): ToolcraftModelDocumentV1 {
+  const primitiveIds = primitives.map((primitive) => primitive.id);
+  const node: ToolcraftModelNode = {
+    children: [],
+    id: "node-1",
+    localMatrix: [...IDENTITY_MATRIX],
+    name: "Root",
+    primitiveIds,
+    ...nodeOverrides,
+  };
+  const min: [number, number, number] = [...primitives[0]!.bounds.min];
+  const max: [number, number, number] = [...primitives[0]!.bounds.max];
+  for (const primitive of primitives.slice(1)) {
+    for (let axis = 0; axis < 3; axis += 1) {
+      min[axis] = Math.min(min[axis], primitive.bounds.min[axis]);
+      max[axis] = Math.max(max[axis], primitive.bounds.max[axis]);
+    }
+  }
+
+  return {
+    bounds: { max, min },
+    nodes: [node],
+    primitives,
+    provenance: {
+      adapterVersion: "topology-test@1",
+      canonicalSchemaVersion: 1,
+      operations: [],
+      sourceFormat: "glb",
+    },
+    rootNodeIds: [node.id],
+    version: 1,
+  };
+}
+
+export function createOpenPlanePrimitive(
+  overrides: Partial<ToolcraftModelPrimitive> = {},
+): ToolcraftModelPrimitive {
+  const positions = overrides.positions ?? new Float32Array([
+    0, 0, 0,
+    1, 0, 0,
+    1, 1, 0,
+    0, 1, 0,
+  ]);
+  return createTopologyPrimitive({
+    bounds: boundsForPositions(positions),
+    indices: new Uint32Array([0, 1, 2, 0, 2, 3]),
+    normals: new Float32Array([
+      0, 0, 1,
+      0, 0, 1,
+      0, 0, 1,
+      0, 0, 1,
+    ]),
+    positions,
+    ...overrides,
+  });
+}
+
+export function createRepairablePrimitive(): ToolcraftModelPrimitive {
+  const positions = new Float32Array([
+    0, 0, 0,
+    1, 0, 0,
+    1, 1, 0,
+    0, 1, 0,
+    2, 0, 0,
+    3, 0, 0,
+    5, 5, 5,
+  ]);
+  return createTopologyPrimitive({
+    bounds: boundsForPositions(positions),
+    indices: new Uint32Array([
+      0, 1, 2,
+      0, 2, 3,
+      0, 0, 1,
+      0, 4, 5,
+      2, 0, 1,
+    ]),
+    normals: undefined,
+    positions,
+  });
+}
+
+export function createDisconnectedClosedPrimitive(): ToolcraftModelPrimitive {
+  const positions = new Float32Array([
+    0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1,
+    3, 0, 0, 4, 0, 0, 3, 1, 0, 3, 0, 1,
+  ]);
+  const tetra = [0, 2, 1, 0, 1, 3, 0, 3, 2, 1, 2, 3];
+  return createTopologyPrimitive({
+    bounds: boundsForPositions(positions),
+    indices: new Uint32Array([...tetra, ...tetra.map((index) => index + 4)]),
+    normals: new Float32Array(positions.length).fill(1),
+    positions,
+  });
+}
+
+export function createClosedSolidWithDuplicatePrimitive(): ToolcraftModelPrimitive {
+  const primitive = createTopologyPrimitive();
+  return createTopologyPrimitive({
+    indices: new Uint32Array([
+      ...primitive.indices,
+      primitive.indices[0]!, primitive.indices[1]!, primitive.indices[2]!,
+    ]),
+  });
+}

package/templates/runtime/model-import/topology/model-topology-types.ts

@@ -0,0 +1,14 @@
+import type { ToolcraftModelWorkerAnalysisSummary } from "../model-import-types";
+import type { ToolcraftModelRepairPlan } from "./model-repair-plan";
+
+export type ToolcraftModelAnalysis = ToolcraftModelWorkerAnalysisSummary & Readonly<{
+  repairPlan?: ToolcraftModelRepairPlan;
+}>;
+
+export type {
+  ToolcraftModelAnalysisOutcome,
+  ToolcraftModelTopologyDiagnostic,
+  ToolcraftModelTopologyDiagnosticCode,
+  ToolcraftModelTopologySeverity,
+  ToolcraftModelTopologyStatistics,
+} from "../model-import-types";

package/templates/runtime/model-import/worker/bounded-worker-cache.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  createToolcraftBoundedWorkerCache,
+  createToolcraftWorkerCacheCoordinator,
+} from "./bounded-worker-cache";
+
+describe("aggregate worker cache budget", () => {
+  it("evicts globally across decode, analysis, and repair caches", () => {
+    const coordinator = createToolcraftWorkerCacheCoordinator({
+      maxAggregateBytes: 10,
+    });
+    const cache = () => createToolcraftBoundedWorkerCache<string>({
+      coordinator,
+      maxEntries: 4,
+      sizeOf: (value) => value.length,
+    });
+    const decode = cache();
+    const analysis = cache();
+    const repair = cache();
+
+    decode.set("decode", "123456");
+    expect(coordinator.retainedBytes()).toBe(6);
+    analysis.set("analysis", "123456");
+    expect(coordinator.retainedBytes()).toBe(6);
+    expect(decode.get("decode")).toBeUndefined();
+    expect(analysis.get("analysis")).toBe("123456");
+
+    repair.set("repair", "123456");
+    expect(coordinator.retainedBytes()).toBe(6);
+    expect(analysis.get("analysis")).toBeUndefined();
+    expect(repair.get("repair")).toBe("123456");
+    expect(coordinator.retainedBytes()).toBe(6);
+    expect(coordinator.retainedBytes()).toBeLessThanOrEqual(
+      coordinator.maxAggregateBytes,
+    );
+  });
+
+  it.each([Infinity, Number.NaN, 0, -1, Number.MAX_SAFE_INTEGER + 1])(
+    "rejects invalid aggregate byte budget %s",
+    (maxAggregateBytes) => {
+      expect(() => createToolcraftWorkerCacheCoordinator({
+        maxAggregateBytes,
+      })).toThrow(/finite positive safe integer/u);
+    },
+  );
+});

package/templates/runtime/model-import/worker/bounded-worker-cache.ts

@@ -0,0 +1,147 @@
+type CacheEntryToken = object;
+
+type CoordinatedEntry = Readonly<{
+  byteLength: number;
+  evict: () => void;
+}>;
+
+export type ToolcraftWorkerCacheCoordinator = Readonly<{
+  maxAggregateBytes: number;
+  release: (token: CacheEntryToken) => void;
+  reserve: (
+    token: CacheEntryToken,
+    byteLength: number,
+    evict: () => void,
+  ) => boolean;
+  retainedBytes: () => number;
+  touch: (token: CacheEntryToken) => void;
+}>;
+
+export function createToolcraftWorkerCacheCoordinator(options: Readonly<{
+  maxAggregateBytes: number;
+}>): ToolcraftWorkerCacheCoordinator {
+  if (!Number.isSafeInteger(options.maxAggregateBytes) ||
+      options.maxAggregateBytes <= 0) {
+    throw new Error(
+      "Worker cache maxAggregateBytes must be a finite positive safe integer.",
+    );
+  }
+  const entries = new Map<CacheEntryToken, CoordinatedEntry>();
+  let retainedBytes = 0;
+
+  const release = (token: CacheEntryToken): void => {
+    const entry = entries.get(token);
+    if (!entry) return;
+    entries.delete(token);
+    retainedBytes -= entry.byteLength;
+  };
+
+  return Object.freeze({
+    maxAggregateBytes: options.maxAggregateBytes,
+    release,
+    reserve: (token, byteLength, evict) => {
+      if (!Number.isSafeInteger(byteLength) || byteLength < 0 ||
+          byteLength > options.maxAggregateBytes) return false;
+      release(token);
+      entries.set(token, { byteLength, evict });
+      retainedBytes += byteLength;
+      while (retainedBytes > options.maxAggregateBytes) {
+        const oldest = entries.entries().next().value as
+          | [CacheEntryToken, CoordinatedEntry]
+          | undefined;
+        if (!oldest) break;
+        const [oldestToken, oldestEntry] = oldest;
+        entries.delete(oldestToken);
+        retainedBytes -= oldestEntry.byteLength;
+        oldestEntry.evict();
+      }
+      return entries.has(token);
+    },
+    retainedBytes: () => retainedBytes,
+    touch: (token) => {
+      const entry = entries.get(token);
+      if (!entry) return;
+      entries.delete(token);
+      entries.set(token, entry);
+    },
+  });
+}
+
+export type ToolcraftBoundedWorkerCache<Value> = Readonly<{
+  clear: () => void;
+  dispose: () => void;
+  get: (key: string) => Value | undefined;
+  set: (key: string, value: Value) => void;
+  size: () => number;
+}>;
+
+type LocalEntry<Value> = Readonly<{
+  byteLength: number;
+  token: CacheEntryToken;
+  value: Value;
+}>;
+
+export function createToolcraftBoundedWorkerCache<Value>(options: Readonly<{
+  coordinator: ToolcraftWorkerCacheCoordinator;
+  maxEntries: number;
+  sizeOf: (value: Value) => number;
+}>): ToolcraftBoundedWorkerCache<Value> {
+  if (!Number.isSafeInteger(options.maxEntries) || options.maxEntries <= 0) {
+    throw new Error(
+      "Bounded worker cache maxEntries must be a finite positive safe integer.",
+    );
+  }
+  if (typeof options.sizeOf !== "function") {
+    throw new Error("Bounded worker cache sizeOf must be a function.");
+  }
+  const entries = new Map<string, LocalEntry<Value>>();
+  let disposed = false;
+
+  const remove = (key: string): void => {
+    const entry = entries.get(key);
+    if (!entry) return;
+    entries.delete(key);
+    options.coordinator.release(entry.token);
+  };
+  const clear = (): void => {
+    for (const key of [...entries.keys()]) remove(key);
+  };
+
+  return Object.freeze({
+    clear,
+    dispose: () => {
+      if (disposed) return;
+      disposed = true;
+      clear();
+    },
+    get: (key) => {
+      if (disposed) return undefined;
+      const entry = entries.get(key);
+      if (!entry) return undefined;
+      entries.delete(key);
+      entries.set(key, entry);
+      options.coordinator.touch(entry.token);
+      return entry.value;
+    },
+    set: (key, value) => {
+      if (disposed) return;
+      const byteLength = options.sizeOf(value);
+      if (!Number.isSafeInteger(byteLength) || byteLength < 0 ||
+          byteLength > options.coordinator.maxAggregateBytes) return;
+      remove(key);
+      const token: CacheEntryToken = {};
+      const entry: LocalEntry<Value> = { byteLength, token, value };
+      entries.set(key, entry);
+      const retained = options.coordinator.reserve(token, byteLength, () => {
+        if (entries.get(key)?.token === token) entries.delete(key);
+      });
+      if (!retained) entries.delete(key);
+      while (entries.size > options.maxEntries) {
+        const oldestKey = entries.keys().next().value as string | undefined;
+        if (oldestKey === undefined) break;
+        remove(oldestKey);
+      }
+    },
+    size: () => entries.size,
+  });
+}

package/templates/runtime/model-import/worker/cooperative-buffer-snapshot.ts

@@ -0,0 +1,195 @@
+export const TOOLCRAFT_MODEL_WORKER_SNAPSHOT_CHUNK_BYTES = 1024 * 1024;
+
+export type ToolcraftModelWorkerYieldToHost = () => Promise<void>;
+
+export type ToolcraftModelWorkerBufferSource = Readonly<{
+  byteLength: number;
+  bytes: Uint8Array;
+}>;
+
+export type ToolcraftModelWorkerBufferCopies =
+  | Promise<readonly ArrayBuffer[] | undefined>
+  | readonly ArrayBuffer[]
+  | undefined;
+
+const arrayBufferByteLengthGetter = Object.getOwnPropertyDescriptor(
+  ArrayBuffer.prototype,
+  "byteLength",
+)?.get;
+const typedArrayPrototype = Object.getPrototypeOf(Uint8Array.prototype) as object;
+const typedArrayBufferGetter = Object.getOwnPropertyDescriptor(
+  typedArrayPrototype,
+  "buffer",
+)?.get;
+const typedArrayByteLengthGetter = Object.getOwnPropertyDescriptor(
+  typedArrayPrototype,
+  "byteLength",
+)?.get;
+const typedArrayByteOffsetGetter = Object.getOwnPropertyDescriptor(
+  typedArrayPrototype,
+  "byteOffset",
+)?.get;
+const typedArrayTagGetter = Object.getOwnPropertyDescriptor(
+  typedArrayPrototype,
+  Symbol.toStringTag,
+)?.get;
+
+function inspectArrayBuffer(value: unknown): ToolcraftModelWorkerBufferSource | undefined {
+  if (!arrayBufferByteLengthGetter) return undefined;
+  try {
+    const byteLength = Reflect.apply(arrayBufferByteLengthGetter, value, []) as number;
+    if (!Number.isSafeInteger(byteLength) || byteLength <= 0) return undefined;
+    const bytes = new Uint8Array(value as ArrayBuffer);
+    if (bytes.byteLength !== byteLength) return undefined;
+    return Object.freeze({ byteLength, bytes });
+  } catch {
+    return undefined;
+  }
+}
+
+function inspectUint8Array(value: unknown): ToolcraftModelWorkerBufferSource | undefined {
+  if (!typedArrayBufferGetter || !typedArrayByteLengthGetter ||
+      !typedArrayByteOffsetGetter || !typedArrayTagGetter ||
+      !arrayBufferByteLengthGetter) return undefined;
+  try {
+    if (Reflect.apply(typedArrayTagGetter, value, []) !== "Uint8Array") return undefined;
+    const buffer = Reflect.apply(typedArrayBufferGetter, value, []) as ArrayBuffer;
+    const byteLength = Reflect.apply(typedArrayByteLengthGetter, value, []) as number;
+    const byteOffset = Reflect.apply(typedArrayByteOffsetGetter, value, []) as number;
+    const bufferByteLength = Reflect.apply(
+      arrayBufferByteLengthGetter,
+      buffer,
+      [],
+    ) as number;
+    if (!Number.isSafeInteger(byteLength) || byteLength <= 0 ||
+        !Number.isSafeInteger(byteOffset) || byteOffset < 0 ||
+        !Number.isSafeInteger(bufferByteLength) ||
+        byteOffset > bufferByteLength - byteLength) return undefined;
+    return Object.freeze({
+      byteLength,
+      bytes: new Uint8Array(buffer, byteOffset, byteLength),
+    });
+  } catch {
+    return undefined;
+  }
+}
+
+export function inspectToolcraftModelWorkerArrayBuffer(
+  value: unknown,
+): ToolcraftModelWorkerBufferSource | undefined {
+  return inspectArrayBuffer(value);
+}
+
+export function inspectToolcraftModelWorkerBuffer(
+  value: unknown,
+): ToolcraftModelWorkerBufferSource | undefined {
+  return inspectArrayBuffer(value) ?? inspectUint8Array(value);
+}
+
+function assertSourceReadable(source: ToolcraftModelWorkerBufferSource): void {
+  if (source.bytes.byteLength !== source.byteLength) {
+    throw new Error("A model worker snapshot source became unreadable.");
+  }
+}
+
+function copySmallBuffers(
+  sources: readonly ToolcraftModelWorkerBufferSource[],
+  isCurrent: () => boolean,
+): readonly ArrayBuffer[] | undefined {
+  const copies: ArrayBuffer[] = [];
+  for (const source of sources) {
+    if (!isCurrent()) return undefined;
+    assertSourceReadable(source);
+    const destination = new Uint8Array(source.byteLength);
+    destination.set(source.bytes);
+    copies.push(destination.buffer);
+  }
+  return Object.freeze(copies);
+}
+
+async function copyLargeBuffers(
+  sources: readonly ToolcraftModelWorkerBufferSource[],
+  isCurrent: () => boolean,
+  yieldToHost: ToolcraftModelWorkerYieldToHost,
+): Promise<readonly ArrayBuffer[] | undefined> {
+  const copies: ArrayBuffer[] = [];
+  let bytesUntilYield = TOOLCRAFT_MODEL_WORKER_SNAPSHOT_CHUNK_BYTES;
+  for (let sourceIndex = 0; sourceIndex < sources.length; sourceIndex += 1) {
+    const source = sources[sourceIndex]!;
+    if (!isCurrent()) return undefined;
+    assertSourceReadable(source);
+    const destination = new Uint8Array(source.byteLength);
+    copies.push(destination.buffer);
+    let offset = 0;
+    while (offset < source.byteLength) {
+      if (!isCurrent()) return undefined;
+      assertSourceReadable(source);
+      const copyByteLength = Math.min(
+        bytesUntilYield,
+        source.byteLength - offset,
+      );
+      destination.set(
+        source.bytes.subarray(offset, offset + copyByteLength),
+        offset,
+      );
+      offset += copyByteLength;
+      bytesUntilYield -= copyByteLength;
+      const hasMore = offset < source.byteLength || sourceIndex < sources.length - 1;
+      if (bytesUntilYield === 0 && hasMore) {
+        await yieldToHost();
+        if (!isCurrent()) return undefined;
+        bytesUntilYield = TOOLCRAFT_MODEL_WORKER_SNAPSHOT_CHUNK_BYTES;
+      }
+    }
+  }
+  return Object.freeze(copies);
+}
+
+export function copyToolcraftModelWorkerBuffers(
+  sources: readonly ToolcraftModelWorkerBufferSource[],
+  totalByteLength: number,
+  isCurrent: () => boolean,
+  yieldToHost: ToolcraftModelWorkerYieldToHost,
+): ToolcraftModelWorkerBufferCopies {
+  if (!isCurrent()) return undefined;
+  return totalByteLength <= TOOLCRAFT_MODEL_WORKER_SNAPSHOT_CHUNK_BYTES
+    ? copySmallBuffers(sources, isCurrent)
+    : copyLargeBuffers(sources, isCurrent, yieldToHost);
+}
+
+function yieldWithMessageChannel(): Promise<void> | undefined {
+  if (typeof MessageChannel !== "function") return undefined;
+  try {
+    return new Promise((resolve) => {
+      const channel = new MessageChannel();
+      channel.port1.onmessage = () => {
+        channel.port1.close();
+        channel.port2.close();
+        resolve();
+      };
+      channel.port2.postMessage(undefined);
+    });
+  } catch {
+    return undefined;
+  }
+}
+
+export async function yieldToToolcraftModelWorkerHost(): Promise<void> {
+  const scheduler = (globalThis as Readonly<{
+    scheduler?: Readonly<{ yield?: () => Promise<void> }>;
+  }>).scheduler;
+  if (typeof scheduler?.yield === "function") {
+    try {
+      await Reflect.apply(scheduler.yield, scheduler, []);
+      return;
+    } catch {
+      // Fall through to a broadly supported macrotask boundary.
+    }
+  }
+  const channelYield = yieldWithMessageChannel();
+  if (channelYield) {
+    await channelYield;
+    return;
+  }
+  await new Promise<void>((resolve) => setTimeout(resolve, 0));
+}