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

package/src/__tests__/sparse-tag.unit.test.ts

@@ -0,0 +1,201 @@
+import { describe, expect, it } from 'vitest';
+import type { Component } from '../component';
+import { componentId, defineComponent } from '../component';
+import { Disabled, Entity } from '../entity';
+import type { EntityHandle } from '../entity-handle';
+import { SparseStorageRequiresTagError } from '../errors';
+import { Update } from '../schedule-token';
+import { sparseTagHas } from '../storage/change-detection';
+import { World } from '../world';
+
+import { worldInternal } from '../world-internal';
+
+describe('sparse tag storage', () => {
+  it('defaults components to table and rejects sparse components with fields', () => {
+    const TableTag = defineComponent('DefaultTableTag', {});
+    expect(TableTag.storage).toBe('table');
+    expect(Disabled.storage).toBe('table');
+    expect(() =>
+      defineComponent('InvalidSparseData', { value: 'f32' }, { storage: 'sparse' }),
+    ).toThrow(SparseStorageRequiresTagError);
+  });
+
+  it('shares one Table across Archetypes that differ only by sparse membership', () => {
+    const Position = defineComponent('SharedTablePosition', { x: 'f32' });
+    const Selected = defineComponent('SharedTableSelected', {}, { storage: 'sparse' });
+    const world = new World();
+    const plain = world.spawn({ component: Position, data: { x: 1 } }).unwrap();
+    const selected = world
+      .spawn({ component: Position, data: { x: 2 } }, { component: Selected, data: {} })
+      .unwrap();
+    const graph = world[worldInternal].getGraph();
+    const plainArchetype = world[worldInternal].getEntityArchetype(plain);
+    const selectedArchetype = world[worldInternal].getEntityArchetype(selected);
+
+    expect(plainArchetype).not.toBe(selectedArchetype);
+    expect(plainArchetype?.tableId).toBe(selectedArchetype?.tableId);
+    expect(graph.tables).toHaveLength(1);
+    expect(graph.tables[0]?.components.map((component: Component) => component.name)).toEqual([
+      'Entity',
+      'SharedTablePosition',
+    ]);
+  });
+
+  it('flips sparse membership without changing any Table state', () => {
+    const Wide = defineComponent('SparseFlipWide', {
+      a: 'f32',
+      b: 'f32',
+      c: 'f32',
+      d: 'f32',
+    });
+    const Selected = defineComponent('SparseFlipSelected', {}, { storage: 'sparse' });
+    const world = new World();
+    const entity = world.spawn({ component: Wide, data: { a: 1, b: 2, c: 3, d: 4 } }).unwrap();
+    const graph = world[worldInternal].getGraph();
+    const sourceArchetype = world[worldInternal].getEntityArchetype(entity);
+    if (sourceArchetype === undefined) throw new Error('source archetype missing');
+    const table = graph.tables[sourceArchetype.tableId];
+    if (table === undefined) throw new Error('table missing');
+    const tableRow = sourceArchetype.rows[0] ?? -1;
+    const before = {
+      size: table.size,
+      capacity: table.capacity,
+      version: table.version,
+      fields: [...table.storage.values()].flatMap(({ fields }) =>
+        [...fields.values()].map((column) => ({
+          buffer: column.view.buffer,
+          bytes: new Uint8Array(column.view.buffer).slice(),
+        })),
+      ),
+      epochs: [...table.storage.values()].map(({ epochs }) => ({
+        added: epochs.added.slice(),
+        changed: epochs.changed.slice(),
+      })),
+    };
+
+    world.addComponent(entity, { component: Selected, data: {} }).unwrap();
+    const selectedArchetype = world[worldInternal].getEntityArchetype(entity);
+    expect(selectedArchetype?.tableId).toBe(table.id);
+    expect(selectedArchetype?.rows[0]).toBe(tableRow);
+    expect(table.size).toBe(before.size);
+    expect(table.capacity).toBe(before.capacity);
+    expect(table.version).toBe(before.version);
+    for (const [index, column] of before.fields.entries()) {
+      const current = [...table.storage.values()].flatMap(({ fields }) => [...fields.values()])[
+        index
+      ];
+      expect(current?.view.buffer).toBe(column.buffer);
+      expect(new Uint8Array(current?.view.buffer ?? new ArrayBuffer(0))).toEqual(column.bytes);
+    }
+    expect(
+      [...table.storage.values()].map(({ epochs }) => ({
+        added: epochs.added,
+        changed: epochs.changed,
+      })),
+    ).toEqual(before.epochs);
+
+    world.removeComponent(entity, Selected).unwrap();
+    expect(world[worldInternal].getEntityArchetype(entity)?.tableId).toBe(table.id);
+    expect(table.size).toBe(before.size);
+    expect(table.version).toBe(before.version);
+  });
+
+  it('deduplicates dense table queries and routes sparse predicates through Archetypes', () => {
+    const Position = defineComponent('SparseQueryPosition', { x: 'f32' });
+    const Selected = defineComponent('SparseQuerySelected', {}, { storage: 'sparse' });
+    const world = new World();
+    const first = world.spawn({ component: Position, data: { x: 1 } }).unwrap();
+    const second = world
+      .spawn({ component: Position, data: { x: 2 } }, { component: Selected, data: {} })
+      .unwrap();
+
+    expect(Array.from(world.query({ read: [Position] }).unwrap(), (row) => row.entity)).toEqual([
+      first,
+      second,
+    ]);
+    const spans = [
+      ...world
+        .query({ read: [Position] })
+        .unwrap()
+        .spans()
+        .unwrap(),
+    ];
+    expect(spans).toHaveLength(1);
+    expect(spans[0]?.length).toBe(2);
+    expect([...world.query({ with: [Selected] }).unwrap()].map((row) => row.entity)).toEqual([
+      second,
+    ]);
+    expect([...world.query({ without: [Selected] }).unwrap()].map((row) => row.entity)).toEqual([
+      first,
+    ]);
+    const sparseSpan = world
+      .query({ with: [Selected] })
+      .unwrap()
+      .spans();
+    expect(sparseSpan.ok).toBe(false);
+    if (!sparseSpan.ok) expect(sparseSpan.error.detail.reason).toBe('sparse-component');
+  });
+
+  it('keeps sparse Added and Changed evidence generation-safe', () => {
+    const Selected = defineComponent('SparseEpochSelected', {}, { storage: 'sparse' });
+    const world = new World();
+    const added = world.query({ added: [Selected] }).unwrap();
+    const changed = world.query({ changed: [Selected] }).unwrap();
+    const first = world.spawn({ component: Selected, data: {} }).unwrap();
+    expect([...added].map((row) => row.entity)).toEqual([first]);
+    expect([...changed].map((row) => row.entity)).toEqual([first]);
+
+    world.set(first, Selected, {}).unwrap();
+    expect([...changed].map((row) => row.entity)).toEqual([first]);
+    world.despawn(first).unwrap();
+    const replacement = world.spawn().unwrap();
+    expect(replacement as number).not.toBe(first as number);
+    const set = world[worldInternal].getGraph().sparseTags.get(componentId(Selected));
+    expect(set === undefined ? false : sparseTagHas(set, replacement)).toBe(false);
+    expect([...world.query({ with: [Selected] }).unwrap()]).toEqual([]);
+  });
+
+  it('routes deferred sparse spawn, add, and remove through the same storage boundary', () => {
+    const Selected = defineComponent('DeferredSparseSelected', {}, { storage: 'sparse' });
+    const world = new World();
+    const existing = world.spawn().unwrap();
+    let observed: EntityHandle[] = [];
+
+    world.addSystem(Update, {
+      name: 'deferred-sparse-producer',
+      queries: [],
+      before: ['deferred-sparse-consumer'],
+      fn: (_world, _queries, commands) => {
+        commands.spawn({ component: Selected, data: {} });
+        commands.addComponent(existing, { component: Selected, data: {} });
+      },
+    });
+    world.addSystem(Update, {
+      name: 'deferred-sparse-consumer',
+      queries: [{ with: [Selected] }],
+      fn: (_world, [selected], commands) => {
+        observed = Array.from(selected ?? [], (row) => row.entity);
+        commands.removeComponent(existing, Selected);
+      },
+    });
+
+    expect(world.update(0).ok).toBe(true);
+    expect(observed).toHaveLength(2);
+    expect(world.get(existing, Selected).ok).toBe(false);
+    expect([...world.query({ with: [Selected] }).unwrap()]).toHaveLength(1);
+  });
+
+  it('reports sparse logical identity without pretending it is Table storage', () => {
+    const Selected = defineComponent('SparseInspectSelected', {}, { storage: 'sparse' });
+    const world = new World();
+    const entity = world.spawn({ component: Selected, data: {} }).unwrap();
+    const inspection = world.inspect();
+    const archetype = inspection.archetypes.find((item) => item.entityCount === 1);
+    const table = inspection.tables[archetype?.tableId ?? -1];
+
+    expect(world.get(entity, Entity).unwrap().self).toBe(entity);
+    expect(archetype?.componentNames).toContain('SparseInspectSelected');
+    expect(table?.componentNames).not.toContain('SparseInspectSelected');
+    expect(inspection.activeComponents).toContain('SparseInspectSelected');
+  });
+});

