koota-kit 0.6.2 → 0.7.1

package/dist/esm/coordination.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Borrowed-World coordination for completed model metadata.
+ *
+ * The caller owns the Koota World and its entities. This module only adds its
+ * own marker traits and exposes a committed, immutable projection. It does
+ * not create a World, run systems, serialize entities, or read geometry.
+ */
+import { type Entity, type World } from "koota";
+type BindingMarker = object;
+/**
+ * World-held ownership markers for live bindings. Each binding appends one
+ * opaque marker and removes only that marker at disposal, so no module-global
+ * registry or per-bind Koota trait allocation is needed.
+ */
+export declare const CoordinationBinding: import("koota").Trait<{
+    markers: () => BindingMarker[];
+}>;
+/**
+ * The only trait this module places on caller-owned model entities. Its
+ * fields are a diagnostic mirror of the binding's committed projection;
+ * callers must use `getSnapshot` for an immutable completed view.
+ */
+export declare const CoordinationRegistration: import("koota").Trait<{
+    marker: () => BindingMarker;
+    generation: number;
+    id: string;
+    geometryRevision: number;
+    poseRevision: number;
+    transformRevision: number;
+}>;
+declare const registrationTokenBrand: unique symbol;
+/** An opaque capability token returned only by `Coordination.register`. */
+export type RegistrationToken = {
+    readonly [registrationTokenBrand]: never;
+};
+export type CompletedRevisions = Readonly<{
+    geometry: number;
+    pose: number;
+    transform: number;
+}>;
+export type CompletedMetadata = Readonly<{
+    revisions: CompletedRevisions;
+}>;
+export type CoordinationDescriptor = Readonly<{
+    /** A non-empty caller-authored identity, never a packed Koota entity ID. */
+    id: string;
+    /** Stable, sorted capability labels. Change them by unregistering first. */
+    capabilities: readonly string[];
+}>;
+export type CoordinationEntry = Readonly<{
+    id: string;
+    capabilities: readonly string[];
+    /** Undefined until the producer has explicitly published completed facts. */
+    completed: CompletedMetadata | undefined;
+}>;
+export type CoordinationSnapshot = Readonly<{
+    /** A binding-local publication generation, not a producer content revision. */
+    revision: number;
+    /** Entries sorted lexically by stable caller-authored id. */
+    entries: readonly CoordinationEntry[];
+}>;
+export type CoordinationUpdate = Readonly<{
+    token: RegistrationToken;
+    completed: CompletedMetadata;
+}>;
+export type CoordinationListener = (snapshot: CoordinationSnapshot) => void;
+export type Coordination = Readonly<{
+    readonly world: World;
+    register: (entity: Entity, descriptor: CoordinationDescriptor) => RegistrationToken;
+    publish: (token: RegistrationToken, completed: CompletedMetadata) => CoordinationSnapshot;
+    publishBatch: (updates: readonly CoordinationUpdate[]) => CoordinationSnapshot;
+    unregister: (token: RegistrationToken) => CoordinationSnapshot;
+    /** Remove registrations whose entity or owned trait is no longer current. */
+    prune: () => CoordinationSnapshot;
+    /** Recover a current token after a listener threw during registration. */
+    getRegistration: (id: string) => RegistrationToken | undefined;
+    /** Resolve a stable identity only while its registered entity remains live. */
+    getEntity: (id: string) => Entity | undefined;
+    getSnapshot: () => CoordinationSnapshot;
+    subscribe: (listener: CoordinationListener) => () => void;
+    /** Idempotently remove this module's traits; never destroys the borrowed World. */
+    dispose: () => void;
+}>;
+/**
+ * Bind to a caller-owned Koota World. A live binding writes its opaque marker
+ * onto that same World, without a hidden module-global World registry. Several
+ * bindings may coexist only while they register disjoint caller entities.
+ */
+export declare function bindCoordination(world: World): Coordination;
+export {};
+//# sourceMappingURL=coordination.d.ts.map

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

@@ -0,0 +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;AAwHH;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,GAAG,YAAY,CAgT3D"}

package/dist/esm/coordination.js

