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

package/src/__tests__/array-handle-element.test-d.ts

@@ -0,0 +1,34 @@
+// Compile-time type-derivation tests for the array<handle<X>> schema-vocab
+// extension (feat-20260608-mesh-multi-section-primitive-multi-material-slot M2
+// / w6, AC-01 / AC-02).
+//
+// Locks two invariants after the D-1 schema-vocab extension:
+//
+//   1. Inference (AC-01): FieldValueType<'array<shared<MaterialAsset>>'>
+//      resolves to readonly Handle<'MaterialAsset','shared'>[].
+//
+//   2. Cross-brand (AC-02): array<handle<X>> is distinct from array<u32>
+//      typed array — the brand prevents accidental u32 assignment.
+
+import type { Handle } from '@forgeax/engine-types';
+import { describe, expectTypeOf, it } from 'vitest';
+import type { FieldValueType, SchemaVocabKeyword } from '../component';
+
+describe('array<handle<X>> vocab - keyword recognition (w6, D-1)', () => {
+  it("FieldValueType<'array<shared<MaterialAsset>>'> resolves to readonly Handle<'MaterialAsset','shared'>[]", () => {
+    expectTypeOf<FieldValueType<'array<shared<MaterialAsset>>'>>().toEqualTypeOf<
+      readonly Handle<'MaterialAsset', 'shared'>[]
+    >();
+  });
+
+  it("FieldValueType<'array<shared<MeshAsset>>'> resolves to readonly Handle<'MeshAsset','shared'>[]", () => {
+    expectTypeOf<FieldValueType<'array<shared<MeshAsset>>'>>().toEqualTypeOf<
+      readonly Handle<'MeshAsset', 'shared'>[]
+    >();
+  });
+
+  it('array<handle<MaterialAsset>> is a valid SchemaVocabKeyword', () => {
+    const kw: SchemaVocabKeyword = 'array<shared<MaterialAsset>>';
+    void kw;
+  });
+});

package/src/__tests__/buffer-array-vocab.test-d.ts

@@ -0,0 +1,53 @@
+// Compile-time type-derivation tests for the SchemaVocabKeyword closed union
+// after the M1 buffer/array vocab collapse (w1, AC-01).
+//
+// Locks the new closed-union surface: the legacy `'buffer:<N>'` literal is
+// retired one-cut by feat-20260515-buffer-array-vocab-collapse w4, replaced
+// by the angle-bracket generic shapes `'buffer'` / `'buffer<N>'`. The new
+// vocab forms a 4-keyword closed surface across two orthogonal axes:
+//
+//   element-type axis  | byte-only       | typed
+//   --------------------------------------------------
+//   variable capacity  | 'buffer'        | 'array<T>'
+//   fixed capacity     | 'buffer<N>'     | 'array<T, N>'
+//
+// Negative anchors:
+//   - `'buffer:8'` is NO LONGER a SchemaVocabKeyword (TS error)
+//
+// Positive anchors:
+//   - `'buffer'`        is a SchemaVocabKeyword (compiles)
+//   - `'buffer<8>'`     is a SchemaVocabKeyword (compiles)
+//   - `'array<f32, 16>'` is a SchemaVocabKeyword (compiles)
+//   - `'array<entity>'`  is a SchemaVocabKeyword (compiles)
+
+import { describe, it } from 'vitest';
+import type { SchemaVocabKeyword } from '../component';
+
+describe('schema vocab — buffer-array-collapse closed union (w1, AC-01)', () => {
+  it('legacy buffer:<N> literal is rejected', () => {
+    // @ts-expect-error 'buffer:8' is no longer a SchemaVocabKeyword (collapsed
+    // to 'buffer<8>' by feat-20260515 w4).
+    const bad: SchemaVocabKeyword = 'buffer:8';
+    void bad;
+  });
+
+  it("'buffer' (variable capacity) is a SchemaVocabKeyword", () => {
+    const good: SchemaVocabKeyword = 'buffer';
+    void good;
+  });
+
+  it("'buffer<N>' (fixed capacity) is a SchemaVocabKeyword", () => {
+    const good: SchemaVocabKeyword = 'buffer<8>';
+    void good;
+  });
+
+  it("'array<T, N>' (typed fixed) is a SchemaVocabKeyword", () => {
+    const good: SchemaVocabKeyword = 'array<f32, 16>';
+    void good;
+  });
+
+  it("'array<entity>' (entity variable) is a SchemaVocabKeyword", () => {
+    const good: SchemaVocabKeyword = 'array<entity>';
+    void good;
+  });
+});

