Reconnexion/ng-eventually
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(client): résolution de compte barrière-autoritative — fin du fork à la reconnexion

Browse Source 
Bug: à la reconnexion, resolveAccount lisait le shim depuis le store-root
(did🆖${privateStoreId}), NON abonnable → pas de barrière first-State → un "0 rows"
à froid est ambigu → le retry (resolveAccountReliably/provisionRetry) échoue → nouveau
compte provisionné → FORK → données du compte invisibles.

Cause NextGraph (vérifiée nextgraph-rs): "trouvable-sans-lookup" (store-root) et
"abonnable" (did:ng:o:<RepoID aléatoire>) sont DISJOINTS — pas de doc à la fois
devinable et attendable → une résolution shim purement barrière est impossible.

Fix (indirection pointeur → doc-shim abonnable):
- Les AccountRecord migrent dans un doc-shim doc_create'd (did:ng:o:..., a une barrière).
- Un pointeur écrit-une-fois dans le store-root (<shim:root> <shim:shimDoc> <docShim>)
  le nomme. resolveShimDoc lit le pointeur → ensureRepoOpen(docShim) [barrière] → lecture
  de compte AUTORITATIVE (cold 0 = absent pour de vrai). Retry de compte SUPPRIMÉ.
- Micro-garde résiduel (pointerGuard, ex-provisionRetry) sur le SEUL triple pointeur
  écrit-une-fois; ne peut jamais forker un compte; fork de pointeur réconcilié au
  doc-shim canonique (lexicographiquement-min), sans perte.
- Migration: migrateLegacyRecords copie (pas déplace) les comptes de l'ancien store-root
  vers le doc-shim avant toute conclusion "absent"; idempotent; wallet neuf → no-op.

