@adobe/ecs 0.0.0-stage → 0.2.0

package/src/interface/registry/declarations.ts

@@ -0,0 +1,196 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Schema } from '../schema/schema.js';
+import type { Key as TraitKey } from '../trait/key.js';
+import { declarationsName } from './ids.js';
+import { layoutOf } from './layout.js';
+import { claimKey, declarationOf, failRegistration, firstKeyOf, installCatchUp, kindOf, labelOf, recordFailure, requireKey, sameDeclaration } from './names.js';
+import { isReduction } from './reduction.js';
+import { allowsNull, hasBoolean, isComparable, isEntity, isString, isStruct, matchesSchema } from './schemas.js';
+import { addTrait, isTrait } from './traits.js';
+
+/**
+ * A registered declaration, as any consumer iterating components or resources sees it: its `type` and other traits.
+ * Without `type`, the value isn't data. `default` is what it starts at, never its schema's, which holds none; `fresh`
+ * starts it as an empty `Map` or `Set` of each world's own.
+ */
+export type AnyDeclaration = { readonly type?: Schema; readonly default?: unknown; readonly fresh?: unknown } & { readonly [T in TraitKey]?: unknown };
+
+/** The value schema of any registered component or resource, or undefined for a value that isn't data. */
+export const schemaOf = (key: unknown): Schema | undefined => declarationOf(key)?.type;
+
+/** Global constructors of Transferable values, where the platform has them. */
+const transferables: readonly string[] = [
+    "ArrayBuffer", "ImageBitmap", "OffscreenCanvas", "MessagePort", "VideoFrame", "AudioData",
+    "ReadableStream", "WritableStream", "TransformStream", "RTCDataChannel",
+];
+
+/** Whether `value` is an instance of the global constructor `name`, where the platform has one. */
+const isInstance = (value: unknown, name: string): boolean => {
+    const constructor: unknown = Reflect.get(globalThis, name);
+    return typeof constructor === "function" && value instanceof constructor;
+};
+
+/**
+ * The thread a registered declaration's value lives on: none for a struct or a string, which live in shared memory,
+ * else its `thread` or `"world"`. Only a value with a struct or string schema is known to be one.
+ */
+export const threadOfDeclaration = (declaration: AnyDeclaration): string | null => {
+    if (declaration.type !== undefined && (isStruct(declaration.type) || isString(declaration.type))) return null;
+    // A shared component's value is its archetype's, which every thread reads.
+    if (declaration.shared === true) return null;
+    return typeof declaration.thread === "string" ? declaration.thread : "world";
+};
+
+/** Whether a schema, or any schema inside it, holds a `default`. */
+const holdsDefault = (schema: Schema): boolean => {
+    if ("default" in schema) return true;
+    if ("anyOf" in schema) return schema.anyOf.some(holdsDefault);
+    if ("allOf" in schema) return schema.allOf.some(holdsDefault);
+    if ("const" in schema) return false;
+    switch (schema.type) {
+        case "object": return Object.values(schema.properties).some(holdsDefault);
+        case "array": case "set": return holdsDefault(schema.items);
+        case "map": return holdsDefault(schema.keys) || holdsDefault(schema.values);
+        default: return false;
+    }
+};
+
+/** Throws for a declaration whose traits can't hold, so far as values tell: types check the rest. */
+const check = (kind: "component" | "resource", key: symbol, declaration: AnyDeclaration): void => {
+    const fail = (message: string): never => failRegistration(kind, key, message);
+    for (const trait of Reflect.ownKeys(declaration)) {
+        if (trait !== "default" && trait !== "fresh" && !isTrait(trait)) fail(`${labelOf(trait)} isn't a registered trait.`);
+    }
+    const { type, fresh } = declaration;
+    if (type !== undefined && holdsDefault(type)) fail("its schema holds a default, which a schema never does: its start is its declaration's default.");
+    if (fresh !== undefined) {
+        if (fresh !== "Map" && fresh !== "Set") fail(`fresh is "Map" or "Set".`);
+        if ("default" in declaration) fail("it starts fresh, so it has no default.");
+        if (type !== undefined && "type" in type && (type.type === "set" || type.type === "map") && (type.type === "set") !== (fresh === "Set")) fail(`a ${type.type} starts as a fresh ${type.type === "set" ? "Set" : "Map"}.`);
+    }
+    // A start however the build found it, a literal, its type's namespace's or an identity, is one of its type's values.
+    if (type !== undefined && "default" in declaration && !matchesSchema(type, declaration.default)) fail(`its default, ${labelOf(declaration.default)}, isn't one of its type's values.`);
+    try {
+        layoutOf(type);
+    }
+    catch (error) {
+        fail(error instanceof Error ? error.message : String(error));
+    }
+    if (declaration.reference !== undefined && !(type !== undefined && isEntity(type))) fail("a reference's type is Entity.schema.");
+    // A cycle of `within` hosts closes when its last component registers, so it's found then.
+    const cycle: symbol[] = [key];
+    for (let host = declaration.within; typeof host === "symbol"; host = declarationOf(host)?.within) {
+        const first = firstKeyOf(host);
+        if (first === firstKeyOf(key)) fail(`components are within each other in a cycle: ${cycle.map(labelOf).sort().join(", ")}.`);
+        if (cycle.includes(first)) break;
+        cycle.push(first);
+    }
+    if (declaration.derived !== undefined && kind !== "component") fail("only a component is derived.");
+    if (declaration.derived === true && declaration.within !== undefined) fail("a derived component's rule covers within.");
+    if (declaration.derived === true && declaration.reference !== undefined) fail("a rule can't set a derived component's target, so it's no reference.");
+    if (declaration.derived === true && type !== undefined && fresh === undefined && !("default" in declaration || "const" in type || allowsNull(type))) {
+        fail("a derived component has a default, which it starts at.");
+    }
+    if (declaration.reduce !== undefined) {
+        const operator = declaration.reduce;
+        if (kind !== "resource") fail("only a resource is reduced.");
+        if (!isReduction(operator)) fail(`reduce is one of "+", "*", "min", "max", "&", "|" or "^".`);
+        if (type === undefined || !isStruct(type)) fail("a reduced resource is a struct of numbers or booleans.");
+        if (type !== undefined && hasBoolean(type) && operator !== "&" && operator !== "|" && operator !== "^") fail(`booleans reduce with "&", "|" or "^".`);
+    }
+    const { thread } = declaration;
+    if (thread !== undefined) {
+        if (typeof thread !== "string" || thread === "") fail("thread is a thread's name.");
+        if (type !== undefined && isStruct(type)) fail("a struct lives in shared memory, so it has no thread.");
+        if (type !== undefined && isString(type)) fail("a string lives in shared memory, so it has no thread.");
+    }
+    if (isInstance(declaration.default, "Node") && thread !== "main") fail(`a DOM Node lives on "main".`);
+    const { shared } = declaration;
+    if (shared !== undefined) {
+        if (shared !== true) fail("shared is true.");
+        if (kind !== "component") fail("only a component is shared.");
+        if (type === undefined || !isComparable(type)) fail("a shared component's value is comparable data: numbers, booleans, strings, and arrays and objects of those.");
+        if (thread !== undefined) fail("a shared value lives in shared memory, so it has no thread.");
+        if (declaration.derived !== undefined) fail("a derived component isn't shared: its rule adds it with its default.");
+        if (declaration.reference !== undefined) fail("a reference isn't shared: its target despawning acts on each holder.");
+    }
+    const { transfer } = declaration;
+    if (transfer !== undefined) {
+        if (transfer !== true) fail("transfer is true.");
+        if (type !== undefined) fail("a value with a schema is data, which isn't Transferable.");
+        const value = declaration.default;
+        if (value !== undefined && value !== null && !transferables.some(constructor => isInstance(value, constructor))) fail("its value isn't Transferable.");
+    }
+};
+
+/**
+ * Registers a declaration of `kind` under `key`, fixed from then on. The same declaration again is accepted, and so is
+ * a new symbol with the id of a key of this kind, as a module evaluated again makes it.
+ */
+const createRegistry = (kind: "component" | "resource") => (key: unknown, declaration: AnyDeclaration): void => {
+    const symbol = requireKey(kind, key);
+    const existing = kindOf(symbol);
+    if (existing === kind && sameDeclaration(declarationOf(symbol), declaration)) return;
+    if (existing === undefined) check(kind, symbol, declaration);
+    claimKey(symbol, kind, declaration);
+};
+
+/** Registers a component: the package's own, and tests' keys made at runtime; the build declares every other. */
+export const registerComponent = createRegistry("component");
+
+/** Registers a resource: the package's own, and tests' keys made at runtime; the build declares every other. */
+export const registerResource = createRegistry("resource");
+
+/** The global map of what the build declared, made here when no generated code made it first. */
+const declared = ((): Map<unknown, unknown> => {
+    const name = Symbol.for(declarationsName);
+    const found: unknown = Reflect.get(globalThis, name);
+    if (found instanceof Map) return found;
+    const made = new Map<unknown, unknown>();
+    Reflect.set(globalThis, name, made);
+    return made;
+})();
+
+/** Whether a value the generated code recorded is a declaration: an object of traits, as the build wrote it. */
+const isDeclaration = (value: unknown): value is AnyDeclaration => typeof value === "object" && value !== null;
+
+/** Registers one key the build declared, as its kind says. */
+const registerDeclared = (key: unknown, entry: unknown): void => {
+    const kind: unknown = typeof entry === "object" && entry !== null ? Reflect.get(entry, "kind") : undefined;
+    const declaration: unknown = typeof entry === "object" && entry !== null ? Reflect.get(entry, "declaration") : undefined;
+    if (kind === "trait") addTrait(key);
+    else if (kind === "component" && isDeclaration(declaration)) registerComponent(key, declaration);
+    else if (kind === "resource" && isDeclaration(declaration)) registerResource(key, declaration);
+};
+
+/** How many of the map's entries this copy registered. */
+let seen = 0;
+let catching = false;
+
+/**
+ * Registers what the build declared since this last ran, in the order modules evaluated, as each module registered
+ * its keys when it was evaluated. A declaration that fails is recorded for its own key, whose every use fails giving
+ * it as the reason, and never for a read of another key. Reads of keys while it runs see those registered so far.
+ */
+const catchUp = (): void => {
+    if (catching || declared.size === seen) return;
+    catching = true;
+    try {
+        let index = 0;
+        for (const [key, entry] of declared) {
+            if (index++ < seen) continue;
+            seen++;
+            try {
+                registerDeclared(key, entry);
+            }
+            catch (error) {
+                if (typeof key === "symbol") recordFailure(key, error instanceof Error ? error.message : String(error));
+            }
+        }
+    }
+    finally {
+        catching = false;
+    }
+};
+
+installCatchUp(catchUp);

