@adobe/ecs 0.0.0-stage → 0.1.0

package/src/interface/math/vec4/u32/bitwise-xor.ts

@@ -0,0 +1,9 @@
+import type { U32 as Vec4_U32 } from "./u32.js";
+import { intrinsic } from "../../intrinsic.js";
+
+export const bitwiseXor = intrinsic({ wgsl: "^", form: "infix", parameters: ["vec4u", "vec4u"], result: "vec4u" }, ([x1, y1, z1, w1]: Vec4_U32, [x2, y2, z2, w2]: Vec4_U32): Vec4_U32 => [
+    (x1 ^ x2) >>> 0,
+    (y1 ^ y2) >>> 0,
+    (z1 ^ z2) >>> 0,
+    (w1 ^ w2) >>> 0,
+]);

package/src/interface/math/vec4/u32/clamp.ts

@@ -0,0 +1,6 @@
+import type { U32 as Vec4_U32 } from "./u32.js";
+import { max } from "./max.js";
+import { min } from "./min.js";
+import { intrinsic } from "../../intrinsic.js";
+
+export const clamp = intrinsic({ wgsl: "clamp", parameters: ["vec4u", "vec4u", "vec4u"], result: "vec4u" }, (v: Vec4_U32, minVec: Vec4_U32, maxVec: Vec4_U32): Vec4_U32 => min(max(v, minVec), maxVec));

package/src/interface/math/vec4/u32/count-leading-zeros.ts

@@ -0,0 +1,10 @@
+import type { U32 as Vec4_U32 } from "./u32.js";
+import { U32 } from "../../u32/index.js";
+import { intrinsic } from "../../intrinsic.js";
+
+export const countLeadingZeros = intrinsic({ wgsl: "countLeadingZeros", parameters: ["vec4u"], result: "vec4u" }, ([x, y, z, w]: Vec4_U32): Vec4_U32 => [
+    U32.countLeadingZeros(x),
+    U32.countLeadingZeros(y),
+    U32.countLeadingZeros(z),
+    U32.countLeadingZeros(w),
+]);

package/src/interface/math/vec4/u32/count-one-bits.ts

@@ -0,0 +1,10 @@
+import type { U32 as Vec4_U32 } from "./u32.js";
+import { U32 } from "../../u32/index.js";
+import { intrinsic } from "../../intrinsic.js";
+
+export const countOneBits = intrinsic({ wgsl: "countOneBits", parameters: ["vec4u"], result: "vec4u" }, ([x, y, z, w]: Vec4_U32): Vec4_U32 => [
+    U32.countOneBits(x),
+    U32.countOneBits(y),
+    U32.countOneBits(z),
+    U32.countOneBits(w),
+]);

package/src/interface/math/vec4/u32/count-trailing-zeros.ts

@@ -0,0 +1,10 @@
+import type { U32 as Vec4_U32 } from "./u32.js";
+import { U32 } from "../../u32/index.js";
+import { intrinsic } from "../../intrinsic.js";
+
+export const countTrailingZeros = intrinsic({ wgsl: "countTrailingZeros", parameters: ["vec4u"], result: "vec4u" }, ([x, y, z, w]: Vec4_U32): Vec4_U32 => [
+    U32.countTrailingZeros(x),
+    U32.countTrailingZeros(y),
+    U32.countTrailingZeros(z),
+    U32.countTrailingZeros(w),
+]);

package/src/interface/math/vec4/u32/equals.ts

@@ -0,0 +1,4 @@
+import type { U32 as Vec4_U32 } from "./u32.js";
+
+export const equals = (a: Vec4_U32, b: Vec4_U32): boolean =>
+    a[0] === b[0] && a[1] === b[1] && a[2] === b[2] && a[3] === b[3];

package/src/interface/math/vec4/u32/max.ts

@@ -0,0 +1,9 @@
+import type { U32 as Vec4_U32 } from "./u32.js";
+import { intrinsic } from "../../intrinsic.js";
+
+export const max = intrinsic({ wgsl: "max", parameters: ["vec4u", "vec4u"], result: "vec4u" }, ([x1, y1, z1, w1]: Vec4_U32, [x2, y2, z2, w2]: Vec4_U32): Vec4_U32 => [
+    Math.max(x1, x2) >>> 0,
+    Math.max(y1, y2) >>> 0,
+    Math.max(z1, z2) >>> 0,
+    Math.max(w1, w2) >>> 0,
+]);

