@synapse-sdk/client 0.3.4 → 0.3.6

package/dist/scene.js

@@ -1,22 +1,27 @@
-// The scene (PLAN v0.24 §1, §5, §10), the JS spelling of the Rust client's `scene.rs`: the active
-// project's scene as this node sees it.
+// The scene (PLAN v0.24 §1, §5, §10; attach PLAN v0.34), the JS spelling of the Rust client's `scene.rs`:
+// the active project's scene as this node sees it.
 //
-// `scene()` follows the incarnations the runtime announces under `runtime/scene/` (`@<epoch>`, one at
-// a time: the active project's) and reads both tracks of the one it binds to: `authored` (a snapshot
-// frame, then one diff frame per applied batch; a later group is a fresh snapshot that replaces the
-// copy) and `live` (each group starts with the whole live set, then one frame per runtime tick). The
+// `scene()` asks the runtime where the live incarnation stands (`synapse/scene/open`: its `epoch`, its
+// `version`) and reads both tracks of that incarnation (`runtime/scene/@<epoch>`): `authored` (a
+// snapshot frame, then one diff frame per applied batch; a later group is a fresh snapshot that replaces
+// the copy) and `live` (each group starts with the whole live set, then one frame per runtime tick). The
 // copy this node keeps (the mirror) is authored ⊕ live: a live row replaces `xform.t/q`, `joints` and
 // `state` of the authored entity it names; a live entity is a row of its own. Nothing is kept across
-// incarnations.
+// incarnations. A diff out of sequence is not applied: the track is subscribed again (its open group
+// starts with a snapshot) and `synced` is false until the copy is back at the version seen (the gap).
 //
 // One task per node, the store's shape: every `scene()` on the node shares it; the task owns the
 // session it is told about (`Node.monitor`), the incarnation it reads, the mirror and the writes in
 // flight, and is driven by one mailbox, in order:
 // - `session` / `sessionEnded` / `nodeEnded`: what was bound on the previous session is over (the
-//   mirror empties, the handle is `detached`); the announcements are followed again on the new one;
+//   mirror empties, the handle is `detached`); the scene is opened again on the new one;
+// - `opened`: the runtime's answer to the open: its version is wanted and its incarnation read;
+//   `project_settling` is asked again, paced; `project_inactive` answers the `scene()` calls waiting
+//   (detached) and opens again when the project feed shows a project active;
 // - the incarnation's tracks are read by the task's reader (the only writer of the mirror), which
-//   tells the task of each authored frame applied (`applied`); the incarnation's end (its final frame,
-//   or the tracks ending) empties the mirror and the announcements are followed again (`followEnded`);
+//   tells the task of each authored frame applied (`applied`) and of the live track's first keyframe
+//   (`liveKeyed`); the incarnation's end (its final frame, or the tracks ending) empties the mirror and
+//   the scene is opened again (`followEnded`);
 // - `join`: a `scene()` call waiting for the scene to be in (attached, or no project active);
 // - `apply` / `applyDone`: an authoring batch (it names the bound incarnation's epoch) and the
 //   runtime's answer; the caller is answered once the mirror shows the version;
@@ -35,8 +40,8 @@
 // (`status.get().unclaimedDrops`) when refused. Nothing here reads the mirror to decide what to send: the mirror is a
 // read cache. The Rust client's `scene.rs` is the reference; this file behaves as it does.
 //
-// States: `attached` (an incarnation's snapshot is in the mirror, and every frame of both tracks this
-// node already held when the first frame of each arrived has been applied), `detached` (none: no
+// States: `attached` (the copy is current as of the open: the authored plane at the version the open
+// answered or past it, and the live track's first keyframe applied), `detached` (none: no
 // active project, a session gap, between incarnations), `closed` (`close()` or the node ending). While
 // detached the entities are empty, every author verb fails `project_inactive` at once and a live
 // write drops its batch and counts it. A closed handle's verbs fail `not_connected`.