package/src/interface/registry/declared.test.ts

@@ -0,0 +1,40 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import { identify, recordDeclaration } from "./ids.test-helper.js";
+import "./declarations.js";
+import { declarationOf, kindOf, sameKey, whyUnregistered } from "./names.js";
+
+describe("declarations the build records", () => {
+    it("registers a key at its first use, as its kind says", () => {
+        const speed = Symbol("declaredTest/speed");
+        const tag = Symbol("declaredTest/tag");
+        recordDeclaration(speed, "resource", { type: { type: "number" }, default: 1 });
+        recordDeclaration(tag, "trait");
+        expect([kindOf(speed), kindOf(tag)]).toEqual(["resource", "trait"]);
+        expect(declarationOf(speed)).toEqual({ type: { type: "number" }, default: 1 });
+    });
+    it("registers in the order modules recorded them, so a trait comes before what declares it", () => {
+        const mark = Symbol("declaredTest/mark");
+        const marked = Symbol("declaredTest/marked");
+        recordDeclaration(mark, "trait");
+        recordDeclaration(marked, "component", { type: { const: true }, [mark]: true });
+        expect(kindOf(marked)).toBe("component");
+    });
+    it("takes another symbol of one id, as a module evaluated again records it, as the same key", () => {
+        const first = identify(Symbol("declaredTest/again"), "declaredTest/keys.ts#again");
+        const again = identify(Symbol("declaredTest/again"), "declaredTest/keys.ts#again");
+        recordDeclaration(first, "component", { type: { type: "number" } });
+        recordDeclaration(again, "component", { type: { type: "number" } });
+        expect([kindOf(again), sameKey(first, again)]).toEqual(["component", true]);
+    });
+    it("never throws a declaration that fails for another key's use, and gives it as the reason its own key's uses fail", () => {
+        const late = Symbol("declaredTest/late");
+        const fine = Symbol("declaredTest/fine");
+        recordDeclaration(late, "component", { type: { type: "number" }, reduce: "+" });
+        recordDeclaration(fine, "component", { type: { type: "number" } });
+        expect([kindOf(fine), kindOf(late)]).toEqual(["component", undefined]);
+        expect(whyUnregistered(late)).toBe(`its declaration failed to register: Cannot register component "declaredTest/late": only a resource is reduced.`);
+        // Left valid, so any other copy of the registry reading the map later registers it.
+        recordDeclaration(late, "component", { type: { type: "number" } });
+    });
+});

