@forgeax/engine-ecs 0.1.21 → 0.1.24

package/src/__tests__/component-requirements.unit.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it } from 'vitest';
+import { defineComponent } from '../component';
+import type { EntityHandle } from '../entity-handle';
+import { Update } from '../schedule-token';
+import { World } from '../world';
+
+describe('component requirements', () => {
+  it('materializes transitive requirements for synchronous spawn', () => {
+    const Base = defineComponent('RequirementsBase', { value: { type: 'f32', default: 3 } });
+    const Middle = defineComponent('RequirementsMiddle', {}, { requires: [Base] });
+    const Carrier = defineComponent('RequirementsCarrier', {}, { requires: [Middle] });
+    const world = new World();
+
+    const entity = world.spawn({ component: Carrier, data: {} }).unwrap();
+
+    expect(world.get(entity, Carrier).ok).toBe(true);
+    expect(world.get(entity, Middle).ok).toBe(true);
+    expect(world.get(entity, Base).unwrap().value).toBe(3);
+  });
+
+  it('keeps explicit required data and adds missing requirements on addComponent', () => {
+    const Base = defineComponent('RequirementsExplicitBase', { value: 'f32' });
+    const Carrier = defineComponent('RequirementsExplicitCarrier', {}, { requires: [Base] });
+    const world = new World();
+    const entity = world.spawn({ component: Base, data: { value: 9 } }).unwrap();
+
+    expect(world.addComponent(entity, { component: Carrier, data: {} }).ok).toBe(true);
+    expect(world.get(entity, Base).unwrap().value).toBe(9);
+
+    const explicit = world
+      .spawn({ component: Carrier, data: {} }, { component: Base, data: { value: 17 } })
+      .unwrap();
+    expect(world.get(explicit, Base).unwrap().value).toBe(17);
+  });
+
+  it('applies requirements to deferred Commands.spawn', () => {
+    const Base = defineComponent('RequirementsDeferredBase', { value: 'f32' });
+    const Carrier = defineComponent('RequirementsDeferredCarrier', {}, { requires: [Base] });
+    const world = new World();
+    let entity: EntityHandle | undefined;
+
+    world
+      .addSystem(Update, {
+        name: 'requirements-deferred-spawn',
+        queries: [],
+        fn: (_world, _queries, commands) => {
+          entity = commands.spawn({ component: Carrier, data: {} });
+        },
+      })
+      .unwrap();
+
+    expect(world.update(0).ok).toBe(true);
+    expect(entity).toBeDefined();
+    expect(world.get(entity as EntityHandle, Base).ok).toBe(true);
+  });
+
+  it('applies requirements to deferred Commands.addComponent', () => {
+    const Base = defineComponent('RequirementsDeferredAddBase', { value: 'f32' });
+    const Carrier = defineComponent('RequirementsDeferredAddCarrier', {}, { requires: [Base] });
+    const world = new World();
+    const entity = world.spawn().unwrap();
+
+    world
+      .addSystem(Update, {
+        name: 'requirements-deferred-add',
+        queries: [],
+        fn: (_world, _queries, commands) => {
+          commands.addComponent(entity, { component: Carrier, data: {} });
+        },
+      })
+      .unwrap();
+
+    expect(world.update(0).ok).toBe(true);
+    expect(world.get(entity, Base).ok).toBe(true);
+  });
+});