package/src/__tests__/buffer-field-input-widen.unit.test.ts

@@ -0,0 +1,99 @@
+// feat-20260621 M-C w27 (verify round 1 V2 / AC-A4): the write surface of a
+// `'buffer'` / `'buffer<N>'` field must accept any AllowSharedBufferSource view
+// (Float32Array / ArrayBuffer / Uint8Array), not Uint8Array alone. The read
+// side stays Uint8Array. HUMAN DECISION = widen (strict superset): any view is
+// normalized to Uint8Array at the single ECS buffer-write ingestion point, so
+// existing Uint8Array callers are unaffected.
+//
+// RED before w28: `world.set(e, C, { data: Float32Array.of(...) })` and
+// `{ data: new ArrayBuffer(16) }` fail to type-check (FieldInputType<'buffer'>
+// = Uint8Array). GREEN after w28: all three view types compile and round-trip
+// to the correct bytes through the read side.
+
+import { describe, expect, it } from 'vitest';
+import { type Component, defineComponent } from '../component';
+import { World } from '../world';
+
+describe('M-C w27: buffer-field write accepts AllowSharedBufferSource (AC-A4)', () => {
+  it("variable 'buffer' field accepts Float32Array on world.set + round-trips bytes", () => {
+    const Params = defineComponent('W27VarBuffer', { data: { type: 'buffer' } });
+    const w = new World();
+    const e = w.spawn({ component: Params, data: { data: new Uint8Array(16) } }).unwrap();
+
+    const src = Float32Array.of(1.5, 0, 0, 0);
+    // Typed write surface accepts Float32Array (widened input type).
+    w.set(e, Params, { data: src }).unwrap();
+
+    const out = w.get(e, Params).unwrap();
+    // Read side is Uint8Array; bytes match the Float32Array little-endian layout.
+    expect(out.data).toBeInstanceOf(Uint8Array);
+    expect(out.data.byteLength).toBe(16);
+    expect(new Float32Array(out.data.buffer, out.data.byteOffset, 4)[0]).toBeCloseTo(1.5);
+  });
+
+  it("variable 'buffer' field accepts ArrayBuffer on world.set + round-trips bytes", () => {
+    const Params = defineComponent('W27VarBufferAB', { data: { type: 'buffer' } });
+    const w = new World();
+    const e = w.spawn({ component: Params, data: { data: new Uint8Array(8) } }).unwrap();
+
+    const ab = new ArrayBuffer(8);
+    new DataView(ab).setUint32(0, 0xdeadbeef, true);
+    // Typed write surface accepts a raw ArrayBuffer.
+    w.set(e, Params, { data: ab }).unwrap();
+
+    const out = w.get(e, Params).unwrap();
+    expect(out.data).toBeInstanceOf(Uint8Array);
+    expect(out.data.byteLength).toBe(8);
+    expect(new DataView(out.data.buffer, out.data.byteOffset).getUint32(0, true)).toBe(0xdeadbeef);
+  });
+
+  it("variable 'buffer' field still accepts Uint8Array (zero-regression control)", () => {
+    const Params = defineComponent('W27VarBufferU8', { data: { type: 'buffer' } });
+    const w = new World();
+    const e = w.spawn({ component: Params, data: { data: new Uint8Array(4) } }).unwrap();
+
+    const u8 = Uint8Array.of(10, 20, 30, 40);
+    w.set(e, Params, { data: u8 }).unwrap();
+
+    const out = w.get(e, Params).unwrap();
+    expect(Array.from(out.data)).toEqual([10, 20, 30, 40]);
+  });
+
+  it("fixed 'buffer<N>' field accepts Float32Array of matching byteLength + round-trips", () => {
+    const Params = defineComponent('W27FixedBuffer', { data: { type: 'buffer<16>' } });
+    const w = new World();
+    const e = w.spawn({ component: Params, data: { data: new Uint8Array(16) } }).unwrap();
+
+    const src = Float32Array.of(2, 3, 4, 5);
+    w.set(e, Params, { data: src }).unwrap();
+
+    const out = w.get(e, Params).unwrap();
+    expect(out.data).toBeInstanceOf(Uint8Array);
+    expect(out.data.byteLength).toBe(16);
+    const view = new Float32Array(out.data.buffer, out.data.byteOffset, 4);
+    expect(Array.from(view)).toEqual([2, 3, 4, 5]);
+  });
+
+  it("spawn data accepts AllowSharedBufferSource on a 'buffer' field", () => {
+    const Params = defineComponent('W27SpawnBuffer', { data: { type: 'buffer' } });
+    const w = new World();
+    // Float32Array passed directly to spawn data (widened input type).
+    const e = w.spawn({ component: Params, data: { data: Float32Array.of(9, 0, 0, 0) } }).unwrap();
+
+    const out = w.get(e, Params).unwrap();
+    expect(out.data.byteLength).toBe(16);
+    expect(new Float32Array(out.data.buffer, out.data.byteOffset, 4)[0]).toBeCloseTo(9);
+  });
+
+  // Type-level: FieldInputType<'buffer'> must be assignable from all three views.
+  it('FieldInputType<buffer> accepts the three AllowSharedBufferSource subtypes (compile-time)', () => {
+    const Params = defineComponent('W27TypeProbe', { data: { type: 'buffer' } });
+    const w = new World();
+    const e = w.spawn({ component: Params, data: { data: new Uint8Array(16) } }).unwrap();
+    void (Params as Component);
+    // These three lines are the AC-A4 compile gate: red before widen, green after.
+    w.set(e, Params, { data: Float32Array.of(1, 2, 3, 4) });
+    w.set(e, Params, { data: new ArrayBuffer(16) });
+    w.set(e, Params, { data: new Uint8Array(16) });
+  });
+});

