@codehz/ecs 0.8.1 → 0.9.0

package/src/__tests__/serialization/bounds.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from "bun:test";
-import { component, type EntityId } from "../../entity";
+import { component, relation, type EntityId } from "../../entity";
+import { decodeSerializedId, encodeEntityId, encodeEntityIdCached } from "../../storage/serialization";
 import { World } from "../../world/world";
 
 describe("Serialization edge cases", () => {
@@ -234,4 +235,136 @@ describe("Serialization edge cases", () => {
     expect(newWorld.has(e3, Position)).toBe(false);
     expect(newWorld.get(e3, Velocity)).toEqual({ vx: 15 });
   });
+
+  it("should serialize and deserialize singleton components (covers componentEntities paths)", () => {
+    const world = new World();
+    const Config = component<{ debug: boolean }>();
+    // Singleton shorthand populates internal component entity
+    world.set(Config, { debug: true });
+    world.sync();
+
+    const snapshot = world.serialize();
+    const restored = new World(snapshot);
+
+    expect(restored.has(Config)).toBe(true);
+    expect(restored.get(Config)).toEqual({ debug: true });
+  });
+
+  it("should round-trip anonymous (no-name) components in entity-relations and component-relations", () => {
+    const world = new World();
+    const A = component<{ v: number }>(); // anonymous -> triggers numeric fallback + warn paths
+    const B = component<string>(); // also anonymous for target in comp-rel
+    const e1 = world.new();
+    const e2 = world.new();
+    const relE = relation(A, e1);
+    const relC = relation(A, B);
+    world.set(e2, relE, { v: 42 });
+    world.set(e2, relC, { v: 99 });
+    world.sync();
+
+    const snap = world.serialize();
+    const r = new World(snap);
+
+    expect(r.has(e2, relE)).toBe(true);
+    expect(r.get(e2, relE)).toEqual({ v: 42 });
+    expect(r.has(e2, relC)).toBe(true);
+    expect(r.get(e2, relC)).toEqual({ v: 99 });
+  });
+
+  describe("Serialization ID codec (low-level, covers all decode/encode branches)", () => {
+    it("should exercise cache hit/miss and no-cache path in encodeEntityIdCached", () => {
+      const C = component<number>();
+      const cache = new Map();
+      const c1 = encodeEntityIdCached(C, cache);
+      const c2 = encodeEntityIdCached(C, cache);
+      expect(c2).toBe(c1); // hit
+      const noCache = encodeEntityIdCached(C); // else branch (no cache provided)
+      expect(noCache).toBeDefined();
+      // also wrapper
+      expect(encodeEntityId(C)).toBeDefined();
+    });
+
+    it("should round-trip all relation kinds including wildcard via encode/decode", () => {
+      const C = component<boolean>();
+      const E = 9999 as EntityId<any>;
+      const relE = relation(C, E);
+      const C2 = component<string>();
+      const relC = relation(C, C2);
+      const wild = relation(C, "*");
+
+      expect(decodeSerializedId(encodeEntityId(relE))).toBe(relE);
+      expect(decodeSerializedId(encodeEntityId(relC))).toBe(relC);
+      expect(decodeSerializedId(encodeEntityId(wild))).toBe(wild);
+    });
+
+    it("should hit numeric string fallbacks and all error throws in decode", () => {
+      const C1 = component<number>();
+      const C2 = component<string>();
+      const id1 = C1 as unknown as number;
+      const id2 = C2 as unknown as number;
+
+      // numeric fallback paths (when name lookup fails; use real allocated IDs as strings)
+      expect(decodeSerializedId(String(id1) as any)).toBe(id1 as any);
+      expect(decodeSerializedId({ component: String(id2), target: 99999 } as any)).toBeDefined(); // component-relation numeric fallback; creates valid relation(C2, fakeTarget)
+
+      // error paths (unknown names hit throws before relation() ctor)
+      expect(() => decodeSerializedId("TotallyUnknownName!!" as any)).toThrow(/Unknown component name in snapshot/);
+      expect(() => decodeSerializedId({ component: "BadName", target: 1 } as any)).toThrow(
+        /Unknown component name in snapshot/,
+      );
+      expect(() => decodeSerializedId({ component: "123", target: "BadTargetName" } as any)).toThrow(
+        /Unknown target component name in snapshot/,
+      );
+      expect(() => decodeSerializedId({ foo: "bar" } as any)).toThrow(/Invalid ID in snapshot/);
+    });
+  });
+
+  describe("Entity-ID-as-componentType references (ad-hoc entity refs)", () => {
+    it("should round-trip worlds using raw EntityIds as component types (covers 'entity' branch in deserialize reference tracking)", () => {
+      const world = new World();
+
+      const eTarget = world.new();
+      const eHolder = world.new();
+
+      // Use a raw entity ID (>= ENTITY_ID_START) directly as a component "type".
+      // This models an untyped/ad-hoc reference to another entity.
+      // The value is omitted (void presence-only component).
+      world.set(eHolder, eTarget as unknown as EntityId<any>);
+      world.sync();
+
+      const snapshot = world.serialize();
+      const restored = new World(snapshot);
+
+      expect(restored.exists(eTarget)).toBe(true);
+      expect(restored.exists(eHolder)).toBe(true);
+
+      // The ad-hoc component must survive the roundtrip.
+      expect(restored.has(eHolder, eTarget as unknown as EntityId<any>)).toBe(true);
+    });
+  });
+
+  describe("ComponentEntities deserialization guards", () => {
+    it("should ignore componentEntities snapshot entries whose id is not a real component entity (covers continue guard)", () => {
+      const world = new World();
+      const Config = component<{ debug: boolean }>();
+      world.set(Config, { debug: true });
+      world.sync();
+
+      const snap: any = world.serialize();
+
+      // Inject a bogus entry: a high ordinary entity id (never a component entity)
+      const bogus = 123456 as EntityId;
+      snap.componentEntities = snap.componentEntities || [];
+      snap.componentEntities.push({
+        id: bogus,
+        components: [{ type: 99, value: "should-be-ignored" }],
+      });
+
+      const restored = new World(snap);
+
+      // Real singleton still works; bogus entry was skipped without error
+      expect(restored.has(Config)).toBe(true);
+      expect(restored.get(Config)).toEqual({ debug: true });
+    });
+  });
 });