package/src/__tests__/spawn-field-error.test-d.ts

@@ -0,0 +1,41 @@
+// Compile-time type assertions for World.spawn() field-level error signalling
+// after the fallback overload is removed (AC-09 historical) + after the M2
+// `ComponentData.data` widening to `Partial<ShapeOf<S>>` (AC-01 / AC-02 of
+// feat-20260517-spawn-default-fallback).
+//
+// Anchors: requirements §AC-09 / requirements-decisions §F (AC-09 field-level
+// error signal restoration); research §R5.2 (P3 landing — AC-09 must live in
+// ECS strict-typed __tests__, not the runtime test files that erase Camera /
+// World types via 'unknown'); plan-strategy §2 decision D-4. The historical
+// "missing required field" probe migrated to the AC-02 partial-data probe in
+// world.test-d.ts §t6.b once M2 widened ComponentData<S>.data to
+// Partial<ShapeOf<S>>.
+//
+// The fallback overload 'spawn(...componentDatas: ComponentData[])' was the
+// historical TS escape hatch — calls that supplied a wrong `data.<field>`
+// type or omitted a required field landed on the loose overload and emitted
+// only a vague 'No overload matches this call'. After T-04 deletes the
+// fallback, the only remaining candidate is the mapped-tuple primary, which
+// surfaces field-level diagnostics ('Type X is not assignable to type Y') --
+// the test below asserts that contract for the wrong-VALUE shape (the
+// missing-FIELD shape is now a valid call after M2 / AC-02 and is covered by
+// world.test-d.ts §t6.b).
+
+import { describe, it } from 'vitest';
+import { defineComponent } from '../component';
+import { World } from '../world';
+
+describe('spawn field-level errors (AC-09 wrong-value shape)', () => {
+  it('AC-09 wrong field type: schema {value: string} rejects {value: number}', () => {
+    const Name = defineComponent('Name', { value: { type: 'string' } });
+    const world = new World();
+    world.spawn({
+      component: Name,
+      data: {
+        // @ts-expect-error AC-09 data.value must be string per schema; mapped-
+        // tuple primary inference fires field-level TS2322 on the offending key.
+        value: 42,
+      },
+    });
+  });
+});

