@forgeax/engine-ecs 0.1.21 → 0.1.24

package/dist/index.mjs

@@ -21,6 +21,31 @@ function componentDefinition(component) {
   }
   return definition;
 }
+function componentRequirements(component) {
+  return definitions.definitions.get(component)?.policy.requires ?? [];
+}
+function expandComponentRequirements(componentDatas) {
+  let hasRequirements = false;
+  for (const entry of componentDatas) {
+    if (componentRequirements(entry.component).length !== 0) {
+      hasRequirements = true;
+      break;
+    }
+  }
+  if (!hasRequirements) return componentDatas;
+  const expanded = [...componentDatas];
+  const seen = new Set(expanded.map((entry) => entry.component));
+  for (let index = 0; index < expanded.length; index++) {
+    const component = expanded[index]?.component;
+    if (component === void 0) continue;
+    for (const required of componentRequirements(component)) {
+      if (seen.has(required)) continue;
+      seen.add(required);
+      expanded.push({ component: required, data: {} });
+    }
+  }
+  return expanded;
+}
 function deepFreeze(value) {
   if (value === null || typeof value !== "object" && typeof value !== "function") {
     return value;
@@ -654,6 +679,17 @@ var ChangeEpochExhaustedError = class extends Error {
     this.detail = { epoch };
   }
 };
+var DerivedRangeOutOfBoundsError = class extends Error {
+  name = "DerivedRangeOutOfBoundsError";
+  code = "derived-range-out-of-bounds";
+  expected = "a non-negative span-relative range with start + count <= span.length";
+  hint = "check start and count against the QuerySpan length, then retry without changing World state";
+  detail;
+  constructor(start, count, spanLength) {
+    super(`Derived range [${start}, ${start + count}) exceeds QuerySpan length ${spanLength}.`);
+    this.detail = { start, count, spanLength };
+  }
+};
 var ProtectedResourceError = class extends Error {
   name = "ProtectedResourceError";
   code = "resource-protected";
@@ -1254,7 +1290,11 @@ function defineComponent(name, fields, options) {
   registerComponentDefinition(token, {
     fields: frozenFields,
     defaults: frozenDefaults,
-    policy: { transient: options?.transient ?? false, meta }
+    policy: {
+      transient: options?.transient ?? false,
+      meta,
+      requires: Object.freeze([...options?.requires ?? []])
+    }
   });
   return Object.freeze(token);
 }
@@ -1385,7 +1425,11 @@ function defineRelationship(options) {
   };
   const target = defineComponent(options.targetName, targetFields);
   const sourceFields = { [options.sourceField]: { type: "entity" } };
-  const source = defineComponent(options.sourceName, sourceFields);
+  const source = defineComponent(
+    options.sourceName,
+    sourceFields,
+    options.sourceRequires === void 0 ? void 0 : { requires: options.sourceRequires }
+  );
   roles.set(source, {
     kind: "source",
     target,
@@ -1563,51 +1607,10 @@ function entityGeneration(entity) {
   return unpackGen(entity);
 }
 
-// src/world-change-journal.ts
-var EMPTY_CHANGES = Object.freeze([]);
-var WorldChangeJournal = class {
-  constructor(capacity = 65536) {
-    this.capacity = capacity;
-    if (!Number.isSafeInteger(capacity) || capacity <= 0) {
-      throw new RangeError("WorldChangeJournal capacity must be a positive safe integer");
-    }
-    this.records = new Array(capacity);
-  }
-  capacity;
-  records;
-  nextSequence = 1;
-  cursor() {
-    return this.nextSequence - 1;
-  }
-  append(change) {
-    const sequence = this.nextSequence;
-    this.nextSequence += 1;
-    this.records[(sequence - 1) % this.capacity] = { ...change, sequence };
-    return sequence;
-  }
-  readAfter(cursor) {
-    const latest = this.cursor();
-    if (!Number.isSafeInteger(cursor) || cursor < 0 || cursor > latest) {
-      throw new RangeError(`WorldChangeJournal cursor ${cursor} is outside 0..${latest}`);
-    }
-    const oldestAvailable = Math.max(1, latest - this.capacity + 1);
-    if (cursor < oldestAvailable - 1) {
-      return { status: "overflow", cursor: latest, oldestAvailable };
-    }
-    if (cursor === latest) {
-      return { status: "ok", cursor: latest, records: EMPTY_CHANGES };
-    }
-    const records = [];
-    for (let sequence = cursor + 1; sequence <= latest; sequence += 1) {
-      const record = this.records[(sequence - 1) % this.capacity];
-      if (record === void 0 || record.sequence !== sequence) {
-        return { status: "overflow", cursor: latest, oldestAvailable };
-      }
-      records.push(record);
-    }
-    return { status: "ok", cursor: latest, records };
-  }
-};
+// src/internal.ts
+var DERIVED_WRITER = /* @__PURE__ */ Symbol.for(
+  "forgeax.ecs.query.derivedWriter"
+);
 
 // src/storage/archetype.ts
 var INITIAL_CAPACITY = 64;
@@ -2039,10 +2042,246 @@ function markComponentChanged(graph, location, entity, componentId2, epoch) {
   const tableRow2 = archetype.rows[location.archetypeRow] ?? -1;
   epochs.changed[tableRow2] = epoch();
 }
-function readTableEntityRange(table, rowStart, rowCount) {
-  const entities = table.storage.get(componentId(Entity))?.fields.get("self")?.view;
-  if (entities === void 0) return [];
-  return entities.subarray(rowStart, rowStart + rowCount);
+function createDerivedRangeWriter(world, component, source) {
+  let boundEpoch = -1;
+  let bindingTables = [];
+  let bindings = [];
+  let bindingByTable = /* @__PURE__ */ new Map();
+  let runStartBuffers = [];
+  let runCountBuffers = [];
+  const rebind = () => {
+    const tables = source.tables();
+    const nextBindings = [];
+    const nextRunStartBuffers = [];
+    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
+      });
+      const runCapacity = Math.max(1, table.size);
+      nextRunStartBuffers.push(new Int32Array(runCapacity));
+      nextRunCountBuffers.push(new Int32Array(runCapacity));
+    }
+    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();
+  };
+  rebind();
+  const writer = {
+    get bindings() {
+      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));
+      }
+      if (boundEpoch !== source.structureEpoch()) rebind();
+      const binding = bindings[bindingIndex];
+      const table = bindingTables[bindingIndex];
+      if (binding === void 0 || table === void 0 || !Number.isSafeInteger(bindingIndex) || !Number.isSafeInteger(base) || !Number.isSafeInteger(start) || !Number.isSafeInteger(count) || bindingIndex < 0 || base < 0 || start < 0 || count < 0 || base + start + count > binding.rowCapacity || table.storage.get(componentId(component)) === void 0) {
+        return err(new DerivedRangeOutOfBoundsError(start, count, binding?.rowCapacity ?? 0));
+      }
+      if (count === 0) return ok(void 0);
+      const previousEpoch = world[worldInternal].getMutationEpoch();
+      let epoch;
+      try {
+        epoch = world[worldInternal].nextMutationEpoch();
+      } catch (cause) {
+        return err(cause);
+      }
+      try {
+        kernel(binding, base, start, count, context);
+        world[worldInternal].publishDerivedRange(
+          table,
+          componentId(component),
+          base + start,
+          count,
+          epoch
+        );
+        return ok(void 0);
+      } catch (cause) {
+        world[worldInternal].restoreMutationEpoch(previousEpoch);
+        world[worldInternal].poisonExecution({
+          code: "shared-kernel-failed",
+          kernelName: `derived-range:${component.name}`,
+          cause,
+          partialWrite: true,
+          retryable: false
+        });
+        return err(new SharedKernelFailureError(component.name, world.identity, cause, true));
+      }
+    },
+    probeAndCommitRange(bindingIndex, base, start, count, probe, commit, context) {
+      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) || !Number.isSafeInteger(base) || !Number.isSafeInteger(start) || !Number.isSafeInteger(count) || bindingIndex < 0 || base < 0 || start < 0 || count < 0 || base + start + count > binding.rowCapacity || table.storage.get(componentId(component)) === void 0) {
+        return err(new DerivedRangeOutOfBoundsError(start, count, binding?.rowCapacity ?? 0));
+      }
+      if (count === 0) return ok(void 0);
+      const previousEpoch = world[worldInternal].getMutationEpoch();
+      let runCount = 0;
+      let epoch = 0;
+      let epochReserved = false;
+      let runStart = -1;
+      try {
+        for (let offset = 0; offset < count; offset += 1) {
+          const row = base + start + offset;
+          const changed = probe(binding, row, context);
+          if (changed) {
+            if (!epochReserved) {
+              try {
+                epoch = world[worldInternal].nextMutationEpoch();
+                epochReserved = true;
+              } catch (cause) {
+                return err(cause);
+              }
+            }
+            if (runStart < 0) runStart = row;
+            commit(binding, row, context);
+          } else if (runStart >= 0) {
+            runStarts[runCount] = runStart;
+            runCounts[runCount] = row - runStart;
+            runCount += 1;
+            runStart = -1;
+          }
+        }
+        if (runStart >= 0) {
+          runStarts[runCount] = runStart;
+          runCounts[runCount] = base + start + count - runStart;
+          runCount += 1;
+        }
+        if (runCount > 0) {
+          const componentIdentifier = componentId(component);
+          for (let index = 0; index < runCount; index += 1) {
+            const runStartValue = runStarts[index] ?? 0;
+            const runLength = runCounts[index] ?? 0;
+            world[worldInternal].publishDerivedRange(
+              table,
+              componentIdentifier,
+              runStartValue,
+              runLength,
+              epoch
+            );
+          }
+        }
+        return ok(void 0);
+      } catch (cause) {
+        if (epochReserved) world[worldInternal].restoreMutationEpoch(previousEpoch);
+        world[worldInternal].poisonExecution({
+          code: "shared-kernel-failed",
+          kernelName: `derived-range:${component.name}:probe`,
+          cause,
+          partialWrite: true,
+          retryable: false
+        });
+        return err(new SharedKernelFailureError(component.name, world.identity, cause, true));
+      }
+    }
+  };
+  return writer;
+}
+function buildWholeColumnShape(table, components) {
+  const shape = {};
+  for (const component of components) {
+    const fields = table.storage.get(componentId(component))?.fields;
+    if (fields === void 0) continue;
+    for (const [fieldName, column] of fields) shape[fieldName] = column.view;
+  }
+  return shape;
 }
 
 // src/query/query.ts
