@adobe/ecs 0.1.0 → 0.2.1

package/src/interface/trait/types.ts

@@ -1,14 +1,15 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Component } from '../component/component.js';
 import type { Components } from '../component/types.js';
 import type { Entity } from '../entity/entity.js';
 import type { IsNode, IsTransferable } from '../platform/platform.js';
 import type { Resource } from '../resource/resource.js';
 import type { Reduction } from '../resource/reduction.js';
-import type { IsString, IsStruct } from '../schema/is-struct.js';
+import type { IsComparable, IsString, IsStruct } from '../schema/is-struct.js';
 import type { Thread } from '../thread/thread.js';
 
 /** The value type of the component or resource `N`. */
-type ValueOf<N> = N extends Component.Key ? Component.Value<N> : N extends Resource.Key ? Resource.Value<N> : never;
+type ValueOf<N> = N extends Component.Key ? Component<N> : N extends Resource.Key ? Resource<N> : never;
 
 /**
  * Whether each component's and resource's value is a struct, `"string"` for a string, computed once so a check is a
@@ -19,15 +20,16 @@ type Structs = { readonly [K in Component.Key | Resource.Key as K]: IsString<Val
 
 /**
  * The value each trait allows on the component or resource `N`. Augment it, with this exact type parameter, to
- * define a trait, and register its name with `Trait.register`. A trait that doesn't apply to `N` resolves to `never`.
+ * define a trait, keyed by a `Symbol()` constant of the same module, which the build registers. A trait that doesn't
+ * apply to `N` resolves to `never`.
  * An allowed value may look at `N`'s own traits and at the one component a declared value names, never map over
  * every component, or checking grows with the square of the component count.
  */
 export interface Traits<N extends Component.Key | Resource.Key> {
     /** The value type: declared as a TypeScript type, registered as a schema for it when it's data. */
     readonly type: unknown;
-    /** Present only while a rule deriving it matches, so commands never add or remove it. */
-    readonly derived: N extends Component.Key ? true : never;
+    /** Present only while a rule deriving it matches, so commands never add or remove it. Not on a shared component. */
+    readonly derived: N extends Component.Key ? Components[N] extends { readonly shared: true } ? never : true : never;
     /** Exists only while its host component does, and is removed with it. Not on a derived component, which its rule covers. */
     readonly within: N extends Component.Key
         ? Components[N] extends { readonly derived: true } | { readonly within: N } ? never : Component.Key
@@ -37,20 +39,31 @@ export interface Traits<N extends Component.Key | Resource.Key> {
      * component. Not on a derived component, whose target only a command could set.
      */
     readonly reference: N extends Component.Key
-        ? Components[N] extends { readonly derived: true } ? never : [Component.Value<N>] extends [Entity] ? "owner" | "weak" : never
+        ? Components[N] extends { readonly derived: true } | { readonly shared: true } ? never : [Component<N>] extends [Entity] ? "owner" | "weak" : never
         : never;
     /**
      * On a resource, the operator systems reduce into it with: each run that a contributor runs in starts it at the
      * operator's identity and leaves it holding the fold of every contribution. Booleans fold bitwise.
      */
     readonly reduce: N extends Resource.Key
-        ? [Resource.Value<N>] extends [boolean] ? "&" | "|" | "^" : Structs[N] extends true ? Reduction : never
+        ? [Resource<N>] extends [boolean] ? "&" | "|" | "^" : Structs[N] extends true ? Reduction : never
         : never;
     /**
      * The logical thread an object lives on, `"world"` without it. Not on a struct or a string, which live in shared
      * memory. A DOM `Node` lives on `"main"`, and says so.
      */
-    readonly thread: Structs[N] extends true | "string" ? never : IsNode<ValueOf<N>> extends true ? "main" : Thread;
+    readonly thread: Structs[N] extends true | "string" ? never
+        : N extends Component.Key ? Components[N] extends { readonly shared: true } ? never : IsNode<ValueOf<N>> extends true ? "main" : Thread
+        : IsNode<ValueOf<N>> extends true ? "main" : Thread;
     /** The value may be moved, never copied, to its thread: only a Transferable value. */
     readonly transfer: IsTransferable<ValueOf<N>> extends true ? true : never;
+    /**
+     * On a component of comparable data (numbers, booleans, strings, arrays and plain objects of those): each archetype
+     * holds one value of it for every entity it holds, so entities of equal values share an archetype. Rows read it as
+     * their archetype's value; `commands.add` with another value moves the entity. Not on a derived component or a
+     * reference, and it has no thread: every thread reads it.
+     */
+    readonly shared: N extends Component.Key
+        ? Components[N] extends { readonly derived: true } | { readonly reference: unknown } ? never : IsComparable<Component<N>> extends true ? true : never
+        : never;
 }

package/src/interface/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "../../../data/tsconfig-base.json",
+  "extends": "../../tsconfig.base.json",
   "compilerOptions": {
     "rootDir": ".",
     "outDir": "../../dist/interface",

package/src/interface/world/create.ts

@@ -1,15 +1,18 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Resource } from '../resource/resource.js';
 import type { WorldWritten } from '../resource/written.js';
+import type { InvalidDeclarations } from './declarations.js';
 import type { World } from './world.js';
 
 /** Values resources start at in place of their defaults: any but those only the world writes. */
-export type InitialResources = { readonly [K in Exclude<Resource.Key, WorldWritten>]?: Resource.Value<K> };
+export type InitialResources = { readonly [K in Exclude<Resource.Key, WorldWritten>]?: Resource<K> };
 
 /**
- * Creates a world on this thread, synchronously, with resources starting at the given values in place of their
- * defaults. This thread is its `"world"` thread for the world's life: it runs the sync points, the ticks and the GPU
- * device, and fills every logical thread no joined thread claims. Keys are the resources' symbols, built-in ones
- * included (`{ [workers]: 0 }`); string keys are never a resource's, so they're ignored. Throws for a symbol that isn't
- * a resource, or is one only the world writes.
+ * The type of `World.create`.
+ * @inline
  */
-export type Create = (resources?: InitialResources) => World;
+export type Create = (
+    // Unknown while every declaration holds; else what a call's `this` can't be, so the call reports it, printed whole.
+    this: [InvalidDeclarations] extends [never] ? unknown : { readonly "declarations don't hold": { readonly [D in InvalidDeclarations as D["key"]]: D["members"] } },
+    resources?: InitialResources,
+) => World;

package/src/interface/world/declarations.ts

@@ -0,0 +1,34 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Component } from '../component/component.js';
+import type { Components } from '../component/types.js';
+import type { Resource } from '../resource/resource.js';
+import type { Resources } from '../resource/types.js';
+import type { Key as TraitKey } from '../trait/key.js';
+import type { Traits } from '../trait/types.js';
+
+/**
+ * The members of key `K`'s declaration `Entry` that don't hold: a trait whose value `Traits<K>` doesn't allow, a name
+ * that isn't a trait, and a `default` that isn't of the declared type. Checks only `K`'s own traits, so the whole check
+ * is linear in the declarations.
+ */
+type Invalid<K extends Component.Key | Resource.Key, Entry, Value> =
+    | { readonly [T in Exclude<keyof Entry, "type" | "default">]-?: T extends TraitKey ? ([Entry[T]] extends [Traits<K>[T]] ? never : T) : T }[Exclude<keyof Entry, "type" | "default">]
+    | (Entry extends { readonly default: infer D } ? ([D] extends [Value] ? never : "default") : never);
+
+/**
+ * Key `K` with what's wrong with each member that doesn't hold, keyed by member so an error prints a trait by its
+ * key's binding; written in place, as an alias would print by its name.
+ */
+type Reported<K, Members extends PropertyKey> = [Members] extends [never] ? never : {
+    readonly key: K;
+    readonly members: { readonly [M in Members]: M extends "default" ? "isn't of the declared type" : M extends TraitKey ? "isn't allowed on this key" : "isn't a trait" };
+};
+
+/**
+ * Every declaration in `Components` and `Resources` with members that don't hold, each as its key and what's wrong
+ * with those members; `never` when all hold. The build registers declarations without a type checker, so
+ * `World.create` reports these.
+ */
+export type InvalidDeclarations =
+    | { readonly [K in Component.Key]: Reported<K, Invalid<K, Components[K], Component<K>>> }[Component.Key]
+    | { readonly [K in Resource.Key]: Reported<K, Invalid<K, Resources[K], Resource<K>>> }[Resource.Key];

