Sylvain Duchesne
0b37d17c2f
Les deux contrats et la doctrine portent des centaines de citations `file:line` vers `src/`. Le rangement par destin les périmait en bloc — 208 reprises (45 chemins `src/x.ts`, 163 mentions nues). Sans ça la réorganisation pourrissait l'instrument même qui tient la discipline qu'elle sert. Et un défaut relevé par le contrat interne, vérifié : `ng-proxy` fabriquait un membre `login`. `@ng-org/web` n'expose aucune méthode de ce nom — zéro occurrence dans les déclarations installées comme dans `sdk/js/lib-wasm/src/lib.rs` — mais le proxy répondait une fonction au lieu d'`undefined`, laquelle plantait à l'appel. C'était le seul endroit où ce wrapper ajoutait à la surface du SDK, contre son propre en-tête. 157 tests unitaires, typecheck src/test/e2e vert.
60 lines
3.1 KiB
Markdown
60 lines
3.1 KiB
Markdown
# ADR — Use a store NURI as the `useShape` scope AND `@graph`
|
|
|
|
**Date:** 2026-03-17 · **Status:** Accepted (partially superseded — see below).
|
|
Historical decision, ported into this lib because the *insight* still governs how
|
|
the shim opens repos. Original context: the consuming app.
|
|
|
|
> **Partially superseded (2026-07-03).** The private-store-only scope was replaced
|
|
> for shareable domain entities: they are now scoped AND written to the
|
|
> **protected** store (`did:ng:${protected_store_id}`), verified to open without
|
|
> `RepoNotFound`. **The central insight of this ADR still holds** and now applies
|
|
> to **both** stores: you must open the repo via the store's NURI
|
|
> or you get `RepoNotFound`. *(How it is opened has since changed — see the note
|
|
> under Decision.)*
|
|
|
|
## Context
|
|
|
|
Loading test data updated the in-memory ORM signals (immediate UI) but produced
|
|
`RepoNotFound` on `doc_create` and `orm_frontend_update`. Data vanished on reload
|
|
because the SPARQL writes never reached the broker: the verifier's `self.repos`
|
|
HashMap did not contain the store's repo → `resolve_target()` failed.
|
|
|
|
## Options considered
|
|
|
|
### A — `did:ng:i` scope + `doc_create` for `@graph`
|
|
`did:ng:i` is documented as a subscription scope; `doc_create` returns a real
|
|
NURI. **Against:** `did:ng:i` goes through `NuriTargetV0::UserSite`, which does
|
|
NOT open individual repos; `doc_create` calls `resolve_target(PrivateStore)`,
|
|
which requires the repo already in `self.repos` → fails; needs complex retry/timing.
|
|
|
|
### B — the store NURI as scope AND `@graph` (chosen)
|
|
Exact copy of the working `expense-tracker-rdf` example: `orm_start_graph` with
|
|
the store's NURI opens the repo in `self.repos`; subsequent `orm_frontend_update`
|
|
finds it. Simple, no retry. **Against:** slightly less flexible than `did:ng:i`
|
|
(scoped to one store); requires passing the session down to the ORM hook.
|
|
|
|
### C — `did:ng:i` scope + reuse an existing entity's `@graph`
|
|
Works for users who already have data. **Against:** fails for empty wallets (no
|
|
entity to reuse) → falls back to `doc_create` and the same `RepoNotFound`.
|
|
|
|
## Decision
|
|
|
|
**Option B**: use the store NURI as both the `useShape` scope AND the write
|
|
`@graph`, exactly like `expense-tracker-rdf`. This is why this lib's shim opens the
|
|
store repo before writing, and why **`did:ng:i` must never be used as a scope** (it
|
|
breaks writes with `RepoNotFound`). See the scope rule in
|
|
[`../simulation.md`](../simulation.md).
|
|
|
|
*The decision stands; the mechanism named in it has been replaced.* Opening was
|
|
`orm_start_graph` when this was written. It is now `ensureRepoOpen` — `doc_subscribe`
|
|
plus a wait for the first `State` (`packages/client/src/emulated-verifier/open-repo.ts:167`) — after
|
|
`orm_start_graph` was found to hang on a fan-out (`subscribe.ts:28,181`). What must be
|
|
read here is the invariant *"open the repo, by its store NURI, before writing"*, not the
|
|
call that used to implement it.
|
|
|
|
## Consequences
|
|
|
|
- **Positive:** immediate writes after connect (no retry); persistence across
|
|
reload; aligned with the official examples.
|
|
- **Risk:** if NextGraph changes the store's open behaviour, this breaks.
|