@@ -0,0 +1,408 @@
+/**
+ * Borrowed-World coordination for completed model metadata.
+ *
+ * The caller owns the Koota World and its entities. This module only adds its
+ * 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";
+/**
+ * World-held ownership markers for live bindings. Each binding appends one
+ * opaque marker and removes only that marker at disposal, so no module-global
+ * registry or per-bind Koota trait allocation is needed.
+ */
+export const CoordinationBinding = trait({ markers: () => [] });
+/**
+ * The only trait this module places on caller-owned model entities. Its
+ * fields are a diagnostic mirror of the binding's committed projection;
+ * callers must use `getSnapshot` for an immutable completed view.
+ */
+export const CoordinationRegistration = trait({
+    marker: () => ({}),
+    generation: 0,
+    id: "",
+    geometryRevision: 0,
+    poseRevision: 0,
+    transformRevision: 0,
+});
+const tokenMarker = Symbol("koota-kit.coordination.token");
+function fail(message) {
+    throw new Error(`coordination: ${message}`);
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null;
+}
+function requireNonEmptyString(value, name) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new TypeError(`coordination: ${name} must be a non-empty string.`);
+    }
+    return value;
+}
+function copyCapabilities(value) {
+    if (!Array.isArray(value)) {
+        throw new TypeError("coordination: descriptor.capabilities must be an array of non-empty strings.");
+    }
+    const capabilities = value.map((capability) => requireNonEmptyString(capability, "capability"));
+    capabilities.sort((left, right) => Number(left > right) - Number(left < right));
+    for (let index = 1; index < capabilities.length; index += 1) {
+        if (capabilities[index] === capabilities[index - 1]) {
+            throw new TypeError(`coordination: duplicate capability "${capabilities[index]}".`);
+        }
+    }
+    return Object.freeze(capabilities);
+}
+function copyRevisions(value) {
+    if (!isObject(value)) {
+        throw new TypeError("coordination: completed.revisions must be an object.");
+    }
+    const names = ["geometry", "pose", "transform"];
+    const values = names.map((name) => value[name]);
+    for (const [index, revision] of values.entries()) {
+        if (!Number.isSafeInteger(revision) || revision < 0) {
+            throw new RangeError(`coordination: completed.revisions.${names[index]} must be a non-negative safe integer.`);
+        }
+    }
+    return Object.freeze({
+        geometry: values[0],
+        pose: values[1],
+        transform: values[2],
+    });
+}
+function copyCompleted(value) {
+    if (!isObject(value)) {
+        throw new TypeError("coordination: completed metadata must be an object.");
+    }
+    return Object.freeze({ revisions: copyRevisions(value.revisions) });
+}
+function sameRevisions(left, right) {
+    return (left.geometry === right.geometry &&
+        left.pose === right.pose &&
+        left.transform === right.transform);
+}
+function assertNoRegression(previous, next) {
+    if (!previous)
+        return;
+    for (const name of ["geometry", "pose", "transform"]) {
+        if (next.revisions[name] < previous.revisions[name]) {
+            throw new RangeError(`coordination: completed revision ${name} may not decrease.`);
+        }
+    }
+}
+function makeSnapshot(revision, registrations) {
+    const entries = [...registrations]
+        .map((registration) => Object.freeze({
+        id: registration.id,
+        capabilities: registration.capabilities,
+        completed: registration.completed,
+    }))
+        .sort((left, right) => Number(left.id > right.id) - Number(left.id < right.id));
+    return Object.freeze({ revision, entries: Object.freeze(entries) });
+}
+function stateIsOwned(state, marker, generation) {
+    return state?.marker === marker && state.generation === generation;
+}
+/**
+ * Bind to a caller-owned Koota World. A live binding writes its opaque marker
+ * onto that same World, without a hidden module-global World registry. Several
+ * bindings may coexist only while they register disjoint caller entities.
+ */
+export function bindCoordination(world) {
+    if (!world?.isInitialized) {
+        fail("a live Koota World is required.");
+    }
+    const marker = Object.freeze({});
+    const existingMarkers = world.get(CoordinationBinding)?.markers ?? [];
+    const markers = [...existingMarkers, marker];
+    try {
+        if (world.has(CoordinationBinding))
+            world.set(CoordinationBinding, { markers });
+        else
+            world.add(CoordinationBinding({ markers }));
+    }
+    catch (error) {
+        const currentMarkers = world.get(CoordinationBinding)?.markers;
+        if (world.isInitialized && currentMarkers?.includes(marker)) {
+            const remaining = currentMarkers.filter((candidate) => candidate !== marker);
+            if (remaining.length === 0)
+                world.remove(CoordinationBinding);
+            else
+                world.set(CoordinationBinding, { markers: remaining });
+        }
+        throw error;
+    }
+    let disposed = false;
+    let notifying = false;
+    let mutating = false;
+    let nextRegistrationGeneration = 0;
+    let nextSnapshotRevision = 0;
+    const registrationsById = new Map();
+    const registrationsByToken = new Map();
+    const listeners = new Set();
+    let snapshot = makeSnapshot(nextSnapshotRevision, registrationsById.values());
+    const assertActive = () => {
+        if (disposed)
+            fail("the binding has been disposed.");
+        if (notifying || mutating)
+            fail("mutating a binding while it notifies listeners is not allowed.");
+    };
+    const assertMutable = () => {
+        assertActive();
+        if (!world.isInitialized || !world.get(CoordinationBinding)?.markers.includes(marker)) {
+            fail("the binding no longer owns its World marker.");
+        }
+    };
+    const isCurrent = (registration) => {
+        if (!world.isInitialized || !world.has(registration.entity))
+            return false;
+        return stateIsOwned(registration.entity.get(CoordinationRegistration), marker, registration.state.generation);
+    };
+    const registrationFor = (token) => {
+        const registration = registrationsByToken.get(token);
+        if (!registration || token[tokenMarker] !== marker) {
+            fail("the registration token does not belong to this binding.");
+        }
+        if (!isCurrent(registration)) {
+            fail("the registration token is stale; call prune before re-registering its id.");
+        }
+        return registration;
+    };
+    const notify = () => {
+        const deliveries = [...listeners];
+        const errors = [];
+        notifying = true;
+        try {
+            for (const listener of deliveries) {
+                try {
+                    listener(snapshot);
+                }
+                catch (error) {
+                    errors.push(error);
+                }
+            }
+        }
+        finally {
+            notifying = false;
+        }
+        if (errors.length === 1)
+            throw errors[0];
+        if (errors.length > 1) {
+            const error = Object.assign(new Error("coordination: listener failures after commit."), {
+                errors: Object.freeze(errors),
+            });
+            throw error;
+        }
+    };
+    const nextCounter = (value, name) => {
+        const next = value + 1;
+        if (!Number.isSafeInteger(next)) {
+            throw new RangeError(`coordination: ${name} exceeded the safe integer range.`);
+        }
+        return next;
+    };
+    const commit = (revision) => {
+        nextSnapshotRevision = revision;
+        snapshot = makeSnapshot(revision, registrationsById.values());
+        notify();
+        return snapshot;
+    };
+    const register = (entity, descriptor) => {
+        assertMutable();
+        if (!world.has(entity))
+            fail("entity must be live in this binding's World.");
+        if (!isObject(descriptor))
+            throw new TypeError("coordination: descriptor must be an object.");
+        const id = requireNonEmptyString(descriptor.id, "descriptor.id");
+        const capabilities = copyCapabilities(descriptor.capabilities);
+        if (registrationsById.has(id))
+            fail(`stable id "${id}" is already registered.`);
+        if (entity.has(CoordinationRegistration)) {
+            fail("entity already carries a coordination registration trait.");
+        }
+        const registrationGeneration = nextCounter(nextRegistrationGeneration, "registration generation");
+        const snapshotRevision = nextCounter(nextSnapshotRevision, "snapshot revision");
+        const state = Object.freeze({
+            marker,
+            generation: registrationGeneration,
+            id,
+            geometryRevision: 0,
+            poseRevision: 0,
+            transformRevision: 0,
+        });
+        const token = Object.freeze({ [tokenMarker]: marker });
+        const registration = {
+            entity,
+            token,
+            state,
+            id,
+            capabilities,
+            completed: undefined,
+        };
+        // Every validation above happens before the Koota marker or this binding's
+        // projection changes. Koota callbacks can observe this raw trait; they are
+        // deliberately outside the atomic committed-snapshot contract.
+        mutating = true;
+        try {
+            try {
+                entity.add(CoordinationRegistration(state));
+            }
+            catch (error) {
+                const current = entity.get(CoordinationRegistration);
+                if (stateIsOwned(current, marker, registrationGeneration)) {
+                    entity.remove(CoordinationRegistration);
+                }
+                throw error;
+            }
+            nextRegistrationGeneration = registrationGeneration;
+            registrationsById.set(id, registration);
+            registrationsByToken.set(token, registration);
+            commit(snapshotRevision);
+        }
+        finally {
+            mutating = false;
+        }
+        return token;
+    };
+    const publishBatch = (updates) => {
+        assertMutable();
+        if (!Array.isArray(updates)) {
+            throw new TypeError("coordination: publishBatch updates must be an array.");
+        }
+        const prepared = [];
+        const seen = new Set();
+        for (const update of updates) {
+            if (!isObject(update))
+                throw new TypeError("coordination: each update must be an object.");
+            const candidate = update;
+            if (seen.has(candidate.token))
+                fail("publishBatch contains a duplicate registration token.");
+            seen.add(candidate.token);
+            const registration = registrationFor(candidate.token);
+            const completed = copyCompleted(candidate.completed);
+            assertNoRegression(registration.completed, completed);
+            prepared.push({ registration, completed });
+        }
+        const changed = prepared.some(({ registration, completed }) => !registration.completed ||
+            !sameRevisions(registration.completed.revisions, completed.revisions));
+        if (!changed)
+            return snapshot;
+        const snapshotRevision = nextCounter(nextSnapshotRevision, "snapshot revision");
+        // Raw traits can expose individual mirror writes to Koota callbacks, but
+        // the committed projection changes only after every mirror write succeeds.
+        const preparedStates = prepared.map(({ registration, completed }) => ({
+            registration,
+            completed,
+            state: Object.freeze({
+                ...registration.state,
+                geometryRevision: completed.revisions.geometry,
+                poseRevision: completed.revisions.pose,
+                transformRevision: completed.revisions.transform,
+            }),
+        }));
+        mutating = true;
+        try {
+            for (const { registration, state } of preparedStates) {
+                registration.entity.set(CoordinationRegistration, state);
+            }
+            for (const { registration, completed } of preparedStates) {
+                registration.completed = completed;
+            }
+            return commit(snapshotRevision);
+        }
+        finally {
+            mutating = false;
+        }
+    };
+    const unregister = (token) => {
+        assertMutable();
+        const registration = registrationFor(token);
+        const snapshotRevision = nextCounter(nextSnapshotRevision, "snapshot revision");
+        mutating = true;
+        try {
+            registration.entity.remove(CoordinationRegistration);
+            registrationsById.delete(registration.id);
+            registrationsByToken.delete(token);
+            return commit(snapshotRevision);
+        }
+        finally {
+            mutating = false;
+        }
+    };
+    const prune = () => {
+        assertActive();
+        const stale = [...registrationsById.values()].filter((registration) => !isCurrent(registration));
+        if (stale.length === 0)
+            return snapshot;
+        const snapshotRevision = nextCounter(nextSnapshotRevision, "snapshot revision");
+        mutating = true;
+        try {
+            for (const registration of stale) {
+                registrationsById.delete(registration.id);
+                registrationsByToken.delete(registration.token);
+            }
+            return commit(snapshotRevision);
+        }
+        finally {
+            mutating = false;
+        }
+    };
+    const getEntity = (id) => {
+        const registration = registrationsById.get(id);
+        return registration && isCurrent(registration) ? registration.entity : undefined;
+    };
+    const getRegistration = (id) => {
+        const registration = registrationsById.get(id);
+        return registration && isCurrent(registration) ? registration.token : undefined;
+    };
+    const getSnapshot = () => snapshot;
+    const subscribe = (listener) => {
+        if (disposed)
+            fail("the binding has been disposed.");
+        if (typeof listener !== "function")
+            throw new TypeError("coordination: listener must be a function.");
+        listeners.add(listener);
+        return () => listeners.delete(listener);
+    };
+    const dispose = () => {
+        if (disposed)
+            return;
+        assertActive();
+        const snapshotRevision = nextCounter(nextSnapshotRevision, "snapshot revision");
+        mutating = true;
+        try {
+            listeners.clear();
+            for (const registration of registrationsById.values()) {
+                if (isCurrent(registration))
+                    registration.entity.remove(CoordinationRegistration);
+            }
+            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;
+        }
+        finally {
+            mutating = false;
+        }
+    };
+    return Object.freeze({
+        world,
+        register,
+        publish: (token, completed) => publishBatch([{ token, completed }]),
+        publishBatch,
+        unregister,
+        prune,
+        getRegistration,
+        getEntity,
+        getSnapshot,
+        subscribe,
+        dispose,
+    });
+}

