koota-kit 0.8.8 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.9.0 (2026-10-14)
+
+<!-- Release notes generated using configuration in .github/release.yml at main -->
+
+## What's Changed
+* feat(integration): extract browser-compatible caller adapters by @jbdevprimary in https://github.com/jbcom/koota-kit/pull/80
+
+
+**Full Changelog**: https://github.com/jbcom/koota-kit/compare/v0.8.8...v0.9.0
+
 ## 0.8.8 (2026-10-14)
 
 <!-- Release notes generated using configuration in .github/release.yml at main -->

package/docs/INTEGRATION_PROOF.md

@@ -119,3 +119,40 @@ The pinned 0.8.6 composition uses dense arrays with own indexed entries. The
 prototype-filled sparse-array defect tracked in [issue 68](https://github.com/jbcom/koota-kit/issues/68)
 is outside this legitimate-input proof; this guide does not claim that defect
 has been repaired in the installed release.
+
+## Browser caller boundary
+
+The packed example source has browser-safe siblings, without adding package
+runtime exports or dependencies. `mesh-input.mjs` contains the unchanged mesh
+validation and authored face mapping. `cohort-core.mjs` retains the resource
+ledger and requires synchronous `hashBytes(chunks)` returning lowercase SHA256
+hex. `cohort.mjs` preserves the Node API with `node:crypto`; the fixture disk
+transport and JSDOM observer remain Node-only.
+
+The protocol hashes ordered chunks without delimiters. Typed views contribute
+exactly their buffer offset and byte length in native byte order. Other values
+contribute UTF-8 bytes of unchanged `JSON.stringify`, including insertion order.
+Undefined serialization and cycles reject before hashing. Promise or malformed
+hex results reject before publication; asynchronous Web Crypto is unsuitable.
+
+A private browser caller imports `sha256` from its pinned
+`@noble/hashes/sha2.js` 2.4.0 install and supplies that primitive to
+`createBrowserProofCohort(coordination, specifications, sha256)` in
+`browser-cohort.mjs`. The package itself does not resolve or depend on Noble.
+The caller must compare its actual installed primitive with the original Node
+hashes for empty, ordered multichunk, offset, Unicode and typed-array vectors.
+
+`react-inspector.mjs` supplies the same component to both observers. It checks
+`useWorld()` against the exact raw World and subscribes to the committed cohort.
+`browser-observer.mjs` mounts it in an existing native DOM container using the
+caller's installed React, `createRoot`, raw `WorldProvider` and `useWorld`.
+Its returned cleanup only unmounts React. The private Humanoid route retains
+ownership of its evaluator, producer, rendering and GPU evidence.
+
+Resolve example source from hash-verified physical files in the installed
+registry package, or an explicitly recorded immutable source transport. These
+files are packed caller examples, not runtime export subpaths. No workspace
+alias, additional geometry registry or private fixture publication is needed.
+Browser digest equality, same-World observation and retained leases must be
+verified in the actual browser realm; Node adapter tests alone do not establish
+live rendered acceptance.

package/examples/coordination-proof/browser-cohort.mjs

@@ -0,0 +1,17 @@
+import { createProofCohort as createCoreCohort } from "./cohort-core.mjs";
+export { PROOF_FRAME } from "./cohort-core.mjs";
+
+/** Supply sha256 from the private consumer's pinned @noble/hashes/sha2.js install. */
+export function createBrowserHashBytes(sha256) {
+  return (chunks) => {
+    const hash = sha256.create();
+    for (const chunk of chunks) hash.update(chunk);
+    return Array.from(hash.digest(), (byte) => byte.toString(16).padStart(2, "0")).join("");
+  };
+}
+
+export function createBrowserProofCohort(coordination, specifications, sha256) {
+  return createCoreCohort(coordination, specifications, {
+    hashBytes: createBrowserHashBytes(sha256),
+  });
+}

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

@@ -0,0 +1,24 @@
+import { createProofInspector } from "./react-inspector.mjs";
+
+/** Native DOM mounting on the private caller route; no JSDOM or global replacement. */
+export function mountProofInspector({
+  React,
+  createRoot,
+  WorldProvider,
+  useWorld,
+  container,
+  cohort,
+  world,
+  onObservation,
+}) {
+  const Inspector = createProofInspector({ React, useWorld });
+  const root = createRoot(container);
+  root.render(
+    React.createElement(
+      WorldProvider,
+      { world },
+      React.createElement(Inspector, { cohort, world, onObservation }),
+    ),
+  );
+  return () => root.unmount();
+}

package/examples/coordination-proof/cohort-core.mjs

@@ -0,0 +1,417 @@
+import { assertMesh, sourceFaceIds } from "./mesh-input.mjs";
+import {
+  indexedBounds,
+  nearestOpenSurface,
+  NumericalOracleRangeError,
+  worldPositions,
+} from "./open-surface.mjs";
+
+export const PROOF_FRAME = Object.freeze({
+  id: "caller-proof-world",
+  unit: "metre",
+  metric: "euclidean",
+});
+const freeze = Object.freeze;
+const tuple = (r) => JSON.stringify([r.geometry, r.pose, r.transform]);
+const stampKey = (r, s) =>
+  JSON.stringify([
+    r.identity.sourceId,
+    r.identity.instanceId,
+    r.identity.partId,
+    r.identity.registration.id,
+    r.identity.registration.generation,
+    [r.frame.id, r.frame.unit, r.frame.metric],
+    s,
+    r.topology[s].id,
+    [r.revisions.geometry, r.revisions.topology, r.revisions.pose, r.revisions.transform],
+  ]);
+/** Preserve the Node reference protocol: ordered exact views and unchanged JSON UTF-8. */
+export function hashValues(hashBytes, ...values) {
+  if (typeof hashBytes !== "function") throw new TypeError("proof: synchronous hashBytes required");
+  const encoder = new TextEncoder();
+  const chunks = values.map((value) => {
+    if (ArrayBuffer.isView(value))
+      return new Uint8Array(value.buffer, value.byteOffset, value.byteLength).slice();
+    const json = JSON.stringify(value);
+    if (json === undefined) throw new TypeError("proof: value has no JSON serialization");
+    return encoder.encode(json);
+  });
+  const digest = hashBytes(chunks);
+  if (typeof digest !== "string" || !/^[0-9a-f]{64}$/.test(digest))
+    throw new TypeError("proof: hashBytes must return synchronous lowercase SHA256 hex");
+  return digest;
+}
+function sameIndexBytes(left, right) {
+  if (left.length !== right.length || left.byteLength !== right.byteLength) return false;
+  const a = new Uint8Array(left.buffer, left.byteOffset, left.byteLength);
+  const b = new Uint8Array(right.buffer, right.byteOffset, right.byteLength);
+  for (let index = 0; index < a.length; index += 1) if (a[index] !== b[index]) return false;
+  return true;
+}
+
+/** Test-only caller resource ledger; coordination snapshots are the sole commit boundary. */
+export function createProofCohort(coordination, specifications, { hashBytes } = {}) {
+  if (typeof hashBytes !== "function") throw new TypeError("proof: synchronous hashBytes required");
+  const hashArrays = (...values) => hashValues(hashBytes, ...values);
+  const models = new Map(),
+    views = new WeakMap();
+  let busy = false,
+    disposalStarted = false;
+  function current(m) {
+    return (
+      coordination.getRegistration(m.id) === m.token && coordination.getEntity(m.id) === m.entity
+    );
+  }
+  function selectedVersion(m, s) {
+    const e = s.entries.find((e) => e.id === m.id);
+    return e?.completed ? m.versions.get(tuple(e.completed.revisions)) : undefined;
+  }
+  function collect() {
+    if (busy) return;
+    const s = coordination.getSnapshot();
+    for (const m of models.values()) {
+      const active = current(m) ? selectedVersion(m, s) : undefined;
+      for (const [id, v] of m.versions) if (v !== active && v.leases === 0) m.versions.delete(id);
+    }
+  }
+  function view(s) {
+    function invalid() {
+      const cached = views.get(s);
+      if (cached?.valid === false) return cached;
+      const result = freeze({ coordination: s, records: freeze([]), valid: false });
+      views.set(s, result);
+      return result;
+    }
+    if ([...models.values()].some((m) => !m.removed && !current(m))) return invalid();
+    // Cached metadata does not lease buffers; verify retained versions before using it.
+    if (
+      [...models.values()].some(
+        (m) =>
+          !m.removed &&
+          (!s.entries.find((entry) => entry.id === m.id)?.completed || !selectedVersion(m, s)),
+      )
+    )
+      return invalid();
+    const cached = views.get(s);
+    if (cached?.valid === true) return cached;
+    const records = [];
+    for (const m of models.values()) {
+      if (m.removed) continue;
+      const v = selectedVersion(m, s);
+      if (s.entries.find((entry) => entry.id === m.id)?.completed && !v) {
+        return invalid();
+      }
+      if (v) records.push(...v.parts.map((p) => p.record));
+    }
+    records.sort(
+      (a, b) =>
+        Number(stampKey(a, "full") > stampKey(b, "full")) -
+        Number(stampKey(a, "full") < stampKey(b, "full")),
+    );
+    const result = freeze({ coordination: s, records: freeze(records), valid: true });
+    views.set(s, result);
+    return result;
+  }
+  function prepare(m, u) {
+    if (!current(m)) throw new Error("proof: stale owned registration lifetime");
+    const revisions = freeze({ ...u.revisions }),
+      previous = selectedVersion(m, coordination.getSnapshot());
+    for (const epoch of ["geometry", "topology", "pose", "transform"]) {
+      if (
+        !Number.isSafeInteger(revisions[epoch]) ||
+        revisions[epoch] < 0 ||
+        (previous && revisions[epoch] < previous.revisions[epoch])
+      )
+        throw new Error(`proof: invalid or regressing ${epoch} epoch`);
+    }
+    if (
+      previous &&
+      revisions.topology !== previous.revisions.topology &&
+      revisions.geometry === previous.revisions.geometry
+    )
+      throw new Error("proof: topology replacement must advance geometry epoch");
+    const frame = freeze({ ...(u.frame ?? m.frame ?? PROOF_FRAME) });
+    if (
+      typeof frame.id !== "string" ||
+      frame.id.length === 0 ||
+      typeof frame.unit !== "string" ||
+      frame.unit.length === 0 ||
+      frame.metric !== "euclidean"
+    )
+      throw new Error("proof: invalid declared frame");
+    const partIds = new Set();
+    const parts = u.parts.map((p) => {
+      if (!p.id || partIds.has(p.id) || !p.fullTopologyId || !p.visibleTopologyId)
+        throw new Error("proof: invalid or duplicate part/topology identity");
+      partIds.add(p.id);
+      assertMesh(p.positions, p.full, p.positions.length / 3);
+      assertMesh(p.positions, p.visible, p.positions.length / 3);
+      const full = new Uint32Array(p.full),
+        visible = new Uint32Array(p.visible),
+        sourcePositions = new Float32Array(p.positions);
+      assertMesh(sourcePositions, full, sourcePositions.length / 3);
+      assertMesh(sourcePositions, visible, sourcePositions.length / 3);
+      const previousPart = previous?.parts.find((part) => part.record.identity.partId === p.id);
+      // Reuse only a committed same-lifetime part after validating fresh copies.
+      const canReuse =
+        previousPart &&
+        previous.revisions.topology === revisions.topology &&
+        previousPart.record.identity.sourceId === m.sourceId &&
+        previousPart.record.identity.instanceId === m.instanceId &&
+        previousPart.record.identity.registration.generation === m.providerGeneration &&
+        previousPart.record.topology.full.id === p.fullTopologyId &&
+        previousPart.record.topology.visible.id === p.visibleTopologyId &&
+        sameIndexBytes(previousPart.full, full) &&
+        sameIndexBytes(previousPart.visible, visible);
+      const visibleFaces = canReuse ? previousPart.visibleFaces : sourceFaceIds(full, visible),
+        positions = worldPositions(sourcePositions, u.toWorld);
+      const identity = freeze({
+        sourceId: m.sourceId,
+        instanceId: m.instanceId,
+        partId: p.id,
+        registration: freeze({ id: m.id, generation: m.providerGeneration }),
+      });
+      const record = freeze({
+        identity,
+        frame,
+        revisions,
+        topology: freeze({
+          full: freeze({
+            id: p.fullTopologyId,
+            bounds: indexedBounds(positions, full),
+            enclosesSurface: true,
+          }),
+          visible: freeze({
+            id: p.visibleTopologyId,
+            bounds: indexedBounds(positions, visible),
+            enclosesSurface: true,
+          }),
+        }),
+        capabilities: freeze(p.nearestSurface === false ? [] : ["nearest-surface"]),
+      });
+      return {
+        record,
+        sourcePositions,
+        positions,
+        full,
+        visible,
+        visibleFaces,
+        provenance: p.provenance ?? null,
+      };
+    });
+    const topologyHash = hashArrays(
+      ...parts.flatMap((p) => [
+        p.record.identity,
+        p.record.topology.full.id,
+        p.record.topology.visible.id,
+        p.full,
+        p.visible,
+      ]),
+    );
+    if (
+      previous &&
+      previous.topologyHash !== topologyHash &&
+      revisions.geometry === previous.revisions.geometry
+    )
+      throw new Error("proof: topology bytes/identity replacement must advance geometry epoch");
+    const fingerprint = hashArrays(
+      revisions,
+      [...u.toWorld],
+      ...parts.flatMap((p) => [p.record, p.provenance, p.sourcePositions, p.full, p.visible]),
+    );
+    const existing = m.versions.get(tuple(revisions));
+    if (existing) {
+      if (existing.fingerprint !== fingerprint)
+        throw new Error("proof: changed content under the same completed tuple");
+      return existing;
+    }
+    return { revisions, parts, topologyHash, fingerprint, leases: 0 };
+  }
+  const specificationIds = new Set();
+  for (const specification of specifications) {
+    for (const field of ["id", "sourceId", "instanceId"])
+      if (typeof specification[field] !== "string" || specification[field].length === 0)
+        throw new Error("proof: invalid model identity");
+    if (
+      !Number.isSafeInteger(specification.providerGeneration) ||
+      specification.providerGeneration < 0
+    )
+      throw new Error("proof: invalid provider generation");
+    if (specificationIds.has(specification.id)) throw new Error("proof: duplicate model identity");
+    if (coordination.getRegistration(specification.id))
+      throw new Error("proof: pre-existing caller registration");
+    specificationIds.add(specification.id);
+  }
+  for (const specification of specifications) {
+    if (models.has(specification.id)) throw new Error("proof: duplicate model identity");
+    const m = { ...specification, token: undefined, versions: new Map(), removed: false };
+    models.set(m.id, m);
+    const previousToken = coordination.getRegistration(m.id);
+    try {
+      m.token = coordination.register(m.entity, { id: m.id, capabilities: ["open-surface"] });
+    } catch (error) {
+      if (
+        coordination.getEntity(m.id) === m.entity &&
+        coordination.getRegistration(m.id) !== previousToken
+      )
+        m.token = coordination.getRegistration(m.id);
+      const errors = [error];
+      for (const owned of models.values())
+        if (owned.token && coordination.getRegistration(owned.id) === owned.token) {
+          try {
+            coordination.unregister(owned.token);
+          } catch (e) {
+            errors.push(e);
+          }
+        }
+      throw new AggregateError(
+        errors,
+        "proof: construction failed; owned token recovery attempted",
+      );
+    }
+  }
+  function publish(updates) {
+    if (busy) throw new Error("proof: publication/disposal reentry");
+    if (disposalStarted) throw new Error("proof: disposed cohort");
+    busy = true;
+    try {
+      const seen = new Set();
+      const prepared = updates.map((u) => {
+        const m = models.get(u.id);
+        if (!m || seen.has(u.id)) throw new Error("proof: unknown or duplicate model update");
+        seen.add(u.id);
+        return { m, v: prepare(m, u) };
+      });
+      // Native trait callbacks select OLD; committed subscribers select NEW, from this same ledger.
+      for (const { m, v } of prepared) m.versions.set(tuple(v.revisions), v);
+      coordination.publishBatch(
+        prepared.map(({ m, v }) => ({
+          token: m.token,
+          completed: {
+            revisions: {
+              geometry: v.revisions.geometry,
+              pose: v.revisions.pose,
+              transform: v.revisions.transform,
+            },
+          },
+        })),
+      );
+      return view(coordination.getSnapshot());
+    } finally {
+      busy = false;
+      collect();
+    }
+  }
+  function capture(snapshot = coordination.getSnapshot()) {
+    if (disposalStarted) throw new Error("proof: disposed cohort cannot acquire fresh captures");
+    const selected = view(snapshot),
+      versions = [],
+      partsByStamp = new Map(),
+      diagnostics = [];
+    if (selected.valid)
+      for (const m of models.values()) {
+        if (m.removed) continue;
+        const v = selectedVersion(m, snapshot);
+        if (!v) continue;
+        v.leases += 1;
+        versions.push(v);
+        for (const p of v.parts)
+          for (const s of ["full", "visible"]) partsByStamp.set(stampKey(p.record, s), p);
+      }
+    let released = false;
+    const assertLease = () => {
+      if (released) throw new Error("proof: released capture");
+    };
+    return freeze({
+      snapshot: selected,
+      provider: freeze({
+        snapshot() {
+          assertLease();
+          return selected.valid ? selected.records : [freeze({})];
+        },
+      }),
+      oracle: freeze({
+        nearest({ record, topology, point, maximumDistance }) {
+          assertLease();
+          const p = partsByStamp.get(stampKey(record, topology));
+          if (!p) return undefined;
+          const consumed = freeze({
+            identity: record.identity,
+            frame: record.frame,
+            topology: freeze({ selection: topology, id: record.topology[topology].id }),
+            revisions: record.revisions,
+          });
+          let hit;
+          try {
+            hit = nearestOpenSurface(
+              p.positions,
+              p[topology],
+              point,
+              topology === "visible" ? p.visibleFaces : undefined,
+            );
+          } catch (error) {
+            if (error instanceof NumericalOracleRangeError)
+              return freeze({ kind: "unknown", reason: "numerical-oracle-range", consumed });
+            throw error;
+          }
+          if (!hit || hit.distance > maximumDistance) return freeze({ kind: "no-hit", consumed });
+          diagnostics.push(freeze({ identity: record.identity, ...hit, consumed }));
+          return freeze({
+            kind: "nearest",
+            witness: freeze({
+              triangleId: `${record.identity.partId}/full-face/${hit.face}`,
+              point: hit.point,
+              distance: hit.distance,
+              frame: record.frame,
+              consumed,
+            }),
+          });
+        },
+      }),
+      getDiagnostics: () => freeze([...diagnostics]),
+      release() {
+        if (released) return;
+        released = true;
+        for (const v of versions) v.leases -= 1;
+        partsByStamp.clear();
+        collect();
+      },
+    });
+  }
+  function dispose() {
+    if (busy) throw new Error("proof: publication/disposal reentry");
+    busy = true;
+    disposalStarted = true;
+    const errors = [];
+    try {
+      for (const m of models.values()) {
+        if (m.removed) continue;
+        if (coordination.getRegistration(m.id) !== m.token) {
+          m.removed = true;
+          continue;
+        }
+        try {
+          coordination.unregister(m.token);
+        } catch (e) {
+          errors.push(e);
+        }
+        m.removed = coordination.getRegistration(m.id) !== m.token;
+      }
+    } finally {
+      busy = false;
+      collect();
+    }
+    if (errors.length)
+      throw new AggregateError(
+        errors,
+        "proof: disposal errors; failed owned cleanup remains retryable",
+      );
+  }
+  return freeze({
+    publish,
+    capture,
+    dispose,
+    getSnapshot: () => view(coordination.getSnapshot()),
+    subscribe: (listener) => coordination.subscribe(() => listener()),
+  });
+}

package/examples/coordination-proof/cohort.mjs

@@ -1,408 +1,14 @@
 import { createHash } from "node:crypto";
-import { assertMesh, sourceFaceIds } from "./fixture.mjs";
-import {
-  indexedBounds,
-  nearestOpenSurface,
-  NumericalOracleRangeError,
-  worldPositions,
-} from "./open-surface.mjs";
+import { createProofCohort as createCoreCohort } from "./cohort-core.mjs";
+export { PROOF_FRAME } from "./cohort-core.mjs";
 
-export const PROOF_FRAME = Object.freeze({
-  id: "caller-proof-world",
-  unit: "metre",
-  metric: "euclidean",
-});
-const freeze = Object.freeze;
-const tuple = (r) => JSON.stringify([r.geometry, r.pose, r.transform]);
-const stampKey = (r, s) =>
-  JSON.stringify([
-    r.identity.sourceId,
-    r.identity.instanceId,
-    r.identity.partId,
-    r.identity.registration.id,
-    r.identity.registration.generation,
-    [r.frame.id, r.frame.unit, r.frame.metric],
-    s,
-    r.topology[s].id,
-    [r.revisions.geometry, r.revisions.topology, r.revisions.pose, r.revisions.transform],
-  ]);
-function hashArrays(...values) {
+export function hashBytes(chunks) {
   const hash = createHash("sha256");
-  for (const v of values)
-    hash.update(
-      ArrayBuffer.isView(v) ? Buffer.from(v.buffer, v.byteOffset, v.byteLength) : JSON.stringify(v),
-    );
+  for (const chunk of chunks) hash.update(chunk);
   return hash.digest("hex");
 }
-function sameIndexBytes(left, right) {
-  if (left.length !== right.length || left.byteLength !== right.byteLength) return false;
-  const a = new Uint8Array(left.buffer, left.byteOffset, left.byteLength);
-  const b = new Uint8Array(right.buffer, right.byteOffset, right.byteLength);
-  for (let index = 0; index < a.length; index += 1) if (a[index] !== b[index]) return false;
-  return true;
-}
 
-/** Test-only caller resource ledger; coordination snapshots are the sole commit boundary. */
+/** Node reference API; only the hash primitive differs from the browser caller. */
 export function createProofCohort(coordination, specifications) {
-  const models = new Map(),
-    views = new WeakMap();
-  let busy = false,
-    disposalStarted = false;
-  function current(m) {
-    return (
-      coordination.getRegistration(m.id) === m.token && coordination.getEntity(m.id) === m.entity
-    );
-  }
-  function selectedVersion(m, s) {
-    const e = s.entries.find((e) => e.id === m.id);
-    return e?.completed ? m.versions.get(tuple(e.completed.revisions)) : undefined;
-  }
-  function collect() {
-    if (busy) return;
-    const s = coordination.getSnapshot();
-    for (const m of models.values()) {
-      const active = current(m) ? selectedVersion(m, s) : undefined;
-      for (const [id, v] of m.versions) if (v !== active && v.leases === 0) m.versions.delete(id);
-    }
-  }
-  function view(s) {
-    function invalid() {
-      const cached = views.get(s);
-      if (cached?.valid === false) return cached;
-      const result = freeze({ coordination: s, records: freeze([]), valid: false });
-      views.set(s, result);
-      return result;
-    }
-    if ([...models.values()].some((m) => !m.removed && !current(m))) return invalid();
-    // Cached metadata does not lease buffers; verify retained versions before using it.
-    if (
-      [...models.values()].some(
-        (m) =>
-          !m.removed &&
-          (!s.entries.find((entry) => entry.id === m.id)?.completed || !selectedVersion(m, s)),
-      )
-    )
-      return invalid();
-    const cached = views.get(s);
-    if (cached?.valid === true) return cached;
-    const records = [];
-    for (const m of models.values()) {
-      if (m.removed) continue;
-      const v = selectedVersion(m, s);
-      if (s.entries.find((entry) => entry.id === m.id)?.completed && !v) {
-        return invalid();
-      }
-      if (v) records.push(...v.parts.map((p) => p.record));
-    }
-    records.sort(
-      (a, b) =>
-        Number(stampKey(a, "full") > stampKey(b, "full")) -
-        Number(stampKey(a, "full") < stampKey(b, "full")),
-    );
-    const result = freeze({ coordination: s, records: freeze(records), valid: true });
-    views.set(s, result);
-    return result;
-  }
-  function prepare(m, u) {
-    if (!current(m)) throw new Error("proof: stale owned registration lifetime");
-    const revisions = freeze({ ...u.revisions }),
-      previous = selectedVersion(m, coordination.getSnapshot());
-    for (const epoch of ["geometry", "topology", "pose", "transform"]) {
-      if (
-        !Number.isSafeInteger(revisions[epoch]) ||
-        revisions[epoch] < 0 ||
-        (previous && revisions[epoch] < previous.revisions[epoch])
-      )
-        throw new Error(`proof: invalid or regressing ${epoch} epoch`);
-    }
-    if (
-      previous &&
-      revisions.topology !== previous.revisions.topology &&
-      revisions.geometry === previous.revisions.geometry
-    )
-      throw new Error("proof: topology replacement must advance geometry epoch");
-    const frame = freeze({ ...(u.frame ?? m.frame ?? PROOF_FRAME) });
-    if (
-      typeof frame.id !== "string" ||
-      frame.id.length === 0 ||
-      typeof frame.unit !== "string" ||
-      frame.unit.length === 0 ||
-      frame.metric !== "euclidean"
-    )
-      throw new Error("proof: invalid declared frame");
-    const partIds = new Set();
-    const parts = u.parts.map((p) => {
-      if (!p.id || partIds.has(p.id) || !p.fullTopologyId || !p.visibleTopologyId)
-        throw new Error("proof: invalid or duplicate part/topology identity");
-      partIds.add(p.id);
-      assertMesh(p.positions, p.full, p.positions.length / 3);
-      assertMesh(p.positions, p.visible, p.positions.length / 3);
-      const full = new Uint32Array(p.full),
-        visible = new Uint32Array(p.visible),
-        sourcePositions = new Float32Array(p.positions);
-      assertMesh(sourcePositions, full, sourcePositions.length / 3);
-      assertMesh(sourcePositions, visible, sourcePositions.length / 3);
-      const previousPart = previous?.parts.find((part) => part.record.identity.partId === p.id);
-      // Reuse only a committed same-lifetime part after validating fresh copies.
-      const canReuse =
-        previousPart &&
-        previous.revisions.topology === revisions.topology &&
-        previousPart.record.identity.sourceId === m.sourceId &&
-        previousPart.record.identity.instanceId === m.instanceId &&
-        previousPart.record.identity.registration.generation === m.providerGeneration &&
-        previousPart.record.topology.full.id === p.fullTopologyId &&
-        previousPart.record.topology.visible.id === p.visibleTopologyId &&
-        sameIndexBytes(previousPart.full, full) &&
-        sameIndexBytes(previousPart.visible, visible);
-      const visibleFaces = canReuse ? previousPart.visibleFaces : sourceFaceIds(full, visible),
-        positions = worldPositions(sourcePositions, u.toWorld);
-      const identity = freeze({
-        sourceId: m.sourceId,
-        instanceId: m.instanceId,
-        partId: p.id,
-        registration: freeze({ id: m.id, generation: m.providerGeneration }),
-      });
-      const record = freeze({
-        identity,
-        frame,
-        revisions,
-        topology: freeze({
-          full: freeze({
-            id: p.fullTopologyId,
-            bounds: indexedBounds(positions, full),
-            enclosesSurface: true,
-          }),
-          visible: freeze({
-            id: p.visibleTopologyId,
-            bounds: indexedBounds(positions, visible),
-            enclosesSurface: true,
-          }),
-        }),
-        capabilities: freeze(p.nearestSurface === false ? [] : ["nearest-surface"]),
-      });
-      return {
-        record,
-        sourcePositions,
-        positions,
-        full,
-        visible,
-        visibleFaces,
-        provenance: p.provenance ?? null,
-      };
-    });
-    const topologyHash = hashArrays(
-      ...parts.flatMap((p) => [
-        p.record.identity,
-        p.record.topology.full.id,
-        p.record.topology.visible.id,
-        p.full,
-        p.visible,
-      ]),
-    );
-    if (
-      previous &&
-      previous.topologyHash !== topologyHash &&
-      revisions.geometry === previous.revisions.geometry
-    )
-      throw new Error("proof: topology bytes/identity replacement must advance geometry epoch");
-    const fingerprint = hashArrays(
-      revisions,
-      [...u.toWorld],
-      ...parts.flatMap((p) => [p.record, p.provenance, p.sourcePositions, p.full, p.visible]),
-    );
-    const existing = m.versions.get(tuple(revisions));
-    if (existing) {
-      if (existing.fingerprint !== fingerprint)
-        throw new Error("proof: changed content under the same completed tuple");
-      return existing;
-    }
-    return { revisions, parts, topologyHash, fingerprint, leases: 0 };
-  }
-  const specificationIds = new Set();
-  for (const specification of specifications) {
-    for (const field of ["id", "sourceId", "instanceId"])
-      if (typeof specification[field] !== "string" || specification[field].length === 0)
-        throw new Error("proof: invalid model identity");
-    if (
-      !Number.isSafeInteger(specification.providerGeneration) ||
-      specification.providerGeneration < 0
-    )
-      throw new Error("proof: invalid provider generation");
-    if (specificationIds.has(specification.id)) throw new Error("proof: duplicate model identity");
-    if (coordination.getRegistration(specification.id))
-      throw new Error("proof: pre-existing caller registration");
-    specificationIds.add(specification.id);
-  }
-  for (const specification of specifications) {
-    if (models.has(specification.id)) throw new Error("proof: duplicate model identity");
-    const m = { ...specification, token: undefined, versions: new Map(), removed: false };
-    models.set(m.id, m);
-    const previousToken = coordination.getRegistration(m.id);
-    try {
-      m.token = coordination.register(m.entity, { id: m.id, capabilities: ["open-surface"] });
-    } catch (error) {
-      if (
-        coordination.getEntity(m.id) === m.entity &&
-        coordination.getRegistration(m.id) !== previousToken
-      )
-        m.token = coordination.getRegistration(m.id);
-      const errors = [error];
-      for (const owned of models.values())
-        if (owned.token && coordination.getRegistration(owned.id) === owned.token) {
-          try {
-            coordination.unregister(owned.token);
-          } catch (e) {
-            errors.push(e);
-          }
-        }
-      throw new AggregateError(
-        errors,
-        "proof: construction failed; owned token recovery attempted",
-      );
-    }
-  }
-  function publish(updates) {
-    if (busy) throw new Error("proof: publication/disposal reentry");
-    if (disposalStarted) throw new Error("proof: disposed cohort");
-    busy = true;
-    try {
-      const seen = new Set();
-      const prepared = updates.map((u) => {
-        const m = models.get(u.id);
-        if (!m || seen.has(u.id)) throw new Error("proof: unknown or duplicate model update");
-        seen.add(u.id);
-        return { m, v: prepare(m, u) };
-      });
-      // Native trait callbacks select OLD; committed subscribers select NEW, from this same ledger.
-      for (const { m, v } of prepared) m.versions.set(tuple(v.revisions), v);
-      coordination.publishBatch(
-        prepared.map(({ m, v }) => ({
-          token: m.token,
-          completed: {
-            revisions: {
-              geometry: v.revisions.geometry,
-              pose: v.revisions.pose,
-              transform: v.revisions.transform,
-            },
-          },
-        })),
-      );
-      return view(coordination.getSnapshot());
-    } finally {
-      busy = false;
-      collect();
-    }
-  }
-  function capture(snapshot = coordination.getSnapshot()) {
-    if (disposalStarted) throw new Error("proof: disposed cohort cannot acquire fresh captures");
-    const selected = view(snapshot),
-      versions = [],
-      partsByStamp = new Map(),
-      diagnostics = [];
-    if (selected.valid)
-      for (const m of models.values()) {
-        if (m.removed) continue;
-        const v = selectedVersion(m, snapshot);
-        if (!v) continue;
-        v.leases += 1;
-        versions.push(v);
-        for (const p of v.parts)
-          for (const s of ["full", "visible"]) partsByStamp.set(stampKey(p.record, s), p);
-      }
-    let released = false;
-    const assertLease = () => {
-      if (released) throw new Error("proof: released capture");
-    };
-    return freeze({
-      snapshot: selected,
-      provider: freeze({
-        snapshot() {
-          assertLease();
-          return selected.valid ? selected.records : [freeze({})];
-        },
-      }),
-      oracle: freeze({
-        nearest({ record, topology, point, maximumDistance }) {
-          assertLease();
-          const p = partsByStamp.get(stampKey(record, topology));
-          if (!p) return undefined;
-          const consumed = freeze({
-            identity: record.identity,
-            frame: record.frame,
-            topology: freeze({ selection: topology, id: record.topology[topology].id }),
-            revisions: record.revisions,
-          });
-          let hit;
-          try {
-            hit = nearestOpenSurface(
-              p.positions,
-              p[topology],
-              point,
-              topology === "visible" ? p.visibleFaces : undefined,
-            );
-          } catch (error) {
-            if (error instanceof NumericalOracleRangeError)
-              return freeze({ kind: "unknown", reason: "numerical-oracle-range", consumed });
-            throw error;
-          }
-          if (!hit || hit.distance > maximumDistance) return freeze({ kind: "no-hit", consumed });
-          diagnostics.push(freeze({ identity: record.identity, ...hit, consumed }));
-          return freeze({
-            kind: "nearest",
-            witness: freeze({
-              triangleId: `${record.identity.partId}/full-face/${hit.face}`,
-              point: hit.point,
-              distance: hit.distance,
-              frame: record.frame,
-              consumed,
-            }),
-          });
-        },
-      }),
-      getDiagnostics: () => freeze([...diagnostics]),
-      release() {
-        if (released) return;
-        released = true;
-        for (const v of versions) v.leases -= 1;
-        partsByStamp.clear();
-        collect();
-      },
-    });
-  }
-  function dispose() {
-    if (busy) throw new Error("proof: publication/disposal reentry");
-    busy = true;
-    disposalStarted = true;
-    const errors = [];
-    try {
-      for (const m of models.values()) {
-        if (m.removed) continue;
-        if (coordination.getRegistration(m.id) !== m.token) {
-          m.removed = true;
-          continue;
-        }
-        try {
-          coordination.unregister(m.token);
-        } catch (e) {
-          errors.push(e);
-        }
-        m.removed = coordination.getRegistration(m.id) !== m.token;
-      }
-    } finally {
-      busy = false;
-      collect();
-    }
-    if (errors.length)
-      throw new AggregateError(
-        errors,
-        "proof: disposal errors; failed owned cleanup remains retryable",
-      );
-  }
-  return freeze({
-    publish,
-    capture,
-    dispose,
-    getSnapshot: () => view(coordination.getSnapshot()),
-    subscribe: (listener) => coordination.subscribe(() => listener()),
-  });
+  return createCoreCohort(coordination, specifications, { hashBytes });
 }

package/examples/coordination-proof/consumer-package.json

@@ -10,6 +10,7 @@
     "react-dom": "19.3.0",
     "strata-procedural": "0.1.0",
     "yuka": "0.7.8",
-    "yuka-kit": "1.1.0"
+    "yuka-kit": "1.1.0",
+    "@noble/hashes": "2.4.0"
   }
 }

