@adobe/ecs 0.1.0 → 0.2.0

package/src/interface/world/create.ts

@@ -1,5 +1,7 @@
+// © 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. */
@@ -10,6 +12,11 @@ export type InitialResources = { readonly [K in Exclude<Resource.Key, WorldWritt
  * 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.
+ * a resource, or is one only the world writes. While a declaration's trait or default doesn't hold, each call fails to
+ * compile, once, naming each such key, its members and what's wrong with them.
  */
-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.Value<K>>> }[Component.Key]
+    | { readonly [K in Resource.Key]: Reported<K, Invalid<K, Resources[K], Resource.Value<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,17 @@
+// © 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.
+ * `threads` this thread fills: their objects live here, and the systems and finalizers reading them run here. Resolves,
+ * once the world accepted the claim, to the same world: its `run` runs systems there, and its `add` and `remove` take
+ * observer systems, which run here after the world's sync points. Add them before awaiting anything else, so the
+ * world's `share` resolves with them in place. Its `dispose` disconnects this thread. Rejects with an `Error` saying
+ * why it didn't join: the world refused the claim, was disposed, or its thread ended first, as the platform reports it:
+ * the world's `Worker` failing to start or throwing first, a port closed, as in node, or, in a browser, the world's
+ * thread ending once it was shared through a port this thread listened on. A browser world's worker that the page ended
+ * before this thread heard from it isn't reported, so the join stays pending. Rejects too where memory can't be shared,
+ * as without cross-origin isolation.
  */
-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,
@@ -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,3 +1,4 @@
+// © 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';

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>>();

package/src/observe/plans.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Component, Entity } from '../interface/index.js';
 import { compare, compareNumbers } from './compare.js';
 

package/src/observe/query.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Component } from '../interface/index.js';
 
 type Comparison<T> = {

package/src/observe/resource.ts

@@ -1,6 +1,7 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { System, type Resource, type World } from '../interface/index.js';
 import type { Observe } from './observe.js';
-import { createEntry, give, giveFirst, none, noDelivery, ownName, passed, scheduleRead, stateOf, subscribe, sweepSubscribers, throwFailed, type Entry, type Read, type Shape, type WorldState } from './world-state.js';
+import { createEntry, give, giveFirst, labelled, none, noDelivery, passed, scheduleRead, stateOf, subscribe, sweepSubscribers, throwFailed, type Entry, type Read, type Shape, type WorldState } from './world-state.js';
 
 /**
  * A resource's observers, sharing one value: `notifier`, added, gives the value after each pass whose sync point
@@ -27,17 +28,17 @@ const shapes = new WeakMap<WorldState, Map<Resource.Key, ResourceShape>>();
 
 const createShape = (state: WorldState, byKey: Map<Resource.Key, ResourceShape>, key: Resource.Key): ResourceShape => {
     const entry = createEntry<unknown>(undefined);
-    const label = ownName(`Observe.resource(${key.description ?? "?"})`);
+    const label = `Observe.resource(${key.description ?? "?"})`;
     // On a joined thread, first values come once a run of this system resolved, never in its pass: none to skip.
     const { joined } = state;
-    const notifier = System.create({ name: label, observer: true, resources: { read: [key], changed: [key] } }, ({ resources }) => {
+    const notifier = System.create(labelled({ observer: true, resources: { changed: [key] } }, label, { resources: [key] }), ({ resources }) => {
         passed(state);
         entry.value = resources[key];
         entry.valid = true;
         if (entry.stopped > 0) sweepSubscribers(entry);
         throwFailed(give(entry, 0, true, state.pass, joined ? -1 : state.pass, none));
     });
-    const reader = System.create({ name: label, observer: true, resources: { read: [key] } }, ({ resources }) => {
+    const reader = System.create(labelled({ observer: true }, label, { resources: [key] }), ({ resources }) => {
         const through = shape.called.shift() ?? 0;
         entry.value = resources[key];
         entry.valid = true;