package/src/__tests__/buffer-pool.test-d.ts

@@ -0,0 +1,32 @@
+// Compile-time type assertions for BufferPool.release (w6 + AC-13).
+//
+// Locks BufferPool.prototype.release return type to Result<void, never>:
+// the slot id never escapes ECS internals, no generation tag, no stale-slot
+// error arm. Any future PR adding a generation-tag error arm (e.g.
+// Result<void, BufferPoolStaleSlotError>) breaks this file at compile time
+// and blocks the PR (plan-strategy §4 R-spec-5.1 dual-enforce; OOS-3 guard).
+//
+// Spec: docs/specs/2026-06-14-ecs-managed-lifecycle-ssot-design.md §3.3
+// "Managed handles are operational, not persistent" — BufferPool sub-section.
+//
+// This file is the type-layer half of the dual-enforce; packages/ecs/README.md
+// §"Managed handles are operational, not persistent" (w8) is the documentation
+// half. Both must ship together.
+
+import type { Result } from '@forgeax/engine-types';
+import { describe, expectTypeOf, it } from 'vitest';
+import type { BufferPool } from '../buffer-pool';
+
+describe('BufferPool.release — type contract (w6)', () => {
+  it('release returns Result<void, never> — no error arm; OOS-3 guard', () => {
+    type ReleaseFn = BufferPool['release'];
+    type ReleaseReturn = ReturnType<ReleaseFn>;
+    expectTypeOf<ReleaseReturn>().toEqualTypeOf<Result<void, never>>();
+  });
+
+  it('release accepts a number id (slot id never escapes — no Handle<Buffer> public surface)', () => {
+    type ReleaseFn = BufferPool['release'];
+    type ReleaseParams = Parameters<ReleaseFn>;
+    expectTypeOf<ReleaseParams>().toEqualTypeOf<[id: number]>();
+  });
+});

