@forgeax/engine-ecs 0.1.21 → 0.1.24

package/src/__tests__/query.unit.test.ts

@@ -138,7 +138,7 @@ describe('executable Query', () => {
     expect(spans[0]?.get(Position).x[0]).toBe(1);
   });
 
-  it('returns structured span capability failures', () => {
+  it('returns structured span capability failures and coalesces changed rows', () => {
     const world = new World();
     const optional = world
       .query({ read: [Position], optional: [Velocity] })
@@ -146,11 +146,15 @@ describe('executable Query', () => {
       .spans();
     expect(!optional.ok && optional.error.detail.reason).toBe('optional-data');
 
-    const changed = world
-      .query({ read: [Position], changed: [Position] })
-      .unwrap()
-      .spans();
-    expect(!changed.ok && changed.error.detail.reason).toBe('row-change-filter');
+    const { world: changedWorld, first, second } = createWorld();
+    const changedQuery = changedWorld.query({ read: [Position], changed: [Position] }).unwrap();
+    expect([...changedQuery.spans().unwrap()].flatMap((span) => Array.from(span.entities))).toEqual(
+      [first, second],
+    );
+    changedWorld.set(second, Position, { x: 9 }).unwrap();
+    const changedSpans = [...changedQuery.spans().unwrap()];
+    expect(changedSpans).toHaveLength(1);
+    expect(Array.from(changedSpans[0]?.entities ?? [])).toEqual([second]);
   });
 
   it('does not commit observation after partial iteration', () => {

package/src/__tests__/relationship-index.test.ts

@@ -1,8 +1,12 @@
+import { err } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
-import { componentSchema } from '../component';
+import { componentSchema, defineComponent } from '../component';
 import { componentDefinition } from '../component-schema';
+import { ManagedBufferOutOfBoundsError } from '../errors';
+import { getDerivedWriter } from '../internal';
 import { defineRelationship, RelationshipIndex, relationshipRole } from '../relationship-index';
 import { World } from '../world';
+import { worldInternal } from '../world-internal';
 
 describe('relationship index', () => {
   it('keeps source writable and target materialized/read-only by role', () => {
@@ -67,4 +71,146 @@ describe('relationship index', () => {
     );
     world.spawn({ component: pair.target, data: { sources: [] } });
   });
+
+  it('detaches public target arrays from the materialized mirror and index', () => {
+    const pair = defineRelationship({
+      sourceName: 'DetachedSource',
+      sourceField: 'target',
+      targetName: 'DetachedTargets',
+      targetField: 'sources',
+    });
+    const world = new World();
+    const target = world.spawn().unwrap();
+    const source = world.spawn({ component: pair.source, data: { target } }).unwrap();
+    const beforeEpoch = world[worldInternal].getRelationshipEpoch(pair.source);
+    const exposed = world.get(target, pair.target).unwrap().sources;
+
+    exposed.fill(0);
+    exposed[0] = 0;
+
+    expect(Array.from(world.get(target, pair.target).unwrap().sources)).toEqual([source]);
+    expect(
+      Array.from(world[worldInternal].getRelationshipTargetEntities(pair.source, target)),
+    ).toEqual([source]);
+    expect(world.get(source, pair.source).unwrap().target).toBe(target);
+    expect(world[worldInternal].getRelationshipEpoch(pair.source)).toBe(beforeEpoch);
+  });
+
+  it('routes source set, row mutation, reparent, and null detach through one mirror owner', () => {
+    const pair = defineRelationship({
+      sourceName: 'OwnedSource',
+      sourceField: 'target',
+      targetName: 'OwnedTargets',
+      targetField: 'sources',
+    });
+    const world = new World();
+    const first = world.spawn().unwrap();
+    const second = world.spawn().unwrap();
+    const source = world.spawn({ component: pair.source, data: { target: first } }).unwrap();
+
+    expect(Array.from(world.get(first, pair.target).unwrap().sources)).toEqual([source]);
+    world.set(source, pair.source, { target: second }).unwrap();
+    expect(Array.from(world.get(first, pair.target).unwrap().sources)).toEqual([]);
+    expect(Array.from(world.get(second, pair.target).unwrap().sources)).toEqual([source]);
+
+    const row = world
+      .query({ write: [pair.source] })
+      .unwrap()
+      .at(source);
+    if (row === undefined) throw new Error('expected source row');
+    row.mut(pair.source).target = first;
+    expect(Array.from(world.get(second, pair.target).unwrap().sources)).toEqual([]);
+    expect(Array.from(world.get(first, pair.target).unwrap().sources)).toEqual([source]);
+
+    world.set(source, pair.source, { target: null }).unwrap();
+    expect(Array.from(world.get(first, pair.target).unwrap().sources)).toEqual([]);
+
+    const sourceQuery = world.query({ write: [pair.source] }).unwrap();
+    const sourceSpans = sourceQuery.spans();
+    expect(sourceSpans.ok).toBe(false);
+    if (!sourceSpans.ok) expect(sourceSpans.error.detail.reason).toBe('relationship-component');
+    const sourceWriter = getDerivedWriter(sourceQuery, pair.source);
+    expect(sourceWriter.ok).toBe(false);
+    if (!sourceWriter.ok) expect(sourceWriter.error.detail.reason).toBe('relationship-component');
+
+    const targetQuery = world.query({ write: [pair.target] }).unwrap();
+    const targetWriter = getDerivedWriter(targetQuery, pair.target);
+    expect(targetWriter.ok).toBe(false);
+    if (!targetWriter.ok) expect(targetWriter.error.detail.reason).toBe('relationship-component');
+  });
+
+  it('rejects stale source targets before changing owner state', () => {
+    const pair = defineRelationship({
+      sourceName: 'AtomicSource',
+      sourceField: 'target',
+      targetName: 'AtomicTargets',
+      targetField: 'sources',
+    });
+    const world = new World();
+    const target = world.spawn().unwrap();
+    const source = world.spawn({ component: pair.source, data: { target } }).unwrap();
+    const stale = world.spawn().unwrap();
+    world.despawn(stale).unwrap();
+    const beforeValue = world.get(source, pair.source).unwrap().target;
+    const beforeMirror = Array.from(world.get(target, pair.target).unwrap().sources);
+    const beforeMutation = world[worldInternal].getMutationEpoch();
+    const beforeRelationship = world[worldInternal].getRelationshipEpoch(pair.source);
+    const result = world.set(source, pair.source, { target: stale });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error.code).toBe('stale-entity');
+    expect(world.get(source, pair.source).unwrap().target).toBe(beforeValue);
+    expect(Array.from(world.get(target, pair.target).unwrap().sources)).toEqual(beforeMirror);
+    expect(world[worldInternal].getMutationEpoch()).toBe(beforeMutation);
+    expect(world[worldInternal].getRelationshipEpoch(pair.source)).toBe(beforeRelationship);
+
+    const row = world
+      .query({ write: [pair.source] })
+      .unwrap()
+      .at(source);
+    if (row === undefined) throw new Error('expected source row after stale rejection');
+    expect(() => {
+      row.mut(pair.source).target = stale;
+    }).toThrow('stale');
+    expect(world.get(source, pair.source).unwrap().target).toBe(beforeValue);
+    expect(world[worldInternal].getMutationEpoch()).toBe(beforeMutation);
+    expect(world[worldInternal].getRelationshipEpoch(pair.source)).toBe(beforeRelationship);
+  });
+
+  it('prepares mirror capacity before source structural mutation on allocation failure', () => {
+    const Required = defineComponent('CapacityAtomicRequired', {});
+    const pair = defineRelationship({
+      sourceName: 'CapacityAtomicSource',
+      sourceField: 'target',
+      targetName: 'CapacityAtomicTargets',
+      targetField: 'sources',
+      sourceRequires: [Required],
+    });
+    const world = new World();
+    const target = world.spawn().unwrap();
+    const source = world.spawn().unwrap();
+    const pool = world[worldInternal].getBufferPool();
+    const originalAlloc = pool.alloc;
+    const beforeMutation = world[worldInternal].getMutationEpoch();
+    const beforeStructure = world[worldInternal].getStructureEpoch();
+    const beforeRelationship = world[worldInternal].getRelationshipEpoch(pair.source);
+    Object.defineProperty(pool, 'alloc', {
+      configurable: true,
+      value: () => err(new ManagedBufferOutOfBoundsError(4, 0)),
+    });
+    try {
+      const result = world.addComponent(source, { component: pair.source, data: { target } });
+      expect(result.ok).toBe(false);
+      if (!result.ok) expect(result.error.code).toBe('managed-buffer-out-of-bounds');
+      expect(world.hasComponent(source, pair.source)).toBe(false);
+      expect(world.hasComponent(source, Required)).toBe(false);
+      expect(world.hasComponent(target, pair.target)).toBe(false);
+      expect(world[worldInternal].getMutationEpoch()).toBe(beforeMutation);
+      expect(world[worldInternal].getStructureEpoch()).toBe(beforeStructure);
+      expect(world[worldInternal].getRelationshipEpoch(pair.source)).toBe(beforeRelationship);
+      expect(pool._liveCount()).toBe(0);
+    } finally {
+      Object.defineProperty(pool, 'alloc', { configurable: true, value: originalAlloc });
+    }
+  });
 });

package/src/__tests__/shared-ref-store.unit.test.ts

@@ -70,7 +70,6 @@ describe('w6 SharedRefStore: alloc + resolve', () => {
     expect(store.markChanged(handle).ok).toBe(true);
     expect(store.getMutationEpoch()).toBe(1);
     expect(store.readChangesSince(0)).toEqual({
-      status: 'ok',
       cursor: 1,
       records: [{ epoch: 1, handle: unwrapHandle(handle) }],
     });
@@ -80,21 +79,17 @@ describe('w6 SharedRefStore: alloc + resolve', () => {
     expect(store.getMutationEpoch()).toBe(1);
   });
 
-  it('reports bounded-journal overflow instead of hiding changed handles', () => {
+  it('keeps one latest mutation epoch per handle without a bounded journal', () => {
     const store = new SharedRefStore();
     const handle = store.alloc('MaterialAsset', { value: 1 });
     for (let index = 0; index < 4097; index += 1) store.markChanged(handle).unwrap();
 
     expect(store.readChangesSince(0)).toEqual({
-      status: 'overflow',
       cursor: 4097,
-      oldestAvailable: 2,
+      records: [{ epoch: 4097, handle: unwrapHandle(handle) }],
     });
     const latest = store.readChangesSince(4096);
-    expect(latest.status).toBe('ok');
-    if (latest.status === 'ok') {
-      expect(latest.records).toEqual([{ epoch: 4097, handle: unwrapHandle(handle) }]);
-    }
+    expect(latest.records).toEqual([{ epoch: 4097, handle: unwrapHandle(handle) }]);
   });
 
   it('resolve returns SharedRefStaleError after rc drops to 0 (gen incremented on release)', () => {

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

@@ -0,0 +1,6 @@
+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

@@ -0,0 +1,49 @@
+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/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

@@ -392,12 +392,15 @@ export type ManagedArrayElementValue<T extends ManagedArrayElementType> = T exte
  *
  * The 4 buffer/array keywords (`'buffer'` / `'buffer<N>'` / `'array<T>'` /
  * `'array<T, N>'`) all resolve directly to a concrete TypedArray (or
- * Uint8Array for the byte-only buffer family). The materialised value is a
- * read-only snapshot: for fixed `buffer<N>` / `array<T,N>` it aliases the
- * inline column buffer (feat-20260602); for variable `buffer` / `array<T>`
- * it aliases the BufferPool slot bytes (plan-strategy §2.2 D-R3 contract).
- * Mutation flows through `world.set` / `world.push` / `world.pop`
- * not direct assignment to the returned TypedArray.
+ * Uint8Array for the byte-only buffer family). At the public `world.get`
+ * boundary, a relationship-target `array<entity>` is a detached `Uint32Array`
+ * snapshot. Other public array fields retain their existing transient live
+ * TypedArray alias: fixed `buffer<N>` / `array<T,N>` values alias the inline
+ * column buffer (feat-20260602), while variable `buffer` / `array<T>` values
+ * alias the BufferPool slot bytes. Internal `readRow`, `_getArrayView`, and
+ * `materializeArrayView` paths always use the live zero-copy alias. Mutation
+ * flows through `world.set` / `world.push` / `world.pop`, not direct
+ * assignment to a returned TypedArray.
  *
  * The `'string'` arm resolves to a native JS `string` (D-R1 / AC-13): the
  * dispatch routes the column u32 through `UniqueRefStore.resolve(handle)`
@@ -930,7 +933,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 +1001,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 +1180,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,10 @@ 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'
+  | 'relationship-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,59 @@
+// @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';
+export type { WorldInternal } from './world-internal';
+export { worldInternal } from './world-internal';
+
+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,
+  DerivedRangeCursor,
+  DerivedRangeRowCommit,
+  DerivedRangeRowProbe,
+  DerivedRangeWriter,
+} from './query/derived-range-writer';