fix: un second doc_subscribe tuait le premier, et les inbox n'étaient lues qu'à la connexion

packages/polyfill/src/emulated-verifier/connect.ts

@@ -7,7 +7,7 @@
  * like "the share did not work" rather than "nobody processed the queue". So the
  * moment an identity is connected ({@link setCurrentUser}), this runs.
  *
- * Two steps, in order, and the order matters:
+ * Three steps, in order, and the order matters:
  *
  *   1. **Restore** — replay the durable registers back into what this user holds. All of
  *      them: the Store branches of its three stores (the emulated `AddRepo { read_cap }` —
@@ -16,9 +16,13 @@
  *      a handful of reads, no inbox needed.
  *   2. **Process** — drain the user's inbox (`inbox.processInbox`), which files any
  *      new Link durably and puts it among what the user holds.
+ *   3. **Keep applying** — start watching those same inboxes, for as long as this identity
+ *      stays connected (`emulated-verifier/inbox-observer.ts`). Step 2 is the backlog;
+ *      this is the regime.
  *
  * Restoring first means a reconnecting user can read its documents immediately, without
- * waiting on the inbox round-trip.
+ * waiting on the inbox round-trip; watching last means the backlog is applied before the
+ * first push arrives to apply it again.
  *
  * ── Restoring means ALL the registers, and that is a scar ─────────────────
  * Until 2026-08-16 this step read the Links and nothing else, so a fresh page put back the
@@ -46,12 +50,21 @@
  * both are answered by the same place — `AddInboxCap` records on the User branch
  * (`engine/repo/src/types.rs:1969`) — so `storeRegistry.myInboxes()` enumerates
  * them and this drains each in turn.
+ *
+ * ── And then it KEEPS going ───────────────────────────────────────────────
+ * Step 2 drains the backlog; it does not end the obligation. Upstream the backlog is the
+ * exception (`from_queue`) and the rule is that a session applies each message as it
+ * arrives, so connecting ends by starting the continuous observation of the same inboxes
+ * (`emulated-verifier/inbox-observer.ts`), which lasts as long as this identity is
+ * connected. Until 2026-08-17 there was no step 3, and a deposit made while its recipient
+ * sat connected in front of the application converged only when that person reloaded.
  */
 
 import { getCaps, getCurrentUser } from "../shared-wallet/bootstrap";
 import { lookupAccount } from "../shared-wallet/account-registry";
 import { accessLogPrefix, shortNuri } from "../shared-wallet/access-log";
 import { myInboxes, readLinks, restoreOwnCaps } from "./branch-registers";
+import { startObservingInboxes } from "./inbox-observer";
 import { processInbox } from "../surface/inbox";
 import type { Nuri } from "../model/types";
 
@@ -126,7 +139,7 @@ const inFlight = new Map<string, Promise<void>>();
  * Not fixed with a retry, a timeout or a flag on purpose: deciding *what to do* about a
  * broker that cannot answer belongs to the caller, and it can only decide if it is told.
  */
-// @provenance connectedUser kind=aligned level=1 ref=engine/verifier/src/verifier.rs:inbox — upstream the verifier restores and processes with nothing for a caller to await; this is the awaitable form, for a deterministic start
+// @provenance connectedUser kind=aligned level=1 ref=engine/verifier/src/verifier.rs:inbox — upstream the verifier restores, applies the queue handed over at connection and keeps applying what follows, with nothing for a caller to await; this is the awaitable form of the first two, for a deterministic start
 export async function connectedUser(): Promise<void> {
   const holder = getCurrentUser();
   if (holder === null) return;
@@ -165,7 +178,18 @@ export async function connectedUser(): Promise<void> {
     // success. That is how sharing broke once (`.project/concepts/sign-in/`
     // `knowledge_settling-is-not-connecting`), and conflating absence with ignorance is
     // the same fault `inbox.share` was fixed for on 2026-08-10.
-    if ((await lookupAccount(holder)) === null) return;
+    if ((await lookupAccount(holder)) === null) {
+      // Nothing to restore and no queue to drain — but this identity is CONNECTED, and it
+      // will acquire both during the session: provisioning is lazy here, so a person's very
+      // first visit connects with no stores at all and gets its account the moment the
+      // application creates anything. Watching from now on provisions nothing (`myInboxes`
+      // answers `[]` for an identity with no account) and is what makes that first session
+      // behave like every other one — the alternative was a brand-new user watched from
+      // their SECOND visit onwards, which is precisely the person most likely to be sent
+      // something.
+      if (stillConnected()) await startObservingInboxes();
+      return;
+    }
     if (!stillConnected()) return;
     // 1. Durable first, and ALL of it — see the header. The documents this user MADE, from
     //    the Store branches of its own stores, and then the caps it was GIVEN, from the
@@ -202,6 +226,24 @@ export async function connectedUser(): Promise<void> {
         reportUndrained(inbox, error);
       }
     }
+    // 3. …and from here on, KEEP applying. The backlog above is the special case, not the
+    //    rule: upstream a session is handed each inbox message as it arrives and applies it
+    //    inline, and only the messages waiting at connection are the "queue"
+    //    (`from_queue`). Draining once and stopping made a deposit wait for the recipient
+    //    to reload the page. See `emulated-verifier/inbox-observer.ts`.
+    //
+    //    After the drain, not before: connecting owes the backlog first, and the
+    //    observation subscribes to the same inboxes this loop just read.
+    //
+    //    Unconditional on the loop's outcome, deliberately. An inbox that could not be
+    //    drained is reported and denies nobody their session, and it must not deny them the
+    //    observation of the OTHER inboxes either — nor of itself, since the next push is a
+    //    fresh attempt at exactly the deposit that failed.
+    //    Awaited, and it never rejects: what connecting starts, connecting finishes, so a
+    //    caller that got its promise back knows the watching is in place — not merely
+    //    requested. (It does not wait for the applying that watching then triggers.)
+    if (!stillConnected()) return;
+    await startObservingInboxes();
   })();
 
   inFlight.set(holder, run);

packages/polyfill/src/emulated-verifier/inbox-drain.ts

