@adobe/ecs 0.0.0-stage → 0.1.0

package/src/implementation/world/layout-directory.fixture.ts

@@ -0,0 +1,186 @@
+import { Component } from "../../interface/component/component.js";
+import { Entity } from "../../interface/entity/entity.js";
+import { System } from "../../interface/system/system.js";
+import type { World } from "../../interface/world/world.js";
+import { workers } from "../../interface/resources/workers.js";
+import { readEach, select } from "./reads.test-helper.js";
+import { createWorld } from "./create.js";
+import { countingWorkers } from "./platforms.test-helper.js";
+
+/** Scenarios of workers reading layouts from the directory, run built in node and from source in chromium. */
+
+const value = Symbol("layoutDirectoryTest/value");
+const target = Symbol("layoutDirectoryTest/target");
+const seen = Symbol("layoutDirectoryTest/seen");
+const child = Symbol("layoutDirectoryTest/child");
+const tag0 = Symbol("layoutDirectoryTest/tag0");
+const tag1 = Symbol("layoutDirectoryTest/tag1");
+const tag2 = Symbol("layoutDirectoryTest/tag2");
+const tag3 = Symbol("layoutDirectoryTest/tag3");
+const tag4 = Symbol("layoutDirectoryTest/tag4");
+const tag5 = Symbol("layoutDirectoryTest/tag5");
+const tag6 = Symbol("layoutDirectoryTest/tag6");
+const tags = [tag0, tag1, tag2, tag3, tag4, tag5, tag6] as const;
+
+declare module "@adobe/ecs" {
+    export interface Components {
+        [value]: { type: number };
+        [target]: { type: Entity };
+        [seen]: { type: number };
+        [child]: { type: true };
+        [tag0]: { type: true };
+        [tag1]: { type: true };
+        [tag2]: { type: true };
+        [tag3]: { type: true };
+        [tag4]: { type: true };
+        [tag5]: { type: true };
+        [tag6]: { type: true };
+    }
+}
+
+Component.register(value, { type: { type: "number", precision: 1 } });
+Component.register(target, { type: Entity.schema });
+Component.register(seen, { type: { type: "number", precision: 1 } });
+Component.register(child, { type: { const: true } });
+Component.register(tag0, { type: { const: true } });
+Component.register(tag1, { type: { const: true } });
+Component.register(tag2, { type: { const: true } });
+Component.register(tag3, { type: { const: true } });
+Component.register(tag4, { type: { const: true } });
+Component.register(tag5, { type: { const: true } });
+Component.register(tag6, { type: { const: true } });
+
+/** The component lists of 100 archetypes: `value` with each of the first 100 combinations of the tags. */
+const lists = Array.from({ length: 100 }, (_, i): (typeof value | (typeof tags)[number])[] => [value, ...tags.filter((_, bit) => (i & (1 << bit)) !== 0)]);
+
+/** Spawns `count` entities into each of the 100 archetypes. */
+const fill = System.create({ name: "layoutDirectoryTest/fill", input: { type: "object", properties: { count: { type: "integer" } } } }, ({ input, commands }) => {
+    for (const list of lists) for (let i = 0; i < input.count; i++) commands.spawn(list)({ [value]: 0 });
+});
+
+const bump = System.create({ name: "layoutDirectoryTest/bump", kernel: "cpu", components: { write: [value] } }, row => {
+    row[value] = row[value] + 1;
+});
+
+const total = { sum: 0, count: 0 };
+/** Sums every value on the world's thread, so it reads what workers wrote. */
+const sum = System.create({ name: "layoutDirectoryTest/sum", components: { read: [value] } }, row => {
+    total.sum += row[value];
+    total.count++;
+});
+
+/** Entities whose values the lookups read, recorded as they spawn. */
+const spawned: Entity[] = [];
+const make = System.create({ name: "layoutDirectoryTest/make" }, ({ commands }) => {
+    for (let i = 0; i < 64; i++) commands.spawn([target, seen])({ [target]: Entity.none, [seen]: 0 });
+    commands.spawn([value])({ [value]: -1 });
+});
+const spawnMany = System.create({ name: "layoutDirectoryTest/spawnMany", input: { type: "object", properties: { count: { type: "integer" } } } }, ({ input, commands }) => {
+    for (let i = 0; i < input.count; i++) spawned.push(commands.spawn([value])({ [value]: i }));
+});
+/** Aims each looker at one of the last spawned entities. */
+let aimed = 0;
+const aim = System.create({ name: "layoutDirectoryTest/aim", components: { write: [target] } }, row => {
+    row[target] = spawned[spawned.length - 1 - aimed++];
+});
+const despawnValues = System.create({ name: "layoutDirectoryTest/despawnValues", components: { has: [value], not: [child] } }, (row, { commands }) => {
+    commands.despawn(row.entity);
+});
+/** Lookups from workers. */
+const look = System.create({
+    name: "layoutDirectoryTest/look",
+    kernel: "cpu",
+    components: { read: [target], write: [seen] },
+    lookup: { targets: { read: [value] } },
+}, (row, { lookup: { targets } }) => {
+    const other = targets(row[target]);
+    row[seen] = other === null ? -1 : other[value];
+});
+/** Spawns from workers: a child per looker. */
+const breed = System.create({ name: "layoutDirectoryTest/breed", kernel: "cpu", components: { read: [seen] } }, (row, { commands }) => {
+    commands.spawn([value, child])({ [value]: row[seen] });
+});
+
+/** Runs `use` with a world, then disposes it. */
+const using = async <T>(world: World, use: (world: World) => Promise<T>): Promise<T> => {
+    try {
+        return await use(world);
+    }
+    finally {
+        await world.dispose();
+    }
+};
+
+const totals = async (world: World): Promise<{ sum: number; count: number }> => {
+    total.sum = total.count = 0;
+    await world.run(sum);
+    return { ...total };
+};
+
+/** Rows that spawn into each of the 100 archetypes in each round after the first, which spawns 1. */
+export const rounds: readonly number[] = [16, 32, 64, 128, 256];
+
+/** 100 archetypes grown over `rounds`, each round bumped by workers: layout messages after the first round, and the totals. */
+export const grown = async (wasm: boolean): Promise<{ readonly messages: number; readonly totals: { sum: number; count: number } }> => {
+    const counting = countingWorkers();
+    return using(createWorld({ [workers]: 3 }, { minimumChunk: 16, wasm, pool: counting.platform }), async world => {
+        await world.run(fill, { count: 1 });
+        await world.run(bump);
+        const before = counting.posted("layout");
+        for (const count of rounds) {
+            await world.run(fill, { count });
+            await world.run(bump);
+        }
+        return { messages: counting.posted("layout") - before, totals: await totals(world) };
+    });
+};
+
+/**
+ * Lookups and spawns from workers once the entity table grows from 64 entities past 10,000 and its free list past
+ * 10,000 indexes: layout messages meanwhile, what the lookers saw, and the children workers spawned.
+ */
+export const tableGrown = async (): Promise<{ readonly messages: number; readonly seen: readonly (number | null)[]; readonly children: number; readonly values: readonly (number | null)[] }> => {
+    spawned.length = 0;
+    aimed = 0;
+    const counting = countingWorkers();
+    return using(createWorld({ [workers]: 2 }, { minimumChunk: 16, wasm: false, pool: counting.platform }), async world => {
+        await world.run(make);
+        await world.run(look);
+        await world.run(breed);
+        const lookers = await select(world, { required: [seen] });
+        const before = counting.posted("layout");
+        await world.run(spawnMany, { count: 10_000 });
+        await world.run(aim);
+        await world.run(look);
+        const seenValues = await readEach(world, lookers, seen);
+        await world.run(despawnValues);
+        await world.run(breed);
+        const messages = counting.posted("layout") - before;
+        const children = await select(world, { required: [child] });
+        return { messages, seen: seenValues, children: new Set(children).size, values: await readEach(world, children, value) };
+    });
+};
+
+/** Workers' kernels once memory grows between runs: how often it grew, layout messages meanwhile, and the totals. */
+export const memoryGrown = async (wasm: boolean): Promise<{ readonly grows: number; readonly messages: number; readonly totals: { sum: number; count: number } }> => {
+    const counting = countingWorkers();
+    return using(createWorld({ [workers]: 2 }, { minimumChunk: 16, wasm, pool: counting.platform }), async world => {
+        await world.run(fill, { count: 1 });
+        await world.run(bump);
+        let grows = 0;
+        const original = WebAssembly.Memory.prototype.grow;
+        WebAssembly.Memory.prototype.grow = function (this: WebAssembly.Memory, delta: number) {
+            grows++;
+            return original.call(this, delta);
+        };
+        const before = counting.posted("layout");
+        try {
+            await world.run(fill, { count: 2_000 });
+            await world.run(bump);
+        }
+        finally {
+            WebAssembly.Memory.prototype.grow = original;
+        }
+        return { grows, messages: counting.posted("layout") - before, totals: await totals(world) };
+    });
+};

