@adobe/ecs 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,153 @@
+import type { IsData } from "./is-data.js";
+import type { IsStruct } from "./is-struct.js";
+import type { Schema } from "./schema.js";
+
+// Local copies of the standard compile-time assertion helpers.
+type Equal<X, Y> =
+    (<T>() => T extends X ? 1 : 2) extends
+    (<T>() => T extends Y ? 1 : 2) ? true : false;
+const check = <_T extends true>() => { };
+
+// primitives
+check<Equal<Schema.ToType<{ type: 'string' }>, string>>();
+check<Equal<Schema.ToType<{ type: 'number' }>, number>>();
+check<Equal<Schema.ToType<{ type: 'integer' }>, number>>();
+check<Equal<Schema.ToType<{ type: 'boolean' }>, boolean>>();
+check<Equal<Schema.ToType<{ type: 'null' }>, null>>();
+
+// const narrows
+check<Equal<Schema.ToType<{ const: 'a' }>, 'a'>>();
+check<Equal<Schema.ToType<{ const: true }>, true>>();
+
+// standalone const accepts any JSON value
+check<Equal<Schema.ToType<{ const: 'x' }>, 'x'>>();
+check<Equal<Schema.ToType<{ const: readonly [1, 2] }>, readonly [1, 2]>>();
+const okConst: Schema = { const: { a: [1, 'b', null, { c: true }] } };
+// @ts-expect-error undefined is not a JSON value
+const badConstUndefined: Schema = { const: undefined };
+// @ts-expect-error functions are not JSON values
+const badConstFn: Schema = { const: () => 1 };
+// @ts-expect-error nested non-JSON values are rejected
+const badConstNested: Schema = { type: 'object', properties: {}, const: { a: undefined } };
+// @ts-expect-error `type` + `const` is redundant, not a valid Schema
+const badTypeAndConst: Schema = { type: 'boolean', const: true };
+// @ts-expect-error same when written `as const satisfies Schema`
+const badSatisfies = { type: 'boolean', const: true } as const satisfies Schema;
+void [badTypeAndConst, badSatisfies];
+void [okConst, badConstUndefined, badConstFn, badConstNested];
+
+// arrays
+check<Equal<Schema.ToType<{ type: 'array'; items: { type: 'number' } }>, readonly number[]>>();
+
+// objects: all required when `required` is absent
+check<Equal<
+    Schema.ToType<{ type: 'object'; properties: { a: { type: 'number' }; b: { type: 'string' } } }>,
+    { readonly a: number; readonly b: string }
+>>();
+// objects: only listed keys required when `required` is present
+check<Equal<
+    Schema.ToType<{ type: 'object'; properties: { a: { type: 'number' }; b: { type: 'string' } }; required: ['a'] }>,
+    { readonly a: number; readonly b?: string }
+>>();
+
+// combinators
+check<Equal<Schema.ToType<{ anyOf: [{ type: 'string' }, { type: 'null' }] }>, string | null>>();
+check<Equal<
+    Schema.ToType<{ allOf: [
+        { type: 'object'; properties: { a: { type: 'number' } } },
+        { type: 'object'; properties: { b: { type: 'string' } } },
+    ] }>,
+    { readonly a: number } & { readonly b: string }
+>>();
+
+// ForType: accepts matching schemas, rejects mismatches
+const okNumber: Schema.ForType<number> = { type: 'integer' };
+const okNull: Schema.ForType<null> = { type: 'null' };
+const okUnion: Schema.ForType<string | null> = { anyOf: [{ type: 'string' }, { type: 'null' }] };
+const okArray: Schema.ForType<readonly string[]> = { type: 'array', items: { type: 'string' } };
+// @ts-expect-error string schema does not describe a number
+const badNumber: Schema.ForType<number> = { type: 'string' };
+// @ts-expect-error union members must describe a branch of the union
+const badUnion: Schema.ForType<string | null> = { anyOf: [{ type: 'number' }] };
+// @ts-expect-error array items must match
+const badArray: Schema.ForType<readonly string[]> = { type: 'array', items: { type: 'number' } };
+void [okNumber, okNull, okUnion, okArray, badNumber, badUnion, badArray];
+
+// every schema form is writable-free, so `as const` literals satisfy Schema
+const asConstObject = { type: 'object', properties: { a: { type: 'number' } }, required: ['a'] } as const satisfies Schema;
+const asConstAnyOf = { anyOf: [{ type: 'string' }, { type: 'null' }] } as const satisfies Schema;
+const asConstAllOf = { allOf: [{ type: 'object', properties: {} }, { const: 1 }] } as const satisfies Schema;
+const asConstArray = { type: 'array', items: { const: [1, { a: null }] } } as const satisfies Schema;
+check<Equal<Schema.ToType<typeof asConstObject>['a'], number>>();
+check<Equal<Schema.ToType<typeof asConstAnyOf>, string | null>>();
+void [asConstObject, asConstAnyOf, asConstAllOf, asConstArray];
+
+// fields are readonly
+declare const stringSchema: Extract<Schema, { type: 'string' }>;
+// @ts-expect-error schemas are immutable
+stringSchema.minLength = 1;
+declare const objectSchema: Extract<Schema, { type: 'object' }>;
+// @ts-expect-error properties are immutable
+objectSchema.properties = {};
+// @ts-expect-error required is a readonly array
+objectSchema.required?.push('x');
+
+// ForType<true> must not admit the redundant type + const form
+// @ts-expect-error redundant
+const badForTypeRedundant: Schema.ForType<true> = { type: 'boolean', const: true };
+void badForTypeRedundant;
+
+// ForType boolean literals: only the matching bare const schema
+const okTrue: Schema.ForType<true> = { const: true };
+const okFalse: Schema.ForType<false> = { const: false };
+const okBoolean: Schema.ForType<boolean> = { type: 'boolean' };
+// @ts-expect-error const false does not describe true
+const badTrue: Schema.ForType<true> = { const: false };
+// @ts-expect-error const true does not describe false
+const badFalse: Schema.ForType<false> = { const: true };
+// @ts-expect-error redundant type + const for false
+const badFalseRedundant: Schema.ForType<false> = { type: 'boolean', const: false };
+// @ts-expect-error a const schema is too narrow for plain boolean
+const badBoolean: Schema.ForType<boolean> = { const: true };
+// @ts-expect-error type without const is too wide for the literal
+const badTrueWide: Schema.ForType<true> = { type: 'boolean' };
+void [okTrue, okFalse, okBoolean, badTrue, badFalse, badFalseRedundant, badBoolean, badTrueWide];
+
+// fixed-length arrays are tuples; any other length is an array
+check<Equal<Schema.ToType<{ type: 'array'; items: { type: 'number' }; minItems: 3; maxItems: 3 }>, readonly [number, number, number]>>();
+check<Equal<Schema.ToType<{ type: 'array'; items: { type: 'number' }; minItems: 2; maxItems: 3 }>, readonly number[]>>();
+check<Equal<Schema.ToType<{ type: 'array'; items: { type: 'number' }; minItems: number; maxItems: number }>, readonly number[]>>();
+
+// sets and maps, forms JSON lacks, are read-only
+check<Equal<Schema.ToType<{ type: 'set'; items: { type: 'string' } }>, ReadonlySet<string>>>();
+check<Equal<Schema.ToType<{ type: 'map'; keys: { type: 'string' }; values: { type: 'array'; items: { type: 'number' } } }>, ReadonlyMap<string, readonly number[]>>>();
+check<Equal<Schema.ToType<{ type: 'object'; properties: { tags: { type: 'set'; items: { const: 'a' } } } }>, { readonly tags: ReadonlySet<'a'> }>>();
+const okSet: Schema.ForType<ReadonlySet<number>> = { type: 'set', items: { type: 'integer' } };
+const okMap: Schema.ForType<ReadonlyMap<string, boolean>> = { type: 'map', keys: { type: 'string' }, values: { type: 'boolean' } };
+// @ts-expect-error a set's items must match
+const badSet: Schema.ForType<ReadonlySet<number>> = { type: 'set', items: { type: 'string' } };
+// @ts-expect-error a map's values must match
+const badMap: Schema.ForType<ReadonlyMap<string, boolean>> = { type: 'map', keys: { type: 'string' }, values: { type: 'number' } };
+// @ts-expect-error a set has items, not keys and values
+const badSetForm: Schema = { type: 'set', keys: { type: 'string' }, values: { type: 'string' } };
+// @ts-expect-error a map has keys and values
+const badMapForm: Schema = { type: 'map', items: { type: 'string' } };
+void [okSet, okMap, badSet, badMap, badSetForm, badMapForm];
+
+// A ReadonlySet or ReadonlyMap of data is data; a Set or Map, which changes in place, isn't, nor one holding functions.
+check<Equal<IsData<ReadonlySet<string>>, true>>();
+check<Equal<IsData<ReadonlyMap<string, { readonly x: number }>>, true>>();
+check<Equal<IsData<ReadonlySet<() => void>>, false>>();
+check<Equal<IsData<Set<string>>, false>>();
+check<Equal<IsData<Map<string, number>>, false>>();
+// An object is data only when every member is: a record of handles isn't, however deep they are.
+check<Equal<IsData<{ readonly context: GPUCanvasContext; readonly canvas: HTMLCanvasElement }>, false>>();
+check<Equal<IsData<{ readonly pipelines: { readonly fill: GPURenderPipeline } }>, false>>();
+check<Equal<IsData<{ readonly items: readonly { readonly blob: Blob }[] }>, false>>();
+check<Equal<IsData<{ readonly at: readonly [number, number]; readonly label?: string; readonly nested: { readonly x: number } }>, true>>();
+// A recursive data type is still data.
+type Tree = { readonly value: number; readonly children: readonly Tree[] };
+check<Equal<IsData<Tree>, true>>();
+// Neither is a struct: neither lives in shared memory.
+check<Equal<IsStruct<ReadonlySet<number>>, false>>();
+check<Equal<IsStruct<ReadonlyMap<number, number>>, false>>();

