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

package/src/__tests__/managed-array-vocab.test-d.ts

@@ -0,0 +1,137 @@
+// Compile-time type-derivation tests for the array<T,N> / array<T> schema-vocab
+// keywords (w12, AC-01 / AC-02 / AC-03 / AC-04).
+//
+// Locks four invariants:
+//
+//   1. Inference (AC-01): defineComponent('Foo', { entities: { type: 'array<entity>' } })
+//      derives `entities` to a `Uint32Array` (the Entity column storage);
+//      defineComponent('Bar', { mat: { type: 'array<f32, 16>' } }) derives `mat` to a
+//      `Float32Array` (fixed-capacity TypedArray snapshot).
+//      Inference holds at three application points: (a) world.addSystem fn
+//      callback; (b) QueryRow loop; (c) direct world.get call site.
+//
+//   2. Cross-shape (AC-02): both `array<T>` and `array<T, N>` resolve to a
+//      concrete `TypedArrayFor<T>` surface (no intermediate view-class
+//      wrapper). Mutation flows through `world.push` / `world.pop` /
+//      `world.set`; the TypedArray itself is a read-only snapshot.
+//
+//   3. Element-type (AC-03): T must be scalar + entity. Schema strings
+//      `'array<ref<X>>' / 'array<shared<X>>' / 'array<buffer<8>>' /
+//      'array<array<f32,4>>'` are TS compile-time errors when used as a
+//      schema field value.
+//
+//   4. Cross-brand (AC-04): the value returned by `snap[i]` for an
+//      `'array<entity>'` field is the underlying `number` packed Entity bit
+//      pattern; assigning it directly to a `Handle<Mesh, 'unique'>`
+//      parameter is a TS compile-time error.
+
+import type { Handle } from '@forgeax/engine-types';
+import { describe, expectTypeOf, it } from 'vitest';
+import type {
+  defineComponent,
+  FieldValueType,
+  SchemaFieldType,
+  SchemaOf,
+  ShapeOf,
+  TypedArrayFor,
+} from '../component';
+import type { World } from '../world';
+
+describe('array vocab - keyword recognition (w12, AC-01)', () => {
+  it('array<entity> derives to Uint32Array', () => {
+    expectTypeOf<FieldValueType<'array<entity>'>>().toEqualTypeOf<Uint32Array>();
+  });
+
+  it('array<f32, 16> derives to Float32Array', () => {
+    expectTypeOf<FieldValueType<'array<f32, 16>'>>().toEqualTypeOf<Float32Array>();
+  });
+
+  it('array<u32> derives to Uint32Array', () => {
+    expectTypeOf<FieldValueType<'array<u32>'>>().toEqualTypeOf<Uint32Array>();
+  });
+
+  it('array<i32, 4> derives to Int32Array', () => {
+    expectTypeOf<FieldValueType<'array<i32, 4>'>>().toEqualTypeOf<Int32Array>();
+  });
+
+  it('array<bool> derives to Uint8Array', () => {
+    expectTypeOf<FieldValueType<'array<bool>'>>().toEqualTypeOf<Uint8Array>();
+  });
+
+  it('ShapeOf threads array vocab through FieldValueType', () => {
+    type S = {
+      entities: 'array<entity>';
+      mat: 'array<f32, 16>';
+      indices: 'array<u32>';
+    };
+    type Expected = {
+      entities: Uint32Array;
+      mat: Float32Array;
+      indices: Uint32Array;
+    };
+    expectTypeOf<ShapeOf<S>>().toEqualTypeOf<Expected>();
+  });
+});
+
+describe('array vocab - three-application-point inference (w12, AC-01 / AC-02)', () => {
+  it('application point (a) - inside world.addSystem fn callback', () => {
+    type Foo = ReturnType<typeof defineComponent<'Foo', { entities: 'array<entity>' }>>;
+    type FooShape = ShapeOf<SchemaOf<Foo>>;
+    expectTypeOf<FooShape['entities']>().toEqualTypeOf<Uint32Array>();
+  });
+
+  it('application point (b) - inside a QueryRow loop', () => {
+    type Foo = ReturnType<typeof defineComponent<'Foo', { entities: 'array<entity>' }>>;
+    type FooShape = ShapeOf<SchemaOf<Foo>>;
+    expectTypeOf<FooShape['entities']>().toEqualTypeOf<Uint32Array>();
+  });
+
+  it('application point (c) - direct world.get call site', () => {
+    type Foo = ReturnType<typeof defineComponent<'Foo', { entities: 'array<entity>' }>>;
+    type FooShape = ShapeOf<SchemaOf<Foo>>;
+    // expectType: direct world.get(e, Foo).unwrap().entities matches TypedArrayFor<'u32'>.
+    const arr: TypedArrayFor<'u32'> = new Uint32Array(0);
+    expectTypeOf(arr).toEqualTypeOf<FooShape['entities']>();
+  });
+
+  it('World type still resolves (no parser regression)', () => {
+    expectTypeOf<World>().toBeObject();
+  });
+});
+
+describe('array vocab - element-type rejection (w12, AC-03)', () => {
+  it('array<ref<X>> is not a recognised schema field type', () => {
+    // @ts-expect-error 'array<ref<X>>' is not a SchemaFieldType (AC-03 element-type).
+    const bad: SchemaFieldType = 'array<ref<MaterialAsset>>';
+    void bad;
+  });
+
+  it('array<handle<X>> is now a recognised schema field type (feat-20260608 M2 D-1)', () => {
+    const valid: SchemaFieldType = 'array<shared<MeshAsset>>';
+    void valid;
+  });
+
+  it('array<buffer<N>> is not a recognised schema field type', () => {
+    // @ts-expect-error 'array<buffer<8>>' is not a SchemaFieldType (AC-03 element-type).
+    const bad: SchemaFieldType = 'array<buffer<8>>';
+    void bad;
+  });
+
+  it('array<array<f32,4>> nesting is not a recognised schema field type', () => {
+    // @ts-expect-error 'array<array<f32,4>>' is not a SchemaFieldType (AC-03 element-type).
+    const bad: SchemaFieldType = 'array<array<f32,4>>';
+    void bad;
+  });
+});
+
+describe('array vocab - cross-brand rejection (w12, AC-04)', () => {
+  it("snap[i] is number; not assignable to Handle<Mesh, 'unique'>", () => {
+    const takesMeshHandle = (h: Handle<'Mesh', 'unique'>): void => {
+      void h;
+    };
+    const view: TypedArrayFor<'u32'> = new Uint32Array(1);
+    const elem: number = view[0] ?? 0;
+    // @ts-expect-error number is not assignable to Handle<'Mesh','unique'> (AC-04 cross-brand).
+    takesMeshHandle(elem);
+  });
+});

