@forgeax/engine-ecs 0.1.33 → 0.1.35

package/src/storage/archetype-graph.ts

@@ -29,6 +29,8 @@ export interface ArchetypeGraph {
   /** Global generation counter. Incremented on each new archetype. */
   generation: number;
   tables: Table[];
+  activeTables: Set<Table>;
+  activeTablesByComponent: Map<ComponentId, Set<Table>>;
   tableDedupByKey: Map<string, TableId>;
   tableGeneration: number;
   sparseTags: Map<ComponentId, SparseTagSet>;
@@ -44,6 +46,8 @@ export function createArchetypeGraph(shared = false): ArchetypeGraph {
     dedupByKey: new Map(),
     generation: 0,
     tables: [],
+    activeTables: new Set(),
+    activeTablesByComponent: new Map(),
     tableDedupByKey: new Map(),
     tableGeneration: 0,
     sparseTags: new Map(),
@@ -67,7 +71,17 @@ export function getOrCreateTable(
   const key = tableKey(tableComponents.map((component) => componentOwner.componentId(component)));
   const existingId = graph.tableDedupByKey.get(key);
   if (existingId !== undefined) return getTable(graph, existingId);
-  const table = createTable(tableComponents, graph.tables.length, graph.shared);
+  const directories = [graph.activeTables];
+  for (const component of tableComponents) {
+    const id = componentOwner.componentId(component);
+    let directory = graph.activeTablesByComponent.get(id);
+    if (directory === undefined) {
+      directory = new Set();
+      graph.activeTablesByComponent.set(id, directory);
+    }
+    directories.push(directory);
+  }
+  const table = createTable(tableComponents, graph.tables.length, graph.shared, directories);
   graph.tables.push(table);
   graph.tableDedupByKey.set(key, table.id);
   graph.tableGeneration += 1;

package/src/storage/change-detection.ts

@@ -7,15 +7,22 @@ import { type EntityHandle, entityIndex } from '../entity-handle';
 import type { ArchetypeGraph } from './archetype-graph';
 import { getOrCreateSparseTagSet } from './archetype-graph';
 
+export const PROJECTION_BLOCK_SIZE = 256;
+
 const INITIAL_SPARSE_CAPACITY = 64;
 
 export interface ComponentEpochColumns {
   added: Float64Array;
   changed: Float64Array;
+  blocks: Float64Array;
 }
 
 export function createComponentEpochColumns(capacity: number): ComponentEpochColumns {
-  return { added: new Float64Array(capacity), changed: new Float64Array(capacity) };
+  return {
+    added: new Float64Array(capacity),
+    changed: new Float64Array(capacity),
+    blocks: new Float64Array(Math.ceil(capacity / PROJECTION_BLOCK_SIZE)),
+  };
 }
 
 export function growComponentEpochColumns(
@@ -26,7 +33,9 @@ export function growComponentEpochColumns(
   const changed = new Float64Array(capacity);
   added.set(columns.added);
   changed.set(columns.changed);
-  return { added, changed };
+  const blocks = new Float64Array(Math.ceil(capacity / PROJECTION_BLOCK_SIZE));
+  blocks.set(columns.blocks);
+  return { added, changed, blocks };
 }
 
 export function copyComponentEpoch(
@@ -37,6 +46,8 @@ export function copyComponentEpoch(
 ): void {
   target.added[targetRow] = source.added[sourceRow] ?? 0;
   target.changed[targetRow] = source.changed[sourceRow] ?? 0;
+  const block = Math.floor(targetRow / PROJECTION_BLOCK_SIZE);
+  target.blocks[block] = Math.max(target.blocks[block] ?? 0, target.changed[targetRow] ?? 0);
 }
 
 export interface SparseTagSet {
@@ -190,7 +201,7 @@ export function markComponentsAdded(
     const epochs = table?.storage.get(componentId)?.epochs;
     if (epochs === undefined) continue;
     epochs.added[tableRow] = epoch;
-    epochs.changed[tableRow] = epoch;
+    publishComponentRange(epochs, tableRow, 1, epoch);
   }
 }
 
@@ -212,5 +223,26 @@ export function markComponentChanged(
   const epochs = graph.tables[archetype.tableId]?.storage.get(componentId)?.epochs;
   if (epochs === undefined) return;
   const tableRow = archetype.rows[location.archetypeRow] ?? -1;
-  epochs.changed[tableRow] = epoch();
+  publishComponentRange(epochs, tableRow, 1, epoch());
+}
+
+/** Row evidence and its conservative block summary share the World epoch. */
+export function publishComponentRange(
+  columns: ComponentEpochColumns,
+  start: number,
+  count: number,
+  epoch: number,
+): void {
+  if (count === 0) return;
+  if (count === 1) {
+    columns.changed[start] = epoch;
+    columns.blocks[Math.floor(start / PROJECTION_BLOCK_SIZE)] = epoch;
+    return;
+  }
+  columns.changed.fill(epoch, start, start + count);
+  columns.blocks.fill(
+    epoch,
+    Math.floor(start / PROJECTION_BLOCK_SIZE),
+    Math.ceil((start + count) / PROJECTION_BLOCK_SIZE),
+  );
 }

package/src/storage/table.ts

@@ -17,6 +17,7 @@ import {
   copyComponentEpoch,
   createComponentEpochColumns,
   growComponentEpochColumns,
+  PROJECTION_BLOCK_SIZE,
 } from './change-detection';
 import { arrayCountColumnName, type Column, createColumn, growColumn } from './column';
 
@@ -38,6 +39,8 @@ export interface Table {
   size: number;
   capacity: number;
   version: number;
+  membership: Float64Array;
+  readonly activeDirectories: readonly Set<Table>[];
 }
 
 export function tableKey(componentIds: ReadonlyArray<ComponentId>): string {
@@ -55,6 +58,7 @@ export function createTable(
   components: ReadonlyArray<Component>,
   id: TableId,
   shared = false,
+  activeDirectories: readonly Set<Table>[] = [new Set<Table>()],
 ): Table {
   const sortedComponents = canonicalComponents(components);
   const capacity = INITIAL_CAPACITY;
@@ -102,23 +106,31 @@ export function createTable(
     size: 0,
     capacity,
     version: 0,
+    membership: new Float64Array(Math.ceil(capacity / PROJECTION_BLOCK_SIZE)),
+    activeDirectories,
   };
 }
 
-export function appendTableRow(table: Table, entity: EntityHandle): number {
+export function appendTableRow(table: Table, entity: EntityHandle, epoch = 0): number {
   if (table.size === table.capacity) growTable(table, table.capacity * 2);
   const row = table.size;
   const self = table.storage.get(componentId(Entity))?.fields.get('self');
   if (self !== undefined) self.view[row] = entity as number;
   table.size = row + 1;
+  if (row === 0) for (const directory of table.activeDirectories) directory.add(table);
+  markTableMembership(table, row, epoch);
   return row;
 }
 
 export function removeTableRow(
   table: Table,
   row: number,
+  epoch = 0,
 ): { movedEntity: EntityHandle; newRow: number } | null {
   const lastRow = table.size - 1;
+  markTableMembership(table, row, epoch);
+  markTableMembership(table, lastRow, epoch);
+  if (lastRow === 0) for (const directory of table.activeDirectories) directory.delete(table);
   if (row === lastRow) {
     table.size = lastRow;
     return null;
@@ -148,6 +160,13 @@ export function growTable(table: Table, targetCapacity: number): void {
     componentStorage.fields = fields;
     componentStorage.epochs = growComponentEpochColumns(componentStorage.epochs, capacity);
   }
+  const membership = new Float64Array(Math.ceil(capacity / PROJECTION_BLOCK_SIZE));
+  membership.set(table.membership);
+  table.membership = membership;
   table.capacity = capacity;
   table.version += 1;
 }
+
+export function markTableMembership(table: Table, row: number, epoch: number): void {
+  table.membership[Math.floor(row / PROJECTION_BLOCK_SIZE)] = epoch;
+}

package/src/world-internal.ts

@@ -23,7 +23,6 @@ import type { SharedRefStore } from './shared-ref-store';
 import type { Archetype } from './storage/archetype';
 import type { ArchetypeGraph } from './storage/archetype-graph';
 import type { ChangeTicks } from './storage/change-detection';
-import type { StructuralEvidenceRing } from './storage/structural-evidence';
 import type { Table } from './storage/table';
 import type { ClockWriter } from './time';
 import type { ComponentData, EcsError, EntityRecord } from './world';
@@ -75,7 +74,6 @@ export interface WorldInternal {
   readonly getSchedules: () => ReadonlyMap<ScheduleToken, Schedule>;
   readonly getSharedRefs: () => SharedRefStore;
   readonly getStructureEpoch: () => number;
-  readonly getStructuralEvidence: () => StructuralEvidenceRing;
   readonly lookupAlive: (
     entity: EntityHandle,
     operation: string,

package/src/world.ts

@@ -1,3 +1,4 @@
+import { publishComponentRange } from './storage/change-detection';
 // @forgeax/engine-ecs — World: top-level ECS container.
 //
 // World owns entities, archetypes (via ArchetypeGraph), and component registry.
@@ -131,9 +132,7 @@ import {
   type FieldView,
   normalizeBufferWrite,
 } from './storage/column';
-import type { StructuralEvidenceInput } from './storage/structural-evidence';
-import { StructuralEvidenceRing as StructuralEvidenceRingImpl } from './storage/structural-evidence';
-import { appendTableRow, removeTableRow, type Table } from './storage/table';
+import { appendTableRow, markTableMembership, removeTableRow, type Table } from './storage/table';
 import {
   createWorldClock,
   DEFAULT_TIME_POLICY,
@@ -373,7 +372,6 @@ export class World {
   /** Per-World shared-ref store; public read-only for direct handle operations. */
   readonly sharedRefs: SharedRefStore = new SharedRefStoreImpl();
   private readonly componentMutationEpochs: number[] = [];
-  private readonly structuralEvidence = new StructuralEvidenceRingImpl();
   /** One packed reverse index per relationship source component. */
   private readonly relationshipIndexes = new Map<number, RelationshipIndex>();
   private mutationEpoch = 0;
@@ -430,7 +428,6 @@ export class World {
       getSchedules: () => this.schedules,
       getSharedRefs: () => this.sharedRefs,
       getStructureEpoch: this.getStructureEpoch.bind(this),
-      getStructuralEvidence: () => this.structuralEvidence,
       lookupAlive: this.lookupAlive.bind(this),
       markComponentChanged: this.internalmarkComponentChanged.bind(this),
       markComponentRangeChanged: this.internalmarkComponentRangeChanged.bind(this),
@@ -512,10 +509,6 @@ export class World {
     return worldScheduleUsesComponent(this, component);
   }
 
-  private recordStructuralEvidence(evidence: StructuralEvidenceInput): void {
-    this.structuralEvidence.append(evidence);
-  }
-
   /** Resolve current logical identity for a packed entity handle. */
   private internalgetEntityArchetype(entity: EntityHandle): Archetype | undefined {
     const record = this.records[entityIndex(entity)];
@@ -557,7 +550,7 @@ export class World {
     if (epochs === undefined) {
       throw new Error(`Derived component ${componentId} is not in the table.`);
     }
-    epochs.changed.fill(epoch, rowStart, rowStart + rowCount);
+    publishComponentRange(epochs, rowStart, rowCount, epoch);
     this.componentMutationEpochs[componentId] = epoch;
   }
 
@@ -606,7 +599,7 @@ export class World {
     const epochs = table.storage.get(componentId)?.epochs;
     if (epochs === undefined || rowCount === 0) return;
     const epoch = this.internalnextMutationEpoch();
-    epochs.changed.fill(epoch, rowStart, rowStart + rowCount);
+    publishComponentRange(epochs, rowStart, rowCount, epoch);
     this.componentMutationEpochs[componentId] = epoch;
   }
 
@@ -1410,11 +1403,6 @@ export class World {
     if (mirrorAdded) {
       this.internalmarkComponentsAdded(target, [mirrorLocalId]);
       this.advanceStructureEpoch();
-      this.recordStructuralEvidence({
-        kind: 'component-added',
-        entity: target,
-        componentId: mirrorLocalId,
-      });
     }
     return ok(undefined);
   }
@@ -1651,12 +1639,8 @@ export class World {
       data: value,
     });
     if (!valuePreflight.ok) return valuePreflight;
-    const currentValue = this.readRow(arch, component, row) as Record<string, unknown>;
-    const mergedValue = {
-      ...currentValue,
-      ...(value as Record<string, unknown>),
-    };
-    const enumError = validateEnumFieldValues(component, mergedValue, entity as number);
+    // Enum constraints are field-local; untouched fields are already validated.
+    const enumError = validateEnumFieldValues(component, value, entity as number);
     if (enumError !== null) return err(enumError as unknown as EcsError);
 
     if (component.storage === 'sparse') {
@@ -2191,11 +2175,6 @@ export class World {
       // components-added epoch/evidence record that claims the edge exists.
       this.internalmarkComponentsAdded(entity, [componentId(componentData.component)]);
       this.advanceStructureEpoch();
-      this.recordStructuralEvidence({
-        kind: 'component-added',
-        entity,
-        componentId: localId,
-      });
     }
     return ok(undefined);
   }
@@ -2308,12 +2287,8 @@ export class World {
       this.migrateEntity(rec, srcArch, targetArch);
     }
     if (!internal) {
+      this.internalnextMutationEpoch();
       this.advanceStructureEpoch();
-      this.recordStructuralEvidence({
-        kind: 'component-removed',
-        entity,
-        componentId: localId,
-      });
     }
     return ok(undefined);
   }
@@ -2378,7 +2353,7 @@ export class World {
       record.archetypeId = arch.id;
       storageTouched = true;
       const table = this.table(arch);
-      const tableRow = appendTableRow(table, entity);
+      const tableRow = appendTableRow(table, entity, this.mutationEpoch + 1);
       const archetypeRow = appendArchetypeRow(arch, tableRow);
       record.archetypeRow = archetypeRow;
 
@@ -2415,7 +2390,6 @@ export class World {
         ...componentDatas.map((cd) => componentId(cd.component)),
       ]);
       this.advanceStructureEpoch();
-      this.recordStructuralEvidence({ kind: 'spawn', entity });
       return ok(undefined);
     } catch (error) {
       if (storageTouched) this.poisonAfterEntityMutation('World.materializeEntity', error);
@@ -3021,6 +2995,28 @@ export class World {
     const isVariable = arrayMeta.length === undefined;
     const fixedLength = arrayMeta.length ?? 0;
 
+    // Same-typed inline storage can copy elements without packing temporary bytes.
+    // TypedArray.set preserves overlapping source views; different element types
+    // retain the byte-copy contract below.
+    if (
+      !isVariable &&
+      metaKey !== 'shared' &&
+      meta.viewCtor !== undefined &&
+      col.view instanceof meta.viewCtor &&
+      (raw == null || Array.isArray(raw) || raw instanceof meta.viewCtor)
+    ) {
+      const start = row * col.arity;
+      const count = raw == null ? 0 : Math.min(raw.length, col.arity);
+      if (Array.isArray(raw)) {
+        for (let i = 0; i < count; i++)
+          col.view[start + i] = typeof raw[i] === 'number' ? raw[i] : 0;
+      } else if (raw != null) {
+        col.view.set(raw.length <= col.arity ? raw : raw.subarray(0, count), start);
+      }
+      col.view.fill(0, start + count, start + col.arity);
+      return;
+    }
+
     // Determine the payload's logical element count. Accept any TypedArray
     // (Float32Array / Uint32Array / etc.) plus plain numeric arrays; an
     // undefined / missing payload is treated as a length-0 init. Bytes are
@@ -3230,7 +3226,7 @@ export class World {
     const entity = (srcTable.storage.get(componentId(EntityComponent))?.fields.get('self')?.view[
       oldTableRow
     ] ?? 0) as EntityHandle;
-    const newTableRow = appendTableRow(targetTable, entity);
+    const newTableRow = appendTableRow(targetTable, entity, this.mutationEpoch + 1);
     const newArchetypeRow = appendArchetypeRow(targetArch, newTableRow);
 
     // Copy shared component data.
@@ -3276,7 +3272,7 @@ export class World {
         movedRecord.archetypeRow = archetypeSwap.newRow;
       }
     }
-    const tableSwap = removeTableRow(srcTable, oldTableRow);
+    const tableSwap = removeTableRow(srcTable, oldTableRow, this.mutationEpoch + 1);
     if (tableSwap !== null) {
       const movedRecord = this.records[entityIndex(tableSwap.movedEntity)];
       if (movedRecord?.generation === entityGeneration(tableSwap.movedEntity)) {
@@ -3313,6 +3309,7 @@ export class World {
     }
     record.archetypeId = targetArch.id;
     record.archetypeRow = appendArchetypeRow(targetArch, tableRow);
+    markTableMembership(table, tableRow, this.mutationEpoch + 1);
   }
 
   /**
@@ -3366,7 +3363,7 @@ export class World {
             movedRecord.archetypeRow = archetypeSwap.newRow;
           }
         }
-        const tableSwap = removeTableRow(table, tableRow);
+        const tableSwap = removeTableRow(table, tableRow, this.mutationEpoch + 1);
         if (tableSwap !== null) {
           const movedRecord = this.records[entityIndex(tableSwap.movedEntity)];
           if (movedRecord?.generation === entityGeneration(tableSwap.movedEntity)) {
@@ -3377,7 +3374,6 @@ export class World {
           }
         }
       }
-      this.recordStructuralEvidence({ kind: 'despawn', entity });
       record.archetypeId = -1;
       record.archetypeRow = -1;
       record.generation += 1;
@@ -3386,6 +3382,7 @@ export class World {
         const childResult = this.despawnEntity(child, true);
         if (!childResult.ok) return childResult;
       }
+      this.internalnextMutationEpoch();
       this.advanceStructureEpoch();
       return ok(undefined);
     } catch (error) {

package/dist/__tests__/structural-evidence.contract.test-d.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=structural-evidence.contract.test-d.d.ts.map

package/dist/__tests__/structural-evidence.contract.test-d.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"structural-evidence.contract.test-d.d.ts","sourceRoot":"","sources":["../../src/__tests__/structural-evidence.contract.test-d.ts"],"names":[],"mappings":""}

package/dist/__tests__/structural-evidence.contract.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=structural-evidence.contract.test.d.ts.map

package/dist/__tests__/structural-evidence.contract.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"structural-evidence.contract.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/structural-evidence.contract.test.ts"],"names":[],"mappings":""}

package/dist/storage/structural-evidence.d.ts

@@ -1,30 +0,0 @@
-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 declare class StructuralEvidenceRing {
-    readonly capacity: number;
-    private readonly events;
-    private nextSequence;
-    constructor(capacity?: number);
-    get cursor(): number;
-    append(input: StructuralEvidenceInput): number;
-    readAfter(cursor: number): StructuralEvidenceRead;
-}
-//# sourceMappingURL=structural-evidence.d.ts.map

package/dist/storage/structural-evidence.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"structural-evidence.d.ts","sourceRoot":"","sources":["../../src/storage/structural-evidence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD,MAAM,MAAM,sBAAsB,GAAG,OAAO,GAAG,SAAS,GAAG,iBAAiB,GAAG,mBAAmB,CAAC;AAEnG,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,kBAAmB,SAAQ,uBAAuB;IACjE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,MAAM,sBAAsB,GAC9B;IACE,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,CAAC;CAChD,GACD;IAAE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/F,2FAA2F;AAC3F,qBAAa,sBAAsB;IAIrB,QAAQ,CAAC,QAAQ;IAH7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwC;IAC/D,OAAO,CAAC,YAAY,CAAK;gBAEJ,QAAQ,SAAO;IAOpC,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,MAAM,CAAC,KAAK,EAAE,uBAAuB,GAAG,MAAM;IAO9C,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,sBAAsB;CAkBlD"}

package/src/__tests__/structural-evidence.contract.test-d.ts

@@ -1,6 +0,0 @@
-import type { StructuralEvidence, StructuralEvidenceKind } from '../storage/structural-evidence';
-
-const kind: StructuralEvidenceKind = 'component-added';
-const evidence: StructuralEvidence = { sequence: 1, kind, entity: 0 as never, componentId: 4 };
-// @ts-expect-error evidence sequence is producer-owned.
-evidence.sequence = 2;

package/src/__tests__/structural-evidence.contract.test.ts

@@ -1,49 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { encodeEntity } from '../entity-handle';
-import { StructuralEvidenceRing } from '../storage/structural-evidence';
-
-describe('typed structural evidence ring', () => {
-  it('records lifecycle, component membership, packed identity, and sequence facts', () => {
-    const ring = new StructuralEvidenceRing(8);
-    const entity = encodeEntity(4, 2);
-    const cursor = ring.cursor;
-    ring.append({ kind: 'spawn', entity });
-    ring.append({ kind: 'component-added', entity, componentId: 7 });
-    ring.append({ kind: 'component-removed', entity, componentId: 7 });
-    ring.append({ kind: 'despawn', entity });
-    const read = ring.readAfter(cursor);
-    expect(read.status).toBe('ok');
-    if (read.status !== 'ok') return;
-    expect(
-      read.events.map(({ kind, entity: packed, sequence }) => ({ kind, packed, sequence })),
-    ).toEqual([
-      { kind: 'spawn', packed: entity, sequence: 1 },
-      { kind: 'component-added', packed: entity, sequence: 2 },
-      { kind: 'component-removed', packed: entity, sequence: 3 },
-      { kind: 'despawn', packed: entity, sequence: 4 },
-    ]);
-  });
-
-  it('fails closed on overflow and exposes the cursor for consumer reconciliation', () => {
-    const ring = new StructuralEvidenceRing(2);
-    const cursor = ring.cursor;
-    const entity = encodeEntity(1, 4);
-    const reused = encodeEntity(1, 5);
-    ring.append({ kind: 'spawn', entity });
-    ring.append({ kind: 'despawn', entity });
-    ring.append({ kind: 'spawn', entity: reused });
-    expect(ring.readAfter(cursor)).toMatchObject({
-      status: 'overflow',
-      cursor: 3,
-      oldestAvailable: 2,
-    });
-    expect(ring.cursor).toBe(3);
-  });
-
-  it('rejects cursors outside the producer-owned sequence range', () => {
-    const ring = new StructuralEvidenceRing(4);
-    const entity = encodeEntity(3, 1);
-    ring.append({ kind: 'spawn', entity });
-    expect(() => ring.readAfter(2)).toThrow(RangeError);
-  });
-});

package/src/storage/structural-evidence.ts

@@ -1,64 +0,0 @@
-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 };
-  }
-}