package/src/interface/schema/schemas.type-test.ts

@@ -0,0 +1,12 @@
+import type { Schema } from "./schema.js";
+
+const ok: Schema.ForType<true> = { const: true };
+const okObj: Schema.ForType<{ readonly x: number; readonly tags: readonly string[] }> = {
+    type: 'object',
+    properties: { x: { type: 'number' }, tags: { type: 'array', items: { type: 'string' } } },
+};
+// @ts-expect-error string schema does not describe a number
+const bad: Schema.ForType<number> = { type: 'string' };
+// @ts-expect-error const must match the type
+const badConst: Schema.ForType<true> = { const: false };
+void [ok, okObj, bad, badConst];

package/src/interface/system/access.ts

@@ -0,0 +1,67 @@
+import type { Component } from '../component/component.js';
+import type { Resource } from '../resource/resource.js';
+import type { Writable } from '../component/value.js';
+import type { Condition } from '../resource/condition.js';
+import type { Reduced } from '../resource/reduction.js';
+import type { WorldWritten } from '../resource/written.js';
+import type { Index } from '../indexes/index-type.js';
+
+/**
+ * Matches every component in `read`, `write`, `has`, `added` and `changed`, and excludes `not`. A component in `write`
+ * is also readable, so it's never listed in `read` as well.
+ */
+export type ComponentAccess = {
+    readonly read?: readonly Component.Key[];
+    /** A component holding a `reference` changes only through commands, so it can't be written here. */
+    readonly write?: readonly Writable[];
+    readonly has?: readonly Component.Key[];
+    readonly not?: readonly Component.Key[];
+    /** Passes rows where any of these were added since the system last ran. */
+    readonly added?: readonly Component.Key[];
+    /** Passes rows where any of these may have changed since the system last ran. */
+    readonly changed?: readonly Component.Key[];
+};
+
+/**
+ * Read-only access to other entities: by entity, matching `read`, `has` and `not`, or through an index by key. A lookup
+ * by entity's `changed` names components it reads or has, whose changes its row's `changed` reports. An index lookup's
+ * `read` names components every entity the index holds has, its key parts or its `has`, and its `changed` the ones
+ * whose changes its lists' `changed` reports. Both report as a system's `changed` filter does; its system can't write a
+ * key part or what it reads.
+ */
+export type Lookup =
+    | Pick<ComponentAccess, "read" | "has" | "not"> & { readonly changed?: readonly Component.Key[] }
+    | { readonly index: Index; readonly read?: readonly Component.Key[]; readonly changed?: readonly Component.Key[] };
+
+/**
+ * A system's lookup. An index lookup's `changed: true` makes the index a change filter, as a resource in `changed` is:
+ * every row passes when an entity entered or left the index, or moved to another key or position in it, since the
+ * system last ran. A system whose only change filters these are runs only then, skipped before its body otherwise, as
+ * when a condition fails, keeping its `lastRun`. Its lists' `changed` then reports those changes alone. Only on the
+ * world's thread.
+ */
+export type SystemLookup =
+    | Lookup
+    | { readonly index: Index; readonly read?: readonly Component.Key[]; readonly changed: true };
+
+/**
+ * The parent each row's values flow down from: the entity its `through` reference names, read before the row. Rows
+ * run parent first, so a parent's value is the one written earlier in the same run, and `read` may name components the
+ * system writes.
+ */
+export type Up = { readonly through: Component.With<"reference">; readonly read?: readonly Component.Key[] };
+
+/**
+ * A resource in `write` is also readable, so it's never listed in `read` as well. Reduced resources are never written,
+ * nor are those only the world writes.
+ */
+export type ResourceAccess = {
+    readonly read?: readonly Resource.Key[];
+    readonly write?: readonly Exclude<Resource.Key, Reduced | WorldWritten>[];
+    /** Passes every row when any of these changed since the system last ran. */
+    readonly changed?: readonly Resource.Key[];
+    /** Runs only while each of these is neither `null` nor `false`, and reads it as such. Otherwise it's skipped, successfully. */
+    readonly is?: readonly Condition[];
+    /** Runs only while each of these is `null` or `false`. Otherwise it's skipped, successfully. */
+    readonly not?: readonly Condition[];
+};

