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

docs+refactor(client): fidelity pass — id identity, drop connections, no faux-login, accurate NextGraph framing

Browse Source 
Align the polyfill's surface and docs with the verified NextGraph reality and
remove application-level concepts:

- Identity is an ID, not a username: AccountRecord.id, shim predicate shim:id,
  normalizeId; accounts core becomes IdentityStore (set/clear/get) — the faux
  login/logout framing is gone (identity is set at wallet-import time).
- Relationship/connection is an application concept, not a platform primitive
  (NextGraph has no bilateral-connection primitive: grantee is unpersisted
  scaffolding, cap-send is unimplemented). Remove connections.ts; caps exposes
  only a directed grantRead(doc, granteeId) + a read-only protectedDocsOf(owner).
  Delete the now-dead isolation.ts social-visibility axis.
- Inbox docs: NextGraph has no separate curator — the recipient's own verifier
  unseals and applies each queued sealed message inline (process_inbox);
  inbox_post_link is a proposed/future API. Stop attributing the emulated
  curator to the platform.
- Read isolation reframed around the outcome: no cap -> empty union read;
  targeted read of an unheld repo -> RepoNotFound; cap introspection
  (canRead/governsRead) is emulation-only with no NextGraph API behind it.
- read-model.md corrected: the listing path is per-doc ANCHORED default-graph
  queries, never the anchorless GRAPH ?g union (that is O(wallet)); the probe
  section no longer claims the opposite.
- README recap table restructured (target | current NextGraph status | current
  emulation); INDEX_ACCOUNT documented as reservedAccount("index") in the
  sentinel namespace; de-domained generic-layer comments; softened tone.

