feat(client): union-read ReadCap gate + listMyEntityDocs + doc corrections

- read-model.ts `readUnion` now applies the emulated ReadCap gate (drops a
  subject when its doc is governsRead && !canRead for the current identity), so
  per-scope isolation holds by construction AND by filter.
- store-registry: `listMyEntityDocs(username, scope)` (current account only) vs
  the all-accounts `listEntityDocs` fallback (documented as the enumeration to
  avoid on the read path).
- docs: nextgraph-current-state / read-model — corrected to the SOURCE-VERIFIED
  reality that the JS SDK exposes NO open/sync-by-cap primitive
  (load_repo_from_read_cap is pub(crate)); in the mono-wallet all repos are
  already local (same session), so the anchorless union spans them with no open
  step. simulation.md: listEntityDocs+useShape({graphs}) is a fallback, not the
  read path.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

packages/client/src/read-model.ts

@@ -34,7 +34,7 @@
  */
 
 import { docCreate, sparqlUpdate, sparqlQuery } from "./docs";
-import { getStoreRegistryDeps } from "./polyfill";
+import { getStoreRegistryDeps, getCaps, getCurrentUser } from "./polyfill";
 import { assertNuri } from "./sparql";
 import type { Nuri } from "./types";
 
@@ -72,17 +72,26 @@ async function sessionId(): Promise<string> {
 }
 
 /**
- * Open/sync ONE doc into the session store by running a cheap anchored probe
- * query against it (`resolve_target_for_sparql(anchor)` opens that repo). Per-doc
- * and tolerant: a doc that can't be opened (not yet synced, no cap) throws HERE,
- * in isolation, and is skipped — it never aborts the listing of the others (the
- * fan-out ORM's failure mode). Returns whether the open succeeded.
+ * Touch ONE doc with a cheap anchored `ASK`, tolerant per-doc.
+ *
+ * VERIFIED (T03.k, see docs/nextgraph-current-state.md § *A repo is only queryable
+ * once OPENED/synced*): the current JS SDK exposes **no primitive that SYNCS an
+ * unknown repo**. An anchored `sparql_query` resolves via `resolve_target_for_sparql`
+ * → `self.repos.get(id).ok_or(RepoNotFound)` — it never PULLS an absent repo (and
+ * neither do `doc_subscribe` nor `orm_start_graph`; the real loader
+ * `load_repo_from_read_cap` is `pub(crate)`, unexposed). So this `ASK` cannot sync:
+ * on a repo already in `self.repos` (every doc `doc_create`d this session — which,
+ * in the mono-wallet polyfill, is ALL of them) it is a no-op that confirms presence;
+ * on a genuinely-absent repo it throws `RepoNotFound` HERE, in isolation, and the
+ * doc is skipped — never aborting the listing of the others (the ORM fan-out's
+ * failure mode). Returns whether the touch succeeded.
+ *
+ * At the real multi-store migration this becomes a real sync: opening a per-user
+ * store repo by cap is a native broker fetch (`verifier.rs:1423` `OpenRepo` TODO).
  */
 async function openDoc(sid: string, doc: Nuri): Promise<boolean> {
   try {
     const nuri = assertNuri(doc);
-    // ASK is the cheapest way to touch (hence open) the repo; the result is
-    // irrelevant — the side effect (repo opened into the union) is the point.
     await sparqlQuery(sid, "ASK { ?s ?p ?o }", undefined, nuri);
     return true;
   } catch (error) {
@@ -126,6 +135,16 @@ export async function readUnion(docs: Nuri[]): Promise<UnionSubject[]> {
     return [];
   }
 
+  // Cap gate (defence-in-depth). The union spans every OPENED graph, so a subject
+  // whose DOCUMENT is under a read policy the current user may not satisfy must be
+  // dropped — isolation holds BY CONSTRUCTION (the app only resolves docs it is
+  // entitled to) AND BY FILTER here. Generic: the lib owns the cap registry; a doc
+  // under no policy (`!governsRead`) flows through unchanged. In this polyfill each
+  // subject IRI IS its own document NURI, so the cap key is the subject.
+  const caps = getCaps();
+  const user = getCurrentUser();
+  const denied = (doc: string): boolean => caps.governsRead(doc) && !caps.canRead(doc, user);
+
   const bySubject = new Map<string, UnionSubject>();
   for (const row of rows) {
     const s = row.s?.value;
@@ -133,6 +152,7 @@ export async function readUnion(docs: Nuri[]): Promise<UnionSubject[]> {
     const o = row.o?.value;
     const g = row.g?.value ?? "";
     if (!s || !p || o === undefined) continue;
+    if (denied(s)) continue;
     let entry = bySubject.get(s);
     if (!entry) {
       entry = { subject: s, graph: g, props: {} };

packages/client/src/store-registry.ts

@@ -369,31 +369,56 @@ export async function createEntityDoc(username: string, scope: Scope): Promise<N
   return entityNuri;
 }
 
+/** Read the entity-document NURIs contained in ONE scope index document. */
+async function readScopeIndex(indexDoc: Nuri): Promise<Nuri[]> {
+  const s = await session();
+  const out: Nuri[] = [];
+  try {
+    const res = await sparqlQuery(
+      s.sessionId,
+      `SELECT ?e WHERE { GRAPH <${assertNuri(indexDoc)}> { <${INDEX_SUBJECT}> <${P.contains}> ?e } }`,
+      undefined,
+      indexDoc,
+    );
+    for (const row of readBindings(res)) {
+      const v = bindingValue(row, "e");
+      if (v) out.push(v);
+    }
+  } catch (error) {
+    console.error("[storeRegistry] readScopeIndex read failed:", error);
+  }
+  return out;
+}
+
 /**
  * Every entity document NURI of `scope`, across all accounts — the read
  * fan-out for per-entity scopes. Reads each account's scope index document and
  * unions the contained NURIs. Use as `useShape(shape, { graphs })`.
+ *
+ * NOTE (read-by-need): this ALL-ACCOUNTS fan-out contradicts the read-by-need
+ * model (docs/read-model.md) — it opens/syncs other accounts' possibly-unsynced
+ * docs, which HANGS. Prefer {@link listMyEntityDocs} (my own account's scope
+ * docs) for "my entities", and the discovery index for "all public events".
+ * Retained for callers that legitimately need every account (tests).
  */
 export async function listEntityDocs(scope: Scope): Promise<Nuri[]> {
   const accounts = await allAccounts();
-  const s = await session();
   const out: Nuri[] = [];
   for (const a of accounts) {
-    const indexDoc = indexDocOf(a, scope);
-    try {
-      const res = await sparqlQuery(
-        s.sessionId,
-        `SELECT ?e WHERE { GRAPH <${assertNuri(indexDoc)}> { <${INDEX_SUBJECT}> <${P.contains}> ?e } }`,
-        undefined,
-        indexDoc,
-      );
-      for (const row of readBindings(res)) {
-        const v = bindingValue(row, "e");
-        if (v) out.push(v);
-      }
-    } catch (error) {
-      console.error("[storeRegistry] listEntityDocs read failed:", error);
-    }
+    out.push(...(await readScopeIndex(indexDocOf(a, scope))));
   }
   return out;
 }
+
+/**
+ * The entity-document NURIs of `scope` belonging to ONE account (`username`) —
+ * the read-by-need path for "my own entities" (my profile, my participations).
+ * Bounded to a SINGLE account: it resolves only that account's scope index doc
+ * (via `ensureAccount`) and reads the contained NURIs — NO cross-account
+ * enumeration, so it never touches another account's unsynced docs. This is the
+ * helper FestipodDataContext uses instead of the all-accounts `listEntityDocs`.
+ */
+export async function listMyEntityDocs(username: string, scope: Scope): Promise<Nuri[]> {
+  const record = await ensureAccount(username);
+  return readScopeIndex(indexDocOf(record, scope));
+}