@forgeax/engine-ecs 0.1.21 → 0.1.23

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,162 @@ 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 runStartBuffers = [];
+  let runCountBuffers = [];
+  const rebind = () => {
+    const tables = source.tables();
+    const nextBindings = [];
+    const nextRunStartBuffers = [];
+    const nextRunCountBuffers = [];
+    for (const table of tables) {
+      nextBindings.push({
+        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;
+    runStartBuffers = nextRunStartBuffers;
+    runCountBuffers = nextRunCountBuffers;
+    boundEpoch = source.structureEpoch();
+  };
+  rebind();
+  const writer = {
+    get bindings() {
+      if (boundEpoch !== source.structureEpoch()) rebind();
+      return bindings;
+    },
+    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
@@ -2154,7 +2309,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;
@@ -2185,7 +2340,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 +2356,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 +2371,7 @@ var ExecutableQuery = class {
   compiled;
   matchedArchetypes = [];
   matchedTables = [];
+  matchedTableObjects = [];
   lastGraphGeneration = -1;
   lastObservedEpoch = 0;
   active = false;
@@ -2306,7 +2462,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 +2481,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 +2525,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 +2594,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 +2636,20 @@ 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";
     return void 0;
   }
 };
@@ -3394,8 +3608,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;
@@ -3762,11 +3976,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 +
@@ -4211,8 +4425,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;
@@ -4557,7 +4771,7 @@ var WorldComponentAccess = class {
    * 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
+   *   `world.get(e, GlobalTransform).world`. The accessor is the zero-materialization
    *   route the propagate kernel and render walk use.
    */
   _getArrayView(entity, component, fieldName) {
@@ -4884,11 +5098,11 @@ var WorldComponentAccess = class {
    *   (lazy mirror create or exclusive reparent).
    * @internal
    */
-  _addComponentCore(entity, componentData, internal) {
+  _addComponentCore(entity, componentData, internal, resolveRequirements = true) {
     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), {
@@ -4930,6 +5144,29 @@ var WorldComponentAccess = class {
     if (enumErr !== null) {
       return err(enumErr);
     }
+    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) return added;
+        srcArch = this.graph.archetypes[rec.archetypeId];
+        if (!srcArch) {
+          return err(
+            new StaleEntityError(entity, entityIndex(entity), entityGeneration(entity), {
+              operation: "addComponent",
+              component: componentData.component.name,
+              expectedGeneration: rec.generation,
+              actualGeneration: rec.generation
+            })
+          );
+        }
+      }
+    }
     const localId = componentId(componentData.component);
     if (srcArch.components.some((candidate) => componentId(candidate) === localId)) {
       const role = relationshipRole(componentData.component);
@@ -4985,6 +5222,11 @@ var WorldComponentAccess = class {
       if (!relationshipResult.ok) return relationshipResult;
     }
     this.markStructureChanged();
+    this.state.recordStructuralEvidence({
+      kind: "component-added",
+      entity,
+      componentId: localId
+    });
     return ok(void 0);
   }
   /**
@@ -5062,8 +5304,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,6 +5343,7 @@ 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);
@@ -5131,6 +5378,10 @@ var WorldComponentAccess = class {
       }
     }
     this.markStructureChanged();
+    this.state.recordStructuralEvidence({
+      kind: "spawn",
+      entity
+    });
     return ok(void 0);
   }
   // ──────────────────────────────────────────────────────────────────────────
@@ -5411,7 +5662,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 +5671,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 +5776,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 +5858,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 +5871,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 +5895,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 +6092,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 +6121,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);
@@ -5886,6 +6178,10 @@ function spawnCore(world, componentDatas, internal) {
     }
   }
   world[worldInternal].markStructureChanged();
+  world[worldInternal].recordStructuralEvidence({
+    kind: "spawn",
+    entity: spawnedEntity
+  });
   return ok(spawnedEntity);
 }
 function despawnCore(world, entity, internal) {
@@ -5936,8 +6232,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;
@@ -6586,9 +6885,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 +6964,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 });
@@ -6691,10 +6987,10 @@ var World = class {
       despawnCore: this.internaldespawnCore.bind(this),
       getArrayView: this.internalgetArrayView.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 +7005,28 @@ 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),
+      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),
       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 +7072,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 +7103,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 +7134,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 +7147,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 +7156,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,12 +7173,6 @@ 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);
@@ -6886,14 +7181,6 @@ var World = class {
   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 +7197,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