@forgeax/engine-ecs 0.1.23 → 0.1.25

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-entity-lifecycle.ts

@@ -65,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)
@@ -101,8 +129,14 @@ 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();
@@ -199,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));
   }
 
@@ -231,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));
   }
@@ -308,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),
@@ -348,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,6 +22,9 @@ type InternalName =
   | 'cancelPendingEntity'
   | 'despawnCore'
   | 'getArrayView'
+  | 'getArrayLength'
+  | 'getArrayElement'
+  | 'getFieldValue'
   | 'getBufferPool'
   | 'getClockWriter'
   | 'getComponentChange'
@@ -53,6 +56,7 @@ type InternalName =
   | 'nextMutationEpoch'
   | 'poisonExecution'
   | 'publishDerivedRange'
+  | 'prepareRelationshipInsert'
   | 'preflightComponentData'
   | 'readRow'
   | 'recordStructuralEvidence'
@@ -60,6 +64,7 @@ type InternalName =
   | 'relationshipOnInsert'
   | 'relationshipOnRemove'
   | 'releaseManagedRefsOnRow'
+  | 'releaseRelationshipPreparation'
   | 'removeComponentCore'
   | 'routeError'
   | 'restoreMutationEpoch'

package/src/world.ts

@@ -60,7 +60,11 @@ import {
 } from './execution/shared-kernel';
 import type { QueryDescriptor } from './query/query';
 import { createQuery, type Query, type QueryCreationError } from './query/query';
-import { isRelationshipTarget, type RelationshipTargetComponent } from './relationship-index';
+import {
+  isRelationshipTarget,
+  type RelationshipTargetComponent,
+  relationshipRole,
+} from './relationship-index';
 import { createResourceStore, type ResourceStore } from './resource';
 import { createSchedule, type Schedule, type SystemDescriptor, type SystemSet } from './schedule';
 import { FixedUpdate, Update } from './schedule-token';
@@ -433,6 +437,9 @@ export class World {
       cancelPendingEntity: this.internalcancelPendingEntity.bind(this),
       despawnCore: this.internaldespawnCore.bind(this),
       getArrayView: this.internalgetArrayView.bind(this),
+      getArrayLength: this.internalgetArrayLength.bind(this),
+      getArrayElement: this.internalgetArrayElement.bind(this),
+      getFieldValue: this.internalgetFieldValue.bind(this),
       getBufferPool: this.internalgetBufferPool.bind(this),
       getClockWriter: this.internalgetClockWriter.bind(this),
       getComponentChange: this.internalgetComponentChange.bind(this),
@@ -463,6 +470,7 @@ export class World {
       materializePendingEntity: this.internalmaterializePendingEntity.bind(this),
       nextMutationEpoch: this.internalnextMutationEpoch.bind(this),
       poisonExecution: this.internalpoisonExecution.bind(this),
+      prepareRelationshipInsert: this.internalprepareRelationshipInsert.bind(this),
       publishDerivedRange: this.internalpublishDerivedRange.bind(this),
       preflightComponentData: this.internalpreflightComponentData.bind(this),
       readRow: this.internalreadRow.bind(this),
@@ -471,6 +479,7 @@ export class World {
       relationshipOnInsert: this.internalrelationshipOnInsert.bind(this),
       relationshipOnRemove: this.internalrelationshipOnRemove.bind(this),
       releaseManagedRefsOnRow: this.internalreleaseManagedRefsOnRow.bind(this),
+      releaseRelationshipPreparation: this.internalreleaseRelationshipPreparation.bind(this),
       removeComponentCore: this.internalremoveComponentCore.bind(this),
       routeError: this.internalrouteError.bind(this),
       restoreMutationEpoch: this.internalrestoreMutationEpoch.bind(this),
@@ -679,7 +688,12 @@ export class World {
     component: Component,
     value: Record<string, unknown>,
   ): Result<void, EcsError> {
-    return this.componentAccess.set(entity, component, value as never, false);
+    return this.componentAccess.set(
+      entity,
+      component,
+      value as never,
+      relationshipRole(component)?.kind === 'source',
+    );
   }
 
   /** Query facade read that does not re-enter the public World API. */
@@ -1109,6 +1123,31 @@ export class World {
     return this.componentAccess._getArrayView(entity, component, fieldName);
   }
 
+  private internalgetArrayLength(
+    entity: EntityHandle,
+    component: Component,
+    fieldName: string,
+  ): number | undefined {
+    return this.componentAccess._getArrayLength(entity, component, fieldName);
+  }
+
+  private internalgetArrayElement(
+    entity: EntityHandle,
+    component: Component,
+    fieldName: string,
+    index: number,
+  ): number | undefined {
+    return this.componentAccess._getArrayElement(entity, component, fieldName, index);
+  }
+
+  private internalgetFieldValue(
+    entity: EntityHandle,
+    component: Component,
+    fieldName: string,
+  ): number | undefined {
+    return this.componentAccess._getFieldValue(entity, component, fieldName);
+  }
+
   set<S extends ComponentSchema, C extends Component<string, S>>(
     entity: EntityHandle,
     component: C & WritableComponent<C>,
@@ -1222,8 +1261,18 @@ export class World {
     h: EntityHandle,
     c: Component,
     v: Record<string, unknown>,
+    preparation?: unknown,
   ): Result<void, EcsError> {
-    return this.componentAccess.relationshipOnInsert(h, c, v);
+    return this.componentAccess.relationshipOnInsert(h, c, v, preparation as never);
+  }
+  /** */ private internalprepareRelationshipInsert(
+    c: Component,
+    v: Record<string, unknown>,
+  ): Result<unknown, EcsError> {
+    return this.componentAccess.prepareRelationshipInsert(c, v);
+  }
+  /** */ private internalreleaseRelationshipPreparation(preparation: unknown): void {
+    this.componentAccess.releaseRelationshipPreparation(preparation as never);
   }
   /** */ private internalrelationshipOnRemove(
     h: EntityHandle,