@forgeax/engine-ecs 0.1.23 → 0.1.24

package/dist/index.mjs

@@ -2046,6 +2046,7 @@ function createDerivedRangeWriter(world, component, source) {
   let boundEpoch = -1;
   let bindingTables = [];
   let bindings = [];
+  let bindingByTable = /* @__PURE__ */ new Map();
   let runStartBuffers = [];
   let runCountBuffers = [];
   const rebind = () => {
@@ -2055,6 +2056,8 @@ function createDerivedRangeWriter(world, component, source) {
     const nextRunCountBuffers = [];
     for (const table of tables) {
       nextBindings.push({
+        tableId: table.id,
+        entities: table.storage.get(componentId(Entity))?.fields.get("self")?.view ?? new Uint32Array(0),
         read: buildWholeColumnShape(table, source.readComponents),
         write: buildWholeColumnShape(table, source.writeComponents),
         rowCapacity: table.size
@@ -2065,6 +2068,11 @@ function createDerivedRangeWriter(world, component, source) {
     }
     bindingTables = tables;
     bindings = nextBindings;
+    bindingByTable = /* @__PURE__ */ new Map();
+    for (let index = 0; index < nextBindings.length; index += 1) {
+      const binding = nextBindings[index];
+      if (binding !== void 0) bindingByTable.set(binding.tableId, index);
+    }
     runStartBuffers = nextRunStartBuffers;
     runCountBuffers = nextRunCountBuffers;
     boundEpoch = source.structureEpoch();
@@ -2075,6 +2083,82 @@ function createDerivedRangeWriter(world, component, source) {
       if (boundEpoch !== source.structureEpoch()) rebind();
       return bindings;
     },
+    locateEntity(entity, cursor) {
+      if (world.execution.health === "poisoned") return false;
+      if (boundEpoch !== source.structureEpoch()) rebind();
+      const archetype = world[worldInternal].getEntityArchetype(entity);
+      if (archetype === void 0) return false;
+      const bindingIndex = bindingByTable.get(archetype.tableId);
+      if (bindingIndex === void 0) return false;
+      const record = world[worldInternal].getRecords()[entity & 16777215];
+      if (record === void 0 || record.archetypeId !== archetype.id) return false;
+      const row = archetype.rows[record.archetypeRow];
+      const binding = bindings[bindingIndex];
+      if (binding === void 0 || row === void 0 || row < 0 || row >= binding.rowCapacity) {
+        return false;
+      }
+      cursor.bindingIndex = bindingIndex;
+      cursor.row = row;
+      return true;
+    },
+    publishChangedRows(bindingIndex, changed) {
+      if (world.execution.health === "poisoned") {
+        return err(new WorldPoisonedError(world.identity, world.execution.fault));
+      }
+      if (boundEpoch !== source.structureEpoch()) rebind();
+      const binding = bindings[bindingIndex];
+      const table = bindingTables[bindingIndex];
+      const runStarts = runStartBuffers[bindingIndex];
+      const runCounts = runCountBuffers[bindingIndex];
+      if (binding === void 0 || table === void 0 || runStarts === void 0 || runCounts === void 0 || !Number.isSafeInteger(bindingIndex) || bindingIndex < 0 || changed.length < binding.rowCapacity || table.storage.get(componentId(component)) === void 0) {
+        return err(new DerivedRangeOutOfBoundsError(0, changed.length, binding?.rowCapacity ?? 0));
+      }
+      let runCount = 0;
+      let runStart = -1;
+      for (let row = 0; row < binding.rowCapacity; row += 1) {
+        if ((changed[row] ?? 0) !== 0) {
+          if (runStart < 0) runStart = row;
+        } else if (runStart >= 0) {
+          runStarts[runCount] = runStart;
+          runCounts[runCount] = row - runStart;
+          runCount += 1;
+          runStart = -1;
+        }
+      }
+      if (runStart >= 0) {
+        runStarts[runCount] = runStart;
+        runCounts[runCount] = binding.rowCapacity - runStart;
+        runCount += 1;
+      }
+      if (runCount === 0) return ok(void 0);
+      const previousEpoch = world[worldInternal].getMutationEpoch();
+      let epoch;
+      try {
+        epoch = world[worldInternal].nextMutationEpoch();
+        const componentIdentifier = componentId(component);
+        for (let index = 0; index < runCount; index += 1) {
+          world[worldInternal].publishDerivedRange(
+            table,
+            componentIdentifier,
+            runStarts[index] ?? 0,
+            runCounts[index] ?? 0,
+            epoch
+          );
+        }
+        changed.fill(0, 0, binding.rowCapacity);
+        return ok(void 0);
+      } catch (cause) {
+        world[worldInternal].restoreMutationEpoch(previousEpoch);
+        world[worldInternal].poisonExecution({
+          code: "shared-kernel-failed",
+          kernelName: `derived-range:${component.name}:publish`,
+          cause,
+          partialWrite: true,
+          retryable: false
+        });
+        return err(new SharedKernelFailureError(component.name, world.identity, cause, true));
+      }
+    },
     writeRange(bindingIndex, base, start, count, kernel, context) {
       if (world.execution.health === "poisoned") {
         return err(new WorldPoisonedError(world.identity, world.execution.fault));
@@ -2288,7 +2372,13 @@ var QueryRowFacade = class _QueryRowFacade {
   mut(component) {
     const current = this.get(component);
     if (current === void 0) throw new Error(`Query row lacks ${component.name}.`);
-    this.world[worldInternal].markComponentChanged(this.entity, componentId(component));
+    if (isRelationshipTarget(component)) {
+      throw new RelationshipTargetReadonlyError(component.name, "query row");
+    }
+    const relationshipSource2 = relationshipRole(component)?.kind === "source";
+    if (!relationshipSource2) {
+      this.world[worldInternal].markComponentChanged(this.entity, componentId(component));
+    }
     return new Proxy(current, {
       set: (target, property, value) => {
         if (typeof property !== "string") return false;
@@ -2325,6 +2415,9 @@ var QuerySpanFacade = class {
     );
   }
   mut(component) {
+    if (relationshipRole(component) !== void 0) {
+      throw new RelationshipTargetReadonlyError(component.name, "query span");
+    }
     this.world[worldInternal].markComponentRangeChanged(
       this.table,
       componentId(component),
@@ -2650,6 +2743,9 @@ var ExecutableQuery = class {
   spanUnavailableReason() {
     if (this.compiled.sparseRoute) return "sparse-component";
     if ((this.compiled.descriptor.optional?.length ?? 0) > 0) return "optional-data";
+    if ((this.compiled.descriptor.write ?? []).some((component) => relationshipRole(component))) {
+      return "relationship-component";
+    }
     return void 0;
   }
 };
@@ -3637,6 +3733,52 @@ var ComponentStorage = class {
     const elementCount = countCol?.view[row] ?? 0;
     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, component, row, fieldName) {
+    const fieldCols = this.table(arch).storage.get(componentId(component))?.fields;
+    if (fieldCols === void 0) return void 0;
+    const arrayMeta = componentDefinition(component).fields[fieldName]?.arrayMeta;
+    if (arrayMeta === void 0) return void 0;
+    if (arrayMeta.length !== void 0) 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, component, row, fieldName, index) {
+    if (!Number.isSafeInteger(index) || index < 0) return void 0;
+    const fieldCols = this.table(arch).storage.get(componentId(component))?.fields;
+    if (fieldCols === void 0) return void 0;
+    const arrayMeta = componentDefinition(component).fields[fieldName]?.arrayMeta;
+    if (arrayMeta === void 0) return void 0;
+    const length = this.readArrayLength(arch, component, row, fieldName);
+    if (length === void 0 || index >= length) return void 0;
+    const col = fieldCols.get(fieldName);
+    if (col === void 0) return void 0;
+    if (arrayMeta.length !== void 0) {
+      return col.view[row * col.arity + index];
+    }
+    const slotId = col.view[row];
+    const bytes = this.bufferPool.view(slotId);
+    if (arrayMeta.elementType === "entity") {
+      const byteOffset = index * 4;
+      if (byteOffset + 4 > bytes.byteLength) return void 0;
+      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, component, row, fieldName) {
+    return this.table(arch).storage.get(componentId(component))?.fields.get(fieldName)?.view[row];
+  }
   // ──────────────────────────────────────────────────────────────────────────
   // Internal — archetype data read/write
   // ──────────────────────────────────────────────────────────────────────────
@@ -3701,7 +3843,7 @@ var ComponentStorage = class {
     if (!col) return;
     col.view[row] = handle;
   }
-  writeRow(arch, component, row, value) {
+  writeRow(arch, component, row, value, options) {
     const localId = componentId(component);
     const fieldCols = this.table(arch).storage.get(localId)?.fields;
     if (!fieldCols) {
@@ -3750,6 +3892,12 @@ var ComponentStorage = class {
       } else {
         const arrayMeta = componentDefinition(component).fields[fieldName]?.arrayMeta;
         if (arrayMeta !== void 0) {
+          if (options?.skipVariableArrayInitialization === true && arrayMeta.length === void 0) {
+            col.view[row] = 0;
+            const countCol = fieldCols.get(arrayCountColumnName(fieldName));
+            if (countCol !== void 0) countCol.view[row] = 0;
+            continue;
+          }
           this.writeArrayField(arch, component, row, fieldName, fieldType, arrayMeta, raw);
         } else {
           col.view[row] = raw;
@@ -4125,20 +4273,19 @@ var ComponentStorage = class {
     return readArrayElementAt(bytes, idx, elementType);
   }
   /**
-   * 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
@@ -4397,6 +4544,9 @@ function relationshipPayloadWrites(data) {
     return true;
   });
 }
+function detachRelationshipTargetArray(value) {
+  return value instanceof Uint32Array ? value.slice() : value;
+}
 var WorldComponentAccess = class {
   constructor(state) {
     this.state = state;
@@ -4437,16 +4587,19 @@ var WorldComponentAccess = class {
     }
     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, target) {
     const role = relationshipRole(source);
     if (role?.kind !== "source") return [];
     const mirror = relationshipMirror(source);
     if (mirror === void 0) return [];
-    const result = this.get(target, mirror);
-    if (!result.ok) return [];
-    const entries = result.value[role.targetField];
-    return entries !== void 0 && typeof entries === "object" ? entries : [];
+    const entries = this._getArrayView(target, mirror, role.targetField);
+    return entries === void 0 ? [] : entries;
   }
   markComponentAdded(entity, component) {
     this.state.markComponentAdded(entity, componentId(component));
@@ -4526,8 +4679,7 @@ var WorldComponentAccess = class {
     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) === true;
-    if (!targetIsPending && !targetLive && !holderIsPending) {
+    if (!targetIsPending && !targetLive) {
       return err(
         new StaleEntityError(target, entityIndex(target), entityGeneration(target), {
           operation: "relationship-insert",
@@ -4584,7 +4736,14 @@ var WorldComponentAccess = class {
       current = next;
     }
   }
-  /** Prepare the target side before a source archetype mutation commits. */
+  /**
+   * 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, value) {
     const role = relationshipRole(component);
     if (role?.kind !== "source") return ok(void 0);
@@ -4605,34 +4764,114 @@ var WorldComponentAccess = class {
       );
     }
     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: {} },
-        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 === void 0) {
+      return err(new ComponentNotPresentError(target, mirror.name));
+    }
+    const meta = TYPE_METADATA[arrayMeta.elementType];
+    if (meta?.byteSize === void 0) {
+      return err(new ComponentNotPresentError(target, mirror.name));
+    }
+    let currentLength = 0;
+    let slotId = 0;
+    if (mirrorPresent) {
+      currentLength = this._getArrayLength(target, mirror, fieldName) ?? 0;
+      const fieldCols = this.table(targetArch).storage.get(mirrorLocalId)?.fields;
+      const column = fieldCols?.get(fieldName);
+      if (column === void 0) {
+        return err(new ComponentNotPresentError(target, mirror.name));
+      }
+      const row = this.tableRow(targetRec);
+      slotId = column.view[row];
+    }
+    const requiredBytes = (currentLength + 1) * meta.byteSize;
+    const maximum = Math.floor(262144 / meta.byteSize);
+    if (!Number.isSafeInteger(currentLength + 1) || currentLength + 1 > maximum) {
+      return err(new ManagedBufferOutOfBoundsError(requiredBytes, 262144));
+    }
+    const preparation = {
+      target,
+      mirror,
+      fieldName,
+      mirrorPresent,
+      reservedSlotId: void 0
+    };
+    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) {
+    if (preparation === void 0 || preparation.reservedSlotId === void 0) return;
+    const slotId = preparation.reservedSlotId;
+    this.bufferPool.release(slotId);
+    preparation.reservedSlotId = void 0;
+  }
+  /** Install a reserved slot after the target mirror archetype exists. */
+  installRelationshipPreparation(preparation) {
+    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 === void 0) {
+      return err(
+        new ComponentNotPresentError(preparation.target, preparation.mirror.name)
+      );
+    }
+    const fieldCols = this.table(arch).storage.get(componentId(preparation.mirror))?.fields;
+    const column = fieldCols?.get(preparation.fieldName);
+    if (column === void 0) {
+      return err(
+        new ComponentNotPresentError(preparation.target, preparation.mirror.name)
       );
-      if (!added.ok) return added;
     }
-    const length = this.relationshipTargetEntries(component, target).length;
-    return this.ensureArrayCapacity(target, mirror, role.targetField, length + 1);
+    const slotId = preparation.reservedSlotId;
+    if (slotId !== void 0) {
+      column.view[this.tableRow(record.value)] = slotId;
+      preparation.reservedSlotId = void 0;
+    }
+    return ok(void 0);
   }
   /** Append `holder` to the materialized target list. */
-  relationshipOnInsert(holder, component, value) {
+  relationshipOnInsert(holder, component, value, preparation) {
     const role = relationshipRole(component);
     if (role?.kind !== "source") return ok(void 0);
     const target = this.relationshipTargetEntity(component, value);
     if (target === null) return ok(void 0);
     const mirror = relationshipMirror(component);
     if (mirror === void 0) return ok(void 0);
-    const prepared = this.prepareRelationshipInsert(component, value);
-    if (!prepared.ok) {
-      if (prepared.error.code === "stale-entity") return ok(void 0);
-      return prepared;
+    let prepared = preparation;
+    if (prepared === void 0) {
+      const preparedResult = this.prepareRelationshipInsert(component, value);
+      if (!preparedResult.ok) return preparedResult;
+      prepared = preparedResult.value;
     }
+    if (prepared === void 0) return ok(void 0);
     const targetSlot = entityIndex(target);
     const targetRec = this.records[targetSlot];
-    if (!this.recordIsLive(targetRec, entityGeneration(target))) return ok(void 0);
+    const actualGeneration = targetRec?.generation ?? -1;
+    if (!this.recordIsLive(targetRec, entityGeneration(target))) {
+      return err(
+        new StaleEntityError(target, targetSlot, entityGeneration(target), {
+          operation: "relationship-insert",
+          component: component.name,
+          expectedGeneration: entityGeneration(target),
+          actualGeneration
+        })
+      );
+    }
     const targetArch = this.graph.archetypes[targetRec.archetypeId];
     const mirrorLocalId = componentId(mirror);
     const hasMirror = targetArch?.components.some((component2) => componentId(component2) === mirrorLocalId) ?? false;
@@ -4643,9 +4882,19 @@ var WorldComponentAccess = class {
           component: mirror,
           data: {}
         },
+        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;
@@ -4655,7 +4904,10 @@ var WorldComponentAccess = class {
       role.targetField,
       holder
     );
-    if (!mirrored.ok) return mirrored;
+    if (!mirrored.ok) {
+      this.releaseRelationshipPreparation(prepared);
+      return mirrored;
+    }
     this.relationshipIndex(component)?.attach(holder, target, slot);
     return ok(void 0);
   }
@@ -4688,15 +4940,16 @@ var WorldComponentAccess = class {
   /**
    * 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;
@@ -4736,7 +4989,13 @@ var WorldComponentAccess = class {
     if (!arch.components.some((candidate) => componentId(candidate) === localId)) {
       return err(new ComponentNotPresentError(entity, 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;
+      targetValue[role.targetField] = detachRelationshipTargetArray(targetValue[role.targetField]);
+    }
+    return ok(value);
   }
   /**
    * Column-level zero-copy view of an `array<T, N>` / `array<T>` field.
@@ -4770,9 +5029,10 @@ var WorldComponentAccess = class {
    * 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, GlobalTransform).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, component, fieldName) {
     const record = this.lookupAlive(entity, "_getArrayView", component.name);
@@ -4782,6 +5042,109 @@ var WorldComponentAccess = class {
     if (!arch) return void 0;
     return this.storage.readArrayView(arch, component, this.tableRow(rec), fieldName);
   }
+  /** Internal zero-materialisation read for ECS-owned relationship lists. */
+  _getArrayLength(entity, component, fieldName) {
+    const record = this.lookupAlive(entity, "relationship-read", component.name);
+    if (!record.ok) return void 0;
+    const arch = this.graph.archetypes[record.value.archetypeId];
+    if (arch === void 0) return void 0;
+    return this.storage.readArrayLength(arch, component, this.tableRow(record.value), fieldName);
+  }
+  /** Internal zero-materialisation read for one ECS-owned array element. */
+  _getArrayElement(entity, component, fieldName, index) {
+    const record = this.lookupAlive(entity, "relationship-read", component.name);
+    if (!record.ok) return void 0;
+    const arch = this.graph.archetypes[record.value.archetypeId];
+    if (arch === void 0) return void 0;
+    return this.storage.readArrayElement(
+      arch,
+      component,
+      this.tableRow(record.value),
+      fieldName,
+      index
+    );
+  }
+  /** Internal scalar-column read used by parent-first hierarchy traversal. */
+  _getFieldValue(entity, component, fieldName) {
+    const record = this.lookupAlive(entity, "relationship-read", component.name);
+    if (!record.ok) return void 0;
+    const arch = this.graph.archetypes[record.value.archetypeId];
+    if (arch === void 0) return void 0;
+    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.
+   */
+  setRelationshipSource(entity, component, value, record, arch, markChanged) {
+    const role = relationshipRole(component);
+    if (role?.kind !== "source") return ok(void 0);
+    const row = this.tableRow(record);
+    const current = this.storage.readRow(arch, component, row);
+    const valuePreflight = this.preflightComponentFieldValues(entity, {
+      component,
+      data: value
+    });
+    if (!valuePreflight.ok) return valuePreflight;
+    const merged = { ...current, ...value };
+    const enumError = validateEnumFieldValues(component, merged, entity);
+    if (enumError !== null) return err(enumError);
+    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, 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, target)
+        );
+      }
+      const cycleHit = entity === target && roleAllowsSelf ? null : this.relationshipCycleHit(component, target, entity);
+      if (cycleHit !== null) {
+        return err(
+          new RelationshipSelfCycleError(component.name, entity, cycleHit)
+        );
+      }
+    }
+    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 === void 0) {
+      return err(new ComponentNotPresentError(entity, component.name));
+    }
+    sourceColumn.view[row] = target === null ? ENTITY_NULL_RAW : target;
+    if (markChanged) this.markComponentChanged(entity, component);
+    return ok(void 0);
+  }
   /**
    * Write (partial) component data to an entity.
    *
@@ -4820,6 +5183,20 @@ var WorldComponentAccess = class {
     if (!arch.components.some((candidate) => componentId(candidate) === localId)) {
       return err(new ComponentNotPresentError(entity, component.name));
     }
+    const role = relationshipRole(component);
+    if (role?.kind === "target") {
+      return err(new RelationshipTargetReadonlyError(component.name, "set"));
+    }
+    if (role?.kind === "source") {
+      return this.setRelationshipSource(
+        entity,
+        component,
+        value,
+        rec,
+        arch,
+        markChanged
+      );
+    }
     const valuePreflight = this.preflightComponentFieldValues(entity, {
       component,
       data: value
@@ -4986,51 +5363,6 @@ var WorldComponentAccess = class {
     this.markComponentChanged(entity, component);
     return ok(void 0);
   }
-  ensureArrayCapacity(entity, component, fieldName, minimum) {
-    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, 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, component.name));
-    const fieldNameStr = fieldName;
-    const col = fieldCols.get(fieldNameStr);
-    if (!col) return err(new ComponentNotPresentError(entity, component.name));
-    const arrayMeta = componentDefinition(component).fields[fieldNameStr]?.arrayMeta;
-    if (arrayMeta === void 0) {
-      return err(new ComponentNotPresentError(entity, component.name));
-    }
-    const meta = TYPE_METADATA[arrayMeta.elementType];
-    if (!meta?.byteSize) {
-      return err(new ComponentNotPresentError(entity, component.name));
-    }
-    const maximum = Math.floor(262144 / 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)];
-    if (slotId === 0) {
-      if (minimum === 0) return ok(void 0);
-      const allocated = this.bufferPool.alloc(byteLength);
-      if (!allocated.ok) return allocated;
-      col.view[this.tableRow(rec)] = allocated.value.id;
-      return ok(void 0);
-    }
-    if (this.bufferPool.view(slotId).byteLength >= byteLength) return ok(void 0);
-    const grown = this.bufferPool.grow(slotId, byteLength);
-    return grown.ok ? ok(void 0) : 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
@@ -5098,7 +5430,7 @@ var WorldComponentAccess = class {
    *   (lazy mirror create or exclusive reparent).
    * @internal
    */
-  _addComponentCore(entity, componentData, internal, resolveRequirements = true) {
+  _addComponentCore(entity, componentData, internal, resolveRequirements = true, skipVariableArrayInitialization = false) {
     const record = this.lookupAlive(entity, "addComponent", componentData.component.name);
     if (!record.ok) return record;
     const rec = record.value;
@@ -5144,6 +5476,19 @@ var WorldComponentAccess = class {
     if (enumErr !== null) {
       return err(enumErr);
     }
+    const localId = componentId(componentData.component);
+    let relationshipPreparation;
+    const componentAlreadyPresent = srcArch.components.some(
+      (candidate) => componentId(candidate) === localId
+    );
+    if (!internal && !componentAlreadyPresent && relationshipRole(componentData.component)?.kind === "source") {
+      const prepared = this.prepareRelationshipInsert(
+        componentData.component,
+        filled
+      );
+      if (!prepared.ok) return prepared;
+      relationshipPreparation = prepared.value;
+    }
     if (resolveRequirements) {
       const required = expandComponentRequirements([componentData]).slice(1);
       for (const requirement of required) {
@@ -5153,9 +5498,13 @@ var WorldComponentAccess = class {
           continue;
         }
         const added = this._addComponentCore(entity, requirement, internal, false);
-        if (!added.ok) return added;
+        if (!added.ok) {
+          this.releaseRelationshipPreparation(relationshipPreparation);
+          return added;
+        }
         srcArch = this.graph.archetypes[rec.archetypeId];
         if (!srcArch) {
+          this.releaseRelationshipPreparation(relationshipPreparation);
           return err(
             new StaleEntityError(entity, entityIndex(entity), entityGeneration(entity), {
               operation: "addComponent",
@@ -5167,32 +5516,21 @@ var WorldComponentAccess = class {
         }
       }
     }
-    const localId = componentId(componentData.component);
     if (srcArch.components.some((candidate) => componentId(candidate) === localId)) {
+      this.releaseRelationshipPreparation(relationshipPreparation);
       const role = relationshipRole(componentData.component);
       if (role?.kind === "source" && role.exclusive && !internal) {
-        const prepared = this.prepareRelationshipInsert(
-          componentData.component,
-          filled
-        );
-        if (!prepared.ok) return prepared;
-        const removeR = this._removeComponentCore(
+        return this.setRelationshipSource(
           entity,
           componentData.component,
-          false
+          filled,
+          rec,
+          srcArch,
+          true
         );
-        if (!removeR.ok) return removeR;
-        return this._addComponentCore(entity, componentData, false);
       }
       return err(new ComponentAlreadyPresentError(entity, componentData.component.name));
     }
-    if (!internal && relationshipRole(componentData.component)?.kind === "source") {
-      const prepared = this.prepareRelationshipInsert(
-        componentData.component,
-        filled
-      );
-      if (!prepared.ok) return prepared;
-    }
     const targetArch = getAddEdge(
       this.graph,
       srcArch,
@@ -5209,7 +5547,8 @@ var WorldComponentAccess = class {
         targetArch,
         componentData.component,
         this.tableRow(rec),
-        filled
+        filled,
+        skipVariableArrayInitialization ? { skipVariableArrayInitialization: true } : void 0
       );
     }
     this.markComponentAdded(entity, componentData.component);
@@ -5217,9 +5556,13 @@ var WorldComponentAccess = class {
       const relationshipResult = this.relationshipOnInsert(
         entity,
         componentData.component,
-        filled
+        filled,
+        relationshipPreparation
       );
-      if (!relationshipResult.ok) return relationshipResult;
+      if (!relationshipResult.ok) {
+        this.releaseRelationshipPreparation(relationshipPreparation);
+        return relationshipResult;
+      }
     }
     this.markStructureChanged();
     this.state.recordStructuralEvidence({
@@ -5347,6 +5690,35 @@ var WorldComponentAccess = class {
     const slot = entityIndex(entity);
     const record = this.records[slot];
     if (!record || record.archetypeId !== -1) return ok(void 0);
+    const relationshipPreparations = [];
+    for (let index = 0; index < componentDatas.length; index += 1) {
+      const componentData = componentDatas[index];
+      if (componentData === void 0 || relationshipRole(componentData.component)?.kind !== "source") {
+        continue;
+      }
+      const filled = fillComponentDefaults(
+        componentData.component,
+        componentData.data
+      );
+      const target = this.relationshipTargetEntity(
+        componentData.component,
+        filled
+      );
+      const targetRecord = target === null ? void 0 : this.records[entityIndex(target)];
+      if (target !== null && targetRecord !== void 0 && this.recordIsLive(targetRecord, entityGeneration(target))) {
+        const prepared = this.prepareRelationshipInsert(
+          componentData.component,
+          filled
+        );
+        if (!prepared.ok) {
+          for (const reservation of relationshipPreparations) {
+            this.releaseRelationshipPreparation(reservation);
+          }
+          return prepared;
+        }
+        relationshipPreparations[index] = prepared.value;
+      }
+    }
     const componentIds = componentDatas.map((cd) => componentId(cd.component));
     const components = componentDatas.map((cd) => cd.component);
     const arch = getOrCreateArchetype(this.graph, componentIds, components);
@@ -5364,15 +5736,21 @@ var WorldComponentAccess = class {
       this.storage.writeRow(arch, cd.component, tableRow2, filled);
     }
     this.storage.writeEntitySelf(arch, tableRow2, entity);
-    for (const cd of componentDatas) {
+    for (let index = 0; index < componentDatas.length; index += 1) {
+      const cd = componentDatas[index];
+      if (cd === void 0) continue;
       if (relationshipRole(cd.component)?.kind === "source") {
         const filled = fillComponentDefaults(cd.component, cd.data);
         const relationshipResult = this.relationshipOnInsert(
           entity,
           cd.component,
-          filled
+          filled,
+          relationshipPreparations[index]
         );
         if (!relationshipResult.ok) {
+          for (const reservation of relationshipPreparations) {
+            this.releaseRelationshipPreparation(reservation);
+          }
           return relationshipResult;
         }
       }
@@ -6137,6 +6515,27 @@ function spawnCore(world, componentDatas, internal) {
     if (enumErr !== null) return err(enumErr);
     filledData.push(filled);
   }
+  const relationshipPreparations = [];
+  if (!internal) {
+    for (let index = 0; index < componentDatas.length; index += 1) {
+      const componentData = componentDatas[index];
+      const value = filledData[index];
+      if (componentData === void 0 || value === void 0 || relationshipRole(componentData.component)?.kind !== "source") {
+        continue;
+      }
+      const prepared = world[worldInternal].prepareRelationshipInsert(
+        componentData.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 === void 0)
@@ -6172,9 +6571,15 @@ function spawnCore(world, componentDatas, internal) {
       const relation = world[worldInternal].relationshipOnInsert(
         spawnedEntity,
         cd.component,
-        filled
+        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();
@@ -6248,7 +6653,8 @@ function despawnCore(world, entity, internal) {
 }
 function worldAddChild(world, parent, child, component, data) {
   const holderComp = component;
-  if (relationshipRole(holderComp)?.kind !== "source") {
+  const role = relationshipRole(holderComp);
+  if (role?.kind !== "source") {
     return err(new ComponentNotPresentError(child, component.name));
   }
   const parentSlot = entityIndex(parent);
@@ -6277,7 +6683,6 @@ function worldAddChild(world, parent, child, component, data) {
       })
     );
   }
-  const role = relationshipRole(holderComp);
   if (child === parent && !(role?.kind === "source" && role.allowSelf)) {
     return err(new RelationshipSelfCycleError(component.name, child, child));
   }
@@ -6328,10 +6733,10 @@ function worldRemoveChild(world, parent, child, component) {
 }
 function worldReparent(world, child, newParent, component, data) {
   const holderComp = component;
-  if (relationshipRole(holderComp)?.kind !== "source") {
+  const role = relationshipRole(holderComp);
+  if (role?.kind !== "source") {
     return err(new ComponentNotPresentError(child, component.name));
   }
-  const role = relationshipRole(holderComp);
   if (child === newParent && !(role?.kind === "source" && role.allowSelf)) {
     return err(
       new RelationshipSelfCycleError(component.name, child, newParent)
@@ -6361,11 +6766,14 @@ function worldReparent(world, child, newParent, component, data) {
       })
     );
   }
-  if (childArch.components.some((component2) => componentId(component2) === componentId(holderComp))) {
-    const removeResult = world.removeComponent(child, component);
-    if (!removeResult.ok) return removeResult;
+  const payload = {
+    ...data,
+    [role.sourceField]: newParent
+  };
+  if (childArch.components.some((candidate) => componentId(candidate) === componentId(holderComp))) {
+    return world.set(child, component, payload);
   }
-  return world.addComponent(child, { component, data });
+  return world.addComponent(child, { component, data: payload });
 }
 function worldIterAncestors(world, entity) {
   return {
@@ -6986,6 +7394,9 @@ var World = class {
       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),
@@ -7016,6 +7427,7 @@ var World = class {
       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),
@@ -7024,6 +7436,7 @@ var World = class {
       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),
@@ -7175,7 +7588,12 @@ var World = class {
   }
   /** Query facade write after the facade has already marked evidence. */
   internalsetQueryRow(entity, component, value) {
-    return this.componentAccess.set(entity, component, value, false);
+    return this.componentAccess.set(
+      entity,
+      component,
+      value,
+      relationshipRole(component)?.kind === "source"
+    );
   }
   /** Query facade read that does not re-enter the public World API. */
   internalgetQueryRow(entity, component) {
@@ -7523,6 +7941,15 @@ var World = class {
   internalgetArrayView(entity, component, fieldName) {
     return this.componentAccess._getArrayView(entity, component, fieldName);
   }
+  internalgetArrayLength(entity, component, fieldName) {
+    return this.componentAccess._getArrayLength(entity, component, fieldName);
+  }
+  internalgetArrayElement(entity, component, fieldName, index) {
+    return this.componentAccess._getArrayElement(entity, component, fieldName, index);
+  }
+  internalgetFieldValue(entity, component, fieldName) {
+    return this.componentAccess._getFieldValue(entity, component, fieldName);
+  }
   set(entity, component, value) {
     if (isRelationshipTarget(component)) return this.relationshipTargetWriteError(component, "set");
     return this.componentAccess.set(entity, component, value);
@@ -7591,8 +8018,16 @@ var World = class {
     this.componentAccess.releaseManagedRefsOnRow(a, c, r);
   }
   /** */
-  internalrelationshipOnInsert(h, c, v) {
-    return this.componentAccess.relationshipOnInsert(h, c, v);
+  internalrelationshipOnInsert(h, c, v, preparation) {
+    return this.componentAccess.relationshipOnInsert(h, c, v, preparation);
+  }
+  /** */
+  internalprepareRelationshipInsert(c, v) {
+    return this.componentAccess.prepareRelationshipInsert(c, v);
+  }
+  /** */
+  internalreleaseRelationshipPreparation(preparation) {
+    this.componentAccess.releaseRelationshipPreparation(preparation);
   }
   /** */
   internalrelationshipOnRemove(h, c, v) {