From e62a17e5a2a580498b25930049e6b513bf4b2f14 Mon Sep 17 00:00:00 2001 From: Sylvain Duchesne Date: Mon, 6 Jul 2026 23:56:51 +0200 Subject: [PATCH] docs(data-layer): correct the graph-round-trip claim (it was the bloat hang) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The lib e2e harness proves that on the current broker an anchored INSERT DATA { GRAPH {…} } DOES round-trip — the earlier 'explicit GRAPH writes a phantom named graph the read never sees' claim was false; the '0 entity' symptom was actually the wallet-bloat hang (caveat_wallet-bloat-hang), not a graph mismatch. Reframe the no-GRAPH default-graph rule as a simplicity/safety convention, not a round-trip necessity. Lib/app inline comments asserting the phantom-graph claim remain to reconcile. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../data-layer/rule_document-per-entity.md | 25 ++++++++++++------- 1 file changed, 16 insertions(+), 9 deletions(-) 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