@forgeax/engine-ecs 0.1.20 → 0.1.23

package/src/component-schema.ts

@@ -18,6 +18,8 @@ export interface ComponentSchemaDefinition {
 export interface ComponentPolicy {
   readonly transient: boolean;
   readonly meta: Record<string, unknown>;
+  /** Components that are materialized whenever this component is added. */
+  readonly requires: readonly Component[];
 }
 
 /** Immutable schema reflection plus non-token policy projection. */
@@ -60,6 +62,55 @@ export function componentDefinition(component: Component): ComponentDefinition {
   return definition;
 }
 
+/** Read the generic structural requirements declared by one component. */
+export function componentRequirements(component: Component): readonly Component[] {
+  // Keep invalid/foreign tokens on the ordinary preflight error path. The
+  // expansion helper runs before validation, so it must not turn a structured
+  // `component-not-defined` Result into an uncaught registry exception.
+  return definitions.definitions.get(component)?.policy.requires ?? [];
+}
+
+type ComponentDataLike = {
+  readonly component: Component;
+  readonly data: Partial<Record<string, unknown>>;
+};
+
+/**
+ * Expand component requirements once at the structural boundary.
+ *
+ * Explicit component data wins and is never duplicated. Requirements are
+ * appended in declaration order, and the same identity set also terminates a
+ * malformed dependency cycle without a per-frame scan.
+ */
+export function expandComponentRequirements<T extends ComponentDataLike>(
+  componentDatas: readonly T[],
+): T[] {
+  let hasRequirements = false;
+  for (const entry of componentDatas) {
+    if (componentRequirements(entry.component).length !== 0) {
+      hasRequirements = true;
+      break;
+    }
+  }
+  // Most structural operations use components without dependencies. Preserve
+  // that path without copying or allocating a Set; callers only consume the
+  // returned list and never mutate it.
+  if (!hasRequirements) return componentDatas as T[];
+
+  const expanded = [...componentDatas];
+  const seen = new Set<Component>(expanded.map((entry) => entry.component));
+  for (let index = 0; index < expanded.length; index++) {
+    const component = expanded[index]?.component;
+    if (component === undefined) continue;
+    for (const required of componentRequirements(component)) {
+      if (seen.has(required)) continue;
+      seen.add(required);
+      expanded.push({ component: required, data: {} } as T);
+    }
+  }
+  return expanded;
+}
+
 /**
  * Freeze a schema value recursively.  Component descriptors are authored data,
  * so nested defaults and enum label maps must not become mutation channels.

package/src/component.ts

@@ -930,7 +930,7 @@ export interface FieldDescriptor<T extends SchemaFieldType = SchemaFieldType> {
  * same meaning): scene collect skips a `transient` field just as it skips a
  * `transient` component. Granularity is sunk to the field level so a component
  * can persist most of its fields while excluding a derived/reconstructable one
- * (e.g. `Transform.world`). Absent means the field participates in
+ * (e.g. `GlobalTransform.world`). Absent means the field participates in
  * serialization.
  */
 export interface FieldReflection {
@@ -998,6 +998,12 @@ export interface DefineComponentOptions {
    * rebuilt by the mirror hook after instantiateScene).
    */
   readonly transient?: boolean;
+  /**
+   * Components materialized automatically when this component is added.
+   * Explicit data for a required component wins; the ECS appends only missing
+   * identities at the spawn/add boundary, never from a frame system.
+   */
+  readonly requires?: readonly Component[];
   /**
    * Component-level open metadata namespace. Entries are copied into
    * `Component.meta` at registration; the ECS core assigns no meaning to any
@@ -1171,7 +1177,11 @@ export function defineComponent<const N extends string, const S extends FieldsIn
   registerComponentDefinition(token, {
     fields: frozenFields,
     defaults: frozenDefaults,
-    policy: { transient: options?.transient ?? false, meta },
+    policy: {
+      transient: options?.transient ?? false,
+      meta,
+      requires: Object.freeze([...(options?.requires ?? [])]),
+    },
   });
   return Object.freeze(token);
 }

package/src/errors/query-and-component-errors.ts

@@ -122,7 +122,7 @@ export class SpawnDataUnknownFieldError extends Error {
     this.detail = { component: componentName, field: fieldName, knownFields: sortedKnown };
   }
 }
-export type QuerySpanUnavailableReason = 'optional-data' | 'row-change-filter' | 'sparse-component';
+export type QuerySpanUnavailableReason = 'optional-data' | 'sparse-component';
 
 export class QueryDescriptorConflictError extends Error {
   override readonly name = 'QueryDescriptorConflictError';

package/src/errors/validation-errors.ts

@@ -291,6 +291,36 @@ export function validateEnumFieldValues<S extends ComponentSchema>(
  * `.hint` — names the offending field plus the valid replacement form.
  */
 const SPAWN_LIGHT_INVALID_BOUNDS_POLICY = {
+  intensity: {
+    expected: 'intensity is finite and >= 0',
+    hint: (componentName: string, got: number | readonly number[]) =>
+      `${componentName}.intensity must be a finite non-negative number (got ${got})`,
+  },
+  color: {
+    expected: 'color is a finite non-negative [r, g, b] vector',
+    hint: (componentName: string, got: number | readonly number[]) =>
+      `${componentName}.color must contain three finite non-negative channels (got ${JSON.stringify(got)})`,
+  },
+  width: {
+    expected: 'width is finite and > 0',
+    hint: (componentName: string, got: number | readonly number[]) =>
+      `${componentName}.width must be a finite positive meter value (got ${got})`,
+  },
+  height: {
+    expected: 'height is finite and > 0',
+    hint: (componentName: string, got: number | readonly number[]) =>
+      `${componentName}.height must be a finite positive meter value (got ${got})`,
+  },
+  irradiance: {
+    expected: 'irradiance is a finite 27-value SH vector',
+    hint: (componentName: string, got: number | readonly number[]) =>
+      `${componentName}.irradiance must contain 27 finite SH values (got ${JSON.stringify(got)})`,
+  },
+  radius: {
+    expected: 'radius is finite and >= R_MIN',
+    hint: (componentName: string, got: number | readonly number[]) =>
+      `${componentName}.radius must be a finite value >= R_MIN (got ${got})`,
+  },
   range: {
     expected: 'range >= 0 or Number.POSITIVE_INFINITY',
     hint: (componentName: string, got: number | readonly number[]) =>

package/src/errors.ts

@@ -399,6 +399,20 @@ export class ChangeEpochExhaustedError extends Error {
   }
 }
 
+export class DerivedRangeOutOfBoundsError extends Error {
+  override readonly name = 'DerivedRangeOutOfBoundsError';
+  readonly code = 'derived-range-out-of-bounds' as const;
+  readonly expected = 'a non-negative span-relative range with start + count <= span.length';
+  readonly hint =
+    'check start and count against the QuerySpan length, then retry without changing World state';
+  readonly detail: { readonly start: number; readonly count: number; readonly spanLength: number };
+
+  constructor(start: number, count: number, spanLength: number) {
+    super(`Derived range [${start}, ${start + count}) exceeds QuerySpan length ${spanLength}.`);
+    this.detail = { start, count, spanLength };
+  }
+}
+
 /**
  * Thrown when insertResource/removeResource is called on a World-owned
  * protected resource (Time or FixedTime).
@@ -1189,15 +1203,25 @@ export type EcsErrorDetail =
       readonly actualLength: number;
       readonly expectedStride: 16;
     }
-  // feat-20260519-light-casters-point-spot-pbr w2 — PointLight / SpotLight
+  // feat-20260519-light-casters-point-spot-pbr w2 — light and local probe
   // spawn-time payload bound violation (plan-strategy D-S3 a). detail.field
-  // three-branch ('range' | 'innerOuter' | 'outerNinety') keeps four bound
-  // violations under one code; AI users narrow on `.detail.field` after the
+  // names the validated scalar or RGB payload while one code keeps the
+  // recovery surface closed; AI users narrow on `.detail.field` after the
   // outer `switch (err.code)` to pick the specific recovery hint.
   | {
       readonly code: 'spawn-light-invalid-bounds';
-      readonly field: 'range' | 'innerOuter' | 'outerNinety';
-      readonly got: number;
+      readonly field:
+        | 'direction'
+        | 'intensity'
+        | 'color'
+        | 'width'
+        | 'height'
+        | 'irradiance'
+        | 'radius'
+        | 'range'
+        | 'innerOuter'
+        | 'outerNinety';
+      readonly got: number | readonly number[];
     }
   // feat-20260520-2d-sprite-layer-mvp M-2 w13 — resource-setter bound
   // violation (plan-strategy D-4). receivedMode carries the rejected

package/src/internal.ts

@@ -0,0 +1,56 @@
+// @forgeax/engine-ecs/internal — package-owner seams that are intentionally
+// absent from the public ECS barrel.
+//
+// This entry keeps the existing component-owner imports stable and adds the
+// typed symbol used by scene propagation. A symbol avoids putting a derived
+// writer method on the discoverable Query contract while still letting the
+// owning package share the exact query implementation without a private path
+// import or an untyped cast at each consumer.
+
+export * from './component';
+
+import type { Result } from '@forgeax/engine-types';
+import type { Component } from './component';
+import type { QuerySpanUnavailableError } from './errors';
+import type { DerivedRangeWriter } from './query/derived-range-writer';
+import type { Query } from './query/query';
+
+/** Internal identity for the ECS-owned derived range writer accessor. */
+export const DERIVED_WRITER: unique symbol = Symbol.for(
+  'forgeax.ecs.query.derivedWriter',
+) as unknown as typeof DERIVED_WRITER;
+
+type DerivedWriterQuery<
+  R extends readonly Component[],
+  W extends readonly Component[],
+  O extends readonly Component[],
+> = Query<R, W, O> & {
+  readonly [DERIVED_WRITER]: <C extends W[number]>(
+    component: C,
+  ) => Result<DerivedRangeWriter<R[number], C>, QuerySpanUnavailableError>;
+};
+
+/**
+ * Resolve the ECS-owned derived writer through its internal symbol seam.
+ * Consumers of this module retain the component/query type relationship while
+ * the public Query and QuerySpan surfaces remain read/write-only contracts.
+ */
+export function getDerivedWriter<
+  R extends readonly Component[],
+  W extends readonly Component[],
+  O extends readonly Component[],
+  C extends W[number],
+>(
+  query: Query<R, W, O>,
+  component: C,
+): Result<DerivedRangeWriter<R[number], C>, QuerySpanUnavailableError> {
+  const internalQuery = query as DerivedWriterQuery<R, W, O>;
+  return internalQuery[DERIVED_WRITER](component);
+}
+
+export type {
+  DerivedColumnBinding,
+  DerivedRangeRowCommit,
+  DerivedRangeRowProbe,
+  DerivedRangeWriter,
+} from './query/derived-range-writer';

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);
-    },
-  };
-}