@adobe/ecs 0.1.0 → 0.2.0

package/src/interface/system/create.ts

@@ -1,130 +1,128 @@
-import type { Component } from '../component/component.js';
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Entity } from '../entity/entity.js';
 import type { Index } from '../indexes/index-type.js';
+import type { Condition } from '../resource/condition.js';
 import { takeIdOfDeclaration } from '../registry/ids.js';
 import { nameOf } from '../registry/items.js';
 import { claimSystem } from '../registry/program.js';
-import type { Resource } from '../resource/resource.js';
-import type { Schema } from '../schema/schema.js';
-import type { Body } from './body.js';
-import type { Commands } from './commands.js';
-import { checkComposite, checkLeaf } from './check.js';
+import type { Body, Context } from './body.js';
+import { checkComposite, checkLeaf, inputSchemaOf } from './check.js';
 import type { Composite } from './composite.js';
 import type { CompositeDeclaration } from './composite-declaration.js';
-import type { Declaration } from './declaration.js';
-import type { CheckMembers, CompositeInputOf, InputOf } from './input.js';
+import type { Declaration, Resolved } from './declaration.js';
+import type { CheckMembers, CompositeInputOf, InputOf, ResultOf, ReturnsNoPromise } from './input.js';
 import type { Leaf } from './leaf.js';
 import type { Listed, Property } from './property.js';
-import type { StructComponent, StructResource } from './struct.js';
 import type { System } from './system.js';
 import type { OneThread, ThreadedBy, ThreadsOf } from './threads.js';
 import type { HeldBy } from './values.js';
+import type { Shared } from '../component/value.js';
+import { accessOf, compact, componentLists, lookupsLists, resourceUses, upReads, whereReadsOf } from './resolve.js';
 
-type Reduced<D extends Declaration> = keyof Property<D, "reduce"> & Resource.Key;
-type Written<D, K extends "components" | "resources"> = Listed<Property<D, K>, "write">;
-type Is<D> = Listed<Property<D, "resources">, "is">;
 type Lookups<D> = Property<D, "lookup">;
 
