diff --git a/.project/concepts/data-layer/rule_document-per-entity.md b/.project/concepts/data-layer/rule_document-per-entity.md index 1b1cb86..a3f9571 100644 --- a/.project/concepts/data-layer/rule_document-per-entity.md +++ b/.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 ` 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 ` 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 {…} }` **ancré** au doc +> round-trippe (relu aussi bien en graphe par défaut qu'en `GRAPH `). 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