ng-eventually/docs/simulation.md

# How this library emulates mature NextGraph on one shared wallet

> Everything in this file is emulation. None of the behaviours described here is a
> real NextGraph feature: each is a stopgap the lib fabricates on top of the
> current, immature NextGraph (the exact gaps it compensates for are in
> [`nextgraph-current-state.md`](./nextgraph-current-state.md)). Every piece has a
> real target and goes away when NextGraph matures — the swap is lib-only, and the
> consumer application's code is unchanged. The per-behaviour recap table lives in the
> top-level [`README.md`](../README.md) (*What is emulated (and how it goes away)*);
> the removal checklist is [`migration-guide.md`](./migration-guide.md). Read this
> file for *how* each emulation works; read those two for *what is fake* and *what
> replaces it*.

The consumer application writes against `@ng-eventually/client` as if NextGraph
already shipped per-entity documents in public/protected/private stores, capabilities
and inboxes. It hasn't (see [`nextgraph-current-state.md`](./nextgraph-current-state.md)).
This file is the lib's own engineering doctrine on how it fabricates that mature
face on top of one single shared wallet / broker. Everything here is
polyfill-era and disappears at migration ([`migration-guide.md`](./migration-guide.md)).

## The premise: one shared wallet, everything readable

Current NextGraph has no cross-wallet read (`OpenRepo` is a TODO at
`engine/verifier/src/verifier.rs:1423`; a foreign NURI raises `RepoNotFound`; a
session only holds its own 3 stores in `self.repos`). So "each user their own
wallet" is blocked at the root — no data ever crosses the boundary between two
wallets.

The lib's answer: everyone opens the same wallet. NextGraph sees a single
identity, so everything is physically readable. "Multi-user" becomes an
application fiction the lib maintains. On top of that one wallet the lib rebuilds,
by emulation, the per-user stores + capabilities + inbox the consumer application
codes against.

## Physical user vs virtual user — never enumerate the physical one

**Nomenclature (aligned on NextGraph, 2026-07-30).** A **wallet** upstream is only a
**keyring**; what owns three stores is a **user** (a *site*), and one wallet holds
several of them (`SensitiveWalletV0.sites`, `engine/wallet/src/types.rs:434,457`).
So this document says *user*, not *wallet*, for the thing an identity is — the two
words meant the opposite of each other here until this was corrected.

Because the emulation runs on ONE shared wallet, distinguish two levels:

- **The physical user** — the single NextGraph user everybody's session opens. Its
  stores hold every account's documents plus the library's own internals (the
  pointer, the doc-shim, the inbox documents) as named graphs, accumulating without
  bound across sessions and runs. Listing or scanning "all documents" at this level
  is meaningless and O(size): it mixes every virtual user's data with library
  internals, and it is exactly what an anchorless `sparql_query` (`GRAPH ?g { … }`)
  does. The physical user is a substrate, not something to enumerate.

- **A virtual user** — the library's emulation of one identity: the documents the
  shim attributes to that account (its three store documents in
  `shared-wallet/account-registry.ts`). This is what "the user owns", and over it "list my
  documents" is meaningful and bounded.

**Which API you use follows that line, and it is enforced** (see `shared-wallet/physical.ts`):
machinery operating on the *index of virtual users* — the store-root pointer, the
doc-shim, the account records — goes through unguarded primitives that are never
exported from the package. Everything touching a virtual user's own content goes
through the guarded `docs.*`, even when the library is what calls it. One API is the
app's; the other must never be.

**Consequence for reads (see `read-model.md`):** to list an identity's entities you
enumerate the *virtual* user — that account's store document, bounded to its own
documents — never the physical union. A bloated shared wallet then costs nothing,
and nothing is enumerated across users at all: you read your own documents and the
ones whose cap you were given.

At migration each virtual user becomes a real user with its own wallet; the
physical/virtual distinction, the "never enumerate the physical one" rule, and
`shared-wallet/physical.ts` all dissolve into native per-user reads.

## Two axes, never conflate them (store ≠ document)

The single most load-bearing distinction. Two **orthogonal** axes the
terminology historically fused:

- **Axis A — which native store?** A wallet has 3: `private_store_id`,
  `protected_store_id`, `public_store_id`. Historic origin of "mono-store /
  multi-store" (use 1 store vs the 3).
- **Axis B — how many documents in a store?** A store contains documents; the
  document (= repo = `@graph`) is the sharing + rights boundary. The ReadCap —
  hence isolation — is per-document.

