@adobe/ecs 0.0.0-stage → 0.2.0

package/src/perftest/invariants.ts

@@ -0,0 +1,63 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { clock } from "../interface/resources/clock.js";
+import { workers } from "../interface/resources/workers.js";
+import { System } from "../interface/system/system.js";
+import { createWorld } from "../implementation/index.js";
+import type { Benchmark } from "./benchmark.js";
+import { fastest } from "./suite.js";
+
+// Kernels taking remainders: of a value the same for every row, from resources, and of a number column in every row,
+// against the same kernel without them.
+
+const level = Symbol("invariants/level");
+const step = Symbol("invariants/step");
+declare module "@adobe/ecs" {
+    export interface Components {
+        [level]: { type: number };
+        [step]: { type: number };
+    }
+}
+
+const rows = 10_000;
+
+const seed = System.create({}, ({ commands }) => {
+    for (let i = 0; i < rows; i++) commands.spawn([level, step])({ [level]: 0, [step]: i % 3 });
+});
+
+/** Raises each row by its step. */
+const raise = System.create({ kernel: true, components: { with: [level, step] } }, row => {
+    row[level] += row[step];
+});
+/** Raises each row by its step on even ticks: a remainder of a resource, the same for every row. */
+const raiseOnEvenTicks = System.create({ kernel: true, components: { with: [level, step] } }, (row, { resources }) => {
+    if (resources[clock].tick % 2 === 0) row[level] += row[step];
+});
+
+/** Wraps each row's level at 1,000 after its step: a remainder of a number column, an integer in every row. */
+const wrap = System.create({ kernel: true, components: { with: [level, step] } }, row => {
+    row[level] = (row[level] + row[step]) % 1000;
+});
+
+const run = async (system: System<void>): Promise<number> => {
+    const world = createWorld({ [workers]: 0 });
+    await world.run(seed);
+    const best = await fastest(() => world.run(system));
+    await world.dispose();
+    return best;
+};
+
+const benchmark = (name: string, operation: string, system: System<void>): Benchmark => ({
+    name,
+    operation,
+    per: "rows",
+    n: rows,
+    typical: [1_000, 100_000],
+    best: { bytes: 24, basis: "Each row reads its 8-byte step and reads and writes its 8-byte level." },
+    run: () => run(system),
+});
+
+export const invariantBenchmarks: readonly Benchmark[] = [
+    benchmark("raise 10K", "A kernel adding one number column to another over 10K rows, as `raise on even ticks 10K` does on even ticks.", raise),
+    benchmark("wrap 10K", "`raise 10K` wrapping each level at 1,000: a remainder of a number column by a literal in every row, an integer there.", wrap),
+    benchmark("raise on even ticks 10K", "`raise 10K` under a test of the clock's tick `% 2`: a value of resources the same for every row, computed once a call.", raiseOnEvenTicks),
+];

package/src/perftest/joined.ts

