@adobe/ecs 0.1.0 → 0.2.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,8 +1,9 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Key } from "./key.js";
-import type { Value } from './value.js';
+import type { Type } from './value.js';
 
 /** The resources a system can run on the condition of: their type allows `null` or `false`. */
-export type Condition = { [K in Key]: null extends Value<K> ? K : false extends Value<K> ? K : never }[Key];
+export type Condition = { [K in Key]: null extends Type<K> ? K : false extends Type<K> ? K : never }[Key];
 
 /** A condition's value while `is` holds: neither `null` nor `false`. */
-export type Holding<K extends Key> = Exclude<Value<K>, null | false>;
+export type Holding<K extends Key> = Exclude<Type<K>, null | false>;

package/src/interface/resource/index.ts

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

package/src/interface/resource/key.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Resources } from './types.js';
 
 export type Key = keyof Resources;

package/src/interface/resource/reduction.ts

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

package/src/interface/resource/register.test.ts

@@ -1,12 +1,11 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { describe, expect, it } from "vitest";
-import { Component } from "../component/component.js";
+import { registerComponent, registerResource } from "../registry/declarations.js";
 import { declarationOf, kindOf, threadOfDeclaration } from "../registry/index.js";
 import { always, cadence, clock, gpuDevice, wake, workers } from "../resources/index.js";
-import { Resource } from "./resource.js";
 
 const time = Symbol("typesResourceTest/time");
 const symbol = Symbol("typesResourceTest/symbol");
-const shared = Symbol("typesResourceTest/shared");
 const cache = Symbol("typesResourceTest/cache");
 const port = Symbol("typesResourceTest/port");
 const total = Symbol("typesResourceTest/total");
@@ -16,92 +15,79 @@ const tags = Symbol("typesResourceTest/tags");
 
 declare module "@adobe/ecs" {
     export interface Resources {
-        [time]: { type: number };
-        [symbol]: { type: boolean };
-        [shared]: { type: true };
-        [cache]: { type: Map<string, number>; thread: "main" };
+        [time]: { type: number; default: 0 };
+        [symbol]: { type: boolean; default: false };
+        [cache]: { type: ReadonlyMap<string, number>; thread: "main" };
         [port]: { type: MessagePort | null; transfer: true };
-        [total]: { type: number; reduce: "+" };
-        [flags]: { type: boolean; reduce: "|" };
+        [total]: { type: number; default: 0; reduce: "+" };
+        [flags]: { type: boolean; default: false; reduce: "|" };
         [names]: { type: ReadonlyMap<string, number> };
         [tags]: { type: ReadonlySet<string> };
     }
-    export interface Components {
-        [shared]: { type: true };
-    }
 }
 
-Resource.register(time, { type: { type: "number", default: 0 } });
-Resource.register(symbol, { type: { type: "boolean", default: false } });
-// @ts-expect-error a key declared as both a component and a resource can't be registered as either
-Component.register(shared, { type: { const: true } });
-Resource.register(cache, { default: new Map(), thread: "main" });
-Resource.register(port, { transfer: true });
-Resource.register(total, { type: { type: "number", default: 0 }, reduce: "+" });
-Resource.register(flags, { type: { type: "boolean", default: false }, reduce: "|" });
-const namesSchema = { type: "map", keys: { type: "string" }, values: { type: "number" } } as const;
-Resource.register(names, { type: namesSchema, default: new Map([["a", 1]]) });
-Resource.register(tags, { type: { type: "set", items: { type: "string" }, default: new Set(["x"]) } });
-
-const untyped: (...parameters: never[]) => unknown = Resource.register;
+/** Registers a declaration as the build does, which a test may write wrong. */
+const register = (key: unknown, declaration: object): void => registerResource(key, declaration);
 
-/** Registers as an untyped caller would, bypassing the types' checks. */
-const register = (key: unknown, declaration: object): void => {
-    Reflect.apply(untyped, undefined, [key, declaration]);
-};
+const namesSchema = { type: "map", keys: { type: "string" }, values: { type: "number" } } as const;
 
