koota-kit 0.9.1 → 0.9.3

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.9.3 (2026-10-15)
+
+<!-- Release notes generated using configuration in .github/release.yml at main -->
+
+## What's Changed
+* fix: guard coordination against mismatched Koota dispatch by @jbdevprimary in https://github.com/jbcom/koota-kit/pull/86
+
+
+**Full Changelog**: https://github.com/jbcom/koota-kit/compare/v0.9.2...v0.9.3
+
+## 0.9.2 (2026-10-14)
+
+<!-- Release notes generated using configuration in .github/release.yml at main -->
+
+## What's Changed
+* test(spatial): preserve invalid-provider diagnostic precedence by @jbdevprimary in https://github.com/jbcom/koota-kit/pull/85
+
+
+**Full Changelog**: https://github.com/jbcom/koota-kit/compare/v0.9.1...v0.9.2
+
 ## 0.9.1 (2026-10-14)
 
 <!-- Release notes generated using configuration in .github/release.yml at main -->

package/README.md

@@ -138,6 +138,13 @@ ID. Listener errors occur after a committed publication; retrieve a token with
 `getRegistration(id)` if registration notification threw before `register`
 could return it.
 
+Use one Koota runtime and module format per process. Koota 0.6.6 replaces numeric
+entity dispatch when the opposite ESM/CommonJS peer format loads. Coordination
+then rejects live reads, writes, and cleanup with a dispatch-realm error;
+`getSnapshot()` still returns its last committed view. Raw callback writes may
+already have happened, but failed cleanup never reports successful disposal.
+The independent `koota-kit/spatial` entry can be imported in either format.
+
 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.

package/dist/cjs/coordination.cjs