Consumer application (Festipod) rewired separately to own the relationship
concept and feed the lib an id. Lib gates: bun test 83 pass / 0 fail, tsc clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Sylvain Duchesne
2026-07-06 14:02:16 +02:00
parent d39b12885a
commit 63ecfeeff8
31 changed files with 1059 additions and 1396 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/client/src/read-model.ts
+36 -36
View File
@@ -1,39 +1,39 @@
/**
* read-model — the LISTING primitive of the polyfill: read a BOUNDED, by-need set
* of documents, each with its OWN anchored `sparql_query`, and return the triples
* read-model — the listing primitive of the polyfill: read a bounded, by-need set
* of documents, each with its own anchored `sparql_query`, and return the triples
* grouped per subject. This is the mechanism documented in docs/read-model.md.
*
* ── WHY per-doc ANCHORED, never an anchorless union-scan ───────────────────
* An ANCHORED `sparql_query(sid, "SELECT ?s ?p ?o WHERE { ?s ?p ?o }", base, doc)`
* ── Why per-doc anchored, rather than an anchorless union-scan ─────────────
* An anchored `sparql_query(sid, "SELECT ?s ?p ?o WHERE { ?s ?p ?o }", base, doc)`
* is restricted to the anchor repo's graph: `resolve_target_for_sparql(Repo)` →
* `Some(repo_graph_name)`, which becomes the query's DEFAULT graph. A body with NO
* `GRAPH` wrapper reads only that default graph → ONLY that doc's triples, O(1) per
* doc, INDEPENDENT of how many other graphs the local store holds.
* `Some(repo_graph_name)`, which becomes the query's default graph. A body with no
* `GRAPH` wrapper reads only that default graph → only that doc's triples, O(1) per
* doc, independent of how many other graphs the local store holds.
*
* An ANCHORLESS query (`anchor` undefined → `UserSite` → `set_default_graph_as_union`)
* spans EVERY named graph currently in the session store. On a SHARED / bloated
* wallet that accumulates across runs, that is O(wallet size) → the observed ~90s
* timeouts. So the read path must NEVER union-scan all graphs: it reads exactly the
* bounded by-need set, one anchored query per doc.
* The footgun this avoids: an anchorless query (`anchor` undefined → `UserSite` →
* `set_default_graph_as_union`) spans EVERY named graph currently in the session
* store. On a shared / bloated wallet that accumulates across runs, that is
* O(wallet size) → the observed ~90s timeouts. So the read path never union-scans
* all graphs — it reads exactly the bounded by-need set, one anchored query per doc.
*
* NB (verified, docs/read-model.md § probe step 4): an explicit `GRAPH ?g { … }`
* body iterates the NAMED graphs regardless of the default graph, so an anchor does
* NOT bound such a body. The per-doc read therefore uses a DEFAULT-GRAPH body (no
* body iterates the named graphs regardless of the default graph, so an anchor does
* not bound such a body. The per-doc read therefore uses a default-graph body (no
* `GRAPH` wrapper) so the anchor's one-repo restriction actually applies.
*
* ── WHY not the reactive ORM fan-out ──────────────────────────────────────
* ── Why not the reactive ORM fan-out ──────────────────────────────────────
* `useShape({ graphs: […manyDocs] })` drives `orm_start_graph` over a fan-out of
* per-entity graphs; a freshly-created / not-yet-synced doc in that fan-out makes
* `RepoNotFound` abort the whole subscription → the readyPromise never resolves →
* the ~75s hang (docs/nextgraph-current-state.md § The ORM fan-out hang). Listing
* MUST instead be a set of one-shot anchored `sparql_query`s. There is no reactive
* union query, so reactivity is assembled by RE-QUERYING on a change signal.
* is instead a set of one-shot anchored `sparql_query`s. There is no reactive
* union query, so reactivity is assembled by re-querying on a change signal.
*
* ── GENERIC by construction ───────────────────────────────────────────────
* Zero application domain here: the consumer passes the doc NURIs to read (from
* ── Generic by construction ───────────────────────────────────────────────
* No application domain here: the consumer passes the doc NURIs to read (from
* the discovery index for public events, or its own scope docs for my-entities)
* and interprets the returned per-subject property bags. All NextGraph I/O routes
* through the T01.a `docs` primitives (the REAL injected `ng`), so this module
* through the T01.a `docs` primitives (the real injected `ng`), so this module
* imports no `@ng-org` package.
*
* At the real multi-store migration the per-doc anchored read is unchanged (native
@@ -80,18 +80,18 @@ async function sessionId(): Promise<string> {
}
/**
* Read ONE doc with an ANCHORED default-graph query, tolerant per-doc.
* Read one doc with an anchored default-graph query, tolerant per-doc.
*
* The anchor (`doc` NURI) restricts the query to that repo's graph as the DEFAULT
* The anchor (`doc` NURI) restricts the query to that repo's graph as the default
* graph (`resolve_target_for_sparql(Repo)` → `Some(repo_graph_name)`); a body with
* NO `GRAPH` wrapper reads exactly that default graph → ONLY this doc's triples.
* This is O(1) in the doc's own size and INDEPENDENT of the rest of the (possibly
* no `GRAPH` wrapper reads exactly that default graph → only this doc's triples.
* This is O(1) in the doc's own size and independent of the rest of the (possibly
* bloated / shared) session store — it never iterates other graphs.
*
* All same-session repos (every doc `doc_create`d this session — in the mono-wallet
* polyfill, ALL of them) are already in `self.repos`, so the anchored query resolves
* polyfill, all of them) are already in `self.repos`, so the anchored query resolves
* the repo directly with no separate open. A genuinely-absent repo throws
* `RepoNotFound` HERE, in isolation, and the doc is skipped — never aborting the
* `RepoNotFound` here, in isolation, and the doc is skipped — never aborting the
* others (unlike the ORM fan-out). Returns the doc's rows, or `[]` on failure.
*
* At the real multi-store migration this becomes a real sync: opening a per-user
@@ -103,7 +103,7 @@ async function readDoc(
): Promise<Array<Record<string, { value: string } | undefined>>> {
try {
const nuri = assertNuri(doc);
// Anchored to `nuri` → default graph = this repo. NO `GRAPH ?g` wrapper, so
// Anchored to `nuri` → default graph = this repo. No `GRAPH ?g` wrapper, so
// the anchor's one-repo restriction applies (an explicit `GRAPH ?g` body would
// iterate all named graphs regardless of the anchor — see docs § probe step 4).
const res = await sparqlQuery(
@@ -126,10 +126,10 @@ async function readDoc(
* Docs that fail are skipped (see {@link readDoc}); a failing doc never aborts the
* batch.
*
* NEVER an anchorless union-scan over all graphs (which is O(wallet size) and wrong
* on a shared / bloated wallet). Each doc is read with an anchored default-graph
* query, O(1) per doc, independent of wallet size — a non-empty wallet no longer
* matters. Reads run in parallel via `Promise.all`.
* Never an anchorless union-scan over all graphs (which is O(wallet size) and wrong
* on a shared / bloated wallet — the footgun this path exists to avoid). Each doc is
* read with an anchored default-graph query, O(1) per doc, independent of wallet
* size — a non-empty wallet no longer matters. Reads run in parallel via `Promise.all`.
*/
export async function readUnion(docs: Nuri[]): Promise<UnionSubject[]> {
const sid = await sessionId();
@@ -142,17 +142,17 @@ export async function readUnion(docs: Nuri[]): Promise<UnionSubject[]> {
);
// Cap gate (defence-in-depth). A doc whose read policy the current user may not
// satisfy is 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 doc NURI.
// satisfy is dropped. Isolation holds both 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 doc NURI.
const caps = getCaps();
const user = getCurrentUser();
const bySubject = new Map<string, UnionSubject>();
for (const { doc, rows } of perDoc) {
if (caps.governsRead(doc) && !caps.canRead(doc, user)) continue;
// Anchored to `doc`, so every row belongs to `doc`; the subject IS the doc NURI
// Anchored to `doc`, so every row belongs to `doc`; the subject is the doc NURI
// (writeEntity invariant). Pin subject/graph to the doc NURI (the anchor), which
// is stable regardless of the repo_graph_name overlay suffix the store carries.
for (const row of rows) {