package/src/__tests__/component-version-surface.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest';
+import { defineComponent } from '../component';
+import { readStructuralEvidence } from '../projection';
+import type { Query } from '../query/query';
+import { World } from '../world';
+
+const Value = defineComponent('ComponentVersionSurfaceValue', { value: 'f32' });
+
+function changedEntities(query: Query): number[] {
+  const entities: number[] = [];
+  for (const span of query.spans().unwrap()) entities.push(...span.entities);
+  return entities;
+}
+
+describe('component version surface', () => {
+  it('keeps value versions and typed structural evidence separate', () => {
+    const world = new World();
+    const query = world.query({ changed: [Value] }).unwrap();
+    const entity = world.spawn({ component: Value, data: { value: 1 } }).unwrap();
+
+    expect(changedEntities(query)).toEqual([entity]);
+    world.set(entity, Value, { value: 2 }).unwrap();
+    expect(changedEntities(query)).toEqual([entity]);
+    expect(changedEntities(query)).toEqual([]);
+
+    const structuralRead = readStructuralEvidence(world, 0);
+    expect(structuralRead.status).toBe('ok');
+    if (structuralRead.status !== 'ok') return;
+    expect(structuralRead.events).toEqual([expect.objectContaining({ kind: 'spawn', entity })]);
+  });
+
+  it('lets independent consumers observe the same component version', () => {
+    const world = new World();
+    const entity = world.spawn({ component: Value, data: { value: 2 } }).unwrap();
+    const first = world.query({ changed: [Value] }).unwrap();
+    const second = world.query({ changed: [Value] }).unwrap();
+    changedEntities(first);
+    changedEntities(second);
+
+    world.set(entity, Value, { value: 3 }).unwrap();
+
+    expect(changedEntities(first)).toEqual([entity]);
+    expect(changedEntities(second)).toEqual([entity]);
+  });
+});

package/src/__tests__/derived-range-writer.contract.test-d.ts

@@ -0,0 +1,35 @@
+import type { Component } from '../component';
+import { getDerivedWriter } from '../internal';
+import type { DerivedColumnBinding, DerivedRangeKernel } from '../query/derived-range-writer';
+import type { Query, QuerySpan } from '../query/query';
+
+declare const Value: Component<'DerivedRangeWriterValue', { value: 'f32' }>;
+declare const span: QuerySpan<readonly [], readonly [typeof Value]>;
+declare const query: Query<readonly [], readonly [typeof Value]>;
+declare const readOnlyQuery: Query<readonly [typeof Value], readonly []>;
+declare const binding: DerivedColumnBinding<typeof Value, typeof Value>;
+const kernel: DerivedRangeKernel<typeof Value, typeof Value> = (
+  nextBinding,
+  base,
+  start,
+  count,
+  _context,
+) => {
+  nextBinding.write.value[base + start] = count;
+  binding.write.value[0] = nextBinding.write.value[base + start] ?? 0;
+};
+void kernel;
+
+// The derived writer is intentionally absent from the public Query contract.
+// It is resolved through the package-internal typed accessor instead.
+void getDerivedWriter(query, Value);
+// @ts-expect-error Query must not expose the package-internal writer as a string method.
+query.derivedWriter(Value);
+// @ts-expect-error A read-only Query cannot create a derived writer.
+readOnlyQuery.derivedWriter(Value);
+
+// A writer is query-owned and package-internal; QuerySpan has no writer method.
+// @ts-expect-error QuerySpan must not expose a public derived writer protocol.
+span.derivedWriter(Value);
+// @ts-expect-error QuerySpan must not expose raw table or storage handles.
+span.table;

package/src/__tests__/derived-range-writer.contract.test.ts