package/src/interface/registry/finalizer-order.ts

@@ -0,0 +1,53 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Finalizer } from '../finalizer/created.js';
+import { firstItemOf } from './items.js';
+import { firstKeyOf, labelOf } from './names.js';
+
+/**
+ * Finalizers in run order: `before` and `after` first, then registration order. Throws for a cycle, and for two that
+ * both write a resource, or where one reads what the other writes, with no ordering between them.
+ */
+export const orderFinalizers = (runners: readonly Finalizer[]): Finalizer[] => {
+    const indexOf = new Map<object, number>(runners.map((runner, index) => [firstItemOf(runner), index]));
+    const successors = runners.map(() => new Set<number>());
+    runners.forEach((runner, index) => {
+        const { before, after } = runner.declaration;
+        for (const finalizer of before ?? []) { const other = indexOf.get(firstItemOf(finalizer)); if (other !== undefined) successors[index].add(other); }
+        for (const finalizer of after ?? []) { const other = indexOf.get(firstItemOf(finalizer)); if (other !== undefined) successors[other].add(index); }
+    });
+    const incoming = runners.map(() => 0);
+    for (const next of successors) for (const other of next) incoming[other]++;
+    const order: number[] = [];
+    const ready = runners.flatMap((_, index) => incoming[index] === 0 ? [index] : []);
+    while (ready.length > 0) {
+        ready.sort((a, b) => a - b);
+        const index = ready.shift() ?? 0;
+        order.push(index);
+        for (const other of successors[index]) if (--incoming[other] === 0) ready.push(other);
+    }
+    if (order.length < runners.length) {
+        const cycle = runners.filter((_, index) => !order.includes(index)).map(runner => `"${runner.name}"`).join(", ");
+        throw new Error(`Finalizers ${cycle} are ordered in a cycle.`);
+    }
+    const reaches = (from: number, to: number): boolean => {
+        const seen = new Set<number>();
+        const stack = [from];
+        while (stack.length > 0) {
+            const next = stack.pop() ?? 0;
+            if (next === to) return true;
+            if (seen.has(next)) continue;
+            seen.add(next);
+            stack.push(...successors[next]);
+        }
+        return false;
+    };
+    const writes = runners.map(runner => new Set<unknown>((runner.declaration.resources?.write ?? []).map(firstKeyOf)));
+    const reads = runners.map(runner => new Set<unknown>((runner.declaration.resources?.read ?? []).map(firstKeyOf)));
+    for (let a = 0; a < runners.length; a++) for (let b = a + 1; b < runners.length; b++) {
+        const conflict = [...writes[a]].find(key => writes[b].has(key) || reads[b].has(key)) ?? [...writes[b]].find(key => reads[a].has(key));
+        if (conflict !== undefined && !reaches(a, b) && !reaches(b, a)) {
+            throw new Error(`Finalizers "${runners[a].name}" and "${runners[b].name}" both access "${labelOf(conflict)}", one writing it; order them with before or after.`);
+        }
+    }
+    return order.map(index => runners[index]);
+};

