fix: une tentative dépassée n'ouvre plus rien, et libère ce qu'elle avait ouvert

packages/polyfill/src/surface/subscribe.ts

@@ -230,7 +230,15 @@ function fanOut(nuri: Nuri, entry: DocFanOut, resp: DocChange, type: DocChangeTy
   }
 }
 
-/** Is `attempt` still the establish this fan-out is waiting on? */
+/**
+ * Is `attempt` still the establish this fan-out is waiting on?
+ *
+ * Two independent ways to stop being it, and each is the only one that catches its own case:
+ * the fan-out was RELEASED (last listener left, or `resetDocSubscriptions`), which drops it
+ * from the map and leaves the counter untouched — so only the map half sees it; or it was
+ * SUPERSEDED in place by {@link resubscribeDocs}, which keeps the very same entry in the map
+ * and bumps the counter — so only the counter half sees it.
+ */
 function isCurrentAttempt(nuri: Nuri, entry: DocFanOut, attempt: number): boolean {
   return fanOuts.get(nuri) === entry && entry.attempt === attempt;
 }
@@ -307,6 +315,33 @@ function releaseFanOut(nuri: Nuri, entry: DocFanOut): void {
  * 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.
+ *
+ * ── Everything here is gated on the ATTEMPT, never on the entry alone ──────
+ * A superseded establish must not deliver, must not re-seed the barrier, and must not
+ * install its unsubscribe: {@link resubscribeDocs} re-opens the channel ON THE SAME entry,
+ * so entry identity says "this fan-out still stands" and says nothing about which call it is
+ * waiting on. Gated on identity only, a first attempt that SUCCEEDS after a second one has
+ * replaced it fans the PREVIOUS session's `State` out to every listener, re-seeds
+ * `lastState` with it — the exact stale barrier {@link resubscribeDocs} cleared it to
+ * prevent — and overwrites `realUnsub`, so the eventual teardown releases the dead channel
+ * and leaves the live one subscribed upstream.
+ *
+ * ── A superseded attempt is RELEASED, not dropped ──────────────────────────
+ * Dropping its unsubscribe would leak a live subscription. Upstream's `CancelFn` closes only
+ * its OWN `tx` and never touches `branch_subscriptions` (`engine/verifier/src/verifier.rs:479-484`),
+ * so releasing a loser cannot silence the winner — and cross-session there IS no winner to
+ * 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 ──────────────
+ * It is what makes the sentence above true rather than merely likely. Superseded while the
+ * session id was still resolving, this opens NO channel at all — so every attempt that owns
+ * 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
+ * served first. Whoever inserts last wins the branch (`verifier.rs:361`), so a superseded
+ * attempt is always the upstream LOSER, never the live channel. Without this guard the two
+ * calls could reach the broker in either order, and releasing the loser would be a coin flip
+ * on whether the document goes silent.
  */
 async function establish(
   nuri: Nuri,
@@ -322,17 +357,25 @@ async function establish(
   const doc_subscribe = ng.doc_subscribe as (...a: unknown[]) => unknown;
   try {
     const sid = await sessionId();
+    // Superseded (or torn down) while the session id was resolving: open NOTHING. Cheaper
+    // than opening a channel to close it, and it is what keeps a superseded attempt from
+    // ever reaching the broker AFTER the attempt that replaced it.
+    if (!isCurrentAttempt(nuri, entry, attempt)) return;
     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;
+      // A push that belongs to a torn-down fan-out, or to an establish that has been
+      // superseded — either way the real unsubscribe has not taken effect yet, and neither
+      // this fan-out's listeners nor its barrier are this call's to touch any more.
+      if (!isCurrentAttempt(nuri, entry, attempt)) return;
       const type = docChangeType(resp);
       // Remember the barrier for whoever joins next; a later `State` replaces it.
       if (type === "State") entry.lastState = { resp, type };
       fanOut(nuri, entry, 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 (!isCurrentAttempt(nuri, entry, attempt)) {
+      // Everyone left, the fan-out was reset, or a later establish replaced this one —
+      // release the channel this call just opened, because nothing else holds it. (A
+      // released fan-out is out of the map, which is why the listener count is not asked
+      // about separately: the last one out already took the entry with it.)
       if (typeof unsub === "function") unsub();
       return;
     }