@forgeax/engine-ecs 0.0.0-dev.8d955ade1c79

package/src/__tests__/component-nan-preflight.unit.test.ts

@@ -0,0 +1,186 @@
+import { describe, expect, it } from 'vitest';
+import { defineComponent } from '../component';
+import { defineRelationship } from '../relationship-index';
+import { Update } from '../schedule-token';
+import { World } from '../world';
+
+const Marker = defineComponent('NanPreflightMarker', {});
+const Numeric = defineComponent('NanPreflightNumeric', {
+  scalar: 'f32',
+  values: 'array<f32>',
+});
+const InlineNumeric = defineComponent('NanPreflightInlineNumeric', {
+  scalar: 'f32',
+  values: 'array<f32, 2>',
+});
+const { source: ParentOf, target: ChildrenOf } = defineRelationship({
+  sourceName: 'NanPreflightParentOf',
+  sourceField: 'parent',
+  targetName: 'NanPreflightChildrenOf',
+  targetField: 'children',
+});
+
+interface NumericValueError {
+  readonly code: string;
+  readonly detail: {
+    readonly component: string;
+    readonly field: string;
+    readonly received: unknown;
+    readonly index?: number;
+  };
+}
+
+function expectNumericValueError(
+  error: unknown,
+  expected: { readonly field: string; readonly received: unknown; readonly index?: number },
+): void {
+  expect(error).toBeDefined();
+  if (error === undefined) return;
+  const numericError = error as NumericValueError;
+  expect(numericError.code).toBe('component-numeric-value-invalid');
+  expect(numericError.detail).toMatchObject({
+    component: Numeric.name,
+    field: expected.field,
+    received: expected.received,
+    ...(expected.index === undefined ? {} : { index: expected.index }),
+  });
+}
+
+describe('component NaN object-write preflight', () => {
+  it('rejects spawn scalar NaN before entity or relationship mutation', () => {
+    const world = new World();
+    const parent = world.spawn({ component: Marker, data: {} }).unwrap();
+    const beforeCount = world.inspect().entityCount;
+    const beforeEpoch = world.getStructureEpoch();
+
+    const result = world.spawn(
+      { component: Numeric, data: { scalar: Number.NaN, values: [1, 2] } },
+      { component: ParentOf, data: { parent } },
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok)
+      expectNumericValueError(result.error, { field: 'scalar', received: Number.NaN });
+    expect(world.inspect().entityCount).toBe(beforeCount);
+    expect(world.getStructureEpoch()).toBe(beforeEpoch);
+    expect(world.get(parent, ChildrenOf).ok).toBe(false);
+  });
+
+  it('rejects addComponent array NaN before archetype or managed-array mutation', () => {
+    const world = new World();
+    const entity = world.spawn({ component: Marker, data: {} }).unwrap();
+    const beforeEpoch = world.getStructureEpoch();
+
+    const result = world.addComponent(entity, {
+      component: Numeric,
+      data: { scalar: 3, values: [1, Number.NaN] },
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expectNumericValueError(result.error, {
+        field: 'values',
+        received: Number.NaN,
+        index: 1,
+      });
+    }
+    expect(world.get(entity, Numeric).ok).toBe(false);
+    expect(world.getStructureEpoch()).toBe(beforeEpoch);
+  });
+
+  it('rejects set array NaN and preserves the complete old value', () => {
+    const world = new World();
+    const entity = world
+      .spawn({ component: Numeric, data: { scalar: 4, values: [1, 2] } })
+      .unwrap();
+
+    const result = world.set(entity, Numeric, { values: [7, Number.NaN] });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expectNumericValueError(result.error, {
+        field: 'values',
+        received: Number.NaN,
+        index: 1,
+      });
+    }
+    const current = world.get(entity, Numeric).unwrap();
+    expect(current.scalar).toBe(4);
+    expect(Array.from(current.values)).toEqual([1, 2]);
+  });
+
+  it('rejects QueryRow.mut scalar NaN and preserves the old field', () => {
+    const world = new World();
+    const entity = world
+      .spawn({ component: Numeric, data: { scalar: 5, values: [1, 2] } })
+      .unwrap();
+    const row = world
+      .query({ write: [Numeric] })
+      .unwrap()
+      .at(entity);
+    expect(row).toBeDefined();
+    let thrown: unknown;
+
+    try {
+      if (row !== undefined) row.mut(Numeric).scalar = Number.NaN;
+    } catch (error) {
+      thrown = error;
+    }
+
+    expectNumericValueError(thrown, { field: 'scalar', received: Number.NaN });
+    expect(world.get(entity, Numeric).unwrap().scalar).toBe(5);
+  });
+
+  it('rejects a deferred command before adding the component', () => {
+    const world = new World();
+    const entity = world.spawn({ component: Marker, data: {} }).unwrap();
+    world
+      .addSystem(Update, {
+        name: 'nan-preflight-command',
+        queries: [],
+        fn: (_world, _queries, commands) => {
+          commands.addComponent(entity, {
+            component: Numeric,
+            data: { scalar: Number.NaN, values: [1, 2] },
+          });
+        },
+      })
+      .unwrap();
+
+    const result = world.update(0);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('command-failed');
+      if (result.error.code === 'command-failed') {
+        expectNumericValueError(result.error.detail.cause, {
+          field: 'scalar',
+          received: Number.NaN,
+        });
+      }
+    }
+    expect(world.get(entity, Numeric).ok).toBe(false);
+    expect(world.execution.health).toBe('healthy');
+  });
+
+  it('accepts positive Infinity while leaving QuerySpan as the raw numeric boundary', () => {
+    const world = new World({ storage: 'shared' });
+    const entity = world
+      .spawn({
+        component: InlineNumeric,
+        data: { scalar: Number.POSITIVE_INFINITY, values: [Number.POSITIVE_INFINITY, 2] },
+      })
+      .unwrap();
+    expect(world.set(entity, InlineNumeric, { scalar: Number.POSITIVE_INFINITY }).ok).toBe(true);
+    expect(world.get(entity, InlineNumeric).unwrap().scalar).toBe(Number.POSITIVE_INFINITY);
+
+    const spans = world
+      .query({ write: [InlineNumeric] })
+      .unwrap()
+      .spans()
+      .unwrap();
+    for (const span of spans) span.mut(InlineNumeric).scalar[0] = Number.NaN;
+
+    expect(world.get(entity, InlineNumeric).unwrap().scalar).toBeNaN();
+  });
+});