package/examples/coordination-proof/fixture.mjs

@@ -2,6 +2,9 @@ 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"],
@@ -33,34 +36,6 @@ export function decodeArray(bytes, descriptor) {
   return array;
 }
 
-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;
-}
-
 /** 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"));

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/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

@@ -1,4 +1,5 @@
 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 }) {
@@ -19,26 +20,16 @@ export async function observeCommittedUpdate({ registryImport, cohort, world, pu
   const observations = [];
   const container = dom.window.document.getElementById("proof");
   const root = createRoot(container);
-  function Inspector() {
-    assert.equal(useWorld(), world);
-    const snapshot = React.useSyncExternalStore(
-      cohort.subscribe,
-      cohort.getSnapshot,
-      cohort.getSnapshot,
-    );
-    observations.push(snapshot);
-    return React.createElement(
-      "output",
-      null,
-      snapshot.coordination.entries
-        .map((entry) => `${entry.id}:${entry.completed?.revisions.pose ?? "pending"}`)
-        .join(","),
-    );
-  }
+  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 }, React.createElement(Inspector))),
+      root.render(React.createElement(WorldProvider, { world }, inspector)),
     );
     const before = container.textContent;
     const previous = cohort.getSnapshot();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "koota-kit",
-  "version": "0.8.8",
+  "version": "0.9.0",
   "description": "Deterministic Koota simulation conventions: world lifecycle, dual RNG streams, safe object traits, and world-scoped event logs.",
   "type": "module",
   "license": "MIT",