package/src/implementation/world/layout-directory.ts

@@ -0,0 +1,230 @@
+import { allocateArray, growArray } from './arrays.js';
+import type { Archetype } from './archetype.js';
+import type { Entities } from './entities.js';
+import type { Memory } from './memory.js';
+
+/**
+ * Where everything in the shared memory is, for other threads: a header at offset 0 that never moves, a table of
+ * archetype record offsets by archetype id, and a record per archetype. Every word is a `Uint32`, since memory reaches
+ * 4 GiB. The world's thread keeps its JS fields as the source of truth and writes records only at flushes, each
+ * record's version last, with `Atomics.store`; a reader checks a record's version before using what it cached.
+ *
+ * Header words: the memory's length in pages (`memory.ts`), the table's offset and length, the structure epoch, then
+ * the entity-table record: its `cursor` offset, which never moves, `free` offset and capacity, `archetype`, `row` and
+ * `generation` offsets and their capacity, and its version; then the resource entity's index plus one, 0 for none. The
+ * table's length is `cursor[2]`.
+ *
+ * The structure epoch is odd from the start of each sync point that applies anything until its directory writes at the
+ * end, and even otherwise. A thread reading entity locations outside a task reads while it's even and checks it again
+ * after, retrying on a change, and waits on it while it's odd, counted in the waiters word first; the world notifies
+ * waiting readers when it turns even.
+ */
+export const tableOffsetWord = 1;
+export const tableLengthWord = 2;
+export const structureWord = 3;
+export const entitiesWord = 4;
+export const cursorField = 0;
+export const freeField = 1;
+export const freeCapacityField = 2;
+export const archetypeField = 3;
+export const rowField = 4;
+export const generationField = 5;
+export const capacityField = 6;
+export const entitiesVersionField = 7;
+export const resourceEntityWord = 12;
+/** Readers waiting on the structure epoch, so the world notifies only when one is. */
+export const structureWaitersWord = 13;
+
+/**
+ * An archetype record: its capacity, `entities` offset, storage count, version, flags and row count, then per storage
+ * its component number, flags, column, `added`, `changed`, `chunkAdded` and `chunkChanged` offsets, and chunk count.
+ * Offsets a storage doesn't have are 0. A record is allocated once, since an archetype's storages are fixed, and never
+ * moves. Its count is written at flushes while a joined thread may read it, for archetypes whose count changed.
+ */
+export const recordCapacity = 0;
+export const recordEntities = 1;
+export const recordStorages = 2;
+export const recordVersion = 3;
+export const recordFlags = 4;
+export const recordCount = 5;
+export const recordWords = 6;
+/** Record flags: it's the resource archetype, of the entity resources live on. */
+export const resourceFlag = 1;
+/** Record flags: it holds reports, which only queries that require a component see. */
+export const metaFlag = 2;
+export const storageWords = 8;
+export const storageComponent = 0;
+export const storageFlags = 1;
+export const storageColumn = 2;
+export const storageAdded = 3;
+export const storageChanged = 4;
+export const storageChunkAdded = 5;
+export const storageChunkChanged = 6;
+export const storageChunks = 7;
+/**
+ * Storage flags: it keeps ticks; it has a column in linear memory, a string's of handles included; its objects are a joined thread's, whose number is
+ * the flags from `threadShift` on, and its column holds each row's tag (`move-log.ts`).
+ */
+export const tickedFlag = 1;
+export const linearFlag = 2;
+export const remoteFlag = 4;
+export const threadShift = 8;
+
+/** The world's side of the directory. */
+export type LayoutDirectory = {
+    readonly memory: Memory;
+    readonly header: Uint32Array;
+    /** The header as signed words, which `Atomics.notify` takes. */
+    readonly words: Int32Array;
+    table: Uint32Array;
+    /** By archetype id, its record, once flushed. */
+    readonly records: (Uint32Array | undefined)[];
+    /** The entity table's version as last flushed. */
+    entities: number;
+    /** Whether a joined thread may read entity locations outside a task, so sync points keep the structure epoch. */
+    guarded: boolean;
+};
+
+const initialTable = 64;
+
+/** A directory for shared memory; without it, no other thread reads the memory, so there's none. */
+export const createLayoutDirectory = (memory: Memory): LayoutDirectory | null => {
+    if (!memory.shared) return null;
+    const table = allocateArray(memory, Uint32Array, initialTable).fill(0);
+    const { header } = memory;
+    header[tableOffsetWord] = table.byteOffset;
+    header[tableLengthWord] = 0;
+    return { memory, header, words: new Int32Array(header.buffer, header.byteOffset, header.length), table, records: [], entities: -1, guarded: false };
+};
+
+const writeEntities = ({ header }: LayoutDirectory, entities: Entities): void => {
+    header[entitiesWord + cursorField] = entities.cursor.byteOffset;
+    header[entitiesWord + freeField] = entities.free.byteOffset;
+    header[entitiesWord + freeCapacityField] = entities.free.length;
+    header[entitiesWord + archetypeField] = entities.archetype.byteOffset;
+    header[entitiesWord + rowField] = entities.row.byteOffset;
+    header[entitiesWord + generationField] = entities.generation.byteOffset;
+    header[entitiesWord + capacityField] = entities.archetype.length;
+    Atomics.store(header, entitiesWord + entitiesVersionField, entities.version);
+};
+
+/** The record for an archetype, allocated and entered in the table the first time it's flushed. */
+const recordOf = (directory: LayoutDirectory, archetype: Archetype): Uint32Array => {
+    const existing = directory.records[archetype.id];
+    if (existing !== undefined) return existing;
+    const { memory, header } = directory;
+    if (archetype.id >= directory.table.length) {
+        const used = directory.table.length;
+        let length = used * 2;
+        while (length <= archetype.id) length *= 2;
+        directory.table = growArray(memory, directory.table, Uint32Array, length, used).fill(0, used);
+        header[tableOffsetWord] = directory.table.byteOffset;
+    }
+    const record = allocateArray(memory, Uint32Array, recordWords + archetype.storages.length * storageWords);
+    directory.records[archetype.id] = record;
+    return record;
+};
+
+const writeArchetype = (directory: LayoutDirectory, archetype: Archetype): void => {
+    const fresh = directory.records[archetype.id] === undefined;
+    const record = recordOf(directory, archetype);
+    record[recordCapacity] = archetype.capacity;
+    record[recordEntities] = archetype.entities.byteOffset;
+    record[recordStorages] = archetype.storages.length;
+    record[recordFlags] = (archetype.resource ? resourceFlag : 0) | (archetype.meta ? metaFlag : 0);
+    record[recordCount] = archetype.count;
+    for (let s = 0; s < archetype.storages.length; s++) {
+        const storage = archetype.storages[s];
+        const base = recordWords + s * storageWords;
+        // A string's column of handles is in linear memory too, its records with it.
+        const linear = storage.layout.kind === "linear" || storage.layout.kind === "string";
+        const { remote } = storage;
+        record[base + storageComponent] = storage.component;
+        record[base + storageFlags] = (storage.ticked ? tickedFlag : 0) | (linear ? linearFlag : 0) | (remote === null ? 0 : remoteFlag | (remote.thread << threadShift));
+        record[base + storageColumn] = linear ? storage.views.u8.byteOffset : remote === null ? 0 : storage.tags.byteOffset;
+        record[base + storageAdded] = storage.ticked ? storage.added.byteOffset : 0;
+        record[base + storageChanged] = storage.ticked ? storage.changed.byteOffset : 0;
+        record[base + storageChunkAdded] = storage.ticked ? storage.chunkAdded.byteOffset : 0;
+        record[base + storageChunkChanged] = storage.ticked ? storage.chunkChanged.byteOffset : 0;
+        record[base + storageChunks] = storage.chunkAdded.length;
+    }
+    Atomics.store(record, recordVersion, archetype.version);
+    // Entered once complete, so a reader that finds it finds a whole record.
+    if (fresh) directory.table[archetype.id] = record.byteOffset;
+};
+
+/**
+ * Writes the records of archetypes created or bumped since the last flush, the resource archetype's flagged, and the
+ * entity table's and the resource entity's if they moved. Runs at the end of each sync point and wherever registration
+ * changes layouts; allocates only for new records.
+ */
+export const flushDirectory = (directory: LayoutDirectory | null, bumped: Archetype[], archetypes: readonly Archetype[], entities: Entities, resourceEntity: number, counted: Archetype[]): void => {
+    if (directory === null) return;
+    const resourceWord = resourceEntity < 0 ? 0 : (resourceEntity >>> 0) + 1;
+    if (directory.header[resourceEntityWord] !== resourceWord) Atomics.store(directory.header, resourceEntityWord, resourceWord);
+    if (counted.length > 0) flushCounts(directory, counted);
+    if (bumped.length === 0 && entities.version === directory.entities) return;
+    if (entities.version !== directory.entities) {
+        writeEntities(directory, entities);
+        directory.entities = entities.version;
+    }
+    if (bumped.length === 0) return;
+    for (let k = 0; k < bumped.length; k++) {
+        const archetype = bumped[k];
+        archetype.listed = false;
+        writeArchetype(directory, archetype);
+    }
+    bumped.length = 0;
+    Atomics.store(directory.header, tableLengthWord, archetypes.length);
+};
+
+/**
+ * A flush between sync points, as registration's: under the structure epoch, as a sync point's is, while a joined
+ * thread may read records.
+ */
+export const flushBetween = (directory: LayoutDirectory | null, bumped: Archetype[], archetypes: readonly Archetype[], entities: Entities, resourceEntity: number, counted: Archetype[]): void => {
+    if (directory === null) return;
+    const guarding = directory.guarded && (bumped.length > 0 || counted.length > 0 || entities.version !== directory.entities);
+    if (guarding) Atomics.add(directory.words, structureWord, 1);
+    flushDirectory(directory, bumped, archetypes, entities, resourceEntity, counted);
+    if (guarding) endStructure(directory);
+};
+
+/** Writes the counts of archetypes whose count changed, those with records; a new archetype's comes with its record. */
+const flushCounts = (directory: LayoutDirectory, counted: Archetype[]): void => {
+    for (let k = 0; k < counted.length; k++) {
+        const archetype = counted[k];
+        archetype.counted = false;
+        const record = directory.records[archetype.id];
+        if (record !== undefined) record[recordCount] = archetype.count;
+    }
+    counted.length = 0;
+};
+
+/** Lists an archetype whose count changed for the next flush, while a joined thread may read counts. */
+export const countChanged = (counted: Archetype[], archetype: Archetype): void => {
+    if (archetype.counted) return;
+    archetype.counted = true;
+    counted.push(archetype);
+};
+
+/**
+ * At the start of a sync point that applies anything, once a joined thread may read locations: the structure epoch
+ * turns odd, by an exchange, so the writes after it can't be seen before it.
+ */
+export const beginStructure = (directory: LayoutDirectory | null): void => {
+    if (directory !== null && directory.guarded) Atomics.add(directory.words, structureWord, 1);
+};
+
+/**
+ * Once a sync point's directory writes are done: the structure epoch turns even, by a store, since only the world
+ * writes it, waking readers only when one waits on it.
+ */
+export const endStructure = (directory: LayoutDirectory | null): void => {
+    if (directory === null) return;
+    const { words } = directory;
+    const epoch = words[structureWord];
+    if ((epoch & 1) === 0) return;
+    Atomics.store(words, structureWord, epoch + 1);
+    if (Atomics.load(words, structureWaitersWord) !== 0) Atomics.notify(words, structureWord);
+};