package/src/__tests__/component-schema.test-d.ts

@@ -0,0 +1,119 @@
+// Compile-time + runtime test for Component field-schema literal preservation +
+// 4-probe quintet over SchemaVocabKeyword (w3, AC-09).
+//
+// Locks two invariants:
+//
+//   1. Literal preservation: defineComponent('Foo', { value: 'string' } as
+//      const) yields `SchemaOf<typeof Foo>['value']` typed as the literal `'string'`,
+//      not widened to plain `string`. AI users that read
+//      `SchemaOf<typeof Component>` gets the schema keyword as a literal
+//      type --- the basis of `isManagedField` switch / cascade discrimination.
+//
+//   2. 4-probe quintet (w4, plan-strategy §2.2 / D-R3 predicate merge):
+//      The legacy string-only + ref-only probes collapse into a single
+//      `isManagedField` arm covering both `'string'` and `'unique<T>'`. The
+//      remaining probes target the other SchemaVocabKeyword tiers:
+//        isManagedField        => 'string' | 'unique<T>'   (NEW unified arm)
+//        isManagedBufferField  => 'buffer' / 'buffer<N>'
+//        isEntityField         => 'entity'
+//        isManagedArrayField   => 'array<T,N>' / 'array<T>'
+//      AI users grep `isXxxField` once and get the discrimination toolkit.
+
+import { describe, expectTypeOf, it } from 'vitest';
+import {
+  defineComponent,
+  isEntityField,
+  isManagedArrayField,
+  isManagedBufferField,
+  isManagedField,
+  type SchemaOf,
+  type SchemaVocabKeyword,
+} from '../component';
+
+describe('component schema --- literal preservation (w3, AC-09)', () => {
+  it("defineComponent('Foo', { value: 'string' }) preserves 'string' literal", () => {
+    const Foo = defineComponent('Foo', { value: 'string' });
+    type ValueField = SchemaOf<typeof Foo>['value'];
+    expectTypeOf<ValueField>().toEqualTypeOf<'string'>();
+
+    // The token intentionally exposes only name/fields/storage. These
+    // negative probes keep removed convenience facts out of autocomplete.
+    // @ts-expect-error Component.schema was removed; use SchemaOf<typeof Foo>.
+    void Foo.schema;
+    // @ts-expect-error Component.id is an ECS-owner fact, not token data.
+    void Foo.id;
+    // @ts-expect-error Component.defaults lives in componentDefinition(Foo).
+    void Foo.defaults;
+    // @ts-expect-error Component.toSchemaJSON was removed with the duplicate projection.
+    void Foo.toSchemaJSON;
+  });
+
+  it('schema literal is *not* widened to plain `string`', () => {
+    const Foo = defineComponent('Foo', { value: 'string' });
+    type ValueField = SchemaOf<typeof Foo>['value'];
+    // The literal must NOT widen to base `string` --- AI users rely on the
+    // narrow type for switch / cascade discrimination.
+    expectTypeOf<ValueField>().not.toEqualTypeOf<string>();
+  });
+
+  it('multi-field schemas preserve every keyword literal', () => {
+    const Bar = defineComponent('Bar', {
+      name: 'string',
+      mass: 'f32',
+      target: 'entity',
+    });
+    expectTypeOf<SchemaOf<typeof Bar>['name']>().toEqualTypeOf<'string'>();
+    expectTypeOf<SchemaOf<typeof Bar>['mass']>().toEqualTypeOf<'f32'>();
+    expectTypeOf<SchemaOf<typeof Bar>['target']>().toEqualTypeOf<'entity'>();
+  });
+});
+
+describe('component schema --- 4-probe quintet (w3, AC-09)', () => {
+  it('all four probes have signature `(s: string) => boolean`', () => {
+    expectTypeOf(isManagedField).toEqualTypeOf<(s: string) => boolean>();
+    expectTypeOf(isManagedBufferField).toEqualTypeOf<(s: string) => boolean>();
+    expectTypeOf(isEntityField).toEqualTypeOf<(s: string) => boolean>();
+    expectTypeOf(isManagedArrayField).toEqualTypeOf<(s: string) => boolean>();
+  });
+
+  it("isManagedField recognises 'string' literal and 'unique<T>' template", () => {
+    // Behavioural assertions (AC-09) --- the unified arm must cover both
+    // `'string'` and `'unique<T>'` keywords in a single predicate.
+    expectTypeOf(isManagedField('string')).toEqualTypeOf<boolean>();
+    expectTypeOf(isManagedField('unique<MeshAsset>')).toEqualTypeOf<boolean>();
+    // Runtime cases:
+    if (!isManagedField('string')) throw new Error("isManagedField('string') must be true");
+    if (!isManagedField('unique<MeshAsset>'))
+      throw new Error("isManagedField('unique<MeshAsset>') must be true");
+    if (isManagedField('entity')) throw new Error("isManagedField('entity') must be false");
+    if (isManagedField('buffer<128>'))
+      throw new Error("isManagedField('buffer<128>') must be false");
+    // 'buffer' bare keyword is not a SchemaVocabKeyword but the predicate
+    // must still reject it (defensive for the erased runtime call site).
+    if (isManagedField('buffer')) throw new Error("isManagedField('buffer') must be false");
+  });
+
+  it('SchemaVocabKeyword closed union has 7 members covered by 4 probes', () => {
+    // Mapping (membership <-> probe):
+    //   buffer / buffer<N> => isManagedBufferField
+    //   ref<T>             => isManagedField   (NEW unified arm w/ 'string')
+    //   handle<T>          => (no managed probe; ECS treats handles as opaque)
+    //   entity             => isEntityField
+    //   array<T,N> + array<T> => isManagedArrayField (counts as one)
+    //   string             => isManagedField   (NEW unified arm w/ 'unique<T>')
+    //
+    // The closed union still has exactly 7 template-literal arms; we lock
+    // the union shape so any drift (e.g. removing one arm or adding a
+    // sixth probe family) shows up as a type error.
+    type Sample =
+      | 'buffer<128>'
+      | 'unique<MaterialAsset>'
+      | 'shared<MeshAsset>'
+      | 'entity'
+      | 'array<f32, 16>'
+      | 'array<u32>'
+      | 'string';
+    // Every member of `Sample` is assignable to `SchemaVocabKeyword`.
+    expectTypeOf<Sample>().toMatchTypeOf<SchemaVocabKeyword>();
+  });
+});