package/dist/esm/index.d.ts

@@ -10,4 +10,6 @@ export { defineEventLog } from "./eventLog.js";
 export type { EventLog } from "./eventLog.js";
 export { defineTrait } from "./traits/index.js";
 export type { SafeSchema } from "./traits/index.js";
+export { bindCoordination, CoordinationBinding, CoordinationRegistration, } from "./coordination.js";
+export type { CompletedMetadata, CompletedRevisions, Coordination, CoordinationDescriptor, CoordinationEntry, CoordinationListener, CoordinationSnapshot, CoordinationUpdate, RegistrationToken, } from "./coordination.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,YAAY,EACZ,aAAa,EACb,cAAc,EACd,eAAe,EACf,QAAQ,EACR,kBAAkB,EAClB,aAAa,EACb,KAAK,GACN,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE5E,OAAO,EACL,MAAM,EACN,SAAS,EACT,gBAAgB,EAChB,YAAY,EACZ,SAAS,EACT,OAAO,EACP,OAAO,EACP,IAAI,EACJ,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,OAAO,EACP,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,SAAS,GACV,MAAM,UAAU,CAAC;AAClB,YAAY,EACV,SAAS,EACT,iBAAiB,EACjB,QAAQ,EACR,SAAS,EACT,iBAAiB,EACjB,UAAU,EACV,kBAAkB,GACnB,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC1F,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAEzD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAEvE,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,YAAY,EACZ,aAAa,EACb,cAAc,EACd,eAAe,EACf,QAAQ,EACR,kBAAkB,EAClB,aAAa,EACb,KAAK,GACN,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE5E,OAAO,EACL,MAAM,EACN,SAAS,EACT,gBAAgB,EAChB,YAAY,EACZ,SAAS,EACT,OAAO,EACP,OAAO,EACP,IAAI,EACJ,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,OAAO,EACP,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,SAAS,GACV,MAAM,UAAU,CAAC;AAClB,YAAY,EACV,SAAS,EACT,iBAAiB,EACjB,QAAQ,EACR,SAAS,EACT,iBAAiB,EACjB,UAAU,EACV,kBAAkB,GACnB,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC1F,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAEzD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAEvE,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,iBAAiB,EACjB,kBAAkB,EAClB,YAAY,EACZ,sBAAsB,EACtB,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,mBAAmB,CAAC"}