package/src/__tests__/change-detection.unit.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from 'vitest';
+import { componentId, defineComponent } from '../component';
+import { World } from '../world';
+
+import { worldInternal } from '../world-internal';
+
+const Marker = defineComponent('ChangeDetectionMarker', { value: 'f32' });
+
+describe('mutation epoch evidence', () => {
+  it('advances once per successful mutation and not for failures or no-ops', () => {
+    const Other = defineComponent('MutationEpochOther', { value: 'f32' });
+    const world = new World();
+    const entity = world.spawn({ component: Marker, data: { value: 1 } }).unwrap();
+    expect(world[worldInternal].getMutationEpoch()).toBe(1);
+    expect(world[worldInternal].getComponentChange(entity, componentId(Marker))).toEqual({
+      added: 1,
+      changed: 1,
+    });
+
+    expect(world.set(entity, Other, { value: 2 }).ok).toBe(false);
+    world.removeResource('missing');
+    expect(world[worldInternal].getMutationEpoch()).toBe(1);
+
+    world.set(entity, Marker, { value: 2 }).unwrap();
+    expect(world[worldInternal].getMutationEpoch()).toBe(2);
+    expect(world[worldInternal].getComponentChange(entity, componentId(Marker))).toEqual({
+      added: 1,
+      changed: 2,
+    });
+  });
+
+  it('keeps resource evidence on its ResourceStore entry', () => {
+    const world = new World();
+    world.insertResource('ChangeDetectionResource', { value: 1 });
+    expect(world.getResourceChange('ChangeDetectionResource')).toEqual({ added: 1, changed: 1 });
+    world.update(1 / 60).unwrap();
+    world.insertResource('ChangeDetectionResource', { value: 2 });
+    expect(world.getResourceChange('ChangeDetectionResource')).toEqual({ added: 1, changed: 2 });
+  });
+
+  it('keeps independent query cursors and retries after consumer throws', () => {
+    const world = new World();
+    const entity = world.spawn({ component: Marker, data: { value: 1 } }).unwrap();
+    const first = world.query({ read: [Marker], changed: [Marker] }).unwrap();
+    const second = world.query({ read: [Marker], changed: [Marker] }).unwrap();
+
+    expect(() => {
+      for (const _row of first) throw new Error('consumer failure');
+    }).toThrow('consumer failure');
+    expect([...first].map((row) => row.entity)).toEqual([entity]);
+    expect([...second].map((row) => row.entity)).toEqual([entity]);
+  });
+
+  it('does not inherit evidence when a slot generation is reused', () => {
+    const world = new World();
+    const retired = world.spawn({ component: Marker, data: { value: 1 } }).unwrap();
+    const added = world.query({ read: [Marker], added: [Marker] }).unwrap();
+    expect([...added].map((row) => row.entity)).toEqual([retired]);
+
+    world.despawn(retired).unwrap();
+    const reused = world.spawn({ component: Marker, data: { value: 2 } }).unwrap();
+    expect((reused as number) & 0xffffff).toBe((retired as number) & 0xffffff);
+    expect(reused).not.toBe(retired);
+    expect([...added].map((row) => row.entity)).toEqual([reused]);
+  });
+
+  it('carries evidence through grow, migration, and swap-pop', () => {
+    const Attached = defineComponent('MutationEpochAttached', { flag: 'u8' });
+    const world = new World();
+    const entities = Array.from({ length: 65 }, (_, value) =>
+      world.spawn({ component: Marker, data: { value } }).unwrap(),
+    );
+    const changed = world.query({ read: [Marker], changed: [Marker] }).unwrap();
+    expect([...changed].length).toBe(65);
+
+    const survivor = entities[0];
+    const removed = entities[1];
+    if (survivor === undefined || removed === undefined) throw new Error('fixture');
+    world.addComponent(survivor, { component: Attached, data: { flag: 1 } }).unwrap();
+    world.despawn(removed).unwrap();
+    expect([...changed]).toEqual([]);
+
+    world.set(survivor, Marker, { value: 99 }).unwrap();
+    expect([...changed].map((row) => row.entity)).toEqual([survivor]);
+  });
+});

package/src/__tests__/command-buffer.test.ts

