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

package/src/__tests__/ecs-core-reduction.perf.test.ts

@@ -0,0 +1,260 @@
+import { execFileSync } from 'node:child_process';
+import os from 'node:os';
+import {
+  type Component,
+  defineComponent,
+  defineRelationship,
+  type EntityHandle,
+  Time,
+  Update,
+  World,
+} from '@forgeax/engine-ecs';
+import { describe, expect, it } from 'vitest';
+
+const { source: ChildOf, target: Children } = defineRelationship({
+  sourceName: 'M0PerfChildOf',
+  sourceField: 'parent',
+  targetName: 'M0PerfChildren',
+  targetField: 'entities',
+  exclusive: true,
+  linkedSpawn: true,
+});
+
+const ENTITY_COUNT = 100_000;
+const ROOT_COUNT = 1_000;
+const COMMAND_COUNT = 10_000;
+const CLOCK_READ_COUNT = 10_000_000;
+const SAMPLE_ROUNDS = 3;
+
+type Sample = {
+  readonly name: string;
+  readonly samplesMs: number[];
+  readonly medianMs: number;
+  readonly p95Ms: number;
+  readonly ci95Ms: readonly [number, number];
+  readonly workload: Record<string, number>;
+};
+
+function percentile(samples: readonly number[], quantile: number): number {
+  const ordered = [...samples].sort((a, b) => a - b);
+  const index = Math.min(ordered.length - 1, Math.ceil(ordered.length * quantile) - 1);
+  return ordered[index] ?? 0;
+}
+
+function summarize(name: string, samplesMs: number[], workload: Record<string, number>): Sample {
+  const mean = samplesMs.reduce((sum, sample) => sum + sample, 0) / samplesMs.length;
+  const variance =
+    samplesMs.reduce((sum, sample) => sum + (sample - mean) ** 2, 0) /
+    Math.max(1, samplesMs.length - 1);
+  const margin = 1.96 * Math.sqrt(variance / samplesMs.length);
+  return {
+    name,
+    samplesMs,
+    medianMs: percentile(samplesMs, 0.5),
+    p95Ms: percentile(samplesMs, 0.95),
+    ci95Ms: [mean - margin, mean + margin],
+    workload,
+  };
+}
+
+function measure(name: string, run: () => number, workload: Record<string, number>): Sample {
+  const samples: number[] = [];
+  for (let round = 0; round < SAMPLE_ROUNDS; round += 1) {
+    const start = performance.now();
+    const result = run();
+    samples.push(performance.now() - start);
+    if (result < 0) throw new Error('M0 benchmark sink underflow');
+  }
+  return summarize(name, samples, workload);
+}
+
+function createHierarchy(): {
+  world: World;
+  roots: EntityHandle[];
+  entities: EntityHandle[];
+  value: Component;
+} {
+  const Value = defineComponent('M0PerfValue', { value: 'u32' });
+  const children = Children as unknown as Component;
+  const childOf = ChildOf as unknown as Component;
+  const world = new World();
+  const roots: EntityHandle[] = [];
+  for (let index = 0; index < ROOT_COUNT; index += 1) {
+    roots.push(
+      world
+        .spawn(
+          { component: children, data: { entities: [] } },
+          { component: Value, data: { value: index } },
+        )
+        .unwrap(),
+    );
+  }
+  const entities: EntityHandle[] = [...roots];
+  for (let index = ROOT_COUNT; index < ENTITY_COUNT; index += 1) {
+    const parent = roots[index % ROOT_COUNT];
+    if (parent === undefined) throw new Error('M0 benchmark root missing');
+    entities.push(
+      world
+        .spawn(
+          { component: childOf, data: { parent } },
+          { component: Value, data: { value: index } },
+        )
+        .unwrap(),
+    );
+  }
+  return { world, roots, entities, value: Value };
+}
+
+function createSubtree(): { world: World; root: EntityHandle } {
+  const world = new World();
+  const root = world
+    .spawn({ component: Children as unknown as Component, data: { entities: [] } })
+    .unwrap();
+  for (let index = 0; index < 10_000; index += 1) {
+    world.spawn({ component: ChildOf as unknown as Component, data: { parent: root } }).unwrap();
+  }
+  return { world, root };
+}
+
+describe('M0 ECS reduction workload characterization', () => {
+  it('records fixed workload statistics and no comparison verdict', { timeout: 300_000 }, () => {
+    const hierarchy = createHierarchy();
+    const valueQuery = hierarchy.world.query({ read: [hierarchy.value] });
+    expect(valueQuery.ok).toBe(true);
+    if (!valueQuery.ok) throw new Error('M0 benchmark query failed');
+    const samples: Sample[] = [];
+    samples.push(
+      measure(
+        'row-span-iteration',
+        () => {
+          let rowSum = 0;
+          for (const row of valueQuery.value)
+            rowSum += Number((row.get(hierarchy.value) as { value: number }).value);
+          let spanSum = 0;
+          for (const span of valueQuery.value.spans().unwrap()) {
+            const values = (span.get(hierarchy.value) as unknown as { value: ArrayLike<number> })
+              .value;
+            for (let index = 0; index < span.length; index += 1) spanSum += values[index] ?? 0;
+          }
+          return rowSum + spanSum;
+        },
+        { entities: ENTITY_COUNT, roots: ROOT_COUNT },
+      ),
+    );
+    samples.push(
+      measure(
+        'children-iteration',
+        () =>
+          hierarchy.roots.reduce(
+            (sum, root) =>
+              sum +
+              ((
+                hierarchy.world.get(root, Children as unknown as Component).unwrap() as unknown as {
+                  entities: ArrayLike<number>;
+                }
+              ).entities.length ?? 0),
+            0,
+          ),
+        { entities: ENTITY_COUNT, roots: ROOT_COUNT },
+      ),
+    );
+    samples.push(
+      measure(
+        'continuous-reparent',
+        () => {
+          let sum = 0;
+          for (let index = ROOT_COUNT; index < ROOT_COUNT * 2; index += 1) {
+            const entity = hierarchy.entities[index];
+            const parent = hierarchy.roots[(index + 1) % ROOT_COUNT];
+            if (entity === undefined || parent === undefined) continue;
+            sum += Number(
+              hierarchy.world.addComponent(entity, {
+                component: ChildOf as unknown as Component,
+                data: { parent },
+              }).ok,
+            );
+          }
+          return sum;
+        },
+        { entities: ENTITY_COUNT, roots: ROOT_COUNT, operations: ROOT_COUNT },
+      ),
+    );
+    samples.push(
+      measure(
+        'subtree-despawn',
+        () => {
+          const subtree = createSubtree();
+          return Number(subtree.world.despawn(subtree.root).ok);
+        },
+        { subtreeEntities: 10_001 },
+      ),
+    );
+    samples.push(
+      measure(
+        'mixed-command-batch',
+        () => {
+          const world = new World();
+          const Marker = defineComponent('M0PerfCommandMarker', {});
+          world.addSystem(Update, {
+            name: 'm0-command-batch',
+            queries: [],
+            fn: (_world, _queries, commands) => {
+              for (let index = 0; index < COMMAND_COUNT; index += 1)
+                commands.spawn({ component: Marker, data: {} });
+            },
+          });
+          return Number(world.update(0).ok);
+        },
+        { commands: COMMAND_COUNT },
+      ),
+    );
+    samples.push(
+      measure(
+        'clock-getter',
+        () => {
+          let sink = 0;
+          const time = hierarchy.world.getResource(Time);
+          for (let index = 0; index < CLOCK_READ_COUNT; index += 1) sink += time.elapsed;
+          return sink;
+        },
+        { reads: CLOCK_READ_COUNT },
+      ),
+    );
+    samples.push(
+      measure(
+        'shared-ref-churn',
+        () => {
+          let sink = 0;
+          for (let index = 0; index < COMMAND_COUNT; index += 1) {
+            const handle = hierarchy.world.allocSharedRef('M0PerfAsset', { index });
+            sink += Number(hierarchy.world.sharedRefs.release(handle).ok);
+          }
+          return sink;
+        },
+        { handles: COMMAND_COUNT },
+      ),
+    );
+    const revision = execFileSync('git', ['rev-parse', 'HEAD'], {
+      cwd: process.cwd(),
+      encoding: 'utf8',
+    }).trim();
+    process.stdout.write(
+      `${JSON.stringify({
+        schemaVersion: 1,
+        baseline: 'M0',
+        comparison: null,
+        environment: {
+          node: process.version,
+          platform: process.platform,
+          arch: process.arch,
+          cpu: os.cpus()[0]?.model,
+          revision,
+        },
+        samples,
+        stopRule: 'same-semantics p95 regression greater than 5 percent requires human decision',
+      })}\n`,
+    );
+    expect(samples).toHaveLength(7);
+    expect(samples.every((sample) => sample.p95Ms >= sample.medianMs)).toBe(true);
+  });
+});

