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

package/src/__tests__/table-archetype-mapping.unit.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, it } from 'vitest';
+import { componentId, defineComponent } from '../component';
+import { Entity } from '../entity';
+import type { EntityHandle } from '../entity-handle';
+import { appendArchetypeRow, growArchetype, removeArchetypeRow } from '../storage/archetype';
+import { createArchetypeGraph, getOrCreateArchetype } from '../storage/archetype-graph';
+import { appendTableRow, growTable, removeTableRow } from '../storage/table';
+import { World } from '../world';
+
+describe('Table and Archetype ownership', () => {
+  it('stores component columns only on Table and logical membership only on Archetype', () => {
+    const Position = defineComponent('TableOwnerPosition', { x: 'f32' });
+    const graph = createArchetypeGraph();
+    const archetype = getOrCreateArchetype(graph, [componentId(Position)], [Position]);
+    const table = graph.tables[archetype.tableId];
+    if (table === undefined) throw new Error('table missing');
+
+    expect(table.storage.has(componentId(Entity))).toBe(true);
+    expect(table.storage.has(componentId(Position))).toBe(true);
+    expect(archetype.rows).toBeInstanceOf(Uint32Array);
+    expect('storage' in archetype).toBe(false);
+  });
+
+  it('grows logical and physical capacities independently', () => {
+    const Position = defineComponent('IndependentCapacityPosition', { x: 'f32' });
+    const graph = createArchetypeGraph();
+    const archetype = getOrCreateArchetype(graph, [componentId(Position)], [Position]);
+    const table = graph.tables[archetype.tableId];
+    if (table === undefined) throw new Error('table missing');
+    const archetypeCapacity = archetype.capacity;
+    const tableCapacity = table.capacity;
+
+    growArchetype(archetype, archetypeCapacity * 2);
+    expect(archetype.capacity).toBe(archetypeCapacity * 2);
+    expect(table.capacity).toBe(tableCapacity);
+
+    growTable(table, tableCapacity * 2);
+    expect(table.capacity).toBe(tableCapacity * 2);
+    expect(archetype.capacity).toBe(archetypeCapacity * 2);
+  });
+
+  it('keeps archetypeRow to tableRow explicit across independent swap-pop', () => {
+    const Position = defineComponent('SwapMappingPosition', { x: 'f32' });
+    const graph = createArchetypeGraph();
+    const archetype = getOrCreateArchetype(graph, [componentId(Position)], [Position]);
+    const table = graph.tables[archetype.tableId];
+    if (table === undefined) throw new Error('table missing');
+    const first = 0x01000001 as EntityHandle;
+    const second = 0x02000002 as EntityHandle;
+    const firstTableRow = appendTableRow(table, first);
+    const secondTableRow = appendTableRow(table, second);
+    appendArchetypeRow(archetype, firstTableRow);
+    appendArchetypeRow(archetype, secondTableRow);
+
+    expect(removeArchetypeRow(archetype, 0)).toEqual({ movedTableRow: 1, newRow: 0 });
+    expect(archetype.rows[0]).toBe(1);
+    expect(removeTableRow(table, 0)).toEqual({ movedEntity: second, newRow: 0 });
+    expect(table.storage.get(componentId(Entity))?.fields.get('self')?.view[0]).toBe(second);
+  });
+
+  it('world migration and despawn maintain both mapping layers', () => {
+    const Position = defineComponent('WorldMappingPosition', { x: 'f32' });
+    const Selected = defineComponent('WorldMappingSelected', {});
+    const world = new World();
+    const first = world.spawn({ component: Position, data: { x: 1 } }).unwrap();
+    const second = world.spawn({ component: Position, data: { x: 2 } }).unwrap();
+
+    world.addComponent(first, { component: Selected, data: {} }).unwrap();
+    expect(world.get(first, Position).unwrap().x).toBe(1);
+    expect(world.get(second, Position).unwrap().x).toBe(2);
+
+    world.despawn(first).unwrap();
+    expect(world.get(second, Entity).unwrap().self).toBe(second);
+    expect([...world.query({ read: [Position] }).unwrap()].map((row) => row.entity)).toEqual([
+      second,
+    ]);
+  });
+});

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

