fix: dire le pari comme un pari, et distinguer deux manques d'inbox que rien ne distinguait

.project/concepts/app-contract/_debt.md

@@ -0,0 +1,7 @@
+# Doc-debt — app-contract
+
+> Presence of a block = doc to update. Processed → delete the block; no blocks left → delete this file.
+> One block = one "big change": `why` + `files` + `verify` (leaves to review).
+
+## Raw markers (consolidate into blocks, then delete)
+- TOUCHED packages/polyfill/src/surface/subscribe.ts @2026-08-20 (session f93872b5-293a-4916-a353-181409a96d42)

packages/polyfill/src/emulated-verifier/branch-registers.ts

@@ -502,10 +502,29 @@ export async function myInboxes(): Promise<Nuri[]> {
 export interface InboxEnumeration {
   /** Every inbox this holder may read that COULD be listed — possibly not all of them. */
   inboxes: Nuri[];
-  /** What stopped the rest from being listed, or `null` when nothing did. */
+  /**
-  incomplete: { error: unknown } | null;
+   * What stopped the rest from being listed, or `null` when nothing did — and WHICH of the
+   * two registers stopped it, because the two shortfalls are not the same condition.
+   *
+   * `"account-record"` means the user's OWN two inboxes are missing, which is where a share
+   * addressed to a PERSON lands: the identity has nothing watched that a stranger can reach,
+   * and the document half was never even attempted (the account record is what it reads
+   * through). `"user-branch"` means those two are in hand and only the per-document inboxes
+   * are missing. Told apart because a caller that reports one of them has to be able to say
+   * that the OTHER one has now happened — `error` alone cannot, and the observation
+   * de-duplicating on "already said something" swallowed exactly that.
+   */
+  incomplete: { error: unknown; register: InboxRegister } | null;
 }
 
+/**
+ * WHICH of the two registers behind {@link enumerateMyInboxes} could not be read.
+ *
+ * Named after the register, not after the failure, because that is what a reader has to go
+ * and look at: the account record in the doc-shim, and the User branch of the private store.
+ */
+export type InboxRegister = "account-record" | "user-branch";
+
 /**
  * {@link myInboxes}, for the caller that can use a PARTIAL answer — the live observation.
  *
@@ -537,7 +556,7 @@ export async function enumerateMyInboxes(): Promise<InboxEnumeration> {
   } catch (error) {
     // The account record is what the other half reads THROUGH (`readInboxCapPairs` resolves
     // the same record to find the private store), so there is no second half to attempt.
-    return { inboxes: out, incomplete: { error } };
+    return { inboxes: out, incomplete: { error, register: "account-record" } };
   }
   try {
     for (const { inbox } of await readInboxCapPairs()) {
@@ -546,7 +565,7 @@ export async function enumerateMyInboxes(): Promise<InboxEnumeration> {
       out.push(inbox);
     }
   } catch (error) {
-    return { inboxes: out, incomplete: { error } };
+    return { inboxes: out, incomplete: { error, register: "user-branch" } };
   }
   return { inboxes: out, incomplete: null };
 }

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

@@ -57,7 +57,7 @@
 
 import { getCaps, getCurrentUser } from "../shared-wallet/bootstrap";
 import { accessLogPrefix, logStage, shortNuri } from "../shared-wallet/access-log";
-import { enumerateMyInboxes, type InboxEnumeration } from "./branch-registers";
+import { enumerateMyInboxes, type InboxEnumeration, type InboxRegister } from "./branch-registers";
 import { drainInboxSerially, drainsSettled } from "./inbox-drain";
 import { lookupAccount } from "../shared-wallet/account-registry";
 import { processInbox } from "../surface/inbox";
@@ -83,7 +83,7 @@ interface Observation {
   /** A trigger that arrived mid-cycle: the running one repeats once rather than lose it. */
   enumerateAgain: boolean;
   /**
-   * True while the shortfall reported by the last enumeration is still the SAME one — so a
+   * WHICH shortfall was reported last, or `null` when the last list came back WHOLE — so a
    * register that stays unreadable is reported once, not once per cycle.
    *
    * Every signal this observation listens to runs a full cycle, and a persistent shortfall
@@ -91,8 +91,17 @@ interface Observation {
    * is nudged: one deposit produced three copies of the same line. That is what buries the
    * report that matters under the report that repeats. Cleared the moment a list comes back
    * WHOLE, so a shortfall that goes away and returns is a new occurrence and says so.
+   *
+   * ── The register, and not a bare "already said something" ─────────────────
+   * There are TWO shortfalls, they are disjoint, and one is far worse than the other: the
+   * account record failing leaves this identity with NOTHING watched, its own two inboxes
+   * included, while the User branch failing leaves those two watched and only the
+   * per-document inboxes missing ({@link InboxEnumeration.incomplete}). A boolean here made
+   * the second silence the first — the condition CHANGED, to a materially different one, and
+   * the log said nothing because something had already been said. Keyed by register, a
+   * change of shortfall is what it is: news.
    */
-  shortfallReported: boolean;
+  shortfallReported: InboxRegister | null;
   /** Enumerations and applications in flight — what {@link observationSettled} waits on. */
   pending: Set<Promise<void>>;
 }