package/src/interface/registry/ids.test-helper.ts

@@ -0,0 +1,48 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { declarationsName, idsName, accessName } from './ids.js';
+
+/**
+ * Gives a key or a declaration an id, as code the plugin generates does for a top-level `Symbol(...)` declaration or a
+ * top-level binding's constructor call. Returns what it was given.
+ */
+export const identify = <T extends symbol | object>(value: T, id: string): T => {
+    const name = Symbol.for(idsName);
+    const existing: unknown = Reflect.get(globalThis, name);
+    const map = existing instanceof Map ? existing : new Map<unknown, string>();
+    map.set(value, id);
+    Reflect.set(globalThis, name, map);
+    return value;
+};
+
+/** Records a key's declaration, as the function the plugin appends to a module declaring keys does. */
+export const recordDeclaration = (key: symbol, kind: "component" | "resource" | "trait", declaration?: object): void => {
+    const name = Symbol.for(declarationsName);
+    const existing: unknown = Reflect.get(globalThis, name);
+    const map = existing instanceof Map ? existing : new Map<unknown, unknown>();
+    map.set(key, { kind, declaration });
+    Reflect.set(globalThis, name, map);
+};
+
+/**
+ * Gives a declaration, or the body of a system declaring nothing, what its body uses, as the plugin does where it sees
+ * the constructor's call: for calls it doesn't see. Each list names keys; what isn't given is used by nothing.
+ */
+export const giveAccess = <T extends object>(made: T, uses: {
+    readonly read?: readonly symbol[];
+    readonly write?: readonly symbol[];
+    readonly resources?: { readonly read?: readonly symbol[]; readonly write?: readonly symbol[]; readonly reduce?: readonly symbol[] };
+    readonly lookup?: { readonly [name: string]: readonly symbol[] };
+    readonly up?: readonly symbol[];
+} = {}): T => {
+    const name = Symbol.for(accessName);
+    let map: unknown = Reflect.get(globalThis, name);
+    if (!(map instanceof WeakMap)) Reflect.set(globalThis, name, map = new WeakMap<object, unknown>());
+    if (map instanceof WeakMap) map.set(made, {
+        components: { read: uses.read ?? [], write: uses.write ?? [] },
+        resources: { read: uses.resources?.read ?? [], write: uses.resources?.write ?? [], reduce: uses.resources?.reduce ?? [] },
+        lookup: uses.lookup ?? {},
+        up: uses.up ?? [],
+        at: "a test",
+    });
+    return made;
+};