@@ -0,0 +1,103 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+/// <reference types="node" />
+import type { MessagePort as NodeMessagePort } from "node:worker_threads";
+import { join } from "../implementation/index.js";
+import { scopeChannel } from "../implementation/world/port.js";
+import type { World } from "../interface/world/world.js";
+import { counter, empty, order, remoteRuns, observerAmounts, observerCaptions, observerCounter, observerSeen, observerSelect, type FromJoined, type ToJoined } from "./remote.js";
+import { handoffSystems } from "./handoff.js";
+import { release } from "./finalized.js";
+import { tailSystems } from "./tails.js";
+import { take, transferBatch, transferBytes, transferCount, transferSystems } from "./transfers.js";
+import { peersOf } from "../implementation/world/join.js";
+import { Observe } from "../observe/index.js";
+import { programFinalizers, requireDefinition } from "../interface/registry/index.js";
+
+/**
+ * A thread joined to a benchmark's world: it times runs, or reads after each sync point until asked to stop, or claims
+ * the thread the handoff benchmarks' systems run on, the one the despawn objects benchmark's finalizer runs on, or the
+ * one the tail benchmarks' tails run on.
+ */
+type Message = ToJoined
+    | { readonly kind: "port"; readonly port: MessagePort | NodeMessagePort; readonly threads?: readonly ("handoffBenchmark" | "finalizedBenchmark" | "tailsBenchmark" | "transfersBenchmark")[] }
+    | { readonly kind: "transfers"; readonly side: number; readonly fastestOf: number };
+
+const channel = scopeChannel<FromJoined | { readonly kind: "joined" } | { readonly kind: "transferred"; readonly milliseconds: number }, Message>();
+let remote: World | null = null;
+let stop: (() => void) | null = null;
+let last = 0;
+let notified = 0;
+
+channel.onMessage(async message => {
+    if (message.kind === "port") {
+        // The systems the handoff benchmarks place on the thread it claims, which it imports so it runs them.
+        if (message.threads !== undefined) for (const system of [...handoffSystems, ...tailSystems, ...transferSystems]) requireDefinition(system);
+        // The finalizer the despawn benchmark places there, which importing its module declared.
+        if (!programFinalizers().some(finalizer => finalizer === release)) throw new Error("joined: the despawn objects benchmark's finalizer isn't declared here.");
+        remote = await join(message.port, { threads: message.threads ?? [] });
+        channel.post({ kind: "joined" });
+        return;
+    }
+    if (remote === null) return;
+    if (message.kind === "transfers") {
+        // The loader moves each run's values straight to the claimed thread once the world gave it a channel there.
+        const world = remote;
+        while ((peersOf.get(world)?.() ?? 0) === 0) await new Promise(resolve => setTimeout(resolve, 1));
+        const pixels = new ImageData(message.side, message.side);
+        const batch = async () => {
+            const assets = await Promise.all(Array.from({ length: transferBatch }, async () => ({ buffer: new ArrayBuffer(transferBytes), bitmap: await createImageBitmap(pixels) })));
+            const start = performance.now();
+            await Promise.all(assets.map(asset => world.run(take, asset)));
+            return performance.now() - start;
+        };
+        await batch();
+        const batches = transferCount / transferBatch;
+        let milliseconds = 0;
+        // Every batch's time, or the fastest of `fastestOf` batches for as many transfers.
+        if (message.fastestOf === 0) for (let k = 0; k < batches; k++) milliseconds += await batch();
+        else {
+            let fastest = Infinity;
+            for (let k = 0; k < message.fastestOf; k++) fastest = Math.min(fastest, await batch());
+            milliseconds = fastest * batches;
+        }
+        channel.post({ kind: "transferred", milliseconds });
+        return;
+    }
+    if (message.kind === "runs") {
+        for (let k = 0; k < 100; k++) await remote.run(empty);
+        let best = Infinity;
+        for (let stretch = 0; stretch < message.stretches; stretch++) {
+            const start = performance.now();
+            for (let k = 0; k < remoteRuns; k++) await remote.run(empty);
+            best = Math.min(best, performance.now() - start);
+        }
+        channel.post({ kind: "ran", milliseconds: best });
+        return;
+    }
+    if (message.kind === "stop") {
+        stop?.();
+        channel.post({ kind: "stopped", last: Math.max(last, observerSeen.last), notified: notified + observerSeen.notified });
+        return;
+    }
+    if (message.kind === "observer resource" || message.kind === "observer select" || message.kind === "observer captions" || message.kind === "observer amounts") {
+        // An observer system of this thread's own, which the world posts here after each sync point.
+        const system = message.kind === "observer resource" ? observerCounter : message.kind === "observer select" ? observerSelect
+            : message.kind === "observer captions" ? observerCaptions : observerAmounts;
+        const world = remote;
+        world.add(system);
+        stop = () => world.remove(system);
+        channel.post({ kind: "observing" });
+        return;
+    }
+    let first = true;
+    const observing = (value: unknown): void => {
+        notified++;
+        last = typeof value === "number" ? value : Array.isArray(value) ? value.length : -1;
+        if (!first) return;
+        first = false;
+        channel.post({ kind: "observing" });
+    };
+    stop = message.kind === "factory resource"
+        ? Observe.resource(remote, counter)(observing)
+        : Observe.select(remote, { required: [order], order: { [order]: true } })(observing);
+});

package/src/perftest/journal.ts

