@forgeax/engine-ecs 0.1.20 → 0.1.23

package/src/storage/structural-evidence.ts

@@ -0,0 +1,64 @@
+import type { EntityHandle } from '../entity-handle';
+
+export type StructuralEvidenceKind = 'spawn' | 'despawn' | 'component-added' | 'component-removed';
+
+export interface StructuralEvidenceInput {
+  readonly kind: StructuralEvidenceKind;
+  readonly entity: EntityHandle;
+  readonly componentId?: number;
+}
+
+export interface StructuralEvidence extends StructuralEvidenceInput {
+  readonly sequence: number;
+}
+
+export type StructuralEvidenceRead =
+  | {
+      readonly status: 'ok';
+      readonly cursor: number;
+      readonly events: readonly StructuralEvidence[];
+    }
+  | { readonly status: 'overflow'; readonly cursor: number; readonly oldestAvailable: number };
+
+/** Bounded producer-owned structural evidence; consumers never infer facts by scanning. */
+export class StructuralEvidenceRing {
+  private readonly events: Array<StructuralEvidence | undefined>;
+  private nextSequence = 1;
+
+  constructor(readonly capacity = 1024) {
+    if (!Number.isSafeInteger(capacity) || capacity <= 0) {
+      throw new RangeError('StructuralEvidenceRing capacity must be a positive safe integer');
+    }
+    this.events = new Array<StructuralEvidence | undefined>(capacity);
+  }
+
+  get cursor(): number {
+    return this.nextSequence - 1;
+  }
+
+  append(input: StructuralEvidenceInput): number {
+    const sequence = this.nextSequence;
+    this.nextSequence += 1;
+    this.events[(sequence - 1) % this.capacity] = { ...input, sequence };
+    return sequence;
+  }
+
+  readAfter(cursor: number): StructuralEvidenceRead {
+    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: StructuralEvidence[] = [];
+    for (let sequence = cursor + 1; sequence <= latest; sequence += 1) {
+      const event = this.events[(sequence - 1) % this.capacity];
+      if (event === undefined || event.sequence !== sequence) {
+        return { status: 'overflow', cursor: latest, oldestAvailable };
+      }
+      events.push(event);
+    }
+    return { status: 'ok', cursor: latest, events };
+  }
+}

package/src/world-component-access.ts

@@ -22,7 +22,7 @@ import {
   TYPE_METADATA,
 } from './component';
 import { fillComponentDefaults, validateComponentDataKeys } from './component-default-fallback';