package/src/interface/math/vec4/u32/min.ts

@@ -0,0 +1,9 @@
+import type { U32 as Vec4_U32 } from "./u32.js";
+import { intrinsic } from "../../intrinsic.js";
+
+export const min = intrinsic({ wgsl: "min", parameters: ["vec4u", "vec4u"], result: "vec4u" }, ([x1, y1, z1, w1]: Vec4_U32, [x2, y2, z2, w2]: Vec4_U32): Vec4_U32 => [
+    Math.min(x1, x2) >>> 0,
+    Math.min(y1, y2) >>> 0,
+    Math.min(z1, z2) >>> 0,
+    Math.min(w1, w2) >>> 0,
+]);

package/src/interface/math/vec4/u32/multiply.ts

@@ -0,0 +1,9 @@
+import type { U32 as Vec4_U32 } from "./u32.js";
+import { intrinsic } from "../../intrinsic.js";
+
+export const multiply = intrinsic({ wgsl: "*", form: "infix", parameters: ["vec4u", "vec4u"], result: "vec4u" }, ([x1, y1, z1, w1]: Vec4_U32, [x2, y2, z2, w2]: Vec4_U32): Vec4_U32 => [
+    Math.imul(x1, x2) >>> 0,
+    Math.imul(y1, y2) >>> 0,
+    Math.imul(z1, z2) >>> 0,
+    Math.imul(w1, w2) >>> 0,
+]);

package/src/interface/math/vec4/u32/negate.ts

@@ -0,0 +1,3 @@
+import type { U32 as Vec4_U32 } from "./u32.js";
+
+export const negate = ([x, y, z, w]: Vec4_U32): Vec4_U32 => [(-x) >>> 0, (-y) >>> 0, (-z) >>> 0, (-w) >>> 0];

package/src/interface/math/vec4/u32/one.ts

@@ -0,0 +1,3 @@
+import type { U32 as Vec4_U32 } from "./u32.js";
+
+export const one: Vec4_U32 = [1, 1, 1, 1];

package/src/interface/math/vec4/u32/public.ts

@@ -0,0 +1,22 @@
+export * from "./add.js";
+export * from "./bitwise-and.js";
+export * from "./bitwise-not.js";
+export * from "./bitwise-or.js";
+export * from "./bitwise-xor.js";
+export * from "./clamp.js";
+export * from "./count-leading-zeros.js";
+export * from "./count-one-bits.js";
+export * from "./count-trailing-zeros.js";
+export * from "./equals.js";
+export * from "./max.js";
+export * from "./min.js";
+export * from "./multiply.js";
+export * from "./negate.js";
+export * from "./one.js";
+export * from "./reverse-bits.js";
+export * from "./scale.js";
+export * from "./shift-left.js";
+export * from "./shift-right.js";
+export * from "./subtract.js";
+export * from "./zero.js";
+export * from "./schema.js";

package/src/interface/math/vec4/u32/reverse-bits.ts

@@ -0,0 +1,10 @@
+import type { U32 as Vec4_U32 } from "./u32.js";
+import { U32 } from "../../u32/index.js";
+import { intrinsic } from "../../intrinsic.js";
+
+export const reverseBits = intrinsic({ wgsl: "reverseBits", parameters: ["vec4u"], result: "vec4u" }, ([x, y, z, w]: Vec4_U32): Vec4_U32 => [
+    U32.reverseBits(x),
+    U32.reverseBits(y),
+    U32.reverseBits(z),
+    U32.reverseBits(w),
+]);

package/src/interface/math/vec4/u32/scale.ts

@@ -0,0 +1,10 @@
+import type { U32 as Vec4_U32 } from "./u32.js";
+import { intrinsic } from "../../intrinsic.js";
+import type { U32 } from "../../u32/index.js";
+
+export const scale = intrinsic({ wgsl: "*", form: "infix", parameters: ["vec4u", "u32"], result: "vec4u" }, ([x, y, z, w]: Vec4_U32, s: U32): Vec4_U32 => [
+    Math.imul(x, s) >>> 0,
+    Math.imul(y, s) >>> 0,
+    Math.imul(z, s) >>> 0,
+    Math.imul(w, s) >>> 0,
+]);