package/src/__tests__/stale-error.test-d.ts

@@ -0,0 +1,208 @@
+import { Update } from '../schedule-token';
+// AC-L5 stale-error compile-assertion vehicle.
+//
+// Sediments 5 method-level `expectTypeOf` assertions (the 4 `lookupAlive`
+// callers — `get` / `set` / `addComponent` / `removeComponent` — plus
+// `addSystem`) into a dedicated test-d file so that `tsc -b` (and vitest
+// typecheck) certify, every release, the load-bearing type-layer contract
+// of F-1's stale-error precision work:
+//
+//   1. Each of the 4 mutation/read methods returns `Result<..., EcsError>`
+//      whose error variant — when narrowed to `StaleEntityError` — exposes
+//      `.operation: string | undefined` and `.component: string | undefined`
+//      (charter proposition 4: errors are structured payloads, not strings).
+//   2. `addSystem`'s class-method generic shape is preserved (a method-level
+//      simplified counterpart of `types.test-d.ts:[w15]` — that file owns the
+//      QueryRow inference theme; this file owns the signature
+//      shape theme; both coexist per plan-strategy §2 S-3 OQ-3).
+//
+// File structure mirrors `minimal-example.test-d.ts` (vitest test-d form,
+// `expectTypeOf` based, single top-level `describe` per method group).
+
+import type { Result } from '@forgeax/engine-types';
+import { describe, expectTypeOf, it } from 'vitest';
+import type { CommandBuffer } from '../commands';
+import { defineComponent } from '../component';
+import type { EntityHandle } from '../entity-handle';
+import { entityIndex } from '../entity-handle';
+import type { EcsErrorCode } from '../errors';
+import { StaleEntityError } from '../errors';
+import type { EcsError } from '../world';
+import { World } from '../world';
+
+describe('[w6] AC-L5 — world.get returns Result<ShapeOf<S>, EcsError> with structured stale payload', () => {
+  it('return type is Result<{ x: number; y: number }, EcsError>; stale narrowing exposes .operation/.component', () => {
+    const Position = defineComponent('Position', { x: { type: 'f32' }, y: { type: 'f32' } });
+
+    const world = new World();
+    const e = world.spawn({ component: Position, data: { x: 0, y: 0 } }).unwrap();
+    const r = world.get(e, Position);
+
+    // Signature shape: Result<ShapeOf<S>, EcsError>.
+    expectTypeOf(r).toEqualTypeOf<Result<{ readonly x: number; readonly y: number }, EcsError>>();
+
+    if (!r.ok) {
+      const err = r.error;
+      // EcsError is a union; narrowing to StaleEntityError surfaces .operation/.component.
+      if (err instanceof StaleEntityError) {
+        expectTypeOf(err.operation).toEqualTypeOf<string | undefined>();
+        expectTypeOf(err.component).toEqualTypeOf<string | undefined>();
+      }
+    }
+  });
+});
+
+describe('[w6] AC-L5 — world.set returns Result<void, EcsError> with structured stale payload', () => {
+  it('return type is Result<void, EcsError>; stale narrowing exposes .operation/.component', () => {
+    const Position = defineComponent('Position', { x: { type: 'f32' }, y: { type: 'f32' } });
+
+    const world = new World();
+    const e = world.spawn({ component: Position, data: { x: 0, y: 0 } }).unwrap();
+    const r = world.set(e, Position, { x: 10 });
+
+    expectTypeOf(r).toEqualTypeOf<Result<void, EcsError>>();
+
+    if (!r.ok) {
+      const err = r.error;
+      if (err instanceof StaleEntityError) {
+        expectTypeOf(err.operation).toEqualTypeOf<string | undefined>();
+        expectTypeOf(err.component).toEqualTypeOf<string | undefined>();
+      }
+    }
+  });
+});
+
+describe('[w6] AC-L5 — world.addComponent returns Result<void, EcsError> with structured stale payload', () => {
+  it('return type is Result<void, EcsError>; stale narrowing exposes .operation/.component', () => {
+    const Position = defineComponent('Position', { x: { type: 'f32' }, y: { type: 'f32' } });
+    const Velocity = defineComponent('Velocity', { dx: { type: 'f32' }, dy: { type: 'f32' } });
+
+    const world = new World();
+    const e = world.spawn({ component: Position, data: { x: 0, y: 0 } }).unwrap();
+    const r = world.addComponent(e, { component: Velocity, data: { dx: 1, dy: 0 } });
+
+    expectTypeOf(r).toEqualTypeOf<Result<void, EcsError>>();
+
+    if (!r.ok) {
+      const err = r.error;
+      if (err instanceof StaleEntityError) {
+        expectTypeOf(err.operation).toEqualTypeOf<string | undefined>();
+        expectTypeOf(err.component).toEqualTypeOf<string | undefined>();
+      }
+    }
+  });
+});
+
+describe('[w6] AC-L5 — world.removeComponent returns Result<void, EcsError> with structured stale payload', () => {
+  it('return type is Result<void, EcsError>; stale narrowing exposes .operation/.component', () => {
+    const Position = defineComponent('Position', { x: { type: 'f32' }, y: { type: 'f32' } });
+
+    const world = new World();
+    const e = world.spawn({ component: Position, data: { x: 0, y: 0 } }).unwrap();
+    const r = world.removeComponent(e, Position);
+
+    expectTypeOf(r).toEqualTypeOf<Result<void, EcsError>>();
+
+    if (!r.ok) {
+      const err = r.error;
+      if (err instanceof StaleEntityError) {
+        expectTypeOf(err.operation).toEqualTypeOf<string | undefined>();
+        expectTypeOf(err.component).toEqualTypeOf<string | undefined>();
+      }
+    }
+  });
+});
+
+describe('[w6] AC-L5 — world.addSystem<const Qs> method signature shape (simplified counterpart of types.test-d.ts:[w15])', () => {
+  it('addSystem returns void; fn receives mapped queryResults + CommandBuffer at the method-level call site', () => {
+    const Position = defineComponent('Position', { x: { type: 'f32' }, y: { type: 'f32' } });
+
+    const world = new World();
+    const ret = world.addSystem(Update, {
+      name: 'ac-l5-shape-probe',
+      queries: [{ read: [Position] }],
+      fn: (_world, queryResults, commands) => {
+        const query = queryResults[0];
+        if (query) {
+          for (const row of query) expectTypeOf(row.get(Position).x).toBeNumber();
+        }
+        expectTypeOf(commands).toEqualTypeOf<CommandBuffer>();
+      },
+    });
+
+    // Class-method `addSystem` reports a structured schedule-scope result.
+    expectTypeOf(ret.ok).toEqualTypeOf<boolean>();
+  });
+});
+
+// w3: type-level assertion — entityIndex returns number (u32 slot, low 24 bits)
+describe('[w3] Entity codec type contract', () => {
+  it('entityIndex returns number', () => {
+    const fake = 0 as EntityHandle;
+    expectTypeOf(entityIndex(fake)).toEqualTypeOf<number>();
+  });
+});
+
+// w13: EcsErrorCode exhaustion test-d — store-level type completeness gate.
+// Verifies the closed union includes 'shared-ref-stale' and 'unique-ref-stale'
+// so that any exhaustive switch without these codes triggers TS never error.
+// Distinct from w19 (resolveAssetHandle real consumption path, AC-10).
+describe('[w13] EcsErrorCode union completeness — stale codes present', () => {
+  it('exhaustive switch over EcsErrorCode must include shared-ref-stale', () => {
+    // If shared-ref-stale is NOT in the union, this switch block would
+    // still compile because the type level never would not trigger —
+    // this test-d proves the code IS in the union.
+    const assertExhaustive = (code: EcsErrorCode): string => {
+      switch (code) {
+        case 'stale-entity':
+        case 'component-already-present':
+        case 'component-not-present':
+        case 'cyclic-dependency':
+        case 'resource-not-found':
+        case 'system-before-unknown':
+        case 'unique-ref-released':
+        case 'unique-ref-double-release':
+        case 'unique-ref-stale':
+        case 'shared-ref-released':
+        case 'shared-ref-double-release':
+        case 'shared-ref-payload-invalid':
+        case 'shared-ref-stale':
+        case 'builtin-slot-not-owned':
+        case 'managed-buffer-out-of-bounds':
+        case 'managed-buffer-shrink-not-supported':
+        case 'fixed-size-mismatch':
+        case 'managed-array-invalid-value':
+        case 'relationship-self-cycle':
+        case 'relationship-detach-mismatch':
+        case 'remove-essential-component':
+        case 'spawn-data-unknown-field':
+        // feat-20260713-mount-override-component-add-and-shared-ref-round M2 / w9
+        case 'shared-field-invalid-value':
+        // feat-20260714-bevy-style-system-sets M1 / w3
+        case 'system-set-not-registered':
+        case 'time-delta-invalid':
+        case 'time-config-invalid':
+        case 'schedule-scope-mismatch':
+        case 'component-field-invalid-value':
+        case 'component-numeric-value-invalid':
+        case 'shared-kernel-ineligible':
+        case 'shared-kernel-failed':
+        case 'world-poisoned':
+        case 'command-failed':
+        case 'system-failed':
+          return code;
+      }
+    };
+    expectTypeOf(assertExhaustive).toBeFunction();
+  });
+
+  it('shared-ref-stale is assignable to EcsErrorCode', () => {
+    const stale: EcsErrorCode = 'shared-ref-stale';
+    expectTypeOf(stale).toEqualTypeOf<'shared-ref-stale'>();
+  });
+
+  it('unique-ref-stale is assignable to EcsErrorCode', () => {
+    const stale: EcsErrorCode = 'unique-ref-stale';
+    expectTypeOf(stale).toEqualTypeOf<'unique-ref-stale'>();
+  });
+});

