From dbd99738f080afc31a63a32e72d0d918af3aab9b Mon Sep 17 00:00:00 2001 From: Sylvain Duchesne Date: Wed, 12 Aug 2026 18:32:23 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20deux=20affirmations=20que=20les=20mesur?= =?UTF-8?q?es=20ont=20d=C3=A9menties?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit La doctrine disait que la suite applicative ne peut pas être mesurée sur une machine dont le réseau bouge. Elle vient de passer 27/27 quatre fois d'affilée sous exactement ce bruit. Ce qui tranche n'est donc pas l'état de la machine mais la FORME de l'échec — un délai nommé sur une opération broker désigne le transport, une assertion qui rend une valeur inattendue désigne le code — et la répétition. Et la feuille sur le règlement de l'identité décrivait encore la session comme un thunk fourni par l'application. Elle appartient désormais au paquet, dont le wrapper init() capture l'événement : plus aucune application ne peut la câbler de travers, ce qui était pourtant la cause exacte de la régression racontée juste au-dessus. Dette de doc soldée. --- .project/concepts/app-contract/_debt.md | 10 ---------- .project/concepts/e2e-harness/_debt.md | 7 ------- .../e2e-harness/caveat_a-dropped-pipe-kills-a-run.md | 8 +++++--- .project/concepts/sign-in/_debt.md | 11 ----------- .../sign-in/knowledge_settling-is-not-connecting.md | 6 +++--- 5 files changed, 8 insertions(+), 34 deletions(-) delete mode 100644 .project/concepts/app-contract/_debt.md delete mode 100644 .project/concepts/e2e-harness/_debt.md delete mode 100644 .project/concepts/sign-in/_debt.md diff --git a/.project/concepts/app-contract/_debt.md b/.project/concepts/app-contract/_debt.md deleted file mode 100644 index 6b6fed8..0000000 --- a/.project/concepts/app-contract/_debt.md +++ /dev/null @@ -1,10 +0,0 @@ -# Doc-debt — app-contract - -> Presence of a block = doc to update. Processed → delete the block; no blocks left → delete this file. -> One block = one "big change": `why` + `files` + `verify` (leaves to review). - -## Raw markers (consolidate into blocks, then delete) -- TOUCHED packages/polyfill/src/surface/lifecycle.ts @2026-08-12 (session f93872b5-293a-4916-a353-181409a96d42) -- TOUCHED packages/polyfill/src/index.ts @2026-08-12 (session f93872b5-293a-4916-a353-181409a96d42) -- TOUCHED examples/notebook/app.ts @2026-08-12 (session f93872b5-293a-4916-a353-181409a96d42) -- TOUCHED docs/api-contract.md @2026-08-12 (session f93872b5-293a-4916-a353-181409a96d42) diff --git a/.project/concepts/e2e-harness/_debt.md b/.project/concepts/e2e-harness/_debt.md deleted file mode 100644 index e5f6c3a..0000000 --- a/.project/concepts/e2e-harness/_debt.md +++ /dev/null @@ -1,7 +0,0 @@ -# Doc-debt — e2e-harness - -> Presence of a block = doc to update. Processed → delete the block; no blocks left → delete this file. -> One block = one "big change": `why` + `files` + `verify` (leaves to review). - -## Raw markers (consolidate into blocks, then delete) -- TOUCHED packages/polyfill/e2e/polyfill-entry.ts @2026-08-12 (session f93872b5-293a-4916-a353-181409a96d42) diff --git a/.project/concepts/e2e-harness/caveat_a-dropped-pipe-kills-a-run.md b/.project/concepts/e2e-harness/caveat_a-dropped-pipe-kills-a-run.md index cd61866..b90aaed 100644 --- a/.project/concepts/e2e-harness/caveat_a-dropped-pipe-kills-a-run.md +++ b/.project/concepts/e2e-harness/caveat_a-dropped-pipe-kills-a-run.md @@ -16,8 +16,10 @@ Before waits were bounded this was fatal in a specific way: the suite blocked in ## The host can be the cause too -A machine that reconfigures its network — a container in a crash-restart loop cycling its virtual interface, for instance — makes the applicative suite unmeasurable. The browser answers with a network-changed error, broker sockets fail, and every failure looks like a different product bug. +A machine that reconfigures its network — a container in a crash-restart loop cycling its virtual interface, for instance — makes the applicative suite unreliable. The browser answers with a network-changed error, broker sockets fail, and every failure looks like a different product bug. -This has happened here: seven failures out of ten runs, all transport, none product. The check costs seconds — watch for repeated link events, and look for a container restarting. +This has happened here: seven failures out of ten runs in one afternoon, all transport, none product. The check costs seconds — watch for repeated link events, and look for a container restarting. -**The discipline that follows:** a suite that fails for transport reasons has measured nothing. Do not read it as a red baseline, do not chase it as a regression, and do not commit against it. Restore a stable environment first, then measure. +But do not conclude the suite is unmeasurable: under that same churn it also ran green four times in a row. A red run under a moving network proves nothing, and neither does a green one. What decides is the SHAPE of the failure — a named deadline on a browser or broker operation points at the transport, a failed assertion carrying an unexpected value points at the code — and repetition: three consecutive green runs, or a failure that reproduces. + +**The discipline that follows:** a suite that fails for transport reasons has measured nothing. Do not read it as a red baseline, do not chase it as a regression, and do not commit against it. Re-run it — and if the environment is known to be moving, say so alongside the result instead of letting a single run stand as the verdict. diff --git a/.project/concepts/sign-in/_debt.md b/.project/concepts/sign-in/_debt.md deleted file mode 100644 index 613973f..0000000 --- a/.project/concepts/sign-in/_debt.md +++ /dev/null @@ -1,11 +0,0 @@ -# Doc-debt — sign-in - -> Presence of a block = doc to update. Processed → delete the block; no blocks left → delete this file. -> One block = one "big change": `why` + `files` + `verify` (leaves to review). - -## Raw markers (consolidate into blocks, then delete) -- TOUCHED packages/polyfill/src/shared-wallet/session.ts @2026-08-12 (session f93872b5-293a-4916-a353-181409a96d42) -- TOUCHED packages/polyfill/src/shared-wallet/bootstrap.ts @2026-08-12 (session f93872b5-293a-4916-a353-181409a96d42) -- TOUCHED packages/polyfill/src/surface/lifecycle.ts @2026-08-12 (session f93872b5-293a-4916-a353-181409a96d42) -- TOUCHED packages/polyfill/src/shared-wallet/access-gate.ts @2026-08-12 (session f93872b5-293a-4916-a353-181409a96d42) -- TOUCHED packages/polyfill/src/shared-wallet/account-registry.ts @2026-08-12 (session f93872b5-293a-4916-a353-181409a96d42) diff --git a/.project/concepts/sign-in/knowledge_settling-is-not-connecting.md b/.project/concepts/sign-in/knowledge_settling-is-not-connecting.md index ba72aaf..7a952f8 100644 --- a/.project/concepts/sign-in/knowledge_settling-is-not-connecting.md +++ b/.project/concepts/sign-in/knowledge_settling-is-not-connecting.md @@ -16,7 +16,7 @@ They must stay apart, and the reason is not tidiness. `init()` starts the broker redirect as its first statement when the page is top-level, so anything the barrier needs to show must already be in place. The `barrier` must therefore appear **before** `init()`. -But an identity cannot connect before `init()` either: connecting reaches the application's session thunk, which only `init()`'s own callback resolves. Await the whole of sign-in before `init()` and it deadlocks; call it after and the `barrier` never appears. +But an identity cannot connect before `init()` either: connecting needs the session, which arrives only through `init()`'s callback. Await the whole of sign-in before `init()` and it deadlocks; call it after and the `barrier` never appears. The way out is that only *half* of it has that dependency. Settling is awaited by this package's `init()` wrapper before it delegates; connecting stays in the published call, awaited where a session exists. @@ -26,13 +26,13 @@ It does **not** cover calling the published sign-in strictly first and awaiting ## The failure this cost -Settling once reached the session, because recording who is acting also fired the connection. In the reference application `init()` is called *from inside the executor that builds the session promise*, so the thunk could not answer by construction. It threw, the account lookup answered null, and the connection run abandoned **without restoring or draining** — having already registered itself as in flight. The published call then joined that dead run and resolved having done nothing. +Settling once reached the session, because recording who is acting also fired the connection. At the time the session was assembled by the application: it built a promise around `init()`'s callback and handed the package a thunk reading it. The application called `init()` *from inside the executor building that promise*, so the thunk could not answer by construction. It threw, the account lookup answered null, and the connection run abandoned **without restoring or draining** — having already registered itself as in flight. The published call then joined that dead run and resolved having done nothing. Symptom: a document shared with someone did not open for them. No error, just unreadable content. Nothing had changed in the connection logic. What changed was *when* the identity was recorded. Before the split, nothing recorded an identity during module evaluation: a session existed, the run was healthy, and joining it was harmless. -Hence the shape of the fix — recording who acts and starting to connect are separate operations, and the session-free half only records. To validate: the session thunk must never be called while settling. +Hence the shape of the fix — recording who acts and starting to connect are separate operations, and the session-free half only records. The session is now the package's own — its `init()` wrapper captures the event — so no application can wire this wrong again. To validate: nothing reachable from settling asks for a session. ## The lesson worth keeping