chore(sync): strict common-v8 parity pass on Bun-first fork

.ai/knowledge/common-v8-parity-plan-2026-02-16.md

@@ -0,0 +1,90 @@
+# Common-v8 Parity Plan (Bun-first)
+
+## Goal
+
+Reach practical `upstream/common-v8` compatibility for architecture/API/behavior while keeping:
+
+- `bun` runtime and package manager
+- `biome` instead of eslint/prettier
+- reduced dependencies and Bun-native replacements where beneficial
+
+## Hard Rules
+
+- No wholesale merge of upstream branch.
+- No return of removed tooling (`pnpm`, `pnpx`, `eslint`, `prettier`).
+- Every upstream commit must be classified:
+  - `verified-equivalent`
+  - `pending-adopt`
+  - `intentional-divergence`
+- Any divergence must include reason + impact.
+
+## Verification Gates
+
+- `bunx tsc --build packages/common packages/web packages/react-native packages/nodejs`
+- `bunx vitest run` for targeted suites around touched areas
+- `bun run verify:fast`
+- `SYNC_GUARD_MAIN_REF=miccy-dev bun run sync:guard:common-v8:strict`
+
+## Upstream Commit Matrix (Current Snapshot)
+
+Source: `git cherry -v miccy-dev upstream/common-v8`
+
+| Upstream | Subject | Status | Local Note |
+|---|---|---|---|
+| `fc99998` | Add evoluError tab channel and error handling | `verified-equivalent` | Implemented via local worker/tab error flow (`EvoluTabOutput`, `InitTab`, shared `evoluError` store). |
+| `c3e32b0` | Update pnpm-lock.yaml | `intentional-divergence` | Bun lockfile is authoritative. |
+| `e62d12a` | Add microtask batch utility | `verified-equivalent` | Present in local fork (`microtask batch` utility + export). |
+| `31e07eb` | Implement mutation methods | `verified-equivalent` | `createEvolu` mutation dispatch/coalescing is implemented and covered; queue processing is serialized across microtasks. |
+| `da75834` | Rename worker module to Shared | `verified-equivalent` | `Shared.ts` is now present and exported; legacy `Worker.ts` stays as compatibility layer. |
+| `019ad76` | Add testCreateWorker and worker tests | `verified-equivalent` | Backported: `testCreateWorker`, `testCreateMessageChannel`, `testCreateMessagePort`, `testCreateSharedWorker` + `packages/common/test/Worker.test.ts`. |
+| `b90fae5` | Wire createEvolu to DB worker init | `verified-equivalent` | Local runtime already wires InitEvolu + DB worker init flow; covered by local-first Evolu tests. |
+| `d4fb5ba` | Wire platform DB workers and worker rename | `intentional-divergence` | Keep Bun-first Worker/DbWorker layout, but `local-first` now exports upstream `Db` contract and moves fork-only protocol under `Experimental*` aliases. |
+| `a986d23` | Add leader lock and worker init wiring | `verified-equivalent` | LeaderLock wiring is present across common/web/react-native runtime deps and tests. |
+| `cc87fde` | Add canonical test name constants | `verified-equivalent` | `testName`/`testAppName` present locally. |
+| `857608f` | Rename common test deps module | `verified-equivalent` | Test helper imports now converge on `_deps.ts`; `_deps.nodejs.ts` left as compatibility re-export shim. |
+| `d5e7e3c` | Add React Native leader lock tests | `verified-equivalent` | RN leader lock tests are present and green. |
+| `27a34ec` | Add web leader lock browser tests | `verified-equivalent` | Web leader lock browser tests are present and green. |
+| `cb1e7e0` | Use store-only worker console output | `verified-equivalent` | Worker bootstrap now uses `createWorkerRun` + store output forwarding path. |
+| `f05ec75` | Use Run<D> type for run.daemon | `verified-equivalent` | Already ported in local fork. |
+| `af7aca4` | Update TreeShaking.test.ts | `intentional-divergence` | Bun-first keeps normalized tree-shaking snapshot to stabilize cross-runtime size variance. |
+| `2cc6272` | Sort imports | `intentional-divergence` | Non-functional; handled by Biome formatting policy. |
+| `2a585dc` | Centralize deterministic test values | `verified-equivalent` | Already ported. |
+| `fb46547` | Use deterministic AppOwner in playground | `verified-equivalent` | Already ported. |
+| `fefc8e3` | Refactor db worker init flow | `verified-equivalent` | Stack ownership + daemon init flow is already present in local worker startup path. |
+| `db759d4` | Broker channel wiring + leader acquired output | `verified-equivalent` | Leader channel wiring and `LeaderAcquired` handling are implemented and regression-tested. |
+| `a2a448d` | Typed NativeMessagePort generics | `verified-equivalent` | Already ported. |
+| `746ea84` | Refactored local-first worker channel wiring | `verified-equivalent` | Already ported with Bun-first file layout. |
+| `0b390f6` | Clarified SharedWorker communication comment | `verified-equivalent` | Doc-level parity covered in local comments/docs. |
+| `0bbef0a` | Simplified worker deps + forwarded DbWorker console entries | `verified-equivalent` | Ported behavior; continue regression checks. |
+| `57d2390` | Wired DbWorker init payload and worker output flow | `verified-equivalent` | Ported with local worker protocol/wiring. |
+| `d4f0e5f` | Wired sqlite driver into React Native deps | `verified-equivalent` | Ported. |
+| `096326e` | Documented type aliases for composed deps | `intentional-divergence` | Upstream `apps/web` docs were removed from this fork; docs parity is tracked in `website/apps/docs`. |
+| `7f12041` | Refactored DB worker startup to initialize schema/bootstrap clock | `verified-equivalent` | `Db.ts` is now aligned with upstream startup/bootstrap flow (clock + schema init + quarantine reapply) with Bun-first cleanup only. |
+| `f94006d` | SQLite throw-first semantics + protocol/storage alignment | `verified-equivalent` | Ported in local fork (conflict-resolved variant). |
+| `1f7be0d` | Update pnpm-lock.yaml | `intentional-divergence` | Bun lockfile only. |
+| `af2e3f6` | Use getOk in SQLite setup paths | `verified-equivalent` | Ported. |
+| `717abb4` | Upgrade Biome to v2.4.0 and update config | `verified-equivalent` | Ported via local dependency/config update. |
+| `c089ae9` | Queue mutations, add quarantine, rename messages | `intentional-divergence` | Upstream `Db.ts`/`Shared.ts` queue+ack path is now aligned; local `Evolu.ts` keeps Bun-first direct `DbWorkerClient` queue path as internal runtime divergence. Public API remains compatible. |
+
+## Remaining Blocking Gaps
+
+No unresolved blocking gaps in the tracked `common-v8` matrix.
+
+Open divergence to track:
+
+1. `c089ae9` runtime path in `Evolu.ts` remains intentionally Bun-first (direct DbWorker client queue) instead of upstream SharedWorker mutation queue orchestration.
+
+## Execution Order
+
+1. Worker/runtime parity batch:
+   - `a986d23`, `fefc8e3`, `db759d4`, `b90fae5`, `d4fb5ba`, `857608f`, `d5e7e3c`, `27a34ec`, `cb1e7e0`
+2. Mutation queue/protocol batch:
+   - `31e07eb`, `c089ae9`
+3. DB startup/docs batch:
+   - `7f12041`, `019ad76`, `af7aca4`, `096326e`
+
+## Bun-native Replacement Opportunities (After Parity)
+
+- Keep `webpack` only where explicitly needed for compatibility snapshots (tree-shaking baseline).
+- Add optional Bun-native comparison path (`bun build --minify`) for internal perf tracking, not as baseline replacement.
+- Review and remove redundant Node-era tooling wrappers where Bun provides equivalent runtime/build/test behavior.