@@ -0,0 +1,55 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { workers } from "../interface/resources/workers.js";
+import { System } from "../interface/system/system.js";
+import { createWorld } from "../implementation/index.js";
+import type { Benchmark } from "./benchmark.js";
+import { forest, local, propagateChanged } from "./hierarchy.js";
+
+// Frames of a filtered `up` over 4K rows while a few hundred of them move archetype each frame: the journal of what
+// sync points changed fills every few frames, and what it keeps decides whether the tree patches or builds again.
+
+const flag = Symbol("journal/flag");
+declare module "@adobe/ecs" {
+    export interface Components {
+        [flag]: { type: true };
+    }
+}
+
+const moved = 250;
+const frames = 64;
+
+/** Flags `moved` rows, or unflags them, from `start` on in storage order. */
+const toggle = System.create({ kernel: false, components: { with: [local] } }, (row, { commands }, input: { readonly start: number; readonly on: boolean }) => {
+    const at = row.entity % 4_096;
+    if (at < input.start || at >= input.start + moved) return;
+    if (input.on) commands.add(row.entity, flag, true);
+    else commands.remove(row.entity, flag);
+});
+
+export const journalBenchmarks: readonly Benchmark[] = [{
+    name: "up filtered 4K, 250 moving a frame",
+    operation: "Frames of a filtered `up` over 1K chains of 4 while 250 rows move archetype each frame, timed over 64 frames: the journal fills every few frames.",
+    per: "frames",
+    n: frames,
+    typical: [1, 1],
+    best: { bytes: moved * 64, basis: "Each moved row and its child read and write about 64 bytes of tree, order and values." },
+    run: async () => {
+        const world = createWorld({ [workers]: 0 });
+        await world.run(forest, { roots: 1_000, depth: 4 });
+        await world.run(propagateChanged);
+        let frame = 0;
+        const stretch = async (): Promise<number> => {
+            const start = performance.now();
+            for (let k = 0; k < frames; k++, frame++) {
+                await world.run(toggle, { start: (frame >> 1) % 16 * moved, on: frame % 2 === 0 });
+                await world.run(propagateChanged);
+            }
+            return performance.now() - start;
+        };
+        for (let k = 0; k < 4; k++) await stretch();
+        let best = Infinity;
+        for (let k = 0; k < 16; k++) best = Math.min(best, await stretch());
+        await world.dispose();
+        return best;
+    },
+}];

package/src/perftest/keys.ts

@@ -0,0 +1,101 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+/**
+ * A microbenchmark of reading a values object's symbol keys, as commands and spawns do: each round builds the
+ * object literal a spawn site would, then reads every key and its value. Run with `node dist/perf/run.js --keys`
+ * after `pnpm exec vite build --config vite.perf.config.ts`; it prints nanoseconds per object by method and key count.
+ */
+
+const keys: readonly symbol[] = Array.from({ length: 6 }, (_, k) => Symbol(`keys/${k}`));
+const [k0, k1, k2, k3, k4, k5] = keys;
+
+/** Each count's literal, so every object of a count has one shape, as one spawn site's do. */
+const literals: readonly ((i: number) => object)[] = [
+    i => ({ [k0]: i }),
+    i => ({ [k0]: i, [k1]: i }),
+    i => ({ [k0]: i, [k1]: i, [k2]: i }),
+    i => ({ [k0]: i, [k1]: i, [k2]: i, [k3]: i }),
+    i => ({ [k0]: i, [k1]: i, [k2]: i, [k3]: i, [k4]: i }),
+    i => ({ [k0]: i, [k1]: i, [k2]: i, [k3]: i, [k4]: i, [k5]: i }),
+];
+
+/** Reads every symbol key and value; returns a sum so nothing is optimized away. */
+type Method = (values: object) => number;
+
+const methods: readonly (readonly [string, Method])[] = [
+    // Building the literal alone, the cost every method includes.
+    ["the literal alone", () => 0],
+    ["Object.keys, then symbols", values => {
+        let sum = 0;
+        for (const key of Object.keys(values)) sum += Number(Reflect.get(values, key));
+        for (const key of Object.getOwnPropertySymbols(values)) sum += Number(Reflect.get(values, key));
+        return sum;
+    }],
+    ["Object.getOwnPropertySymbols", values => {
+        let sum = 0;
+        const found = Object.getOwnPropertySymbols(values);
+        for (let k = 0; k < found.length; k++) sum += Number(Reflect.get(values, found[k]));
+        return sum;
+    }],
+    // Not a way to read unknown keys: values read by keys known in advance, to separate listing keys from reading values.
+    ["known keys, no listing", values => {
+        let sum = 0;
+        for (let k = 0; k < keys.length; k++) {
+            const value: unknown = Reflect.get(values, keys[k]);
+            if (value !== undefined) sum += Number(value);
+        }
+        return sum;
+    }],
+    ["Reflect.ownKeys, symbols only", values => {
+        let sum = 0;
+        const found = Reflect.ownKeys(values);
+        for (let k = 0; k < found.length; k++) {
+            const key = found[k];
+            if (typeof key === "symbol") sum += Number(Reflect.get(values, key));
+        }
+        return sum;
+    }],
+];
+
+const rounds = 1_000_000;
+
+/** The fastest of several timed passes, in nanoseconds per object. */
+const time = (method: Method, literal: (i: number) => object): number => {
+    let best = Infinity;
+    let sink = 0;
+    for (let pass = 0; pass < 7; pass++) {
+        const start = performance.now();
+        for (let i = 0; i < rounds; i++) sink += method(literal(i));
+        best = Math.min(best, performance.now() - start);
+    }
+    if (sink === -1) console.log(sink);
+    return (best * 1e6) / rounds;
+};
+
+const names: readonly string[] = keys.map((_, k) => `keys/${k}`);
+const [s0, s1, s2, s3, s4, s5] = names;
+
+/** The same literals keyed by strings, for comparison with string keys read by `Object.keys`. */
+const stringLiterals: readonly ((i: number) => object)[] = [
+    i => ({ [s0]: i }),
+    i => ({ [s0]: i, [s1]: i }),
+    i => ({ [s0]: i, [s1]: i, [s2]: i }),
+    i => ({ [s0]: i, [s1]: i, [s2]: i, [s3]: i }),
+    i => ({ [s0]: i, [s1]: i, [s2]: i, [s3]: i, [s4]: i }),
+    i => ({ [s0]: i, [s1]: i, [s2]: i, [s3]: i, [s4]: i, [s5]: i }),
+];
+
+const stringKeys: Method = values => {
+    let sum = 0;
+    const found = Object.keys(values);
+    for (let k = 0; k < found.length; k++) sum += Number(Reflect.get(values, found[k]));
+    return sum;
+};
+
+/** Prints one line per method: nanoseconds per object for 1 to 6 keys. */
+export const runKeyReading = (): void => {
+    console.log(["method".padEnd(32), ...literals.map((_, k) => `${k + 1} key${k === 0 ? "" : "s"}`.padStart(8))].join(""));
+    for (const [name, method] of methods) {
+        console.log([name.padEnd(32), ...literals.map(literal => `${time(method, literal).toFixed(1)}`.padStart(8))].join(""));
+    }
+    console.log(["string keys, Object.keys".padEnd(32), ...stringLiterals.map(literal => `${time(stringKeys, literal).toFixed(1)}`.padStart(8))].join(""));
+};