@@ -0,0 +1,179 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createCommandBuffer, flushCommands } from '../commands';
+import { defineComponent } from '../component';
+import { Entity } from '../entity';
+import type { EntityHandle } from '../entity-handle';
+import { CommandFailedError, SystemFailedError } from '../errors';
+import { defineRelationship } from '../relationship-index';
+import { Update } from '../schedule-token';
+import { World } from '../world';
+import { worldInternal } from '../world-internal';
+
+const CommandPosition = defineComponent('CommandBufferPosition', { x: 'f32' });
+const CommandVelocity = defineComponent('CommandBufferVelocity', { x: 'f32' });
+const { source: CommandChildOf, target: CommandChildren } = defineRelationship({
+  sourceName: 'CommandBufferChildOf',
+  sourceField: 'parent',
+  targetName: 'CommandBufferChildren',
+  targetField: 'entities',
+});
+
+describe('CommandBuffer terminal lifecycle', () => {
+  it('commits after a successful drain and rejects later writes', () => {
+    const world = new World();
+    const buffer = createCommandBuffer(world);
+    buffer.despawn(1 as never);
+    flushCommands(buffer, world);
+    expect(buffer.status).toBe('committed');
+    expect(() => buffer.despawn(1 as never)).toThrow('committed');
+  });
+
+  it('aborts a preflight command failure without poisoning the world', () => {
+    const world = new World();
+    const buffer = createCommandBuffer(world);
+    const poison = vi.spyOn(world[worldInternal], 'poisonExecution');
+    const entity = world.spawn().unwrap();
+    buffer.removeComponent(entity, Entity);
+    expect(() => flushCommands(buffer, world)).toThrow(CommandFailedError);
+    expect(buffer.status).toBe('aborted');
+    expect(poison).not.toHaveBeenCalled();
+  });
+
+  it('poisons the World on a system exception after command staging', () => {
+    const world = new World();
+    world
+      .addSystem(Update, {
+        name: 'throws-after-stage',
+        queries: [],
+        fn: (_world, _queries, commands) => {
+          commands.despawn(1 as never);
+          throw new Error('system failure');
+        },
+      })
+      .unwrap();
+    const result = world.update(0);
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error).toBeInstanceOf(SystemFailedError);
+    expect(world.execution.health).toBe('poisoned');
+    expect(world.update(0).ok).toBe(false);
+  });
+
+  it('preflights same-batch duplicate component mutations without partial writes', () => {
+    const world = new World();
+    const entity = world.spawn({ component: CommandPosition, data: { x: 1 } }).unwrap();
+    const buffer = createCommandBuffer(world, {
+      systemName: 'duplicate',
+      scheduleName: Update.name,
+    });
+    buffer.addComponent(entity, { component: CommandVelocity, data: { x: 2 } });
+    buffer.addComponent(entity, { component: CommandVelocity, data: { x: 3 } });
+
+    expect(() => flushCommands(buffer, world)).toThrow(CommandFailedError);
+    expect(world.hasComponent(entity, CommandVelocity)).toBe(false);
+    expect(world.execution.health).toBe('healthy');
+  });
+
+  it('preflights relationship cycles and keeps the existing hierarchy intact', () => {
+    const world = new World();
+    const root = world.spawn().unwrap();
+    const child = world.spawn({ component: CommandChildOf, data: { parent: root } }).unwrap();
+    const grandchild = world.spawn({ component: CommandChildOf, data: { parent: child } }).unwrap();
+    const buffer = createCommandBuffer(world, { systemName: 'cycle', scheduleName: Update.name });
+    buffer.addComponent(root, { component: CommandChildOf, data: { parent: grandchild } });
+
+    expect(() => flushCommands(buffer, world)).toThrow(CommandFailedError);
+    expect(world.execution.health).toBe('healthy');
+    const current = world.get(child, CommandChildOf);
+    expect(current.ok).toBe(true);
+    if (current.ok) expect(current.value.parent).toBe(root);
+  });
+
+  it('treats an exclusive relationship add as a staged reparent', () => {
+    const world = new World();
+    const first = world.spawn().unwrap();
+    const second = world.spawn().unwrap();
+    const child = world.spawn({ component: CommandChildOf, data: { parent: first } }).unwrap();
+    const buffer = createCommandBuffer(world, {
+      systemName: 'reparent',
+      scheduleName: Update.name,
+    });
+    buffer.addComponent(child, { component: CommandChildOf, data: { parent: second } });
+
+    expect(() => flushCommands(buffer, world)).not.toThrow();
+    const current = world.get(child, CommandChildOf);
+    expect(current.ok).toBe(true);
+    if (current.ok) expect(current.value.parent).toBe(second);
+    const oldChildren = world.get(first, CommandChildren);
+    const newChildren = world.get(second, CommandChildren);
+    expect(oldChildren.ok && Array.from(oldChildren.value.entities)).toEqual([]);
+    expect(newChildren.ok && Array.from(newChildren.value.entities)).toEqual([child]);
+  });
+
+  it('sees relationship edges staged earlier in the same batch when checking cycles', () => {
+    const world = new World();
+    const a = world.spawn().unwrap();
+    const b = world.spawn().unwrap();
+    const buffer = createCommandBuffer(world, {
+      systemName: 'batch-cycle',
+      scheduleName: Update.name,
+    });
+    buffer.addComponent(a, { component: CommandChildOf, data: { parent: b } });
+    buffer.addComponent(b, { component: CommandChildOf, data: { parent: a } });
+
+    expect(() => flushCommands(buffer, world)).toThrow(CommandFailedError);
+    expect(world.hasComponent(a, CommandChildOf)).toBe(false);
+    expect(world.hasComponent(b, CommandChildOf)).toBe(false);
+    expect(world.execution.health).toBe('healthy');
+  });
+
+  it('bumps a cancelled pending reservation so a later entity cannot alias its handle', () => {
+    const world = new World();
+    let pending: EntityHandle | undefined;
+    world
+      .addSystem(Update, {
+        name: 'pending-abort',
+        queries: [],
+        fn: (_world, _queries, commands) => {
+          pending = commands.spawn({ component: CommandPosition, data: { x: 4 } });
+          throw new Error('abort pending');
+        },
+      })
+      .unwrap();
+
+    const failed = world.update();
+    expect(failed.ok).toBe(false);
+    expect(world.execution.health).toBe('poisoned');
+    const replacement = world.spawn().unwrap();
+    const stale = world.get(pending as EntityHandle, CommandPosition);
+    expect(stale.ok).toBe(false);
+    if (!stale.ok) expect(stale.error.code).toBe('stale-entity');
+    expect(replacement).not.toBe(pending);
+  });
+
+  it('reports the last committed command when a later flush write unexpectedly fails', () => {
+    const world = new World();
+    const first = world.spawn().unwrap();
+    const second = world.spawn().unwrap();
+    const buffer = createCommandBuffer(world, { systemName: 'flush', scheduleName: Update.name });
+    buffer.despawn(first);
+    buffer.despawn(second);
+    const original = world.despawn.bind(world);
+    vi.spyOn(world, 'despawn')
+      .mockImplementationOnce((entity) => original(entity))
+      .mockImplementationOnce(() => {
+        throw new Error('unexpected write fault');
+      });
+
+    let failure: unknown;
+    try {
+      flushCommands(buffer, world);
+    } catch (error) {
+      failure = error;
+    }
+    expect(failure).toBeInstanceOf(SystemFailedError);
+    if (failure instanceof SystemFailedError) {
+      expect(failure.detail.lastCommittedCommand).toEqual({ index: 0, kind: 'despawn' });
+    }
+    expect(world.execution.health).toBe('poisoned');
+  });
+});