@@ -0,0 +1,83 @@
+/**
+ * ONE drain at a time per inbox — the serializer both things that drain an inbox go through.
+ *
+ * Two of them exist in this package, and they are not coordinated by anything else: the
+ * CONTINUOUS observation of the connected identity's own inboxes
+ * (`emulated-verifier/inbox-observer.ts`) and the deferred timer that stands in for an
+ * ABSENT owner (`emulated-verifier/inbox-processor.ts`). Both can be pointed at the same
+ * inbox in the same page — a deposit into an inbox whose owner is also connected here arms
+ * the timer AND pushes to the observation.
+ *
+ * Draining writes what it applies (`branch-registers.addLink`, on the owner's User branch),
+ * so two passes over one queue interleave their reads and writes and apply the same records
+ * twice. Sequencing them is the same reasoning `connect.connectedUser` drains its inboxes
+ * one after another for, and it belongs HERE rather than in either caller: an invariant that
+ * holds only while both callers remember it is not an invariant.
+ *
+ * It is a queue, not a lock: a run that arrives while another is going is not dropped, it
+ * follows. Dropping would be wrong — the second run exists because something new landed.
+ */
+
+import { accessLogPrefix, shortNuri } from "../shared-wallet/access-log";
+import type { Nuri } from "../model/types";
+
+/** Drains in flight or queued, per inbox — the chain a new run appends itself to. */
+const running = new Map<Nuri, Promise<void>>();
+
+/**
+ * Where a drain's failure goes.
+ *
+ * It cannot throw: nothing awaits these — neither the timer nor a push is a caller — and an
+ * unhandled rejection would take down whatever runtime it is in over work the application
+ * never requested. But "nowhere" is not the alternative. A drain that swallows its failure
+ * is indistinguishable from one that succeeded, which is precisely the defect family removed
+ * from this package on 2026-08-13, and a CONTINUOUS drain that swallowed would repeat that
+ * silence for as long as the session lasts. So it goes to the package's own log stream — the
+ * same `console.error` with the same `[<identity>][polyfill]` prefix `startConnect` and
+ * `inbox.watch` use — and it is NOT gated by the access-log flag: a diagnostic may be
+ * opt-in, a failure may not.
+ *
+ * One failed item denies nothing, here as at connection: the inbox is not consumed by
+ * failing, the deposit stays in it, and the next push or the next connection applies it.
+ */
+function reportFailure(inbox: Nuri, error: unknown): void {
+  console.error(
+    accessLogPrefix() + " could not apply what is in this inbox — its deposits stay in it " +
+      "and the next attempt will try again: " + shortNuri(inbox) + ":",
+    error,
+  );
+}
+
+/**
+ * Run `process` for `inbox`, behind any run of the same inbox still in flight.
+ *
+ * Resolves when THIS run has finished (or failed, having reported itself), so a caller
+ * that wants to wait can — while a caller that does not simply drops the promise.
+ */
+// @provenance drainInboxSerially kind=aligned level=1 ref=engine/verifier/src/verifier.rs:inbox — upstream one verifier owns an inbox and applies its messages one at a time as they arrive; this is that serialization, for the two paths this package drains from
+export function drainInboxSerially(inbox: Nuri, process: () => Promise<void>): Promise<void> {
+  const previous = running.get(inbox) ?? Promise.resolve();
+  const next = previous
+    // A previous run that FAILED must not cancel this one: its failure was reported where
+    // failures go, and the deposits it did not apply are exactly what this run is for.
+    .catch(() => undefined)
+    .then(process)
+    .catch((error: unknown) => reportFailure(inbox, error))
+    .then(() => {
+      if (running.get(inbox) === next) running.delete(inbox);
+    });
+  running.set(inbox, next);
+  return next;
+}
+
+/**
+ * Wait until no drain is in flight. The seam a suite needs to observe convergence without
+ * waiting for it — and the one `runScheduledInboxProcessingNow` awaits after firing its
+ * windows. Loops, because a drain can be chained behind the one being awaited.
+ */
+// @provenance drainsSettled kind=invention level=none ref=none — a test/lifecycle seam over the queue above; upstream nothing exposes "is the verifier done applying"
+export async function drainsSettled(): Promise<void> {
+  while (running.size > 0) {
+    await Promise.all([...running.values()]);
+  }
+}

packages/polyfill/src/emulated-verifier/inbox-observer.ts

