@adobe/ecs 0.0.0-stage → 0.2.0

package/src/interface/registry/strata.ts

@@ -0,0 +1,94 @@
+// © 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
+ * 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,74 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { threadOfDeclaration } from './declarations.js';
+import { lookupKeysOf, orderKeysOf } from './indexes.js';
+import { declarationOf, kindOf, labelOf, whyUnregistered } 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}: ${whyUnregistered(key)}.`);
+        }
+    }
+};
+
+/**
+ * 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,13 @@
+// © 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", "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";
+
+/** 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,15 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+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/resource/condition.ts

@@ -0,0 +1,9 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+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/index.ts

@@ -0,0 +1,3 @@
+// © 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

@@ -0,0 +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

@@ -0,0 +1,12 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+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,93 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+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";
+
+const time = Symbol("typesResourceTest/time");
+const symbol = Symbol("typesResourceTest/symbol");
+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; default: 0 };
+        [symbol]: { type: boolean; default: false };
+        [cache]: { type: ReadonlyMap<string, number>; thread: "main" };
+        [port]: { type: MessagePort | null; transfer: true };
+        [total]: { type: number; default: 0; reduce: "+" };
+        [flags]: { type: boolean; default: false; reduce: "|" };
+        [names]: { type: ReadonlyMap<string, number> };
+        [tags]: { type: ReadonlySet<string> };
+    }
+}
+
+/** Registers a declaration as the build does, which a test may write wrong. */
+const register = (key: unknown, declaration: object): void => registerResource(key, declaration);
+
+const namesSchema = { type: "map", keys: { type: "string" }, values: { type: "number" } } as const;
+
+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(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(() => 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, 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 });
+        // 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 => 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({ 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");
+    });
+    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");
+    });
+});

package/src/interface/resource/resource.ts

@@ -0,0 +1,5 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+export type Resource = never;
+
+export * as Resource from './index.js';

package/src/interface/resource/types.ts

@@ -0,0 +1,7 @@
+// © 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

@@ -0,0 +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 };
+
+/** The value type of resource `K`. */
+export type Value<K extends Key> = ValueTypes[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>>;
+
+/** Every resource's thread, computed once so `ThreadOf` is a lookup. */
+type Threads = { readonly [K in Key]: ThreadOf<Resources[K], Value<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];

package/src/interface/resource/written.ts

@@ -0,0 +1,5 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { clock } from '../resources/clock.js';
+
+/** Resources only the world writes: systems and finalizers read them, and worlds don't start them at other values. */
+export type WorldWritten = typeof clock;

package/src/interface/resources/always.ts

@@ -0,0 +1,13 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { registerResource } from '../registry/declarations.js';
+
+/** Whether every beat of the cadence runs a tick, not only beats where `wake` is due or a run arrived. False by default. */
+export const always = Symbol("always");
+
+declare module '@adobe/ecs' {
+    export interface Resources {
+        [always]: { type: boolean };
+    }
+}
+
+registerResource(always, { type: { type: "boolean" }, default: false });

package/src/interface/resources/cadence.ts

@@ -0,0 +1,28 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { registerResource } from '../registry/declarations.js';
+
+/** The cadence's value, for the implementation: `Resource.Value<typeof cadence>`. */
+export type Cadence = { readonly kind: "frame" } | { readonly kind: "fixed"; readonly step: number; readonly maxSteps?: number };
+
+/**
+ * When the world ticks: once per animation frame, `{ kind: "frame" }`, the default, or every `step` milliseconds,
+ * `{ kind: "fixed", step }`. Under `fixed`, a beat that's behind runs at most `maxSteps` ticks, 4 by default, and drops
+ * the rest of the debt; each tick's `clock.delta` is `step`.
+ */
+export const cadence = Symbol("cadence");
+
+declare module '@adobe/ecs' {
+    export interface Resources {
+        [cadence]: { type: Cadence };
+    }
+}
+
+registerResource(cadence, {
+    type: {
+        anyOf: [
+            { type: "object", properties: { kind: { const: "frame" } } },
+            { type: "object", properties: { kind: { const: "fixed" }, step: { type: "number", minimum: 0 }, maxSteps: { type: "integer", minimum: 1 } }, required: ["kind", "step"] },
+        ],
+    },
+    default: { kind: "frame" },
+});

package/src/interface/resources/clock.ts

@@ -0,0 +1,19 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { registerResource } from '../registry/declarations.js';
+
+/**
+ * The current tick, written only by the world before each tick: `now`, the beat's time in milliseconds, `delta`, the
+ * milliseconds since the previous tick (`step` under a fixed cadence), and `tick`, how many ticks ran before.
+ */
+export const clock = Symbol("clock");
+
+declare module '@adobe/ecs' {
+    export interface Resources {
+        [clock]: { type: { readonly now: number; readonly delta: number; readonly tick: number } };
+    }
+}
+
+registerResource(clock, {
+    type: { type: "object", properties: { now: { type: "number" }, delta: { type: "number" }, tick: { type: "number" } } },
+    default: { now: 0, delta: 0, tick: 0 },
+});

package/src/interface/resources/gpu-device.ts

@@ -0,0 +1,17 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { registerResource } from '../registry/declarations.js';
+
+/**
+ * The device the world's GPU storage lives on, for both `kernel: "gpu"` kernels and render systems, or null for a world
+ * without one. It lives on `"world"`, with the world. The world moves its GPU storage to whatever this is set to, and
+ * never destroys a device.
+ */
+export const gpuDevice = Symbol("gpuDevice");
+
+declare module '@adobe/ecs' {
+    export interface Resources {
+        [gpuDevice]: { type: GPUDevice | null };
+    }
+}
+
+registerResource(gpuDevice, {});

package/src/interface/resources/index.ts

@@ -0,0 +1,7 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+export * from './always.js';
+export { cadence } from './cadence.js';
+export * from './clock.js';
+export * from './gpu-device.js';
+export * from './wake.js';
+export * from './workers.js';

package/src/interface/resources/wake.ts

@@ -0,0 +1,16 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { registerResource } from '../registry/declarations.js';
+
+/**
+ * The earliest `clock.now`, in milliseconds, at which a system asked for the next tick, by contributing to it; Infinity
+ * for none. The first beat at or after it runs a tick.
+ */
+export const wake = Symbol("wake");
+
+declare module '@adobe/ecs' {
+    export interface Resources {
+        [wake]: { type: number; reduce: "min" };
+    }
+}
+
+registerResource(wake, { type: { type: "number" }, reduce: "min", default: Infinity });

package/src/interface/resources/workers.ts

@@ -0,0 +1,13 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { registerResource } from '../registry/declarations.js';
+
+/** The kernel pool's size, 0 for none, or `null`, the default, for the platform's choice. The pool follows it at sync points. */
+export const workers = Symbol("workers");
+
+declare module '@adobe/ecs' {
+    export interface Resources {
+        [workers]: { type: number | null };
+    }
+}
+
+registerResource(workers, { type: { anyOf: [{ type: "integer", minimum: 0 }, { type: "null" }] }, default: null });

package/src/interface/rule/create.ts

@@ -0,0 +1,27 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { declarationOf, kindOf, labelOf, whyUnregistered } from '../registry/names.js';
+import { takeIdOfDeclaration } from '../registry/ids.js';
+import { nameOf } from '../registry/items.js';
+import { addRule } from '../registry/program.js';
+import type { Rule as Created } from './created.js';
+import type { Declaration } from './declaration.js';
+
+/**
+ * Declares a rule, which applies in every world, and returns it: identified by that value, labeled by its binding. Throws
+ * if it matches on a key that isn't a registered component, derives a component that isn't derived, or derives in a
+ * cycle through a negation.
+ */
+export const create = <const D extends Declaration>(declaration: D & { readonly components: { readonly has?: never } }): { readonly name: string } => {
+    const id = takeIdOfDeclaration(declaration);
+    const name = nameOf(declaration, id, "rule");
+    const { derive } = declaration;
+    const components = { has: declaration.components.with, not: declaration.components.not };
+    for (const key of [...components.has ?? [], ...components.not ?? [], ...derive]) {
+        if (kindOf(key) !== "component") throw new Error(`Rule "${name}" uses "${labelOf(key)}", which isn't a registered component: ${whyUnregistered(key)}.`);
+    }
+    for (const key of derive) {
+        if (declarationOf(key)?.derived !== true) throw new Error(`Rule "${name}" derives "${labelOf(key)}", which isn't declared derived.`);
+    }
+    const rule: Created = { kind: "rule", name, declaration: { ...declaration, components } };
+    return addRule(rule, id);
+};

package/src/interface/rule/created.ts

@@ -0,0 +1,5 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Stored } from './declaration.js';
+
+/** A rule: entities matching its components have the components it derives. */
+export type Rule = { readonly kind: "rule"; readonly name: string; readonly declaration: Stored };

package/src/interface/rule/declaration.ts

@@ -0,0 +1,15 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Component } from '../component/component.js';
+import type { Derived } from '../component/value.js';
+
+export type Declaration = {
+    /** Which entities the rule matches, by the components they have and don't have. */
+    readonly components: { readonly with?: readonly Component.Key[]; readonly not?: readonly Component.Key[] };
+    /** Components present on matching entities, while any rule deriving them matches. */
+    readonly derive: readonly Derived[];
+};
+
+/** A rule's declaration as the world takes it: what it requires in `has`. */
+export type Stored = Omit<Declaration, "components"> & {
+    readonly components: { readonly has?: readonly symbol[]; readonly not?: readonly symbol[] };
+};

package/src/interface/rule/index.ts

@@ -0,0 +1,2 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+export * from './create.js';

package/src/interface/rule/rule.ts

@@ -0,0 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+export type Rule = never;
+
+export * as Rule from './index.js';