PR: Cherry-pick common-v8 from upstream

.ai/knowledge/02-dependencies.md

@@ -22,7 +22,7 @@ bunx <package>       # Execute packages
 
 ### Development
 - **Turbo** 2.8.1 - Monorepo build orchestration
-- **Biome** 2.3.13 - Linting and formatting
+- **Biome** 2.3.14 - Linting and formatting
 - **Vitest** ^4.0.18 - Testing framework
 - **TypeDoc** ^0.28.16 - API documentation
 

.ai/tasks/archive/cherry-pick-common-v8-SUPERSEDED.md

@@ -22,7 +22,7 @@ Migrating changes from `upstream/common-v8` to our fork, while preserving our st
 | Tool    | Before | After  | Status           |
 | ------- | ------ | ------ | ---------------- |
 | Bun     | 1.3.6  | 1.3.8  | ✅ Done           |
-| Biome   | 2.3.13 | 2.3.13 | ✅ Current        |
+| Biome   | 2.3.14 | 2.3.14 | ✅ Current        |
 | Turbo   | 2.8.1  | 2.8.1  | ✅ Current        |
 | Node.js | >=24   | >=24   | ✅ LTS 24 correct |
 

.changeset/create-query-builder.md

@@ -0,0 +1,16 @@
+---
+"@evolu/common": major
+---
+
+Replaced `evolu.createQuery` with standalone `createQueryBuilder` function
+
+Queries are now created using a standalone `createQueryBuilder` function instead of `evolu.createQuery` method. This enables query creation without an Evolu instance, improving code organization and enabling schema-first development.
+
+```ts
+// Before
+const todosQuery = evolu.createQuery((db) => db.selectFrom("todo").selectAll());
+
+// After
+const createQuery = createQueryBuilder(Schema);
+const todosQuery = createQuery((db) => db.selectFrom("todo").selectAll());
+```

.github/copilot-instructions.md

@@ -71,11 +71,6 @@ apps/
 
 Follow these specific conventions and patterns:
 
-## Test-driven development
-
-- Write a failing test before implementing a new feature or fixing a bug
-- Keep test code cleaner than production code — good tests let you refactor production code; nothing protects messy tests
-
 ## Code organization & imports
 
 - **Use named imports only** - avoid default exports and namespace imports