@@ -0,0 +1,346 @@
+/**
+ * While an identity is connected, its inboxes are WATCHED and what arrives is APPLIED.
+ *
+ * ── The regime this restores, and the one it replaces ─────────────────────
+ * Upstream, applying an inbox is not something that happens at connection — it is what a
+ * session DOES. A sealed message reaches the recipient's own verifier as it arrives
+ * (`LocalBrokerMessage::Inbox` → `session.verifier.inbox(msg, from_queue)`,
+ * `sdk/rust/src/local_broker.rs`), which unseals it and applies it inline
+ * (`engine/verifier/src/inbox_processor.rs`); `from_queue` distinguishes the backlog handed
+ * over at connection from the messages that follow, and BOTH go through the same door. So
+ * the backlog is the special case, and the continuity is the rule.
+ *
+ * This package had emulated only the backlog. `inbox.processInbox` was called from exactly
+ * one place — `connect.connectedUser`, at connection — and nothing anywhere applied a
+ * deposit after that. A share deposited into an inbox whose owner was sitting connected in
+ * front of it converged only when that person reloaded the page, and the deposit's own
+ * session covered the gap by usurping the owner's identity on a twenty-second timer
+ * (`emulated-verifier/inbox-processor.ts`) — which does nothing at all if the depositor
+ * closes their tab, and tells the connected owner nothing either way.
+ *
+ * So: for as long as an identity is connected, every inbox it may read is subscribed to,
+ * and every push over one of them applies what is in it.
+ *
+ * ── Watching is not applying ──────────────────────────────────────────────
+ * `inbox.watch` looks like this and is not: it NOTIFIES an application that made a call and
+ * named one inbox, and it applies nothing. This applies, on the whole set, without anybody
+ * asking — because processing an inbox is the library's job and not the app's, which is the
+ * same ruling `connect.ts` opens with.
+ *
+ * ── Subscription, never a poll ────────────────────────────────────────────
+ * Every half is push-driven. The inboxes themselves are subscribed to individually. WHICH
+ * inboxes exist is itself a subscription, on two channels that do not overlap:
+ *
+ *   - the REGISTER — an inbox opened mid-session appends an `AddInboxCap` record to the
+ *     User branch of the private store (`branch-registers.openDocumentInbox`), so a push on
+ *     that document re-enumerates `myInboxes()`;
+ *   - WHAT THIS IDENTITY HOLDS (`CapRegistry.onChange`) — the same signal `watchShape`
+ *     re-reads on. It answers the case the register cannot: an identity that connects
+ *     before it has an account at all. Provisioning is lazy here, so a person's FIRST visit
+ *     connects with no stores, no private store to follow and no inbox to watch; the
+ *     account appears later, the moment the application creates anything, and filing its
+ *     caps is what says so. Without this channel a brand-new user was watched from their
+ *     SECOND visit onwards — which is exactly the person most likely to be sent something.
+ *
+ * So a document whose inbox this identity opened five minutes into the session is watched
+ * like the rest, and so is the very first inbox of a person who had none when they arrived.
+ *
+ * ── It belongs to ONE holder, and stops when that holder does ─────────────
+ * Everything below resolves the CURRENT holder when it runs — `myInboxes`, `processInbox`
+ * and everything under them ask `getCurrentUser()` at the moment they execute. So an
+ * observation started for Alice must not still be firing when Bob is connected: it would
+ * read Alice's registers under Bob, or file Alice's capabilities into Bob's ring. The
+ * observation is therefore stamped with its holder, every step re-checks it, and switching
+ * identity (or disconnecting) tears it down — the same rule, and the same reason,
+ * `connect.connectedUser` carries `stillConnected()` for.
+ */
+
+import { getCaps, getCurrentUser } from "../shared-wallet/bootstrap";
+import { accessLogPrefix, logStage, shortNuri } from "../shared-wallet/access-log";
+import { myInboxes } from "./branch-registers";
+import { drainInboxSerially, drainsSettled } from "./inbox-drain";
+import { lookupAccount } from "../shared-wallet/account-registry";
+import { processInbox } from "../surface/inbox";
+import { subscribeDoc, type Unsubscribe } from "../surface/subscribe";
+import type { Nuri, PrincipalId } from "../model/types";
+
+/**
+ * One identity's live observation. Held whole rather than as loose module variables so
+ * that a step started under it can ask "am I still the current one" by IDENTITY of the
+ * object, not by comparing a name that a re-connection may have restored in between.
+ */
+interface Observation {
+  /** WHO this observation belongs to. Every step re-checks it before acting. */
+  holder: PrincipalId;
+  /** One subscription per inbox observed, keyed by it. */
+  inboxes: Map<Nuri, Unsubscribe>;
+  /** The subscription on the register that says WHICH inboxes exist. */
+  register: Unsubscribe | null;
+  /** Unsubscribe from the held-caps change signal — the second "which inboxes" channel. */
+  holdings: Unsubscribe | null;
+  /** True while a re-enumeration is running, so its own effects do not restart it. */
+  enumerating: boolean;
+  /** A trigger that arrived mid-cycle: the running one repeats once rather than lose it. */
+  enumerateAgain: boolean;
+  /** Enumerations and applications in flight — what {@link observationSettled} waits on. */
+  pending: Set<Promise<void>>;
+}
+
+let observation: Observation | null = null;
+
+/**
+ * Where a failure to WATCH goes — distinct from a failure to APPLY, which
+ * `inbox-drain.ts` reports.
+ *
+ * Not a rejection: nothing awaits this work, exactly as at connection. And not silence, for
+ * the same reason as everywhere else in this package — an observation that cannot be
+ * established leaves deposits unapplied for the whole session, and the only thing a person
+ * would notice is that a share never arrives.
+ */
+function reportUnobserved(what: string, error: unknown): void {
+  console.error(
+    accessLogPrefix() + " connected, but " + what + " — deposits made from now on may not be " +
+      "applied until the next connection:",
+    error,
+  );
+}
+
+/** Is `obs` still the live observation, for the identity it belongs to? */
+function current(obs: Observation): boolean {
+  return observation === obs && getCurrentUser() === obs.holder;
+}
+
+/** Track a piece of in-flight work so {@link observationSettled} can wait for it. */
+function track(obs: Observation, work: Promise<void>): void {
+  obs.pending.add(work);
+  void work.finally(() => obs.pending.delete(work));
+}
+
+/**
+ * Apply whatever is in `inbox`, for the holder this observation belongs to.
+ *
+ * Through the shared per-inbox queue, so this cannot interleave with a drain the deferred
+ * timer started on the same inbox (nor with another push of its own): two passes over one
+ * queue apply the same records twice. A failure is reported there and stops nothing — the
+ * next push over this inbox tries again, and the other inboxes were never involved.
+ */
+async function applyWhatArrived(obs: Observation, inbox: Nuri): Promise<void> {
+  if (!current(obs)) return;
+  await drainInboxSerially(inbox, async () => {
+    // Re-checked INSIDE the queue: this run may have waited behind another one, and the
+    // identity can have moved while it waited. `processInbox` resolves the holder at each
+    // of its steps, so running it for the wrong one is not a near-miss — it reads someone
+    // else's registers and files into someone else's ring.
+    if (!current(obs)) return;
+    try {
+      await processInbox(inbox);
+    } catch (error) {
+      // An identity that moved MID-DRAIN throws here too, and it is the ordinary case rather
+      // than an exotic one: `processInbox` resolves the holder at each step, so the new
+      // holder is refused an inbox that is not theirs somewhere in the middle. That is
+      // ABANDONING — which this package has always called "not a failure" — and reporting it
+      // would put a broker-looking error in the log every time a page switches user.
+      // Nothing is lost: an inbox is not consumed by being abandoned, so the deposit is
+      // still there for its owner's next connection. Same rule, same words, as the drain
+      // loop in `connect.connectedUser`.
+      if (!current(obs)) return;
+      throw error;
+    }
+  });
+}
+
+/**
+ * (Re-)enumerate the inboxes this identity may read and subscribe to the ones not yet
+ * watched. Idempotent: an inbox already observed is left alone, so a re-enumeration costs
+ * one read and nothing else.
+ *
+ * Never removes: the list only grows within a session (an `AddInboxCap` record is durable),
+ * and dropping a subscription on a guess would silently stop applying an inbox.
+ */
+async function watchTheInboxes(obs: Observation): Promise<void> {
+  if (!current(obs)) return;
+  let inboxes: Nuri[];
+  try {
+    inboxes = await myInboxes();
+  } catch (error) {
+    // Not knowing WHICH inboxes exist is the whole observation failing, not one queue.
+    reportUnobserved("the inboxes to watch could not be listed", error);
+    return;
+  }
+  if (!current(obs)) return;
+  for (const inbox of inboxes) {
+    if (obs.inboxes.has(inbox)) continue;
+    try {
+      // The push is the signal; the drain is the work. The FIRST push is the initial
+      // `State`, which drains an inbox connection has usually just drained — idempotent,
+      // and the alternative (skip the first) would lose a deposit that landed in the gap
+      // between the two.
+      obs.inboxes.set(
+        inbox,
+        subscribeDoc(inbox, () => track(obs, applyWhatArrived(obs, inbox))),
+      );
+      logStage("OBSERVING " + shortNuri(inbox) + " for " + obs.holder);
+    } catch (error) {
+      reportUnobserved("this inbox could not be watched: " + shortNuri(inbox), error);
+    }
+  }
+}
+
+/**
+ * Follow the register that says which inboxes exist, so one opened MID-SESSION is picked
+ * up. See the module header: `openDocumentInbox` appends its record to the User branch of
+ * the private store, and a same-session write pushes to its own subscribers.
+ *
+ * Idempotent, and RETRIED rather than given up on: an identity that connects before it has
+ * an account has no private store to follow yet, and acquires one the first time the
+ * application creates anything. Re-entered from the holdings signal, it catches up then.
+ */
+async function watchTheRegister(obs: Observation): Promise<void> {
+  if (!current(obs) || obs.register !== null) return;
+  let store: Nuri | undefined;
+  try {
+    // `lookupAccount`, not `resolveAccount`: the tolerant form answers `null` for a read
+    // that FAILED exactly as for one that found nothing, and the two could not mean more
+    // different things here — "this identity has no account yet" is a state to wait
+    // quietly through, "the broker did not answer" is a failure to report. The same
+    // distinction `connect.connectedUser` and `inbox.share` are built on.
+    store = (await lookupAccount(obs.holder))?.docPrivate;
+  } catch (error) {
+    reportUnobserved("the register of your inboxes could not be reached", error);
+    return;
+  }
+  // No account yet — nothing to follow, and asking for one would PROVISION it, which
+  // connecting deliberately does not do (`connect.connectedUser`). The holdings signal
+  // brings us back here the moment there is something to follow.
+  if (!store || !current(obs) || obs.register !== null) return;
+  try {
+    obs.register = subscribeDoc(store, () => track(obs, enumerate(obs)));
+  } catch (error) {
+    reportUnobserved("an inbox opened later in this session will not be watched", error);
+  }
+}
+
+/**
+ * The whole "which inboxes am I watching" cycle: catch up on the register, then on the
+ * inboxes. Both halves are idempotent, so this is what every trigger runs.
+ *
+ * A trigger that arrives while a cycle is running does not start a second one — the cycle
+ * FILES caps for the inboxes it lists (`myInboxes` → `fileOwnInbox`), which is one of the
+ * signals that runs it, so overlapping runs would pile up on their own effects. It is
+ * REMEMBERED instead of dropped: the running cycle repeats once more at the end, because a
+ * signal that arrived mid-cycle may be about something that cycle had already read past.
+ *
+ * That terminates rather than ping-ponging: filing a cap this identity already holds fires
+ * nothing (`caps.file` notifies only on a genuinely new one), so the repeat that finds
+ * nothing new sets no flag and the loop ends.
+ */
+async function enumerate(obs: Observation): Promise<void> {
+  if (!current(obs)) return;
+  if (obs.enumerating) {
+    obs.enumerateAgain = true;
+    return;
+  }
+  obs.enumerating = true;
+  try {
+    do {
+      obs.enumerateAgain = false;
+      await watchTheRegister(obs);
+      await watchTheInboxes(obs);
+    } while (obs.enumerateAgain && current(obs));
+  } finally {
+    obs.enumerating = false;
+  }
+}
+
+/**
+ * Start observing the connected identity's inboxes. Called at the end of the connection
+ * work (`connect.connectedUser`), and idempotent: calling it again for the identity already
+ * being observed changes nothing.
+ *
+ * ── It resolves when the WATCHING is in place, not when the applying is done ──
+ * Connecting publishes one guarantee — *the work it starts, it finishes* — and "your
+ * inboxes are now being watched" is part of that work, so this is awaited rather than
+ * fired. What it does NOT wait for is the applying: subscribing pushes an initial `State`,
+ * which drains each inbox again, and making a person's sign-in wait on a second pass over
+ * a backlog `connectedUser` has just applied would buy nothing.
+ *
+ * It never rejects. Failing to WATCH is reported where failures go and denies nobody their
+ * session — the same rule the drain loop above it follows, and for the same reason: what
+ * has not been applied stays in its queue for the next attempt.
+ */
+// @provenance startObservingInboxes kind=aligned level=1 ref=engine/verifier/src/verifier.rs:inbox — upstream a connected verifier is handed each inbox message as it arrives and applies it; here the arrival signal is a document push, and the set of inboxes is the User branch's `AddInboxCap` records
+export async function startObservingInboxes(): Promise<void> {
+  const holder = getCurrentUser();
+  if (holder === null) return;
+  if (observation !== null && observation.holder === holder) return;
+  stopObservingInboxes();
+  const obs: Observation = {
+    holder,
+    inboxes: new Map(),
+    register: null,
+    holdings: null,
+    enumerating: false,
+    enumerateAgain: false,
+    pending: new Set(),
+  };
+  observation = obs;
+  // The second "which inboxes exist" channel — see the module header. It is what makes a
+  // person's FIRST session watched at all: they connect holding nothing, and their account
+  // (with its inboxes) appears the moment the application creates something.
+  obs.holdings = getCaps().onChange(() => track(obs, enumerate(obs)));
+  const setup = enumerate(obs);
+  track(obs, setup);
+  await setup;
+}
+
+/**
+ * Stop observing — on an identity change, on disconnection, and when the library is
+ * un-configured.
+ *
+ * Work already inside the drain queue is not cancelled (nothing can un-issue a write
+ * already sent); it is neutralised instead, because every step re-checks that its
+ * observation is still the current one and returns rather than filing for the wrong holder.
+ */
+// @provenance stopObservingInboxes kind=aligned level=1 ref=engine/verifier/src/verifier.rs:Verifier — a verifier's inbox processing lives and dies with its session; switching identity is another session, so nothing of the previous one keeps applying
+export function stopObservingInboxes(): void {
+  const obs = observation;
+  if (obs === null) return;
+  observation = null;
+  for (const unsub of obs.inboxes.values()) {
+    try {
+      unsub();
+    } catch (error) {
+      console.error(accessLogPrefix() + " stopping an inbox observation failed:", error);
+    }
+  }
+  obs.inboxes.clear();
+  for (const unsub of [obs.register, obs.holdings]) {
+    if (!unsub) continue;
+    try {
+      unsub();
+    } catch (error) {
+      console.error(accessLogPrefix() + " stopping an inbox observation failed:", error);
+    }
+  }
+  obs.register = null;
+  obs.holdings = null;
+}
+
+/**
+ * Wait until the observation has nothing in flight — the enumerations it is running and the
+ * drains they started.
+ *
+ * A seam for a suite that has to observe convergence without waiting for it, in the same
+ * spirit as `runScheduledInboxProcessingNow`: it names no inbox and starts no work, so it
+ * can only wait for what a push has already caused. Never exported from the package.
+ */
+// @provenance observationSettled kind=invention level=none ref=none — a test seam over the observation; upstream nothing exposes "has the verifier finished applying"
+export async function observationSettled(): Promise<void> {
+  for (;;) {
+    const obs = observation;
+    const inFlight = obs ? [...obs.pending] : [];
+    if (inFlight.length === 0) break;
+    await Promise.all(inFlight);
+  }
+  await drainsSettled();
+}