@@ -116,6 +125,22 @@ function reportUnobserved(what: string, error: unknown): void {
   );
 }
 
+/**
+ * What a shortfall on `register` leaves unwatched, in the words the log uses.
+ *
+ * The two lines have to READ differently, not merely be counted differently: a reader who
+ * sees the second one after the first has to be able to tell that the condition changed, and
+ * two identical sentences make an escalation look like a repeat. Both keep the phrase the
+ * report has always ended on, because it is the one thing this line is scanned for.
+ */
+function shortfallSaid(register: InboxRegister): string {
+  return register === "account-record"
+    ? "the inboxes to watch could not all be listed (the account record — your own two " +
+        "inboxes, where a share addressed to you by name lands, are NOT among the ones watched)"
+    : "the inboxes to watch could not all be listed (the register of the inboxes opened on " +
+        "documents — your own two are watched)";
+}
+
 /** Is `obs` still the live observation, for the identity it belongs to? */
 function current(obs: Observation): boolean {
   return observation === obs && getCurrentUser() === obs.holder;
@@ -193,7 +218,10 @@ async function applyWhatArrived(obs: Observation, inbox: Nuri): Promise<void> {
  * Once per OCCURRENCE, though, not once per enumeration — see
  * {@link Observation.shortfallReported}. The retry that repairs it is also what re-reads it,
  * so a condition that persists is re-discovered by every signal; reporting each discovery
- * says "it happened again" about the single thing that never stopped happening.
+ * says "it happened again" about the single thing that never stopped happening. An
+ * occurrence is per REGISTER, because the two shortfalls are two conditions: the list going
+ * from "missing the document inboxes" to "missing your own two" is not the same fault
+ * continuing, it is a worse one starting.
  */
 async function watchTheInboxes(obs: Observation): Promise<void> {
   if (!current(obs)) return;
@@ -207,10 +235,10 @@ async function watchTheInboxes(obs: Observation): Promise<void> {
   }
   if (!current(obs)) return;
   if (listed.incomplete === null) {
-    obs.shortfallReported = false;
+    obs.shortfallReported = null;
-  } else if (!obs.shortfallReported) {
+  } else if (obs.shortfallReported !== listed.incomplete.register) {
-    obs.shortfallReported = true;
+    obs.shortfallReported = listed.incomplete.register;
-    reportUnobserved("the inboxes to watch could not all be listed", listed.incomplete.error);
+    reportUnobserved(shortfallSaid(listed.incomplete.register), listed.incomplete.error);
   }
   for (const inbox of listed.inboxes) {
     if (obs.inboxes.has(inbox)) continue;
@@ -373,7 +401,7 @@ export async function startObservingInboxes(): Promise<void> {
     holdings: null,
     enumerating: false,
     enumerateAgain: false,
-    shortfallReported: false,
+    shortfallReported: null,
     pending: new Set(),
   };
   observation = obs;

packages/polyfill/src/surface/subscribe.ts

@@ -202,6 +202,15 @@ interface DocFanOut {
   lastState: { resp: DocChange; type: DocChangeType } | null;
 }
 
+/**
+ * Every document with at least one local listener.
+ *
+ * An entry in this map ALWAYS has listeners — that is the invariant the rest of the module
+ * reads "is this fan-out still standing" off: a listener is added synchronously with the
+ * entry that holds it ({@link subscribeDocUnguarded}), and the last one out takes the entry
+ * with it ({@link releaseFanOut}, {@link resetDocSubscriptions}). So no caller asks after the
+ * listener count separately; `fanOuts.get(nuri) === entry` already answers it.
+ */
 const fanOuts = new Map<Nuri, DocFanOut>();
 
 /** Hand one push to one listener, isolating a throwing handler from the others. */
@@ -333,15 +342,46 @@ function releaseFanOut(nuri: Nuri, entry: DocFanOut): void {
  * silence: `resubscribeDocs` runs on a session change, the superseded call sits on the
  * previous session's verifier, and nothing else will ever close it.
  *
- * ── Why the guard sits BEFORE the call, and not only after it ──────────────
+ * ── Why the guard sits BEFORE the call, and what it does NOT settle ────────
- * It is what makes the sentence above true rather than merely likely. Superseded while the
+ * What it settles is a fact: superseded while the session id was still resolving, this opens
- * session id was still resolving, this opens NO channel at all — so every attempt that owns
+ * NO channel at all. That is the wider half of the window, and it closes it outright.
- * one issued its `doc_subscribe` strictly before the current attempt existed, and by the
+ *
- * global broker lock held for the whole call (`sdk/rust/src/local_broker.rs:3057`) it was
+ * What it leaves open is a BET, and it is written down here as one. For an attempt that DID
- * served first. Whoever inserts last wins the branch (`verifier.rs:361`), so a superseded
+ * place its call before being superseded, this code releases the channel that call opened —
- * attempt is always the upstream LOSER, never the live channel. Without this guard the two
+ * which is only ever releasing the upstream LOSER if the broker SERVED the two calls in the
- * calls could reach the broker in either order, and releasing the loser would be a coin flip
+ * order they were ISSUED. Issuing is all this module can order; service is the broker's, and
- * on whether the document goes silent.
+ * nothing found upstream promises the two agree:
+ *
+ *   - `LOCAL_BROKER` is behind an `async_std::sync::RwLock` held for the whole call
+ *     (`sdk/rust/src/local_broker.rs:3057`), and that type IS `async_lock::RwLock`
+ *     (async-std 1.13.2 `src/sync/mod.rs:181`, a re-export);
+ *   - `RwLock::write()` takes the lock's internal `async_lock::Mutex` first (async-lock 3.4.1
+ *     `src/rwlock/raw.rs:163-168`), and that mutex is documented as "eventual fairness" —
+ *     fair ON AVERAGE, not FIFO (`src/mutex.rs:22-24`). Its hot loop re-runs a bare
+ *     `compare_exchange` on every poll, so a call arriving later can take the lock ahead of
+ *     one already waiting;
+ *   - and the anti-starvation fallback that would eventually force fairness is
+ *     `#[cfg(all(feature = "std", not(target_family = "wasm")))]` (`src/mutex.rs:578-581`) —
+ *     compiled out on wasm, which is where this SDK runs.
+ *
+ * So the lock SERIALISES the calls; it does not ORDER them. Two attempts on the same branch
+ * of the same verifier is a reachable state — the last listener leaving while an establish is
+ * in flight releases the fan-out, and the next joiner opens a fresh one against the same
+ * session — so this is not a cross-session-only concern.
+ *
+ * What breaks the bet is therefore a service order inverted relative to the issue order, and
+ * this is what it costs when it happens: the superseded call inserts LAST, so it wins the
+ * branch and closes the current attempt's sender (`verifier.rs:361`); this code then releases
+ * its own channel, leaving the branch holding a closed sender that `push_app_response` drops
+ * at the first push (`verifier.rs:258-261`). Nothing rejects and nothing logs. The fan-out
+ * holds a `realUnsub` and believes itself subscribed, `establishing` stays true so no later
+ * joiner re-opens it, and the document is silently dead for the rest of the session —
+ * `test/subscribe.test.ts` drives exactly that and pins it.
+ *
+ * Releasing is still what to do: DROPPING the superseded unsubscribe instead leaks a live
+ * subscription in the ordinary case, and buys nothing in the inverted one — the winner's own
+ * callback is gated on an attempt that is no longer current, so it delivers to nobody either
+ * way. The bet is on which failure mode is reachable, never on releasing being free.
  */
 async function establish(
   nuri: Nuri,
@@ -426,7 +466,6 @@ export function resubscribeDocs(): void {
     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

packages/polyfill/test/continuous-inbox-observation.test.ts

@@ -31,7 +31,7 @@
 import { test, expect, describe, afterAll, beforeEach } from "bun:test";
 import { inbox as inboxSurface, storeRegistry } from "../src/index";
 import { getCaps, setCurrentUser } from "../src/shared-wallet/bootstrap";
-import { resolveAccount, userInbox } from "../src/shared-wallet/account-registry";
+import { resetRegistryCache, resolveAccount, userInbox } from "../src/shared-wallet/account-registry";
 import { observationSettled } from "../src/emulated-verifier/inbox-observer";
 import { cancelScheduledInboxProcessing } from "../src/emulated-verifier/inbox-processor";
 import { connectedUser } from "../src/emulated-verifier/connect";
@@ -105,6 +105,17 @@ function depositReadsOf(inbox: Nuri): number {
   ).length;
 }
 
+/**
+ * The doc-shim, read off the WALLET — the document the account records live in, and the one
+ * `userInbox` asks "which inbox does this user own". Found by the record it carries rather
+ * than by a minting order, so it is the shim because of what is written in it.
+ */
+function theDocShim(): Nuri {
+  const record = quads.find((q) => q.p === `${SHIM}:id`);
+  if (!record) throw new Error("no account record was written, so there is no doc-shim to name");
+  return record.g as Nuri;
+}
+
 /** The inbox recorded for a note, read off the WALLET — no application can ask the package. */
 function inboxOnTheNote(note: Nuri): Nuri {
   const record = quads.find((q) => q.p === `${SHIM}:inboxCap` && q.o.startsWith(note + " "));
@@ -527,6 +538,37 @@ describe("listing the inboxes when one of the two registers cannot be read", ()
     expect(partial.inboxes).not.toContain(inboxOnTheNote(note));
   });
 
+  /**
+   * The two shortfalls are not degrees of one condition — they are two, and the worse one is
+   * the one this suite exists for. The account record names the user's OWN two inboxes, which
+   * is where a share addressed to a PERSON lands, and it is also what the other half reads
+   * THROUGH; losing it means nothing at all is watched. Losing the User branch means those two
+   * are watched and only the per-document inboxes are missing. A caller handed `error` alone
+   * cannot tell which it is holding.
+   */
+  test("names WHICH register fell short, and the account record is the worse one", async () => {
+    await bobSharesWithAlice();
+    await converge(); // let the depositor's own session finish before the broker breaks
+    const shim = theDocShim();
+    // Another session, so nothing is answered from a warm cache. Her record is read first —
+    // that is what connecting does — and the broker goes away between that read and the one
+    // that names her inboxes. Both live in the doc-shim, so this is one hiccup, mid-list.
+    resetRegistryCache();
+    setCurrentUser("alice");
+    expect(await resolveAccount("alice")).not.toBeNull();
+    fake._failReadsOn.add(shim);
+    const listed = await enumerateMyInboxes();
+    fake._failReadsOn.delete(shim);
+
+    expect(listed.incomplete?.register).toBe("account-record");
+    expect(String(listed.incomplete?.error)).toContain("RepoNotFound");
+    // Nothing came back: not one inbox of hers can be named, so not one can be watched. That
+    // is what makes this shortfall a different report from the other one and not a louder
+    // copy of it — there, her own two are in the list.
+    expect(listed.inboxes).toEqual([]);
+    await converge();
+  });
+
   test("still REJECTS for the caller that cannot use a partial list", async () => {
     await signIn("alice");
     await storeRegistry.openDocumentInbox(await storeRegistry.createEntityDoc("public"));
@@ -596,6 +638,56 @@ describe("a register that stays unreadable", () => {
     expect(reported.filter((l) => /could not all be listed/.test(l))).toHaveLength(1);
   });
 
+  /**
+   * A shortfall is deduplicated per REGISTER, because there are two of them and they are not
+   * the same news.
+   *
+   * The account record failing leaves this identity with NOTHING watched — its own two
+   * inboxes included, which is where a share addressed to a PERSON lands. The User branch
+   * failing leaves those two watched and only the per-document inboxes missing. Remembering
+   * merely that "something was already said" made the second condition arrive in silence: the
+   * log went on describing a state that had stopped being the one the identity was in.
+   */
+  test("a shortfall on the OTHER register is reported, not swallowed as already said", async () => {
+    await bobSharesWithAlice();
+    await converge();
+    const shim = theDocShim();
+    const store = (await resolveAccount("alice"))?.docPrivate;
+    if (store === undefined) throw new Error("the fixture did not give Alice a private store");
+
+    const reported = await whileWatchingTheLog(async () => {
+      // Another session. Connecting reads her account record first, and the doc-shim goes
+      // away right after — so her own two inboxes cannot even be NAMED, and the document
+      // half is never reached. `signIn` taken in its two steps, which is all it is, so the
+      // hiccup can land where a hiccup lands: in the middle.
+      resetRegistryCache();
+      setCurrentUser("alice");
+      expect(await resolveAccount("alice")).not.toBeNull();
+      fake._failReadsOn.add(shim);
+      try {
+        await connectedUser();
+      } catch {
+        // The restore rejects on the unreadable shim; she is connected regardless.
+      }
+      await converge();
+
+      // The doc-shim answers again and the private store stops instead: her own two inboxes
+      // are watched now, and only the ones opened on documents are missing. A milder
+      // condition, a different one — and the application creating something is what makes
+      // the observation look again (`CapRegistry.onChange`).
+      fake._failReadsOn.delete(shim);
+      fake._failReadsOn.add(store);
+      await storeRegistry.createEntityDoc("protected");
+      await converge();
+    });
+    fake._failReadsOn.delete(store);
+
+    const shortfalls = reported.filter((l) => /could not all be listed/.test(l));
+    expect(shortfalls).toHaveLength(2);
+    expect(shortfalls.filter((l) => /the account record/.test(l))).toHaveLength(1);
+    expect(shortfalls.filter((l) => /inboxes opened on documents/.test(l))).toHaveLength(1);
+  });
+
   /**
    * Once per OCCURRENCE, and a second occurrence is a real one.
    *

packages/polyfill/test/subscribe.test.ts

@@ -41,7 +41,11 @@ const SESSION: RegistrySession = { sessionId: "sid-1", privateStoreId: "PRIV" };
  * exactly the assumption that cost this package a view that never re-read and an inbox that
  * never notified, and a fake that holds it cannot fail on either.
  */
-function makeFakeNg(failFor: Set<string> = new Set(), hangFor: Set<string> = new Set()) {
+function makeFakeNg(
+  failFor: Set<string> = new Set(),
+  hangFor: Set<string> = new Set(),
+  queueFor: Set<string> = new Set(),
+) {
   const subs = new Map<string, (r: unknown) => void>();
   // A call the broker has neither answered nor refused yet, so a LATER call can overtake it
   // and this one can settle afterwards. Held on an object rather than in a `let` so its
@@ -52,15 +56,16 @@ function makeFakeNg(failFor: Set<string> = new Set(), hangFor: Set<string> = new
     cb: ((r: unknown) => void) | null;
     live: boolean;
   } = { reject: null, resolve: null, cb: null, live: false };
-  const doc_subscribe = mock(async (nuri: string, _sid: unknown, cb: (r: unknown) => void) => {
+  /**
-    if (failFor.has(nuri)) throw new Error(`RepoNotFound: ${nuri}`);
+   * The broker's side of ONE `doc_subscribe`, at the moment it is SERVED — taking the branch
-    if (hangFor.has(nuri)) {
+   * over for `cb` and handing back the cancel.
-      return await new Promise((resolve, reject) => {
+   *
-        hung.reject = reject;
+   * Apart from the call because ACCEPTING a call and SERVING it are two moments, and the
-        hung.resolve = resolve as (unsub: () => void) => void;
+   * broker does not promise they happen in the same order (see {@link queued}). Everything
-        hung.cb = cb;
+   * that decides who holds the branch is here, so serving is one function call and a test can
-      });
+   * make it happen when it likes.
-    }
+   */
+  const serveBranch = (nuri: string, cb: (r: unknown) => void): (() => void) => {
     subs.set(nuri, cb); // whoever held this branch is dropped, without a word
     // Initial State push, delivered async (as the real RPC does) — and only while this
     // callback still holds the branch.
@@ -70,7 +75,47 @@ function makeFakeNg(failFor: Set<string> = new Set(), hangFor: Set<string> = new
     return () => {
       if (subs.get(nuri) === cb) subs.delete(nuri);
     };
+  };
+  /**
+   * Calls the broker has ACCEPTED and not yet SERVED, in the order they were issued.
+   *
+   * `subs.set` at call time would hardwire "served in the order issued", which is not
+   * something the platform offers: the whole call is serialised under one
+   * `async_std::sync::RwLock` (`sdk/rust/src/local_broker.rs:3057`) — but that IS
+   * `async_lock::RwLock` (async-std 1.13.2 `src/sync/mod.rs:181`), whose internal mutex is
+   * documented as "eventual fairness", explicitly not FIFO (async-lock 3.4.1
+   * `src/mutex.rs:22-24`), and whose anti-starvation fallback is compiled out on wasm
+   * (`src/mutex.rs:578-581`) — which is where this SDK runs. A fake that can only serve in
+   * issue order cannot fail on the state that assumption is wrong about.
+   */
+  const queued: Array<() => void> = [];
+  const doc_subscribe = mock(async (nuri: string, _sid: unknown, cb: (r: unknown) => void) => {
+    if (failFor.has(nuri)) throw new Error(`RepoNotFound: ${nuri}`);
+    if (hangFor.has(nuri)) {
+      return await new Promise((resolve, reject) => {
+        hung.reject = reject;
+        hung.resolve = resolve as (unsub: () => void) => void;
+        hung.cb = cb;
+      });
+    }
+    if (queueFor.has(nuri)) {
+      return await new Promise<() => void>((resolve) => {
+        queued.push(() => resolve(serveBranch(nuri, cb)));
+      });
+    }
+    return serveBranch(nuri, cb);
   });
+  /**
+   * Serve the accepted calls, in the order given — `serveQueued(1, 0)` serves the SECOND
+   * call first, which is the inversion the module's release-the-loser reasoning bets against.
+   */
+  const serveQueued = (...order: number[]): void => {
+    for (const i of order) {
+      const serve = queued[i];
+      if (!serve) throw new Error(`no call number ${i} was accepted (${queued.length} were)`);
+      serve();
+    }
+  };
   const push = (nuri: string): void => {
     subs.get(nuri)?.({ V0: { Patch: { doc: nuri } } });
   };
@@ -120,12 +165,13 @@ function makeFakeNg(failFor: Set<string> = new Set(), hangFor: Set<string> = new
     resolveHung,
     pushHung,
     hungIsLive,
+    serveQueued,
     _subs: subs,
   };
 }
 
-function inject(failFor?: Set<string>, hangFor?: Set<string>) {
+function inject(failFor?: Set<string>, hangFor?: Set<string>, queueFor?: Set<string>) {
-  const ng = makeFakeNg(failFor, hangFor);
+  const ng = makeFakeNg(failFor, hangFor, queueFor);
   configure({ ng: ng as any, useShape: (() => {}) as any });
   // Synchronous fake store → no sync lag; disable the anti-fork retry backoff.
   configureStoreRegistry({ getSession: async () => SESSION });
@@ -557,14 +603,112 @@ test("an establish SUPERSEDED while the session id resolves never reaches the br
   gate.release?.();
   await tick();
 
-  // ONE call, and it is the current attempt's. This is what makes "release a superseded
+  // ONE call, and it is the current attempt's. What that buys is exact and worth stating
-  // attempt" safe rather than a coin flip: every attempt that OWNS a channel placed its call
+  // exactly: an establish superseded in THIS window opens nothing, so there is no channel of
-  // before the attempt replacing it existed, so the broker — which serialises the whole call
+  // its own to release and no second call for the broker to order. It does not make releasing
-  // under one lock — served it first, and whoever inserts last holds the branch. The
+  // a superseded attempt safe in general — that rests on a bet about SERVICE order, which the
-  // superseded one is therefore always the evicted one, never the live channel.
+  // two tests below take apart.
   expect(ng.doc_subscribe).toHaveBeenCalledTimes(1);
   expect(ng.isSubscribed(A)).toBe(true);
   expect(seen.length).toBeGreaterThan(0);
   stop();
   expect(ng.isSubscribed(A)).toBe(false);
 });
+
+/**
+ * Two attempts on ONE branch, and the broker free to serve them in either order.
+ *
+ * `resubscribeDocs` re-opens a fan-out whose first establish has not settled, and the last
+ * listener leaving mid-establish then re-joining does the same against the SAME session — so
+ * two calls contending for one branch is a state this module reaches. Which of them ends up
+ * holding the branch is the broker's to decide, not this module's: the call is serialised
+ * under one `async_std::sync::RwLock` (`sdk/rust/src/local_broker.rs:3057`), and serialised
+ * is not ordered. That lock IS `async_lock::RwLock` (async-std 1.13.2 `src/sync/mod.rs:181`),
+ * `write()` takes its internal `async_lock::Mutex` first (async-lock 3.4.1
+ * `src/rwlock/raw.rs:163-168`), and that mutex is documented as "eventual fairness" and
+ * explicitly not FIFO (`src/mutex.rs:22-24`) — with the anti-starvation fallback that would
+ * eventually force fairness compiled out on wasm (`src/mutex.rs:578-581`), which is where
+ * this SDK runs.
+ *
+ * Both orders are therefore real, and they do not end the same way. The fake serves on
+ * demand (`serveQueued`) rather than at call time precisely so both can be exercised: a fake
+ * that inserts in call order asserts the happy one into existence.
+ */
+async function twoAttemptsOnOneBranch(): Promise<{
+  ng: ReturnType<typeof makeFakeNg>;
+  seen: unknown[];
+  failures: unknown[];
+  stop: Unsubscribe;
+}> {
+  const ng = inject(undefined, undefined, new Set([A]));
+  const seen: unknown[] = [];
+  const failures: unknown[] = [];
+  const stop = subscribeDocReportingSetupFailure(
+    A,
+    (r) => seen.push(r),
+    (e) => failures.push(e),
+  );
+  await tick(); // the first attempt has PLACED its call — the broker has it, unserved
+  expect(ng.doc_subscribe).toHaveBeenCalledTimes(1);
+  resubscribeDocs(); // …and is superseded, after the call, not before it
+  await tick();
+  expect(ng.doc_subscribe).toHaveBeenCalledTimes(2);
+  return { ng, seen, failures, stop };
+}
+
+test("served in the order issued, the superseded attempt is the one the broker evicted", async () => {
+  const { ng, seen, failures, stop } = await twoAttemptsOnOneBranch();
+
+  ng.serveQueued(0, 1); // the first call first — the order the module bets on
+  await tick();
+
+  // The current attempt inserted last, so it holds the branch; the superseded one released a
+  // channel that had already been displaced. The document is live and pushing.
+  expect(ng.isSubscribed(A)).toBe(true);
+  const before = seen.length;
+  ng.push(A);
+  expect(seen.length).toBe(before + 1);
+  expect(failures).toEqual([]);
+  stop();
+  expect(ng.isSubscribed(A)).toBe(false);
+});
+
+test("served in the INVERTED order, the document goes silently dead — nothing rejects, nothing logs", async () => {
+  const { ng, seen, failures, stop } = await twoAttemptsOnOneBranch();
+
+  const logged: string[] = [];
+  const realError = console.error;
+  console.error = ((...a: unknown[]) => {
+    logged.push(a.map(String).join(" "));
+  }) as typeof console.error;
+  try {
+    ng.serveQueued(1, 0); // the SECOND call served first — the bet, broken
+    await tick();
+  } finally {
+    console.error = realError;
+  }
+
+  // The superseded call inserted LAST, so it took the branch and closed the current
+  // attempt's sender (`engine/verifier/src/verifier.rs:361`); this module then released the
+  // channel that call had opened, because the attempt behind it is no longer current. What
+  // upstream is left holding is a closed sender, which `push_app_response` drops at the first
+  // push (`verifier.rs:258-261`) — here, a branch with nobody on it.
+  expect(ng.isSubscribed(A)).toBe(false);
+  const before = seen.length;
+  ng.push(A);
+  expect(seen.length).toBe(before); // the listener is subscribed and hears nothing
+
+  // And nothing anywhere says so. No rejection reaches the caller that ASKED to be told, and
+  // the log is clean: every call resolved, so there was no failure to report.
+  expect(failures).toEqual([]);
+  expect(logged).toEqual([]);
+
+  // The fan-out believes itself subscribed, which is what makes this last the session: it
+  // holds a `realUnsub` and `establishing` never went back to false, so the next joiner is
+  // handed the dead entry instead of opening a channel of its own.
+  const alsoStop = subscribeDoc(A, () => {});
+  await tick();
+  expect(ng.doc_subscribe).toHaveBeenCalledTimes(2); // no third call — nobody re-opens it
+  alsoStop();
+  stop();
+});