package/src/interface/system/body.ts

@@ -0,0 +1,49 @@
+import type { Component } from '../component/component.js';
+import type { Entity } from '../entity/entity.js';
+import type { Resource } from '../resource/resource.js';
+import type { Holding } from '../resource/condition.js';
+import type { Schema } from '../schema/schema.js';
+import type { Commands } from './commands.js';
+import type { Declaration } from './declaration.js';
+import type { Listed, Property } from './property.js';
+import type { RenderContext } from './render.js';
+import type { ComponentValues, LookupFunction, ResourceValues, Values } from './values.js';
+
+/** `read` values are read-only, `write` values readable and writable. */
+export type Row<D extends Declaration> =
+    { readonly entity: Entity }
+    & Values<Listed<Property<D, "components">, "read">, Listed<Property<D, "components">, "write">, Component.Key, ComponentValues>;
+
+type Resources<D> = Listed<Property<D, "resources">, "read"> | Listed<Property<D, "resources">, "write"> | Is<D>;
+type Is<D> = Listed<Property<D, "resources">, "is">;
+type Reduced<D> = keyof Property<D, "reduce"> & Resource.Key;
+
+/**
+ * What a body uses besides its row, by kind, under the declaration's own keys: each is present only when the
+ * declaration declares something of its kind. `commands` is there for every system but a GPU kernel, a render system
+ * and an observer system.
+ */
+export type Context<D extends Declaration> =
+    ([Resources<D>] extends [never] ? {} : {
+        readonly resources: Values<Listed<Property<D, "resources">, "read">, Listed<Property<D, "resources">, "write">, Resource.Key, ResourceValues>
+            & { readonly [K in Is<D> & Resource.Key]: Holding<K> };
+    })
+    & ([keyof Property<D, "lookup">] extends [never] ? {} : {
+        readonly lookup: { readonly [K in keyof Property<D, "lookup">]: LookupFunction<Property<D, "lookup">[K]> };
+    })
+    & ([Reduced<D>] extends [never] ? {} : {
+        /** Each resource it reduces into, as a function contributing a value to the run's fold. */
+        readonly reduce: { readonly [K in Reduced<D>]: (value: Resource.Value<K>) => void };
+    })
+    & (Property<D, "input"> extends Schema ? { readonly input: Schema.ToType<Property<D, "input">> } : {})
+    & (Property<D, "up"> extends object ? {
+        /** The parent's `up.read` values, or null for a row without a parent. */
+        readonly up: { readonly [K in Listed<Property<D, "up">, "read"> & Component.Key]: Component.Value<K> } | null;
+    } : {})
+    & (D extends { readonly kernel: "gpu" } | { readonly shader: object } | { readonly observer: true } ? {} : { readonly commands: Commands });
+
+/** `(row, context)` for a system with `components`, `(context)` for one without, and `(gpu, context)` for a render system. */
+export type Body<D extends Declaration> =
+    D extends { readonly shader: object } ? (gpu: RenderContext, context: Context<D>) => void :
+    Property<D, "components"> extends undefined ? (context: Context<D>) => void :
+    (row: Row<D>, context: Context<D>) => void;

