Reconnexion/ng-eventually
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
117 Commits 2 Branches 2 Tags
fc3c129bd3c6adf4b5b7312e5d5d60070e95af50
Commit Graph

8 Commits

Author SHA1 Message Date
Sylvain Duchesne fc3c129bd3 fix: l'identifiant est dans l'URL avant qu'init() ne l'emporte 
@ng-org/web fait déjà la redirection vers le broker — même hôte, même forme,
même test de cadre (dist/ngweb.js). Le polyfill n'a donc rien à réimplémenter
là : ce qui lui revient, c'est la seule chose qu'init() ne peut pas faire, à
savoir mettre ?ng-id= dans window.location.href avant qu'il ne le lise.

rememberIdentity() s'exécute désormais sur les trois chemins — identité posée
par l'appelant, venue du stockage, ou saisie à la barrière. Le cas du stockage
était le silencieux : le paramètre restait absent, l'iframe lisait une identité
vide et provisionnait un second espace virtuel, sans erreur.

L'écriture dans le stockage et celle dans la barre d'adresse sont deux try
indépendants : un stockage qui refuse d'écrire ne doit pas emporter avec lui le
paramètre, qui est le seul à franchir la frontière de partition.

Le contrat retire l'obligation « être ouverte via la redirection du broker » :
elle n'a jamais été celle de l'application. Ni broker, ni iframe, ni redirection
n'y sont plus nommés.
 2026-08-11 11:59:57 +02:00
Sylvain Duchesne 737729c9ce refactor: le paquet s'appelle polyfill, « SDK » désigne celui de NextGraph 
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. »
 2026-08-10 17:14:25 +02:00
Sylvain Duchesne 49b046268e docs(contract): le contrat décrit l'API, et rien d'autre 
Récriture complète de `contract_sdk-surface.md` sur le cadrage du propriétaire du projet :
**le contrat dit ce que le SDK met à disposition, point.**

Ce qui en sort, et pourquoi ça n'y avait pas sa place :

- **tout état d'implémentation** — chiffrement, confidentialité, valeur de remplacement,
  ce qui est émulé, ce qui n'est pas encore fait. Le lecteur est un agent qui développe
  une application appelante : s'il lit qu'une chose est provisoire, il conçoit des
  compensations — sa propre couche de chiffrement, un choix de ne pas stocker telle
  donnée, un avertissement d'interface — toutes fausses et toutes à retirer. Il doit
  pouvoir considérer que ce SDK **est** celui de NextGraph ;
- **la fabrique** — « polyfill », « portefeuille partagé », « multi-utilisateurs », la
  migration, ce que l'application supprimera un jour, les écarts par rapport à la cible ;
- **l'argumentaire** — ce que le modèle « permet », ce que telle règle « achète », la
  confidentialité composable. Un appelant a besoin de savoir qu'une référence rendue ne
  porte pas de clé, pas de savoir ce que ça lui apporte.

Ce qui entre : les **trois obligations de déploiement**, vérifiées dans le code — servir un
`.ngw` depuis son bundle et le passer à `configure`, être ouverte via la redirection du
broker, appeler `ensureIdentity()` dans un contexte navigateur avant de rendre — et trois
clauses contraignantes qui manquaient : l'identifiant rendu est **opaque**, le préfixe
`urn:ng-eventually:` est **réservé sur les sujets**, et le placement recommandé est un
document par entité métier, plusieurs objets dans un document restant permis.

`## Guarantees` devient une suite d'énoncés plats. `## Non-guarantees` ne liste que des
**absences de capacité** — pas de nom d'affichage, pas de révocation, rien par lecteur sur
un document en store public, pas d'écriture déléguée — jamais un manque par rapport à
autre chose.

L'application d'exemple n'affiche plus l'identifiant comme un nom : elle le montre pour ce
qu'il est, un identifiant technique. C'était exactement ce que la clause « opaque »
interdit, dans le fichier censé montrer le bon geste.

202 tests, typechecks propres, `lint` sans erreur. 148 → 135 lignes.
 2026-08-10 15:03:08 +02:00
Sylvain Duchesne 33b96fdc8d docs(concept): la règle interdit la divergence, elle ne la met plus en balance 
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.
 2026-08-10 14:51:17 +02:00