@@ -121,16 +121,79 @@ function bindCoordination(world) {
     if (!world?.isInitialized) {
         fail("a live Koota World is required.");
     }
+    // Koota's numeric Entity methods close over their imported peer universe.
+    // Opposite ESM/CJS imports replace those global methods, even before this
+    // module first loads. Pointer stability alone therefore cannot attest them.
+    const dispatch = {
+        get: 0..get,
+        has: 0..has,
+        add: 0..add,
+        set: 0..set,
+        remove: 0..remove,
+    };
+    const assertRealm = () => {
+        if (koota_1.universe.worlds[world.id] !== world ||
+            0..get !== dispatch.get ||
+            0..has !== dispatch.has ||
+            0..add !== dispatch.add ||
+            0..set !== dispatch.set ||
+            0..remove !== dispatch.remove) {
+            fail("the Koota entity dispatch realm no longer matches the borrowed World.");
+        }
+    };
+    assertRealm();
     const marker = Object.freeze({});
+    let holder;
+    let holderId;
+    let store;
+    const assertAttested = () => {
+        assertRealm();
+        const markers = world.get(exports.CoordinationBinding)?.markers;
+        let matches = false;
+        try {
+            matches =
+                world.has(holder) &&
+                    (0, koota_1.getStore)(world, exports.CoordinationBinding) === store &&
+                    store.markers[holderId] === markers &&
+                    dispatch.get.call(holder, exports.CoordinationBinding)?.markers === markers;
+        }
+        catch {
+            // A foreign peer may have no World at this numeric ID at all.
+        }
+        assertRealm();
+        if (!matches)
+            fail("the Koota entity dispatch realm cannot attest the World marker.");
+    };
+    const assertOwned = () => {
+        assertAttested();
+        const markers = world.get(exports.CoordinationBinding)?.markers;
+        if (!markers?.includes(marker)) {
+            fail("the binding no longer owns its World marker.");
+        }
+        return markers;
+    };
     const existingMarkers = world.get(exports.CoordinationBinding)?.markers ?? [];
     const markers = [...existingMarkers, marker];
     try {
+        assertRealm();
         if (world.has(exports.CoordinationBinding))
             world.set(exports.CoordinationBinding, { markers });
         else
             world.add((0, exports.CoordinationBinding)({ markers }));
+        assertRealm();
+        store = (0, koota_1.getStore)(world, exports.CoordinationBinding);
+        // World traits live on an existing excluded entity. Find only our marker
+        // by direct store identity once; later checks use this cached holder in O(1).
+        const holders = world.entities.filter((entity) => store.markers[(0, koota_1.unpackEntity)(entity).entityId] === markers);
+        if (holders.length !== 1)
+            fail("the Koota entity dispatch realm has no unique marker holder.");
+        holder = holders[0];
+        holderId = (0, koota_1.unpackEntity)(holder).entityId;
+        assertOwned();
     }
     catch (error) {
+        // Direct World APIs close over the original World even if a callback
+        // changed entity dispatch before we could attest its numeric holder.
         const currentMarkers = world.get(exports.CoordinationBinding)?.markers;
         if (world.isInitialized && currentMarkers?.includes(marker)) {
             const remaining = currentMarkers.filter((candidate) => candidate !== marker);
@@ -142,6 +205,7 @@ function bindCoordination(world) {
         throw error;
     }
     let disposed = false;
+    let cleanupMarkerRemoved = false;
     let notifying = false;
     let mutating = false;
     let nextRegistrationGeneration = 0;
@@ -158,12 +222,15 @@ function bindCoordination(world) {
     };
     const assertMutable = () => {
         assertActive();
-        if (!world.isInitialized || !world.get(exports.CoordinationBinding)?.markers.includes(marker)) {
+        if (!world.isInitialized)
             fail("the binding no longer owns its World marker.");
-        }
+        assertOwned();
     };
     const isCurrent = (registration) => {
-        if (!world.isInitialized || !world.has(registration.entity))
+        if (!world.isInitialized)
+            return false;
+        assertOwned();
+        if (!world.has(registration.entity))
             return false;
         return stateIsOwned(registration.entity.get(exports.CoordinationRegistration), marker, registration.state.generation);
     };
@@ -190,6 +257,16 @@ function bindCoordination(world) {
                     errors.push(error);
                 }
             }
+            // Listener failures occur after commit. A listener may also change peer
+            // dispatch without throwing; report that boundary to the caller too.
+            if (world.isInitialized) {
+                try {
+                    assertOwned();
+                }
+                catch (error) {
+                    errors.push(error);
+                }
+            }
         }
         finally {
             notifying = false;
@@ -226,6 +303,7 @@ function bindCoordination(world) {
         const capabilities = copyCapabilities(descriptor.capabilities);
         if (registrationsById.has(id))
             fail(`stable id "${id}" is already registered.`);
+        assertOwned();
         if (entity.has(exports.CoordinationRegistration)) {
             fail("entity already carries a coordination registration trait.");
         }
@@ -254,15 +332,20 @@ function bindCoordination(world) {
         mutating = true;
         try {
             try {
+                assertOwned();
                 entity.add((0, exports.CoordinationRegistration)(state));
+                assertOwned();
             }
             catch (error) {
-                const current = entity.get(exports.CoordinationRegistration);
+                // These captured peer functions use their original lexical universe;
+                // rollback only the trait this attempted registration placed there.
+                const current = dispatch.get.call(entity, exports.CoordinationRegistration);
                 if (stateIsOwned(current, marker, registrationGeneration)) {
-                    entity.remove(exports.CoordinationRegistration);
+                    dispatch.remove.call(entity, exports.CoordinationRegistration);
                 }
                 throw error;
             }
+            assertOwned();
             nextRegistrationGeneration = registrationGeneration;
             registrationsById.set(id, registration);
             registrationsByToken.set(token, registration);
@@ -294,6 +377,7 @@ function bindCoordination(world) {
         }
         const changed = prepared.some(({ registration, completed }) => !registration.completed ||
             !sameRevisions(registration.completed.revisions, completed.revisions));
+        assertOwned();
         if (!changed)
             return snapshot;
         const snapshotRevision = nextCounter(nextSnapshotRevision, "snapshot revision");
@@ -312,8 +396,11 @@ function bindCoordination(world) {
         mutating = true;
         try {
             for (const { registration, state } of preparedStates) {
+                assertOwned();
                 registration.entity.set(exports.CoordinationRegistration, state);
+                assertOwned();
             }
+            assertOwned();
             for (const { registration, completed } of preparedStates) {
                 registration.completed = completed;
             }
@@ -329,7 +416,9 @@ function bindCoordination(world) {
         const snapshotRevision = nextCounter(nextSnapshotRevision, "snapshot revision");
         mutating = true;
         try {
+            assertOwned();
             registration.entity.remove(exports.CoordinationRegistration);
+            assertOwned();
             registrationsById.delete(registration.id);
             registrationsByToken.delete(token);
             return commit(snapshotRevision);
@@ -340,12 +429,16 @@ function bindCoordination(world) {
     };
     const prune = () => {
         assertActive();
+        if (world.isInitialized)
+            assertOwned();
         const stale = [...registrationsById.values()].filter((registration) => !isCurrent(registration));
         if (stale.length === 0)
             return snapshot;
         const snapshotRevision = nextCounter(nextSnapshotRevision, "snapshot revision");
         mutating = true;
         try {
+            if (world.isInitialized)
+                assertOwned();
             for (const registration of stale) {
                 registrationsById.delete(registration.id);
                 registrationsByToken.delete(registration.token);
@@ -357,10 +450,14 @@ function bindCoordination(world) {
         }
     };
     const getEntity = (id) => {
+        if (world.isInitialized && !disposed)
+            assertOwned();
         const registration = registrationsById.get(id);
         return registration && isCurrent(registration) ? registration.entity : undefined;
     };
     const getRegistration = (id) => {
+        if (world.isInitialized && !disposed)
+            assertOwned();
         const registration = registrationsById.get(id);
         return registration && isCurrent(registration) ? registration.token : undefined;
     };
@@ -377,24 +474,49 @@ function bindCoordination(world) {
         if (disposed)
             return;
         assertActive();
+        if (world.isInitialized) {
+            if (cleanupMarkerRemoved)
+                assertRealm();
+            else
+                assertOwned();
+        }
         const snapshotRevision = nextCounter(nextSnapshotRevision, "snapshot revision");
         mutating = true;
         try {
-            listeners.clear();
-            for (const registration of registrationsById.values()) {
-                if (isCurrent(registration))
-                    registration.entity.remove(exports.CoordinationRegistration);
+            if (!cleanupMarkerRemoved) {
+                for (const registration of registrationsById.values()) {
+                    if (isCurrent(registration)) {
+                        assertOwned();
+                        registration.entity.remove(exports.CoordinationRegistration);
+                        assertOwned();
+                    }
+                }
+                if (world.isInitialized) {
+                    const remaining = assertOwned().filter((candidate) => candidate !== marker);
+                    try {
+                        if (remaining.length === 0)
+                            world.remove(exports.CoordinationBinding);
+                        else
+                            world.set(exports.CoordinationBinding, { markers: remaining });
+                    }
+                    catch (error) {
+                        assertRealm();
+                        // A same-peer callback can throw after the marker write completed.
+                        // Remember only this disposal's confirmed removal, so a retry can
+                        // finish without treating an externally lost marker as ownership.
+                        cleanupMarkerRemoved = !world.get(exports.CoordinationBinding)?.markers.includes(marker);
+                        throw error;
+                    }
+                    // Final removal intentionally makes owned-marker attestation absent.
+                    assertRealm();
+                    cleanupMarkerRemoved = true;
+                }
             }
+            if (world.isInitialized)
+                assertRealm();
+            listeners.clear();
             registrationsById.clear();
             registrationsByToken.clear();
-            const markerState = world.get(exports.CoordinationBinding);
-            if (world.isInitialized && markerState?.markers.includes(marker)) {
-                const remaining = markerState.markers.filter((candidate) => candidate !== marker);
-                if (remaining.length === 0)
-                    world.remove(exports.CoordinationBinding);
-                else
-                    world.set(exports.CoordinationBinding, { markers: remaining });
-            }
             nextSnapshotRevision = snapshotRevision;
             snapshot = makeSnapshot(nextSnapshotRevision, []);
             disposed = true;

package/dist/cjs/coordination.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"coordination.d.ts","sourceRoot":"","sources":["../../src/coordination.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAS,KAAK,MAAM,EAAE,KAAK,KAAK,EAAE,MAAM,OAAO,CAAC;AAEvD,KAAK,aAAa,GAAG,MAAM,CAAC;AAW5B;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;mBAAgC,aAAa,EAAE;EAAG,CAAC;AAEnF;;;;GAIG;AACH,eAAO,MAAM,wBAAwB;kBACb,aAAa;;;;;;EAMnC,CAAC;AAEH,OAAO,CAAC,MAAM,sBAAsB,EAAE,OAAO,MAAM,CAAC;AAEpD,2EAA2E;AAC3E,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,CAAC,sBAAsB,CAAC,EAAE,KAAK,CAAC;CAC1C,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC,SAAS,EAAE,kBAAkB,CAAC;CAC/B,CAAC,CAAC;AAEH,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C,4EAA4E;IAC5E,EAAE,EAAE,MAAM,CAAC;IACX,4EAA4E;IAC5E,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CACjC,CAAC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,6EAA6E;IAC7E,SAAS,EAAE,iBAAiB,GAAG,SAAS,CAAC;CAC1C,CAAC,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAC1C,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,OAAO,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACvC,CAAC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC;IACxC,KAAK,EAAE,iBAAiB,CAAC;IACzB,SAAS,EAAE,iBAAiB,CAAC;CAC9B,CAAC,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,CAAC,QAAQ,EAAE,oBAAoB,KAAK,IAAI,CAAC;AAE5E,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,sBAAsB,KAAK,iBAAiB,CAAC;IACpF,OAAO,EAAE,CAAC,KAAK,EAAE,iBAAiB,EAAE,SAAS,EAAE,iBAAiB,KAAK,oBAAoB,CAAC;IAC1F,YAAY,EAAE,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,KAAK,oBAAoB,CAAC;IAC/E,UAAU,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,oBAAoB,CAAC;IAC/D,6EAA6E;IAC7E,KAAK,EAAE,MAAM,oBAAoB,CAAC;IAClC,0EAA0E;IAC1E,eAAe,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,iBAAiB,GAAG,SAAS,CAAC;IAC/D,+EAA+E;IAC/E,SAAS,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IAC9C,WAAW,EAAE,MAAM,oBAAoB,CAAC;IACxC,SAAS,EAAE,CAAC,QAAQ,EAAE,oBAAoB,KAAK,MAAM,IAAI,CAAC;IAC1D,mFAAmF;IACnF,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CAAC,CAAC;AA+HH;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,GAAG,YAAY,CAgT3D"}
+{"version":3,"file":"coordination.d.ts","sourceRoot":"","sources":["../../src/coordination.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAA2C,KAAK,MAAM,EAAE,KAAK,KAAK,EAAE,MAAM,OAAO,CAAC;AAEzF,KAAK,aAAa,GAAG,MAAM,CAAC;AAW5B;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;mBAAgC,aAAa,EAAE;EAAG,CAAC;AAEnF;;;;GAIG;AACH,eAAO,MAAM,wBAAwB;kBACb,aAAa;;;;;;EAMnC,CAAC;AAEH,OAAO,CAAC,MAAM,sBAAsB,EAAE,OAAO,MAAM,CAAC;AAEpD,2EAA2E;AAC3E,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,CAAC,sBAAsB,CAAC,EAAE,KAAK,CAAC;CAC1C,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC,SAAS,EAAE,kBAAkB,CAAC;CAC/B,CAAC,CAAC;AAEH,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C,4EAA4E;IAC5E,EAAE,EAAE,MAAM,CAAC;IACX,4EAA4E;IAC5E,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CACjC,CAAC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,6EAA6E;IAC7E,SAAS,EAAE,iBAAiB,GAAG,SAAS,CAAC;CAC1C,CAAC,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAC1C,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,OAAO,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACvC,CAAC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC;IACxC,KAAK,EAAE,iBAAiB,CAAC;IACzB,SAAS,EAAE,iBAAiB,CAAC;CAC9B,CAAC,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,CAAC,QAAQ,EAAE,oBAAoB,KAAK,IAAI,CAAC;AAE5E,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,sBAAsB,KAAK,iBAAiB,CAAC;IACpF,OAAO,EAAE,CAAC,KAAK,EAAE,iBAAiB,EAAE,SAAS,EAAE,iBAAiB,KAAK,oBAAoB,CAAC;IAC1F,YAAY,EAAE,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,KAAK,oBAAoB,CAAC;IAC/E,UAAU,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,oBAAoB,CAAC;IAC/D,6EAA6E;IAC7E,KAAK,EAAE,MAAM,oBAAoB,CAAC;IAClC,0EAA0E;IAC1E,eAAe,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,iBAAiB,GAAG,SAAS,CAAC;IAC/D,+EAA+E;IAC/E,SAAS,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IAC9C,WAAW,EAAE,MAAM,oBAAoB,CAAC;IACxC,SAAS,EAAE,CAAC,QAAQ,EAAE,oBAAoB,KAAK,MAAM,IAAI,CAAC;IAC1D,mFAAmF;IACnF,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CAAC,CAAC;AA+HH;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,GAAG,YAAY,CAoa3D"}

package/dist/esm/coordination.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"coordination.d.ts","sourceRoot":"","sources":["../../src/coordination.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAS,KAAK,MAAM,EAAE,KAAK,KAAK,EAAE,MAAM,OAAO,CAAC;AAEvD,KAAK,aAAa,GAAG,MAAM,CAAC;AAW5B;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;mBAAgC,aAAa,EAAE;EAAG,CAAC;AAEnF;;;;GAIG;AACH,eAAO,MAAM,wBAAwB;kBACb,aAAa;;;;;;EAMnC,CAAC;AAEH,OAAO,CAAC,MAAM,sBAAsB,EAAE,OAAO,MAAM,CAAC;AAEpD,2EAA2E;AAC3E,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,CAAC,sBAAsB,CAAC,EAAE,KAAK,CAAC;CAC1C,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC,SAAS,EAAE,kBAAkB,CAAC;CAC/B,CAAC,CAAC;AAEH,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C,4EAA4E;IAC5E,EAAE,EAAE,MAAM,CAAC;IACX,4EAA4E;IAC5E,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CACjC,CAAC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,6EAA6E;IAC7E,SAAS,EAAE,iBAAiB,GAAG,SAAS,CAAC;CAC1C,CAAC,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAC1C,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,OAAO,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACvC,CAAC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC;IACxC,KAAK,EAAE,iBAAiB,CAAC;IACzB,SAAS,EAAE,iBAAiB,CAAC;CAC9B,CAAC,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,CAAC,QAAQ,EAAE,oBAAoB,KAAK,IAAI,CAAC;AAE5E,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,sBAAsB,KAAK,iBAAiB,CAAC;IACpF,OAAO,EAAE,CAAC,KAAK,EAAE,iBAAiB,EAAE,SAAS,EAAE,iBAAiB,KAAK,oBAAoB,CAAC;IAC1F,YAAY,EAAE,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,KAAK,oBAAoB,CAAC;IAC/E,UAAU,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,oBAAoB,CAAC;IAC/D,6EAA6E;IAC7E,KAAK,EAAE,MAAM,oBAAoB,CAAC;IAClC,0EAA0E;IAC1E,eAAe,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,iBAAiB,GAAG,SAAS,CAAC;IAC/D,+EAA+E;IAC/E,SAAS,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IAC9C,WAAW,EAAE,MAAM,oBAAoB,CAAC;IACxC,SAAS,EAAE,CAAC,QAAQ,EAAE,oBAAoB,KAAK,MAAM,IAAI,CAAC;IAC1D,mFAAmF;IACnF,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CAAC,CAAC;AA+HH;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,GAAG,YAAY,CAgT3D"}
+{"version":3,"file":"coordination.d.ts","sourceRoot":"","sources":["../../src/coordination.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAA2C,KAAK,MAAM,EAAE,KAAK,KAAK,EAAE,MAAM,OAAO,CAAC;AAEzF,KAAK,aAAa,GAAG,MAAM,CAAC;AAW5B;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;mBAAgC,aAAa,EAAE;EAAG,CAAC;AAEnF;;;;GAIG;AACH,eAAO,MAAM,wBAAwB;kBACb,aAAa;;;;;;EAMnC,CAAC;AAEH,OAAO,CAAC,MAAM,sBAAsB,EAAE,OAAO,MAAM,CAAC;AAEpD,2EAA2E;AAC3E,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,CAAC,sBAAsB,CAAC,EAAE,KAAK,CAAC;CAC1C,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC,SAAS,EAAE,kBAAkB,CAAC;CAC/B,CAAC,CAAC;AAEH,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C,4EAA4E;IAC5E,EAAE,EAAE,MAAM,CAAC;IACX,4EAA4E;IAC5E,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CACjC,CAAC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,6EAA6E;IAC7E,SAAS,EAAE,iBAAiB,GAAG,SAAS,CAAC;CAC1C,CAAC,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAC1C,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,OAAO,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACvC,CAAC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC;IACxC,KAAK,EAAE,iBAAiB,CAAC;IACzB,SAAS,EAAE,iBAAiB,CAAC;CAC9B,CAAC,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,CAAC,QAAQ,EAAE,oBAAoB,KAAK,IAAI,CAAC;AAE5E,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,sBAAsB,KAAK,iBAAiB,CAAC;IACpF,OAAO,EAAE,CAAC,KAAK,EAAE,iBAAiB,EAAE,SAAS,EAAE,iBAAiB,KAAK,oBAAoB,CAAC;IAC1F,YAAY,EAAE,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,KAAK,oBAAoB,CAAC;IAC/E,UAAU,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,oBAAoB,CAAC;IAC/D,6EAA6E;IAC7E,KAAK,EAAE,MAAM,oBAAoB,CAAC;IAClC,0EAA0E;IAC1E,eAAe,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,iBAAiB,GAAG,SAAS,CAAC;IAC/D,+EAA+E;IAC/E,SAAS,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IAC9C,WAAW,EAAE,MAAM,oBAAoB,CAAC;IACxC,SAAS,EAAE,CAAC,QAAQ,EAAE,oBAAoB,KAAK,MAAM,IAAI,CAAC;IAC1D,mFAAmF;IACnF,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CAAC,CAAC;AA+HH;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,GAAG,YAAY,CAoa3D"}

package/dist/esm/coordination.js

@@ -5,7 +5,7 @@
  * own marker traits and exposes a committed, immutable projection. It does
  * not create a World, run systems, serialize entities, or read geometry.
  */
-import { trait } from "koota";
+import { getStore, trait, universe, unpackEntity } from "koota";
 /**
  * World-held ownership markers for live bindings. Each binding appends one
  * opaque marker and removes only that marker at disposal, so no module-global
@@ -117,16 +117,79 @@ export function bindCoordination(world) {
     if (!world?.isInitialized) {
         fail("a live Koota World is required.");
     }
+    // Koota's numeric Entity methods close over their imported peer universe.
+    // Opposite ESM/CJS imports replace those global methods, even before this
+    // module first loads. Pointer stability alone therefore cannot attest them.
+    const dispatch = {
+        get: 0..get,
+        has: 0..has,
+        add: 0..add,
+        set: 0..set,
+        remove: 0..remove,
+    };
+    const assertRealm = () => {
+        if (universe.worlds[world.id] !== world ||
+            0..get !== dispatch.get ||
+            0..has !== dispatch.has ||
+            0..add !== dispatch.add ||
+            0..set !== dispatch.set ||
+            0..remove !== dispatch.remove) {
+            fail("the Koota entity dispatch realm no longer matches the borrowed World.");
+        }
+    };
+    assertRealm();
     const marker = Object.freeze({});
+    let holder;
+    let holderId;
+    let store;
+    const assertAttested = () => {
+        assertRealm();
+        const markers = world.get(CoordinationBinding)?.markers;
+        let matches = false;
+        try {
+            matches =
+                world.has(holder) &&
+                    getStore(world, CoordinationBinding) === store &&
+                    store.markers[holderId] === markers &&
+                    dispatch.get.call(holder, CoordinationBinding)?.markers === markers;
+        }
+        catch {
+            // A foreign peer may have no World at this numeric ID at all.
+        }
+        assertRealm();
+        if (!matches)
+            fail("the Koota entity dispatch realm cannot attest the World marker.");
+    };
+    const assertOwned = () => {
+        assertAttested();
+        const markers = world.get(CoordinationBinding)?.markers;
+        if (!markers?.includes(marker)) {
+            fail("the binding no longer owns its World marker.");
+        }
+        return markers;
+    };
     const existingMarkers = world.get(CoordinationBinding)?.markers ?? [];
     const markers = [...existingMarkers, marker];
     try {
+        assertRealm();
         if (world.has(CoordinationBinding))
             world.set(CoordinationBinding, { markers });
         else
             world.add(CoordinationBinding({ markers }));
+        assertRealm();
+        store = getStore(world, CoordinationBinding);
+        // World traits live on an existing excluded entity. Find only our marker
+        // by direct store identity once; later checks use this cached holder in O(1).
+        const holders = world.entities.filter((entity) => store.markers[unpackEntity(entity).entityId] === markers);
+        if (holders.length !== 1)
+            fail("the Koota entity dispatch realm has no unique marker holder.");
+        holder = holders[0];
+        holderId = unpackEntity(holder).entityId;
+        assertOwned();
     }
     catch (error) {
+        // Direct World APIs close over the original World even if a callback
+        // changed entity dispatch before we could attest its numeric holder.
         const currentMarkers = world.get(CoordinationBinding)?.markers;
         if (world.isInitialized && currentMarkers?.includes(marker)) {
             const remaining = currentMarkers.filter((candidate) => candidate !== marker);
@@ -138,6 +201,7 @@ export function bindCoordination(world) {
         throw error;
     }
     let disposed = false;
+    let cleanupMarkerRemoved = false;
     let notifying = false;
     let mutating = false;
     let nextRegistrationGeneration = 0;
@@ -154,12 +218,15 @@ export function bindCoordination(world) {
     };
     const assertMutable = () => {
         assertActive();
-        if (!world.isInitialized || !world.get(CoordinationBinding)?.markers.includes(marker)) {
+        if (!world.isInitialized)
             fail("the binding no longer owns its World marker.");
-        }
+        assertOwned();
     };
     const isCurrent = (registration) => {
-        if (!world.isInitialized || !world.has(registration.entity))
+        if (!world.isInitialized)
+            return false;
+        assertOwned();
+        if (!world.has(registration.entity))
             return false;
         return stateIsOwned(registration.entity.get(CoordinationRegistration), marker, registration.state.generation);
     };
@@ -186,6 +253,16 @@ export function bindCoordination(world) {
                     errors.push(error);
                 }
             }
+            // Listener failures occur after commit. A listener may also change peer
+            // dispatch without throwing; report that boundary to the caller too.
+            if (world.isInitialized) {
+                try {
+                    assertOwned();
+                }
+                catch (error) {
+                    errors.push(error);
+                }
+            }
         }
         finally {
             notifying = false;
@@ -222,6 +299,7 @@ export function bindCoordination(world) {
         const capabilities = copyCapabilities(descriptor.capabilities);
         if (registrationsById.has(id))
             fail(`stable id "${id}" is already registered.`);
+        assertOwned();
         if (entity.has(CoordinationRegistration)) {
             fail("entity already carries a coordination registration trait.");
         }
@@ -250,15 +328,20 @@ export function bindCoordination(world) {
         mutating = true;
         try {
             try {
+                assertOwned();
                 entity.add(CoordinationRegistration(state));
+                assertOwned();
             }
             catch (error) {
-                const current = entity.get(CoordinationRegistration);
+                // These captured peer functions use their original lexical universe;
+                // rollback only the trait this attempted registration placed there.
+                const current = dispatch.get.call(entity, CoordinationRegistration);
                 if (stateIsOwned(current, marker, registrationGeneration)) {
-                    entity.remove(CoordinationRegistration);
+                    dispatch.remove.call(entity, CoordinationRegistration);
                 }
                 throw error;
             }
+            assertOwned();
             nextRegistrationGeneration = registrationGeneration;
             registrationsById.set(id, registration);
             registrationsByToken.set(token, registration);
@@ -290,6 +373,7 @@ export function bindCoordination(world) {
         }
         const changed = prepared.some(({ registration, completed }) => !registration.completed ||
             !sameRevisions(registration.completed.revisions, completed.revisions));
+        assertOwned();
         if (!changed)
             return snapshot;
         const snapshotRevision = nextCounter(nextSnapshotRevision, "snapshot revision");
@@ -308,8 +392,11 @@ export function bindCoordination(world) {
         mutating = true;
         try {
             for (const { registration, state } of preparedStates) {
+                assertOwned();
                 registration.entity.set(CoordinationRegistration, state);
+                assertOwned();
             }
+            assertOwned();
             for (const { registration, completed } of preparedStates) {
                 registration.completed = completed;
             }
@@ -325,7 +412,9 @@ export function bindCoordination(world) {
         const snapshotRevision = nextCounter(nextSnapshotRevision, "snapshot revision");
         mutating = true;
         try {
+            assertOwned();
             registration.entity.remove(CoordinationRegistration);
+            assertOwned();
             registrationsById.delete(registration.id);
             registrationsByToken.delete(token);
             return commit(snapshotRevision);
@@ -336,12 +425,16 @@ export function bindCoordination(world) {
     };
     const prune = () => {
         assertActive();
+        if (world.isInitialized)
+            assertOwned();
         const stale = [...registrationsById.values()].filter((registration) => !isCurrent(registration));
         if (stale.length === 0)
             return snapshot;
         const snapshotRevision = nextCounter(nextSnapshotRevision, "snapshot revision");
         mutating = true;
         try {
+            if (world.isInitialized)
+                assertOwned();
             for (const registration of stale) {
                 registrationsById.delete(registration.id);
                 registrationsByToken.delete(registration.token);
@@ -353,10 +446,14 @@ export function bindCoordination(world) {
         }
     };
     const getEntity = (id) => {
+        if (world.isInitialized && !disposed)
+            assertOwned();
         const registration = registrationsById.get(id);
         return registration && isCurrent(registration) ? registration.entity : undefined;
     };
     const getRegistration = (id) => {
+        if (world.isInitialized && !disposed)
+            assertOwned();
         const registration = registrationsById.get(id);
         return registration && isCurrent(registration) ? registration.token : undefined;
     };
@@ -373,24 +470,49 @@ export function bindCoordination(world) {
         if (disposed)
             return;
         assertActive();
+        if (world.isInitialized) {
+            if (cleanupMarkerRemoved)
+                assertRealm();
+            else
+                assertOwned();
+        }
         const snapshotRevision = nextCounter(nextSnapshotRevision, "snapshot revision");
         mutating = true;
         try {
-            listeners.clear();
-            for (const registration of registrationsById.values()) {
-                if (isCurrent(registration))
-                    registration.entity.remove(CoordinationRegistration);
+            if (!cleanupMarkerRemoved) {
+                for (const registration of registrationsById.values()) {
+                    if (isCurrent(registration)) {
+                        assertOwned();
+                        registration.entity.remove(CoordinationRegistration);
+                        assertOwned();
+                    }
+                }
+                if (world.isInitialized) {
+                    const remaining = assertOwned().filter((candidate) => candidate !== marker);
+                    try {
+                        if (remaining.length === 0)
+                            world.remove(CoordinationBinding);
+                        else
+                            world.set(CoordinationBinding, { markers: remaining });
+                    }
+                    catch (error) {
+                        assertRealm();
+                        // A same-peer callback can throw after the marker write completed.
+                        // Remember only this disposal's confirmed removal, so a retry can
+                        // finish without treating an externally lost marker as ownership.
+                        cleanupMarkerRemoved = !world.get(CoordinationBinding)?.markers.includes(marker);
+                        throw error;
+                    }
+                    // Final removal intentionally makes owned-marker attestation absent.
+                    assertRealm();
+                    cleanupMarkerRemoved = true;
+                }
             }
+            if (world.isInitialized)
+                assertRealm();
+            listeners.clear();
             registrationsById.clear();
             registrationsByToken.clear();
-            const markerState = world.get(CoordinationBinding);
-            if (world.isInitialized && markerState?.markers.includes(marker)) {
-                const remaining = markerState.markers.filter((candidate) => candidate !== marker);
-                if (remaining.length === 0)
-                    world.remove(CoordinationBinding);
-                else
-                    world.set(CoordinationBinding, { markers: remaining });
-            }
             nextSnapshotRevision = snapshotRevision;
             snapshot = makeSnapshot(nextSnapshotRevision, []);
             disposed = true;

package/docs/API.md

@@ -360,6 +360,19 @@ trait before rethrowing, so an existing peer binding remains intact and the
 caller may retry registration. `getEntity` and `getRegistration` return `undefined` for a stale
 registration.
 
+Use one Koota runtime and module format per process. Koota
+0.6.6 replaces numeric entity dispatch when its opposite ESM/CommonJS format
+loads. Binding rejects a foreign peer World before adding its marker, and
+attests the existing marker holder to detect contamination that predates the
+first kit import. Later live reads, mutations, and cleanup throw a
+`coordination:` dispatch-realm error if that attestation fails; they preserve
+the last committed snapshot and subscribers. `getSnapshot()` remains readable.
+A subscriber that changes dispatch after publication triggers an error after
+all listeners receive the newly committed snapshot; that publication stays
+committed. An opposite-format `koota-kit/spatial` import is safe because that entry does
+not load Koota. This guard detects the known peer-format conflict; it does not
+repair global methods or make mixed-format entity operations interoperable.
+
 `publishBatch` validates every token and metadata value before it changes any
 owned trait or snapshot. Its completed projection changes only after every raw
 Koota trait write succeeds; a Koota callback error can leave partial raw mirror

package/docs/ARCHITECTURE.md

@@ -67,7 +67,28 @@ authority over caller entities and traits. Each binding owns an opaque marker
 held on that World and registration records tagged with that marker, so it can
 remove only its own records. Bindings may coexist only for disjoint entities.
 `CoordinationBinding` and `CoordinationRegistration` have one identity per
-module format; consumers should not mix package formats in a single Koota World.
+module format. Applications must use one Koota runtime and module format per
+process. Koota 0.6.6 installs numeric entity methods globally; loading
+its opposite ESM/CommonJS format replaces dispatch for already live entities.
+Coordination rejects a World outside its imported peer universe before adding
+markers. It then attests dispatch against the existing World marker holder,
+using the public `getStore`, `unpackEntity`, and `universe` APIs. The initial
+holder lookup inspects only its owned marker store; subsequent checks cache the
+holder and require constant work. There is no probe entity, hidden World,
+prototype repair, or second World registry.
+
+Every live read and raw mutation verifies that dispatch and marker ownership
+still agree. Callbackful writes are checked before and after the raw operation
+and before committing metadata or cleanup. A mismatch throws while preserving
+the previous completed snapshot and subscribers. A dispatch change during listener
+delivery is a postcommit error: all listeners receive the new committed
+snapshot, and that snapshot stays published. A raw callback may already
+have written or removed an owned trait; that partial raw state is outside the
+completed projection. Registration rollback uses the previously attested peer
+functions solely for its just-added owned trait. Initial binding rollback uses
+direct World methods. Final marker removal checks dispatch without requiring
+the removed marker, then commits cleanup. Destroyed-World cleanup needs no
+entity dispatch, and an already disposed binding stays idempotent.
 
 Before a publication, coordination validates every update and produces a new
 immutable view sorted by caller-authored stable ID. Koota raw trait callbacks

package/package.json

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