package/src/__tests__/minimal-example.test-d.ts

@@ -0,0 +1,42 @@
+import { Update } from '../schedule-token';
+// AC-4 minimal-example compile-assertion vehicle.
+//
+// Pastes requirements §10.4 "30-second onboarding minimal example" into a
+// dedicated file so `tsc -b` (and vitest typecheck) certify, every release,
+// that an AI user can write the bundle-field access pattern WITHOUT any `as`
+// casts and WITHOUT explicit `as const` annotations.
+//
+// Note: requirements §10.4 prose uses `createWorld()`. The shipped API is
+// `new World()`; the load-bearing assertion is the bundle field access shape
+// (KD-1 + KD-2 + KD-3 chain), not the constructor form. The minimal-example
+// JSDoc on `SystemDescriptor` (w17) and the CHANGELOG migration block (w18)
+// follow the same shape so the three discovery surfaces stay congruent
+// (charter proposition 1: same signal, three entry points).
+
+import { describe, expectTypeOf, it } from 'vitest';
+import { defineComponent } from '../component';
+import { World } from '../world';
+
+describe('[w14] AC-4 — 30-second onboarding minimal example', () => {
+  it('bundle field access compiles without `as` casts', () => {
+    const Position = defineComponent('Position', { x: { type: 'f32' }, y: { type: 'f32' } });
+    const Velocity = defineComponent('Velocity', { dx: { type: 'f32' }, dy: { type: 'f32' } });
+
+    const world = new World();
+    world.addSystem(Update, {
+      name: 'movement',
+      queries: [{ read: [Velocity], write: [Position] }],
+      fn: (_world, queryResults, _commands) => {
+        for (const row of queryResults[0]) {
+          const velocity = row.get(Velocity);
+          const position = row.mut(Position);
+          expectTypeOf(position.x).toBeNumber();
+          expectTypeOf(velocity.dx).toBeNumber();
+          position.x += velocity.dx;
+        }
+      },
+    });
+
+    expectTypeOf(world).toMatchTypeOf<World>();
+  });
+});

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