@@ -498,6 +493,68 @@ const processTask: Task<void, ParseError | TimeoutError> = async (run) => {
 const result = await sleep("1s")(run);
 ```
 
+## Test-driven development
+
+- Write a failing test before implementing a new feature or fixing a bug
+- Run tests using the `runTests` tool with the test file path
+- Test files are in `packages/*/test/*.test.ts`
+- Use `testNames` parameter to run specific tests by name
+- Run related tests after making code changes to verify correctness
+
+### Test structure
+
+- Use `describe` blocks to group related tests by feature or function
+- Use `test` or `it` for individual test cases (both are equivalent)
+- Test names should be descriptive phrases: `"returns true for non-empty array"`
+- Use nested `describe` for sub-categories
+
+```ts
+import { describe, expect, expectTypeOf, test } from "vitest";
+
+describe("arrayFrom", () => {
+  test("creates array from iterable", () => {
+    const result = arrayFrom(new Set([1, 2, 3]));
+    expect(result).toEqual([1, 2, 3]);
+  });
+
+  test("returns input unchanged if already an array", () => {
+    const input = [1, 2, 3];
+    const result = arrayFrom(input);
+    expect(result).toBe(input);
+  });
+});
+```
+
+### Type testing
+
+Use `expectTypeOf` from Vitest for compile-time type assertions:
+
+```ts
+import { expectTypeOf } from "vitest";
+
+test("returns readonly array", () => {
+  const result = arrayFrom(2, () => "x");
+  expectTypeOf(result).toEqualTypeOf<ReadonlyArray<string>>();
+});
+
+test("NonEmptyArray requires at least one element", () => {
+  const _valid: NonEmptyArray<number> = [1, 2, 3];
+  // @ts-expect-error - empty array is not a valid NonEmptyArray
+  const _invalid: NonEmptyArray<number> = [];
+});
+```
+
+### Inline snapshots
+
+Use `toMatchInlineSnapshot` for readable test output directly in the test file:
+
+```ts
+test("Buffer", () => {
+  const buffer = createBuffer([1, 2, 3]);
+  expect(buffer.unwrap()).toMatchInlineSnapshot(`uint8:[1,2,3]`);
+});
+```
+
 ## Testing
 
 - **Create deps per test** - use `testCreateDeps()` from `@evolu/common` for test isolation
@@ -564,18 +621,6 @@ bun run test --filter @evolu/common -- -t "yields and returns ok"
 - **No prefixes** - avoid `feat:`, `fix:`, `feature:` etc.
 - **Be descriptive** - explain what the change does
 
-```bash
-# Good
-Add support for custom error formatters
-Fix memory leak in WebSocket reconnection
-Update schema validation to handle edge cases
-
-# Avoid
-feat: add support for custom error formatters
-fix: memory leak in websocket reconnection
-Update schema validation to handle edge cases.
-```
-
 ## Changesets
 
 - **Write in past tense** - describe what was done, not what will be done

AGENTS.md

@@ -12,13 +12,13 @@
 
 ## 📊 Quick Context
 
-| Aspect | Value |
-|--------|-------|
-| Package Manager | Bun 1.3.8 |
-| Node.js | >=24.0.0 |
-| Linter/Formatter | Biome 2.3.13 |
-| Test Framework | Vitest |
-| Upstream | evoluhq/evolu |
+| Aspect           | Value         |
+| ---------------- | ------------- |
+| Package Manager  | Bun 1.3.8     |
+| Node.js          | >=24.0.0      |
+| Linter/Formatter | Biome 2.3.14  |
+| Test Framework   | Vitest        |
+| Upstream         | evoluhq/evolu |
 
 ## 🗂️ Repository Structure
 
@@ -92,13 +92,13 @@ bun run verify
 
 ## 📍 Related Resources
 
-| Resource | Location |
-|----------|----------|
-| Issues | `../knowledge/05-Issues/` |
-| Roadmap | `../knowledge/05-Issues/roadmap.md` |
-| Architecture | `../knowledge/02-Architecture/` |
-| Bench Suite | `../bench-suite/` (sibling repo) |
-| Upstream | https://github.com/evoluhq/evolu |
+| Resource     | Location                            |
+| ------------ | ----------------------------------- |
+| Issues       | `../knowledge/05-Issues/`           |
+| Roadmap      | `../knowledge/05-Issues/roadmap.md` |
+| Architecture | `../knowledge/02-Architecture/`     |
+| Bench Suite  | `../bench-suite/` (sibling repo)    |
+| Upstream     | https://github.com/evoluhq/evolu    |
 
 ## 🤖 For AI Agents
 

README.md

@@ -73,6 +73,7 @@ Linting
 Testing
 
 - `bun run test` - Run tests
+- [Vitest VS Code extension](https://github.com/vitest-dev/vscode)
 
 Release
 

apps/web/package.json

@@ -61,7 +61,7 @@
     "@evolu/tsconfig": "workspace:*",
     "@types/mdx": "^2.0.13",
     "@types/node": "^24.10.9",
-    "@types/react": "~19.2.10",
+    "@types/react": "~19.2.11",
     "@types/react-dom": "~19.2.3",
     "@types/react-highlight-words": "^0.20.1",
     "@types/rss": "^0.0.32",

apps/web/src/app/(playgrounds)/playgrounds/full/EvoluFullExample.tsx

@@ -5,6 +5,7 @@ import {
   createEvolu,
   createFormatTypeError,
   createObjectURL,
+  createQueryBuilder,
   FiniteNumber,
   id,
   idToIdBytes,
@@ -99,6 +100,8 @@ const Schema = {
   },
 };
 
+const createQuery = createQueryBuilder(Schema);
+
 const deps = createEvoluDeps();
 
 const evolu = createEvolu(deps)(Schema, {
@@ -212,7 +215,7 @@ const App: FC = () => {
   );
 };
 
-const projectsWithTodosQuery = evolu.createQuery(
+const projectsWithTodosQuery = createQuery(
   (db) =>
     db
       .selectFrom("project")
@@ -409,7 +412,7 @@ const HomeTabProjectSectionTodoItem: FC<{
 
   // Demonstrate history tracking. Evolu automatically tracks all changes
   // in the evolu_history table, making it easy to build audit logs or undo features.
-  const titleHistoryQuery = evolu.createQuery((db) =>
+  const titleHistoryQuery = createQuery((db) =>
     db
       .selectFrom("evolu_history")
       .select(["value", "timestamp"])
@@ -503,7 +506,7 @@ const HomeTabProjectSectionTodoItem: FC<{
   );
 };
 
-const projectsQuery = evolu.createQuery((db) =>
+const projectsQuery = createQuery((db) =>
   db
     .selectFrom("project")
     .select(["id", "name", "fooJson"])
@@ -716,7 +719,7 @@ const AccountTab: FC = () => {
   );
 };
 
-const deletedProjectsQuery = evolu.createQuery((db) =>
+const deletedProjectsQuery = createQuery((db) =>
   db
     .selectFrom("project")
     .select(["id", "name", "updatedAt"])
@@ -728,7 +731,7 @@ const deletedProjectsQuery = evolu.createQuery((db) =>
 
 type DeletedProjectsRow = typeof deletedProjectsQuery.Row;
 
-const deletedTodosQuery = evolu.createQuery((db) =>
+const deletedTodosQuery = createQuery((db) =>
   db
     .selectFrom("todo")
     .select(["id", "title", "isCompleted", "projectId", "updatedAt"])

apps/web/src/app/(playgrounds)/playgrounds/multitenant/EvoluMultitenantExample.tsx

@@ -23,6 +23,9 @@ const Schema = {
 
 const deps = createEvoluDeps();
 
+// Create a typed query builder from the schema
+const createQuery = Evolu.createQueryBuilder(Schema);
+
 deps.evoluError.subscribe(() => {
   const error = deps.evoluError.get();
   if (!error) return;
@@ -73,7 +76,7 @@ export const EvoluMultitenantExample: FC = () => (
 );
 
 // Evolu uses Kysely for type-safe SQL (https://kysely.dev/).
-const todosQuery = evolu.createQuery((db) =>
+const todosQuery = createQuery((db) =>
   db
     // Type-safe SQL: try autocomplete for table and column names.
     .selectFrom("todo")

biome.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.3.13/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.3.14/schema.json",
   "vcs": {
     "enabled": true,
     "clientKind": "git",