package/src/implementation/world/lifetime.cases.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from "vitest";
+import type * as Fixture from "./lifetime.fixture.js";
+
+/** What kernels hold across the pool: the cases, over the fixture built for node or from source. */
+export const lifetimeCases = (load: () => Promise<typeof Fixture>) => describe("what a kernel holds", () => {
+    it("lives as long as the kernel: new values of one kernel leave every table as it was, on every worker too", async () => {
+        const fixture = await load();
+        const { before, after, collected, total, ran } = await fixture.freshKernels(200);
+        expect(total).toBe(fixture.rows - 1);
+        // Its report counts the kernel's run and the workers it ran on.
+        expect({ systems: ran.systems, workers: ran.workers, joined: ran.joined, gpu: ran.gpu }).toEqual({ systems: 1, workers: 2, joined: 0, gpu: false });
+        expect(before.workers).toHaveLength(2);
+        // Workers keep a kernel by its code, so new values of it add nothing there, collected or not.
+        expect(after.workers).toEqual(before.workers);
+        // The world's thread releases what a value held once it's collected, where a collector is exposed.
+        if (collected) expect(after).toEqual(before);
+    }, 120_000);
+});

package/src/implementation/world/lifetime.fixture.ts

@@ -0,0 +1,77 @@
+import { Component } from "../../interface/component/component.js";
+import { Entity } from "../../interface/entity/entity.js";
+import { Resource } from "../../interface/resource/resource.js";
+import { System } from "../../interface/system/system.js";
+import { workers } from "../../interface/resources/workers.js";
+import { createWorld, type Tables } from "./create.js";
+import { collector, freshKernel, tablesAfterCollecting } from "./lifetime.test-helper.js";
+import { readResource } from "./reads.test-helper.js";
+import { fillReports, runOf } from "./reports.test-helper.js";
+import { Report } from "../../interface/report/report.js";
+
+/** Scenarios of what kernels hold across the pool, run built in node and from source in chromium. */
+
+const value = Symbol("lifetimeFixture/value");
+const target = Symbol("lifetimeFixture/target");
+const out = Symbol("lifetimeFixture/out");
+const total = Symbol("lifetimeFixture/total");
+
+declare module "@adobe/ecs" {
+    export interface Components {
+        [value]: { type: number };
+        [target]: { type: Entity };
+        [out]: { type: number };
+    }
+    export interface Resources {
+        [total]: { type: number; reduce: "+" };
+    }
+}
+
+Component.register(value, { type: { type: "number", precision: 1 } });
+Component.register(target, { type: Entity.schema });
+Component.register(out, { type: { type: "number", precision: 1 } });
+Resource.register(total, { type: { type: "number", default: 0 }, reduce: "+" });
+
+export const rows = 4_096;
+
+const seed = System.create({ name: "lifetimeFixture/seed" }, ({ commands }) => {
+    let previous = commands.spawn([value])({ [value]: 0 });
+    for (let i = 1; i < rows; i++) previous = commands.spawn([value, target, out])({ [value]: i, [target]: previous, [out]: 0 });
+});
+
+/** A kernel that holds what kernels can: a lookup's directory, reduction partials and its load on each worker. */
+const measure = System.create({
+    name: "lifetimeFixture/measure",
+    kernel: "cpu",
+    components: { read: [value, target], write: [out] },
+    lookup: { targets: { read: [value] } },
+    reduce: { [total]: "+" },
+}, (row, { lookup: { targets }, reduce }) => {
+    const other = targets(row[target]);
+    row[out] = other === null ? -1 : row[value] - other[value];
+    reduce[total](1);
+});
+
+/**
+ * Runs `count` new values of a kernel, as a module evaluated again makes, each once, on two workers: the world's tables
+ * before and after, once collected where a collector is exposed; whether one was; and the last run's total.
+ */
+export const freshKernels = async (count: number): Promise<{ readonly before: Tables; readonly after: Tables; readonly collected: boolean; readonly total: number; readonly ran: Report[typeof Report.run] }> => {
+    const world = createWorld({ [workers]: 2 }, { minimumChunk: 64 });
+    try {
+        await world.run(seed);
+        // Past the runs that spawn reports, which grow the entity table.
+        await fillReports(world);
+        await world.run(measure);
+        await world.run(freshKernel(measure));
+        await world.run(measure);
+        const before = await tablesAfterCollecting(world);
+        for (let k = 0; k < count; k++) await world.run(freshKernel(measure));
+        const last = await world.run(measure);
+        const after = await tablesAfterCollecting(world);
+        return { before, after, collected: collector() !== null, total: await readResource(world, total), ran: await runOf(world, last) };
+    }
+    finally {
+        await world.dispose();
+    }
+};

