docs: passer vision, readcap-and-nuri-model et l'incident en anglais

Le reste du dossier docs/ était déjà en anglais ; ces trois fichiers avaient été
rédigés en français par erreur. Traduction fidèle, sans changement de fond :
mêmes sections, mêmes tableaux, mêmes blocs de code. Le retour à la ligne dur à
78 colonnes est levé (une ligne par paragraphe, convention du projet).

Marqueurs épistémiques préservés et rendus aussi visibles : VERIFIED / INFERRED /
CORRECTED / DIRECTION / GAP. Les citations verbatim de commentaires amont restent
intactes.

Deux incohérences de FOND signalées par la traduction et corrigées ici — elles
étaient invisibles tant qu'on lisait chaque section isolément :

- readcap-and-nuri-model, section « Caveats / gaps » : elle listait encore le
  fetch keyless comme hypothèse INFÉRÉE à confirmer, alors que le bloc CORRIGÉ du
  §4bis la déclare fausse et non constructible. Contradiction interne née de ma
  correction partielle. Conservée barrée plutôt que supprimée : l'hypothèse est
  intuitive et se reformera sinon.
- incident write-loss : l'intro affirmait en fait établi que « l'écriture
  n'atteint jamais durablement le broker », alors que la réserve épistémique plus
  bas dit explicitement que l'alternative (perte d'écriture vs réhydratation à
  froid) n'est pas tranchée. L'intro ne rapporte plus que le symptôme observé.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014GbGgNEHRejVKoREvFuDFg