-describe("Resource.register", () => {
+describe("registering a resource", () => {
     it("records the declaration by its symbol, which needs no description", () => {
-        expect(declarationOf(time)).toEqual({ type: { type: "number", default: 0 } });
-        expect(declarationOf(symbol)).toEqual({ type: { type: "boolean", default: false } });
+        expect(declarationOf(time)).toEqual({ type: { type: "number" }, default: 0 });
+        expect(declarationOf(symbol)).toEqual({ type: { type: "boolean" }, default: false });
         expect(kindOf(symbol)).toBe("resource");
         const anonymous = Symbol();
-        register(anonymous, { type: { type: "boolean", default: false } });
+        register(anonymous, { type: { type: "boolean" }, default: false });
         expect(kindOf(anonymous)).toBe("resource");
         // Another symbol with the same description is another key.
-        expect(() => register(Symbol("typesResourceTest/symbol"), { type: { type: "number", default: 0 } })).not.toThrow();
-        expect(() => register("typesResourceTest/text", { type: { type: "number", default: 0 } })).toThrow("a key is a plain Symbol(...), not a string.");
+        expect(() => register(Symbol("typesResourceTest/symbol"), { type: { type: "number" }, default: 0 })).not.toThrow();
+        expect(() => register("typesResourceTest/text", { type: { type: "number" }, default: 0 })).toThrow("a key is a plain Symbol(...), not a string.");
     });
     it("accepts the same declaration again, and rejects a different one or one also declared as a component", () => {
-        expect(() => Resource.register(time, { type: { type: "number", default: 0 } })).not.toThrow();
-        expect(() => Resource.register(time, { type: { type: "number", default: 1 } })).toThrow(`Cannot register resource "typesResourceTest/time": already registered as a resource, with another declaration.`);
-        // @ts-expect-error a key declared as both a component and a resource can't be registered as either
-        expect(() => Resource.register(shared, { type: { const: true, default: true } })).toThrow("already registered as a component");
+        expect(() => register(time, { type: { type: "number" }, default: 0 })).not.toThrow();
+        expect(() => register(time, { type: { type: "number" }, default: 1 })).toThrow(`Cannot register resource "typesResourceTest/time": already registered as a resource, with another declaration.`);
+        const shared = Symbol("typesResourceTest/shared");
+        registerComponent(shared, { type: { const: true } });
+        expect(() => register(shared, { type: { const: true }, default: true })).toThrow("already registered as a component");
     });
-    it("takes a resource's default from its declaration or its schema, never both, and compares sets and maps by their entries", () => {
-        expect(declarationOf(names)).toEqual({ type: namesSchema, default: new Map([["a", 1]]) });
-        expect(() => Resource.register(names, { type: namesSchema, default: new Map([["a", 1]]) })).not.toThrow();
-        expect(() => Resource.register(names, { type: namesSchema, default: new Map([["a", 2]]) })).toThrow("with another declaration");
-        expect(() => Resource.register(tags, { type: { type: "set", items: { type: "string" }, default: new Set(["x"]) } })).not.toThrow();
-        expect(() => Resource.register(tags, { type: { type: "set", items: { type: "string" }, default: new Set(["y"]) } })).toThrow("with another declaration");
-        expect(() => register(Symbol("typesResourceTest/twice"), { type: { type: "number", default: 0 }, default: 1 })).toThrow("its default is given twice");
+    it("takes a resource's default from its declaration, never its schema, and compares sets and maps by their entries", () => {
+        expect(declarationOf(names)).toEqual({ type: namesSchema, fresh: "Map" });
+        expect(declarationOf(tags)).toEqual({ type: { type: "set", items: { type: "string" } }, fresh: "Set" });
+        const listed = Symbol("typesResourceTest/listed");
+        expect(() => register(listed, { type: { ...namesSchema }, default: new Map([["a", 1]]) })).not.toThrow();
+        expect(() => register(listed, { type: { ...namesSchema }, default: new Map([["a", 1]]) })).not.toThrow();
+        expect(() => register(listed, { type: { ...namesSchema }, default: new Map([["a", 2]]) })).toThrow("with another declaration");
+        expect(() => register(Symbol("typesResourceTest/inSchema"), { type: { type: "number", default: 0 } })).toThrow("its schema holds a default, which a schema never does");
+        expect(() => register(Symbol("typesResourceTest/inField"), { type: { type: "object", properties: { a: { type: "number", default: 0 } } } })).toThrow("its schema holds a default");
         expect(threadOfDeclaration(declarationOf(names) ?? {})).toBe("world");
     });
     it("declares gpuDevice on \"world\", and the loop's state as resources", () => {
         expect(declarationOf(gpuDevice)).toEqual({});
         expect(threadOfDeclaration(declarationOf(gpuDevice) ?? {})).toBe("world");
-        expect(declarationOf(workers)).toEqual({ type: { anyOf: [{ type: "integer", minimum: 0 }, { type: "null" }], default: null } });
+        expect(declarationOf(workers)).toEqual({ type: { anyOf: [{ type: "integer", minimum: 0 }, { type: "null" }] }, default: null });
         // null isn't a struct, so workers is an object resource on "world".
         expect(threadOfDeclaration(declarationOf(workers) ?? {})).toBe("world");
-        const defaults = [cadence, always, wake, clock].map(name => {
-            const type = declarationOf(name)?.type;
-            return type !== undefined && "default" in type ? type.default : undefined;
-        });
+        const defaults = [cadence, always, wake, clock].map(name => declarationOf(name)?.default);
         expect(defaults).toEqual([{ kind: "frame" }, false, Infinity, { now: 0, delta: 0, tick: 0 }]);
         expect(declarationOf(wake)?.reduce).toBe("min");
         expect([cadence, always, wake, clock].map(name => threadOfDeclaration(declarationOf(name) ?? {}))).toEqual(["world", null, null, null]);
     });
     it("checks thread and transfer as far as values tell", () => {
-        expect(declarationOf(cache)).toEqual({ default: new Map(), thread: "main" });
+        expect(declarationOf(cache)).toEqual({ type: namesSchema, thread: "main", fresh: "Map" });
         expect(threadOfDeclaration(declarationOf(cache) ?? {})).toBe("main");
         expect(declarationOf(port)).toEqual({ transfer: true });
         expect(() => register(Symbol("typesResourceTest/buffer"), { default: new ArrayBuffer(8), transfer: true })).not.toThrow();
         expect(() => register(Symbol("typesResourceTest/map"), { default: new Map(), transfer: true })).toThrow("its value isn't Transferable");
-        expect(() => register(Symbol("typesResourceTest/count"), { type: { type: "number", default: 0 }, thread: "main" })).toThrow("a struct lives in shared memory");
+        expect(() => register(Symbol("typesResourceTest/count"), { type: { type: "number" }, default: 0, thread: "main" })).toThrow("a struct lives in shared memory");
+    });
+    it("starts a fresh value only as an empty Map or Set, and not beside a default", () => {
+        expect(() => register(Symbol("typesResourceTest/array"), { fresh: "Array" })).toThrow(`fresh is "Map" or "Set".`);
+        expect(() => register(Symbol("typesResourceTest/both"), { fresh: "Map", default: null })).toThrow("it starts fresh, so it has no default.");
+        expect(() => register(Symbol("typesResourceTest/set"), { type: { type: "set", items: { type: "string" } }, fresh: "Map" })).toThrow("a set starts as a fresh Set.");
     });
     it("checks reductions", () => {
-        expect(() => register(Symbol("typesResourceTest/badOperator"), { type: { type: "number", default: 0 }, reduce: "-" })).toThrow('reduce is one of "+"');
-        expect(() => register(Symbol("typesResourceTest/sumFlags"), { type: { type: "boolean", default: false }, reduce: "+" })).toThrow('booleans reduce with "&", "|" or "^"');
-        expect(() => register(Symbol("typesResourceTest/text"), { type: { type: "string", default: "" }, reduce: "max" })).toThrow("a reduced resource is a struct");
+        expect(() => register(Symbol("typesResourceTest/badOperator"), { type: { type: "number" }, default: 0, reduce: "-" })).toThrow('reduce is one of "+"');
+        expect(() => register(Symbol("typesResourceTest/sumFlags"), { type: { type: "boolean" }, default: false, reduce: "+" })).toThrow('booleans reduce with "&", "|" or "^"');
+        expect(() => register(Symbol("typesResourceTest/text"), { type: { type: "string" }, default: "", reduce: "max" })).toThrow("a reduced resource is a struct");
     });
 });

package/src/interface/resource/resource.ts

@@ -1,4 +1,8 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Key } from './key.js';
+import type { Type } from './value.js';
 
-export type Resource = never;
+/** The type of resource `K`'s value, as its record in `Resources` declares it: `Resource<typeof clock>`. */
+export type Resource<K extends Key> = Type<K>;
 
 export * as Resource from './index.js';

package/src/interface/resource/types.ts

@@ -1,3 +1,7 @@
-/** Each resource's traits, `type` included, by augmentation: `[time]: { type: number }`. Registration must give exactly these. */
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+/**
+ * Each resource's traits, `type` and its `default` included, by augmentation in the module declaring its key:
+ * `[time]: { type: number; default: 0 }`. The build registers each.
+ */
 export interface Resources {
 }

package/src/interface/resource/value.ts

@@ -1,20 +1,21 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { ThreadOf } from '../thread/of.js';
 import type { Key } from "./key.js";
 import type { Resources } from "./types.js";
 
-/** Every resource's value type, computed once so `Value` is a lookup. */
-type ValueTypes = { readonly [K in Key]: Resources[K] extends { readonly type: infer T } ? T : never };
+/** Every resource's value type, computed once so `Type` is a lookup. */
+type Types = { readonly [K in Key]: Resources[K] extends { readonly type: infer T } ? T : never };
 
 /** The value type of resource `K`. */
-export type Value<K extends Key> = ValueTypes[K];
+export type Type<K extends Key> = Types[K];
 
 type Primitive = string | number | boolean | bigint | symbol | null | undefined;
 
 /** Resource `K`'s value as reads return it: read-only, with branded primitives such as `Entity` as they are. */
-export type ReadonlyValue<K extends Key> = Value<K> extends Primitive ? Value<K> : Readonly<Value<K>>;
+export type ReadonlyType<K extends Key> = Type<K> extends Primitive ? Type<K> : Readonly<Type<K>>;
 
 /** Every resource's thread, computed once so `ThreadOf` is a lookup. */
-type Threads = { readonly [K in Key]: ThreadOf<Resources[K], Value<K>> };
+type Threads = { readonly [K in Key]: ThreadOf<Resources[K], Type<K>> };
 
 /** The thread resource `K` lives on, or `never` for a struct, which lives in shared memory. */
 export type ThreadOfResource<K extends Key> = Threads[K];