package/src/__tests__/component-schema.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'vitest';
+import { defineComponent } from '../component';
+import { assertComponentStorage, componentDefinition, deepFreeze } from '../component-schema';
+
+describe('component schema contract', () => {
+  it('deep freezes nested field facts and owner defaults', () => {
+    const component = defineComponent('SchemaFreeze', {
+      mode: { type: 'enum', default: 1, labels: { idle: 0, run: 1 } },
+      payload: { type: 'array<f32, 2>', default: [1, 2] as never },
+    });
+
+    expect(Object.isFrozen(component.fields)).toBe(true);
+    expect(Object.isFrozen(component.fields.mode)).toBe(true);
+    expect(Object.isFrozen(component.fields.mode?.labels)).toBe(true);
+    const defaults = componentDefinition(component).defaults;
+    expect(Object.isFrozen(defaults)).toBe(true);
+    expect(Object.isFrozen(defaults?.payload)).toBe(true);
+  });
+
+  it('keeps the public token surface to name, fields, and storage', () => {
+    const component = defineComponent('ComponentSurface', { value: 'f32' });
+    expect(Object.keys(component)).toEqual(['name', 'fields', 'storage']);
+    expect(Reflect.ownKeys(component)).toEqual(['name', 'fields', 'storage']);
+    expect(Object.getPrototypeOf(component)).toBe(Object.prototype);
+    expect('schema' in component).toBe(false);
+    expect('id' in component).toBe(false);
+    expect('defaults' in component).toBe(false);
+    expect('toSchemaJSON' in component).toBe(false);
+  });
+
+  it('accepts only the closed table/sparse storage vocabulary', () => {
+    expect(() => assertComponentStorage('table')).not.toThrow();
+    expect(() => assertComponentStorage('sparse')).not.toThrow();
+    expect(() => assertComponentStorage('columnar')).toThrow(/Expected 'table' or 'sparse'/);
+    expect(deepFreeze({ nested: { value: 1 } }).nested).toEqual({ value: 1 });
+  });
+
+  it('treats typed arrays and ArrayBuffer as immutable leaf projections', () => {
+    const values = new Float32Array([1, 2]);
+    const buffer = new ArrayBuffer(8);
+
+    const projected = deepFreeze({ values, buffer });
+    expect(Object.isFrozen(projected)).toBe(true);
+    expect(Object.isFrozen(values)).toBe(false);
+    expect(Object.isFrozen(buffer)).toBe(false);
+    expect(values[0]).toBe(1);
+    expect(buffer.byteLength).toBe(8);
+  });
+
+  it('rejects an invalid runtime storage value before registration', () => {
+    expect(() => defineComponent('InvalidStorage', {}, { storage: 'columnar' as 'table' })).toThrow(
+      /Expected 'table' or 'sparse'/,
+    );
+  });
+});

