@forgeax/engine-ecs 0.1.21 → 0.1.24

package/src/world-component-access.ts

@@ -22,7 +22,7 @@ import {
   TYPE_METADATA,
 } from './component';
 import { fillComponentDefaults, validateComponentDataKeys } from './component-default-fallback';
-import { componentDefinition } from './component-schema';
+import { componentDefinition, expandComponentRequirements } from './component-schema';
 import { validateManagedArrayValues, validateSharedFieldValues } from './component-value-validate';
 import { Entity as EntityComponent } from './entity';
 import {
@@ -63,6 +63,7 @@ import {
 } from './storage/archetype-graph';
 import { removeSparseTag } from './storage/change-detection';
 import { arrayCountColumnName, type FieldView, normalizeBufferWrite } from './storage/column';
+import type { StructuralEvidenceInput } from './storage/structural-evidence';
 import { appendTableRow, type Table } from './storage/table';
 import type { UniqueRefStore } from './unique-ref-store';
 import type { ComponentData, EcsError, EntityRecord } from './world';
@@ -70,6 +71,22 @@ import { ComponentStorage } from './world-component-storage';
 
 type ErrorContext = { readonly systemName: string };
 
+/**
+ * Prepared target-side work for one relationship source write.
+ *
+ * A reservation is deliberately kept outside the World columns until the
+ * source operation is ready to commit. That lets direct, spawn, and deferred
+ * source writes observe BufferPool failures before adding a mirror component
+ * or advancing any ECS epoch.
+ */
+interface RelationshipPreparation {
+  readonly target: EntityHandle;
+  readonly mirror: Component;
+  readonly fieldName: string;
+  readonly mirrorPresent: boolean;
+  reservedSlotId: number | undefined;
+}
+
 type ArrayFieldsOf<S extends ComponentSchema> = {
   [K in keyof S]: S[K] extends
     | `array<${ManagedArrayElementType}>`
@@ -95,6 +112,15 @@ function relationshipPayloadWrites(data: Readonly<Record<string, unknown>>): boo
   });
 }
 
