ng-eventually/docs/migration-guide.md

Migration guide — when real NextGraph matures

The whole point of this library: the consumer application already writes SDK-shaped code, so when NextGraph ships cross-wallet reads, capabilities and inboxes, only this lib changes. The consumer application's code does not change. This is the checklist.

Guiding invariant

Every emulated piece has a 1:1 image in the real infra. Migration = swap the emulation for the real primitive, remove the scaffold. If a piece of the emulation has no clear target image, that is a drift signal (see simulation.md).

Checklist

1. Emulated ReadCaps → real capabilities

The shape is already the target's (P1a): a ReadCap is the document's key, a each identity holds a set of caps, and there is no read-ACL anywhere. So this step swaps the emulated key for the real one, not the model:

• emulated-verifier/caps.ts's per-identity record becomes the verifier's own local user storage — it was always the cache, not the register. The two durable registers we emulate (readCap on the store's Store branch, link on its User branch) become the real AddRepo / AddLink commits. Remove the emulation; the wallet and the branches already hold them.
• nuri.ts's stand-in cap value — the constant OK — becomes the real r:{base64url(serde_bare(ObjectRef))}. It is one function (mintCap), because every path now READS a stored cap instead of recomputing one. hasReadCap / targetOf stay meaningful: the r: discriminant is upstream grammar, not ours.
• inbox.share(doc, toUser) becomes the native sealed delivery (whatever the SDK ends up naming it — see the note below and ContactDetails.read_cap), and inbox.read's inline absorption becomes the recipient's own verifier applying queued messages. The consumer's call does not change.
• caps.markInPublicStore and the whole of emulated-verifier/public-store.ts disappear: which store a document sits in stops being a fact we record, and serving a public store's repos becomes the broker's job (expose_outer, the ReadCap downloaded from the outer overlay — PublicRepoLinkV0, engine/net/src/types.rs:5098). Nothing an application calls changes: it circulates bare references now, and will still.
• assertMayWrite goes with it — refusing a write on a cap the public store served is a stand-in for the write cap this emulation does not have.
• The read filter (emulated-verifier/read-filter.ts) and the possession gate in read-model.readUnion are then dead code — the broker only delivers documents whose cap the wallet holds. Remove them.
• The write guard (surface/ng-proxy.ts sparql_update override) is a separate axis and is decorative today (every internal writer bypasses the proxy); it belongs to the P1b batch, not here.

The access unit is already the document (@graph), matching the native per-repo cap model, so this is a key-material step, not a reshape.

2. Place documents in real native stores

Today docCreate(..., undefined) writes every document into the shared wallet's private store, and the public|protected|private scope is a logical label in the shim (see the two-axes section in simulation.md).

• doc_create cannot target a non-private native store today — verified: StoreRepo is not constructible from the WEB build of the SDK, so there is no way to pass a public/protected store as the create destination (docCreate's trailing store arg is left undefined → private store). The private store works only because it opens without RepoNotFound.
• When the SDK lets you construct/target a native store, the migration adds a getNativeStore(scope)-style resolver returning the real store to pass as the docCreate destination, so the logical scope label becomes a real store placement. (No such helper exists yet — it is blocked on the SDK gap above.)
• At that point shared-wallet/account-registry.ts maps (account, scope) to the user's real store NURI instead of a document in the shared wallet; the per-scope index document (the store-container emulation) is replaced by the store itself. The surface facing the consumer application (createEntityDoc, listMyEntityDocs, resolvers) is designed to survive that swap unchanged.

3. Drop the resolver / shim

The sharedWalletShim (account → 3 scope-document NURIs, held in a subscribable doc-shim reached via a write-once pointer in the store-root — see nextgraph-current-state.md § The pointer → doc-shim indirection) has no target equivalent — the target has no central directory. Remove it entirely: shared-wallet/account-registry.ts, configureStoreRegistry, the pointer + doc-shim resolution, and the pointerGuard dep. Cross-wallet reads replace the fan-out; per-user wallets replace the shared one.

4. Real inbox → drop the in-lib read emulation

Replace the emulated inbox.ts deposit (docs.sparqlUpdate into a shared-wallet document) with the native sealed deposit, once one is exposed to JS. Its name and shape are NOT known: no inbox method exists in @ng-org/web, the verifier has no InboxPost arm, and inbox_post_link is OUR proposed name (fork-inbox-fallback.md), not an announced API. On the read side the recipient's own verifier unseals each queued sealed message and applies it inline when it processes its inbox — there is no separate curator to build; the in-lib read emulation simply goes away. (There is no global index to replace the cross-account fan-out: both were removed on 2026-07-30 — you cannot discover in NextGraph, you follow links.)

5. Retire the identity store → real per-user login

Remove shared-wallet/virtualUsers.ts (the IdentityStore that persists the identity id in localStorage) and the app-level "Connexion" screen. The technical broker gate becomes the real per-user login (see decisions/shared-wallet-login-flow.md). The flow shape ("broker redirect → app") does not change.

6. Drop the isolation scaffold — already gone

isolation.ts (the old application-visibility filter) was deleted from the library; nothing remains to remove at migration. Kept as a numbered step so the following numbers stay stable across references.

7. Remove the build alias — the client becomes the real SDK

The consumer application imports @ng-org/web / @ng-org/orm resolved to this lib via a build alias during the polyfill period. Removing the alias makes those imports resolve to the real SDK — the ng/useShape/inbox surface is SDK-identical, so no consumer code changes. The one non-SDK call — configure(...) / @ng-eventually/client/polyfill — is deleted. The lib itself disappears.

The one break already taken: declareConnections

P1a broke the consumer once, deliberately and early, so that migration would not. The old surface was an ACL held in memory, which forced the consumer to re-declare every grant on every session (declareConnections). That call disappears: with delivered caps the grant moves to the moment a connection is accepted — one inbox.share(doc, toUser) per document shared — and it persists, because the delivery lives in the recipient's inbox rather than in a map that empties at reload. There is no analogue of protectedDocsOf + the re-derivation loop.

This is a consumer re-architecture, not an API swap, and it is the price of being coded against a model that will exist. Nothing else about the migration below touches consumer code.

What does not change

The consumer application's code. Shapes, screens, the acts of sharing access, entity→scope mapping, the relationship graph — all injected, all untouched. Migration is entirely inside this library plus removing the alias + the bootstrap call. That asymmetry — a mature SDK face outward, all compensation inward — is the library's reason to exist.