-import { componentDefinition } from './component-schema';
+import { componentDefinition, expandComponentRequirements } from './component-schema';
 import { validateManagedArrayValues, validateSharedFieldValues } from './component-value-validate';
 import { Entity as EntityComponent } from './entity';
 import {
@@ -63,6 +63,7 @@ import {
 } from './storage/archetype-graph';
 import { removeSparseTag } from './storage/change-detection';
 import { arrayCountColumnName, type FieldView, normalizeBufferWrite } from './storage/column';
+import type { StructuralEvidenceInput } from './storage/structural-evidence';
 import { appendTableRow, type Table } from './storage/table';
 import type { UniqueRefStore } from './unique-ref-store';
 import type { ComponentData, EcsError, EntityRecord } from './world';
@@ -106,8 +107,8 @@ export interface ComponentAccessState {
   readonly markComponentAdded: (entity: EntityHandle, componentId: number) => void;
   readonly markComponentsAdded: (entity: EntityHandle, componentIds: readonly number[]) => void;
   readonly markComponentChanged: (entity: EntityHandle, componentId: number) => void;
-  readonly removeComponentChange: (entity: EntityHandle, componentId: number) => void;
   readonly markStructureChanged: () => void;
+  readonly recordStructuralEvidence: (evidence: StructuralEvidenceInput) => void;
   routeError(err: unknown, ctx: ErrorContext): void;
 }
 
@@ -568,7 +569,7 @@ export class WorldComponentAccess {
    * 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(
@@ -1011,12 +1012,13 @@ export class WorldComponentAccess {
     entity: EntityHandle,
     componentData: ComponentData<S>,
     internal: boolean,
+    resolveRequirements = true,
   ): Result<void, EcsError> {
     const record = this.lookupAlive(entity, 'addComponent', componentData.component.name);
     if (!record.ok) return record;
 
     const rec = record.value;
-    const srcArch = this.graph.archetypes[rec.archetypeId];
+    let srcArch = this.graph.archetypes[rec.archetypeId];
     /* istanbul ignore next -- defensive: alive record always has valid archetypeId */
     if (!srcArch) {
       return err(
@@ -1066,6 +1068,38 @@ export class WorldComponentAccess {
       return err(enumErr as unknown as EcsError);
     }
 
+    // Generic component requirements are resolved once at the structural
+    // boundary. Explicit data remains authoritative; only missing required
+    // identities are added before the requested component is migrated.
+    if (resolveRequirements) {
+      const required = expandComponentRequirements([componentData]).slice(1);
+      for (const requirement of required) {
+        if (
+          srcArch.components.some(
+            (candidate) => componentId(candidate) === componentId(requirement.component),
+          )
+        ) {
+          continue;
+        }
+        // The closure is expanded once above. Bypass requirement expansion for
+        // each member so malformed dependency cycles remain finite and the
+        // structural work still happens in one deterministic sequence.
+        const added = this._addComponentCore(entity, requirement as ComponentData, internal, false);
+        if (!added.ok) return added;
+        srcArch = this.graph.archetypes[rec.archetypeId];
+        if (!srcArch) {
+          return err(
+            new StaleEntityError(entity as number, entityIndex(entity), entityGeneration(entity), {
+              operation: 'addComponent',
+              component: componentData.component.name,
+              expectedGeneration: rec.generation,
+              actualGeneration: rec.generation,
+            }),
+          );
+        }
+      }
+    }
+
     // Check if entity already has this component (using World-local ID).
     const localId = componentId(componentData.component);
     if (srcArch.components.some((candidate) => componentId(candidate) === localId)) {
@@ -1144,6 +1178,11 @@ export class WorldComponentAccess {
     }
 
     this.markStructureChanged();
+    this.state.recordStructuralEvidence({
+      kind: 'component-added',
+      entity,
+      componentId: localId,
+    });
     return ok(undefined);
   }
 
@@ -1249,8 +1288,12 @@ export class WorldComponentAccess {
     } else {
       this.storage.migrateEntity(rec, srcArch, targetArch);
     }
-    this.state.removeComponentChange(entity, componentId(component));
     this.markStructureChanged();
+    this.state.recordStructuralEvidence({
+      kind: 'component-removed',
+      entity,
+      componentId: localId,
+    });
     return ok(undefined);
   }
 
@@ -1292,6 +1335,7 @@ export class WorldComponentAccess {
     entity: EntityHandle,
     componentDatas: ComponentData[],
   ): Result<void, EcsError> {
+    componentDatas = expandComponentRequirements(componentDatas);
     const slot = entityIndex(entity);
     const record = this.records[slot];
     if (!record || record.archetypeId !== -1) return ok(undefined);
@@ -1341,6 +1385,10 @@ export class WorldComponentAccess {
       }
     }
     this.markStructureChanged();
+    this.state.recordStructuralEvidence({
+      kind: 'spawn',
+      entity,
+    });
     return ok(undefined);
   }
 

package/src/world-core.ts

@@ -4,7 +4,7 @@ import type { RelationshipIndex } from './relationship-index';
 import type { SharedRefStore } from './shared-ref-store';
 import { SharedRefStore as SharedRefStoreImpl } from './shared-ref-store';
 import { type ArchetypeGraph, createArchetypeGraph } from './storage/archetype-graph';
-import { WorldChangeJournal } from './storage/change-detection';
+import { StructuralEvidenceRing } from './storage/structural-evidence';
 import type { UniqueRefStore } from './unique-ref-store';
 import { UniqueRefStore as UniqueRefStoreImpl } from './unique-ref-store';
 import type { EntityRecord } from './world';
@@ -43,7 +43,7 @@ export class WorldCore {
   readonly sharedRefs: SharedRefStore = new SharedRefStoreImpl();
   readonly storage: WorldStorageCore;
   readonly componentMutationEpochs: number[] = [];
-  readonly changeJournal = new WorldChangeJournal();
+  readonly structuralEvidence = new StructuralEvidenceRing();
   /** One packed reverse index per relationship source component. */
   readonly relationshipIndexes = new Map<number, RelationshipIndex>();
   mutationEpoch = 0;

package/src/world-entity-lifecycle.ts

@@ -8,6 +8,7 @@ import { err, isRetiredSlot, ok, pack, type Result } from '@forgeax/engine-types
 import type { Component, ComponentSchema, InputShapeOf, ShapeOf } from './component';
 import { componentId, componentSchema } from './component';
 import { fillComponentDefaults, validateComponentDataKeys } from './component-default-fallback';
+import { expandComponentRequirements } from './component-schema';
 import { validateManagedArrayValues, validateSharedFieldValues } from './component-value-validate';
 import { Entity } from './entity';
 import {
@@ -48,6 +49,7 @@ export function spawnCore(
   componentDatas: { component: Component; data: Partial<Record<string, unknown>> }[],
   internal: boolean,
 ): Result<EntityHandle, EcsError> {
+  componentDatas = expandComponentRequirements(componentDatas);
   const filledData: Record<string, unknown>[] = [];
   for (const cd of componentDatas) {
     const preflight = world[worldInternal].preflightComponentData(null, cd);
@@ -104,6 +106,10 @@ export function spawnCore(
     }
   }
   world[worldInternal].markStructureChanged();
+  world[worldInternal].recordStructuralEvidence({
+    kind: 'spawn',
+    entity: spawnedEntity,
+  });
   return ok(spawnedEntity);
 }
 
@@ -169,8 +175,11 @@ export function despawnCore(
       }
     }
   }
+  world[worldInternal].recordStructuralEvidence({
+    kind: 'despawn',
+    entity,
+  });
   if (record) {
-    world[worldInternal].removeEntityChanges(entity);
     record.archetypeId = -1;
     record.archetypeRow = -1;
     record.generation += 1;

package/src/world-internal.ts

@@ -23,10 +23,10 @@ type InternalName =
   | 'despawnCore'
   | 'getArrayView'
   | 'getBufferPool'
-  | 'getChangeCursor'
   | 'getClockWriter'
   | 'getComponentChange'
   | 'getComponentMutationEpoch'
+  | 'getComponentMutationEpochs'
   | 'getEntityArchetype'
   | 'getFixedAccumulator'
   | 'getFreeIndices'
@@ -41,28 +41,28 @@ type InternalName =
   | 'getSchedules'
   | 'getSharedRefs'
   | 'getStructureEpoch'
+  | 'getStructuralEvidence'
   | 'getUniqueRefs'
   | 'lookupAlive'
   | 'markComponentAdded'
   | 'markComponentChanged'
   | 'markComponentRangeChanged'
   | 'markComponentsAdded'
-  | 'markDerivedComponentChanges'
   | 'markStructureChanged'
   | 'materializePendingEntity'
   | 'nextMutationEpoch'
   | 'poisonExecution'
+  | 'publishDerivedRange'
   | 'preflightComponentData'
-  | 'readChangesSince'
   | 'readRow'
+  | 'recordStructuralEvidence'
   | 'recordIsLive'
   | 'relationshipOnInsert'
   | 'relationshipOnRemove'
   | 'releaseManagedRefsOnRow'
-  | 'removeComponentChange'
   | 'removeComponentCore'
-  | 'removeEntityChanges'
   | 'routeError'
+  | 'restoreMutationEpoch'
   | 'setFixedAccumulator'
   | 'setQueryRow'
   | 'spawnCore'

package/src/world.ts

@@ -28,6 +28,7 @@ import type {
   ComponentNotDefinedError,
   ComponentNotPresentError,
   ComponentNumericValueInvalidError,
+  DerivedRangeOutOfBoundsError,
   FixedSizeMismatchError,
   ManagedArrayInvalidValueError,
   ManagedBufferOutOfBoundsError,
@@ -71,9 +72,11 @@ import {
   markComponentChanged,
   markComponentsAdded,
   readComponentChange,
-  readTableEntityRange,
-  type WorldChangeRead,
 } from './storage/change-detection';
+import type {
+  StructuralEvidenceInput,
+  StructuralEvidenceRing,
+} from './storage/structural-evidence';
 import {
   type ClockWriter,
   createWorldClock,
@@ -144,6 +147,8 @@ export type EcsError =
   | ScheduleScopeMismatchError
   | SharedKernelEligibilityError
   | SharedKernelFailureError
+  | DerivedRangeOutOfBoundsError
+  | ChangeEpochExhaustedError
   | WorldPoisonedError;
 
 /** Component data for spawn/addComponent: component token + initial values.
@@ -324,9 +329,6 @@ export class World {
   private get componentMutationEpochs() {
     return this.core.componentMutationEpochs;
   }
-  private get changeJournal() {
-    return this.core.changeJournal;
-  }
   /** Free index slots (LIFO stack). */
   private get records() {
     return this.core.records;
@@ -409,9 +411,8 @@ export class World {
         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 as EcsError, context),
     });
     this.clock = createWorldClock({ ...DEFAULT_TIME_POLICY, ...options.time });
@@ -433,10 +434,10 @@ export class World {
       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),
@@ -451,28 +452,28 @@ export class World {
       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),
@@ -536,19 +537,18 @@ export class World {
     return this.mutationEpoch;
   }
 
-  /** Current cursor for a persistent projection subscriber. */
-  private internalgetChangeCursor(): number {
-    return this.changeJournal.cursor();
+  /** Structure snapshot used to invalidate borrowed query facades. */
+  private internalgetStructureEpoch(): number {
+    return this.structureEpoch;
   }
 
-  /** Read complete mutation evidence or an explicit rebuild signal. */
-  private internalreadChangesSince(cursor: number): WorldChangeRead {
-    return this.changeJournal.readAfter(cursor);
+  /** Typed structural facts are produced by this World and consumed by projections. */
+  private internalgetStructuralEvidence(): StructuralEvidenceRing {
+    return this.core.structuralEvidence;
   }
 
-  /** Structure snapshot used to invalidate borrowed query facades. */
-  private internalgetStructureEpoch(): number {
-    return this.structureEpoch;
+  private internalrecordStructuralEvidence(evidence: StructuralEvidenceInput): void {
+    this.core.structuralEvidence.append(evidence);
   }
 
   /** Resolve current logical identity for a packed entity handle. */
@@ -577,6 +577,25 @@ export class World {
     return this.mutationEpoch;
   }
 
+  private internalrestoreMutationEpoch(epoch: number): void {
+    this.mutationEpoch = epoch;
+  }
+
+  private internalpublishDerivedRange(
+    table: ArchetypeGraph['tables'][number],
+    componentId: number,
+    rowStart: number,
+    rowCount: number,
+    epoch: number,
+  ): void {
+    const epochs = table.storage.get(componentId)?.epochs;
+    if (epochs === undefined) {
+      throw new Error(`Derived component ${componentId} is not in the table.`);
+    }
+    epochs.changed.fill(epoch, rowStart, rowStart + rowCount);
+    this.componentMutationEpochs[componentId] = epoch;
+  }
+
   /** Record one successful structural mutation. */
   private internalmarkStructureChanged(): void {
     this.structureEpoch += 1;
@@ -600,7 +619,6 @@ export class World {
     markComponentsAdded(this.graph, record, entity, componentIds, epoch);
     for (const componentId of componentIds) {
       this.componentMutationEpochs[componentId] = epoch;
-      this.changeJournal.append({ kind: 'component-added', entity, componentId });
     }
   }
 
@@ -615,7 +633,6 @@ export class World {
     });
     if (epoch !== undefined) {
       this.componentMutationEpochs[componentId] = epoch;
-      this.changeJournal.append({ kind: 'component-changed', entity, componentId });
     }
   }
 
@@ -631,13 +648,6 @@ export class World {
     const epoch = this.internalnextMutationEpoch();
     epochs.changed.fill(epoch, rowStart, rowStart + rowCount);
     this.componentMutationEpochs[componentId] = epoch;
-    for (const entity of readTableEntityRange(table, rowStart, rowCount)) {
-      this.changeJournal.append({
-        kind: 'component-changed',
-        entity,
-        componentId,
-      });
-    }
   }
 
   /** Latest mutation token for one component-owned projection. */
@@ -645,6 +655,11 @@ export class World {
     return this.componentMutationEpochs[componentId] ?? 0;
   }
 
+  /** Borrow the component-version summary used to skip unrelated value columns. */
+  private internalgetComponentMutationEpochs(): readonly number[] {
+    return this.componentMutationEpochs;
+  }
+
   /** Read a materialized relationship target in O(1 + k). */
   private internalgetRelationshipTargetEntities(
     source: Component,
@@ -658,16 +673,6 @@ export class World {
     return this.core.relationshipIndexes.get(componentId(source))?.epoch ?? 0;
   }
 
-  /** Publish changes to a value derived without an authored mutation epoch. */
-  private internalmarkDerivedComponentChanges(
-    componentId: number,
-    entities: Iterable<EntityHandle>,
-  ): void {
-    for (const entity of entities) {
-      this.changeJournal.append({ kind: 'derived-component-changed', entity, componentId });
-    }
-  }
-
   /** Query facade write after the facade has already marked evidence. */
   private internalsetQueryRow(
     entity: EntityHandle,
@@ -685,16 +690,6 @@ export class World {
     return this.componentAccess.get(entity, component) as Result<Record<string, unknown>, EcsError>;
   }
 
-  /** Remove one component's change state after archetype removal. */
-  private internalremoveComponentChange(entity: EntityHandle, componentId: number): void {
-    this.changeJournal.append({ kind: 'component-removed', entity, componentId });
-  }
-
-  /** Remove all change state before an entity handle is retired. */
-  private internalremoveEntityChanges(entity: EntityHandle): void {
-    this.changeJournal.append({ kind: 'entity-removed', entity });
-  }
-
   /** Return resource change ticks for diagnostics and resource-driven systems. */
   getResourceChange(name: string): ChangeTicks | undefined {
     const entry = this.resources.entries.get(name);