package/src/interface/world/filter.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 
 export type Comparison<T> = {
     readonly "=="?: T;

package/src/interface/world/index.ts

@@ -1,2 +1,3 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 // The `World` namespace's members: none, since a consumer declares nothing more with it.
 export {};

package/src/interface/world/join.ts

@@ -1,10 +1,9 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Thread } from '../thread/thread.js';
 import type { World } from './world.js';
 
 /**
- * Joins, from another thread, a world that `share` let join through the other end of `port`, claiming the logical
- * `threads` this thread fills: their objects live here, and the systems and finalizers reading them run here. The world
- * it returns is the same one: its `run` runs systems there, and its `add` and `remove` take observer systems, which run
- * here after the world's sync points. Its `dispose` disconnects this thread.
+ * The type of `World.join`.
+ * @inline
  */
-export type Join = (port: Parameters<World["share"]>[0], options?: { readonly threads?: readonly Exclude<Thread, "world">[] }) => World;
+export type Join = (port: Parameters<World["share"]>[0], options?: { readonly threads?: readonly Exclude<Thread, "world">[] }) => Promise<World>;

package/src/interface/world/loop.type-test.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import {
     Finalizer, System, always, cadence, clock, gpuDevice, wake, workers,
     type Component, type Resource, type World,
@@ -24,14 +25,14 @@ world.remove(move);
 void removed;
 
 // Built-in resources.
-check<Equal<Resource.Value<typeof gpuDevice>, GPUDevice | null>>();
-check<Equal<Resource.Value<typeof workers>, number | null>>();
+check<Equal<Resource<typeof gpuDevice>, GPUDevice | null>>();
+check<Equal<Resource<typeof workers>, number | null>>();
 // null is the platform's choice of pool size.
 export const platformPool: World = create({ [workers]: null });
-check<Equal<Resource.Value<typeof always>, boolean>>();
-check<Equal<Resource.Value<typeof wake>, number>>();
-check<Equal<Resource.Value<typeof clock>, { readonly now: number; readonly delta: number; readonly tick: number }>>();
-check<Equal<Resource.Value<typeof cadence>, { readonly kind: "frame" } | { readonly kind: "fixed"; readonly step: number; readonly maxSteps?: number }>>();
+check<Equal<Resource<typeof always>, boolean>>();
+check<Equal<Resource<typeof wake>, number>>();
+check<Equal<Resource<typeof clock>, { readonly now: number; readonly delta: number; readonly tick: number }>>();
+check<Equal<Resource<typeof cadence>, { readonly kind: "frame" } | { readonly kind: "fixed"; readonly step: number; readonly maxSteps?: number }>>();
 // Built-in resources are symbols, so worlds start them at other values through their imported keys.
 check<Equal<[typeof gpuDevice, typeof workers, typeof cadence, typeof always, typeof wake, typeof clock] extends readonly symbol[] ? true : false, true>>();
 // @ts-expect-error a resource key is its imported symbol, never its description
@@ -42,23 +43,27 @@ type Removed = "component" | "persistent" | "shared" | "threadPort" | "threadSta
 check<Equal<Extract<Removed, keyof typeof Ecs | Component.Key>, never>>();
 
 // Systems read the loop's state, ask for a wake time and change its cadence.
-System.create({ name: "loopTypeTest/read", resources: { read: [clock] } }, ({ resources }) => {
+System.create({}, ({ resources }) => {
     const now: number = resources[clock].now;
     void now;
 });
-System.create({ name: "loopTypeTest/pace", resources: { write: [cadence, always] } }, ({ resources }) => {
+System.create({}, ({ resources }) => {
     resources[cadence] = { kind: "fixed", step: 1000 / 60, maxSteps: 2 };
     resources[always] = true;
 });
-System.create({ name: "loopTypeTest/sleep", reduce: { [wake]: "min" } }, ({ reduce }) => { reduce[wake](1000); });
-// @ts-expect-error clock is written only by the world
-System.create({ name: "loopTypeTest/clock", resources: { write: [clock] } }, () => {});
-// @ts-expect-error wake is reduced, never written
-System.create({ name: "loopTypeTest/wake", resources: { write: [wake] } }, () => {});
-// @ts-expect-error a finalizer doesn't write clock either
-Finalizer.create({ name: "loopTypeTest/finalizeClock", components: {}, resources: { write: [clock] } }, () => {});
+System.create({}, ({ reduce }) => { reduce[wake](1000); });
+System.create({}, ({ resources }) => {
+    // @ts-expect-error clock is written only by the world
+    resources[clock] = resources[clock];
+    // @ts-expect-error wake is reduced, never written
+    resources[wake] = 0;
+});
+Finalizer.create({ components: {} }, (_row, { resources }) => {
+    // @ts-expect-error a finalizer doesn't write clock either
+    resources[clock] = resources[clock];
+});
 // @ts-expect-error a cadence is a frame or a fixed step
-System.create({ name: "loopTypeTest/badCadence", resources: { write: [cadence] } }, ({ resources }) => { resources[cadence] = { kind: "fixed" }; });
+System.create({}, ({ resources }) => { resources[cadence] = { kind: "fixed" }; });
 
 // Worlds start the loop's settings at other values; clock is the world's own.
 const paced: World = create({ [cadence]: { kind: "fixed", step: 10 }, [always]: true, [workers]: 2 });

package/src/interface/world/run.type-test.ts

@@ -0,0 +1,87 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type * as Ecs from '../index.js';
+import { gpuDevice } from '../resources/gpu-device.js';
+import { System } from '../system/system.js';
+import { integrate, main, move, position, time, watchTime } from '../system/system.type-test.js';
+import type { World } from './world.js';
+
+type Equal<X, Y> = (<T>() => T extends X ? 1 : 2) extends (<T>() => T extends Y ? 1 : 2) ? true : false;
+const check = <_T extends true>() => { };
+
+declare const world: World;
+declare const ecs: typeof Ecs;
+
+const frames = Symbol("runTypeTest/frames");
+declare module '@adobe/ecs' {
+    export interface Resources {
+        [frames]: { type: number };
+    }
+}
+
+// A run resolves to its per-run body's value: a one-off read is an observer system returning it.
+const count = System.create({ observer: true }, ({ resources }) => resources[frames]);
+check<Equal<typeof count, System<undefined, number>>>();
+const counted: Promise<number> = world.run(count);
+// @ts-expect-error a run of it resolves to a number
+const notText: Promise<string> = world.run(count);
+
+// A system that declares nothing, and one taking input, resolve to what their bodies return.
+const next = System.create(({ resources }) => resources[frames] + 1);
+const nextValue: Promise<number> = world.run(next);
+const scaled = System.create({}, ({ resources }, input: { readonly by: number }) => ({ scaled: resources[frames] * input.by }));
+const scaledValue: Promise<{ scaled: number }> = world.run(scaled, { by: 2 });
+
+// A body that may be skipped, as one whose conditions or resource change filters can fail, may give undefined.
+const changedFrames = System.create({ observer: true, resources: { changed: [frames] } }, ({ resources }) => resources[frames]);
+check<Equal<typeof changedFrames, System<undefined, number | undefined>>>();
+const whileDevice = System.create({ resources: { is: [gpuDevice] } }, () => "drawn");
+const drawn: Promise<string | undefined> = world.run(whileDevice);
+
+// Row systems, composites, render systems and bodies returning nothing resolve to nothing.
+const rows: Promise<void> = world.run(integrate);
+const composite: Promise<void> = world.run(main);
+const input: Promise<void> = world.run(move, { distance: 1 });
+const nothing: Promise<void> = world.run(watchTime);
+const valuedRows = System.create({ components: { with: [position] } }, row => row[position]);
+check<Equal<typeof valuedRows, System>>();
+check<Equal<typeof main, System>>();
+check<Equal<typeof watchTime, System>>();
+const drawing = System.render({ shader: { accessors: { place: position } } }, () => {});
+check<Equal<typeof drawing, System>>();
+
+// What a body returns doesn't change where a system goes: composites and constraints take it, and so do ticks.
+const reads = System.create([count, integrate]);
+check<Equal<typeof reads, System>>();
+System.create({ after: [count] }, () => {});
+world.add(count);
+world.add(next);
+
+// A run that fails rejects with an Error naming what failed; nothing else describes a run, so there's no Report.
+// @ts-expect-error runs give their body's value and reject with what failed: no Report
+void ecs.Report;
+// @ts-expect-error no run numbers
+const numbered: Promise<number> = world.run(main);
+
+void [counted, notText, nextValue, scaledValue, drawn, rows, composite, input, nothing, numbered, time];
+
+// A body returns no promise: it starts the work, and a later run finishes it.
+// @ts-expect-error a body returns no promise
+System.create(() => Promise.resolve(1));
+// @ts-expect-error a body returns no promise
+System.create({ observer: true }, () => Promise.resolve(1));
+// @ts-expect-error a body returns no promise, a row system's neither
+System.create({ components: { with: [position] } }, () => Promise.resolve());
+// @ts-expect-error a body returns no promise, a render system's neither
+System.render({ shader: { accessors: { place: position } } }, () => Promise.resolve());
+const thenable: PromiseLike<number> = Promise.resolve(1);
+// @ts-expect-error nor any PromiseLike
+System.create(() => thenable);
+// @ts-expect-error nor a return type wide enough to hide one, unknown
+System.create((): unknown => Promise.resolve(1));
+// @ts-expect-error or object
+System.create((): object => Promise.resolve(1));
+// @ts-expect-error a row body's neither
+System.create({ components: { with: [position] } }, (): unknown => Promise.resolve());
+// Values of other types are a body's to return.
+System.create(() => ({}));
+System.create((): { readonly then?: never } => ({}));

package/src/interface/world/share.type-test.ts

@@ -1,11 +1,17 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { World } from './world.js';
 
+type Equal<X, Y> = (<T>() => T extends X ? 1 : 2) extends (<T>() => T extends Y ? 1 : 2) ? true : false;
+const check = <_T extends true>() => { };
+
 declare const world: World;
 declare const channel: MessageChannel;
 declare const worker: Worker;
 
-// Sharing lets another thread join through a port: a MessagePort, a Worker or a worker's own scope.
-const shared: void = world.share(channel.port1);
+// Sharing lets another thread join through a port: a MessagePort, a Worker or a worker's own scope. It resolves once
+// that thread has joined, to nothing.
+const shared: Promise<void> = world.share(channel.port1);
+check<Equal<ReturnType<World["share"]>, Promise<void>>>();
 world.share(worker);
 world.share(self);
 // A port is share's parameter, inferred where a consumer names it.

package/src/interface/world/world.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Input } from '../system/input.js';
 import type { System } from '../system/system.js';
 
@@ -8,25 +9,33 @@ import type { System } from '../system/system.js';
 export type World = {
     /**
      * The one way to change state. Runs are sequential in call order; physically, any that don't conflict overlap. Each
-     * runs a system or composite, ending in a sync point, and resolves to its number: every run and tick takes the
-     * next, in the order they run. What went wrong, if anything, is a report the world spawns for that number (see
-     * `Report`): systems, finalizers and GPU work that failed, systems skipped after a failed tier, commands that did
-     * nothing, and warnings. Rejects only when the run can't happen or finish: registration fails, the world is
-     * disposed, its GPU device is lost, or its sync point can't apply a command's value. Observer systems, the run's and
-     * those added, run after its sync point and its report, before it resolves; their throws are `"system"` failures
-     * in the next run's report, since each report's errors are written once. A run of observer systems alone runs them
-     * once after an empty sync point, and doesn't wake the loop.
+     * runs a system or composite, ending in a sync point, then observer systems, the run's and those added, and
+     * resolves to what a per-run body returns: a system without components resolves to its body's value, or
+     * `undefined` when its body was skipped, and any other system or composite to nothing. So a one-off read is a run
+     * of an observer system returning what it read; one that runs on a joined thread, as it reads objects there, runs
+     * there before the run resolves, to its value as structured clone. A run of observer systems alone runs them once
+     * after an empty sync point, and doesn't wake the loop.
+     *
+     * When a system or finalizer of the run fails, later tiers are skipped, the sync point still applies what was done,
+     * and once its observer systems ran the run rejects with an `Error` naming each failure, its system's label and id,
+     * message and cause. It rejects too when the run can't happen or finish: registration fails, the world is disposed,
+     * its GPU device is lost, or its sync point can't apply a command's value. What fails after it, an observer system
+     * added or GPU work, is reported out of band, as ticks' failures are (see `add`).
      */
-    run<I>(system: System<I>, ...input: Input<NoInfer<I>>): Promise<number>;
+    run<I, R>(system: System<I, R>, ...input: Input<NoInfer<I>>): Promise<R>;
     /**
      * Adds a system to every tick, from the next one on, ordered with those already added by its constraints, as a
      * composite's members are. A tick runs on a beat of the `cadence` resource where `always` is set, `wake` is due or
      * a run arrived since the last tick, and only while some system is added. Throws for a system with no ordering path
-     * to one already added that conflicts with it; failures are in the tick's report. An observer system runs after
-     * every run's and tick's sync point instead. It never conflicts and doesn't count as an added system for ticking.
-     * On a joined thread `add` takes only observer systems, whose keys need ids: each runs on that thread after the
-     * world's sync points, once for the newest when the thread fell behind, reading structs and the objects of the
-     * threads it fills as of one sync point; its failures are in a later run's report.
+     * to one already added that conflicts with it. An observer system runs after every run's and tick's sync point
+     * instead. It never conflicts and doesn't count as an added system for ticking. On a joined thread `add` takes only
+     * observer systems, whose keys need ids: each runs on that thread after the world's sync points, once for the
+     * newest when the thread fell behind, reading structs and the objects of the threads it fills as of one sync point.
+     *
+     * What added systems throw, and what fails in ticks, is reported out of band on the world's thread, as an `Error`
+     * naming what failed with what it threw as its cause: through `reportError` where the platform has it, as browsers
+     * and their workers do, and otherwise thrown from a task of its own, an uncaught exception, as in node. A system is
+     * reported once while it keeps failing, and again once it has run without failing since.
      */
     add(system: System<void>): void;
     /**
@@ -40,13 +49,19 @@ export type World = {
     /**
      * Lets another thread join this world through `port`, one end of a channel to it, of the browser or node: a
      * `MessagePort`, a `Worker`, or a worker's own scope, `self` or node's `parentPort`. That thread joins through the
-     * other end, claiming the logical threads it fills; a thread claimed twice can't join. Throws on a joined thread,
-     * and where memory can't be shared, as without cross-origin isolation.
+     * other end, claiming the logical threads it fills. Resolves once it has joined: the threads it claims are its own,
+     * and the observer systems it added as its join resolved, before awaiting anything else, are added, so a run
+     * started afterwards runs on it and reaches them; one it adds later reaches the runs after its add arrived.
+     * Rejects with an `Error` saying why it didn't join: the world refused its claim, as of a thread claimed twice, the
+     * world was disposed, the port is shared already, or that thread ended first, as the platform reports it: a
+     * `Worker` failing to start or throwing first, a node worker exiting, a port closed, or, once that thread asked to
+     * join, its end however it came. A browser worker ended before it asked to join isn't reported, so its share stays
+     * pending. Rejects too on a joined thread, and where memory can't be shared, as without cross-origin isolation.
      */
     share(port: { readonly postMessage: (message: never, transfer: never) => void } & (
         | { readonly addEventListener: (type: "message", listener: (event: unknown) => void) => void }
         | { readonly on: (event: "message", listener: (value: unknown) => void) => unknown }
-    )): void;
+    )): Promise<void>;
     /**
      * Waits for pending runs, then stops ticking and releases memory, and joined threads' runs reject; the world is
      * unusable afterwards. On a joined thread, it disconnects this thread.

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

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { Component } from '../component/component.js';
 import type { Entity } from '../entity/entity.js';
 import { System } from '../system/system.js';
@@ -22,9 +23,6 @@ declare module '@adobe/ecs' {
         [shared]: { type: true };
     }
 }
-Component.register(point, { type: { type: "object", properties: { x: { type: "number" } } } });
-Component.register(persistent, { type: { const: true } });
-Component.register(shared, { type: { const: true } });
 // Reading goes through observer systems: a world has no observers, and no synchronous reads.
 // @ts-expect-error no observe: observer systems read a world
 void world.observe;
@@ -37,9 +35,9 @@ void world.synchronize;
 // @ts-expect-error no World.Query: observer systems declare what they read
 export type NoQuery = World.Query<[typeof persistent]>;
 
-// A run resolves to its number; what went wrong is in its report (`Report`).
-const ran: Promise<number> = world.run(main);
-const moved: Promise<number> = world.run(move, { distance: 1 });
+// A run resolves to its per-run body's value, here nothing (see `run.type-test.ts`), and rejects when a system failed.
+const ran: Promise<void> = world.run(main);
+const moved: Promise<void> = world.run(move, { distance: 1 });
 // @ts-expect-error a system with input needs it
 world.run(move);
 // @ts-expect-error input must match its schema
@@ -70,12 +68,10 @@ check<Equal<ReturnType<Create>, World>>();
 export type Created = World.Create;
 // @ts-expect-error no World.InitialResources: Parameters<typeof createWorld>[0]
 export type Initial = World.InitialResources;
-// @ts-expect-error no World.Failure: Report.Failure
+// @ts-expect-error no World.Failure: a failed run rejects with an Error
 export type Failed = World.Failure;
-// @ts-expect-error no World.Warning: Report.Warning
-export type Warned = World.Warning;
 
 // An observer system is added to every run and tick, or run once after an empty sync point.
 const addedObserver: void = world.add(watchTime);
-const ranObserver: Promise<number> = world.run(watchTime);
+const ranObserver: Promise<void> = world.run(watchTime);
 void [addedObserver, ranObserver];

package/src/observe/compare.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 // Comparing and testing component values for queries: equality, order, and `where` conditions compiled once.
 
 /** Whether two values are equal: primitives by identity, objects and arrays by their own keys, recursively. */

package/src/observe/entity.ts

@@ -1,6 +1,7 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { Index, System, type Component, type Entity, type World } from '../interface/index.js';
 import type { Observe } from './observe.js';
-import { createEntry, give, giveFirst, keysId, labelOf, none, noDelivery, ownName, passed, scheduleDelivery, scheduleRead, stateOf, subscribe, sweepSubscribers, throwFailed, type Entry, type Read, type Shape, type WorldState } from './world-state.js';
+import { createEntry, give, giveFirst, keysId, labelOf, labelled, none, noDelivery, passed, scheduleDelivery, scheduleRead, stateOf, subscribe, sweepSubscribers, throwFailed, type Entry, type Read, type Shape, type WorldState } from './world-state.js';
 
 /** An observed entity's value, shared by its observers, and by optional component whether it had it last. */
 type EntityEntry = Entry<object | null> & { readonly entity: Entity; readonly present: boolean[] };
@@ -26,12 +27,12 @@ type EntityShape = Shape & {
 const shapes = new WeakMap<WorldState, Map<string, EntityShape>>();
 
 /** Indexes of the entities with every component of a list, by its id: one per list in the program. */
-const memberIndexes = new Map<string, Index<{ readonly key: readonly []; readonly components: { readonly has: readonly Component.Key[] } }>>();
+const memberIndexes = new Map<string, Index<{ readonly key: readonly []; readonly components: { readonly with: readonly Component.Key[] } }>>();
 
 const membersOf = (required: readonly Component.Key[]) => {
     const id = keysId(required);
     let index = memberIndexes.get(id);
-    if (index === undefined) memberIndexes.set(id, index = Index.create({ name: `Observe.entity(${labelOf(required)})`, key: [], components: { has: [...required] } }));
+    if (index === undefined) memberIndexes.set(id, index = Index.create(labelled({ key: [], components: { with: [...required] } }, `Observe.entity(${labelOf(required)})`)));
     return index;
 };
 
@@ -49,7 +50,7 @@ type Finders = {
 };
 
 const createShape = (state: WorldState, byShape: Map<string, EntityShape>, id: string, required: readonly Component.Key[], optional: readonly Component.Key[]): EntityShape => {
-    const name = ownName(`Observe.entity(${labelOf(required)}${optional.length === 0 ? "" : `; ${labelOf(optional)}`})`);
+    const name = `Observe.entity(${labelOf(required)}${optional.length === 0 ? "" : `; ${labelOf(optional)}`})`;
     const rows: (LookupRow | null)[] = optional.map(() => null);
     /**
      * Reads an entry's entity, giving its value if it changed and first values to subscribers waiting up to `through`:
@@ -128,14 +129,14 @@ const createShape = (state: WorldState, byShape: Map<string, EntityShape>, id: s
     let finders: Finders | null = null;
     let source: object | null = null;
     const system = optional.length === 0
-        ? System.create({ name, observer: true, lookup: { presence: { has: required, changed: required }, values: { read: required }, members: { index: membersOf(required), changed: required } } }, ({ lookup }) => {
+        ? System.create(labelled({ observer: true, lookup: { presence: { with: required, changed: required }, values: { with: required }, members: { index: membersOf(required), changed: required } } }, name, { lookup: { values: required } }), ({ lookup }) => {
             if (source !== lookup || finders === null) {
                 source = lookup;
                 finders = { presence: lookup.presence, values: lookup.values, optional: noOptional };
             }
             pass(lookup.members().changed, finders);
         })
-        : System.create({ name, observer: true, lookup: optionalLookups(required, optional) }, ({ lookup }) => {
+        : System.create(labelled({ observer: true, lookup: optionalLookups(required, optional) }, name, { lookup: optionalReads(required, optional) }), ({ lookup }) => {
             if (source !== lookup || finders === null) {
                 source = lookup;
                 finders = { presence: lookup.presence, values: lookup.values, optional: (index, entity) => lookup[index](entity) };
@@ -172,22 +173,29 @@ const createShape = (state: WorldState, byShape: Map<string, EntityShape>, id: s
 
 const noOptional = (): null => null;
 
-type Watched = { readonly read: readonly Component.Key[]; readonly changed: readonly Component.Key[] };
+type Watched = { readonly with: readonly Component.Key[]; readonly changed: readonly Component.Key[] };
 
 /** Lookups of an entity's required components, whether and what, and one of each optional one, by its position. */
 const optionalLookups = (required: readonly Component.Key[], optional: readonly Component.Key[]): {
-    readonly presence: { readonly has: readonly Component.Key[]; readonly changed: readonly Component.Key[] };
-    readonly values: { readonly read: readonly Component.Key[] };
+    readonly presence: { readonly with: readonly Component.Key[]; readonly changed: readonly Component.Key[] };
+    readonly values: { readonly with: readonly Component.Key[] };
     readonly [index: number]: Watched;
 } => {
-    const lookups: { presence: { readonly has: readonly Component.Key[]; readonly changed: readonly Component.Key[] }; values: { readonly read: readonly Component.Key[] }; [index: number]: Watched } = {
-        presence: { has: required, changed: required },
-        values: { read: required },
+    const lookups: { presence: { readonly with: readonly Component.Key[]; readonly changed: readonly Component.Key[] }; values: { readonly with: readonly Component.Key[] }; [index: number]: Watched } = {
+        presence: { with: required, changed: required },
+        values: { with: required },
     };
-    for (let i = 0; i < optional.length; i++) lookups[i] = { read: [optional[i]], changed: [optional[i]] };
+    for (let i = 0; i < optional.length; i++) lookups[i] = { with: [optional[i]], changed: [optional[i]] };
     return lookups;
 };
 
+/** What the optional shape's body reads of its lookups' rows: the required values, and each optional one. */
+const optionalReads = (required: readonly Component.Key[], optional: readonly Component.Key[]): { readonly [name: string]: readonly Component.Key[] } => {
+    const reads: { [name: string]: readonly Component.Key[] } = { values: required };
+    for (let i = 0; i < optional.length; i++) reads[i] = [optional[i]];
+    return reads;
+};
+
 export const observeEntity = <T>(world: World, entity: Entity, components: { readonly required?: readonly Component.Key[]; readonly optional?: readonly Component.Key[] }): Observe<T | null> => {
     const required = [...components.required ?? []];
     const optional = [...components.optional ?? []];

package/src/observe/index.ts

@@ -1 +1,2 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 export { Observe } from './observe.js';

package/src/observe/members.ts

@@ -1,10 +1,11 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Component, Components, Entity, Resource, World } from '../interface/index.js';
 import { observeEntity } from './entity.js';
 import type { Observe } from './observe.js';
 import { observeCount, observeSelect } from './select.js';
 import type { Query } from './query.js';
 import { observeResource } from './resource.js';
-import type { ReadonlyResourceValue, ReadonlyValue } from './values.js';
+import type { ReadonlyResourceType, ReadonlyType } from './values.js';
 
 export { toPromise } from './to-promise.js';
 export type { Query } from './query.js';
@@ -13,7 +14,7 @@ export type { Query } from './query.js';
  * A resource's value, then a new one after each run or tick that changed it: one whose sync point stamped it, even with
  * the same value, a reduced resource when its fold differs.
  */
-export const resource = <R extends Resource.Key>(world: World, resource: R): Observe<ReadonlyResourceValue<R>> =>
+export const resource = <R extends Resource.Key>(world: World, resource: R): Observe<ReadonlyResourceType<R>> =>
     observeResource(world, resource);
 
 /**
@@ -26,7 +27,7 @@ export const entity = <const R extends readonly Component.Key[] = [], const O ex
     world: World,
     entity: Entity,
     components: { readonly required?: R; readonly optional?: O },
-): Observe<({ readonly [K in keyof Pick<Components, R[number]>]: ReadonlyValue<K> } & { readonly [K in keyof Pick<Components, O[number]>]?: ReadonlyValue<K> }) | null> =>
+): Observe<({ readonly [K in keyof Pick<Components, R[number]>]: ReadonlyType<K> } & { readonly [K in keyof Pick<Components, O[number]>]?: ReadonlyType<K> }) | null> =>
     observeEntity(world, entity, components);
 
 /**

package/src/observe/observe.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 /**
  * Observes a sequence of values: `notify` is called zero or more times, possibly during the call that subscribes,
  * possibly later; an observer mustn't depend on either. Returns the function that stops it.

package/src/observe/observe.type-test.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { Component, Resource, type Entity, type World } from '../interface/index.js';
 import { Observe } from './index.js';
 
@@ -21,10 +22,6 @@ declare module '@adobe/ecs' {
         [time]: { type: number };
     }
 }
-Component.register(point, { type: { type: "object", properties: { x: { type: "number" } } } });
-Component.register(persistent, { type: { const: true } });
-Component.register(shared, { type: { const: true } });
-Resource.register(time, { type: { type: "number", default: 0 } });
 
 // The module's `Observe` has the shape of the package root's.
 check<Equal<Observe<number>, (notify: (value: number) => void) => () => void>>();