package/src/__tests__/world/commands.test.ts

@@ -0,0 +1,337 @@
+import { describe, expect, it } from "bun:test";
+import { Archetype } from "../../archetype/archetype";
+import { SparseStoreImpl } from "../../archetype/store";
+import { ComponentChangeset } from "../../commands/changeset";
+import { component, createEntityId, relation, type ComponentId, type EntityId } from "../../entity";
+import {
+  applyChangeset,
+  areComponentTypesEqual,
+  filterRegularComponentTypes,
+  maybeRemoveWildcardMarker,
+  type CommandProcessorContext,
+} from "../../world/commands";
+import { World } from "../../world/world";
+
+function createSparseStore() {
+  return new SparseStoreImpl();
+}
+
+function makeArchetype(componentTypes: EntityId<any>[]): Archetype {
+  return new Archetype(componentTypes, createSparseStore());
+}
+
+function makeCtx(): CommandProcessorContext {
+  const store = createSparseStore();
+  return {
+    sparseStore: store,
+    ensureArchetype: (types) => new Archetype(Array.from(types), store),
+  };
+}
+
+describe("world/commands internal coverage", () => {
+  const A = component<number>();
+  const B = component<string>();
+  const Tag = component({ dontFragment: true });
+  const Data = component<{ v: number }>({ dontFragment: true });
+  const ExclusiveTag = component({ dontFragment: true, exclusive: true });
+
+  describe("areComponentTypesEqual", () => {
+    it("returns true for equal arrays (same order)", () => {
+      expect(areComponentTypesEqual([A, B], [A, B])).toBe(true);
+    });
+
+    it("returns true for equal arrays after normalization (different order)", () => {
+      expect(areComponentTypesEqual([B, A], [A, B])).toBe(true);
+    });
+
+    it("returns false for different lengths", () => {
+      expect(areComponentTypesEqual([A], [A, B])).toBe(false);
+    });
+
+    it("returns false for different content after normalization", () => {
+      expect(areComponentTypesEqual([A, B], [A, Tag])).toBe(false);
+    });
+  });
+
+  describe("filterRegularComponentTypes", () => {
+    it("keeps wildcard markers for dontFragment and drops specific dontFragment relations", () => {
+      const wild = relation(Tag, "*");
+      const specific = relation(Tag, createEntityId(9999) as EntityId);
+      const result = filterRegularComponentTypes([A, specific, wild, B]);
+      // specific dontFragment relation should be filtered out; wildcard marker kept
+      expect(result).toContain(wild);
+      expect(result).toContain(A);
+      expect(result).toContain(B);
+      expect(result).not.toContain(specific);
+    });
+  });
+
+  describe("removeMatchingRelations + maybeRemoveWildcardMarker (marker retention)", () => {
+    it("keeps wildcard marker when removing one of multiple non-exclusive dontFragment relations (archetype path)", () => {
+      const store = createSparseStore();
+      const p1 = createEntityId(2001) as EntityId;
+      const p2 = createEntityId(2002) as EntityId;
+      const r1 = relation(Tag, p1);
+      const r2 = relation(Tag, p2);
+      const wild = relation(Tag, "*");
+
+      // Archetype declares the wildcard marker (as required for dontFragment)
+      const arch = new Archetype([A, wild], store);
+      const entity = createEntityId(5001) as EntityId;
+
+      // Put the entity in the archetype with two concrete relations stored in dontFragment store
+      arch.addEntity(entity, new Map([[A, 1]]));
+      store.setValue(entity, r1, undefined);
+      store.setValue(entity, r2, undefined);
+
+      const changeset = new ComponentChangeset();
+      // Remove only one target
+      changeset.delete(r1);
+
+      // Call the function under test (simulates what processDeleteCommand does for non-wildcard delete)
+      maybeRemoveWildcardMarker(entity, arch, r1, Tag as unknown as ComponentId<any>, changeset);
+
+      // Marker must NOT have been scheduled for removal
+      expect(changeset.removes.has(wild)).toBe(false);
+      // We only mutated changeset; the store still contains the other relation entry
+      // (presence is observable via getAllForEntity because value may legitimately be undefined for tags)
+      const remaining = store.getAllForEntity(entity).some(([t]) => t === r2);
+      expect(remaining).toBe(true);
+    });
+
+    it("keeps wildcard marker when other relation exists only in dontFragmentData for the entity", () => {
+      const store = createSparseStore();
+      const p1 = createEntityId(2001) as EntityId;
+      const p2 = createEntityId(2002) as EntityId;
+      const r1 = relation(Tag, p1);
+      const r2 = relation(Tag, p2);
+      const wild = relation(Tag, "*");
+
+      const arch = new Archetype([A, wild], store);
+      const entity = createEntityId(5002) as EntityId;
+
+      arch.addEntity(entity, new Map([[A, 1]]));
+      // Only store relations in dontFragment (no regular archetype components for them)
+      store.setValue(entity, r1, undefined);
+      store.setValue(entity, r2, undefined);
+
+      const changeset = new ComponentChangeset();
+      changeset.delete(r1);
+
+      maybeRemoveWildcardMarker(entity, arch, r1, Tag as unknown as ComponentId<any>, changeset);
+
+      expect(changeset.removes.has(wild)).toBe(false);
+    });
+
+    it("keeps wildcard marker on exclusive dontFragment flip when remove+add are in same changeset (batch)", () => {
+      const store = createSparseStore();
+      const p1 = createEntityId(3001) as EntityId;
+      const p2 = createEntityId(3002) as EntityId;
+      const r1 = relation(ExclusiveTag, p1);
+      const r2 = relation(ExclusiveTag, p2);
+      const wild = relation(ExclusiveTag, "*");
+
+      const arch = new Archetype([A, wild], store);
+      const entity = createEntityId(5003) as EntityId;
+
+      arch.addEntity(entity, new Map([[A, 1]]));
+      store.setValue(entity, r1, { x: 1 }); // some value
+
+      const changeset = new ComponentChangeset();
+      // Simulate exclusive flip: remove old target, add new target in one batch
+      changeset.delete(r1);
+      changeset.set(r2, undefined); // ExclusiveTag is a void/tag dontFragment component
+
+      maybeRemoveWildcardMarker(entity, arch, r1, ExclusiveTag as unknown as ComponentId<any>, changeset);
+
+      // Because a replacement add is present, marker must be kept
+      expect(changeset.removes.has(wild)).toBe(false);
+    });
+  });
+
+  describe("pruneMissingRemovals (via applyChangeset)", () => {
+    it("prunes remove commands for components the entity does not actually have", () => {
+      const ctx = makeCtx();
+      const entity = createEntityId(6001) as EntityId;
+
+      // Archetype with only A
+      const arch = makeArchetype([A]);
+      arch.addEntity(entity, new Map([[A, 42]]));
+
+      const changeset = new ComponentChangeset();
+      // Spurious removes that do not exist on the entity
+      changeset.delete(B);
+      changeset.delete(relation(Tag, createEntityId(7777) as EntityId));
+
+      const entityToArch = new Map([[entity, arch]]);
+      const removed: Map<EntityId<any>, any> | null = new Map();
+
+      const resultArch = applyChangeset(ctx, entity, arch, changeset, entityToArch, removed);
+
+      // No structural change should have occurred (pruned), entity stays in same archetype
+      expect(resultArch).toBe(arch);
+      expect(entityToArch.get(entity)).toBe(arch);
+      // The spurious removes should have been pruned (no error, no move)
+      expect(changeset.removes.size).toBe(0);
+    });
+  });
+
+  describe("applyDontFragmentChanges recording paths (with hooks)", () => {
+    it("records removal of dontFragment relation even when stored value is undefined (tag/void case)", () => {
+      const store = createSparseStore();
+      const p = createEntityId(4001) as EntityId;
+      const r = relation(Tag, p); // Tag is dontFragment void-style
+      const wild = relation(Tag, "*");
+
+      const arch = new Archetype([A, wild], store);
+      const entity = createEntityId(7001) as EntityId;
+      arch.addEntity(entity, new Map([[A, 1]]));
+      store.setValue(entity, r, undefined); // explicitly undefined payload
+
+      const changeset = new ComponentChangeset();
+      changeset.delete(r);
+
+      // removedComponents non-null triggers the hook-recording path
+      const removedComponents = new Map<EntityId<any>, any>();
+
+      const ctx: CommandProcessorContext = {
+        sparseStore: store,
+        ensureArchetype: (t) => new Archetype(Array.from(t), store),
+      };
+
+      // No regular structural change (only dontFragment relation change)
+      applyChangeset(ctx, entity, arch, changeset, new Map(), removedComponents);
+
+      // The key: we should have recorded something for the removed dontFragment relation
+      // even though its value was undefined. This exercises the getAllForEntity fallback.
+      expect(removedComponents.has(r)).toBe(true);
+    });
+
+    it("records and applies normal dontFragment add/remove with data payloads", () => {
+      const store = createSparseStore();
+      const p = createEntityId(4002) as EntityId;
+      const r = relation(Data, p);
+      const wild = relation(Data, "*");
+
+      const arch = new Archetype([A, wild], store);
+      const entity = createEntityId(7002) as EntityId;
+      arch.addEntity(entity, new Map([[A, 1]]));
+
+      const changeset = new ComponentChangeset();
+      changeset.set(r, { v: 99 });
+
+      const ctx: CommandProcessorContext = {
+        sparseStore: store,
+        ensureArchetype: (t) => new Archetype(Array.from(t), store),
+      };
+
+      applyChangeset(ctx, entity, arch, changeset, new Map(), null);
+
+      expect(store.getValue(entity, r)).toEqual({ v: 99 });
+    });
+  });
+
+  describe("applyChangeset archetype move vs in-place dontFragment update", () => {
+    it("moves archetype when regular component is added/removed alongside dontFragment changes", () => {
+      const store = createSparseStore();
+      const p = createEntityId(5005) as EntityId;
+      const r = relation(Data, p);
+      const wild = relation(Data, "*");
+
+      const arch = new Archetype([A, wild], store);
+      const entity = createEntityId(8001) as EntityId;
+      arch.addEntity(entity, new Map([[A, 1]]));
+      store.setValue(entity, r, { v: 1 });
+
+      const changeset = new ComponentChangeset();
+      changeset.delete(A); // regular component removal → structural change
+      changeset.delete(r); // dontFragment
+
+      const ctx: CommandProcessorContext = {
+        sparseStore: store,
+        ensureArchetype: (t) => new Archetype(Array.from(t), store),
+      };
+      const entityToArch = new Map([[entity, arch]]);
+      const removed = new Map();
+
+      const newArch = applyChangeset(ctx, entity, arch, changeset, entityToArch, removed);
+
+      expect(newArch).not.toBe(arch);
+      expect(entityToArch.get(entity)).toBe(newArch);
+      expect(removed.has(r)).toBe(true); // recorded because removedComponents was provided
+    });
+  });
+
+  // These tests go through the public World API + full command processing pipeline
+  // (processCommands → processDeleteCommand → maybeRemoveWildcardMarker, etc.)
+  // to ensure branch coverage is attributed correctly for the early-return paths.
+  describe("public API paths for remaining branch coverage (processDeleteCommand etc.)", () => {
+    it("non-exclusive dontFragment: removing one target keeps wildcard marker (via World commands)", () => {
+      const world = new World();
+      const ParentTag = component({ dontFragment: true }); // non-exclusive
+      const p1 = world.new();
+      const p2 = world.new();
+      const child = world.new();
+
+      const r1 = relation(ParentTag, p1);
+      const r2 = relation(ParentTag, p2);
+      const wild = relation(ParentTag, "*");
+
+      world.set(child, r1, undefined);
+      world.set(child, r2, undefined);
+      world.sync();
+
+      // At this point child should have the wildcard marker in its (regular) component types
+      // Remove only one concrete relation
+      world.remove(child, r1);
+      world.sync();
+
+      // Marker must still exist (we can observe via wildcard query or has on the marker)
+      expect(world.has(child, wild)).toBe(true);
+      // The other relation survives
+      expect(world.has(child, r2)).toBe(true);
+      // The removed one is gone
+      expect(world.has(child, r1)).toBe(false);
+    });
+
+    it("exclusive dontFragment replacement via set (normal path) retains marker and cleans old target", () => {
+      const world = new World();
+      const ChildOf = component({ dontFragment: true, exclusive: true });
+      const parentA = world.new();
+      const parentB = world.new();
+      const child = world.new();
+
+      const rA = relation(ChildOf, parentA);
+      const rB = relation(ChildOf, parentB);
+      const wild = relation(ChildOf, "*");
+
+      world.set(child, rA, undefined);
+      world.sync();
+
+      // Normal exclusive flip via set — handleExclusiveRelation removes the old target
+      // using removeMatchingRelations (direct changeset delete, marker kept by other logic)
+      world.set(child, rB, undefined);
+      world.sync();
+
+      expect(world.has(child, wild)).toBe(true);
+      expect(world.has(child, rB)).toBe(true);
+      expect(world.has(child, rA)).toBe(false);
+    });
+
+    it("spurious remove of non-present component is a no-op (pruneMissingRemovals via World)", () => {
+      const world = new World();
+      const Pos = component<{ x: number }>();
+      const e = world.new();
+      world.set(e, Pos, { x: 10 });
+      world.sync();
+
+      // Remove something that was never present
+      world.remove(e, B);
+      // Should not throw and not affect existing data
+      world.sync();
+
+      expect(world.has(e, Pos)).toBe(true);
+      expect(world.get(e, Pos)).toEqual({ x: 10 });
+    });
+  });
+});

