@forgeax/engine-ecs 0.1.21 → 0.1.24

package/src/world-component-storage.ts

@@ -114,6 +114,79 @@ export class ComponentStorage {
     return reinterpretSlotBytes(liveBytes, arrayMeta.elementType, elementCount);
   }
 
+  /**
+   * Read the live length of an array field without materialising a typed view.
+   * Relationship consumers use this narrow storage seam for hot reverse-list
+   * walks; the target array remains owned by the ECS column and no snapshot is
+   * created per entity.
+   */
+  readArrayLength(
+    arch: Archetype,
+    component: Component,
+    row: number,
+    fieldName: string,
+  ): number | undefined {
+    const fieldCols = this.table(arch).storage.get(componentId(component))?.fields;
+    if (fieldCols === undefined) return undefined;
+    const arrayMeta = componentDefinition(component).fields[fieldName]?.arrayMeta;
+    if (arrayMeta === undefined) return undefined;
+    if (arrayMeta.length !== undefined) return arrayMeta.length;
+    const count = fieldCols.get(arrayCountColumnName(fieldName))?.view[row];
+    return typeof count === 'number' ? count : 0;
+  }
+
+  /**
+   * Read one array element directly from its backing column/BufferPool slot.
+   * The relationship target vocabulary is `array<entity>`, so its hot path
+   * decodes the packed u32 in-place and does not allocate a TypedArray view.
+   */
+  readArrayElement(
+    arch: Archetype,
+    component: Component,
+    row: number,
+    fieldName: string,
+    index: number,
+  ): number | undefined {
+    if (!Number.isSafeInteger(index) || index < 0) return undefined;
+    const fieldCols = this.table(arch).storage.get(componentId(component))?.fields;
+    if (fieldCols === undefined) return undefined;
+    const arrayMeta = componentDefinition(component).fields[fieldName]?.arrayMeta;
+    if (arrayMeta === undefined) return undefined;
+    const length = this.readArrayLength(arch, component, row, fieldName);
+    if (length === undefined || index >= length) return undefined;
+    const col = fieldCols.get(fieldName);
+    if (col === undefined) return undefined;
+    if (arrayMeta.length !== undefined) {
+      return col.view[row * col.arity + index] as number;
+    }
+    const slotId = col.view[row] as number;
+    const bytes = this.bufferPool.view(slotId);
+    if (arrayMeta.elementType === 'entity') {
+      const byteOffset = index * 4;
+      if (byteOffset + 4 > bytes.byteLength) return undefined;
+      return (
+        ((bytes[byteOffset] ?? 0) |
+          ((bytes[byteOffset + 1] ?? 0) << 8) |
+          ((bytes[byteOffset + 2] ?? 0) << 16) |
+          ((bytes[byteOffset + 3] ?? 0) << 24)) >>>
+        0
+      );
+    }
+    return this.readArrayElementAt(bytes, index, arrayMeta.elementType);
+  }
+
+  /** Read one scalar field without constructing a component shape. */
+  readFieldValue(
+    arch: Archetype,
+    component: Component,
+    row: number,
+    fieldName: string,
+  ): number | undefined {
+    return this.table(arch).storage.get(componentId(component))?.fields.get(fieldName)?.view[row] as
+      | number
+      | undefined;
+  }
+
   // ──────────────────────────────────────────────────────────────────────────
   // Internal — archetype data read/write
   // ──────────────────────────────────────────────────────────────────────────
