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

package/src/__tests__/query-trs-flat-column-ratio.perf.test.ts

@@ -0,0 +1,194 @@
+// feat-20260709 M2 / w5: query flat-column A/B perf ratio bench (AC-09, D-2/D-9).
+//
+// In-process ratio gate, NOT absolute wallclock (memory
+// absolute-wallclock-perf-gate-flakes-use-in-process-ratio): the same
+// process, same JIT tier, and same allocator time both sides, so the
+// candidate/baseline ratio isolates the column-shape effect from host noise.
+//
+//   Baseline:  10 per-axis f32 scalar columns (the pre-migration Transform
+//              shape, synthesized here so the gate survives the migration).
+//   Candidate: pos array<f32,3> / quat array<f32,4> / scale array<f32,3>
+//              (the post-migration shape), read via the query bundle's flat
+//              stride-N subarray -- `pos[i*3+a]`, zero per-call allocation
+//              (research Finding 5 adjudication table, allowed row).
+//
+// Gate: ratio = candidate_min / baseline_min <= 1.15 (N=10_000 entities,
+// min-of-5 rounds, sides alternate per round to cancel warm-up drift).
+// Expected ratio is ~1.0 or below (3/4-wide contiguous lanes have better
+// locality than 10 scattered columns); 1.15 is anti-noise headroom, not a
+// performance concession.
+//
+// Falsifiability (plan-strategy 5.4, one-time manual check, not in CI):
+// swapping the candidate reader to the `world.get(e, C).pos` materializing
+// path makes the ratio blow past the gate -- verified once by hand during
+// w5 (see milestone report), then restored to the flat form below.
+//
+// skipIf escape hatch (D-2): default OFF. If a specific CI host proves
+// noisy, gate on an env flag here (e.g. FORGEAX_SKIP_TRS_RATIO_BENCH) --
+// deliberately not wired until real-world flake data demands it.
+
+import { describe, expect, it } from 'vitest';
+import { defineComponent } from '../component';
+import { World } from '../world';
+
+const N = 10_000;
+const ROUNDS = 5;
+const INNER_REPEATS = 300;
+const RATIO_GATE = 1.15;
+
+const BaselineTrs10 = defineComponent('W5_BaselineTrs10', {
+  posX: 'f32',
+  posY: 'f32',
+  posZ: 'f32',
+  quatX: 'f32',
+  quatY: 'f32',
+  quatZ: 'f32',
+  quatW: 'f32',
+  scaleX: 'f32',
+  scaleY: 'f32',
+  scaleZ: 'f32',
+});
+
+const CandidateTrsVec = defineComponent('W5_CandidateTrsVec', {
+  pos: { type: 'array<f32, 3>', default: new Float32Array(3) },
+  quat: { type: 'array<f32, 4>', default: new Float32Array([0, 0, 0, 1]) },
+  scale: { type: 'array<f32, 3>', default: new Float32Array([1, 1, 1]) },
+});
+
+function spawnBaselineWorld(): World {
+  const world = new World();
+  for (let i = 0; i < N; i++) {
+    world.spawn({
+      component: BaselineTrs10,
+      data: {
+        posX: i,
+        posY: i * 2,
+        posZ: i * 3,
+        quatX: 0,
+        quatY: 0,
+        quatZ: 0,
+        quatW: 1,
+        scaleX: 1,
+        scaleY: 1,
+        scaleZ: 1,
+      },
+    });
+  }
+  return world;
+}
+
+function spawnCandidateWorld(): World {
+  const world = new World();
+  for (let i = 0; i < N; i++) {
+    world.spawn({
+      component: CandidateTrsVec,
+      data: { pos: [i, i * 2, i * 3], quat: [0, 0, 0, 1], scale: [1, 1, 1] },
+    });
+  }
+  return world;
+}
+
+/** Sum all 10 TRS lanes over every entity via per-axis scalar columns. */
+function traverseBaseline(world: World): number {
+  const query = world.query({ read: [BaselineTrs10] }).unwrap();
+  let sum = 0;
+  for (let rep = 0; rep < INNER_REPEATS; rep++) {
+    for (const span of query.spans().unwrap()) {
+      const b = span.get(BaselineTrs10);
+      const n = span.length;
+      for (let i = 0; i < n; i++) {
+        sum +=
+          (b.posX[i] as number) +
+          (b.posY[i] as number) +
+          (b.posZ[i] as number) +
+          (b.quatX[i] as number) +
+          (b.quatY[i] as number) +
+          (b.quatZ[i] as number) +
+          (b.quatW[i] as number) +
+          (b.scaleX[i] as number) +
+          (b.scaleY[i] as number) +
+          (b.scaleZ[i] as number);
+      }
+    }
+  }
+  return sum;
+}
+
+/** Sum all 10 TRS lanes over every entity via flat stride-N array columns. */
+function traverseCandidate(world: World): number {
+  const query = world.query({ read: [CandidateTrsVec] }).unwrap();
+  let sum = 0;
+  for (let rep = 0; rep < INNER_REPEATS; rep++) {
+    for (const span of query.spans().unwrap()) {
+      const c = span.get(CandidateTrsVec);
+      const pos = c.pos;
+      const quat = c.quat;
+      const scale = c.scale;
+      const n = span.length;
+      for (let i = 0; i < n; i++) {
+        sum +=
+          (pos[i * 3] as number) +
+          (pos[i * 3 + 1] as number) +
+          (pos[i * 3 + 2] as number) +
+          (quat[i * 4] as number) +
+          (quat[i * 4 + 1] as number) +
+          (quat[i * 4 + 2] as number) +
+          (quat[i * 4 + 3] as number) +
+          (scale[i * 3] as number) +
+          (scale[i * 3 + 1] as number) +
+          (scale[i * 3 + 2] as number);
+      }
+    }
+  }
+  return sum;
+}
+
+describe('w5 -- TRS flat-column A/B perf ratio (AC-09)', () => {
+  it(`candidate/baseline traversal ratio stays <= ${RATIO_GATE} (min-of-${ROUNDS}, N=${N})`, () => {
+    const baselineWorld = spawnBaselineWorld();
+    const candidateWorld = spawnCandidateWorld();
+
+    // Warm-up: bring both traversal fns to the same JIT tier before timing.
+    let sink = 0;
+    sink += traverseBaseline(baselineWorld);
+    sink += traverseCandidate(candidateWorld);
+
+    const baselineTimes: number[] = [];
+    const candidateTimes: number[] = [];
+
+    for (let round = 0; round < ROUNDS; round++) {
+      // Alternate side order per round to cancel residual warm-up drift.
+      const baselineFirst = round % 2 === 0;
+      if (baselineFirst) {
+        const b0 = performance.now();
+        sink += traverseBaseline(baselineWorld);
+        baselineTimes.push(performance.now() - b0);
+        const c0 = performance.now();
+        sink += traverseCandidate(candidateWorld);
+        candidateTimes.push(performance.now() - c0);
+      } else {
+        const c0 = performance.now();
+        sink += traverseCandidate(candidateWorld);
+        candidateTimes.push(performance.now() - c0);
+        const b0 = performance.now();
+        sink += traverseBaseline(baselineWorld);
+        baselineTimes.push(performance.now() - b0);
+      }
+    }
+
+    // Both sides sum identical values -- equality doubles as a correctness
+    // check and keeps the traversal loops from being dead-code-eliminated.
+    expect(sink).toBeGreaterThan(0);
+
+    const baselineMin = Math.min(...baselineTimes);
+    const candidateMin = Math.min(...candidateTimes);
+    const ratio = candidateMin / baselineMin;
+
+    // biome-ignore lint/suspicious/noConsole: surface the measured ratio in test output for AC-09 review
+    console.info(
+      `[w5 perf ratio] baseline_min=${baselineMin.toFixed(3)}ms candidate_min=${candidateMin.toFixed(3)}ms ratio=${ratio.toFixed(3)}`,
+    );
+
+    expect(ratio).toBeLessThanOrEqual(RATIO_GATE);
+  });
+});

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