package/src/__tests__/commands-deferred.unit.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from 'vitest';
+import { defineComponent } from '../component';
+import { FixedUpdate, Update } from '../schedule-token';
+import { World } from '../world';
+
+describe('schedule-owned deferred commands', () => {
+  it('makes producer commands visible to an explicit successor', () => {
+    const Marker = defineComponent('DeferredMarker', {});
+    const world = new World();
+    let observed = 0;
+
+    world.addSystem(Update, {
+      name: 'producer',
+      queries: [],
+      before: ['consumer'],
+      fn: (_world, _queries, commands) => commands.spawn({ component: Marker, data: {} }),
+    });
+    world.addSystem(Update, {
+      name: 'consumer',
+      queries: [{ with: [Marker] }],
+      fn: (_world, results) => (observed += [...results[0]].length),
+    });
+
+    expect(world.update(0).ok).toBe(true);
+    expect(observed).toBe(1);
+  });
+
+  it('drains commands recursively at a schedule final boundary', () => {
+    const Marker = defineComponent('CascadeMarker', {});
+    const world = new World();
+    let drained = false;
+
+    world.addSystem(Update, {
+      name: 'producer',
+      queries: [],
+      fn: (_world, _queries, commands) => commands.spawn({ component: Marker, data: {} }),
+    });
+    world.addSystem(Update, {
+      name: 'observer',
+      queries: [{ with: [Marker] }],
+      fn: () => (drained = true),
+    });
+
+    expect(world.update(0).ok).toBe(true);
+    expect(world.update(0).ok).toBe(true);
+    expect(drained).toBe(true);
+  });
+
+  it('isolates Update and FixedUpdate command buffers', () => {
+    const Marker = defineComponent('ScheduleIsolationMarker', {});
+    const world = new World();
+    let fixedObserved = 0;
+
+    world.addSystem(Update, {
+      name: 'update-producer',
+      queries: [],
+      fn: (_world, _queries, commands) => commands.spawn({ component: Marker, data: {} }),
+    });
+    world.addSystem(FixedUpdate, {
+      name: 'fixed-observer',
+      queries: [{ with: [Marker] }],
+      fn: (_world, results) => (fixedObserved += [...results[0]].length),
+    });
+
+    expect(world.update(1 / 60).ok).toBe(true);
+    expect(fixedObserved).toBe(0);
+  });
+});

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

