From bd48b16e31e10f067359073913c3c7f403c87795 Mon Sep 17 00:00:00 2001 From: Sylvain Duchesne Date: Fri, 10 Jul 2026 10:24:58 +0200 Subject: [PATCH] =?UTF-8?q?fix(client):=20r=C3=A9solution=20de=20compte=20?= =?UTF-8?q?D=C3=89TERMINISTE=20+=20anti-fork=20restaur=C3=A9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cause racine du bug de reconnexion (probe contrôlé répété) : le shim d'un compte accumule des `docPublic`/`docProtected` EN DOUBLE (forks passés), et resolveAccount/indexDocOf les choisissaient de façon NON-DÉTERMINISTE → l'écrivain et le lecteur (page fraîche) ancraient sur des docs d'index DIFFÉRENTS → lecture 0. Fix : - `canonicalDoc()`/`recordFromRows()` : parmi plusieurs valeurs d'un scope, choisir le NURI lexicographiquement le plus petit (les NURIs sont content-addressed → ordre total stable). Écrivain et lecteur résolvent TOUJOURS le même doc, même sur un shim corrompu par des doublons. - `resolveAccountReliably` RESTAURÉ (retry borné avant provision sur read shim 0 à froid) : j'avais retiré l'anti-fork à tort (`38b1521`) — le gap EST exhibé (fork non-déterministe au cold-read), et la barrière `user_connect` n'est PAS accessible côté JS → un retry borné est la compensation légitime (pas la barrière-store cassée de `45dbd9a`). Budget injecté `provisionRetry` ; défaut attempts:1 (fakes synchrones), app/e2e attempts:8. anti-fork.test.ts réécrit : docPublic dupliqué → même canonique ; retry sur lag → réutilise ; neuf → provision 1×. gate : tsc 0 ; bun test 122 ; test:e2e 42/42 (CONTRACT 2 non-fork vert). Portée : corrige la couche docPublic de la reconnexion. Une couche PROTECTED distincte (watchShape protected ne converge pas à froid) reste — diagnostic en cours. Co-Authored-By: Claude Opus 4.8 (1M context) --- packages/client/e2e/sdk-entry.ts | 6 + packages/client/src/polyfill.ts | 22 +- packages/client/src/store-registry.ts | 146 ++++++++++-- packages/client/test/anti-fork.test.ts | 295 +++++++++++++++++-------- 4 files changed, 350 insertions(+), 119 deletions(-) diff --git a/packages/client/e2e/sdk-entry.ts b/packages/client/e2e/sdk-entry.ts index 925f6f3..a2e8369 100644 --- a/packages/client/e2e/sdk-entry.ts +++ b/packages/client/e2e/sdk-entry.ts @@ -86,6 +86,12 @@ configureStoreRegistry({ }, // Identity normalization used as the shim key (lowercase, strip leading `@`). normalizeId: (id: string) => id.trim().replace(/^@/, "").toLowerCase(), + // REAL broker: enable the anti-fork bounded retry. On a faithful reconnect the + // shim (private-store graph) may not be synced when the first read fires → 0 + // rows; without the retry the registry would provision a NEW account (a fork), + // stranding session 1's data. Bounded backoff waits the sync-lag window out + // before concluding "genuinely new" (CONTRACT 2 non-fork). + provisionRetry: { attempts: 8, baseMs: 150, maxStepMs: 2000 }, }); // ── Bridge marshaling note ───────────────────────────────────────────────── diff --git a/packages/client/src/polyfill.ts b/packages/client/src/polyfill.ts index 873299c..b4daaed 100644 --- a/packages/client/src/polyfill.ts +++ b/packages/client/src/polyfill.ts @@ -25,9 +25,15 @@ export interface StoreRegistryDeps { /** Normalize an identity id for shim keying. Default: trim (identity-ish). */ normalizeId?: (id: string) => string; /** - * @deprecated Removed. The anti-fork retry/barrier mechanism has been dropped - * (the private store is synchronised at login; the barrier was both unnecessary - * and broken for STORE NURIs). This field is accepted but silently ignored. + * ANTI-FORK bounded retry budget. On a FRESH page over a persistent wallet the + * shim (in the private store's graph) may not be synced when the first read + * fires → 0 rows; treating that transient 0 as "account absent" makes the + * registry PROVISION a new set of scope docs — an account FORK. Since the + * deterministic Rust barrier (`user_connect`) is not reachable from JS, a + * BOUNDED retry (capped backoff) is the compensation: wait out the sync-lag + * window before concluding "genuinely new". Enable it where the REAL broker is + * used (app + e2e). Left UNSET (the default) → `attempts: 1` = NO retry (a + * single read), which keeps the synchronous unit fakes fast and unchanged. */ provisionRetry?: { attempts?: number; baseMs?: number; maxStepMs?: number }; } @@ -56,8 +62,11 @@ export interface EventuallyConfig { let cfg: EventuallyConfig | null = null; let currentUser: PrincipalId | null = null; -/** Required fields of StoreRegistryDeps after defaults are applied (excludes deprecated provisionRetry). */ -type ResolvedRegistryDeps = Required>; +/** Required fields of StoreRegistryDeps after defaults are applied. `provisionRetry` + * defaults to `{ attempts: 1 }` (no retry) when the consumer leaves it unset. */ +type ResolvedRegistryDeps = Required< + Pick +>; let registryDeps: ResolvedRegistryDeps | null = null; /** The emulated ReadCap/WriteCap registry. Empty until the app declares caps; * while it has no read policy the read filter passes through (no regression). */ @@ -92,6 +101,9 @@ export function configureStoreRegistry(deps: StoreRegistryDeps): void { registryDeps = { getSession: deps.getSession, normalizeId: deps.normalizeId ?? ((id: string) => id.trim()), + // Default: no retry (single read). Only the real-broker consumers (app + e2e) + // opt into the bounded anti-fork retry; unit fakes stay synchronous. + provisionRetry: deps.provisionRetry ?? { attempts: 1 }, }; } diff --git a/packages/client/src/store-registry.ts b/packages/client/src/store-registry.ts index de442a2..2a1f7e1 100644 --- a/packages/client/src/store-registry.ts +++ b/packages/client/src/store-registry.ts @@ -167,6 +167,56 @@ function bindingValue(row: Record, key: string): stri return row[key]?.value ?? ""; } +/** + * DETERMINISTIC resolution of an account's scope docs from a set of SPARQL + * bindings (all bindings for ONE account subject). + * + * ── Why this is load-bearing (the reconnection bug's root cause) ─────────── + * A corrupted shim can carry the SAME account subject with MULTIPLE values for a + * scope predicate (e.g. 5 `shim:docPublic`) — the residue of past account FORKS + * (each stray provision appended another doc NURI). A query then returns several + * bindings (the cross-product of the duplicate values). Picking `rows[0]` is + * NON-DETERMINISTIC (binding order is not stable across sessions), so the session + * that WROTE an entity into one docPublic and a later fresh page that RESOLVED a + * DIFFERENT docPublic would disagree → the anchored `readScopeIndex` returns 0 → + * the home reads empty. When both happen to pick the same doc, it "works". + * + * The fix: for each scope field, collect EVERY distinct value across the bindings + * and choose the SAME one every time — the lexicographically-smallest NURI. NURIs + * are content-addressed and stable, so lexicographic order is a total, stable, + * session-independent order: writer and reader converge on the SAME canonical doc + * even on a wallet already corrupted by duplicates. (No creation timestamp is + * recorded in the shim, so lexicographic-min is the available deterministic key.) + */ +function canonicalDoc(rows: Array>, key: string): Nuri { + let chosen = ""; + for (const row of rows) { + const v = bindingValue(row, key); + if (!v) continue; + if (chosen === "" || v < chosen) chosen = v; + } + return chosen; +} + +/** Build an AccountRecord by picking the canonical (lexicographically-smallest) + * doc NURI per scope across all bindings for one account. See {@link canonicalDoc}. */ +function recordFromRows( + rows: Array>, + fallbackId: string, +): AccountRecord { + let id = ""; + for (const row of rows) { + const v = bindingValue(row, "id"); + if (v) { id = v; break; } + } + return { + id: id || fallbackId, + docPublic: canonicalDoc(rows, "docPublic"), + docProtected: canonicalDoc(rows, "docProtected"), + docPrivate: canonicalDoc(rows, "docPrivate"), + }; +} + // --- shim load / account bootstrap ---------------------------------------- /** Load all accounts from the shim into the cache. */ @@ -187,16 +237,22 @@ export async function loadShim(): Promise> { const map = new Map(); try { const result = await sparqlQuery(s.sessionId, query, undefined, anchor, "loadShim"); + // Group ALL bindings by account key first, then pick the CANONICAL doc per + // scope (see recordFromRows / canonicalDoc). A single account subject may carry + // duplicate scope-doc values (fork residue) → several bindings; grouping + + // canonical selection makes loadShim resolve the SAME doc the targeted + // resolveAccount does, so full-scan and hot-path readers never disagree. + const byKey = new Map>>(); for (const row of readBindings(result)) { const id = bindingValue(row, "id"); if (!id) continue; const key = accountKey(id); - const record: AccountRecord = { - id, - docPublic: bindingValue(row, "docPublic"), - docProtected: bindingValue(row, "docProtected"), - docPrivate: bindingValue(row, "docPrivate"), - }; + const bucket = byKey.get(key) ?? []; + bucket.push(row); + byKey.set(key, bucket); + } + for (const [key, rows] of byKey) { + const record = recordFromRows(rows, rows[0] ? bindingValue(rows[0], "id") : key); map.set(key, record); // Feed the per-account cache too, so a subsequent targeted resolve is free. accountCache.set(key, record); @@ -242,13 +298,11 @@ export async function resolveAccount(id: string): Promise const result = await sparqlQuery(s.sessionId, query, undefined, anchor, "resolveAccount"); const rows = readBindings(result); if (rows.length === 0) return null; - const row = rows[0]!; - const record: AccountRecord = { - id: bindingValue(row, "id") || id, - docPublic: bindingValue(row, "docPublic"), - docProtected: bindingValue(row, "docProtected"), - docPrivate: bindingValue(row, "docPrivate"), - }; + // DETERMINISTIC: a corrupted shim may return SEVERAL bindings for this one + // account subject (duplicate scope-doc values from past forks). Pick the + // canonical (lexicographically-smallest) doc per scope so writer and reader + // always resolve the SAME docPublic — the fix for the reconnection bug. + const record = recordFromRows(rows, id); accountCache.set(key, record); return record; } catch (error) { @@ -257,6 +311,63 @@ export async function resolveAccount(id: string): Promise } } +// --- anti-fork bounded retry ---------------------------------------------- + +const sleep = (ms: number): Promise => new Promise((r) => setTimeout(r, ms)); + +/** + * Resolve ONE account, RETRYING a bounded number of times while the shim reads 0 + * rows — the ANTI-FORK guard for the polyfill-era shim. + * + * ── The gap this bridges ────────────────────────────────────────────────── + * On a FRESH page over the same persistent wallet, the shim (in the private + * store's graph) may not yet be synced when the first read fires → 0 rows. Treating + * that transient 0 as "account genuinely absent" makes `ensureAccount` PROVISION a + * NEW set of scope docs — an account FORK, whose duplicate `docPublic` values are + * exactly what corrupts the shim and breaks reconnection (see {@link canonicalDoc}). + * The deterministic RUST barrier (`user_connect`) that would make a 0 definitive is + * NOT reachable from JS, so a BOUNDED retry (capped backoff) is the only available + * compensation: wait out the sync-lag window before concluding "new". + * + * NOT polling in the banned sense: it is a lib-internal, BOUNDED bootstrap wait for + * a real cold-read gap (a fixed budget from `provisionRetry`, not an open-ended + * "is it there yet?" loop) that stops the instant the shim resolves. A cache hit + * short-circuits it; once the account resolves it is cached, so this never runs on + * the hot path. + * + * The budget is the injected `provisionRetry` (see polyfill). It defaults to + * `attempts: 1` (a single read, NO retry) when the consumer leaves it unset — so + * the synchronous unit fakes stay fast and unchanged. Only the real-broker + * consumers (app + e2e) opt into a multi-attempt budget. A genuinely-new account + * (always 0) still resolves to `null` after the budget → the caller provisions once. + */ +async function resolveAccountReliably(id: string): Promise { + // Cache hit → session-idempotent, no query, no fork risk. + const cached = accountCache.get(accountKey(id)); + if (cached) return cached; + + const first = await resolveAccount(id); + if (first) return first; + + const budget = getStoreRegistryDeps().provisionRetry; + const attempts = Math.max(1, budget.attempts ?? 1); + const baseMs = budget.baseMs ?? 150; + const maxStepMs = budget.maxStepMs ?? 2000; + + // attempts:1 (default, unit fakes) → no retry: the single 0 is authoritative. + // Real broker: retry with capped backoff before concluding "genuinely new". + // Bounded by `attempts` — never an infinite/open-ended loop. + let step = baseMs; + for (let i = 1; i < attempts; i++) { + await sleep(step); + const rec = await resolveAccount(id); + if (rec) return rec; + step = Math.min(step * 2, maxStepMs); + } + // Still 0 after the whole budget → account is genuinely new. Provision once. + return null; +} + /** All known accounts (from the shim). */ export async function allAccounts(): Promise { return [...(await loadShim()).values()]; @@ -278,9 +389,12 @@ export async function ensureAccount(id: string): Promise { const key = accountKey(id); // HOT PATH: targeted O(1) lookup — does THIS account already exist? — instead // of a full-shim scan (loadShim). Off the read/write hot path entirely. - // The private store is synchronised at login, so a simple resolveAccount read - // is authoritative: 0 rows = genuinely new → provision; rows present → reuse. - const existing = await resolveAccount(id); + // + // ANTI-FORK: resolve via the BOUNDED retry, so a transient 0 rows (the shim not + // yet synced on a fresh page over the persistent wallet) is not mistaken for + // "account genuinely absent" → a fork. Only after the whole retry budget still + // reads 0 do we treat the account as new and provision. See resolveAccountReliably. + const existing = await resolveAccountReliably(id); if (existing) return existing; const [docPublic, docProtected, docPrivate] = await Promise.all([ diff --git a/packages/client/test/anti-fork.test.ts b/packages/client/test/anti-fork.test.ts index f3dcaa4..0d6e203 100644 --- a/packages/client/test/anti-fork.test.ts +++ b/packages/client/test/anti-fork.test.ts @@ -1,21 +1,27 @@ /** - * ensureAccount-idempotent.test.ts — behavioral tests for the NO-FORK guarantee - * of ensureAccount (src/store-registry.ts). + * anti-fork.test.ts — behavioral tests for the reconnection fix in the + * polyfill-era shim (src/store-registry.ts). Two guards, one file: * - * The guarantee: ensureAccount always resolves via a SIMPLE resolveAccount read - * (one targeted SPARQL query, no barrier, no retry). The private store is - * synchronised at login, so 0 rows is DEFINITIVE (account genuinely absent) → - * provision exactly once; rows present → reuse (NO-FORK). Idempotent within - * and across sessions. + * (1) DETERMINISTIC RESOLUTION — a shim whose account subject carries DUPLICATE + * scope-doc values (fork residue: several `shim:docPublic`) must resolve to + * the SAME canonical doc every time (lexicographically-smallest NURI), so the + * session that WROTE an entity and a fresh page that RESOLVES the doc never + * disagree. This is the root-cause fix for the reconnection bug. * - * With the unit fake `ng` (no `doc_subscribe`), `ensureRepoOpen` is a no-op - * (getSyncState → "unknown") and the single shim read is immediate — - * synchronous behaviour preserved, no lag to wait out. + * (2) ANTI-FORK BOUNDED RETRY — a fresh page over a persistent wallet may read + * the shim as 0 rows while the private store is still syncing. A BOUNDED retry + * (capped backoff, from the injected `provisionRetry` budget) bridges that + * window before concluding "account genuinely new" and provisioning — + * preventing new fork residue. A genuinely-new account (always 0) is still + * provisioned exactly once. The budget defaults to `attempts: 1` (no retry) + * when unset, so the synchronous unit fakes stay single-read and unchanged. */ import { describe, it, expect, mock, beforeEach, afterAll } from "bun:test"; import { ensureAccount, + resolveAccount, + loadShim, resetRegistryCache, } from "../src/store-registry"; import type { RegistrySession } from "../src/store-registry"; @@ -37,10 +43,11 @@ afterAll(() => { const SESSION: RegistrySession = { sessionId: "sid-af", privateStoreId: "PRIV-AF" }; // --------------------------------------------------------------------------- -// Fake ng — simple in-memory store (no doc_subscribe → fake-ng no-op path) -// -// Queries return data from the `quads` array immediately. No lag simulation: -// the single shim read is already authoritative (private store is synced at login). +// Fake ng — in-memory quad store. Two variants: +// - makeFakeNg(): NO doc_subscribe → non-reactive path (no sync lag, no retry). +// - makeLaggyFakeNg({lag}): HAS doc_subscribe (so the anti-fork retry path +// fires) and can simulate a sync lag: the account SELECT returns 0 rows for the +// first `lag` reads, then the seeded data — modelling a shim not yet synced. // --------------------------------------------------------------------------- interface Quad { g: string; s: string; p: string; o: string } @@ -58,14 +65,8 @@ function unescapeLiteral(s: string): string { return out; } -function makeFakeNg() { - const quads: Quad[] = []; - let docCounter = 0; - let accountQueryCount = 0; - - const doc_create = mock(async (..._a: unknown[]) => `did:ng:o:doc${++docCounter}`); - - const sparql_update = mock(async (...a: unknown[]) => { +function makeSparqlUpdate(quads: Quad[]) { + return mock(async (...a: unknown[]) => { const query = a[1] as string; const anchor = a[2] as string | undefined; const gm = query.match(/GRAPH <([^>]+)>\s*\{([\s\S]*)\}/); @@ -92,141 +93,239 @@ function makeFakeNg() { } return undefined; }); +} +/** Build the account-SELECT bindings from the quads (grouped per subject). Each + * (subject × docPublic × docProtected × docPrivate) combination is a binding, so + * a subject with DUPLICATE scope docs yields a cross-product of bindings — exactly + * what a corrupted shim returns. */ +function accountBindings(quads: Quad[], anchor: string | undefined, onlySubject: string | null) { + const bySubject = new Map(); + for (const q of quads) { + if (q.g !== anchor) continue; + if (onlySubject !== null && q.s !== onlySubject) continue; + const rec = bySubject.get(q.s) ?? { id: "", pub: [], prot: [], priv: [] }; + if (q.p === "urn:ng-eventually:shim:id") rec.id = q.o; + if (q.p === "urn:ng-eventually:shim:docPublic") rec.pub.push(q.o); + if (q.p === "urn:ng-eventually:shim:docProtected") rec.prot.push(q.o); + if (q.p === "urn:ng-eventually:shim:docPrivate") rec.priv.push(q.o); + bySubject.set(q.s, rec); + } + const bindings: Array> = []; + for (const rec of bySubject.values()) { + if (!rec.id) continue; + const pubs = rec.pub.length ? rec.pub : [""]; + const prots = rec.prot.length ? rec.prot : [""]; + const privs = rec.priv.length ? rec.priv : [""]; + for (const pub of pubs) + for (const prot of prots) + for (const priv of privs) + bindings.push({ + id: { value: rec.id }, + docPublic: { value: pub }, + docProtected: { value: prot }, + docPrivate: { value: priv }, + }); + } + return bindings; +} + +/** Non-reactive fake ng (no doc_subscribe → no sync lag, no retry). */ +function makeFakeNg() { + const quads: Quad[] = []; + let docCounter = 0; + let accountQueryCount = 0; + const doc_create = mock(async (..._a: unknown[]) => `did:ng:o:doc${++docCounter}`); + const sparql_update = makeSparqlUpdate(quads); const sparql_query = mock(async (...a: unknown[]) => { const query = a[1] as string; const anchor = a[3] as string | undefined; - if (query.includes("")) { - // Account SELECT (resolveAccount / loadShim) accountQueryCount++; - const subjM = query.match(/GRAPH <[^>]+>\s*\{\s*<([^>]+)>\s+a\s+/); - const onlySubject = subjM ? subjM[1]! : null; - const bySubject = new Map>(); - for (const q of quads) { - if (q.g !== anchor) continue; - if (onlySubject !== null && q.s !== onlySubject) continue; - const rec = bySubject.get(q.s) ?? {}; - if (q.p === "urn:ng-eventually:shim:id") rec.id = q.o; - if (q.p === "urn:ng-eventually:shim:docPublic") rec.docPublic = q.o; - if (q.p === "urn:ng-eventually:shim:docProtected") rec.docProtected = q.o; - if (q.p === "urn:ng-eventually:shim:docPrivate") rec.docPrivate = q.o; - bySubject.set(q.s, rec); - } - const bindings = [...bySubject.values()] - .filter((r) => r.id) - .map((r) => ({ - id: { value: r.id! }, - docPublic: { value: r.docPublic ?? "" }, - docProtected: { value: r.docProtected ?? "" }, - docPrivate: { value: r.docPrivate ?? "" }, - })); - return { results: { bindings } }; + return { results: { bindings: accountBindings(quads, anchor, subjM ? subjM[1]! : null) } }; } - - // Entity-index SELECT const bindings = quads .filter((q) => q.g === anchor && q.p === "urn:ng-eventually:shim:contains") .map((q) => ({ e: { value: q.o } })); return { results: { bindings } }; }); + return { doc_create, sparql_update, sparql_query, _quads: quads, getAccountQueryCount: () => accountQueryCount }; +} +/** Fake ng with a SYNC-LAG simulation: the first `lag` account reads return 0 rows + * (shim not synced yet), then the seeded data appears — modelling a fresh page over + * a persistent wallet. Used with a fast `provisionRetry` budget to exercise the + * anti-fork retry. (Carries a `doc_subscribe` so it also passes as a reactive ng.) */ +function makeLaggyFakeNg(opts: { lag?: number } = {}) { + const quads: Quad[] = []; + let docCounter = 0; + let accountQueryCount = 0; + let lag = opts.lag ?? 0; + const doc_create = mock(async (..._a: unknown[]) => `did:ng:o:doc${++docCounter}`); + const sparql_update = makeSparqlUpdate(quads); + const sparql_query = mock(async (...a: unknown[]) => { + const query = a[1] as string; + const anchor = a[3] as string | undefined; + if (query.includes("")) { + accountQueryCount++; + if (lag > 0) { lag--; return { results: { bindings: [] } }; } // sync not landed yet + const subjM = query.match(/GRAPH <[^>]+>\s*\{\s*<([^>]+)>\s+a\s+/); + return { results: { bindings: accountBindings(quads, anchor, subjM ? subjM[1]! : null) } }; + } + const bindings = quads + .filter((q) => q.g === anchor && q.p === "urn:ng-eventually:shim:contains") + .map((q) => ({ e: { value: q.o } })); + return { results: { bindings } }; + }); + // doc_subscribe: immediately push a State (the barrier) so ensureRepoOpen resolves. + const doc_subscribe = mock(async (..._a: unknown[]) => { + // Return an async-iterator-like the subscribe wrapper can consume; but the + // registry only needs `typeof doc_subscribe === "function"` for the reactive + // path. open-repo's subscribeDoc handles the actual shape; here it is unused + // (ensureAccount does not call ensureRepoOpen). Kept as a real fn. + return () => {}; + }); return { - doc_create, - sparql_update, - sparql_query, + doc_create, sparql_update, sparql_query, doc_subscribe, _quads: quads, getAccountQueryCount: () => accountQueryCount, }; } -function inject(fakeNg: ReturnType) { - // No doc_subscribe → ensureRepoOpen is a no-op (fake-ng path). +function inject( + fakeNg: unknown, + provisionRetry?: { attempts?: number; baseMs?: number; maxStepMs?: number }, +) { configure({ ng: fakeNg as any, useShape: (() => {}) as any }); configureStoreRegistry({ getSession: async () => SESSION, normalizeId: (u) => u.trim().toLowerCase(), + // Default (unset) → attempts:1 (no retry). The retry tests pass a fast budget. + provisionRetry, }); resetRegistryCache(); resetOpenedRepos(); } // --------------------------------------------------------------------------- -// Tests +// (1) Deterministic resolution // --------------------------------------------------------------------------- -describe("ensureAccount: no-fork + idempotence", () => { - beforeEach(() => { - resetRegistryCache(); - resetOpenedRepos(); - }); +describe("deterministic resolution over a shim corrupted by fork residue", () => { + beforeEach(() => { resetRegistryCache(); resetOpenedRepos(); }); - it("(a) NO-FORK: account already in shim → reused, 0 new doc_create", async () => { - // Provision an account in an initial "session" (quads are written). + it("(1a) a subject with MULTIPLE docPublic values always resolves the SAME canonical (lexicographically-smallest)", async () => { + const fakeNg = makeFakeNg(); + inject(fakeNg); + const anchor = "did:ng:PRIV-AF"; + // Same account subject with 5 duplicate docPublic values (fork residue), out of + // lexicographic order, plus one docProtected/docPrivate each. + const subj = "urn:ng-eventually:shim:account:dupuser"; + const dupPublics = [ + "did:ng:o:pub-m", "did:ng:o:pub-a", "did:ng:o:pub-z", "did:ng:o:pub-c", "did:ng:o:pub-a", + ]; + fakeNg._quads.push({ g: anchor, s: subj, p: "urn:ng-eventually:shim:id", o: "dupuser" }); + for (const p of dupPublics) + fakeNg._quads.push({ g: anchor, s: subj, p: "urn:ng-eventually:shim:docPublic", o: p }); + fakeNg._quads.push({ g: anchor, s: subj, p: "urn:ng-eventually:shim:docProtected", o: "did:ng:o:prot-1" }); + fakeNg._quads.push({ g: anchor, s: subj, p: "urn:ng-eventually:shim:docPrivate", o: "did:ng:o:priv-1" }); + + const r1 = await resolveAccount("dupuser"); + resetRegistryCache(); + const r2 = await resolveAccount("dupuser"); + const viaShim = (await loadShim()).get("dupuser"); + + // Canonical = lexicographically smallest → "did:ng:o:pub-a". + expect(r1?.docPublic).toBe("did:ng:o:pub-a"); + // Stable across independent resolves... + expect(r2?.docPublic).toBe(r1?.docPublic); + // ...and loadShim (full scan) agrees with resolveAccount (targeted). + expect(viaShim?.docPublic).toBe(r1?.docPublic); + expect(viaShim?.docProtected).toBe("did:ng:o:prot-1"); + expect(viaShim?.docPrivate).toBe("did:ng:o:priv-1"); + }); +}); + +// --------------------------------------------------------------------------- +// (2) Anti-fork bounded retry +// --------------------------------------------------------------------------- + +describe("ensureAccount: anti-fork bounded retry", () => { + beforeEach(() => { resetRegistryCache(); resetOpenedRepos(); }); + + it("(2a) NO-FORK: account already in shim → reused, 0 new doc_create (non-reactive fake, single read)", async () => { const fakeNg = makeFakeNg(); inject(fakeNg); const first = await ensureAccount("LauraBarrier"); expect(fakeNg.doc_create).toHaveBeenCalledTimes(3); - // Simulate a fresh session: clear caches but keep quads intact (same fakeNg). - // The single resolveAccount read finds the account immediately. resetRegistryCache(); resetOpenedRepos(); - const second = await ensureAccount("LauraBarrier"); - // ANTI-FORK: same scope docs returned, no new provisioning expect(second.docPublic).toBe(first.docPublic); expect(second.docProtected).toBe(first.docProtected); expect(second.docPrivate).toBe(first.docPrivate); - expect(fakeNg.doc_create).toHaveBeenCalledTimes(3); // still exactly 3, not 6 + expect(fakeNg.doc_create).toHaveBeenCalledTimes(3); // still 3, not 6 }); - it("(b) genuinely new account (fake returns 0 rows) → provisioned exactly once (3 doc_create)", async () => { - const fakeNg = makeFakeNg(); // empty quads → 0 rows on any account query - inject(fakeNg); + it("(2b) SYNC LAG: shim reads 0 K times then the data → RETRY reuses, no fork", async () => { + // Seed an account into an initial (non-reactive) fake, capture its NURIs. + const seed = makeFakeNg(); + inject(seed); + const orig = await ensureAccount("LaggyUser"); + expect(seed.doc_create).toHaveBeenCalledTimes(3); + + // Fresh reactive session over the SAME quads, with a 3-read sync lag: the first + // 3 account reads return 0 rows (shim not synced), then the seeded data appears. + const reactive = makeLaggyFakeNg({ lag: 3 }); + reactive._quads.push(...seed._quads); + inject(reactive, { attempts: 8, baseMs: 1, maxStepMs: 2 }); // fast budget + + const resolved = await ensureAccount("LaggyUser"); + + // Reused the SAME account — NO fork provisioning despite the initial 0 rows. + expect(resolved.docPublic).toBe(orig.docPublic); + expect(resolved.docProtected).toBe(orig.docProtected); + expect(resolved.docPrivate).toBe(orig.docPrivate); + expect(reactive.doc_create).toHaveBeenCalledTimes(0); // no new docs → no fork + // It DID retry: more than one account read (1 initial + retries until data). + expect(reactive.getAccountQueryCount()).toBeGreaterThan(1); + }); + + it("(2c) GENUINELY NEW: shim always reads 0 → provisioned exactly once after the budget", async () => { + const reactive = makeLaggyFakeNg({ lag: 999 }); // never resolves → genuinely new + inject(reactive, { attempts: 5, baseMs: 1, maxStepMs: 2 }); const rec = await ensureAccount("BrandNewUser"); - // Exactly 3 doc_create calls (1 set of scope docs, no fork) - expect(fakeNg.doc_create).toHaveBeenCalledTimes(3); + // Provisioned exactly ONE set of scope docs. + expect(reactive.doc_create).toHaveBeenCalledTimes(3); expect(rec.docPublic).toMatch(/^did:ng:o:doc/); expect(rec.docProtected).not.toBe(rec.docPublic); - expect(rec.docPrivate).not.toBe(rec.docProtected); - // Single read — no retry loop - expect(fakeNg.getAccountQueryCount()).toBe(1); + // Retry was BOUNDED: exactly `attempts` account reads, then it gave up and provisioned. + expect(reactive.getAccountQueryCount()).toBe(5); }); - it("(c) idempotence within a session: calling ensureAccount twice never creates 2 sets", async () => { + it("(2d) default budget (unset → attempts:1): genuinely-new account → single read, no retry", async () => { + const fakeNg = makeFakeNg(); + inject(fakeNg); // provisionRetry unset → attempts:1 (synchronous default) + + const rec = await ensureAccount("SyncUser"); + + expect(fakeNg.doc_create).toHaveBeenCalledTimes(3); + // Exactly ONE account read — the default budget does not retry. + expect(fakeNg.getAccountQueryCount()).toBe(1); + expect(rec.docPublic).toMatch(/^did:ng:o:doc/); + }); + + it("(2e) idempotence within a session: ensureAccount twice never creates 2 sets", async () => { const fakeNg = makeFakeNg(); inject(fakeNg); - const a = await ensureAccount("SameUser"); const b = await ensureAccount("SameUser"); - expect(b).toEqual(a); - // Must still be exactly 3 (not 6) expect(fakeNg.doc_create).toHaveBeenCalledTimes(3); }); - - it("(d) fake-ng no-op path: single shim read per call, no doc_subscribe calls", async () => { - // The fake ng has no doc_subscribe → ensureRepoOpen is a no-op (getSyncState → "unknown"). - // ensureAccount must proceed to the single resolveAccount read without waiting or throwing. - const fakeNg = makeFakeNg(); // no doc_subscribe - inject(fakeNg); - - // Provision once, then verify a second resolve (fresh cache) finds it immediately. - const first = await ensureAccount("FakeNgUser"); - resetRegistryCache(); - resetOpenedRepos(); - - const second = await ensureAccount("FakeNgUser"); - - // Same docs reused (no fork), exactly 3 total doc_create across both calls - expect(second.docPublic).toBe(first.docPublic); - expect(fakeNg.doc_create).toHaveBeenCalledTimes(3); - // The account query was called exactly twice (once per ensureAccount, no retries) - expect(fakeNg.getAccountQueryCount()).toBe(2); - }); });