@@ -0,0 +1,339 @@
+import { describe, expect, it } from 'vitest';
+import { componentId, defineComponent } from '../component';
+import { ChangeEpochExhaustedError } from '../errors';
+import { getDerivedWriter } from '../internal';
+import type { Query } from '../query/query';
+import { World } from '../world';
+import { worldInternal } from '../world-internal';
+
+const Value = defineComponent('DerivedRangeWriterValue', { value: 'f32' });
+const Input = defineComponent('DerivedRangeWriterInput', { value: 'f32' });
+
+function fixture(): {
+  world: World;
+  query: Query<readonly [typeof Input], readonly [typeof Value]>;
+} {
+  const world = new World();
+  for (let index = 0; index < 4; index += 1) {
+    world
+      .spawn(
+        { component: Input, data: { value: index } },
+        { component: Value, data: { value: index } },
+      )
+      .unwrap();
+  }
+  const query = world.query({ read: [Input], write: [Value] }).unwrap();
+  return { world, query };
+}
+
+describe('package-internal derived range writer contract', () => {
+  it('publishes only the exact span-relative range with one component epoch', () => {
+    const { world, query } = fixture();
+    const writer = getDerivedWriter(query, Value).unwrap();
+    const beforeEpoch = world[worldInternal].getMutationEpoch();
+
+    expect(
+      writer.writeRange(
+        0,
+        0,
+        1,
+        2,
+        (binding, _base, start, count) => {
+          expect(count).toBe(2);
+          binding.write.value[start] = 11;
+          binding.write.value[start + 1] = 12;
+        },
+        undefined,
+      ),
+    ).toEqual({ ok: true, value: undefined });
+    expect(world[worldInternal].getMutationEpoch()).toBe(beforeEpoch + 1);
+    const values: number[] = [];
+    for (const row of world.query({ read: [Value] }).unwrap()) {
+      values.push(row.get(Value).value);
+    }
+    expect(values).toEqual([0, 11, 12, 3]);
+
+    const graph = world[worldInternal].getGraph();
+    const record = world[worldInternal].getRecords()[0];
+    const table = graph.tables[graph.archetypes[record?.archetypeId ?? -1]?.tableId ?? -1];
+    const epochs = table?.storage.get(componentId(Value))?.epochs.changed;
+    expect(epochs?.slice(0, 4)).toEqual(new Float64Array([1, beforeEpoch + 1, beforeEpoch + 1, 4]));
+  });
+
+  it('does not call the kernel or consume an epoch for a zero-length range', () => {
+    const { world, query } = fixture();
+    const writer = getDerivedWriter(query, Value).unwrap();
+    const beforeEpoch = world[worldInternal].getMutationEpoch();
+    let called = false;
+    expect(
+      writer.writeRange(
+        0,
+        0,
+        2,
+        0,
+        () => {
+          called = true;
+        },
+        undefined,
+      ),
+    ).toEqual({ ok: true, value: undefined });
+    expect(called).toBe(false);
+    expect(world[worldInternal].getMutationEpoch()).toBe(beforeEpoch);
+  });
+
+  it('probes each row once and commits only the exact changed runs', () => {
+    const { world, query } = fixture();
+    const writer = getDerivedWriter(query, Value).unwrap();
+    const beforeEpoch = world[worldInternal].getMutationEpoch();
+    let probes = 0;
+    let commits = 0;
+    const result = writer.probeAndCommitRange(
+      0,
+      0,
+      0,
+      4,
+      (_binding, row) => {
+        probes += 1;
+        return row === 1 || row === 3;
+      },
+      (binding, row) => {
+        commits += 1;
+        binding.write.value[row] = row + 10;
+      },
+      undefined,
+    );
+    expect(result).toEqual({ ok: true, value: undefined });
+    expect(probes).toBe(4);
+    expect(commits).toBe(2);
+    expect(world[worldInternal].getMutationEpoch()).toBe(beforeEpoch + 1);
+    const values: number[] = [];
+    for (const row of world.query({ read: [Value] }).unwrap()) values.push(row.get(Value).value);
+    expect(values).toEqual([0, 11, 2, 13]);
+    const graph = world[worldInternal].getGraph();
+    const record = world[worldInternal].getRecords()[0];
+    const table = graph.tables[graph.archetypes[record?.archetypeId ?? -1]?.tableId ?? -1];
+    const epochs = table?.storage.get(componentId(Value))?.epochs.changed;
+    expect(epochs?.[1]).toBe(beforeEpoch + 1);
+    expect(epochs?.[3]).toBe(beforeEpoch + 1);
+  });
+
+  it('poisons the World when a changed-row commit fails after partial output', () => {
+    const { world, query } = fixture();
+    const writer = getDerivedWriter(query, Value).unwrap();
+    const failed = writer.probeAndCommitRange(
+      0,
+      0,
+      0,
+      2,
+      () => true,
+      (binding, row) => {
+        binding.write.value[row] = 31;
+        if (row === 1) throw new Error('partial row commit failure');
+      },
+      undefined,
+    );
+    expect(failed.ok).toBe(false);
+    expect(world.execution.health).toBe('poisoned');
+    expect(
+      writer.probeAndCommitRange(
+        0,
+        0,
+        0,
+        1,
+        () => false,
+        () => undefined,
+        undefined,
+      ).ok,
+    ).toBe(false);
+  });
+
+  it('keeps the World healthy when the initial epoch reservation is exhausted', () => {
+    const { world, query } = fixture();
+    const writer = getDerivedWriter(query, Value).unwrap();
+    const rows = query[Symbol.iterator]();
+    const first = rows.next();
+    const firstEntity = first.done ? undefined : first.value.entity;
+    rows.return?.();
+    if (firstEntity === undefined) throw new Error('expected a fixture entity');
+    const beforeEpoch = world[worldInternal].getMutationEpoch();
+    const originalNextEpoch = world[worldInternal].nextMutationEpoch;
+    Object.defineProperty(world[worldInternal], 'nextMutationEpoch', {
+      configurable: true,
+      value: () => {
+        throw new ChangeEpochExhaustedError(Number.MAX_SAFE_INTEGER);
+      },
+    });
+    try {
+      let commits = 0;
+      const failed = writer.probeAndCommitRange(
+        0,
+        0,
+        0,
+        2,
+        (_binding, row) => row === 0,
+        (binding, row) => {
+          commits += 1;
+          binding.write.value[row] = 10;
+        },
+        undefined,
+      );
+      expect(failed.ok).toBe(false);
+      if (!failed.ok) expect(failed.error.code).toBe('change-epoch-exhausted');
+      expect(commits).toBe(0);
+      expect(world.execution.health).toBe('healthy');
+      expect(world[worldInternal].getMutationEpoch()).toBe(beforeEpoch);
+      expect(world.get(firstEntity, Value).unwrap().value).toBe(0);
+      const graph = world[worldInternal].getGraph();
+      const record = world[worldInternal].getRecords()[0];
+      const table = graph.tables[graph.archetypes[record?.archetypeId ?? -1]?.tableId ?? -1];
+      const epochs = table?.storage.get(componentId(Value))?.epochs.changed;
+      expect(epochs?.slice(0, 4)).toEqual(new Float64Array([1, 2, 3, 4]));
+    } finally {
+      Object.defineProperty(world[worldInternal], 'nextMutationEpoch', {
+        configurable: true,
+        value: originalNextEpoch,
+      });
+    }
+
+    const retried = writer.probeAndCommitRange(
+      0,
+      0,
+      0,
+      2,
+      () => true,
+      (binding, row) => {
+        binding.write.value[row] = 10;
+      },
+      undefined,
+    );
+    expect(retried.ok).toBe(true);
+    expect(world.execution.health).toBe('healthy');
+    expect(world[worldInternal].getMutationEpoch()).toBe(beforeEpoch + 1);
+    expect(world.get(firstEntity, Value).unwrap().value).toBe(10);
+  });
+
+  it('poisons and restores the epoch when a later sparse probe fails', () => {
+    const { world, query } = fixture();
+    const writer = getDerivedWriter(query, Value).unwrap();
+    const rows = query[Symbol.iterator]();
+    const first = rows.next();
+    const firstEntity = first.done ? undefined : first.value.entity;
+    rows.return?.();
+    if (firstEntity === undefined) throw new Error('expected a fixture entity');
+    const beforeEpoch = world[worldInternal].getMutationEpoch();
+    const failed = writer.probeAndCommitRange(
+      0,
+      0,
+      0,
+      3,
+      (_binding, row) => {
+        if (row === 2) throw new Error('later sparse probe failure');
+        return row === 0;
+      },
+      (binding, row) => {
+        binding.write.value[row] = row + 10;
+      },
+      undefined,
+    );
+    expect(failed.ok).toBe(false);
+    expect(world.execution.health).toBe('poisoned');
+    expect(world[worldInternal].getMutationEpoch()).toBe(beforeEpoch);
+    expect(world.get(firstEntity, Value).unwrap().value).toBe(10);
+    const graph = world[worldInternal].getGraph();
+    const record = world[worldInternal].getRecords()[0];
+    const table = graph.tables[graph.archetypes[record?.archetypeId ?? -1]?.tableId ?? -1];
+    const epochs = table?.storage.get(componentId(Value))?.epochs.changed;
+    expect(epochs?.slice(0, 4)).toEqual(new Float64Array([1, 2, 3, 4]));
+    expect(
+      writer.probeAndCommitRange(
+        0,
+        0,
+        0,
+        1,
+        () => false,
+        () => undefined,
+        undefined,
+      ).ok,
+    ).toBe(false);
+  });
+
+  it('rejects an out-of-bounds range before the kernel and permits same-cursor retry', () => {
+    const { world, query } = fixture();
+    const writer = getDerivedWriter(query, Value).unwrap();
+    const beforeEpoch = world[worldInternal].getMutationEpoch();
+    const failed = writer.writeRange(
+      0,
+      0,
+      3,
+      2,
+      () => {
+        throw new Error('kernel must not run');
+      },
+      undefined,
+    );
+    expect(failed.ok).toBe(false);
+    if (!failed.ok && failed.error.code === 'derived-range-out-of-bounds') {
+      expect(failed.error.code).toBe('derived-range-out-of-bounds');
+      expect(failed.error.expected).toContain('span-relative range');
+      expect(failed.error.hint).toContain('start');
+      expect(failed.error.detail).toMatchObject({ start: 3, count: 2 });
+    }
+    expect(world[worldInternal].getMutationEpoch()).toBe(beforeEpoch);
+    expect(
+      writer.writeRange(
+        0,
+        0,
+        2,
+        1,
+        (binding, _base, start) => {
+          binding.write.value[start] = 22;
+        },
+        undefined,
+      ).ok,
+    ).toBe(true);
+  });
+
+  it('keeps state on epoch exhaustion and poisons after a partial kernel write', () => {
+    const { world, query } = fixture();
+    const writer = getDerivedWriter(query, Value).unwrap();
+    const beforeEpoch = world[worldInternal].getMutationEpoch();
+    const originalNextEpoch = world[worldInternal].nextMutationEpoch;
+    Object.defineProperty(world[worldInternal], 'nextMutationEpoch', {
+      configurable: true,
+      value: () => {
+        throw new ChangeEpochExhaustedError(Number.MAX_SAFE_INTEGER);
+      },
+    });
+    const exhausted = writer.writeRange(
+      0,
+      0,
+      0,
+      1,
+      () => {
+        throw new Error('kernel must not run');
+      },
+      undefined,
+    );
+    expect(exhausted.ok).toBe(false);
+    expect(world[worldInternal].getMutationEpoch()).toBe(beforeEpoch);
+    Object.defineProperty(world[worldInternal], 'nextMutationEpoch', {
+      configurable: true,
+      value: originalNextEpoch,
+    });
+
+    const partial = writer.writeRange(
+      0,
+      0,
+      0,
+      2,
+      (binding) => {
+        binding.write.value[0] = 31;
+        throw new Error('partial kernel failure');
+      },
+      undefined,
+    );
+    expect(partial.ok).toBe(false);
+    expect(world.execution.health).toBe('poisoned');
+    expect(writer.writeRange(0, 0, 0, 1, () => undefined, undefined).ok).toBe(false);
+  });
+});

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