@@ -0,0 +1,196 @@
+import { describe, expect, expectTypeOf, it, vi } from 'vitest';
+import { componentId, defineComponent } from '../component';
+import type { EntityHandle } from '../entity-handle';
+import {
+  QueryDataRequiresFieldsError,
+  QueryDescriptorConflictError,
+  QueryIterationActiveError,
+  QueryIterationInvalidatedError,
+} from '../errors';
+import type { QueryRow } from '../query/query';
+import type { Table } from '../storage/table';
+import { World } from '../world';
+
+import { worldInternal } from '../world-internal';
+
+const Position = defineComponent('QueryPosition', { x: 'f32', y: 'f32' });
+const Velocity = defineComponent('QueryVelocity', { x: 'f32', y: 'f32' });
+const Selected = defineComponent('QuerySelected', {});
+
+function createWorld(): { world: World; first: EntityHandle; second: EntityHandle } {
+  const world = new World();
+  const first = world
+    .spawn(
+      { component: Position, data: { x: 1, y: 2 } },
+      { component: Velocity, data: { x: 3, y: 4 } },
+      { component: Selected, data: {} },
+    )
+    .unwrap();
+  const second = world.spawn({ component: Position, data: { x: 5, y: 6 } }).unwrap();
+  return { world, first, second };
+}
+
+describe('executable Query', () => {
+  it('validates access roles and tag data at creation', () => {
+    const world = new World();
+    const conflict = world.query({ read: [Position], write: [Position] });
+    expect(conflict.ok).toBe(false);
+    if (!conflict.ok) {
+      expect(conflict.error).toBeInstanceOf(QueryDescriptorConflictError);
+      expect(conflict.error.detail).toEqual({
+        componentName: Position.name,
+        roles: ['read', 'write'],
+      });
+    }
+
+    const tagData = world.query({ read: [Selected] });
+    expect(tagData.ok).toBe(false);
+    if (!tagData.ok) expect(tagData.error).toBeInstanceOf(QueryDataRequiresFieldsError);
+  });
+
+  it('iterates each matching entity once and exposes optional data precisely', () => {
+    const { world, first, second } = createWorld();
+    const query = world
+      .query({ read: [Position], optional: [Velocity], with: [Selected] })
+      .unwrap();
+    const seen: number[] = [];
+    for (const row of query) {
+      seen.push(row.entity);
+      expect(row.has(Position)).toBe(true);
+      expect(row.has(Velocity)).toBe(true);
+      expect(row.get(Position).x).toBe(1);
+      expect(row.get(Velocity)?.x).toBe(3);
+    }
+    expect(seen).toEqual([first]);
+    expect(seen).not.toContain(second);
+  });
+
+  it('addresses one matching entity without scanning the query tables', () => {
+    const { world, first, second } = createWorld();
+    const query = world
+      .query({ read: [Position], optional: [Velocity], with: [Selected] })
+      .unwrap();
+
+    const row = query.at(first);
+    expect(row?.entity).toBe(first);
+    expect(row?.get(Position)?.x).toBe(1);
+    expect(query.at(second)).toBeUndefined();
+  });
+
+  it('checks optional presence without materialising a component row', () => {
+    const { world } = createWorld();
+    const query = world.query({ read: [Position], optional: [Velocity] }).unwrap();
+    const readRowSpy = vi.spyOn(world[worldInternal], 'getQueryRow');
+
+    const presence: boolean[] = [];
+    for (const row of query) presence.push(row.has(Velocity));
+    expect(presence).toEqual([true, false]);
+    expect(readRowSpy).not.toHaveBeenCalled();
+  });
+
+  it('row.mut marks one epoch and writes through the component owner', () => {
+    const { world, first } = createWorld();
+    const query = world.query({ write: [Position], with: [Selected] }).unwrap();
+    const before = world[worldInternal].getMutationEpoch();
+    for (const row of query) {
+      const position = row.mut(Position);
+      position.x += 10;
+      position.y = 20;
+    }
+    expect(world[worldInternal].getMutationEpoch()).toBe(before + 1);
+    expect(world.get(first, Position).unwrap()).toMatchObject({ x: 11, y: 20 });
+  });
+
+  it('spans are zero-copy and span.mut marks the whole range once', () => {
+    const { world, first, second } = createWorld();
+    const query = world.query({ write: [Position] }).unwrap();
+    const spans = query.spans().unwrap();
+    const before = world[worldInternal].getMutationEpoch();
+    const buffers = new Set(
+      world[worldInternal].getGraph().tables.flatMap((table: Table) => {
+        const buffer = table.storage.get(componentId(Position))?.fields.get('x')?.view.buffer;
+        return buffer === undefined ? [] : [buffer];
+      }),
+    );
+    let count = 0;
+    let spanCount = 0;
+    let nextX = 42;
+    for (const span of spans) {
+      spanCount += 1;
+      const positions = span.mut(Position);
+      count += span.length;
+      for (let index = 0; index < span.length; index++) positions.x[index] = nextX++;
+      expect(buffers.has(positions.x.buffer)).toBe(true);
+    }
+    expect(count).toBe(2);
+    expect(world[worldInternal].getMutationEpoch()).toBe(before + spanCount);
+    expect(world.get(first, Position).unwrap().x).toBe(42);
+    expect(world.get(second, Position).unwrap().x).toBe(43);
+  });
+
+  it('exposes packed readonly entity identities on each span', () => {
+    const { world, first, second } = createWorld();
+    const query = world.query({ read: [Position] }).unwrap();
+    const spans = [...query.spans().unwrap()];
+
+    expect(spans.reduce((count, span) => count + span.length, 0)).toBe(2);
+    expect(spans.flatMap((span) => Array.from(span.entities))).toEqual([first, second]);
+    expect(spans[0]?.get(Position).x[0]).toBe(1);
+  });
+
+  it('returns structured span capability failures', () => {
+    const world = new World();
+    const optional = world
+      .query({ read: [Position], optional: [Velocity] })
+      .unwrap()
+      .spans();
+    expect(!optional.ok && optional.error.detail.reason).toBe('optional-data');
+
+    const changed = world
+      .query({ read: [Position], changed: [Position] })
+      .unwrap()
+      .spans();
+    expect(!changed.ok && changed.error.detail.reason).toBe('row-change-filter');
+  });
+
+  it('does not commit observation after partial iteration', () => {
+    const { world, first, second } = createWorld();
+    const query = world.query({ read: [Position], changed: [Position] }).unwrap();
+    const iterator = query[Symbol.iterator]();
+    expect(iterator.next().done).toBe(false);
+    iterator.return?.();
+
+    const seen: EntityHandle[] = [];
+    for (const row of query) seen.push(row.entity);
+    expect(seen).toEqual([first, second]);
+  });
+
+  it('keeps same-frame late writes for the next observation', () => {
+    const { world, first } = createWorld();
+    const query = world.query({ read: [Position], changed: [Position] }).unwrap();
+    expect([...query].length).toBe(2);
+    world.set(first, Position, { x: 9 }).unwrap();
+    const seen: EntityHandle[] = [];
+    for (const row of query) seen.push(row.entity);
+    expect(seen).toEqual([first]);
+  });
+
+  it('fails fast on reentry and synchronous structural invalidation', () => {
+    const { world } = createWorld();
+    const query = world.query({ read: [Position] }).unwrap();
+    const iterator = query[Symbol.iterator]();
+    expect(iterator.next().done).toBe(false);
+    expect(() => query[Symbol.iterator]()).toThrow(QueryIterationActiveError);
+    iterator.return?.();
+
+    const invalidated = query[Symbol.iterator]();
+    expect(invalidated.next().done).toBe(false);
+    world.spawn({ component: Position, data: { x: 0, y: 0 } }).unwrap();
+    expect(() => invalidated.next()).toThrow(QueryIterationInvalidatedError);
+  });
+
+  it('infers row access without casts', () => {
+    type Row = QueryRow<readonly [typeof Position], readonly [typeof Velocity], readonly []>;
+    expectTypeOf<Row['entity']>().toBeNumber();
+  });
+});