package/src/interface/math/vec4/u32/schema.ts

@@ -0,0 +1,4 @@
+import type { Schema } from "../../../schema/schema.js";
+import { schema as item } from "../../u32/schema.js";
+
+export const schema = { type: "array", items: item, minItems: 4, maxItems: 4 } as const satisfies Schema;

package/src/interface/math/vec4/u32/shift-left.ts

@@ -0,0 +1,8 @@
+import type { U32 as Vec4_U32 } from "./u32.js";
+
+export const shiftLeft = ([x, y, z, w]: Vec4_U32, s: number): Vec4_U32 => [
+    (x << s) >>> 0,
+    (y << s) >>> 0,
+    (z << s) >>> 0,
+    (w << s) >>> 0,
+];

package/src/interface/math/vec4/u32/shift-right.ts

@@ -0,0 +1,9 @@
+import type { U32 as Vec4_U32 } from "./u32.js";
+import { U32 } from "../../u32/index.js";
+
+export const shiftRight = ([x, y, z, w]: Vec4_U32, s: number): Vec4_U32 => [
+    U32.shiftRight(x, s),
+    U32.shiftRight(y, s),
+    U32.shiftRight(z, s),
+    U32.shiftRight(w, s),
+];

package/src/interface/math/vec4/u32/subtract.ts

@@ -0,0 +1,9 @@
+import type { U32 as Vec4_U32 } from "./u32.js";
+import { intrinsic } from "../../intrinsic.js";
+
+export const subtract = intrinsic({ wgsl: "-", form: "infix", parameters: ["vec4u", "vec4u"], result: "vec4u" }, ([x1, y1, z1, w1]: Vec4_U32, [x2, y2, z2, w2]: Vec4_U32): Vec4_U32 => [
+    (x1 - x2) >>> 0,
+    (y1 - y2) >>> 0,
+    (z1 - z2) >>> 0,
+    (w1 - w2) >>> 0,
+]);

package/src/interface/math/vec4/u32/u32.ts

@@ -0,0 +1,4 @@
+/** Vectors of integers in [0, 2^32). Functions wrap as WGSL's u32 does; for other values their results are indeterminate. */
+export type U32 = readonly [number, number, number, number];
+
+export * as U32 from "./public.js";

package/src/interface/math/vec4/u32/zero.ts

@@ -0,0 +1,3 @@
+import type { U32 as Vec4_U32 } from "./u32.js";
+
+export const zero: Vec4_U32 = [0, 0, 0, 0];

package/src/interface/platform/platform.ts

@@ -0,0 +1,35 @@
+/**
+ * The instance type of the global constructor `Name`, or `never` where the loaded libraries don't declare it, so types
+ * that name platform classes compile with or without the DOM and worker libraries.
+ */
+export type Instance<Name extends string, Scope = typeof globalThis> =
+    Scope extends { readonly [K in Name]: { readonly prototype: infer P } } ? P : never;
+
+/**
+ * A value the platform can move to another thread without copying it, as `postMessage` does with a transfer list.
+ * `MediaSourceHandle` is left out: the DOM library declares it empty, so every value would match it.
+ */
+export type Transferable<Scope = typeof globalThis> =
+    | ArrayBuffer
+    | Instance<"ImageBitmap", Scope>
+    | Instance<"OffscreenCanvas", Scope>
+    | Instance<"MessagePort", Scope>
+    | Instance<"VideoFrame", Scope>
+    | Instance<"AudioData", Scope>
+    | Instance<"ReadableStream", Scope>
+    | Instance<"WritableStream", Scope>
+    | Instance<"TransformStream", Scope>
+    | Instance<"RTCDataChannel", Scope>;
+
+/** Whether every value of `T` but `null` and `undefined` is Transferable. */
+export type IsTransferable<T, Scope = typeof globalThis> =
+    [Exclude<T, null | undefined>] extends [never] ? false :
+    [Exclude<T, null | undefined>] extends [Transferable<Scope>] ? true :
+    false;
+
+/** Whether `T`, but `null` and `undefined`, is a DOM `Node`: never where the DOM library isn't loaded. */
+export type IsNode<T, Scope = typeof globalThis> =
+    [Instance<"Node", Scope>] extends [never] ? false :
+    [Exclude<T, null | undefined>] extends [never] ? false :
+    [Exclude<T, null | undefined>] extends [Instance<"Node", Scope>] ? true :
+    false;