.ai/memory/user-preferences.md

@@ -9,3 +9,15 @@
 ## Specifika Projektu
 - **Aktuální stav**: 
 - **Kritické Todo**: 
+
+## Sync Pravidla (`upstream/common-v8` -> `evolu-plan-b`)
+- **Baseline**: `common-v8` je výchozí architektura/UX/API kompatibilita.
+- **Bez wholesale merge**: nikdy neprovádět slepé 1:1 mergnutí celé větve, které vrací odstraněné dependency/tooling.
+- **Bun-first/Biome-first**: zachovat `bun` + `biome`, nevracet `pnpm`, `pnpx`, `eslint`, `prettier` ani jejich workflow.
+- **Commit-parity workflow**: každou upstream změnu mapovat jako `adopt exact` / `equivalent` / `intentional divergence`.
+- **Povinný reporting odchylek předem**: pokud nebude něco implementováno nebo bude řešeno jinak, vždy předem uvést důvod, dopad a návrh.
+- **Performance & deps policy**: aktivně hledat náhrady 3rd-party knihoven nativními Bun funkcemi a hlásit je; preferovat méně závislostí a vyšší výkon.
+- **No chaos refactors**: nepřesouvat naming/soubory bez jasného přínosu (výkon, stabilita, kompatibilita).
+- **Keep local supersets**: pokud máme navíc oproti upstreamu (vyřešený issue, lepší implementace, funkce navíc), nikdy to nerevertovat, pokud je zachovaná upstream kompatibilita.
+- **Testy můžou být napřed**: aktivně přidávat/rozšiřovat test coverage i nad rámec upstreamu, pokud to zvyšuje jistotu kompatibility a stability.
+- **Escalation style**: při nalezení upstream chyby nebo lepší Bun varianty nejdřív zastavit a dodat stručný report: problém -> dopad -> návrh -> riziko.