package/src/__tests__/define-component-options.test-d.ts

@@ -0,0 +1,35 @@
+// Compile-time type-derivation tests for the DefineComponentOptions surface
+// after the M1 buffer/array vocab collapse (w3, AC-05).
+//
+// Locks the `arrayStride` option-bit removal: passing an `arrayStride` map
+// to `defineComponent`'s third options arg is a TS compile-time error after
+// w5. The stride contract migrates to RenderSystem-extract entry-site
+// defensive plus AI user set-site responsibility (plan-strategy §2.3).
+//
+// Pre-M1 (before w5): `arrayStride: { ... }` is a valid option on
+// `DefineComponentOptions` and the @ts-expect-error directive is unsatisfied
+// (TDD red state).
+//
+// Post-M1 (after w5): the option is removed; the directive is satisfied; the
+// surface is narrower.
+
+import { describe, it } from 'vitest';
+import { type DefineComponentOptions, defineComponent } from '../component';
+
+describe('DefineComponentOptions — arrayStride option-bit removed (w3, AC-05)', () => {
+  it('arrayStride is no longer a key on DefineComponentOptions', () => {
+    type Opts = DefineComponentOptions;
+    // @ts-expect-error 'arrayStride' is no longer a key on DefineComponentOptions
+    // after feat-20260515 w5 (stride responsibility migrated to RenderSystem
+    // extract entry).
+    const opts: Opts = { arrayStride: { f: 16 } };
+    void opts;
+  });
+
+  it('defineComponent rejects arrayStride at the call-site', () => {
+    // @ts-expect-error 'arrayStride' is no longer accepted by defineComponent
+    // after feat-20260515 w5.
+    const Bar = defineComponent('Bar', { f: { type: 'array<f32>' } }, { arrayStride: { f: 16 } });
+    void Bar;
+  });
+});