package/src/perftest/log.ts

@@ -0,0 +1,126 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { createBuffer } from "../implementation/world/buffer.js";
+import { createCommands } from "../implementation/world/commands.js";
+import { asEntity } from "../implementation/world/entities.js";
+import { cellOf, createMirror, nameComponent, rebuild, replay, type Mirror } from "../implementation/world/mirror.js";
+import { createMoveLog } from "../implementation/world/move-log.js";
+import { claimThreads } from "../implementation/world/remote.js";
+import { createState, defaultOf, idOf, type State } from "../implementation/world/state.js";
+import { synchronize } from "../implementation/world/synchronize.js";
+import type { Benchmark } from "./benchmark.js";
+
+// A joined thread's object columns following the world's rows: replaying the move log, and rebuilding from the layout
+// directory once it lapped. The world and the thread's mirror are on this thread, the mirror timed alone.
+
+const serial = Symbol("log/serial");
+const label = Symbol("log/label");
+const moved = Symbol("log/moved");
+declare module "@adobe/ecs" {
+    export interface Threads {
+        logBenchmark: true;
+    }
+    export interface Components {
+        [serial]: { type: number };
+        [label]: { type: Label; thread: "logBenchmark" };
+        [moved]: { type: true };
+    }
+}
+const none = { text: "none" } as const;
+/** A row's label, which starts as `none`, so the mirror's copies are told apart by identity. */
+type Label = { readonly text: string } | null;
+const Label = { default: none };
+
+/** Entities moved, and swapped out of the rows they leave, per sync point of `log replay`. */
+export const replayMoves = 10_000;
+/** Rows `log rebuild 100K` rebuilds. */
+export const rebuildRows = 100_000;
+
+/** A world whose "logBenchmark" objects a mirror on this thread fills, with `count` entities holding one each. */
+const joinedWorld = (count: number): { readonly state: State; readonly mirror: Mirror; readonly entities: readonly number[] } => {
+    const state = createState(true);
+    let mirror: Mirror | null = null;
+    const log = createMoveLog(state.memory, 1, state.starts, component => {
+        const key = state.keys[component];
+        if (mirror !== null && typeof key === "symbol") nameComponent(mirror, component, key, defaultOf);
+    });
+    mirror = createMirror(state.memory.memory, log.block, 1);
+    for (const key of [serial, label, moved]) idOf(state, key);
+    claimThreads(state, log, ["logBenchmark"]);
+    const target = { buffer: createBuffer() };
+    const commands = createCommands(state, target);
+    const entities: number[] = [];
+    for (let k = 0; k < count; k++) entities.push(commands.spawn([serial, label])({ [serial]: k }));
+    synchronize(state);
+    if (!rebuild(mirror)) throw new Error("log: the mirror didn't rebuild.");
+    return { state, mirror, entities };
+};
+
+/**
+ * The fastest of `rounds` replays of a sync point moving `replayMoves` of 20K entities to another archetype holding the
+ * thread's objects, and back the next, each move leaving a row the archetype's last swaps into.
+ */
+const logReplay = async (rounds = 40): Promise<number> => {
+    const { state, mirror, entities } = joinedWorld(2 * replayMoves);
+    const target = { buffer: createBuffer() };
+    const commands = createCommands(state, target);
+    let best = Infinity;
+    for (let round = 0; round < rounds; round++) {
+        for (let k = 0; k < replayMoves; k++) {
+            // Every other one, so the rows they leave are spread over the archetype.
+            const entity = asEntity(entities[2 * k]);
+            if (round % 2 === 0) commands.add(entity, moved);
+            else commands.remove(entity, moved);
+        }
+        state.queued.push({ buffer: target.buffer, guarded: true });
+        synchronize(state);
+        const start = performance.now();
+        const replayed = replay(mirror);
+        const time = performance.now() - start;
+        // The first sync point with the rows in place grows the ring to hold them, which a thread rebuilds after.
+        if (replayed === "lapped" && round === 0 && rebuild(mirror)) continue;
+        if (replayed !== "current") throw new Error(`log replay: the mirror's replay was ${replayed}.`);
+        if (round > 1) best = Math.min(best, time);
+        await Promise.resolve();
+    }
+    const last = state.archetypes.find(archetype => archetype.count === replayMoves * 2);
+    if (last === undefined || cellOf(mirror, last.id, 0, idOf(state, label))?.value !== none) throw new Error("log replay: the mirror doesn't hold the rows' objects.");
+    return best;
+};
+
+/** The fastest of `rounds` rebuilds of `rebuildRows` rows from the layout directory, as after the log lapped. */
+const logRebuild = async (rounds = 20): Promise<number> => {
+    const { state, mirror } = joinedWorld(rebuildRows);
+    let best = Infinity;
+    for (let round = 0; round < rounds; round++) {
+        const start = performance.now();
+        const rebuilt = rebuild(mirror);
+        const time = performance.now() - start;
+        if (!rebuilt) throw new Error("log rebuild: the mirror didn't rebuild.");
+        if (round > 1) best = Math.min(best, time);
+        await Promise.resolve();
+    }
+    const archetype = state.archetypes.find(candidate => candidate.count === rebuildRows);
+    if (archetype === undefined || cellOf(mirror, archetype.id, rebuildRows - 1, idOf(state, label))?.value !== none) throw new Error("log rebuild: the mirror doesn't hold the rows' objects.");
+    return best;
+};
+
+export const logBenchmarks: readonly Benchmark[] = [
+    {
+        name: "log replay",
+        operation: "A joined thread replaying a sync point's move log: 10K entities holding its objects moving archetype, each leaving a row the last swaps into, as when a tag on DOM-backed entities toggles.",
+        per: "moves",
+        n: replayMoves,
+        typical: [1, 10_000],
+        best: { bytes: 128, basis: "Each move copies out and reads two 16-byte entries, and copies its object, ticks and entity twice, 32 bytes read and written each." },
+        run: () => logReplay(),
+    },
+    {
+        name: "log rebuild 100K",
+        operation: "A joined thread rebuilding its object columns over 100K rows from the layout directory, as when it fell further behind than its log holds.",
+        per: "rows",
+        n: rebuildRows,
+        typical: [1_000, 100_000],
+        best: { bytes: 60, basis: "Each row reads its 8-byte entity, 4-byte tag and 16 bytes of ticks, and writes its entity, object and ticks." },
+        run: () => logRebuild(),
+    },
+];

