@pixel-point/toolcraft 0.0.15 → 0.0.16

package/templates/runtime/model-import/topology/model-repair-plan-codec.test.ts

@@ -0,0 +1,125 @@
+import { describe, expect, it } from "vitest";
+
+import { TOOLCRAFT_DEFAULT_MODEL_IMPORT_LIMITS } from "../model-import-limits";
+import {
+  TOOLCRAFT_MODEL_REPAIR_ALGORITHM_VERSION,
+  type ToolcraftModelRepairPlan,
+} from "./model-repair-plan";
+import {
+  decodeToolcraftModelRepairPlanEnvelope,
+  encodeToolcraftModelRepairPlanEnvelope,
+} from "./model-repair-plan-codec";
+import { TOOLCRAFT_MODEL_TOPOLOGY_ANALYZER_VERSION } from "./model-topology-analysis";
+import { digestToolcraftRepairPlanPayload } from "./model-topology-digest";
+
+function repairPlan(indexCount = 20_000): ToolcraftModelRepairPlan {
+  const payload = {
+    algorithmVersion: TOOLCRAFT_MODEL_REPAIR_ALGORITHM_VERSION,
+    analyzerVersion: TOOLCRAFT_MODEL_TOPOLOGY_ANALYZER_VERSION,
+    operations: [{
+      expectedCountDelta: { triangles: -indexCount, vertices: 0 },
+      primitiveId: "primitive-0",
+      primitiveIndex: 0,
+      safetyPreconditions: ["indices are in range"],
+      triangleIndices: Array.from({ length: indexCount }, (_, index) => index),
+      type: "remove-invalid-triangles" as const,
+    }],
+    profile: "realtime-mesh" as const,
+    sourceDocumentDigest: `sha256:${"2".repeat(64)}`,
+  };
+  const planDigest = digestToolcraftRepairPlanPayload(payload);
+  return {
+    ...payload,
+    planDigest,
+    recipeId: `${TOOLCRAFT_MODEL_REPAIR_ALGORITHM_VERSION}:${planDigest}`,
+  };
+}
+
+describe("repair plan transferable envelope", () => {
+  it("round-trips a large plan through a bounded versioned envelope in the worker", () => {
+    const plan = repairPlan();
+    const envelope = encodeToolcraftModelRepairPlanEnvelope(plan);
+
+    expect(envelope).toBeInstanceOf(Uint8Array);
+    expect(envelope.byteLength).toBeGreaterThan(100_000);
+    const decoded = decodeToolcraftModelRepairPlanEnvelope(envelope, {
+      expectedPlanDigest: plan.planDigest,
+      expectedProfile: plan.profile,
+      limits: TOOLCRAFT_DEFAULT_MODEL_IMPORT_LIMITS,
+    });
+
+    expect(decoded).toEqual(plan);
+    expect(Object.isFrozen(decoded)).toBe(true);
+    expect(Object.isFrozen(decoded.operations)).toBe(true);
+    expect(Object.isFrozen(decoded.operations[0])).toBe(true);
+    expect(Object.isFrozen(decoded.operations[0]!.safetyPreconditions)).toBe(true);
+    expect(Object.isFrozen(
+      (decoded.operations[0] as { triangleIndices: readonly number[] }).triangleIndices,
+    )).toBe(true);
+  });
+
+  it("keeps semantic digests stable across object insertion order", () => {
+    const first = {
+      operations: [{
+        expectedCountDelta: { triangles: 0, vertices: -2 },
+        primitiveId: "primitive-0",
+        primitiveIndex: 0,
+        removedVertexIndices: [4, 5],
+        retainedVertexIndices: [0, 1, 2, 3],
+        safetyPreconditions: ["stable remap"],
+        type: "compact-unused-vertices",
+      }],
+      profile: "realtime-mesh",
+    };
+    const second = {
+      profile: "realtime-mesh",
+      operations: [{
+        type: "compact-unused-vertices",
+        safetyPreconditions: ["stable remap"],
+        retainedVertexIndices: [0, 1, 2, 3],
+        removedVertexIndices: [4, 5],
+        primitiveIndex: 0,
+        primitiveId: "primitive-0",
+        expectedCountDelta: { vertices: -2, triangles: 0 },
+      }],
+    };
+
+    expect(digestToolcraftRepairPlanPayload(first)).toBe(
+      digestToolcraftRepairPlanPayload(second),
+    );
+  });
+
+  it("rejects malformed framing and a forged semantic plan digest", () => {
+    const plan = repairPlan(3);
+    const malformed = encodeToolcraftModelRepairPlanEnvelope(plan);
+    malformed[0] ^= 0xff;
+    expect(() => decodeToolcraftModelRepairPlanEnvelope(malformed, {
+      expectedPlanDigest: plan.planDigest,
+      expectedProfile: plan.profile,
+      limits: TOOLCRAFT_DEFAULT_MODEL_IMPORT_LIMITS,
+    })).toThrow(/envelope/u);
+
+    const forged = {
+      ...plan,
+      planDigest: `sha256:${"0".repeat(64)}`,
+      recipeId: `${TOOLCRAFT_MODEL_REPAIR_ALGORITHM_VERSION}:sha256:${"0".repeat(64)}`,
+    };
+    const forgedEnvelope = encodeToolcraftModelRepairPlanEnvelope(forged);
+    expect(() => decodeToolcraftModelRepairPlanEnvelope(forgedEnvelope, {
+      expectedPlanDigest: forged.planDigest,
+      expectedProfile: forged.profile,
+      limits: TOOLCRAFT_DEFAULT_MODEL_IMPORT_LIMITS,
+    })).toThrow(/digest/u);
+  });
+
+  it("enforces the envelope byte limit before JSON parsing", () => {
+    const plan = repairPlan(100);
+    const envelope = encodeToolcraftModelRepairPlanEnvelope(plan);
+    expect(() => decodeToolcraftModelRepairPlanEnvelope(envelope, {
+      expectedPlanDigest: plan.planDigest,
+      expectedProfile: plan.profile,
+      limits: TOOLCRAFT_DEFAULT_MODEL_IMPORT_LIMITS,
+      maxByteLength: 64,
+    })).toThrow(/byte limit/u);
+  });
+});

