.project/concepts/data-layer/rule_document-per-entity.md

@@ -75,15 +75,22 @@ lève « Set is readonly because scope is empty » (les tests unitaires fake-ng
 Donc : **écriture = SPARQL direct dans le doc de l'entité** (immédiat, par-document) ;
 **lecture = union + re-query** (ci-dessus).
 
-**Piège de graphe (INSERT/DELETE sans wrapper `GRAPH`).** L'écriture doit viser le **graphe par
-défaut** du document — on passe le NURI du document comme **ancre** de `docs.sparqlUpdate` et on
-écrit le corps SPARQL **sans** clause `GRAPH <…>` explicite. La lecture union interroge elle aussi
-le graphe par défaut ancré (`readEntities`/`readUnion`) ; un corps enveloppé dans un
-`GRAPH <nuriDuDoc>` explicite écrit dans un graphe **nommé distinct** que cette lecture ne voit
-pas → l'entité ne fait jamais l'aller-retour (elle « disparaît » silencieusement). Vaut pour
-`writeEntity`, `updateEntityField` et les écritures de `registration.ts`. (Le *pourquoi* côté SDK
-— comment l'ancre restreint la requête au graphe du repo — appartient au SDK `@ng-eventually/client`,
-pas ici.)
+**Convention de graphe (écrire dans le graphe par défaut ancré).** L'écriture passe le NURI du
+document comme **ancre** de `docs.sparqlUpdate` et écrit le corps SPARQL **sans** clause
+`GRAPH <…>` explicite ; la lecture union interroge le même graphe par défaut ancré
+(`readEntities`/`readUnion`). C'est la forme **canonique et toujours sûre** — à conserver pour
+`writeEntity`, `updateEntityField` et `registration.ts`.
+
+> **Correction (2026-07-06).** Un commentaire antérieur (et une version de ce paragraphe)
+> affirmaient qu'un corps `GRAPH <nuriDuDoc>` explicite écrit dans un graphe *nommé distinct* que
+> la lecture ancrée ne verrait pas → l'entité « disparaîtrait ». **C'est faux sur le broker
+> courant** (`@ng-org/web 0.1.2-alpha.13`) : le harness e2e réel de la lib
+> (`packages/client/e2e/`) vérifie qu'un `INSERT DATA { GRAPH <plainNuri> {…} }` **ancré** au doc
+> round-trippe (relu aussi bien en graphe par défaut qu'en `GRAPH <plainNuri>`). Le symptôme « 0
+> entité » qu'on avait attribué à ce « piège » venait en réalité du **hang de wallet gonflé** (cf.
+> `bdd-testing/caveat_wallet-bloat-hang`), pas d'un mismatch de graphe. La règle « sans wrapper
+> `GRAPH` » reste donc un choix de **simplicité/sûreté**, pas une nécessité de round-trip. (Le
+> *pourquoi* côté SDK vit dans `@ng-eventually/client`, pas ici.)
 
 Idem pour la **mutation d'un champ** existant (p. ex. `participantCount`) : muter une valeur
 en mémoire ne tient pas — la re-query union relit la valeur **persistée** depuis le broker