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

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
+20 -20
View File
@@ -1,15 +1,15 @@
# Fallback — forking NextGraph to expose the inbox (path NOT taken)
# Fallback — forking NextGraph to expose the inbox (path not taken)
**Status:** NOT taken — short-circuited by this lib's **emulated inbox**
**Status:** not taken — short-circuited by this lib's emulated inbox
(`inbox.ts`, see [`simulation.md`](./simulation.md)). Kept as the fallback plan if
a **native** broker inbox ever becomes necessary — chiefly for the **crypto
anonymity** the emulation does not provide (native `from = None` sealed deposit).
a native broker inbox ever becomes necessary — chiefly for the crypto
anonymity the emulation does not provide (native `from = None` sealed deposit).
Current NextGraph does not expose the inbox to the JS SDK: the verifier has no
`InboxPost` arm and no wasm helper seals a deposit (see
[`nextgraph-current-state.md`](./nextgraph-current-state.md) § Inbox). Two ways to
get a real inbox: **emulate it** (what this lib does) or **fork the engine** (this
document). The emulation won; this is the archived alternative.
get a real inbox: emulate it (what this lib does) or fork the engine (this
document). The emulation was chosen; this is the archived alternative.
## Strategic posture
@@ -33,13 +33,13 @@ a full stack for a feature the upstream will likely ship differently.
session_id, to_inbox_nuri, to_profile_nuri, link, anonymous)`, modeled on
`social_query_start`.
4. **`engine/verifier/src/inbox_processor.rs`** (`process_inbox`) — a receive arm
that **materializes** the message into a document in the owner's store (model on
the `ContactDetails` handler). The app then reads via ORM/SPARQL — no new
inbox-read API.
where the owner's own verifier unseals the queued message and applies it inline
into the owner's store (model on the `ContactDetails` handler). The app then
reads via ORM/SPARQL — no new inbox-read API.
**Identity resolution** (known/anonymous): free via app-side SPARQL (JOIN the
sender inbox NURI against `social:contact` docs). **Discovering the owner's
inbox**: embed the owner's `public_store` inbox NURI in the entity document or
Identity resolution (known/anonymous): free via app-side SPARQL (JOIN the
sender inbox NURI against `social:contact` docs). Discovering the owner's
inbox: embed the owner's `public_store` inbox NURI in the entity document or
public profile (the QR profile-share flow already carries it).
## Layer 2 — deployment (from the fork)
@@ -76,18 +76,18 @@ Maintain patched client packages, not just the wasm. The generic forwarding
sides. For write-only (request/response) — unneeded.
- **`@ng-org/orm`** — only if inbox writes join the ORM flow. Otherwise unneeded.
## Layer 3 — consumer integration
## Layer 3 — consumer application integration
Exposing the method is not enough; the consumer must model the entity + its inbox
NURI, write the registration, deposit into the host inbox, and read/resolve
notifications. Several of these are **already done** in the shared-wallet emulation
Exposing the method is not enough; the consumer application must model the entity +
its inbox NURI, write the registration, deposit into the host inbox, and read/resolve
notifications. Several of these are already done in the shared-wallet emulation
(registration wired on the emulated `inbox.post`), which is precisely why this fork
was not needed.
## Why this fallback still matters
The emulated inbox stores `from = null` as *absence of a triple*; it does not seal
deposits, so it does not provide the target's **crypto** anonymity. If a consumer
needs true anonymous-but-verifiable deposits to a non-connected host, only a native
inbox (`from = None` sealed) delivers it — and this fork is the route. Until then,
the emulation is sufficient.
deposits, so it does not provide the target's crypto anonymity. If a consumer
application needs true anonymous-but-verifiable deposits to a non-connected host,
only a native inbox (`from = None` sealed) delivers it — and this fork is the route.
Until then, the emulation is sufficient.