koota-kit 0.6.0 → 0.7.0

package/docs/ARCHITECTURE.md

@@ -13,6 +13,7 @@ rng ──────────────────> seedrandom + seed
 world ────────────────> koota + rng
 schedule ─────────────> world (advanceClock) + WorldHandle scratch
 eventLog ─────────────> WorldHandle scratch
+coordination ─────────> koota (borrowed World, no sibling runtime dependency)
 react ────────────────> koota/react + react + world (type only)
 index ────────────────> public re-exports only (never react)
 ```
@@ -44,6 +45,25 @@ than carrying it, so one huge dt cannot cause a catch-up storm.
 `eventLog` uses the handle's scratch map so event lifetime matches world
 lifetime. It does not use a process-global queue.
 
+`coordination` accepts an existing raw Koota `World` and attaches only its
+own ownership and registration traits. Its immutable snapshot is a completed
+metadata projection, not a second World or ECS serializer. The World retains
+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.
+
+Before a publication, coordination validates every update and produces a new
+immutable view sorted by caller-authored stable ID. Koota raw trait callbacks
+may see the individual mirror writes, so the completed view changes only after
+all mirror writes succeed and is the sole atomic observer boundary. Producers
+share a binding to form one atomic cohort; disjoint bindings are independent
+cohorts. Listener callbacks cannot mutate the registry while delivery
+is active. There is no event-log drain: every coordination subscriber is
+independent. Entity destruction is detected by `World.has` and becomes a
+published removal only when the caller explicitly invokes `prune`.
+
 `react` is the only module that imports React, through `koota/react`. It is
 reachable only from the `koota-kit/react` subpath: `index` does not re-export it,
 and `react` is an optional peer dependency, so an application that never imports
@@ -70,6 +90,10 @@ it reaches `react` or `koota/react`.
     delivered at any frame rate runs the same steps in the same order, as long
     as no single tick owes more than `maxSteps` (beyond that, the excess is
     dropped by design, so a one-second frame and sixty 1/60 s frames differ).
+11. A coordination snapshot publishes only fully validated completed metadata;
+    failed batch preparation leaves the prior projection visible.
+12. Coordination disposal never destroys or resets a caller-owned World,
+    entity, caller trait, provider, or geometry buffer.
 
 ## Performance choices
 
@@ -78,6 +102,9 @@ it reaches `react` or `koota/react`.
   through JSON.
 - Event logs allocate on first push, leave scratch untouched for empty reads,
   truncate in place on drain, and expose a non-allocating `size` operation.
+- Coordination snapshots are rebuilt only after a completed registration,
+  publication, removal, or explicit prune. Equal completed revisions retain
+  the prior snapshot identity and do not notify subscribers.
 - The package is not bundled. ESM and CommonJS outputs preserve small subpath
   entry points and let application bundlers tree-shake normally.
 
@@ -92,3 +119,7 @@ it reaches `react` or `koota/react`.
   passes, so the application still owns stable domain keys.
 - No multi-consumer queue semantics: publish separate logs when two systems
   must independently consume the same fact.
+- No geometry, broadphase, exact-query, source/provenance, topology, unit,
+  frame, pose, renderer, React, or AI adapter: those are later explicit
+  producer/query contracts. A coordination revision is not evidence that a
+  provider's buffers are immutable or fresh.

package/docs/contributing.md

@@ -20,8 +20,9 @@ Sourcey site.
 Branch from `main`, make a focused Conventional Commit, open an upstream pull
 request, and keep the branch current by merging `main` into it when necessary.
 The protected path uses automated checks rather than a routine human approval;
-merge commits preserve the constituent history. Do not hand-edit versions or
-`CHANGELOG.md`: Release Please owns them.
+merge commits preserve the constituent history and GitHub release notes list
+each merged pull request once. Do not hand-edit versions or `CHANGELOG.md`:
+Release Please owns them.
 
 Read the repository [contribution guide](https://github.com/jbcom/koota-kit/blob/main/CONTRIBUTING.md)
 and [agent instructions](https://github.com/jbcom/koota-kit/blob/main/AGENTS.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "koota-kit",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Deterministic Koota simulation conventions: world lifecycle, dual RNG streams, safe object traits, and world-scoped event logs.",
   "type": "module",
   "license": "MIT",
@@ -83,6 +83,16 @@
         "default": "./dist/cjs/eventLog.cjs"
       }
     },
+    "./coordination": {
+      "import": {
+        "types": "./dist/esm/coordination.d.ts",
+        "default": "./dist/esm/coordination.js"
+      },
+      "require": {
+        "types": "./dist/cjs/coordination.d.cts",
+        "default": "./dist/cjs/coordination.cjs"
+      }
+    },
     "./react": {
       "import": {
         "types": "./dist/esm/react.d.ts",
@@ -204,6 +214,9 @@
       "eventLog": [
         "./dist/esm/eventLog.d.ts"
       ],
+      "coordination": [
+        "./dist/esm/coordination.d.ts"
+      ],
       "react": [
         "./dist/esm/react.d.ts"
       ],