@@ -0,0 +1,79 @@
+import { describe, expect, it } from 'vitest';
+import { FixedUpdate, Update } from '../schedule-token';
+import { FixedTime, Time } from '../time';
+import { World } from '../world';
+
+describe('World time resources', () => {
+  it('rejects negative, NaN, and infinite deltas without mutating time', () => {
+    const world = new World();
+    const before = world.getResource(Time);
+
+    for (const delta of [-1, Number.NaN, Number.POSITIVE_INFINITY]) {
+      const result = world.update(delta);
+      expect(result.ok).toBe(false);
+      if (!result.ok) {
+        expect(result.error.code).toBe('time-delta-invalid');
+        expect(result.error.expected).toBe('a finite delta greater than or equal to 0');
+        expect(result.error.hint).toContain('world.update');
+      }
+    }
+
+    expect(world.getResource(Time)).toEqual(before);
+  });
+
+  it('treats an omitted delta as zero while still running Update', () => {
+    const world = new World();
+    let updates = 0;
+    world.addSystem(Update, { name: 'update', queries: [], fn: () => updates++ });
+
+    expect(world.update().ok).toBe(true);
+    expect(world.getResource(Time)).toMatchObject({ delta: 0, elapsed: 0 });
+    expect(world.getResource(FixedTime).tick).toBe(0);
+    expect(updates).toBe(1);
+  });
+
+  it('advances Time by an explicit positive delta', () => {
+    const world = new World();
+
+    expect(world.update(0.025).ok).toBe(true);
+    expect(world.getResource(Time)).toMatchObject({ delta: 0.025, elapsed: 0.025 });
+  });
+
+  it('rejects an incoherent policy before writing protected resources', () => {
+    const world = new World({
+      time: { fixedDeltaSeconds: 1 / 60, maxStepsPerUpdate: 4, maxDeltaSeconds: 0.05 },
+    });
+    const beforeTime = world.getResource(Time);
+    const beforeFixed = world.getResource(FixedTime);
+
+    const result = world.update(0.01);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('time-config-invalid');
+      expect(result.error.expected).toContain('maxDeltaSeconds >=');
+      expect(result.error.hint).toContain('maxDeltaSeconds');
+    }
+    expect(world.getResource(Time)).toEqual(beforeTime);
+    expect(world.getResource(FixedTime)).toEqual(beforeFixed);
+  });
+
+  it('uses the clamped Time delta as the fixed accumulator input', () => {
+    const world = new World();
+    let fixedRuns = 0;
+    world.addSystem(Update, { name: 'observe-time', queries: [], fn: () => {} });
+    world.addSystem(FixedUpdate, { name: 'fixed', queries: [], fn: () => fixedRuns++ });
+
+    expect(world.update(5).ok).toBe(true);
+    const time = world.getResource(Time);
+    const fixed = world.getResource(FixedTime);
+    expect(time.delta).toBe(0.1);
+    expect(fixed).toMatchObject({
+      delta: 1 / 60,
+      maxStepsPerUpdate: 4,
+      droppedUpdates: 1,
+    });
+    expect(fixedRuns).toBe(4);
+    expect(fixed.droppedSeconds).toBeCloseTo(1 / 60, 12);
+  });
+});

package/src/__tests__/types.test-d.ts

@@ -0,0 +1,38 @@
+import { describe, expectTypeOf, it } from 'vitest';
+import { defineComponent } from '../component';
+import type { Query, QueryDescriptor, QueryRow, QuerySpan } from '../query/query';
+import { World } from '../world';
+
+const Position = defineComponent('QueryTypePosition', { x: 'f32', y: 'f32' });
+const Velocity = defineComponent('QueryTypeVelocity', { x: 'f32' });
+
+describe('Query public type inference', () => {
+  it('infers row read, write, and optional roles', () => {
+    const world = new World();
+    const query = world.query({ read: [Velocity], write: [Position] }).unwrap();
+    expectTypeOf(query).toMatchTypeOf<
+      Query<readonly [typeof Velocity], readonly [typeof Position], readonly []>
+    >();
+  });
+
+  it('projects scalar row and column shapes', () => {
+    const row = null as unknown as QueryRow<
+      readonly [typeof Velocity],
+      readonly [typeof Position],
+      readonly []
+    >;
+    const span = null as unknown as QuerySpan<
+      readonly [typeof Velocity],
+      readonly [typeof Position]
+    >;
+    expectTypeOf(row.get(Velocity).x).toBeNumber();
+    expectTypeOf(row.mut(Position).x).toBeNumber();
+    expectTypeOf(span.get(Velocity).x).toEqualTypeOf<Float32Array>();
+    expectTypeOf(span.mut(Position).x).toEqualTypeOf<Float32Array>();
+  });
+
+  it('keeps descriptor access tuples literal', () => {
+    const descriptor = { read: [Position], write: [Velocity] } satisfies QueryDescriptor;
+    expectTypeOf(descriptor.read).toEqualTypeOf<(typeof Position)[]>();
+  });
+});

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