Sylvain Duchesne 7076c0cca8 fix: readUnion regroupe par sujet réel — la fusion était une divergence 
`readUnion` indexait par DOCUMENT une table nommée `bySubject`, créait ses entrées avec
`subject: doc`, et jetait le sujet réellement lu après s'en être servi pour écarter la
machinerie. Tout triplet non-machinerie d'un document tombait donc dans un sac unique
étiqueté par la référence du document : deux entités écrites sous deux sujets revenaient
**conflées**, une entité écrite sous un autre sujet revenait **ré-étiquetée**. Sans erreur,
sans trace.

**C'était une divergence, et c'est à ce titre qu'elle tombe.** NextGraph dit l'inverse aux
deux niveaux : une requête ancrée résout le graphe du repo comme graphe par défaut et rend
les sujets tels qu'ils sont ; et l'ORM porte sur chaque objet **deux** propriétés
distinctes, `@id` et `@graph`, dont il FABRIQUE la première quand on la laisse vide
(`graphIri + ":q:" + aléa`). Plusieurs objets par graphe est le cas prévu, et `@id` existe
pour les distinguer à l'intérieur d'un `@graph`.

La règle du projet reste **« un document séparé par entité métier »**, mais c'est une
recommandation de placement dictée par le modèle de sécurité — une clé est par repo, donc
l'isolation par entité exige un repo par entité. Ce n'est pas une contrainte que la lecture
a le droit d'imposer en rendant l'autre disposition invisible. Le contrat porte désormais la
recommandation, le code porte la capacité ; il faisait exactement l'inverse.

**La justification de l'épinglage était une erreur de catégorie**, et elle a été retirée
plutôt que contournée : `repo_graph_name` formate un nom de GRAPHE, il est estampillé sur
les quads et aucun sujet n'est réécrit. Deux confirmations indépendantes, dont la suite e2e
qui écrit un sujet puis le relit par correspondance exacte contre le vrai broker.

`UnionSubject.subject` passe de `Nuri` à `string` — un sujet RDF réel est un IRI
quelconque. `graph` reste `Nuri` et devient le champ à repasser au SDK ; l'app d'exemple
l'utilise à ses deux sites, où le sens était « le document ».

**Et la suite e2e ne comptait que les entrées.** C'est pour cela qu'elle est restée verte
pendant tout le défaut : compter ne distingue pas un regroupement par document d'un
regroupement par sujet. Elle écrit maintenant deux sujets dans le dernier document et
vérifie les trois choses qui comptent — quatre entrées pour trois documents, chaque entrée
portant le sujet sous lequel elle a été écrite, et son `graph` étant la référence du
document.

202 tests unitaires (5 ajoutés, dont 3 échouent si l'on restaure l'ancien repliage),
e2e 42/42 et applicatif 12/12.
 2026-08-10 14:50:07 +02:00
Sylvain Duchesne f378c71739 docs: sept affirmations sur NextGraph requalifiées à la source 
Lot F de la revue adverse. Chaque affirmation relue dans `nextgraph-rs` par symbole avant
d'être réécrite ; aucune ne s'est révélée exacte.

- `AddLink` / `RemoveLink` / `RepoLinkV0` étaient présentés comme **implémentés**. Leurs
  arms de vérificateur sont des `Ok(())`, là où celui d'`AddRepo` fait un vrai travail, et
  rien ne les construit. Le tableau dit désormais « déclaré, stubbé », et la conclusion qui
  en déduisait « le registre existe, seule la livraison manque » est corrigée : **les deux
  bouts** sont déclarés-et-stubbés.
- La table `inboxes` était dite « reconstruite vide à chaque session » — elle est
  repeuplée au chargement, et la clé privée d'inbox est persistée par repo. L'argument de
  sécurité qui s'appuyait dessus repose maintenant sur le bon motif : la table est **par
  vérificateur**, pas éphémère.
- La citation de « `doc_create` laisse `inbox: None` » pointait un constructeur réservé aux
  tests ; re-ciblée sur le chemin de production.
- `ExtObjectGet` était dit « le seul » primitif accessible à un non-membre et exigeant les
  clés : il y en a trois, et sa structure n'a aucun champ de clé.
- L'en-tête de `public-store.ts` était marqué **VERIFIED** alors qu'il repose sur un
  commentaire de doc, et la condition qu'il citait (« si les brokers pairs l'autorisent »)
  disparaissait de la conclusion. Requalifié en **pari**, condition rétablie.
- Deux sur-restrictions corrigées (ce qu'écrit le traitement d'un `ContactDetails`, et le
  prétendu « miroir 1:1 » de `NuriV0`, qui a dix champs).

