@synapse-sdk/client 0.1.0 → 0.3.0

package/dist/store.js

@@ -0,0 +1,898 @@
+// The store (SDK §9, PLAN v0.20 §7), the JS spelling of the Rust client's `store.rs`: one task per
+// namespace per node, told about sessions by the node's loop (`Node.monitor`), driven by one mailbox.
+// Its intent is the open (`synapse/store/open` with the handle's access mode); admitted, it follows the
+// incarnation the reply names (`runtime/store/<ns>/@<epoch>`, or `runtime/config/@<epoch>`), track
+// `data`: a snapshot, then diffs, then a final frame. The mirror is the runtime's: nothing is decided
+// here. A refusal is asked again, paced, with a warning (R6); a transient reply paced, silently; an
+// incarnation that ends (writer gone, project switch, the owner restarted) replays the intent;
+// `destroyed` ends the handle. Writes name the epoch the mirror holds; the runtime checks ownership
+// (`not_owner`). Between incarnations (a session change, a replay) nothing is known: `store_gone`.
+import * as Moq from "@moq/net";
+import { FLAGS, STORE_CONFIG, STORE_TRACK, SynapseError, decode as decodeBody, decodeHeader, moqPriority, storeBasePath, } from "@synapse-sdk/core";
+import { startOn } from "./calls.js";
+import { REFOLLOW_PACE_MS, holderOf, isTransient, refusalPaceMs } from "./channel.js";
+import { latestSubscription, waitActive } from "./session.js";
+import { AsyncQueue, TIMEOUT, deferred, withTimeout } from "./util.js";
+export const ENDED_DESTROYED = "destroyed";
+export const ENDED_CONNECTION_LOST = "connection_lost";
+export const ENDED_CLIENT = "client";
+const ENDED_STORE_GONE = "store_gone";
+/** A watcher this many batches behind is ended, never grown. */
+export const STORE_FEED_CAP = 256;
+/** How long an incarnation the open's reply named has to show up on the announcement cursor (no "live" marker in @moq/net's JS cursor). */
+const ANNOUNCE_WITHIN_MS = 1000;
+const isFinal = (reason) => reason === ENDED_DESTROYED;
+const gone = (name, why) => new SynapseError("store_gone", `store ${JSON.stringify(name)}: ${why}`);
+// ------------------------------------------------------------------------------------- state
+/** The mirror and what the runtime said about the namespace; written by the task and its reader only. */
+export class State {
+    epoch;
+    version = 0;
+    rows = new Map();
+    flat = new Map();
+    mode;
+    owner;
+    mine = false;
+    claim;
+    minRole;
+    onDeath;
+    absent = false;
+    loaded = false;
+    gap = false;
+    pending = 0;
+    ended;
+    #listeners = new Set();
+    #watchers = new Set();
+    subscribe(l) { this.#listeners.add(l); return () => { this.#listeners.delete(l); }; }
+    #notify() { for (const l of [...this.#listeners]) {
+        try {
+            l();
+        }
+        catch (e) {
+            queueMicrotask(() => { throw e; });
+        }
+    } }
+    watch() {
+        const q = new AsyncQueue(STORE_FEED_CAP, () => { void q.close(true); this.#watchers.delete(q); });
+        if (this.ended !== undefined)
+            void q.close();
+        else
+            this.#watchers.add(q);
+        return q;
+    }
+    /** A feed its reader has left: it is closed and gets nothing more. */
+    unwatch(q) { this.#watchers.delete(q); void q.close(); }
+    #emit(records) {
+        if (records.length)
+            for (const w of [...this.#watchers])
+                w.push(records);
+        this.#notify();
+    }
+    applySnapshot(s) {
+        const records = [];
+        const rows = new Map(Object.entries(s.rows));
+        for (const [k, row] of rows) {
+            const old = this.rows.get(k);
+            if (!old)
+                records.push({ kind: "put", key: k, value: row.v, previousValue: undefined, by: undefined });
+            else if (!sameValue(old.v, row.v))
+                records.push({ kind: "put", key: k, value: row.v, previousValue: old.v, by: undefined });
+        }
+        for (const [k, old] of this.rows)
+            if (!rows.has(k))
+                records.push({ kind: "delete", key: k, previousValue: old.v, by: undefined });
+        this.rows = rows;
+        this.flat = new Map([...rows].map(([k, r]) => [k, r.v]));
+        this.version = s.version;
+        this.epoch = s.epoch;
+        this.mode = s.mode;
+        this.owner = s.owner ?? undefined;
+        this.minRole = s.min_role;
+        this.onDeath = s.on_death;
+        this.absent = false;
+        this.loaded = true;
+        this.gap = false;
+        this.#emit(records);
+    }
+    applyDiff(d, warn) {
+        if (d.version !== this.version + 1) {
+            warn(`store: diff out of sequence (have ${this.version}, got ${d.version}); not synced until the next snapshot`);
+            this.gap = true;
+        }
+        const records = [];
+        const flat = new Map(this.flat);
+        for (const [k, row] of Object.entries(d.changed)) {
+            const prev = this.rows.get(k);
+            if (!prev || !sameValue(prev.v, row.v))
+                records.push({ kind: "put", key: k, value: row.v, previousValue: prev?.v, by: d.by });
+            flat.set(k, row.v);
+            this.rows.set(k, row);
+        }
+        for (const k of d.removed) {
+            flat.delete(k);
+            const old = this.rows.get(k);
+            if (old) {
+                this.rows.delete(k);
+                records.push({ kind: "delete", key: k, previousValue: old.v, by: d.by });
+            }
+        }
+        this.flat = flat;
+        this.version = d.version;
+        this.#emit(records);
+    }
+    #clear() {
+        const records = [...this.rows].map(([key, r]) => ({ kind: "delete", key, previousValue: r.v, by: undefined }));
+        this.rows = new Map();
+        this.flat = new Map();
+        this.#emit(records);
+    }
+    /** Nothing of the incarnation is known until the runtime answers the next open. */
+    reset() {
+        if (this.ended !== undefined)
+            return;
+        this.#clear();
+        this.epoch = undefined;
+        this.version = 0;
+        this.loaded = false;
+        this.gap = false;
+        this.mode = undefined;
+        this.owner = undefined;
+        this.mine = false;
+        this.claim = undefined;
+        this.minRole = undefined;
+        this.onDeath = undefined;
+        this.absent = false;
+        this.#notify();
+    }
+    opened(a) {
+        if (this.ended !== undefined)
+            return;
+        this.epoch = undefined;
+        this.version = 0;
+        this.loaded = false;
+        this.gap = false;
+        this.mode = a?.mode;
+        this.owner = a?.owner ?? undefined;
+        this.mine = a?.mine ?? false;
+        this.claim = a?.claim;
+        this.minRole = a?.min_role;
+        this.onDeath = a?.on_death;
+        this.absent = a === undefined;
+        this.#notify();
+    }
+    end(reason) {
+        if (this.ended !== undefined)
+            return;
+        this.#clear();
+        this.ended = reason;
+        this.absent = false;
+        for (const w of this.#watchers)
+            void w.close();
+        this.#watchers.clear();
+        this.#notify();
+    }
+    setPending(n) { this.pending = n; this.#notify(); }
+    /** The status a handle reports: a closed handle (`closed`) has ended (`client`) whatever the namespace does. */
+    status(nodeConnected, closed = false) {
+        const ended = closed ? ENDED_CLIENT : this.ended;
+        const connected = ended === undefined && nodeConnected;
+        return { synced: connected && this.pending === 0 && !this.gap && (this.loaded || this.absent), connected, pending: this.pending, mode: this.mode, owner: this.owner, mine: this.mine, minRole: this.minRole, onDeath: this.onDeath, absent: this.absent, version: this.version, epoch: this.epoch, ended };
+    }
+}
+function sameValue(a, b) {
+    if (a === b)
+        return true;
+    if (a instanceof Uint8Array && b instanceof Uint8Array)
+        return a.length === b.length && a.every((x, i) => x === b[i]);
+    if (typeof a !== "object" || typeof b !== "object" || !a || !b)
+        return false;
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    const ka = Object.keys(a), kb = Object.keys(b);
+    if (ka.length !== kb.length)
+        return false;
+    for (const k of ka)
+        if (!sameValue(a[k], b[k]))
+            return false;
+    return true;
+}
+/** The namespace shared by its handles and its task. */
+export class Namespace {
+    name;
+    opts;
+    node;
+    warn;
+    state = new State();
+    mailbox = new AsyncQueue(Infinity);
+    exited = deferred();
+    handles = 0;
+    constructor(name, opts, node, warn) {
+        this.name = name;
+        this.opts = opts;
+        this.node = node;
+        this.warn = warn;
+    }
+    post(e) { return this.mailbox.push(e); }
+    request(make) {
+        const reply = deferred();
+        if (!this.post(make(reply)))
+            return Promise.reject(gone(this.name, "the handle ended"));
+        return reply.promise;
+    }
+}
+export function startNamespace(ns, registry) { void run(ns, registry); }
+async function run(ns, registry) {
+    const { name, opts, state, warn, node } = ns;
+    const post = (e) => { ns.post(e); };
+    const config = name === STORE_CONFIG;
+    let session;
+    let phase = { kind: "idle" };
+    const ph = () => phase;
+    let attempts = 0;
+    let refusals = 0;
+    let destroying = 0;
+    /** The version the open reply named: the value is "in" (a `join` answered) once the mirror has reached it. */
+    let wanted = 0;
+    /** The active project as last known (project namespaces): `undefined` = no snapshot yet. */
+    let known;
+    let unwatchProject;
+    const joining = [];
+    let versionWaiters = [];
+    const leaveIncarnation = () => { for (const w of versionWaiters.splice(0))
+        w.reply.reject(gone(name, `the handle left the incarnation before version ${w.version}`)); };
+    const stopPhase = () => {
+        if (phase.kind === "following")
+            phase.stop.abort();
+        else if (phase.kind === "paced")
+            clearTimeout(phase.timer);
+        else if (phase.kind === "opening")
+            phase.o.announced.close();
+    };
+    const idle = () => { stopPhase(); phase = { kind: "idle" }; };
+    /** Writes the open on the task's session, from `idle`, when nothing holds it back. */
+    const open = () => {
+        if (phase.kind !== "idle" || destroying > 0 || state.ended !== undefined || !session)
+            return;
+        const s = session;
+        leaveIncarnation();
+        attempts += 1;
+        const attempt = attempts;
+        let announced;
+        try {
+            announced = s.sub.announced(Moq.Path.Pattern.parse(`${storeBasePath(name)}/*`));
+        }
+        catch (e) {
+            warn(`store ${name}: announcement cursor refused: ${e instanceof Error ? e.message : String(e)}`);
+            return;
+        }
+        const args = { namespace: name };
+        if (opts.access)
+            args.access = opts.access;
+        if (opts.onDeath)
+            args.on_death = opts.onDeath;
+        try {
+            const run = startOn(node, s, "synapse/store/open", args, {});
+            phase = { kind: "opening", o: { attempt, session: s, announced, again: undefined } };
+            void run.result.then(v => post({ kind: "opened", attempt, result: { ok: v } }), (e) => post({ kind: "opened", attempt, result: { err: e instanceof SynapseError ? e : new SynapseError("internal", String(e)) } }));
+        }
+        catch {
+            announced.close(); /* the session is going: its end is on its way */
+        }
+    };
+    /** The intent is asked again after `paceMs`: the mirror resets. With an open outstanding, once that is answered. */
+    const again = (paceMs) => {
+        state.reset();
+        if (phase.kind === "opening") {
+            phase.o.again = paceMs;
+            return;
+        }
+        stopPhase();
+        const a = attempts;
+        phase = { kind: "paced", timer: setTimeout(() => post({ kind: "paced", attempt: a }), paceMs) };
+    };
+    /**
+     * The node's session is now `s` (or none). The reader of the previous session is stopped and its end
+     * awaited before the mirror resets, so nothing of it lands on the next incarnation; a final frame it
+     * had already been handed is the runtime's statement: `destroyed` ends the handle, returned as the
+     * reason (no open is written).
+     */
+    const sessionChanged = async (s) => {
+        if (phase.kind === "following") {
+            const { stop, done } = phase;
+            stop.abort();
+            const r = await done;
+            if (r !== undefined && isFinal(r))
+                return r;
+        }
+        session = s;
+        idle();
+        leaveIncarnation();
+        state.reset();
+        unwatchProject?.();
+        unwatchProject = undefined;
+        if (s && !config) {
+            const feed = s.project;
+            const current = feed.get();
+            if (known === undefined)
+                known = current ? current.active : undefined;
+            else if (current)
+                post({ kind: "projectChanged", now: current.active });
+            unwatchProject = feed.subscribe(p => { if (p)
+                post({ kind: "projectChanged", now: p.active }); });
+        }
+        open();
+        return undefined;
+    };
+    const opened = (attempt, result) => {
+        if (phase.kind !== "opening" || phase.o.attempt !== attempt)
+            return;
+        const { announced, again: due, session: s } = phase.o;
+        phase = { kind: "idle" };
+        if ("err" in result && (result.err.code === "connection_lost" || result.err.code === "not_connected")) {
+            announced.close();
+            session = undefined;
+            return;
+        }
+        if (due !== undefined) {
+            announced.close();
+            const a = attempts;
+            phase = { kind: "paced", timer: setTimeout(() => post({ kind: "paced", attempt: a }), due) };
+            return;
+        }
+        if ("ok" in result) {
+            let access;
+            try {
+                access = parseOpen(result.ok);
+            }
+            catch (e) {
+                announced.close();
+                warn(`store ${name}: open reply not understood (${e instanceof Error ? e.message : String(e)}); asked again`);
+                again(REFOLLOW_PACE_MS);
+                return;
+            }
+            refusals = 0;
+            state.opened(access);
+            wanted = access?.version ?? 0;
+            const stop = new AbortController();
+            const done = follow(ns, s, announced, access?.epoch, stop.signal);
+            phase = { kind: "following", attempt, stop, done };
+            void done.then(reason => post({ kind: "followEnded", attempt, reason }));
+            if (!access)
+                for (const j of joining.splice(0))
+                    j.resolve();
+            return;
+        }
+        announced.close();
+        const e = result.err;
+        if (isTransient(e)) {
+            again(REFOLLOW_PACE_MS);
+            return;
+        }
+        if (e.code === "project_inactive") {
+            for (const j of joining.splice(0))
+                j.reject(e);
+            phase = { kind: "waitingProject", before: known };
+            return;
+        }
+        refusals += 1;
+        const pace = refusalPaceMs(refusals);
+        warn(`store ${name}: open refused by the runtime (${e.code}${e.message ? `: ${e.message}` : ""}; holder ${holderOf(e) ?? "-"}; attempt ${refusals}; again in ${pace} ms)`);
+        again(pace);
+    };
+    const applied = (epoch, version) => {
+        const reached = versionWaiters.filter(w => w.epoch === epoch && w.version <= version);
+        versionWaiters = versionWaiters.filter(w => !reached.includes(w));
+        for (const w of reached)
+            w.reply.resolve();
+        // In = the mirror holds what the runtime named at the open (its version), not just a first snapshot.
+        if (state.loaded && state.epoch === epoch && state.version >= wanted)
+            for (const j of joining.splice(0))
+                j.resolve();
+    };
+    const join = (reply) => {
+        if (phase.kind === "waitingProject") {
+            reply.reject(new SynapseError("project_inactive"));
+            return;
+        }
+        if (state.absent || (state.loaded && state.version >= wanted))
+            reply.resolve();
+        else
+            joining.push(reply);
+    };
+    const waitVersion = (epoch, version, reply) => {
+        if (state.ended !== undefined || state.epoch !== epoch) {
+            reply.reject(gone(name, `the handle left the incarnation before version ${version}`));
+            return;
+        }
+        if (state.version >= version) {
+            reply.resolve();
+            return;
+        }
+        versionWaiters.push({ epoch, version, reply });
+    };
+    const projectChanged = (now) => {
+        if (phase.kind === "waitingProject") {
+            if (!sameProject(now, phase.before)) {
+                known = now;
+                phase = { kind: "idle" };
+                open();
+            }
+            return;
+        }
+        if (known === undefined || !sameProject(known, now)) {
+            known = now;
+            if (phase.kind === "opening" || phase.kind === "following")
+                again(REFOLLOW_PACE_MS);
+        }
+    };
+    const write = (op, args, reply) => {
+        if (state.ended !== undefined) {
+            reply.reject(gone(name, `the handle ended (${state.ended})`));
+            return;
+        }
+        const epoch = state.epoch;
+        if (epoch === undefined) {
+            reply.reject(state.absent ? gone(name, "the namespace is absent: open it with an access mode to create it") : gone(name, "no incarnation is bound: the intent is being replayed"));
+            return;
+        }
+        if (!session) {
+            reply.reject(new SynapseError("not_connected"));
+            return;
+        }
+        const w = { namespace: name, epoch };
+        if (state.claim !== undefined)
+            w.claim = state.claim;
+        if (args.key !== undefined)
+            w.key = args.key;
+        if (args.value !== undefined)
+            w.value = args.value;
+        if (args.values !== undefined)
+            w.values = args.values;
+        let run;
+        try {
+            run = startOn(node, session, `synapse/store/${op}`, w, {});
+        }
+        catch (e) {
+            reply.reject(e instanceof SynapseError ? e : new SynapseError("internal", String(e)));
+            return;
+        }
+        if (op === "destroy")
+            destroying += 1;
+        state.setPending(state.pending + 1);
+        void run.result.then(v => post({ kind: "writeDone", op, result: { ok: v }, reply }), (e) => post({ kind: "writeDone", op, result: { err: e instanceof SynapseError ? e : new SynapseError("internal", String(e)) }, reply }));
+    };
+    /** `true` when it ends the handle (a confirmed destroy). */
+    const writeDone = (op, result, reply) => {
+        state.setPending(state.pending - 1);
+        const destroyed = op === "destroy" && "ok" in result;
+        if (op === "destroy")
+            destroying -= 1;
+        if (destroyed)
+            state.end(ENDED_DESTROYED);
+        if ("ok" in result)
+            reply.resolve(result.ok);
+        else
+            reply.reject(result.err);
+        if (!destroyed)
+            open();
+        return destroyed;
+    };
+    const endingError = () => state.ended === undefined || state.ended === ENDED_CONNECTION_LOST
+        ? new SynapseError("connection_lost", `store ${JSON.stringify(name)}: the node ended before the namespace was read`)
+        : gone(name, `the handle ended before the namespace was read (${state.ended})`);
+    const { session: first, unmonitor } = node.monitor((e) => ns.post(e.kind === "started" ? { kind: "session", session: e.session } : e.kind === "ended" ? { kind: "sessionEnded" } : { kind: "nodeEnded" }));
+    let reason = null; // null: no reason (a destroy ended it)
+    try {
+        await sessionChanged(first); // no reader yet: it cannot end the handle
+        loop: for (;;) {
+            const ev = await ns.mailbox.next();
+            if (!ev) {
+                reason = undefined;
+                break;
+            }
+            switch (ev.kind) {
+                case "session":
+                case "sessionEnded": {
+                    const r = await sessionChanged(ev.kind === "session" ? ev.session : undefined);
+                    if (r !== undefined) {
+                        reason = r;
+                        break loop;
+                    }
+                    break;
+                }
+                case "nodeEnded":
+                    reason = ENDED_CONNECTION_LOST;
+                    break loop;
+                case "opened":
+                    opened(ev.attempt, ev.result);
+                    break;
+                case "applied":
+                    applied(ev.epoch, ev.version);
+                    break;
+                case "followEnded": {
+                    // A final frame is the runtime's statement about the namespace: `destroyed` ends the handle,
+                    // whichever reader (current or already stopped) was handed it; every other end of the current
+                    // reader replays the intent, and of a stopped one is already dealt with.
+                    if (ev.reason !== undefined && isFinal(ev.reason)) {
+                        reason = ev.reason;
+                        break loop;
+                    }
+                    {
+                        const p = ph();
+                        if (p.kind !== "following" || p.attempt !== ev.attempt)
+                            break;
+                    }
+                    phase = { kind: "idle" };
+                    again(REFOLLOW_PACE_MS);
+                    break;
+                }
+                case "join":
+                    join(ev.reply);
+                    break;
+                case "waitVersion":
+                    waitVersion(ev.epoch, ev.version, ev.reply);
+                    break;
+                case "write":
+                    write(ev.op, ev.args, ev.reply);
+                    break;
+                case "writeDone":
+                    if (writeDone(ev.op, ev.result, ev.reply)) {
+                        reason = undefined;
+                        break loop;
+                    }
+                    break;
+                case "projectChanged":
+                    if (!config)
+                        projectChanged(ev.now);
+                    break;
+                case "paced":
+                    if (ph().kind === "paced" && ev.attempt === attempts) {
+                        phase = { kind: "idle" };
+                        open();
+                    }
+                    break;
+                case "close":
+                    reason = ENDED_CLIENT;
+                    break loop;
+            }
+        }
+    }
+    finally {
+        unmonitor();
+        unwatchProject?.();
+        if (reason !== null && reason !== undefined)
+            state.end(reason);
+        const e = endingError();
+        for (const j of joining.splice(0))
+            j.reject(e);
+        leaveIncarnation();
+        {
+            const p = ph();
+            if (p.kind === "following" || p.kind === "paced")
+                idle();
+        }
+        // Every write in flight is answered to its caller before the task ends; an open in flight is waited out.
+        while (state.pending > 0 || ph().kind === "opening") {
+            const ev = await ns.mailbox.next();
+            if (!ev)
+                break;
+            if (ev.kind === "writeDone")
+                writeDone(ev.op, ev.result, ev.reply);
+            else if (ev.kind === "write")
+                write(ev.op, ev.args, ev.reply);
+            else if (ev.kind === "opened") {
+                const p = ph();
+                if (p.kind === "opening" && p.o.attempt === ev.attempt) {
+                    p.o.announced.close();
+                    phase = { kind: "idle" };
+                }
+            }
+            else if (ev.kind === "join")
+                ev.reply.reject(e);
+            else if (ev.kind === "waitVersion")
+                ev.reply.reject(gone(name, "the handle ended"));
+        }
+        if (state.ended === undefined)
+            state.end(reason ?? ENDED_CLIENT);
+        // The mailbox takes nothing more (a request now fails at once); what is still queued is answered.
+        void ns.mailbox.close();
+        for (let ev = ns.mailbox.tryNext(); ev; ev = ns.mailbox.tryNext()) {
+            if (ev.kind === "write")
+                ev.reply.reject(gone(name, `the handle ended (${state.ended})`));
+            else if (ev.kind === "join")
+                ev.reply.reject(e);
+            else if (ev.kind === "waitVersion")
+                ev.reply.reject(gone(name, "the handle ended"));
+        }
+        if (registry.get(name) === ns)
+            registry.delete(name);
+        ns.exited.resolve();
+    }
+}
+const sameProject = (a, b) => (a === b) || (!!a && !!b && a.id === b.id && a.since_us === b.since_us);
+/** An open's reply: `undefined` = absent. */
+function parseOpen(reply) {
+    if (!reply || typeof reply !== "object")
+        throw new Error("not a map");
+    const r = reply;
+    if (r.absent === true)
+        return undefined;
+    if (typeof r.epoch !== "string" || typeof r.mode !== "string")
+        throw new Error("no epoch/mode");
+    return r;
+}
+/** The epoch of an announced prefix under the namespace's base path (`<base>/@<epoch>`). */
+function announcedEpoch(base, prefix) {
+    if (!prefix.startsWith(`${base}/@`))
+        return undefined;
+    const e = prefix.slice(base.length + 2);
+    return e && !e.includes("/") ? e : undefined;
+}
+/**
+ * Reads the incarnation the open bound (`want`; `undefined`: absent, the first one announced), writing
+ * the mirror and telling the task of each frame applied; returns how the track ended (`undefined`:
+ * no final frame — the session, or the broker, went; the task replays).
+ */
+async function follow(ns, session, announced, want, signal) {
+    const { state, warn, name } = ns;
+    const base = storeBasePath(name);
+    const onAbort = () => announced.close();
+    signal.addEventListener("abort", onAbort, { once: true });
+    let sub;
+    try {
+        // The incarnation: ours, or, absent, the first announced. One the reply named has a bound to show up on the cursor (an announce/retract pair the cursor never saw is gone for good): then the runtime is asked again.
+        let epoch;
+        const deadline = want !== undefined ? setTimeout(() => announced.close(), ANNOUNCE_WITHIN_MS) : undefined;
+        try {
+            for (;;) {
+                const u = await announced.next();
+                if (!u)
+                    return undefined;
+                if (u.kind === "retracted")
+                    continue;
+                const e = announcedEpoch(base, String(u.prefix));
+                if (e !== undefined && (want === undefined || want === e)) {
+                    epoch = e;
+                    break;
+                }
+            }
+        }
+        finally {
+            if (deadline !== undefined)
+                clearTimeout(deadline);
+        }
+        // Resolving the broadcast races an end of this epoch already on the cursor.
+        const req = session.request(`${base}/@${epoch}`);
+        const retracted = (async () => { for (;;) {
+            const u = await announced.next();
+            if (!u)
+                return false;
+            if (u.kind === "retracted" && announcedEpoch(base, 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(r => ({ gone: r }))]);
+            if ("gone" in r) {
+                req.close();
+                return r.gone ? ENDED_STORE_GONE : undefined;
+            }
+            bc = r.bc;
+        }
+        catch {
+            req.close();
+            return undefined;
+        }
+        announced.close();
+        sub = bc.track(STORE_TRACK).subscribe(latestSubscription(moqPriority(1)));
+        const s = sub;
+        // Closing the subscriber ends `recvGroup`, not a read on the group it already handed us: that group is closed too.
+        let g;
+        signal.addEventListener("abort", () => { s.close(); g?.close(); }, { once: true });
+        // The first group read is the open one, from its start: a snapshot, then the diffs.
+        for (;;) {
+            g = await s.recvGroup();
+            if (!g)
+                break;
+            for (;;) {
+                let f;
+                try {
+                    f = await g.readFrame();
+                }
+                catch {
+                    break;
+                }
+                if (!f)
+                    break;
+                let header, hlen;
+                try {
+                    ({ header, hlen } = decodeHeader(f.payload));
+                }
+                catch {
+                    warn(`store ${name}: frame not decodable`);
+                    continue;
+                }
+                let body;
+                try {
+                    body = decodeBody(f.payload.subarray(hlen));
+                }
+                catch {
+                    warn(`store ${name}: frame body not decodable`);
+                    continue;
+                }
+                if (header.flags & FLAGS.END) {
+                    const fin = body;
+                    return fin && typeof fin.reason === "string" ? fin.reason : ENDED_STORE_GONE;
+                }
+                // A stopped reader no longer writes the mirror: it belongs to the next incarnation (or to none).
+                if (header.flags & FLAGS.KEY) {
+                    const snap = body;
+                    if (!snap || snap.epoch !== epoch) {
+                        warn(`store ${name}: snapshot of another epoch dropped`);
+                        continue;
+                    }
+                    if (signal.aborted)
+                        continue;
+                    if (state.ended === undefined)
+                        state.applySnapshot(snap);
+                    ns.post({ kind: "applied", epoch, version: snap.version });
+                }
+                else if (header.flags & FLAGS.DELTA) {
+                    const diff = body;
+                    if (!diff || typeof diff.version !== "number") {
+                        warn(`store ${name}: diff not decodable`);
+                        continue;
+                    }
+                    if (signal.aborted)
+                        continue;
+                    if (state.ended === undefined && state.loaded)
+                        state.applyDiff(diff, warn);
+                    ns.post({ kind: "applied", epoch, version: diff.version });
+                }
+            }
+        }
+        return undefined; // the track ended with no final frame: the session (or the broker) went
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        signal.removeEventListener("abort", onAbort);
+        try {
+            sub?.close();
+        }
+        catch { /* closed */ }
+        announced.close();
+    }
+}
+// ------------------------------------------------------------------------------------ handle
+/** The application's handle on a namespace: the last one closed ends the task. */
+export class StoreHandleImpl {
+    ns;
+    #closed = false;
+    /** Resolved when this handle closes: its version waits end. */
+    #left = deferred();
+    /** This handle's change feeds: closed with it. */
+    #feeds = new Set();
+    #valueObj;
+    #valueOf;
+    constructor(ns) {
+        this.ns = ns;
+        ns.handles++;
+    }
+    #ended() { return gone(this.ns.name, `the handle ended (${ENDED_CLIENT})`); }
+    get name() { return this.ns.name; }
+    /** The whole value, what the runtime has; the same object while nothing changed (reference-stable for React). */
+    get value() {
+        const flat = this.ns.state.flat;
+        if (this.#valueOf !== flat) {
+            this.#valueOf = flat;
+            this.#valueObj = Object.fromEntries(flat);
+        }
+        return this.#valueObj;
+    }
+    get(key) { return this.ns.state.flat.get(key); }
+    get synced() { return this.status.synced; }
+    get status() { return this.ns.state.status(this.ns.node.isConnected, this.#closed); }
+    /** `set(key, value)` or `set({ ...several keys })` (one atomic write); resolves once `value` shows it. */
+    async set(keyOrValues, value) {
+        const v = typeof keyOrValues === "string" ? await this.#write("put", { key: keyOrValues, value }) : await this.#write("put_many", { values: keyOrValues });
+        await this.#reached(v);
+    }
+    async delete(key) { await this.#reached(await this.#write("delete", { key })); }
+    async clear() { await this.#reached(await this.#write("clear", {})); }
+    async destroy() { await this.#write("destroy", {}); }
+    /** The wire half of a write: the runtime's answer, the version it assigned. */
+    async #write(op, args) {
+        if (this.#closed)
+            throw this.#ended();
+        const r = await this.ns.request(reply => ({ kind: "write", op, args, reply }));
+        const v = r?.version;
+        return typeof v === "number" ? v : typeof v === "bigint" ? Number(v) : 0;
+    }
+    /** The echo half: the mirror has applied `version` of the bound incarnation (`store_gone` if it changes first). */
+    #reached(version) {
+        const epoch = this.ns.state.epoch;
+        if (this.#closed)
+            return Promise.reject(this.#ended());
+        if (epoch === undefined)
+            return Promise.reject(gone(this.ns.name, `no incarnation is bound (the write of version ${version} may have landed on the previous one)`));
+        const waited = this.ns.request(reply => ({ kind: "waitVersion", epoch, version, reply }));
+        return Promise.race([waited, this.#left.promise.then(() => { throw this.#ended(); })]);
+    }
+    /** `for await (const value of store.watch())`: the whole value after each change; `store.watch(key)`: that key's value each time it changes. Ends with the handle; leaving the loop removes the feed. */
+    async *watch(key) {
+        if (this.#closed)
+            return;
+        const q = this.ns.state.watch();
+        this.#feeds.add(q);
+        try {
+            for await (const batch of q) {
+                if (key === undefined)
+                    yield this.value;
+                else if (batch.some(c => c.key === key))
+                    yield this.ns.state.flat.get(key);
+            }
+        }
+        finally {
+            this.#feeds.delete(q);
+            this.ns.state.unwatch(q);
+        }
+    }
+    /** The framework bridge (React's `useStore`): called on every change of the value or the status. */
+    subscribe(listener) { return this.ns.state.subscribe(listener); }
+    /** Waits for the namespace to be in (the first snapshot applied, or absent). */
+    join() { return this.ns.request(reply => ({ kind: "join", reply })); }
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#left.resolve();
+        for (const q of this.#feeds)
+            this.ns.state.unwatch(q);
+        this.#feeds.clear();
+        if (--this.ns.handles === 0)
+            this.ns.post({ kind: "close" });
+    }
+    async [Symbol.asyncDispose]() { this.close(); }
+}
+/**
+ * `store(name, opts)`: one task per namespace per node; a second `store` with the same options joins
+ * it (no open written), with other options `invalid_input`; one exiting is waited out.
+ */
+export async function openStore(node, registry, name, opts, warn) {
+    if (!node.currentSession())
+        throw new SynapseError("not_connected");
+    for (;;) {
+        const live = registry.get(name);
+        if (live) {
+            if (live.handles === 0) {
+                await live.exited.promise;
+                continue;
+            }
+            if (live.opts.access !== opts.access || live.opts.onDeath !== opts.onDeath)
+                throw new SynapseError("invalid_input", `store ${JSON.stringify(name)}: this node already has it open with other options`);
+            const h = new StoreHandleImpl(live);
+            try {
+                await h.join();
+            }
+            catch (e) {
+                h.close();
+                throw e;
+            }
+            return h;
+        }
+        const ns = new Namespace(name, opts, node, warn);
+        registry.set(name, ns);
+        const h = new StoreHandleImpl(ns);
+        startNamespace(ns, registry);
+        try {
+            await h.join();
+        }
+        catch (e) {
+            h.close();
+            throw e;
+        }
+        return h;
+    }
+}