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

[miccy]

Summary

• align packages/common/src/local-first/Db.ts and packages/common/src/local-first/Shared.ts with upstream common-v8 worker orchestration flow
• keep Bun-first runtime/tooling (bun, biome) and avoid reintroducing pnpm/eslint/prettier
• keep fork-only protocol surface behind explicit Experimental* aliases while preserving upstream Db exports
• add upstream ancestry marker commit (merge -s ours upstream/common-v8) so next sync wave has explicit merge base
• update parity tracking doc (.ai/knowledge/common-v8-parity-plan-2026-02-16.md)

Validation

• bun run verify:fast
• bunx vitest run packages/common/test/local-first/Shared.test.ts packages/common/test/local-first/Worker.test.ts packages/common/test/local-first/Evolu.test.ts
• bunx vitest run packages/web/test/DbWorker.test.ts
• bun test ./packages/bun/test/BunDbWorker.test.ts

Notes

• intentional divergence remains in packages/common/src/local-first/Evolu.ts runtime queue path (Bun-first direct DbWorkerClient queue), API-compatible with upstream common-v8.

Summary by CodeRabbit

• New Features

  • Added platform-agnostic shared worker implementation for coordinating multi-tab communication.
  • Introduced enhanced worker and message port testing utilities.
  • Added console-level tracking and forwarding across worker boundaries.

• API Changes

  • Simplified SQLite execution API to return results directly; errors now surface via exceptions.
  • Refactored storage operations to return concrete values instead of wrapped results.
  • Updated mutation queue processing with improved serialization and retry logic.

• Bug Fixes

  • Improved error handling with explicit console logging at protocol and storage boundaries.
  • Enhanced database schema validation and quarantine message handling.

• Tests

  • Added comprehensive worker lifecycle and message channel testing.
  • Expanded SQLite and storage integration test coverage.

[coderabbitai]

📝 Walkthrough

Walkthrough

This pull request implements a comprehensive refactoring to remove SqliteError from public APIs and transition to throw-first error semantics. It introduces generic type parameters to message ports for better type safety, establishes a platform-agnostic Shared Worker implementation for coordinating worker communication, and significantly simplifies storage and database interfaces by eliminating Result-wrapped returns in favor of direct values. The changes span configuration, type definitions, test infrastructure, and implementation across multiple packages.

Changes

