@instruktlabs/kiln 1.2.2 → 1.2.3

package/src/qa/material.ts

@@ -3,6 +3,7 @@ import * as THREE from 'three';
 import type { KilnTextureMetadata } from '../textures';
 import { conformancePromotionAuthorization, KILN_ENGINE_QA_OWNER, type QaRule } from './registry';
 import type { QaContext, QaFinding } from './types';
+import { inspectAtlasScene } from './atlas';
 
 type StandardMaterial = THREE.MeshStandardMaterial & {
   isMeshStandardMaterial?: boolean;
@@ -276,6 +277,7 @@ export function inspectPortableSceneMaterials(
       }
     }
   });
+  findings.push(...inspectAtlasScene(scene).findings);
   return findings;
 }
 

package/src/qa/skin-integrity.ts

@@ -0,0 +1,291 @@
+import * as THREE from 'three';
+import type { QaFinding } from './types';
+
+/** Source serialization invariants, independent of style, body plan or optional QA policy. */
+export interface SkinIntegrityInspectionV1 {
+  schemaVersion: 1;
+  findings: QaFinding[];
+  meshesChecked: number;
+  verticesChecked: number;
+  truncated: boolean;
+  /** Current posed world-space bounds only; not a whole-animation envelope. */
+  bounds: { nodePath: string; min: [number, number, number]; max: [number, number, number] }[];
+}
+
+const MAX_FINDINGS = 64;
+const WEIGHT_TOLERANCE = 1e-5;
+type Attribute = THREE.BufferAttribute | THREE.InterleavedBufferAttribute;
+
+function validAttribute(a: Attribute | undefined, count: number, size: number): a is Attribute {
+  if (!a || a.itemSize !== size || a.count !== count || !Number.isSafeInteger(count) || count < 1)
+    return false;
+  if ('isInterleavedBufferAttribute' in a) {
+    return (
+      Number.isSafeInteger(a.data.stride) &&
+      a.data.stride >= size &&
+      Number.isSafeInteger(a.offset) &&
+      a.offset >= 0 &&
+      a.offset + size <= a.data.stride &&
+      (count - 1) * a.data.stride + a.offset + size <= a.array.length
+    );
+  }
+  return count * size <= a.array.length;
+}
+
+function finiteAffine(matrix: THREE.Matrix4 | undefined): matrix is THREE.Matrix4 {
+  const e = matrix?.elements;
+  return (
+    !!e &&
+    e.length === 16 &&
+    [...e].every((v) => Number.isFinite(v) && Number.isFinite(Math.fround(v))) &&
+    // Inverting valid TRS matrices can introduce double-precision roundoff.
+    // Judge the affine row at the Float32 precision used by the exported data.
+    Math.fround(e[3]!) === 0 &&
+    Math.fround(e[7]!) === 0 &&
+    Math.fround(e[11]!) === 0 &&
+    Math.fround(e[15]!) === 1
+  );
+}
+
+/** Read logical attributes and transforms without updating or repairing the caller's scene. */
+export function inspectSkinIntegrity(root: THREE.Object3D): SkinIntegrityInspectionV1 {
+  const result: SkinIntegrityInspectionV1 = {
+    schemaVersion: 1,
+    findings: [],
+    meshesChecked: 0,
+    verticesChecked: 0,
+    truncated: false,
+    bounds: [],
+  };
+  const paths = new Map<THREE.Object3D, string>();
+  const pending: [THREE.Object3D, string, number][] = [[root, '', 0]];
+  while (pending.length) {
+    const [node, parent, sibling] = pending.pop()!;
+    if (paths.has(node)) continue;
+    const segment = `${(node.name || node.type).slice(0, 80)}[${sibling}]`;
+    const path = (parent ? `${parent}/${segment}` : segment).slice(-800);
+    paths.set(node, path);
+    for (let i = node.children.length - 1; i >= 0; i--) pending.push([node.children[i]!, path, i]);
+  }
+  const worlds = new Map<THREE.Object3D, THREE.Matrix4>();
+  function world(node: THREE.Object3D): THREE.Matrix4 | undefined {
+    const chain: THREE.Object3D[] = [],
+      seen = new Set<THREE.Object3D>();
+    let cursor: THREE.Object3D | null = node;
+    while (cursor && !worlds.has(cursor)) {
+      if (seen.has(cursor)) return undefined;
+      seen.add(cursor);
+      chain.push(cursor);
+      cursor = cursor.parent;
+    }
+    while (chain.length) {
+      const n = chain.pop()!;
+      const local = n.matrixAutoUpdate
+        ? new THREE.Matrix4().compose(n.position, n.quaternion, n.scale)
+        : n.matrix.clone();
+      const parent = n.parent ? worlds.get(n.parent) : undefined;
+      const value =
+        n.matrixWorldAutoUpdate === false
+          ? n.matrixWorld.clone()
+          : parent
+            ? new THREE.Matrix4().multiplyMatrices(parent, local)
+            : local;
+      worlds.set(n, value);
+    }
+    return worlds.get(node);
+  }
+  for (const [node, nodePath] of paths) {
+    const mesh = node as THREE.SkinnedMesh;
+    if (!mesh.isSkinnedMesh) continue;
+    if (result.findings.length >= MAX_FINDINGS) {
+      result.truncated = true;
+      break;
+    }
+    result.meshesChecked++;
+    const start = result.findings.length;
+    const add = (
+      code: string,
+      message: string,
+      attribute?: string,
+      measurement?: QaFinding['measurement'],
+    ) => {
+      if (result.findings.length >= MAX_FINDINGS) {
+        result.truncated = true;
+        return;
+      }
+      result.findings.push({
+        code,
+        disposition: 'block',
+        dimension: 'exportIntegrity',
+        profile: 'skin.source-integrity.v1',
+        message,
+        affected: { node: mesh.name.slice(0, 160), nodePath, ...(attribute ? { attribute } : {}) },
+        ...(measurement ? { measurement } : {}),
+        repairText:
+          'Rebuild the named binding at its intended rest pose. Keep bone order, inverse bind matrices and four influence lanes aligned with every final vertex; unwrap or change topology before binding. Do not repair invalid indices by normalizing weights.',
+      });
+    };
+    const skeleton = mesh.skeleton,
+      bones = skeleton?.bones;
+    if (!bones?.length || !Array.isArray(bones)) {
+      add('SKIN_SKELETON', 'Skinned mesh requires a nonempty skeleton in the exported hierarchy.');
+      continue;
+    }
+    const unique = new Set<THREE.Bone>();
+    for (let joint = 0; joint < bones.length; joint++) {
+      const bone = bones[joint];
+      if (!bone?.isObject3D || !paths.has(bone) || unique.has(bone)) {
+        add(
+          'SKIN_JOINT_MEMBERSHIP',
+          `Joint ${joint} (${JSON.stringify(bone?.name?.slice(0, 160) ?? 'missing')}) must be a distinct node inside the exported hierarchy.`,
+          `joints[${joint}]`,
+        );
+      }
+      if (bone) unique.add(bone);
+      if (!finiteAffine(skeleton.boneInverses?.[joint])) {
+        add(
+          'SKIN_INVERSE_BIND',
+          `Joint ${joint} (${JSON.stringify(bone?.name?.slice(0, 160) ?? 'missing')}) requires a finite affine inverse bind matrix.`,
+          `boneInverses[${joint}]`,
+        );
+      }
+      if (result.truncated) break;
+    }
+    if (
+      !finiteAffine(mesh.bindMatrix) ||
+      !Number.isFinite(mesh.bindMatrix.determinant()) ||
+      mesh.bindMatrix.determinant() === 0 ||
+      ![THREE.AttachedBindMode, THREE.DetachedBindMode].includes(mesh.bindMode)
+    ) {
+      add(
+        'SKIN_BIND_MATRIX',
+        'Mesh requires a finite invertible affine bind matrix and an attached or detached bind mode.',
+        'bindMatrix',
+      );
+    }
+    const position = mesh.geometry?.getAttribute('position'),
+      count = position?.count ?? 0;
+    const indices = mesh.geometry?.getAttribute('skinIndex'),
+      weights = mesh.geometry?.getAttribute('skinWeight');
+    if (
+      !validAttribute(position, count, 3) ||
+      !validAttribute(indices, count, 4) ||
+      indices.normalized ||
+      !validAttribute(weights, count, 4)
+    ) {
+      add(
+        'SKIN_ATTRIBUTES',
+        'Skin requires xyz positions and four non-normalized joint indices and four weights per final vertex, backed by complete buffers.',
+        'skinIndex/skinWeight',
+      );
+      continue;
+    }
+    const invalid = new Map<
+      string,
+      { count: number; first: number; last: number; attribute: string }
+    >();
+    const bad = (code: string, vertex: number, attribute: string) => {
+      const row = invalid.get(code);
+      if (row) {
+        if (row.last !== vertex) row.count++;
+        row.last = vertex;
+      } else invalid.set(code, { count: 1, first: vertex, last: vertex, attribute });
+    };
+    for (let vertex = 0; vertex < count; vertex++) {
+      let sum = 0;
+      for (let lane = 0; lane < 4; lane++) {
+        const index = indices.getComponent(vertex, lane),
+          weight = weights.getComponent(vertex, lane);
+        if (!Number.isInteger(index) || index < 0 || index >= bones.length)
+          bad('SKIN_JOINT_INDEX', vertex, 'skinIndex');
+        if (!Number.isFinite(weight) || weight < 0 || weight > 1)
+          bad('SKIN_WEIGHT_VALUE', vertex, 'skinWeight');
+        sum += weight;
+      }
+      if (!Number.isFinite(sum) || Math.abs(sum - 1) > WEIGHT_TOLERANCE)
+        bad('SKIN_WEIGHT_SUM', vertex, 'skinWeight');
+    }
+    result.verticesChecked += count;
+    for (const [code, row] of invalid) {
+      const why =
+        code === 'SKIN_JOINT_INDEX'
+          ? 'indices must address the skeleton, including zero-weight lanes'
+          : code === 'SKIN_WEIGHT_SUM'
+            ? `weights must sum to one within ${WEIGHT_TOLERANCE}`
+            : 'weights must be finite values in [0,1]';
+      add(
+        code,
+        `Invalid ${row.attribute} at vertex range ${row.first}..${row.last} (${row.count} affected vertices): ${why}.`,
+        row.attribute,
+        {
+          name: 'invalidSkinVertices',
+          actual: row.count,
+          expected: 0,
+          breakdown: { firstVertex: row.first, lastVertex: row.last },
+        },
+      );
+    }
+    if (result.findings.length !== start) continue;
+    const meshWorld = world(mesh);
+    if (!finiteAffine(meshWorld)) {
+      add('SKIN_POSE_TRANSFORM', 'Current mesh world transform must be finite and affine.');
+      continue;
+    }
+    const inverse =
+      mesh.bindMode === THREE.AttachedBindMode
+        ? meshWorld.clone().invert()
+        : mesh.bindMatrix.clone().invert();
+    const matrices: THREE.Matrix4[] = [];
+    for (let joint = 0; joint < bones.length; joint++) {
+      const boneWorld = world(bones[joint]!);
+      if (!finiteAffine(boneWorld)) {
+        add(
+          'SKIN_POSE_TRANSFORM',
+          `Current transform for joint ${joint} must be finite and affine.`,
+          `joints[${joint}]`,
+        );
+        break;
+      }
+      matrices.push(
+        new THREE.Matrix4()
+          .multiplyMatrices(boneWorld, skeleton.boneInverses[joint]!)
+          .multiply(mesh.bindMatrix),
+      );
+    }
+    if (result.findings.length !== start) continue;
+    const base = new THREE.Vector3(),
+      posed = new THREE.Vector3(),
+      temp = new THREE.Vector3(),
+      box = new THREE.Box3();
+    for (let vertex = 0; vertex < count; vertex++) {
+      // Mesh's implementation evaluates morphs but does not invoke the unsafe skin path.
+      THREE.Mesh.prototype.getVertexPosition.call(mesh, vertex, base);
+      posed.set(0, 0, 0);
+      for (let lane = 0; lane < 4; lane++) {
+        const weight = weights.getComponent(vertex, lane);
+        if (weight !== 0)
+          posed.addScaledVector(
+            temp.copy(base).applyMatrix4(matrices[indices.getComponent(vertex, lane)]!),
+            weight,
+          );
+      }
+      posed.applyMatrix4(inverse).applyMatrix4(meshWorld);
+      if (
+        !Number.isFinite(Math.fround(posed.x)) ||
+        !Number.isFinite(Math.fround(posed.y)) ||
+        !Number.isFinite(Math.fround(posed.z))
+      ) {
+        add(
+          'SKIN_POSED_VERTEX',
+          `Current deformed vertex ${vertex} is not finite and Float32-representable. Check positions, morphs and weighted joint transforms.`,
+          `position[${vertex}]`,
+        );
+        break;
+      }
+      box.expandByPoint(posed);
+    }
+    if (result.findings.length === start)
+      result.bounds.push({ nodePath, min: box.min.toArray(), max: box.max.toArray() });
+  }
+  return result;
+}