package/src/__tests__/ecs-error-code-31.test-d.ts

@@ -0,0 +1,42 @@
+// ecs-error-code-31.test-d - owner error union boundary type-test.
+//
+// Coverage (plan-strategy D-9):
+//   - EcsErrorCode union has gained the 31st member 'scene-override-type-
+//     mismatch' (literal D-9 string locked).
+//   - The new literal is assignable to EcsErrorCode at the type layer
+//     (positive assertion). Cross-feat hardening: the literal must NOT
+//     be quietly aliased to a different existing member.
+//
+// EcsErrorDetail evolution for this code (detail shape `{ code, comp,
+// field, expectedType, actualType }`) is exercised by M2 unit tests
+// (requirements §Edge cases table last row, reviewer Issue 1) — out
+// of scope here; this file only locks the EcsErrorCode union literal.
+//
+// TDD red signal: until w9 widens EcsErrorCode to 31 members, the
+// `toExtend<EcsErrorCode>` assertion produces TS2344. w9 turns this
+// red into green.
+//
+// Note: plan-tasks.json originally listed the targetFile under
+// packages/types; @forgeax/engine-types has zero engine-ecs dep
+// (math-free + ecs-free per AGENTS.md). The test must live under the
+// ecs package to import EcsErrorCode locally — recorded in the M1
+// report as filesOutsideTargets with reason.
+//
+// Charter mapping: proposition 4 (explicit failure: type-level union
+// widening surfaced at compile-time, not via ad-hoc string literal
+// matching).
+
+import { describe, expectTypeOf, it } from 'vitest';
+import type { EcsErrorCode } from '../errors';
+
+describe('owner error union boundary', () => {
+  it("keeps 'scene-override-type-mismatch' out of EcsErrorCode", () => {
+    expectTypeOf<'scene-override-type-mismatch'>().not.toExtend<EcsErrorCode>();
+  });
+});
+
+describe('EcsErrorCode enum write validation', () => {
+  it("includes the 'component-field-invalid-value' literal", () => {
+    expectTypeOf<'component-field-invalid-value'>().toExtend<EcsErrorCode>();
+  });
+});

