@adobe/ecs 0.1.0 → 0.2.0

package/src/perftest/indexes.ts

@@ -1,4 +1,4 @@
-import { Component } from "../interface/component/component.js";
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { Entity } from "../interface/entity/entity.js";
 import { Index } from "../interface/indexes/index-type.js";
 import { workers } from "../interface/resources/workers.js";
@@ -7,6 +7,7 @@ import type { World } from "../interface/world/world.js";
 import { createWorld } from "../implementation/index.js";
 import type { Benchmark } from "./benchmark.js";
 import { fastest } from "./suite.js";
+import type { U32, Vec3 } from "../interface/math/index.js";
 
 // Benchmarks of indexes: keeping them current, and looking up through them.
 
@@ -19,30 +20,23 @@ const place = Symbol("indexes/place");
 const cell = Symbol("indexes/cell");
 declare module "@adobe/ecs" {
     export interface Components {
-        [key]: { type: number };
+        [key]: { type: U32 };
         [amount]: { type: number };
         [marked]: { type: true };
-        [serial]: { type: number };
+        [serial]: { type: U32 };
         [parent]: { type: Entity };
-        [place]: { type: readonly [number, number, number] };
-        [cell]: { type: readonly [number, number, number] };
+        [place]: { type: Vec3 };
+        [cell]: { type: Vec3.I32 };
     }
 }
-Component.register(key, { type: { type: "integer", minimum: 0, maximum: 0x7FFFFFFF } });
-Component.register(amount, { type: { type: "number" } });
-Component.register(marked, { type: { const: true } });
-Component.register(serial, { type: { type: "integer", minimum: 0, maximum: 0x7FFFFFFF } });
-Component.register(parent, { type: Entity.schema });
-Component.register(place, { type: { type: "array", items: { type: "number", precision: 1 }, minItems: 3, maxItems: 3 } });
-Component.register(cell, { type: { type: "array", items: { type: "integer", minimum: -0x80000000, maximum: 0x7FFFFFFF }, minItems: 3, maxItems: 3 } });
 
 const million = 1_000_000;
 
 /** Distinct keys among the indexed entities: ten entities a bucket. */
 const keys = million / 10;
-const byKey = Index.create({ name: "indexes/byKey", key: [key] });
+const byKey = Index.create({ key: [key] });
 
