@forgeax/engine-ecs 0.1.23 → 0.1.24

package/src/query/derived-range-writer.ts

@@ -1,6 +1,9 @@
 import { err, ok, type Result } from '@forgeax/engine-types';
 import type { Component } from '../component';
 import * as componentOwner from '../component';
+import { componentId } from '../component';
+import { Entity } from '../entity';
+import type { EntityHandle } from '../entity-handle';
 import {
   DerivedRangeOutOfBoundsError,
   SharedKernelFailureError,
@@ -13,11 +16,21 @@ import type { MutableColumnShape, ReadonlyColumnShape } from './query';
 
 /** Package-internal whole-column storage owned by one dense query table. */
 export interface DerivedColumnBinding<R extends Component, C extends Component> {
+  /** Physical table identity for package-internal projection consumers. */
+  readonly tableId: number;
+  /** Whole entity column; every dense table carries the essential Entity row. */
+  readonly entities: Readonly<Uint32Array>;
   readonly read: ReadonlyColumnShape<R>;
   readonly write: MutableColumnShape<C>;
   readonly rowCapacity: number;
 }
 
+/** Reusable identity cursor for O(1) dense-table lookup without a row facade. */
+export interface DerivedRangeCursor {
+  bindingIndex: number;
+  row: number;
+}
+
 export type DerivedRangeKernel<R extends Component, C extends Component> = (
   binding: DerivedColumnBinding<R, C>,
   base: number,
@@ -97,6 +110,10 @@ function countAllocation(name: keyof DerivedRangeAllocationTrace): void {
 
 export interface DerivedRangeWriter<R extends Component, C extends Component> {
   readonly bindings: readonly DerivedColumnBinding<R, C>[];
+  /** Locate a live entity in its bound table and return its physical row. */
+  locateEntity(entity: EntityHandle, cursor: DerivedRangeCursor): boolean;
+  /** Publish rows whose values were written directly into a derived column. */
+  publishChangedRows(bindingIndex: number, changed: Uint8Array): Result<void, EcsError>;
   writeRange(
     bindingIndex: number,
     base: number,
@@ -130,6 +147,7 @@ export function createDerivedRangeWriter<R extends Component, C extends Componen
   let boundEpoch = -1;
   let bindingTables: readonly Table[] = [];
   let bindings: readonly DerivedColumnBinding<R, C>[] = [];
+  let bindingByTable = new Map<number, number>();
   let runStartBuffers: readonly Int32Array[] = [];
   let runCountBuffers: readonly Int32Array[] = [];
 
@@ -141,6 +159,9 @@ export function createDerivedRangeWriter<R extends Component, C extends Componen
     const nextRunCountBuffers: Int32Array[] = [];
     for (const table of tables) {
       nextBindings.push({
+        tableId: table.id,
+        entities: (table.storage.get(componentId(Entity))?.fields.get('self')?.view ??
+          new Uint32Array(0)) as Uint32Array,
         read: buildWholeColumnShape(table, source.readComponents) as ReadonlyColumnShape<R>,
         write: buildWholeColumnShape(table, source.writeComponents) as MutableColumnShape<C>,
         rowCapacity: table.size,
@@ -153,6 +174,11 @@ export function createDerivedRangeWriter<R extends Component, C extends Componen
     }
     bindingTables = tables;
     bindings = nextBindings;
+    bindingByTable = new Map<number, number>();
+    for (let index = 0; index < nextBindings.length; index += 1) {
+      const binding = nextBindings[index];
+      if (binding !== undefined) bindingByTable.set(binding.tableId, index);
+    }
     runStartBuffers = nextRunStartBuffers;
     runCountBuffers = nextRunCountBuffers;
     boundEpoch = source.structureEpoch();
@@ -165,6 +191,91 @@ export function createDerivedRangeWriter<R extends Component, C extends Componen
       if (boundEpoch !== source.structureEpoch()) rebind();
       return bindings;
     },
+    locateEntity(entity, cursor) {
+      if (world.execution.health === 'poisoned') return false;
+      if (boundEpoch !== source.structureEpoch()) rebind();
+      const archetype = world[worldInternal].getEntityArchetype(entity);
+      if (archetype === undefined) return false;
+      const bindingIndex = bindingByTable.get(archetype.tableId);
+      if (bindingIndex === undefined) return false;
+      const record = world[worldInternal].getRecords()[(entity as unknown as number) & 0x00ffffff];
+      if (record === undefined || record.archetypeId !== archetype.id) return false;
+      const row = archetype.rows[record.archetypeRow];
+      const binding = bindings[bindingIndex];
+      if (binding === undefined || row === undefined || row < 0 || row >= binding.rowCapacity) {
+        return false;
+      }
+      cursor.bindingIndex = bindingIndex;
+      cursor.row = row;
+      return true;
+    },
+    publishChangedRows(bindingIndex, changed) {
+      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 === undefined ||
+        table === undefined ||
+        runStarts === undefined ||
+        runCounts === undefined ||
+        !Number.isSafeInteger(bindingIndex) ||
+        bindingIndex < 0 ||
+        changed.length < binding.rowCapacity ||
+        table.storage.get(componentOwner.componentId(component)) === undefined
+      ) {
+        return err(new DerivedRangeOutOfBoundsError(0, changed.length, binding?.rowCapacity ?? 0));
+      }
+      let runCount = 0;
+      let runStart = -1;
+      for (let row = 0; row < binding.rowCapacity; row += 1) {
+        if ((changed[row] ?? 0) !== 0) {
+          if (runStart < 0) runStart = row;
+        } else if (runStart >= 0) {
+          runStarts[runCount] = runStart;
+          runCounts[runCount] = row - runStart;
+          runCount += 1;
+          runStart = -1;
+        }
+      }
+      if (runStart >= 0) {
+        runStarts[runCount] = runStart;
+        runCounts[runCount] = binding.rowCapacity - runStart;
+        runCount += 1;
+      }
+      if (runCount === 0) return ok(undefined);
+      const previousEpoch = world[worldInternal].getMutationEpoch();
+      let epoch: number;
+      try {
+        epoch = world[worldInternal].nextMutationEpoch();
+        const componentIdentifier = componentOwner.componentId(component);
+        for (let index = 0; index < runCount; index += 1) {
+          world[worldInternal].publishDerivedRange(
+            table,
+            componentIdentifier,
+            runStarts[index] ?? 0,
+            runCounts[index] ?? 0,
+            epoch,
+          );
+        }
+        changed.fill(0, 0, binding.rowCapacity);
+        return ok(undefined);
+      } catch (cause) {
+        world[worldInternal].restoreMutationEpoch(previousEpoch);
+        world[worldInternal].poisonExecution({
+          code: 'shared-kernel-failed',
+          kernelName: `derived-range:${component.name}:publish`,
+          cause,
+          partialWrite: true,
+          retryable: false,
+        });
+        return err(new SharedKernelFailureError(component.name, world.identity, cause, true));
+      }
+    },
     writeRange(bindingIndex, base, start, count, kernel, context) {
       if (world.execution.health === 'poisoned') {
         return err(new WorldPoisonedError(world.identity, world.execution.fault));

package/src/query/query.ts

@@ -18,8 +18,10 @@ import {
   QueryIterationInvalidatedError,
   QuerySpanUnavailableError,
   type QuerySpanUnavailableReason,
+  RelationshipTargetReadonlyError,
 } from '../errors';
 import { DERIVED_WRITER } from '../internal';
+import { isRelationshipTarget, relationshipRole } from '../relationship-index';
 import type { Archetype, ArchetypeId } from '../storage/archetype';
 import type { ArchetypeGraph } from '../storage/archetype-graph';
 import { sparseTagIndex } from '../storage/change-detection';
@@ -229,7 +231,17 @@ class QueryRowFacade<
   mut<C extends W[number]>(component: C): MutableRowShape<C> {
     const current = this.get(component);
     if (current === undefined) throw new Error(`Query row lacks ${component.name}.`);
-    this.world[worldInternal].markComponentChanged(this.entity, componentId(component));
+    if (isRelationshipTarget(component)) {
+      throw new RelationshipTargetReadonlyError(component.name, 'query row');
+    }
+    // Relationship sources must let the owner validate before recording
+    // authored evidence. A stale/cyclic target therefore has zero mutation
+    // side effects, while ordinary components retain the existing eager
+    // `mut()` evidence semantics.
+    const relationshipSource = relationshipRole(component)?.kind === 'source';
+    if (!relationshipSource) {
+      this.world[worldInternal].markComponentChanged(this.entity, componentId(component));
+    }
     return new Proxy(current, {
       set: (target, property, value) => {
         if (typeof property !== 'string') return false;
@@ -275,6 +287,12 @@ class QuerySpanFacade<R extends readonly Component[], W extends readonly Compone
   }
 
   mut<C extends W[number]>(component: C): MutableColumnShape<C> {
+    // A span exposes live column storage. Relationship source and target
+    // columns must never obtain that raw write capability: source writes need
+    // target-side maintenance and target writes are engine-owned projections.
+    if (relationshipRole(component) !== undefined) {
+      throw new RelationshipTargetReadonlyError(component.name, 'query span');
+    }
     this.world[worldInternal].markComponentRangeChanged(
       this.table,
       componentId(component),
@@ -662,6 +680,13 @@ class ExecutableQuery<
   private spanUnavailableReason(): QuerySpanUnavailableReason | undefined {
     if (this.compiled.sparseRoute) return 'sparse-component';
     if ((this.compiled.descriptor.optional?.length ?? 0) > 0) return 'optional-data';
+    // A writable relationship source would bypass the source owner (and its
+    // materialized target/backpointer), while a target is an ECS-owned
+    // projection. Keep read-only relationship inputs usable by Scene's
+    // derived writer; only the descriptor's writable role is ineligible.
+    if ((this.compiled.descriptor.write ?? []).some((component) => relationshipRole(component))) {
+      return 'relationship-component';
+    }
     return undefined;
   }
 }