@@ -0,0 +1,72 @@
+import { Update } from '../schedule-token';
+// w7 --- 3-point AC-02: world.get(e, C).unwrap().value infers as `string`.
+//
+// Locks AC-02 from requirements: AI users see a native JS `string` value
+// (not StringView, not a wrapper) when reading a `'string'` schema-vocab
+// field at three application points:
+//
+//   (a) inside `world.addSystem(Update, { fn })` callback;
+//   (b) inside a QueryRow loop;
+//   (c) at top-level after a direct import.
+//
+// All three sites pass through the same `FieldValueType<'string'> = string`
+// derivation locked by w9 / w12; this file pins the inference at the
+// observable read shape, with zero `as` assertions.
+//
+// Uses an inline `defineComponent('TestName', { value: 'string' })` instead
+// of the public `Name` token: `Name` was migrated to `@forgeax/engine-runtime`
+// (tweak-20260612-ecs-concept-compression -- it is a built-in component, not
+// part of the ECS framework itself). The ECS-internal type test exercises the
+// `'string'` schema-vocab keyword directly to avoid an upstream import
+// dependency on the runtime sibling.
+
+import { describe, expectTypeOf, it } from 'vitest';
+import { defineComponent } from '../component';
+import { World } from '../world';
+
+const TestName = defineComponent('TestName', { value: { type: 'string' } });
+
+describe('w7 --- (a) inside world.addSystem fn callback (AC-02)', () => {
+  it('world.get(e, TestName).unwrap().value infers as string', () => {
+    const w = new World();
+    const e = w.spawn({ component: TestName, data: { value: 'Player' } }).unwrap();
+
+    w.addSystem(Update, {
+      name: 'reader',
+      queries: [],
+      fn: () => {
+        const value = w.get(e, TestName).unwrap().value;
+        expectTypeOf(value).toEqualTypeOf<string>();
+      },
+    });
+  });
+});
+
+describe('w7 --- (b) inside a QueryRow loop (AC-02)', () => {
+  it('world.get(e, TestName).unwrap().value infers as string from a query callback', () => {
+    const w = new World();
+    const e = w.spawn({ component: TestName, data: { value: 'Boss' } }).unwrap();
+
+    w.addSystem(Update, {
+      name: 'queryReader',
+      queries: [{ with: [TestName] }],
+      fn: (_world, results) => {
+        for (const result of results) {
+          for (const _bundle of result) {
+            const value = w.get(e, TestName).unwrap().value;
+            expectTypeOf(value).toEqualTypeOf<string>();
+          }
+        }
+      },
+    });
+  });
+});
+
+describe('w7 --- (c) top-level direct import (AC-02)', () => {
+  it('world.get(e, TestName).unwrap().value infers as string at top-level', () => {
+    const w = new World();
+    const e = w.spawn({ component: TestName, data: { value: 'Hero' } }).unwrap();
+    const value = w.get(e, TestName).unwrap().value;
+    expectTypeOf(value).toEqualTypeOf<string>();
+  });
+});