package/src/__tests__/string-view-symmetry.test-d.ts

@@ -0,0 +1,26 @@
+// w9 --- AC-01 type-level FieldValueType<'string'> contract.
+//
+// Locks AC-01: the `'string'` schema-vocab keyword resolves through
+// `FieldValueType<...>` to a native JS `string`. After the StringView
+// collapse (D-R1, requirements 2.2), there is no longer a 3-arm symmetry
+// between StringView / FixedArrayView / VarArrayView --- the string field
+// reads directly as a JS string by-reference, leaving the array fields
+// alone in the view-class category.
+//
+// This file is a focused FieldValueType<'string'> contract test; the prior
+// 3-arm view-class symmetry content was retired together with StringView.
+
+import { describe, expectTypeOf, it } from 'vitest';
+import type { FieldValueType, ShapeOf } from '../component';
+
+describe('w9 --- FieldValueType<"string"> resolves to native JS string (AC-01)', () => {
+  it('FieldValueType<"string"> = string', () => {
+    expectTypeOf<FieldValueType<'string'>>().toEqualTypeOf<string>();
+  });
+
+  it('ShapeOf threads "string" through FieldValueType to a native string field', () => {
+    type S = { value: 'string' };
+    type Expected = { value: string };
+    expectTypeOf<ShapeOf<S>>().toEqualTypeOf<Expected>();
+  });
+});