package/src/__tests__/relationship-index.perf.test.ts

@@ -0,0 +1,126 @@
+import os from 'node:os';
+import { describe, expect, it } from 'vitest';
+import type { EntityHandle } from '../entity-handle';
+import { defineRelationship } from '../relationship-index';
+import { World } from '../world';
+
+const SAMPLE_ROUNDS = 7;
+const PARENT_COUNT = 8;
+const CHILD_COUNT = 512;
+const pair = defineRelationship({
+  sourceName: 'PerfWorldRelationshipSource',
+  sourceField: 'target',
+  targetName: 'PerfWorldRelationshipTargets',
+  targetField: 'sources',
+});
+
+type SampleStats = {
+  readonly medianMs: number;
+  readonly p95Ms: number;
+  readonly ci95Ms: readonly [number, number];
+  readonly sampleCount: number;
+};
+
+function percentile(samples: readonly number[], quantile: number): number {
+  const sorted = [...samples].sort((a, b) => a - b);
+  return sorted[Math.min(sorted.length - 1, Math.ceil(sorted.length * quantile) - 1)] ?? 0;
+}
+
+function summarize(samples: readonly number[]): SampleStats {
+  const mean = samples.reduce((sum, sample) => sum + sample, 0) / samples.length;
+  const variance =
+    samples.reduce((sum, sample) => sum + (sample - mean) ** 2, 0) /
+    Math.max(1, samples.length - 1);
+  const margin = 1.96 * Math.sqrt(variance / samples.length);
+  return {
+    medianMs: percentile(samples, 0.5),
+    p95Ms: percentile(samples, 0.95),
+    ci95Ms: [mean - margin, mean + margin],
+    sampleCount: samples.length,
+  };
+}
+
+function makeFixture(): {
+  world: World;
+  parents: readonly EntityHandle[];
+  children: readonly EntityHandle[];
+} {
+  const world = new World();
+  const parents = Array.from({ length: PARENT_COUNT }, () => world.spawn().unwrap());
+  const children: EntityHandle[] = [];
+  for (let index = 0; index < CHILD_COUNT; index += 1) {
+    const child = world.spawn().unwrap();
+    const parent = parents[index % PARENT_COUNT];
+    if (parent === undefined) throw new Error('relationship benchmark parent missing');
+    world.addChild(parent, child, pair.source, { target: parent }).unwrap();
+    children.push(child);
+  }
+  return { world, parents, children };
+}
+
+function runWorldWorkload(mode: 'baseline' | 'candidate'): number {
+  const { world, parents, children } = makeFixture();
+  for (let index = 0; index < children.length; index += 1) {
+    const child = children[index];
+    const nextParent = parents[(index + 1) % PARENT_COUNT];
+    if (child === undefined || nextParent === undefined)
+      throw new Error('benchmark entity missing');
+    world.reparent(child, nextParent, pair.source, { target: nextParent }).unwrap();
+    world.removeChild(nextParent, child, pair.source).unwrap();
+    world.addChild(nextParent, child, pair.source, { target: nextParent }).unwrap();
+  }
+
+  let count = 0;
+  if (mode === 'candidate') {
+    for (const parent of parents) count += world.get(parent, pair.target).unwrap().sources.length;
+  } else {
+    const sources = world.query({ read: [pair.source] }).unwrap();
+    for (const parent of parents) {
+      for (const row of sources) {
+        if (row.get(pair.source).target === parent) count += 1;
+      }
+    }
+  }
+  return count;
+}
+
+function measure(mode: 'baseline' | 'candidate'): SampleStats {
+  const samples: number[] = [];
+  for (let round = 0; round < SAMPLE_ROUNDS; round += 1) {
+    const start = performance.now();
+    const count = runWorldWorkload(mode);
+    samples.push(performance.now() - start);
+    if (count !== CHILD_COUNT) throw new Error(`relationship workload count mismatch: ${count}`);
+  }
+  return summarize(samples);
+}
+
+describe('M2 relationship World workload', () => {
+  it('collects same-semantics baseline/candidate attach-detach-reparent-read evidence', () => {
+    const baseline = measure('baseline');
+    const candidate = measure('candidate');
+    const environment = {
+      node: process.version,
+      platform: process.platform,
+      arch: process.arch,
+      cpu: os.cpus()[0]?.model,
+    };
+    const p95Stop = candidate.p95Ms > baseline.p95Ms * 1.05;
+    // biome-ignore lint/suspicious/noConsole: benchmark emits machine-readable evidence
+    console.info(
+      JSON.stringify({
+        schemaVersion: 1,
+        workload: 'world-relationship-attach-detach-reparent-read',
+        baseline,
+        candidate,
+        environment,
+        workloadShape: { parents: PARENT_COUNT, children: CHILD_COUNT, rounds: SAMPLE_ROUNDS },
+        stopRule: 'candidate p95 > baseline p95 * 1.05 requires human decision',
+        p95Stop,
+      }),
+    );
+    expect(baseline.sampleCount).toBe(SAMPLE_ROUNDS);
+    expect(candidate.sampleCount).toBe(SAMPLE_ROUNDS);
+    expect(p95Stop).toBe(false);
+  });
+});

