@forgeax/engine-ecs 0.1.26 → 0.1.28

package/README.md

@@ -10,6 +10,11 @@ mutation, two schedules, resources, time, and optional shared numeric kernels.
 > in their owning packages. Do not add a second ECS facade for one of those
 > domains.
 
+`World` directly owns its graph, entity records, managed stores, relationship
+indexes, epochs, structural evidence, 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.
+
 ```mermaid
 flowchart LR
   HOST["App host"] --> WORLD["World.update(delta)"]
@@ -169,50 +174,18 @@ relationship source: adding `ChildOf` also materializes its required
 components. The reverse `Children` projection does not gain a second write
 path, and no frame system scans the world to repair the dependency.
 
-An exclusive relationship can be moved through the generic owner method. Using
-the schema above, pass the source component and its declared source-field data:
-`world.reparent(child, newParent, ChildOf, { parent: newParent })`.
-For another relationship, replace `ChildOf` and `parent` with that schema's
-source component and source field; both are required. `linkedSpawn: true`
-means despawning a target recursively despawns its linked source entities;
-`linkedSpawn: false` leaves those entities alive and their source edge is then
-an explicit dangling state that the owning domain must repair.
-
 `Children` and `AnimationTargets` are read projections, not a second write
-authority. `Children { entities }` is a materialized target owned by ECS; the
+authority. `Children { entities` is a materialized target owned by ECS; the
 Scene package owns the `ChildOf` vocabulary and chooses where to use it. The
 same rule applies to `AnimationTargets`. Direct target writes are rejected by
 `World` at both the type and runtime boundaries.
 
-Every writable relationship source uses that same owner path: `World.set`, row
-mutation, structural add/re-add/reparent, spawn, and deferred Commands all
-enter the owner for liveness/cycle validation and target preparation. Expected
-relationship rejection leaves the source, mirror, backpointer, versions, and
-epochs unchanged. Query spans reject both relationship roles before exposing a
-raw column, because a numeric source write cannot maintain the reverse
-projection. `query.spans()` and the internal derived-writer seam report
-`query-span-unavailable` with `detail.reason === 'relationship-component'` for
-any writable relationship source or target; use `World.set`, `row.mut`, or a
-structural command so the owner can converge both sides.
-
-Deferred `Commands.spawn` uses the same component-data shape as `World.spawn`:
-each entry is `{ component, data }`, and the pending handle is materialized at
-command flush. Relationship validation and mirror preparation happen before
-the committed source row; expected failures leave the World healthy, while an
-unknown post-write failure poisons it and requires an App-owned rebuild.
-
 ## Queries and projections
 
 Queries are the only public data-plane API. A row is the flexible path; a span
 is the packed numeric path and includes entity handles for owner-side identity.
 Raw `Table`, `Archetype`, `Column`, and `FieldView` values are package-private.
 
-Use `query.spans()` only for dense, table-only descriptors. It rejects optional
-data and sparse components with `query-span-unavailable`; `changed` and `added`
-filters are supported and yield only matching contiguous runs. Span columns
-are zero-copy transient TypedArray views and are invalid after a structure
-epoch change.
-
 ```ts
 const query = world.query({ read: [Position] }).unwrap();
 for (const row of query) console.log(row.entity, row.get(Position).x);
@@ -238,6 +211,65 @@ for (const span of changed.spans().unwrap()) {
 // the owner's ordinary Query and then drain the changed Query once.
 ```
 
+`added` is the matching first-observation filter for component membership. It
+uses the same row-version cursor as `changed`, so each consumer drains its own
+query independently:
+
+```ts
+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:
+
+```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;
+}
+```
+
+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,
+columns, or mutable views. Ordinary gameplay code should continue to use
+`World.get` and queries.
+
+When an owner needs one scalar or one array element without materializing a row,
+import the capability explicitly and keep the probe read-only. Entity fields
+are returned as their stored u32, so narrow a non-null value to the existing
+`EntityHandle` before passing it to another entity-typed probe:
+
+```ts
+import { ENTITY_NULL_RAW, type EntityHandle } from '@forgeax/engine-ecs';
+import { ChildOf, Children } from '@forgeax/engine-scene';
+import { worldRead } from '@forgeax/engine-ecs/world-read';
+
+const parentRaw = world[worldRead].getFieldValue(child, ChildOf, 'parent');
+const parent: EntityHandle | undefined =
+  parentRaw === undefined || parentRaw === ENTITY_NULL_RAW
+    ? undefined
+    : (parentRaw as EntityHandle);
+const count =
+  parent === undefined ? undefined : world[worldRead].getArrayLength(parent, Children, 'entities');
+const firstChild =
+  parent === undefined
+    ? undefined
+    : world[worldRead].getArrayElement(parent, Children, 'entities', 0);
+```
+
+`undefined` means the entity, component, field, or element is unavailable; the
+capability never hands out a storage view and cannot mutate the World.
+
 Queries never expose table ids, rows, columns, or a duplicate snapshot data
 plane.
 
@@ -282,6 +314,28 @@ if (!result.ok) {
 }
 ```
 
+Recovery means constructing a fresh World and replaying the authoritative
+game state; a poisoned identity is never reused:
+
+```ts
+function createWorld(): World {
+  const next = new World();
+  next.addSystem(Update, Move).unwrap();
+  return next;
+}
+
+let liveWorld = createWorld();
+const step = liveWorld.update(1 / 60);
+if (!step.ok && liveWorld.execution.health === 'poisoned') {
+  // The first failed frame can be `system-failed`; a later call is
+  // `world-poisoned`. Health is the stable recovery boundary for both.
+  liveWorld = createWorld();
+  for (const saved of savedPositions) {
+    liveWorld.spawn({ component: Position, data: saved }).unwrap();
+  }
+}
+```
+
 Expected command failures are reported before structural commit and leave the
 World unchanged. A system throw or an unknown post-write failure cannot prove
 that no row was mutated: the World becomes poisoned and must be rebuilt by the
@@ -314,6 +368,7 @@ their owner instead of being forwarded through the root.
 | `@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/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 |
 
 `Result`, `ok`, `err`, and `Handle` come from `@forgeax/engine-types`; ECS does
@@ -331,7 +386,11 @@ consumer needs one of those concerns, move the owner to App, Scene, Render,
 Physics, or the explicitly named ECS subpath.
 </details>
 
-## Verification
+## Contract invariants
+
+The following are package-contract statements, not a claim that every
+repository-wide browser, Dawn, or consumer gate is green. Gate results for a
+specific change belong to its closed-loop verification report.
 
 - [x] Entity and component mutation use one World authority.
 - [x] Relationship targets remain materialized for $O(1 + k)$ reads.
@@ -341,7 +400,7 @@ Physics, or the explicitly named ECS subpath.
 - [x] Advanced projection/shared/externalization APIs are named subpaths.
 
 For the full migration rationale and acceptance matrix, see the canonical
-[ECS 80% architecture design](../../.forgeax-harness/docs/specs/2026-08-22-ecs-core-80-percent-architecture-reduction-design.md).
+[ECS World ownership simplification design](../../.forgeax-harness/docs/specs/2026-09-08-ecs-worldcore-simplification-design.md).
 
 ### Large managed arrays
 

package/dist/__tests__/world-read.unit.test.d.ts

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

package/dist/__tests__/world-read.unit.test.d.ts.map

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

package/dist/commands.d.ts

@@ -2,6 +2,7 @@ import type { Result } from '@forgeax/engine-types';
 import type { Component, ComponentSchema } from './component';
 import { type EntityHandle } from './entity-handle';
 import { type CommandKind } from './errors';
+import type { WorldExecutionState } from './execution/shared-kernel';
 import type { ComponentData, EcsError } from './world';
 import { type WorldInternal, worldInternal } from './world-internal';
 export type Command = {
@@ -42,6 +43,7 @@ export interface CommandBuffer {
 /** Minimal world interface needed by CommandBuffer for entity allocation. */
 export interface WorldForCommands {
     readonly [worldInternal]: WorldInternal;
+    readonly execution: WorldExecutionState;
     /**
      * Allocate a pending entity index, returning [entity handle, index slot].
      * @internal

package/dist/commands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"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"}