package/src/__tests__/string-vocab.test-d.ts

@@ -0,0 +1,49 @@
+// w12 --- 'string' SchemaVocabKeyword + FieldValueType<'string'> = string.
+//
+// Locks two tier-2 invariants after the StringView collapse (D-R1):
+//
+//   1. 'string' remains a member of the closed `SchemaVocabKeyword` union
+//      (the union member count is unchanged at 7 --- the collapse swapped
+//      the value shape only, not the keyword surface).
+//
+//   2. `FieldValueType<'string'>` resolves to a native JS `string` (not
+//      the retired StringView wrapper). `ShapeOf<{ value: 'string' }>`
+//      threads through to `{ value: string }`.
+//
+// The prior file's StringView 5-surface assertions and JS-string
+// prototype-method `@ts-expect-error` cases were retired together with
+// StringView; the file survives as the focused vocab + FieldValueType
+// contract test.
+
+import { describe, expectTypeOf, it } from 'vitest';
+import type {
+  defineComponent,
+  FieldValueType,
+  SchemaOf,
+  SchemaVocabKeyword,
+  ShapeOf,
+} from '../component';
+
+describe('w12 --- "string" remains a SchemaVocabKeyword member (closed-union invariant)', () => {
+  it("'string' extends SchemaVocabKeyword", () => {
+    expectTypeOf<'string'>().toMatchTypeOf<SchemaVocabKeyword>();
+  });
+});
+
+describe('w12 --- FieldValueType<"string"> = string (post-collapse)', () => {
+  it("FieldValueType<'string'> = string", () => {
+    expectTypeOf<FieldValueType<'string'>>().toEqualTypeOf<string>();
+  });
+
+  it('ShapeOf threads "string" through FieldValueType', () => {
+    type S = { value: 'string' };
+    type Expected = { value: string };
+    expectTypeOf<ShapeOf<S>>().toEqualTypeOf<Expected>();
+  });
+
+  it('three application points all infer the value field as string', () => {
+    type Foo = ReturnType<typeof defineComponent<'Foo', { value: 'string' }>>;
+    type FooShape = ShapeOf<SchemaOf<Foo>>;
+    expectTypeOf<FooShape['value']>().toEqualTypeOf<string>();
+  });
+});