package/src/__tests__/relationship-index.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from 'vitest';
+import { componentSchema } from '../component';
+import { componentDefinition } from '../component-schema';
+import { defineRelationship, RelationshipIndex, relationshipRole } from '../relationship-index';
+import { World } from '../world';
+
+describe('relationship index', () => {
+  it('keeps source writable and target materialized/read-only by role', () => {
+    const pair = defineRelationship({
+      sourceName: 'IndexSource',
+      sourceField: 'target',
+      targetName: 'IndexTargets',
+      targetField: 'sources',
+    });
+    expect(relationshipRole(pair.source)?.kind).toBe('source');
+    expect(relationshipRole(pair.target)?.kind).toBe('target');
+    expect(componentDefinition(pair.target).fields.sources?.transient).toBe(true);
+    expect(componentSchema(pair.target).sources).toBe('array<entity>');
+  });
+
+  it('stores only source slots; World owns the materialized target array', () => {
+    const index = new RelationshipIndex();
+    const parentA = 1 as never;
+    const parentB = 2 as never;
+    const first = 11 as never;
+    const second = 12 as never;
+    index.attach(first, parentA, 0);
+    index.attach(second, parentA, 1);
+    expect(index.slotOf(second)).toBe(1);
+    expect(index.detach(first)).toBe(true);
+    index.updateSlot(second, parentA, 0);
+    expect(index.slotOf(second)).toBe(0);
+    index.reparent(second, parentB, 0);
+    expect(index.targetOf(second)).toBe(parentB);
+    expect(index.epoch).toBeGreaterThan(0);
+  });
+
+  it('recovers only from the supplied R source records', () => {
+    const index = new RelationshipIndex();
+    index.recover([
+      [11 as never, 1 as never],
+      [12 as never, 1 as never],
+    ]);
+    expect(index.slotOf(11 as never)).toBe(0);
+    expect(index.slotOf(12 as never)).toBe(1);
+    expect(index.targetOf(12 as never)).toBe(1);
+  });
+
+  it('materializes the target and rejects direct target writes', () => {
+    const pair = defineRelationship({
+      sourceName: 'WorldSource',
+      sourceField: 'target',
+      targetName: 'WorldTargets',
+      targetField: 'sources',
+    });
+    const world = new World();
+    const target = world.spawn().unwrap();
+    const source = world.spawn({ component: pair.source, data: { target } }).unwrap();
+    expect(world.get(target, pair.target).unwrap().sources).toContain(source);
+    // @ts-expect-error relationship targets are read-only projections.
+    expect(world.set(target, pair.target, { sources: [] }).ok).toBe(false);
+    // @ts-expect-error relationship targets are read-only projections.
+    expect(world.removeComponent(target, pair.target).ok).toBe(false);
+    // @ts-expect-error relationship targets are read-only projections.
+    expect(world.addComponent(target, { component: pair.target, data: { sources: [] } }).ok).toBe(
+      false,
+    );
+    world.spawn({ component: pair.target, data: { sources: [] } });
+  });
+});