-/**
- * An index lookup reads and watches only what every entity its index holds has, and its system doesn't write what it
- * finds rows by or reads through it. A lookup by entity watches only what it reads or has.
- */
-type IndexLookups<D> = {
+/** A lookup's `changed` names what it requires: a lookup by entity's `with`, an index lookup's what its index holds. */
+type LookupChanges<D> = {
     readonly lookup?: {
         readonly [N in keyof Lookups<D>]?: Lookups<D>[N] extends { readonly index: Index<infer I> }
-            ? {
-                readonly index?: Index<{ readonly key: readonly Exclude<Component.Key, Written<D, "components">>[] }>;
-                readonly read?: readonly Exclude<HeldBy<I>, Written<D, "components">>[];
-                readonly changed?: readonly HeldBy<I>[] | true;
-            }
-            : { readonly changed?: readonly (Listed<Lookups<D>[N], "read"> | Listed<Lookups<D>[N], "has">)[] }
+            ? { readonly changed?: readonly HeldBy<I>[] | true }
+            : { readonly changed?: readonly Listed<Lookups<D>[N], "with">[] }
     };
 };
 
-/** A system's rows are ordered by an index whose key parts it doesn't write. */
-type Order<D> = { readonly order?: Index<{ readonly key: readonly Exclude<Component.Key, Written<D, "components">>[] }> };
-
-/**
- * A key in `write` is readable too, so it isn't also in `read`. A system doesn't read or filter on what it reduces
- * into, since the fold is only finished after every contributor runs. A condition in `is` is readable too, and isn't
- * written or also in `not`.
- */
-type Lists<D extends Declaration> = {
-    readonly components?: { readonly read?: readonly Exclude<Component.Key, Written<D, "components">>[] };
-    readonly resources?: {
-        readonly read?: readonly Exclude<Resource.Key, Written<D, "resources"> | Reduced<D> | Is<D>>[];
-        readonly write?: readonly Exclude<Resource.Key, Is<D>>[];
-        readonly changed?: readonly Exclude<Resource.Key, Reduced<D>>[];
-        readonly not?: readonly Exclude<Resource.Key, Is<D>>[];
-    };
+/** What a body reads, writes and reduces into is inferred, never declared. */
+type Inferred = {
+    readonly components?: { readonly read?: never; readonly write?: never; readonly has?: never };
+    readonly resources?: { readonly read?: never; readonly write?: never; readonly reduce?: never };
+    readonly up?: { readonly read?: never };
+    readonly reduce?: never;
 };
 
-type Kernel = {
-    readonly components?: { readonly read?: readonly StructComponent[]; readonly write?: readonly StructComponent[] };
-    readonly lookup?: {
-        readonly [name: string]:
-            | { readonly read?: readonly StructComponent[]; readonly has?: readonly Component.Key[]; readonly not?: readonly Component.Key[]; readonly changed?: readonly Component.Key[]; readonly index?: never }
-            | { readonly read?: readonly StructComponent[]; readonly changed?: readonly Component.Key[] | true; readonly index: Index<{ readonly key: readonly StructComponent[] }> };
-    };
-    readonly up?: { readonly read?: readonly StructComponent[] };
-    readonly order?: Index<{ readonly key: readonly StructComponent[] }>;
-    readonly resources?: { readonly read?: readonly StructResource[]; readonly write?: never };
-};
+/** A condition is in `is` or `not`, not both. */
+type Conditions<D> = { readonly resources?: { readonly not?: readonly Exclude<Condition, Listed<Property<D, "resources">, "is">>[] } };
 
 /** What a GPU kernel can't use yet, beyond any kernel's limits. */
 type GpuKernel = {
     readonly lookup?: { readonly [name: string]: never };
     readonly components?: { readonly added?: never; readonly changed?: never };
     readonly resources?: { readonly changed?: never };
-    readonly reduce?: { readonly [K in Resource.Key]?: never };
     readonly order?: { readonly "error: GPU kernels have no order yet": true };
 };
 
 /**
- * An observer system only reads, after a sync point: it writes and reduces into nothing, takes no input, isn't a
- * kernel, has no `up`, and is ordered with nothing.
+ * An observer system only reads, after a sync point: its row and resources are read-only, and it never compiles to a
+ * kernel, has no `up`, and is ordered with nothing. That it takes no input is checked at its body.
  */
 type Observer = {
-    readonly kernel?: never;
-    readonly components?: { readonly write?: never };
-    readonly resources?: { readonly write?: never };
-    readonly reduce?: never;
-    readonly input?: never;
+    readonly kernel?: false;
     readonly up?: never;
     readonly before?: never;
     readonly after?: never;
     readonly during?: never;
 };
 
-/** The fields of input `I` that hold an entity. */
-type EntityFields<I> = { [K in keyof I]-?: [Exclude<I[K], undefined>] extends [Entity] ? K : never }[keyof I] & string;
-
-/** A system on one entity takes it from an entity field of its input, and runs on its row, in no order. */
-type Targeted<D extends Declaration> = {
-    readonly target?: EntityFields<InputOf<D>>;
-    readonly kernel?: never;
+/** A system on one entity runs on its row, in no order; that its target is an entity field of its input is checked at its body. */
+type Targeted = {
+    readonly kernel?: false;
     readonly up?: never;
     readonly order?: never;
-    readonly reduce?: never;
 };
 
+/** `where` names only shared components, and keeps rows unordered across archetypes, so it's without `up`, `order` and a target. */
+type Where<D> = D extends { readonly components: { readonly where: infer W } }
+    ? { readonly components?: { readonly where?: { readonly [K in Exclude<keyof W, Shared>]: { readonly "error: where names only shared components, which each archetype holds one value of": K } } } }
+        & (D extends { readonly up: object } | { readonly order: object } | { readonly target: string }
+            ? { readonly components?: { readonly where?: { readonly "error: where can't be used with up, order or a target, which run rows across archetypes": true } } } : {})
+    : {};
+
+/**
+ * Whether the threads a declaration's objects live on hold, once its type is known: never checked against the
+ * constraint itself, which TypeScript instantiates the parameter with while a predicate in `where` waits for its type.
+ */
+type Placed<D extends Declaration> = Declaration extends D ? {} : OneThread<ThreadsOf<D>, ThreadedBy<D>>;
+
 type Validate<D extends Declaration> =
-    Lists<D>
-    & IndexLookups<D>
-    & Order<D>
-    & (D extends { readonly input: Schema } ? { readonly components?: { readonly added?: never; readonly changed?: never } } : {})
-    & (D extends { readonly kernel: "cpu" | "gpu" } ? Kernel : {})
+    LookupChanges<D>
+    & Where<D>
+    & Conditions<D>
+    & Inferred
     & (D extends { readonly kernel: "gpu" } ? GpuKernel : {})
     // `up` and `order` order rows, so a system without them has neither, and one has at most one of them.
-    & (Property<D, "components"> extends undefined ? { readonly up?: { readonly [key: string]: never }; readonly order?: { readonly "error: a system without components runs once, in no order": true } } : {})
+    & (Property<D, "components"> extends undefined ? {
+        readonly up?: { readonly [key: string]: never };
+        readonly order?: { readonly "error: a system without components runs once, in no order": true };
+        readonly kernel?: false | { readonly "error: a system without components runs once, so there's nothing to compile": true };
+    } : {})
     & (D extends { readonly up: object } ? { readonly order?: { readonly "error: up and order both decide the order of its rows": true } } : {})
+    // GPU kernels don't read components an archetype may lack yet.
+    & (D extends { readonly components: { readonly optional: readonly [unknown, ...unknown[]] } }
+        ? { readonly kernel?: boolean | { readonly "error: a GPU kernel can't have optional components yet": true } } : {})
     & (D extends { readonly observer: true } ? Observer : {})
-    & (D extends { readonly target: string } ? Targeted<D> : {})
+    & (D extends { readonly target: string } ? Targeted : {})
     & (D extends { readonly target: string } ? Property<D, "components"> extends undefined ? { readonly target?: { readonly "error: a system on one entity runs on its row, so it needs components": true } } : {} : {})
-    & { readonly shader?: never };
+    // A body's input is the type of its parameter after its context, not part of its declaration.
+    & { readonly shader?: never; readonly input?: never };
+
+/** The fields of input `I` that hold an entity. */
+type EntityFields<I> = { [K in keyof I]-?: [Exclude<I[K], undefined>] extends [Entity] ? K : never }[keyof I] & string;
 
-/** The body of a system that declares nothing, which runs once per run with its commands. */
-type Alone = (context: { readonly commands: Commands }) => void;
+/**
+ * What a declaration requires of the input its body takes, checked at the body, since the input is known only once the
+ * body is: a target names an entity field of it, and a system with input doesn't filter on added or changed, as its
+ * runs pass different input, nor is it an observer. Every check passes for `never`, the input before the body is
+ * inferred.
+ */
+type Checks<D, I> = [I] extends [never] ? unknown :
+    (D extends { readonly target: infer T extends string }
+        ? [I] extends [undefined] ? { readonly "error: a system with a target takes its input after its context": T }
+        : T extends EntityFields<I> ? unknown : { readonly "error: its target is no entity field of its input": T }
+        : unknown)
+    & ([I] extends [undefined] ? unknown
+        : (D extends { readonly components: { readonly added: object } | { readonly changed: object } } ? { readonly "error: a system with input can't filter on added or changed, as its runs pass different input; pass it through a resource": true } : unknown)
+        & (D extends { readonly observer: true } ? { readonly "error: an observer system takes no input": true } : unknown));
+
+/** The body of a system that declares nothing, which runs once per run with its resources and commands. */
+type Alone = (context: Context<{}>) => void;
 
 /** A composite: its list of members, or its declaration. */
 type Composition = readonly System<unknown>[] | CompositeDeclaration;
@@ -133,48 +131,77 @@ type Composition = readonly System<unknown>[] | CompositeDeclaration;
 type MembersOf<C> = C extends CompositeDeclaration ? C["systems"] : C;
 
 /** A member whose input has a field of a different type than another member's becomes the error saying so. */
-type Checked<C> = C extends Alone ? unknown : C extends CompositeDeclaration ? { readonly systems: CheckMembers<C["systems"]> } : CheckMembers<C>;
+type Checked<C> = C extends Alone ? ReturnsNoPromise<C> : C extends CompositeDeclaration ? { readonly systems: CheckMembers<C["systems"]> } : CheckMembers<C>;
 
 /**
  * Declares a system and returns it; nothing runs. The arguments tell the forms apart:
- * - `create(body)`: a system that declares nothing, whose body runs once per run with its commands.
+ * - `create(body)`: a system that declares nothing, whose body runs once per run with its resources and commands.
  * - `create(declaration, body)`: a system.
  * - `create([move, collide])`: a composite of the systems listed, which may live on different threads.
- * - `create({ systems: [move, collide], after: [input] })`: a composite with a name or constraints.
+ * - `create({ systems: [move, collide], after: [input] })`: a composite with constraints.
  *
- * Each run passes a composite's members one input, with every field of theirs. Throws if a system names a key that
- * isn't registered as its kind, lists a key in both `read` and `write`, writes a reference, a lookup reads a component
- * it writes or goes through an index keyed by one, or reads through an index what not every entity it holds has, its
+ * What a body reads, writes and reduces into the build infers from it. Each run passes a composite's members one
+ * input, with every field of theirs. Throws if a system names a key that isn't registered as its kind, its body writes
+ * a reference, a lookup's rows are read where it writes them or it goes through an index keyed by what it writes, its
  * rows are ordered by an index it isn't sorted or keyed by what it writes, its object components and resources live on
  * different threads, or its reductions, conditions, `up`, `order` or placement can't hold, or it's an observer and
- * writes, reduces, takes input, is a kernel, has `up` or is ordered; or if a composite's member isn't a system a
- * constructor returned, or two members declare an input field with different schemas. A composite's observer members
- * run after its sync point, ordered with nothing.
+ * writes, reduces, takes input, is a kernel, has `up` or is ordered; if the build couldn't follow how its body uses its
+ * resources, lookups or parent; or if a composite's member isn't a system a constructor returned, or two members
+ * declare an input field with different schemas. A composite's observer members run after its sync point, ordered
+ * with nothing.
+ *
+ * A run of a system without components resolves to what its body returns, or `undefined` when its conditions, resource
+ * change filters or index lookups' `changed: true` skip it; a run of any other system or a composite to nothing. A
+ * body returns no promise, by type and at runtime, where returning one fails its system: a run never waits for one.
  *
  * One argument, a body or a composite, is one overload, so a mistake in it is reported where it is rather than as no
  * overload matching.
  */
-export function create<const D extends Declaration>(declaration: D & Validate<D> & OneThread<ThreadsOf<D>, ThreadedBy<D>>, body: Body<D>): System<InputOf<D>>;
-export function create<const C extends Alone | Composition>(only: C & Checked<C>): C extends Alone ? System : System<CompositeInputOf<MembersOf<C>>>;
-export function create(first: Declaration | Leaf["body"] | readonly System<unknown>[] | CompositeDeclaration, second?: Leaf["body"]): System<unknown> {
+export function create<const D extends Declaration, B extends Body<D, never>>(declaration: D & Validate<D> & Placed<D>, body: B & Checks<D, InputOf<D, B>> & ReturnsNoPromise<B>): System<InputOf<D, B>, ResultOf<D, B>>;
+export function create<const C extends Alone | Composition>(only: C & Checked<C>): C extends (context: Context<{}>) => infer R ? System<undefined, R> : System<CompositeInputOf<MembersOf<C>>>;
+// The plugin passes the schema of the body's input as a third argument.
+export function create(first: Declaration | Leaf["body"] | readonly System<unknown>[] | CompositeDeclaration, second?: Leaf["body"], input?: unknown): System<unknown> {
     // The plugin gives its id to the call's first argument: the declaration, the members, or the body made into a
     // system alone.
     const id = takeIdOfDeclaration(first);
-    if (isList(first)) return compose({ systems: first }, id);
-    if (typeof first !== "function" && second === undefined && "systems" in first) return compose(first, id);
-    const declaration: Declaration = typeof first === "function" ? {} : first;
+    if (isList(first)) return compose(first, { systems: first }, id);
+    if (typeof first !== "function" && second === undefined && "systems" in first) return compose(first, first, id);
+    const declared: Declaration = typeof first === "function" ? {} : first;
     const body = typeof first === "function" ? first : second;
     if (body === undefined) throw new Error("A system needs a body, and a composite its systems.");
-    const system: Leaf & System<unknown> = { kind: "system", name: nameOf(declaration.name, id, "system"), declaration, body };
+    const name = nameOf(first, id, "system");
+    const declaration = resolve(`System "${name}"`, declared, accessOf(`System "${name}"`, first));
+    const schema = inputSchemaOf(name, body, declaration.components === undefined ? 1 : 2, input);
+    const system: Leaf & System<unknown> = { kind: "system", name, declaration, input: schema, body };
     checkLeaf(system);
     claimSystem(system, id);
     return system;
 }
 
+/** A declaration as the world takes it, with what the build inferred its body uses. */
+const resolve = (what: string, declared: Declaration, access: ReturnType<typeof accessOf>): Resolved => {
+    const reading = declared.observer === true;
+    const { components, lookup, up, resources, ...rest } = declared;
+    const uses = resourceUses(what, access, resources?.is);
+    // What `where`'s predicates read counts as the system's reads, for its order, conflicts and placement.
+    const whereReads = whereReadsOf(what, components, access);
+    const conditions: readonly symbol[] = resources?.is ?? [];
+    for (const key of whereReads) if (!uses.read.includes(key) && !uses.write.includes(key) && !conditions.includes(key)) uses.read.push(key);
+    const resolved: Resolved = {
+        ...rest,
+        ...components === undefined ? {} : { components: componentLists(components, access.components, reading, whereReads) },
+        ...lookup === undefined ? {} : { lookup: lookupsLists(lookup, access) },
+        ...up === undefined ? {} : { up: { through: up.through, read: upReads(what, access) } },
+    };
+    const lists = compact({ read: uses.read, write: uses.write, reduce: uses.reduce, changed: resources?.changed, is: resources?.is, not: resources?.not });
+    return Object.keys(lists).length === 0 ? resolved : { ...resolved, resources: lists };
+};
+
 const isList = (value: unknown): value is readonly System<unknown>[] => Array.isArray(value);
 
-const compose = (declaration: CompositeDeclaration, id: string | undefined): System<unknown> => {
-    const system: Composite & System<unknown> = { kind: "composite", name: nameOf(declaration.name, id, "system"), declaration };
+/** A composite of `declaration`, labeled by `first`, the argument the plugin labeled. */
+const compose = (first: object, declaration: CompositeDeclaration, id: string | undefined): System<unknown> => {
+    const system: Composite & System<unknown> = { kind: "composite", name: nameOf(first, id, "system"), declaration };
     checkComposite(system);
     claimSystem(system, id);
     return system;

package/src/interface/system/declaration.ts

@@ -1,35 +1,39 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Index } from '../indexes/index-type.js';
 import type { Resource } from '../resource/resource.js';
-import type { Schema } from '../schema/schema.js';
-import type { ComponentAccess, ResourceAccess, SystemLookup, Up } from './access.js';
-import type { Name } from './name.js';
+import type { ComponentAccess, ComponentLists, ResourceAccess, ResourceLists, SystemLookup, SystemLookupLists, Up, UpLists } from './access.js';
 import type { Shader } from './render.js';
 import type { System } from './system.js';
-import type { OperatorOf, Reduced } from '../resource/reduction.js';
 
 /**
  * A system never declares its thread: it runs on the one its object components and resources live on, those it
- * reads, writes or filters on by change, through `components`, `lookup`, `up` and `resources` but `has` and `not`.
- * Without them, a kernel runs on the kernel pool and any other system on `"world"`.
+ * reads, writes or filters on by change, through its row, lookups, `up` and resources. Without them, a kernel runs on
+ * the kernel pool and any other system on `"world"`. A declaration says only what its body can't show: which entities
+ * it runs over, its filters and conditions, and its order; the build infers what the body reads, writes and reduces.
  */
 export type Declaration = {
-    readonly name?: Name;
     /**
-     * Compiled to a kernel, which the build rejects if the body leaves the kernel subset. Values in `components` and
-     * `lookup` must be structs and resources read-only. Without it, the system runs as written, on its thread.
-     * - `"cpu"`: runs on the kernel pool. - `"gpu"`: also has no lookups, change filters, commands or loops, and only
-     *   4-byte scalar values, its `up` included. It runs as a   compute shader in a world with a GPU, and as a `"cpu"`
-     *   kernel in one without. Every matched row counts as   changed in what it writes.
+     * Whether its body compiles to a kernel, a function the build compiles to run on every matched row, in parallel, on
+     * the kernel pool. Values in `components` and `lookup` must be structs and resources read-only.
+     * - Without it, a system with components compiles when its body is in the kernel subset and its declaration allows
+     *   it, and otherwise runs as written, computing as the body as written does. A system without components runs once,
+     *   as written.
+     * - `true`: compiles, or the build fails saying why. Its arithmetic may round each step to storage precision, as
+     *   WASM's f32 SIMD lanes do, so its results may differ from the body as written.
+     * - `false`: runs as written, on its thread.
+     * - `"gpu"`: also has no lookups, change filters, commands or loops, and only 4-byte scalar values, its `up`
+     *   included. It runs as a compute shader in a world with a GPU, and as a kernel on the pool in one without. Every
+     *   matched row counts as changed in what it writes.
      */
-    readonly kernel?: "cpu" | "gpu";
-    /** The entities it runs over, and what it reads and writes of theirs. Omitted for a system that runs once per run. */
+    readonly kernel?: boolean | "gpu";
+    /** The entities it runs over. Omitted for a system that runs once per run. */
     readonly components?: ComponentAccess;
     readonly lookup?: { readonly [name: string]: SystemLookup };
     /**
-     * Runs rows in depth order through `through`, so each reads its parent's `read` values after the parent ran, as
-     * the context's `up`, or null for a row without a parent. With change filters, a row also passes when its parent,
-     * or what it reads of its parent, changed since the system last ran, or it moved to another archetype, as removing
-     * its parent moves it. Rows on or under a parent cycle don't run.
+     * Runs rows in depth order through `through`, so each reads its parent's values after the parent ran, as the
+     * context's `up`, or null for a row without a parent. With change filters, a row also passes when its parent, or
+     * what it reads of its parent, changed since the system last ran, or it moved to another archetype, as removing its
+     * parent moves it. Rows on or under a parent cycle don't run.
      */
     readonly up?: Up;
     /**
@@ -39,14 +43,10 @@ export type Declaration = {
      */
     readonly order?: Index<{ readonly sorted: true }>;
     readonly resources?: ResourceAccess;
-    /** The resources its body contributes to, each with the operator its `reduce` trait declares. */
-    readonly reduce?: { readonly [K in Reduced]?: OperatorOf<K> };
-    /** The object of named fields passed to each run. A system with input can't use `added` or `changed`. */
-    readonly input?: Extract<Schema, { readonly type: "object" }>;
     /**
-     * The input field naming the one entity it runs on: its body runs once, on that entity's row, when the entity is
-     * alive and matches `components`, and not at all otherwise. Needs `components`; not with `kernel`, `up`, `order`
-     * or `reduce`.
+     * The field of its body's input naming the one entity it runs on: its body runs once, on that entity's row, when
+     * the entity is alive and matches `components`, and not at all otherwise. Needs `components`; not with `kernel`,
+     * `up` or `order`, nor with a body that reduces.
      */
     readonly target?: string;
     /** Makes this a render system (see `render`): its body records GPU work over the GPU copy of the components it names. */
@@ -63,3 +63,11 @@ export type Declaration = {
      */
     readonly observer?: true;
 };
+
+/** A declaration as the world takes it: the build's inferred reads, writes and reductions joined with what it declares. */
+export type Resolved = Omit<Declaration, "components" | "lookup" | "up" | "resources"> & {
+    readonly components?: ComponentLists;
+    readonly lookup?: { readonly [name: string]: SystemLookupLists };
+    readonly up?: UpLists;
+    readonly resources?: ResourceLists;
+};

package/src/interface/system/definition.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Composite } from './composite.js';
 import type { Leaf } from './leaf.js';
 

package/src/interface/system/index.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 export type { Commands } from './commands.js';
 export * from './create.js';
 export { render, type RenderContext, type RenderTable } from './render.js';

package/src/interface/system/input.ts

@@ -1,11 +1,42 @@
-import type { Schema } from '../schema/schema.js';
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Property } from './property.js';
 import type { System } from './system.js';
 
+/** How many parameters come before a body's input: the row and the context, or the context alone. */
+type Before<D> = D extends { readonly components: object } ? 2 : 1;
+
+/** The input body `B` of declaration `D` takes: the type of its parameter after the context, or `undefined` without one. */
+export type InputOf<D, B> = B extends (...parameters: infer P) => void ? P["length"] extends Before<D> ? undefined : P[Before<D>] : undefined;
+
+/** Whether a declaration's conditions, resource change filters or index lookups' `changed: true` can skip its body. */
+type Skippable<D> =
+    D extends { readonly resources: { readonly is: object } | { readonly not: object } | { readonly changed: object } } ? true
+    : true extends { [N in keyof Property<D, "lookup">]: Property<D, "lookup">[N] extends { readonly changed: true } ? true : false }[keyof Property<D, "lookup">] ? true
+    : false;
+
+/**
+ * What a run of a system of declaration `D` and body `B` resolves to: for one without components, what its body
+ * returns, or `undefined` too when its body may be skipped; for one with components, nothing.
+ */
+export type ResultOf<D, B> = D extends { readonly components: object } ? void
+    : B extends (...parameters: never[]) => infer R ? [R] extends [void] ? R : Skippable<D> extends true ? R | undefined : R : void;
+
+/** Whether `R` is exactly `unknown` or `object`, return types wide enough to hide a promise. */
+type Hides<R> = unknown extends R ? true
+    : [R] extends [object] ? [object] extends [R] ? [keyof R] extends [never] ? string extends R ? false : true : false : false : false;
+
 /**
- * The input a system declares: a value of its `input` schema, or `undefined` without one; `unknown` for `any`, as an
- * overload's declaration erases to, since every schema's value type is too deep to compute.
+ * A body returning a promise or another `PromiseLike`, or declared to return `unknown` or `object`, which may be one,
+ * becomes the error saying it returns none: a run never waits for one, so a body starts the work and a later run
+ * finishes it. Types can't tell a body returning `any`, nor an async function typed as returning `void`.
  */
-export type InputOf<D> = 0 extends 1 & D ? unknown : D extends { readonly input: infer A extends Schema } ? Schema.ToType<A> : undefined;
+export type ReturnsNoPromise<B> = B extends (...parameters: never[]) => infer R
+    ? 0 extends (1 & R) ? unknown
+    : [Extract<R, PromiseLike<unknown>>] extends [never] ? Hides<R> extends true ? NoPromise : unknown
+    : NoPromise
+    : unknown;
+
+type NoPromise = { readonly "error: a body returns no promise; start the work, and finish it in a later run": true };
 
 /** What `run` takes after a system: nothing, or one value. */
 export type Input<I> = [I] extends [undefined] ? [] : [input: I];

package/src/interface/system/leaf.ts

@@ -1,13 +1,20 @@
-import type { Declaration } from './declaration.js';
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Schema } from '../schema/schema.js';
+import type { Resolved } from './declaration.js';
 import type { Name } from './name.js';
 
+/** The schema of a body's input: an object of named fields. */
+export type InputSchema = Extract<Schema, { readonly type: "object" }>;
+
 /**
  * A system that runs a body: `"render"` for one made by `render`, `"system"` otherwise. Its body's parameters are
- * checked where it's created, so a leaf holds any body.
+ * checked where it's created, so a leaf holds any body. `input` is the schema of its body's input, which the plugin
+ * gives from the type of the body's parameter after its context, or undefined; every leaf has it, so leaves share a shape.
  */
 export type Leaf = {
     readonly kind: "system" | "render";
     readonly name: Name;
-    readonly declaration: Declaration;
+    readonly declaration: Resolved;
+    readonly input: InputSchema | undefined;
     readonly body: (...parameters: never[]) => void;
 };

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

@@ -0,0 +1,53 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Component } from '../component/component.js';
+import { Entity, Index, System } from "@adobe/ecs";
+
+const position = Symbol("listsTypeTest/position");
+const velocity = Symbol("listsTypeTest/velocity");
+const scale = Symbol("listsTypeTest/scale");
+declare module "@adobe/ecs" {
+    interface Components {
+        [position]: { type: number };
+        [velocity]: { type: number };
+    }
+    interface Resources {
+        [scale]: { type: number };
+    }
+}
+
+type Equal<A, B> = (<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2) ? true : false;
+const expectType = <T extends true>(): T | undefined => undefined;
+
+// A list of components declared `as const` is a tuple, an archetype wherever component lists go.
+export const Particle = [position, velocity] as const;
+expectType<Equal<typeof Particle, readonly [typeof position, typeof velocity]>>();
+export const one: readonly Component.Key[] = Particle;
+export const move = System.create({ components: { with: [...Particle] } }, row => { row[position] += row[velocity]; });
+export const read = System.create({ observer: true, components: { with: [...Particle] } }, row => { void row[velocity]; });
+
+// Declared without `as const`, a list's keys widen to `symbol`, which no list of components takes.
+const loose = [position, velocity];
+expectType<Equal<typeof loose, symbol[]>>();
+// @ts-expect-error so it's never a list of components
+export const looseList: readonly Component.Key[] = loose;
+// @ts-expect-error nor an index's
+export const byLoose = Index.create({ key: [position], components: { with: loose } });
+
+/** A list whose components are known only at runtime says so by its type. */
+const runtime: readonly (typeof position | typeof velocity)[] = Particle;
+
+export const spawn = System.create(({ commands }) => {
+    commands.spawn(Particle)({ [position]: 1, [velocity]: 2 });
+    // @ts-expect-error a tuple's values are required
+    commands.spawn(Particle)({ [position]: 1 });
+    commands.spawn([position, velocity])({ [position]: 1, [velocity]: 2 });
+    // @ts-expect-error a list declared without `as const` can't be spawned
+    commands.spawn(loose);
+    // @ts-expect-error nor added
+    commands.add(Entity.none, loose, {});
+    // A runtime list takes any of its values.
+    commands.spawn(runtime)({ [position]: 1 });
+    commands.add(Entity.none, Particle, { [position]: 1, [velocity]: 2 });
+    // @ts-expect-error a resource is never in a list of components
+    commands.spawn([position, scale]);
+});

package/src/interface/system/name.ts

@@ -1,6 +1,7 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 /**
- * The label reports and errors give it, which needn't be unique: the value its constructor returns is its identity, so
- * separately written code can't collide by name. Namespacing it (`"physics/integrate"`) keeps labels short. Without
- * one, it's labeled by its binding and the id the plugin gave it, or else by its kind numbered.
+ * The label errors give it, for display: its binding, from the id the plugin gave it; for one made in a
+ * function, the binding or function the plugin found it in; else its kind numbered. The value its constructor returns
+ * is its identity, so labels needn't be unique.
  */
 export type Name = string;

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

@@ -0,0 +1,51 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Entity } from '../entity/entity.js';
+import { System } from './system.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("optionalTest/position");
+const velocity = Symbol("optionalTest/velocity");
+const pilot = Symbol("optionalTest/pilot");
+
+declare module '@adobe/ecs' {
+    export interface Components {
+        [position]: { type: number };
+        [velocity]: { type: number };
+        [pilot]: { type: Entity; reference: "owner" };
+    }
+}
+
+// An optional component is its value, or undefined where an entity lacks it.
+System.create({ components: { with: [position], optional: [velocity, pilot] } }, row => {
+    check<Equal<typeof row[typeof velocity], number | undefined>>();
+    const speed = row[velocity];
+    if (speed !== undefined) row[position] += speed;
+    row[velocity] = 2;
+    // @ts-expect-error a reference is read-only in a row, optional or not
+    row[pilot] = Entity.none;
+});
+
+// A CPU kernel reads them as a body run as written does; GPU kernels don't read components an archetype may lack yet.
+System.create({ kernel: true, components: { with: [position], optional: [velocity] } }, row => { void row[velocity]; });
+System.create({
+    // @ts-expect-error a GPU kernel can't have optional components yet
+    kernel: "gpu",
+    components: { with: [position], optional: [velocity] },
+}, row => { void row[velocity]; });
+
+// An observer system reads its optional components and writes nothing.
+System.create({ observer: true, components: { with: [position], optional: [velocity] } }, row => {
+    void row[velocity];
+    // @ts-expect-error an observer system's row is read-only
+    row[velocity] = 1;
+});
+
+// A lookup by entity's optional component is its value, or undefined where the entity lacks it.
+System.create({ components: { with: [pilot] }, lookup: { pilots: { with: [position], optional: [velocity] } } }, (row, { lookup }) => {
+    const found = lookup.pilots(row[pilot]);
+    if (found === null) return;
+    check<Equal<typeof found[typeof position], number>>();
+    check<Equal<typeof found[typeof velocity], number | undefined>>();
+});

package/src/interface/system/property.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 
 export type Property<T, K extends PropertyKey> = T extends { readonly [P in K]?: infer V } ? V : undefined;