package/src/__tests__/structure-epoch-boundaries.unit.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest';
+import { defineComponent } from '../component';
+import { World } from '../world';
+
+describe('structureEpoch boundaries', () => {
+  it('reports a strictly increasing revision for each successful structure write', () => {
+    const Tag = defineComponent('StructureEpochBoundaryTag', {});
+    const world = new World();
+    const values = [world.getStructureEpoch()];
+    const entity = world.spawn({ component: Tag, data: {} }).unwrap();
+    values.push(world.getStructureEpoch());
+    world
+      .addComponent(entity, {
+        component: defineComponent('StructureEpochBoundaryExtra', { value: 'f32' }),
+        data: { value: 1 },
+      })
+      .unwrap();
+    values.push(world.getStructureEpoch());
+    world.despawn(entity).unwrap();
+    values.push(world.getStructureEpoch());
+
+    expect(values).toEqual([...values].sort((left, right) => left - right));
+    expect(new Set(values).size).toBe(values.length);
+  });
+
+  it('keeps scalar writes and stale writes outside the structure revision', () => {
+    const Value = defineComponent('StructureEpochBoundaryValue', { value: 'f32' });
+    const world = new World();
+    const entity = world.spawn({ component: Value, data: { value: 1 } }).unwrap();
+    const epoch = world.getStructureEpoch();
+
+    world.set(entity, Value, { value: 3 }).unwrap();
+    expect(world.getStructureEpoch()).toBe(epoch);
+    world.despawn(entity).unwrap();
+    const afterDespawn = world.getStructureEpoch();
+    expect(world.set(entity, Value, { value: 4 }).ok).toBe(false);
+    expect(world.getStructureEpoch()).toBe(afterDespawn);
+  });
+});

