@forgeax/engine-ecs 0.1.21 → 0.1.24

package/src/relationship-index.ts

@@ -24,6 +24,14 @@ export interface RelationshipOptions {
   readonly sourceField: string;
   readonly targetName: string;
   readonly targetField: string;
+  /**
+   * Components materialized with the writable source side.  This is the
+   * relationship equivalent of `defineComponent(..., { requires })`: the
+   * dependency is resolved once at the structural boundary, never by a frame
+   * system.  It applies only to the source; the reverse target remains an
+   * engine-owned projection.
+   */
+  readonly sourceRequires?: readonly Component[];
   readonly exclusive?: boolean;
   readonly linkedSpawn?: boolean;
   /** Allow a source to point at its own holder (e.g. self-animated entities). */
@@ -75,7 +83,11 @@ export function defineRelationship<
   };
   const target = defineComponent(options.targetName, targetFields);
   const sourceFields: FieldsInput = { [options.sourceField]: { type: 'entity' } };
-  const source = defineComponent(options.sourceName, sourceFields);
+  const source = defineComponent(
+    options.sourceName,
+    sourceFields,
+    options.sourceRequires === undefined ? undefined : { requires: options.sourceRequires },
+  );
 
   roles.set(source, {
     kind: 'source',

package/src/shared-ref-store.ts

@@ -84,7 +84,7 @@ import {
   SharedRefStaleError,
 } from './errors';
 
-const SHARED_REF_MUTATION_JOURNAL_CAPACITY = 4096;
+const SHARED_REF_RELEASE_EVIDENCE_CAPACITY = 4096;
 
 export interface SharedRefMutation {
   readonly epoch: number;
@@ -98,17 +98,10 @@ export interface SharedRefReleaseEvidence {
   readonly evidence: 'released';
 }
 
-export type SharedRefMutationRead =
-  | {
-      readonly status: 'ok';
-      readonly cursor: number;
-      readonly records: readonly SharedRefMutation[];
-    }
-  | {
-      readonly status: 'overflow';
-      readonly cursor: number;
-      readonly oldestAvailable: number;
-    };
+export interface SharedRefMutationRead {
+  readonly cursor: number;
+  readonly records: readonly SharedRefMutation[];
+}
 
 // MAX_SLOT is now imported from @forgeax/engine-types (codec SSOT, D-1).
 // The local constant is removed to avoid drift (AC-15).
@@ -147,7 +140,8 @@ export class SharedRefStore {
   >();
   private nextSlot = BUILTIN_BASE;
   private mutationEpoch = 0;
-  private readonly mutationJournal: SharedRefMutation[] = [];
+  /** Latest published mutation epoch per live handle; not an event journal. */
+  private readonly mutationEpochs = new Map<number, number>();
   private readonly releaseJournal: SharedRefReleaseEvidence[] = [];
 
   /**
@@ -271,10 +265,7 @@ export class SharedRefStore {
       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(undefined);
   }
 
@@ -283,16 +274,16 @@ export class SharedRefStore {
     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: number): SharedRefMutationRead {
-    const oldestAvailable = this.mutationJournal[0]?.epoch ?? this.mutationEpoch + 1;
-    if (cursor < oldestAvailable - 1) {
-      return { status: 'overflow', cursor: this.mutationEpoch, oldestAvailable };
+    const records: SharedRefMutation[] = [];
+    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,
     };
   }
 
@@ -372,6 +363,7 @@ export class SharedRefStore {
     }
     this.refcounts.delete(raw);
     this.payloads.delete(raw);
+    this.mutationEpochs.delete(raw);
     // Gen increment + retire (AC-07): bump gen; once it would exceed MAX_GEN
     // (gen 255 is still usable; the bump to 256 triggers retire) the slot is
     // permanently retired — NOT pushed to freeSlots. This prevents handle
@@ -389,7 +381,7 @@ export class SharedRefStore {
       evidence: 'released' as const,
     });
     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);

package/src/storage/change-detection.ts

@@ -2,14 +2,10 @@
 
 import type { Component } from '../component';
 import * as componentOwner from '../component';
-import { Entity } from '../entity';
 import { type EntityHandle, entityIndex } from '../entity-handle';
 
-export { WorldChangeJournal, type WorldChangeRead } from '../world-change-journal';
-
 import type { ArchetypeGraph } from './archetype-graph';
 import { getOrCreateSparseTagSet } from './archetype-graph';
-import type { Table } from './table';
 
 const INITIAL_SPARSE_CAPACITY = 64;
 
@@ -218,14 +214,3 @@ export function markComponentChanged(
   const tableRow = archetype.rows[location.archetypeRow] ?? -1;
   epochs.changed[tableRow] = epoch();
 }
-
-export function readTableEntityRange(
-  table: Table,
-  rowStart: number,
-  rowCount: number,
-): readonly EntityHandle[] {
-  const entities = table.storage.get(componentOwner.componentId(Entity))?.fields.get('self')
-    ?.view as Uint32Array | undefined;
-  if (entities === undefined) return [];
-  return entities.subarray(rowStart, rowStart + rowCount) as unknown as readonly EntityHandle[];
-}

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 };
+  }
+}