package/templates/runtime/model-import/topology/model-repair-plan-codec.ts

@@ -0,0 +1,96 @@
+import type { ToolcraftModelRepairPlan } from "./model-repair-plan";
+import {
+  TOOLCRAFT_MODEL_REPAIR_PLAN_ENVELOPE_MAX_BYTES,
+  TOOLCRAFT_MODEL_REPAIR_PLAN_ENVELOPE_VERSION,
+} from "./model-repair-plan-envelope";
+import {
+  validateToolcraftModelRepairPlan,
+  type ToolcraftModelRepairPlanValidationOptions,
+} from "./model-repair-plan-validation";
+
+const HEADER_BYTES = 16;
+const MAGIC = Object.freeze([0x54, 0x43, 0x52, 0x50, 0x4c, 0x41, 0x4e, 0x00]);
+const encoder = new TextEncoder();
+const decoder = new TextDecoder("utf-8", { fatal: true });
+
+type DecodeOptions = ToolcraftModelRepairPlanValidationOptions & Readonly<{
+  maxByteLength?: number;
+}>;
+
+function fail(message: string): never {
+  throw Object.assign(new Error(message), {
+    category: "repair",
+    code: "repair-plan-envelope-invalid",
+  });
+}
+
+function byteLimit(value: number | undefined): number {
+  const result = value ?? TOOLCRAFT_MODEL_REPAIR_PLAN_ENVELOPE_MAX_BYTES;
+  if (!Number.isSafeInteger(result) || result < HEADER_BYTES ||
+      result > TOOLCRAFT_MODEL_REPAIR_PLAN_ENVELOPE_MAX_BYTES) {
+    return fail("Repair plan envelope byte limit is invalid.");
+  }
+  return result;
+}
+
+function viewOf(value: ArrayBuffer | Uint8Array): Uint8Array {
+  return value instanceof Uint8Array
+    ? new Uint8Array(value.buffer, value.byteOffset, value.byteLength)
+    : new Uint8Array(value);
+}
+
+export function encodeToolcraftModelRepairPlanEnvelope(
+  plan: ToolcraftModelRepairPlan,
+  options: Readonly<{ maxByteLength?: number }> = {},
+): Uint8Array<ArrayBuffer> {
+  const payload = encoder.encode(JSON.stringify({
+    algorithmVersion: plan.algorithmVersion,
+    analyzerVersion: plan.analyzerVersion,
+    operations: plan.operations,
+    planDigest: plan.planDigest,
+    profile: plan.profile,
+    recipeId: plan.recipeId,
+    sourceDocumentDigest: plan.sourceDocumentDigest,
+  }));
+  const totalByteLength = HEADER_BYTES + payload.byteLength;
+  if (totalByteLength > byteLimit(options.maxByteLength)) {
+    return fail("Repair plan envelope exceeds its byte limit.");
+  }
+  const envelope = new Uint8Array(totalByteLength);
+  envelope.set(MAGIC, 0);
+  const header = new DataView(envelope.buffer);
+  header.setUint16(8, TOOLCRAFT_MODEL_REPAIR_PLAN_ENVELOPE_VERSION, true);
+  header.setUint16(10, 0, true);
+  header.setUint32(12, payload.byteLength, true);
+  envelope.set(payload, HEADER_BYTES);
+  return envelope;
+}
+
+export function decodeToolcraftModelRepairPlanEnvelope(
+  value: ArrayBuffer | Uint8Array,
+  options: DecodeOptions,
+): ToolcraftModelRepairPlan {
+  const bytes = viewOf(value);
+  const maximum = byteLimit(options.maxByteLength);
+  if (bytes.byteLength < HEADER_BYTES || bytes.byteLength > maximum) {
+    return fail("Repair plan envelope exceeds its byte limit.");
+  }
+  for (let index = 0; index < MAGIC.length; index += 1) {
+    if (bytes[index] !== MAGIC[index]) {
+      return fail("Repair plan envelope framing is invalid.");
+    }
+  }
+  const header = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (header.getUint16(8, true) !== TOOLCRAFT_MODEL_REPAIR_PLAN_ENVELOPE_VERSION ||
+      header.getUint16(10, true) !== 0 ||
+      header.getUint32(12, true) !== bytes.byteLength - HEADER_BYTES) {
+    return fail("Repair plan envelope framing is invalid.");
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(decoder.decode(bytes.subarray(HEADER_BYTES)));
+  } catch {
+    return fail("Repair plan envelope payload is invalid UTF-8 JSON.");
+  }
+  return validateToolcraftModelRepairPlan(parsed, options);
+}

