@forgeax/engine-ecs 0.1.21 → 0.1.24

package/src/projection/index.ts

@@ -3,7 +3,7 @@ import type { Component } from '../component';
 import { componentId } from '../component';
 import type { EntityHandle } from '../entity-handle';
 import type { SharedRefMutationRead } from '../shared-ref-store';
-import type { WorldChangeRead } from '../storage/change-detection';
+import type { StructuralEvidenceRead } from '../storage/structural-evidence';
 import type { EcsError, World } from '../world';
 import { worldInternal } from '../world-internal';
 
@@ -24,41 +24,9 @@ export {
   StaleEntityError,
 } from '../errors';
 
-export type ProjectionChangeKind =
-  | 'component-added'
-  | 'component-changed'
-  | 'component-removed'
-  | 'derived-component-changed'
-  | 'entity-removed';
-
-export interface ProjectionChange {
-  readonly entity: EntityHandle;
-  readonly kind: ProjectionChangeKind;
-  /** Token identity is the owner-facing component discriminator. */
-  readonly component?: Component;
-  /** Numeric id remains journal evidence for ECS-internal consumers. */
-  readonly componentId?: number;
-}
-
-export type ProjectionRead =
-  | {
-      readonly status: 'delta';
-      readonly cursor: number;
-      readonly changes: readonly ProjectionChange[];
-    }
-  | {
-      readonly status: 'rebuild';
-      readonly cursor: number;
-      readonly reason: 'journal-overflow';
-    };
-
-export interface WorldProjection {
-  readonly cursor: number;
-  poll(): ProjectionRead;
-}
-
-export interface WorldProjectionOptions {
-  readonly components?: readonly Component[];
+/** Read producer-owned typed structural facts without inferring from a World scan. */
+export function readStructuralEvidence(world: World, cursor: number): StructuralEvidenceRead {
+  return world[worldInternal].getStructuralEvidence().readAfter(cursor) as StructuralEvidenceRead;
 }
 
 export interface RenderProjectionComponentRequest {
@@ -83,28 +51,34 @@ export interface RenderProjectionSpans {
 
 export interface RenderChangeBatchOk {
   readonly status: 'ok';
-  readonly cursor: number;
-  readonly world: Extract<WorldChangeRead, { readonly status: 'ok' }>;
-  readonly sharedRefs: Extract<SharedRefMutationRead, { readonly status: 'ok' }>;
+  readonly version: RenderReadVersion;
+  readonly world: RenderWorldChanges;
+  readonly sharedRefs: SharedRefMutationRead;
 }
 
-export interface RenderChangeBatchOverflow {
-  readonly status: 'overflow';
-  readonly cursor: number;
+export interface RenderChangeBatchRebuild {
+  readonly status: 'rebuild';
+  readonly version: RenderReadVersion;
   readonly resync: true;
-  readonly oldestAvailable: number;
-  readonly world: WorldChangeRead;
+  readonly reason: 'structure-changed';
+  readonly world: RenderWorldChanges;
   readonly sharedRefs: SharedRefMutationRead;
 }
 
-export type RenderChangeBatch = RenderChangeBatchOk | RenderChangeBatchOverflow;
+export interface RenderWorldChanges {
+  readonly fromEpoch: number;
+  readonly toEpoch: number;
+  readonly changedComponentIds: readonly number[];
+}
+
+export type RenderChangeBatch = RenderChangeBatchOk | RenderChangeBatchRebuild;
 
 export interface RenderReadLease {
   readonly worldIdentity: string;
   readonly generation: number;
-  readChanges(cursor: number): RenderChangeBatch;
+  readChanges(version: RenderReadVersion): RenderChangeBatch;
   querySpans(request: RenderProjectionRequest): RenderProjectionSpans;
-  inspectCursor(): number;
+  captureVersion(): RenderReadVersion;
   dispose(): void;
 }
 
@@ -124,9 +98,10 @@ export function readRenderArrayView(
     | undefined;
 }
 
-interface ProjectionCursor {
-  readonly world: number;
-  readonly sharedRefs: number;
+export interface RenderReadVersion {
+  readonly mutationEpoch: number;
+  readonly structureEpoch: number;
+  readonly sharedRefEpoch: number;
 }
 
 function readProjectionSpans(
@@ -167,80 +142,78 @@ function readProjectionSpans(
 export function createRenderReadLease(world: World, token: object = {}): RenderReadLease {
   void token;
   const sharedRefs = world[worldInternal].getSharedRefs();
-  const generation = Math.max(1, world[worldInternal].getStructureEpoch());
   let disposed = false;
-  let nextCursor = 1;
-  const cursors = new Map<number, ProjectionCursor>([
-    [
-      0,
-      { world: world[worldInternal].getChangeCursor(), sharedRefs: sharedRefs.getMutationEpoch() },
-    ],
-  ]);
 
   const assertLive = (): void => {
     if (disposed) throw new Error('RenderReadLease is disposed.');
   };
 
-  const captureCursor = (): number => {
-    const cursor = nextCursor++;
-    cursors.set(cursor, {
-      world: world[worldInternal].getChangeCursor(),
-      sharedRefs: sharedRefs.getMutationEpoch(),
-    });
-    if (cursors.size > 8) {
-      const oldest = cursors.keys().next().value;
-      if (typeof oldest === 'number' && oldest !== cursor) cursors.delete(oldest);
-    }
-    return cursor;
+  const captureVersion = (): RenderReadVersion => {
+    return {
+      mutationEpoch: world[worldInternal].getMutationEpoch(),
+      structureEpoch: world[worldInternal].getStructureEpoch(),
+      sharedRefEpoch: sharedRefs.getMutationEpoch(),
+    };
   };
 
   return {
     worldIdentity: world.identity,
-    generation,
-    inspectCursor(): number {
+    get generation(): number {
+      return Math.max(1, world[worldInternal].getStructureEpoch());
+    },
+    captureVersion(): RenderReadVersion {
       assertLive();
-      return captureCursor();
+      return captureVersion();
     },
-    readChanges(cursor: number): RenderChangeBatch {
+    readChanges(start: RenderReadVersion): RenderChangeBatch {
       assertLive();
-      const start = cursors.get(cursor);
-      if (start === undefined) throw new RangeError(`Unknown RenderReadLease cursor ${cursor}.`);
-      const worldRead = world[worldInternal].readChangesSince(start.world) as WorldChangeRead;
-      const sharedRead = sharedRefs.readChangesSince(start.sharedRefs);
-      const next = captureCursor();
-      if (worldRead.status === 'overflow' || sharedRead.status === 'overflow') {
-        const oldestAvailable = Math.min(
-          worldRead.status === 'overflow' ? worldRead.oldestAvailable : Number.MAX_SAFE_INTEGER,
-          sharedRead.status === 'overflow' ? sharedRead.oldestAvailable : Number.MAX_SAFE_INTEGER,
-        );
+      const toEpoch = world[worldInternal].getMutationEpoch() as number;
+      const componentEpochs = world[
+        worldInternal
+      ].getComponentMutationEpochs() as readonly number[];
+      const changedComponentIds: number[] = [];
+      for (let componentId = 0; componentId < componentEpochs.length; componentId += 1) {
+        const epoch = componentEpochs[componentId] ?? 0;
+        if (epoch > start.mutationEpoch && epoch <= toEpoch) changedComponentIds.push(componentId);
+      }
+      const worldRead: RenderWorldChanges = {
+        fromEpoch: start.mutationEpoch,
+        toEpoch,
+        changedComponentIds,
+      };
+      const sharedRead = sharedRefs.readChangesSince(start.sharedRefEpoch);
+      const version = captureVersion();
+      const structureChanged = start.structureEpoch !== world[worldInternal].getStructureEpoch();
+      if (structureChanged) {
         return {
-          status: 'overflow',
-          cursor: next,
+          status: 'rebuild',
+          version,
           resync: true,
-          oldestAvailable,
+          reason: 'structure-changed',
           world: worldRead,
           sharedRefs: sharedRead,
         };
       }
-      return { status: 'ok', cursor: next, world: worldRead, sharedRefs: sharedRead };
+      return { status: 'ok', version, world: worldRead, sharedRefs: sharedRead };
     },
     querySpans(request: RenderProjectionRequest): RenderProjectionSpans {
       assertLive();
-      return readProjectionSpans(world, generation, request);
+      return readProjectionSpans(
+        world,
+        Math.max(1, world[worldInternal].getStructureEpoch()),
+        request,
+      );
     },
     dispose(): void {
       disposed = true;
-      cursors.clear();
     },
   };
 }
 
 /**
- * Publish one owner-derived component value without confusing it with an
- * authored mutation. Owner packages use this narrow seam for fields such as
- * `Transform.world`: the write still passes through ECS validation and managed
- * storage, while the journal records a `derived-component-changed` fact for
- * incremental projections.
+ * Publish one owner-derived component value through the component's ordinary
+ * version. Numeric consumers observe the same row epoch regardless of which
+ * owner computed the value; there is no parallel derived-change vocabulary.
  */
 export function setDerivedComponent(
   world: World,
@@ -250,7 +223,7 @@ export function setDerivedComponent(
 ): Result<void, EcsError> {
   const result = world[worldInternal].setQueryRow(entity, component, value);
   if (!result.ok) return result;
-  world[worldInternal].markDerivedComponentChanges(componentId(component), [entity]);
+  world[worldInternal].markComponentChanged(entity, componentId(component));
   return result;
 }
 
@@ -262,57 +235,3 @@ export function routeWorldError(
 ): void {
   world[worldInternal].routeError(error, context);
 }
-
-/**
- * Create the narrow incremental evidence surface for an owner projection.
- * Rebuilds intentionally return a reason; complete data always comes from
- * the owner's regular Query/QuerySpan path.
- */
-export function createWorldProjection(
-  world: World,
-  options: WorldProjectionOptions = {},
-): WorldProjection {
-  const componentById =
-    options.components === undefined
-      ? undefined
-      : new Map(options.components.map((component) => [componentId(component), component]));
-  const componentIds = componentById === undefined ? undefined : new Set(componentById.keys());
-  let cursor = world[worldInternal].getChangeCursor();
-
-  const pollSince = (requestedCursor: number): ProjectionRead => {
-    const result = world[worldInternal].readChangesSince(requestedCursor);
-    if (result.status === 'overflow') {
-      cursor = result.cursor;
-      return { status: 'rebuild', cursor, reason: 'journal-overflow' };
-    }
-    cursor = result.cursor;
-    const changes: ProjectionChange[] = [];
-    for (const record of result.records) {
-      if (
-        componentIds !== undefined &&
-        record.kind !== 'entity-removed' &&
-        (record.componentId === undefined || !componentIds.has(record.componentId))
-      ) {
-        continue;
-      }
-      const component =
-        record.componentId === undefined ? undefined : componentById?.get(record.componentId);
-      changes.push({
-        entity: record.entity,
-        kind: record.kind,
-        ...(component === undefined ? {} : { component }),
-        ...(record.componentId === undefined ? {} : { componentId: record.componentId }),
-      });
-    }
-    return { status: 'delta', cursor, changes };
-  };
-
-  return {
-    get cursor(): number {
-      return cursor;
-    },
-    poll(): ProjectionRead {
-      return pollSince(cursor);
-    },
-  };
-}