@adobe/ecs 0.0.0-stage → 0.2.0

package/src/implementation/world/terminal.ts

@@ -0,0 +1,14 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+/**
+ * The `Symbol.for` name of the global `WeakSet` of system bodies the plugin proved never reach their context's
+ * `commands`. Its version changes with the set's format.
+ */
+export const terminalBodiesName = "@adobe/ecs/terminal@1";
+
+const terminalBodies = Symbol.for(terminalBodiesName);
+
+/** Whether the plugin proved a system's body never reaches its context's `commands`. */
+export const provenTerminal = (body: unknown): boolean => {
+    const set: unknown = Reflect.get(globalThis, terminalBodies);
+    return set instanceof WeakSet && typeof body === "function" && set.has(body);
+};

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

@@ -0,0 +1,279 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { declarationOf, firstKeyOf, keyOfId, labelOf } from '../../interface/registry/index.js';
+import { layoutOf, viewsOf, type Layout, type Views } from '../../interface/registry/layout.js';
+import { alias, writeOf } from './archetype.js';
+import { parseShared } from './shared.js';
+import { emptyViews } from './arrays.js';
+import { arrivalsWord, viewInMemory, type ArrivalsView } from './arrivals.js';
+import { tableLength } from './entities.js';
+import {
+    archetypeField, capacityField, cursorField, entitiesVersionField, entitiesWord, freeCapacityField, freeField, generationField, linearFlag,
+    reclaimedFlag, recordCapacity, recordCount, recordEntities, recordFlags, recordGeneration, recordStorages, recordVersion, recordWords, remoteFlag, replacedWord, resourceEntityWord, resourceFlag,
+    rowField, storageAdded, storageBlockAdded, storageBlockChanged, storageChanged, storageChunkAdded, storageChunkChanged, storageChunks, storageColumn,
+    storageComponent, storageFlags, storageWords, tableLengthWord, tableOffsetWord, threadShift, tickedFlag, sharedFlag,
+} from './layout-directory.js';
+import { blockShift, chunkShift } from './kernel.js';
+import { coveringBuffer, pageBytes, pagesWord } from './memory.js';
+import { createStringReader } from './strings.js';
+import type { Mirror, Mirrored } from './mirror.js';
+import type { Row, RowArchetype, RowHost, RowStorage } from './rows.js';
+import type { Key } from './state.js';
+
+// A joined thread's view of the world's layout directory (threads.md, "Shared layout directory"): archetypes by their
+// records, struct columns and ticks in shared memory, this thread's objects in its mirror, and the entity table, with
+// the world's numbers for the keys its systems name.
+
+/** A joined thread's view of a storage of the world's, in shared memory, or of this thread's objects, in its mirror. */
+export type ThreadStorage = RowStorage & { readonly component: number };
+
+/** A joined thread's view of one of the world's archetypes, by its record, as of its version and the mirror's columns. */
+export type ThreadArchetype = RowArchetype & {
+    readonly record: number;
+    readonly version: number;
+    readonly mirrored: Mirrored | null | undefined;
+    readonly components: readonly number[];
+    readonly resource: boolean;
+    /** Reclaimed, matching no system, and how many times it was reused for other shared values (`reclaim.ts`). */
+    readonly reclaimed: boolean;
+    readonly generation: number;
+    readonly storageById: readonly (ThreadStorage | undefined)[];
+};
+
+export type EntityViews = { cursor: Int32Array; free: Int32Array; generation: Uint32Array; archetype: Int32Array; row: Uint32Array; length: number };
+
+/** A setup naming keys by the world's numbers, with their ids. */
+type Named = { readonly keys: readonly (readonly [number, string])[] };
+
+const noTicks = new Float64Array(0);
+const noTags = new Uint32Array(0);
+const noValues: unknown[] = [];
+
+/** The memory as this thread last viewed it: its buffer, its words and its views, made again once it grew. */
+export type Viewed = { buffer: ArrayBufferLike; words: Uint32Array; views: Views };
+
+/**
+ * A joined thread's directory reader over `memory`, its objects in `mirror` where it fills some: one per thread,
+ * shared by the systems the world places there and the observer systems it adds.
+ */
+export const createThreadDirectory = (memory: WebAssembly.Memory, mirror: Mirror | null) => {
+    const viewed: Viewed = { buffer: new ArrayBuffer(0), words: new Uint32Array(0), views: emptyViews };
+    let pages = -1;
+    /** By the world's number: what its key is here, and its layout, for the keys this thread's systems name. */
+    const keys: (Key | undefined)[] = [];
+    const layouts: Layout[] = [];
+    const numbers = new Map<Key, number>();
+    const archetypes: (ThreadArchetype | undefined)[] = [];
+    let entities: EntityViews | null = null;
+    let entitiesVersion = -1;
+    const rows: RowHost & { tick: number } = { layouts, rows: new Map<string, Row>(), tick: 0, records: true };
+    const noMirrored: readonly (Mirrored | null | undefined)[] = [];
+    const thread = mirror?.thread ?? -1;
+    /** The records strings' columns name, which this thread reads. */
+    const strings = createStringReader(memory);
+    /**
+     * Moved on whenever a view `archetypeAt` gave a row may have been made again: the world replaced an archetype's
+     * arrays, the views were dropped, or the mirror rebuilt. Index lookups' rows stay bound while it stays the same, so
+     * they check it rather than each archetype for every row. A mirror that begins holding an archetype needs no move:
+     * it does from the first entry naming it, replayed before any run reads a row there.
+     */
+    const replaced = { count: 0 };
+    /** The directory's `replacedWord`, and the mirror's archetypes, as this thread last saw them. */
+    let replacedSeen = 0;
+    let mirroredSeen: readonly (Mirrored | null | undefined)[] = noMirrored;
+
+    /**
+     * Moves `replaced` on if any archetype's view may have changed since it last looked: once a run, before it reads
+     * rows, since the world replaces arrays only at a sync point or a move outside one, which wait for a run in progress.
+     */
+    const settle = (): void => {
+        const word = Atomics.load(viewed.words, replacedWord);
+        const mirrored = mirror?.archetypes ?? noMirrored;
+        if (word === replacedSeen && mirrored === mirroredSeen) return;
+        replacedSeen = word;
+        mirroredSeen = mirrored;
+        replaced.count++;
+    };
+
+    /** Views of the memory again, once it grew, every archetype's with them, and `replaced` settled. Returns its buffer. */
+    const refresh = (): ArrayBufferLike => {
+        if (viewed.words.length === 0) viewed.words = new Uint32Array(memory.buffer);
+        const current = Atomics.load(viewed.words, pagesWord);
+        if (current === pages) {
+            settle();
+            return viewed.buffer;
+        }
+        const latest = coveringBuffer(memory, current * pageBytes);
+        if (latest.byteLength < current * pageBytes) throw new Error(`This thread's memory is ${latest.byteLength} bytes, short of the ${current * pageBytes} the world stored.`);
+        viewed.buffer = latest;
+        viewed.words = new Uint32Array(latest);
+        viewed.views = viewsOf(latest, 0, latest.byteLength);
+        pages = current;
+        archetypes.length = 0;
+        // Defensive: rows bound to the old views still read the same shared memory, and arrays that moved bumped `replacedWord`.
+        replaced.count++;
+        entitiesVersion = -1;
+        settle();
+        return latest;
+    };
+
+    const refreshEntities = (): EntityViews => {
+        const { words, buffer } = viewed;
+        const record = entitiesWord;
+        const version = Atomics.load(words, record + entitiesVersionField);
+        if (entities === null || version !== entitiesVersion) {
+            const capacity = words[record + capacityField];
+            const views: EntityViews = {
+                cursor: new Int32Array(buffer, words[record + cursorField], 4),
+                free: new Int32Array(buffer, words[record + freeField], words[record + freeCapacityField]),
+                archetype: new Int32Array(buffer, words[record + archetypeField], capacity),
+                row: new Uint32Array(buffer, words[record + rowField], capacity),
+                generation: new Uint32Array(buffer, words[record + generationField], capacity),
+                length: 0,
+            };
+            if (entities === null) entities = views;
+            // Spawners hold the table, so it's updated in place.
+            else Object.assign(entities, views);
+            entitiesVersion = version;
+        }
+        entities.length = entities.cursor[tableLength];
+        return entities;
+    };
+
+    /**
+     * By the offset of its text, each shared value read, as its archetype's storage's layout, with that text: a text's
+     * block is freed as its archetype is reused for other values (`reclaim.ts`), and may hold another's after.
+     */
+    const sharedLayouts = new Map<number, { readonly text: string; readonly layout: Layout }>();
+    const sharedLayoutAt = (offset: number): Layout => {
+        const { words, buffer } = viewed;
+        const units = new Uint16Array(buffer, offset + 4, words[offset >> 2]);
+        let text = "";
+        for (let i = 0; i < units.length; i++) text += String.fromCharCode(units[i]);
+        const known = sharedLayouts.get(offset);
+        if (known !== undefined && known.text === text) return known.layout;
+        const layout: Layout = { kind: "constant", value: parseShared(text), shared: true };
+        sharedLayouts.set(offset, { text, layout });
+        return layout;
+    };
+
+    /** A storage's view, by its record's words; this thread's objects by their mirror column. */
+    const storageOf = (base: number, capacity: number, mirrored: Mirrored | null | undefined): ThreadStorage | undefined => {
+        const { words, buffer } = viewed;
+        const component = words[base + storageComponent];
+        const flags = words[base + storageFlags];
+        // A shared component's storage holds its archetype's value.
+        const layout = layouts[component] === undefined ? undefined : (flags & sharedFlag) !== 0 ? sharedLayoutAt(words[base + storageColumn]) : layouts[component];
+        if (layout === undefined) return undefined;
+        const ticked = (flags & tickedFlag) !== 0;
+        const own = (flags & remoteFlag) !== 0 && flags >>> threadShift === thread;
+        const chunks = words[base + storageChunks];
+        const added = ticked ? new Float64Array(buffer, words[base + storageAdded], capacity) : noTicks;
+        const changed = ticked ? new Float64Array(buffer, words[base + storageChanged], capacity) : noTicks;
+        return {
+            component,
+            layout,
+            ...writeOf(layout),
+            views: (layout.kind === "linear" || layout.kind === "string") && (flags & linearFlag) !== 0 ? viewsOf(buffer, words[base + storageColumn], capacity * layout.stride) : emptyViews,
+            strings: layout.kind === "string" ? strings : null,
+            // Rows only this thread's systems write: a mirror's column, or one of its own while the mirror has none.
+            values: own ? mirrored?.byComponent[component]?.values ?? [] : noValues,
+            tags: own ? new Uint32Array(buffer, words[base + storageColumn], capacity) : noTags,
+            ticked,
+            added,
+            // A constant's `changed` ticks are its `added` ticks.
+            changed: alias(layout) ? added : changed,
+            chunkAdded: ticked ? new Float64Array(buffer, words[base + storageChunkAdded], chunks) : noTicks,
+            chunkChanged: ticked ? new Float64Array(buffer, words[alias(layout) ? base + storageChunkAdded : base + storageChunkChanged], chunks) : noTicks,
+            blockAdded: ticked ? new Float64Array(buffer, words[base + storageBlockAdded], chunks << (chunkShift - blockShift)) : noTicks,
+            blockChanged: ticked ? new Float64Array(buffer, words[alias(layout) ? base + storageBlockAdded : base + storageBlockChanged], chunks << (chunkShift - blockShift)) : noTicks,
+        };
+    };
+
+    const viewArchetype = (id: number, record: number, version: number, mirrored: Mirrored | null | undefined): ThreadArchetype => {
+        const { words, buffer } = viewed;
+        const capacity = words[record + recordCapacity];
+        const storageById: (ThreadStorage | undefined)[] = [];
+        const components: number[] = [];
+        for (let s = 0; s < words[record + recordStorages]; s++) {
+            const base = record + recordWords + s * storageWords;
+            components.push(words[base + storageComponent]);
+            const storage = storageOf(base, capacity, mirrored);
+            if (storage !== undefined) storageById[storage.component] = storage;
+        }
+        return {
+            id, record, version, mirrored, components, storageById,
+            resource: (words[record + recordFlags] & resourceFlag) !== 0,
+            reclaimed: (words[record + recordFlags] & reclaimedFlag) !== 0,
+            generation: words[record + recordGeneration],
+            entities: new Float64Array(buffer, words[record + recordEntities], capacity),
+        };
+    };
+
+    /** An archetype's view: one load of its record's version, and new views only once it, or the mirror, moved on. */
+    const archetypeAt = (id: number): ThreadArchetype | undefined => {
+        const { words } = viewed;
+        const cached = archetypes[id];
+        const mirrored = (mirror?.archetypes ?? noMirrored)[id];
+        if (cached !== undefined && cached.mirrored === mirrored && Atomics.load(words, cached.record + recordVersion) === cached.version) return cached;
+        const offset = cached?.record ?? (id < Atomics.load(words, tableLengthWord) ? words[(words[tableOffsetWord] >> 2) + id] >> 2 : 0);
+        if (offset === 0) return undefined;
+        return archetypes[id] = viewArchetype(id, offset, Atomics.load(words, offset + recordVersion), mirrored);
+    };
+
+    const countOf = (archetype: ThreadArchetype): number => viewed.words[archetype.record + recordCount];
+    /** The ring of rows' moves, once the world wrote one, in this thread's view of the memory. */
+    let arrivalsView: ArrivalsView | null = null;
+    const arrivals = (): ArrivalsView | null => {
+        const { words } = viewed;
+        if (arrivalsView !== null && arrivalsView.control === words) return arrivalsView;
+        // Before this thread views the memory, there's nothing to read.
+        if (words.length <= arrivalsWord) return null;
+        const offset = Atomics.load(words, arrivalsWord);
+        return arrivalsView = offset === 0 ? null : viewInMemory(words, offset);
+    };
+
+    /** The resource entity's archetype and row, or null before resources exist. */
+    const resourceRow = (): { readonly archetype: ThreadArchetype; readonly row: number } | null => {
+        const word = Atomics.load(viewed.words, resourceEntityWord);
+        if (word === 0) return null;
+        const table = refreshEntities();
+        const index = word - 1;
+        const archetype = archetypeAt(table.archetype[index]);
+        return archetype === undefined ? null : { archetype, row: table.row[index] };
+    };
+
+    const tableCount = (): number => Atomics.load(viewed.words, tableLengthWord);
+
+    /** Takes the world's numbers for the keys of systems or finalizers it places here. */
+    const name = (setups: readonly Named[]): void => {
+        for (const { keys: named } of setups) {
+            for (const [number, id] of named) {
+                const key = keyOfId(id);
+                if (key === undefined || keys[number] !== undefined) continue;
+                keys[number] = key;
+                numbers.set(firstKeyOf(key), number);
+                const declaration = declarationOf(key);
+                // A shared component's values are its archetypes': each storage of it holds its own.
+                layouts[number] = declaration?.shared === true ? { kind: "constant", value: undefined, shared: true } : layoutOf(declaration?.type);
+                // Views hold storages only of components with layouts here, so they're made again.
+                archetypes.length = 0;
+                // Defensive: a lookup's read keys are named before its runner and pool exist, so no bound row lacks a storage.
+                replaced.count++;
+            }
+        }
+    };
+
+    const numberOf = (key: Key): number => {
+        const number = numbers.get(firstKeyOf(key));
+        if (number === undefined) throw new Error(`"${labelOf(key)}" has no number from the world here.`);
+        return number;
+    };
+
+    return {
+        viewed, rows, keys, layouts, numbers, mirror, strings, replaced,
+        refresh, refreshEntities, archetypeAt, countOf, arrivals, resourceRow, tableCount, name, numberOf,
+        layoutOf: (key: Key): Layout | undefined => layouts[numbers.get(firstKeyOf(key)) ?? -1],
+    };
+};
+
+export type ThreadDirectory = ReturnType<typeof createThreadDirectory>;