package/src/render-service-host.ts

@@ -248,7 +248,6 @@ export async function startLocalRenderService(
     stderr = `${stderr}${chunk.toString()}`.slice(-2_000);
   });
   const deadline = Date.now() + budget;
-  let exitedAt: number | undefined;
   try {
     while (Date.now() < deadline) {
       const fresh = await inspectLocalRenderService(url, dir, 1_000);
@@ -258,11 +257,10 @@ export async function startLocalRenderService(
       const exited = windowsLaunch
         ? windowsLaunch.hasExited()
         : running.exitCode !== null || running.signalCode !== null;
-      if (exited) exitedAt ??= Date.now();
-      // Another client may have won the socket while this child lost its bind. Give
-      // that listener a bounded health warmup, and join only after full verification.
-      // A failed spawn has no such race; absent/unknown never count as success.
-      if (spawnError || (exitedAt !== undefined && Date.now() - exitedAt >= 1500))
+      // A competing child can win the socket while this one exits after losing
+      // its bind. An unknown listener gets the same startup deadline as our child;
+      // only verified health permits joining. An exited child with no listener fails.
+      if (spawnError || (exited && fresh.kind === 'absent'))
         throw new Error(
           `render service exited during startup${spawnError ? `: ${spawnError.message}` : ''}${stderr.trim() ? `: ${stderr.trim()}` : windowsLaunch ? '; launch the renderer manually to inspect native-driver errors' : ''}`,
         );