**Sur la grammaire du ReadCap, une correction de MA correction.** J'avais écrit que la
forme `{target}:r:{cap}` était notre invention. Faux : le segment `r:` et son encodage sont
ceux d'amont, et l'auteur de NextGraph l'a énoncé. Ce qui est établi est plus étroit —
aucun parseur amont n'accepte aujourd'hui un NURI de repo qui le porte, et le segment est
produit comme valeur de champ. J'avais conclu d'une implémentation absente à ce que la
cible ferait, ce que la doctrine du projet interdit nommément. Seule « P1b remplace la
valeur, pas la forme » est corrigée, requalifiée en **pari**.

**Et la surface ne publie plus de type que personne n'utilise.** `export * from
"./model/types"` publiait huit types en bloc ; c'est une liste nommée de six. `ReadCap`
sort — aucune signature publiée ne le prend ni ne le rend, seules deux fonctions privées
de `inbox.ts` s'en servent — et `InboxScope` aussi. Un type n'est publié que si une
signature publiée l'utilise.

197 tests, 0 échec ; les trois typechecks propres ; `lint` sans erreur.
 2026-08-10 12:09:20 +02:00
Sylvain Duchesne cdc09a1a1d refactor(api): l'application ne nomme plus son identité — elle l'apprend 
Lot C de la revue adverse. Cinq corrections, dont une qui change la forme de la surface.

**L'application ne pouvait pas obtenir son identité par l'API.** `ensureIdentity()`
rendait `void`, `getCurrentUser` n'est plus publié — et pourtant `createEntityDoc(id, …)`
et `listMyEntityDocs(id, …)` l'exigeaient. L'app d'exemple s'en sortait en lisant
`localStorage["ng-eventually:identity"]` et le paramètre `?ng-id`, deux constantes
PRIVÉES du portail d'accès. Une frontière qu'aucun consommateur ne devrait voir, et
encore moins dont il devrait dépendre.

Vérifié au niveau 2 avant de trancher : `session_start(wallet_name, user_id)` prend
l'identité — donc en amont l'application la DÉTIENT, elle la tient du portefeuille
qu'elle a ouvert. Ici c'est le portail qui la choisit, donc c'est au portail de la
rendre. Deux changements, tous deux vers la cible :

- `ensureIdentity()` rend l'identité qu'il a établie ;
- `createEntityDoc(scope)`, `listMyEntityDocs(scope)`, `resolveWriteGraph(scope)`
  perdent leur paramètre d'identité. En amont `doc_create(session_id, …)` ne porte
  aucun utilisateur : une session EST celle d'un utilisateur. Passer la sienne à chaque
  appel de placement était un geste sans successeur.

L'application garde l'identité pour l'afficher, et ne la passe plus à rien.

**`inbox.share` provisionnait un destinataire inexistant.** Une faute de frappe créait
les trois stores et l'inbox de ce nom, et la clé atterrissait où personne ne regarde —
sans la moindre erreur. En amont on ne peut pas viser un nom qu'on invente : un dépôt est
scellé vers une clé d'inbox qui vous est parvenue par un contact entrant. Refuser est
fidèle ; provisionner était l'invention.

**`createEntityDoc` avalait l'échec de ses deux écritures** et rendait quand même une
référence — le document n'était dans aucun store, donc la session suivante ne le listait
pas et sa lecture rendait vide, en silence. Il lève maintenant, comme `doc_create` en
amont propage les siennes.

**Deux entrées prenaient `Nuri` au lieu de `NuriLike`** (`inbox.watch`,
`openDocumentInbox`), ce qui contredisait la raison même pour laquelle aucune garde de
type n'est publiée. Et **deux messages d'erreur nommaient des symboles retirés**
(`storeRegistry.documentInboxAddress`, `setCurrentUser`) : une erreur qui envoie vers une
fonction inexistante est pire qu'une erreur muette.

Contrat d'API et feuille `contract_sdk-surface` mis à jour ; `readForDocument` et le refus
de `share` obtiennent enfin leur règle en §9.

189 tests unitaires, e2e 40/40 et applicatif 12/12.
 2026-08-10 10:31:15 +02:00
Sylvain Duchesne 30f6263db5 docs(concept): le contrat entre le polyfill et l'application qui l'utilise 
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.
 2026-08-10 09:25:01 +02:00