@@ -0,0 +1,348 @@
+// feat-20260614-ecs-managed-lifecycle-ssot M1 t-w1: store-unit tests for
+// UniqueRefStore.release order + throw-safety + slot reuse.
+//
+// These tests drive UniqueRefStore directly (no World) per research
+// Finding 1.5: the regression repro path is achievable with a spy callback,
+// no Rapier / World fixture required. Verifies AC-01, AC-02, AC-06, AC-07
+// (requirements §3.1, §5).
+//
+// TDD red -> green:
+//   - (a) order assertion + (b) throw-safety: red before w2, green after w2.
+//   - (c) slot reuse: green after w7 (M3 deletes the gen-255 retirement that
+//     would otherwise force nextSlot to grow during 1000 iters on a single
+//     slot). Documented inline so reviewer can correlate the carryover.
+
+import { handleGeneration, handleSlot, pack, unwrapHandle } from '@forgeax/engine-types';
+import { describe, expect, it, vi } from 'vitest';
+import { UniqueRefStaleError } from '../errors';
+import { UniqueRefStore } from '../unique-ref-store';
+
+describe('UniqueRefStore release ordering + throw-safety (feat-20260614 M1)', () => {
+  it('AC-01: releaseCallbacks entry is removed BEFORE onRelease fires', () => {
+    const store = new UniqueRefStore();
+    let observedHasCallback: boolean | null = null;
+
+    // Spy reads the private releaseCallbacks Map at the moment cb fires.
+    // After the M1 fix (w2) the entry is deleted before invocation, so the
+    // observation is `false`. Before the fix the entry is still live so
+    // observation is `true` -> assertion fails (red).
+    const onRelease = vi.fn((_payload: { id: number }) => {
+      // biome-ignore lint/suspicious/noExplicitAny: targeted private read for the order assertion
+      const internalCallbacks = (store as any).releaseCallbacks as Map<number, unknown>;
+      // biome-ignore lint/suspicious/noExplicitAny: handle raw u32 read for the lookup
+      const raw = (store as any).payloads as Map<number, unknown>;
+      // The handle is a u32 brand. Re-derive raw via the live keys snapshot
+      // since the handle isn't directly in scope inside the cb closure.
+      void raw;
+      // Use the callbacks map's keys: at the moment of cb invocation, the
+      // entry MUST already be gone -> map size 0 (only one alloc was made).
+      observedHasCallback = internalCallbacks.size > 0;
+    });
+
+    const handle = store.alloc('Test', { id: 7 }, onRelease);
+    const result = store.release(handle);
+
+    expect(result.ok).toBe(true);
+    expect(onRelease).toHaveBeenCalledTimes(1);
+    expect(observedHasCallback).toBe(false);
+  });
+
+  it('AC-02 + AC-06: throwing onRelease re-throws once; second release returns Stale (gen incremented, M4)', () => {
+    const store = new UniqueRefStore();
+    const onRelease = vi.fn((_payload: { id: number }) => {
+      throw new Error('intentional cleanup failure');
+    });
+
+    const handle = store.alloc('Test', { id: 9 }, onRelease);
+
+    // First release must propagate the throw (no try/finally swallowing).
+    expect(() => store.release(handle)).toThrow('intentional cleanup failure');
+    expect(onRelease).toHaveBeenCalledTimes(1);
+
+    // After M4 gen increment, the store gen is now 1 while handle gen is 0.
+    // Second release returns stale (gen mismatch), not double-release.
+    const second = store.release(handle);
+    expect(second.ok).toBe(false);
+    if (!second.ok) {
+      expect(second.error).toBeInstanceOf(UniqueRefStaleError);
+    }
+    expect(onRelease).toHaveBeenCalledTimes(1);
+  });
+
+  it('AC-07: 1000-iteration alloc/release loop reuses slots (no unbounded growth)', () => {
+    const store = new UniqueRefStore();
+
+    for (let i = 0; i < 1000; i++) {
+      const handle = store.alloc('Test', { id: i });
+      const result = store.release(handle);
+      expect(result.ok).toBe(true);
+    }
+
+    expect(store._liveCount()).toBe(0);
+
+    // nextSlot is private. After M3 (w7) deletes the gen-255 retirement path
+    // a single slot recycles forever and nextSlot stays at 2. Before w7,
+    // gen-255 retirement forces ~4 fresh slots over 1000 iters (256 per slot
+    // before retirement). The bound below stays true in both regimes and
+    // tightens after M3; the inline comment is the bridge between this test
+    // and M3's removal of gen retirement (research Finding 1.4).
+    // biome-ignore lint/suspicious/noExplicitAny: targeted private read for slot-reuse verification
+    const nextSlot = (store as any).nextSlot as number;
+    expect(nextSlot).toBeLessThan(10);
+  });
+});
+
+// ─── w6 M3: gen welding alloc tests ─────────────────────────────────────
+// feat-20260623-asset-handle-generation M3 — alloc embeds generation into
+// the returned handle via codec.pack(slot, gen). First alloc gen=0 (AC-06);
+// slot 0 sentinel stays pack(0,0)===0 and isLive(0)===false (R6).
+// M3 scope: gen welding only, no gen increment on release (that's M4).
+// Reused slots always get gen=0 in M3.
+describe('w6 M3 UniqueRefStore: gen welding on alloc', () => {
+  it('AC-06: first alloc gen=0 => handleSlot matches raw slot', () => {
+    const store = new UniqueRefStore();
+    const handle = store.alloc('TestAsset', { id: 1 });
+
+    const slot = handleSlot(handle);
+    const gen = handleGeneration(handle);
+
+    expect(gen).toBe(0);
+    // UniqueRefStore.nextSlot starts at 1, so the first alloc should be slot 1
+    expect(slot).toBe(1);
+  });
+
+  it('AC-05: pack(slot,0)===slot for slot 0-5 (sentinel + typical slots)', () => {
+    for (let s = 0; s <= 5; s++) {
+      expect(pack(s, 0)).toBe(s);
+    }
+  });
+
+  it('R6: slot 0 sentinel — pack(0,0)===0 and isLive(0)===false', () => {
+    expect(pack(0, 0)).toBe(0);
+
+    // isLive should return false for any handle whose raw value is 0.
+    // TypeScript disallows constructing Handle<T, 'unique'> with literal 0
+    // from outside toUnique, but isLive reads the raw value — passing
+    // a brand-cast 0 tests the sentinel path.
+    const store = new UniqueRefStore();
+    // biome-ignore lint/suspicious/noExplicitAny: sentinel test pattern
+    expect(store.isLive(0 as any)).toBe(false);
+  });
+
+  it('alloc welds gen into handle — gen extractable via handleGeneration', () => {
+    // After alloc gen welding, handleGeneration returns the gen embedded
+    // during alloc. In M3, gen is always 0 because release does not yet
+    // increment _generations (M4). But the pack(slot,gen) -> handleGeneration
+    // round-trip must work.
+    const store = new UniqueRefStore();
+    const h = store.alloc('TestAsset', { id: 1 });
+    expect(handleGeneration(h)).toBe(0);
+    expect(handleSlot(h)).toBe(1);
+    expect(pack(handleSlot(h), handleGeneration(h))).toBe(unwrapHandle(h));
+    // Not using unwrapHandle directly — using pack+handleSlot+handleGeneration
+    // as indirect verification.
+    // biome-ignore lint/suspicious/noExplicitAny: access the raw brand value
+    expect(h as any as number).toBe(pack(1, 0));
+  });
+
+  it('resolve works correctly after gen-welded alloc (gen increments on release, M4)', () => {
+    // Alloc + release + re-alloc: the second handle resolves to the
+    // second payload. After M4, release increments gen, re-alloc gets gen=1.
+    const store = new UniqueRefStore();
+    const h1 = store.alloc('MeshAsset', { mesh: 'cube' });
+    expect(handleGeneration(h1)).toBe(0);
+
+    expect(store.release(h1).ok).toBe(true);
+
+    const h2 = store.alloc('MeshAsset', { mesh: 'sphere' });
+    // M4: release incremented gen to 1, so re-alloc gets gen=1
+    expect(handleGeneration(h2)).toBe(1);
+
+    const r = store.resolve(h2);
+    expect(r.ok).toBe(true);
+    if (r.ok) {
+      expect(r.value).toEqual({ mesh: 'sphere' });
+    }
+  });
+
+  it('alloc with onRelease fires after gen-welded release', () => {
+    const cb = vi.fn();
+    const store = new UniqueRefStore();
+    const h = store.alloc('Asset', { key: 1 }, cb);
+    expect(store.release(h).ok).toBe(true);
+    expect(cb).toHaveBeenCalledTimes(1);
+    expect(cb).toHaveBeenCalledWith({ key: 1 });
+  });
+
+  it('R6: slot 0 sentinel isLive false — alloc never produces slot 0', () => {
+    const store = new UniqueRefStore();
+    // Alloc 100 handles and release them — slot 0 should never appear
+    // because nextSlot starts at 1 and freeSlots only contain released
+    // slots >= 1.
+    const handles: ReturnType<typeof store.alloc>[] = [];
+    for (let i = 0; i < 100; i++) {
+      handles.push(store.alloc('Test', { id: i }));
+    }
+    for (const h of handles) {
+      expect(handleSlot(h)).toBeGreaterThanOrEqual(1);
+      expect(store.release(h).ok).toBe(true);
+    }
+    // All slots recycled — still no slot 0
+    const h = store.alloc('Test', { id: 999 });
+    expect(handleSlot(h)).toBeGreaterThanOrEqual(1);
+  });
+
+  it('M4: alloc after release reuses slot with gen 1 (gen increments on release)', () => {
+    const store = new UniqueRefStore();
+    const h1 = store.alloc('MeshAsset', { mesh: 'cube' });
+    void handleSlot(h1); // probe slot
+    expect(store.release(h1).ok).toBe(true);
+
+    const h2 = store.alloc('MeshAsset', { mesh: 'sphere' });
+    expect(handleGeneration(h2)).toBe(1);
+
+    const r2 = store.resolve(h2);
+    expect(r2.ok).toBe(true);
+    if (r2.ok) expect(r2.value).toEqual({ mesh: 'sphere' });
+
+    // h1 (gen=0) is stale now
+    const r1 = store.resolve(h1);
+    expect(r1.ok).toBe(false);
+    if (!r1.ok) expect(r1.error.code).toBe('unique-ref-stale');
+  });
+});
+
+// ─── w9 M4: stale detection unit tests (red phase) ─────────────────────
+// feat-20260623-asset-handle-generation M4 — gen comparison on
+// resolve/release (UniqueRefStore has no retain). RED phase: gen increment
+// on release is NOT implemented yet, so stale detections return ok.
+describe('w9 M4 UniqueRefStore: stale detection (resolve/release + retire)', () => {
+  it('AC-01: stale resolve returns error with code unique-ref-stale', () => {
+    const store = new UniqueRefStore();
+    const h1 = store.alloc('MeshAsset', { mesh: 'cube' });
+    // Release bumps gen 0->1, then re-alloc gets gen=1.
+    expect(store.release(h1).ok).toBe(true);
+
+    const h2 = store.alloc('MeshAsset', { mesh: 'sphere' });
+    expect(handleGeneration(h2)).toBe(1);
+
+    // h1 (gen=0) is stale
+    const r = store.resolve(h1);
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.error.code).toBe('unique-ref-stale');
+    }
+    // h2 resolves normally
+    const r2 = store.resolve(h2);
+    expect(r2.ok).toBe(true);
+    if (r2.ok) {
+      expect(r2.value).toEqual({ mesh: 'sphere' });
+    }
+  });
+
+  it('AC-01: stale resolve never returns a payload', () => {
+    const store = new UniqueRefStore();
+    const h1 = store.alloc('MeshAsset', { mesh: 'cube' });
+    expect(store.release(h1).ok).toBe(true);
+    store.alloc('MeshAsset', { mesh: 'sphere' });
+
+    const r = store.resolve(h1);
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      // biome-ignore lint/suspicious/noExplicitAny: accessing value on Result union error branch to verify no payload leak
+      expect((r as any).value).toBeUndefined();
+    }
+  });
+
+  it('AC-03: stale release returns error, does NOT drop payload of new holder', () => {
+    const store = new UniqueRefStore();
+    const h1 = store.alloc('MeshAsset', { mesh: 'cube' });
+    expect(store.release(h1).ok).toBe(true);
+
+    const h2 = store.alloc('MeshAsset', { mesh: 'sphere' });
+    // h2 is live. Stale release of h1 must NOT drop h2's payload.
+    const r = store.release(h1);
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.error.code).toBe('unique-ref-stale');
+    }
+
+    // h2 is still live — resolve should succeed
+    const r2 = store.resolve(h2);
+    expect(r2.ok).toBe(true);
+    if (r2.ok) {
+      expect(r2.value).toEqual({ mesh: 'sphere' });
+    }
+  });
+
+  it('AC-03: stale release does not trigger onRelease callback', () => {
+    const cb = vi.fn();
+    const store = new UniqueRefStore();
+    const h1 = store.alloc('MeshAsset', { mesh: 'cube' }, cb);
+    expect(store.release(h1).ok).toBe(true);
+
+    // Re-alloc with new gen
+    store.alloc('MeshAsset', { mesh: 'sphere' });
+
+    // Stale release of h1 should NOT fire h2's callback
+    const r = store.release(h1);
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.error.code).toBe('unique-ref-stale');
+    }
+    expect(cb).toHaveBeenCalledTimes(1); // only from the first release (gen match)
+  });
+
+  it('AC-04: new handle after reuse resolves and releases normally', () => {
+    const store = new UniqueRefStore();
+    const h1 = store.alloc('MeshAsset', { mesh: 'cube' });
+    expect(store.release(h1).ok).toBe(true);
+
+    const h2 = store.alloc('MeshAsset', { mesh: 'sphere' });
+    expect(handleGeneration(h2)).toBe(1);
+
+    // resolve
+    const r = store.resolve(h2);
+    expect(r.ok).toBe(true);
+    if (r.ok) expect(r.value).toEqual({ mesh: 'sphere' });
+
+    // release
+    expect(store.release(h2).ok).toBe(true);
+
+    // h1 still stale
+    const rStale = store.resolve(h1);
+    expect(rStale.ok).toBe(false);
+    if (!rStale.ok) {
+      expect(rStale.error.code).toBe('unique-ref-stale');
+    }
+  });
+
+  it('AC-07: retire-on-255 — gen pushed past MAX_GEN then slot not recycled', () => {
+    const store = new UniqueRefStore();
+    const h = store.alloc('MeshAsset', { mesh: 'cube' });
+    const slot = handleSlot(h);
+
+    // gen=255 is still a usable handle under the new gen > MAX_GEN predicate.
+    // Bump _generations[slot] to 255 and push to freeSlots so the next alloc
+    // reuses it with gen=255.
+    // biome-ignore lint/suspicious/noExplicitAny: private mutation for retire edge boundary
+    (store as any)._generations[slot] = 255;
+    // biome-ignore lint/suspicious/noExplicitAny: push slot to free list so alloc reuses
+    (store as any).freeSlots.push(slot);
+
+    // Alloc reuses slot with gen=255
+    const h2 = store.alloc('MeshAsset', { mesh: 'sphere' });
+    expect(handleGeneration(h2)).toBe(255);
+    // Verify gen=255 is a usable handle — resolve succeeds.
+    const rResolve = store.resolve(h2);
+    expect(rResolve.ok).toBe(true);
+
+    // Release h2: gen matches, gen++ to 256 (>MAX_GEN), slot retired.
+    expect(store.release(h2).ok).toBe(true);
+
+    // Slot must not be recycled (retired)
+    // biome-ignore lint/suspicious/noExplicitAny: private read
+    const freeSlots: number[] = (store as any).freeSlots;
+    expect(freeSlots.indexOf(slot)).toBe(-1);
+  });
+});