package/src/__tests__/plugin-service.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, it } from 'vitest';
+import { createWorldContext } from '../plugin-service';
+import { World } from '../world';
+
+describe('world plugin service', () => {
+  it('creates a Cordis context with the World owner', async () => {
+    const world = new World();
+    const context = await createWorldContext(world);
+
+    expect(context).toBeDefined();
+    await context.fiber.dispose();
+  });
+});

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

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest';
+import { defineComponent } from '../component';
+import { World } from '../world';
+
+const Position = defineComponent('CombinationPosition', { x: 'f32' });
+
+describe('Query.combinations', () => {
+  it('uses the same filtered entity order as row iteration', () => {
+    const world = new World();
+    const entities = [1, 2, 3].map((x) =>
+      world.spawn({ component: Position, data: { x } }).unwrap(),
+    );
+    const query = world.query({ read: [Position] }).unwrap();
+    const pairs = [...query.combinations()].map((rows) => rows.map((row) => row.entity));
+    expect(pairs).toEqual([
+      [entities[0], entities[1]],
+      [entities[0], entities[2]],
+      [entities[1], entities[2]],
+    ]);
+  });
+
+  it('supports k-tuples and yields none when k exceeds the match count', () => {
+    const world = new World();
+    for (const x of [1, 2, 3]) world.spawn({ component: Position, data: { x } }).unwrap();
+    const query = world.query({ read: [Position] }).unwrap();
+    expect([...query.combinations(3)]).toHaveLength(1);
+    expect([...query.combinations(4)]).toEqual([]);
+  });
+
+  it('does not commit change observation when combination iteration stops early', () => {
+    const world = new World();
+    const entities = [1, 2, 3].map((x) =>
+      world.spawn({ component: Position, data: { x } }).unwrap(),
+    );
+    const query = world.query({ read: [Position], changed: [Position] }).unwrap();
+    const iterator = query.combinations(2)[Symbol.iterator]();
+    expect(iterator.next().done).toBe(false);
+    iterator.return?.();
+
+    expect(Array.from(query, (row) => row.entity)).toEqual(entities);
+  });
+});

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