package/src/interface/system/check.ts

@@ -0,0 +1,227 @@
+import { layoutOf } from '../registry/layout.js';
+import { declarationOf, kindOf, labelOf } from '../registry/names.js';
+import { definitionOf } from '../registry/program.js';
+import { reducedBy, scheduleOf } from '../registry/schedule.js';
+import { conditional } from '../registry/schemas.js';
+import { requireRegistered, threadOf } from '../registry/threads.js';
+import { checkWorldWritten } from '../registry/written.js';
+import { checkLookup, indexDefinitionOf, lookupKeysOf, orderKeysOf } from '../registry/indexes.js';
+import { labelOfItem } from '../registry/items.js';
+import type { Schema } from '../schema/schema.js';
+import type { Composite } from './composite.js';
+import type { Definition } from './definition.js';
+import type { Leaf } from './leaf.js';
+
+type Key = symbol;
+
+/** Throws if a key is in both `read` and `write`: `write` already makes it readable. */
+const checkLists = (name: string, what: string, lists: { readonly read?: readonly Key[]; readonly write?: readonly Key[] } | undefined): void => {
+    const writes = new Set(lists?.write);
+    const both = (lists?.read ?? []).find(key => writes.has(key));
+    if (both !== undefined) throw new Error(`System "${name}" lists "${labelOf(both)}" in both ${what} read and write; write already makes it readable.`);
+};
+
+/**
+ * Throws if a leaf reduces into a resource with an operator its `reduce` trait doesn't declare, or also reads, writes
+ * or filters on it, or writes a resource that's reduced, which only its contributors' fold sets.
+ */
+const checkReductions = (leaf: Leaf): void => {
+    const { name } = leaf;
+    const { reduce, resources } = leaf.declaration;
+    const others = new Set<Key>([...resources?.read ?? [], ...resources?.write ?? [], ...resources?.changed ?? []]);
+    for (const key of reducedBy(leaf)) {
+        const declared = declarationOf(key)?.reduce;
+        const operator: unknown = Reflect.get(reduce ?? {}, key);
+        if (declared === undefined) throw new Error(`System "${name}" reduces "${labelOf(key)}", which has no reduce trait.`);
+        if (declared !== operator) throw new Error(`System "${name}" reduces "${labelOf(key)}" with "${labelOf(operator)}", but it's declared reduce: "${labelOf(declared)}".`);
+        if (others.has(key)) throw new Error(`System "${name}" reduces "${labelOf(key)}", so it can't also read, write or filter on it.`);
+    }
+    for (const key of resources?.write ?? []) {
+        if (declarationOf(key)?.reduce !== undefined) throw new Error(`System "${name}" writes "${labelOf(key)}", which is reduced; only its contributors' fold sets it.`);
+    }
+};
+
+/**
+ * Throws if a condition isn't a resource whose value can be `null` or `false`, is in both `is` and `not`, or is also
+ * read or written: `is` already makes it readable.
+ */
+const checkConditions = (leaf: Leaf): void => {
+    const { name } = leaf;
+    const { resources } = leaf.declaration;
+    const is = resources?.is ?? [];
+    const not = resources?.not ?? [];
+    const listed = new Set<Key>([...resources?.read ?? [], ...resources?.write ?? []]);
+    for (const key of [...is, ...not]) {
+        const declaration = declarationOf(key);
+        if (kindOf(key) !== "resource" || declaration === undefined) throw new Error(`System "${name}" runs on the condition of "${labelOf(key)}", which isn't a registered resource.`);
+        const { type } = declaration;
+        if (type !== undefined && !conditional(type)) throw new Error(`System "${name}" runs on the condition of "${labelOf(key)}", which is never null or false.`);
+    }
+    for (const key of is) {
+        if (not.includes(key)) throw new Error(`System "${name}" lists "${labelOf(key)}" in both resources is and not.`);
+        if (listed.has(key)) throw new Error(`System "${name}" lists "${labelOf(key)}" in resources is and in read or write; is already makes it readable.`);
+    }
+};
+
+/** Why kernels can't read a component's values, or null when they can: they read only structs, in linear memory. */
+const unreadByKernels = (key: symbol): string | null => {
+    const { kind } = layoutOf(declarationOf(key)?.type);
+    return kind === "object" ? "which isn't stored in linear memory" : kind === "string" ? "a string, which kernels don't read yet" : null;
+};
+
+/**
+ * Throws for what a leaf's kind and placement rule out: `up` without components or through a key that isn't a reference
+ * component, `order` by anything but a sorted index, without components, with `up` or on the GPU, a kernel's lookup of
+ * a value outside linear memory, a GPU kernel's change filters, lookups and reductions, and a render system's
+ * reductions.
+ */
+const checkPlacement = (leaf: Leaf): void => {
+    const { name } = leaf;
+    const { kernel, components, lookup, up, resources, order } = leaf.declaration;
+    const fail = (message: string): never => { throw new Error(`System "${name}" ${message}.`); };
+    if (order !== undefined) {
+        const index = indexDefinitionOf(order);
+        if (index === undefined) fail("orders its rows by a value Index.create didn't return");
+        else if (index.declaration.sorted !== true) fail(`orders its rows by index "${labelOfItem(index)}", which isn't sorted`);
+        if (components === undefined) fail("orders its rows without components, so it runs once");
+        if (up !== undefined) fail("uses both up and order, which both decide the order of its rows");
+        if (kernel === "gpu") fail("can't run on the GPU: GPU kernels have no order yet");
+        if (kernel !== undefined) {
+            for (const key of orderKeysOf(leaf.declaration)) {
+                const unread = unreadByKernels(key);
+                if (unread !== null) throw new Error(`Kernel "${name}": its rows are ordered by an index keyed by "${labelOf(key)}", ${unread}.`);
+            }
+        }
+    }
+    if (up !== undefined) {
+        if (components === undefined) fail("uses up, which orders rows, without components");
+        if (kindOf(up.through) !== "component" || declarationOf(up.through)?.reference === undefined) {
+            throw new Error(`System "${name}": up.through "${labelOf(up.through)}" isn't a reference component.`);
+        }
+    }
+    const lookups = Object.values(lookup ?? {});
+    if (kernel !== undefined) {
+        // Workers read lookups from shared memory, so their values must be linear there too.
+        for (const key of lookups.flatMap(found => found.read ?? [])) {
+            const unread = unreadByKernels(key);
+            if (unread !== null) throw new Error(`Kernel "${name}": a lookup reads "${labelOf(key)}", ${unread}.`);
+        }
+        for (const key of lookups.flatMap(lookupKeysOf)) {
+            const unread = unreadByKernels(key);
+            if (unread !== null) throw new Error(`Kernel "${name}": a lookup goes through an index keyed by "${labelOf(key)}", ${unread}.`);
+        }
+    }
+    const reduces = reducedBy(leaf).length > 0;
+    if (kernel === "gpu") {
+        if ((components?.added?.length ?? 0) + (components?.changed?.length ?? 0) + (resources?.changed?.length ?? 0) > 0) fail("can't run on the GPU: GPU kernels don't support change filters yet");
+        if (lookups.length > 0) fail("can't run on the GPU: GPU kernels don't support lookups yet");
+        if (reduces) fail("can't run on the GPU: GPU kernels don't support reductions yet");
+    }
+    if (reduces && leaf.kind === "render") fail("can't reduce: a render system records GPU work rather than running rows");
+    if ((leaf.declaration.shader !== undefined) !== (leaf.kind === "render")) fail("has a shader only when System.render makes it");
+};
+
+/**
+ * Throws for what an observer system can't declare: it only reads, after a sync point, so it writes and reduces into
+ * nothing, takes no input, isn't a kernel or a render system, has no `up`, and is ordered with nothing.
+ */
+const checkObserver = (leaf: Leaf): void => {
+    const { name, declaration } = leaf;
+    const { observer } = declaration;
+    if (observer === undefined) return;
+    const fail = (message: string): never => { throw new Error(`System "${name}" is an observer, so it ${message}.`); };
+    if (observer !== true) throw new Error(`System "${name}": observer is true or left out.`);
+    if (leaf.kind === "render") fail("records no GPU work");
+    if (declaration.kernel !== undefined) fail("isn't a kernel");
+    if ((declaration.components?.write?.length ?? 0) + (declaration.resources?.write?.length ?? 0) > 0) fail("writes nothing");
+    if (reducedBy(leaf).length > 0) fail("reduces into nothing");
+    if (declaration.input !== undefined) fail("takes no input");
+    if (declaration.up !== undefined) fail("has no up");
+    if ((declaration.before?.length ?? 0) + (declaration.after?.length ?? 0) + (declaration.during?.length ?? 0) > 0) fail("is ordered with nothing");
+};
+
+/**
+ * Throws for a leaf that names a component or resource that isn't registered as one, lists a key in both `read` and
+ * `write`, writes a reference, has a lookup reading a component it writes, takes input that isn't an object schema,
+ * uses object components and resources of different threads, declares what an observer system can't, or whose
+ * reductions, conditions, `up` or placement can't hold.
+ */
+export const checkLeaf = (leaf: Leaf): void => {
+    const { name, declaration } = leaf;
+    const { components, resources, lookup, input } = declaration;
+    checkLists(name, "components", components);
+    checkLists(name, "resources", resources);
+    checkWorldWritten(`System "${name}"`, resources?.write);
+    const writes = new Set<Key>(components?.write);
+    for (const lookupName in lookup) {
+        checkLookup("System", name, lookupName, lookup[lookupName]);
+        for (const key of lookup[lookupName].read ?? []) {
+            if (writes.has(key)) throw new Error(`System "${name}": lookup "${lookupName}" reads "${labelOf(key)}", which the system writes.`);
+        }
+        for (const key of lookupKeysOf(lookup[lookupName])) {
+            if (writes.has(key)) throw new Error(`System "${name}": lookup "${lookupName}" goes through an index keyed by "${labelOf(key)}", which the system writes.`);
+        }
+    }
+    for (const key of orderKeysOf(declaration)) {
+        if (writes.has(key)) throw new Error(`System "${name}": its rows are ordered by an index keyed by "${labelOf(key)}", which the system writes.`);
+    }
+    if (input !== undefined) {
+        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.`);
+        }
+    }
+    checkTarget(leaf);
+    threadOf(declaration, "System", name);
+    requireRegistered("System", name, "component", components?.has);
+    requireRegistered("System", name, "component", components?.not);
+    for (const lookupName in lookup) {
+        const found = lookup[lookupName];
+        requireRegistered("System", name, "component", "has" in found ? found.has : undefined);
+        requireRegistered("System", name, "component", "not" in found ? found.not : undefined);
+    }
+    for (const key of components?.write ?? []) {
+        if (declarationOf(key)?.reference !== undefined) throw new Error(`System "${name}" writes "${labelOf(key)}", a reference, which changes only through commands.`);
+    }
+    checkObserver(leaf);
+    checkReductions(leaf);
+    checkConditions(leaf);
+    checkPlacement(leaf);
+};
+
+/**
+ * Throws if a system on one entity takes it from what isn't an entity field of its input, has no components, or is a
+ * kernel, has `up` or `order`, or reduces.
+ */
+const checkTarget = (leaf: Leaf): void => {
+    const { name, declaration } = leaf;
+    const { target, input, components, kernel, up, order, reduce } = declaration;
+    if (target === undefined) return;
+    const fail = (message: string): never => { throw new Error(`System "${name}" runs on one entity, so it ${message}.`); };
+    const field: Schema | undefined = input !== undefined && "properties" in input ? Reflect.get(input.properties, target) : undefined;
+    if (field === undefined || !("format" in field) || field.format !== "entity") fail(`takes it from an input field "${target}" holding an entity`);
+    if (components === undefined) fail("needs components");
+    if (kernel !== undefined) fail("isn't a kernel");
+    if (up !== undefined || order !== undefined) fail("has no up or order");
+    if (reduce !== undefined) fail("reduces into nothing");
+};
+
+/** Every leaf under a system, each once. Throws for a member no System constructor returned. */
+const leavesOf = (system: Definition, leaves: Set<Leaf>): Set<Leaf> => {
+    if (system.kind !== "composite") return leaves.add(system);
+    for (const member of system.declaration.systems) {
+        const definition = definitionOf(member);
+        if (definition === undefined) throw new Error(`System "${system.name}": member "${member.name}" isn't a system a System constructor returned.`);
+        leavesOf(definition, leaves);
+    }
+    return leaves;
+};
+
+/**
+ * Throws for a member no System constructor returned, members ordered in a cycle, two that conflict with no order
+ * between them, or an input field two members declare with different schemas.
+ */
+export const checkComposite = (composite: Composite): void => {
+    leavesOf(composite, new Set());
+    scheduleOf(composite);
+};