packages/polyfill/src/emulated-verifier/inbox-processor.ts

@@ -1,18 +1,26 @@
 /**
- * The inbox-processing SERVICE this deployment has not got — emulated by a timer.
+ * A stand-in for an inbox whose owner is NOT HERE — emulated by a timer.
  *
  * ── What is missing, and what stands in for it ────────────────────────────
  * Upstream a deposit does not wait for anybody: the broker routes the sealed message
  * (`inboxes: PubKey → RepoId`, `engine/verifier/src/verifier.rs:105,1677`) and the
- * recipient's verifier applies it when it processes the inbox
- * (`engine/verifier/src/inbox_processor.rs`). A real NextGraph deployment will have
- * something running continuously that does this; today, in this library, the ONLY thing
- * that drains an inbox is its owner connecting (`connect.connectedUser` →
- * `inbox.processInbox`), which can be hours away.
+ * RECIPIENT's own verifier applies it as it arrives, for as long as that recipient has a
+ * session (`LocalBrokerMessage::Inbox` → `session.verifier.inbox(…)`,
+ * `sdk/rust/src/local_broker.rs`). Two different things follow from that, and this module
+ * is only one of them:
+ *
+ *   - a connected identity's own inboxes are observed and applied continuously, which is
+ *     `emulated-verifier/inbox-observer.ts` and needs no timer at all;
+ *   - an identity that is NOT connected has nobody to apply anything for it. Upstream the
+ *     broker queues the message until it comes back; here, on ONE shared wallet, the
+ *     depositor's own page can stand in for it.
  *
  * So: a successful deposit arms a ONE-SHOT timer that processes the TARGET's inbox, twenty
  * seconds later. Alice deposits into Bob's inbox; twenty seconds later this package drains
- * Bob's inbox, while the connected session is still Alice's.
+ * Bob's inbox, while the connected session is still Alice's. When Bob IS connected in this
+ * page, the observation has already applied it long before the window closes and the timer
+ * finds nothing left to do — harmless (draining is idempotent) and not worth a special
+ * case: the two answer different questions, and only this one answers the absent owner.
  *
  * ── That is identity usurpation, and it is deliberate ─────────────────────
  * It is only possible because one shared wallet holds every virtual identity, and it is
@@ -32,7 +40,8 @@
  * the real path, not a repair.
  */
 