This commit is contained in:
Sylvain Duchesne
2026-07-28 15:51:22 +02:00
parent 518292498a
commit 0d52c82ba9
3 changed files with 135 additions and 285 deletions
+19 -48
View File
@@ -1,61 +1,32 @@
# Vision & principes du polyfill `@ng-eventually/client`
# Vision & principles of the `@ng-eventually/client` polyfill
## Raison d'être
## Purpose
Un **stand-in fidèle en FORME** des primitives futures de NextGraph. Objectif
**unique** : que les consommateurs (Festipod) soient **codés contre le modèle
mental CORRECT** — celui de NextGraph fini — et **n'aient RIEN à réécrire** quand
NextGraph fournira les vraies primitives.
A **stand-in faithful in SHAPE** to NextGraph's future primitives. **Single** objective: that consumers (Festipod) be **coded against the CORRECT mental model** — the one of finished NextGraph — and have **NOTHING to rewrite** when NextGraph provides the real primitives.
## Ce que le polyfill n'est PAS
## What the polyfill is NOT
Une couche de **sécurité**. Le **wallet partagé** (tout le monde partage les mêmes
clés) + l'absence de vraie crypto rendent l'émulation **infiniment moins
sécurisée** qu'un wallet-par-utilisateur — c'est un **véhicule de dev/staging**,
pas un but. **L'insécurité est ACCEPTÉE.** Un attaquant qui contourne l'émulation
n'est pas notre problème.
A **security** layer. The **shared wallet** (everyone shares the same keys) plus the absence of real crypto make the emulation **infinitely less secure** than a wallet-per-user — it is a **dev/staging vehicle**, not a goal. **Insecurity is ACCEPTED.** An attacker who bypasses the emulation is not our problem.
## Le seul critère : shape-fidelity, avec RIGUEUR
## The only criterion: shape-fidelity, with RIGOR
Les **surfaces exposées** doivent matcher **exactement la FORME** des primitives
futures, **même là où l'enforcement est simulé**. Le **mode d'échec à éviter** :
exposer la **mauvaise forme** → le consommateur code contre un modèle qui
n'existera pas → réécriture. L'inversion **ACL** des ReadCaps était exactement ce
défaut (une ACL là où le réel est **possession de clé**) — un manque de rigueur.
The **exposed surfaces** must match the **exact SHAPE** of the future primitives, **even where enforcement is simulated**. The **failure mode to avoid**: exposing the **wrong shape** → the consumer codes against a model that will not exist → rewrite. The **ACL** inversion of ReadCaps was exactly that defect (an ACL where the real thing is **key possession**) — a lack of rigor.
## Simuler la crypto pour EMPÊCHER les raccourcis
## Simulating crypto to PREVENT shortcuts
Sans un minimum de simulation crypto, des raccourcis préjudiciables sont pris (on
lit le clair, on retombe sur des ACLs). Le polyfill **simule** donc le mécanisme
final, assez pour tenir cet **invariant** :
Without a minimum of crypto simulation, damaging shortcuts get taken (reading the plaintext, falling back on ACLs). The polyfill therefore **simulates** the final mechanism, enough to hold this **invariant**:
> **Un `did` (id nu, SANS ReadCap) et un NURI (AVEC ReadCap) sont traités
> VRAIMENT différemment : le premier ne permet PAS de lire la donnée ; le second
> est SUFFISANT et REQUIS.**
> **A `did` (bare id, WITHOUT a ReadCap) and a NURI (WITH a ReadCap) are treated GENUINELY differently: the former does NOT allow reading the data; the latter is SUFFICIENT and REQUIRED.**
Concrètement : la donnée d'un document est **stockée chiffrée** (chiffrement
symétrique par-doc, même léger) ; le **ReadCap = la clé** ; sans elle, **impossible
de déchiffrer/lire**. Pas d'ACL, pas de clair accessible « à côté ». Obtenir la
lecture = **détenir la clé**, exactement comme en cible.
Concretely: a document's data is **stored encrypted** (per-doc symmetric encryption, however lightweight); the **ReadCap = the key**; without it, **decrypting/reading is impossible**. No ACL, no plaintext accessible "on the side". Obtaining read access = **holding the key**, exactly as in the target model.
## Conséquences de forme (à respecter partout)
## Shape consequences (to respect everywhere)
- **Tout est clés et URLs.** Il n'y a **pas** de notion d'appartenance, de rôle ni
de liste d'autorisation dans le modèle : uniquement de la cryptographie
symétrique et asymétrique, des URIs, et qui détient quelle clé. Toute forme
exposée qui ressemble à une ACL, un `member`, un `role` ou une `permission` est
une **mauvaise forme**, quel que soit l'échafaudage qu'on peut lire par ailleurs
dans l'état courant de NextGraph.
- **Lecture = possession de la clé de lecture** (ReadCap = `{id, clé}`). Un id nu
(un `did` sans ReadCap) ne lit pas.
- **Écriture = possession de la clé d'écriture** — une clé **distincte** de celle
de lecture, donc un axe distinct, mais **de la possession elle aussi**.
- **Partage d'un cap = le sceller à un destinataire** (livraison **durable**, au
moment du partage — PAS une ACL re-déclarée à chaque session).
- **Révocation = re-key** (nouvelle clé ; les anciens détenteurs gardent l'ancien
état). Non-rétroactif.
- **Référence cap-less** (nommer/pointer sans lire) **distincte** de la référence
cap-porteuse.
- **Everything is keys and URLs.** There is **no** notion of membership, role, or authorization list in the model: only symmetric and asymmetric cryptography, URIs, and who holds which key. Any exposed shape that looks like an ACL, a `member`, a `role`, or a `permission` is a **wrong shape**, whatever scaffolding one may otherwise read in the current state of NextGraph.
- **Reading = possession of the read key** (ReadCap = `{id, key}`). A bare id (a `did` without a ReadCap) does not read.
- **Writing = possession of the write key** — a key **distinct** from the read key, hence a distinct axis, but **possession too**.
- **Sharing a cap = sealing it to a recipient** (**durable** delivery, at share time — NOT an ACL re-declared every session).
- **Revocation = re-key** (new key; former holders keep the old state). Non-retroactive.
- **Cap-less reference** (naming/pointing without reading) **distinct** from the cap-bearing reference.
Voir `readcap-and-nuri-model.md` (le vrai modèle, vérifié dans `nextgraph-rs`) et
`briefs/2026-07-20-caps-emulation-alignment.md` (le chantier d'alignement).
See `readcap-and-nuri-model.md` (the real model, verified in `nextgraph-rs`) and `briefs/2026-07-20-caps-emulation-alignment.md` (the alignment effort).