package/src/interface/system/commands.ts

@@ -0,0 +1,26 @@
+import type { Component } from '../component/component.js';
+import type { Entity } from '../entity/entity.js';
+import type { Essential } from '../component/value.js';
+import type { ValuesOf } from '../archetype/values-of.js';
+
+/** The value an `add` of one component takes: none for a tag. */
+type ValueArgument<K extends Essential> = Component.Value<K> extends true ? [value?: true] : [value: Component.Value<K>];
+
+/**
+ * Structural changes and writes to other entities, applied in issue order at the next sync point. They take only the
+ * components commands may add: every one but those rules derive.
+ */
+export type Commands = {
+    /**
+     * The spawner of entities of exactly `components`: the same function for a world and list each time, so calling
+     * it allocates nothing. It returns a real entity immediately, alive at the sync point.
+     */
+    spawn<const C extends readonly Essential[]>(components: C): (values: ValuesOf<C>) => Entity;
+    despawn(entity: Entity): void;
+    /** Adds or replaces one component's value, marking it changed. */
+    add<K extends Essential>(entity: Entity, component: K, ...value: ValueArgument<K>): void;
+    /** Adds or replaces the values of `components`, marking them changed. */
+    add<const C extends readonly Essential[]>(entity: Entity, components: C, values: ValuesOf<C>): void;
+    remove(entity: Entity, component: Essential): void;
+    remove(entity: Entity, components: readonly Essential[]): void;
+};