package/src/implementation/world/lifetime.test-helper.ts

@@ -0,0 +1,78 @@
+import type { System } from "../../interface/system/system.js";
+import type { Leaf } from "../../interface/system/leaf.js";
+import { definitionOf } from "../../interface/registry/index.js";
+import { claimSystem } from "../../interface/registry/program.js";
+import { attachKernel, kernelOf } from "./attach-kernel.js";
+import type { CreatedWorld, Tables } from "./create.js";
+
+/**
+ * What finishes V8's optimizing compiles in flight, where node runs with `--allow-natives-syntax`; null elsewhere. A
+ * compile on a background thread holds the objects it read, systems among them, as roots until it's installed, which
+ * a busy machine can put off past any number of collections.
+ */
+const compiles = (): (() => void) | null => {
+    try {
+        // A string, since `%` calls parse only with the flag, and not at all in TypeScript.
+        const finish: unknown = new Function("%FinalizeOptimization();");
+        return typeof finish === "function" ? () => { Reflect.apply(finish, undefined, []); } : null;
+    }
+    catch {
+        return null;
+    }
+};
+
+/**
+ * The garbage collector, once optimizing compiles in flight are finished, where node runs with `--expose-gc` and
+ * `--allow-natives-syntax`; null elsewhere, as in a browser.
+ */
+export const collector = (): (() => void) | null => {
+    const gc: unknown = Reflect.get(globalThis, "gc");
+    const finish = compiles();
+    if (typeof gc !== "function" || finish === null) return null;
+    return () => {
+        finish();
+        Reflect.apply(gc, undefined, []);
+    };
+};
+
+const task = (): Promise<void> => new Promise(resolve => setTimeout(resolve, 0));
+
+/**
+ * Collects garbage, then lets finalization callbacks run, a few times over, since a callback may release what the next
+ * collection frees. Does nothing without a collector.
+ */
+export const collect = async (): Promise<void> => {
+    const gc = collector();
+    if (gc === null) return;
+    for (let round = 0; round < 4; round++) {
+        await task();
+        gc();
+    }
+    await task();
+};
+
+/** The JS heap's used bytes after collecting, where node exposes the collector. */
+export const heapAfterCollecting = async (): Promise<number> => {
+    await collect();
+    return process.memoryUsage().heapUsed;
+};
+
+/** A world's tables once garbage is collected. */
+export const tablesAfterCollecting = async (world: CreatedWorld): Promise<Tables> => {
+    await collect();
+    return world.tables();
+};
+
+/**
+ * A new value of a kernel system, with the same declaration, body and compiled kernel, as a module evaluated again
+ * makes: the build compiles kernels only at module scope, so no other code makes one.
+ */
+export const freshKernel = (system: System): System => {
+    const leaf = definitionOf(system);
+    const description = kernelOf(system);
+    if (leaf === undefined || leaf.kind === "composite" || description === undefined) throw new Error("Not a kernel system.");
+    // What `System.create` makes of the same declaration and body, without the id a top-level binding takes.
+    const copy: Leaf & System = { kind: leaf.kind, name: leaf.name, declaration: leaf.declaration, body: leaf.body };
+    claimSystem(copy, undefined);
+    return attachKernel(copy, description);
+};