@adobe/ecs 0.0.0-stage → 0.1.0

package/src/interface/registry/strata.ts

@@ -0,0 +1,93 @@
+/**
+ * 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
+ * its query matches; a component declared within a host stays only while the host is present. Each stratum is a least
+ * fixed point, evaluated after every stratum it depends on, so the result is a pure function of the archetype.
+ */
+
+/** A rule as component ids. */
+export type RuleFacts = { readonly has: readonly number[]; readonly not: readonly number[]; readonly derives: readonly number[] };
+
+/** Strata in evaluation order: the rules deriving into each, with only that stratum's components, and its `within` dependents. */
+export type Strata = readonly {
+    readonly rules: readonly { readonly has: readonly number[]; readonly not: readonly number[]; readonly derives: readonly number[] }[];
+    readonly within: readonly { readonly dependent: number; readonly host: number }[];
+}[];
+
+type Edge = { readonly to: number; readonly negative: boolean; readonly within: boolean };
+
+/**
+ * Orders rules and `within` declarations into strata. Throws for a cycle through a negation, which could oscillate,
+ * and for a cycle through `within`. `hosts[id]` is the host of a component declared within one, or -1.
+ */
+export const strataOf = (rules: readonly RuleFacts[], hosts: readonly number[], nameOf: (id: number) => string): Strata => {
+    const edges = new Map<number, Edge[]>();
+    const nodes = new Set<number>();
+    const edge = (from: number, to: number, negative: boolean, within: boolean): void => {
+        nodes.add(from);
+        nodes.add(to);
+        let list = edges.get(from);
+        if (list === undefined) edges.set(from, list = []);
+        list.push({ to, negative, within });
+    };
+    for (const rule of rules) {
+        for (const derived of rule.derives) {
+            for (const id of rule.has) edge(id, derived, false, false);
+            for (const id of rule.not) edge(id, derived, true, false);
+            nodes.add(derived);
+        }
+    }
+    hosts.forEach((host, dependent) => { if (host >= 0) edge(host, dependent, false, true); });
+    // Tarjan's algorithm: each component is emitted after every component it reaches, so dependents come out first.
+    const index = new Map<number, number>();
+    const low = new Map<number, number>();
+    const stack: number[] = [];
+    const onStack = new Set<number>();
+    const components: number[][] = [];
+    let counter = 0;
+    const visit = (node: number): void => {
+        index.set(node, counter);
+        low.set(node, counter);
+        counter++;
+        stack.push(node);
+        onStack.add(node);
+        for (const { to } of edges.get(node) ?? []) {
+            if (!index.has(to)) {
+                visit(to);
+                low.set(node, Math.min(low.get(node) ?? 0, low.get(to) ?? 0));
+            }
+            else if (onStack.has(to)) low.set(node, Math.min(low.get(node) ?? 0, index.get(to) ?? 0));
+        }
+        if (low.get(node) !== index.get(node)) return;
+        const component: number[] = [];
+        for (;;) {
+            const member = stack.pop();
+            if (member === undefined) break;
+            onStack.delete(member);
+            component.push(member);
+            if (member === node) break;
+        }
+        components.push(component);
+    };
+    for (const node of nodes) if (!index.has(node)) visit(node);
+    components.reverse();
+    return components.map(members => {
+        const inside = new Set(members);
+        for (const member of members) {
+            for (const { to, negative, within } of edges.get(member) ?? []) {
+                if (!inside.has(to)) continue;
+                const cycle = members.map(nameOf).sort().join(", ");
+                if (negative) throw new Error(`Rules derive in a cycle through a negation, which could oscillate: ${cycle}.`);
+                if (within) throw new Error(`Components are within each other in a cycle: ${cycle}.`);
+            }
+        }
+        return {
+            rules: rules.flatMap(rule => {
+                const derives = rule.derives.filter(id => inside.has(id));
+                return derives.length === 0 ? [] : [{ has: rule.has, not: rule.not, derives }];
+            }),
+            within: members.flatMap(dependent => (hosts[dependent] ?? -1) >= 0 ? [{ dependent, host: hosts[dependent] ?? -1 }] : []),
+        };
+    });
+};
+

package/src/interface/registry/threads.ts