package/src/perftest/loop.ts

@@ -0,0 +1,50 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { always } from "../interface/resources/always.js";
+import { System } from "../interface/system/system.js";
+import { backToBack, createWorld } from "../implementation/index.js";
+import { idle, unused } from "./suite.js";
+import { eachTick } from "./observer.js";
+
+/** Ticks in each timed stretch of `loopTickIdle`. */
+export const loopTicks = 10_000;
+
+/** Observer systems in `observer idle 100`. */
+export const observerIdles = 100;
+
+/** Observer systems no entity matches, each run after every tick. */
+const idleObserver = Array.from({ length: observerIdles }, (_, i) => System.create({ observer: true, components: { with: [unused] } }, () => {}));
+
+/**
+ * The fastest of `stretches` stretches of `loopTicks` ticks with nothing changed, after one to warm up: a world with
+ * `always` set, one system no entity matches and `observer` observer systems none matches, driven back to back, counted
+ * by an observer system reading its clock.
+ */
+export const loopTickIdle = async (stretches = 5, observer = 0): Promise<number> => {
+    const driver = backToBack();
+    const world = createWorld({ [always]: true }, { loop: driver });
+    let best = Infinity;
+    try {
+        await new Promise<void>(resolve => {
+            let ticks = 0;
+            let stretch = 0;
+            let start = 0;
+            const unobserve = eachTick(world, () => {
+                if (ticks++ % loopTicks !== 0) return;
+                const now = performance.now();
+                // The first stretch warms up.
+                if (stretch > 1) best = Math.min(best, now - start);
+                start = now;
+                if (stretch++ <= stretches) return;
+                unobserve();
+                resolve();
+            });
+            for (let k = 0; k < observer; k++) world.add(idleObserver[k]);
+            world.add(idle);
+        });
+    }
+    finally {
+        await world.dispose();
+        driver.close();
+    }
+    return best;
+};

