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

package/src/__tests__/field-value-type.test-d.ts

@@ -0,0 +1,57 @@
+// Compile-time type-derivation tests for the FieldValueType<T> 4-keyword
+// TypedArray contract after the M1 buffer/array vocab collapse (w2, AC-02).
+//
+// Locks the new contract: the four schema-vocab keywords for byte / typed
+// array storage all resolve to a concrete TypedArray (or Uint8Array for the
+// byte-only `buffer` family) without an intermediate view-class wrapper.
+//
+//   FieldValueType<'array<f32>'>      => Float32Array
+//   FieldValueType<'array<entity>'>   => Uint32Array (Entity column storage)
+//   FieldValueType<'buffer'>          => Uint8Array
+//   FieldValueType<'buffer<8>'>       => Uint8Array
+//
+// Pre-M1 (before w4): array<...> derives to Var/FixedArrayView and buffer<N>
+// is unrecognised — both shapes produce TS errors against the expected
+// TypedArray equivalence below; this is the TDD red state.
+//
+// Post-M1 (after w4): the 4 keywords resolve directly to TypedArray and the
+// expectTypeOf assertions hold.
+
+import { describe, expectTypeOf, it } from 'vitest';
+import type { FieldValueType, TypedArrayFor } from '../component';
+
+describe('FieldValueType — buffer/array TypedArray contract (w2, AC-02)', () => {
+  it("FieldValueType<'array<f32>'> resolves to Float32Array", () => {
+    expectTypeOf<FieldValueType<'array<f32>'>>().toEqualTypeOf<Float32Array>();
+  });
+
+  it("FieldValueType<'array<u32>'> resolves to Uint32Array", () => {
+    expectTypeOf<FieldValueType<'array<u32>'>>().toEqualTypeOf<Uint32Array>();
+  });
+
+  it("FieldValueType<'array<entity>'> resolves to Uint32Array (Entity column storage)", () => {
+    expectTypeOf<FieldValueType<'array<entity>'>>().toEqualTypeOf<Uint32Array>();
+  });
+
+  it("FieldValueType<'array<f32, 16>'> resolves to Float32Array (fixed capacity)", () => {
+    expectTypeOf<FieldValueType<'array<f32, 16>'>>().toEqualTypeOf<Float32Array>();
+  });
+
+  it("FieldValueType<'buffer'> resolves to Uint8Array (variable byte slot)", () => {
+    expectTypeOf<FieldValueType<'buffer'>>().toEqualTypeOf<Uint8Array>();
+  });
+
+  it("FieldValueType<'buffer<8>'> resolves to Uint8Array (fixed byte slot)", () => {
+    expectTypeOf<FieldValueType<'buffer<8>'>>().toEqualTypeOf<Uint8Array>();
+  });
+});
+
+describe('TypedArrayFor — public single-export contract (w2, AC-02)', () => {
+  it("TypedArrayFor<'f32'> is Float32Array", () => {
+    expectTypeOf<TypedArrayFor<'f32'>>().toEqualTypeOf<Float32Array>();
+  });
+
+  it("TypedArrayFor<'u32'> is Uint32Array", () => {
+    expectTypeOf<TypedArrayFor<'u32'>>().toEqualTypeOf<Uint32Array>();
+  });
+});

package/src/__tests__/fixed-update.unit.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, it } from 'vitest';
+import { FixedUpdate, Update } from '../schedule-token';
+import { FixedTime, Time } from '../time';
+import { World } from '../world';
+
+describe('fixed update loop', () => {
+  it('runs zero, one, and multiple fixed iterations while preserving remainder', () => {
+    const world = new World();
+    const ticks: number[] = [];
+    world.addSystem(FixedUpdate, {
+      name: 'fixed',
+      queries: [],
+      fn: (_world) => ticks.push(_world.getResource<typeof FixedTime>(FixedTime).tick),
+    });
+
+    expect(world.update(0.01).ok).toBe(true);
+    expect(world.update(0.01).ok).toBe(true);
+    expect(world.update(2 / 60).ok).toBe(true);
+    expect(ticks).toEqual([1, 2, 3]);
+    expect(world.getResource<typeof FixedTime>(FixedTime).tick).toBe(3);
+    expect(world.getResource<typeof FixedTime>(FixedTime).overstep).toBeCloseTo(1 / 300, 12);
+  });
+
+  it('clamps before accumulating fixed time and records exact dropped metrics', () => {
+    const world = new World();
+    let fixedRuns = 0;
+    world.addSystem(FixedUpdate, { name: 'fixed', queries: [], fn: () => fixedRuns++ });
+
+    expect(world.update(5).ok).toBe(true);
+    const time = world.getResource<typeof Time>(Time);
+    const fixed = world.getResource<typeof FixedTime>(FixedTime);
+    expect(time.delta).toBe(0.1);
+    expect(fixedRuns).toBe(4);
+    expect(fixed.droppedUpdates).toBe(1);
+    expect(fixed.droppedSeconds).toBeCloseTo(1 / 60, 12);
+    expect(fixed.overstep).toBeCloseTo(1 / 60, 10);
+  });
+
+  it('does not replay discarded catch-up time on the next healthy frame', () => {
+    const world = new World();
+    let fixedRuns = 0;
+    world.addSystem(FixedUpdate, { name: 'fixed', queries: [], fn: () => fixedRuns++ });
+
+    expect(world.update(5).ok).toBe(true);
+    const afterLargeFrame = world.getResource<typeof FixedTime>(FixedTime);
+    const largeFrameTick = afterLargeFrame.tick;
+    const largeFrameDroppedSeconds = afterLargeFrame.droppedSeconds;
+    const largeFrameDroppedUpdates = afterLargeFrame.droppedUpdates;
+
+    expect(world.update(1 / 60).ok).toBe(true);
+    const afterHealthyFrame = world.getResource<typeof FixedTime>(FixedTime);
+    expect(fixedRuns).toBe(5);
+    expect(afterHealthyFrame.tick).toBe(largeFrameTick + 1);
+    expect(afterHealthyFrame.droppedSeconds).toBe(largeFrameDroppedSeconds);
+    expect(afterHealthyFrame.droppedUpdates).toBe(largeFrameDroppedUpdates);
+  });
+
+  it('runs Update before and after the intrinsic fixed node', () => {
+    const world = new World();
+    const trace: string[] = [];
+    world.addSystem(Update, {
+      name: 'before-fixed',
+      queries: [],
+      before: [FixedUpdate],
+      fn: () => trace.push('before'),
+    });
+    world.addSystem(FixedUpdate, { name: 'fixed', queries: [], fn: () => trace.push('fixed') });
+    world.addSystem(Update, {
+      name: 'after-fixed',
+      queries: [],
+      after: [FixedUpdate],
+      fn: () => trace.push('after'),
+    });
+
+    expect(world.update(1 / 60).ok).toBe(true);
+    expect(trace).toEqual(['before', 'fixed', 'after']);
+  });
+});

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

