koota-kit 0.8.7 → 0.8.8

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.8.8 (2026-10-14)
+
+<!-- Release notes generated using configuration in .github/release.yml at main -->
+
+## What's Changed
+* test: prove registry caller composition in one World by @jbdevprimary in https://github.com/jbcom/koota-kit/pull/76
+
+
+**Full Changelog**: https://github.com/jbcom/koota-kit/compare/v0.8.7...v0.8.8
+
 ## 0.8.7 (2026-10-14)
 
 <!-- Release notes generated using configuration in .github/release.yml at main -->

package/README.md

@@ -138,6 +138,10 @@ ID. Listener errors occur after a committed publication; retrieve a token with
 `getRegistration(id)` if registration notification threw before `register`
 could return it.
 
+The [caller composition proof](docs/INTEGRATION_PROOF.md) documents the optional
+registry consumer, copied figure inputs, immutable geometry captures and the
+limits of open-surface integration evidence.
+
 ### Randomness has two jobs
 
 - `rng.gen` defines stable world content: terrain, layouts, initial spawns.

package/docs/INTEGRATION_PROOF.md

@@ -0,0 +1,121 @@
+# Caller composition proof
+
+This proof composes existing entities in one caller-owned Koota World. It is an
+application example and a bounded test oracle, not another runtime adapter or
+geometry backend. The package root gains no model, renderer, AI or geometry
+dependency.
+
+## Inputs and execution
+
+`examples/coordination-proof/consumer-package.json` declares every optional
+package used by the independent registry consumer. Copy it into a private
+directory outside this workspace, copy `registry-import.mjs` beside its
+`package.json`, install it with `npm install --ignore-scripts --bin-links=false`,
+and retain the resulting package lock. The runner resolves all package imports
+from that directory. It never imports this checkout's library source or build.
+The pinned Koota Kit version must include both the coordination and spatial
+exports; coordination alone is insufficient.
+
+Supply an authorized copied figure fixture directory containing `fixture.json`
+and the arrays named by its manifest. The loader reads only the rest positions,
+rest normals, full and visible indices, and both poses' positions and normals.
+It checks every byte length and SHA256, decodes little-endian values explicitly,
+checks triangle ranges, and maps visible triangles to their full source face IDs.
+Posed positions already contain their single ground lift; the proof applies no
+additional lift or pose evaluation.
+
+The preparation command needs no optional package:
+
+```sh
+node examples/coordination-proof/prepare.mjs "$FIXTURE_DIRECTORY" "$RECEIPT_FILE"
+```
+
+The registry composition command uses the independent installed consumer:
+
+```sh
+node examples/coordination-proof/run.mjs \
+  "$FIXTURE_DIRECTORY" "$CONSUMER_DIRECTORY" "$RECEIPT_FILE"
+```
+
+Run these bounded array/query checks through the project's authorized remote
+run facility. Use canonical absolute input paths and a regular-file-only
+consumer install. Declare exactly the copied fixture inputs and private consumer
+inputs, preserve their hashes, and return the receipt directory. Keep logs
+outside returned directories so artifact replacement cannot overwrite them.
+
+## Ownership and observation
+
+Model A uses the published Strata terrain API's portable indexed heightfield.
+Its anchor is explicitly authored by the caller on a generated vertex; the proof
+does not claim an unexported Strata mesh or anchor API. Model B uses actual copied
+figure and garment arrays, with full body triangles preserved even when hidden
+by visible outfit masking. These inputs certify open surfaces only.
+
+Both existing entities retain caller Position, Velocity, Intent and ModelKind
+traits. The caller writes positions, pulls them through Yuka's existing
+`AIBridge.syncFromKoota`, writes an intent stamped with the consumed surface
+epochs, runs its behavior, then uses `syncToKoota` to write velocity. The bridge
+does not become a second position writer. React's existing `WorldProvider`
+observes that exact raw World, and `useSyncExternalStore` observes the immutable
+view selected by the same committed coordination snapshot.
+
+The caller's resource ledger prepares copied immutable geometry versions before
+`publishBatch`. A committed coordination snapshot selects one version for every
+model using its owned registration lifetime and completed geometry, pose and
+transform tuple. Geometry, topology, pose and transform remain explicit spatial
+epochs. Replacing topology must also advance geometry; a publication generation
+or opaque registration token never stands in for a producer epoch.
+
+Native raw trait callbacks select the previous completed cohort; coordination
+subscribers select the new completed cohort. Failed preparation or a raw-write
+failure retains the old selected version. A listener exception occurs after
+commit and retains the new selected version. Identical publication is a no-op;
+changed bytes or provenance under the same completed tuple are rejected.
+Pending owned models invalidate the view until every model has a completed
+retained version. A completed model with an explicit empty part list represents
+known absence. Invalid views remain stable for React and fail closed in queries.
+
+The private proof can reuse a selected part's visible-to-full face correspondence
+after validating fresh copies and comparing its explicit topology epoch, source,
+instance, part, topology IDs and exact index bytes. Position copies, transforms,
+bounds and fingerprints are still recomputed. A changed selection recomputes the
+correspondence; retained captures keep their prior face ordinals.
+
+`capture()` returns a fixed provider, oracle and idempotent `release()`. Always
+release in `finally`. A capture retains its old copied arrays through later
+publications and disposal. Oracle lookup uses the complete copied record stamp,
+including source, instance, part, provider generation, frame, topology and all
+four epochs. Unrelated entries in the binding do not invalidate owned versions.
+Disposal attempts every owned registration, preserves entities and custom state,
+and keeps failed cleanup retryable without touching a replacement registration.
+
+## Evidence boundary
+
+The reference oracle exhaustively evaluates indexed triangles in its supported
+numerical range after transforming all vertices into the declared world Euclidean
+metric. It returns stamped `unknown` for overflow, underflow, subnormal arithmetic
+or thin triangles whose squared aspect ratio falls below its roundoff margin.
+It does not
+convert a local nearest winner into a world answer. Witness diagnostics retain
+full source face IDs, barycentric coordinates and geometric normals; degenerate
+faces retain segment/point witnesses without inventing a normal. This is a
+bounded correctness oracle, not a performance backend or a production kernel.
+
+The tests exercise checksum rejection, full/visible face ownership, a
+nonuniform transform that changes the winning triangle, coherent two-model
+publication, rollback, postcommit notification errors, explicit invalidation,
+capture retention, registration reuse, reentry and retryable cleanup. New gates
+require an observed fault-injection failure, byte-identical input/source
+restoration, then a passing rerun.
+
+Copied input proof, registry composition and headless mounted React observation
+do not establish a live Humanoid producer contract or CPU-to-GPU vertex parity.
+Fresh silent rendered acceptance remains a separate owner-reviewed requirement.
+No containment, solid penetration, traversability or line-of-sight result is
+claimed. The receipts report bounded measurements without a comparative
+performance claim.
+
+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.

package/examples/coordination-proof/cohort.mjs

@@ -0,0 +1,408 @@
+import { createHash } from "node:crypto";
+import { assertMesh, sourceFaceIds } from "./fixture.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],
+  ]);
+function hashArrays(...values) {
+  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),
+    );
+  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. */
+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()),
+  });
+}

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

@@ -0,0 +1,15 @@
+{
+  "name": "koota-caller-proof-consumer",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "jsdom": "30.1.2",
+    "koota": "0.6.6",
+    "koota-kit": "0.8.6",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "strata-procedural": "0.1.0",
+    "yuka": "0.7.8",
+    "yuka-kit": "1.1.0"
+  }
+}