@@ -175,10 +248,10 @@ export class ComponentStorage {
       } else {
         const arrayMeta = componentDefinition(component).fields[fieldName]?.arrayMeta;
         if (arrayMeta !== undefined) {
-          // M1 read path: materialise a fresh TypedArray snapshot each call
-          // (D-4 no cache; plan-strategy §2.2 read-only contract). The
-          // snapshot aliases the BufferPool slot bytes; mutations route
-          // through `world.set` / `world.push` / `world.pop`.
+          // Internal row path: materialise a fresh TypedArray view each call
+          // without copying its backing bytes. Public World.get detaches a
+          // relationship target array after this read; ECS relationship and
+          // Scene owners use this readRow seam as zero-copy storage access.
           (out as Record<string, unknown>)[fieldName] = this.materializeArrayView(
             arch,
             component,
@@ -215,6 +288,7 @@ export class ComponentStorage {
     component: Component<string, S>,
     row: number,
     value: ShapeOf<S>,
+    options?: { readonly skipVariableArrayInitialization?: boolean },
   ): void {
     const localId = componentId(component);
     const fieldCols = this.table(arch).storage.get(localId)?.fields;
@@ -291,6 +365,16 @@ export class ComponentStorage {
       } else {
         const arrayMeta = componentDefinition(component).fields[fieldName]?.arrayMeta;
         if (arrayMeta !== undefined) {
+          if (options?.skipVariableArrayInitialization === true && arrayMeta.length === undefined) {
+            // Relationship preparation can reserve the first target slot
+            // before the mirror archetype is created. Leave the fresh row at
+            // the sentinel until the owner installs that reservation; this
+            // keeps an injected alloc failure out of the structural path.
+            col.view[row] = 0;
+            const countCol = fieldCols.get(arrayCountColumnName(fieldName));
+            if (countCol !== undefined) countCol.view[row] = 0;
+            continue;
+          }
           // M1 spawn path for array<T> / array<T,N> fields (D-3 double-
           // column for variable; single column for fixed).
           // Spawn path: no prior-slot release (fresh rows carry stale debris
@@ -810,20 +894,19 @@ export class ComponentStorage {
   }
 
   /**
-   * Materialise a fresh `TypedArray` snapshot for an `array<T,N>` /
-   * `array<T>` field at `row` (plan-strategy §2.2 -- read-only snapshot
-   * contract; mutations route through `world.set` / `world.push` /
-   * `world.pop`).
+   * Materialise a fresh `TypedArray` view for an `array<T,N>` / `array<T>`
+   * field at `row`. This is the internal row-storage path: the returned view
+   * aliases the live column or BufferPool slot. `WorldComponentAccess.get`
+   * detaches relationship target arrays at the public boundary; internal ECS
+   * relationship maintenance and Scene traversal keep this zero-copy path.
    *
    * **Transient view contract (feat-20260602):** for fixed `array<T,N>`
    * columns the returned `TypedArray` aliases the inline column buffer
    * directly (`col.view.subarray(row * arity, ...)`); for variable
    * `array<T>` columns it aliases the live `BufferPool` slot bytes
-   * (zero-copy; `pool.view(slotId)` is the SSOT byte region). In both
-   * cases the view is valid only until the next structural change. Writing
-   * into the snapshot is undefined behaviour -- the contract is read-only
-   * and the implementation may switch to a copy in the future without
-   * breaking AI users who consume only `length` / index reads.
+   * (zero-copy; `pool.view(slotId)` is the SSOT byte region). In both cases
+   * the view is valid only until the next structural change. Internal callers
+   * must not write through it except via the owner mutation helpers.
    *
    * For variable arrays the typed-array length matches the live count from
    * the sidecar `<fieldName>:count` column; for fixed arrays it matches the
@@ -1011,11 +1094,14 @@ export class ComponentStorage {
 
 /**
  * Reinterpret a `BufferPool` slot's `Uint8Array` byte region as the typed
- * view for `elementType`, sliced to `elementCount` elements. Backs the
- * `world.get(e, C).<arrayField>` read path: the returned typed array
- * aliases live slot bytes (zero-copy) but is contractually a read-only
- * snapshot (plan-strategy §2.2). `entity` element fields surface as
- * `Uint32Array` (Entity packs slot+gen into u32).
+ * view for `elementType`, sliced to `elementCount` elements. This is the
+ * internal materialization used by `readRow`/`materializeArrayView`: the
+ * returned view aliases live slot bytes. `WorldComponentAccess.get` detaches
+ * relationship-target `array<entity>` values at the public boundary; other
+ * public array fields retain the existing transient live-view contract.
+ * `_getArrayView` and other internal owners always retain zero-copy access.
+ * `entity` element fields surface as `Uint32Array` (Entity packs slot+gen
+ * into u32).
  */
 /**
  * Element-byte-width for a managed-array element type, read off the global

package/src/world-core.ts

@@ -4,7 +4,7 @@ import type { RelationshipIndex } from './relationship-index';
 import type { SharedRefStore } from './shared-ref-store';
 import { SharedRefStore as SharedRefStoreImpl } from './shared-ref-store';
 import { type ArchetypeGraph, createArchetypeGraph } from './storage/archetype-graph';
-import { WorldChangeJournal } from './storage/change-detection';
+import { StructuralEvidenceRing } from './storage/structural-evidence';
 import type { UniqueRefStore } from './unique-ref-store';
 import { UniqueRefStore as UniqueRefStoreImpl } from './unique-ref-store';
 import type { EntityRecord } from './world';
@@ -43,7 +43,7 @@ export class WorldCore {
   readonly sharedRefs: SharedRefStore = new SharedRefStoreImpl();
   readonly storage: WorldStorageCore;
   readonly componentMutationEpochs: number[] = [];
-  readonly changeJournal = new WorldChangeJournal();
+  readonly structuralEvidence = new StructuralEvidenceRing();
   /** One packed reverse index per relationship source component. */
   readonly relationshipIndexes = new Map<number, RelationshipIndex>();
   mutationEpoch = 0;

package/src/world-entity-lifecycle.ts

@@ -8,6 +8,7 @@ import { err, isRetiredSlot, ok, pack, type Result } from '@forgeax/engine-types
 import type { Component, ComponentSchema, InputShapeOf, ShapeOf } from './component';
 import { componentId, componentSchema } from './component';
 import { fillComponentDefaults, validateComponentDataKeys } from './component-default-fallback';
+import { expandComponentRequirements } from './component-schema';
 import { validateManagedArrayValues, validateSharedFieldValues } from './component-value-validate';
 import { Entity } from './entity';
 import {
@@ -48,6 +49,7 @@ export function spawnCore(
   componentDatas: { component: Component; data: Partial<Record<string, unknown>> }[],
   internal: boolean,
 ): Result<EntityHandle, EcsError> {
+  componentDatas = expandComponentRequirements(componentDatas);
   const filledData: Record<string, unknown>[] = [];
   for (const cd of componentDatas) {
     const preflight = world[worldInternal].preflightComponentData(null, cd);
@@ -63,6 +65,34 @@ export function spawnCore(
     if (enumErr !== null) return err(enumErr as unknown as EcsError);
     filledData.push(filled as Record<string, unknown>);
   }
+  // Reserve every relationship target before allocating the new source row.
+  // In particular, an injected BufferPool failure must not leave a source
+  // entity, mirror component, or mutation epoch behind.
+  const relationshipPreparations: unknown[] = [];
+  if (!internal) {
+    for (let index = 0; index < componentDatas.length; index += 1) {
+      const componentData = componentDatas[index];
+      const value = filledData[index];
+      if (
+        componentData === undefined ||
+        value === undefined ||
+        relationshipRole(componentData.component as Component)?.kind !== 'source'
+      ) {
+        continue;
+      }
+      const prepared = world[worldInternal].prepareRelationshipInsert(
+        componentData.component as Component,
+        value,
+      );
+      if (!prepared.ok) {
+        for (const reservation of relationshipPreparations) {
+          world[worldInternal].releaseRelationshipPreparation(reservation);
+        }
+        return prepared;
+      }
+      relationshipPreparations[index] = prepared.value;
+    }
+  }
   const indexSlot = world[worldInternal].allocateIndex();
   const record = world[worldInternal].getRecords()[indexSlot];
   if (record === undefined)
@@ -99,11 +129,21 @@ export function spawnCore(
         spawnedEntity,
         cd.component as Component,
         filled,
+        relationshipPreparations[i],
       );
-      if (!relation.ok) return relation;
+      if (!relation.ok) {
+        for (const reservation of relationshipPreparations) {
+          world[worldInternal].releaseRelationshipPreparation(reservation);
+        }
+        return relation;
+      }
     }
   }
   world[worldInternal].markStructureChanged();
+  world[worldInternal].recordStructuralEvidence({
+    kind: 'spawn',
+    entity: spawnedEntity,
+  });
   return ok(spawnedEntity);
 }
 
@@ -169,8 +209,11 @@ export function despawnCore(
       }
     }
   }
+  world[worldInternal].recordStructuralEvidence({
+    kind: 'despawn',
+    entity,
+  });
   if (record) {
-    world[worldInternal].removeEntityChanges(entity);
     record.archetypeId = -1;
     record.archetypeRow = -1;
     record.generation += 1;
@@ -190,7 +233,8 @@ export function worldAddChild<S extends ComponentSchema>(
   data: Partial<InputShapeOf<S>>,
 ): Result<void, EcsError> {
   const holderComp = component as Component;
-  if (relationshipRole(holderComp)?.kind !== 'source') {
+  const role = relationshipRole(holderComp);
+  if (role?.kind !== 'source') {
     return err(new ComponentNotPresentError(child as number, component.name));
   }
 
@@ -222,7 +266,6 @@ export function worldAddChild<S extends ComponentSchema>(
     );
   }
 
-  const role = relationshipRole(holderComp);
   if (child === parent && !(role?.kind === 'source' && role.allowSelf)) {
     return err(new RelationshipSelfCycleError(component.name, child as number, child as number));
   }
@@ -299,10 +342,10 @@ export function worldReparent<S extends ComponentSchema>(
   data: Partial<InputShapeOf<S>>,
 ): Result<void, EcsError> {
   const holderComp = component as Component;
-  if (relationshipRole(holderComp)?.kind !== 'source') {
+  const role = relationshipRole(holderComp);
+  if (role?.kind !== 'source') {
     return err(new ComponentNotPresentError(child as number, component.name));
   }
-  const role = relationshipRole(holderComp);
   if (child === newParent && !(role?.kind === 'source' && role.allowSelf)) {
     return err(
       new RelationshipSelfCycleError(component.name, child as number, newParent as number),
@@ -339,13 +382,19 @@ export function worldReparent<S extends ComponentSchema>(
       }),
     );
   }
+  const payload = {
+    ...(data as Record<string, unknown>),
+    [role.sourceField]: newParent,
+  } as Partial<InputShapeOf<S>>;
   if (
-    childArch.components.some((component) => componentId(component) === componentId(holderComp))
+    childArch.components.some((candidate) => componentId(candidate) === componentId(holderComp))
   ) {
-    const removeResult = world.removeComponent(child, component);
-    if (!removeResult.ok) return removeResult;
+    // Existing exclusive sources are updated through the same owner-level
+    // write barrier as `world.set`; remove+add would expose a partial mirror
+    // state and would invalidate unrelated query spans.
+    return world.set(child, component as never, payload as never);
   }
-  return world.addComponent(child, { component, data });
+  return world.addComponent(child, { component, data: payload });
 }
 
 /** Iterate ancestors in child-to-root order while safely terminating corrupt cycles. */

package/src/world-internal.ts

@@ -22,11 +22,14 @@ type InternalName =
   | 'cancelPendingEntity'
   | 'despawnCore'
   | 'getArrayView'
+  | 'getArrayLength'
+  | 'getArrayElement'
+  | 'getFieldValue'
   | 'getBufferPool'
-  | 'getChangeCursor'
   | 'getClockWriter'
   | 'getComponentChange'
   | 'getComponentMutationEpoch'
+  | 'getComponentMutationEpochs'
   | 'getEntityArchetype'
   | 'getFixedAccumulator'
   | 'getFreeIndices'
@@ -41,28 +44,30 @@ type InternalName =
   | 'getSchedules'
   | 'getSharedRefs'
   | 'getStructureEpoch'
+  | 'getStructuralEvidence'
   | 'getUniqueRefs'
   | 'lookupAlive'
   | 'markComponentAdded'
   | 'markComponentChanged'
   | 'markComponentRangeChanged'
   | 'markComponentsAdded'
-  | 'markDerivedComponentChanges'
   | 'markStructureChanged'
   | 'materializePendingEntity'
   | 'nextMutationEpoch'
   | 'poisonExecution'
+  | 'publishDerivedRange'
+  | 'prepareRelationshipInsert'
   | 'preflightComponentData'
-  | 'readChangesSince'
   | 'readRow'
+  | 'recordStructuralEvidence'
   | 'recordIsLive'
   | 'relationshipOnInsert'
   | 'relationshipOnRemove'
   | 'releaseManagedRefsOnRow'
-  | 'removeComponentChange'
+  | 'releaseRelationshipPreparation'
   | 'removeComponentCore'
-  | 'removeEntityChanges'
   | 'routeError'
+  | 'restoreMutationEpoch'
   | 'setFixedAccumulator'
   | 'setQueryRow'
   | 'spawnCore'