Le contrat publie et l'api-contract etaient traites avec le retrait lui-meme ;
restaient les documents qui decrivaient readUnion comme la primitive de
lecture du paquet, ou qui nommaient le module disparu.
Ce que les lecteurs apprennent maintenant : lire un document, c'est
docs.sparqlQuery ancre dessus, et lire plusieurs documents, c'est cet appel
une fois par document -- avec la decision sur une lecture qui echoue ecrite
au point d'appel. Deux consequences sont dites plutot que decouvertes : une
lecture refusee leve au lieu de rendre une liste vide, et les sujets sous le
prefixe reserve urn:ng-eventually: reviennent dans le resultat, a l'appelant
de les ignorer -- sans aucun gain de droits, les deux registres qu'un
document ordinaire porte etant l'adresse de sa boite et, pour un document
public, la cle que son magasin sert deja a qui la demande.
Les briefs dates ne sont pas touches : ils decrivent un etat de juillet, et
le reecrire falsifierait ce qui avait ete decide alors.
Deux corrections indépendantes dans la doc vivante, les briefs et décisions
datés restant tels qu'écrits.
P1a et P1b ne disaient rien à personne. Six mois plus tard il aurait fallu lire
le code pour savoir de quoi on parle, et le coût de la recherche se repaie à
chaque lecture. Ils deviennent cap-surface — la forme des capacités, livrée le
2026-07-28 — et cap-enforcement — ce qui reste : le chiffrement par document et
les gardes d'écriture aujourd'hui décoratives. 28 occurrences.
Et api-contract.md se contredisait à quatre lignes d'intervalle : il annonçait
deux points d'entrée en tête, et en bas qu'il n'y en a qu'un depuis la fusion du
2026-08-07. Vérifié dans package.json avant d'écrire — exports mappe exactement
{".": "./src/index.ts"} et src/polyfill.ts n'existe pas.
Ce qui identifie un symbole polyfill-era ne change pas : le bloc marqué dans
src/index.ts et le test de vocabulaire, plus aucun chemin d'import.
Le nom @ng-eventually/sdk entrait en collision avec le SDK de NextGraph, dont
ce paquet est justement un polyfill. Impossible d'écrire « le SDK » sans lever
l'ambiguïté à chaque phrase — et le contrat publié, lu par une application,
était le pire endroit pour laisser traîner ça.
packages/sdk → packages/polyfill, @ng-eventually/sdk → @ng-eventually/polyfill,
contract_sdk-surface → contract_polyfill-surface, e2e/sdk-entry.ts →
e2e/polyfill-entry.ts, docs/sdk-reference.md → docs/polyfill-reference.md.
Les occurrences de « SDK » qui désignent celui de NextGraph restent intactes,
y compris les chemins dans nextgraph-rs (sdk/js/orm, sdk/js/web). Le tri s'est
fait occurrence par occurrence, pas par substitution.
Le contrat énonce désormais son identité en une phrase : « This package is a
polyfill of NextGraph's SDK. »
Amorce le système `concept` dans ce dépôt et ouvre `app-contract` — la frontière
entre cette bibliothèque et les applications qui la consomment.
C'est un contrat **inter-dépôts** et ce dépôt en est le FOURNISSEUR : les applications
vivent ailleurs et tireront `sdk-surface` d'ici. D'où le type `contract_`, ses cinq
sections obligatoires, et l'inscription dans `.project/contracts.yaml` — c'est
l'inscription qui publie.
Trois feuilles :
- **`contract_sdk-surface`** — l'engagement, écrit du point de vue de l'appelant.
Ce qu'il peut tenir pour acquis : permissif en entrée et précis en sortie ; toute
référence rendue est NUE, aucun appel ne rend jamais de clé ; lire est la possession,
écrire est la propriété ; donner à lire est un seul acte et le destinataire n'appelle
rien ; un dépôt s'adresse à une inbox, jamais à un document ; `ensureIdentity()` est
toute la connexion ; et `configure` est le seul appel qu'il supprimera.
Ce qu'il ne doit PAS tenir pour acquis, dit aussi crûment : aucune confidentialité,
rien de « par lecteur » sur un document public, aucune révocation, aucune écriture
déléguée, et les références ne voyagent que dans un déploiement.
- **`rule_would-the-caller-unlearn-it`** — le test qui décide de tout : est-ce que
ceci ferait apprendre à l'appelant quelque chose qu'il devra DÉSAPPRENDRE ? Avec les
deux tells que la revue de ces jours-ci a rendus concrets : une exception nommée
cesse d'en être une dès qu'on la publie, et un symbole gardé parce qu'il était là
n'est pas une décision.
- **`knowledge_what-an-app-deletes-at-migration`** — les deux destins d'un symbole
publié, le cas intermédiaire d'`ensureIdentity` (substance jetée, site d'appel
conservé), et le fait que la liste de suppression n'est plus portée par un chemin
d'import depuis la fusion des entrées : une garantie mécanique remplacée par une
garantie documentaire, dont seule la moitié est tenue par un test.
Le vocabulaire du concept fixe trois termes que ce projet a déjà payé cher :
`reference` (jamais « lien »), `ReadCap`, `polyfill-era`. `lint` est conformant.
Reste à décider : ce dépôt n'a pas de `CLAUDE.md` racine, donc l'`AGENTS.md` généré
n'est chargé nulle part.
Sylvain Duchesne