`docCreate(sessionId, "Graph", "data:graph", "store", undefined)` targets the shared
wallet's private store. The trailing `store` arg left `undefined` targets the
private store (this is what `shared-wallet/account-registry.ts`'s `createDoc()` does). So every
document the shim creates physically lives in one store (private), and the
`public|protected|private` scope is a logical label tracked in RDF by the
shim — not a NextGraph store. Therefore what a consumer application's "multi-store"
flag switches on is really multi-document with logical scope labels, never
multi-store. Do not read `Scope` (`types.ts`) as a physical store — it is the
logical label the registry attaches.

> Why `undefined` and not a real store? Because `doc_create` **cannot target a
> non-private native store** today from the WEB build: `StoreRepo` is not constructible there (verified
> — see the parked `getNativeStore` note in
> [`migration-guide.md`](./migration-guide.md)). The private store is reachable
> because it opens without `RepoNotFound`.

## The shared-wallet shim (`shared-wallet/account-registry.ts`)

Emulates the target infrastructure — where each user owns their own
public/protected/private stores — on top of one shared wallet.

- **One document per (account × scope)** inside the shared wallet, created via the
  `docs.docCreate` primitive. The `scope` (`public|protected|private`) is a
  logical attribute tracked here, not a physical store.
- **The `sharedWalletShim`** is the mapping `account → its 3 scope-document
  NURIs`. It is persisted as RDF, but **not directly in the store-root graph** — it
  lives in a subscribable **doc-shim** reached through a write-once **pointer** in the
  store-root, an indirection forced by a NextGraph fact: "findable-without-lookup"
  (store-root) and "subscribable / cold-read-authoritative" (`did:ng:o:` repo with a
  first-`State` barrier) are DISJOINT. The pointer (findable) names the doc-shim
  (authoritative); resolution reads the pointer from the store-root, opens the doc-shim
  through its barrier, and reads the account authoritatively — so a fresh reconnecting
  session never mistakes sync-lag for "account absent" (which would provision a FORK).
  Full rationale — including why the old account-level retry (`provisionRetry`) is
  removed (pre-indirection store-root records are NOT recovered; such wallets are dev
  data and simply get a fresh doc-shim) — is in
  [`nextgraph-current-state.md`](./nextgraph-current-state.md) §§ *Findable vs
  subscribable* / *The pointer → doc-shim indirection*. This map is the
  account→document trust root, which is why every untrusted value that reaches its
  SPARQL is escaped (see SPARQL hardening below). It makes identity resolution
  cross-device: another device opening the same wallet reads the same pointer → the
  same doc-shim → the same virtualUsers.
- **Per-entity documents + per-scope index.** `createEntityDoc(id, scope)`
  makes a dedicated document for one entity (mirrors the target, where each entity
  is its own document/repo with a future inbox) and appends its NURI to the
  account's scope index document — the index doc plays the role of the future
  store-container (it lists the entity-document NURIs "in" that scope).
  `listMyEntityDocs(id, scope)` reads back ONE user's documents — bounded to that
  user, and the only listing there is: the cross-account fan-out
  (`listEntityDocs` / `resolveReadGraphs` / `allAccounts` / `loadShim`) was
  **removed on 2026-07-30**, being cross-user enumeration by construction. The real read path is
  `readUnion(docs)`, which reads the by-need doc set with one per-doc
  anchored `sparql_query`, never an anchorless union-scan of the physical
  wallet (see [`read-model.md`](./read-model.md)). The consumer application resolves
  the by-need doc set from the current wallet's own scope index and
  `listMyEntityDocs(id, scope)` (its own account, bounded — no cross-account fan-out).
- **Generic by construction.** The registry knows only the three native scopes,
  zero application entity kind. The consumer application maps its entities to a scope
  and injects the session + identity-id normalization via `configureStoreRegistry({
  getSession, normalizeId })` (`polyfill.ts`).

The `store≠document` two axes materialize here directly: the registry moves along
axis B (more documents = more isolation), never axis A (it always writes into the
one private store via `docCreate(..., undefined)`).

### A virtual user's structure — the three emulated stores

A *virtual user* = one account in the shim, keyed by its virtual-wallet id
(the technical identifier the consumer application sets when the physical user is
opened; it identifies *which* virtual user, and is an id rather than a
human-friendly handle). Its structure mirrors the target "1 user = 1 wallet with 3
native stores":

```
Virtual user (id)
├── public store    = docPublic  index → [ entity doc NURI, entity doc NURI, … ]
├── protected store = docProtected index → [ record doc NURI, record doc NURI, … ]
└── private store   = docPrivate index → [ record doc NURI, … ]
```

So the 3 native stores (public/protected/private) are present, but emulated: each
"store" is an index document
(`VirtualUserRecord.{docPublic,docProtected,docPrivate}`) that lists the NURIs of the
per-entity documents in that scope. It is not a physical native store.

Everything is physical in one place: the 3 index documents, every per-entity
document, and the shim anchor itself all live in the shared physical user's
private store (`docCreate(..., undefined)`). The 3-store structure is the per-account
logical layer the lib maintains on top.

```
Physical user (shared, one) → private_store (physical) holds everything:
   • the shim anchor:  virtual-wallet-id → { docPublic, docProtected, docPrivate }
   • every account's 3 scope-index docs + all per-entity docs + inboxes
```

At migration each virtual user's 3 index documents become the user's 3 **real**
native stores, the entity documents move into them physically, and the
virtual/physical distinction dissolves (see [`migration-guide.md`](./migration-guide.md)).

### SDK-shaped scope resolvers — the consumer application holds no store-id

The consumer application must never construct a `did:ng:${store_id}` NURI itself:
physical placement is the lib's job (the whole point of the SDK boundary). Two
resolvers turn a logical scope into an opaque graph NURI without exposing any
store-id:

- **`resolveScopeGraph(scope)`** — the graph where the current session writes
  entities of `scope`, and whose repo `useShape` subscribes to read them back.
  Use the returned value as BOTH the read scope (`useShape(shape, nuri)`) and the
  `@graph` write target. Placement lives HERE (Axis A): `private` → the private
  native store; `public` + `protected` → the **protected** native store, because
  `doc_create`/ORM cannot target a non-private/protected native store today (SDK
  blocker, [`migration-guide.md`](./migration-guide.md)). At migration each scope
  resolves to the user's real per-scope store — the change is in this function,
  and the consumer application is unchanged.
- **`userInbox(id)` / `openDocumentInbox(doc)`** — an inbox BELONGS to someone. The
  first is a user's own inbox (where Links arrive), the second a DEDICATED inbox for
  one of its documents, opened on demand by its **owner only** (ownership read from the
  Store branches — a received cap is not ownership, and a recipient must not be able to
  redirect the owner's deposits to itself). Both are dedicated documents (real repo
  NURIs from `docCreate`), never the private-store root: routing deposits into the shim
  graph would bloat the account→document trust root without bound. `myInboxes()`
  enumerates both levels — what `emulated-verifier/connect.ts` drains at connection — and `isOwnInbox`
  answers from the same record. *(The former `resolveInboxAnchor`, a single inbox COMMON
  to every user, was removed on 2026-07-30: nothing may be common but the mechanisms
  that make the virtual users work.)*
- **`documentInboxAddress(doc)` — the DEPOSIT side, and the one a third party uses.**
  Reading an inbox and finding where to deposit into it are opposite acts with opposite
  audiences, and conflating them is what made per-document inboxes unusable at first:
  resolution answered *"which inbox do I know for this document"*, so a depositor got
  one of their own and their deposit vanished silently
  ([`briefs/2026-08-03-document-inbox-addressing.md`](./briefs/2026-08-03-document-inbox-addressing.md)).
  A document that has an inbox carries its address on its emulated **Header branch** —
  a reserved subject inside the document, so any holder of the document reads it, and
  `read-model` filters the whole `urn:ng-eventually:` namespace out of consumer data
  (`src/emulated-verifier/machinery.ts`). This mirrors upstream's split: a depositor seals with the inbox
  PUBLIC key and needs nothing else, only the owner holds the private half.
  **One inbox belongs to one document** — never several documents behind one inbox, a
  relation upstream cannot express (the verifier routes by `inboxes: PubKey → RepoId`
  and unseals with that repo's key, `engine/verifier/src/verifier.rs:1677,1928`), which
  is also why a deposit carries no target document: the address identifies it. A fresh
  document therefore has NO inbox and `documentInboxAddress` returns `undefined` — its
  owner opens one when the document is meant to receive, which is what keeps the cost
  proportional. At migration the address becomes the repo's native inbox pubkey and the
  resolution moves; the consumer-facing act is unchanged.
- **`inbox.postToDocument(doc, { payload })`** — the one call an app makes to reach a
  document's owner: it names the DOCUMENT, never an inbox. **Throws** when the document
  has no inbox, rather than returning quietly: a deposit that vanishes without an error
  is the exact bug this path shipped with.

Both resolve the native store ids from the injected session
(`RegistrySession.protectedStoreId` / `publicStoreId`, alongside the existing
`privateStoreId` anchor). The consumer application hands the whole session to the
lib at the one injection point (`configureStoreRegistry({ getSession })`) — that is
wiring, not placement logic; everything else in the consumer application speaks only
in scopes. If the session omits `protectedStoreId`, the non-private scopes fall back
to the private store rather than emit a broken NURI.

## `RepoNotFound` and the `orm_start_graph` scope rule

A hard constraint inherited from the SDK: to read **and** write entities through
the ORM, the store's repo must be **explicitly opened** in the verifier's
`self.repos` HashMap. `orm_start_graph` with a store's NURI opens that repo;
without it, `orm_frontend_update` fails with `RepoNotFound`.

- **Scope** for `useShape`: the store NURI, e.g. `did:ng:${privateStoreId}` (or,
  in the consumer application, a per-user store once that migration happens).
- **`@graph`** (write target): the same store NURI.
- Never use `did:ng:i` as a scope: it subscribes to the user's whole site via
  a special code path (`NuriTargetV0::UserSite`) that does not open individual
  repos, breaking every write with `RepoNotFound`.

Both the private and the protected native stores were verified to open the same
way for ORM+SPARQL (round-trip probe, no `RepoNotFound`). The original arbitration
is preserved in [`decisions/private-store-nuri-scope.md`](./decisions/private-store-nuri-scope.md).

## The `@ng-org` double-proxy `DataCloneError` constraint

A validated hard constraint, not a style choice: `docs.ts` calls the real
injected `ng` (`getConfig().ng`) directly, never the public `ng` proxy
(`makeNg` in `surface/ng-proxy.ts`).

`@ng-org/web`'s `ng` is already an iframe-RPC proxy (postMessage marshaling,
see [`nextgraph-current-state.md`](./nextgraph-current-state.md) § integration).
Wrapping it in the lib's own JS `Proxy` (double proxy) breaks `doc_create`'s
postMessage marshaling with `DataCloneError: function ... could not be cloned`.
Reaching the real `ng` held in the config avoids the double-proxy. This was
verified: routing the shim's `doc_create`/SPARQL through the public proxy turned
4 multistore scenarios red, so it was reverted. The integration boundary is:

- **Through the lib's public proxy** (validated): `useShape` (ORM + ReadCap
  filter), `init`/`initNg`, `login`.