package/src/interface/registry/ids.test.ts

@@ -0,0 +1,111 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import { Finalizer } from "../finalizer/finalizer.js";
+import { Rule } from "../rule/rule.js";
+import { System } from "../system/system.js";
+import { registerComponent, registerResource } from "./declarations.js";
+import { addTrait } from "./traits.js";
+import { giveAccess, identify } from "./ids.test-helper.js";
+import { declarationOf, kindOf, labelOf, programFinalizers, programRules, requireDefinition, sameItem, scheduleOf } from "./index.js";
+
+// Each pair is one module's key and the key that module makes when evaluated again: one id, two symbols.
+const score = Symbol("score");
+const scoreAgain = Symbol("score");
+const shown = Symbol("shown");
+const shownAgain = Symbol("shown");
+const level = Symbol("level");
+const levelAgain = Symbol("level");
+const changed = Symbol("changed");
+const changedAgain = Symbol("changed");
+const crossed = Symbol("crossed");
+const crossedAgain = Symbol("crossed");
+const unnamed = Symbol("score");
+identify(unnamed, "idsTest/other.ts#score");
+const tagged = Symbol("tagged");
+const taggedAgain = Symbol("tagged");
+
+identify(score, "idsTest/keys.ts#score");
+identify(scoreAgain, "idsTest/keys.ts#score");
+identify(shown, "idsTest/keys.ts#shown");
+identify(shownAgain, "idsTest/keys.ts#shown");
+identify(level, "idsTest/keys.ts#level");
+identify(levelAgain, "idsTest/keys.ts#level");
+identify(changed, "idsTest/keys.ts#changed");
+identify(changedAgain, "idsTest/keys.ts#changed");
+identify(crossed, "idsTest/keys.ts#crossed");
+identify(crossedAgain, "idsTest/keys.ts#crossed");
+identify(tagged, "idsTest/keys.ts#tagged");
+identify(taggedAgain, "idsTest/keys.ts#tagged");
+
+// The keys' ids are given by hand, after the keys are made, so they're registered here rather than declared, which
+// registers a key as soon as it's made.
+registerComponent(score, { type: { type: "number" } });
+registerComponent(shown, { type: { const: true }, derived: true });
+registerResource(level, { type: { type: "number" }, default: 0 });
+registerComponent(changed, { type: { type: "number" } });
+registerComponent(crossed, { type: { type: "number" } });
+addTrait(tagged);
+
+/** Calls a constructor as an untyped caller would, naming keys no declaration types. */
+const untyped = <F extends (...parameters: never[]) => unknown>(create: F) => (...parameters: unknown[]): ReturnType<F> => Reflect.apply(create, undefined, parameters);
+const system = untyped(System.create);
+const rule = untyped(Rule.create);
+const finalizer = untyped(Finalizer.create);
+type Row = { [key: symbol]: number };
+
+describe("keys with ids", () => {
+    it("labels a key by its description, however many keys share it", () => {
+        expect(labelOf(score)).toBe("score");
+        registerComponent(unnamed, { type: { type: "number" } });
+        expect([labelOf(score), labelOf(unnamed)]).toEqual(["score", "score"]);
+        expect(labelOf(Symbol("score"))).toBe("score");
+    });
+    it("accepts another symbol under a registered key's id with the same declaration, as the same key", () => {
+        registerComponent(scoreAgain, { type: { type: "number" } });
+        registerComponent(shownAgain, { type: { const: true }, derived: true });
+        registerResource(levelAgain, { type: { type: "number" }, default: 0 });
+        addTrait(taggedAgain);
+        expect([kindOf(scoreAgain), kindOf(levelAgain), kindOf(taggedAgain)]).toEqual(["component", "resource", "trait"]);
+        expect(declarationOf(scoreAgain)).toBe(declarationOf(score));
+        expect(labelOf(scoreAgain)).toBe("score");
+    });
+    it("rejects another symbol under a registered key's id with another declaration, or as another kind", () => {
+        expect(() => registerComponent(changedAgain, { type: { type: "string" } })).toThrow(
+            `Cannot register component "changed" (idsTest/keys.ts#changed): its id is another key's, with another declaration; if a module was evaluated again with a changed declaration, reload the page.`);
+        expect(() => registerResource(crossedAgain, { type: { type: "number" }, default: 0 })).toThrow(
+            `Cannot register resource "crossed" (idsTest/keys.ts#crossed): its id is a component's.`);
+        expect([kindOf(changedAgain), kindOf(crossedAgain)]).toEqual([undefined, undefined]);
+    });
+    it("keeps keys of different ids apart, though their descriptions match", () => {
+        registerComponent(unnamed, { type: { type: "number" } });
+        system(giveAccess(identify({ components: { with: [score] } }, "idsTest/systems.ts#unnamed"), { write: [score] }), (row: Row) => { row[score] = 1; });
+        expect(() => system(giveAccess(identify({ components: { with: [unnamed] } }, "idsTest/systems.ts#unnamed"), { write: [unnamed] }), (row: Row) => { row[unnamed] = 1; })).toThrow("reload the page");
+    });
+});
+
+describe("declarations evaluated again", () => {
+    it("accept a system whose keys match by id, as a new system", () => {
+        const first = system(giveAccess(identify({ components: { with: [score] } }, "idsTest/systems.ts#system"), { write: [score], resources: { read: [level] } }), (row: Row, { resources }: { resources: Row }) => { row[score] = resources[level] ?? 0; });
+        const again = system(giveAccess(identify({ components: { with: [scoreAgain] } }, "idsTest/systems.ts#system"), { write: [scoreAgain], resources: { read: [levelAgain] } }), (row: Row, { resources }: { resources: Row }) => { row[scoreAgain] = resources[levelAgain] ?? 0; });
+        expect(again).not.toBe(first);
+        expect(sameItem(again, first)).toBe(true);
+    });
+    it("accept a rule whose keys match by id, which is already recorded", () => {
+        const created = rule(identify({ components: { with: [score] }, derive: [shown] }, "idsTest/systems.ts#rule"));
+        const rules = programRules().length;
+        expect(rule(identify({ components: { with: [scoreAgain] }, derive: [shownAgain] }, "idsTest/systems.ts#rule"))).toBe(created);
+        expect(programRules()).toHaveLength(rules);
+    });
+    it("accept a finalizer whose keys match by id, keeping its place with the new body", () => {
+        const first = finalizer(giveAccess(identify({ components: { with: [score] } }, "idsTest/systems.ts#finalizer")), () => {});
+        const body = (): void => {};
+        expect(finalizer(giveAccess(identify({ components: { with: [scoreAgain] } }, "idsTest/systems.ts#finalizer")), body)).toBe(first);
+        const found = programFinalizers().find(finalizer => finalizer.name === "finalizer");
+        expect(found?.kind === "finalizer" ? found.body : null).toBe(body);
+    });
+    it("schedule symbols of one id as one key", () => {
+        const write = system(giveAccess({ components: { with: [score] } }, { write: [score] }), (row: Row) => { row[score] = 1; });
+        const read = system(giveAccess({ components: { with: [scoreAgain] } }, { read: [scoreAgain] }), (row: Row) => { void row[scoreAgain]; });
+        expect(() => scheduleOf(requireDefinition(system({ systems: [write, read] })))).toThrow("both access");
+    });
+});

