@adobe/ecs 0.1.0 → 0.2.1

package/src/implementation/world/joined-observer.ts

@@ -1,6 +1,7 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Leaf } from '../../interface/system/leaf.js';
-import type { SystemLookup } from '../../interface/system/access.js';
-import { idOfItem, idOfKey, indexOfLookup, labelOf, labelOfItem, threadOf, watchedBy, watchesEntries } from '../../interface/registry/index.js';
+import type { SystemLookupLists } from '../../interface/system/access.js';
+import { idOfItem, idOfKey, idOrNull, indexOfLookup, labelOf, threadOf, watchedBy, watchesEntries } from '../../interface/registry/index.js';
 import type { Archetype } from './archetype.js';
 import { readCell } from './cells.js';
 import { indexOf } from './entities.js';
@@ -43,8 +44,18 @@ export const ranSkipped = 1;
 export const ranExecuted = 2;
 /** Set once the world removed the system, which the thread checks before it claims a post. */
 export const removedWord = observerLine + 2;
-/** The newest run of the joined thread the post is for, its sequence, or 0 for none. */
+/**
+ * The newest run of the joined thread the post is for, its sequence; `worldRun` for a run of the world's, which the
+ * thread gives what the post's body returned or threw; or 0 for none.
+ */
 export const runsWord = observerLine + 3;
+/** A runs word for a run of the world's that resolves to the post's body's value, and for one that doesn't. */
+export const worldRunValued = -1;
+export const worldRun = -2;
+/** What a post of `observer` writes in its runs word. */
+const owedWord = (observer: JoinedObserver): number => observer.pending === 0 ? observer.valued ? worldRunValued : worldRun : Math.max(observer.pending, 0);
+/** Whether a post that held `stored` in its runs word ran for run `pending`. */
+const ranFor = (stored: number, pending: number): boolean => pending === 0 ? stored < 0 : stored >= pending;
 /** The sync of the thread's log the post is as of, which its objects are replayed through first. */
 export const syncWord = observerLine + 4;
 /** From this f64 word of the block: the tick the post takes as its `lastRun` once it ran, then the `lastRun` it filters by. */
@@ -77,6 +88,8 @@ export type ObserverTarget = {
     /** By index there, what's placed; indexes it dropped, placed again first. */
     readonly placed: (JoinedObserver | undefined)[];
     readonly free: number[];
+    /** The ids of the systems the thread imported as it joined claiming threads, which those placed there by id must be among. */
+    readonly imported: ReadonlySet<string>;
 };
 
 /** A lookup through an index by an observer system on a joined thread, through a record the world writes before each post. */