@@ -0,0 +1,73 @@
+import { threadOfDeclaration } from './declarations.js';
+import { lookupKeysOf, orderKeysOf } from './indexes.js';
+import { declarationOf, kindOf, labelOf } from './names.js';
+
+type Key = symbol;
+type Lists = {
+    readonly read?: readonly Key[];
+    readonly write?: readonly Key[];
+    readonly added?: readonly Key[];
+    readonly changed?: readonly Key[];
+    readonly is?: readonly Key[];
+};
+
+/**
+ * What places a system or finalizer: the names it reads, writes or filters on by change, but not `has` and `not`, and
+ * the key parts of the indexes it looks up through or orders its rows by.
+ */
+export type Placed = {
+    readonly components?: Lists;
+    readonly lookup?: { readonly [name: string]: { readonly read?: readonly Key[]; readonly index?: unknown } };
+    readonly up?: { readonly read?: readonly Key[] };
+    readonly order?: unknown;
+    readonly resources?: Lists;
+};
+
+/** Throws unless each key is registered as `kind`. */
+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.`);
+        }
+    }
+};
+
+/**
+ * The thread a system or finalizer runs on: the one its object components and resources live on, or null when it uses
+ * none. Throws when they live on different threads, or a name it's placed by isn't registered as its kind.
+ */
+export const threadOf = (declaration: Placed, what: "System" | "Finalizer", name: string): string | null => {
+    /** By thread, the labels of the keys placing it there. */
+    const threads = new Map<string, Set<string>>();
+    const add = (kind: "component" | "resource", keys: readonly Key[] | undefined): void => {
+        requireRegistered(what, name, kind, keys);
+        for (const key of keys ?? []) {
+            const found = declarationOf(key);
+            const thread = found === undefined ? null : threadOfDeclaration(found);
+            if (thread === null) continue;
+            const labels = threads.get(thread) ?? new Set<string>();
+            labels.add(`"${labelOf(key)}"`);
+            threads.set(thread, labels);
+        }
+    };
+    const { components, lookup, up, resources } = declaration;
+    add("component", components?.read);
+    add("component", components?.write);
+    add("component", components?.added);
+    add("component", components?.changed);
+    for (const name in lookup) {
+        add("component", lookup[name].read);
+        add("component", lookupKeysOf(lookup[name]));
+    }
+    add("component", up?.read);
+    add("component", orderKeysOf(declaration));
+    add("resource", resources?.read);
+    add("resource", resources?.write);
+    add("resource", resources?.changed);
+    add("resource", resources?.is);
+    if (threads.size > 1) {
+        const placed = [...threads].map(([thread, labels]) => `${[...labels].join(", ")} on "${thread}"`).join(" and ");
+        throw new Error(`${what} "${name}" uses ${placed}; its object components and resources live on one thread.`);
+    }
+    return threads.keys().next().value ?? null;
+};

package/src/interface/registry/traits.ts

@@ -0,0 +1,12 @@
+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"]);
+
+/** 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";
+
+/** Registers a trait's key; registering it again is accepted. Throws for a key that isn't a plain symbol, or one of another kind. */
+export const addTrait = (key: unknown): void => {
+    if (kindOf(key) !== "trait") claimKey(key, "trait");
+};

package/src/interface/registry/written.ts

@@ -0,0 +1,14 @@
+import { clock } from '../resources/clock.js';
+import { labelOf } from './names.js';
+
+/** Resources only the world writes. */
+const worldWritten: ReadonlySet<symbol> = new Set([clock]);
+
+/** Throws if `writes` lists a resource only the world writes. */
+export const checkWorldWritten = (what: string, writes: readonly (symbol)[] | undefined): void => {
+    const found = writes?.find(key => worldWritten.has(key));
+    if (found !== undefined) throw new Error(`${what} writes "${labelOf(found)}", which only the world writes.`);
+};
+
+/** Whether only the world writes a resource. */
+export const isWorldWritten = (key: symbol): boolean => worldWritten.has(key);

package/src/interface/report/components.ts

@@ -0,0 +1,69 @@
+import { register } from '../component/register.js';
+import type { Failure, Warning } from './failure.js';
+
+/**
+ * What every run and tick reports, all structs, so every thread reads it: `number`, the run's own, every run and tick
+ * taking the next in the order they ran; `elapsed`, milliseconds from its start to its sync point; `systems`, how many
+ * ran; `workers`, how many pool workers took part; `joined`, how many joined threads ran its systems; `main`, whether
+ * any ran on the main thread; `gpu`, whether it submitted GPU work; `dropped`, commands that did nothing, their entity
+ * gone at the sync point.
+ */
+export const run = Symbol("Report/run");
+/**
+ * What went wrong, on a report only when something did: `failures`, systems, finalizers, GPU work, threads and unique
+ * indexes that failed, in the order they ran or were found; `skipped`, the labels of systems that didn't run, those in
+ * tiers after one that failed and those of a joined thread that's gone; `warnings`, what ran but slowed the run.
+ */
+export const errors = Symbol("Report/errors");
+
+declare module '@adobe/ecs' {
+    export interface Components {
+        [run]: {
+            type: {
+                readonly number: number;
+                readonly elapsed: number;
+                readonly systems: number;
+                readonly workers: number;
+                readonly joined: number;
+                readonly main: boolean;
+                readonly gpu: boolean;
+                readonly dropped: number;
+            };
+        };
+        [errors]: { type: { readonly failures: readonly Failure[]; readonly skipped: readonly string[]; readonly warnings: readonly Warning[] } };
+    }
+}
+
+const text = { type: "string" } as const;
+const count = { type: "integer", minimum: 0 } as const;
+
+register(run, {
+    type: {
+        type: "object",
+        properties: {
+            number: count, elapsed: { type: "number", minimum: 0 }, systems: count, workers: count, joined: count,
+            main: { type: "boolean" }, gpu: { type: "boolean" }, dropped: count,
+        },
+    },
+});
+register(errors, {
+    type: {
+        type: "object",
+        properties: {
+            failures: {
+                type: "array",
+                items: {
+                    type: "object",
+                    properties: {
+                        kind: { anyOf: [{ const: "system" }, { const: "finalizer" }, { const: "gpu" }, { const: "thread" }, { const: "index" }] },
+                        name: text,
+                        message: text,
+                        stack: { anyOf: [text, { type: "null" }] },
+                    },
+                },
+            },
+            skipped: { type: "array", items: text },
+            warnings: { type: "array", items: { type: "object", properties: { kind: { const: "blocking" }, name: text, message: text } } },
+        },
+    },
+});

package/src/interface/report/failure.ts

@@ -0,0 +1,26 @@
+/** What failed in a run: a system, finalizer, GPU work, thread or unique index. */
+export type Failure = {
+    /**
+     * What failed: a system or finalizer that threw, GPU work, a system whose thread is gone, which didn't run, or a
+     * unique index found holding two entities for one key, of which lookups give the one with the lower entity index;
+     * later tiers still run after a `"thread"` or `"index"` failure.
+     */
+    readonly kind: "system" | "finalizer" | "gpu" | "thread" | "index";
+    /**
+     * The label of the system or finalizer that failed; for GPU work, of the system whose run submitted it; for an
+     * index, the index's, with the key and both entities in `message`. Labels are for display: a system's,
+     * finalizer's or index's is its name while no other registered system, rule, finalizer or index has it, else its
+     * name with its id, or numbered without one.
+     */
+    readonly name: string;
+    /** An Error's message, or String() of anything else thrown. */
+    readonly message: string;
+    /** The thrown Error's `stack`, as the JavaScript engine formats it, for logs and display; null when it had none. */
+    readonly stack: string | null;
+};
+
+/**
+ * What ran but slowed a run. `"blocking"`: a system that runs on a thread a joined thread fills and isn't terminal, so
+ * its tier waited for that thread, by the system's label.
+ */
+export type Warning = { readonly kind: "blocking"; readonly name: string; readonly message: string };

package/src/interface/report/index.ts

@@ -0,0 +1,8 @@
+import { create as createArchetype } from '../archetype/create.js';
+import { run } from './components.js';
+
+export { errors, run } from './components.js';
+export type { Failure, Warning } from './failure.js';
+
+/** A report's archetype: the world gives every run and tick one, which gains `errors` when something went wrong. */
+export const Archetype = createArchetype([run]);

package/src/interface/report/report.ts

@@ -0,0 +1,11 @@
+import type { Component } from '../component/component.js';
+import type { errors, run } from './components.js';
+
+/**
+ * A report's values, as rows and lookups give them. After the sync point of each run and tick, before its observer
+ * systems, the world writes its report, an entity it keeps for recent runs: `errors` is there only when something went
+ * wrong. Once a run resolves, its report is there. Queries that require no component don't see reports.
+ */
+export type Report = { readonly [run]: Component.Value<typeof run>; readonly [errors]?: Component.Value<typeof errors> };
+
+export * as Report from './index.js';

package/src/interface/report/report.type-test.ts

@@ -0,0 +1,63 @@
+import type { Component } from '../component/component.js';
+import * as resources from '../resources/index.js';
+import { System } from '../system/system.js';
+import { main, watchTime } from '../system/system.type-test.js';
+import type { World } from '../world/world.js';
+import { Report } from './report.js';
+
+type Equal<X, Y> = (<T>() => T extends X ? 1 : 2) extends (<T>() => T extends Y ? 1 : 2) ? true : false;
+const check = <_T extends true>() => { };
+
+declare const world: World;
+
+// Each key is a component, declared under its namespaced computed key.
+type Run = {
+    readonly number: number;
+    readonly elapsed: number;
+    readonly systems: number;
+    readonly workers: number;
+    readonly joined: number;
+    readonly main: boolean;
+    readonly gpu: boolean;
+    readonly dropped: number;
+};
+type Errors = { readonly failures: readonly Report.Failure[]; readonly skipped: readonly string[]; readonly warnings: readonly Report.Warning[] };
+check<Equal<Component.Value<typeof Report.run>, Run>>();
+check<Equal<Component.Value<typeof Report.errors>, Errors>>();
+check<Equal<typeof Report.Archetype, readonly [typeof Report.run]>>();
+
+// A failure and a warning, as data.
+declare const failure: Report.Failure;
+check<Equal<typeof failure.kind, "system" | "finalizer" | "gpu" | "thread" | "index">>();
+check<Equal<typeof failure.stack, string | null>>();
+check<Equal<Report.Warning, { readonly kind: "blocking"; readonly name: string; readonly message: string }>>();
+
+// A report's values: errors only when something went wrong.
+check<Equal<Report, { readonly [Report.run]: Run; readonly [Report.errors]?: Errors }>>();
+
+// An observer system follows reports by their components.
+const logged: Report.Failure[] = [];
+export const logger = System.create({ observer: true, components: { read: [Report.run, Report.errors], changed: [Report.errors] } }, row => {
+    const number: number = row[Report.run].number;
+    for (const each of row[Report.errors].failures) logged.push(each);
+    // @ts-expect-error a report's lists are read-only
+    row[Report.errors].failures.push(logged[0]);
+    void number;
+});
+export const timings = System.create({ observer: true, components: { read: [Report.run], changed: [Report.run] } }, row => {
+    const { elapsed, systems, workers, joined, main: onMain, gpu, dropped } = row[Report.run];
+    void [elapsed, systems, workers, joined, onMain, gpu, dropped];
+});
+
+// A run resolves to its number; a rejected run rejects.
+const ran: Promise<number> = world.run(main);
+const observed: Promise<number> = world.run(watchTime);
+void [ran, observed];
+// @ts-expect-error no index by run: indexes key on whole components
+void Report.byRun;
+// @ts-expect-error no failures component: they're in errors
+void Report.failures;
+// @ts-expect-error no World.Report: a report is entities
+export type Reported = World.Report;
+// @ts-expect-error no report resource: reports are entities
+void resources.report;

package/src/interface/resource/condition.ts

@@ -0,0 +1,8 @@
+import type { Key } from "./key.js";
+import type { Value } 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];
+
+/** A condition's value while `is` holds: neither `null` nor `false`. */
+export type Holding<K extends Key> = Exclude<Value<K>, null | false>;

package/src/interface/resource/declaration.ts

@@ -0,0 +1,29 @@
+import type { Describing, Starting } from "../component/declaration.js";
+import type { IsData } from "../schema/is-data.js";
+import type { Schema } from "../schema/schema.js";
+import type { Key as TraitKey } from "../trait/key.js";
+import type { Required } from "../trait/required.js";
+import type { Traits } from "../trait/types.js";
+import type { SymbolKeys } from "../trait/symbol-keys.js";
+import type { Key } from "./key.js";
+import type { Resources } from "./types.js";
+
+/**
+ * A resource always has a value: its schema's `default` or the declaration's, of the declared type `T`, either left
+ * out only when `T` allows `null`. A type that isn't data has no schema, so only the declaration's.
+ */
+type TypePart<S, T> =
+    IsData<T> extends true
+        ? [S] extends [never] ? { readonly type: Schema } : Describing<S, T> & (S extends { readonly default: unknown } ? { readonly default?: never } : Starting<T>)
+        : { readonly type?: never } & Starting<T>;
+
+/** As for components, with the value a resource starts at. */
+export type Declaration<K extends Key, S> =
+    { readonly type?: S }
+    & TypePart<S, Resources[K]["type"]>
+    & { readonly [T in Exclude<keyof Resources[K], "type">]:
+        T extends TraitKey ? (Resources[K][T] extends Traits<K>[T] ? Resources[K][T] : never) :
+        never }
+    & { readonly [T in Exclude<TraitKey, keyof Resources[K]>]?: never }
+    & Required<Resources[K], Resources[K]["type"]>
+    & SymbolKeys;

package/src/interface/resource/declaration.type-test.ts

@@ -0,0 +1,89 @@
+import { Resource } from './resource.js';
+
+const gravity = Symbol("declarationTypeTest/gravity");
+const total = Symbol("declarationTypeTest/total");
+const names = Symbol("declarationTypeTest/names");
+const tags = Symbol("declarationTypeTest/tags");
+const selected = Symbol("declarationTypeTest/selected");
+const device = Symbol("declarationTypeTest/device");
+const page = Symbol("declarationTypeTest/page");
+const handles = Symbol("declarationTypeTest/handles");
+const candidates = Symbol("declarationTypeTest/candidates");
+const misnamed = Symbol("declarationTypeTest/misnamed");
+
+type Box = { readonly x: number; readonly y: number };
+type Candidate = Box & { readonly id: number };
+
+declare module '@adobe/ecs' {
+    export interface Resources {
+        [gravity]: { type: number };
+        [total]: { type: number; reduce: "+" };
+        [names]: { type: ReadonlyMap<string, number> };
+        [tags]: { type: ReadonlySet<string> };
+        [selected]: { type: string | null };
+        [device]: { type: GPUDevice | null };
+        [page]: { type: Document; thread: "main" };
+        [handles]: { type: Map<string, number> };
+        [candidates]: { type: readonly Candidate[] };
+        [misnamed]: { type: readonly Candidate[] };
+    }
+}
+
+const namesSchema = { type: "map", keys: { type: "string" }, values: { type: "number" } } as const;
+
+// A resource starts at its schema's default or its declaration's.
+Resource.register(gravity, { type: { type: "number", default: -9.8 } });
+Resource.register(total, { type: { type: "number", default: 0 }, reduce: "+" });
+Resource.register(names, { type: namesSchema, default: new Map() });
+Resource.register(tags, { type: { type: "set", items: { type: "string" } }, default: new Set(["a"]) });
+// A type that allows null starts at null without one.
+Resource.register(selected, { type: { anyOf: [{ type: "string" }, { type: "null" }] } });
+Resource.register(device, {});
+Resource.register(page, { default: document, thread: "main" });
+Resource.register(handles, { default: new Map() });
+
+// A schema describes exactly the declared type.
+// @ts-expect-error a string isn't a number
+Resource.register(gravity, { type: { type: "string", default: "" } });
+// @ts-expect-error a map's values are numbers
+Resource.register(names, { type: { type: "map", keys: { type: "string" }, values: { type: "string" } }, default: new Map() });
+
+// An intersection describes the object it equals.
+const number = { type: "number" } as const;
+Resource.register(candidates, { type: { type: "array", items: { type: "object", properties: { id: number, x: number, y: number }, required: ["id", "x", "y"] }, default: [] } });
+// @ts-expect-error a member's name differs
+Resource.register(misnamed, { type: { type: "array", items: { type: "object", properties: { key: number, x: number, y: number }, required: ["key", "x", "y"] }, default: [] } });
+
+// Every declared trait is registered, with its declared value, and nothing undeclared is.
+// @ts-expect-error a declared trait is missing
+Resource.register(total, { type: { type: "number", default: 0 } });
+// @ts-expect-error an undeclared trait is given
+Resource.register(gravity, { type: { type: "number", default: 0 }, reduce: "+" });
+// @ts-expect-error a trait's value differs from the declared one
+Resource.register(total, { type: { type: "number", default: 0 }, reduce: "max" });
+// A declaration held in a constant gets no excess property check, so the types name each undeclared trait.
+const reduced = { type: { type: "number", default: 0 }, reduce: "+" } as const;
+// @ts-expect-error an undeclared trait is given
+Resource.register(gravity, reduced);
+
+// A type that's data is registered with its schema; one that isn't data has none.
+// @ts-expect-error a map of strings to numbers is data, so it has a schema
+Resource.register(names, { default: new Map() });
+// @ts-expect-error a string is data, so it has a schema, though it may start at null
+Resource.register(selected, {});
+// @ts-expect-error a value that isn't data has no schema
+Resource.register(handles, { type: { type: "object", properties: {} }, default: new Map() });
+
+// A default is a value of the declared type, given once.
+// @ts-expect-error the schema's default isn't a number
+Resource.register(gravity, { type: { type: "number", default: "down" } });
+// @ts-expect-error the declaration's default isn't a map of strings to numbers
+Resource.register(names, { type: namesSchema, default: new Set() });
+// @ts-expect-error a default isn't a Map
+Resource.register(handles, { default: "map" });
+// @ts-expect-error a type without null starts at a default
+Resource.register(gravity, { type: { type: "number" } });
+// @ts-expect-error a value that isn't data, without null, starts at a default
+Resource.register(handles, {});
+// @ts-expect-error a schema's default and the declaration's can't both be given
+Resource.register(gravity, { type: { type: "number", default: 0 }, default: 1 });

package/src/interface/resource/index.ts

@@ -0,0 +1,3 @@
+export * from './register.js';
+export type { Key } from './key.js';
+export type { Value } from './value.js';

package/src/interface/resource/key.ts

@@ -0,0 +1,3 @@
+import type { Resources } from './types.js';
+
+export type Key = keyof Resources;

package/src/interface/resource/reduction.ts

@@ -0,0 +1,11 @@
+import type { Key } from "./key.js";
+import type { Resources } from './types.js';
+
+/** How a reduction combines values, leaf by leaf: a sum, a product, the least or greatest, or a bitwise fold. */
+export type Reduction = "+" | "*" | "min" | "max" | "&" | "|" | "^";
+
+/** The resources declared with a `reduce` trait, which systems contribute to and nothing writes. */
+export type Reduced = { [K in Key]: Resources[K] extends { readonly reduce: Reduction } ? K : never }[Key];
+
+/** The operator resource `K` is reduced with. */
+export type OperatorOf<K extends Reduced> = Resources[K] extends { readonly reduce: infer R } ? R : never;

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

@@ -0,0 +1,107 @@
+import { describe, expect, it } from "vitest";
+import { Component } from "../component/component.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");
+const flags = Symbol("typesResourceTest/flags");
+const names = Symbol("typesResourceTest/names");
+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" };
+        [port]: { type: MessagePort | null; transfer: true };
+        [total]: { type: number; reduce: "+" };
+        [flags]: { type: boolean; 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 as an untyped caller would, bypassing the types' checks. */
+const register = (key: unknown, declaration: object): void => {
+    Reflect.apply(untyped, undefined, [key, declaration]);
+};
+
+describe("Resource.register", () => {
+    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(kindOf(symbol)).toBe("resource");
+        const anonymous = Symbol();
+        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.");
+    });
+    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");
+    });
+    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");
+        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 } });
+        // 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;
+        });
+        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(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");
+    });
+    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");
+    });
+});