koota-kit 0.8.7 → 0.9.0

package/examples/coordination-proof/fixture.mjs

@@ -0,0 +1,97 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+
+import { assertMesh, sourceFaceIds } from "./mesh-input.mjs";
+export { assertMesh, sourceFaceIds } from "./mesh-input.mjs";
+
+const types = {
+  Float32Array: [Float32Array, 4, "getFloat32"],
+  Uint32Array: [Uint32Array, 4, "getUint32"],
+  Uint16Array: [Uint16Array, 2, "getUint16"],
+  Uint8Array: [Uint8Array, 1, "getUint8"],
+};
+
+/** Decode independently of host endianness and retain no aliases into file bytes. */
+export function decodeArray(bytes, descriptor) {
+  const type = types[descriptor.type];
+  if (!type || !Number.isSafeInteger(descriptor.length) || descriptor.length < 0) {
+    throw new TypeError("fixture: invalid array descriptor");
+  }
+  const [Constructor, width, getter] = type;
+  if (
+    bytes.byteLength !== descriptor.byteLength ||
+    bytes.byteLength !== descriptor.length * width
+  ) {
+    throw new Error("fixture: array byte length mismatch");
+  }
+  const hash = createHash("sha256").update(bytes).digest("hex");
+  if (hash !== descriptor.sha256) throw new Error("fixture: SHA256 mismatch");
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const array = new Constructor(descriptor.length);
+  for (let index = 0; index < array.length; index += 1) {
+    array[index] = view[getter](index * width, true);
+    if (!Number.isFinite(array[index])) throw new Error("fixture: nonfinite array value");
+  }
+  return array;
+}
+
+/** Fixture transport only: this does not evaluate poses or claim a live HK adapter. */
+export async function loadFigureFixture(directory) {
+  const manifestBytes = await readFile(join(directory, "fixture.json"));
+  const manifest = JSON.parse(manifestBytes.toString("utf8"));
+  if (
+    manifest.format !== 1 ||
+    manifest.unit !== "metre" ||
+    manifest.byteOrder !== "little-endian"
+  ) {
+    throw new Error("fixture: unsupported format, unit or byte order");
+  }
+  const inputs = [
+    { file: "fixture.json", sha256: createHash("sha256").update(manifestBytes).digest("hex") },
+  ];
+  async function load(descriptor) {
+    if (basename(descriptor.file) !== descriptor.file) throw new Error("fixture: unsafe file name");
+    const array = decodeArray(await readFile(join(directory, descriptor.file)), descriptor);
+    inputs.push({ file: descriptor.file, sha256: descriptor.sha256 });
+    return array;
+  }
+  const parts = [];
+  for (const part of manifest.parts) {
+    const rest = await load(part.arrays.rest);
+    const restNormals = await load(part.arrays.restNormals);
+    const full = await load(part.arrays.fullIndex);
+    const visible = await load(part.arrays.index);
+    assertMesh(rest, full, part.vertexCount);
+    assertMesh(rest, visible, part.vertexCount);
+    if (full.length / 3 !== part.fullTriangleCount || visible.length / 3 !== part.triangleCount) {
+      throw new Error("fixture: declared topology count mismatch");
+    }
+    if (restNormals.length !== rest.length) throw new Error("fixture: malformed normals");
+    const visibleFaceIds = sourceFaceIds(full, visible);
+    const poses = {};
+    for (const pose of manifest.poses) {
+      if (pose.grounding !== "already applied once to every part; do not apply again") {
+        throw new Error("fixture: unknown grounding contract");
+      }
+      const source = pose.parts.find((candidate) => candidate.id === part.id);
+      if (!source) throw new Error("fixture: pose part missing");
+      const positions = await load(source.positions);
+      const normals = await load(source.normals);
+      assertMesh(positions, full, part.vertexCount);
+      if (normals.length !== positions.length) throw new Error("fixture: malformed posed normals");
+      poses[pose.name] = { positions, normals };
+    }
+    parts.push({
+      id: part.id,
+      geometryHash: part.geometryHash,
+      rest,
+      restNormals,
+      full,
+      visible,
+      visibleFaceIds,
+      poses,
+    });
+  }
+  return { manifest, parts, inputs };
+}

package/examples/coordination-proof/mesh-input.mjs