- **Through the real injected `ng`** (`docs.ts` primitives): `doc_create` + all
  shim/inbox SPARQL.

`docs.ts` therefore imports **no** `@ng-org` package and must **not** import from
`./ng-proxy`.

## Emulated ReadCap — per document (`emulated-verifier/caps.ts` + `emulated-verifier/read-filter.ts`)

In the target the broker only delivers documents the wallet holds a ReadCap
for, so `useShape` already returns an authorized subset. Here (single shared
wallet, everything readable) the lib reproduces that with a read-filtered view:

- **`CapRegistry` (`emulated-verifier/caps.ts`)** models a ReadCap as what it is: **the document's
  key**. The access unit is the document = repo NURI (an item's `@graph`), never
  the item — because in `nextgraph-rs` a store is just a container repo and holding
  its cap does not grant the repos it references (no store-level read inheritance;
  verified). The registry records, **per identity**, the caps it holds — `Map<Nuri, ReadCap>`
  — and answers exactly one question: `capFor(nuri)`, *do I hold this document's
  cap?* There is deliberately **no** "may principal P read document D": that is an
  ACL question, and the real model cannot answer it either.
- **`nuri.ts`** carries the cap-less / cap-bearing distinction, which upstream is
  one object (`NuriV0 { target, access }`) discriminated by the `:r:{cap}` segment.
  `Nuri` names, `ReadCap` names *and* reads. Both are plain strings — the real SDK
  takes `nuri: String` and enforces at runtime through cryptography, so a branded
  type would be a concept NextGraph does not have. The stand-in key value is the
  constant `OK` (see the module header): the only question the emulation answers is
  *do I hold this cap or not*, so the value says exactly that and pretends nothing
  more. P1b, not P1a, is the batch that turns the shape into a protection.
- **`emulated-verifier/read-filter.ts`** — `makeReadFilteredView` wraps the reactive set in a
  `Proxy`: iteration / `size` / `forEach` keep only items whose `@graph` the
  current holder holds; everything else (`add`, `delete`, `has`, `getById`…) forwards to
  the target, preserving writes and reactivity. An item with no `@graph` is kept (it
  names no document, so there is no cap to hold). `filterReadable` is the pure
  variant. Note the absence of a `user` parameter — that absence *is* the model.
- **`useShape` (`surface/use-shape.ts`)** applies the view only once a cap exists at all
  (`caps.isEnforcing()`) — before that it passes the real set through unchanged (no
  regression for a consumer that never touches caps). Once ANY cap is issued the
  regime is possession for **every** holder, including one who holds nothing:
  that is the isolation.

In a mono-store layout (every item in one repo) this is all-or-nothing on that
document — exactly the native behaviour, and why fine-grained isolation requires
one document per entity (axis B).

### Where caps come from — stored, never derived

`doc_create` returns a **cap-less** NURI, so "no function ever goes from a bare
reference to a cap" cannot be the whole rule — it would lock a document's own creator
out of it. The real mechanism: creating a document commits `AddRepo { read_cap }` to
the store's **Store branch**, separately from the `ldp:contains` listing on its Main
branch. That is where an owner finds the caps of what it created; a cap RECEIVED for
someone else's document goes elsewhere, on the **User branch** (`AddLink`). The wallet
itself holds one key per user — the private store's read cap — from which the rest is
reached. Hence the invariant:

> **You do not derive a cap from a bare reference. You look it up in what you hold —
> or you were given it.**

Three ways a cap arrives, and there are no others:

- **Creation.** `createEntityDoc(id, scope)` writes the cap on the store's emulated
  Store branch (`shim:readCap`) and the creator holds it. The consumer declares
  nothing, and the cap is minted exactly ONCE — the stored value is the held value,
  which is what keeps this correct when P1b makes the key real.
- **Re-listing.** `listMyEntityDocs(id, scope)` READS those records back. It does not
  recompute anything: that is the whole reason for storing them, and it is what lets
  a **fresh session** read its own documents again with nothing re-declared — the
  durability the old in-memory ACL faked and lost every reload.
- **Delivery.** `shareCap(cap, toInbox)` deposits one document's cap into one
  recipient's inbox; `inbox.read` applies it inline, exactly as the recipient's own
  verifier applies queued messages upstream. **Receiving needs no operation** — a
  consumer already watching its inbox gets them, and the resulting change
  re-triggers the reads that were empty for want of that cap.

**The caps a holder holds are not the sharing mechanism.** Handing over a *store* cap would give
away everything the store contains, present and future. The unit of sharing is the
document; the Store branch is a private index.

Switching identity **switches** records — it never wipes one. If it wiped,
durability would be a lie and per-session re-declaration would come back under
another name.

### Sharing, publication, and the recipient

- **`setCurrentUser(id)` (`polyfill.ts`)** — the SDK's "current identity" call.
  It selects *whose* caps are consulted, lazily, so the delivered subset always
  reflects the identity in effect at read time.
- **`shareCap(cap, toInbox)`** — the one sharing act the lib exposes. Recipients
  are addressed as **inboxes**, which `inbox.post(targetInbox)` already does here;
  there is no `PrincipalId` in this surface, because that notion exists nowhere
  upstream. Reaching several recipients means calling it once per inbox, which is
  what the real model does too (each delivery is sealed to one recipient).
- **`getCaps().publishRepoLink(doc)`** — upstream `RepoLinkV0`: a shareable link
  **whoever receives it** can open. Put the *link* in what you make discoverable, not
  the bare NURI, or no reader can open it. Publication is **not recursive**: a public
  document may reference private ones, and the reference grants nothing on what it
  references — which is what lets a public object point at a private identity without
  disclosing it.

Upstream, directed delivery is a **gap, not a disagreement**: `ContactDetails.read_cap`
exists, but the message construction is `unimplemented!()`, its only caller passes
"without read_cap", and the receiver discards the cap. The shape is right; the
implementation is absent, so this lib emulates it meanwhile.

**Key rotation needs nothing on this surface.** A rotated key is re-sent to the
inbox of whoever keeps access, and that inbox is processed automatically at the next
connection — so access is not lost, it is *deferred*, consistent with local-first.
Same channel as the initial delivery, so there is **no subscription obligation** to
expose and no special case to write. Revocation stays what it is: stop re-delivering,
non-retroactive.

The relationship concept — who is "connected" to whom, and therefore whose documents
to share — is owned by the consumer application, not the lib. A connection or
friendship is not a NextGraph primitive; the only platform-mappable primitive is the
per-document cap delivery above.

The result is the target's discrimination reproduced end-to-end: you read the
documents whose caps you hold, and nothing else. Proven in
`test/isolation-active.test.ts` (a document nobody shared is unreadable; a share to
one inbox reveals it there and only there; a bare reference reads nothing while the
repo link opens the published document; a returning identity keeps its caps) and in
`test/cross-user-access.test.ts`, the acceptance test below.

This discrimination is only observable because each entity is its own document (the
consumer application creates per-entity docs via `createEntityDoc`) — in a mono-store
layout the per-document ReadCap is all-or-nothing.

### The acceptance test — no cryptography required

Alice owns a protected document holding a secret and a public one that carries a
**reference** to it. Bob, holding the public document's link, reads it, finds the
reference, and can NAME the protected document while reading nothing of it —
publication is **not recursive**. Charlie, holding the same link plus the protected
document's cap (delivered to his inbox), reads through the very same reference. The
only difference between them is each of them holds; nobody was named to any
registry. And dynamically: the cap lands in Bob's inbox, his client processes it, and
the read that was empty yields the content — the held-caps signal re-running it.

That is what real NextGraph does, and it holds **without a line of encryption** —
which is what makes the P1a (shape) / P1b (enforcement) split honest rather than
cosmetic. Proven in `test/cross-user-access.test.ts`.

> **After P1a the shape is right and the isolation is still fake.** The stand-in key
> is a constant, and several read paths (`docs.sparqlQuery`/`sparqlUpdate`, the whole
> inbox, `store-registry`, `subscribe`, `open-repo`) consult no cap at all — worse,
> any wallet can reach any document. That is the subject of
> [`briefs/2026-07-30-virtual-wallet-boundary.md`](./briefs/2026-07-30-virtual-wallet-boundary.md).
> Nothing may be claimed "anonymous" or "private" until it lands.

### Write-guard coverage (honest scope)

The emulated write guard (`surface/ng-proxy.ts`, `sparql_update` override) enforces the
per-document write cap on the public `ng` proxy only. In practice the
consumer application's write paths (`docs.sparqlUpdate`, ORM `ngSet`) call the real
injected `ng` directly — never the public proxy — for the validated `DataCloneError`
reason above. So the guard is best-effort: it fires for any write routed
through the public proxy, but the consumer application's real write paths bypass it
and are not guarded today. This is a deliberate, recorded limitation of the emulation
(the write guard becomes effective only when the broker/verifier enforces caps
natively at migration); the read side is what makes isolation observably active.

### The per-document ReadCap is the isolation path (item-level filter retired)

Isolation is enforced by the per-document ReadCap (`emulated-verifier/caps.ts` + `emulated-verifier/read-filter.ts`)
alone: the access unit is the document (`@graph` = repo), and the only acts are
possession-shaped (`createEntityDoc` files a cap, `shareCap` delivers one,
`publishRepoLink` emits an openable link). Because the consumer application writes
one document per entity, the per-document cap discriminates at entity granularity —
the target's behaviour.

The old item-level application-visibility filter (the since-deleted `isolation.ts`
`applyIsolation`, a `Set`-of-records filter keyed on owner+scope) is retired
from the consumer path: the application carries no access logic — it declares its
identity and shares caps, and trusts the SDK. Its matrix functions are
dead scaffolding kept for reference and removed at migration. There is no longer a
second, coexisting app-layer filter to reconcile — the single axis is the
per-document cap, exactly as in the target.

## Emulated inbox (`inbox.ts`)

Current NextGraph does not expose the inbox to the JS SDK (verifier has no
`InboxPost` arm; no wasm sealing helper — see
[`nextgraph-current-state.md`](./nextgraph-current-state.md) § Inbox). Rather than
fork the broker ([`fork-inbox-fallback.md`](./fork-inbox-fallback.md)), the lib
emulates the inbox on the shared wallet:

- **Target vs polyfill.** In the target, `post` seals a reference into the owner's
  native inbox — through a JS call that **does not exist and is not announced** — and the recipient's
  own verifier unseals each queued message and applies it inline when it processes
  its inbox — there is no separate curator or materialization process. Here,
  everything is readable, so the lib emulates the read side in-lib.
- **`post(targetInbox, opts)`** appends a deposit `{ from, payload, ts }` as RDF
  into the inbox document (in the shared wallet) via `docs.sparqlUpdate`. Each
  deposit is a unique RDF subject, so concurrent deposits don't collide. `from` is
  bound to the current identity (`getCurrentUser`) — it is authenticated, not
  caller-supplied: omit it to stamp the current user, pass `null` to deposit
  anonymously, and a `from` naming another principal is rejected as a spoof.
  This reproduces the protocol's "identified if known, anonymous otherwise" and
  the target's guarantee that a client cannot forge another's sender identity (in
  the target the broker seals `from` from the wallet's own key; here the check
  closes the spoof the shared wallet would otherwise allow). The emulation stores
  `from = null` as *absence of a triple*, so it does not provide the target's
  crypto anonymity (`from = None` sealed), which only a native inbox would.
  Proven in `test/inbox.test.ts` case (c).
- **`read` / `materialize` (alias)** emulate the recipient-side read: they read the
  deposits back via `docs.sparqlQuery`, JSON-parse each payload, sort by `ts`.
- **`watch(targetInbox, onDeposits, { intervalMs })`** is the emulated watcher: it
  polls `read` and fires when the deposit count changes (the polyfill has no
  reactive inbox subscription). Fires once immediately; returns an unsubscribe.

### An inbox BELONGS to a virtual user (2026-07-30)

`storeRegistry.userInbox(id)` resolves — creating on first sight — the inbox
document of one virtual user, recorded in the doc-shim under `shim:docInbox` and
read by its own query (so an account written before this existed still resolves).
The asymmetry that matters:

- **Depositing into anyone's inbox is open.** It is the ONLY way a link crosses
  from one wallet to another, and since you cannot discover, it is the bootstrap of
  the whole reachability graph. A deposit grants the depositor nothing in return —
  upstream it is an anonymous sealed box.
- **Reading an inbox is confined to its owner** (`isOwnInbox`, enforced in `read` /
  `readSynced`, hence in `watch`). Since P1a routes ReadCaps through deposits, an
  unguarded read let anyone who knew an inbox NURI collect the caps addressed to its
  owner — defeating directed sharing. Anonymous owns no inbox and reads none.

At migration this guard disappears into cryptography: an inbox is sealed to its
owner's key.

The module knows no domain — the consumer application supplies the inbox document
NURI and interprets `payload`. At migration `post` becomes the native sealed
deposit — **whose JS name and signature are not known**, since none is exposed or
announced — and the read side is served by the recipient's own verifier unsealing
queued messages inline.
The inbox + watcher is the one deposit/read mechanism a consumer reuses for its own
purposes — a registration/deposit, a cap delivery (`shareCap`), a link handed to
someone — same `post` API, same watcher.

## The virtual user boundary (`emulated-verifier/reach.ts` + `shared-wallet/physical.ts`)

Every access function is confined to the user currently connected: no cross-user
access, so the consumer is coded against a reach that will actually exist.
**Two rules, one criterion — possession — implemented in two places**, deliberately
redundant so a lapse in either is caught by the other:

- **Rule 1, authorization** (`assertMayReach`, at the passage points `docs.sparqlQuery`
  / `sparqlUpdate` / `subscribeDoc`): nothing reaches `ng` unless the connected user
  possesses that document's cap. It fires on a request that should never have been
  made, and makes it fail loudly rather than succeed quietly.
- **Rule 2, do not even attempt** (`mustNotAttempt`, at the callers — `readUnion`
  filters before opening or reading, `ensureRepoOpen` returns): a reader holding no
  cap does not issue the operation at all. Upstream you cannot even *address* a repo
  you have no cap for, so asking is not "a read that will be refused" — it is a read
  with no meaning.

**Possession decides, never the shape of the reference in hand.** A caller
legitimately holds a bare NURI while possessing its cap elsewhere — references travel
bare through content and stores, the cap sits in what the user holds.

The exception is **depositing** into another user's inbox (`docs.depositInto`): a
named primitive rather than a flag, because it is a different act — you hold no cap,
you cannot read back, and you get nothing in return. It is the only channel by which
a link crosses between users, hence the bootstrap of the whole reachability graph.

The machinery lives in `shared-wallet/physical.ts` (see *Physical user vs virtual user* above):
unguarded primitives, never exported from the package, used only for the index of
virtual users. Separating the FUNCTIONS is what replaced an earlier exemption list —
the machinery does not get waved through the guard, it calls something the guard
never saw.

## Connecting a user (`emulated-verifier/connect.ts`)

Processing inboxes is the **library's** job, not the app's: a consumer must never
have to remember to drain a queue for documents shared with it to become readable —
forgetting would look like "the share did not work" rather than "nobody consumed the
queue". So `setCurrentUser` fires `connectedUser()`, which does two things in order:

1. **Restore** — read back the caps this user already applied (`readLinks`, the
   emulated `AddLink` records on its User branch) into what it holds. Durable state,
   one read, no inbox involved.
2. **Drain** — process every inbox it may read (`myInboxes`: its own, plus one per
   document it opened an inbox on), filing any new Link durably.

Restore-first is what lets a reconnecting user read its shared documents immediately
instead of waiting on a queue round-trip.

**Fire-and-forget, deliberately.** The setter is synchronous and every consumer calls
it from synchronous code; making it async would push the wait back onto the app,
which is the obligation this removes. The work announces itself through
`CapRegistry.onChange` — which `watchShape` already listens to — so a view that was
empty for want of a cap re-reads when the cap lands. `connectedUser()` is exported
for a caller that needs to await it (tests, a deterministic startup).

**It does not provision.** Connecting an identity that does not exist creates
nothing (`resolveAccount`, not `ensureAccount`): otherwise connecting would mint a
user's stores and their caps as a background side effect, arming the whole emulation
at a moment nothing controls.

*Cost worth knowing*: `setCurrentUser` therefore has observable asynchronous effects
— it reads, and it logs. Tests asserting on log output must await `connectedUser()`
first.

## ~~Emulated discovery index + special account~~ — REMOVED 2026-07-30

**There is no discovery in NextGraph. You cannot discover; you can only follow links** (see [`readcap-and-nuri-model.md`](./readcap-and-nuri-model.md) §4ter-bis). Publishing is two acts — place the data in your public store, **and** circulate its link (into an inbox, or into a document the reader already holds) — and it is seen only by those who received the link.

`discovery.ts` (a global index owned by a reserved `@index` account, `submitToIndex` / `readIndex` / `watchIndex`), its tests, and `watchShape`'s public-scope fold were **removed**. The module failed on two independent counts: it emulated a capability the target will never have — teaching consumers a model that does not exist — and it was **data common to several wallets**, where nothing may be common but the indexing mechanisms that make the virtual users work.

The ADR that specified it ([`decisions/discovery-model.md`](./decisions/discovery-model.md)) is marked superseded, and keeps the part that survives: the `discovery → synchronization → query` frame still holds, with stage 1 re-read as *"a link reached you"* rather than *"you consulted an index"*. Which makes the **inbox** the bootstrap of the whole reachability graph — see [`briefs/2026-07-30-virtual-wallet-boundary.md`](./briefs/2026-07-30-virtual-wallet-boundary.md).

## Emulated write guard (`surface/ng-proxy.ts`)

The public `ng` proxy overrides `sparql_update` to enforce an emulated write
cap: a write is refused unless the current user holds the target document's
write cap. It passes through (no regression) unless a write policy exists and that
specific document (the `anchor` arg) is governed by it — ungoverned docs (the
mono-store default, no cap declared) flow through unchanged. This mirrors the target
broker/verifier, which refuses a write without the document's write cap.

## Identity store (`shared-wallet/virtualUsers.ts`)

The real NextGraph login (redirect to the broker, opening the single shared
wallet) is perceived as a technical access barrier (see the login
flow in [`decisions/shared-wallet-login-flow.md`](./decisions/shared-wallet-login-flow.md)).
This layer is not a login: it is an `IdentityStore` that holds the current
identity id the consumer application relays to it:

- The identity id is set at wallet-import time by the consumer application and
  relayed to the lib via its current-identity call. It is persisted in
  `localStorage` so the id survives reloads and lands on the same account
  when the shared wallet re-opens. In practice the id is often a human-friendly
  handle the consumer application chose, but the lib's surface speaks only of an id.
- `set(id)` / `clear()` / `get()` only read/write the id in storage. They never
  call NextGraph (no `session_stop` / `wallet_close`) — the shared wallet stays
  open underneath. The real logout lives elsewhere (hidden in the consumer
  application's settings/debug), because it forces a new redirect.
- Framework-agnostic: no React, no DOM beyond an optional injected
  `VirtualUserStorage` (a `window.localStorage`, a test fake, or `null` for SSR). The
  React `Context`/`Provider` stays in the consumer application. `normalizeId`
  (case-insensitive, optional leading `@` stripped, trimmed) is the pure
  normalizer, reusable as the shim key normalizer.

## SPARQL injection hardening (`sparql.ts`)

Every module that builds SPARQL by interpolation (inbox, store-registry) routes
untrusted values through `sparql.ts` first, because a `"` closes a literal and a
`>` closes an IRI, letting an injected value wreck the shim graph (the account →
document trust root):

- **`escapeLiteral`** — for LITERAL position (`"..."`): escapes backslash,
  double-quote, C0 whitespace. Lossless (literals legitimately carry arbitrary
  text — JSON payloads, display names).
- **`escapeIri`** — for untrusted values embedded into an IRI (`<PREFIX:${…}>`,
  e.g. an identity id minted into an account-subject IRI): percent-encodes every
  IRI-hostile character so any id (spaces, unicode, punctuation) stays
  usable while breakout is impossible.
- **`assertNuri`** — for trusted-shaped NURIs coming back from `ng`
  (`did:ng:...`): validates and throws on IRI-breaking chars rather than emitting
  a malformed/injected query.

These are re-exported from `@ng-eventually/client` so the consumer application
reuses the same escaping when it builds SPARQL.