@@ -0,0 +1,86 @@
+// Compile-time type assertions for the Handle<T,M> brand (w1 + AC-02).
+//
+// Locks two phantom dimensions:
+//   - target T (the asset type tag, e.g. 'MeshAsset' / 'MaterialAsset')
+//   - mode M ('unique' | 'shared')
+//
+// AC-02 requires at least one @ts-expect-error proving cross-mode rejection.
+// Cross-target rejection is also covered. Handle<T,M> still widens to number
+// for GPU upload compatibility.
+//
+// w3: EntityHandle type-level assertions — EntityHandle is numeric (widens
+// to number), and encodeEntity returns an EntityHandle (not a bare number).
+
+import type { Handle } from '@forgeax/engine-types';
+import { describe, expectTypeOf, it } from 'vitest';
+import type { EntityHandle } from '../entity-handle';
+
+describe('Handle<T,M> — phantom brand (w1)', () => {
+  it('Handle<T,M> structurally widens to number (GPU upload compatibility)', () => {
+    type H = Handle<'MeshAsset', 'shared'>;
+    expectTypeOf<H>().toMatchTypeOf<number>();
+  });
+
+  it('Handle<T,managed> and Handle<T,unmanaged> are distinct types', () => {
+    type Managed = Handle<'MaterialAsset', 'unique'>;
+    type Unmanaged = Handle<'MaterialAsset', 'shared'>;
+    // Neither type is assignable to the other under TS structural rules
+    // because the phantom `__handle.mode` differs.
+    expectTypeOf<Managed>().not.toEqualTypeOf<Unmanaged>();
+  });
+
+  it('Handle<A,M> and Handle<B,M> with distinct targets are distinct types', () => {
+    type Mesh = Handle<'MeshAsset', 'shared'>;
+    type Material = Handle<'MaterialAsset', 'shared'>;
+    expectTypeOf<Mesh>().not.toEqualTypeOf<Material>();
+  });
+
+  it('plain number is not assignable to Handle<T,M> (brand prevents accidental construction)', () => {
+    type Mesh = Handle<'MeshAsset', 'shared'>;
+    const n = 42 as number;
+    // @ts-expect-error — plain number cannot be widened to a phantom-branded Handle
+    const h: Mesh = n;
+    void h;
+  });
+
+  it('Handle<T,managed> is not assignable to Handle<T,unmanaged> (cross-mode rejection — AC-02)', () => {
+    type Managed = Handle<'MaterialAsset', 'unique'>;
+    type Unmanaged = Handle<'MaterialAsset', 'shared'>;
+    const m = 0 as unknown as Managed;
+    // @ts-expect-error — managed handle cannot be assigned to an unmanaged slot
+    const u: Unmanaged = m;
+    void u;
+  });
+
+  it('Handle<T,unmanaged> is not assignable to Handle<T,managed> (cross-mode reverse)', () => {
+    type Managed = Handle<'MeshAsset', 'unique'>;
+    type Unmanaged = Handle<'MeshAsset', 'shared'>;
+    const u = 0 as unknown as Unmanaged;
+    // @ts-expect-error — unmanaged handle cannot be assigned to a managed slot
+    const m: Managed = u;
+    void m;
+  });
+
+  it('Handle<A,M> is not assignable to Handle<B,M> (cross-target rejection)', () => {
+    type Mesh = Handle<'MeshAsset', 'shared'>;
+    type Material = Handle<'MaterialAsset', 'shared'>;
+    const mesh = 0 as unknown as Mesh;
+    // @ts-expect-error — mesh handle cannot be assigned to a material handle slot
+    const mat: Material = mesh;
+    void mat;
+  });
+});
+
+// w3: EntityHandle type-level assertions
+describe('[w3] EntityHandle -- numeric brand', () => {
+  it('EntityHandle widens to number (runtime identity is a JS number)', () => {
+    expectTypeOf<EntityHandle>().toMatchTypeOf<number>();
+  });
+
+  it('plain number is not assignable to EntityHandle (brand prevents accidental construction)', () => {
+    const n = 42 as number;
+    // @ts-expect-error -- plain number cannot be widened to phantom-branded EntityHandle
+    const eh: EntityHandle = n;
+    void eh;
+  });
+});