@@ -0,0 +1,27 @@
+export function assertMesh(positions, indices, vertexCount) {
+  if (positions.length !== vertexCount * 3 || indices.length % 3 !== 0) {
+    throw new Error("fixture: malformed mesh layout");
+  }
+  for (const index of indices) {
+    if (!Number.isInteger(index) || index < 0 || index >= vertexCount) {
+      throw new Error("fixture: index out of range");
+    }
+  }
+}
+
+/** Preserve authored full-source face ordinals even for render-visible selection. */
+export function sourceFaceIds(full, visible) {
+  const faces = new Map();
+  for (let offset = 0; offset < full.length; offset += 3) {
+    const key = `${full[offset]},${full[offset + 1]},${full[offset + 2]}`;
+    if (faces.has(key)) throw new Error("fixture: duplicate full source face");
+    faces.set(key, offset / 3);
+  }
+  const selected = new Uint32Array(visible.length / 3);
+  for (let offset = 0; offset < visible.length; offset += 3) {
+    const id = faces.get(`${visible[offset]},${visible[offset + 1]},${visible[offset + 2]}`);
+    if (id === undefined) throw new Error("fixture: visible face absent from full source");
+    selected[offset / 3] = id;
+  }
+  return selected;
+}

package/examples/coordination-proof/open-surface.mjs