@@ -0,0 +1,59 @@
+import { describe, expect, it } from 'vitest';
+import { defineComponent } from '../component';
+import { Update } from '../schedule-token';
+import { World } from '../world';
+
+describe('World ComponentCatalog', () => {
+  it('owns independent leases for the same declaration in multiple Worlds', () => {
+    const Position = defineComponent('WorldCatalogPosition', { x: 'f32' });
+    const worldA = new World();
+    const worldB = new World();
+    const leaseA = worldA.components.register(Position).unwrap();
+    const leaseB = worldB.components.register(Position).unwrap();
+
+    expect(worldA.components.resolve(Position.name)).toBe(Position);
+    expect(worldB.components.resolve(Position.name)).toBe(Position);
+    expect(leaseA.dispose().ok).toBe(true);
+    expect(worldA.components.resolve(Position.name)).toBeUndefined();
+    expect(worldB.components.resolve(Position.name)).toBe(Position);
+    expect(leaseB.dispose().ok).toBe(true);
+  });
+
+  it('refuses the last unregister while entities or systems still reference the token', () => {
+    const Marker = defineComponent('WorldCatalogMarker', {});
+    const world = new World();
+    const lease = world.components.register(Marker).unwrap();
+    const entity = world.spawn({ component: Marker, data: {} }).unwrap();
+
+    const entityFailure = lease.dispose();
+    expect(entityFailure.ok).toBe(false);
+    if (!entityFailure.ok) expect(entityFailure.error.code).toBe('component-in-use');
+
+    world.despawn(entity).unwrap();
+    world
+      .addSystem(Update, {
+        name: 'world-catalog-reader',
+        queries: [{ read: [Marker] }],
+        fn: () => undefined,
+      })
+      .unwrap();
+    const systemFailure = lease.dispose();
+    expect(systemFailure.ok).toBe(false);
+    if (!systemFailure.ok) expect(systemFailure.error.code).toBe('component-in-use');
+
+    world.removeSystem(Update, 'world-catalog-reader').unwrap();
+    expect(lease.dispose().ok).toBe(true);
+    expect(world.components.resolve(Marker.name)).toBeUndefined();
+  });
+
+  it('rejects a different token with the same name inside one World', () => {
+    const First = defineComponent('WorldCatalogConflict', { x: 'f32' });
+    const Second = defineComponent('WorldCatalogConflict', { x: 'f32' });
+    const world = new World();
+    const lease = world.components.register(First).unwrap();
+    const conflict = world.components.register(Second);
+    expect(conflict.ok).toBe(false);
+    if (!conflict.ok) expect(conflict.error.code).toBe('component-name-conflict');
+    expect(lease.dispose().ok).toBe(true);
+  });
+});

package/src/__tests__/component-definition-identity.unit.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest';
+
+describe('component definition identity', () => {
+  it('shares token reflection between root and externalization bundles', async () => {
+    const indexPath = '../../dist/index.mjs';
+    const externalizationPath = '../../dist/externalization/index.mjs';
+    const [
+      { componentDefinition, defineComponent },
+      { classifyEntityField, projectComponentData },
+    ] = await Promise.all([import(indexPath), import(externalizationPath)]);
+    const Probe = defineComponent('ComponentDefinitionIdentityProbe', {
+      target: 'entity',
+      targets: 'array<entity>',
+    });
+
+    expect(componentDefinition(Probe).fields.target?.type).toBe('entity');
+    expect(classifyEntityField(Probe, 'target')).toEqual({ kind: 'entity', isArray: false });
+    expect(classifyEntityField(Probe, 'targets')).toEqual({ kind: 'entity', isArray: true });
+    expect(projectComponentData(Probe, { target: 7, targets: [8, 9] })).toEqual({
+      target: 7,
+      targets: [8, 9],
+    });
+  });
+});