docs: deux concepts pour ce que la journée a appris

sign-in — comment un utilisateur passe de rien à une identité qui agit. La barrière, l'identifiant qui franchit une frontière de partition par l'URL, et surtout : la redirection vers le broker appartient à @ng-org/web, vérifié dans son bundle. Le polyfill ne la réimplémente pas ; ce qui lui revient est la seule chose qu'init() ne peut pas faire, écrire l'identifiant dans l'URL avant qu'il ne la lise. La feuille centrale dit pourquoi régler l'identité et se connecter sont deux actes séparés : l'un ne demande aucune session, l'autre en exige une, et les confondre bloque dans un sens et casse le partage en silence dans l'autre. Le piège encore vivant — une connexion abandonnée qui reste joignable — est consigné comme tel, non corrigé. e2e-harness — ce que chaque suite juge, et deux choses qu'un agent doit savoir avant de diagnostiquer : le raccourci qui pré-injectait l'identifiant dans l'URL a tenu deux défauts invisibles pendant des mois (un lien de téléchargement vers un 404 que rien ne servait, et une barrière inatteignable pour tout nouvel arrivant) ; et un tuyau devtools qui lâche tue une exécution sans que Playwright n'émette d'événement, ce qui ressemble à un défaut produit et n'en est pas. Le vocabulaire gagne settle, barrier, journey et batch. J'avais aussi introduit « hand-over » pour la redirection : retiré, c'est le mot de NextGraph qui l'emporte.
2026-08-11 19:24:00 +02:00
parent 16e24f67f9
commit 7c2e8d8f1f
10 changed files with 234 additions and 10 deletions
@@ -0,0 +1,32 @@
+---
+type: overview
+summary: How a person gets from holding nothing to acting as an identity — the barrier, the broker hand-over, and the split between settling and connecting
+triggers:
+  keywords: [sign-in, signin, identity, ensureIdentity, settleIdentity, barrier, gate, wallet, broker, redirect, ng-id, currentUser, session]
+  paths:
+    - "packages/polyfill/src/shared-wallet/**"
+    - "packages/polyfill/src/surface/lifecycle.ts"
+    - "packages/polyfill/src/emulated-verifier/connect.ts"
+vocabulary:
+  - term: settle
+    gloss: decide which identity is acting, from the URL, storage, or the barrier — needs no session
+    not: [resolve identity, determine user, login]
+    see: knowledge_settling-is-not-connecting
+  - term: barrier
+    gloss: the full-screen overlay this package mounts to hand out the wallet and take an identifier
+    not: [modal, popup, login screen]
+---
+
+# sign-in — getting a person from nothing to acting
+
+This concept covers everything between "someone opens the application" and "an identity is acting with a live session": the `barrier` this package mounts, the wallet a newcomer must obtain, the broker redirect, and the two distinct acts — `settle` and connect — that were once conflated and must stay apart.
+
+None of it is app-facing. An application awaits one call and renders; it must never learn that a broker, an iframe or a redirect exist. What it may rely on lives in `app-contract`; what follows is how that promise is kept.
+
+The whole thing is scaffolding: upstream, a person opens **their** wallet, it contains **their** site, and `session_start` takes an id that came from the wallet. There is nothing to name and nothing to choose. This concept exists because one shared wallet hosts several identities.
+
+## Read first
+
+- `knowledge_how-a-user-gets-in` — the flow end to end, and which layer owns each step.
+- `knowledge_settling-is-not-connecting` — the split, and the cycle that forces it.
+- `caveat_connect-memoizes-an-abandoned-run` — a live trap, unfixed.