package/templates/runtime/model-import/topology/model-repair-plan-envelope.ts

@@ -0,0 +1,13 @@
+import type { ToolcraftModelImportLimits } from "../../schema/types";
+
+export const TOOLCRAFT_MODEL_REPAIR_PLAN_ENVELOPE_VERSION = 1 as const;
+export const TOOLCRAFT_MODEL_REPAIR_PLAN_ENVELOPE_MAX_BYTES = 64 * 1024 * 1024;
+
+export function getToolcraftModelRepairPlanEnvelopeByteLimit(
+  limits: Readonly<ToolcraftModelImportLimits>,
+): number {
+  return Math.floor(Math.min(
+    TOOLCRAFT_MODEL_REPAIR_PLAN_ENVELOPE_MAX_BYTES,
+    limits.maxEstimatedWorkerBytes,
+  ));
+}

package/templates/runtime/model-import/topology/model-repair-plan-validation.ts

@@ -0,0 +1,325 @@
+import type {
+  ToolcraftModelImportLimits,
+  ToolcraftModelTopologyProfile,
+} from "../../schema/types";
+import {
+  TOOLCRAFT_MODEL_REPAIR_ALGORITHM_VERSION,
+  type ToolcraftModelRepairOperation,
+  type ToolcraftModelRepairPlan,
+} from "./model-repair-plan";
+import { TOOLCRAFT_MODEL_TOPOLOGY_ANALYZER_VERSION } from "./model-topology-analysis";
+import { digestToolcraftRepairPlanPayload } from "./model-topology-digest";
+
+const SHA256_DIGEST_PATTERN = /^sha256:[0-9a-f]{64}$/u;
+const MAX_ID_LENGTH = 1_024;
+const MAX_PRECONDITION_LENGTH = 512;
+const MAX_PRECONDITIONS = 32;
+const MAX_TEXT_CODE_UNITS = 8 * 1024 * 1024;
+
+type UnknownRecord = Record<string, unknown>;
+type ValidationBudget = { numericEntries: number; textCodeUnits: number };
+
+export type ToolcraftModelRepairPlanValidationOptions = Readonly<{
+  expectedPlanDigest: string;
+  expectedProfile?: ToolcraftModelTopologyProfile;
+  expectedSourceDocumentDigest?: string;
+  limits: Readonly<ToolcraftModelImportLimits>;
+}>;
+
+function invalid(message: string): never {
+  throw Object.assign(new Error(message), {
+    category: "repair",
+    code: "repair-plan-envelope-invalid",
+  });
+}
+
+function record(
+  value: unknown,
+  allowedKeys: readonly string[],
+  label: string,
+): UnknownRecord {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return invalid(`Repair plan envelope ${label} must be an object.`);
+  }
+  const keys = Reflect.ownKeys(value);
+  if (keys.some((key) => typeof key !== "string" || !allowedKeys.includes(key))) {
+    return invalid(`Repair plan envelope ${label} has unsupported fields.`);
+  }
+  return value as UnknownRecord;
+}
+
+function requireOnlyFields(
+  value: UnknownRecord,
+  fields: readonly string[],
+  label: string,
+): void {
+  if (Reflect.ownKeys(value).some((key) =>
+    typeof key !== "string" || !fields.includes(key)
+  )) {
+    invalid(`Repair plan envelope ${label} has unsupported fields.`);
+  }
+}
+
+function string(
+  value: unknown,
+  label: string,
+  maxLength = MAX_ID_LENGTH,
+): string {
+  if (typeof value !== "string" || value.length === 0 || value.length > maxLength) {
+    return invalid(`Repair plan envelope ${label} is invalid.`);
+  }
+  return value;
+}
+
+function digest(value: unknown, label: string): string {
+  const result = string(value, label, 71);
+  if (!SHA256_DIGEST_PATTERN.test(result)) {
+    return invalid(`Repair plan envelope ${label} digest is invalid.`);
+  }
+  return result;
+}
+
+function integer(value: unknown, label: string): number {
+  if (!Number.isSafeInteger(value)) {
+    return invalid(`Repair plan envelope ${label} must be a safe integer.`);
+  }
+  return value as number;
+}
+
+function nonNegativeInteger(
+  value: unknown,
+  label: string,
+  maximum: number,
+): number {
+  const result = integer(value, label);
+  if (result < 0 || result > maximum) {
+    return invalid(`Repair plan envelope ${label} exceeds its limit.`);
+  }
+  return result;
+}
+
+function strings(
+  value: unknown,
+  budget: ValidationBudget,
+): readonly string[] {
+  if (!Array.isArray(value) || value.length > MAX_PRECONDITIONS) {
+    return invalid("Repair plan envelope safety preconditions are invalid.");
+  }
+  const result: string[] = [];
+  for (let index = 0; index < value.length; index += 1) {
+    if (!Object.prototype.hasOwnProperty.call(value, index)) {
+      return invalid("Repair plan envelope contains a sparse string array.");
+    }
+    const entry = string(
+      value[index],
+      "safety precondition",
+      MAX_PRECONDITION_LENGTH,
+    );
+    if (entry.length > budget.textCodeUnits) {
+      return invalid("Repair plan envelope text exceeds its limit.");
+    }
+    budget.textCodeUnits -= entry.length;
+    result.push(entry);
+  }
+  return Object.freeze(result);
+}
+
+function numbers(
+  value: unknown,
+  label: string,
+  maximumLength: number,
+  maximumValue: number,
+  budget: ValidationBudget,
+): readonly number[] {
+  if (!Array.isArray(value) || value.length > maximumLength ||
+      value.length > budget.numericEntries) {
+    return invalid(`Repair plan envelope ${label} exceeds its limit.`);
+  }
+  const result: number[] = [];
+  for (let index = 0; index < value.length; index += 1) {
+    if (!Object.prototype.hasOwnProperty.call(value, index)) {
+      return invalid(`Repair plan envelope ${label} is sparse.`);
+    }
+    result.push(nonNegativeInteger(value[index], label, maximumValue));
+  }
+  budget.numericEntries -= result.length;
+  return Object.freeze(result);
+}
+
+function countDelta(
+  value: unknown,
+  limits: Readonly<ToolcraftModelImportLimits>,
+): Readonly<{ triangles: number; vertices: number }> {
+  const input = record(value, ["triangles", "vertices"], "count delta");
+  const triangles = integer(input.triangles, "triangle count delta");
+  const vertices = integer(input.vertices, "vertex count delta");
+  if (Math.abs(triangles) > limits.maxTriangles ||
+      Math.abs(vertices) > limits.maxVertices) {
+    return invalid("Repair plan envelope count delta exceeds its limit.");
+  }
+  return Object.freeze({ triangles, vertices });
+}
+
+function operation(
+  value: unknown,
+  limits: Readonly<ToolcraftModelImportLimits>,
+  budget: ValidationBudget,
+): ToolcraftModelRepairOperation {
+  const candidate = record(value, [
+    "expectedCountDelta",
+    "flippedTriangleIndices",
+    "primitiveId",
+    "primitiveIndex",
+    "removedVertexIndices",
+    "retainedVertexIndices",
+    "safetyPreconditions",
+    "triangleIndices",
+    "type",
+    "vertexCount",
+  ], "operation");
+  const type = string(candidate.type, "operation type", 80);
+  const commonFields = [
+    "expectedCountDelta",
+    "primitiveId",
+    "primitiveIndex",
+    "safetyPreconditions",
+    "type",
+  ];
+  const specificFields = type === "compact-unused-vertices"
+    ? ["removedVertexIndices", "retainedVertexIndices"]
+    : type === "repair-local-winding"
+      ? ["flippedTriangleIndices"]
+      : type === "remove-duplicate-triangles" ||
+          type === "remove-invalid-triangles"
+        ? ["triangleIndices"]
+        : type === "regenerate-normals"
+          ? ["vertexCount"]
+          : type === "recalculate-bounds"
+            ? []
+            : undefined;
+  if (!specificFields) {
+    return invalid("Repair plan envelope operation type is unsupported.");
+  }
+  requireOnlyFields(candidate, [...commonFields, ...specificFields], "operation");
+  const primitiveId = string(candidate.primitiveId, "primitive id");
+  if (primitiveId.length > budget.textCodeUnits) {
+    return invalid("Repair plan envelope text exceeds its limit.");
+  }
+  budget.textCodeUnits -= primitiveId.length;
+  const common = {
+    expectedCountDelta: countDelta(candidate.expectedCountDelta, limits),
+    primitiveId,
+    primitiveIndex: nonNegativeInteger(
+      candidate.primitiveIndex,
+      "primitive index",
+      limits.maxPrimitives - 1,
+    ),
+    safetyPreconditions: strings(candidate.safetyPreconditions, budget),
+  };
+  if (type === "compact-unused-vertices") {
+    return Object.freeze({
+      ...common,
+      removedVertexIndices: numbers(candidate.removedVertexIndices,
+        "removed vertex indices", limits.maxVertices, limits.maxVertices - 1, budget),
+      retainedVertexIndices: numbers(candidate.retainedVertexIndices,
+        "retained vertex indices", limits.maxVertices, limits.maxVertices - 1, budget),
+      type,
+    });
+  }
+  if (type === "repair-local-winding") {
+    return Object.freeze({
+      ...common,
+      flippedTriangleIndices: numbers(candidate.flippedTriangleIndices,
+        "flipped triangle indices", limits.maxTriangles, limits.maxTriangles - 1, budget),
+      type,
+    });
+  }
+  if (type === "remove-duplicate-triangles" ||
+      type === "remove-invalid-triangles") {
+    return Object.freeze({
+      ...common,
+      triangleIndices: numbers(candidate.triangleIndices,
+        "triangle indices", limits.maxTriangles, limits.maxTriangles - 1, budget),
+      type,
+    });
+  }
+  if (type === "regenerate-normals") {
+    return Object.freeze({
+      ...common,
+      type,
+      vertexCount: nonNegativeInteger(
+        candidate.vertexCount,
+        "normal vertex count",
+        limits.maxVertices,
+      ),
+    });
+  }
+  if (type === "recalculate-bounds") {
+    return Object.freeze({ ...common, type });
+  }
+  return invalid("Repair plan envelope operation type is unsupported.");
+}
+
+export function validateToolcraftModelRepairPlan(
+  value: unknown,
+  options: ToolcraftModelRepairPlanValidationOptions,
+): ToolcraftModelRepairPlan {
+  const candidate = record(value, [
+    "algorithmVersion",
+    "analyzerVersion",
+    "operations",
+    "planDigest",
+    "profile",
+    "recipeId",
+    "sourceDocumentDigest",
+  ], "payload");
+  if (!Array.isArray(candidate.operations) || candidate.operations.length === 0 ||
+      candidate.operations.length > options.limits.maxPrimitives * 6 + 1) {
+    return invalid("Repair plan envelope operation count exceeds its limit.");
+  }
+  const budget: ValidationBudget = {
+    numericEntries: options.limits.maxTriangles * 3 +
+      options.limits.maxVertices * 2,
+    textCodeUnits: MAX_TEXT_CODE_UNITS,
+  };
+  const operations = Object.freeze(candidate.operations.map((entry) =>
+    operation(entry, options.limits, budget)
+  ));
+  const algorithmVersion = string(candidate.algorithmVersion, "algorithm version", 80);
+  const analyzerVersion = string(candidate.analyzerVersion, "analyzer version", 80);
+  const planDigest = digest(candidate.planDigest, "semantic plan");
+  const sourceDocumentDigest = digest(
+    candidate.sourceDocumentDigest,
+    "source document",
+  );
+  const profile = candidate.profile;
+  if (profile !== "realtime-mesh" && profile !== "solid-mesh") {
+    return invalid("Repair plan envelope profile is invalid.");
+  }
+  const validatedProfile: ToolcraftModelTopologyProfile = profile;
+  if (algorithmVersion !== TOOLCRAFT_MODEL_REPAIR_ALGORITHM_VERSION ||
+      analyzerVersion !== TOOLCRAFT_MODEL_TOPOLOGY_ANALYZER_VERSION ||
+      (options.expectedProfile !== undefined &&
+        validatedProfile !== options.expectedProfile) ||
+      (options.expectedSourceDocumentDigest !== undefined &&
+        sourceDocumentDigest !== options.expectedSourceDocumentDigest) ||
+      planDigest !== options.expectedPlanDigest ||
+      candidate.recipeId !== `${algorithmVersion}:${planDigest}`) {
+    return invalid("Repair plan envelope identity or digest is invalid.");
+  }
+  const payload = {
+    algorithmVersion,
+    analyzerVersion,
+    operations,
+    profile: validatedProfile,
+    sourceDocumentDigest,
+  };
+  if (digestToolcraftRepairPlanPayload(payload) !== planDigest) {
+    return invalid("Repair plan envelope semantic digest does not match its payload.");
+  }
+  return Object.freeze({
+    ...payload,
+    planDigest,
+    recipeId: `${algorithmVersion}:${planDigest}`,
+  });
+}