package/src/__tests__/deprecated-vocab-rejection.unit.test.ts

@@ -0,0 +1,59 @@
+// feat-20260614 M5 / w25 — runtime rejection tests for the two retired
+// schema-vocab keyword families. Both renames preserve brand and storage
+// layout; only the keyword + dispatch arm changed. The
+// SchemaUnsupportedFieldError migration hint redirects AI users straight
+// to the new keyword (charter F1 single-entry indexability).
+//
+//   'ref<T>'    -> hint contains 'unique<T>'   (M1 rename)
+//   'handle<T>' -> hint contains 'shared<T>'   (M5 cut)
+//
+// AC-14 (requirements): writing either deprecated literal to defineComponent
+// must throw a structured error with the migration hint pointing at the
+// replacement keyword.
+
+import { describe, expect, it } from 'vitest';
+import { defineComponent } from '../component';
+
+describe('w25 deprecated schema-vocab rejection', () => {
+  it("'handle<MeshAsset>' throws SchemaUnsupportedFieldError + hint mentions 'shared<MeshAsset>'", () => {
+    // gate-allow:ecs-brand
+    let caught: unknown;
+    try {
+      defineComponent('w25HandleSample', { f: { type: 'handle<MeshAsset>' } } as never); // gate-allow:ecs-brand
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).toBeDefined();
+    const e = caught as { code: string; hint: string };
+    expect(e.code).toBe('schema-unsupported-field');
+    expect(e.hint).toContain("'shared<MeshAsset>'");
+    expect(e.hint).toContain('feat-20260614 M5');
+  });
+
+  it("'ref<PhysicsBody>' throws SchemaUnsupportedFieldError + hint mentions 'unique<PhysicsBody>'", () => {
+    // gate-allow:ecs-brand
+    let caught: unknown;
+    try {
+      defineComponent('w25RefSample', { f: { type: 'ref<PhysicsBody>' } } as never); // gate-allow:ecs-brand
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).toBeDefined();
+    const e = caught as { code: string; hint: string };
+    expect(e.code).toBe('schema-unsupported-field');
+    expect(e.hint).toContain("'unique<PhysicsBody>'");
+    expect(e.hint).toContain('feat-20260614 M1');
+  });
+
+  it("'shared<MeshAsset>' is accepted (the new keyword still works)", () => {
+    expect(() => {
+      defineComponent('w25SharedSample', { f: { type: 'shared<MeshAsset>' } });
+    }).not.toThrow();
+  });
+
+  it("'unique<PhysicsBody>' is accepted (the new keyword still works)", () => {
+    expect(() => {
+      defineComponent('w25UniqueSample', { f: { type: 'unique<PhysicsBody>' } });
+    }).not.toThrow();
+  });
+});

package/src/__tests__/despawn-all.unit.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from 'vitest';
+
+import { defineComponent, World } from '../index';
+
+describe('World.despawnAll', () => {
+  it('routes every live entity through normal despawn cleanup', () => {
+    const Marker = defineComponent('DespawnAllMarker', { value: 'u32' });
+    const world = new World();
+    world.spawn({ component: Marker, data: { value: 1 } }).unwrap();
+    world.spawn({ component: Marker, data: { value: 2 } }).unwrap();
+
+    const result = world.despawnAll();
+
+    expect(result.ok).toBe(true);
+    expect(world.inspect().entityCount).toBe(0);
+  });
+});

package/src/__tests__/ecs-core-reduction.characterization.test.ts