package/dist/esm/index.js

@@ -17,3 +17,4 @@ export { createMasterSeed, deriveSeed, isMasterSeed, MASTER_SEED_BYTES } from ".
 export { createSchedule } from "./schedule.js";
 export { defineEventLog } from "./eventLog.js";
 export { defineTrait } from "./traits/index.js";
+export { bindCoordination, CoordinationBinding, CoordinationRegistration, } from "./coordination.js";

package/docs/API.md

@@ -251,6 +251,108 @@ scratch map. `drain` truncates the live array in place so an existing internal
 reference is not orphaned. Empty reads do not create a scratch entry. `peek`
 returns a detached array; `size` does not allocate.
 
+## `coordination`
+
+Import from `koota-kit/coordination` or the root. This React-free entry binds
+to an existing caller-owned Koota `World`; it never creates, resets, or
+destroys that World or its entities.
+
+```ts
+type CompletedRevisions = Readonly<{
+  geometry: number;
+  pose: number;
+  transform: number;
+}>;
+
+type CompletedMetadata = Readonly<{ revisions: CompletedRevisions }>;
+type CoordinationDescriptor = Readonly<{
+  id: string;
+  capabilities: readonly string[];
+}>;
+type CoordinationUpdate = Readonly<{
+  token: RegistrationToken;
+  completed: CompletedMetadata;
+}>;
+type CoordinationEntry = Readonly<{
+  id: string;
+  capabilities: readonly string[];
+  completed: CompletedMetadata | undefined;
+}>;
+type CoordinationSnapshot = Readonly<{
+  revision: number;
+  entries: readonly CoordinationEntry[];
+}>;
+
+function bindCoordination(world: World): Coordination;
+```
+
+`id` is a caller-authored, non-empty stable string. It is not a packed Koota
+entity ID. Capability labels are copied, sorted, and must be unique non-empty
+strings; change a capability set by unregistering and registering again.
+`completed.revisions.geometry`, `.pose`, and `.transform` are all required
+non-negative safe integers. They may advance independently but no dimension
+may decrease. A new completed value with all three values equal is a no-op.
+
+```ts
+type Coordination = Readonly<{
+  readonly world: World;
+  register(entity: Entity, descriptor: CoordinationDescriptor): RegistrationToken;
+  publish(token: RegistrationToken, completed: CompletedMetadata): CoordinationSnapshot;
+  publishBatch(updates: readonly CoordinationUpdate[]): CoordinationSnapshot;
+  unregister(token: RegistrationToken): CoordinationSnapshot;
+  prune(): CoordinationSnapshot;
+  getRegistration(id: string): RegistrationToken | undefined;
+  getEntity(id: string): Entity | undefined;
+  getSnapshot(): CoordinationSnapshot;
+  subscribe(listener: (snapshot: CoordinationSnapshot) => void): () => void;
+  dispose(): void;
+}>;
+```
+
+`register` accepts only a live entity in the supplied `World`; cross-World,
+destroyed, duplicated, and externally conflicting entities are rejected before
+the coordinator mutates its projection. The opaque token is scoped to one
+binding and to the entity generation. `publish` and `unregister` reject a
+stale token. If an entity is destroyed or the owned registration trait is
+removed externally, call `prune()` to publish its removal before reusing the
+stable ID. If Koota rejects the binding marker during construction or rejects an
+add callback during `register`, the binding removes only its just-added marker or
+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.
+
+`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
+writes, which are outside that projection. A completed snapshot is immutable,
+detached from the caller input, and sorted by stable ID. Producers that need a
+cross-producer atomic cohort must publish through the same binding; disjoint
+bindings are independent cohorts. `revision` is a binding-local committed
+publication generation, not a geometry, pose, transform, source-hash, or
+provider freshness claim. It deliberately does not serialize entities or join
+the RNG/clock `WorldSnapshot` boundary.
+
+Subscribers each receive the same committed snapshot. A subscribe or
+unsubscribe during delivery affects only a later publication. Registry mutation
+during delivery or an owned Koota trait callback throws. Listener failures are
+reported after every listener has been offered the committed snapshot; they do
+not roll back it. When a listener throws during `register`, use
+`getRegistration(id)` to recover the successfully committed token.
+
+`dispose` is idempotent. It removes only this binding's registration traits and
+World-held ownership marker, keeps other bindings' markers, and never destroys
+or resets the borrowed World, its entities, caller traits, providers, or
+buffers. Several bindings may share a World only for disjoint entities.
+
+`CoordinationBinding` and `CoordinationRegistration` are the exported Koota
+trait identities for this module format. The binding trait holds only opaque
+per-binding ownership markers on the borrowed World; it is removed when the
+last binding disposes. Direct trait mutation is outside the immutable committed-
+snapshot contract; use the binding methods for publication. The module has no
+renderer, React, producer, geometry, spatial-index, or AI dependency. Exact
+adapters must own their own immutable buffers or read leases and report their
+own source, topology, frame, unit, and freshness contracts.
+
 ## `react`
 
 Import from `koota-kit/react`. Requires `react` (`>=18`), an optional peer