@forgeax/engine-ecs 0.1.33 → 0.1.35

package/README.md

@@ -11,7 +11,7 @@ mutation, two schedules, resources, time, and optional shared numeric kernels.
 > domains.
 
 `World` directly owns its graph, entity records, managed stores, relationship
-indexes, epochs, structural evidence, and execution health. Query, command, and
+indexes, row/block revisions, and execution health. Query, command, and
 lifecycle helpers receive only the typed package-internal capabilities they
 actually consume; there is no `WorldCore`, `WorldData`, or second state bag.
 
@@ -199,7 +199,9 @@ for (const span of writable.spans().unwrap()) {
 Incremental owners keep their own `changed` Query. Component row versions are
 the value-change authority; `World.getStructureEpoch()` invalidates caches when
 entity/component membership changes. There is no parallel value-event journal
-or projection-change object vocabulary.
+or projection-change object vocabulary. A changed query uses the existing
+component mutation epochs to skip row scans when any required changed input
+has no unobserved write; row versions still select the exact result otherwise.
 
 ```ts
 const structureEpoch = world.getStructureEpoch();
@@ -220,24 +222,38 @@ const added = world.query({ read: [Position], added: [Position] }).unwrap();
 for (const row of added) initializeProjection(row.entity, row.get(Position));
 ```
 
-Structural membership facts have a bounded, typed cursor in the projection
-subpath. Read after the last cursor, consume every returned event, and rebuild
-from an ordinary query when the ring reports overflow:
+State consumers use `createStateProjection` from the projection subpath. A consumer
+retains accepted identities per 256-row block; current membership and component
+revisions discover the next unique source-index work set. Deletion, migration,
+sparse tags and generation reuse reconcile against final World records, without
+a structural event history or an overflow recovery mode.
 
 ```ts
-import { readStructuralEvidence } from '@forgeax/engine-ecs/projection';
-
-let cursor = 0;
-const evidence = readStructuralEvidence(world, cursor);
-if (evidence.status === 'overflow') {
-  rebuildProjectionFromQuery(world);
-  cursor = evidence.cursor;
-} else {
-  for (const event of evidence.events) applyStructuralEvent(event);
-  cursor = evidence.cursor;
+import { createStateProjection } from '@forgeax/engine-ecs/projection';
+
+const projection = createStateProjection(world, [Position]);
+const candidate = projection.read();
+for (const index of candidate.indices) {
+  reconcileCurrentEntity(index, projection.entity(index));
 }
+candidate.accept(); // Only after the consumer successfully applies its changes.
 ```
 
+| Boundary | Contract |
+|:--|:--|
+| Discovery | Enumerates current nonempty relevant tables plus retained deleted blocks; unchanged blocks skip row reads. |
+| Acceptance | Synchronous, consumer-local; a new read, invalidation, or World mutation expires an outstanding candidate. |
+| Failure | Leave the batch unaccepted and read again; poisoned Worlds reject projection. |
+| Scratch | `indices` is borrowed until the next `read`; do not retain it as a snapshot. |
+| Invalidation | Preserves prior identities so deleted sources can still leave the consumer. |
+| Fast check | `isCurrent()` compares accepted World epochs without allocating a batch; unrelated writes may return false. |
+| Root facts | `membershipChanged` and `changedComponents` conservatively identify work domains; `changed(entity, component)` checks a surviving value against acceptance. Removed components require current-membership reconciliation. |
+
+The optional third argument selects candidate table membership (any listed
+component); it defaults to the observed components. Sparse candidates conservatively
+include current tables. Consumers still inspect final component membership and
+values: the work set is conservative, never an event stream.
+
 The `@forgeax/engine-ecs/world-read` seam is a read-only owner capability for
 hot semantic scalar/array probes. `World.getStructureEpoch()` remains the
 public cache-invalidation primitive; the seam never returns tables, archetypes,
@@ -296,8 +312,9 @@ runs one update step, and flushes each system's command buffer. Clock readers
 receive a stable read view; the scheduler owns writes. Resources are non-owning
 values: Cordis/plugin owners dispose external payloads, not `World`.
 Final shared-reference `release()` returns the payload to its caller.
-`readReleaseEvidence()` retains only bounded handle/refcount/generation records;
-diagnostic history must not extend the lifetime of released meshes or textures.
+The store retains no release journal or content-change versions. Runtime content
+uses managed ECS components owned by `assets-runtime`; final release does not
+retain the external payload.
 
 ## Failure and recovery
 
@@ -369,7 +386,7 @@ their owner instead of being forwarded through the root.
 | Entry | Purpose |
 |:--|:--|
 | `@forgeax/engine-ecs` | World, components, relationships, queries, schedules, resources, errors |
-| `@forgeax/engine-ecs/projection` | Explicit render read versions, typed structural evidence, and numeric spans |
+| `@forgeax/engine-ecs/projection` | Current-state block projection, render read versions, and numeric spans |
 | `@forgeax/engine-ecs/shared` | Shared numeric kernel contracts |
 | `@forgeax/engine-ecs/world-read` | Safe semantic scalar/array reads for owner-package hot paths |
 | `@forgeax/engine-ecs/externalization` | Generic component projection and entity remap |

package/dist/__tests__/query-idle.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=query-idle.unit.test.d.ts.map

package/dist/__tests__/query-idle.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-idle.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/query-idle.unit.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/set-allocation.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=set-allocation.unit.test.d.ts.map

package/dist/__tests__/set-allocation.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"set-allocation.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/set-allocation.unit.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/state-projection.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=state-projection.unit.test.d.ts.map

package/dist/__tests__/state-projection.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-projection.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/state-projection.unit.test.ts"],"names":[],"mappings":""}

package/dist/index.d.ts

@@ -137,7 +137,7 @@ export type { Query, QueryCreationError, QueryDescriptor, QueryRow, QuerySpan, }
  * // the SharedRefStore publishes release evidence at rc=0.
  * ```
  */
-export type { SharedRefReleaseEvidence, SharedRefReleaseRecord } from './shared-ref-store.js';
+export type { SharedRefReleaseEvidence } from './shared-ref-store.js';
 /**
  * ECS-managed handle store (M1). Owns the lifecycle of every
  * `Handle<T, 'unique'>` derived from `ref<T>` schema fields - World hooks

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AA0DH,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,uBAAuB,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAerF;;;;;;GAMG;AACH,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AACpE,OAAO,EACL,kBAAkB,EAClB,WAAW,GACZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,kBAAkB,EAClB,KAAK,2BAA2B,GACjC,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,WAAW,EACX,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,MAAM,GACP,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,SAAS,EACT,KAAK,iBAAiB,EACtB,IAAI,EACJ,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,YAAY,GAClB,MAAM,QAAQ,CAAC;AAChB;;;GAGG;AACH,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACxC;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,uBAAuB,EAAE,cAAc,EAAE,CAAC;AAMrE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;;;;;;;;;;;;;;;;;GAiBG;AACH,YAAY,EACV,SAAS,EACT,eAAe,EACf,eAAe,EACf,YAAY,EACZ,QAAQ,EACR,OAAO,GACR,MAAM,aAAa,CAAC;AACrB;;;;;;;GAOG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C;;;;;;;GAOG;AACH,YAAY,EACV,KAAK,EACL,kBAAkB,EAClB,eAAe,EACf,QAAQ,EACR,SAAS,GACV,MAAM,eAAe,CAAC;AACvB;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,YAAY,EAAE,wBAAwB,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAE9F;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;;;GAOG;AACH,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD;;;;;;;;;GASG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAMnC;;;;;;;;;;;GAWG;AACH,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD;;;;;;;;;;;;GAYG;AACH;;;;;;;;;;GAUG;AACH,YAAY,EACV,gBAAgB,EAChB,YAAY,EACZ,SAAS,GACV,MAAM,YAAY,CAAC;AACpB;;;;;;;;;;;;;GAaG;AACH;;;;;;;;GAQG;AACH,OAAO,EACL,YAAY,EACZ,eAAe,GAChB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;GASG;AAMH;;;;;;;;GAQG;AAuBH,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AA0DH,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,uBAAuB,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAerF;;;;;;GAMG;AACH,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AACpE,OAAO,EACL,kBAAkB,EAClB,WAAW,GACZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,kBAAkB,EAClB,KAAK,2BAA2B,GACjC,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,WAAW,EACX,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,MAAM,GACP,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,SAAS,EACT,KAAK,iBAAiB,EACtB,IAAI,EACJ,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,YAAY,GAClB,MAAM,QAAQ,CAAC;AAChB;;;GAGG;AACH,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACxC;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,uBAAuB,EAAE,cAAc,EAAE,CAAC;AAMrE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;;;;;;;;;;;;;;;;;GAiBG;AACH,YAAY,EACV,SAAS,EACT,eAAe,EACf,eAAe,EACf,YAAY,EACZ,QAAQ,EACR,OAAO,GACR,MAAM,aAAa,CAAC;AACrB;;;;;;;GAOG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C;;;;;;;GAOG;AACH,YAAY,EACV,KAAK,EACL,kBAAkB,EAClB,eAAe,EACf,QAAQ,EACR,SAAS,GACV,MAAM,eAAe,CAAC;AACvB;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,YAAY,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAEtE;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;;;GAOG;AACH,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD;;;;;;;;;GASG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAMnC;;;;;;;;;;;GAWG;AACH,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD;;;;;;;;;;;;GAYG;AACH;;;;;;;;;;GAUG;AACH,YAAY,EACV,gBAAgB,EAChB,YAAY,EACZ,SAAS,GACV,MAAM,YAAY,CAAC;AACpB;;;;;;;;;;;;;GAaG;AACH;;;;;;;;GAQG;AACH,OAAO,EACL,YAAY,EACZ,eAAe,GAChB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;GASG;AAMH;;;;;;;;GAQG;AAuBH,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC"}