package/src/interface/registry/ids.ts

@@ -0,0 +1,76 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+/**
+ * The `Symbol.for` name of the global `Map` that code the plugin generates fills: from key to id, and from a
+ * system's, rule's or finalizer's declaration to id. Its version changes with the map's format.
+ */
+export const idsName = "@adobe/ecs/ids@1";
+
+const ids = Symbol.for(idsName);
+
+/**
+ * The `Symbol.for` name of the global `Map` code the plugin generates fills, from each key a module declares to its
+ * kind and declaration, `{ kind, declaration }`, in the order modules evaluate. Every copy of the package reads it and
+ * none changes it. Its version changes with the format.
+ */
+export const declarationsName = "@adobe/ecs/declarations@1";
+
+const idsMap = (): Map<unknown, unknown> | undefined => {
+    const map: unknown = Reflect.get(globalThis, ids);
+    return map instanceof Map ? map : undefined;
+};
+
+/** The id the plugin gave a key, its module path and binding (`src/keys.ts#position`), if it gave one. */
+export const idOfKey = (key: symbol): string | undefined => {
+    const id: unknown = idsMap()?.get(key);
+    return typeof id === "string" ? id : undefined;
+};
+
+/**
+ * The id the plugin gave the declaration a top-level binding's constructor call passes (`src/systems.ts#move`), if
+ * it gave one, taken out of the map so the object declares nothing else under it.
+ */
+export const takeIdOfDeclaration = (declaration: object): string | undefined => {
+    const map = idsMap();
+    const id: unknown = map?.get(declaration);
+    if (id === undefined) return undefined;
+    map?.delete(declaration);
+    return typeof id === "string" ? id : undefined;
+};
+
+/**
+ * The `Symbol.for` name of the global `WeakMap` from a declaration to the label the plugin gave a constructor call that
+ * isn't a top-level binding's, by the binding or function it's in, or an internal factory gave its declaration. Weak,
+ * so a declaration whose constructor threw before taking its label isn't kept.
+ */
+export const labelsName = "@adobe/ecs/labels@1";
+
+const labels = Symbol.for(labelsName);
+
+/** The label given the declaration a constructor call passes, if any, taken out of the map. */
+export const takeLabelOfDeclaration = (declaration: object): string | undefined => {
+    const map: unknown = Reflect.get(globalThis, labels);
+    if (!(map instanceof WeakMap || map instanceof Map)) return undefined;
+    const label: unknown = map.get(declaration);
+    if (label === undefined) return undefined;
+    map.delete(declaration);
+    return typeof label === "string" ? label : undefined;
+};
+
+/**
+ * The `Symbol.for` name of the global `WeakMap` from a declaration, or the body of a system declaring nothing, to what
+ * the build inferred its body uses (`Access` in `system/resolve.ts`), which the plugin fills where it calls a
+ * constructor; an internal factory making declarations at runtime gives its own first, which the plugin's doesn't
+ * replace. Its version changes with the format.
+ */
+export const accessName = "@adobe/ecs/access@1";
+
+const access = Symbol.for(accessName);
+
+/** What the build inferred the body a declaration or body is made with uses, if it inferred it, taken out of the map. */
+export const takeAccessOf = (declaration: object): unknown => {
+    const map: unknown = Reflect.get(globalThis, access);
+    if (!(map instanceof WeakMap)) return undefined;
+    const found: unknown = map.get(declaration);
+    map.delete(declaration);
+    return found;
+};