package/src/interface/system/commands.type-test.ts

@@ -0,0 +1,93 @@
+import { Resource } from '../resource/resource.js';
+import { Component } from '../component/component.js';
+import { Archetype } from '../archetype/archetype.js';
+import type { Entity } from '../entity/entity.js';
+import type { Commands } from './commands.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>() => { };
+
+const position = Symbol("commandsTypeTest/position");
+const velocity = Symbol("commandsTypeTest/velocity");
+const label = Symbol("commandsTypeTest/label");
+const player = Symbol("commandsTypeTest/player");
+const slot = Symbol("commandsTypeTest/slot");
+const time = Symbol("commandsTypeTest/time");
+declare module '@adobe/ecs' {
+    export interface Components {
+        [position]: { type: number };
+        [velocity]: { type: number };
+        [label]: { type: string | null };
+        [player]: { type: true };
+        [slot]: { type: number; derived: true };
+    }
+    export interface Resources {
+        [time]: { type: number };
+    }
+}
+Component.register(position, { type: { type: "number" } });
+Component.register(velocity, { type: { type: "number" } });
+Component.register(label, { type: { anyOf: [{ type: "string" }, { type: "null" }] } });
+Component.register(player, { type: { const: true } });
+Component.register(slot, { type: { type: "number", default: 0 }, derived: true });
+Resource.register(time, { type: { type: "number", default: 0 } });
+
+const particle = Archetype.create([position, velocity, label, player]);
+
+export const issue = (commands: Commands, entity: Entity): void => {
+    // `spawn` is curried: the components first, then their values, giving an entity.
+    const insert = commands.spawn(particle);
+    const spawned: Entity = insert({ [position]: 0, [velocity]: 1 });
+    check<Equal<Parameters<typeof insert>[0], { readonly [position]: number; readonly [velocity]: number } & { readonly [label]?: string | null; readonly [player]?: true }>>();
+    // A tag needs no value, nor does a component whose type allows null; any other is required.
+    insert({ [position]: 0, [velocity]: 1, [label]: "a", [player]: true });
+    // @ts-expect-error velocity has no default
+    insert({ [position]: 0 });
+    // @ts-expect-error values are exact against the components: velocity isn't in this spawn
+    commands.spawn([position])({ [position]: 0, [velocity]: 1 });
+    // @ts-expect-error values have the components' types
+    commands.spawn([position])({ [position]: "zero" });
+    // A plain or inline list spawns too.
+    commands.spawn([position, player])({ [position]: 0 });
+    commands.spawn([])({});
+    // A list that isn't a tuple takes any of its components' values.
+    const dynamic: (typeof position | typeof player)[] = [position];
+    commands.spawn(dynamic)({});
+    commands.spawn(dynamic)({ [position]: 1 });
+    // @ts-expect-error but only theirs
+    commands.spawn(dynamic)({ [velocity]: 1 });
+    // @ts-expect-error spawn takes its components first
+    commands.spawn({ [position]: 0 });
+    // @ts-expect-error commands never add a derived component
+    commands.spawn([slot]);
+    // @ts-expect-error nor a resource
+    commands.spawn([time]);
+    void spawned;
+
+    // `add` takes one component and its value, or a list and its values; a tag needs no value.
+    commands.add(entity, position, 1);
+    commands.add(entity, player);
+    commands.add(entity, player, true);
+    // @ts-expect-error a component with a value type takes its value
+    commands.add(entity, position);
+    // @ts-expect-error of its type
+    commands.add(entity, position, "one");
+    commands.add(entity, [position, player], { [position]: 1 });
+    commands.add(entity, particle, { [position]: 1, [velocity]: 2 });
+    // @ts-expect-error a list's values are exact against it
+    commands.add(entity, [position], { [position]: 1, [velocity]: 2 });
+    // @ts-expect-error the list form requires its components
+    commands.add(entity, { [position]: 1 });
+    // @ts-expect-error commands never add a derived component
+    commands.add(entity, slot, 1);
+
+    // `remove` takes one component or one list.
+    commands.remove(entity, position);
+    commands.remove(entity, [position, player]);
+    commands.remove(entity, particle);
+    // @ts-expect-error no rest parameters
+    commands.remove(entity, position, velocity);
+    // @ts-expect-error commands never remove a derived component
+    commands.remove(entity, slot);
+    commands.despawn(entity);
+};

package/src/interface/system/composite-declaration.ts

@@ -0,0 +1,14 @@
+import type { Name } from './name.js';
+import type { System } from './system.js';
+
+/** Each run passes every member the same input, with the fields of all their inputs. */
+export type CompositeDeclaration = {
+    readonly name?: Name;
+    readonly systems: readonly System<unknown>[];
+    /** Hard constraint, applied to every member. */
+    readonly before?: readonly System<unknown>[];
+    /** Hard constraint, applied to every member. */
+    readonly after?: readonly System<unknown>[];
+    /** Runs inside the span of the systems listed: after what they follow and before what follows them. Applied to every member. */
+    readonly during?: readonly System<unknown>[];
+};