@@ -87,11 +100,15 @@ export type JoinedObserver = Copied & {
     readonly target: ObserverTarget;
     readonly index: number;
     readonly label: string;
+    /** The id the plugin gave it, which failures give beside its label. */
+    readonly id: string | null;
     readonly runner: Runner;
     /** Struct components its lookups read or watch, and the key parts of the indexes they go through. */
     readonly lookupReads: readonly number[];
     readonly watched: readonly number[];
     readonly filtered: boolean;
+    /** Whether it has `where` and change filters, so it keeps a point per archetype there, which the world doesn't see. */
+    readonly pointed: boolean;
     readonly records: readonly Record[];
     readonly ticks: Float64Array;
     /** For one reading only struct resources, no rows or lookups: its posts' two places. */
@@ -105,6 +122,8 @@ export type JoinedObserver = Copied & {
     cancels: number;
     /** The newest run it's owed to, which it's posted for until it ran: 0 for one of the world's, -1 for none. */
     pending: number;
+    /** Whether the run of the world's it's owed to resolves to its body's value, which the thread then gives back. */
+    valued: boolean;
     stopped: boolean;
     /** Whether the thread dropped it, so its block can go once no post is live. */
     dropped: boolean;
@@ -157,20 +176,59 @@ export type ObserverState = {
     count: number;
     /** Posts again, between runs, what's owed to a run once a post was cancelled outside a sync point. */
     again: (() => void) | null;
+    /** By one owed to a run of the world's in progress, which waits for it: what settles that wait once it ran there. */
+    readonly waiting: Map<JoinedObserver, (result: PostResult) => void>;
 };
 
-export const createObserverState = (): ObserverState => ({ posts: [], pending: new Set(), targets: new Map(), proxies: new WeakMap(), count: 0, again: null });
+/** What a post owed to a run of the world's gave back: its body's value or what it threw; `gone` once its thread is. */
+export type PostResult = { readonly value: unknown; readonly error: unknown; readonly gone: boolean };
+
+export const createObserverState = (): ObserverState => ({ posts: [], pending: new Set(), targets: new Map(), proxies: new WeakMap(), count: 0, again: null, waiting: new Map() });
+
+const nothingThere: PostResult = { value: undefined, error: undefined, gone: false };
+
+/**
+ * Waits for a post of `observer` owed to the run of the world's in progress: once it ran there, with what its body
+ * returned or threw; once it's removed, with nothing; once its thread is gone, as gone.
+ */
+export const awaitPost = (state: State, observer: JoinedObserver, valued: boolean): Promise<PostResult> => {
+    if (observer.target.ended) return Promise.resolve(goneThere(observer));
+    if (observer.stopped) return Promise.resolve(nothingThere);
+    observer.valued = valued;
+    return new Promise(resolve => state.observer.waiting.set(observer, resolve));
+};
+
+const goneThere = (observer: JoinedObserver): PostResult =>
+    ({ value: undefined, error: new Error(`Thread "${observer.target.label}" is gone, so its systems don't run.`), gone: true });
+
+/** A post owed to a run of the world's ran there: what its body returned or threw settles the run's wait. */
+export const ranThere = (state: State, observer: JoinedObserver, value: unknown, error: unknown): void => {
+    const settle = state.observer.waiting.get(observer);
+    if (settle === undefined) return;
+    state.observer.waiting.delete(observer);
+    observer.valued = false;
+    settle({ value, error, gone: false });
+};
+
+/** Settles a run's wait for `observer` with `result`, if one waits. */
+const endWait = (state: State, observer: JoinedObserver, result: PostResult): void => {
+    const settle = state.observer.waiting.get(observer);
+    if (settle === undefined) return;
+    state.observer.waiting.delete(observer);
+    observer.valued = false;
+    settle(result);
+};
 
 /** A joined thread's end. */
-export const createObserverTarget = (thread: number, label: string, post: (message: ToJoined) => void, wake: () => void): ObserverTarget => {
+export const createObserverTarget = (thread: number, label: string, post: (message: ToJoined) => void, wake: () => void, imported: ReadonlySet<string>): ObserverTarget => {
     let finish = (): void => {};
     const end = new Promise<void>(resolve => { finish = resolve; });
-    return { thread, label, post, wake, log: null, ended: false, left: false, end, finish, placed: [], free: [] };
+    return { thread, label, post, wake, log: null, ended: false, left: false, end, finish, placed: [], free: [], imported };
 };
 
 const unique = (ids: readonly number[]): readonly number[] => [...new Set(ids)];
 
-const lookupReadsOf = (state: State, lookup: { readonly [name: string]: SystemLookup } | undefined): { readonly reads: readonly number[]; readonly watched: readonly number[] } => {
+const lookupReadsOf = (state: State, lookup: { readonly [name: string]: SystemLookupLists } | undefined): { readonly reads: readonly number[]; readonly watched: readonly number[] } => {
     const reads: number[] = [];
     const watched: number[] = [];
     for (const name in lookup) {
@@ -199,20 +257,23 @@ const startCounting = (state: State): void => {
 export const createJoinedObserverRunner = (state: State, leaf: Leaf, target: ObserverTarget, since = 0): Runner => {
     for (const lookup of Object.values(leaf.declaration.lookup ?? {})) {
         const index = indexOfLookup(lookup);
-        if (index !== undefined && watchesEntries(lookup)) throw new Error(entriesOnJoined(leaf, threadOf(leaf.declaration, "System", leaf.name) ?? target.label, labelOfItem(index)));
+        if (index !== undefined && watchesEntries(lookup)) throw new Error(entriesOnJoined(leaf, threadOf(leaf.declaration, "System", leaf.name) ?? target.label, index.name));
     }
     // One placed there by the objects it names, rather than the thread's own, is named there by its id and its keys'.
     if (!state.observer.proxies.has(leaf)) {
-        if (idOfItem(leaf) === undefined) {
-            const thread = threadOf(leaf.declaration, "System", leaf.name) ?? target.label;
-            throw new Error(`System "${labelOfItem(leaf)}" runs on thread "${thread}", which a joined thread fills, and has no id, so that thread can't name it; the build gives top-level systems one.`);
+        const id = idOfItem(leaf);
+        const thread = threadOf(leaf.declaration, "System", leaf.name) ?? target.label;
+        if (id === undefined) {
+            throw new Error(`System "${leaf.name}" runs on thread "${thread}", which a joined thread fills, and has no id, so that thread can't name it; the build gives top-level systems one.`);
         }
+        // That thread runs only what it imported, so a post of one it didn't would never be answered.
+        if (!target.imported.has(id)) throw new Error(`System "${leaf.name}" runs on thread "${thread}", which the joined thread claiming it never imported.`);
         const unnamed = unnamedKey(leaf);
         if (unnamed !== null) throw new Error(unnamed);
     }
-    const base = createRunner(state, leaf, since);
     const { declaration } = leaf;
     const { components, resources } = declaration;
+    const base = createRunner(state, leaf, since);
     const ids = (keys: readonly Key[] | undefined): number[] => [...new Set((keys ?? []).map(key => idOf(state, key)))];
     // Strings live in shared memory, as structs do.
     const isStruct = (id: number): boolean => state.layouts[id].kind !== "object";
@@ -260,7 +321,7 @@ export const createJoinedObserverRunner = (state: State, leaf: Leaf, target: Obs
     const index = target.free.pop() ?? target.placed.length;
     const proxy = state.observer.proxies.get(leaf);
     const observer: JoinedObserver = {
-        target, index, label: proxy?.label ?? labelOfItem(leaf), runner: base,
+        target, index, label: proxy?.label ?? leaf.name, id: proxy === undefined ? idOrNull(leaf) : null, runner: base,
         matched: base.matched,
         reads: ids([...components?.read ?? [], ...components?.added ?? [], ...components?.changed ?? []]).filter(isStruct),
         resourceReads: resourceIds.filter(isStruct),
@@ -272,8 +333,9 @@ export const createJoinedObserverRunner = (state: State, leaf: Leaf, target: Obs
         gone: () => target.ended, idle: () => target.end,
         lookupReads: looked.reads, watched: looked.watched,
         filtered: (components?.added?.length ?? 0) + (components?.changed?.length ?? 0) + (resources?.changed?.length ?? 0) > 0,
+        pointed: components?.where !== undefined && (components.added?.length ?? 0) + (components.changed?.length ?? 0) + (resources?.changed?.length ?? 0) > 0,
         records, ticks: contained?.slots[0].ticks ?? new Float64Array(buffer, block + tickSlot * 8, 2), contained,
-        live: false, tick: 0, copied: false, cancels: 0, pending: -1, stopped: false, dropped: false, freed: false,
+        live: false, tick: 0, copied: false, cancels: 0, pending: -1, valued: false, stopped: false, dropped: false, freed: false,
     };
     target.placed[index] = observer;
     state.observer.count++;
@@ -325,6 +387,7 @@ const stop = (state: State, observer: JoinedObserver): void => {
     if (observer.contained !== null) Atomics.store(observer.contained.slots[1].control, removedWord, 1);
     state.observer.pending.delete(observer);
     observer.pending = -1;
+    endWait(state, observer, nothingThere);
     state.observer.count--;
     if (state.observer.count === 0 && !state.claimed) state.counting = false;
     if (!observer.target.ended) observer.target.post({ protocol: "@adobe/ecs/join@1", kind: "unplace observers", indexes: [observer.index] });
@@ -357,6 +420,7 @@ export const endTarget = (state: State, target: ObserverTarget, left: boolean):
         if (observer === undefined) continue;
         state.observer.pending.delete(observer);
         observer.pending = -1;
+        endWait(state, observer, goneThere(observer));
         if (observer.contained !== null) dropPosts(observer, observer.contained);
         tryFree(state, observer);
     }
@@ -392,6 +456,8 @@ const mayRun = (state: State, observer: JoinedObserver): boolean => {
         }
     }
     else if (!observer.filtered) return true;
+    // An archetype `where` skipped catches up when it passes, by a point the world doesn't see: posted each time.
+    if (observer.pointed) return true;
     if (observer.added.length + observer.changed.length === 0) return false;
     for (const archetype of observer.matched()) {
         if (archetype.count === 0) continue;
@@ -440,7 +506,7 @@ const write = (state: State, observer: JoinedObserver, tick: number): void => {
     Atomics.store(control, progressWord, opening);
     for (const word of [doneWord, waitingWord, snapshotOffsetWord, snapshotRowsWord, snapshotStartWord, snapshotFlagsWord, outcomeWord]) Atomics.store(control, word, 0);
     Atomics.store(control, endWord, observer.end);
-    Atomics.store(control, runsWord, Math.max(observer.pending, 0));
+    Atomics.store(control, runsWord, owedWord(observer));
     Atomics.store(control, syncWord, observer.target.log === null ? 0 : Atomics.load(observer.target.log.header, logSyncWord));
     observer.ticks[0] = tick;
     observer.ticks[1] = observer.lastRun;
@@ -482,7 +548,7 @@ const writeContained = (state: State, observer: JoinedObserver, contained: Conta
     }
     if (flags !== slot.flags) control[snapshotFlagsWord] = flags;
     control[outcomeWord] = notRun;
-    control[runsWord] = observer.pending < 0 ? 0 : observer.pending;
+    control[runsWord] = owedWord(observer);
     slot.ticks[0] = tick;
     slot.ticks[1] = observer.lastRun;
     slot.tick = tick;
@@ -519,7 +585,7 @@ const headPasses = headExecuted | headRan;
 const takeOutcome = (observer: JoinedObserver, slot: Slot, outcome: number): void => {
     if (outcome !== notRun) observer.cancels = 0;
     if (outcome === ranExecuted && slot.tick > observer.lastRun) observer.lastRun = slot.tick;
-    if (outcome !== notRun && observer.pending >= 0 && slot.control[runsWord] >= observer.pending) observer.pending = -1;
+    if (outcome !== notRun && observer.pending >= 0 && ranFor(slot.control[runsWord], observer.pending)) observer.pending = -1;
 };
 
 /**
@@ -690,7 +756,7 @@ const settle = (state: State, observer: JoinedObserver): void => {
     const outcome = Atomics.load(observer.control, outcomeWord);
     if (outcome !== notRun) observer.cancels = 0;
     if (outcome === ranExecuted) observer.lastRun = observer.tick;
-    if (outcome !== notRun && observer.pending >= 0 && Atomics.load(observer.control, runsWord) >= observer.pending) {
+    if (outcome !== notRun && observer.pending >= 0 && ranFor(Atomics.load(observer.control, runsWord), observer.pending)) {
         observer.pending = -1;
         state.observer.pending.delete(observer);
     }
@@ -792,7 +858,7 @@ export const settleObserverKeys = (state: State, components: readonly number[],
 /** Why an observer system's key can't cross to a joined thread, or null when every one can. */
 export const unnamedKey = (leaf: Leaf): string | null => {
     const unnamed = keysOf(leaf).find(key => idOfKey(key) === undefined);
-    return unnamed === undefined ? null : `System "${labelOfItem(leaf)}" names "${labelOf(unnamed)}", which has no id, so a joined thread can't name it; the build gives top-level keys one.`;
+    return unnamed === undefined ? null : `System "${leaf.name}" names "${labelOf(unnamed)}", which has no id, so a joined thread can't name it; the build gives top-level keys one.`;
 };
 
 /** Runs of observer systems from joined threads, by the value standing for their input: the run's sequence there. */

package/src/implementation/world/joining-worker.fixture.ts

@@ -1,21 +1,31 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { MessagePort as NodeMessagePort } from "node:worker_threads";
 import { workers } from "../../interface/resources/workers.js";
 import { System } from "../../interface/system/system.js";
 import { Observe } from "../../observe/index.js";
 import { createWorld, join } from "./create.js";
+import { threadLock } from "./joining.js";
 import { scopeChannel } from "./port.js";
-import { drive, idle, names, total, until, withReports, type Driven, type Reported } from "./joining.test-helper.js";
+import { drive, idle, names, total, until, type Driven } from "./joining.test-helper.js";
 
 /** A thread joining a world through the port it's sent and driving it, or holding a world it shares through it. */
 
 /** A system only this thread imports, which a world elsewhere never did. */
-const unimportedByMain = System.create({ name: "joiningTest/unimportedByMain" }, () => {});
+const unimportedByMain = System.create({}, () => {});
 
 type Port = MessagePort | NodeMessagePort;
 export type ToJoiningWorker =
     | { readonly kind: "join"; readonly port: Port; readonly threads: readonly "main"[] }
     | { readonly kind: "idle"; readonly port: Port; readonly threads: readonly "main"[] }
+    /** Join, and add an observer system hearing `total`, as the join resolved. */
+    | { readonly kind: "listen"; readonly port: Port; readonly threads: readonly "main"[] }
+    /** What the observer system `listen` added heard, once it heard `value`, or after a few seconds. */
+    | { readonly kind: "heard"; readonly value: number }
+    /** Join, then end this thread on the turn the join resolved, before the world heard it finished. */
+    | { readonly kind: "exit on join"; readonly port: Port; readonly threads: readonly "main"[] }
     | { readonly kind: "host"; readonly port: Port }
+    /** Hold a world shared through the port, then block this thread for good, so the world never answers a join. */
+    | { readonly kind: "host and stall"; readonly port: Port }
     /** Hold a world shared through this worker's own scope, which this fixture's messages share. */
     | { readonly kind: "host scope" }
     /** Once the thread that joined has left: the world's state, and the reports of the runs it drove. */
@@ -23,44 +33,74 @@ export type ToJoiningWorker =
 export type FromJoiningWorker =
     | { readonly kind: "driven"; readonly driven: Driven }
     | { readonly kind: "joined"; readonly ran: string }
+    | { readonly kind: "listening"; readonly joined: string }
+    | { readonly kind: "heard"; readonly heard: readonly number[] }
     | { readonly kind: "shared" }
-    | { readonly kind: "state"; readonly driven: Reported | null; readonly total: number; readonly names: readonly string[]; readonly status: string | null };
+    | { readonly kind: "state"; readonly driven: Driven | null; readonly total: number; readonly names: readonly string[]; readonly status: string | null };
 
 const channel = scopeChannel<FromJoiningWorker, ToJoiningWorker>();
 let hosted: ReturnType<typeof createWorld> | null = null;
+/** What the observer system `listen` adds heard. */
+const heard: number[] = [];
+const hear = System.create({ observer: true }, ({ resources }) => { heard.push(resources[total]); });
+const messageOf = (error: unknown): string => error instanceof Error ? error.message : String(error);
+/** Ends this thread at once: node's worker exits, and a browser worker closes, dropping the tasks it queued. */
+const exit = (): void => {
+    if (globalThis.process?.versions?.node !== undefined) globalThis.process.exit(0);
+    else self.close();
+};
 channel.onMessage(async message => {
     // The world's own messages, where it shares the scope.
     if ("protocol" in message) return;
     if (message.kind === "host scope") {
         const world = createWorld({ [workers]: 0 });
         const scope = globalThis.process?.getBuiltinModule?.("node:worker_threads")?.parentPort ?? self;
-        world.share(scope);
+        void world.share(scope);
         hosted = world;
         channel.post({ kind: "shared" });
     }
     else if (message.kind === "join") {
-        const remote = join(message.port, { threads: message.threads });
+        const remote = await join(message.port, { threads: message.threads });
         channel.post({ kind: "driven", driven: await drive(remote, unimportedByMain) });
         await remote.dispose();
     }
     else if (message.kind === "idle") {
-        // Joins and stays, its one run's outcome posted.
-        const remote = join(message.port, { threads: message.threads });
-        const ran = await remote.run(idle).then(() => "ran", (error: unknown) => error instanceof Error ? error.message : String(error));
+        // Joins and stays, its one run's outcome posted, or why it didn't join.
+        const ran = await join(message.port, { threads: message.threads }).then(remote => remote.run(idle)).then(() => "ran", messageOf);
         channel.post({ kind: "joined", ran });
     }
-    else if (message.kind === "host") {
+    else if (message.kind === "listen") {
+        const joined = await join(message.port, { threads: message.threads }).then(remote => {
+            remote.add(hear);
+            return "joined";
+        }, messageOf);
+        channel.post({ kind: "listening", joined });
+    }
+    else if (message.kind === "heard") {
+        const end = performance.now() + 5000;
+        while (!heard.includes(message.value) && performance.now() < end) await new Promise(resolve => setTimeout(resolve, 1));
+        channel.post({ kind: "heard", heard });
+    }
+    else if (message.kind === "exit on join") {
+        await join(message.port, { threads: message.threads });
+        exit();
+    }
+
+    else if (message.kind === "host" || message.kind === "host and stall") {
         const world = createWorld({ [workers]: 0 });
-        world.share(message.port);
+        void world.share(message.port);
         hosted = world;
+        // Once the world told the port the lock this thread holds while it lives, where it holds one.
+        await threadLock();
         channel.post({ kind: "shared" });
+        if (message.kind === "host and stall") Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0);
     }
     else if (message.kind === "state" && hosted !== null) {
         // Once the thread that joined has left.
         const threads = await until(hosted.threads, shown => shown[0]?.status === "gone");
         channel.post({
             kind: "state",
-            driven: message.driven === undefined ? null : await withReports(hosted, message.driven),
+            driven: message.driven ?? null,
             total: await Observe.toPromise(Observe.resource(hosted, total)),
             names: await Observe.toPromise(Observe.resource(hosted, names)),
             status: threads[0]?.status ?? null,

package/src/implementation/world/joining.cases.ts

@@ -1,13 +1,15 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { describe, expect, it } from "vitest";
 import type * as Fixture from "./joining.fixture.js";
 
-const clean = { failures: [], skipped: [], dropped: 0, warnings: [] };
-
 /** Threads joining worlds on others: the cases, over the fixture built for node or from source. */
 export const joiningCases = (load: () => Promise<typeof Fixture>) => describe("joining", () => {
     const expectDriven = (driven: Awaited<ReturnType<typeof Fixture.worldThere>>["driven"] | null, unimported: RegExp) => {
-        expect(driven?.reports).toEqual([clean, clean, clean, clean, clean]);
-        expect(driven?.failures).toEqual(["joiningTest failure"]);
+        // Runs resolve to what their bodies returned, posted from the world's thread.
+        expect(driven?.runs).toEqual([1, 1, 12, 2, 123]);
+        expect(driven?.failed).toMatch(/^System "fail" \(.*joining\.test-helper\.ts#fail\) failed: joiningTest failure$/);
+        // Its own observer system runs on the joined thread, resolving to what it read there.
+        expect(driven?.read).toBe(123);
         expect(driven?.total).toBe(123);
         expect(driven?.selected).toBe(2);
         expect(driven?.counted).toBe(1);
@@ -42,11 +44,45 @@ export const joiningCases = (load: () => Promise<typeof Fixture>) => describe("j
 
     it("show a joined thread that dies as gone", async () => {
         const fixture = await load();
-        expect(await fixture.dies()).toEqual({ ran: "ran", status: "gone" });
+        expect(await fixture.dies()).toEqual({ ran: "ran", share: "joined", status: "gone" });
+    }, 30000);
+
+    it("refuse a thread claimed twice, rejecting its share and its join, saying why", async () => {
+        const fixture = await load();
+        expect(await fixture.claimedTwice()).toEqual({ first: "ran", second: 'Thread "main" is claimed twice.', shared: ["joined", 'Thread "main" is claimed twice.'], status: "gone" });
+    }, 30000);
+
+    it("resolve share once a worker joined, so a run from this thread reaches the observer systems it added as it joined", async () => {
+        const fixture = await load();
+        const result = await fixture.signal();
+        expect(result.share).toBe("joined");
+        expect(result.joined).toBe("joined");
+        expect(result.heard).toContain(7);
     }, 30000);
 
-    it("refuse a thread claimed twice", async () => {
+    it("reject share for a worker that dies before its join finished, releasing its claims", async () => {
+        const fixture = await load();
+        expect(await fixture.diesJoining()).toEqual({ share: "The thread was gone before it joined.", again: "joined" });
+    }, 30000);
+
+    it("reject a run of an observer system the thread claiming its objects never imported, and go on", async () => {
+        const fixture = await load();
+        expect(await fixture.unimportedObserver()).toEqual({
+            ran: expect.stringMatching(/^System "shelvedHere" runs on thread "main", which the joined thread claiming it never imported\.$/),
+            after: "joined", disposed: "joined",
+        });
+    }, 60000);
+
+    it("reject a share with a worker, and a join through one, that fails as it starts, saying why", async () => {
+        const fixture = await load();
+        expect(await fixture.failingWorkers()).toEqual({
+            shared: expect.stringMatching(/^The thread failed before it joined: .*failing worker$/),
+            joined: expect.stringMatching(/^The world's thread failed before it answered: .*failing worker$/),
+        });
+    }, 60000);
+
+    it("reject a join whose world's thread dies before answering", async () => {
         const fixture = await load();
-        expect(await fixture.claimedTwice()).toEqual({ first: "ran", second: 'Thread "main" is claimed twice.', status: "gone" });
+        expect(await fixture.worldDies()).toBe("The world's thread is gone.");
     }, 30000);
 });

package/src/implementation/world/joining.fixture.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 /// <reference types="node" />
 import { Observe } from "../../observe/index.js";
 import { workers } from "../../interface/resources/workers.js";
@@ -5,7 +6,7 @@ import { System } from "../../interface/system/system.js";
 import type { World } from "../../interface/world/world.js";
 import { createWorld, join } from "./create.js";
 import type { FromJoiningWorker, ToJoiningWorker } from "./joining-worker.fixture.js";
-import { add, drive, names, total, until, withReports } from "./joining.test-helper.js";
+import { add, drive, idle, names, shelf, total, until } from "./joining.test-helper.js";
 
 /**
  * Scenarios of a thread joining a world on another, run built in node and from source in chromium: a worker joining a
@@ -13,7 +14,9 @@ import { add, drive, names, total, until, withReports } from "./joining.test-hel
  */
 
 /** A system only this thread imports, which a world on a worker never did. */
-const unimportedByWorker = System.create({ name: "joiningTest/unimportedByWorker" }, () => {});
+const unimportedByWorker = System.create({}, () => {});
+/** An observer system only this thread imports, reading an object of `main`, so it's placed on a thread claiming it. */
+const shelvedHere = System.create({ observer: true }, ({ resources }) => resources[shelf].length);
 
 type Worker = {
     readonly ask: (message: ToJoiningWorker, transfer?: readonly unknown[]) => Promise<FromJoiningWorker>;
@@ -57,21 +60,35 @@ const start = (): Worker => {
     };
 };
 
+/** Starts a worker that fails as it starts: it, as a port, and how to end it. */
+const startFailing = (): Pick<Worker, "port" | "terminate"> => {
+    if (typeof globalThis.Worker === "function") {
+        const worker = new globalThis.Worker(new URL("./failing-worker.fixture.js", import.meta.url), { type: "module" });
+        return { port: worker, terminate: async () => worker.terminate() };
+    }
+    const threads = globalThis.process.getBuiltinModule("node:worker_threads");
+    const worker = new threads.Worker(new URL("./failing-worker.fixture.js", import.meta.url));
+    return { port: worker, terminate: async () => { await worker.terminate(); } };
+};
+
 const within = <T>(promise: Promise<T>, milliseconds: number, otherwise: T): Promise<T> =>
     Promise.race([promise, new Promise<T>(resolve => setTimeout(() => resolve(otherwise), milliseconds))]);
 
+/** `"joined"` once a share or join resolved, or the message it rejected with. */
+const outcomeOf = (promise: Promise<unknown>): Promise<string> => promise.then(() => "joined", (error: unknown) => error instanceof Error ? error.message : String(error));
+
 /** A world here, a worker joining it and driving it, then leaving. */
 export const worldHere = async () => {
     const world = createWorld({ [workers]: 0 });
     const { port1, port2 } = new MessageChannel();
-    world.share(port1);
-    const joined = until(world.threads, threads => threads[0]?.status === "joined");
+    const shared = world.share(port1);
     const worker = start();
     const reply = await worker.ask({ kind: "join", port: port2, threads: ["main"] }, [port2]);
-    const claims = (await joined)[0]?.claims ?? null;
+    await shared;
+    const claims = (await until(world.threads, threads => threads[0] !== undefined))[0]?.claims ?? null;
     const gone = (await until(world.threads, threads => threads[0]?.status === "gone"))[0];
     const result = {
-        driven: reply.kind === "driven" ? await withReports(world, reply.driven) : null,
+        driven: reply.kind === "driven" ? reply.driven : null,
         claims,
         status: gone?.status ?? null,
         total: await Observe.toPromise(Observe.resource(world, total)),
@@ -87,7 +104,7 @@ export const worldThere = async () => {
     const worker = start();
     const { port1, port2 } = new MessageChannel();
     await worker.ask({ kind: "host", port: port1 }, [port1]);
-    const remote = join(port2, { threads: ["main"] });
+    const remote = await join(port2, { threads: ["main"] });
     const driven = await drive(remote, unimportedByWorker);
     await remote.dispose();
     const state = await worker.ask({ kind: "state", driven });
@@ -99,36 +116,119 @@ export const worldThere = async () => {
 export const dies = async () => {
     const world = createWorld({ [workers]: 0 });
     const { port1, port2 } = new MessageChannel();
-    world.share(port1);
+    const shared = outcomeOf(world.share(port1));
     const worker = start();
     const reply = await worker.ask({ kind: "idle", port: port2, threads: [] }, [port2]);
+    const share = await shared;
     await worker.terminate();
     const gone = await within(until(world.threads, threads => threads[0]?.status === "gone"), 20000, null);
     await world.dispose();
-    return { ran: reply.kind === "joined" ? reply.ran : null, status: gone?.[0]?.status ?? null };
+    return { ran: reply.kind === "joined" ? reply.ran : null, share, status: gone?.[0]?.status ?? null };
 };
 
-/** Two workers claiming `main`: the second's run, and its status. */
+/** Two workers claiming `main`: each side's outcome of the second's join, the first's run, and the second's status. */
 export const claimedTwice = async () => {
     const world = createWorld({ [workers]: 0 });
     const first = new MessageChannel();
     const second = new MessageChannel();
-    world.share(first.port1);
-    world.share(second.port1);
+    const shares = [outcomeOf(world.share(first.port1)), outcomeOf(world.share(second.port1))];
     const pair = [start(), start()];
     const one = await pair[0].ask({ kind: "idle", port: first.port2, threads: ["main"] }, [first.port2]);
     const two = await pair[1].ask({ kind: "idle", port: second.port2, threads: ["main"] }, [second.port2]);
     const gone = (await until(world.threads, threads => threads[1]?.status === "gone"))[1];
+    const shared = await Promise.all(shares);
     for (const worker of pair) await worker.terminate();
     await world.dispose();
-    return { first: one.kind === "joined" ? one.ran : null, second: two.kind === "joined" ? two.ran : null, status: gone?.status ?? null };
+    return { first: one.kind === "joined" ? one.ran : null, second: two.kind === "joined" ? two.ran : null, shared, status: gone?.status ?? null };
+};
+
+/**
+ * A world here, a worker joining it and adding an observer system as its join resolved: once `share` resolved, a run
+ * from this thread reaches it. What the worker's join and the world's share gave, and what the observer system heard.
+ */
+export const signal = async () => {
+    const world = createWorld({ [workers]: 0 });
+    const { port1, port2 } = new MessageChannel();
+    const shared = outcomeOf(world.share(port1));
+    const worker = start();
+    const listening = worker.ask({ kind: "listen", port: port2, threads: ["main"] }, [port2]);
+    const share = await shared;
+    await world.run(add, { amount: 7 });
+    const reply = await listening;
+    const heard = await worker.ask({ kind: "heard", value: 7 });
+    await worker.terminate();
+    await world.dispose();
+    return { share, joined: reply.kind === "listening" ? reply.joined : null, heard: heard.kind === "heard" ? heard.heard : null };
+};
+
+/**
+ * A worker that ends on the turn its join resolved, so the world never hears its join finished: what the world's
+ * share gave, and whether another thread then claims what it claimed.
+ */
+export const diesJoining = async () => {
+    const world = createWorld({ [workers]: 0 });
+    const first = new MessageChannel();
+    const shared = within(outcomeOf(world.share(first.port1)), 20000, "pending");
+    const worker = start();
+    // Never answered: the worker ends.
+    void worker.ask({ kind: "exit on join", port: first.port2, threads: ["main"] }, [first.port2]);
+    const share = await shared;
+    const second = new MessageChannel();
+    const again = outcomeOf(world.share(second.port1));
+    const remote = await join(second.port2, { threads: ["main"] });
+    const result = { share, again: await again };
+    await remote.dispose();
+    await worker.terminate();
+    await world.dispose();
+    return result;
+};
+
+/**
+ * A worker claiming `main`, then a run here of an observer system reading `main`'s objects that the worker never
+ * imported: what the run gave, and whether the world still runs and disposes.
+ */
+export const unimportedObserver = async () => {
+    const world = createWorld({ [workers]: 0 });
+    const { port1, port2 } = new MessageChannel();
+    const shared = world.share(port1);
+    const worker = start();
+    await worker.ask({ kind: "idle", port: port2, threads: ["main"] }, [port2]);
+    await shared;
+    const ran = await within(outcomeOf(world.run(shelvedHere)), 10000, "pending");
+    const after = await within(outcomeOf(world.run(idle)), 10000, "pending");
+    const disposed = await within(outcomeOf(world.dispose()), 10000, "pending");
+    await worker.terminate();
+    return { ran, after, disposed };
+};
+
+/** A share with a worker, and a join through another, each failing as it starts: what each gave. */
+export const failingWorkers = async () => {
+    const world = createWorld({ [workers]: 0 });
+    const sharedWith = startFailing();
+    const shared = await within(outcomeOf(world.share(sharedWith.port)), 20000, "pending");
+    const joinedThrough = startFailing();
+    const joined = await within(outcomeOf(join(joinedThrough.port)), 20000, "pending");
+    await sharedWith.terminate();
+    await joinedThrough.terminate();
+    await world.dispose();
+    return { shared, joined };
+};
+
+/** This thread joining a world on a worker that stalls before it answers, then is ended: what the join gave. */
+export const worldDies = async () => {
+    const worker = start();
+    const { port1, port2 } = new MessageChannel();
+    await worker.ask({ kind: "host and stall", port: port1 }, [port1]);
+    const joining = within(outcomeOf(join(port2)), 20000, "pending");
+    await worker.terminate();
+    return await joining;
 };
 
 /** A world on a worker shared through its own scope, this thread joined through the worker: runs, an observer factory, leaving. */
 export const scopes = async () => {
     const worker = start();
     await worker.ask({ kind: "host scope" });
-    const remote = join(worker.port);
+    const remote = await join(worker.port);
     for (const amount of [4, 5, 6]) await remote.run(add, { amount });
     const observed = await until(Observe.resource(remote, total), value => value === 456);
     await remote.dispose();