Reconnexion/ng-eventually
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(concept): la règle interdit la divergence, elle ne la met plus en balance

Browse Source 
La feuille testait ce que l'APPELANT apprendrait. Le propriétaire du projet a énoncé la
règle plus large : rester au plus près de NextGraph, et n'admettre aucune implémentation
qui en diverge — que l'appelant s'en aperçoive ou non.

L'ordre des deux questions est ce qui a manqué. Sur la fusion de `readUnion`, posée en
premier, « l'appelant devra-t-il désapprendre ? » ne tranchait pas : « une entité par
document » est une bonne pratique par ailleurs, alors que désapprendrait-il au juste ? Le
raisonnement a piétiné des heures là-dessus. Posée en premier, « la cible fait-elle ça ? »
a demandé un regard : le niveau 1 rend les sujets réels, et l'ORM du niveau 3 porte `@id`
ET `@graph` sur chaque objet en fabriquant le premier quand on l'omet. Divergence, fin.

« Devra-t-il désapprendre ? » reste, mais mesure la gravité d'une divergence inévitable —
jamais son autorisation. Et un tell est ajouté, celui qui a produit ce défaut : une
recommandation que le code impose au lieu de la guider, en rendant l'autre disposition
invisible.
This commit is contained in:
Sylvain Duchesne
2026-08-10 14:51:17 +02:00
parent 7076c0cca8
commit 33b96fdc8d
3 changed files with 29 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.project/concepts/app-contract/_overview.md
+2 -2
View File
@@ -27,12 +27,12 @@ vocabulary:
This library exists so an application can be **written today against the NextGraph that does not ship yet**, and keep its code when it does. Everything under this concept governs that boundary: what the package publishes, what a caller may rely on, what it must not, and what disappears at migration.
The distinguishing question, asked at every surface choice: **would this make a caller learn something it has to UNLEARN?** If yes it is a deviation, whatever it buys — see `rule_would-the-caller-unlearn-it`.
The distinguishing question, asked at every choice — published signature as much as internal mechanism: **does the target do this?** If it does it differently, we do it their way, whatever that costs. *Would a caller have to unlearn it?* comes second, and measures how bad a divergence is — never whether one is allowed. See `rule_no-divergence-from-nextgraph`.
This repo is the **provider** of `contract_sdk-surface`; consuming applications live in other repos and pull it. The per-symbol ruling, with an epistemic label on every target-side claim, stays here in `docs/api-contract.md` — that is maintainer material, not the engagement.
## Read first
- `contract_sdk-surface` — the engagement itself, written from the caller's point of view.
- `rule_would-the-caller-unlearn-it` — the test that decides what may be published.
- `rule_no-divergence-from-nextgraph` — the test that decides what may be built at all.
- `knowledge_what-an-app-deletes-at-migration` — the two fates a published symbol can have.