Tests: unit 128/128, e2e réel 42/42 (CONTRACT 2 = non-fork du compte à la reconnexion),
red-before/green-after prouvé. Docs: nextgraph-current-state (antagonisme + indirection),
simulation, migration-guide.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Sylvain Duchesne
2026-07-13 17:46:16 +02:00
parent 5cdc6ce77f
commit 5e91771da6
17 changed files with 744 additions and 351 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/client/src/polyfill.ts
+17 -16
View File
@@ -25,17 +25,18 @@ export interface StoreRegistryDeps {
/** Normalize an identity id for shim keying. Default: trim (identity-ish). */
normalizeId?: (id: string) => string;
/**
* 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.
* POINTER micro-guard budget. The account records now live in a subscribable
* doc-shim (`did:ng:o:...`) reached through a well-known write-once POINTER triple
* in the store-root graph. The doc-shim read is barrier-AUTHORITATIVE, so accounts
* need NO retry (this replaces the deleted account-level `provisionRetry`). The
* ONLY residual sync-lag window is the store-root pointer read itself — one
* write-once triple. This bounded guard re-reads JUST that pointer a few times if a
* fresh cold read misses it; it can never provision or fork an account (worst case:
* a couple extra reads before an existing pointer is seen). Enable it where the REAL
* broker is used (app + e2e). Left UNSET (the default) → `attempts: 1` = single
* read, keeping the synchronous unit fakes fast and unchanged.
*/
provisionRetry?: { attempts?: number; baseMs?: number; maxStepMs?: number };
pointerGuard?: { attempts?: number; baseMs?: number; maxStepMs?: number };
}
export interface EventuallyConfig {
@@ -62,10 +63,10 @@ export interface EventuallyConfig {
let cfg: EventuallyConfig | null = null;
let currentUser: PrincipalId | null = null;
/** Required fields of StoreRegistryDeps after defaults are applied. `provisionRetry`
* defaults to `{ attempts: 1 }` (no retry) when the consumer leaves it unset. */
/** Required fields of StoreRegistryDeps after defaults are applied. `pointerGuard`
* defaults to `{ attempts: 1 }` (single read) when the consumer leaves it unset. */
type ResolvedRegistryDeps = Required<
Pick<StoreRegistryDeps, "getSession" | "normalizeId" | "provisionRetry">
Pick<StoreRegistryDeps, "getSession" | "normalizeId" | "pointerGuard">
>;
let registryDeps: ResolvedRegistryDeps | null = null;
/** The emulated ReadCap/WriteCap registry. Empty until the app declares caps;
@@ -101,9 +102,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 },
// Default: single read (no re-read). Only the real-broker consumers (app + e2e)
// opt into the bounded pointer micro-guard; unit fakes stay synchronous.
pointerGuard: deps.pointerGuard ?? { attempts: 1 },
};
}
packages/client/src/store-registry.ts
+375 -171
View File
@@ -9,10 +9,38 @@
* physical NextGraph store. Isolation is enforced by the app layer + the
* emulated cap registry, not by crypto.
*
* The mapping (account → its 3 document NURIs) is the **sharedWalletShim**,
* persisted as RDF in the shared wallet's private store (the anchor, always
* known from the session). That makes login cross-device: another device
* opening the same wallet reads the same shim and finds the same accounts.
* The mapping (account → its 3 document NURIs) is the **sharedWalletShim**. It
* is persisted as RDF, but NOT in the store-root graph anymore — see the
* indirection below. That makes login cross-device: another device opening the
* same wallet reads the same shim and finds the same accounts.
*
* ── The indirection: pointer (store-root) → doc-shim (subscribable) ─────────
* On the real NextGraph platform "findable-without-lookup" and "subscribable"
* are DISJOINT (verified at the source, see docs/nextgraph-current-state.md
* § *Findable vs subscribable*):
* - the ONLY NURI a fresh session can name WITHOUT a lookup is the store-root
* `did:ng:${privateStoreId}` — but a store-root has NO first-`State` sync
* BARRIER, so a cold "0 rows" on it is AMBIGUOUS (could be sync-lag, could
* be truly empty);
* - the ONLY thing that DOES have a first-`State` barrier is a `did:ng:o:<RepoID>`
* doc from `doc_create` — but its RepoID is RANDOM, so a fresh session
* cannot GUESS it; it must be looked up.
* So a purely-barrier shim resolution is impossible: you cannot have a doc that
* is both guessable and authoritative on a cold read. The indirection bridges
* this: a well-known, write-ONCE **pointer** triple in the store-root names a
* **doc-shim** (`did:ng:o:...`) that holds all account records and IS
* subscribable. Resolution reads the pointer (a single oldest write-once triple,
* near-always synced), then opens the doc-shim through its `ensureRepoOpen`
* BARRIER and reads the account AUTHORITATIVELY (0 = genuinely absent).
*
* A pointer FORK (two devices writing the pointer before either synced) is
* BENIGN: the pointer is reconciled to a canonical doc-shim (lexicographically-
* smallest NURI) and destroys no account data — worst case a doc-shim not chosen
* is migrated forward on next resolve. This is why the OLD account-level retry
* (`resolveAccountReliably` / `provisionRetry`) is GONE: the account read is now
* barrier-authoritative, so it never needs to be retried to distinguish sync-lag
* from absence. A micro-guard remains ONLY on the pointer read (one write-once
* triple) — see resolvePointer.
*
* ── Generic by construction ──────────────────────────────────────────────
* This module knows only the three native scopes; it knows no application
@@ -62,6 +90,18 @@ const P = {
// documents (one per entity) that live "in" that scope.
const INDEX_SUBJECT = `${SHIM}:index`;
// --- pointer (store-root → doc-shim indirection) --------------------------
//
// The pointer is a SINGLE well-known triple written ONCE into the store-root
// graph on the very first login, then IMMUTABLE. Its object is the NURI of the
// doc-shim (a `did:ng:o:...` repo) where all AccountRecords actually live. The
// store-root is NOT subscribable (no first-`State` barrier), but the pointer is
// the OLDEST triple in that graph and is write-once, so it is near-always synced
// on a cold read — and even a transient miss is bounded by a small guard
// (resolvePointer), NOT by an account-level retry.
const POINTER_SUBJECT = `${SHIM}:root`;
const POINTER_PRED = `${SHIM}:shimDoc`;
function accountSubject(id: string): string {
// The id is UNTRUSTED and lands in an IRI position. Percent-encode it
// (escapeIri) so no `>` / `"` / whitespace / control char can break out of
@@ -110,7 +150,7 @@ function accountKey(id: string): string {
/** Minimal session shape the registry needs — provided by the consumer. */
export interface RegistrySession {
sessionId: string;
/** The shared wallet's private store id — the shim anchor. */
/** The shared wallet's private store id — the pointer anchor. */
privateStoreId: string;
/** The shared wallet's protected store id (native store). Optional: only the
* scope resolvers need it; the shim only needs the private anchor. */
@@ -127,8 +167,11 @@ async function session(): Promise<RegistrySession> {
return getStoreRegistryDeps().getSession();
}
/** The shim lives in the shared wallet's private store (always-known anchor). */
async function anchorNuri(): Promise<Nuri> {
/** The pointer lives in the shared wallet's private STORE-ROOT graph (the only
* always-known-without-lookup anchor). NOT subscribable — hence the pointer is
* a write-once triple, and the actual account records live in the doc-shim it
* names (see rootNuri vs the doc-shim). */
async function rootNuri(): Promise<Nuri> {
const s = await session();
return `did:ng:${s.privateStoreId}`;
}
@@ -144,10 +187,23 @@ let cache: Map<string, AccountRecord> | null = null;
// targeted resolve never forces a full shim scan. Both are cleared together.
const accountCache = new Map<string, AccountRecord>();
// The resolved doc-shim NURI for the current session (cached: the pointer read +
// barrier open happen once, then every account read reuses this doc). Cleared on
// resetRegistryCache / wallet switch.
let shimDocNuri: Nuri | null = null;
// De-dupe concurrent pointer-resolutions so a fresh page firing many parallel
// ensureAccount/resolveAccount calls opens the doc-shim exactly once.
let shimDocInFlight: Promise<Nuri> | null = null;
/** Reset cache (e.g. after switching the shared wallet). Mostly for tests. */
export function resetRegistryCache(): void {
cache = null;
accountCache.clear();
shimDocNuri = null;
shimDocInFlight = null;
// The per-session migration guard is tied to the resolved doc-shim, which is
// dropped here — so a switched wallet (or a test) re-runs the legacy scan.
migratedInto.clear();
}
// --- SPARQL result helpers ------------------------------------------------
@@ -171,7 +227,7 @@ function bindingValue(row: Record<string, { value: string }>, key: string): stri
* 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) ───────────
* ── Why this is load-bearing (residual fork residue) ───────────────────────
* 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
@@ -187,6 +243,12 @@ function bindingValue(row: Record<string, { value: string }>, key: string): stri
* 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.)
*
* With the barrier-authoritative doc-shim read, account FORKS no longer occur (a
* fresh page reads the doc-shim through its first-`State` barrier, so a cold 0 is
* definitive and never triggers a fork-provision). `canonicalDoc` is RETAINED to
* stay robust against the residue of PAST forks already persisted in a wallet, and
* to reconcile a benign pointer fork the same content-addressed way.
*/
function canonicalDoc(rows: Array<Record<string, { value: string }>>, key: string): Nuri {
let chosen = "";
@@ -217,16 +279,196 @@ function recordFromRows(
};
}
// --- shim load / account bootstrap ----------------------------------------
// --- pointer resolution + doc-shim bootstrap ------------------------------
/** Load all accounts from the shim into the cache. */
export async function loadShim(): Promise<Map<string, AccountRecord>> {
if (cache) return cache;
const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
/**
* Read the pointer(s) from the store-root graph → the canonical doc-shim NURI, or
* `""` if no pointer exists yet.
*
* The store-root is NOT subscribable, so this read has no first-`State` barrier:
* a cold 0 is ambiguous. But the pointer is ONE write-once triple (the OLDEST in
* that graph), so it is near-always synced. The ONLY residual guard is a small
* bounded re-read here (NOT an account retry): a handful of quick re-reads of that
* single triple. It is bounded, benign, and — crucially — it can never re-provision
* an account or fork data; the worst it can do is take a couple extra reads to see a
* pointer that is still landing. The account records themselves are read
* authoritatively through the doc-shim barrier, never through this guard.
*
* If MULTIPLE pointers exist (a pointer fork: two devices each wrote a pointer to
* their own freshly-created doc-shim before either synced), reconcile to the
* canonical (lexicographically-smallest) doc-shim NURI — content-addressed and
* stable, so every device converges on the SAME doc-shim. A pointer fork is benign:
* no account data is lost (migration folds any non-canonical doc-shim forward).
*/
async function resolvePointer(): Promise<Nuri> {
const s = await session();
const anchor = await anchorNuri();
const root = await rootNuri();
// COLD-START heal: open the store-root repo before the anchored read, so a fresh
// wallet whose store-root isn't yet in `self.repos` resolves instead of throwing
// `RepoNotFound`. Idempotent; a no-op with the unit fake ng. The store-root has no
// barrier, so this open cannot make the read authoritative — the guard below does.
await ensureRepoOpen(root);
const query = `
SELECT ?shimDoc WHERE {
GRAPH <${assertNuri(root)}> {
<${POINTER_SUBJECT}> <${POINTER_PRED}> ?shimDoc .
}
}`;
// Micro-guard (POINTER only): a small bounded re-read to bridge the store-root
// sync-lag window on the ONE write-once pointer triple. Bounded, and it can only
// ever DELAY seeing an existing pointer — never provision, never fork. Uses the
// injected pointerGuard budget (defaults to a single read when unset, so unit
// fakes stay synchronous). NB this is NOT the deleted account-level provisionRetry.
const budget = getStoreRegistryDeps().pointerGuard;
const attempts = Math.max(1, budget.attempts ?? 1);
const baseMs = budget.baseMs ?? 150;
const maxStepMs = budget.maxStepMs ?? 2000;
let step = baseMs;
for (let i = 0; i < attempts; i++) {
try {
const result = await sparqlQuery(s.sessionId, query, undefined, root, "resolvePointer");
const doc = canonicalDoc(readBindings(result), "shimDoc");
if (doc) return doc;
} catch (error) {
console.error("[storeRegistry] resolvePointer read failed:", error);
}
if (i < attempts - 1) {
await sleep(step);
step = Math.min(step * 2, maxStepMs);
}
}
return "";
}
/** Write the pointer (store-root → doc-shim), once, at first login. Idempotent in
* practice (only called when no pointer was found); a concurrent double-write is
* reconciled by canonicalDoc on read. */
async function writePointer(doc: Nuri): Promise<void> {
const s = await session();
const root = await rootNuri();
await ensureRepoOpen(root);
const update = `
INSERT DATA {
GRAPH <${assertNuri(root)}> {
<${POINTER_SUBJECT}> <${POINTER_PRED}> <${assertNuri(doc)}> .
}
}`;
try {
await sparqlUpdate(s.sessionId, update, root, "writePointer");
} catch (error) {
console.error("[storeRegistry] writePointer failed:", error);
}
}
/** Create one graph document in the shared wallet's private store (→ a NURI). */
async function createDoc(): Promise<Nuri> {
const s = await session();
// crdt="Graph" (RDF/SPARQL/ORM), class="data:graph", destination="store",
// store_repo=undefined → shared wallet's private store.
return docCreate(s.sessionId, "Graph", "data:graph", "store", undefined);
}
/**
* Resolve (or on first login, create) the doc-shim NURI for this session — the
* `did:ng:o:...` repo that holds every AccountRecord and IS subscribable.
*
* Steps (cached; runs at most once per session, concurrent callers share one):
* 1. Read the pointer from the store-root (resolvePointer). If present → that is
* the doc-shim; open it through its first-`State` BARRIER so subsequent account
* reads are AUTHORITATIVE, then MIGRATE any legacy store-root records into it.
* 2. No pointer → FIRST login (or a wallet from before the indirection):
* a. create a fresh doc-shim (`doc_create`), which bootstraps the repo into the
* session (`self.repos`) — so it is already open/synced in-session;
* b. publish the pointer (store-root → the new doc-shim), once;
* c. open it (barrier — trivially satisfied for a just-created in-session repo)
* and MIGRATE any legacy AccountRecords found in the store-root graph into it
* (see migrateLegacyRecords) — this is what guarantees NO existing account is
* lost when a pre-indirection wallet is opened for the first time.
* The BARRIER matters on RECONNECT (step 1, reading an EXISTING remote doc-shim);
* on first-login creation it is a no-op, so the pointer is published first.
*/
async function resolveShimDoc(): Promise<Nuri> {
if (shimDocNuri) return shimDocNuri;
if (shimDocInFlight) return shimDocInFlight;
const p = (async (): Promise<Nuri> => {
const existing = await resolvePointer();
if (existing) {
// Open the doc-shim through its first-`State` barrier BEFORE any account read,
// so a cold 0 on the doc-shim is authoritative (genuinely absent), not sync-lag.
await ensureRepoOpen(existing);
// A pointer that predates a migration still points at a doc-shim, but the LEGACY
// store-root records (from before the indirection) may not have been folded in.
// Migrate best-effort (idempotent) so no legacy account is ever stranded.
await migrateLegacyRecords(existing);
shimDocNuri = existing;
return existing;
}
// FIRST login (no pointer): create the doc-shim (bootstrapped in-session), publish
// the pointer, then open (no-op barrier for a just-created repo) + migrate legacy.
const doc = await createDoc();
await writePointer(doc);
await ensureRepoOpen(doc);
await migrateLegacyRecords(doc);
shimDocNuri = doc;
return doc;
})();
shimDocInFlight = p;
try {
return await p;
} finally {
shimDocInFlight = null;
}
}
// --- migration (legacy store-root records → the doc-shim) ------------------
// Guard so the (best-effort, O(all-accounts)) legacy scan runs at most once per
// session per target doc-shim. Cleared with the rest via resetRegistryCache.
const migratedInto = new Set<Nuri>();
/**
* MIGRATION — fold any AccountRecords that live at the OLD location (the store-root
* graph, where the pre-indirection shim wrote them) into the new doc-shim.
*
* ── Why this exists (do NOT lose an existing account) ──────────────────────
* Before the indirection, `ensureAccount` wrote `<subj> a Account ; id ; docPublic ;
* docProtected ; docPrivate` directly into the store-root graph. A wallet created
* under that scheme has its accounts there, not in a doc-shim. When such a wallet is
* first opened under the new scheme, resolveShimDoc creates/opens the doc-shim; this
* function reads the store-root graph best-effort and RE-INSERTS every legacy record
* into the doc-shim, so barrier-authoritative resolveAccount finds it — instead of
* seeing 0 in the (fresh) doc-shim and provisioning a NEW forked account.
*
* ── Behaviour (precise) ────────────────────────────────────────────────────
* - Best-effort: a store-root read failure (RepoNotFound on a truly fresh wallet)
* is swallowed — there is simply nothing to migrate.
* - Copy, don't move: legacy triples are LEFT in the store-root (never deleted), so
* the migration is safe to re-run and an aborted migration never loses data. The
* doc-shim becomes the authoritative read location; the store-root copy is inert.
* - Idempotent: re-inserting the same `<subj> ... docPublic <X>` triples is a no-op
* (RDF set semantics); and `migratedInto` skips the scan after the first run per
* session. Re-running after new legacy writes (there should be none post-migration)
* would simply re-copy them.
* - Runs once per session before the first authoritative account read, so a legacy
* account resolves on the very first resolveAccount after reconnect.
*/
async function migrateLegacyRecords(doc: Nuri): Promise<void> {
if (migratedInto.has(doc)) return;
migratedInto.add(doc);
const s = await session();
const root = await rootNuri();
// Read every legacy account record from the OLD store-root location.
const query = `
SELECT ?id ?docPublic ?docProtected ?docPrivate WHERE {
GRAPH <${assertNuri(anchor)}> {
GRAPH <${assertNuri(root)}> {
?acc a <${P.type}> ;
<${P.id}> ?id ;
<${P.docPublic}> ?docPublic ;
@@ -234,13 +476,59 @@ export async function loadShim(): Promise<Map<string, AccountRecord>> {
<${P.docPrivate}> ?docPrivate .
}
}`;
const map = new Map<string, AccountRecord>();
// COLD-START heal: open the anchor (private-store-root) repo before the shim scan,
// so an anchored read on a fresh wallet whose anchor repo isn't yet in `self.repos`
// resolves instead of throwing `RepoNotFound`. Idempotent; see resolveAccount.
await ensureRepoOpen(anchor);
let rows: Array<Record<string, { value: string }>> = [];
try {
const result = await sparqlQuery(s.sessionId, query, undefined, anchor, "loadShim");
await ensureRepoOpen(root);
const result = await sparqlQuery(s.sessionId, query, undefined, root, "migrateLegacyRead");
rows = readBindings(result);
} catch (error) {
// No legacy repo / nothing to read → nothing to migrate. Not an error.
console.error("[storeRegistry] migrateLegacyRecords read (best-effort) failed:", error);
return;
}
if (rows.length === 0) return;
// Group by account subject, pick the canonical doc per scope (fold any legacy fork
// residue the SAME content-addressed way as resolveAccount), and re-insert into the
// doc-shim. Grouping needs the subject; the SELECT above doesn't bind it, so we key
// on the account id literal (stable per account) instead.
const byId = new Map<string, Array<Record<string, { value: string }>>>();
for (const row of rows) {
const id = bindingValue(row, "id");
if (!id) continue;
const bucket = byId.get(id) ?? [];
bucket.push(row);
byId.set(id, bucket);
}
await ensureRepoOpen(doc);
for (const [id, group] of byId) {
const record = recordFromRows(group, id);
if (!record.docPublic && !record.docProtected && !record.docPrivate) continue;
await writeRecord(doc, record);
}
}
// --- shim load / account bootstrap ----------------------------------------
/** Load all accounts from the shim (the doc-shim) into the cache. */
export async function loadShim(): Promise<Map<string, AccountRecord>> {
if (cache) return cache;
const s = await session();
const doc = await resolveShimDoc();
const query = `
SELECT ?id ?docPublic ?docProtected ?docPrivate WHERE {
?acc a <${P.type}> ;
<${P.id}> ?id ;
<${P.docPublic}> ?docPublic ;
<${P.docProtected}> ?docProtected ;
<${P.docPrivate}> ?docPrivate .
}`;
const map = new Map<string, AccountRecord>();
// The doc-shim is opened (first-`State` barrier) by resolveShimDoc, so this read is
// authoritative.
await ensureRepoOpen(doc);
try {
const result = await sparqlQuery(s.sessionId, query, undefined, doc, "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 +
@@ -271,9 +559,17 @@ export async function loadShim(): Promise<Map<string, AccountRecord>> {
/**
* Resolve ONE account by its shim key with a BOUNDED query — O(1), independent
* of the number of accounts in the shim. This is the HOT-PATH lookup: it hits
* the account record at its known subject (`accountSubject(id)`) directly,
* instead of scanning EVERY account like {@link loadShim}. Returns the account's
* record or `null` if it does not exist yet.
* the account record at its known subject (`accountSubject(id)`) directly in the
* doc-shim, instead of scanning EVERY account like {@link loadShim}. Returns the
* account's record or `null` if it does not exist yet.
*
* ── Barrier-AUTHORITATIVE (the reconnection fix) ────────────────────────────
* The read targets the DOC-SHIM (`did:ng:o:...`), which resolveShimDoc opened
* through its first-`State` barrier. So a cold 0 rows here is DEFINITIVE ("account
* genuinely absent"), not ambiguous sync-lag — no account-level retry is needed or
* used. This is what replaced the old `resolveAccountReliably` / `provisionRetry`
* loop: the store-root ambiguity that forced the retry is gone once the read moves
* behind the doc-shim barrier.
*
* Cached per account (in `accountCache`); a hit skips the query entirely, so
* repeated resolves of the same account are free. `resetRegistryCache` clears it.
@@ -284,43 +580,27 @@ export async function resolveAccount(id: string): Promise<AccountRecord | null>
if (cached) return cached;
const s = await session();
const anchor = await anchorNuri();
// COLD-START heal (polyfill-era): the shim lives in the private-store-root graph
// (the anchor). An anchored `sparql_query` on a repo absent from the verifier's
// `self.repos` throws `RepoNotFound` — a HARD error here, unlike per-entity docs
// which silently read 0 (the private/store target resolves through
// `resolve_target_for_sparql`, which requires the repo loaded). Open the anchor
// ONCE before reading, idempotently — the SAME open-before-read guard
// `readScopeIndex` applies to its index doc. NB (see docs/nextgraph-current-state):
// `ensureRepoOpen` (→ `doc_subscribe`) can only OPEN/subscribe a repo the session
// ALREADY holds; it cannot pull a genuinely-absent repo (no JS primitive does). On
// the real broker the private-store repo is bootstrapped into `self.repos` at
// connect, so this is a defensive same-session open — it makes the anchor read/write
// robust to a not-yet-subscribed anchor without ever being able to hide a truly
// unbootstrapped store. No-op with the unit fake ng and when the repo is already
// open. See open-repo.ts.
await ensureRepoOpen(anchor);
// `subj` is already IRI-safe (accountSubject → escapeIri); `anchor` is a
// trusted-shaped NURI → assertNuri. The query is bounded to this one subject.
const doc = await resolveShimDoc();
// `subj` is already IRI-safe (accountSubject → escapeIri). The read is anchored to
// the doc-shim's default graph (opened through its barrier by resolveShimDoc), so
// it is authoritative. The query is bounded to this one subject.
const subj = accountSubject(id);
const query = `
SELECT ?id ?docPublic ?docProtected ?docPrivate WHERE {
GRAPH <${assertNuri(anchor)}> {
<${subj}> a <${P.type}> ;
<${P.id}> ?id ;
<${P.docPublic}> ?docPublic ;
<${P.docProtected}> ?docProtected ;
<${P.docPrivate}> ?docPrivate .
}
<${subj}> a <${P.type}> ;
<${P.id}> ?id ;
<${P.docPublic}> ?docPublic ;
<${P.docProtected}> ?docProtected ;
<${P.docPrivate}> ?docPrivate .
}`;
try {
const result = await sparqlQuery(s.sessionId, query, undefined, anchor, "resolveAccount");
const result = await sparqlQuery(s.sessionId, query, undefined, doc, "resolveAccount");
const rows = readBindings(result);
if (rows.length === 0) return null;
// 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.
// always resolve the SAME docPublic (robustness against PAST fork residue).
const record = recordFromRows(rows, id);
accountCache.set(key, record);
return record;
@@ -330,99 +610,51 @@ 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()];
}
/** Create one graph document in the shared wallet's private store (→ a NURI). */
async function createDoc(): Promise<Nuri> {
/** Persist one AccountRecord into the doc-shim (anchored default-graph write, the
* canonical always-safe shape — same convention as createEntityDoc). */
async function writeRecord(doc: Nuri, record: AccountRecord): Promise<void> {
const s = await session();
// crdt="Graph" (RDF/SPARQL/ORM), class="data:graph", destination="store",
// store_repo=undefined → shared wallet's private store.
return docCreate(s.sessionId, "Graph", "data:graph", "store", undefined);
const subj = `${SHIM}:account:${escapeIri(accountKey(record.id))}`;
// `subj` is IRI-safe (escapeIri). `id` is UNTRUSTED text in a LITERAL position →
// escapeLiteral. The doc NURIs come from `ng` but are stored as literals here, so
// they are escaped as literals too (defence in depth). NO explicit `GRAPH <…>`
// wrapper: write the anchored DEFAULT graph (the `doc` anchor scopes it) — the
// canonical, always-safe shape the anchored default-graph read queries match.
const update = `
INSERT DATA {
<${subj}> a <${P.type}> ;
<${P.id}> "${escapeLiteral(record.id)}" ;
<${P.docPublic}> "${escapeLiteral(record.docPublic)}" ;
<${P.docProtected}> "${escapeLiteral(record.docProtected)}" ;
<${P.docPrivate}> "${escapeLiteral(record.docPrivate)}" .
}`;
try {
await sparqlUpdate(s.sessionId, update, doc, "writeRecord");
} catch (error) {
console.error("[storeRegistry] writeRecord persist failed:", error);
}
}
/**
* In-flight `ensureAccount` promises, keyed by account key — so CONCURRENT
* `ensureAccount(id)` calls for the SAME account share ONE resolve-or-provision.
*
* ── Why this is load-bearing (the reconnection FORK root cause) ─────────────
* ── Why this is load-bearing (concurrent-provision de-dup) ──────────────────
* On a fresh page over the persistent wallet, SEVERAL independent callers hit
* `ensureAccount(A)` near-simultaneously: `watchShape('public')` and
* `watchShape('protected')` each resolve their doc set (`listMyEntityDocs` →
* `ensureAccount`) and subscribe their container (`scopeIndexDoc` →
* `ensureAccount`), plus the app's owned-events effect. Each runs BEFORE the shim
* has synced, so each `resolveAccountReliably` reads 0 rows and, independently,
* PROVISIONS a brand-new set of scope docs — an account FORK PER caller. Measured:
* a single new account accrued EIGHT distinct `docPublic`/`docProtected` values in
* one session. `canonicalDoc` then makes a fresh reader pick the lexicographic-min
* doc, which differs from the (cached, freshly-created) doc the WRITER wrote into →
* the reader lists an empty scope index → the home/participation reads come back
* empty (the reconnection bug's last layer).
*
* De-duping concurrent provisions collapses those N racing provisions into ONE:
* the first caller resolves-or-provisions; every concurrent caller awaits the SAME
* promise and gets the SAME record, so no duplicate docs are ever minted and writer
* and reader converge on one canonical scope doc. Not polling: a bounded in-memory
* promise map (mirrors open-repo.ts `inFlight`), cleared the instant it settles.
* `ensureAccount(A)` near-simultaneously (watchShape public/protected, the container
* subscriptions, the app's owned-events effect). With the barrier-authoritative
* resolveAccount a fresh page NO LONGER mistakes sync-lag for absence — but if the
* account is GENUINELY new, N concurrent callers would still each see 0 and each
* provision a set of scope docs (an in-session fork). De-duping concurrent provisions
* collapses those N into ONE: the first caller resolves-or-provisions; every
* concurrent caller awaits the SAME promise and gets the SAME record. Not polling: a
* bounded in-memory promise map (mirrors open-repo.ts `inFlight`), cleared the instant
* it settles.
*/
const ensureInFlight = new Map<string, Promise<AccountRecord>>();
@@ -446,49 +678,22 @@ export async function ensureAccount(id: string): Promise<AccountRecord> {
// 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.
//
// 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);
// Barrier-AUTHORITATIVE: resolveAccount reads the doc-shim behind its first-`State`
// barrier (opened by resolveShimDoc), so a 0 here means the account is GENUINELY
// absent — not sync-lag. No account-level retry: the store-root ambiguity that
// forced the old provisionRetry loop is gone once the read moves behind the barrier.
const existing = await resolveAccount(id);
if (existing) return existing;
const doc = await resolveShimDoc();
const [docPublic, docProtected, docPrivate] = await Promise.all([
createDoc(),
createDoc(),
createDoc(),
]);
const record: AccountRecord = { id, docPublic, docProtected, docPrivate };
const s = await session();
const anchor = await anchorNuri();
// COLD-START heal: open the anchor (private-store-root) repo before PROVISIONING
// into it. The provision `sparqlUpdate` targets the private-store graph, which
// resolves through the same repo-loaded requirement — an unopened anchor repo on
// a fresh wallet would throw `RepoNotFound` and the account would never persist.
// Idempotent; a no-op once the repo is open (resolveAccountReliably already
// opened it on the read above in the common path). See open-repo.ts.
await ensureRepoOpen(anchor);
const subj = accountSubject(id);
// `subj` is already IRI-safe (accountSubject → escapeIri). `anchor` is a
// trusted-shaped NURI → assertNuri. `id` is UNTRUSTED text in a LITERAL
// position → escapeLiteral. The doc NURIs come from `ng` but are stored as
// literals here, so they are escaped as literals too (defence in depth).
const update = `
INSERT DATA {
GRAPH <${assertNuri(anchor)}> {
<${subj}> a <${P.type}> ;
<${P.id}> "${escapeLiteral(id)}" ;
<${P.docPublic}> "${escapeLiteral(docPublic)}" ;
<${P.docProtected}> "${escapeLiteral(docProtected)}" ;
<${P.docPrivate}> "${escapeLiteral(docPrivate)}" .
}
}`;
try {
await sparqlUpdate(s.sessionId, update, anchor, "ensureAccount");
} catch (error) {
console.error("[storeRegistry] ensureAccount persist failed:", error);
}
// Persist the record INTO the doc-shim (not the store-root anymore).
await writeRecord(doc, record);
// Feed the per-account cache, and the full-shim cache if it is already loaded
// (so allAccounts / the fan-out see the freshly-created account too).
accountCache.set(key, record);
@@ -582,12 +787,11 @@ const INBOX_ANCHOR_ACCOUNT = reservedAccount("inbox");
* This is a DEDICATED inbox DOCUMENT (a reserved account's public scope document —
* a real repo NURI from `docCreate`, stable across clients via the shim), NOT the
* shared wallet's private-store root. Reason (perf + hygiene): the shim (the
* account→document trust root) lives in the private-store graph and is scanned on
* every `loadShim`; routing every inbox deposit into that SAME graph bloats it
* without bound (thousands of deposit triples across sessions), turning `loadShim`
* into a multi-second full-graph scan. A separate inbox document keeps the shim
* graph small and the deposits isolated. At migration this becomes the host's
* native per-document inbox and the resolution moves here.
* account→document trust root) is scanned on every `loadShim`; routing every inbox
* deposit into that SAME graph bloats it without bound (thousands of deposit triples
* across sessions). A separate inbox document keeps the shim graph small and the
* deposits isolated. At migration this becomes the host's native per-document inbox
* and the resolution moves here.
*/
export async function resolveInboxAnchor(): Promise<Nuri> {
const record = await ensureAccount(INBOX_ANCHOR_ACCOUNT);