Cohort / File(s)	Summary
SQLite API Refactoring packages/common/src/Sqlite.ts, packages/nodejs/src/local-first/Relay.ts	Removes SqliteError from public exports and changes method signatures: exec, export return direct values instead of Result wrappers; transaction introduces new SqliteTransaction interface supporting both generic and void callback forms; createSqlite removes SqliteError from Task error channel. Simplifies driver initialization by using getOk() helper instead of explicit result checks.
Storage Interface Simplification packages/common/src/local-first/Storage.ts, packages/common/src/local-first/Relay.ts	Eliminates nullable returns and Result wrappers: getSize, fingerprint, fingerprintRanges, findLowerBound return non-nullable values; setWriteKey, deleteOwner return void; writeMessages removes StorageWriteError; readDbChange returns non-nullable EncryptedDbChange. Removes StorageWriteError type entirely. Simplifies base storage factory from curried config pattern to no-config initialization.
Error Handling Consolidation packages/common/src/local-first/Error.ts, packages/common/src/local-first/Sync.ts, packages/common/src/local-first/Query.ts, packages/common/src/local-first/Schema.ts	Removes SqliteError from EvoluError union and related imports. Updates function returns from Result<T, SqliteError> to direct values or void (e.g., loadQueries, getDbSchema, ensureDbSchema, clock/sync functions). Consolidates error paths to rely on exceptions rather than error channel propagation.
Message Port Type Generics packages/common/src/Worker.ts, packages/nodejs/src/Worker.ts, packages/react-native/src/Worker.ts, packages/web/src/Worker.ts	Introduces generic Input/Output type parameters to NativeMessagePort, MessagePort, and related abstractions. Updates CreateMessagePort signature to accept typed ports. Adds public testing utilities: testCreateWorker, testCreateSharedWorker, testCreateMessageChannel, testCreateMessagePort with in-memory implementations.
Worker Communication and Console Handling packages/common/src/local-first/Worker.ts, packages/common/src/local-first/Evolu.ts, packages/common/src/local-first/Protocol.ts	Integrates ConsoleLevel and console store output routing into worker initialization. Updates EvoluWorkerInput message shape to use port1/port2 instead of port/brokerPort; includes consoleLevel in InitTab. Refactors mutation queue processing with re-entrancy guards and consolidates error handling to include ConsoleDep in protocol paths.
Shared Worker Implementation packages/common/src/local-first/Shared.ts	Introduces platform-agnostic initSharedWorker function with types for SharedWorkerInput, EvoluInput, EvoluTabOutput. Coordinates tab-level console ports, per-Evolu mutation queues, leader election, and console store subscriptions. Implements retry/backoff for mutation processing and console output queuing until tab connection.
DB Worker Initialization packages/common/src/local-first/Db.ts, packages/common/src/local-first/index.ts, packages/bun/src/BunDbWorker.ts, packages/web/src/local-first/DbWorker.ts	Adds worker-based DB initialization with initDbWorker, DbWorkerInput, and related types. Introduces schema bootstrapping, quarantine handling, and column change validation. Aliases DbWorkerInput/Output types to ExperimentalDbWorkerInput/Output in public exports; updates web worker to accept optional consoleLevel in port config.
Result Helper Utilities packages/common/src/Result.ts, packages/common/test/Result.test.ts	Adds public getOk(result) helper that extracts Ok values from Result<T, never> with assertion. Includes documentation updates reflecting error type changes. Tests verify value extraction and type-level constraints.
Type Aliases and Backward Compatibility packages/common/src/Type.ts, packages/react-native/src/exports/*.ts, packages/react-native/src/shared.ts	Adds deprecated aliases: Name and NameError for SimpleName and SimpleNameError. Introduces CreateSqliteDriverDep to React Native shared dependencies; wires createOpSqliteDriver and createExpoSqliteDriver into platform-specific initializers.
Test Infrastructure Refactor packages/common/test/_deps.ts, packages/common/test/_deps.nodejs.ts, packages/common/test/Worker.test.ts, packages/common/test/local-first/*.test.ts, packages/web/test/*.ts	Consolidates test helpers into _deps.ts with testCreateRunWithSqlite and testCreateRunWithSqliteAndRelayStorage factories. Removes intermediate Result unwrapping (.ok / .value) throughout test assertions; accesses rows/changes directly. Adds comprehensive Worker/SharedWorker/MessageChannel tests. Updates test imports from _deps.nodejs.js to _deps.js.
Configuration and Policy .ai/knowledge/common-v8-parity-plan-2026-02-16.md, .ai/memory/user-preferences.md, biome.json, .changeset/sqlite-refactor.md	Adds upstream parity plan and sync rules documentation. Moves noImportCycles from nursery to suspicious rules in Biome. Introduces changeset describing SQLite refactoring rationale and API surface changes.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Poem

🐰 With throws where errors once were tied,
And ports now typed both far and wide,
The workers dance through channels new,
While SQLite sheds its wrapper too.
Shared workers bring the harmony,
Console logs flow wild and free! 🎪

---

Note

🎁 Summarized by CodeRabbit Free

The PR author is not assigned a seat. To perform a comprehensive line-by-line review, please assign a seat to the pull request author through the subscription management page by visiting https://app.coderabbit.ai/login.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

This PR performs a strict parity alignment pass against upstream/common-v8 for the local-first worker/DB orchestration flow, while preserving the fork’s Bun-first + Biome-first constraints and keeping fork-only protocol surface behind Experimental* aliases.

Changes:

• Refactors SQLite + storage APIs to “throw-first” semantics (removing SqliteError from most result channels) and updates call sites/tests accordingly.
• Introduces/aligns worker orchestration pieces (Shared.ts, worker console forwarding, typed NativeMessagePort generics) and expands worker-related test utilities/coverage.
• Adjusts public exports to preserve upstream Db exports while moving DbWorkerProtocol surface behind Experimental* aliases; updates dependents and lock/config/docs.

Reviewed changes

Copilot reviewed 47 out of 48 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
packages/web/test/Sqlite.test.ts	Updates tests for new throw-first SQLite exec/export return shapes.
packages/web/test/DbWorker.test.ts	Switches to ExperimentalDbWorker* protocol type aliases.
packages/web/src/local-first/Worker.worker.ts	Updates web worker bootstrap to use createWorkerRun + injected runDbWorkerPort.
packages/web/src/local-first/DbWorker.ts	Aligns web DB worker wiring with experimental protocol + console level plumb-through.
packages/web/src/Worker.ts	Tightens NativeMessagePort generic typing in wrapper.
packages/react-native/src/shared.ts	Requires createSqliteDriver dep for RN createEvoluDeps.
packages/react-native/src/exports/expo-sqlite.ts	Wires Expo sqlite driver into deps creation.
packages/react-native/src/exports/bare-op-sqlite.ts	Wires op-sqlite driver into deps creation.
packages/react-native/src/Worker.ts	Tightens NativeMessagePort generic typing in RN worker shims.
packages/nodejs/test/Sqlite.test.ts	Updates tests for new throw-first SQLite exec/export return shapes.
packages/nodejs/src/local-first/Relay.ts	Updates relay startup/storage init for throw-first SQLite and getOk usage.
packages/nodejs/src/Worker.ts	Tightens NativeMessagePort generic typing in wrapper.
packages/common/test/local-first/_utils.ts	Updates schema + exec handling for throw-first SQLite results.
packages/common/test/local-first/Worker.test.ts	Expands worker tests for console forwarding + updated InitTab/InitEvolu wiring.
packages/common/test/local-first/Storage.test.ts	Updates storage tests for new return types and simplified storage config.
packages/common/test/local-first/Shared.test.ts	Adds comprehensive tests for new initSharedWorker behavior.
packages/common/test/local-first/Schema.test.ts	Updates schema tests for new return types (getDbSchema, ensureDbSchema).
packages/common/test/local-first/Relay.test.ts	Updates relay storage tests for throw-first SQLite results and void-return APIs.
packages/common/test/local-first/Protocol.test.ts	Updates protocol tests for console dep and non-nullable joins.
packages/common/test/local-first/Evolu.test.ts	Adds mutation queue serialization test + updates InitEvolu channel payload.
packages/common/test/_deps.ts	Consolidates common test deps helpers (sqlite + relay storage) into one module.
packages/common/test/_deps.nodejs.ts	Keeps backward-compatible re-export shim to _deps.ts.
packages/common/test/Worker.test.ts	Adds tests for new in-memory worker/message channel test utilities.
packages/common/test/Sqlite.test.ts	Refactors transaction/export tests for throw-first semantics.
packages/common/test/Result.test.ts	Adds tests for new getOk and getOrNull.
packages/common/src/local-first/index.ts	Re-exports shared worker module and introduces ExperimentalDbWorker* aliases.
packages/common/src/local-first/Worker.ts	Adds console level plumbing + console store forwarding to tabs.
packages/common/src/local-first/Sync.ts	Refactors sync/storage flow to throw-first SQLite with explicit boundary handling.
packages/common/src/local-first/Storage.ts	Converts many storage ops from Result/null to throw/void and adjusts API contracts.
packages/common/src/local-first/Shared.ts	Adds platform-agnostic SharedWorker orchestration with mutation queue + retry/ack.
packages/common/src/local-first/Schema.ts	Converts schema helpers to throw-first, improves typing for schema validation.
packages/common/src/local-first/Relay.ts	Refactors relay sqlite storage to throw-first base storage and simplified error surface.
packages/common/src/local-first/Query.ts	Refactors query loading to return values directly (no Result).
packages/common/src/local-first/Protocol.ts	Adds console dep and guards around throw-capable storage operations.
packages/common/src/local-first/Evolu.ts	Updates worker init payload (console level, ports) + mutation queue serialization.
packages/common/src/local-first/Error.ts	Removes SqliteError from EvoluError union.
packages/common/src/local-first/Db.ts	Adds upstream-parity DB worker definitions and bootstrap/init flow.
packages/common/src/Worker.ts	Adds typed NativeMessagePort generics + in-memory worker/message test utilities.
packages/common/src/Type.ts	Adds deprecated Name alias for upstream parity.
packages/common/src/Sqlite.ts	Implements throw-first exec/export and overload-based transaction API.
packages/common/src/Result.ts	Adds getOk helper and updates docs/examples accordingly.
packages/bun/test/BunDbWorker.test.ts	Switches Bun DB worker tests to experimental protocol type aliases.
packages/bun/src/BunDbWorker.ts	Switches Bun DB worker implementation to experimental protocol type aliases.
bun.lock	Updates pinned tooling versions (Biome, Turbo, etc.).
biome.json	Updates schema version and promotes noImportCycles rule configuration.
.changeset/sqlite-refactor.md	Documents major SQLite API refactor and boundary handling rationale.
.ai/memory/user-preferences.md	Updates parity sync rules documentation.
.ai/knowledge/common-v8-parity-plan-2026-02-16.md	Adds parity tracking plan and status matrix snapshot.

[Copilot]

@miccy I've opened a new pull request, #40, to work on those changes. Once the pull request is ready, I'll request review from you.