.changeset/sqlite-refactor.md

@@ -5,11 +5,31 @@
 "@evolu/react-native": major
 ---
 
-Refactored createSqlite and CreateSqliteDriver to use Task
+Refactored SQLite integration to use Task and throw-first semantics
 
-- Changed `createSqlite` to `Task<Sqlite, SqliteError, CreateSqliteDriverDep>`
-- Changed `CreateSqliteDriver` to `Task<SqliteDriver, SqliteError>`
+- Changed `createSqlite` to `Task<Sqlite, never, CreateSqliteDriverDep>`
+- Changed `CreateSqliteDriver` to `Task<SqliteDriver>`
+- Removed `SqliteError` from SQLite driver/task APIs
+- Changed `Sqlite.exec` to return `SqliteExecResult` directly (no `Result<..., SqliteError>`)
+- Changed `Sqlite.transaction` to support callbacks returning either `Result<T, E>` or `void` (no `SqliteError` in the error channel)
+- Changed `Sqlite.export` to return `Uint8Array` directly (no `Result<..., SqliteError>`)
 - Simplified `SqliteDriver.exec` by removing the `isMutation` parameter — the driver now determines read vs write internally
 - Replaced `options.memory` and `options.encryptionKey` with a discriminated `options.mode` field (`"memory"` | `"encrypted"`)
-- Added 100% test coverage for better-sqlite3 and WASM SQLite drivers
 - Updated Expo and op-sqlite drivers to match the new API
+
+Why `SqliteError` was removed:
+
+- In Evolu, SQLite runs in-process. Failures are infrastructure-level and unrecoverable at the call site.
+- Wrapping these failures as `Result` values did not create meaningful recovery paths; callers still had to fail.
+- The correct behavior is to let such failures throw and surface them through platform `createRun` global handlers (web, nodejs, react-native), which report uncaught errors via Evolu `console.error`.
+- Evolu also propagates `console.error` entries through its messaging layer into the shared `evoluError` global store, so app-level error subscriptions still receive these failures.
+
+Boundary handling:
+
+- At protocol boundaries (for example Protocol ↔ Storage), error handling remains explicit.
+- Since storage implementations may throw, boundary code uses `try/catch`, logs with `console.error(error)`, and returns protocol-level outcomes.
+- Protocol handles all thrown errors as boundary concerns, without coupling to SQLite-specific error types.
+
+Developer experience:
+
+- This change reduces boilerplate (`if (!result.ok)` branches and `SqliteError` plumbing), making infrastructure code less verbose and easier to follow.

biome.json

@@ -30,6 +30,7 @@
         "noExplicitAny": "off",
         "noImplicitAnyLet": "off",
         "useIterableCallbackReturn": "off",
+        "noImportCycles": "error",
         "noThenProperty": "off",
         "noAssignInExpressions": "off"
       },
@@ -54,14 +55,7 @@
       "security": {
         "noDangerouslySetInnerHtml": "warn"
       },
-      "nursery": {
-        "noImportCycles": {
-          "level": "error",
-          "options": {
-            "ignoreTypes": true
-          }
-        }
-      }
+      "nursery": {}
     }
   },
   "javascript": {