@@ -0,0 +1,195 @@
+export class NumericalOracleRangeError extends RangeError {
+  constructor() {
+    super("proof: numerical oracle range exceeded");
+    this.name = "NumericalOracleRangeError";
+  }
+}
+const MIN_NORMAL = 2 ** -1022;
+const checked = (value) => {
+  if (!Number.isFinite(value) || (value !== 0 && Math.abs(value) < MIN_NORMAL))
+    throw new NumericalOracleRangeError();
+  return value;
+};
+const sum = (...values) => values.reduce((total, value) => checked(total + value), 0);
+const product = (left, right) => {
+  const value = checked(left * right);
+  if (value === 0 && left !== 0 && right !== 0) throw new NumericalOracleRangeError();
+  return value;
+};
+const quotient = (numerator, denominator) => {
+  if (denominator === 0) throw new NumericalOracleRangeError();
+  const value = checked(numerator / denominator);
+  if (value === 0 && numerator !== 0) throw new NumericalOracleRangeError();
+  return value;
+};
+const point = (x, y, z) => Object.freeze({ x: checked(x), y: checked(y), z: checked(z) });
+const sub = (a, b) => [checked(a.x - b.x), checked(a.y - b.y), checked(a.z - b.z)];
+const dot = (a, b) => sum(product(a[0], b[0]), product(a[1], b[1]), product(a[2], b[2]));
+
+export const IDENTITY = Object.freeze([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
+
+/** Column-major affine transformation, applied to every vertex before ranking. */
+export function worldPositions(positions, matrix) {
+  if (
+    matrix.length !== 16 ||
+    matrix.some((value) => !Number.isFinite(value)) ||
+    matrix[3] !== 0 ||
+    matrix[7] !== 0 ||
+    matrix[11] !== 0 ||
+    matrix[15] !== 1
+  ) {
+    throw new Error("proof: expected a finite column-major affine transform");
+  }
+  const output = new Float64Array(positions.length);
+  for (let i = 0; i < positions.length; i += 3) {
+    const [x, y, z] = positions.subarray(i, i + 3);
+    output[i] = sum(
+      product(matrix[0], x),
+      product(matrix[4], y),
+      product(matrix[8], z),
+      matrix[12],
+    );
+    output[i + 1] = sum(
+      product(matrix[1], x),
+      product(matrix[5], y),
+      product(matrix[9], z),
+      matrix[13],
+    );
+    output[i + 2] = sum(
+      product(matrix[2], x),
+      product(matrix[6], y),
+      product(matrix[10], z),
+      matrix[14],
+    );
+  }
+  if (output.some((value) => !Number.isFinite(value))) throw new Error("proof: transform overflow");
+  return output;
+}
+
+export function indexedBounds(positions, indices) {
+  if (indices.length === 0) throw new Error("proof: empty topology has no certified bounds");
+  const min = [Infinity, Infinity, Infinity];
+  const max = [-Infinity, -Infinity, -Infinity];
+  for (const index of indices) {
+    for (let axis = 0; axis < 3; axis += 1) {
+      min[axis] = Math.min(min[axis], positions[index * 3 + axis]);
+      max[axis] = Math.max(max[axis], positions[index * 3 + axis]);
+    }
+  }
+  return Object.freeze({ min: point(...min), max: point(...max) });
+}
+
+// Bounded reference oracle only; deliberately exhaustive, with no cache or BVH.
+function closestTriangle(p, a, b, c) {
+  const ab = sub(b, a),
+    ac = sub(c, a),
+    ap = sub(p, a);
+  const d1 = dot(ab, ap),
+    d2 = dot(ac, ap);
+  if (d1 <= 0 && d2 <= 0) return [1, 0, 0];
+  const bp = sub(p, b),
+    d3 = dot(ab, bp),
+    d4 = dot(ac, bp);
+  if (d3 >= 0 && d4 <= d3) return [0, 1, 0];
+  const vc = checked(product(d1, d4) - product(d3, d2));
+  if (vc <= 0 && d1 >= 0 && d3 <= 0) {
+    const v = quotient(d1, checked(d1 - d3));
+    return [checked(1 - v), v, 0];
+  }
+  const cp = sub(p, c),
+    d5 = dot(ab, cp),
+    d6 = dot(ac, cp);
+  if (d6 >= 0 && d5 <= d6) return [0, 0, 1];
+  const vb = checked(product(d5, d2) - product(d1, d6));
+  if (vb <= 0 && d2 >= 0 && d6 <= 0) {
+    const w = quotient(d2, checked(d2 - d6));
+    return [checked(1 - w), 0, w];
+  }
+  const va = checked(product(d3, d6) - product(d5, d4));
+  if (va <= 0 && d4 - d3 >= 0 && d5 - d6 >= 0) {
+    const numerator = checked(d4 - d3);
+    const w = quotient(numerator, sum(numerator, checked(d5 - d6)));
+    return [0, checked(1 - w), w];
+  }
+  const denominator = sum(va, vb, vc);
+  if (denominator <= 0) throw new NumericalOracleRangeError();
+  const inverse = quotient(1, denominator),
+    v = product(vb, inverse),
+    w = product(vc, inverse);
+  return [sum(1, -v, -w), v, w];
+}
+
+export function nearestOpenSurface(positions, indices, query, sourceFaceIds) {
+  let best;
+  for (let offset = 0; offset < indices.length; offset += 3) {
+    const vertices = [0, 1, 2].map((corner) => {
+      const i = indices[offset + corner] * 3;
+      return point(positions[i], positions[i + 1], positions[i + 2]);
+    });
+    const [a, b, c] = vertices,
+      ab = sub(b, a),
+      ac = sub(c, a);
+    const cross = [
+      checked(product(ab[1], ac[2]) - product(ab[2], ac[1])),
+      checked(product(ab[2], ac[0]) - product(ab[0], ac[2])),
+      checked(product(ab[0], ac[1]) - product(ab[1], ac[0])),
+    ];
+    const area = checked(Math.hypot(...cross));
+    let barycentric;
+    if (area === 0) {
+      const candidates = [
+        [0, 1],
+        [1, 2],
+        [2, 0],
+      ].map(([start, end]) => {
+        const edge = sub(vertices[end], vertices[start]);
+        const length = dot(edge, edge);
+        const t =
+          length === 0
+            ? 0
+            : Math.max(0, Math.min(1, quotient(dot(sub(query, vertices[start]), edge), length)));
+        const weights = [0, 0, 0];
+        weights[start] = checked(1 - t);
+        weights[end] = t;
+        const projected = point(
+          ...["x", "y", "z"].map((axis) =>
+            sum(
+              vertices[start][axis],
+              product(t, checked(vertices[end][axis] - vertices[start][axis])),
+            ),
+          ),
+        );
+        return { weights, distance: checked(Math.hypot(...sub(query, projected))) };
+      });
+      candidates.sort((left, right) => left.distance - right.distance);
+      barycentric = candidates[0].weights;
+    } else {
+      // Gram-region classification squares the aspect ratio. Below this
+      // conservative roundoff margin, this bounded oracle cannot certify it.
+      const longestEdge = checked(
+        Math.max(Math.hypot(...ab), Math.hypot(...ac), Math.hypot(...sub(c, b))),
+      );
+      const quality = quotient(quotient(area, longestEdge), longestEdge);
+      if (quality <= Math.sqrt(64 * Number.EPSILON)) throw new NumericalOracleRangeError();
+      barycentric = closestTriangle(query, a, b, c);
+    }
+    const hit = point(
+      ...["x", "y", "z"].map((axis) =>
+        sum(...vertices.map((vertex, corner) => product(vertex[axis], barycentric[corner]))),
+      ),
+    );
+    const distance = checked(Math.hypot(...sub(query, hit)));
+    const face = sourceFaceIds?.[offset / 3] ?? offset / 3;
+    if (!best || distance < best.distance || (distance === best.distance && face < best.face)) {
+      best = Object.freeze({
+        face,
+        point: hit,
+        distance,
+        barycentric: Object.freeze(barycentric),
+        geometricNormal:
+          area === 0 ? undefined : point(...cross.map((value) => quotient(value, area))),
+      });
+    }
+  }
+  return best;
+}

package/examples/coordination-proof/prepare.mjs

@@ -0,0 +1,82 @@
+import assert from "node:assert/strict";
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { loadFigureFixture } from "./fixture.mjs";
+import { IDENTITY, indexedBounds, nearestOpenSurface, worldPositions } from "./open-surface.mjs";
+
+const directory = process.argv[2];
+if (!directory)
+  throw new Error(
+    "Usage: node examples/coordination-proof/prepare.mjs <fixture-directory> [receipt.json]",
+  );
+const figure = await loadFigureFixture(directory);
+const report = {
+  scope: "copied-buffer/open-surface preparation; no live producer or rendered parity claim",
+  inputs: figure.inputs,
+  parts: [],
+};
+for (const part of figure.parts) {
+  assert.equal(part.poses.relaxed.positions.length, part.rest.length);
+  assert.notDeepEqual(part.poses.relaxed.positions, part.poses.overhead.positions);
+  const before = part.poses.relaxed.positions[0];
+  const copied = new Float32Array(part.poses.relaxed.positions);
+  copied[0] += 1;
+  assert.equal(part.poses.relaxed.positions[0], before);
+  const positions = worldPositions(part.poses.relaxed.positions, IDENTITY);
+  const bounds = indexedBounds(positions, part.full);
+  const face = 0;
+  const corners = [0, 1, 2].map((corner) => part.full[face * 3 + corner] * 3);
+  const centroid = Object.fromEntries(
+    ["x", "y", "z"].map((axis, index) => [
+      axis,
+      corners.reduce((sum, offset) => sum + positions[offset + index], 0) / 3,
+    ]),
+  );
+  const witness = nearestOpenSurface(positions, part.full, centroid);
+  assert.ok(witness.distance < 1e-12);
+  assert.ok(Math.abs(witness.barycentric.reduce((sum, value) => sum + value, 0) - 1) < 1e-12);
+  let hiddenWitness;
+  if (part.full.length !== part.visible.length) {
+    const visibleIds = new Set(part.visibleFaceIds);
+    const hiddenFace = Array.from({ length: part.full.length / 3 }, (_, face) => face).find(
+      (face) => !visibleIds.has(face),
+    );
+    const offsets = [0, 1, 2].map((corner) => part.full[hiddenFace * 3 + corner] * 3);
+    const point = Object.fromEntries(
+      ["x", "y", "z"].map((axis, index) => [
+        axis,
+        offsets.reduce((sum, offset) => sum + positions[offset + index], 0) / 3,
+      ]),
+    );
+    const full = nearestOpenSurface(positions, part.full, point);
+    const visible = nearestOpenSurface(positions, part.visible, point, part.visibleFaceIds);
+    assert.ok(full.distance < 1e-12);
+    assert.ok(visible.distance > 1e-12);
+    hiddenWitness = { hiddenFace, point, full, visible };
+  }
+  report.parts.push({
+    id: part.id,
+    fullTriangles: part.full.length / 3,
+    visibleTriangles: part.visible.length / 3,
+    hiddenTriangles: (part.full.length - part.visible.length) / 3,
+    bounds,
+    witness,
+    hiddenWitness,
+    grounding: "posed input bytes used unchanged; no additional lift",
+  });
+}
+assert.equal(report.parts[0].fullTriangles, 107024);
+assert.equal(report.parts[0].visibleTriangles, 80112);
+assert.equal(report.parts[1].fullTriangles, 66688);
+assert.equal(report.parts[1].visibleTriangles, 66688);
+if (process.argv[3]) {
+  await mkdir(dirname(process.argv[3]), { recursive: true });
+  await writeFile(process.argv[3], `${JSON.stringify(report, null, 2)}\n`);
+}
+console.log(
+  JSON.stringify(
+    { scope: report.scope, inputCount: report.inputs.length, parts: report.parts },
+    null,
+    2,
+  ),
+);

package/examples/coordination-proof/react-inspector.mjs

@@ -0,0 +1,19 @@
+/** Shared raw-koota World inspector; rendering and unmount never own the World. */
+export function createProofInspector({ React, useWorld }) {
+  return function Inspector({ cohort, world, onObservation }) {
+    if (useWorld() !== world) throw new Error("proof: inspector observed a different raw World");
+    const snapshot = React.useSyncExternalStore(
+      cohort.subscribe,
+      cohort.getSnapshot,
+      cohort.getSnapshot,
+    );
+    onObservation?.(snapshot);
+    return React.createElement(
+      "output",
+      null,
+      snapshot.coordination.entries
+        .map((entry) => `${entry.id}:${entry.completed?.revisions.pose ?? "pending"}`)
+        .join(","),
+    );
+  };
+}

package/examples/coordination-proof/react-observer.mjs

@@ -0,0 +1,60 @@
+import assert from "node:assert/strict";
+import { createProofInspector } from "./react-inspector.mjs";
+
+/** A headless mounted observer; neither the component nor its unmount owns the World. */
+export async function observeCommittedUpdate({ registryImport, cohort, world, publish }) {
+  const React = await registryImport("react");
+  const { createRoot } = await registryImport("react-dom/client");
+  const { WorldProvider, useWorld } = await registryImport("koota/react");
+  const { JSDOM } = await registryImport("jsdom");
+  const dom = new JSDOM("<!doctype html><html><body><div id='proof'></div></body></html>");
+  const descriptors = new Map();
+  for (const [name, value] of Object.entries({
+    window: dom.window,
+    document: dom.window.document,
+    IS_REACT_ACT_ENVIRONMENT: true,
+  })) {
+    descriptors.set(name, Object.getOwnPropertyDescriptor(globalThis, name));
+    Object.defineProperty(globalThis, name, { configurable: true, writable: true, value });
+  }
+  const observations = [];
+  const container = dom.window.document.getElementById("proof");
+  const root = createRoot(container);
+  const Inspector = createProofInspector({ React, useWorld });
+  const inspector = React.createElement(Inspector, {
+    cohort,
+    world,
+    onObservation: (snapshot) => observations.push(snapshot),
+  });
+  let unmounted = false;
+  try {
+    await React.act(async () =>
+      root.render(React.createElement(WorldProvider, { world }, inspector)),
+    );
+    const before = container.textContent;
+    const previous = cohort.getSnapshot();
+    await React.act(async () => publish());
+    assert.notEqual(cohort.getSnapshot(), previous);
+    assert.equal(observations.at(-1), cohort.getSnapshot());
+    const after = container.textContent;
+    assert.notEqual(after, before);
+    await React.act(async () => root.unmount());
+    unmounted = true;
+    assert.ok(world.isInitialized);
+    return {
+      before,
+      after,
+      renderCount: observations.length,
+      sameWorld: true,
+      unmountPreservedWorld: true,
+    };
+  } finally {
+    // Clean up an assertion failure before the normal unmount.
+    if (!unmounted) await React.act(async () => root.unmount());
+    dom.window.close();
+    for (const [name, descriptor] of descriptors) {
+      if (descriptor) Object.defineProperty(globalThis, name, descriptor);
+      else delete globalThis[name];
+    }
+  }
+}

package/examples/coordination-proof/registry-import.mjs

@@ -0,0 +1,3 @@
+// Copy beside the private consumer package.json so all imports resolve from its registry install.
+export const registryImport = (specifier) => import(specifier);
+export const registryResolve = (specifier) => import.meta.resolve(specifier);