@@ -0,0 +1,252 @@
+// feat-20260709 M2 / w6: light-extract flat-column A/B perf ratio bench (AC-10, D-2/D-6).
+//
+// Independent of the TRS bench (query-trs-flat-column-ratio.perf.test.ts, D-2):
+// light extract is a distinct hot path (q7) -- it multiplies each color lane by
+// intensity while reading direction, so its per-row work differs from the
+// propagate/getField path. This bench models the render-system-extract light
+// loop over QuerySpan columns, NOT the TRS path, and does not reuse its
+// baseline.
+//
+// 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:  directionX/Y/Z + colorR/G/B + intensity (7 per-axis f32 scalar
+//              columns, the pre-migration light shape, synthesized here so the
+//              gate survives the migration).
+//   Candidate: direction array<f32,3> / color array<f32,3> + intensity (the
+//              post-migration shape), read via the query bundle's flat stride-N
+//              subarray -- direction[i*3+a] / color[i*3+a], zero per-call
+//              allocation (research Finding 5 adjudication table, allowed row;
+//              D-6 forbids .get() materialize / _getArrayView per-call alloc).
+//
+// 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 (contiguous 3-wide lanes have better locality
+// than 7 scattered columns); 1.15 is anti-noise headroom, not a concession.
+//
+// Falsifiability (plan-strategy 5.4, one-time manual check, not in CI):
+// swapping the candidate reader to the world.get(e, C).color materializing path
+// blows the ratio past the gate (precedent magnitude ~51) -- verified once by hand
+// during w6 (see milestone report), then restored to the flat form below.
+
+import { describe, expect, it } from 'vitest';
+import { defineComponent } from '../component';
+import { World } from '../world';
+import { worldInternal } from '../world-internal';
+
+const N = 10_000;
+const ROUNDS = 5;
+const INNER_REPEATS = 30;
+const RATIO_GATE = 1.15;
+
+const BaselineLight7 = defineComponent('W6_BaselineLight7', {
+  directionX: 'f32',
+  directionY: 'f32',
+  directionZ: 'f32',
+  colorR: 'f32',
+  colorG: 'f32',
+  colorB: 'f32',
+  intensity: 'f32',
+});
+
+const CandidateLightVec = defineComponent('W6_CandidateLightVec', {
+  direction: { type: 'array<f32, 3>', default: new Float32Array(3) },
+  color: { type: 'array<f32, 3>', default: new Float32Array([1, 1, 1]) },
+  intensity: { type: 'f32', default: 1 },
+});
+
+function spawnBaselineWorld(): World {
+  const world = new World();
+  for (let i = 0; i < N; i++) {
+    world.spawn({
+      component: BaselineLight7,
+      data: {
+        directionX: i,
+        directionY: i * 2,
+        directionZ: i * 3,
+        colorR: 0.5,
+        colorG: 0.6,
+        colorB: 0.7,
+        intensity: 2,
+      },
+    });
+  }
+  return world;
+}
+
+function spawnCandidateWorld(): World {
+  const world = new World();
+  for (let i = 0; i < N; i++) {
+    world.spawn({
+      component: CandidateLightVec,
+      data: { direction: [i, i * 2, i * 3], color: [0.5, 0.6, 0.7], intensity: 2 },
+    });
+  }
+  return world;
+}
+
+// Preallocated snapshot sinks (mirrors extract writing into a fixed array).
+const snapDir = new Float32Array(N * 3);
+const snapColor = new Float32Array(N * 3);
+
+/** Extract-shaped loop over per-axis scalar columns. */
+function traverseBaseline(world: World): number {
+  const query = world.query({ read: [BaselineLight7] }).unwrap();
+  let sum = 0;
+  for (let rep = 0; rep < INNER_REPEATS; rep++) {
+    for (const span of query.spans().unwrap()) {
+      const b = span.get(BaselineLight7);
+      const n = span.length;
+      for (let i = 0; i < n; i++) {
+        const intensity = b.intensity[i] as number;
+        snapDir[i * 3] = b.directionX[i] as number;
+        snapDir[i * 3 + 1] = b.directionY[i] as number;
+        snapDir[i * 3 + 2] = b.directionZ[i] as number;
+        snapColor[i * 3] = (b.colorR[i] as number) * intensity;
+        snapColor[i * 3 + 1] = (b.colorG[i] as number) * intensity;
+        snapColor[i * 3 + 2] = (b.colorB[i] as number) * intensity;
+        sum += (snapDir[i * 3] as number) + (snapColor[i * 3] as number);
+      }
+    }
+  }
+  return sum;
+}
+
+/** Extract-shaped loop over flat stride-N array columns (D-6 hot-path form). */
+function traverseCandidate(world: World): number {
+  const query = world.query({ read: [CandidateLightVec] }).unwrap();
+  let sum = 0;
+  for (let rep = 0; rep < INNER_REPEATS; rep++) {
+    for (const span of query.spans().unwrap()) {
+      const c = span.get(CandidateLightVec);
+      const direction = c.direction;
+      const color = c.color;
+      const n = span.length;
+      for (let i = 0; i < n; i++) {
+        const intensity = c.intensity[i] as number;
+        snapDir[i * 3] = direction[i * 3] as number;
+        snapDir[i * 3 + 1] = direction[i * 3 + 1] as number;
+        snapDir[i * 3 + 2] = direction[i * 3 + 2] as number;
+        snapColor[i * 3] = (color[i * 3] as number) * intensity;
+        snapColor[i * 3 + 1] = (color[i * 3 + 1] as number) * intensity;
+        snapColor[i * 3 + 2] = (color[i * 3 + 2] as number) * intensity;
+        sum += (snapDir[i * 3] as number) + (snapColor[i * 3] as number);
+      }
+    }
+  }
+  return sum;
+}
+
+describe('w6 -- light-extract flat-column A/B perf ratio (AC-10)', () => {
+  it(`candidate/baseline extract 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 write identical values -- keeps the loops from being
+    // dead-code-eliminated and doubles as a smoke correctness check.
+    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-10 review
+    console.info(
+      `[w6 perf ratio] baseline_min=${baselineMin.toFixed(3)}ms candidate_min=${candidateMin.toFixed(3)}ms ratio=${ratio.toFixed(3)}`,
+    );
+
+    expect(ratio).toBeLessThanOrEqual(RATIO_GATE);
+  });
+});
+
+describe('M5 -- wide table versus sparse tag-flip trend', () => {
+  const widths = [1, 4, 8, 16] as const;
+  const TableFlipTag = defineComponent('M5WideTableFlipTag', {});
+  const SparseFlipTag = defineComponent('M5WideSparseFlipTag', {}, { storage: 'sparse' });
+
+  function makeWideComponent(width: number) {
+    const schema: Record<string, 'f32'> = {};
+    for (let index = 0; index < width; index++) schema[`f${index}`] = 'f32';
+    return defineComponent(`M1WideFlip${width}`, schema);
+  }
+
+  function bytesIn(table: {
+    storage: Map<number, { fields: Map<string, { buffer: ArrayBufferLike }> }>;
+  }): number {
+    let bytes = 0;
+    for (const { fields } of table.storage.values()) {
+      for (const column of fields.values()) bytes += column.buffer.byteLength;
+    }
+    return bytes;
+  }
+
+  it('keeps sparse copied bytes flat at zero while table migration grows with arity', () => {
+    const tableCopiedBytes: number[] = [];
+    const sparseCopiedBytes: number[] = [];
+    for (const width of widths) {
+      const wide = makeWideComponent(width);
+      const tableWorld = new World();
+      const tableEntity = tableWorld.spawn({ component: wide, data: {} as never }).unwrap();
+      const tableBefore = tableWorld[worldInternal].getGraph().tables[0];
+      if (tableBefore === undefined) throw new Error('source table missing');
+      tableCopiedBytes.push(bytesIn(tableBefore));
+      tableWorld.addComponent(tableEntity, { component: TableFlipTag, data: {} }).unwrap();
+
+      const sparseWorld = new World();
+      const sparseEntity = sparseWorld.spawn({ component: wide, data: {} as never }).unwrap();
+      const sparseBefore = sparseWorld[worldInternal].getGraph().tables[0];
+      if (sparseBefore === undefined) throw new Error('source table missing');
+      sparseWorld.addComponent(sparseEntity, { component: SparseFlipTag, data: {} }).unwrap();
+      const sparseAfter = sparseWorld[worldInternal].getGraph().tables[0];
+      sparseCopiedBytes.push(sparseAfter === sparseBefore ? 0 : bytesIn(sparseBefore));
+    }
+
+    // biome-ignore lint/suspicious/noConsole: the trend is the characterization output
+    console.info(
+      `[m5 tag-flip] widths=${widths.join(',')} tableCopiedBytes=${tableCopiedBytes.join(',')} sparseCopiedBytes=${sparseCopiedBytes.join(',')}`,
+    );
+    const [first, second, third, fourth] = tableCopiedBytes;
+    if (
+      first === undefined ||
+      second === undefined ||
+      third === undefined ||
+      fourth === undefined
+    ) {
+      throw new Error('wide-tag trend did not produce four samples');
+    }
+    expect(first).toBeLessThan(second);
+    expect(second).toBeLessThan(third);
+    expect(third).toBeLessThan(fourth);
+    expect(sparseCopiedBytes).toEqual([0, 0, 0, 0]);
+  });
+});

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

@@ -0,0 +1,104 @@
+import { describe, expect, it } from 'vitest';
+import { defineComponent } from '../component';
+import { World } from '../world';
+
+const ENTITY_COUNT = 2_000;
+const ROUNDS = 3;
+
+const TrendValue = defineComponent('StorageTrendValue', { value: 'f32' });
+const TrendSelected = defineComponent('StorageTrendSelected', {}, { storage: 'sparse' });
+
+function minimumDuration(run: () => number): { duration: number; sum: number } {
+  let duration = Number.POSITIVE_INFINITY;
+  let sum = 0;
+  for (let round = 0; round < ROUNDS; round++) {
+    const start = performance.now();
+    sum = run();
+    duration = Math.min(duration, performance.now() - start);
+  }
+  return { duration, sum };
+}
+
+describe('table, sparse, span, and change-distribution trends', () => {
+  it('reports equivalent table-row, sparse-row, and dense-span traversal', () => {
+    const world = new World();
+    for (let index = 0; index < ENTITY_COUNT; index++) {
+      const components = [{ component: TrendValue, data: { value: index + 1 } }] as const;
+      if (index % 2 === 0) {
+        world.spawn(...components, { component: TrendSelected, data: {} }).unwrap();
+      } else {
+        world.spawn(...components).unwrap();
+      }
+    }
+
+    const tableRows = world.query({ read: [TrendValue] }).unwrap();
+    const sparseRows = world.query({ read: [TrendValue], with: [TrendSelected] }).unwrap();
+    const denseSpans = world.query({ read: [TrendValue] }).unwrap();
+
+    const table = minimumDuration(() => {
+      let sum = 0;
+      for (const row of tableRows) sum += row.get(TrendValue).value;
+      return sum;
+    });
+    const sparse = minimumDuration(() => {
+      let sum = 0;
+      for (const row of sparseRows) sum += row.get(TrendValue).value;
+      return sum;
+    });
+    const span = minimumDuration(() => {
+      let sum = 0;
+      for (const range of denseSpans.spans().unwrap()) {
+        const values = range.get(TrendValue).value;
+        for (let index = 0; index < range.length; index++) sum += values[index] ?? 0;
+      }
+      return sum;
+    });
+
+    expect(table.sum).toBe((ENTITY_COUNT * (ENTITY_COUNT + 1)) / 2);
+    expect(sparse.sum).toBe((ENTITY_COUNT / 2) ** 2);
+    expect(span.sum).toBe(table.sum);
+    expect([...denseSpans.spans().unwrap()]).toHaveLength(1);
+
+    // biome-ignore lint/suspicious/noConsole: trend output is review evidence, not an absolute gate
+    console.info(
+      `[storage trend] table-row=${table.duration.toFixed(3)}ms sparse-row=${sparse.duration.toFixed(3)}ms span=${span.duration.toFixed(3)}ms entities=${ENTITY_COUNT}`,
+    );
+  });
+
+  it('observes block and interleaved changes as rows without result fragmentation', () => {
+    const world = new World();
+    const entities = Array.from({ length: ENTITY_COUNT }, (_, index) =>
+      world.spawn({ component: TrendValue, data: { value: index } }).unwrap(),
+    );
+    const changed = world.query({ changed: [TrendValue] }).unwrap();
+    expect([...changed]).toHaveLength(ENTITY_COUNT);
+
+    for (let index = 0; index < ENTITY_COUNT; index += 2) {
+      const entity = entities[index];
+      if (entity === undefined) throw new Error('interleaved trend entity missing');
+      world.set(entity, TrendValue, { value: index + 1 }).unwrap();
+    }
+    const interleavedStart = performance.now();
+    const interleaved = Array.from(changed, (row) => row.entity);
+    const interleavedDuration = performance.now() - interleavedStart;
+
+    for (let index = 0; index < ENTITY_COUNT / 2; index++) {
+      const entity = entities[index];
+      if (entity === undefined) throw new Error('block trend entity missing');
+      world.set(entity, TrendValue, { value: index + 2 }).unwrap();
+    }
+    const blockStart = performance.now();
+    const block = Array.from(changed, (row) => row.entity);
+    const blockDuration = performance.now() - blockStart;
+
+    expect(interleaved).toHaveLength(ENTITY_COUNT / 2);
+    expect(block).toHaveLength(ENTITY_COUNT / 2);
+    expect(interleaved.every((entity, index) => entity === entities[index * 2])).toBe(true);
+    expect(block.every((entity, index) => entity === entities[index])).toBe(true);
+
+    // biome-ignore lint/suspicious/noConsole: distribution timing is characterization evidence
+    console.info(
+      `[change trend] interleaved=${interleavedDuration.toFixed(3)}ms block=${blockDuration.toFixed(3)}ms hits=${ENTITY_COUNT / 2}`,
+    );
+  });
+});