package/src/__tests__/scalar-field-type-owner.test-d.ts

@@ -0,0 +1,71 @@
+import { describe, expectTypeOf, it } from 'vitest';
+import {
+  defineComponent,
+  type FieldValueType,
+  type ScalarFieldType,
+  type SchemaFieldType,
+  type SchemaOf,
+  type ShapeOf,
+} from '../component';
+
+const expectedScalarTypes = [
+  'f32',
+  'f64',
+  'i32',
+  'u32',
+  'i16',
+  'u16',
+  'i8',
+  'u8',
+  'bool',
+  'enum',
+  'ref',
+] as const satisfies readonly ScalarFieldType[];
+type ExpectedScalarFieldType = (typeof expectedScalarTypes)[number];
+
+const ScalarFields = defineComponent('ScalarFieldTypeOwnerProof', {
+  f32: 'f32',
+  f64: 'f64',
+  i32: 'i32',
+  u32: 'u32',
+  i16: 'i16',
+  u16: 'u16',
+  i8: 'i8',
+  u8: 'u8',
+  bool: 'bool',
+  enum: 'enum',
+  ref: 'ref',
+});
+
+describe('ScalarFieldType owner', () => {
+  it('keeps the exact eleven-key scalar vocabulary', () => {
+    expectTypeOf<ScalarFieldType>().toEqualTypeOf<ExpectedScalarFieldType>();
+    expectTypeOf<ExpectedScalarFieldType>().toEqualTypeOf<ScalarFieldType>();
+    expectTypeOf(expectedScalarTypes).toMatchTypeOf<readonly SchemaFieldType[]>();
+
+    // @ts-expect-error unknown schema keywords remain outside the scalar union.
+    const invalid: ScalarFieldType = 'scalar-not-real';
+    void invalid;
+  });
+
+  it('preserves scalar schema acceptance and value declarations', () => {
+    type Shape = ShapeOf<SchemaOf<typeof ScalarFields>>;
+    expectTypeOf<Shape>().toEqualTypeOf<{
+      readonly f32: number;
+      readonly f64: number;
+      readonly i32: number;
+      readonly u32: number;
+      readonly i16: number;
+      readonly u16: number;
+      readonly i8: number;
+      readonly u8: number;
+      readonly bool: boolean;
+      readonly enum: number;
+      readonly ref: number;
+    }>();
+
+    expectTypeOf<FieldValueType<'f32'>>().toEqualTypeOf<number>();
+    expectTypeOf<FieldValueType<'bool'>>().toEqualTypeOf<boolean>();
+    expectTypeOf<FieldValueType<'ref'>>().toEqualTypeOf<number>();
+  });
+});

package/src/__tests__/schedule-determinism.unit.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest';
+import { FixedUpdate, Update } from '../schedule-token';
+import { World } from '../world';
+
+function runTrace(deltas: readonly number[]): string[] {
+  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'),
+  });
+
+  for (const delta of deltas) expect(world.update(delta).ok).toBe(true);
+  return trace;
+}
+
+describe('schedule ordering determinism', () => {
+  it('produces the same trace for the same explicit delta sequence', () => {
+    const deltas = [0, 1 / 120, 1 / 120, 1 / 60, 0.01];
+
+    expect(runTrace(deltas)).toEqual(runTrace(deltas));
+  });
+
+  it('preserves before and after ordering around fixed runs', () => {
+    expect(runTrace([1 / 60])).toEqual(['before', 'fixed', 'after']);
+  });
+});