@@ -0,0 +1,130 @@
+import { defineComponent, defineRelationship, Update, World } from '@forgeax/engine-ecs';
+import { describe, expect, it } from 'vitest';
+
+const { source: ChildOf, target: Children } = defineRelationship({
+  sourceName: 'ReductionChildOf',
+  sourceField: 'parent',
+  targetName: 'ReductionChildren',
+  targetField: 'entities',
+});
+const { source: AnimatedBy, target: AnimationTargets } = defineRelationship({
+  sourceName: 'ReductionAnimatedBy',
+  sourceField: 'player',
+  targetName: 'ReductionAnimationTargets',
+  targetField: 'targets',
+});
+
+describe('M0 ECS reduction characterization', () => {
+  it('F-01: exposes pending reservations after a system throws', () => {
+    const Marker = defineComponent('M0PendingMarker', {});
+    const world = new World();
+
+    world.addSystem(Update, {
+      name: 'throw-after-reservation',
+      queries: [],
+      fn: (_world, _queries, commands) => {
+        commands.spawn({ component: Marker, data: {} });
+        throw new Error('M0 system failure');
+      },
+    });
+
+    const result = world.update(0);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('system-failed');
+      if (result.error.code === 'system-failed') {
+        expect(result.error.detail.cause).toBeInstanceOf(Error);
+      }
+    }
+    expect(world.execution.health).toBe('poisoned');
+  });
+
+  it('F-02: preserves a failed command result at the public update boundary', () => {
+    const Marker = defineComponent('M0CommandMarker', {});
+    const world = new World();
+    const entity = world.spawn({ component: Marker, data: {} }).unwrap();
+    const before = world.inspect().entityCount;
+
+    world.addSystem(Update, {
+      name: 'duplicate-component-command',
+      queries: [],
+      fn: (_world, _queries, commands) => {
+        commands.addComponent(entity, { component: Marker, data: {} });
+      },
+    });
+
+    const result = world.update(0);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('command-failed');
+      if (result.error.code === 'command-failed') {
+        expect(result.error.detail.systemName).toBe('duplicate-component-command');
+        expect(result.error.detail.commandKind).toBe('addComponent');
+        expect((result.error.detail.cause as { readonly code?: string }).code).toBe(
+          'component-already-present',
+        );
+      }
+    }
+    expect(world.execution.health).toBe('healthy');
+    expect(world.inspect().entityCount).toBe(before);
+  });
+
+  it('F-03: despawn does not own shared payload disposal', () => {
+    const world = new World();
+    const payload = { id: 1 };
+    const handle = world.allocSharedRef('M0Asset', payload);
+    const Holder = defineComponent('M0SharedHolder', { asset: 'shared<M0Asset>' });
+    const entity = world.spawn({ component: Holder, data: { asset: handle } }).unwrap();
+    world.sharedRefs.release(handle).unwrap();
+
+    expect(() => world.despawn(entity)).not.toThrow();
+    expect(world.sharedRefs.readReleaseEvidence()).toEqual([
+      { payload, refcount: 0, generation: 1, evidence: 'released' },
+    ]);
+  });
+
+  it('F-07: rejects undefined shared payloads before allocating a slot', () => {
+    const world = new World();
+    expect(() => world.allocSharedRef('M0UndefinedAsset', undefined)).toThrow();
+  });
+
+  it('T-02: rejects an invalid managed-array payload without a row delta', () => {
+    const Values = defineComponent('M0ManagedValues', { values: 'array<f32>' });
+    const world = new World();
+    const beforeEntityCount = world.inspect().entityCount;
+    const beforeEpoch = world.getStructureEpoch();
+
+    const result = world.spawn({
+      component: Values,
+      data: { values: { invalid: true } as never },
+    });
+
+    expect(result.ok).toBe(false);
+    expect(world.inspect().entityCount).toBe(beforeEntityCount);
+    expect(world.getStructureEpoch()).toBe(beforeEpoch);
+  });
+
+  it('keeps ChildOf/Children and AnimatedBy/AnimationTargets as materialized target pairs', () => {
+    const world = new World();
+    const parent = world.spawn({ component: Children, data: { entities: [] } }).unwrap();
+    const child = world.spawn({ component: ChildOf, data: { parent } }).unwrap();
+    const children = world.get(parent, Children).unwrap().entities;
+    expect([...children]).toContain(child);
+
+    const player = world.spawn({ component: AnimationTargets, data: { targets: [] } }).unwrap();
+    const target = world.spawn({ component: AnimatedBy, data: { player } }).unwrap();
+    const targets = world.get(player, AnimationTargets).unwrap().targets;
+    expect([...targets]).toContain(target);
+
+    const childrenEpoch = world.getStructureEpoch();
+    // Relationship target components are intentionally not writable through
+    // the typed mutation facade; the runtime returns a structured refusal.
+    // @ts-expect-error relationship target is a read-only projection.
+    const targetWrite = world.set(parent, Children, { entities: [] });
+    // @ts-expect-error relationship target is a read-only projection.
+    const animationTargetWrite = world.set(player, AnimationTargets, { targets: [] });
+    expect(childrenEpoch).toBeLessThanOrEqual(world.getStructureEpoch());
+    expect(targetWrite.ok).toBe(false);
+    expect(animationTargetWrite.ok).toBe(false);
+  });
+});