PR: adding more Test coverage

.ai/knowledge/07-coverage-progress-2026-02-27.md

@@ -0,0 +1,94 @@
+# Coverage Progress (2026-02-27)
+
+## Context
+
+This note tracks the `P0+P1` coverage hardening wave on top of `origin/main`.
+The new file-level gates are implemented by `scripts/coverage-file-gate.mts` and root scripts:
+
+- `bun run coverage:gate:p0`
+- `bun run coverage:gate:p1`
+
+## Current Snapshot (from `bun run test:coverage` on branch `test-coverage`)
+
+### P0 target files (target: `>=90% statements` and `>=90% branches`)
+
+| File | Statements | Branches | Status |
+|---|---:|---:|---|
+| `packages/common/src/local-first/Sync.ts` | 96.83% | 90.83% | ✅ |
+| `packages/common/src/local-first/Db.ts` | 99.47% | 91.66% | ✅ |
+| `packages/common/src/local-first/Worker.ts` | 95.23% | 100.00% | ✅ |
+| `packages/web/src/local-first/DbWorker.ts` | 98.91% | 93.47% | ✅ |
+
+### P1 target files
+
+| File | Target | Current | Status |
+|---|---|---|---|
+| `packages/common/src/local-first/LocalAuth.ts` | `>=75 / >=60` | `100.00 / 94.11` | ✅ |
+| `packages/web/src/local-first/LocalAuth.ts` | `>=75 / >=60` | `100.00 / 92.30` | ✅ |
+| `packages/nodejs/src/Worker.ts` | `>=90 / >=85` | `100.00 / 100.00` | ✅ |
+| `packages/nodejs/src/Sqlite.ts` | `>=90 / >=85` | `100.00 / 93.75` | ✅ |
+
+Coverage gate status:
+
+- `bun run coverage:gate:p0` ✅
+- `bun run coverage:gate:p1` ✅
+
+## Recent Additions (latest wave)
+
+- Adapter/wrapper coverage:
+  - `packages/web/test/Evolu.test.ts`
+  - `packages/web/test/Worker.test.ts`
+  - `packages/react-web/test/local-first/Evolu.test.ts`
+  - `packages/nodejs/test/WebPlatform.test.ts`
+- Common helper/runtime branch coverage:
+  - `packages/common/test/local-first/Kysely.test.ts`
+  - `packages/common/test/local-first/Schema.test.ts` (index add/drop, `createQueryBuilder` options, `getEvoluSqliteSchema`)
+  - `packages/common/test/Error.test.ts` (`handleGlobalError` branches)
+  - `packages/common/test/String.test.ts` (new file)
+  - `packages/common/test/local-first/LocalAuth.test.ts` (mnemonic path, missing account, username fallback, unregister without fallback owner)
+  - `packages/web/test/LocalAuth.test.ts` (credential throw/missing userHandle/legacy metadata/create-null branches)
+  - `packages/common/test/local-first/Relay.test.ts` (zero-byte write path and mutex-abort propagation)
+- Small runtime hardening:
+  - `packages/common/src/String.ts` now guarantees `string` return even when `JSON.stringify` returns `undefined` (`symbol` case).
+
+## Runtime Adapter Hardening Wave (Relay + DbWorker)
+
+- `packages/nodejs/test/Relay.test.ts`
+  - Added deterministic websocket scenarios for `subscribe -> broadcast -> unsubscribe`.
+  - Added restart scenario with existing relay DB file.
+- `packages/web/test/DbWorker.test.ts`
+  - Added failure-race coverage where follower waits on failing shared `initPromise` and later recovery succeeds.
+- `packages/web/src/local-first/DbWorker.ts`
+  - Added optional test hook `createDriver` into `runWebDbWorkerPortWithOptions` for deterministic init-failure injection (runtime default unchanged).
+- `packages/nodejs/src/local-first/Relay.ts`
+  - Fixed WS message handling lifecycle to use daemon runner deps (`_run.daemon.addDeps(...)`) so callbacks are not aborted after `startRelay` returns.
+  - Kept runtime payload path simple and Bun/Node compatible (`Buffer.from(...)` for outbound binary sends).
+
+## Quick-Win Backlog (post P0/P1)
+
+Prioritized by risk + effort for next PR slices:
+
+1. `packages/web/src/Sqlite.ts` (`82.92% / 76.92%`, missing `3/13` branches)
+   - Remaining branches are OPFS init paths in main thread (`encrypted/default`) and warning fallback; deterministic coverage likely needs injectable sqlite-wasm facade.
+2. `packages/common/src/local-first/Protocol.ts` (`92.93% / 88.83%`, missing `24/215`)
+   - Slightly below 90 branch; higher complexity than the three items above.
+3. `packages/common/src/Console.ts` (`84.21% / 84.00%`, missing `8/50`)
+   - Moderate complexity; mostly branch-focused unit tests.
+4. `packages/common/src/local-first/Relay.ts` (`96.00% / 85.00%`, missing `3/20`)
+  - Small remaining branch gap after latest write-path additions.
+5. `packages/nodejs/src/local-first/Relay.ts` (`97.77% / 81.25%`, missing `3/16`)
+  - Remaining branch gap is now isolated in guarded branches around owner auth and ws event variants; can be closed with focused adapter tests.
+6. `packages/common/src/Type.ts` (`73.50% / 68.32%`, missing `121/382`)
+  - Big-impact but not a quick win; needs dedicated focused campaign.
+
+## Commit Trace (current head segment)
+
+- `308958f4` `fix(nodejs): use daemon runner for relay ws message handling`
+- `e61403e8` `test(web): cover shared initPromise failure cleanup`
+- `5e8ac520` `test(nodejs): cover relay subscribe and restart paths`
+- `67f34c74` `test(relay): cover zero-byte and mutex-abort write paths`
+- `69e3811d` `test(local-auth): expand common and web edge-case coverage`
+- `4ddb510c` `docs(ai): refresh coverage progress snapshot and quick-win backlog`
+- `71ce2289` `fix(common): guarantee string fallback in safelyStringifyUnknownValue`
+- `c18a4777` `test(common): expand schema and error branch coverage`
+- `6653d541` `test(common): fix Kysely test import ordering for Biome`

