@adobe/ecs 0.2.3 → 0.3.0

package/src/implementation/world/run-changes.ts

@@ -0,0 +1,160 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Entity } from '../../interface/entity/entity.js';
+import type { Essential, ReadonlyType } from '../../interface/component/value.js';
+import type { ChangeSet } from '../../interface/finalizer/body.js';
+import type { Resource } from '../../interface/resource/resource.js';
+import { isLeaf, newestKeyOf, scheduleOf, type Definition, type Leaf } from '../../interface/registry/index.js';
+import type { Archetype } from './archetype.js';
+import { readCell } from './cells.js';
+import { asEntity, indexOf, locate } from './entities.js';
+import { sameValue } from './resource-changes.js';
+import { findResource, initialOf } from './resources.js';
+import { metIdOf, type Key, type State } from './state.js';
+import type { Queued } from './synchronize.js';
+
+/**
+ * What a run asked for its changes holds while it runs: by entity its sync points planned, the watched components it
+ * had before the run, none for one born in it, with their values then, and those its adds gave a value; and the
+ * resources its systems write or reduce into, with their values before it.
+ */
+export type Recording = {
+    readonly before: Map<number, { readonly ids: readonly number[] | null; readonly values: ReadonlyMap<number, unknown> }>;
+    readonly given: Map<number, Set<number>>;
+    readonly resources: ReadonlyMap<Key, unknown>;
+};
+
+/** Every component but derived ones and the objects a joined thread fills, as a changes finalizer watches by default. */
+const watched = (state: State, id: number): boolean => !state.derived[id] && !state.resources.has(id) && state.remote[id] === undefined;
+
+const noValues: ReadonlyMap<number, unknown> = new Map();
+
+/** The values of components `ids` of an archetype's row. */
+const valuesAt = (archetype: Archetype, ids: readonly number[], row: number): ReadonlyMap<number, unknown> => {
+    const values = new Map<number, unknown>();
+    for (const id of ids) {
+        const storage = archetype.storageById[id];
+        if (storage !== undefined) values.set(id, readCell(storage, row));
+    }
+    return values;
+};
+
+/** Starts recording a run whose systems write or reduce into `resources`, from their values now. */
+export const startRecording = (state: State, resources: Iterable<Key>): Recording => {
+    const values = new Map<Key, unknown>();
+    for (const key of resources) {
+        const cell = findResource(state, key);
+        values.set(key, cell === undefined ? initialOf(state, key) : readCell(cell.storage, cell.row));
+    }
+    return { before: new Map(), given: new Map(), resources: values };
+};
+
+/**
+ * At a sync point of the run, before it applies: each entity its plan names that no earlier one did, with what it has
+ * now, and the components its adds give a value. `born` holds the rows committed from batches here, by archetype.
+ */
+export const recordPlan = (state: State, recording: Recording, queued: readonly Queued[], born: ReadonlyMap<number, number>): void => {
+    const { plan, archetypes, entities } = state;
+    const note = (entity: number, from: Archetype | null): void => {
+        if (recording.before.has(entity) || from?.resource === true) return;
+        if (from === null) {
+            recording.before.set(entity, { ids: null, values: noValues });
+            return;
+        }
+        const row = entities.row[indexOf(entity)];
+        const ids = from.components.filter(id => watched(state, id));
+        recording.before.set(entity, { ids, values: valuesAt(from, ids, row) });
+    };
+    const give = (entity: number, buffer: number, start: number, end: number): void => {
+        const { ids } = queued[buffer].buffer;
+        for (let k = start; k < end; k++) {
+            if (!watched(state, ids[k])) continue;
+            let given = recording.given.get(entity);
+            if (given === undefined) recording.given.set(entity, given = new Set());
+            given.add(ids[k]);
+        }
+    };
+    for (let entry = 0; entry < plan.count; entry++) {
+        const entity = plan.entity[entry];
+        const fromId = plan.from[entry];
+        const first = fromId < 0 ? undefined : born.get(fromId);
+        note(entity, fromId < 0 || (first !== undefined && entities.row[indexOf(entity)] >= first) ? null : archetypes[fromId]);
+        if (plan.start[entry] < 0) continue;
+        give(entity, plan.buffer[entry], plan.start[entry], plan.end[entry]);
+        const more = plan.more.size === 0 ? undefined : plan.more.get(entry);
+        if (more !== undefined) for (let r = 0; r < more.length; r += 3) give(entity, more[r], more[r + 1], more[r + 2]);
+    }
+    // Rows committed from batches no command touched have no entry.
+    for (const [id, first] of born) {
+        const archetype = archetypes[id];
+        for (let row = first; row < archetype.count; row++) note(archetype.entities[row], null);
+    }
+};
+
+/** A watched component's newest key: watched components are registered and not derived, so they're essential. */
+const keyOf = (state: State, id: number): Essential => newestKeyOf(state.keys[id]) as Essential;
+
+/** A group of a change set, as it's built. */
+type Grouped = { from: Essential[] | null; to: Essential[] | null; added: Essential[]; removed: Essential[]; replaced: Essential[]; entities: Entity[] };
+
+/**
+ * The run's change set once its last sync point applied: each entity grouped by the watched components it had before
+ * the run and has after, those it gained and lost, and those adds gave a value it had before and after, with their
+ * values then and now; and each resource its systems write or reduce into whose value changed.
+ */
+export const changesOf = (state: State, recording: Recording): ChangeSet<Essential, Resource.Key> => {
+    const { archetypes, entities } = state;
+    const groups = new Map<string, Grouped>();
+    const after = new Map<number, ReadonlyMap<number, unknown>>();
+    for (const [entity, { ids: before }] of recording.before) {
+        const index = locate(entities, entity);
+        const to = index < 0 ? null : archetypes[entities.archetype[index]];
+        const ids = to === null ? null : to.components.filter(id => watched(state, id));
+        if (before === null && ids === null) continue;
+        const added = (ids ?? []).filter(id => !(before ?? []).includes(id));
+        const removed = (before ?? []).filter(id => !(ids ?? []).includes(id));
+        const replaced = [...recording.given.get(entity) ?? []].filter(id => before?.includes(id) === true && ids?.includes(id) === true).sort((a, b) => a - b);
+        if (added.length === 0 && removed.length === 0 && replaced.length === 0) continue;
+        if (to !== null && ids !== null) {
+            after.set(entity, valuesAt(to, ids, entities.row[index]));
+        }
+        const name = `${before?.join(",") ?? "-"}|${ids?.join(",") ?? "-"}|${replaced.join(",")}`;
+        let group = groups.get(name);
+        const keys = (list: readonly number[] | null): Essential[] | null => list === null ? null : list.map(id => keyOf(state, id));
+        if (group === undefined) {
+            groups.set(name, group = { from: keys(before), to: keys(ids), added: added.map(id => keyOf(state, id)), removed: removed.map(id => keyOf(state, id)), replaced: replaced.map(id => keyOf(state, id)), entities: [] });
+        }
+        group.entities.push(asEntity(entity));
+    }
+    const resources: { key: Resource.Key; previous: unknown; next: unknown }[] = [];
+    for (const [key, previous] of recording.resources) {
+        const cell = findResource(state, key);
+        const next = cell === undefined ? previous : readCell(cell.storage, cell.row);
+        // A key the run's systems name is a resource's.
+        if (!sameValue(previous, next)) resources.push({ key: newestKeyOf(key) as Resource.Key, previous, next });
+    }
+    const valueOf = (values: ReadonlyMap<number, unknown> | undefined, key: Essential): unknown => {
+        const id = metIdOf(state, key);
+        return id !== undefined && values?.has(id) === true ? values.get(id) : null;
+    };
+    return {
+        groups: [...groups.values()],
+        // Values read from storage match each key's registered schema, so they have its type.
+        resources: resources as ChangeSet<Essential, Resource.Key>["resources"],
+        previous: <K extends Essential>(entity: Entity, key: K) => valueOf(recording.before.get(entity)?.values, key) as ReadonlyType<K> | null,
+        next: <K extends Essential>(entity: Entity, key: K) => valueOf(after.get(entity), key) as ReadonlyType<K> | null,
+    };
+};
+
+/** A system's leaves that run in tiers, or the system itself. */
+const leavesOf = (definition: Definition): readonly Leaf[] => isLeaf(definition) ? [definition] : scheduleOf(definition).tiers.flat();
+
+/** The resources a system's leaves write or reduce into. */
+export const resourcesWrittenBy = (definition: Definition): ReadonlySet<Key> =>
+    new Set(leavesOf(definition).flatMap(leaf => [...leaf.declaration.resources?.write ?? [], ...leaf.declaration.resources?.reduce ?? []]));
+
+/** Whether a system or composite takes input, so a run's options follow it. */
+export const takesInput = (definition: Definition): boolean =>
+    isLeaf(definition) ? definition.input !== undefined : [...scheduleOf(definition).tiers.flat(), ...scheduleOf(definition).observer].some(leaf => leaf.input !== undefined);
+
+/** Whether a run's options ask for its changes. */
+export const asksForChanges = (options: unknown): boolean => typeof options === "object" && options !== null && Reflect.get(options, "changes") === true;