package/src/interface/registry/index.ts

@@ -0,0 +1,30 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+/** What registration recorded, for the implementation to read. Not part of the public interface. */
+export type { AnyDeclaration } from './declarations.js';
+export { schemaOf, threadOfDeclaration } from './declarations.js';
+export type { Kind } from './names.js';
+export { declarationOf, firstKeyOf, keyOfId, kindOf, labelOf, newestKeyOf, whyUnregistered } from './names.js';
+export type { Item } from './program.js';
+export { definitionOf, programFinalizers, programRules, programVersion, requireDefinition } from './program.js';
+export type { Schedule } from './schedule.js';
+export { accessOf, isLeaf, isObserver, reducedBy, scheduleOf } from './schedule.js';
+export type { RuleFacts, Strata } from './strata.js';
+export { strataOf } from './strata.js';
+export type { Placed } from './threads.js';
+export { threadOf } from './threads.js';
+export { isTrait } from './traits.js';
+export { idOfKey } from './ids.js';
+export { isWorldWritten } from './written.js';
+export { sameDeclaration } from './names.js';
+export { firstItemOf, identifiedItems, idOfItem, idOrNull, itemOfId, sameItem } from './items.js';
+export { allowsNull, conditional, isStruct } from './schemas.js';
+export { isReduction, reductionOperators } from './reduction.js';
+export type { Definition } from '../system/definition.js';
+export type { Leaf } from '../system/leaf.js';
+export type { Composite } from '../system/composite.js';
+export type { Rule } from '../rule/created.js';
+export type { Finalizer } from '../finalizer/created.js';
+export { archetypeIndexKey, internArchetype, type Interned } from './archetypes.js';
+export { indexDefinitionOf, indexOfLookup, lookupKeysOf, orderKeysOf, watchedBy, watchesEntries } from './indexes.js';
+export type { Created as IndexDefinition } from '../indexes/created.js';
+export type { Declaration as IndexDeclaration } from '../indexes/declaration.js';

package/src/interface/registry/indexes.ts