package/src/__tests__/entity-disabling.unit.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from 'vitest';
+import { Disabled, defineComponent, World } from '../index';
+import type { Query } from '../query/query';
+
+const Target = defineComponent('EntityDisablingTarget', { value: 'u32' });
+
+function count(query: Query): number {
+  return [...query].length;
+}
+
+describe('Disabled default query filter', () => {
+  it('excludes disabled entities while explicit Disabled queries include them', () => {
+    const world = new World();
+    world.spawn({ component: Target, data: { value: 1 } }).unwrap();
+    world
+      .spawn({ component: Target, data: { value: 2 } }, { component: Disabled, data: {} })
+      .unwrap();
+
+    const active = world.query({ read: [Target] }).unwrap();
+    const disabled = world.query({ read: [Target], with: [Disabled] }).unwrap();
+
+    expect(count(active)).toBe(1);
+    expect(count(disabled)).toBe(1);
+  });
+
+  it('recomputes the default filter when an entity is disabled and re-enabled', () => {
+    const world = new World();
+    const entity = world.spawn({ component: Target, data: { value: 1 } }).unwrap();
+    const active = world.query({ read: [Target] }).unwrap();
+
+    expect(count(active)).toBe(1);
+    world.addComponent(entity, { component: Disabled, data: {} }).unwrap();
+    expect(count(active)).toBe(0);
+    world.removeComponent(entity, Disabled).unwrap();
+    expect(count(active)).toBe(1);
+  });
+});

package/src/__tests__/entity-handle-codec-parity.unit.test.ts