package/src/__tests__/world/debug-stats.test.ts

@@ -0,0 +1,206 @@
+import { describe, expect, it } from "bun:test";
+import { component, relation, type EntityId } from "../../entity";
+import type { SyncDebugStats } from "../../types";
+import { World } from "../../world/world";
+
+describe("World - Debug Stats Collector", () => {
+  type Position = { x: number; y: number };
+  type Velocity = { x: number; y: number };
+
+  const Position = component<Position>();
+  const Velocity = component<Velocity>();
+
+  it("should deliver stats after sync when collector is active", () => {
+    const world = new World();
+    const entity = world.new();
+
+    const received: SyncDebugStats[] = [];
+
+    using _collector = world.createDebugStatsCollector((stats) => {
+      received.push(stats);
+    });
+
+    world.set(entity, Position, { x: 1, y: 2 });
+    world.sync();
+
+    expect(received.length).toBe(1);
+    const stats = received[0]!;
+    expect(stats.commandIterations).toBeGreaterThanOrEqual(0);
+    expect(stats.entities.total).toBeGreaterThanOrEqual(1);
+    expect(stats.archetypes.total).toBeGreaterThanOrEqual(1);
+    expect(typeof stats.timestamps.syncStart).toBe("number");
+    expect(stats.timestamps.syncEnd).toBeGreaterThanOrEqual(stats.timestamps.syncStart);
+  });
+
+  it("should report archetype creation and removal activity", () => {
+    const world = new World();
+    const e1 = world.new();
+    const e2 = world.new();
+
+    const received: SyncDebugStats[] = [];
+    using _collector = world.createDebugStatsCollector((s) => received.push(s));
+
+    // First sync creates the empty archetype + entities
+    world.sync();
+    const afterFirst = received[received.length - 1]!;
+
+    // Cause archetype migrations by adding different components
+    world.set(e1, Position, { x: 0, y: 0 });
+    world.set(e2, Velocity, { x: 1, y: 1 });
+    world.sync();
+
+    const afterMigration = received[received.length - 1]!;
+
+    expect(afterMigration.activity.archetypesCreated).toBeGreaterThanOrEqual(0);
+    // We created at least one new archetype in the second sync
+    expect(afterMigration.activity.archetypesCreated + afterFirst.activity.archetypesCreated).toBeGreaterThan(0);
+
+    // Now remove components to potentially clean up archetypes
+    world.remove(e1, Position);
+    world.remove(e2, Velocity);
+    world.sync();
+
+    const afterRemove = received[received.length - 1]!;
+    expect(afterRemove.activity.archetypesRemoved).toBeGreaterThanOrEqual(0);
+  });
+
+  it("should count actual entity migrations", () => {
+    const world = new World();
+    const entity = world.new();
+
+    const received: SyncDebugStats[] = [];
+    using _collector = world.createDebugStatsCollector((s) => received.push(s));
+
+    world.set(entity, Position, { x: 1, y: 1 });
+    world.sync();
+
+    // Adding a second component should cause a migration
+    world.set(entity, Velocity, { x: 0, y: 0 });
+    world.sync();
+
+    const last = received[received.length - 1]!;
+    expect(last.activity.migrations).toBeGreaterThanOrEqual(1);
+  });
+
+  it("should count hook executions", () => {
+    const world = new World();
+    const entity = world.new();
+
+    const received: SyncDebugStats[] = [];
+    using _collector = world.createDebugStatsCollector((s) => received.push(s));
+
+    // Register a hook
+    world.hook([Position], {
+      on_set: () => {},
+    });
+
+    world.set(entity, Position, { x: 10, y: 20 });
+    world.sync();
+
+    const stats = received[received.length - 1]!;
+    expect(stats.activity.hooksExecuted).toBeGreaterThanOrEqual(1);
+    expect(stats.hooks.total).toBeGreaterThanOrEqual(1);
+  });
+
+  it("should deliver identical object reference to multiple collectors", () => {
+    const world = new World();
+    const e = world.new();
+
+    const receivedA: SyncDebugStats[] = [];
+    const receivedB: SyncDebugStats[] = [];
+
+    using _c1 = world.createDebugStatsCollector((s) => receivedA.push(s));
+    using _c2 = world.createDebugStatsCollector((s) => receivedB.push(s));
+
+    world.set(e, Position, { x: 5, y: 5 });
+    world.sync();
+
+    expect(receivedA.length).toBe(1);
+    expect(receivedB.length).toBe(1);
+    expect(receivedA[0]).toBe(receivedB[0]); // exact same reference
+  });
+
+  it("should stop delivering after collector is disposed", () => {
+    const world = new World();
+    const e = world.new();
+
+    const received: SyncDebugStats[] = [];
+    const collector = world.createDebugStatsCollector((s) => received.push(s));
+
+    world.set(e, Position, { x: 1, y: 1 });
+    world.sync();
+    expect(received.length).toBe(1);
+
+    collector[Symbol.dispose]();
+
+    world.set(e, Position, { x: 2, y: 2 });
+    world.sync();
+    // Should not have received a second stats payload
+    expect(received.length).toBe(1);
+  });
+
+  it("should report command iterations for complex command batches", () => {
+    const world = new World();
+    const entities: EntityId[] = [];
+
+    for (let i = 0; i < 10; i++) {
+      entities.push(world.new());
+    }
+
+    const received: SyncDebugStats[] = [];
+    using _collector = world.createDebugStatsCollector((s) => received.push(s));
+
+    // Many sets on different entities should require at least one iteration
+    for (const e of entities) {
+      world.set(e, Position, { x: 1, y: 1 });
+    }
+    world.sync();
+
+    const stats = received[received.length - 1]!;
+    expect(stats.commandIterations).toBeGreaterThanOrEqual(1);
+  });
+
+  it("should only collect for syncs after the collector was created", () => {
+    const world = new World();
+    const e = world.new();
+
+    world.set(e, Position, { x: 1, y: 1 });
+    world.sync(); // This sync happens before any collector exists
+
+    const received: SyncDebugStats[] = [];
+    using _collector = world.createDebugStatsCollector((s) => received.push(s));
+
+    world.set(e, Position, { x: 2, y: 2 });
+    world.sync(); // This one should be observed
+
+    expect(received.length).toBe(1);
+  });
+
+  it("should observe activity and index changes from relations", () => {
+    const world = new World();
+
+    const ChildOf = component<void>({ exclusive: true });
+
+    const parent1 = world.new();
+    const parent2 = world.new();
+    const child = world.new();
+
+    const received: SyncDebugStats[] = [];
+    using _collector = world.createDebugStatsCollector((s) => received.push(s));
+
+    // Establish a relation (should populate entity reference indices)
+    world.set(child, relation(ChildOf, parent1));
+    world.sync();
+
+    const afterRelation = received[received.length - 1]!;
+    expect(afterRelation.indices.entityReferences).toBeGreaterThanOrEqual(1);
+
+    // Switching an exclusive relation should cause a migration/remove + add
+    world.set(child, relation(ChildOf, parent2));
+    world.sync();
+
+    const afterSwitch = received[received.length - 1]!;
+    // Exclusive relation flip typically causes at least one structural change
+    expect(afterSwitch.activity.migrations).toBeGreaterThanOrEqual(0);
+  });
+});