@adobe/ecs 0.1.0 → 0.2.0

package/src/interface/registry/items.ts

@@ -1,17 +1,17 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { takeLabelOfDeclaration } from './ids.js';
 /** A registered system, rule or finalizer: what each constructor records, told apart by `kind`. */
 type Registered = { readonly kind: string; readonly name: string; readonly declaration: object };
 
 /**
- * A registered item: its kind and declaration, those of the first value registered under its id, its name, its id if
- * the plugin gave one, and the label it has without one, numbered when another item had its name; shared by every
- * value registered under its id. `first` is the value registered first, which stands for it wherever items compare.
+ * A registered item: its kind and declaration, those of the first value registered under its id, and its id if the
+ * plugin gave one; shared by every value registered under its id. `first` is the value registered first, which stands
+ * for it wherever items compare.
  */
 type Entry = {
     readonly kind: string;
     readonly declaration: object;
-    readonly name: string;
     readonly id: string | undefined;
-    readonly numbered: string;
     readonly first: Registered;
 };
 
@@ -21,12 +21,6 @@ const entries = new WeakMap<object, Entry>();
 /** Entries by the ids the plugin gave their declarations. */
 const identified = new Map<string, Entry>();
 
-/** Numbered labels given, so each item's is unique. */
-const labels = new Set<string>();
-
-/** How many registered items have each name. */
-const named = new Map<string, number>();
-
 /** Whether two values are one item: the same value, or values registered under one id. */
 export const sameItem = (a: object, b: object): boolean => {
     if (a === b) return true;
@@ -37,17 +31,6 @@ export const sameItem = (a: object, b: object): boolean => {
 /** The value first registered as this item, which stands for it wherever items compare; any other value as it is. */
 export const firstItemOf = (item: object): object => entries.get(item)?.first ?? item;
 
-/**
- * How errors and reports name a system, rule or finalizer: its name while no other registered item has it, else its
- * name with its id when the plugin gave one, and without one its name numbered by registration order. An item not
- * registered is named by its name.
- */
-export const labelOfItem = (item: { readonly name: string }): string => {
-    const entry = entries.get(item);
-    if (entry === undefined || (named.get(entry.name) ?? 0) <= 1) return item.name;
-    return entry.id === undefined ? entry.numbered : `${entry.name} (${entry.id})`;
-};
-
 /**
  * The item already registered under `id` that `item` is: one of its kind with the same declaration, as a module
  * evaluated again declares it; undefined without an id or for an id not registered. Throws for an id registered as
@@ -64,22 +47,6 @@ export const registeredAs = <T extends Registered>(item: T, id: string | undefin
     return entry.first;
 };
 
-/** A label for an item registered now without an id, its name numbered when another item's has it. */
-const numberedFor = (name: string): string => {
-    let label = name;
-    for (let n = 2; labels.has(label); n++) label = `${name}#${n}`;
-    labels.add(label);
-    return label;
-};
-
-/** An item without an id is forgotten once collected: its name's count and numbered label go with it. */
-const forgotten = new FinalizationRegistry<{ readonly name: string; readonly numbered: string }>(({ name, numbered }) => {
-    labels.delete(numbered);
-    const count = (named.get(name) ?? 0) - 1;
-    if (count > 0) named.set(name, count);
-    else named.delete(name);
-});
-
 /**
  * Records an item under its id: a value of an item `registeredAs` found shares its entry, and any other is a new item.
  */
@@ -89,28 +56,31 @@ export const recordItem = (item: Registered, id: string | undefined, existing: o
         entries.set(item, shared);
         return;
     }
-    const entry: Entry = { kind: item.kind, declaration: item.declaration, name: item.name, id, numbered: numberedFor(item.name), first: item };
-    named.set(item.name, (named.get(item.name) ?? 0) + 1);
+    const entry: Entry = { kind: item.kind, declaration: item.declaration, id, first: item };
     if (id !== undefined) identified.set(id, entry);
-    else forgotten.register(item, { name: item.name, numbered: entry.numbered });
     entries.set(item, entry);
 };
 
-/** How many items of each kind were declared without a name or an id, to number their labels. */
+/** How many items of each kind were labeled by number, to number the next. */
 const anonymous = new Map<string, number>();
 
 /**
- * An item's name: the one its declaration gives; without one, its binding with the id the plugin gave it
- * (`spawn (src/setup.ts#spawn)`), and without an id, its kind numbered by creation (`system #3`).
+ * An item's label: the one the plugin gave its constructor call's first argument, `value`, by the binding or function
+ * it's in, or an internal factory gave it; else its binding, from its id (`spawn` for `src/setup.ts#spawn`); else its
+ * kind numbered by creation (`system #3`).
  */
-export const nameOf = (name: string | undefined, id: string | undefined, kind: "system" | "rule" | "finalizer" | "index"): string => {
-    if (name !== undefined) return name;
-    if (id !== undefined) return `${id.slice(id.lastIndexOf("#") + 1)} (${id})`;
+export const nameOf = (value: object, id: string | undefined, kind: "system" | "rule" | "finalizer" | "index"): string => {
+    const label = takeLabelOfDeclaration(value);
+    if (label !== undefined) return label;
+    if (id !== undefined) return id.slice(id.lastIndexOf("#") + 1);
     const count = (anonymous.get(kind) ?? 0) + 1;
     anonymous.set(kind, count);
     return `${kind} #${count}`;
 };
 
+/** The id the plugin gave an item, or null without one, as failures give it beside its label. */
+export const idOrNull = (item: object): string | null => entries.get(item)?.id ?? null;
+
 /** The id the plugin gave a system, rule or finalizer, by which other threads name it, if it gave one. */
 export const idOfItem = (item: object): string | undefined => entries.get(item)?.id;
 

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

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { describe, expect, it } from "vitest";
 import type { Schema } from "../schema/schema.js";
 import { threadOfDeclaration } from "./declarations.js";
@@ -34,6 +35,25 @@ describe("layoutOf", () => {
         expect(placement({ type: "object", properties: { flag: { type: "boolean" }, weight: { type: "number" }, mass: f32 } })).toEqual({ stride: 24, offsets: [0, 8, 16] });
     });
 
+    it("stores a union of number constants as a number column: integers at the narrowest width holding them", () => {
+        const views = (schema: Schema) => {
+            const layout = layoutOf(schema);
+            return layout.kind === "linear" ? layout.leaves.map(leaf => leaf.view) : layout.kind;
+        };
+        expect(views({ anyOf: [{ const: 0 }, { const: 1 }, { const: 2 }] })).toEqual(["u32"]);
+        expect(views({ anyOf: [{ const: 1 }, { const: -1 }] })).toEqual(["i32"]);
+        expect(views({ anyOf: [{ const: 0.5 }, { const: 1 }] })).toEqual(["f64"]);
+        expect(views({ anyOf: [{ const: 0 }, { const: 2 ** 40 }] })).toEqual(["f64"]);
+        // An integer column would store -0 as 0.
+        expect(views({ anyOf: [{ const: -0 }, { const: 1 }] })).toEqual(["f64"]);
+        expect(views({ type: "object", properties: { mode: { anyOf: [{ const: 0 }, { const: 1 }] }, at: f32 } })).toEqual(["u32", "f32"]);
+        expect(views({ anyOf: [{ const: 0 }, { const: "a" }] })).toBe("object");
+        expect(views({ anyOf: [{ const: 0 }, { type: "null" }] })).toBe("object");
+        // A struct, so it lives in shared memory, on no thread.
+        expect(isStruct({ anyOf: [{ const: 0 }, { const: 1 }] })).toBe(true);
+        expect(threadOfDeclaration({ type: { anyOf: [{ const: 0 }, { const: 1 }] } })).toBe(null);
+    });
+
     it("stores sets and maps as objects, even of numbers, and nothing in them as a struct", () => {
         const set: Schema = { type: "set", items: { type: "number" } };
         const map: Schema = { type: "map", keys: { type: "integer", minimum: 0, maximum: 9 }, values: { type: "boolean" } };

package/src/interface/registry/layout.ts

@@ -1,5 +1,6 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Schema } from '../schema/schema.js';
-import { isString } from './schemas.js';
+import { isString, numberConstants } from './schemas.js';
 
 /** A path from a value to one scalar leaf: `[]` for a scalar, `[1]` for a tuple element, `["x"]` for a struct field. */
 export type Path = readonly (number | string)[];
@@ -33,14 +34,15 @@ export type Leaf = {
 
 /**
  * How a component's values are stored.
- * - `constant`: a `const` schema; no storage, every value is `value`.
+ * - `constant`: a `const` schema; no storage, every value is `value`. A shared component's is one of these per archetype,
+ *   `shared`, its value the archetype's, and its component's is its start.
  * - `linear`: interleaved elements of `stride` bytes in one column. `read` copies a value out; `write` replaces it.
  * - `string`: the world's thread's values, as `object`'s, and a 4-byte handle per row, in one column, to each one's
  *   record in shared memory, which other threads read; only the world's thread writes them.
  * - `object`: a JS array of values, on its logical thread only.
  */
 export type Layout =
-    | { readonly kind: "constant"; readonly value: unknown }
+    | { readonly kind: "constant"; readonly value: unknown; readonly shared?: true }
     | {
         readonly kind: "linear";
         readonly leaves: readonly Leaf[];
@@ -82,6 +84,12 @@ const integerScalar = ({ minimum, maximum }: { readonly minimum?: number; readon
 
 /** `null` if the schema isn't linear: numbers, booleans, fixed-length tuples and structs of those. */
 const shapeOf = (schema: Schema): Shape | null => {
+    // A union of number constants is a number: integers at the narrowest width holding them, and with -0, which an
+    // integer can't hold, f64.
+    const constants = numberConstants(schema);
+    if (constants !== null) {
+        return { kind: "scalar", scalar: constants.every(constant => Number.isInteger(constant) && !Object.is(constant, -0)) ? integerScalar({ minimum: Math.min(...constants), maximum: Math.max(...constants) }) : "f64" };
+    }
     if (!("type" in schema)) return null;
     switch (schema.type) {
         case "number": return { kind: "scalar", scalar: schema.precision === 1 ? "f32" : "f64" };

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

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { describe, expect, it } from "vitest";
 import type { AnyDeclaration } from "./declarations.js";
 import { identify } from "./ids.test-helper.js";
@@ -41,35 +42,32 @@ describe("claimKey", () => {
 });
 
 describe("labelOf", () => {
-    it("labels a key by its description while no other registered key has it, else by its id", () => {
+    it("labels a key by its description, whatever other keys have it", () => {
         const first = Symbol("labelOf/shared");
         const second = Symbol("labelOf/shared");
-        const lone = Symbol("labelOf/lone");
         identify(first, "a.ts#first");
         identify(second, "b.ts#second");
-        identify(lone, "c.ts#lone");
-        expect([labelOf(first), labelOf(lone)]).toEqual(["labelOf/shared", "labelOf/lone"]);
         claimKey(first, "component", number);
-        claimKey(lone, "component", number);
-        expect([labelOf(first), labelOf(second), labelOf(lone)]).toEqual(["labelOf/shared", "b.ts#second", "labelOf/lone"]);
         claimKey(second, "resource", number);
-        expect([labelOf(first), labelOf(second), labelOf(lone)]).toEqual(["a.ts#first", "b.ts#second", "labelOf/lone"]);
+        expect([labelOf(first), labelOf(second)]).toEqual(["labelOf/shared", "labelOf/shared"]);
+        const twin = Symbol("labelOf/shared");
+        claimKey(twin, "trait");
+        expect(labelOf(twin)).toBe("labelOf/shared");
     });
-    it("labels a key without an id by its description, numbered by registration when another key has it", () => {
-        const first = Symbol("labelOf/twin");
-        const second = Symbol("labelOf/twin");
-        const third = Symbol("labelOf/twin");
-        expect(labelOf(first)).toBe("labelOf/twin");
-        claimKey(second, "component", { type: { type: "number" } });
-        claimKey(first, "component", { type: { type: "number" } });
-        claimKey(third, "trait");
-        expect([labelOf(first), labelOf(second), labelOf(third)]).toEqual(["labelOf/twin#2", "labelOf/twin", "labelOf/twin#3"]);
+    it("labels a key without a description by its binding, which the plugin's id names", () => {
+        const speed = Symbol();
+        const other = Symbol();
+        identify(speed, "app@1.0.0/keys.ts#labelOfSpeed");
+        identify(other, "app@1.0.0/other.ts#labelOfSpeed");
+        claimKey(speed, "resource", number);
+        claimKey(other, "component", number);
+        expect([labelOf(speed), labelOf(other)]).toEqual(["labelOfSpeed", "labelOfSpeed"]);
     });
-    it("gives a key without a description a numbered label, and names other values as text", () => {
+    it("gives a key without a description or an id a numbered label, and names other values as text", () => {
         const anonymous = Symbol();
         expect(labelOf(anonymous)).toBe("Symbol()");
         claimKey(anonymous, "trait");
-        expect(labelOf(anonymous)).toMatch(/^Symbol\(\)(#\d+)?$/);
+        expect(labelOf(anonymous)).toBe("Symbol()");
         expect([labelOf("text"), labelOf(1)]).toEqual(["text", "1"]);
     });
 });

package/src/interface/registry/names.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { AnyDeclaration } from './declarations.js';
 import { idOfKey } from './ids.js';
 import { sameItem } from './items.js';
@@ -6,16 +7,14 @@ import { sameItem } from './items.js';
 export type Kind = "component" | "resource" | "trait";
 
 /**
- * A registered key: its kind, its declaration (none for a trait), its description, its id if the plugin gave one, and
- * the label it has without one, numbered when another key had its description; shared by every symbol registered under
- * its id. `first` is the symbol registered first, `newest` the one registered last.
+ * A registered key: its kind, its declaration (none for a trait), its label and its id if the plugin gave one; shared
+ * by every symbol registered under its id. `first` is the symbol registered first, `newest` the one registered last.
  */
 type Entry = {
     readonly kind: Kind;
     readonly declaration: AnyDeclaration | undefined;
     readonly description: string;
     readonly id: string | undefined;
-    readonly numbered: string;
     readonly first: symbol;
     newest: symbol;
 };
@@ -26,14 +25,13 @@ const entries = new Map<symbol, Entry>();
 /** Entries by the ids the plugin gave their keys. */
 const identified = new Map<string, Entry>();
 
-/** Numbered labels given, so each key's is unique. */
-const labels = new Set<string>();
-
-/** How many registered keys have each description. */
-const described = new Map<string, number>();
-
-/** A symbol's description, `Symbol()` without one. */
-const descriptionOf = (key: symbol): string => key.description === undefined || key.description === "" ? "Symbol()" : key.description;
+/** A symbol's description; without one, its binding, which the plugin's id names, or `Symbol()` without an id. */
+const descriptionOf = (key: symbol): string => {
+    if (key.description !== undefined && key.description !== "") return key.description;
+    const id = idOfKey(key);
+    const binding = id === undefined ? "" : id.slice(id.lastIndexOf("#") + 1);
+    return binding === "" ? "Symbol()" : binding;
+};
 
 /** `Symbol.iterator` and the rest, which the platform shares, so they can't be keys. */
 const wellKnown: ReadonlyMap<symbol, string> = new Map(Reflect.ownKeys(Symbol).flatMap((name): [symbol, string][] => {
@@ -41,52 +39,60 @@ const wellKnown: ReadonlyMap<symbol, string> = new Map(Reflect.ownKeys(Symbol).f
     return typeof value === "symbol" ? [[value, `Symbol.${String(name)}`]] : [];
 }));
 
+/** Registers what the build declared since it last ran; the registry's declarations install it. */
+let catchUp = (): void => {};
+
+/** Installs what registers the build's declarations, which every read of keys runs first. */
+export const installCatchUp = (update: () => void): void => {
+    catchUp = update;
+};
+
+/** Why each key the build declared failed to register, for the errors its uses give. */
+const failures = new Map<symbol, string>();
+
+/** Records why a key the build declared failed to register. */
+export const recordFailure = (key: symbol, message: string): void => {
+    failures.set(key, message);
+};
+
+/** A key's entry, once what the build declared is registered. */
+const entryOf = (key: symbol): Entry | undefined => {
+    catchUp();
+    return entries.get(key);
+};
+
 /** Whether a key is a component, a resource or a trait. */
-export const kindOf = (key: unknown): Kind | undefined => typeof key === "symbol" ? entries.get(key)?.kind : undefined;
+export const kindOf = (key: unknown): Kind | undefined => typeof key === "symbol" ? entryOf(key)?.kind : undefined;
 
 /** The declaration of a registered component or resource. */
-export const declarationOf = (key: unknown): AnyDeclaration | undefined => typeof key === "symbol" ? entries.get(key)?.declaration : undefined;
+export const declarationOf = (key: unknown): AnyDeclaration | undefined => typeof key === "symbol" ? entryOf(key)?.declaration : undefined;
 
 /** Whether two values are one key: the same value, or symbols registered under one id. */
 export const sameKey = (a: unknown, b: unknown): boolean => {
     if (a === b) return true;
     if (typeof a !== "symbol" || typeof b !== "symbol") return false;
-    const entry = entries.get(a);
+    const entry = entryOf(a);
     return entry !== undefined && entry === entries.get(b);
 };
 
 /** The symbol first registered as this key, which stands for it wherever keys are compared; any other value as it is. */
-export const firstKeyOf = <K>(key: K): K | symbol => typeof key === "symbol" ? entries.get(key)?.first ?? key : key;
+export const firstKeyOf = <K>(key: K): K | symbol => typeof key === "symbol" ? entryOf(key)?.first ?? key : key;
 
 /** The symbol last registered as this key, by which a world gives values; any other value as it is. */
-export const newestKeyOf = <K>(key: K): K | symbol => typeof key === "symbol" ? entries.get(key)?.newest ?? key : key;
+export const newestKeyOf = <K>(key: K): K | symbol => typeof key === "symbol" ? entryOf(key)?.newest ?? key : key;
 
 /**
- * How errors and reports name a key: its description, `Symbol()` without one, while no other registered key has it;
- * else its id when the plugin gave it one, and without one, for a registered key, its description numbered by
- * registration order. Any other value is named as text.
+ * How errors name a key: its description, or without one its binding from its id, whatever other keys
+ * have; for display only, with its id (`idOfKey`) to tell keys of one label apart. Any other value is named as text.
  */
 export const labelOf = (key: unknown): string => {
     if (typeof key !== "symbol") return String(key);
-    const known = wellKnown.get(key);
-    if (known !== undefined) return known;
-    const entry = entries.get(key);
-    const description = entry?.description ?? descriptionOf(key);
-    if ((described.get(description) ?? 0) <= (entry === undefined ? 0 : 1)) return description;
-    return entry === undefined ? idOfKey(key) ?? description : entry.id ?? entry.numbered;
+    return wellKnown.get(key) ?? entries.get(key)?.description ?? descriptionOf(key);
 };
 
-/** A label for a key registered now without an id, its description numbered when another key's has it. */
-const numberedFor = (description: string): string => {
-    let label = description;
-    for (let n = 2; labels.has(label); n++) label = `${description}#${n}`;
-    labels.add(label);
-    return label;
-};
-
-/** Throws, naming the key, for a key registration can't take. */
-export const failRegistration = (kind: Kind, key: unknown, message: string): never => {
-    throw new Error(`Cannot register ${kind} "${labelOf(key)}": ${message}`);
+/** Throws, naming the key by its label, and by `id` too where the failure is its id's, for a key registration can't take. */
+export const failRegistration = (kind: Kind, key: unknown, message: string, id?: string): never => {
+    throw new Error(`Cannot register ${kind} "${labelOf(key)}"${id === undefined ? "" : ` (${id})`}: ${message}`);
 };
 
 /** The key, or a throw for one that isn't a plain `Symbol(...)`: a `Symbol.for` or well-known symbol is shared. */
@@ -135,20 +141,34 @@ export const claimKey = (key: unknown, kind: Kind, declaration?: AnyDeclaration)
     const id = idOfKey(symbol);
     const named = id === undefined ? undefined : identified.get(id);
     if (named !== undefined) {
-        if (named.kind !== kind) failRegistration(kind, symbol, `its id is a ${named.kind}'s.`);
+        if (named.kind !== kind) failRegistration(kind, symbol, `its id is a ${named.kind}'s.`, id);
         if (!sameDeclaration(named.declaration, declaration)) {
-            failRegistration(kind, symbol, "its id is another key's, with another declaration; if a module was evaluated again with a changed declaration, reload the page.");
+            failRegistration(kind, symbol, "its id is another key's, with another declaration; if a module was evaluated again with a changed declaration, reload the page.", id);
         }
         named.newest = symbol;
         entries.set(symbol, named);
         return;
     }
     const description = descriptionOf(symbol);
-    const entry: Entry = { kind, declaration, description, id, numbered: numberedFor(description), first: symbol, newest: symbol };
-    described.set(description, (described.get(description) ?? 0) + 1);
+    const entry: Entry = { kind, declaration, description, id, first: symbol, newest: symbol };
     if (id !== undefined) identified.set(id, entry);
     entries.set(symbol, entry);
 };
 
 /** The symbol last registered under an id, by which a world gives values, or undefined where none was. */
-export const keyOfId = (id: string): symbol | undefined => identified.get(id)?.newest;
+export const keyOfId = (id: string): symbol | undefined => {
+    catchUp();
+    return identified.get(id)?.newest;
+};
+
+/**
+ * Why a key isn't registered, for errors: its declaration failed to register; or the build registers keys from their
+ * declarations, so either its module wasn't built with the plugin, which gives keys ids, or it isn't declared.
+ */
+export const whyUnregistered = (key: unknown): string => {
+    const failure = typeof key === "symbol" ? failures.get(key) : undefined;
+    if (failure !== undefined) return `its declaration failed to register: ${failure}`;
+    return typeof key === "symbol" && idOfKey(key) === undefined
+        ? "the build's Compiler.plugin() registers keys from their declarations, and didn't build the module making it"
+        : "declare it beside its key, in interface Components or Resources";
+};

package/src/interface/registry/program.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Finalizer } from '../finalizer/created.js';
 import type { Rule } from '../rule/created.js';
 import type { Definition } from '../system/definition.js';

package/src/interface/registry/reduction.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Reduction } from '../resource/reduction.js';
 
 /** Every reduction operator. */

package/src/interface/registry/schedule.ts

@@ -1,25 +1,22 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Schema } from '../schema/schema.js';
 import type { Definition } from '../system/definition.js';
 import type { Leaf } from '../system/leaf.js';
-import { firstItemOf, labelOfItem } from './items.js';
+import { firstItemOf } from './items.js';
 import { requireDefinition } from './program.js';
 import { firstKeyOf, labelOf, sameDeclaration } from './names.js';
 import { lookupKeysOf, orderKeysOf } from './indexes.js';
 
 type Key = symbol;
 
-/** Throws unless each leaf's input is an object schema of named fields, and a field several declare has one schema. */
+/** Throws unless a field of the input several leaves take has one schema. */
 const checkInputs = (leaves: readonly Leaf[]): void => {
     const fields = new Map<string, { readonly schema: Schema; readonly system: string }>();
     for (const leaf of leaves) {
-        const { input } = leaf.declaration;
-        const name = labelOfItem(leaf);
+        const { input } = leaf;
+        const name = leaf.name;
         if (input === undefined) continue;
-        const schema: Schema = input;
-        if (!("type" in schema) || schema.type !== "object" || typeof schema.properties !== "object" || schema.properties === null) {
-            throw new Error(`System "${name}": input is an object schema of named fields.`);
-        }
-        for (const [field, property] of Object.entries(schema.properties)) {
+        for (const [field, property] of Object.entries(input.properties)) {
             const seen = fields.get(field);
             if (seen === undefined) fields.set(field, { schema: property, system: name });
             else if (!sameDeclaration(seen.schema, property)) {
@@ -39,7 +36,7 @@ export type Schedule = { readonly tiers: readonly (readonly Leaf[])[]; readonly
 export const isLeaf = (system: Definition): system is Leaf => system.kind !== "composite";
 
 /** Whether a system is an observer leaf, which runs after a sync point rather than in a tier. */
-export const isObserver = (system: Definition): system is Leaf => system.kind !== "composite" && system.declaration.observer === true;
+export const isObserver = (system: Definition): system is Leaf & { readonly declaration: { readonly observer: true } } => system.kind !== "composite" && system.declaration.observer === true;
 
 /** Each system is an interval, from its start node to its end node. */
 const start = (unit: number): number => 2 * unit;
@@ -104,7 +101,7 @@ const topologicalOrder = ({ units, successors }: Graph): number[] => {
         for (const next of successors[node]) if (--incoming[next] === 0) ready.push(next);
     }
     if (order.length < successors.length) {
-        const cyclic = units.filter((_, unit) => incoming[start(unit)] > 0 || incoming[end(unit)] > 0).map(system => `"${labelOfItem(system)}"`);
+        const cyclic = units.filter((_, unit) => incoming[start(unit)] > 0 || incoming[end(unit)] > 0).map(system => `"${system.name}"`);
         throw new Error(`Ordering cycle between ${cyclic.join(", ")}.`);
     }
     return order;
@@ -143,8 +140,7 @@ type Access = { readonly reads: ReadonlySet<Key>; readonly writes: ReadonlySet<K
 
 /** The resources a leaf reduces into. */
 export const reducedBy = (leaf: Leaf): readonly Key[] => {
-    const { reduce } = leaf.declaration;
-    return reduce === undefined ? [] : Object.getOwnPropertySymbols(reduce).filter(key => Reflect.get(reduce, key) !== undefined);
+    return leaf.declaration.resources?.reduce ?? [];
 };
 
 /**
@@ -204,7 +200,7 @@ const createSchedule = (system: Definition): Schedule => {
         for (let b = a + 1; b < leaves.length; b++) {
             const key = conflictOf(accesses[a], accesses[b]);
             if (key !== undefined && !ordered(reach, leaves[a].unit, leaves[b].unit)) {
-                throw new Error(`Systems "${labelOfItem(leaves[a].leaf)}" and "${labelOfItem(leaves[b].leaf)}" both access "${labelOf(key)}" and one writes it; order them with before or after.`);
+                throw new Error(`Systems "${leaves[a].leaf.name}" and "${leaves[b].leaf.name}" both access "${labelOf(key)}" and one writes it; order them with before or after.`);
             }
         }
     }

package/src/interface/registry/schemas.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Schema } from '../schema/schema.js';
 
 /** Whether a constant is a struct's value: numbers and booleans, in fixed arrays and objects. */
@@ -5,9 +6,21 @@ const isStructValue = (value: unknown): boolean =>
     typeof value === "number" || typeof value === "boolean"
     || (Array.isArray(value) ? value.every(isStructValue) : typeof value === "object" && value !== null && Object.values(value).every(isStructValue));
 
+/** The values of a union of number constants, which is stored as a number, or null for any other schema. */
+export const numberConstants = (schema: Schema): readonly number[] | null => {
+    if (!("anyOf" in schema) || schema.anyOf.length === 0) return null;
+    const values: number[] = [];
+    for (const option of schema.anyOf) {
+        if (!("const" in option) || typeof option.const !== "number") return null;
+        values.push(option.const);
+    }
+    return values;
+};
+
 /** Whether a schema describes a struct: numbers, booleans, entities, fixed-length tuples and structs of those. */
 export const isStruct = (schema: Schema): boolean => {
     if ("const" in schema) return isStructValue(schema.const);
+    if (numberConstants(schema) !== null) return true;
     if (!("type" in schema)) return false;
     switch (schema.type) {
         case "number":
@@ -28,6 +41,27 @@ export const isStruct = (schema: Schema): boolean => {
 
 const isNull = (schema: Schema): boolean => ("type" in schema && schema.type === "null") || ("const" in schema && schema.const === null);
 
+/** Whether a constant is comparable data: numbers, booleans, strings, and arrays and plain objects of those. */
+const isComparableValue = (value: unknown): boolean =>
+    typeof value === "number" || typeof value === "boolean" || typeof value === "string"
+    || (Array.isArray(value) ? value.every(isComparableValue) : typeof value === "object" && value !== null && Object.values(value).every(isComparableValue));
+
+/**
+ * Whether a schema describes comparable data, which a shared component holds: numbers, booleans, strings, and arrays
+ * and objects of those, compared by structure. Not `null`, sets or maps.
+ */
+export const isComparable = (schema: Schema): boolean => {
+    if ("const" in schema) return isComparableValue(schema.const);
+    if ("anyOf" in schema) return schema.anyOf.length > 0 && schema.anyOf.every(isComparable);
+    if ("allOf" in schema) return schema.allOf.length > 0 && schema.allOf.every(isComparable);
+    switch (schema.type) {
+        case "number": case "integer": case "boolean": case "string": return true;
+        case "array": return isComparable(schema.items);
+        case "object": return Object.values(schema.properties).every(isComparable);
+        default: return false;
+    }
+};
+
 /** Whether a schema describes a string: any string, a string `const`, or a union of those, with `null` or without. */
 export const isString = (schema: Schema): boolean => {
     if ("const" in schema) return typeof schema.const === "string";
@@ -59,3 +93,27 @@ export const isEntity = (schema: Schema): boolean => "format" in schema && schem
 export const conditional = (schema: Schema): boolean =>
     allowsNull(schema) || ("type" in schema && schema.type === "boolean") || ("const" in schema && schema.const === false)
     || ("anyOf" in schema && schema.anyOf.some(conditional));
+
+/** Whether `value` is one of `schema`'s values, as a default must be: its type, length, range and fields. */
+export const matchesSchema = (schema: Schema, value: unknown): boolean => {
+    if ("anyOf" in schema) return schema.anyOf.some(member => matchesSchema(member, value));
+    if ("allOf" in schema) return schema.allOf.every(member => matchesSchema(member, value));
+    if ("const" in schema) return Object.is(schema.const, value) || JSON.stringify(schema.const) === JSON.stringify(value);
+    switch (schema.type) {
+        case "null": return value === null;
+        case "boolean": return typeof value === "boolean";
+        case "string": return typeof value === "string" && value.length >= (schema.minLength ?? 0) && value.length <= (schema.maxLength ?? Infinity);
+        case "number": return typeof value === "number" && (Number.isNaN(value) || (value >= (schema.minimum ?? -Infinity) && value <= (schema.maximum ?? Infinity)));
+        case "integer": return typeof value === "number" && Number.isInteger(value) && ("format" in schema || (value >= (schema.minimum ?? -Infinity) && value <= (schema.maximum ?? Infinity)));
+        case "array": return Array.isArray(value) && value.length >= (schema.minItems ?? 0) && value.length <= (schema.maxItems ?? Infinity) && value.every(item => matchesSchema(schema.items, item));
+        case "set": return value instanceof Set;
+        case "map": return value instanceof Map;
+        case "object": {
+            if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+            const required = schema.required ?? Object.keys(schema.properties);
+            return Object.entries(value).every(([field, item]) => field in schema.properties && matchesSchema(schema.properties[field] ?? { allOf: [] }, item))
+                && required.every(field => field in value);
+        }
+        default: return false;
+    }
+};

package/src/interface/registry/strata.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 /**
  * Structural derivation: which components an archetype's entities have once rules and `within` are applied.
  * Datalog with stratified negation over the components each entity has. A rule adds the components it derives where

package/src/interface/registry/threads.ts

@@ -1,6 +1,7 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { threadOfDeclaration } from './declarations.js';
 import { lookupKeysOf, orderKeysOf } from './indexes.js';
-import { declarationOf, kindOf, labelOf } from './names.js';
+import { declarationOf, kindOf, labelOf, whyUnregistered } from './names.js';
 
 type Key = symbol;
 type Lists = {
@@ -27,7 +28,7 @@ export type Placed = {
 export const requireRegistered = (what: "System" | "Finalizer", name: string, kind: "component" | "resource", keys: readonly Key[] | undefined): void => {
     for (const key of keys ?? []) {
         if (declarationOf(key) === undefined || kindOf(key) !== kind) {
-            throw new Error(`${what} "${name}" uses ${kind} "${labelOf(key)}", which isn't a registered ${kind}; import the module that registers it.`);
+            throw new Error(`${what} "${name}" uses ${kind} "${labelOf(key)}", which isn't a registered ${kind}: ${whyUnregistered(key)}.`);
         }
     }
 };

package/src/interface/registry/traits.ts

@@ -1,7 +1,8 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { claimKey, kindOf } from './names.js';
 import type { BuiltIn } from '../trait/key.js';
 
-const builtIn: ReadonlySet<unknown> = new Set<BuiltIn>(["type", "derived", "within", "reference", "reduce", "thread", "transfer"]);
+const builtIn: ReadonlySet<unknown> = new Set<BuiltIn>(["type", "derived", "within", "reference", "reduce", "thread", "transfer", "shared"]);
 
 /** Whether `name` is a trait: a built-in one's string, or a registered trait's symbol. */
 export const isTrait = (name: unknown): boolean => builtIn.has(name) || kindOf(name) === "trait";

package/src/interface/registry/written.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { clock } from '../resources/clock.js';
 import { labelOf } from './names.js';
 

package/src/interface/resource/condition.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Key } from "./key.js";
 import type { Value } from './value.js';