+/**
+ * Relationship target arrays are public read-only projections. Keep the
+ * detached-copy rule at the World.get boundary while internal relationship
+ * owners continue to borrow the live storage through `_getArrayView`.
+ */
+function detachRelationshipTargetArray(value: unknown): unknown {
+  return value instanceof Uint32Array ? value.slice() : value;
+}
+
 export interface ComponentAccessState {
   readonly graph: ArchetypeGraph;
   readonly records: EntityRecord[];
@@ -106,8 +132,8 @@ export interface ComponentAccessState {
   readonly markComponentAdded: (entity: EntityHandle, componentId: number) => void;
   readonly markComponentsAdded: (entity: EntityHandle, componentIds: readonly number[]) => void;
   readonly markComponentChanged: (entity: EntityHandle, componentId: number) => void;
-  readonly removeComponentChange: (entity: EntityHandle, componentId: number) => void;
   readonly markStructureChanged: () => void;
+  readonly recordStructuralEvidence: (evidence: StructuralEvidenceInput) => void;
   routeError(err: unknown, ctx: ErrorContext): void;
 }
 
@@ -160,16 +186,19 @@ export class WorldComponentAccess {
     return index;
   }
 
-  /** Read the World-owned materialized target array; never consults a shadow list. */
+  /**
+   * Read the World-owned materialized target array without a public snapshot.
+   * This is an internal relationship-owner path: it borrows the live
+   * `Uint32Array` so attach/detach stays zero-copy. Public `World.get` detaches
+   * target arrays before returning them to callers.
+   */
   relationshipTargetEntries(source: Component, target: EntityHandle): readonly EntityHandle[] {
     const role = relationshipRole(source);
     if (role?.kind !== 'source') return [];
     const mirror = relationshipMirror(source);
     if (mirror === undefined) return [];
-    const result = this.get(target, mirror);
-    if (!result.ok) return [];
-    const entries = (result.value as Record<string, unknown>)[role.targetField];
-    return entries !== undefined && typeof entries === 'object' ? (entries as EntityHandle[]) : [];
+    const entries = this._getArrayView(target, mirror, role.targetField);
+    return entries === undefined ? [] : (entries as unknown as readonly EntityHandle[]);
   }
 
   private markComponentAdded(entity: EntityHandle, component: Component): void {
@@ -269,9 +298,10 @@ export class WorldComponentAccess {
     const targetRecord = this.records[entityIndex(target)];
     const actualGeneration = targetRecord?.generation ?? -1;
     const targetLive = this.recordIsLive(targetRecord, entityGeneration(target));
-    const holderIsPending =
-      holder === null || pendingEntities?.has(holder as unknown as number) === true;
-    if (!targetIsPending && !targetLive && !holderIsPending) {
+    // A source edge is never allowed to publish a dangling target. Pending
+    // targets are the only exception, and are admitted only for the deferred
+    // command batch that reserved that exact handle.
+    if (!targetIsPending && !targetLive) {
       return err(
         new StaleEntityError(target as number, entityIndex(target), entityGeneration(target), {
           operation: 'relationship-insert',
@@ -346,11 +376,18 @@ export class WorldComponentAccess {
     }
   }
 
-  /** Prepare the target side before a source archetype mutation commits. */
-  private prepareRelationshipInsert(
+  /**
+   * Reserve target-side relationship capacity without touching World columns.
+   *
+   * A missing mirror reserves its first slot before the mirror archetype is
+   * created. An existing mirror either reserves an empty slot or grows its
+   * existing BufferPool slot; both failure paths return before any component,
+   * relationship index, or ECS epoch changes.
+   */
+  prepareRelationshipInsert(
     component: Component,
     value: Record<string, unknown>,
-  ): Result<void, EcsError> {
+  ): Result<RelationshipPreparation | undefined, EcsError> {
     const role = relationshipRole(component);
     if (role?.kind !== 'source') return ok(undefined);
     const target = this.relationshipTargetEntity(component, value);
@@ -370,19 +407,91 @@ export class WorldComponentAccess {
       );
     }
     const targetArch = this.graph.archetypes[targetRec.archetypeId];
-    const hasMirror =
-      targetArch?.components.some((candidate) => componentId(candidate) === componentId(mirror)) ??
-      false;
-    if (!hasMirror) {
-      const added = this._addComponentCore(
-        target,
-        { component: mirror, data: {} as Partial<ShapeOf<ComponentSchema>> },
-        true,
+    const mirrorLocalId = componentId(mirror);
+    const mirrorPresent =
+      targetArch?.components.some((candidate) => componentId(candidate) === mirrorLocalId) ?? false;
+    const fieldName = role.targetField;
+    const arrayMeta = componentDefinition(mirror).fields[fieldName]?.arrayMeta;
+    if (arrayMeta === undefined) {
+      return err(new ComponentNotPresentError(target as number, mirror.name));
+    }
+    const meta = TYPE_METADATA[arrayMeta.elementType];
+    if (meta?.byteSize === undefined) {
+      return err(new ComponentNotPresentError(target as number, mirror.name));
+    }
+    let currentLength = 0;
+    let slotId = 0;
+    if (mirrorPresent) {
+      currentLength = this._getArrayLength(target, mirror, fieldName) ?? 0;
+      const fieldCols = this.table(targetArch as Archetype).storage.get(mirrorLocalId)?.fields;
+      const column = fieldCols?.get(fieldName);
+      if (column === undefined) {
+        return err(new ComponentNotPresentError(target as number, mirror.name));
+      }
+      const row = this.tableRow(targetRec);
+      slotId = column.view[row] as number;
+    }
+    const requiredBytes = (currentLength + 1) * meta.byteSize;
+    const maximum = Math.floor(262_144 / meta.byteSize);
+    if (!Number.isSafeInteger(currentLength + 1) || currentLength + 1 > maximum) {
+      return err(new ManagedBufferOutOfBoundsError(requiredBytes, 262_144));
+    }
+
+    const preparation: RelationshipPreparation = {
+      target,
+      mirror,
+      fieldName,
+      mirrorPresent,
+      reservedSlotId: undefined,
+    };
+    if (!mirrorPresent || slotId === 0) {
+      const allocated = this.bufferPool.alloc(requiredBytes);
+      if (!allocated.ok) return allocated;
+      preparation.reservedSlotId = allocated.value.id;
+    } else if (this.bufferPool.view(slotId).byteLength < requiredBytes) {
+      const grown = this.bufferPool.grow(slotId, requiredBytes);
+      if (!grown.ok) return grown;
+    }
+    return ok(preparation);
+  }
+
+  /** Release a target-capacity reservation that did not reach commit. */
+  releaseRelationshipPreparation(preparation: RelationshipPreparation | undefined): void {
+    if (preparation === undefined || preparation.reservedSlotId === undefined) return;
+    const slotId = preparation.reservedSlotId;
+    this.bufferPool.release(slotId);
+    preparation.reservedSlotId = undefined;
+  }
+
+  /** Install a reserved slot after the target mirror archetype exists. */
+  private installRelationshipPreparation(
+    preparation: RelationshipPreparation,
+  ): Result<void, EcsError> {
+    const record = this.lookupAlive(
+      preparation.target,
+      'relationship-capacity',
+      preparation.mirror.name,
+    );
+    if (!record.ok) return record;
+    const arch = this.graph.archetypes[record.value.archetypeId];
+    if (arch === undefined) {
+      return err(
+        new ComponentNotPresentError(preparation.target as number, preparation.mirror.name),
       );
-      if (!added.ok) return added;
     }
-    const length = this.relationshipTargetEntries(component, target).length;
-    return this.ensureArrayCapacity(target, mirror, role.targetField as never, length + 1);
+    const fieldCols = this.table(arch).storage.get(componentId(preparation.mirror))?.fields;
+    const column = fieldCols?.get(preparation.fieldName);
+    if (column === undefined) {
+      return err(
+        new ComponentNotPresentError(preparation.target as number, preparation.mirror.name),
+      );
+    }
+    const slotId = preparation.reservedSlotId;
+    if (slotId !== undefined) {
+      column.view[this.tableRow(record.value)] = slotId;
+      preparation.reservedSlotId = undefined;
+    }
+    return ok(undefined);
   }
 
   /** Append `holder` to the materialized target list. */
@@ -390,6 +499,7 @@ export class WorldComponentAccess {
     holder: EntityHandle,
     component: Component,
     value: Record<string, unknown>,
+    preparation?: RelationshipPreparation,
   ): Result<void, EcsError> {
     const role = relationshipRole(component);
     if (role?.kind !== 'source') return ok(undefined);
@@ -399,19 +509,28 @@ export class WorldComponentAccess {
     /* istanbul ignore next -- defineComponent relationship validation guarantees mirror exists */
     if (mirror === undefined) return ok(undefined);
 
-    const prepared = this.prepareRelationshipInsert(component, value);
-    if (!prepared.ok) {
-      // A dangling source edge is still useful state: hierarchy/animation
-      // projections report the missing target. The target mirror cannot be
-      // updated, but insertion itself remains atomic and successful.
-      if (prepared.error.code === 'stale-entity') return ok(undefined);
-      return prepared;
+    let prepared = preparation;
+    if (prepared === undefined) {
+      const preparedResult = this.prepareRelationshipInsert(component, value);
+      if (!preparedResult.ok) return preparedResult;
+      prepared = preparedResult.value;
     }
+    if (prepared === undefined) return ok(undefined);
 
     // Lazy-create the mirror component on the target when absent (D-3c).
     const targetSlot = entityIndex(target);
     const targetRec = this.records[targetSlot];
-    if (!this.recordIsLive(targetRec, entityGeneration(target))) return ok(undefined);
+    const actualGeneration = targetRec?.generation ?? -1;
+    if (!this.recordIsLive(targetRec, entityGeneration(target))) {
+      return err(
+        new StaleEntityError(target as number, targetSlot, entityGeneration(target), {
+          operation: 'relationship-insert',
+          component: component.name,
+          expectedGeneration: entityGeneration(target),
+          actualGeneration: actualGeneration,
+        }),
+      );
+    }
     const targetArch = this.graph.archetypes[targetRec.archetypeId];
     const mirrorLocalId = componentId(mirror);
     const hasMirror =
@@ -424,8 +543,18 @@ export class WorldComponentAccess {
           data: {} as Partial<ShapeOf<ComponentSchema>>,
         },
         true,
+        false,
+        true,
       );
-      if (!added.ok) return added;
+      if (!added.ok) {
+        this.releaseRelationshipPreparation(prepared);
+        return added;
+      }
+    }
+    const installed = this.installRelationshipPreparation(prepared);
+    if (!installed.ok) {
+      this.releaseRelationshipPreparation(prepared);
+      return installed;
     }
     const targetEntries = this.relationshipTargetEntries(component, target);
     const slot = targetEntries.length;
@@ -435,7 +564,10 @@ export class WorldComponentAccess {
       role.targetField as never,
       holder as never,
     );
-    if (!mirrored.ok) return mirrored;
+    if (!mirrored.ok) {
+      this.releaseRelationshipPreparation(prepared);
+      return mirrored;
+    }
     this.relationshipIndex(component)?.attach(holder, target, slot);
     return ok(undefined);
   }
@@ -476,15 +608,16 @@ export class WorldComponentAccess {
   /**
    * Read component data from an entity.
    *
-   * **Transient view contract (feat-20260602):** for fixed-capacity
-   * `array<T,N>` and `buffer<N>` fields, the returned `TypedArray` (and any
-   * subarray of it) aliases the archetype column buffer directly. The view is
-   * valid only until the next structural change (`spawn` / `despawn` /
-   * `addComponent` / `removeComponent`). Holding a view across a structural
-   * change is undefined behaviour -- the backing `ArrayBuffer` is detached on
-   * column growth, and swap-remove at the same row index points to the wrong
-   * entity. **Re-fetch `world.get(e, C)` on every access.** See
-   * `packages/ecs/README.md` Transient view contract section.
+   * **Public array contract:** relationship target `array<entity>` fields are
+   * detached `Uint32Array` copies. Mutating that returned array cannot alter
+   * the materialized target, relationship index, or source. Other array
+   * fields retain the existing transient view contract: fixed-capacity
+   * `array<T,N>` and `buffer<N>` fields alias the archetype column buffer
+   * directly, while variable managed arrays alias their BufferPool slot. Those
+   * views are valid only until the next structural change (`spawn` /
+   * `despawn` / `addComponent` / `removeComponent`); callers must re-fetch
+   * `world.get(e, C)` on every access. Internal owners use `readRow` and
+   * `_getArrayView` directly and retain zero-copy access.
    *
    * @returns `Result<ShapeOf<S>, EcsError>` —
    *   `ok(ShapeOf<S>)` on success;
@@ -532,7 +665,13 @@ export class WorldComponentAccess {
       return err(new ComponentNotPresentError(entity as number, component.name));
     }
 
-    return ok(this.storage.readRow(arch, component, this.tableRow(rec)));
+    const value = this.storage.readRow(arch, component, this.tableRow(rec));
+    const role = relationshipRole(component);
+    if (role?.kind === 'target') {
+      const targetValue = value as Record<string, unknown>;
+      targetValue[role.targetField] = detachRelationshipTargetArray(targetValue[role.targetField]);
+    }
+    return ok(value);
   }
 
   /**
@@ -567,9 +706,10 @@ export class WorldComponentAccess {
    * Returns `undefined` when the entity is dead, the component is absent, the
    * field does not exist, or the field is not an `array<...>` column.
    *
-   * @internal Engine-internal fast path; AI users read the typed view through
-   *   `world.get(e, Transform).world`. The accessor is the zero-materialization
-   *   route the propagate kernel and render walk use.
+   * @internal Engine-internal fast path; AI users read public component values
+   *   through `world.get`. This accessor is the zero-materialization route the
+   *   propagate kernel, relationship owner, and render walk use; it bypasses
+   *   the detached public relationship-target snapshot.
    */
   _getArrayView(
     entity: EntityHandle,
@@ -585,6 +725,141 @@ export class WorldComponentAccess {
     return this.storage.readArrayView(arch, component, this.tableRow(rec), fieldName);
   }
 
+  /** Internal zero-materialisation read for ECS-owned relationship lists. */
+  _getArrayLength(
+    entity: EntityHandle,
+    component: Component,
+    fieldName: string,
+  ): number | undefined {
+    const record = this.lookupAlive(entity, 'relationship-read', component.name);
+    if (!record.ok) return undefined;
+    const arch = this.graph.archetypes[record.value.archetypeId];
+    if (arch === undefined) return undefined;
+    return this.storage.readArrayLength(arch, component, this.tableRow(record.value), fieldName);
+  }
+
+  /** Internal zero-materialisation read for one ECS-owned array element. */
+  _getArrayElement(
+    entity: EntityHandle,
+    component: Component,
+    fieldName: string,
+    index: number,
+  ): number | undefined {
+    const record = this.lookupAlive(entity, 'relationship-read', component.name);
+    if (!record.ok) return undefined;
+    const arch = this.graph.archetypes[record.value.archetypeId];
+    if (arch === undefined) return undefined;
+    return this.storage.readArrayElement(
+      arch,
+      component,
+      this.tableRow(record.value),
+      fieldName,
+      index,
+    );
+  }
+
+  /** Internal scalar-column read used by parent-first hierarchy traversal. */
+  _getFieldValue(
+    entity: EntityHandle,
+    component: Component,
+    fieldName: string,
+  ): number | undefined {
+    const record = this.lookupAlive(entity, 'relationship-read', component.name);
+    if (!record.ok) return undefined;
+    const arch = this.graph.archetypes[record.value.archetypeId];
+    if (arch === undefined) return undefined;
+    return this.storage.readFieldValue(arch, component, this.tableRow(record.value), fieldName);
+  }
+
+  /**
+   * Converge one writable relationship source mutation through the source
+   * owner. The source scalar and its materialized target list are committed as
+   * one operation; no caller receives a raw source column view that could
+   * bypass the mirror/index maintenance.
+   */
+  private setRelationshipSource(
+    entity: EntityHandle,
+    component: Component,
+    value: Record<string, unknown>,
+    record: EntityRecord,
+    arch: Archetype,
+    markChanged: boolean,
+  ): Result<void, EcsError> {
+    const role = relationshipRole(component);
+    if (role?.kind !== 'source') return ok(undefined);
+    const row = this.tableRow(record);
+    const current = this.storage.readRow(arch, component, row) as Record<string, unknown>;
+    const valuePreflight = this.preflightComponentFieldValues(entity, {
+      component,
+      data: value as never,
+    });
+    if (!valuePreflight.ok) return valuePreflight;
+    const merged = { ...current, ...value };
+    const enumError = validateEnumFieldValues(component, merged, entity as number);
+    if (enumError !== null) return err(enumError as unknown as EcsError);
+
+    const oldTarget = this.relationshipTargetEntity(component, current);
+    const target = this.relationshipTargetEntity(component, merged);
+    if (target !== null) {
+      const targetRecord = this.records[entityIndex(target)];
+      const actualGeneration = targetRecord?.generation ?? -1;
+      if (!this.recordIsLive(targetRecord, entityGeneration(target))) {
+        return err(
+          new StaleEntityError(target as number, entityIndex(target), entityGeneration(target), {
+            operation: 'relationship-insert',
+            component: component.name,
+            expectedGeneration: entityGeneration(target),
+            actualGeneration,
+          }),
+        );
+      }
+      const roleAllowsSelf = role.allowSelf;
+      if (entity === target && !roleAllowsSelf) {
+        return err(
+          new RelationshipSelfCycleError(component.name, entity as number, target as number),
+        );
+      }
+      const cycleHit =
+        entity === target && roleAllowsSelf
+          ? null
+          : this.relationshipCycleHit(component, target, entity);
+      if (cycleHit !== null) {
+        return err(
+          new RelationshipSelfCycleError(component.name, entity as number, cycleHit as number),
+        );
+      }
+    }
+
+    // A same-target source write still counts as authored evidence but does
+    // not churn the target mirror or relationship index.
+    if (oldTarget !== target) {
+      const prepared = this.prepareRelationshipInsert(component, merged);
+      if (!prepared.ok) return prepared;
+      const preparation = prepared.value;
+      if (oldTarget !== null) {
+        const detached = this.relationshipOnRemove(entity, component, current);
+        if (!detached.ok) {
+          this.releaseRelationshipPreparation(preparation);
+          return detached;
+        }
+      }
+      const attached = this.relationshipOnInsert(entity, component, merged, preparation);
+      if (!attached.ok) {
+        this.releaseRelationshipPreparation(preparation);
+        return attached;
+      }
+    }
+
+    const fieldCols = this.table(arch).storage.get(componentId(component))?.fields;
+    const sourceColumn = fieldCols?.get(role.sourceField);
+    if (sourceColumn === undefined) {
+      return err(new ComponentNotPresentError(entity as number, component.name));
+    }
+    sourceColumn.view[row] = target === null ? ENTITY_NULL_RAW : (target as number);
+    if (markChanged) this.markComponentChanged(entity, component);
+    return ok(undefined);
+  }
+
   /**
    * Write (partial) component data to an entity.
    *
@@ -631,6 +906,20 @@ export class WorldComponentAccess {
       // F-02: set on missing component returns err instead of silent ignore
       return err(new ComponentNotPresentError(entity as number, component.name));
     }
+    const role = relationshipRole(component as Component);
+    if (role?.kind === 'target') {
+      return err(new RelationshipTargetReadonlyError(component.name, 'set'));
+    }
+    if (role?.kind === 'source') {
+      return this.setRelationshipSource(
+        entity,
+        component,
+        value as Record<string, unknown>,
+        rec,
+        arch,
+        markChanged,
+      );
+    }
     const valuePreflight = this.preflightComponentFieldValues(entity, {
       component,
       data: value,
@@ -874,58 +1163,6 @@ export class WorldComponentAccess {
     return ok(undefined);
   }
 
-  private ensureArrayCapacity<S extends ComponentSchema, K extends ArrayFieldsOf<S>>(
-    entity: EntityHandle,
-    component: Component<string, S>,
-    fieldName: K,
-    minimum: number,
-  ): Result<void, EcsError> {
-    const record = this.lookupAlive(entity, 'relationship-capacity', component.name);
-    if (!record.ok) return record;
-    const rec = record.value;
-    const arch = this.graph.archetypes[rec.archetypeId];
-    if (!arch) {
-      return err(
-        new StaleEntityError(entity as number, entityIndex(entity), entityGeneration(entity), {
-          operation: 'relationship-capacity',
-          component: component.name,
-          expectedGeneration: entityGeneration(entity),
-          actualGeneration: rec.generation,
-        }),
-      );
-    }
-    const fieldCols = this.table(arch).storage.get(componentId(component))?.fields;
-    if (!fieldCols) return err(new ComponentNotPresentError(entity as number, component.name));
-    const fieldNameStr = fieldName as string;
-    const col = fieldCols.get(fieldNameStr);
-    if (!col) return err(new ComponentNotPresentError(entity as number, component.name));
-    const arrayMeta = componentDefinition(component).fields[fieldNameStr]?.arrayMeta;
-    if (arrayMeta === undefined) {
-      return err(new ComponentNotPresentError(entity as number, component.name));
-    }
-    const meta = TYPE_METADATA[arrayMeta.elementType];
-    if (!meta?.byteSize) {
-      return err(new ComponentNotPresentError(entity as number, component.name));
-    }
-    const maximum = Math.floor(262_144 / meta.byteSize);
-    if (!Number.isSafeInteger(minimum) || minimum < 0 || minimum > maximum) {
-      return err(new ManagedBufferOutOfBoundsError(minimum, maximum));
-    }
-
-    const byteLength = minimum * meta.byteSize;
-    const slotId = col.view[this.tableRow(rec)] as number;
-    if (slotId === 0) {
-      if (minimum === 0) return ok(undefined);
-      const allocated = this.bufferPool.alloc(byteLength);
-      if (!allocated.ok) return allocated;
-      col.view[this.tableRow(rec)] = allocated.value.id;
-      return ok(undefined);
-    }
-    if (this.bufferPool.view(slotId).byteLength >= byteLength) return ok(undefined);
-    const grown = this.bufferPool.grow(slotId, byteLength);
-    return grown.ok ? ok(undefined) : grown;
-  }
-
   /**
    * Remove one variable-array element at a known slot. Relationship holders
    * supply the slot from their backpointer, so this is O(1) and never scans
@@ -1011,12 +1248,14 @@ export class WorldComponentAccess {
     entity: EntityHandle,
     componentData: ComponentData<S>,
     internal: boolean,
+    resolveRequirements = true,
+    skipVariableArrayInitialization = false,
   ): Result<void, EcsError> {
     const record = this.lookupAlive(entity, 'addComponent', componentData.component.name);
     if (!record.ok) return record;
 
     const rec = record.value;
-    const srcArch = this.graph.archetypes[rec.archetypeId];
+    let srcArch = this.graph.archetypes[rec.archetypeId];
     /* istanbul ignore next -- defensive: alive record always has valid archetypeId */
     if (!srcArch) {
       return err(
@@ -1066,45 +1305,85 @@ export class WorldComponentAccess {
       return err(enumErr as unknown as EcsError);
     }
 
-    // Check if entity already has this component (using World-local ID).
     const localId = componentId(componentData.component);
+    let relationshipPreparation: RelationshipPreparation | undefined;
+    const componentAlreadyPresent = srcArch.components.some(
+      (candidate) => componentId(candidate) === localId,
+    );
+    // Reserve relationship target storage before resolving required source
+    // components. A failed mirror allocation must not leave a requirement
+    // component (or its epochs) behind on the source entity.
+    if (
+      !internal &&
+      !componentAlreadyPresent &&
+      relationshipRole(componentData.component as Component)?.kind === 'source'
+    ) {
+      const prepared = this.prepareRelationshipInsert(
+        componentData.component as Component,
+        filled as Record<string, unknown>,
+      );
+      if (!prepared.ok) return prepared;
+      relationshipPreparation = prepared.value;
+    }
+
+    // Generic component requirements are resolved once at the structural
+    // boundary. Explicit data remains authoritative; only missing required
+    // identities are added before the requested component is migrated.
+    if (resolveRequirements) {
+      const required = expandComponentRequirements([componentData]).slice(1);
+      for (const requirement of required) {
+        if (
+          srcArch.components.some(
+            (candidate) => componentId(candidate) === componentId(requirement.component),
+          )
+        ) {
+          continue;
+        }
+        // The closure is expanded once above. Bypass requirement expansion for
+        // each member so malformed dependency cycles remain finite and the
+        // structural work still happens in one deterministic sequence.
+        const added = this._addComponentCore(entity, requirement as ComponentData, internal, false);
+        if (!added.ok) {
+          this.releaseRelationshipPreparation(relationshipPreparation);
+          return added;
+        }
+        srcArch = this.graph.archetypes[rec.archetypeId];
+        if (!srcArch) {
+          this.releaseRelationshipPreparation(relationshipPreparation);
+          return err(
+            new StaleEntityError(entity as number, entityIndex(entity), entityGeneration(entity), {
+              operation: 'addComponent',
+              component: componentData.component.name,
+              expectedGeneration: rec.generation,
+              actualGeneration: rec.generation,
+            }),
+          );
+        }
+      }
+    }
+
+    // Check if entity already has this component (using World-local ID).
     if (srcArch.components.some((candidate) => componentId(candidate) === localId)) {
+      this.releaseRelationshipPreparation(relationshipPreparation);
       // M2 exclusive relationship: re-adding the holder with a (possibly new)
-      // target auto-reparents instead of failing (AC-12). Prune the old side
-      // first (removeComponent prunes the old target), then fall through to
-      // the normal add (which appends the new target). The two steps keep the
-      // materialized target list consistent (AC-13);
-      // removeComponent + addComponent each touch the mirror exactly once and
-      // the mirror component carries no relationship of its own, so there is
-      // no recursion. Reparent only fires for top-level user calls
-      // (!internal); engine-internal lazy create / append
-      // never re-add an existing relationship component.
+      // target auto-reparents instead of failing (AC-12). Route the complete
+      // source mutation through one owner operation so the old mirror, new
+      // mirror, source scalar, and backpointer converge atomically. Engine
+      // internal mirror maintenance never re-adds a source component.
       const role = relationshipRole(componentData.component as Component);
       if (role?.kind === 'source' && role.exclusive && !internal) {
-        const prepared = this.prepareRelationshipInsert(
-          componentData.component as Component,
-          filled as Record<string, unknown>,
-        );
-        if (!prepared.ok) return prepared;
-        const removeR = this._removeComponentCore(
+        return this.setRelationshipSource(
           entity,
           componentData.component as Component,
-          false,
+          filled as Record<string, unknown>,
+          rec,
+          srcArch,
+          true,
         );
-        if (!removeR.ok) return removeR;
-        return this._addComponentCore(entity, componentData, false);
       }
       return err(new ComponentAlreadyPresentError(entity as number, componentData.component.name));
     }
 
-    if (!internal && relationshipRole(componentData.component as Component)?.kind === 'source') {
-      const prepared = this.prepareRelationshipInsert(
-        componentData.component as Component,
-        filled as Record<string, unknown>,
-      );
-      if (!prepared.ok) return prepared;
-    }
-
     // Get target archetype via edge cache.
     const targetArch = getAddEdge(
       this.graph,
@@ -1130,6 +1409,7 @@ export class WorldComponentAccess {
         componentData.component,
         this.tableRow(rec),
         filled as ShapeOf<S>,
+        skipVariableArrayInitialization ? { skipVariableArrayInitialization: true } : undefined,
       );
     }
     this.markComponentAdded(entity, componentData.component as Component);
@@ -1139,11 +1419,20 @@ export class WorldComponentAccess {
         entity,
         componentData.component as Component,
         filled as Record<string, unknown>,
+        relationshipPreparation,
       );
-      if (!relationshipResult.ok) return relationshipResult;
+      if (!relationshipResult.ok) {
+        this.releaseRelationshipPreparation(relationshipPreparation);
+        return relationshipResult;
+      }
     }
 
     this.markStructureChanged();
+    this.state.recordStructuralEvidence({
+      kind: 'component-added',
+      entity,
+      componentId: localId,
+    });
     return ok(undefined);
   }
 
@@ -1249,8 +1538,12 @@ export class WorldComponentAccess {
     } else {
       this.storage.migrateEntity(rec, srcArch, targetArch);
     }
-    this.state.removeComponentChange(entity, componentId(component));
     this.markStructureChanged();
+    this.state.recordStructuralEvidence({
+      kind: 'component-removed',
+      entity,
+      componentId: localId,
+    });
     return ok(undefined);
   }
 
@@ -1292,10 +1585,56 @@ export class WorldComponentAccess {
     entity: EntityHandle,
     componentDatas: ComponentData[],
   ): Result<void, EcsError> {
+    componentDatas = expandComponentRequirements(componentDatas);
     const slot = entityIndex(entity);
     const record = this.records[slot];
     if (!record || record.archetypeId !== -1) return ok(undefined);
 
+    // Reserve target-side relationship storage before materializing this
+    // pending row. The command preflight has already checked the batch graph;
+    // this owner-level reservation closes the remaining managed-capacity
+    // failure window without adding a mirror component or advancing an epoch.
+    const relationshipPreparations: (RelationshipPreparation | undefined)[] = [];
+    for (let index = 0; index < componentDatas.length; index += 1) {
+      const componentData = componentDatas[index];
+      if (
+        componentData === undefined ||
+        relationshipRole(componentData.component as Component)?.kind !== 'source'
+      ) {
+        continue;
+      }
+      const filled = fillComponentDefaults(
+        componentData.component,
+        componentData.data as Record<string, unknown>,
+      );
+      const target = this.relationshipTargetEntity(
+        componentData.component as Component,
+        filled as Record<string, unknown>,
+      );
+      const targetRecord = target === null ? undefined : this.records[entityIndex(target)];
+      // A pending target is materialized by an earlier command in the normal
+      // supported order. Leave it to the existing relationship callback when
+      // that target row becomes live; current-world targets are fully
+      // prepared before this source row is appended.
+      if (
+        target !== null &&
+        targetRecord !== undefined &&
+        this.recordIsLive(targetRecord, entityGeneration(target))
+      ) {
+        const prepared = this.prepareRelationshipInsert(
+          componentData.component as Component,
+          filled as Record<string, unknown>,
+        );
+        if (!prepared.ok) {
+          for (const reservation of relationshipPreparations) {
+            this.releaseRelationshipPreparation(reservation);
+          }
+          return prepared;
+        }
+        relationshipPreparations[index] = prepared.value;
+      }
+    }
+
     // Find or create target archetype (using World-local IDs).
     const componentIds = componentDatas.map((cd) => componentId(cd.component));
     const components = componentDatas.map((cd) => cd.component);
@@ -1327,20 +1666,30 @@ export class WorldComponentAccess {
     this.storage.writeEntitySelf(arch, tableRow, entity);
 
     // Publish relationship targets after all rows are written.
-    for (const cd of componentDatas) {
+    for (let index = 0; index < componentDatas.length; index += 1) {
+      const cd = componentDatas[index];
+      if (cd === undefined) continue;
       if (relationshipRole(cd.component as Component)?.kind === 'source') {
         const filled = fillComponentDefaults(cd.component, cd.data as Record<string, unknown>);
         const relationshipResult = this.relationshipOnInsert(
           entity,
           cd.component as Component,
           filled as Record<string, unknown>,
+          relationshipPreparations[index],
         );
         if (!relationshipResult.ok) {
+          for (const reservation of relationshipPreparations) {
+            this.releaseRelationshipPreparation(reservation);
+          }
           return relationshipResult;
         }
       }
     }
     this.markStructureChanged();
+    this.state.recordStructuralEvidence({
+      kind: 'spawn',
+      entity,
+    });
     return ok(undefined);
   }