-import { accessLogPrefix, logStage, shortNuri } from "../shared-wallet/access-log";
+import { logStage, shortNuri } from "../shared-wallet/access-log";
+import { drainInboxSerially, drainsSettled } from "./inbox-drain";
 import type { Nuri } from "../model/types";
 
 /**
@@ -62,13 +71,6 @@ interface Scheduled {
  */
 const scheduled = new Map<Nuri, Scheduled>();
 
-/**
- * Drains in flight, per inbox — so a run that starts while another is still going CHAINS
- * behind it instead of interleaving with it. Same reason `connect.connectedUser` drains its
- * inboxes sequentially: two concurrent passes over one queue apply the same records twice.
- */
-const running = new Map<Nuri, Promise<void>>();
-
 /**
  * Keep a pending drain from holding a runtime open.
  *
@@ -83,38 +85,14 @@ function releaseFromTheEventLoop(handle: ReturnType<typeof setTimeout>): void {
 }
 
 /**
- * Where a deferred drain's failure goes.
- *
- * It cannot throw: nothing awaits it — the application never asked for this work, and an
- * unhandled rejection would take down whatever runtime it is in over a drain it did not
- * request. But "nowhere" is not the alternative. A drain that swallows its failure is
- * indistinguishable from one that succeeded, which is precisely the defect family removed
- * from this package on 2026-08-13. So it goes to the package's own log stream — the same
- * `console.error` with the same `[<identity>][polyfill]` prefix that `startConnect` and
- * `inbox.watch` use for their un-awaitable failures, and it is NOT gated by the access-log
- * flag: a diagnostic may be opt-in, a failure may not.
+ * Run the drain of `inbox`, behind any run of the same inbox still in flight — including a
+ * run the CONTINUOUS observation started, which is why the queue lives in
+ * `emulated-verifier/inbox-drain.ts` rather than here. That module also owns where a
+ * drain's failure goes; it cannot travel back to a caller, because a timer has none.
  */
-function reportFailure(inbox: Nuri, error: unknown): void {
-  console.error(
-    accessLogPrefix() + " deferred inbox processing failed for " + shortNuri(inbox) + ":",
-    error,
-  );
-}
-
-/** Run the drain of `inbox`, behind any run of the same inbox still in flight. */
 function fire(inbox: Nuri, process: () => Promise<void>): void {
   scheduled.delete(inbox);
-  const previous = running.get(inbox) ?? Promise.resolve();
-  const next = previous
-    // A previous run that FAILED must not cancel this one: its failure was reported where
-    // failures go, and the deposits it did not apply are exactly what this run is for.
-    .catch(() => undefined)
-    .then(process)
-    .catch((error: unknown) => reportFailure(inbox, error))
-    .then(() => {
-      if (running.get(inbox) === next) running.delete(inbox);
-    });
-  running.set(inbox, next);
+  void drainInboxSerially(inbox, process);
 }
 
 /**
@@ -126,7 +104,7 @@ function fire(inbox: Nuri, process: () => Promise<void>): void {
  *
  * Idempotent inside the window: a second deposit into the same inbox joins the pending run.
  */