@@ -0,0 +1,126 @@
+// Entity handle codec parity unit tests (w3).
+//
+// Runtime value assertions verifying bit-pattern equivalence between
+// entity-handle functions and the shared codec in @forgeax/engine-types.
+// These are the AC-14 regression baseline -- encodeEntity must produce
+// identical u32 values to codec.pack, and decode/entityIndex/entityGeneration
+// must match codec unpack results for all gen values including gen>=128
+// (>>>0 anti-ToInt32 guard, R5 from plan-strategy).
+//
+// This file holds runtime assertions; the plan targetFiles listed
+// .test-d.ts which are typecheck-only and cannot execute these checks.
+
+import { MAX_GEN, MAX_SLOT, pack, unpackGen, unpackSlot } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import {
+  decodeEntity,
+  ENTITY_MAX_GENERATION,
+  ENTITY_MAX_INDEX,
+  type EntityHandle,
+  encodeEntity,
+  entityGeneration,
+  entityIndex,
+} from '../entity-handle';
+
+describe('[w3] Entity codec parity -- constants', () => {
+  it('ENTITY_MAX_INDEX === MAX_SLOT', () => {
+    expect(ENTITY_MAX_INDEX).toBe(MAX_SLOT);
+  });
+
+  it('ENTITY_MAX_GENERATION === MAX_GEN', () => {
+    expect(ENTITY_MAX_GENERATION).toBe(MAX_GEN);
+  });
+});
+
+describe('[w3] Entity codec parity -- encodeEntity equals codec.pack', () => {
+  const SLOTS = [0, 1, 5, 42, 1023, 1024, 16777215] as const;
+
+  // gen=0: pack(slot,0)===slot invariant (D-8)
+  it('encodeEntity(i, 0) === pack(i, 0) for sampled slot values', () => {
+    for (const slot of SLOTS) {
+      expect(encodeEntity(slot, 0)).toBe(pack(slot, 0));
+    }
+  });
+
+  // gen=128: the >>>0 guard is load-bearing (R5)
+  it('encodeEntity(i, 128) === pack(i, 128) -- gen>=128 ToInt32 guard', () => {
+    for (const slot of SLOTS) {
+      expect(encodeEntity(slot, 128)).toBe(pack(slot, 128));
+    }
+  });
+
+  // gen=255: edge case, max generation
+  it('encodeEntity(i, 255) === pack(i, 255) -- max gen edge', () => {
+    for (const slot of SLOTS) {
+      expect(encodeEntity(slot, 255)).toBe(pack(slot, 255));
+    }
+  });
+
+  // gen=64: mid-range smoke test
+  it('encodeEntity(i, 64) === pack(i, 64) -- mid-range gen', () => {
+    for (const slot of SLOTS) {
+      expect(encodeEntity(slot, 64)).toBe(pack(slot, 64));
+    }
+  });
+
+  // Mixed gen values across different slots
+  it('encodeEntity(s, g) === pack(s, g) for cross-product of {0,1,42,1024,16777215} x {0,5,17,128,255}', () => {
+    const slots = [0, 1, 42, 1024, 16777215];
+    const gens = [0, 5, 17, 128, 255];
+    for (const slot of slots) {
+      for (const gen of gens) {
+        expect(encodeEntity(slot, gen)).toBe(pack(slot, gen));
+      }
+    }
+  });
+});
+
+describe('[w3] Entity codec parity -- decode functions', () => {
+  const CASES: [number, number][] = [
+    [0, 0],
+    [1, 0],
+    [42, 5],
+    [1024, 128],
+    [16777215, 255],
+    [0, 64],
+    [1, 255],
+    [16777215, 0],
+    [1023, 17],
+  ];
+
+  it('decodeEntity(pack(s, g)) returns { index: s, generation: g }', () => {
+    for (const [slot, gen] of CASES) {
+      const raw = pack(slot, gen) as EntityHandle;
+      const { index, generation } = decodeEntity(raw);
+      expect(index).toBe(slot);
+      expect(generation).toBe(gen);
+    }
+  });
+
+  it('entityIndex(pack(s, g)) === unpackSlot(pack(s, g))', () => {
+    for (const [slot, gen] of CASES) {
+      const raw = pack(slot, gen) as EntityHandle;
+      expect(entityIndex(raw)).toBe(unpackSlot(raw));
+    }
+  });
+
+  it('entityGeneration(pack(s, g)) === unpackGen(pack(s, g))', () => {
+    for (const [slot, gen] of CASES) {
+      const raw = pack(slot, gen) as EntityHandle;
+      expect(entityGeneration(raw)).toBe(unpackGen(raw));
+    }
+  });
+
+  // Full round-trip: encodeEntity -> entityIndex/entityGeneration
+  it('entityIndex(encodeEntity(s, g)) === s', () => {
+    for (const [slot, gen] of CASES) {
+      expect(entityIndex(encodeEntity(slot, gen))).toBe(slot);
+    }
+  });
+
+  it('entityGeneration(encodeEntity(s, g)) === g', () => {
+    for (const [slot, gen] of CASES) {
+      expect(entityGeneration(encodeEntity(slot, gen))).toBe(gen);
+    }
+  });
+});