package/src/__tests__/utils/handle-numeric.ts

@@ -0,0 +1,30 @@
+// @forgeax/engine-ecs — test fixture: brand-unwrap helper.
+//
+// @internal Test-only brand unwrapping for Object.is identity assertions
+// across the family of phantom-branded numeric ids (Handle<T, M>, Entity,
+// SceneInstanceId — all defined as `number & {brand}`). Charter P4
+// (consistent abstraction) — collapses 42 historical brand-unwrap cast
+// sites into one helper so AI users reading the test fixtures see a
+// single intent marker rather than scattered casts. The helper is
+// fixture-scope (lives under __tests__/utils, never re-exported from
+// packages/ecs/src/index.ts) and must not appear in any production code
+// path (AC-08 grep gate).
+//
+// Implementation uses `Number()` to preserve numeric identity while
+// shedding the phantom brand; this avoids the legacy double-cast idiom
+// and keeps the AC-07 grep gate clean even though this file lives
+// inside packages/ecs/src/__tests__/.
+
+/**
+ * Unwrap a phantom-branded numeric id (`Handle<T, M>`, `Entity`,
+ * `SceneInstanceId`, ...) to its underlying `number` representation. Used
+ * by test fixtures that need to compare brand-erased numeric values via
+ * `Object.is` / `===`.
+ *
+ * The constraint `H extends number` keeps the helper aligned with the
+ * brand idiom (`number & {brand}`) used throughout the codebase without
+ * coupling to any specific brand class.
+ *
+ * @internal
+ */
+export const handleNumeric = <H extends number>(h: H): number => Number(h);

