Files

T

Sylvain Duchesne 88f396a7ac fix(caps): créer un document en donne le cap, + corriger 9 faits NextGraph

Le trou trouvé par l'e2e contre le broker en ligne : `docs.docCreate` ne
déposait aucun cap pour le créateur, donc un consommateur pouvait créer un
document par la primitive publique puis se voir refuser sa lecture et son
écriture. En amont c'est impossible — `doc_create` commite
`AddRepo { read_cap }` sur la branche Store du store, et le créateur le détient
dès le premier instant. Délibérément non répliqué dans `physical.ts` : les
documents du shim n'appartiennent à aucun utilisateur virtuel, et
`store-registry` classe leurs caps là où il sait à qui ils sont.

e2e : 22 passés / 8 échoués → 39 / 0. Les autres échecs venaient du harnais,
qui agissait comme une seconde identité sans l'établir, ou lisait un document
quelconque comme une inbox. Un run e2e contre un wallet persistant exige une
identité FRAÎCHE par run : `walletInbox(id)` rend l'inbox stable pour son
propriétaire — c'est son intérêt — donc un id fixe accumule les dépôts des runs
précédents (vert au 2e run, rouge au 3e, à code inchangé).

Revue adverse de la documentation, 9 défauts, tous vérifiés à la source avant
correction :

- « chaque document a une inbox native » est FAUX. Seuls les repos de store
  public et protected en ont une (`site.rs:128,149`) ; `new_store_default` n'en
  pose que `if !private` et `doc_create` laisse `inbox: None`. Le store privé
  n'en a pas non plus. Ce que le code fait est donc une ANTICIPATION — assumée
  et notée comme telle dans `documentInbox`, le brief et l'ADR discovery. Ce qui
  est vérifié, c'est la FORME : `AddInboxCapV0` est clé par `repo_id`.
- `InboxMsgContent::Link` est une variante unit sans charge utile : l'inbox ne
  transporte aucun ReadCap. `shareCap` était juste et le reste ; ses citations
  sont complétées aux deux bouts (émetteur `unimplemented!()`, récepteur qui
  ignore `details.read_cap`).
- les 3 stores appartiennent au user (`SiteV0`), pas au wallet ;
- le TODO `OpenRepo` ne concerne pas la lecture cross-wallet — il est dans
  `open_branch_`, après `RepoNotFound` ; charger par cap, c'est
  `load_repo_from_read_cap` ;
- la liste des méthodes JS était un sous-ensemble présenté comme la surface
  (77 exportées) ;
- `outbox-log.ts` n'enregistre rien : il inspecte l'outbox du SDK ;
- l'ADR private-store-nuri-scope citait `orm_start_graph` au présent, remplacé
  par `ensureRepoOpen` ;
- l'incident write-loss plaçait `disconnections_sender.send` dans `broker.rs` ;
- la section « Apps & services » n'a aucune citation et rien ne lui correspond
  dans le moteur : marquée à re-confirmer, pas à citer comme vérifiée.

Aussi : `fileOwnCaps` n'existe plus (`holdOwnCap` / `readStoreCaps` /
`fileOwnStructure`) — pointeur mort corrigé dans `caps.ts`.

2026-08-03 12:17:40 +02:00

3.1 KiB

Raw Blame History

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.

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/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.

3.1 KiB Raw Blame History

ADR — Use a store NURI as the useShape scope AND @graph