@@ -56,6 +61,7 @@ import { FLAGS, SynapseError, TYPES, decode as decodeBody, decodeHeader, encode
 import { startOn } from "./calls.js";
 import { REFOLLOW_PACE_MS, isTransient, refusalPaceMs } from "./channel.js";
 import { CALL_GROUP_MAX_AGE_MS, StreamWriter, frameTooLarge, latestSubscription, waitActive } from "./session.js";
+import { ANNOUNCE_WITHIN_MS } from "./store.js";
 import { AsyncQueue, StatusCell, deferred, replaceEqualDeep, rethrowLater, watchState } from "./util.js";
 /** Where the runtime announces the scene's incarnations: `runtime/scene/@<epoch>`. */
 const SCENE_BASE = "runtime/scene";
@@ -473,8 +479,10 @@ export class Mirror {
     epoch;
     version = 0;
     hash = "";
-    /** An authored diff skipped a version; cleared by the next snapshot. */
-    gap = false;
+    /** An authored diff skipped a version (not applied; the track is read again from its snapshot): the highest version seen then. Cleared once the copy is back at it (PLAN v0.34 §2.2). */
+    gap;
+    /** The live track's first keyframe of the incarnation is in the copy. */
+    liveKeyed = false;
     pending = 0;
     authored = new Map();
     live = new Map();
@@ -553,7 +561,7 @@ export class Mirror {
         this.merged = replaceEqualDeep(this.merged, merged);
         this.#treeStale = true;
     }
-    /** A snapshot of incarnation `epoch` replaces the authored copy. Not yet `attached`: the reader catches up first (`attach`). */
+    /** A snapshot of incarnation `epoch` replaces the authored copy. The first one is not yet `attached`: that is the task's, once the copy is at the version the open answered. */
     applySnapshot(epoch, s) {
         if (this.state === "closed")
             return;
@@ -563,30 +571,41 @@ export class Mirror {
         this.version = s.version;
         this.hash = s.hash;
         this.epoch = epoch;
-        this.gap = false;
+        this.#heal();
         this.#rebuild();
         this.#notify();
     }
-    /** The reader has applied everything this node held when it bound the incarnation. */
+    /** The copy is current as of the attach (the task checked it): `attached`. */
     attach() { if (this.epoch !== undefined && this.state !== "closed") {
         this.#setState("attached");
         this.#notify();
     } }
-    /** One applied batch: its ops folded into the authored copy. */
+    /** A gap is over once the copy is back at the highest version seen when it opened. */
+    #heal() { if (this.gap !== undefined && this.version >= this.gap)
+        this.gap = undefined; }
+    /**
+     * One applied batch: its ops folded into the authored copy, when it is the next version. Otherwise it is not applied
+     * (`false`): a gap, `synced` false until the copy is back at the version seen; the reader reads the track again from
+     * its snapshot (PLAN v0.34 §2.2).
+     */
     applyDiff(d, warn) {
         if (this.epoch === undefined || this.state === "closed")
-            return;
+            return true;
         if (d.version !== this.version + 1) {
-            warn(`scene: diff out of sequence (have ${this.version}, got ${d.version}); not synced until the next snapshot`);
-            this.gap = true;
+            warn(`scene: diff out of sequence (have ${this.version}, got ${d.version}): not applied; reading the track again from its snapshot`);
+            this.gap = Math.max(this.gap ?? d.version, d.version);
+            this.#notify();
+            return false;
         }
         const touched = [];
         for (const op of d.ops)
             touched.push(...foldAuthored(this.authored, op, d.t, d.by ?? null));
         this.version = d.version;
         this.hash = d.hash;
+        this.#heal();
         this.#refresh(touched);
         this.#notify();
+        return true;
     }
     /** A keyframe replaces the live table. */
     applyKeyframe(k) {
@@ -597,6 +616,7 @@ export class Mirror {
         keepLiveEntities(table, id => old.get(id)?.entity, table.keys());
         const ids = [...this.live.keys(), ...table.keys()];
         this.live = table;
+        this.liveKeyed = true;
         this.#refresh(ids);
         this.#notify();
     }
@@ -628,7 +648,8 @@ export class Mirror {
         this.epoch = undefined;
         this.version = 0;
         this.hash = "";
-        this.gap = false;
+        this.gap = undefined;
+        this.liveKeyed = false;
         this.#setState("detached");
         this.#notify();
     }
@@ -799,6 +820,16 @@ class EntityView extends MirrorView {
     watch(component) {
         return watchState(cb => this.onChange(cb), () => this.get(component), this.ended);
     }
+    /** The entity (or `component` of it) after its next change, as `watch(component)` yields it; the value now once the handle ends. Armed at the call. */
+    changed(component) {
+        if (component === undefined)
+            return super.changed();
+        if (this.ended())
+            return Promise.resolve(this.get(component));
+        // the first step of `watch(component)`, started now (its baseline is read at the first `next()`), then left
+        const it = this.watch(component)[Symbol.asyncIterator]();
+        return it.next().then(r => { void it.return?.(undefined); return r.done ? this.get(component) : r.value; });
+    }
 }
 /** Releases a claim this node does not keep (granted after its handle closed, or after a `live.remove`): the call `synapse/scene/live/remove`, best effort. */
 function release(node, session, id) {
@@ -817,6 +848,14 @@ function replyId(v) {
     return id;
 }
 const sessionGone = (e) => e.code === "connection_lost" || e.code === "not_connected";
+/** The answer of `synapse/scene/open`: where the live incarnation stands. */
+function parseOpen(reply) {
+    const r = reply;
+    const version = typeof r?.version === "bigint" ? Number(r.version) : r?.version;
+    if (typeof r?.epoch !== "string" || typeof version !== "number")
+        throw new SynapseError("internal", "scene open reply not understood");
+    return { epoch: r.epoch, version };
+}
 function openLiveWriter(s) {
     const bc = s.createBroadcast(`${s.prefix}/scene/live`);
     // Kept as long as a call track keeps its groups (the runtime's follower reads every batch).
@@ -995,8 +1034,11 @@ async function run(scene, registry) {
     let phase = { kind: "idle" };
     const ph = () => phase;
     let attempts = 0;
-    /** The incarnation that last ended: not bound again (its announcement may still be seen). */
-    let endedEpoch;
+    /**
+     * The incarnation the open answered and its version then: the copy is current (the handle `attached`) once it holds
+     * that version and the live track's first keyframe (PLAN v0.34 §2.1).
+     */
+    let wanted;
     /** The session's project state as last read. */
     let project;
     let unwatchProject;
@@ -1029,10 +1071,15 @@ async function run(scene, registry) {
             phase.stop.abort();
         else if (phase.kind === "paced")
             clearTimeout(phase.timer);
+        else if (phase.kind === "opening")
+            phase.announced.close();
         phase = { kind: "idle" };
     };
-    /** Follows the announcements on the task's session, from `idle`. */
-    const follow = () => {
+    /**
+     * From `idle`: the announcement cursor under `runtime/scene`, then `synapse/scene/open` on the task's session (the
+     * store's order); its answer comes back as `opened`.
+     */
+    const open = () => {
         if (phase.kind !== "idle" || mirror.state === "closed" || !session)
             return;
         const s = session;
@@ -1044,25 +1091,84 @@ async function run(scene, registry) {
             scene.warn(`scene: announcements not followed: ${e instanceof Error ? e.message : String(e)}`);
             return;
         }
+        let run;
+        try {
+            run = startOn(node, s, "synapse/scene/open", {}, {});
+        }
+        catch {
+            announced.close();
+            return; /* the session is going: its end is on its way */
+        }
         attempts += 1;
         const attempt = attempts;
-        const stop = new AbortController();
-        phase = { kind: "following", attempt, stop };
-        void followIncarnation(scene, s, announced, endedEpoch, stop.signal, attempt).then(r => scene.post({ kind: "followEnded", attempt, epoch: r.epoch, reason: r.reason }));
+        phase = { kind: "opening", attempt, session: s, announced };
+        void run.result.then(v => scene.post({ kind: "opened", attempt, result: { ok: v } }), (e) => scene.post({ kind: "opened", attempt, result: { err: asError(e) } }));
     };
-    /** The incarnation is let go: the mirror empties, writes waiting to show fail, followed again after `paceMs`. */
+    /**
+     * The open of attempt `attempt` answered (one no longer in flight is dropped): the incarnation it names is read, its
+     * version wanted. `project_settling` (or another transient refusal) is asked again, paced; `project_inactive` answers
+     * the waiting `scene()` calls (detached) and waits for the active project to change (at once, paced, when the session
+     * already shows one); so does a scene the runtime cannot serve (warned); the session going is left to its end.
+     */
+    const opened = (attempt, result) => {
+        const p = ph();
+        if (p.kind !== "opening" || p.attempt !== attempt)
+            return;
+        const { session: s, announced } = p;
+        phase = { kind: "idle" };
+        let reply;
+        if ("ok" in result) {
+            try {
+                reply = { ok: parseOpen(result.ok) };
+            }
+            catch (e) {
+                reply = { err: asError(e) };
+            }
+        }
+        else
+            reply = result;
+        if ("ok" in reply) {
+            wanted = reply.ok;
+            const stop = new AbortController();
+            phase = { kind: "following", attempt, stop };
+            void followIncarnation(scene, s, announced, reply.ok.epoch, stop.signal).then(r => scene.post({ kind: "followEnded", attempt, epoch: r.epoch, reason: r.reason }));
+            return;
+        }
+        announced.close();
+        const e = reply.err;
+        if (sessionGone(e)) {
+            session = undefined;
+            return;
+        }
+        if (isTransient(e)) {
+            again(REFOLLOW_PACE_MS);
+            return;
+        }
+        if (e.code === "project_inactive")
+            answerJoins();
+        else
+            scene.warn(`scene: open refused by the runtime (${e.code}${e.message ? `: ${e.message}` : ""}); opened again when the active project changes`);
+        const shown = !!project?.active;
+        if (e.code === "project_inactive" && shown)
+            again(REFOLLOW_PACE_MS);
+        else
+            phase = { kind: "waitingProject" };
+    };
+    /** The incarnation is let go: the mirror empties, writes waiting to show fail, opened again after `paceMs`. */
     const again = (paceMs) => {
         failWaiters(() => new SynapseError("conflict", "the scene's incarnation ended before the write showed"));
         stopPhase();
         mirror.detach();
         unbind();
+        wanted = undefined;
         const a = ++attempts;
         phase = { kind: "paced", timer: setTimeout(() => scene.post({ kind: "paced", attempt: a }), paceMs) };
     };
-    /** The node's session is now `s` (or none): what was bound on the previous one is over; the announcements are followed on `s`. */
+    /** The node's session is now `s` (or none): what was bound on the previous one is over; the scene is opened on `s`. */
     const sessionChanged = (s) => {
         session = s;
         stopPhase();
+        wanted = undefined;
         failWaiters(() => new SynapseError("connection_lost", "the session ended before the write showed in the scene"));
         mirror.detach();
         unbind();
@@ -1075,31 +1181,45 @@ async function run(scene, registry) {
             unwatchProject = s.project.subscribe(p => { scene.post({ kind: "project", snapshot: p }); });
         if (inactive())
             answerJoins();
-        follow();
+        open();
+    };
+    /** The session's project feed changed: with none active the waiting `scene()` calls are answered; a task waiting for a project opens again. */
+    const projectChanged = (snapshot) => {
+        project = snapshot;
+        if (inactive())
+            answerJoins();
+        if (phase.kind === "waitingProject") {
+            phase = { kind: "idle" };
+            open();
+        }
     };
-    /** The reader applied an authored frame of `epoch` reaching `version`: the writes it shows are answered; attached, the `scene()` calls waiting too. */
+    /** The reader applied an authored frame of `epoch` reaching `version`: the writes it shows are answered; the handle attaches when the copy is current. */
     const applied = (epoch, version) => {
         const reached = waiters.filter(w => w.epoch === epoch && w.version <= version);
         waiters = waiters.filter(w => !reached.includes(w));
         for (const w of reached)
             w.reply.resolve();
-        if (mirror.state !== "attached")
-            return;
-        answerJoins();
+        attach();
     };
     /**
-     * Reading `attempt` (the one in progress) caught up with incarnation `epoch` at `version`: the claims are made for it
+     * The copy is current as of the open (PLAN v0.34 §2.1: the authored plane at the version the open answered, or past
+     * it, and the live track's first keyframe applied, both of the incarnation the open named): the claims are made for it
      * first (`bind`), then the handle is `attached` (one path: nothing a handle does after it sees `attached` meets an
-     * unbound attach). A stale reader's attach is ignored.
+     * unbound attach). Attached, the `scene()` calls waiting are answered.
      */
-    const attach = (attempt, epoch, version) => {
-        const p = ph();
-        if (p.kind !== "following" || p.attempt !== attempt || mirror.epoch !== epoch || !session)
+    const attach = () => {
+        const current = mirror.state === "attached"
+            || (wanted !== undefined && mirror.state === "detached" && mirror.epoch === wanted.epoch && mirror.version >= wanted.version && mirror.liveKeyed);
+        if (!current)
             return;
-        if (bound?.session !== session || bound.epoch !== epoch)
-            bind(session, epoch);
-        mirror.attach();
-        applied(epoch, version);
+        if (mirror.state !== "attached") {
+            if (!session || !wanted)
+                return;
+            if (bound?.session !== session || bound.epoch !== wanted.epoch)
+                bind(session, wanted.epoch);
+            mirror.attach();
+        }
+        answerJoins();
     };
     // ---- claims (PLAN v0.31)
     /** The claims are made for an attach no more (a session gap, an incarnation let go): each is unclaimed; answers of asks made before are not this attach's. */
@@ -1453,7 +1573,6 @@ async function run(scene, registry) {
         const e = result.err;
         const live = e.data?.live_epoch;
         if (e.code === "conflict" && typeof live === "string" && live !== epoch && mirror.epoch === epoch) {
-            endedEpoch = epoch;
             again(REFOLLOW_PACE_MS);
         }
         reply.reject(e);
@@ -1489,8 +1608,12 @@ async function run(scene, registry) {
                 case "applied":
                     applied(ev.epoch, ev.version);
                     break;
-                case "attach":
-                    attach(ev.attempt, ev.epoch, ev.version);
+                case "opened":
+                    opened(ev.attempt, ev.result);
+                    break;
+                case "liveKeyed":
+                    if (wanted?.epoch === ev.epoch)
+                        attach();
                     break;
                 case "followEnded": {
                     {
@@ -1499,9 +1622,6 @@ async function run(scene, registry) {
                             break;
                     }
                     phase = { kind: "idle" };
-                    // An incarnation that ended with its final frame is not bound again.
-                    if (ev.epoch !== undefined && ev.reason !== undefined)
-                        endedEpoch = ev.epoch;
                     again(REFOLLOW_PACE_MS);
                     break;
                 }
@@ -1515,9 +1635,7 @@ async function run(scene, registry) {
                     applyDone(ev.epoch, ev.result, ev.reply);
                     break;
                 case "project":
-                    project = ev.snapshot;
-                    if (inactive())
-                        answerJoins();
+                    projectChanged(ev.snapshot);
                     break;
                 case "notice":
                     notice(ev.body);
@@ -1525,7 +1643,7 @@ async function run(scene, registry) {
                 case "paced":
                     if (ph().kind === "paced" && ev.attempt === attempts) {
                         phase = { kind: "idle" };
-                        follow();
+                        open();
                     }
                     break;
                 case "upsert":
@@ -1597,80 +1715,33 @@ function announcedEpoch(prefix) {
     const e = prefix.slice(SCENE_BASE.length + 2);
     return e && !e.includes("/") ? e : undefined;
 }
-/** One track being read: its subscriber and the group it is in (both closed when the reading stops). */
-class TrackReading {
-    sub;
-    group;
-    constructor(sub) {
-        this.sub = sub;
-    }
-    close() { try {
-        this.group?.close();
-    }
-    catch { /* closed */ } try {
-        this.sub.close();
-    }
-    catch { /* closed */ } }
-    /** The first group and its first frame's payload. */
-    async first() {
-        try {
-            const g = await this.sub.recvGroup();
-            if (!g)
-                return undefined;
-            this.group = g;
-            return (await g.readFrame())?.payload;
-        }
-        catch {
-            return undefined;
-        }
-    }
-    /** Reads, without waiting, every frame already held, from the current group on (a newer group that is ready replaces the current one); `on` returns `false` to stop. */
-    drain(on) {
-        for (;;) {
-            const g = this.group;
-            if (g) {
-                let f;
-                try {
-                    f = g.tryReadFrame();
-                }
-                catch {
-                    f = undefined;
-                    this.group = undefined;
-                }
-                if (f) {
-                    if (on(f.payload))
-                        continue;
-                    return;
-                }
-                if (this.group && g.done)
-                    this.group = undefined;
-            }
-            let next;
-            try {
-                next = this.sub.tryRecvGroup();
-            }
-            catch {
-                next = undefined;
-            }
-            if (!next)
-                return;
-            try {
-                this.group?.close();
-            }
-            catch { /* closed */ }
-            this.group = next;
-        }
-    }
-    /** Reads frame by frame as frames come, from the current group on, until `on` returns `false` or the track ends. */
-    async readOn(on) {
+/**
+ * Reads track `name` of `bc` frame by frame as frames come until `on` says `end`, the track ends or `signal` aborts. A
+ * `gap`: this subscription is let go and the track subscribed again, which delivers the open group from its snapshot
+ * (PLAN v0.34 §2.2; no counter, no timer).
+ */
+async function readTrack(bc, name, signal, on) {
+    const track = bc.track(name);
+    for (;;) {
+        if (signal.aborted)
+            return;
+        const sub = track.subscribe(latestSubscription(moqPriority(1)));
+        // Closing the subscriber ends `recvGroup`, not a read on the group it already handed us: that group is closed too.
+        let g;
+        const close = () => { try {
+            g?.close();
+        }
+        catch { /* closed */ } try {
+            sub.close();
+        }
+        catch { /* closed */ } };
+        signal.addEventListener("abort", close, { once: true });
+        let read = "end";
         try {
-            for (;;) {
-                if (!this.group) {
-                    this.group = await this.sub.recvGroup();
-                    if (!this.group)
-                        return;
-                }
-                const g = this.group;
+            groups: for (;;) {
+                g = await sub.recvGroup();
+                if (!g)
+                    break;
                 for (;;) {
                     let f;
                     try {
@@ -1681,13 +1752,22 @@ class TrackReading {
                     }
                     if (!f)
                         break;
-                    if (!on(f.payload))
-                        return;
+                    read = on(f.payload);
+                    if (read !== "read")
+                        break groups;
                 }
-                this.group = undefined;
+                read = "end";
             }
         }
-        catch { /* the track went */ }
+        catch {
+            read = "end"; /* the track went */
+        }
+        finally {
+            signal.removeEventListener("abort", close);
+            close();
+        }
+        if (read !== "gap")
+            return;
     }
 }
 /** A frame's header flags and decoded body, or `undefined` (warned) when it does not decode. */
@@ -1702,14 +1782,18 @@ function decodeFrame(p, warn, what) {
     }
 }
 /**
- * Binds the first incarnation announced (other than `skip`, the one that last ended) and reads both
- * its tracks into the mirror, telling the task of each authored frame applied; returns once the
- * `authored` track ends (its final frame, or the track going). Once `signal` aborts it writes nothing more.
+ * Reads incarnation `epoch` (the one `synapse/scene/open` answered) once it is announced: both its tracks into the
+ * mirror, frame by frame as they come, telling the task of each authored frame applied and of the live track's first
+ * keyframe (the task attaches the handle once the copy is current: a state of the copy, not a count of frames read);
+ * returns once the `authored` track ends (its final frame, or the track going). Once `signal` aborts, or it returned,
+ * it writes nothing more.
  */
-async function followIncarnation(scene, session, announced, skip, signal, attempt) {
+async function followIncarnation(scene, session, announced, epoch, signal) {
     const { mirror, warn } = scene;
     const none = { epoch: undefined, reason: undefined };
-    const closers = [announced];
+    // Its readers stop with the task's signal, and when this returns.
+    const reading = new AbortController();
+    const closers = [announced, { close: () => reading.abort() }];
     const closeAll = () => { for (const c of closers) {
         try {
             c.close();
@@ -1717,36 +1801,38 @@ async function followIncarnation(scene, session, announced, skip, signal, attemp
         catch { /* closed */ }
     } };
     signal.addEventListener("abort", closeAll, { once: true });
+    const stopped = () => reading.signal.aborted;
     try {
-        let epoch;
-        for (;;) {
-            const u = await announced.next();
-            if (!u || signal.aborted)
-                return none;
-            if (u.kind === "retracted")
-                continue;
-            const e = announcedEpoch(String(u.prefix));
-            if (e !== undefined && e !== skip) {
-                epoch = e;
-                break;
+        // The incarnation the open named, once announced: within the store's bound (an announce/retract pair the cursor never
+        // saw is gone for good; the task opens again).
+        const deadline = setTimeout(() => announced.close(), ANNOUNCE_WITHIN_MS);
+        try {
+            for (;;) {
+                const u = await announced.next();
+                if (!u || stopped())
+                    return none;
+                if (u.kind !== "retracted" && announcedEpoch(String(u.prefix)) === epoch)
+                    break;
             }
         }
-        const at = epoch;
-        // Resolving the broadcast races an end of this epoch already on the cursor.
-        const req = session.request(`${SCENE_BASE}/@${at}`);
+        finally {
+            clearTimeout(deadline);
+        }
+        // Resolving the broadcast races an end of this epoch already on the cursor (opened before the open call).
+        const req = session.request(`${SCENE_BASE}/@${epoch}`);
         closers.push(req);
         const retracted = (async () => { for (;;) {
             const u = await announced.next();
             if (!u)
                 return false;
-            if (u.kind === "retracted" && announcedEpoch(String(u.prefix)) === at)
+            if (u.kind === "retracted" && announcedEpoch(String(u.prefix)) === epoch)
                 return true;
         } })();
         let bc;
         try {
-            const r = await Promise.race([waitActive(req, 10_000, signal).then(b => ({ bc: b })), retracted.then(gone => ({ gone }))]);
+            const r = await Promise.race([waitActive(req, 10_000, reading.signal).then(b => ({ bc: b })), retracted.then(gone => ({ gone }))]);
             if ("gone" in r)
-                return r.gone ? { epoch: at, reason: "ended" } : none;
+                return r.gone ? { epoch, reason: "ended" } : none;
             bc = r.bc;
         }
         catch {
@@ -1754,88 +1840,67 @@ async function followIncarnation(scene, session, announced, skip, signal, attemp
         }
         announced.close();
         closers.push(bc);
-        const authored = new TrackReading(bc.track(AUTHORED_TRACK).subscribe(latestSubscription(moqPriority(1))));
-        const live = new TrackReading(bc.track(LIVE_TRACK).subscribe(latestSubscription(moqPriority(1))));
-        closers.push(authored, live);
-        if (signal.aborted)
+        if (stopped())
             return none;
         let end;
-        const ended = () => ({ epoch: at, reason: end });
+        let keyed = false;
         const onAuthored = (p) => {
-            if (signal.aborted)
-                return false;
+            if (stopped())
+                return "end";
             const f = decodeFrame(p, warn, "authored");
             if (!f)
-                return true;
+                return "read";
             if (f.flags & FLAGS.END) {
                 const r = f.body?.reason;
                 end = typeof r === "string" ? r : "ended";
-                return false;
+                return "end";
             }
             let version;
             if (f.flags & FLAGS.KEY) {
                 const s = f.body;
                 if (!s || typeof s.version !== "number" || !isObject(s.entities)) {
                     warn("scene: snapshot not understood");
-                    return true;
+                    return "read";
                 }
-                mirror.applySnapshot(at, s);
+                mirror.applySnapshot(epoch, s);
                 version = s.version;
             }
             else if (f.flags & FLAGS.DELTA) {
                 const d = f.body;
                 if (!d || typeof d.version !== "number" || !Array.isArray(d.ops)) {
                     warn("scene: diff not understood");
-                    return true;
+                    return "read";
                 }
-                mirror.applyDiff(d, warn);
+                if (!mirror.applyDiff(d, warn))
+                    return "gap";
                 version = d.version;
             }
             else
-                return true;
-            scene.post({ kind: "applied", epoch: at, version });
-            return true;
+                return "read";
+            scene.post({ kind: "applied", epoch, version });
+            return "read";
         };
         const onLive = (p) => {
-            if (signal.aborted)
-                return false;
+            if (stopped())
+                return "end";
             const f = decodeFrame(p, warn, "live");
             if (!f || !isObject(f.body))
-                return true;
-            if (f.flags & FLAGS.KEY)
+                return "read";
+            if (f.flags & FLAGS.KEY) {
                 mirror.applyKeyframe(f.body);
+                if (!keyed) {
+                    keyed = true;
+                    scene.post({ kind: "liveKeyed", epoch });
+                }
+            }
             else if (f.flags & FLAGS.DELTA)
                 mirror.applyLiveTick(f.body);
-            return true;
+            return "read";
         };
-        // Catching up: the first frame of each track (the open group's snapshot, the whole live set),
-        // then every frame this node already holds on either, read without waiting; only then is the
-        // handle `attached` (its version is the scene's as far as this node has it).
-        const a0 = await authored.first();
-        if (signal.aborted)
-            return none;
-        if (!a0)
-            return ended();
-        if (!onAuthored(a0))
-            return ended();
-        const l0 = await live.first();
-        if (signal.aborted)
-            return none;
-        if (!l0)
-            return ended();
-        onLive(l0);
-        authored.drain(onAuthored);
-        if (end !== undefined)
-            return ended();
-        live.drain(onLive);
-        if (signal.aborted)
-            return none;
-        // The task attaches the handle, once the claims are made for this incarnation.
-        scene.post({ kind: "attach", attempt, epoch: at, version: mirror.version });
-        // Then frame by frame as they come. The live track's end is the incarnation's: the authored track says how it ended.
-        void live.readOn(onLive);
-        await authored.readOn(onAuthored);
-        return ended();
+        // The live track's end is the incarnation's: the authored track says how it ended.
+        void readTrack(bc, LIVE_TRACK, reading.signal, onLive);
+        await readTrack(bc, AUTHORED_TRACK, reading.signal, onAuthored);
+        return stopped() ? none : { epoch, reason: end };
     }
     catch {
         return none;
@@ -2073,7 +2138,7 @@ export class SceneHandleImpl {
     #statusNow() {
         const m = this.scene.mirror;
         const state = this.#closed ? "closed" : m.state;
-        return { state, synced: state === "attached" && this.scene.node.isConnected && m.pending === 0 && !m.gap, pending: m.pending, version: m.version, hash: m.hash, detachedDrops: this.scene.detachedDrops, unclaimedDrops: this.scene.unclaimedDrops };
+        return { state, synced: state === "attached" && this.scene.node.isConnected && m.pending === 0 && m.gap === undefined, pending: m.pending, version: m.version, hash: m.hash, detachedDrops: this.scene.detachedDrops, unclaimedDrops: this.scene.unclaimedDrops };
     }
     /** The one boolean a node author checks: `status.get().synced`. */
     get synced() { return this.status.get().synced; }
@@ -2163,28 +2228,41 @@ export class SceneHandleImpl {
         return id;
     }
     /**
-     * The entity named `name`, made to carry `components`; its view (by id). None of that name in the authored scene:
-     * `spawn` (with `parent`). One: its authored row (live overrides never count) is compared with what a `patch` of the
-     * components would make of it; equal, nothing is sent; else a `patch` of the components that differ. `parent` is for
-     * the spawn only (an existing entity is not reparented). One of another kind in the mirror: `spawn` too, and the
-     * runtime answers (the mirror may be stale: `name_taken` with `holder` while the name is held, the spawn when it was
-     * freed). An `id` component: `invalid_input` (`data: { component: "id" }`), nothing sent.
+     * The entity named `name`, made to carry `components`; its view (by id). The id is the runtime's answer, never the
+     * copy's: a `spawn` (with `parent`, a fresh id minted here) is sent first; the runtime refusing it `name_taken` names
+     * the holder and its kind (`data.holder`, `data.kind`, `data.layer`). A holder of this kind in the authored or
+     * calibration layer is patched with the components that differ from what the copy shows of it (all of them when the
+     * copy does not show it yet; equal, nothing more is sent): the copy only trims the patch, it never decides. A holder
+     * of another kind, a live one, or an answer without them: the `name_taken` is raised as it came. `parent` is for the
+     * spawn only (an existing entity is not reparented). Any other refusal is raised as it came (`not_found` on the patch:
+     * the entity went meanwhile; upsert again). An `id` component: `invalid_input` (`data: { component: "id" }`), nothing
+     * sent.
      */
     async #upsert(kind, opts) {
         if (this.#closed)
             throw closedError(ENDED_CLIENT);
         refuseId(opts, "scene.authored.upsert");
         const { name, parent: _parent, ...components } = opts;
-        const found = authoredNamed(this.scene.mirror.authored, name);
-        if (!found || found.kind !== kind)
+        let holder;
+        try {
             return this.entity(await this.#spawn(kind, opts));
-        const row = found;
-        const after = mergeSet(row, components);
+        }
+        catch (e) {
+            if (!(e instanceof SynapseError) || e.code !== "name_taken")
+                throw e;
+            // The runtime's answer decides: the holder, its kind and its layer.
+            const d = (e.data ?? {});
+            if (typeof d.holder !== "string" || d.kind !== kind || (d.layer !== "authored" && d.layer !== "calibration"))
+                throw e;
+            holder = d.holder;
+        }
+        const row = this.scene.mirror.authored.get(holder);
+        const after = row ? mergeSet(row, components) : undefined;
         // Only the components that differ (a patch of `flags` alone is what a locked entity accepts).
-        const differ = Object.fromEntries(Object.entries(components).filter(([k]) => !deepEqual(row[k], after[k])));
+        const differ = Object.fromEntries(Object.entries(components).filter(([k, v]) => v !== undefined && (!row || !deepEqual(row[k], after[k]))));
         if (Object.keys(differ).length)
-            await this.#txn(t => t.patch(found.id, differ));
-        return this.entity(found.id);
+            await this.#txn(t => t.patch(holder, differ));
+        return this.entity(holder);
     }
     // ---- live (`scene.live`)
     /**
@@ -2328,7 +2406,8 @@ export class SceneHandleImpl {
 }
 /**
  * The active project's scene (one per project; one task per node, shared by every handle). Resolves
- * once the handle is attached, or at once `detached` when the runtime says no project is active; the
+ * once the handle is attached (the copy at the version `synapse/scene/open` answered, or past it), or at
+ * once `detached` when the runtime says no project is active; the
  * handle then follows the incarnations as they come and go. Without a session (before the first, between
  * two) the task waits for the next one, like after a drop.
  */