@@ -0,0 +1,74 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Created } from '../indexes/created.js';
+import { recordItem, registeredAs } from './items.js';
+import { firstKeyOf, labelOf, sameDeclaration } from './names.js';
+
+/**
+ * Records an index under the id the plugin gave its declaration and returns it; declared again under that id the same,
+ * as a module evaluated again declares it, it's the index already recorded. Throws for that id with another kind or
+ * declaration.
+ */
+export const addIndex = (index: Created, id: string | undefined): Created => {
+    const existing = registeredAs(index, id, sameDeclaration);
+    const found = existing === undefined ? undefined : indexDefinitionOf(existing);
+    if (found !== undefined) return found;
+    recordItem(index, id, undefined);
+    return index;
+};
+
+/** Only `Index.create` makes values of kind `"index"` with a declaration. */
+const isIndex = (value: object): value is Created =>
+    "kind" in value && value.kind === "index" && "declaration" in value && typeof value.declaration === "object" && value.declaration !== null;
+
+/** What `Index.create` recorded for a value, or undefined for any other value. */
+export const indexDefinitionOf = (value: unknown): Created | undefined => typeof value === "object" && value !== null && isIndex(value) ? value : undefined;
+
+type Key = symbol;
+
+/** A lookup as a declaration holds it: by entity, or through an index. */
+type AnyLookup = { readonly index?: unknown; readonly read?: readonly Key[]; readonly has?: readonly Key[]; readonly changed?: readonly Key[] | true };
+
+const noKeys: readonly never[] = [];
+
+/** The components whose changes a lookup's rows or lists report: none for an index lookup's `changed: true`. */
+export const watchedBy = <K extends PropertyKey>(lookup: { readonly changed?: readonly K[] | true }): readonly K[] => lookup.changed === true ? noKeys : lookup.changed ?? noKeys;
+
+/** Whether a lookup's `changed` is true: its index's entries changing is a change filter of its system. */
+export const watchesEntries = (lookup: AnyLookup): boolean => lookup.changed === true;
+
+/** The index a lookup goes through, or undefined for a lookup by entity. */
+export const indexOfLookup = (lookup: AnyLookup): Created | undefined => lookup.index === undefined ? undefined : indexDefinitionOf(lookup.index);
+
+/** The key parts a lookup reads to find rows: its index's, or none for a lookup by entity. */
+export const lookupKeysOf = (lookup: AnyLookup): readonly Key[] => indexOfLookup(lookup)?.declaration.key ?? [];
+
+/**
+ * Throws for a lookup by entity whose `changed` names a component it neither reads nor has, for an index lookup whose
+ * `index` isn't a value `Index.create` returned, or whose `read` or `changed` names a component that not every entity
+ * the index holds has, and for a `changed: true` but on a system's index lookup.
+ */
+export const checkLookup = (what: "System" | "Finalizer", name: string, lookupName: string, lookup: AnyLookup): void => {
+    if (lookup.changed === true) {
+        if (what === "Finalizer") throw new Error(`Finalizer "${name}": lookup "${lookupName}"'s changed is true, which only a system's index lookup takes; a finalizer runs on each entity that stops matching.`);
+        if (lookup.index === undefined) throw new Error(`System "${name}": lookup "${lookupName}"'s changed is true, which only an index lookup takes; name the components it watches.`);
+    }
+    if (lookup.index === undefined) {
+        for (const key of watchedBy(lookup)) {
+            if (!(lookup.read ?? []).includes(key) && !(lookup.has ?? []).includes(key)) throw new Error(`${what} "${name}": lookup "${lookupName}" watches "${labelOf(key)}", which it neither reads nor has; name it in its read or has.`);
+        }
+        return;
+    }
+    const index = indexDefinitionOf(lookup.index);
+    if (index === undefined) throw new Error(`${what} "${name}": lookup "${lookupName}" goes through a value Index.create didn't return.`);
+    const held = new Set<Key>([...index.declaration.key, ...index.declaration.components?.has ?? []].map(firstKeyOf));
+    const check = (verb: string, keys: readonly Key[] | undefined): void => {
+        for (const key of keys ?? []) {
+            if (!held.has(firstKeyOf(key))) throw new Error(`${what} "${name}": lookup "${lookupName}" ${verb} "${labelOf(key)}", which not every entity index "${index.name}" holds has; name its key parts or its has.`);
+        }
+    };
+    check("reads", lookup.read);
+    check("watches", watchedBy(lookup));
+};
+
+/** The key parts a system's rows are ordered by: its `order` index's, or none. */
+export const orderKeysOf = (declaration: { readonly order?: unknown }): readonly Key[] => indexDefinitionOf(declaration.order)?.declaration.key ?? [];