diff --git a/.project/concepts/app-contract/_debt.md b/.project/concepts/app-contract/_debt.md new file mode 100644 index 0000000..1816980 --- /dev/null +++ b/.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) diff --git a/packages/polyfill/src/emulated-verifier/branch-registers.ts b/packages/polyfill/src/emulated-verifier/branch-registers.ts index 7fd6cf7..6fdcec0 100644 --- a/packages/polyfill/src/emulated-verifier/branch-registers.ts +++ b/packages/polyfill/src/emulated-verifier/branch-registers.ts @@ -502,10 +502,29 @@ export async function myInboxes(): Promise { 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 { } 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 { out.push(inbox); } } catch (error) { - return { inboxes: out, incomplete: { error } }; + return { inboxes: out, incomplete: { error, register: "user-branch" } }; } return { inboxes: out, incomplete: null }; } diff --git a/packages/polyfill/src/emulated-verifier/inbox-observer.ts b/packages/polyfill/src/emulated-verifier/inbox-observer.ts index 0504df4..163f138 100644 --- a/packages/polyfill/src/emulated-verifier/inbox-observer.ts +++ b/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>; } @@ -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 { * 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 { if (!current(obs)) return; @@ -207,10 +235,10 @@ async function watchTheInboxes(obs: Observation): Promise { } if (!current(obs)) return; if (listed.incomplete === null) { - obs.shortfallReported = false; - } else if (!obs.shortfallReported) { - obs.shortfallReported = true; - reportUnobserved("the inboxes to watch could not all be listed", listed.incomplete.error); + obs.shortfallReported = null; + } else if (obs.shortfallReported !== listed.incomplete.register) { + obs.shortfallReported = listed.incomplete.register; + 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 { holdings: null, enumerating: false, enumerateAgain: false, - shortfallReported: false, + shortfallReported: null, pending: new Set(), }; observation = obs; diff --git a/packages/polyfill/src/surface/subscribe.ts b/packages/polyfill/src/surface/subscribe.ts index 72e202c..cbe1fa0 100644 --- a/packages/polyfill/src/surface/subscribe.ts +++ b/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(); /** 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 ────────────── - * 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. + * ── Why the guard sits BEFORE the call, and what it does NOT settle ──────── + * What it settles is a fact: superseded while the session id was still resolving, this opens + * NO channel at all. That is the wider half of the window, and it closes it outright. + * + * What it leaves open is a BET, and it is written down here as one. For an attempt that DID + * place its call before being superseded, this code releases the channel that call opened — + * which is only ever releasing the upstream LOSER if the broker SERVED the two calls in the + * order they were ISSUED. Issuing is all this module can order; service is the broker's, and + * 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 diff --git a/packages/polyfill/test/continuous-inbox-observation.test.ts b/packages/polyfill/test/continuous-inbox-observation.test.ts index 0b69d01..dd55420 100644 --- a/packages/polyfill/test/continuous-inbox-observation.test.ts +++ b/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. * diff --git a/packages/polyfill/test/subscribe.test.ts b/packages/polyfill/test/subscribe.test.ts index f30db58..7e2ec13 100644 --- a/packages/polyfill/test/subscribe.test.ts +++ b/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 = new Set(), hangFor: Set = new Set()) { +function makeFakeNg( + failFor: Set = new Set(), + hangFor: Set = new Set(), + queueFor: Set = new Set(), +) { const subs = new Map 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 = new Set(), hangFor: Set = 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}`); - if (hangFor.has(nuri)) { - return await new Promise((resolve, reject) => { - hung.reject = reject; - hung.resolve = resolve as (unsub: () => void) => void; - hung.cb = cb; - }); - } + /** + * The broker's side of ONE `doc_subscribe`, at the moment it is SERVED — taking the branch + * over for `cb` and handing back the cancel. + * + * Apart from the call because ACCEPTING a call and SERVING it are two moments, and the + * broker does not promise they happen in the same order (see {@link queued}). Everything + * 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 = new Set(), hangFor: Set = 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 = new Set(), hangFor: Set = new resolveHung, pushHung, hungIsLive, + serveQueued, _subs: subs, }; } -function inject(failFor?: Set, hangFor?: Set) { - const ng = makeFakeNg(failFor, hangFor); +function inject(failFor?: Set, hangFor?: Set, queueFor?: Set) { + 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 - // attempt" safe rather than a coin flip: every attempt that OWNS a channel placed its call - // before the attempt replacing it existed, so the broker — which serialises the whole call - // under one lock — served it first, and whoever inserts last holds the branch. The - // superseded one is therefore always the evicted one, never the live channel. + // ONE call, and it is the current attempt's. What that buys is exact and worth stating + // exactly: an establish superseded in THIS window opens nothing, so there is no channel of + // its own to release and no second call for the broker to order. It does not make releasing + // a superseded attempt safe in general — that rests on a bet about SERVICE order, which the + // 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; + 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(); +});