package/src/interface/registry/archetypes.ts

@@ -0,0 +1,23 @@
+import { labelOf } from './names.js';
+
+/** Where an archetype holds its program-wide index: a property no other code names. */
+const indexKey = Symbol("archetypeIndex");
+
+let next = 0;
+
+/**
+ * Gives a list of components a program-wide index, once, after checking it names no component twice. Throws for a
+ * component listed twice.
+ */
+export const indexArchetype = (components: readonly unknown[]): void => {
+    for (let k = 1; k < components.length; k++) {
+        if (components.indexOf(components[k]) < k) throw new Error(`An archetype lists "${labelOf(components[k])}" twice.`);
+    }
+    if (!Reflect.has(components, indexKey)) Object.defineProperty(components, indexKey, { value: next++ });
+};
+
+/** The program-wide index `Archetype.create` gave a list, or -1 for a list it wasn't given. */
+export const archetypeIndexOf = (components: readonly unknown[]): number => {
+    const index: unknown = Reflect.get(components, indexKey);
+    return typeof index === "number" ? index : -1;
+};

package/src/interface/registry/declarations.ts

@@ -0,0 +1,102 @@
+import type { Schema } from '../schema/schema.js';
+import type { Key as TraitKey } from '../trait/key.js';
+import { layoutOf } from './layout.js';
+import { claimKey, declarationOf, failRegistration, firstKeyOf, kindOf, labelOf, requireKey, sameDeclaration } from './names.js';
+import { isReduction } from './reduction.js';
+import { allowsNull, hasBoolean, isEntity, isString, isStruct } from './schemas.js';
+import { 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. A resource's `default`, or a derived object's, is what it starts at, when its
+ * schema has none.
+ */
+export type AnyDeclaration = { readonly type?: Schema; readonly default?: 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;
+    return typeof declaration.thread === "string" ? declaration.thread : "world";
+};
+
+/** 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" && !isTrait(trait)) fail(`${labelOf(trait)} isn't a registered trait.`);
+    }
+    const { type } = declaration;
+    if (type !== undefined && "default" in declaration && (kind === "component" || "default" in type)) {
+        fail(kind === "component" ? "its schema holds its default." : "its default is given twice, by its schema and its declaration.");
+    }
+    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 && type !== undefined && !("default" in type || "const" in type || allowsNull(type))) {
+        fail("a derived component's type 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 { 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.
+ */
+export 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);
+};

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

@@ -0,0 +1,52 @@
+import type { Finalizer } from '../finalizer/created.js';
+import { firstItemOf, labelOfItem } 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 => `"${labelOfItem(runner)}"`).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 "${labelOfItem(runners[a])}" and "${labelOfItem(runners[b])}" 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,14 @@
+import { idsName } 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;
+};

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

