clone

a deno framework for local-first web apps that open instantly, work offline and sync when users choose

feat/fix-sync-enrollment-startup
lofi / docs / decisions / 0002-convergence-verdict.md
0002-convergence-verdict.md 4.3K rendered
1# Browser convergence: no upstream defect — the gate never elected sync23Date: 2026-07-18\4Decision: reject the "upstream convergence defect" diagnosis; fix the gate's preconditions; classify5`CatalogueWriteDenied` at boot as benign upstream console noise, not a sync failure67## Question89The browser convergence gate (`apps/reference/tests/convergence_e2e_test.ts`) failed with10`CatalogueWriteDenied` "identically against lofi-node and lofi's own managed dev server", and this11was recorded as an upstream jazz-tools alpha.53 defect (lofi-node `docs/hosting-lofi-apps.md`12validation status; #123 items B1/B3/C1; the homepage caveat in #122 §1). Is it actually upstream,13and what is the minimal reproduction?1415## Contract IDs1617DX-LOCAL-01 and DX-OFFLINE-01 surround the behavior; the affected claim is the documented18"known-broken two-browser reconciliation" status itself, which gated homepage copy (#122 §1).1920## Exact versions2122`jazz-tools@2.0.0-alpha.53` / `jazz-napi@2.0.0-alpha.53`, lofi main at the A3-phase-2 merge,23lofi-node main at the docs-adoption merge, Playwright Chromium (pinned 1.61.1 install).2425## Control2627Headless two-client convergence (`jazz-tools` `createDb` clients, same account, concurrent offline28edits) against lofi-node — passing throughout (lofi-node `tests/convergence_test.ts`).2930## Procedure3132Instrumented probe (per-client console capture, CDP WebSocket frames, per-direction convergence33checks with independent timeouts), run in four configurations: dev server without managed config;34managed server with deployed schema but no sync election; managed server with the real35backup-and-sync election performed through the account UI before identity cloning; the same against36a lofi-node backend with the schema deployed through its admin path.3738## Evidence39401. Both clients — including the first, alone, at boot, before any offline edit — log41 `CatalogueWriteDenied` (`sync_manager/inbox.rs:1401`) for the same content-addressed object id on42 every server and store, deployed schema or not. The denial is not correlated with the second43 client or with reconnection.442. Without election, neither client held any `lofi:` state: no `sync-elected`, no managed namespace.45 Both ran local-only — lofi's own documented first-boot contract — so non-convergence was the46 designed outcome, identical against every server. The historical "controlled experiment" compared47 two non-syncing runs; its parity conclusion was vacuous.483. With the election performed (virtual authenticator, the real two-step phrase ceremony), the49 identical scenario converges in all four directions in ~1s — online-only and offline-reconnect —50 against both the first-party managed server and lofi-node. The `CatalogueWriteDenied` warning51 still appears once per client at boot while sync works, proving it benign.524. A second latent failure hid the first: the documented invocation used `127.0.0.1`, where the53 election ceremony cannot start because an IP address is not a valid WebAuthn RP ID. On54 `localhost` the ceremony works.5556## Decision5758- The gate now performs the backup-and-sync election in `preparePrimary` before identity cloning,59 and its instructions require `localhost`. It passes against both servers.60- B1 (distill an upstream repro) resolves as **not upstream** for convergence. The remaining61 upstream observation is cosmetic: every browser client attempts one unauthorized catalogue write62 at boot and logs a WARN — worth an upstream polish report, not a standing defect issue.63- B3 (standing upstream issue for "browser reconnect denial") is **not filed**: its condition — a64 verifiable upstream defect — does not exist.65- C1 (expected-fail canary) is moot in its planned form; the fixed gate is the assurance artifact.6667## Contract delta6869"Two real browser clients reconciling after offline edits" moves from known-broken to validated70against both servers. The lofi-node validation-status claim and the #122 §1 homepage constraint ("do71not re-point this copy until the upstream fix lands") are both superseded — the scenario the72homepage describes works and can be claimed truthfully.7374## Follow-up7576lofi-node `docs/hosting-lofi-apps.md` validation status rewritten (companion PR); #122 §1 unblocks;77optional: promote the convergence scenario into the golden suite for continuous coverage, and an78upstream courtesy report for the boot-time catalogue-write warning.