fix(client): résolution de compte DÉTERMINISTE + anti-fork restauré

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) <noreply@anthropic.com>

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 ─────────────────────────────────────────────────

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
+   * ANTI-FORK bounded retry budget. On a FRESH page over a persistent wallet the
-   * (the private store is synchronised at login; the barrier was both unnecessary
+   * shim (in the private store's graph) may not be synced when the first read
-   * and broken for STORE NURIs). This field is accepted but silently ignored.
+   * 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). */
+/** Required fields of StoreRegistryDeps after defaults are applied. `provisionRetry`
-type ResolvedRegistryDeps = Required<Pick<StoreRegistryDeps, "getSession" | "normalizeId">>;
+ *  defaults to `{ attempts: 1 }` (no retry) when the consumer leaves it unset. */
+type ResolvedRegistryDeps = Required<
+  Pick<StoreRegistryDeps, "getSession" | "normalizeId" | "provisionRetry">
+>;
 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 },
   };
 }
 

packages/client/src/store-registry.ts

@@ -167,6 +167,56 @@ function bindingValue(row: Record<string, { value: string }>, 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<Record<string, { value: string }>>, 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<Record<string, { value: string }>>,
+  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<Map<string, AccountRecord>> {
   const map = new Map<string, AccountRecord>();
   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<string, Array<Record<string, { value: string }>>>();
     for (const row of readBindings(result)) {
       const id = bindingValue(row, "id");
       if (!id) continue;
       const key = accountKey(id);
-      const record: AccountRecord = {
+      const bucket = byKey.get(key) ?? [];
-        id,
+      bucket.push(row);
-        docPublic: bindingValue(row, "docPublic"),
+      byKey.set(key, bucket);
-        docProtected: bindingValue(row, "docProtected"),
+    }
-        docPrivate: bindingValue(row, "docPrivate"),
+    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<AccountRecord | null>
     const result = await sparqlQuery(s.sessionId, query, undefined, anchor, "resolveAccount");
     const rows = readBindings(result);
     if (rows.length === 0) return null;
-    const row = rows[0]!;
+    // DETERMINISTIC: a corrupted shim may return SEVERAL bindings for this one
-    const record: AccountRecord = {
+    // account subject (duplicate scope-doc values from past forks). Pick the
-      id: bindingValue(row, "id") || id,
+    // canonical (lexicographically-smallest) doc per scope so writer and reader
-      docPublic: bindingValue(row, "docPublic"),
+    // always resolve the SAME docPublic — the fix for the reconnection bug.
-      docProtected: bindingValue(row, "docProtected"),
+    const record = recordFromRows(rows, id);
-      docPrivate: bindingValue(row, "docPrivate"),
-    };
     accountCache.set(key, record);
     return record;
   } catch (error) {
@@ -257,6 +311,63 @@ export async function resolveAccount(id: string): Promise<AccountRecord | null>
   }
 }
 
+// --- anti-fork bounded retry ----------------------------------------------
+
+const sleep = (ms: number): Promise<void> => 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<AccountRecord | null> {
+  // 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<AccountRecord[]> {
   return [...(await loadShim()).values()];
@@ -278,9 +389,12 @@ export async function ensureAccount(id: string): Promise<AccountRecord> {
   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.
+  // ANTI-FORK: resolve via the BOUNDED retry, so a transient 0 rows (the shim not
-  const existing = await resolveAccount(id);
+  // 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([

packages/client/test/anti-fork.test.ts

@@ -1,21 +1,27 @@
 /**
- * ensureAccount-idempotent.test.ts — behavioral tests for the NO-FORK guarantee
+ * anti-fork.test.ts — behavioral tests for the reconnection fix in the
- * of ensureAccount (src/store-registry.ts).
+ * polyfill-era shim (src/store-registry.ts). Two guards, one file:
  *
- * The guarantee: ensureAccount always resolves via a SIMPLE resolveAccount read
+ *  (1) DETERMINISTIC RESOLUTION — a shim whose account subject carries DUPLICATE
- * (one targeted SPARQL query, no barrier, no retry). The private store is
+ *      scope-doc values (fork residue: several `shim:docPublic`) must resolve to
- * synchronised at login, so 0 rows is DEFINITIVE (account genuinely absent) →
+ *      the SAME canonical doc every time (lexicographically-smallest NURI), so the
- * provision exactly once; rows present → reuse (NO-FORK). Idempotent within
+ *      session that WROTE an entity and a fresh page that RESOLVES the doc never
- * and across sessions.
+ *      disagree. This is the root-cause fix for the reconnection bug.
  *
- * With the unit fake `ng` (no `doc_subscribe`), `ensureRepoOpen` is a no-op
+ *  (2) ANTI-FORK BOUNDED RETRY — a fresh page over a persistent wallet may read
- * (getSyncState → "unknown") and the single shim read is immediate —
+ *      the shim as 0 rows while the private store is still syncing. A BOUNDED retry
- * synchronous behaviour preserved, no lag to wait out.
+ *      (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)
+// Fake ng — in-memory quad store. Two variants:
-//
+//   - makeFakeNg(): NO doc_subscribe → non-reactive path (no sync lag, no retry).
-// Queries return data from the `quads` array immediately. No lag simulation:
+//   - makeLaggyFakeNg({lag}): HAS doc_subscribe (so the anti-fork retry path
-// the single shim read is already authoritative (private store is synced at login).
+//     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() {
+function makeSparqlUpdate(quads: Quad[]) {
-  const quads: Quad[] = [];
+  return mock(async (...a: unknown[]) => {
-  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[]) => {
     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;
   });
+}
 
-  const sparql_query = mock(async (...a: unknown[]) => {
+/** Build the account-SELECT bindings from the quads (grouped per subject). Each
-    const query = a[1] as string;
+ *  (subject × docPublic × docProtected × docPrivate) combination is a binding, so
-    const anchor = a[3] as string | undefined;
+ *  a subject with DUPLICATE scope docs yields a cross-product of bindings — exactly
-
+ *  what a corrupted shim returns. */
-    if (query.includes("<urn:ng-eventually:shim:id>")) {
+function accountBindings(quads: Quad[], anchor: string | undefined, onlySubject: string | null) {
-      // Account SELECT (resolveAccount / loadShim)
+  const bySubject = new Map<string, { id: string; pub: string[]; prot: string[]; priv: string[] }>();
-      accountQueryCount++;
-
-      const subjM = query.match(/GRAPH <[^>]+>\s*\{\s*<([^>]+)>\s+a\s+<urn:ng-eventually:shim:Account>/);
-      const onlySubject = subjM ? subjM[1]! : null;
-      const bySubject = new Map<string, Record<string, string>>();
   for (const q of quads) {
     if (q.g !== anchor) continue;
     if (onlySubject !== null && q.s !== onlySubject) continue;
-        const rec = bySubject.get(q.s) ?? {};
+    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.docPublic = q.o;
+    if (q.p === "urn:ng-eventually:shim:docPublic") rec.pub.push(q.o);
-        if (q.p === "urn:ng-eventually:shim:docProtected") rec.docProtected = q.o;
+    if (q.p === "urn:ng-eventually:shim:docProtected") rec.prot.push(q.o);
-        if (q.p === "urn:ng-eventually:shim:docPrivate") rec.docPrivate = q.o;
+    if (q.p === "urn:ng-eventually:shim:docPrivate") rec.priv.push(q.o);
     bySubject.set(q.s, rec);
   }
-      const bindings = [...bySubject.values()]
+  const bindings: Array<Record<string, { value: string }>> = [];
-        .filter((r) => r.id)
+  for (const rec of bySubject.values()) {
-        .map((r) => ({
+    if (!rec.id) continue;
-          id: { value: r.id! },
+    const pubs = rec.pub.length ? rec.pub : [""];
-          docPublic: { value: r.docPublic ?? "" },
+    const prots = rec.prot.length ? rec.prot : [""];
-          docProtected: { value: r.docProtected ?? "" },
+    const privs = rec.priv.length ? rec.priv : [""];
-          docPrivate: { value: r.docPrivate ?? "" },
+    for (const pub of pubs)
-        }));
+      for (const prot of prots)
-      return { results: { bindings } };
+        for (const priv of privs)
+          bindings.push({
+            id: { value: rec.id },
+            docPublic: { value: pub },
+            docProtected: { value: prot },
+            docPrivate: { value: priv },
+          });
   }
+  return bindings;
+}
 
-    // Entity-index SELECT
+/** 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("<urn:ng-eventually:shim:id>")) {
+      accountQueryCount++;
+      const subjM = query.match(/GRAPH <[^>]+>\s*\{\s*<([^>]+)>\s+a\s+<urn:ng-eventually:shim:Account>/);
+      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 } };
   });
+  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("<urn:ng-eventually:shim:id>")) {
+      accountQueryCount++;
+      if (lag > 0) { lag--; return { results: { bindings: [] } }; } // sync not landed yet
+      const subjM = query.match(/GRAPH <[^>]+>\s*\{\s*<([^>]+)>\s+a\s+<urn:ng-eventually:shim:Account>/);
+      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,
+    doc_create, sparql_update, sparql_query, doc_subscribe,
-    sparql_update,
-    sparql_query,
     _quads: quads,
     getAccountQueryCount: () => accountQueryCount,
   };
 }
 
-function inject(fakeNg: ReturnType<typeof makeFakeNg>) {
+function inject(
-  // No doc_subscribe → ensureRepoOpen is a no-op (fake-ng path).
+  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", () => {
+describe("deterministic resolution over a shim corrupted by fork residue", () => {
-  beforeEach(() => {
+  beforeEach(() => { resetRegistryCache(); resetOpenedRepos(); });
-    resetRegistryCache();
-    resetOpenedRepos();
-  });
 
-  it("(a) NO-FORK: account already in shim → reused, 0 new doc_create", async () => {
+  it("(1a) a subject with MULTIPLE docPublic values always resolves the SAME canonical (lexicographically-smallest)", async () => {
-    // Provision an account in an initial "session" (quads are written).
+    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 () => {
+  it("(2b) SYNC LAG: shim reads 0 K times then the data → RETRY reuses, no fork", async () => {
-    const fakeNg = makeFakeNg(); // empty quads → 0 rows on any account query
+    // Seed an account into an initial (non-reactive) fake, capture its NURIs.
-    inject(fakeNg);
+    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)
+    // Provisioned exactly ONE set of scope docs.
-    expect(fakeNg.doc_create).toHaveBeenCalledTimes(3);
+    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);
+    // Retry was BOUNDED: exactly `attempts` account reads, then it gave up and provisioned.
-    // Single read — no retry loop
+    expect(reactive.getAccountQueryCount()).toBe(5);
-    expect(fakeNg.getAccountQueryCount()).toBe(1);
   });
 
-  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);
-  });
 });