package/src/implementation/world/run-results.test.ts

@@ -354,6 +354,23 @@ describe("what a run gathers for tests", () => {
         expect(await runRan(world, System.create([nothing, raise]))).toEqual({ systems: 2, workers: 0, joined: 0, main: true, gpu: false });
         expect(await runRan(world, readLevel)).toEqual({ systems: 0, workers: 0, joined: 0, main: false, gpu: false });
     });
+
+    it("counts each system of a chain once, run whole or entered after a sync point that applies something", async () => {
+        await using world = createWorld({ [workers]: 0 });
+        /** Systems each after the one before, the first after `first`. */
+        const chainOf = (length: number, first: readonly System<unknown>[]): System<unknown>[] => {
+            const links: System<unknown>[] = [];
+            for (let k = 0; k < length; k++) links.push(System.create({ after: links.length === 0 ? first : links.slice(-1) }, ({ resources }) => {
+                resources[frames] = k;
+            }));
+            return links;
+        };
+        expect(await runRan(world, System.create(chainOf(64, [])))).toEqual({ systems: 64, workers: 0, joined: 0, main: true, gpu: false });
+        const reads = System.create({ after: [spawn], components: { with: [amount] } }, row => {
+            counted += row[amount];
+        });
+        expect(await runRan(world, System.create([spawn, reads, ...chainOf(8, [reads])]))).toEqual({ systems: 10, workers: 0, joined: 0, main: true, gpu: false });
+    });
 });
 
 describe("a value a body returned", () => {

package/src/implementation/world/runner.ts

@@ -63,7 +63,7 @@ const noIndexParameters: readonly number[] = [];
 const noAddresses: readonly number[] = [];
 
 /** An archetype's change filters for a runner, and the WASM addresses of its columns and filters (`filterCache`). */
-type Filtered = { readonly version: number; readonly filters: readonly Filter[]; addresses: readonly number[]; addressed: WasmKernel | null };
+type Filtered = { readonly archetype: Archetype; readonly version: number; readonly filters: readonly Filter[]; addresses: readonly number[]; addressed: WasmKernel | null };
 
 /**
  * Runs one leaf system. Each run takes a new tick, which becomes the system's `lastRun`. `start` does main-thread work
@@ -470,7 +470,7 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
 
     /** Drops match `m`, its last taking its place; with `where`, one evaluated stays among those evaluated. */
     const removeMatch = (m: number): void => {
-        filterCache.delete(matches[m]);
+        filterCache[matches[m].id] = undefined;
         matchOf[matches[m].id] = -1;
         let hole = m;
         if (where !== null && m < where.evaluated) {
@@ -487,7 +487,7 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
     /** Matches `m` anew, reused for other values: its point is its last run's, and `where` evaluates it again. */
     const renewMatch = (m: number): void => {
         const archetype = matches[m];
-        filterCache.delete(archetype);
+        filterCache[archetype.id] = undefined;
         points[m] = lastRun;
         generations[m] = archetype.generation;
         if (where !== null && m < where.evaluated) {
@@ -563,12 +563,12 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
      * and the WASM addresses of its columns and filters, for the WASM kernel `addressed` they were taken for, since a
      * kernel loaded again may stamp a tick column the last one muted.
      */
-    const filterCache = new Map<Archetype, Filtered>();
+    const filterCache: (Filtered | undefined)[] = [];
     const noFilters: readonly Filter[] = [];
 
     const filteredOf = (archetype: Archetype) => {
-        const cached = filterCache.get(archetype);
-        if (cached !== undefined && cached.version === archetype.version) return cached;
+        const cached = filterCache[archetype.id];
+        if (cached !== undefined && cached.archetype === archetype && cached.version === archetype.version) return cached;
         const filters = addedIds.length + changedIds.length === 0 ? noFilters : [
             ...addedIds.flatMap(id => {
                 const storage = archetype.storageById[id];
@@ -579,8 +579,8 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
                 return storage === undefined ? [] : [{ ticks: storage.changed, chunks: storage.chunkChanged, blocks: storage.blockChanged }];
             }),
         ];
-        const entry: Filtered = { version: archetype.version, filters, addresses: noAddresses, addressed: null };
-        filterCache.set(archetype, entry);
+        const entry: Filtered = { archetype, version: archetype.version, filters, addresses: noAddresses, addressed: null };
+        filterCache[archetype.id] = entry;
         return entry;
     };
 
@@ -614,13 +614,14 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
         const { value } = row;
         const values = context.value;
         const input = runInput;
+        const { body } = system;
         const filters = filtersOf(archetype);
         // Every row passes, so nothing is filtered.
         // A body may remove its own system, after which no row of it runs.
         if (since < 0 || filters.length === 0) {
             for (let index = 0, count = archetype.count; index < count && !holdings.removed; index++) {
                 row.index = index;
-                const returned = system.body(value, values, input);
+                const returned = body(value, values, input);
                 if (returned !== undefined) noPromise(returned);
             }
             return;
@@ -628,7 +629,7 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
         forEachPassingRange(filters, since, 0, archetype.count, (start, end) => {
             for (let index = start; index < end && !holdings.removed; index++) {
                 row.index = index;
-                const returned = system.body(value, values, input);
+                const returned = body(value, values, input);
                 if (returned !== undefined) noPromise(returned);
             }
         });
@@ -714,10 +715,11 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
         const upContext = context.value;
         const input = runInput;
         upContext.up = parentRow === null ? null : parentRow.value;
+        const { body } = system;
         for (let n = start; n < end && !holdings.removed; n++) {
             row.index = rows[n];
             if (parentRow !== null) parentRow.index = parents[n];
-            const returned = system.body(row.value, upContext, input);
+            const returned = body(row.value, upContext, input);
             if (returned !== undefined) noPromise(returned);
         }
     };
@@ -748,9 +750,10 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
             }
             const row = bindRow(archetype);
             const { value } = row;
+            const { body } = system;
             for (let n = run.start; n < run.end && !holdings.removed; n++) {
                 row.index = run.rows[n];
-                const returned = system.body(value, contextValue, input);
+                const returned = body(value, contextValue, input);
                 if (returned !== undefined) noPromise(returned);
             }
         }
@@ -762,6 +765,7 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
         const { entries, stride, words, lengths, blocks } = sorted;
         const contextValue = context.value;
         const input = runInput;
+        const { body } = system;
         let current = -1;
         let row: ReturnType<typeof bindRow> | null = null;
         let value: object | null = null;
@@ -782,7 +786,7 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
                     current = owner;
                 }
                 row.index = entries[at + 2];
-                const returned = system.body(value, contextValue, input);
+                const returned = body(value, contextValue, input);
                 if (returned !== undefined) noPromise(returned);
             }
         }

package/src/implementation/world/schedule.test.ts

@@ -8,17 +8,25 @@ import { scheduleOf } from "../../interface/registry/schedule.js";
 
 const value = Symbol("scheduleTest/value");
 const other = Symbol("scheduleTest/other");
+const voxel = Symbol("scheduleTest/voxel");
+const mark = Symbol("scheduleTest/mark");
+const size = Symbol("scheduleTest/size");
 
 declare module "@adobe/ecs" {
     export interface Components {
         [value]: { type: number };
         [other]: { type: number };
+        [voxel]: { type: true };
+        [mark]: { type: true };
+    }
+    export interface Resources {
+        [size]: { type: number };
     }
 }
 
 
 /** Systems built as values, not registered, so each test's are its own. */
-const leaf = (declaration: Resolved & { readonly name: string }): Leaf => ({ kind: "system", name: declaration.name, declaration, input: undefined, body: () => {} });
+const leaf = (declaration: Resolved & { readonly name: string }): Leaf => ({ kind: "system", name: declaration.name, declaration, input: undefined, body: () => {}, commands: () => undefined });
 const composite = (declaration: Composite["declaration"] & { readonly name: string }): Composite => ({ kind: "composite", name: declaration.name, declaration });
 
 const names = (system: Definition): string[][] => scheduleOf(system).tiers.map(tier => tier.map(leaf => leaf.name));
@@ -113,6 +121,39 @@ describe("scheduleOf", () => {
             .toEqual([["a", "c"], ["b"]]);
     });
 
+    it("doesn't order two systems on a key both reach through rows that never match one entity", () => {
+        const voxels = leaf({ name: "voxels", components: { write: [value], has: [voxel], not: [mark] } });
+        const marks = leaf({ name: "marks", components: { write: [value], has: [mark] } });
+        const watching = leaf({ name: "watching", components: { read: [value], changed: [value], has: [mark] } });
+        expect(names(composite({ name: "root", systems: [voxels, marks] }))).toEqual([["voxels", "marks"]]);
+        expect(names(composite({ name: "root", systems: [voxels, watching] }))).toEqual([["voxels", "watching"]]);
+    });
+    it("orders two systems whose rows may match one entity, or that reach the key other than through their rows", () => {
+        const voxels = leaf({ name: "voxels", components: { write: [value], has: [voxel] } });
+        const marks = leaf({ name: "marks", components: { write: [value], has: [mark] } });
+        expect(() => scheduleOf(composite({ name: "root", systems: [voxels, marks] })))
+            .toThrow(`Systems "voxels" and "marks" both access "scheduleTest/value" and one writes it; order them with before or after, or, if they never match one entity, add a component of one to the other's not.`);
+        const apart = leaf({ name: "apart", components: { write: [value], has: [voxel], not: [mark] } });
+        const looking = leaf({ name: "looking", components: { has: [mark] }, lookup: { others: { read: [value] } } });
+        expect(() => scheduleOf(composite({ name: "root", systems: [apart, looking] })))
+            .toThrow(`Systems "apart" and "looking" both access "scheduleTest/value" and one writes it; order them with before or after.`);
+        // An optional component is read where an entity has it, so it excludes nothing it doesn't require.
+        const optional = leaf({ name: "optional", components: { read: [value, mark], optional: [mark] } });
+        expect(() => scheduleOf(composite({ name: "root", systems: [apart, optional] }))).toThrow('"apart" and "optional"');
+    });
+
+    it("orders a system before or after every other that uses a resource it lists, but those already ordered and those listing it too", () => {
+        const resize = leaf({ name: "resize", resources: { write: [size] }, before: [size] });
+        const frame = leaf({ name: "frame", resources: { read: [size] } });
+        const pick = leaf({ name: "pick", components: { read: [value] }, resources: { is: [size] } });
+        const old = leaf({ name: "old", resources: { read: [size] }, before: [resize] });
+        expect(names(composite({ name: "root", systems: [frame, pick, resize, old] }))).toEqual([["old"], ["resize"], ["frame", "pick"]]);
+        const last = leaf({ name: "last", resources: { read: [size] }, after: [size] });
+        expect(names(composite({ name: "root", systems: [last, frame, resize] }))).toEqual([["resize"], ["frame"], ["last"]]);
+        const again = leaf({ name: "again", resources: { write: [size] }, before: [size] });
+        expect(() => scheduleOf(composite({ name: "root", systems: [resize, again, frame] }))).toThrow(`Systems "resize" and "again" both access "scheduleTest/size"`);
+    });
+
     it("schedules two systems of one name as two, and one listed twice as one", () => {
         const a = leaf({ name: "a", components: { write: [value] } });
         const copy = leaf({ name: "a", components: { write: [value] }, after: [a] });

package/src/implementation/world/shared.test.ts

@@ -195,10 +195,10 @@ describe("a shared component", () => {
         }));
         expect(looked.sort()).toEqual(["1 sees red", "2 sees red"]);
         const assign: (row: object) => void = row => { Reflect.set(row, team, "blue"); };
-        const assigning = System.create({ kernel: false, components: { with: [team, health] } }, row => {
+        // Taken whole, the row is written: every member but shared ones and references.
+        const assigning = System.create({ kernel: false, components: { with: [team, health], whole: true } }, row => {
             if (row[health] === 1) assign(row);
         });
-        // The build takes the row as written whole, since it can't follow it: every member but shared ones and references.
         expect((await runReported(world, assigning)).failures.map(failure => failure.message)).toEqual([
             expect.stringContaining(`"sharedTest/team" is shared: its value is its archetype's, so give it another with commands.add rather than assigning it`),
         ]);

package/src/implementation/world/state.ts

@@ -1,4 +1,5 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Recording } from './run-changes.js';
 import { createHolds, type Holds } from './stop-lists.js';
 import type { Entity } from '../../interface/entity/entity.js';
 import type { Leaf } from '../../interface/system/leaf.js';
@@ -77,6 +78,14 @@ export const countRan = (state: State, runners: readonly RanRunner[]): void => {
     for (let k = 0; k < tier.logs.length; k++) ran.joined.add(tier.logs[k]);
 };
 
+/** Counts runners into `ran` that all ran here, none on a joined thread: on `main` unless a joined thread claims it. */
+export const countRanHere = (state: State, systems: number, gpu: boolean): void => {
+    const { ran } = state;
+    ran.systems += systems;
+    if (systems !== 0 && state.claims.get("main") === undefined) ran.main = true;
+    if (gpu) ran.gpu = true;
+};
+
 /** Starts gathering what a run ran. */
 export const startRan = (ran: Ran): void => {
     ran.systems = 0;
@@ -126,6 +135,13 @@ export type State = {
     reshapes: number;
     /** Sync points applied, which reclaiming counts. */
     syncs: number;
+    /**
+     * By id, each resource a changes finalizer watches: its value and change tick when its finalizers last ran, which a
+     * later write's report gives as its previous value. Empty while none watches one.
+     */
+    readonly resourcesSeen: Map<number, { value: unknown; tick: number }>;
+    /** What the run in progress records of its changes, when it was asked for them; null otherwise. */
+    recording: Recording | null;
     /** The records strings' columns name, in shared memory; null without it, where strings are held as objects. */
     readonly strings: StringStore | null;
     /** Whether each component is derived, so only rules add and remove it. */
@@ -317,6 +333,8 @@ export const createState = (shared?: boolean, wasm = true, simd = true, gpu = fa
         membership: { log: [], base: 0 },
         reshapes: 0,
         syncs: 0,
+        resourcesSeen: new Map(),
+        recording: null,
         strings: memory.shared ? createStrings(memory) : null,
         derived: [],
         transfers: [],
@@ -504,6 +522,15 @@ export const commandIdOf = (state: State, key: unknown): number => {
     return id;
 };
 
+/** The id of a component a query names, derived ones included. Throws for a key that isn't a registered component. */
+export const queryIdOf = (state: State, key: unknown): number => {
+    const known = typeof key === "symbol" ? state.ids.get(key) : undefined;
+    if (known !== undefined && !state.resources.has(known)) return known;
+    if (typeof key !== "symbol") throw new Error(`"${labelOf(key)}" isn't a component: a component's key is a symbol.`);
+    if (kindOf(key) === "resource") throw new Error(`"${labelOf(key)}" is a resource, not a component.`);
+    return idOf(state, key);
+};
+
 /**
  * An archetype's key: its sorted component ids, each shared one with the number of its value, so archetypes of one
  * component set but other values are others.

package/src/implementation/world/sync-points.test.ts

@@ -0,0 +1,147 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import { Entity } from "../../interface/entity/entity.js";
+import { Index } from "../../interface/indexes/index-type.js";
+import { System } from "../../interface/system/system.js";
+import { workers } from "../../interface/resources/workers.js";
+import { createWorld } from "./create.js";
+import { count as countOf, readEach, select } from "./reads.test-helper.js";
+
+const position = Symbol("syncPointsTest/position");
+const cell = Symbol("syncPointsTest/cell");
+const found = Symbol("syncPointsTest/found");
+const team = Symbol("syncPointsTest/team");
+const member = Symbol("syncPointsTest/member");
+const local = Symbol("syncPointsTest/local");
+const total = Symbol("syncPointsTest/total");
+const parent = Symbol("syncPointsTest/parent");
+const seed = Symbol("syncPointsTest/seed");
+const grown = Symbol("syncPointsTest/grown");
+const children = Symbol("syncPointsTest/children");
+
+declare module "@adobe/ecs" {
+    export interface Components {
+        [position]: { type: number };
+        [cell]: { type: number };
+        [team]: { type: true };
+        [member]: { type: Entity; reference: "owner" };
+        [local]: { type: number };
+        [total]: { type: number };
+        [parent]: { type: Entity; reference: "weak" };
+        [seed]: { type: number };
+        [grown]: { type: number };
+    }
+    export interface Resources {
+        [found]: { type: number };
+        [children]: { type: number; default: 0 };
+    }
+}
+
+const byCell = Index.create({ key: [cell] });
+
+const spawn = System.create(({ commands }) => { for (let k = 0; k < 3; k++) commands.spawn([position])({ [position]: k }); });
+const counted: number[] = [];
+const count = System.create({ components: { with: [position] }, after: [spawn] }, row => { counted.push(row[position]); });
+const changes: number[] = [];
+const watchChanges = System.create({ components: { with: [position], changed: [position] }, after: [count] }, row => { changes.push(row[position]); });
+const deriveCells = System.create({ components: { with: [position], not: [cell] }, after: [watchChanges] }, (row, { commands }) => { commands.add(row.entity, cell, row[position] % 2); });
+const pick = System.create({ lookup: { cells: { index: byCell } }, after: [deriveCells] }, ({ lookup, resources }) => { resources[found] = lookup.cells(0).length; });
+const readFound = System.create({ readonly: true }, ({ resources }) => resources[found]);
+const frame = System.create([spawn, count, watchChanges, deriveCells, pick]);
+
+const spawnTeams = System.create(({ commands }) => {
+    for (let k = 0; k < 3; k++) {
+        const owner = commands.spawn([team])();
+        for (let m = 0; m < 2; m++) commands.spawn([member])({ [member]: owner });
+    }
+});
+const disband = System.create({ components: { with: [team] }, after: [spawnTeams] }, (row, { commands }) => { commands.despawn(row.entity); });
+const round = System.create([spawnTeams, disband]);
+
+/** Spawns a root, `count` children of it and a child of each. */
+const spawnTree = System.create({}, ({ commands }, input: { readonly count: number }) => {
+    const root = commands.spawn([local, total])({ [local]: 1, [total]: 0 });
+    for (let k = 0; k < input.count; k++) {
+        const child = commands.spawn([local, total, parent])({ [local]: 1, [total]: 0, [parent]: root });
+        commands.spawn([local, total, parent])({ [local]: 1, [total]: 0, [parent]: child });
+    }
+});
+const propagate = System.create({ components: { with: [local, total], changed: [local] }, up: { through: parent }, after: [spawnTree] }, (row, { up }) => {
+    row[total] = (up === null ? 0 : up[total]) + row[local];
+});
+const grow = System.create([spawnTree, propagate]);
+
+const plant = System.create(({ commands }) => { for (let k = 0; k < 64; k++) commands.spawn([seed])({ [seed]: k }); });
+const sprout = System.create({ kernel: true, components: { with: [seed] }, after: [plant] }, (row, { commands }) => {
+    commands.spawn([grown])({ [grown]: row[seed] * 2 });
+});
+const tally = System.create({ components: { with: [grown] }, after: [sprout] }, (row, { resources }) => { resources[children] += row[grown]; });
+const garden = System.create([plant, sprout, tally]);
+const readChildren = System.create({ readonly: true }, ({ resources }) => resources[children]);
+
+const spawnSeedlings = System.create(({ commands }) => { commands.spawn(Seedling)({ [seed]: 1, [grown]: 2 }); });
+const countSeedlings = System.create({ components: { with: [seed, grown] }, after: [spawnSeedlings] }, (row, { resources }) => { resources[children] += row[grown]; });
+/** Declared below the systems whose commands name it. */
+const Seedling = [seed, grown] as const;
+
+describe("sync points within a run", () => {
+    it("apply commands before a later system that depends on what they change, which then sees them in the same run", async () => {
+        const world = createWorld({ [workers]: 0 });
+        await world.run(frame);
+        expect(counted).toEqual([0, 1, 2]);
+        expect(await world.run(readFound)).toBe(2);
+        await world.dispose();
+    });
+    it("keep each change seen once by change filters across runs", async () => {
+        const world = createWorld({ [workers]: 0 });
+        changes.length = 0;
+        await world.run(frame);
+        expect(changes).toEqual([0, 1, 2]);
+        changes.length = 0;
+        counted.length = 0;
+        await world.run(frame);
+        // The second run's spawns are new; the first run's three are seen again by count alone.
+        expect([counted.length, changes]).toEqual([6, [0, 1, 2]]);
+        expect(await world.run(readFound)).toBe(4);
+        await world.dispose();
+    });
+
+    it("despawn what rows spawned at an earlier sync point of the run own, once a later tier despawns their owners", async () => {
+        expect(System.describe(round).tiers.map(tier => tier.sync === null)).toEqual([false, true]);
+        await using world = createWorld({ [workers]: 0 });
+        await world.run(round);
+        expect([await countOf(world, { required: [team] }), await countOf(world, { required: [member] })]).toEqual([0, 0]);
+    });
+
+    it("bring an `up` tree up to date at each, built again or patched, for a tier after it in the same run", async () => {
+        expect(System.describe(grow).tiers.map(tier => tier.sync === null)).toEqual([false, true]);
+        await using world = createWorld({ [workers]: 0 });
+        let spawned = 0;
+        // Past the journal's worth a tree patches, then within it.
+        for (const count of [5_000, 3_000, 10]) {
+            await world.run(grow, { count });
+            spawned += count;
+            const totals = await readEach(world, await select(world, { required: [total] }), total);
+            const byDepth = [1, 2, 3].map(depth => totals.filter(value => value === depth).length);
+            expect([byDepth, totals.length]).toEqual([[totals.length - 2 * spawned, spawned, spawned], totals.length]);
+        }
+    });
+
+    it("follow commands naming an archetype declared below their system", async () => {
+        expect(System.describe(System.create([spawnSeedlings, countSeedlings])).tiers.map(tier => tier.sync?.map(reason => reason.keys) ?? null)).toEqual([[[seed, grown]], null]);
+        await using world = createWorld({ [workers]: 0 });
+        await world.run(System.create([spawnSeedlings, countSeedlings]));
+        expect(await world.run(readChildren)).toBe(2);
+    });
+
+    it("commit a kernel's staged spawns at a sync point within the run, for a later tier", async () => {
+        expect(System.describe(garden).tiers.map(tier => tier.sync === null)).toEqual([false, false, true]);
+        await using world = createWorld({ [workers]: 0 });
+        const sum = 63 * 64;
+        await world.run(garden);
+        expect(await world.run(readChildren)).toBe(sum);
+        // The second run's seeds are both runs' plantings, and its tally reads the first run's grown rows too.
+        await world.run(garden);
+        expect(await world.run(readChildren)).toBe(sum + sum + 2 * sum);
+    });
+});