@@ -23,7 +23,7 @@ import { fileURLToPath } from 'node:url';
 import { err, ok, type Result } from '@forgeax/engine-types';
 import { describe, expect, expectTypeOf, it, test } from 'vitest';
 import { componentSchema, defineComponent } from '../component';
-import type { EcsErrorCode } from '../errors';
+import type { EcsErrorCode, EcsErrorDetail } from '../errors';
 import {
   ComponentAlreadyPresentError,
   ComponentNotPresentError,
@@ -977,25 +977,41 @@ import { World } from '../world';
         expect(code).toBe('spawn-light-invalid-bounds');
       });
 
-      it("EcsErrorDetail discriminated variant for 'spawn-light-invalid-bounds' carries field three-branch", () => {
-        const range = {
+      it("EcsErrorDetail discriminated variant for 'spawn-light-invalid-bounds' carries scalar and RGB fields", () => {
+        type InvalidLightBoundsDetail = Extract<
+          EcsErrorDetail,
+          { readonly code: 'spawn-light-invalid-bounds' }
+        >;
+        const range: InvalidLightBoundsDetail = {
           code: 'spawn-light-invalid-bounds',
           field: 'range',
           got: -1,
         };
-        const innerOuter = {
+        const innerOuter: InvalidLightBoundsDetail = {
           code: 'spawn-light-invalid-bounds',
           field: 'innerOuter',
           got: 25,
         };
-        const outerNinety = {
+        const outerNinety: InvalidLightBoundsDetail = {
           code: 'spawn-light-invalid-bounds',
           field: 'outerNinety',
           got: 91,
         };
+        const direction: InvalidLightBoundsDetail = {
+          code: 'spawn-light-invalid-bounds',
+          field: 'direction',
+          got: [Number.NaN, 0, 0],
+        };
+        const irradiance: InvalidLightBoundsDetail = {
+          code: 'spawn-light-invalid-bounds',
+          field: 'irradiance',
+          got: Array.from(new Float32Array(27)),
+        };
         expect(range.code).toBe('spawn-light-invalid-bounds');
         expect(innerOuter.code).toBe('spawn-light-invalid-bounds');
         expect(outerNinety.code).toBe('spawn-light-invalid-bounds');
+        expect(direction.field).toBe('direction');
+        expect(irradiance.field).toBe('irradiance');
       });
 
       it("type-level: switch over EcsErrorCode includes 'spawn-light-invalid-bounds' branch", () => {

package/src/__tests__/externalization-render-read-lease.test-d.ts

@@ -13,7 +13,7 @@ const lease = createRenderReadLease(world);
 const request: RenderProjectionRequest = {
   components: [{ component: Position, fields: ['x'] }],
 };
-const batch = lease.readChanges(lease.inspectCursor());
+const batch = lease.readChanges(lease.captureVersion());
 const projection = lease.querySpans(request);
 
 expectTypeOf(lease.worldIdentity).toEqualTypeOf<string>();

package/src/__tests__/externalization-render-read-lease.unit.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { defineComponent } from '../component';
+import { componentId, defineComponent } from '../component';
 import { createRenderReadLease, type RenderProjectionRequest } from '../projection/index';
 import { World } from '../world';
 
@@ -27,36 +27,36 @@ describe('RenderReadLease contract', () => {
     expect(projection.spans[0]?.fields.y).toEqual(new Float32Array([2]));
   });
 
-  it('publishes world and shared-ref changes through one cursor contract', () => {
+  it('publishes world and shared-ref changes from an explicit consumer version', () => {
     const world = new World();
-    const lease = createRenderReadLease(world);
-    const cursor = lease.inspectCursor();
     const entity = world.spawn({ component: Position, data: { x: 0, y: 0 } }).unwrap();
+    const lease = createRenderReadLease(world);
+    const version = lease.captureVersion();
     world.set(entity, Position, { x: 3 }).unwrap();
-    const batch = lease.readChanges(cursor);
+    const batch = lease.readChanges(version);
 
     expect(batch.status).toBe('ok');
     if (batch.status !== 'ok') return;
-    expect(batch.cursor).toBeGreaterThan(cursor);
-    expect(batch.world.records.some((record) => record.kind === 'component-changed')).toBe(true);
-    expect(batch.sharedRefs.status).toBe('ok');
+    expect(batch.version.mutationEpoch).toBeGreaterThan(version.mutationEpoch);
+    expect(batch.world.changedComponentIds).toContain(componentId(Position));
+    expect(batch.sharedRefs.records).toEqual([]);
   });
 
-  it('reports overflow and requires an explicit resync', () => {
+  it('requires an explicit rebuild after structure changes', () => {
     const world = new World();
     const lease = createRenderReadLease(world);
-    const staleCursor = 0;
+    const version = lease.captureVersion();
 
     for (let index = 0; index < 65537; index += 1) {
       const entity = world.spawn({ component: Position, data: { x: index, y: 0 } }).unwrap();
       world.despawn(entity).unwrap();
     }
 
-    const batch = lease.readChanges(staleCursor);
-    expect(batch.status).toBe('overflow');
-    if (batch.status !== 'overflow') return;
+    const batch = lease.readChanges(version);
+    expect(batch.status).toBe('rebuild');
+    if (batch.status !== 'rebuild') return;
     expect(batch.resync).toBe(true);
-    expect(batch.oldestAvailable).toBeGreaterThan(staleCursor);
+    expect(batch.reason).toBe('structure-changed');
   });
 
   it('detaches idempotently and rejects reads after dispose', () => {
@@ -64,7 +64,7 @@ describe('RenderReadLease contract', () => {
     lease.dispose();
     lease.dispose();
 
-    expect(() => lease.inspectCursor()).toThrow(/disposed/i);
+    expect(() => lease.captureVersion()).toThrow(/disposed/i);
     expect(() => lease.querySpans(request)).toThrow(/disposed/i);
   });
 

package/src/__tests__/query-storage-trends.perf.test.ts

@@ -4,6 +4,7 @@ import { World } from '../world';
 
 const ENTITY_COUNT = 2_000;
 const ROUNDS = 3;
+const SCALE_CHARACTERIZATION_COUNTS = [10_000, 100_000] as const;
 
 const TrendValue = defineComponent('StorageTrendValue', { value: 'f32' });
 const TrendSelected = defineComponent('StorageTrendSelected', {}, { storage: 'sparse' });
@@ -20,6 +21,24 @@ function minimumDuration(run: () => number): { duration: number; sum: number } {
 }
 
 describe('table, sparse, span, and change-distribution trends', () => {
+  it('characterizes fixed-size dense traversal without treating it as a performance verdict', () => {
+    const observations = SCALE_CHARACTERIZATION_COUNTS.map((entityCount) => {
+      const values = new Float32Array(entityCount);
+      for (let index = 0; index < entityCount; index++) values[index] = index + 1;
+      const start = performance.now();
+      let sum = 0;
+      for (const value of values) sum += value;
+      return { entityCount, elapsedMs: performance.now() - start, sum };
+    });
+
+    expect(observations.map(({ sum }) => sum)).toEqual(
+      SCALE_CHARACTERIZATION_COUNTS.map((entityCount) => (entityCount * (entityCount + 1)) / 2),
+    );
+
+    // biome-ignore lint/suspicious/noConsole: characterization output is evidence, not a gate
+    console.info(`[scale characterization] ${JSON.stringify(observations)}`);
+  });
+
   it('reports equivalent table-row, sparse-row, and dense-span traversal', () => {
     const world = new World();
     for (let index = 0; index < ENTITY_COUNT; index++) {