@@ -0,0 +1,124 @@
+import { describe, expect, it } from "vitest";
+import { Component } from "../component/component.js";
+import { Finalizer } from "../finalizer/finalizer.js";
+import { Resource } from "../resource/resource.js";
+import { Rule } from "../rule/rule.js";
+import { System } from "../system/system.js";
+import { Trait } from "../trait/trait.js";
+import { 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");
+
+declare module "@adobe/ecs" {
+    export interface Components {
+        [score]: { type: number };
+        [scoreAgain]: { type: number };
+        [shown]: { type: true; derived: true };
+        [shownAgain]: { type: true; derived: true };
+        [changed]: { type: number };
+        [changedAgain]: { type: string };
+        [crossed]: { type: number };
+        [unnamed]: { type: number };
+    }
+    export interface Resources {
+        [level]: { type: number };
+        [levelAgain]: { type: number };
+        [crossedAgain]: { type: number };
+    }
+    export interface Traits<N> {
+        readonly [tagged]: true;
+        readonly [taggedAgain]: true;
+    }
+}
+
+Component.register(score, { type: { type: "number" } });
+Component.register(shown, { type: { const: true }, derived: true });
+Resource.register(level, { type: { type: "number", default: 0 } });
+Component.register(changed, { type: { type: "number" } });
+Component.register(crossed, { type: { type: "number" } });
+Trait.register(tagged);
+
+describe("keys with ids", () => {
+    it("labels a key by its description, and by its id once another registered key has its description", () => {
+        expect(labelOf(score)).toBe("score");
+        Component.register(unnamed, { type: { type: "number" } });
+        expect([labelOf(score), labelOf(unnamed)]).toEqual(["idsTest/keys.ts#score", "idsTest/other.ts#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", () => {
+        Component.register(scoreAgain, { type: { type: "number" } });
+        Component.register(shownAgain, { type: { const: true }, derived: true });
+        Resource.register(levelAgain, { type: { type: "number", default: 0 } });
+        Trait.register(taggedAgain);
+        expect([kindOf(scoreAgain), kindOf(levelAgain), kindOf(taggedAgain)]).toEqual(["component", "resource", "trait"]);
+        expect(declarationOf(scoreAgain)).toBe(declarationOf(score));
+        expect(labelOf(scoreAgain)).toBe("idsTest/keys.ts#score");
+    });
+    it("rejects another symbol under a registered key's id with another declaration, or as another kind", () => {
+        expect(() => Component.register(changedAgain, { type: { type: "string" } })).toThrow(
+            `Cannot register component "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(() => Resource.register(crossedAgain, { type: { type: "number", default: 0 } })).toThrow(
+            `Cannot register resource "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", () => {
+        Component.register(unnamed, { type: { type: "number" } });
+        System.create(identify({ name: "idsTest/unnamed", components: { write: [score] } }, "idsTest/systems.ts#unnamed"), row => { row[score] = 1; });
+        expect(() => System.create(identify({ name: "idsTest/unnamed", components: { write: [unnamed] } }, "idsTest/systems.ts#unnamed"), 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.create(identify({ name: "idsTest/system", components: { write: [score] }, resources: { read: [level] } }, "idsTest/systems.ts#system"), (row, { resources }) => { row[score] = resources[level]; });
+        const again = System.create(identify({ name: "idsTest/system", components: { write: [scoreAgain] }, resources: { read: [levelAgain] } }, "idsTest/systems.ts#system"), (row, { resources }) => { row[scoreAgain] = resources[levelAgain]; });
+        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 rule = Rule.create(identify({ name: "idsTest/rule", components: { has: [score] }, derive: [shown] }, "idsTest/systems.ts#rule"));
+        const rules = programRules().length;
+        expect(Rule.create(identify({ name: "idsTest/rule", components: { has: [scoreAgain] }, derive: [shownAgain] }, "idsTest/systems.ts#rule"))).toBe(rule);
+        expect(programRules()).toHaveLength(rules);
+    });
+    it("accept a finalizer whose keys match by id, keeping its place with the new body", () => {
+        const first = Finalizer.create(identify({ name: "idsTest/finalizer", components: { read: [score] } }, "idsTest/systems.ts#finalizer"), () => {});
+        const body = (): void => {};
+        expect(Finalizer.create(identify({ name: "idsTest/finalizer", components: { read: [scoreAgain] } }, "idsTest/systems.ts#finalizer"), body)).toBe(first);
+        const found = programFinalizers().find(finalizer => finalizer.name === "idsTest/finalizer");
+        expect(found?.kind === "finalizer" ? found.body : null).toBe(body);
+    });
+    it("schedule symbols of one id as one key", () => {
+        const write = System.create({ name: "idsTest/write", components: { write: [score] } }, row => { row[score] = 1; });
+        const read = System.create({ name: "idsTest/read", components: { read: [scoreAgain] } }, row => { void row[scoreAgain]; });
+        expect(() => scheduleOf(requireDefinition(System.create({ name: "idsTest/unordered", systems: [write, read] })))).toThrow("both access");
+    });
+});

package/src/interface/registry/ids.ts

@@ -0,0 +1,30 @@
+/**
+ * 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);
+
+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;
+};

package/src/interface/registry/index.ts

@@ -0,0 +1,29 @@
+/** 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 } 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, itemOfId, labelOfItem, 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 { archetypeIndexOf } 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';