@adobe/ecs 0.1.0 → 0.2.1

package/src/implementation/world/archetype.ts

@@ -1,7 +1,8 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Entity } from '../../interface/entity/entity.js';
 import type { Layout, Views } from '../../interface/registry/layout.js';
 import { allocateArray, allocateViews, emptyViews, freeArray, freeViews, growArray } from './arrays.js';
-import { chunkShift } from './kernel.js';
+import { blockShift, chunkShift } from './kernel.js';
 import type { Memory } from './memory.js';
 import { nullTag, startTag, type MoveLog } from './move-log.js';
 import type { StringStore } from './strings.js';
@@ -9,7 +10,8 @@ import type { StringStore } from './strings.js';
 /** One component's storage in one archetype. Its views and ticks are replaced when the archetype grows. */
 export type Storage = {
     readonly component: number;
-    readonly layout: Layout;
+    /** A shared component's is replaced as its archetype is reused for other values (`reclaim.ts`). */
+    layout: Layout;
     /**
      * Views of the interleaved column, for a linear layout: row `r` is `layout.stride` bytes at `r * stride`. For a
      * string, each row's handle of its record while records are kept, else 0, as in rows past the archetype's count.
@@ -39,6 +41,12 @@ export type Storage = {
     /** The newest `added` and `changed` tick in each chunk of `2 ** chunkShift` rows, so change filters skip unchanged chunks. */
     chunkAdded: Float64Array;
     chunkChanged: Float64Array;
+    /**
+     * The newest `added` and `changed` tick in each block of `2 ** blockShift` rows, so change filters skip the
+     * unchanged blocks of a chunk that changed: a filter's scan costs what changed, not the chunk.
+     */
+    blockAdded: Float64Array;
+    blockChanged: Float64Array;
     /**
      * The newest tick at which every row may have changed, as a GPU kernel's writes do, so stamping them costs
      * nothing per row: change filters pass the whole column when it's newer than their `lastRun`.
@@ -72,28 +80,60 @@ export const writeOf = (layout: Layout): { readonly write: number; readonly unit
 
 /** Chunks covering `capacity` rows. */
 const chunksFor = (capacity: number): number => Math.max(1, Math.ceil(capacity / 2 ** chunkShift));
+/** Blocks covering those chunks, so every row of a chunk has a block. */
+const blocksFor = (capacity: number): number => chunksFor(capacity) << (chunkShift - blockShift);
 
 /** What stamping a row's ticks writes: a storage's, or a joined thread's view of one. */
-export type Stamped = Pick<Storage, "ticked" | "added" | "changed" | "chunkAdded" | "chunkChanged">;
+export type Stamped = Pick<Storage, "ticked" | "added" | "changed" | "chunkAdded" | "chunkChanged" | "blockAdded" | "blockChanged">;
 
-/** Stamps a row's `changed` tick and its chunk's. Ticks only increase, so the chunk's is the newest. */
+/**
+ * Stamps a row's `changed` tick, its block's and its chunk's. Ticks only increase, so theirs are the newest. Every
+ * writer stores the row, then the block, then the chunk, the reverse of the order filters read them, so a filter on
+ * another thread that finds a chunk newer finds its block and row newer too.
+ */
 export const stampChanged = (storage: Stamped, row: number, tick: number): void => {
     if (!storage.ticked) return;
     storage.changed[row] = tick;
+    storage.blockChanged[row >> blockShift] = tick;
     storage.chunkChanged[row >> chunkShift] = tick;
 };
 
-export const stampAdded = (storage: Stamped, row: number, tick: number): void => {
-    if (!storage.ticked) return;
-    storage.added[row] = tick;
-    storage.chunkAdded[row >> chunkShift] = tick;
+/**
+ * Raises the block and chunk ticks over rows `start` to `end - 1` to at least `tick`: for ticks written to those rows
+ * in bulk, or copied in from rows of other chunks.
+ */
+export const raiseRange = (chunks: Float64Array, blocks: Float64Array, start: number, end: number, tick: number): void => {
+    if (start >= end) return;
+    for (let block = start >> blockShift, last = (end - 1) >> blockShift; block <= last; block++) if (blocks[block] < tick) blocks[block] = tick;
+    for (let chunk = start >> chunkShift, last = (end - 1) >> chunkShift; chunk <= last; chunk++) if (chunks[chunk] < tick) chunks[chunk] = tick;
 };
 
-/** A table of the entities that have exactly `components`. Rows are dense: `0` to `count`. */
+/** A table of the entities that have exactly `components`, with exactly its shared values. Rows are dense: `0` to `count`. */
 export type Archetype = {
     readonly id: number;
     /** Sorted component ids. */
     readonly components: readonly number[];
+    /**
+     * By component id, the number of the value it holds of each shared component (`shared.ts`), once for every row: its
+     * storage's layout holds the value. Empty without shared components.
+     */
+    shared: readonly (number | undefined)[];
+    /** By component id, the canonical text of each shared value it holds, which the layout directory carries to joined threads. */
+    texts: readonly (string | undefined)[];
+    /**
+     * Of one with shared values, reclaimed once empty and reused for others (`reclaim.ts`): its key in the world's
+     * lookup; whether it's reclaimed, waiting in its component set's pool; how many times it was reused; the sync point
+     * it was found empty at, by count, -1 while it isn't, and by tick; and the cached edges that lead to or from it, each
+     * cleared as it's reclaimed, null for none. Kept in place, not apart, so archetypes stay compact for runs.
+     */
+    key: string;
+    reclaimed: boolean;
+    generation: number;
+    emptiedAt: number;
+    emptiedTick: number;
+    edges: Edge[] | null;
+    /** By shared component id, then value number: the archetype with that value in place of its own, cached as moves first take it. */
+    readonly sharing: (Archetype | undefined)[][];
     readonly storages: readonly Storage[];
     readonly storageOf: ReadonlyMap<number, Storage>;
     /** Storages by component id, for hot paths. */
@@ -109,8 +149,6 @@ export type Archetype = {
     capacity: number;
     /** Holds the resource entity, so queries and systems never see it. */
     readonly resource: boolean;
-    /** Holds reports, which only queries that require a component see. */
-    readonly meta: boolean;
     /** Whether a storage holds values as objects or strings, which a removed row must release. */
     readonly objects: boolean;
     /** Its storages of strings, whose records a removed row lets go. */
@@ -129,8 +167,14 @@ export type Archetype = {
     listed: boolean;
 };
 
+/**
+ * A cached edge between two archetypes, one with shared values: `holder[key]` names its target, and holds `cleared`
+ * once either end is reclaimed. Kept in each end's `edges` holding it.
+ */
+export type Edge = { readonly holder: object; readonly key: PropertyKey; readonly cleared: unknown; readonly ends: readonly Archetype[] };
+
 /** Moves the version on once arrays are replaced, and lists the archetype for the layout directory's next flush. */
-const bump = (archetype: Archetype): void => {
+export const bump = (archetype: Archetype): void => {
     archetype.version++;
     archetype.replaced.count++;
     if (archetype.listed) return;
@@ -140,21 +184,33 @@ const bump = (archetype: Archetype): void => {
 
 const initialCapacity = 16;
 
+/** An archetype without shared components holds no values: one empty list for them all. */
+export const noShared: readonly (number | undefined)[] = [];
+const noLayouts: readonly (Layout | undefined)[] = [];
+const noTexts: readonly (string | undefined)[] = [];
+
 /** The tick arrays of a storage without ticks. */
 const noTicks = new Float64Array(0);
 /** The tags of a storage whose values the world's thread holds. */
 const noTags = new Uint32Array(0);
 
+/** Whether a storage's `changed` ticks are its `added` ticks: a constant's, whose value can't change, but a shared one's. */
+export const alias = (layout: Layout): boolean => layout.kind === "constant" && layout.shared !== true;
+
 /**
  * Gives a storage tick arrays for `capacity` rows, every tick set to `tick`. A constant's value can't change, so its
- * `changed` ticks are its `added` ticks: tags cost one tick per row.
+ * `changed` ticks are its `added` ticks: tags cost one tick per row. A shared component's value changes as its entity
+ * moves, so it keeps both.
  */
 const allocateTicks = (memory: Memory, storage: Storage, capacity: number, tick: number): void => {
     storage.ticked = true;
     storage.added = allocateArray(memory, Float64Array, capacity).fill(tick);
-    storage.changed = storage.layout.kind === "constant" ? storage.added : allocateArray(memory, Float64Array, capacity).fill(tick);
+    const aliased = alias(storage.layout);
+    storage.changed = aliased ? storage.added : allocateArray(memory, Float64Array, capacity).fill(tick);
     storage.chunkAdded = allocateArray(memory, Float64Array, chunksFor(capacity)).fill(tick);
-    storage.chunkChanged = storage.layout.kind === "constant" ? storage.chunkAdded : allocateArray(memory, Float64Array, chunksFor(capacity)).fill(tick);
+    storage.chunkChanged = aliased ? storage.chunkAdded : allocateArray(memory, Float64Array, chunksFor(capacity)).fill(tick);
+    storage.blockAdded = allocateArray(memory, Float64Array, blocksFor(capacity)).fill(tick);
+    storage.blockChanged = aliased ? storage.blockAdded : allocateArray(memory, Float64Array, blocksFor(capacity)).fill(tick);
 };
 
 /** Views of a new column, for a linear layout's or a string's `capacity` rows; a string's handles start at 0. */
@@ -180,6 +236,8 @@ const createStorage = (memory: Memory, strings: StringStore | null, component: n
         changed: noTicks,
         chunkAdded: noTicks,
         chunkChanged: noTicks,
+        blockAdded: noTicks,
+        blockChanged: noTicks,
         columnChanged: 0,
         remote: null,
         tags: noTags,
@@ -202,13 +260,22 @@ export const startTicks = (memory: Memory, archetype: Archetype, storage: Storag
  * Creates an archetype, listed in `bumped` for the layout directory's next flush; storages of components a joined
  * thread fills, by `remote`, hold their tags.
  */
-export const createArchetype = (memory: Memory, strings: StringStore | null, id: number, components: readonly number[], layouts: readonly Layout[], resource: boolean, meta: boolean, ticked: ReadonlySet<number>, bumped: Archetype[], replaced: { count: number }, remote: readonly (MoveLog | undefined)[]): Archetype => {
-    const storages = components.map(component => createStorage(memory, strings, component, layouts[component], initialCapacity, resource || ticked.has(component)));
+export const createArchetype = (memory: Memory, strings: StringStore | null, id: number, components: readonly number[], layouts: readonly Layout[], resource: boolean, ticked: ReadonlySet<number>, bumped: Archetype[], replaced: { count: number }, remote: readonly (MoveLog | undefined)[], shared: readonly (number | undefined)[] = noShared, sharedLayouts: readonly (Layout | undefined)[] = noLayouts, texts: readonly (string | undefined)[] = noTexts, key = ""): Archetype => {
+    const storages = components.map(component => createStorage(memory, strings, component, sharedLayouts[component] ?? layouts[component], initialCapacity, resource || ticked.has(component)));
     const storageById: (Storage | undefined)[] = [];
     for (const storage of storages) storageById[storage.component] = storage;
     const archetype: Archetype = {
         id,
         components,
+        shared,
+        texts,
+        key,
+        reclaimed: false,
+        generation: 0,
+        emptiedAt: -1,
+        emptiedTick: -1,
+        edges: null,
+        sharing: [],
         storages,
         storageOf: new Map(storages.map(storage => [storage.component, storage])),
         storageById,
@@ -219,7 +286,6 @@ export const createArchetype = (memory: Memory, strings: StringStore | null, id:
         count: 0,
         capacity: initialCapacity,
         resource,
-        meta,
         objects: storages.some(storage => storage.layout.kind === "object" || storage.layout.kind === "string"),
         strings: storages.filter(storage => storage.layout.kind === "string"),
         version: 0,
@@ -261,6 +327,10 @@ const grow = (memory: Memory, archetype: Archetype, capacity = archetype.capacit
             const used = storage.chunkAdded.length;
             storage.chunkAdded = growArray(memory, storage.chunkAdded, Float64Array, chunks, used).fill(0, used);
             storage.chunkChanged = shared ? storage.chunkAdded : growArray(memory, storage.chunkChanged, Float64Array, chunks, used).fill(0, used);
+            const blocks = blocksFor(capacity);
+            const usedBlocks = storage.blockAdded.length;
+            storage.blockAdded = growArray(memory, storage.blockAdded, Float64Array, blocks, usedBlocks).fill(0, usedBlocks);
+            storage.blockChanged = shared ? storage.blockAdded : growArray(memory, storage.blockChanged, Float64Array, blocks, usedBlocks).fill(0, usedBlocks);
         }
     }
     archetype.entities = growArray(memory, archetype.entities, Float64Array, capacity, count);
@@ -268,6 +338,47 @@ const grow = (memory: Memory, archetype: Archetype, capacity = archetype.capacit
     bump(archetype);
 };
 
+/**
+ * Lets go of an empty archetype's arrays, past what a new one holds: its columns, ticks and entities, each replaced
+ * by one of the first capacity, as when it was made. Its storages stay, so the edges that name them do.
+ */
+export const release = (memory: Memory, archetype: Archetype): void => {
+    if (archetype.capacity <= initialCapacity) return;
+    const capacity = initialCapacity;
+    for (const storage of archetype.storages) {
+        const { layout } = storage;
+        if (layout.kind === "linear" || layout.kind === "string") {
+            freeViews(memory, storage.views);
+            storage.views = columnOf(memory, layout, capacity);
+        }
+        if (storage.remote !== null) {
+            freeArray(memory, storage.tags);
+            storage.tags = allocateArray(memory, Uint32Array, capacity).fill(startTag);
+        }
+        storage.values.length = 0;
+        if (!storage.ticked) continue;
+        const aliased = storage.changed === storage.added;
+        freeArray(memory, storage.added);
+        if (!aliased) freeArray(memory, storage.changed);
+        freeArray(memory, storage.chunkAdded);
+        if (!aliased) freeArray(memory, storage.chunkChanged);
+        freeArray(memory, storage.blockAdded);
+        if (!aliased) freeArray(memory, storage.blockChanged);
+        // As it starts: new rows' ticks are written as they arrive.
+        storage.added = allocateArray(memory, Float64Array, capacity).fill(0);
+        storage.changed = aliased ? storage.added : allocateArray(memory, Float64Array, capacity).fill(0);
+        storage.chunkAdded = allocateArray(memory, Float64Array, chunksFor(capacity)).fill(0);
+        storage.chunkChanged = aliased ? storage.chunkAdded : allocateArray(memory, Float64Array, chunksFor(capacity)).fill(0);
+        storage.blockAdded = allocateArray(memory, Float64Array, blocksFor(capacity)).fill(0);
+        storage.blockChanged = aliased ? storage.blockAdded : allocateArray(memory, Float64Array, blocksFor(capacity)).fill(0);
+        storage.columnChanged = 0;
+    }
+    freeArray(memory, archetype.entities);
+    archetype.entities = allocateArray(memory, Float64Array, capacity);
+    archetype.capacity = capacity;
+    bump(archetype);
+};
+
 /** Grows once to fit `needed` rows, so a sync point adding many doesn't double over and over. */
 export const ensureCapacity = (memory: Memory, archetype: Archetype, needed: number): void => {
     if (needed <= archetype.capacity) return;
@@ -329,7 +440,10 @@ export const copyCell = (from: Storage, fromRow: number, to: Storage, toRow: num
     const changed = from.changed[fromRow];
     to.added[toRow] = added;
     to.changed[toRow] = changed;
-    // A chunk's tick is the newest of its rows, so a row moving in can raise it.
+    // A block's and a chunk's tick are the newest of their rows, so a row moving in can raise them.
+    const block = toRow >> blockShift;
+    if (added > to.blockAdded[block]) to.blockAdded[block] = added;
+    if (changed > to.blockChanged[block]) to.blockChanged[block] = changed;
     const chunk = toRow >> chunkShift;
     if (added > to.chunkAdded[chunk]) to.chunkAdded[chunk] = added;
     if (changed > to.chunkChanged[chunk]) to.chunkChanged[chunk] = changed;

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

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { describe, expect, it } from "vitest";
 import { allocateArray, growArray } from "./arrays.js";
 import { createMemory } from "./memory.js";

package/src/implementation/world/arrays.ts

@@ -1,4 +1,5 @@
-import { viewsOf, type Views } from '../../interface/registry/layout.js';
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { viewsOf, type Layout, type TypedArray, type Views } from '../../interface/registry/layout.js';
 import type { Memory } from './memory.js';
 
 export type ArrayConstructor<T> = {
@@ -41,3 +42,7 @@ export const freeViews = (memory: Memory, views: Views): void => freeArray(memor
 
 /** Views of no bytes, for components with nothing to store. */
 export const emptyViews: Views = viewsOf(new ArrayBuffer(0), 0, 0);
+
+/** A kernel's column of a component an archetype lacks, optional in its system: empty, so its reads give undefined. */
+export const absentColumn = (layout: Layout, source: { readonly kind: string; readonly leaf?: number }): TypedArray =>
+    source.kind === "field" && layout.kind === "linear" && source.leaf !== undefined ? emptyViews[layout.leaves[source.leaf].view] : emptyViews.f64;

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

@@ -0,0 +1,89 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import { arrivalsPosition, arrivalsWord, createArrivals, createDebts, logArrival, viewInMemory, viewOfArrivals } from "./arrivals.js";
+import { createMemory } from "./memory.js";
+
+/** A ring and the debts of a system matching archetypes 0 and 1, at points 5 and 10, its last run 10. */
+const setup = (shared = false) => {
+    const memory = createMemory(shared);
+    const ring = createArrivals(memory);
+    const points = [5, 10];
+    const matchOf = [0, 1, -1];
+    const debts = createDebts(points, matchOf, 0);
+    const view = viewOfArrivals(ring);
+    const read = (through: number, oldest = () => 5) => debts.read(view, through, 3, 10, oldest);
+    return { memory, ring, points, debts, view, read };
+};
+
+describe("arrivals", () => {
+    it("owes an archetype rows moved in the point of the archetype they came from, settled as it runs", () => {
+        const { ring, debts, read } = setup();
+        logArrival(ring, 0, 1, 11);
+        read(12);
+        expect(debts.sinceOf(1, 10)).toBe(5);
+        expect(debts.sinceOf(0, 5)).toBe(5);
+        debts.settle(1);
+        expect(debts.sinceOf(1, 10)).toBe(10);
+    });
+
+    it("carries a debt along moves in order, and a non-match's point is the last run", () => {
+        const { ring, debts, read } = setup();
+        // Into 2, which it doesn't match, from 0; then on to 1: rows from 0 came along.
+        logArrival(ring, 0, 2, 11);
+        logArrival(ring, 2, 1, 12);
+        read(13);
+        expect(debts.sinceOf(1, 10)).toBe(5);
+        const later = setup();
+        // In the other order, the rows reaching 1 came from 2 alone, whose rows the system never saw since its last run.
+        logArrival(later.ring, 2, 1, 11);
+        logArrival(later.ring, 0, 2, 12);
+        later.read(13);
+        expect(later.debts.sinceOf(1, 10)).toBe(10);
+        expect(later.debts.sinceOf(2, 10)).toBe(5);
+    });
+
+    it("reads only the syncs through the run's tick, the rest at the next", () => {
+        const { ring, debts, read } = setup();
+        logArrival(ring, 0, 1, 20);
+        read(19);
+        expect(debts.sinceOf(1, 10)).toBe(10);
+        read(20);
+        expect(debts.sinceOf(1, 10)).toBe(5);
+    });
+
+    it("keeps ticks past 2^32 whole", () => {
+        const { ring, debts, read } = setup();
+        logArrival(ring, 0, 1, 2 ** 32 + 3);
+        read(2 ** 32 + 2);
+        expect(debts.sinceOf(1, 10)).toBe(10);
+        read(2 ** 32 + 3);
+        expect(debts.sinceOf(1, 10)).toBe(5);
+    });
+
+    it("owes every archetype the oldest point once the ring overwrote unread entries, at that read and the next", () => {
+        const { ring, debts, view, read } = setup();
+        for (let k = 0; k <= 4096; k++) logArrival(ring, 1, 0, 11);
+        read(12, () => 3);
+        expect(debts.sinceOf(0, 5)).toBe(3);
+        expect(debts.sinceOf(1, 10)).toBe(3);
+        expect(debts.sinceOf(2, 10)).toBe(3);
+        debts.settle(1);
+        // Read from the ring's position on, owing the same floor again.
+        read(12, () => 9);
+        expect(debts.sinceOf(1, 10)).toBe(3);
+        debts.settle(1);
+        read(12, () => 9);
+        expect(debts.sinceOf(1, 10)).toBe(10);
+        expect(arrivalsPosition(view)).toBe(4097);
+    });
+
+    it("is found by a joined thread through the directory header in shared memory", () => {
+        const { memory, ring, debts } = setup(true);
+        logArrival(ring, 0, 1, 11);
+        const words = new Uint32Array(memory.memory.buffer);
+        const view = viewInMemory(words, words[arrivalsWord]);
+        expect(arrivalsPosition(view)).toBe(1);
+        debts.read(view, 11, 3, 10, () => 5);
+        expect(debts.sinceOf(1, 10)).toBe(5);
+    });
+});

package/src/implementation/world/arrivals.ts

@@ -0,0 +1,165 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { allocateArray } from './arrays.js';
+import type { Memory } from './memory.js';
+
+// The arrivals ring: rows moving between archetypes, a pair of archetypes per block of rows a sync point moves, for
+// systems with `where` and change filters, which keep a point per archetype. A row moved from an archetype the system
+// skipped holds changes it never saw, so its new archetype owes them: its rows pass the system's change filters since
+// the point of the archetype they came from, as of the move (`createDebts`). Written by the world's thread at sync
+// points, while a system with points registered or a joined thread holds claims, and read by each such system as it
+// runs, on the world's thread or a joined one, which finds it by the layout directory's header.
+
+/** The layout directory's header word holding the offset of the ring's control block, 0 before one is written. */
+export const arrivalsWord = 15;
+/**
+ * The control block's words: the entries written, modulo 2^32, stored after each; the capacity; the entries' offset;
+ * and how many times archetypes were reclaimed or reused, modulo 2^32 (`reclaim.ts`), which a joined thread's systems
+ * check to find their matches again.
+ */
+const positionWord = 0;
+const capacityWord = 1;
+const entriesOffsetWord = 2;
+export const membershipWord = 3;
+const controlWords = 16;
+/** An entry: the archetype rows moved from, the one they moved to, and the sync's tick, low and high words. */
+const entryWords = 4;
+/** A power of two, its entries a block of 64 KiB. A system further behind owes, for every archetype, its oldest point. */
+const capacity = 4096;
+
+/** The world's side of the ring: its control block and its entries, each a block of the memory when it's shared. */
+export type Arrivals = { readonly control: Uint32Array; readonly entries: Uint32Array };
+
+/** The ring, allocated with the first arrival logged. */
+export const createArrivals = (memory: Memory): Arrivals => {
+    const entries = allocateArray(memory, Uint32Array, capacity * entryWords).fill(0);
+    const control = allocateArray(memory, Uint32Array, controlWords).fill(0);
+    control[capacityWord] = capacity;
+    control[entriesOffsetWord] = entries.byteOffset;
+    if (memory.shared) Atomics.store(memory.header, arrivalsWord, control.byteOffset);
+    return { control, entries };
+};
+
+/** Logs rows moving from archetype `from` into `to` at a sync point of `tick`. */
+export const logArrival = ({ control, entries }: Arrivals, from: number, to: number, tick: number): void => {
+    const position = control[positionWord];
+    const at = (position & (capacity - 1)) * entryWords;
+    entries[at] = from;
+    entries[at + 1] = to;
+    entries[at + 2] = tick % 0x100000000;
+    entries[at + 3] = Math.floor(tick / 0x100000000);
+    Atomics.store(control, positionWord, (position + 1) >>> 0);
+};
+
+/** Where a reader finds the ring: its control block in `control` from word `controlAt`, its entries likewise. */
+export type ArrivalsView = { readonly control: Uint32Array; readonly controlAt: number; readonly entries: Uint32Array; readonly entriesAt: number };
+
+/** The world's thread's view of its ring. */
+export const viewOfArrivals = ({ control, entries }: Arrivals): ArrivalsView => ({ control, controlAt: 0, entries, entriesAt: 0 });
+
+/** A joined thread's view of the ring whose control block is at byte `offset` of the memory `words` cover. */
+export const viewInMemory = (words: Uint32Array, offset: number): ArrivalsView => {
+    const controlAt = offset >> 2;
+    return { control: words, controlAt, entries: words, entriesAt: words[controlAt + entriesOffsetWord] >> 2 };
+};
+
+/** How many times archetypes were reclaimed or reused, modulo 2^32: 0 before the ring is written. */
+export const membershipOf = (view: ArrivalsView | null): number => view === null ? 0 : Atomics.load(view.control, view.controlAt + membershipWord);
+
+/** The entries written so far, modulo 2^32, as a reader's cursor starts. */
+export const arrivalsPosition = (view: ArrivalsView | null): number => view === null ? 0 : Atomics.load(view.control, view.controlAt + positionWord);
+
+/**
+ * What archetypes owe a system with points: by archetype id, the oldest point rows moved into it since its own point
+ * were last seen at, by the system's point of each archetype they came from, or its last run for a non-match's. A row
+ * is counted changed in its new archetype only if it changed after that, so moves among archetypes the system saw cost
+ * nothing, and a run reads its arrivals once, however many archetypes it goes over.
+ */
+export type Debts = {
+    /** The point an archetype's rows pass change filters after: its own, or older for rows moved in from elsewhere. */
+    readonly sinceOf: (id: number, point: number) => number;
+    /**
+     * Reads arrivals through tick `through`, of `archetypes` archetypes, its last run `latest`; once the ring overwrote
+     * some unread, every archetype owes the oldest of `oldest()`, the system's oldest point, and what any owed.
+     */
+    readonly read: (view: ArrivalsView | null, through: number, archetypes: number, latest: number, oldest: () => number) => void;
+    /** Clears what an archetype owed, as its system runs over it. */
+    readonly settle: (id: number) => void;
+    /** The oldest debt, for what any archetype's rows may pass since; Infinity for none. */
+    readonly oldest: () => number;
+};
+
+/**
+ * The debts of a system with points: `points` by match, and `matchOf` by archetype id, its match or -1, its runner's,
+ * read as they are. Starts reading the ring at entry `start`.
+ */
+export const createDebts = (points: readonly number[], matchOf: readonly number[], start: number): Debts => {
+    /** By archetype id, Infinity for none. */
+    let owed = new Float64Array(64).fill(Infinity);
+    const ensure = (archetypes: number): void => {
+        if (archetypes <= owed.length) return;
+        let length = owed.length * 2;
+        while (length < archetypes) length *= 2;
+        const grown = new Float64Array(length).fill(Infinity);
+        grown.set(owed);
+        owed = grown;
+    };
+    let cursor = start;
+    /**
+     * Once the ring overwrote unread entries, the oldest point as of then, which every archetype owes again at the next
+     * read too: entries skipped may be of syncs after the run's, whose rows that run's archetypes didn't have yet.
+     */
+    let floor = Infinity;
+    const oldestOwed = (): number => {
+        let oldest = Infinity;
+        for (let id = 0; id < owed.length; id++) if (owed[id] < oldest) oldest = owed[id];
+        return oldest;
+    };
+    const owe = (archetypes: number, point: number): void => {
+        for (let id = 0; id < archetypes; id++) if (point < owed[id]) owed[id] = point;
+    };
+    /** Reads entries from the cursor through `through`; false when the ring overwrote some unread, before or while. */
+    const readThrough = (view: ArrivalsView, through: number, latest: number): boolean => {
+        const { control, controlAt, entries, entriesAt } = view;
+        const size = control[controlAt + capacityWord];
+        const pending = (Atomics.load(control, controlAt + positionWord) - cursor) >>> 0;
+        if (pending > size) return false;
+        let read = 0;
+        let debts = owed;
+        const mask = size - 1;
+        for (; read < pending; read++) {
+            const at = entriesAt + ((cursor + read) & mask) * entryWords;
+            if (entries[at + 2] + entries[at + 3] * 0x100000000 > through) break;
+            const from = entries[at];
+            const to = entries[at + 1];
+            if (from >= debts.length || to >= debts.length) {
+                ensure(Math.max(from, to) + 1);
+                debts = owed;
+            }
+            const m = matchOf[from];
+            let point = m >= 0 ? points[m] : latest;
+            if (debts[from] < point) point = debts[from];
+            if (point < debts[to]) debts[to] = point;
+        }
+        if (((Atomics.load(control, controlAt + positionWord) - cursor) >>> 0) > size) return false;
+        cursor = (cursor + read) >>> 0;
+        return true;
+    };
+    return {
+        sinceOf: (id, point) => id < owed.length && owed[id] < point ? owed[id] : point,
+        read: (view, through, archetypes, latest, oldest) => {
+            if (view === null) return;
+            ensure(archetypes);
+            const skipped = floor;
+            floor = Infinity;
+            if (skipped !== Infinity) owe(archetypes, skipped);
+            if (readThrough(view, through, latest)) return;
+            cursor = arrivalsPosition(view);
+            floor = Math.min(oldest(), oldestOwed(), skipped);
+            owe(archetypes, floor);
+        },
+        settle: id => {
+            if (id < owed.length) owed[id] = Infinity;
+        },
+        oldest: oldestOwed,
+    };
+};

package/src/implementation/world/async-loading.test.ts

@@ -1,5 +1,6 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { expect, it } from "vitest";
-import { Component, Entity, Finalizer, Resource, Rule, System, World } from "../../index.js";
+import { Entity, Finalizer, Rule, type Schema, System, World } from "../../index.js";
 import { Observe } from "../../observe/index.js";
 import { createWorld } from "../index.js";
 
@@ -17,28 +18,16 @@ declare module "@adobe/ecs" {
         [meshSource]: { type: string };
         [hidden]: { type: true };
         /** The token of the slot's load; a new one each time the slot starts over. */
-        [meshSlot]: { type: number; derived: true };
+        [meshSlot]: { type: Schema.Type<{ type: "integer" }>; derived: true; default: 0 };
         /** The loaded mesh's handle, which exists only while its slot does. */
-        [meshReady]: { type: number; within: typeof meshSlot };
+        [meshReady]: { type: Schema.Type<{ type: "integer" }>; within: typeof meshSlot };
     }
     interface Resources {
-        [nextToken]: { type: number };
-        [requests]: { type: readonly { readonly entity: Entity; readonly token: number; readonly path: string }[] };
+        [nextToken]: { type: Schema.Type<{ type: "integer" }>; default: 1 };
+        [requests]: { type: Schema.Type<{ type: "array"; items: { type: "object"; properties: { entity: { type: "integer"; format: "entity" }; token: { type: "integer" }; path: { type: "string" } } } }>; default: [] };
     }
 }
 
-Component.register(meshSource, { type: { type: "string" } });
-Component.register(hidden, { type: { const: true } });
-Component.register(meshSlot, { type: { type: "integer", default: 0 }, derived: true });
-Component.register(meshReady, { type: { type: "integer" }, within: meshSlot });
-Resource.register(nextToken, { type: { type: "integer", default: 1 } });
-Resource.register(requests, {
-    type: {
-        type: "array",
-        items: { type: "object", properties: { entity: Entity.schema, token: { type: "integer" }, path: { type: "string" } } },
-        default: [],
-    },
-});
 
 /** Meshes loaded outside the world, by handle: as GPU buffers are. */
 const loaded = new Map<number, string>();
@@ -49,13 +38,11 @@ const load = async (path: string): Promise<number> => {
 };
 
 // 1. A rule derives a slot for every visible entity with a mesh source.
-Rule.create({ name: "asyncLoading/slots", components: { has: [meshSource], not: [hidden] }, derive: [meshSlot] });
+Rule.create({ components: { with: [meshSource], not: [hidden] }, derive: [meshSlot] });
 
 // 2. Each new slot gets a fresh token, and its load is requested; the application starts requested loads.
 const request = System.create({
-    name: "asyncLoading/request",
-    components: { read: [meshSource], write: [meshSlot], added: [meshSlot] },
-    resources: { write: [nextToken, requests] },
+    components: { with: [meshSource, meshSlot], added: [meshSlot] },
 }, (row, { resources }) => {
     const token = resources[nextToken];
     resources[nextToken] = token + 1;
@@ -65,22 +52,20 @@ const request = System.create({
 
 // 3. A completed load arrives as a run of its own. A slot whose token still matches gets the mesh; a stale one releases it.
 const apply = System.create({
-    name: "asyncLoading/apply",
-    input: { type: "object", properties: { entity: Entity.schema, token: { type: "integer" }, handle: { type: "integer" } } },
-    lookup: { slots: { read: [meshSlot] } },
-}, ({ input, lookup, commands }) => {
+    lookup: { slots: { with: [meshSlot] } },
+}, ({ lookup, commands }, input: { readonly entity: Entity; readonly token: number; readonly handle: number }) => {
     if (lookup.slots(input.entity)?.[meshSlot] === input.token) commands.add(input.entity, meshReady, input.handle);
     else loaded.delete(input.handle);
 });
 
 // 4. When the slot goes, its mesh goes with it, and the finalizer releases what was loaded.
-Finalizer.create({ name: "asyncLoading/release", components: { read: [meshReady] } }, row => { loaded.delete(row[meshReady]); });
+Finalizer.create({ components: { with: [meshReady] } }, row => { loaded.delete(row[meshReady]); });
 
-const spawn = System.create({ name: "asyncLoading/spawn" }, ({ commands }) => {
+const spawn = System.create({}, ({ commands }) => {
     commands.spawn([meshSource])({ [meshSource]: "ship.glb" });
     commands.spawn([meshSource])({ [meshSource]: "rock.glb" });
 });
-const hide = System.create({ name: "asyncLoading/hide", input: { type: "object", properties: { entity: Entity.schema } } }, ({ input, commands }) => {
+const hide = System.create({}, ({ commands }, input: { readonly entity: Entity }) => {
     commands.add(input.entity, hidden);
 });
 

package/src/implementation/world/attach-kernel.test.ts

@@ -1,9 +1,17 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { expect, it } from "vitest";
+import { kernelOf } from "./attach-kernel.js";
 
 it("rejects a kernel lookup of a string, which kernels don't read, where the kernel is declared", async () => {
-    await expect(import("./kernel-lookup.test-helper.js")).rejects.toThrow(`Kernel "kernelLookupTest/labels": a lookup reads "kernelLookupTest/label", a string, which kernels don't read yet.`);
+    await expect(import("./kernel-lookup.test-helper.js")).rejects.toThrow(`a lookup reads "kernelLookupTest/label", a string, which kernels don't read yet.`);
 });
 
 it("rejects a compiled kernel that doesn't match its schemas where the kernel is declared", async () => {
-    await expect(import("./kernel-path.test-helper.js")).rejects.toThrow(`Kernel "kernelPathTest/beyond": "kernelPathTest/pair" has no scalar at [2]; destructure tuples and structs or index their fields.`);
+    await expect(import("./kernel-path.test-helper.js")).rejects.toThrow(`"kernelPathTest/pair" has no scalar at [2]; destructure tuples and structs or index their fields.`);
+});
+
+it("compiles an unflagged system whose body fits, and runs as written one whose kernel wouldn't match its schemas", async () => {
+    const { doubled, labels } = await import("./kernel-tried.test-helper.js");
+    expect(kernelOf(doubled)).toBeDefined();
+    expect(kernelOf(labels)).toBeUndefined();
 });