package/src/__tests__/structure-epoch.unit.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest';
+import { defineComponent } from '../component';
+import { World } from '../world';
+
+describe('World structureEpoch', () => {
+  it('bumps for entity and component structure writes', () => {
+    const Position = defineComponent('StructureEpochPosition', { x: 'f32' });
+    const Velocity = defineComponent('StructureEpochVelocity', { dx: 'f32' });
+    const world = new World();
+    const initial = world.getStructureEpoch();
+
+    const entity = world.spawn({ component: Position, data: { x: 1 } }).unwrap();
+    const afterSpawn = world.getStructureEpoch();
+    world.addComponent(entity, { component: Velocity, data: { dx: 2 } }).unwrap();
+    const afterAdd = world.getStructureEpoch();
+    world.removeComponent(entity, Velocity).unwrap();
+    const afterRemove = world.getStructureEpoch();
+    world.despawn(entity).unwrap();
+
+    expect(afterSpawn).toBeGreaterThan(initial);
+    expect(afterAdd).toBeGreaterThan(afterSpawn);
+    expect(afterRemove).toBeGreaterThan(afterAdd);
+    expect(world.getStructureEpoch()).toBeGreaterThan(afterRemove);
+  });
+
+  it('does not bump for scalar writes or no-op writes', () => {
+    const Position = defineComponent('StructureEpochScalar', { x: 'f32' });
+    const world = new World();
+    const entity = world.spawn({ component: Position, data: { x: 1 } }).unwrap();
+    const beforeWrite = world.getStructureEpoch();
+
+    world.set(entity, Position, { x: 2 }).unwrap();
+    expect(world.getStructureEpoch()).toBe(beforeWrite);
+    world.set(entity, Position, {}).unwrap();
+    expect(world.getStructureEpoch()).toBe(beforeWrite);
+  });
+
+  it('does not let stale writes change the current World revision', () => {
+    const Position = defineComponent('StructureEpochStale', { x: 'f32' });
+    const world = new World();
+    const entity = world.spawn({ component: Position, data: { x: 1 } }).unwrap();
+    world.despawn(entity).unwrap();
+    const beforeStaleWrite = world.getStructureEpoch();
+
+    expect(world.set(entity, Position, { x: 2 }).ok).toBe(false);
+    expect(world.getStructureEpoch()).toBe(beforeStaleWrite);
+  });
+});