package/src/__tests__/validation-root-surface.unit.test.ts

@@ -0,0 +1,15 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+const rootSource = readFileSync(new URL('../index.ts', import.meta.url), 'utf8');
+
+describe('ECS validation helpers stay owner-local', () => {
+  it('does not project write-path validators from the public root', async () => {
+    expect(rootSource).not.toContain('validateSharedFieldValues');
+    expect(rootSource).not.toContain('validateEnumFieldValues');
+
+    const root = (await import('../index')) as Record<string, unknown>;
+    expect(root).not.toHaveProperty('validateSharedFieldValues');
+    expect(root).not.toHaveProperty('validateEnumFieldValues');
+  });
+});

package/src/__tests__/visibility-atomic-write.unit.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it } from 'vitest';
+import { defineComponent } from '../component';
+import { World } from '../world';
+
+const VisibilityLike = defineComponent('M1VisibilityLikeAtomic', {
+  state: { type: 'enum', default: 0, labels: { inherited: 0, hidden: 1, visible: 2 } },
+});
+
+const Position = defineComponent('M1VisibilityAtomicPosition', {
+  value: 'f32',
+});
+
+function expectInvalidValue(result: { ok: boolean; error?: unknown }, entity?: number): void {
+  expect(result.ok).toBe(false);
+  if (result.ok) return;
+  const error = result.error as {
+    code: string;
+    expected: string;
+    hint: string;
+    detail: {
+      entity: number | undefined;
+      component: string;
+      field: string;
+      received: unknown;
+      allowedValues: Readonly<Record<string, number>>;
+    };
+  };
+  expect(error.code).toBe('component-field-invalid-value');
+  expect(error.expected).toContain('inherited');
+  expect(error.hint).toContain('VisibilityLike');
+  expect(error.detail).toEqual({
+    entity,
+    component: 'M1VisibilityLikeAtomic',
+    field: 'state',
+    received: 9,
+    allowedValues: { inherited: 0, hidden: 1, visible: 2 },
+  });
+}
+
+describe('M1 Visibility enum writes are atomic', () => {
+  it('rejects an invalid enum during spawn before creating the row', () => {
+    const world = new World();
+
+    const result = world.spawn({ component: VisibilityLike, data: { state: 9 } });
+
+    expectInvalidValue(result);
+    expect(world.spawn({ component: Position, data: { value: 1 } }).unwrap()).toBe(0);
+  });
+
+  it('rejects an invalid enum during addComponent before archetype migration', () => {
+    const world = new World();
+    const entity = world.spawn({ component: Position, data: { value: 1 } }).unwrap();
+
+    const result = world.addComponent(entity, {
+      component: VisibilityLike,
+      data: { state: 9 },
+    });
+
+    expectInvalidValue(result, entity);
+    expect(world.get(entity, VisibilityLike).ok).toBe(false);
+    expect(world.get(entity, Position).unwrap().value).toBe(1);
+  });
+
+  it('rejects an invalid enum during set and preserves the previous value', () => {
+    const world = new World();
+    const entity = world.spawn({ component: VisibilityLike, data: { state: 1 } }).unwrap();
+
+    const result = world.set(entity, VisibilityLike, { state: 9 });
+
+    expectInvalidValue(result, entity);
+    expect(world.get(entity, VisibilityLike).unwrap().state).toBe(1);
+  });
+
+  it('accepts every declared enum value through all three write entries', () => {
+    const world = new World();
+    const entity = world.spawn({ component: VisibilityLike, data: { state: 0 } }).unwrap();
+
+    expect(world.set(entity, VisibilityLike, { state: 1 }).ok).toBe(true);
+    expect(world.addComponent(entity, { component: Position, data: { value: 2 } }).ok).toBe(true);
+    expect(world.get(entity, VisibilityLike).unwrap().state).toBe(1);
+  });
+});