-const seedKeys = System.create({ name: "indexes/seedKeys", input: { type: "object", properties: { count: { type: "integer" }, marked: { type: "integer" } } } }, ({ input, commands }) => {
+const seedKeys = System.create({}, ({ commands }, input: { readonly count: number; readonly marked: number }) => {
     for (let i = 0; i < input.count; i++) {
         if (i < input.marked) commands.spawn([key, amount, marked])({ [key]: (i * 7919) % keys, [amount]: i, [marked]: true });
         else commands.spawn([key, amount])({ [key]: (i * 7919) % keys, [amount]: i });
@@ -51,13 +45,13 @@ const seedKeys = System.create({ name: "indexes/seedKeys", input: { type: "objec
 
 /** Moves every marked entity to another bucket, and back again the next run. */
 let flip = 1;
-const rekeyMarked = System.create({ name: "indexes/rekeyMarked", components: { write: [key], has: [marked] } }, row => { row[key] = (row[key] + flip + keys) % keys; });
+const rekeyMarked = System.create({ components: { with: [key, marked] } }, row => { row[key] = (row[key] + flip + keys) % keys; });
 /** Moves every entity to another bucket. */
-const rekeyAll = System.create({ name: "indexes/rekeyAll", components: { write: [key] } }, row => { row[key] = (row[key] + flip + keys) % keys; });
+const rekeyAll = System.create({ components: { with: [key] } }, row => { row[key] = (row[key] + flip + keys) % keys; });
 
 let found = 0;
 /** Uses `byKey`, so a run of it refreshes the index. */
-const lookOnce = System.create({ name: "indexes/lookOnce", lookup: { byKey: { index: byKey } } }, ({ lookup }) => { found += lookup.byKey(0).length; });
+const lookOnce = System.create({ lookup: { byKey: { index: byKey } } }, ({ lookup }) => { found += lookup.byKey(0).length; });
 
 /** The fastest run of `measured` right after `before`. */
 const after = async (before: () => Promise<unknown>, measured: () => Promise<unknown>, rounds = 40, warmup = 6): Promise<number> => {
@@ -80,8 +74,8 @@ const inline = (): World => createWorld({ [workers]: 0 });
 const threads = navigator.hardwareConcurrency - 1;
 const pooled = (): World => createWorld({ [workers]: threads });
 
-/** A kernel touching nothing, so a world's pool starts, as it does with its first kernel. */
-const startPool = System.create({ name: "indexes/startPool", kernel: "cpu", components: { has: [marked] } }, () => {});
+/** A kernel over every keyed row, doing nothing: rows enough for workers, so the world starts its pool after it. */
+const startPool = System.create({ kernel: true, components: { with: [key] } }, () => {});
 
 /** Indexes `index idle` keeps, each over its own thousand entities. */
 const idleIndexes = 1000;
@@ -91,15 +85,14 @@ declare module "@adobe/ecs" {
         [idleKey]: { type: number };
     }
 }
-Component.register(idleKey, { type: { type: "number" } });
 
 /** Unique serials among `unique lookup 1M`'s entities. */
-const bySerial = Index.create({ name: "indexes/bySerial", key: [serial], unique: true, components: { has: [amount] } });
-const seedSerials = System.create({ name: "indexes/seedSerials" }, ({ commands }) => {
+const bySerial = Index.create({ key: [serial], unique: true, components: { with: [amount] } });
+const seedSerials = System.create({}, ({ commands }) => {
     for (let i = 0; i < million; i++) commands.spawn([serial, amount])({ [serial]: i, [amount]: 1 });
 });
 let summed = 0;
-const lookUnique = System.create({ name: "indexes/lookUnique", lookup: { bySerial: { index: bySerial, read: [amount] } } }, ({ lookup }) => {
+const lookUnique = System.create({ lookup: { bySerial: { index: bySerial } } }, ({ lookup }) => {
     let sum = 0;
     for (let i = 0; i < million; i++) sum += lookup.bySerial(i)?.[amount] ?? 0;
     summed = sum;
@@ -107,22 +100,22 @@ const lookUnique = System.create({ name: "indexes/lookUnique", lookup: { bySeria
 
 /** Parents in `children lookup`, with ten children each. */
 const parents = 10_000;
-const childrenOf = Index.create({ name: "indexes/childrenOf", key: [parent], components: { has: [amount] } });
-const seedFamilies = System.create({ name: "indexes/seedFamilies" }, ({ commands }) => {
+const childrenOf = Index.create({ key: [parent], components: { with: [amount] } });
+const seedFamilies = System.create({}, ({ commands }) => {
     for (let p = 0; p < parents; p++) {
         const entity = commands.spawn([marked])({ [marked]: true });
         for (let c = 0; c < 10; c++) commands.spawn([parent, amount])({ [parent]: entity, [amount]: 1 });
     }
 });
-const sumChildren = System.create({ name: "indexes/sumChildren", components: { has: [marked] }, lookup: { children: { index: childrenOf, read: [amount] } } }, (row, { lookup }) => {
+const sumChildren = System.create({ components: { with: [marked] }, lookup: { children: { index: childrenOf } } }, (row, { lookup }) => {
     const children = lookup.children(row.entity);
     for (let i = 0; i < children.length; i++) summed += children.at(i)[amount];
 });
 
 /** Particles in `grid neighbors 100K`, in a 100 by 100 by 10 grid of unit cells, ten a cell. */
 const particles = 100_000;
-const grid = Index.create({ name: "indexes/grid", key: [cell], components: { has: [place] } });
-const seedParticles = System.create({ name: "indexes/seedParticles" }, ({ commands }) => {
+const grid = Index.create({ key: [cell], components: { with: [place] } });
+const seedParticles = System.create({}, ({ commands }) => {
     for (let i = 0; i < particles; i++) {
         const x = ((i * 7919) % 1000) / 10;
         const y = ((i * 104729) % 1000) / 10;
@@ -131,7 +124,7 @@ const seedParticles = System.create({ name: "indexes/seedParticles" }, ({ comman
     }
 });
 /** The same on a kernel: on the pool, each row's 27 probes in straight-line code. */
-const neighborsKernel = System.create({ name: "indexes/neighborsKernel", kernel: "cpu", components: { read: [place, cell], write: [amount] }, lookup: { near: { index: grid, read: [place] } } }, (row, { lookup }) => {
+const neighborsKernel = System.create({ kernel: true, components: { with: [place, cell, amount] }, lookup: { near: { index: grid } } }, (row, { lookup }) => {
     const [cx, cy, cz] = row[cell];
     const [x] = row[place];
     let push = 0;
@@ -148,7 +141,7 @@ const neighborsKernel = System.create({ name: "indexes/neighborsKernel", kernel:
     }
     row[amount] = push;
 });
-const seedKernelParticles = System.create({ name: "indexes/seedKernelParticles" }, ({ commands }) => {
+const seedKernelParticles = System.create({}, ({ commands }) => {
     for (let i = 0; i < particles; i++) {
         const x = ((i * 7919) % 1000) / 10;
         const y = ((i * 104729) % 1000) / 10;
@@ -159,12 +152,12 @@ const seedKernelParticles = System.create({ name: "indexes/seedKernelParticles"
 
 /** Particles of `rekey 1M`, drifting through cells of 4 units. */
 const drifting = million;
-const drift = System.create({ name: "indexes/drift", kernel: "cpu", components: { write: [place] } }, row => {
+const drift = System.create({ kernel: true, components: { with: [place] } }, row => {
     const [x, y, z] = row[place];
     row[place] = [x + 0.25, y, z];
 });
 /** The cell a particle is in, written only when it crosses into another, so the index's work is the crossings. */
-const rekeyCells = System.create({ name: "indexes/rekeyCells", kernel: "cpu", components: { read: [place], write: [cell], changed: [place] }, after: [drift] }, row => {
+const rekeyCells = System.create({ kernel: true, components: { with: [place, cell], changed: [place] }, after: [drift] }, row => {
     const [x, y, z] = row[place];
     const [cx, cy, cz] = row[cell];
     const nx = Math.floor(x / 4);
@@ -172,11 +165,11 @@ const rekeyCells = System.create({ name: "indexes/rekeyCells", kernel: "cpu", co
     const nz = Math.floor(z / 4);
     if (nx !== cx || ny !== cy || nz !== cz) row[cell] = [nx, ny, nz];
 });
-const coarse = Index.create({ name: "indexes/coarse", key: [cell], components: { has: [place] } });
+const coarse = Index.create({ key: [cell], components: { with: [place] } });
 /** Uses `coarse` once, so a run refreshes it. */
-const lookCoarse = System.create({ name: "indexes/lookCoarse", lookup: { coarse: { index: coarse } }, after: [rekeyCells] }, ({ lookup }) => { found += lookup.coarse([0, 0, 0]).length; });
-const frame = System.create({ name: "indexes/frame", systems: [drift, rekeyCells, lookCoarse] });
-const seedDrifting = System.create({ name: "indexes/seedDrifting" }, ({ commands }) => {
+const lookCoarse = System.create({ lookup: { coarse: { index: coarse } }, after: [rekeyCells] }, ({ lookup }) => { found += lookup.coarse([0, 0, 0]).length; });
+const frame = System.create({ systems: [drift, rekeyCells, lookCoarse] });
+const seedDrifting = System.create({}, ({ commands }) => {
     for (let i = 0; i < drifting; i++) {
         const x = (i * 7919) % 4000 / 10;
         const y = (i * 104729) % 4000 / 10;
@@ -184,12 +177,12 @@ const seedDrifting = System.create({ name: "indexes/seedDrifting" }, ({ commands
     }
 });
 /** The same frame without the index: what computing the key costs alone. */
-const frameUnindexed = System.create({ name: "indexes/frameUnindexed", systems: [drift, rekeyCells] });
+const frameUnindexed = System.create({ systems: [drift, rekeyCells] });
 
 /** Rows of `order run 100K`, ranked in a scattered order. */
 const orderedRows = 100_000;
-const byRank = Index.create({ name: "indexes/byRank", key: [serial], sorted: true, components: { has: [amount] } });
-const seedRanked = System.create({ name: "indexes/seedRanked" }, ({ commands }) => {
+const byRank = Index.create({ key: [serial], sorted: true, components: { with: [amount] } });
+const seedRanked = System.create({}, ({ commands }) => {
     for (let i = 0; i < orderedRows; i++) {
         if (i < orderedRows / 100) commands.spawn([serial, amount, marked])({ [serial]: (i * 7919) % orderedRows, [amount]: i });
         else commands.spawn([serial, amount])({ [serial]: (i * 7919) % orderedRows, [amount]: i });
@@ -197,19 +190,19 @@ const seedRanked = System.create({ name: "indexes/seedRanked" }, ({ commands })
 });
 let accumulated = 0;
 /** Sums its rows' amounts, weighting each by the sum so far, so the order rows run in is part of the result. */
-const inRankOrder = System.create({ name: "indexes/inRankOrder", components: { read: [amount] }, order: byRank }, row => {
+const inRankOrder = System.create({ components: { with: [amount] }, order: byRank }, row => {
     accumulated = (accumulated * 31 + row[amount]) % 1000003;
 });
-const inStorageOrder = System.create({ name: "indexes/inStorageOrder", components: { read: [amount] } }, row => {
+const inStorageOrder = System.create({ components: { with: [amount] } }, row => {
     accumulated = (accumulated * 31 + row[amount]) % 1000003;
 });
-const changedInRankOrder = System.create({ name: "indexes/changedInRankOrder", components: { read: [amount], changed: [amount] }, order: byRank }, row => {
+const changedInRankOrder = System.create({ components: { with: [amount], changed: [amount] }, order: byRank }, row => {
     accumulated = (accumulated * 31 + row[amount]) % 1000003;
 });
-const bumpMarked = System.create({ name: "indexes/bumpMarked", components: { write: [amount], has: [marked] } }, row => { row[amount] += 1; });
+const bumpMarked = System.create({ kernel: false, components: { with: [amount, marked] } }, row => { row[amount] += 1; });
 
 let pushed = 0;
-const neighbors = System.create({ name: "indexes/neighbors", components: { read: [place, cell] }, lookup: { near: { index: grid, read: [place] } } }, (row, { lookup }) => {
+const neighbors = System.create({ components: { with: [place, cell] }, lookup: { near: { index: grid } } }, (row, { lookup }) => {
     const [cx, cy, cz] = row[cell];
     const [x] = row[place];
     let push = 0;
@@ -221,9 +214,9 @@ const neighbors = System.create({ name: "indexes/neighbors", components: { read:
 });
 
 /** Ranks of `sorted range 1M`, one an entity, and the ranges it looks up, ten ranks each. */
-const ranked = Index.create({ name: "indexes/ranked", key: [serial], sorted: true, components: { has: [amount] } });
+const ranked = Index.create({ key: [serial], sorted: true, components: { with: [amount] } });
 const ranges = 10_000;
-const lookRanges = System.create({ name: "indexes/lookRanges", lookup: { ranked: { index: ranked, read: [amount] } } }, ({ lookup }) => {
+const lookRanges = System.create({ lookup: { ranked: { index: ranked } } }, ({ lookup }) => {
     let sum = 0;
     for (let r = 0; r < ranges; r++) {
         const start = (r * 7919) % (million - 10);
@@ -235,15 +228,15 @@ const lookRanges = System.create({ name: "indexes/lookRanges", lookup: { ranked:
 
 /** Entities `sorted page 100K` pages through, by a value one of them changes each run, the page the 20 after the first 100 with a small rank. */
 const pageRows = 100_000;
-const byAmount = Index.create({ name: "indexes/byAmount", key: [amount], sorted: true, components: { has: [key] } });
-const seedPage = System.create({ name: "indexes/seedPage" }, ({ commands }) => {
+const byAmount = Index.create({ key: [amount], sorted: true, components: { with: [key] } });
+const seedPage = System.create({}, ({ commands }) => {
     commands.spawn([amount, key, marked])({ [amount]: 0, [key]: 0, [marked]: true });
     for (let i = 1; i < pageRows; i++) commands.spawn([amount, key])({ [amount]: (i * 7919) % pageRows, [key]: i });
 });
-const nudgeAmount = System.create({ name: "indexes/nudgeAmount", components: { has: [marked], write: [amount] } }, row => { row[amount] += 1; });
+const nudgeAmount = System.create({ kernel: false, components: { with: [amount, marked] } }, row => { row[amount] += 1; });
 let page: number[] = [];
 /** The page, recomputed only when what it reads changed: the 20 rows after the first 100 with a key below half, highest amounts first. */
-const readPage = System.create({ name: "indexes/readPage", lookup: { byAmount: { index: byAmount, read: [key], changed: [key] } }, after: [nudgeAmount] }, ({ lookup }) => {
+const readPage = System.create({ lookup: { byAmount: { index: byAmount, changed: [key] } }, after: [nudgeAmount] }, ({ lookup }) => {
     const all = lookup.byAmount();
     if (!all.changed) return;
     const rows: number[] = [];
@@ -256,7 +249,7 @@ const readPage = System.create({ name: "indexes/readPage", lookup: { byAmount: {
     }
     page = rows;
 });
-const nudgeThenPage = System.create({ name: "indexes/nudgeThenPage", systems: [nudgeAmount, readPage] });
+const nudgeThenPage = System.create({ systems: [nudgeAmount, readPage] });
 
 /** Entities of the keyless benchmarks, and the 1% of them `keyless refresh 1M 1%` moves in and out. */
 const tagged = Symbol("indexes/tagged");
@@ -265,9 +258,8 @@ declare module "@adobe/ecs" {
         [tagged]: { type: true };
     }
 }
-Component.register(tagged, { type: { const: true } });
-const untagged = Index.create({ name: "indexes/untagged", key: [], components: { has: [amount], not: [tagged] } });
-const seedAmounts = System.create({ name: "indexes/seedAmounts" }, ({ commands }) => {
+const untagged = Index.create({ key: [], components: { with: [amount], not: [tagged] } });
+const seedAmounts = System.create({}, ({ commands }) => {
     for (let i = 0; i < million; i++) {
         if (i % 100 === 0) commands.spawn([amount, marked])({ [amount]: i, [marked]: true });
         else commands.spawn([amount])({ [amount]: i });
@@ -275,24 +267,24 @@ const seedAmounts = System.create({ name: "indexes/seedAmounts" }, ({ commands }
 });
 /** Tags every marked entity, which leaves the index, and untags them the next run, which enter it again. */
 let tagging = true;
-const toggleMarked = System.create({ name: "indexes/toggleMarked", components: { has: [marked] } }, (row, { commands }) => {
+const toggleMarked = System.create({ components: { with: [marked] } }, (row, { commands }) => {
     if (tagging) commands.add(row.entity, tagged);
     else commands.remove(row.entity, tagged);
 });
-const lookUntagged = System.create({ name: "indexes/lookUntagged", lookup: { untagged: { index: untagged } } }, ({ lookup }) => { found += lookup.untagged().length; });
+const lookUntagged = System.create({ lookup: { untagged: { index: untagged } } }, ({ lookup }) => { found += lookup.untagged().length; });
 /** Despawns the entities it spawned the run before and spawns as many again. */
 let spawnedLast: Entity[] = [];
-const spawnAndDespawn = System.create({ name: "indexes/spawnAndDespawn" }, ({ commands }) => {
+const spawnAndDespawn = System.create({}, ({ commands }) => {
     for (const entity of spawnedLast) commands.despawn(entity);
     const spawned: Entity[] = [];
     for (let i = 0; i < million / 100; i++) spawned.push(commands.spawn([amount])({ [amount]: i }));
     spawnedLast = spawned;
 });
 /** Writes every entity's amount, which the index holds by but doesn't watch. */
-const writeAmounts = System.create({ name: "indexes/writeAmounts", kernel: "cpu", components: { write: [amount] } }, row => { row[amount] = row[amount] + 1; });
+const writeAmounts = System.create({ kernel: true, components: { with: [amount] } }, row => { row[amount] = row[amount] + 1; });
 /** Reads the index's length and whether it changed, as a count kept by a system would. */
 const lengthReads = 100_000;
-const readLengths = System.create({ name: "indexes/readLengths", lookup: { untagged: { index: untagged } } }, ({ lookup }) => {
+const readLengths = System.create({ lookup: { untagged: { index: untagged } } }, ({ lookup }) => {
     let sum = 0;
     for (let i = 0; i < lengthReads; i++) {
         const rows = lookup.untagged();
@@ -310,13 +302,12 @@ declare module "@adobe/ecs" {
         [flag]: { type: boolean };
     }
 }
-Component.register(flag, { type: { type: "boolean" } });
-const byFlag = Index.create({ name: "indexes/byFlag", key: [flag] });
-const seedFlags = System.create({ name: "indexes/seedFlags" }, ({ commands }) => {
+const byFlag = Index.create({ key: [flag] });
+const seedFlags = System.create({}, ({ commands }) => {
     for (let i = 0; i < flagged; i++) commands.spawn([flag])({ [flag]: i % 2 === 0 });
 });
 /** A run of observer systems alone, which passes every one added. */
-const pass = System.create({ name: "indexes/pass", observer: true }, () => {});
+const pass = System.create({ observer: true }, () => {});
 /** A count of each bucket, written only when the index's entries changed: by `changed: true`, or by its lists' `changed`. */
 const countsWhenChanged = (filtered: boolean): System => filtered
     ? System.create({ observer: true, lookup: { byFlag: { index: byFlag, changed: true } } }, ({ lookup }) => {
@@ -342,6 +333,82 @@ const restingCounts = async (filtered: boolean): Promise<number> => {
     return best;
 };
 
+/** Entities toggled between `byFlag`'s two buckets, one a run, each a different one spread through entity order. */
+let flaggedEntities: Entity[] = [];
+const seedFlagged = System.create({}, ({ commands }, input: { readonly count: number }) => {
+    flaggedEntities = [];
+    for (let i = 0; i < input.count; i++) flaggedEntities.push(commands.spawn([flag])({ [flag]: i % 2 === 0 }));
+});
+const toggleFlag = System.create({ target: "entity", components: { with: [flag] } }, (row, _context, _input: { readonly entity: Entity }) => {
+    row[flag] = !row[flag];
+});
+/** Both buckets' lengths, as a count of done and not done todos. */
+const readFlagLengths = System.create({ lookup: { byFlag: { index: byFlag } } }, ({ lookup }) => {
+    found = lookup.byFlag(false).length + lookup.byFlag(true).length;
+});
+/** Both buckets' first ten rows, in entity order. */
+const readFlagRows = System.create({ lookup: { byFlag: { index: byFlag } } }, ({ lookup }) => {
+    let sum = 0;
+    for (const value of [false, true]) {
+        const rows = lookup.byFlag(value);
+        let last = 0;
+        for (let i = 0; i < 10 && i < rows.length; i++) {
+            const entity = rows.at(i).entity;
+            check(entity > last, "bucket move: rows out of entity order");
+            last = entity;
+            sum += entity;
+        }
+    }
+    found = sum;
+});
+/** Moves a round of `bucketMove` takes. */
+const movesPerRound = 200;
+/**
+ * The fastest round's mean time of moving one entity between `byFlag`'s two buckets of `count` entities between them,
+ * then running `reader`, which refreshes the index and reads it.
+ */
+const bucketMove = async (count: number, reader: System): Promise<number> => {
+    const world = inline();
+    await world.run(seedFlagged, { count });
+    await world.run(reader);
+    let best = Infinity;
+    let next = 0;
+    for (let round = 0; round < 8; round++) {
+        const start = performance.now();
+        for (let k = 0; k < movesPerRound; k++) {
+            await world.run(toggleFlag, { entity: flaggedEntities[(next++ * 7919) % count] });
+            await world.run(reader);
+        }
+        if (round >= 2) best = Math.min(best, (performance.now() - start) / movesPerRound);
+    }
+    check(found > 0, "bucket move: nothing found");
+    await world.dispose();
+    return best;
+};
+const bucketMoveBenchmarks = [1_000, 10_000, 100_000].flatMap((count): Benchmark[] => {
+    const label = `${count / 1000}K`;
+    return [
+        {
+            name: `bucket move ${label} length`,
+            operation: `A run moving one entity between the two buckets of a hash index on a boolean over ${label} entities, then a system reading both buckets' lengths: toggling a todo while counts of done and not done ones are shown.`,
+            per: "moves",
+            n: 1,
+            typical: [1, 100],
+            best: { bytes: 48, basis: "The move reads its 8-byte key and tick, and writes one 12-byte entry out of one bucket and one into the other; each length reads 4 bytes." },
+            run: () => bucketMove(count, readFlagLengths),
+        },
+        {
+            name: `bucket move ${label} in order`,
+            operation: `As \`bucket move ${label} length\`, the system reading each bucket's first ten rows in entity order: a list of done todos shown after a toggle.`,
+            per: "moves",
+            n: 1,
+            typical: [1, 100],
+            best: { bytes: 288, basis: "As the length's, and twenty 12-byte entries read." },
+            run: () => bucketMove(count, readFlagRows),
+        },
+    ];
+});
+
 export const indexBenchmarks: readonly Benchmark[] = [
     {
         name: "observer index unchanged 100",
@@ -388,7 +455,7 @@ export const indexBenchmarks: readonly Benchmark[] = [
         best: { bytes: 8, basis: "Each index reads its journal position, 8 bytes." },
         run: async () => {
             const world = inline();
-            const indexes = Array.from({ length: idleIndexes }, () => Index.create({ key: [], components: { has: [idleKey] } }));
+            const indexes = Array.from({ length: idleIndexes }, () => Index.create({ key: [], components: { with: [idleKey] } }));
             await world.run(System.create(({ commands }) => { for (let i = 0; i < 1000; i++) commands.spawn([idleKey])({ [idleKey]: i }); }));
             const lookup = Object.fromEntries(indexes.map((index, k) => [`i${k}`, { index }]));
             const user = System.create({ lookup }, () => {});
@@ -688,4 +755,5 @@ export const indexBenchmarks: readonly Benchmark[] = [
             return best;
         },
     },
+    ...bucketMoveBenchmarks,
 ];

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

@@ -1,3 +1,4 @@
+// © 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";
@@ -7,7 +8,7 @@ import { counter, empty, order, remoteRuns, observerAmounts, observerCaptions, o
 import { handoffSystems } from "./handoff.js";
 import { release } from "./finalized.js";
 import { tailSystems } from "./tails.js";
-import { take, transferBatch, transferBytes, transferCount, transferSide, transferSystems } from "./transfers.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";
@@ -19,7 +20,7 @@ import { programFinalizers, requireDefinition } from "../interface/registry/inde
  */
 type Message = ToJoined
     | { readonly kind: "port"; readonly port: MessagePort | NodeMessagePort; readonly threads?: readonly ("handoffBenchmark" | "finalizedBenchmark" | "tailsBenchmark" | "transfersBenchmark")[] }
-    | { readonly kind: "transfers" };
+    | { 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;
@@ -33,7 +34,7 @@ channel.onMessage(async message => {
         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 = join(message.port, { threads: message.threads ?? [] });
+        remote = await join(message.port, { threads: message.threads ?? [] });
         channel.post({ kind: "joined" });
         return;
     }
@@ -42,7 +43,7 @@ channel.onMessage(async message => {
         // 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(transferSide, transferSide);
+        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();
@@ -50,8 +51,15 @@ channel.onMessage(async message => {
             return performance.now() - start;
         };
         await batch();
+        const batches = transferCount / transferBatch;
         let milliseconds = 0;
-        for (let k = 0; k < transferCount / transferBatch; k++) milliseconds += await batch();
+        // 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;
     }

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

@@ -1,3 +1,4 @@
+// © 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`

package/src/perftest/log.ts

@@ -1,4 +1,4 @@
-import { Component } from "../interface/component/component.js";
+// © 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";
@@ -21,14 +21,14 @@ declare module "@adobe/ecs" {
     }
     export interface Components {
         [serial]: { type: number };
-        [label]: { type: { readonly text: string } | null; thread: "logBenchmark" };
+        [label]: { type: Label; thread: "logBenchmark" };
         [moved]: { type: true };
     }
 }
-Component.register(serial, { type: { type: "number" } });
-const none = { text: "none" };
-Component.register(label, { type: { anyOf: [{ type: "object", properties: { text: { type: "string" } } }, { type: "null" }], default: none }, thread: "logBenchmark" });
-Component.register(moved, { type: { const: 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;

package/src/perftest/loop.ts

@@ -1,3 +1,4 @@
+// © 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";
@@ -11,7 +12,7 @@ export const loopTicks = 10_000;
 export const observerIdles = 100;
 
 /** Observer systems no entity matches, each run after every tick. */
-const idleObserver = Array.from({ length: observerIdles }, (_, i) => System.create({ name: `loop/idleObserver${i}`, observer: true, components: { has: [unused] } }, () => {}));
+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