package/src/perftest/observed-gpu.ts

@@ -0,0 +1,57 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Entity } from "../interface/entity/entity.js";
+import { gpuDevice } from "../interface/resources/gpu-device.js";
+import { workers } from "../interface/resources/workers.js";
+import { System } from "../interface/system/system.js";
+import { createWorld } from "../implementation/world/create.js";
+import { Observe } from "../observe/index.js";
+import type { Benchmark } from "./benchmark.js";
+import type { F32 } from "../interface/math/index.js";
+
+// An entity observer factory of values a GPU kernel writes: each run reads back what the observer reads.
+
+const heat = Symbol("observedGpu/heat");
+const rate = Symbol("observedGpu/rate");
+declare module "@adobe/ecs" {
+    export interface Components {
+        [heat]: { type: F32 };
+        [rate]: { type: F32 };
+    }
+}
+
+const heated = 100_000;
+let spawned: Entity[] = [];
+const spawn = System.create({}, ({ commands }) => {
+    spawned = [];
+    for (let i = 0; i < heated; i++) spawned.push(commands.spawn([heat, rate])({ [heat]: 0, [rate]: 1 }));
+});
+const warm = System.create({ kernel: "gpu", components: { with: [rate, heat] } }, row => {
+    row[heat] = row[heat] + row[rate];
+});
+
+/** Timed per run by `timed`, which waits for the GPU. */
+export const observedGpuBenchmarks = (device: GPUDevice, timed: (run: () => Promise<unknown>) => Promise<number>): readonly Benchmark[] => [{
+    name: "observe gpu entity factory",
+    operation: "A GPU kernel writing a value of 100K entities, one entity of which is observed through the observer factories: each run reads that storage back for it.",
+    per: "runs",
+    n: 1,
+    typical: [1, 1],
+    best: { bytes: 400_000, basis: "The readback copies the observed storage's 100K 4-byte values.", on: "gpu" },
+    run: async () => {
+        const world = createWorld({ [workers]: 0, [gpuDevice]: device });
+        try {
+            await world.run(spawn);
+            let notified = 0;
+            const stop = Observe.entity(world, spawned[0], { required: [heat] })(() => { notified++; });
+            await world.run(warm);
+            const before = notified;
+            const best = await timed(() => world.run(warm));
+            if (notified <= before) throw new Error("observe gpu entity factory: not notified");
+            stop();
+            return best;
+        }
+        finally {
+            await world.dispose();
+        }
+    },
+}];