-// @provenance scheduleInboxProcessing kind=divergent level=1 ref=engine/verifier/src/verifier.rs:inbox — upstream the RECIPIENT's own verifier applies its inbox; here another identity's session drains it on a timer. Deliberate, unpublished, and only possible on one shared wallet
+// @provenance scheduleInboxProcessing kind=divergent level=1 ref=engine/verifier/src/verifier.rs:inbox — upstream the RECIPIENT's own verifier applies its inbox and the broker queues for it while it is away; here another identity's session drains it on a timer, for a recipient that is not connected in this page (one that IS has its own observation). Deliberate, unpublished, and only possible on one shared wallet
 export function scheduleInboxProcessing(inbox: Nuri, process: () => Promise<void>): void {
   if (scheduled.has(inbox)) return;
   const handle = setTimeout(() => fire(inbox, process), PROCESSING_DELAY_MS);
@@ -152,7 +130,7 @@ export async function runScheduledInboxProcessingNow(): Promise<void> {
     clearTimeout(entry.handle);
     fire(inbox, entry.process);
   }
-  await Promise.all([...running.values()]);
+  await drainsSettled();
 }
 
 /**

packages/polyfill/src/emulated-verifier/open-repo.ts

@@ -74,7 +74,7 @@
 import { mustNotAttempt } from "./reach";
 import { fetchReadCap } from "./public-store";
 import { getConfig, getStoreRegistryDeps } from "../shared-wallet/bootstrap";
-import { subscribeDocUnguarded, type Unsubscribe } from "../surface/subscribe";
+import { resubscribeDocs, subscribeDocUnguarded, type Unsubscribe } from "../surface/subscribe";
 import { logStage, shortNuri } from "../shared-wallet/access-log";
 import type { Nuri } from "../model/types";
 
@@ -137,6 +137,15 @@ export function resetOpenedRepos(): void {
   syncState.clear();
   boundSessionId = null;
   OPEN_TIMEOUT_MS = 8000;
+  // Whatever ELSE was still subscribed to a document — a `watchShape` following a scope,
+  // an inbox observation — belongs to the session that just went away too. One real
+  // subscription now serves all of them (`surface/subscribe.ts`), so dropping the bootstrap
+  // ones above no longer closes those channels; they are re-opened against the new session,
+  // with their barrier forgotten. Without this a bootstrap open would join a surviving
+  // fan-out, be handed the PREVIOUS session's `State`, and call a repo the new session has
+  // never synced "synced". After the held teardown, so a document nobody else follows is
+  // simply released.
+  resubscribeDocs();
 }
 
 /**

packages/polyfill/src/shared-wallet/bootstrap.ts

@@ -25,6 +25,8 @@ import { setAccessLog } from "./access-log";
 import { inspectOutbox } from "./outbox-log";
 import { startConnect } from "../emulated-verifier/connect";
 import { cancelScheduledInboxProcessing } from "../emulated-verifier/inbox-processor";
+import { stopObservingInboxes } from "../emulated-verifier/inbox-observer";
+import { resetDocSubscriptions } from "../surface/subscribe";
 import { resetSharedWalletSession, sharedWalletSession } from "./session";
 
 /**
@@ -191,6 +193,13 @@ let caps = new CapRegistry(capsHolder);
 
 // @provenance configure kind=invention level=none ref=none — same — the whole call disappears at migration, when the consumer initialises the real SDK directly
 export function configure(c: EventuallyConfig): void {
+  // Whatever the PREVIOUS SDK was driving stops here. A document subscription belongs to
+  // the `ng` that opened it and an inbox observation to the identity that was connected
+  // through it, so carrying either into a fresh configuration would leave listeners
+  // attached to a verifier nobody is talking to any more — and, on the observation, work
+  // that files for an identity this call is about to clear.
+  resetDocSubscriptions();
+  stopObservingInboxes();
   cfg = c;
   // Not taken from the config: an application never supplies its own identity — upstream
   // it comes FROM the wallet a person opened. Accepting one here would also let a caller
@@ -224,6 +233,12 @@ export function resetConfig(): void {
   // no longer has an `ng` to read or write with, and report a failure about a session that
   // no longer exists. See `emulated-verifier/inbox-processor.ts`.
   cancelScheduledInboxProcessing();
+  // …and so does the continuous observation, for the same reason and one more: it is a set
+  // of live document subscriptions, which the un-configured library has no `ng` to cancel
+  // through. Both go before the subscriptions themselves, so nothing is left holding a
+  // torn-down fan-out.
+  stopObservingInboxes();
+  resetDocSubscriptions();
   // The hand-over goes with it, for the same reason: it is made of the config's injected
   // `init`, so leaving it behind would let a revived barrier delegate to the PREVIOUS
   // application's SDK.
@@ -350,6 +365,13 @@ export function adoptCurrentUser(id: PrincipalId | null): boolean {
  */
 export function setCurrentUser(id: PrincipalId | null): void {
   const changed = adoptCurrentUser(id);
+  // The PREVIOUS identity stops being watched the moment it stops being connected —
+  // including on `null`, which is a disconnection and not merely "no new work". An
+  // observation applies what arrives by resolving the current holder at each step, so one
+  // left running past a switch would read the old identity's registers under the new one
+  // and file the old one's capabilities into the new one's ring. Whoever connects next
+  // starts their own. See `emulated-verifier/inbox-observer.ts`.
+  if (changed) stopObservingInboxes();
   // Connecting a user is what triggers inbox processing — the library's job, not
   // the app's. Fire-and-forget: this setter is synchronous and every consumer calls
   // it from synchronous code, so the work announces itself through the cap

packages/polyfill/src/surface/subscribe.ts

@@ -31,6 +31,36 @@
  * resolves → the ~75s hang. `doc_subscribe` is per-branch/per-doc and has no
  * fan-out: an absent doc breaks only its own subscription. {@link subscribeDocs}
  * builds a set of these with per-doc error isolation to preserve that property.
+ *
+ * ── ONE real subscription per document, fanned out here ────────────────────
+ * A branch has room for exactly ONE subscriber upstream, and a second `doc_subscribe`
+ * does not join it — it EVICTS the first. `branch_subscriptions: HashMap<BranchId,
+ * Sender<AppResponse>>` holds one sender per branch, and `create_branch_subscription`
+ * inserts into it and closes whatever it displaced
+ * (`engine/verifier/src/verifier.rs:create_branch_subscription`), for the document's own
+ * branch AND for its Header branch.
+ *
+ * Verified against the real broker on 2026-08-17: with two `subscribeDoc` calls on one
+ * document, a write fired the SECOND callback (`Patch`) and the first stopped firing
+ * entirely — after having fired on a write moments earlier. Silently: nothing rejects,
+ * nothing logs, the stale unsubscribe still "works".
+ *
+ * That made every internal subscriber a hazard to every other one. `ensureRepoOpen`
+ * holds a bootstrap subscription per document for the whole session, `watchShape`
+ * subscribes to the documents of a scope, `inbox.watch` to an inbox — so opening a
+ * repo killed the watch on it, and the app-visible result was a view that never
+ * re-read and an inbox that never notified. Both were reported as "the layer does not
+ * notify of its own actions", which is NOT what happens: a same-session write DOES
+ * push (verified the same day — `Patch@69ms` on the writer's own `sparqlUpdate`,
+ * `e2e/reactivity-doc-subscribe.ts`). The push arrived; there was no longer anybody
+ * on the other end.
+ *
+ * So this module keeps at most one real subscription per NURI and fans its pushes out
+ * to every local listener. A listener that joins after the initial `State` is replayed
+ * the remembered one, because that is what its own `doc_subscribe` would have handed
+ * it — without the replay, joining a document somebody else already opened would never
+ * fire, and `inbox.watch`'s "fires once immediately" would silently stop being true.
+ * The real subscription is torn down when the LAST listener leaves.
  */
 
 import { getConfig, getStoreRegistryDeps } from "../shared-wallet/bootstrap";
@@ -87,6 +117,149 @@ async function sessionId(): Promise<string | number> {
   return (await getStoreRegistryDeps().getSession()).sessionId;
 }
 
+// --- one real subscription per document -----------------------------------
+
+/** What a listener is handed on every push. */
+type Listener = (r: DocChange, type: DocChangeType) => void;
+
+/**
+ * The single real `doc_subscribe` behind every local listener on one document.
+ * See the module header for why there can only be one.
+ */
+interface DocFanOut {
+  /** Every local listener on this document. The last one to leave tears it down. */
+  listeners: Set<Listener>;
+  /** The platform's unsubscribe, once the async setup resolved. */
+  realUnsub: (() => void) | null;
+  /** True from the moment setup is kicked off — a later joiner must not kick off a second. */
+  establishing: boolean;
+  /**
+   * The most recent `State` push, replayed to a listener that joins later.
+   * Its own `doc_subscribe` would have pushed one; the fan-out owes it the same.
+   */
+  lastState: { resp: DocChange; type: DocChangeType } | null;
+}
+
+const fanOuts = new Map<Nuri, DocFanOut>();
+
+/** Hand one push to one listener, isolating a throwing handler from the others. */
+function deliver(nuri: Nuri, listener: Listener, resp: DocChange, type: DocChangeType): void {
+  try {
+    listener(resp, type);
+  } catch (error) {
+    console.error("[subscribe] onChange handler threw for", nuri, error);
+  }
+}
+
+/** Drop a fan-out: forget the remembered state and release the real subscription. */
+function releaseFanOut(nuri: Nuri, entry: DocFanOut): void {
+  if (fanOuts.get(nuri) === entry) fanOuts.delete(nuri);
+  entry.lastState = null;
+  entry.establishing = false;
+  const unsub = entry.realUnsub;
+  entry.realUnsub = null;
+  if (!unsub) return;
+  try {
+    unsub();
+  } catch (error) {
+    console.error("[subscribe] unsubscribe failed for", nuri, error);
+  }
+}
+
+/**
+ * Open the one real subscription for `entry` and route its pushes to every listener.
+ * Errors are isolated to this document (they never reject a shared batch — see
+ * {@link subscribeDocs}); a failed setup simply leaves the document silent.
+ */
+async function establish(nuri: Nuri, entry: DocFanOut, ng: { doc_subscribe?: unknown }): Promise<void> {
+  // No reactive primitive on the injected `ng` (the fake in the unit suite): there is
+  // nothing to call, so this document simply never pushes — the same documented no-op
+  // `openRepoUnguarded` takes for the same injection, and not a failure to report. A real
+  // `@ng-org/web` always exposes it.
+  if (typeof ng.doc_subscribe !== "function") return;
+  const doc_subscribe = ng.doc_subscribe as (...a: unknown[]) => unknown;
+  try {
+    const sid = await sessionId();
+    const unsub = (await doc_subscribe(nuri, sid, (resp: DocChange): void => {
+      // A push that arrives after the last listener left belongs to a torn-down
+      // fan-out — the real unsubscribe may not have taken effect yet.
+      if (fanOuts.get(nuri) !== entry) return;
+      const type = docChangeType(resp);
+      // Remember the barrier for whoever joins next; a later `State` replaces it.
+      if (type === "State") entry.lastState = { resp, type };
+      // A copy: a handler may unsubscribe itself (or another) from inside the push.
+      for (const listener of [...entry.listeners]) deliver(nuri, listener, resp, type);
+    })) as (() => void) | undefined;
+    if (fanOuts.get(nuri) !== entry || entry.listeners.size === 0) {
+      // Everyone left (or the fan-out was reset) before setup resolved — cancel now.
+      if (typeof unsub === "function") unsub();
+      return;
+    }
+    entry.realUnsub = typeof unsub === "function" ? unsub : null;
+  } catch (error) {
+    console.error("[subscribe] doc_subscribe failed for", nuri, error);
+  }
+}
+
+/**
+ * Drop every fan-out without notice — what a page that re-`configure()`s does.
+ *
+ * A subscription belongs to the injected SDK that opened it, so when that is replaced
+ * (or removed) its live subscriptions are void: their pushes would come from a verifier
+ * nobody is talking to any more. Called by `configure`/`resetConfig`, and by nothing on
+ * the reactive path — a listener is never dropped while its SDK is still there.
+ */
+// @provenance resetDocSubscriptions kind=invention level=none ref=none — per-session bookkeeping reset, like `resetOpenedRepos`; upstream a verifier owns its own subscriptions and nothing resets them from outside
+export function resetDocSubscriptions(): void {
+  for (const [nuri, entry] of [...fanOuts]) {
+    entry.listeners.clear();
+    releaseFanOut(nuri, entry);
+  }
+  fanOuts.clear();
+}
+
+/**
+ * Re-open every live subscription against the CURRENT session, keeping its listeners.
+ *
+ * Called when the session id changes under the page (`open-repo.resetOpenedRepos`), and
+ * this is the one thing the fan-out owes that a per-caller subscription got for free. A new
+ * session is a new verifier with an empty `self.repos`, so the channel behind a fan-out is
+ * dead — and its remembered `State` is the old verifier's, which would let a bootstrap open
+ * JOIN it, be handed that stale barrier at once, and read a repo the new session has never
+ * synced. Zero rows, "synced", no error: the silent staleness this module exists to remove.
+ *
+ * So the barrier is forgotten and the channel re-opened, rather than the listeners dropped:
+ * a `watchShape` that was following a document keeps following it across the change.
+ */
+// @provenance resubscribeDocs kind=invention level=none ref=none — per-session bookkeeping, like `resetOpenedRepos`; upstream a session's subscriptions die with it and nothing carries them over
+export function resubscribeDocs(): void {
+  // Un-configured (a torn-down suite): there is no SDK to re-open anything against, and
+  // `resetDocSubscriptions` has already emptied this map on that path.
+  let ng: { doc_subscribe?: unknown };
+  try {
+    ng = getConfig().ng as { doc_subscribe?: unknown };
+  } catch {
+    return;
+  }
+  for (const [nuri, entry] of [...fanOuts]) {
+    if (entry.listeners.size === 0) continue;
+    const stale = entry.realUnsub;
+    entry.realUnsub = null;
+    // The barrier belonged to the session that is gone. Whoever joins next waits for a
+    // real one, exactly as they would have on a fresh page.
+    entry.lastState = null;
+    if (stale) {
+      try {
+        stale();
+      } catch (error) {
+        console.error("[subscribe] unsubscribe failed for", nuri, error);
+      }
+    }
+    entry.establishing = true;
+    void establish(nuri, entry, ng);
+  }
+}
+
 /**
  * Subscribe to ONE document. `onChange` fires on the initial state push and on
  * every subsequent change to that doc (local write OR broker-synced remote
@@ -106,7 +279,7 @@ async function sessionId(): Promise<string | number> {
  *
  * Calls the REAL injected `ng.doc_subscribe` directly (never `makeNg`).
  */
-// @provenance subscribeDoc kind=aligned level=2 ref=sdk/js/lib-wasm/src/lib.rs:doc_subscribe — two deliberate deltas: the unsubscribe is returned synchronously, and the callback gets a pre-extracted `type`
+// @provenance subscribeDoc kind=aligned level=2 ref=sdk/js/lib-wasm/src/lib.rs:doc_subscribe — three deliberate deltas: the unsubscribe is returned synchronously, the callback gets a pre-extracted `type`, and N callers of ONE document share ONE upstream subscription because a branch holds a single sender and a second subscribe evicts the first
 export function subscribeDoc(
   nuriLike: NuriLike,
   onChange: (r: DocChange, type: DocChangeType) => void,
@@ -123,53 +296,49 @@ export function subscribeDoc(
  * owns the machinery's entire privileged door — and for nobody else. It is not
  * re-exported by either entry point; the `Unguarded` suffix is the warning.
  */
-// @provenance subscribeDocUnguarded kind=aligned level=2 ref=sdk/js/lib-wasm/src/lib.rs:doc_subscribe — the same call without the reach guard; internal, never published
+// @provenance subscribeDocUnguarded kind=aligned level=2 ref=sdk/js/lib-wasm/src/lib.rs:doc_subscribe — the same call without the reach guard, and the place the one-subscription-per-document fan-out is kept; internal, never published
 export function subscribeDocUnguarded(
   nuri: Nuri,
   onChange: (r: DocChange, type: DocChangeType) => void,
 ): Unsubscribe {
+  // Resolved here, synchronously, so calling this before `configure()` still throws at
+  // the call rather than inside a background task nobody awaits.
   const { ng } = getConfig();
-  let stopped = false;
-  let realUnsub: (() => void) | null = null;
 
-  const cb = (resp: DocChange): void => {
-    if (stopped) return;
-    try {
-      onChange(resp, docChangeType(resp));
-    } catch (error) {
-      console.error("[subscribe] onChange handler threw for", nuri, error);
-    }
-  };
+  let entry = fanOuts.get(nuri);
+  if (!entry) {
+    entry = { listeners: new Set(), realUnsub: null, establishing: false, lastState: null };
+    fanOuts.set(nuri, entry);
+  }
+  const joined = entry;
+  joined.listeners.add(onChange);
 
-  // Kick off the async subscription. Errors are isolated to this doc (they never
-  // reject a shared batch — see subscribeDocs). If setup fails, this doc simply
-  // never fires; the caller's unsubscribe stays a safe no-op.
-  void (async () => {
-    try {
-      const sid = await sessionId();
-      const unsub = (await ng.doc_subscribe(nuri, sid, cb)) as (() => void) | undefined;
-      if (stopped) {
-        // Unsubscribed before setup resolved — cancel immediately.
-        if (typeof unsub === "function") unsub();
-        return;
+  // Joining a document somebody else already opened: hand this listener the `State` its
+  // own `doc_subscribe` would have pushed it. Asynchronously, like the real push, so a
+  // caller that sets itself up after this call still sees it.
+  if (joined.lastState) {
+    const { resp, type } = joined.lastState;
+    queueMicrotask(() => {
+      if (fanOuts.get(nuri) === joined && joined.listeners.has(onChange)) {
+        deliver(nuri, onChange, resp, type);
       }
-      realUnsub = typeof unsub === "function" ? unsub : null;
-    } catch (error) {
-      console.error("[subscribe] doc_subscribe failed for", nuri, error);
-    }
-  })();
+    });
+  }
 
+  if (!joined.establishing) {
+    joined.establishing = true;
+    void establish(nuri, joined, ng as { doc_subscribe?: unknown });
+  }
+
+  let stopped = false;
   return () => {
     if (stopped) return;
     stopped = true;
-    if (realUnsub) {
-      try {
-        realUnsub();
-      } catch (error) {
-        console.error("[subscribe] unsubscribe failed for", nuri, error);
-      }
-      realUnsub = null;
-    }
+    joined.listeners.delete(onChange);
+    // The LAST one out releases the real subscription — while anybody is still
+    // listening, tearing it down would silence them (and re-opening it later is not
+    // free: a second `doc_subscribe` evicts whoever else has the branch by then).
+    if (joined.listeners.size === 0) releaseFanOut(nuri, joined);
   };
 }