README.md

@@ -11,6 +11,73 @@ Primary goals:
 
 Evolu is a TypeScript library and local-first platform.
 
+## Integration Matrix
+
+Coverage snapshot date: `2026-02-27` (from `bun run test:coverage` and `bun run test:coverage:bun`).
+
+| Package | Supported Versions | Implementation Status | Coverage (Statements / Branches) | Notes |
+| --- | --- | --- | --- | --- |
+| `@evolu/common` | Node `>=24.0.0` | Stable core | `94.47% / 89.57%` | Main engine + local-first protocol/runtime. |
+| `@evolu/web` | `@evolu/common ^7.4.1` | Stable | `99.33% / 93.71%` | Browser runtime (Worker/SharedWorker/Web Locks path). |
+| `@evolu/nodejs` | Node `>=24.0.0`, `@evolu/common ^7.4.1` | Stable | `95.74% / 87.50%` | Includes relay adapter hardening (WS lifecycle + subscribe/broadcast/unsubscribe + restart coverage). |
+| `@evolu/react-web` | React `>=19`, React DOM `>=19`, `@evolu/web ^2.4.0` | Stable thin adapter | `100% / 100%` | Thin web integration wrapper. |
+| `@evolu/react-native` | React Native `>=0.81`, Expo `>=54`, `@op-engineering/op-sqlite >=12` | Active hardening | `20.65% / 13.11%` | Core adapters are covered; broader suite is backlog. |
+| `@evolu/react` | React `>=19` | Wrapper support | `0% / 0%` | Hook wrappers; coverage expansion planned. |
+| `@evolu/vue` | Vue `>=3.5.29` | Wrapper support | `0% / 0%` | Composition API wrappers; coverage expansion planned. |
+| `@evolu/svelte` | Svelte `>=5.53.3`, `@evolu/web ^2.4.0` | Wrapper support | `0% / 0%` | Store-based wrappers; coverage expansion planned. |
+| `@evolu/bun` (private) | `@evolu/common ^7.4.1`, Bun `1.3.x` | Experimental adapter | `100% / 100%` | Measured via Bun coverage runner on `BunDbWorker.ts`. |
+
+## Planned Integrations (Roadmap View)
+
+| Integration | Fit | Priority | Expected Path | Main Risk / Blocker |
+| --- | --- | --- | --- | --- |
+| Next.js (App Router) | Very high | P0 | Official `@evolu/react-web` guide + production example for Server/Client boundaries. | SSR/client boundary handling and Worker lifecycle in edge runtimes. |
+| TanStack Start | Very high | P0 | Use `@evolu/react` + `@evolu/web`, focus on SSR/client boundary docs and example app. | SSR edge cases (worker lifecycle and hydration boundary). |
+| Astro | High | P0 | Client-island integration on top of `@evolu/web`, starter template + docs. | Island hydration timing and worker boot ordering. |
+| SvelteKit | High | P1 | `@evolu/svelte` + `@evolu/web` reference app with SSR-aware browser-only init. | Avoiding server-side execution for browser worker primitives. |
+| Nuxt 3 | High | P1 | Vue composables + client-only plugin/module (`@evolu/vue` + `@evolu/web`). | Nitro/SSR split and client plugin ordering. |
+| Remix / React Router | High | P1 | React adapter with explicit browser init boundaries and route loader guidance. | Loader/action patterns can accidentally cross server/client boundary. |
+| Tauri | High | P1 | Web runtime in WebView + optional Rust-side relay bridge for desktop sync scenarios. | Packaging/runtime differences across desktop targets. |
+| Electron | High | P1 | Reuse web runtime in renderer + optional Node relay bridge in main process. | Multi-process lifecycle and secure IPC boundaries. |
+| Capacitor (Ionic) | Medium | P2 | Reuse web runtime in WebView first, then mobile storage/perf hardening. | Mobile WebView storage consistency and background lifecycle constraints. |
+| Flutter | Medium/Low | P2 | Separate adapter/SDK (likely not a thin wrapper) or protocol-level bridge. | Different runtime/language model (Dart), no direct reuse of TS hooks. |
+
+Current recommendation:
+
+- Build first-class examples for `Next.js`, `TanStack Start`, and `Astro`.
+- Follow with `SvelteKit`, `Nuxt`, `Remix`, and `Tauri/Electron` runtime guides.
+- Treat `Flutter` as a separate SDK/bridge effort, not a quick wrapper.
+- Keep protocol/API parity first; add adapters only where lifecycle/storage semantics are clear.
+
+## `@evolu/common` Compatibility and Third-Party Dependencies
+
+- Package version: `7.4.1`
+- Runtime baseline: Node `>=24.0.0`
+- Monorepo toolchain baseline: Bun `1.3.10`
+
+Third-party runtime dependencies used by `@evolu/common`:
+
+| Dependency | Why It Is Used |
+| --- | --- |
+| `@noble/ciphers` | Audited cryptographic ciphers for encryption flows. |
+| `@noble/hashes` | Audited hash primitives used by protocol/auth internals. |
+| `@scure/bip39` | Mnemonic handling for owner/account recovery flows. |
+| `disposablestack` | Disposable stack compatibility utility for cleanup semantics. |
+| `kysely` | Typed SQL query builder integration. |
+| `msgpackr` | Binary message serialization for protocol payloads. |
+| `zod` | Runtime schema validation and parsing. |
+
+Dependency policy:
+
+- No dependency downgrades in sync waves.
+- Sync waves are periodic coordinated dependency sync batches across packages and CI lanes.
+- Prefer native Bun/runtime APIs where practical.
+- Keep API/protocol compatibility with upstream.
+
+## Fork Diff vs Upstream
+
+For a concise overview of what this fork changes, why, and what is intentionally extra, see [UPSTREAM_DIFF.md](./UPSTREAM_DIFF.md).
+
 ## Documentation
 
 For detailed information and usage examples, please visit [evolu.dev](https://www.evolu.dev).
@@ -32,7 +99,7 @@ To chat with other community members, you can join the [Evolu Discord](https://d
 Evolu monorepo uses [Bun](https://bun.sh).
 
 > [!NOTE]
-> The Evolu monorepo is verified to run under **Bun 1.3.9** in combination with **Node.js >=24.0.0**. This compatibility is explicitly tested in CI.
+> The Evolu monorepo is verified to run under **Bun 1.3.10** in combination with **Node.js >=24.0.0**. This compatibility is explicitly tested in CI.
 
 Install dependencies:
 

UPSTREAM_DIFF.md

@@ -0,0 +1,35 @@
+# Evolu Plan B vs Upstream Evolu (High-Level)
+
+This document summarizes the main differences between `SQLoot/evolu-plan-b` and upstream `evoluhq/evolu`.
+
+Scope: high-level product and engineering deltas, not a full commit-by-commit changelog.
+
+## What Is Different
+
+| Area | Plan B Delta | Why |
+| --- | --- | --- |
+| Tooling baseline | Bun-first monorepo workflows (`bun install`, `bun run ...`) with Turborepo orchestration. | Faster local workflows and a single runtime/tooling story. |
+| Formatting and linting | Biome-first formatting/linting policy. | Reduce tooling complexity and keep style/lint fast and consistent. |
+| Upstream sync process | Added sync guard tooling and explicit compatibility tracking for `common-v8` sync waves. | Keep upstream parity while avoiding accidental regressions in fork-specific work. |
+| Coverage governance | Added file-level coverage gates for critical local-first paths (`Sync`, `Db`, `Worker`, `DbWorker`, etc.). | Enforce reliability on highest-risk runtime paths before merges. |
+| Bun runtime adapter | Added Bun-specific worker/db adapter package (`@evolu/bun`, currently private). | Native Bun runtime support and experimentation without changing upstream APIs. |
+| Test expansion | Extra tests for sync/worker/sqlite/refactor edge cases, including runtime adapter races (`DbWorker initPromise` cleanup, Relay WS lifecycle/broadcast flows). | Protect against regressions during aggressive sync and refactor work. |
+
+## What Is Intentionally the Same
+
+| Area | Compatibility Target |
+| --- | --- |
+| Public local-first API | Keep API compatibility with upstream where possible. |
+| Protocol and schema direction | Follow upstream `common-v8` refactor direction and naming. |
+| Core behavior | Preserve upstream semantics unless explicitly documented as fork-only behavior. |
+
+## What Is Extra in Plan B
+
+- Integration coverage dashboards/gates in fork workflow.
+- Bun-focused adapter experiments and tests.
+- SQLoot-specific maintenance/docs structure for sync operations.
+
+## Non-Goals
+
+- This fork is not intended to fragment protocol behavior from upstream.
+- This file is not a replacement for release notes.