@@ -2133,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;
@@ -2154,7 +2399,7 @@ var QuerySpanFacade = class {
     this.rowStart = rowStart;
     this.length = length;
     const entityColumn = table.storage.get(componentId(Entity))?.fields.get("self");
-    this.entities = entityColumn?.view.subarray(rowStart, rowStart + length) ?? new Uint32Array(0);
+    this.entities = entityColumn === void 0 ? new Uint32Array(0) : rowStart === 0 && length === entityColumn.view.length ? entityColumn.view : entityColumn.view.subarray(rowStart, rowStart + length);
   }
   world;
   table;
@@ -2170,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),
@@ -2185,7 +2433,7 @@ var QuerySpanFacade = class {
   }
 };
 function makeManagedColumnReader(view, length, fieldType) {
-  const slots = view.subarray(0, length);
+  const slots = view.length === length ? view : view.subarray(0, length);
   return Object.freeze({
     length,
     get(i) {
@@ -2201,7 +2449,7 @@ function buildColumnShape(table, component, rowStart, rowCount) {
   for (const [fieldName, column] of fields) {
     const start = rowStart * column.arity;
     const end = start + rowCount * column.arity;
-    const view = column.view.subarray(start, end);
+    const view = start === 0 && end === column.view.length ? column.view : column.view.subarray(start, end);
     const fieldType = componentSchema(component)[fieldName];
     shape[fieldName] = fieldType !== void 0 && isManagedField(fieldType) ? makeManagedColumnReader(view, view.length, fieldType) : view;
   }
@@ -2216,6 +2464,7 @@ var ExecutableQuery = class {
   compiled;
   matchedArchetypes = [];
   matchedTables = [];
+  matchedTableObjects = [];
   lastGraphGeneration = -1;
   lastObservedEpoch = 0;
   active = false;
@@ -2306,7 +2555,8 @@ var ExecutableQuery = class {
         query.refreshMatches();
         const structureEpoch = query.world[worldInternal].getStructureEpoch();
         const upperBound = query.world[worldInternal].getMutationEpoch();
-        let index = 0;
+        let tableIndex = 0;
+        let rowIndex = 0;
         let finished = false;
         const close = (commit) => {
           if (finished) return;
@@ -2324,12 +2574,37 @@ var ExecutableQuery = class {
                 query.world[worldInternal].getStructureEpoch()
               );
             }
-            while (index < query.matchedTables.length) {
-              const table = query.world[worldInternal].getGraph().tables[query.matchedTables[index++] ?? -1];
-              if (table === void 0 || table.size === 0) continue;
+            while (tableIndex < query.matchedTables.length) {
+              const table = query.world[worldInternal].getGraph().tables[query.matchedTables[tableIndex] ?? -1];
+              if (table === void 0 || table.size === 0) {
+                tableIndex += 1;
+                rowIndex = 0;
+                continue;
+              }
+              if (query.compiled.changedIds.length === 0 && query.compiled.addedIds.length === 0) {
+                tableIndex += 1;
+                rowIndex = 0;
+                return {
+                  done: false,
+                  value: new QuerySpanFacade(query.world, table, 0, table.size)
+                };
+              }
+              while (rowIndex < table.size && !query.denseChangeMatches(table, rowIndex, upperBound)) {
+                rowIndex += 1;
+              }
+              if (rowIndex >= table.size) {
+                tableIndex += 1;
+                rowIndex = 0;
+                continue;
+              }
+              const start = rowIndex;
+              rowIndex += 1;
+              while (rowIndex < table.size && query.denseChangeMatches(table, rowIndex, upperBound)) {
+                rowIndex += 1;
+              }
               return {
                 done: false,
-                value: new QuerySpanFacade(query.world, table, 0, table.size)
+                value: new QuerySpanFacade(query.world, table, start, rowIndex - start)
               };
             }
             close(true);
@@ -2343,6 +2618,25 @@ var ExecutableQuery = class {
       }
     });
   }
+  [DERIVED_WRITER](component) {
+    const reason = this.spanUnavailableReason();
+    if (reason !== void 0) return err(new QuerySpanUnavailableError(reason));
+    return ok(
+      createDerivedRangeWriter(
+        this.world,
+        component,
+        {
+          structureEpoch: () => this.world[worldInternal].getStructureEpoch(),
+          tables: () => {
+            this.refreshMatches();
+            return this.matchedTableObjects;
+          },
+          readComponents: this.compiled.descriptor.read ?? [],
+          writeComponents: this.compiled.descriptor.write ?? []
+        }
+      )
+    );
+  }
   combinations(k = 2) {
     const query = this;
     return {
@@ -2393,6 +2687,10 @@ var ExecutableQuery = class {
     if (this.lastGraphGeneration === graph.generation) return;
     this.matchedArchetypes = graph.archetypes.filter((archetype) => this.archetypeMatches(archetype)).map((archetype) => archetype.id);
     this.matchedTables = graph.tables.filter((table) => this.tableMatches(table)).map((table) => table.id);
+    this.matchedTableObjects = this.matchedTables.flatMap((id) => {
+      const table = graph.tables[id];
+      return table === void 0 ? [] : [table];
+    });
     this.lastGraphGeneration = graph.generation;
   }
   archetypeMatches(archetype) {
@@ -2431,11 +2729,23 @@ var ExecutableQuery = class {
     }
     return true;
   }
+  denseChangeMatches(table, row, upperBound) {
+    for (const componentId2 of this.compiled.changedIds) {
+      const epoch = table.storage.get(componentId2)?.epochs.changed[row] ?? 0;
+      if (epoch <= this.lastObservedEpoch || epoch > upperBound) return false;
+    }
+    for (const componentId2 of this.compiled.addedIds) {
+      const epoch = table.storage.get(componentId2)?.epochs.added[row] ?? 0;
+      if (epoch <= this.lastObservedEpoch || epoch > upperBound) return false;
+    }
+    return true;
+  }
   spanUnavailableReason() {
     if (this.compiled.sparseRoute) return "sparse-component";
     if ((this.compiled.descriptor.optional?.length ?? 0) > 0) return "optional-data";
-    if ((this.compiled.descriptor.changed?.length ?? 0) > 0 || (this.compiled.descriptor.added?.length ?? 0) > 0)
-      return "row-change-filter";
+    if ((this.compiled.descriptor.write ?? []).some((component) => relationshipRole(component))) {
+      return "relationship-component";
+    }
     return void 0;
   }
 };
@@ -3394,8 +3704,8 @@ var ComponentStorage = class {
   get sharedRefs() {
     return this.state.sharedRefs;
   }
-  routeError(err11, ctx) {
-    this.state.routeError(err11, ctx);
+  routeError(err12, ctx) {
+    this.state.routeError(err12, ctx);
   }
   readArrayView(arch, component, row, fieldName) {
     const fieldCols = this.table(arch).storage.get(componentId(component))?.fields;
@@ -3423,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
   // ──────────────────────────────────────────────────────────────────────────
@@ -3487,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) {
@@ -3536,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;
@@ -3762,11 +4124,11 @@ var ComponentStorage = class {
    * the EcsError contract; this helper only attaches the systemName context
    * so AI users can correlate the error with the holder component / field.
    */
-  routeArrayError(err11, componentName, fieldName) {
+  routeArrayError(err12, componentName, fieldName) {
     const ctx = {
       systemName: `World.write (${componentName}.${fieldName})`
     };
-    this.routeError(err11, ctx);
+    this.routeError(err12, ctx);
   }
   /**
    * Write the value of an `array<T>` / `array<T,N>` field at `row` (D-3 +
@@ -3911,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
@@ -4183,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;
@@ -4211,8 +4575,8 @@ var WorldComponentAccess = class {
   get uniqueRefs() {
     return this.state.uniqueRefs;
   }
-  routeError(err11, ctx) {
-    this.state.routeError(err11, ctx);
+  routeError(err12, ctx) {
+    this.state.routeError(err12, ctx);
   }
   relationshipIndex(component) {
     if (relationshipRole(component)?.kind !== "source") return void 0;
@@ -4223,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));
@@ -4312,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",
@@ -4370,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);
@@ -4391,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;
@@ -4429,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;
@@ -4441,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);
   }
@@ -4474,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;
@@ -4522,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.
@@ -4556,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, 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, component, fieldName) {
     const record = this.lookupAlive(entity, "_getArrayView", component.name);
@@ -4568,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.
    *
@@ -4606,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
@@ -4772,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
@@ -4884,11 +5430,11 @@ var WorldComponentAccess = class {
    *   (lazy mirror create or exclusive reparent).
    * @internal
    */
-  _addComponentCore(entity, componentData, internal) {
+  _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;
-    const srcArch = this.graph.archetypes[rec.archetypeId];
+    let srcArch = this.graph.archetypes[rec.archetypeId];
     if (!srcArch) {
       return err(
         new StaleEntityError(entity, entityIndex(entity), entityGeneration(entity), {
@@ -4931,31 +5477,60 @@ var WorldComponentAccess = class {
       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) {
+        if (srcArch.components.some(
+          (candidate) => componentId(candidate) === componentId(requirement.component)
+        )) {
+          continue;
+        }
+        const added = this._addComponentCore(entity, requirement, 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, entityIndex(entity), entityGeneration(entity), {
+              operation: "addComponent",
+              component: componentData.component.name,
+              expectedGeneration: rec.generation,
+              actualGeneration: rec.generation
+            })
+          );
+        }
+      }
+    }
     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,
@@ -4972,7 +5547,8 @@ var WorldComponentAccess = class {
         targetArch,
         componentData.component,
         this.tableRow(rec),
-        filled
+        filled,
+        skipVariableArrayInitialization ? { skipVariableArrayInitialization: true } : void 0
       );
     }
     this.markComponentAdded(entity, componentData.component);
@@ -4980,11 +5556,20 @@ 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({
+      kind: "component-added",
+      entity,
+      componentId: localId
+    });
     return ok(void 0);
   }
   /**
@@ -5062,8 +5647,12 @@ var WorldComponentAccess = class {
     } 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(void 0);
   }
   // ──────────────────────────────────────────────────────────────────────────
@@ -5097,9 +5686,39 @@ var WorldComponentAccess = class {
    * Idempotent: a record with archetypeId !== -1 is already materialized.
    */
   _materializePendingEntity(entity, componentDatas) {
+    componentDatas = expandComponentRequirements(componentDatas);
     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);
@@ -5117,20 +5736,30 @@ 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;
         }
       }
     }
     this.markStructureChanged();
+    this.state.recordStructuralEvidence({
+      kind: "spawn",
+      entity
+    });
     return ok(void 0);
   }
   // ──────────────────────────────────────────────────────────────────────────
@@ -5411,7 +6040,7 @@ var BufferPool = class {
     return n;
   }
 };
-var SHARED_REF_MUTATION_JOURNAL_CAPACITY = 4096;
+var SHARED_REF_RELEASE_EVIDENCE_CAPACITY = 4096;
 var SharedRefStore = class {
   payloads = /* @__PURE__ */ new Map();
   refcounts = /* @__PURE__ */ new Map();
@@ -5420,7 +6049,8 @@ var SharedRefStore = class {
   internedKeys = /* @__PURE__ */ new Map();
   nextSlot = BUILTIN_BASE;
   mutationEpoch = 0;
-  mutationJournal = [];
+  /** Latest published mutation epoch per live handle; not an event journal. */
+  mutationEpochs = /* @__PURE__ */ new Map();
   releaseJournal = [];
   /**
    * Generation table indexed by slot (D-6). Each entry tracks the current
@@ -5524,26 +6154,23 @@ var SharedRefStore = class {
       throw new RangeError("SharedRefStore mutation epoch exhausted");
     }
     this.mutationEpoch += 1;
-    this.mutationJournal.push({ epoch: this.mutationEpoch, handle: unwrapHandle(handle) });
-    if (this.mutationJournal.length > SHARED_REF_MUTATION_JOURNAL_CAPACITY) {
-      this.mutationJournal.shift();
-    }
+    this.mutationEpochs.set(unwrapHandle(handle), this.mutationEpoch);
     return ok(void 0);
   }
   /** Current upper bound for explicitly published payload mutations. */
   getMutationEpoch() {
     return this.mutationEpoch;
   }
-  /** Read exact changed handles after `cursor`; overflow requires consumer resync. */
+  /** Read each live handle whose latest published mutation is after `cursor`. */
   readChangesSince(cursor) {
-    const oldestAvailable = this.mutationJournal[0]?.epoch ?? this.mutationEpoch + 1;
-    if (cursor < oldestAvailable - 1) {
-      return { status: "overflow", cursor: this.mutationEpoch, oldestAvailable };
+    const records = [];
+    for (const [handle, epoch] of this.mutationEpochs) {
+      if (epoch > cursor) records.push({ epoch, handle });
     }
+    records.sort((left, right) => left.epoch - right.epoch || left.handle - right.handle);
     return {
-      status: "ok",
       cursor: this.mutationEpoch,
-      records: this.mutationJournal.filter((record) => record.epoch > cursor)
+      records
     };
   }
   /**
@@ -5609,6 +6236,7 @@ var SharedRefStore = class {
     }
     this.refcounts.delete(raw);
     this.payloads.delete(raw);
+    this.mutationEpochs.delete(raw);
     const generation = storeGen + 1;
     this._generations[slot] = generation;
     if (!isRetiredSlot(generation)) {
@@ -5621,7 +6249,7 @@ var SharedRefStore = class {
       evidence: "released"
     });
     this.releaseJournal.push(evidence);
-    if (this.releaseJournal.length > SHARED_REF_MUTATION_JOURNAL_CAPACITY) {
+    if (this.releaseJournal.length > SHARED_REF_RELEASE_EVIDENCE_CAPACITY) {
       this.releaseJournal.shift();
     }
     return ok(evidence);
@@ -5645,6 +6273,47 @@ var SharedRefStore = class {
     return this.payloads.size;
   }
 };
+
+// src/storage/structural-evidence.ts
+var StructuralEvidenceRing = class {
+  constructor(capacity = 1024) {
+    this.capacity = capacity;
+    if (!Number.isSafeInteger(capacity) || capacity <= 0) {
+      throw new RangeError("StructuralEvidenceRing capacity must be a positive safe integer");
+    }
+    this.events = new Array(capacity);
+  }
+  capacity;
+  events;
+  nextSequence = 1;
+  get cursor() {
+    return this.nextSequence - 1;
+  }
+  append(input) {
+    const sequence = this.nextSequence;
+    this.nextSequence += 1;
+    this.events[(sequence - 1) % this.capacity] = { ...input, sequence };
+    return sequence;
+  }
+  readAfter(cursor) {
+    const latest = this.cursor;
+    if (!Number.isSafeInteger(cursor) || cursor < 0 || cursor > latest) {
+      throw new RangeError(`StructuralEvidenceRing cursor ${cursor} is outside 0..${latest}`);
+    }
+    const oldestAvailable = Math.max(1, latest - this.capacity + 1);
+    if (cursor < oldestAvailable - 1)
+      return { status: "overflow", cursor: latest, oldestAvailable };
+    const events = [];
+    for (let sequence = cursor + 1; sequence <= latest; sequence += 1) {
+      const event = this.events[(sequence - 1) % this.capacity];
+      if (event === void 0 || event.sequence !== sequence) {
+        return { status: "overflow", cursor: latest, oldestAvailable };
+      }
+      events.push(event);
+    }
+    return { status: "ok", cursor: latest, events };
+  }
+};
 var UniqueRefStore = class {
   payloads = /* @__PURE__ */ new Map();
   freeSlots = [];
@@ -5801,7 +6470,7 @@ var WorldCore = class {
   sharedRefs = new SharedRefStore();
   storage;
   componentMutationEpochs = [];
-  changeJournal = new WorldChangeJournal();
+  structuralEvidence = new StructuralEvidenceRing();
   /** One packed reverse index per relationship source component. */
   relationshipIndexes = /* @__PURE__ */ new Map();
   mutationEpoch = 0;
@@ -5830,6 +6499,7 @@ function tableRow(world, record) {
   return archetype?.rows[record.archetypeRow] ?? -1;
 }
 function spawnCore(world, componentDatas, internal) {
+  componentDatas = expandComponentRequirements(componentDatas);
   const filledData = [];
   for (const cd of componentDatas) {
     const preflight = world[worldInternal].preflightComponentData(null, cd);
@@ -5845,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)
@@ -5880,12 +6571,22 @@ 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();
+  world[worldInternal].recordStructuralEvidence({
+    kind: "spawn",
+    entity: spawnedEntity
+  });
   return ok(spawnedEntity);
 }
 function despawnCore(world, entity, internal) {
@@ -5936,8 +6637,11 @@ function despawnCore(world, entity, internal) {
       }
     }
   }
+  world[worldInternal].recordStructuralEvidence({
+    kind: "despawn",
+    entity
+  });
   if (record) {
-    world[worldInternal].removeEntityChanges(entity);
     record.archetypeId = -1;
     record.archetypeRow = -1;
     record.generation += 1;
@@ -5949,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);
@@ -5978,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));
   }
@@ -6029,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)
@@ -6062,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 {
@@ -6586,9 +7293,6 @@ var World = class {
   get componentMutationEpochs() {
     return this.core.componentMutationEpochs;
   }
-  get changeJournal() {
-    return this.core.changeJournal;
-  }
   /** Free index slots (LIFO stack). */
   get records() {
     return this.core.records;
@@ -6668,8 +7372,8 @@ var World = class {
       markComponentAdded: (entity, component) => this.internalmarkComponentAdded(entity, component),
       markComponentsAdded: (entity, components) => this.internalmarkComponentsAdded(entity, components),
       markComponentChanged: (entity, component) => this.internalmarkComponentChanged(entity, component),
-      removeComponentChange: (entity, component) => this.internalremoveComponentChange(entity, component),
       markStructureChanged: () => this.internalmarkStructureChanged(),
+      recordStructuralEvidence: (evidence) => this.internalrecordStructuralEvidence(evidence),
       routeError: (error, context) => this.internalrouteError(error, context)
     });
     this.clock = createWorldClock({ ...DEFAULT_TIME_POLICY, ...options.time });
@@ -6690,11 +7394,14 @@ 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),
-      getChangeCursor: this.internalgetChangeCursor.bind(this),
       getClockWriter: this.internalgetClockWriter.bind(this),
       getComponentChange: this.internalgetComponentChange.bind(this),
       getComponentMutationEpoch: this.internalgetComponentMutationEpoch.bind(this),
+      getComponentMutationEpochs: this.internalgetComponentMutationEpochs.bind(this),
       getEntityArchetype: this.internalgetEntityArchetype.bind(this),
       getFixedAccumulator: this.internalgetFixedAccumulator.bind(this),
       getFreeIndices: this.internalgetFreeIndices.bind(this),
@@ -6709,28 +7416,30 @@ var World = class {
       getSchedules: this.internalgetSchedules.bind(this),
       getSharedRefs: this.internalgetSharedRefs.bind(this),
       getStructureEpoch: this.internalgetStructureEpoch.bind(this),
+      getStructuralEvidence: this.internalgetStructuralEvidence.bind(this),
       getUniqueRefs: this.internalgetUniqueRefs.bind(this),
       lookupAlive: this.internallookupAlive.bind(this),
       markComponentAdded: this.internalmarkComponentAdded.bind(this),
       markComponentChanged: this.internalmarkComponentChanged.bind(this),
       markComponentRangeChanged: this.internalmarkComponentRangeChanged.bind(this),
       markComponentsAdded: this.internalmarkComponentsAdded.bind(this),
-      markDerivedComponentChanges: this.internalmarkDerivedComponentChanges.bind(this),
       markStructureChanged: this.internalmarkStructureChanged.bind(this),
       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),
-      readChangesSince: this.internalreadChangesSince.bind(this),
       readRow: this.internalreadRow.bind(this),
+      recordStructuralEvidence: this.internalrecordStructuralEvidence.bind(this),
       recordIsLive: this.internalrecordIsLive.bind(this),
       relationshipOnInsert: this.internalrelationshipOnInsert.bind(this),
       relationshipOnRemove: this.internalrelationshipOnRemove.bind(this),
       releaseManagedRefsOnRow: this.internalreleaseManagedRefsOnRow.bind(this),
-      removeComponentChange: this.internalremoveComponentChange.bind(this),
+      releaseRelationshipPreparation: this.internalreleaseRelationshipPreparation.bind(this),
       removeComponentCore: this.internalremoveComponentCore.bind(this),
-      removeEntityChanges: this.internalremoveEntityChanges.bind(this),
       routeError: this.internalrouteError.bind(this),
+      restoreMutationEpoch: this.internalrestoreMutationEpoch.bind(this),
       setFixedAccumulator: this.internalsetFixedAccumulator.bind(this),
       setQueryRow: this.internalsetQueryRow.bind(this),
       spawnCore: this.internalspawnCore.bind(this),
@@ -6776,18 +7485,17 @@ var World = class {
   internalgetMutationEpoch() {
     return this.mutationEpoch;
   }
-  /** Current cursor for a persistent projection subscriber. */
-  internalgetChangeCursor() {
-    return this.changeJournal.cursor();
-  }
-  /** Read complete mutation evidence or an explicit rebuild signal. */
-  internalreadChangesSince(cursor) {
-    return this.changeJournal.readAfter(cursor);
-  }
   /** Structure snapshot used to invalidate borrowed query facades. */
   internalgetStructureEpoch() {
     return this.structureEpoch;
   }
+  /** Typed structural facts are produced by this World and consumed by projections. */
+  internalgetStructuralEvidence() {
+    return this.core.structuralEvidence;
+  }
+  internalrecordStructuralEvidence(evidence) {
+    this.core.structuralEvidence.append(evidence);
+  }
   /** Resolve current logical identity for a packed entity handle. */
   internalgetEntityArchetype(entity) {
     const record = this.records[entityIndex(entity)];
@@ -6808,6 +7516,17 @@ var World = class {
     this.mutationEpoch += 1;
     return this.mutationEpoch;
   }
+  internalrestoreMutationEpoch(epoch) {
+    this.mutationEpoch = epoch;
+  }
+  internalpublishDerivedRange(table, componentId2, rowStart, rowCount, epoch) {
+    const epochs = table.storage.get(componentId2)?.epochs;
+    if (epochs === void 0) {
+      throw new Error(`Derived component ${componentId2} is not in the table.`);
+    }
+    epochs.changed.fill(epoch, rowStart, rowStart + rowCount);
+    this.componentMutationEpochs[componentId2] = epoch;
+  }
   /** Record one successful structural mutation. */
   internalmarkStructureChanged() {
     this.structureEpoch += 1;
@@ -6828,7 +7547,6 @@ var World = class {
     markComponentsAdded(this.graph, record, entity, componentIds, epoch);
     for (const componentId2 of componentIds) {
       this.componentMutationEpochs[componentId2] = epoch;
-      this.changeJournal.append({ kind: "component-added", entity, componentId: componentId2 });
     }
   }
   /** Mark an existing component as changed at the current tick. */
@@ -6842,7 +7560,6 @@ var World = class {
     });
     if (epoch !== void 0) {
       this.componentMutationEpochs[componentId2] = epoch;
-      this.changeJournal.append({ kind: "component-changed", entity, componentId: componentId2 });
     }
   }
   /** Mark one contiguous component range with a single epoch. */
@@ -6852,18 +7569,15 @@ var World = class {
     const epoch = this.internalnextMutationEpoch();
     epochs.changed.fill(epoch, rowStart, rowStart + rowCount);
     this.componentMutationEpochs[componentId2] = epoch;
-    for (const entity of readTableEntityRange(table, rowStart, rowCount)) {
-      this.changeJournal.append({
-        kind: "component-changed",
-        entity,
-        componentId: componentId2
-      });
-    }
   }
   /** Latest mutation token for one component-owned projection. */
   internalgetComponentMutationEpoch(componentId2) {
     return this.componentMutationEpochs[componentId2] ?? 0;
   }
+  /** Borrow the component-version summary used to skip unrelated value columns. */
+  internalgetComponentMutationEpochs() {
+    return this.componentMutationEpochs;
+  }
   /** Read a materialized relationship target in O(1 + k). */
   internalgetRelationshipTargetEntities(source, target) {
     return this.componentAccess.relationshipTargetEntries(source, target);
@@ -6872,28 +7586,19 @@ var World = class {
   internalgetRelationshipEpoch(source) {
     return this.core.relationshipIndexes.get(componentId(source))?.epoch ?? 0;
   }
-  /** Publish changes to a value derived without an authored mutation epoch. */
-  internalmarkDerivedComponentChanges(componentId2, entities) {
-    for (const entity of entities) {
-      this.changeJournal.append({ kind: "derived-component-changed", entity, componentId: componentId2 });
-    }
-  }
   /** 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) {
     return this.componentAccess.get(entity, component);
   }
-  /** Remove one component's change state after archetype removal. */
-  internalremoveComponentChange(entity, componentId2) {
-    this.changeJournal.append({ kind: "component-removed", entity, componentId: componentId2 });
-  }
-  /** Remove all change state before an entity handle is retired. */
-  internalremoveEntityChanges(entity) {
-    this.changeJournal.append({ kind: "entity-removed", entity });
-  }
   /** Return resource change ticks for diagnostics and resource-driven systems. */
   getResourceChange(name) {
     const entry = this.resources.entries.get(name);
@@ -6910,8 +7615,8 @@ var World = class {
    *
    * Not part of the public API.
    */
-  internalrouteError(err11, ctx) {
-    console.error(`[${ctx?.systemName ?? "World"}]`, err11);
+  internalrouteError(err12, ctx) {
+    console.error(`[${ctx?.systemName ?? "World"}]`, err12);
   }
   // ──────────────────────────────────────────────────────────────────────────
   // accessors — M1 extraction seam
@@ -7236,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);
@@ -7304,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) {