@forgeax/engine-ecs 0.1.20 → 0.1.23

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++) {

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

@@ -138,7 +138,7 @@ describe('executable Query', () => {
     expect(spans[0]?.get(Position).x[0]).toBe(1);
   });
 
-  it('returns structured span capability failures', () => {
+  it('returns structured span capability failures and coalesces changed rows', () => {
     const world = new World();
     const optional = world
       .query({ read: [Position], optional: [Velocity] })
@@ -146,11 +146,15 @@ describe('executable Query', () => {
       .spans();
     expect(!optional.ok && optional.error.detail.reason).toBe('optional-data');
 
-    const changed = world
-      .query({ read: [Position], changed: [Position] })
-      .unwrap()
-      .spans();
-    expect(!changed.ok && changed.error.detail.reason).toBe('row-change-filter');
+    const { world: changedWorld, first, second } = createWorld();
+    const changedQuery = changedWorld.query({ read: [Position], changed: [Position] }).unwrap();
+    expect([...changedQuery.spans().unwrap()].flatMap((span) => Array.from(span.entities))).toEqual(
+      [first, second],
+    );
+    changedWorld.set(second, Position, { x: 9 }).unwrap();
+    const changedSpans = [...changedQuery.spans().unwrap()];
+    expect(changedSpans).toHaveLength(1);
+    expect(Array.from(changedSpans[0]?.entities ?? [])).toEqual([second]);
   });
 
   it('does not commit observation after partial iteration', () => {

package/src/__tests__/shared-ref-store.unit.test.ts

@@ -70,7 +70,6 @@ describe('w6 SharedRefStore: alloc + resolve', () => {
     expect(store.markChanged(handle).ok).toBe(true);
     expect(store.getMutationEpoch()).toBe(1);
     expect(store.readChangesSince(0)).toEqual({
-      status: 'ok',
       cursor: 1,
       records: [{ epoch: 1, handle: unwrapHandle(handle) }],
     });
@@ -80,21 +79,17 @@ describe('w6 SharedRefStore: alloc + resolve', () => {
     expect(store.getMutationEpoch()).toBe(1);
   });
 
-  it('reports bounded-journal overflow instead of hiding changed handles', () => {
+  it('keeps one latest mutation epoch per handle without a bounded journal', () => {
     const store = new SharedRefStore();
     const handle = store.alloc('MaterialAsset', { value: 1 });
     for (let index = 0; index < 4097; index += 1) store.markChanged(handle).unwrap();
 
     expect(store.readChangesSince(0)).toEqual({
-      status: 'overflow',
       cursor: 4097,
-      oldestAvailable: 2,
+      records: [{ epoch: 4097, handle: unwrapHandle(handle) }],
     });
     const latest = store.readChangesSince(4096);
-    expect(latest.status).toBe('ok');
-    if (latest.status === 'ok') {
-      expect(latest.records).toEqual([{ epoch: 4097, handle: unwrapHandle(handle) }]);
-    }
+    expect(latest.records).toEqual([{ epoch: 4097, handle: unwrapHandle(handle) }]);
   });
 
   it('resolve returns SharedRefStaleError after rc drops to 0 (gen incremented on release)', () => {

package/src/__tests__/structural-evidence.contract.test-d.ts

@@ -0,0 +1,6 @@
+import type { StructuralEvidence, StructuralEvidenceKind } from '../storage/structural-evidence';
+
+const kind: StructuralEvidenceKind = 'component-added';
+const evidence: StructuralEvidence = { sequence: 1, kind, entity: 0 as never, componentId: 4 };
+// @ts-expect-error evidence sequence is producer-owned.
+evidence.sequence = 2;

package/src/__tests__/structural-evidence.contract.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+import { encodeEntity } from '../entity-handle';
+import { StructuralEvidenceRing } from '../storage/structural-evidence';
+
+describe('typed structural evidence ring', () => {
+  it('records lifecycle, component membership, packed identity, and sequence facts', () => {
+    const ring = new StructuralEvidenceRing(8);
+    const entity = encodeEntity(4, 2);
+    const cursor = ring.cursor;
+    ring.append({ kind: 'spawn', entity });
+    ring.append({ kind: 'component-added', entity, componentId: 7 });
+    ring.append({ kind: 'component-removed', entity, componentId: 7 });
+    ring.append({ kind: 'despawn', entity });
+    const read = ring.readAfter(cursor);
+    expect(read.status).toBe('ok');
+    if (read.status !== 'ok') return;
+    expect(
+      read.events.map(({ kind, entity: packed, sequence }) => ({ kind, packed, sequence })),
+    ).toEqual([
+      { kind: 'spawn', packed: entity, sequence: 1 },
+      { kind: 'component-added', packed: entity, sequence: 2 },
+      { kind: 'component-removed', packed: entity, sequence: 3 },
+      { kind: 'despawn', packed: entity, sequence: 4 },
+    ]);
+  });
+
+  it('fails closed on overflow and exposes the cursor for consumer reconciliation', () => {
+    const ring = new StructuralEvidenceRing(2);
+    const cursor = ring.cursor;
+    const entity = encodeEntity(1, 4);
+    const reused = encodeEntity(1, 5);
+    ring.append({ kind: 'spawn', entity });
+    ring.append({ kind: 'despawn', entity });
+    ring.append({ kind: 'spawn', entity: reused });
+    expect(ring.readAfter(cursor)).toMatchObject({
+      status: 'overflow',
+      cursor: 3,
+      oldestAvailable: 2,
+    });
+    expect(ring.cursor).toBe(3);
+  });
+
+  it('rejects cursors outside the producer-owned sequence range', () => {
+    const ring = new StructuralEvidenceRing(4);
+    const entity = encodeEntity(3, 1);
+    ring.append({ kind: 'spawn', entity });
+    expect(() => ring.readAfter(2)).toThrow(RangeError);
+  });
+});