qubu 0.6.0 → 0.6.2

package/dist/value-CpaUFtjw.mjs

@@ -0,0 +1,45 @@
+import { A as fragment, E as makeSchemaExpression, U as resultValue, Y as standardJson, Z as createDialect } from "./column-DDRvD7SF.mjs";
+//#region src/dialects/standard.ts
+/** SQL:2008-style rendering defaults used by the core builder. */
+function standardDialect() {
+	return createDialect({
+		name: "standard-sql",
+		placeholder: () => "?",
+		json: standardJson
+	});
+}
+//#endregion
+//#region src/core/primitives/parameter.ts
+function parameter(_value, sqlType) {
+	return fragment((context) => context.parameter(_value, sqlType));
+}
+//#endregion
+//#region src/expressions/value.ts
+/** Build a parameterized value expression with an optional runtime SQL domain for the adapter. */
+function value(input, sqlType) {
+	const expression = makeSchemaExpression("value", (context) => context.render(parameter(input, sqlType)), resultValue(void 0, void 0, sqlType));
+	return Object.freeze({
+		...expression,
+		value: input
+	});
+}
+/**
+* Bind a value while declaring its compile-time and runtime SQL semantic domain.
+*
+* @remarks
+*   The domain is a binding hint; it does not select a JavaScript result decoder.
+*/
+function typedValue(input, sqlType) {
+	return value(input, sqlType);
+}
+function isExpressionValue(valueToCheck) {
+	return typeof valueToCheck === "object" && valueToCheck !== null && "expressionKind" in valueToCheck && "render" in valueToCheck && typeof valueToCheck.render === "function";
+}
+function isValueExpression(valueToCheck) {
+	return isExpressionValue(valueToCheck) && valueToCheck.expressionKind === "value" && "value" in valueToCheck;
+}
+function asValue(input, sqlType) {
+	return isExpressionValue(input) ? input : value(input, sqlType);
+}
+//#endregion
+export { parameter as a, value as i, isValueExpression as n, standardDialect as o, typedValue as r, asValue as t };

package/dist/vite/ambient.d.ts

@@ -68,6 +68,8 @@ declare global {
   const isNull: typeof import("qubu").isNull
   const isTrue: typeof import("qubu").isTrue
   const json: typeof import("qubu").json
+  const jsonArrayFrom: typeof import("qubu").jsonArrayFrom
+  const jsonObjectFrom: typeof import("qubu").jsonObjectFrom
   const jsonBoolean: typeof import("qubu").jsonBoolean
   const jsonExists: typeof import("qubu").jsonExists
   const jsonNumber: typeof import("qubu").jsonNumber

package/dist/vite.d.mts

@@ -4,7 +4,7 @@
  * with the ordinary authoring surface of `qubu`; fragment internals, dialect construction, and
  * schema extensions belong to the layered entrypoints.
  */
-declare const qubuGlobals: readonly ["add", "alias", "all", "allowAll", "and", "asc", "asValue", "avg", "bigint", "between", "binary", "boolean", "call", "caseWhen", "cast", "check", "coalesce", "column", "concat", "count", "countDistinct", "correlate", "crossJoin", "cte", "date", "denseRank", "defaultValues", "deleteFrom", "desc", "distinct", "divide", "eq", "except", "execute", "executeRows", "externalDefault", "externalGeneratedColumn", "exists", "fetchFirst", "fetchNext", "foreignKey", "from", "fullJoin", "generatedColumn", "gt", "gte", "groupBy", "having", "identityColumn", "inList", "inQuery", "index", "innerJoin", "insertInto", "insertSelect", "integer", "intersect", "isDistinctFrom", "isNotDistinctFrom", "isNotNull", "isNull", "isTrue", "json", "jsonBoolean", "jsonExists", "jsonNumber", "jsonPath", "jsonText", "lateral", "leftJoin", "like", "lower", "lt", "lte", "max", "min", "modulo", "multiply", "naturalJoin", "nativeColumn", "nativeStorage", "ne", "not", "notExists", "notIn", "notLike", "nullsFirst", "nullsLast", "numeric", "nullable", "offset", "omit", "or", "order", "orderBy", "over", "portableStorage", "primaryKey", "qubu", "references", "recursiveCte", "render", "returning", "rightJoin", "rank", "rowNumber", "scalar", "schema", "schemaCall", "select", "sql", "stream", "subtract", "sum", "table", "text", "timestamp", "union", "unionAll", "unique", "uniqueConstraint", "update", "upper", "value", "values", "where", "withCte", "uuid"];
+declare const qubuGlobals: readonly ["add", "alias", "all", "allowAll", "and", "asc", "asValue", "avg", "bigint", "between", "binary", "boolean", "call", "caseWhen", "cast", "check", "coalesce", "column", "concat", "count", "countDistinct", "correlate", "crossJoin", "cte", "date", "denseRank", "defaultValues", "deleteFrom", "desc", "distinct", "divide", "eq", "except", "execute", "executeRows", "externalDefault", "externalGeneratedColumn", "exists", "fetchFirst", "fetchNext", "foreignKey", "from", "fullJoin", "generatedColumn", "gt", "gte", "groupBy", "having", "identityColumn", "inList", "inQuery", "index", "innerJoin", "insertInto", "insertSelect", "integer", "intersect", "isDistinctFrom", "isNotDistinctFrom", "isNotNull", "isNull", "isTrue", "json", "jsonArrayFrom", "jsonObjectFrom", "jsonBoolean", "jsonExists", "jsonNumber", "jsonPath", "jsonText", "lateral", "leftJoin", "like", "lower", "lt", "lte", "max", "min", "modulo", "multiply", "naturalJoin", "nativeColumn", "nativeStorage", "ne", "not", "notExists", "notIn", "notLike", "nullsFirst", "nullsLast", "numeric", "nullable", "offset", "omit", "or", "order", "orderBy", "over", "portableStorage", "primaryKey", "qubu", "references", "recursiveCte", "render", "returning", "rightJoin", "rank", "rowNumber", "scalar", "schema", "schemaCall", "select", "sql", "stream", "subtract", "sum", "table", "text", "timestamp", "union", "unionAll", "unique", "uniqueConstraint", "update", "upper", "value", "values", "where", "withCte", "uuid"];
 type QubuGlobal = (typeof qubuGlobals)[number];
 //#endregion
 //#region src/vite/index.d.ts

package/dist/vite.mjs

@@ -138,6 +138,8 @@ const qubuGlobals = [
 	"isNull",
 	"isTrue",
 	"json",
+	"jsonArrayFrom",
+	"jsonObjectFrom",
 	"jsonBoolean",
 	"jsonExists",
 	"jsonNumber",

package/docs/dialects-and-execution.md

@@ -79,6 +79,11 @@ rows. Qubu then uses the query's result shape and the adapter's decoder policy
 to produce the typed `ExecutionResult`. A `TransactionalQueryAdapter` can also
 pin one driver connection for a callback transaction:
 
+When present, `request.statement.parameterSqlTypes` is an optional sidecar
+aligned with `statement.parameters`. Adapters can pass each domain to their
+value encoder or driver binding layer when a client distinguishes values such
+as `DATE`, `TIMESTAMP`, `UUID`, and `DECIMAL`.
+
 ```ts
 import { qubu } from "qubu"
 import { postgresDialect } from "qubu/postgres"
@@ -147,10 +152,12 @@ lifecycle.
 
 ### Decode schema-aware result values
 
-Portable boolean, date, timestamp, and JSON columns retain their logical
-result domains through projection aliases, derived queries, CTEs, set
-operations, and mutation `RETURNING`. Register only the conversions required
-by the selected driver configuration:
+Portable boolean, date, timestamp, JSON, and bigint columns retain their
+logical result domains through projection aliases, derived queries, CTEs, set
+operations, and mutation `RETURNING`. The result field exposes that domain as
+`sqlType` before execution. Register only the conversions required by the
+selected driver configuration. `sqlType` identifies the SQL domain; `type` and
+the selected decoder determine whether Qubu converts the returned value:
 
 ```ts
 import {
@@ -180,6 +187,11 @@ const adapter: QueryAdapter = {
 }
 ```
 
+Qubu can decode bigint values exactly when a driver returns a bigint, a safe
+integer, or an integer string. For arbitrary-precision `DECIMAL` values, keep
+the driver's exact representation (usually a string or decimal object) rather
+than converting it to a JavaScript number.
+
 Do not register `jsonTextResultDecoder` when the driver already returns parsed
 JSON. A JSON string is otherwise ambiguous: it may be serialized JSON or an
 already-decoded JSON string scalar. With no registered decoder, Qubu preserves
@@ -459,13 +471,51 @@ back after it rejects, and releases the connection in every case. Qubu only
 creates the scoped client and passes the callback result through. It never
 emits `BEGIN`, `COMMIT`, or `ROLLBACK` itself.
 
-The transaction client exposes `execute()` and `rows()` but no public
-`transaction()` method, so nested transactions are not part of this contract.
-When the adapter also implements `StreamingQueryAdapter`, the scoped client
-also exposes `stream()` and its streams follow the cleanup rule above. Use
-adapter-specific savepoints when a driver needs nested partial rollback.
-`TransactionOptions.signal` is passed to the adapter. Isolation levels and
-other driver-specific settings remain adapter-specific.
+A scoped client's methods follow its adapter's capabilities: `execute()` and
+`rows()` are always available; EXPLAIN and streaming require their respective
+capabilities. `TransactionOptions.signal` is passed to the adapter. Isolation
+levels and other driver-specific settings remain adapter-specific.
+
+### Roll back part of a transaction
+
+The pg, mysql2, and node:sqlite adapters expose `transaction()` on scoped
+clients through the shared `NestedTransactionalQueryAdapter` capability.
+Other adapters retain their existing transaction surface. For example, with a
+bound pg client, catch a nested failure to keep earlier work:
+
+```ts
+await db.transaction(async (outer) => {
+  await outer.execute(firstMutation)
+  try {
+    await outer.transaction(async (inner) => {
+      await inner.execute(optionalMutation)
+    })
+  } catch (error) {
+    // The nested work was rolled back; the outer transaction can continue.
+  }
+  await outer.execute(secondMutation)
+})
+```
+
+Each nested callback uses a uniquely named savepoint on the same connection.
+Success releases it; failure rolls back to it and releases it. Letting the
+failure escape also rolls back the outer transaction. Failed savepoint creation
+or recovery makes the entire transaction unsafe to commit, even if the callback
+catches the error. Primary and cleanup failures are retained in `AggregateError`.
+
+Await every query and nested transaction before returning. These three adapters
+reject finished scoped clients, overlapping sibling scopes, a child started
+while its parent has pending queries, and parent queries while a child is active.
+If a callback finishes with work still pending, the adapter waits for that work
+and rolls back instead of committing. Use the active scoped client for all work
+on a directly supplied connection; its root client rejects unrelated operations
+during the transaction. A pg pool still accepts independent queries and
+transactions on other acquired connections. Raw driver calls and separately
+constructed adapters remain the application's responsibility.
+
+EXPLAIN and result decoding remain available at every depth. Nested transaction
+hooks identify their enclosing transaction with `parentId`; queries identify
+their immediate scope. Cancellation does not interrupt savepoint recovery.
 
 The standalone functions remain useful when the adapter varies by call or a
 small module does not need a bound client:

package/docs/getting-started.md

@@ -91,6 +91,6 @@ type UserRow = typeof query.row
   inputs.
 - [Choose a database dialect](dialects-and-execution.md) when the
   driver expects different identifier, placeholder, or pagination syntax.
-- [Read JSON scalars](guides/json.md) from a JSON column.
+- [Query nested JSON](guides/json.md) or read scalars from a JSON column.
 - [Use the Vite compiler hint](guides/vite-plugin.md) for directive-based
   imports.

package/docs/guides/compose-queries.md

@@ -28,6 +28,28 @@ The rendered statement includes the `WITH` clause before `SELECT`. Selected
 camelCase keys use snake_case while they belong to the CTE relation; the outer
 result projection aliases them back to camelCase for the returned row.
 
+Attach the same clause to an insert, update, or delete when the mutation reads
+through the CTE. For example, an insert can consume a filtered CTE through
+`insertSelect()`:
+
+```ts
+import { insertInto, insertSelect, returning } from "qubu"
+
+const archivedUsers = table("archived_users", { name: text() })
+const archive = insertInto(
+  archivedUsers,
+  insertSelect(select({ name: activeUsers.name }, from(activeUsers)), ["name"]),
+  withCte(activeUsers),
+  returning({ name: archivedUsers.name }),
+)
+```
+
+Qubu renders `WITH ... INSERT` and keeps CTE parameters before mutation
+parameters. For update and delete predicates, select from the CTE in a scalar,
+`IN`, or `EXISTS` subquery; `withCte()` defines the relation but does not add it
+directly to the mutation target's column scope. Recursive CTEs use the same
+pattern and render `WITH RECURSIVE` before the mutation keyword.
+
 ## Build a recursive CTE
 
 `recursiveCte()` uses the anchor projection as the contract for a recursive

package/docs/guides/drizzle.md

@@ -22,7 +22,7 @@ your database:
 
 ```ts
 import { integer, schema, table, text } from "qubu"
-import { toPostgresDrizzleSchema } from "@qubu/drizzle/postgres"
+import { toDrizzleSchema } from "@qubu/drizzle/postgres"
 
 const users = table("user_records", {
   id: integer({ generated: true }),
@@ -31,17 +31,17 @@ const users = table("user_records", {
 })
 
 const appSchema = schema({ users }, { namespace: "app" })
-const drizzleTables = toPostgresDrizzleSchema(appSchema)
+const drizzleTables = toDrizzleSchema(appSchema)
 ```
 
 The import path selects the dialect. Each module imports only its matching
 Drizzle core package:
 
-| Database   | Import                   | Converter                   |
-| ---------- | ------------------------ | --------------------------- |
-| PostgreSQL | `@qubu/drizzle/postgres` | `toPostgresDrizzleSchema()` |
-| MySQL      | `@qubu/drizzle/mysql`    | `toMysqlDrizzleSchema()`    |
-| SQLite     | `@qubu/drizzle/sqlite`   | `toSqliteDrizzleSchema()`   |
+| Database   | Import                   | Converter           |
+| ---------- | ------------------------ | ------------------- |
+| PostgreSQL | `@qubu/drizzle/postgres` | `toDrizzleSchema()` |
+| MySQL      | `@qubu/drizzle/mysql`    | `toDrizzleSchema()` |
+| SQLite     | `@qubu/drizzle/sqlite`   | `toDrizzleSchema()` |
 
 `@qubu/drizzle` exports the shared conversion error and dialect types. It does
 not import a dialect core or provide a universal runtime converter.
@@ -75,7 +75,7 @@ Unix timestamps and Drizzle must continue reading and writing `Date` values:
 
 ```ts
 import { schema, table } from "qubu"
-import { toSqliteDrizzleSchema } from "@qubu/drizzle/sqlite"
+import { toDrizzleSchema } from "@qubu/drizzle/sqlite"
 import { sqliteTimestamp } from "qubu/sqlite"
 
 const events = table("events", {
@@ -85,7 +85,7 @@ const events = table("events", {
   }),
 })
 
-const drizzleTables = toSqliteDrizzleSchema(schema({ events }))
+const drizzleTables = toDrizzleSchema(schema({ events }))
 ```
 
 `timestamp` stores Unix seconds and `timestamp_ms` stores Unix milliseconds.
@@ -129,13 +129,13 @@ belong to the selected dialect:
 
 ```ts
 import { nativeColumn, schema, table } from "qubu"
-import { toPostgresDrizzleSchema } from "@qubu/drizzle/postgres"
+import { toDrizzleSchema } from "@qubu/drizzle/postgres"
 
 const records = table("records", {
   handle: nativeColumn("postgresql", "CITEXT"),
 })
 
-const tables = toPostgresDrizzleSchema(schema({ records }))
+const tables = toDrizzleSchema(schema({ records }))
 ```
 
 Conversion first runs Qubu's snapshot validation for the selected dialect.

package/docs/guides/extensions/typed-expressions.md

@@ -60,7 +60,7 @@ Declare result domains at other extension boundaries too:
 import { typedCall, typedCast, typedValue, unsafeExpression } from "qubu/core"
 import type { SqlText, SqlUuid } from "qubu"
 
-const id = typedValue<SqlUuid, string>("108cb836-20d2-41b2-8c23-f0c94700aa7e")
+const id = typedValue<SqlUuid, string>("108cb836-20d2-41b2-8c23-f0c94700aa7e", "uuid")
 const normalized = typedCall<SqlText, string>()("custom_text", users.name)
 const rawNameAsText = typedCast<string, SqlText>()(users.name, "TEXT")
 const generated = unsafeExpression<string, SqlText>("custom_text()")
@@ -69,8 +69,10 @@ const generated = unsafeExpression<string, SqlText>("custom_text()")
 `typedCall()` preserves source requirements from its arguments. `typedCast()`
 is the fallback when no reusable definition describes the target. It preserves
 operand nullability and source metadata while emitting its supplied type name
-verbatim. `typedValue()` binds a parameter. `unsafeExpression()` emits its
-string unchanged and should remain a last resort.
+verbatim. `typedValue()` binds a parameter and declares its runtime SQL domain
+for the adapter; it does not select a JavaScript result decoder. Schema columns
+carry result-decoder metadata separately. `unsafeExpression()` emits its string
+unchanged and should remain a last resort.
 
 The lower-level forms also expose the SQL domain in their generic lists:
 `call<Output, Name, Arguments, NullableFrom, SqlType>()` and

package/docs/guides/json.md

@@ -1,6 +1,99 @@
-# Read JSON scalars
+# Query nested JSON
 
-> Extract a string, number, or boolean from a JSON column without writing a raw SQL path.
+> Build inferred nested results, or read scalar values from stored JSON documents.
+
+Use jsonArrayFrom() to nest a query's rows and jsonObjectFrom() for a query
+proven to return at most one row. Both preserve filtering, correlation,
+ordering, and pagination:
+
+```ts
+import {
+  correlate,
+  desc,
+  eq,
+  fetchFirst,
+  from,
+  integer,
+  jsonArrayFrom,
+  jsonObjectFrom,
+  orderBy,
+  select,
+  table,
+  text,
+  where,
+} from "qubu"
+
+const users = table("users", { id: integer(), name: text() })
+const posts = table("posts", {
+  id: integer(),
+  authorId: integer(),
+  title: text(),
+})
+const latestPosts = select(
+  { id: posts.id, title: posts.title },
+  from(posts),
+  correlate(users),
+  where(eq(posts.authorId, users.id)),
+  orderBy(desc(posts.id)),
+  fetchFirst(3),
+)
+const latestPost = select(
+  { title: posts.title },
+  from(posts),
+  correlate(users),
+  where(eq(posts.authorId, users.id)),
+  orderBy(desc(posts.id)),
+  fetchFirst(1),
+)
+const query = select(
+  {
+    name: users.name,
+    posts: jsonArrayFrom(latestPosts),
+    latestPost: jsonObjectFrom(latestPost),
+  },
+  from(users),
+)
+// Row: { name: string; posts: { id: number; title: string }[];
+//        latestPost: { title: string } | null }
+```
+
+Execute the query through a Qubu adapter to decode nested results. An empty
+array query returns []; an empty object query returns null. A source-free
+query proven to return exactly one row produces a non-null object type.
+Object queries need Qubu's cardinality proof: an unconditional fetchFirst(1)
+or fetchFirst(0) establishes the bound. A conditional limit does not.
+
+The helpers compose inside further select() projections, so nesting can
+continue without result-type assertions. correlate() and the outer query's
+FROM/JOIN scope remain checked at every level.
+
+### Preserve ordering and logical values
+
+Nested arrays retain explicit ORDER BY and pagination. Tied sort keys retain
+SQL's unspecified tie order; add a unique tie-breaker when order matters.
+DISTINCT ordering must use the same expressions as the selection. Without an
+ORDER BY, array order is unspecified.
+
+Nested results support PostgreSQL, MySQL 8.0.21+, and SQLite 3.45+. Other
+dialects fail during rendering. SQLite's minimum includes the JSON aggregate
+ordering fix needed to retain object values.
+
+Built-in column domains decode to their declared types, including bigint,
+Uint8Array, Date, boolean, and nested JSON. Qubu transports precision-sensitive
+values as text and rejects numbers that lose significant decimal digits or
+exceed JavaScript's safe integer range. Use bigint columns for exact large
+integers. Unknown or custom SQL domains need a supported explicit cast, for
+example cast(value(7), integer()); declaring a TypeScript result alone does
+not provide runtime decoding information.
+
+Custom mapResult() and column decoders receive the JSON transport value as
+unknown: bigint and decimal strings, hexadecimal binary strings, serialized
+JSON strings, or ordinary JSON scalar values. They own conversion to their
+advertised application type. Adapter-wide decoders do not run inside nested
+objects. Keep arbitrary stored JSON within JavaScript's numeric precision;
+unsupported numeric representations fail instead of silently rounding.
+
+## Read stored JSON scalars
 
 Use a structured jsonPath() when a query needs a scalar or an existence check
 inside a JSON document:

package/docs/guides/mutations.md

@@ -44,6 +44,63 @@ render(query)
 
 Use `defaultValues()` only when every non-generated column has a database
 default. Use `insertSelect(query, columns)` for an `INSERT ... SELECT` source.
+An ordinary or recursive `withCte()` clause can prefix any mutation; see
+[Compose queries](compose-queries.md#turn-a-query-into-a-cte) for the typed
+`WITH ... INSERT`, `WITH ... UPDATE`, and `WITH ... DELETE` patterns.
+
+Each field may also be a typed expression whose output is compatible with the
+target column. Expressions render directly and retain their dialect
+requirements; ordinary application values still pass through the column's
+parameter encoder:
+
+```ts
+import { upper } from "qubu"
+
+insertInto(users, values({ name: upper("Ada") }))
+```
+
+An `INSERT ... VALUES` row does not introduce a relational source, so its
+expressions cannot reference columns from the target table or another table.
+Use `insertSelect()` when inserted values need a query source.
+
+## Resolve PostgreSQL conflicts
+
+PostgreSQL upserts can target a primary key, a `unique()` constraint, or a
+declared unique index from the inserted table. A partial unique index carries
+its predicate into the conflict target so PostgreSQL can infer the same index:
+
+```ts
+import { boolean, eq, index, table, text, value } from "qubu"
+import { doUpdate, excluded, onConflict } from "qubu/postgres"
+
+const accounts = table(
+  "accounts",
+  { email: text(), active: boolean(), name: text() },
+  (accounts) => ({
+    constraints: {},
+    indexes: {
+      activeEmail: index([accounts.email], {
+        unique: true,
+        where: eq(accounts.active, value(true)),
+        dialect: { dialect: "postgresql" },
+      }),
+    },
+  }),
+)
+
+const incoming = excluded(accounts)
+const conflict = onConflict(
+  accounts,
+  accounts.indexes.activeEmail,
+  doUpdate({ name: incoming.name }),
+)
+```
+
+The index must be unique, declared on the insert target, and portable or marked
+for PostgreSQL. Index expressions and predicates use the same deterministic,
+parameter-free schema-expression rules as the declared index. Constraint-based
+targets keep their existing cross-dialect behavior; unique-index inference is
+PostgreSQL-specific.
 
 ## Update with a predicate
 
@@ -64,6 +121,38 @@ const query = update(
 The assignment expression is source-aware, so a column from an unrelated table
 cannot silently enter the update.
 
+PostgreSQL updates can introduce one or more typed sources with `updateFrom()`.
+Those sources are available to assignments, the predicate, and `RETURNING`:
+
+```ts
+import { eq, integer, render, returning, table, text, update, where } from "qubu"
+import { postgresDialect, updateFrom } from "qubu/postgres"
+
+const changes = table("user_changes", {
+  userId: integer(),
+  name: text(),
+})
+
+const query = update(
+  users,
+  { name: changes.name },
+  updateFrom(changes),
+  where(eq(users.id, changes.userId)),
+  returning({ id: users.id, sourceName: changes.name }),
+)
+
+render(query, postgresDialect())
+// UPDATE "users" SET "name" = "user_changes"."name"
+// FROM "user_changes"
+// WHERE ("users"."id" = "user_changes"."user_id")
+// RETURNING "users"."id" AS "id", "user_changes"."name" AS "sourceName"
+```
+
+`UPDATE ... FROM` carries a dialect capability requirement, so rendering it
+with the default, SQLite, or MySQL dialect is rejected. Qubu still requires a
+predicate or an explicit `allowAll()` marker; introducing a source does not
+authorize an unrestricted update.
+
 Use `omit` for a runtime-conditional assignment. Qubu removes omitted fields
 before validating and rendering the effective assignment set:
 
@@ -87,6 +176,42 @@ before rendering when every field is omitted. Possible expression branches
 remain source- and capability-aware even when their runtime alternative is
 `omit`.
 
+## Update duplicate keys in MySQL
+
+Use `onDuplicateKeyUpdate()` from `qubu/mysql` to update a row when an insert
+conflicts with any primary or unique key. MySQL chooses the conflicting key;
+this clause has no conflict-target argument or `RETURNING` support.
+
+```ts
+import { insertInto, values } from "qubu"
+import { incoming, onDuplicateKeyUpdate } from "qubu/mysql"
+
+const proposed = incoming(users)
+const query = insertInto(
+  users,
+  values({ name: "Ada", email: "ada@example.com" }),
+  onDuplicateKeyUpdate(users, { name: proposed.name }),
+)
+await db.execute(query)
+```
+
+Declare a unique key on `email` in the database for this example. A duplicate
+email replaces the existing name with the proposed name. Assignments accept
+writable target columns, target-table expressions, `incoming(table)` columns,
+or `omit`. Raw values retain the target column's parameter encoder. At least
+one assignment must remain after omissions.
+
+Incoming references are available only inside the matching table's duplicate-key
+assignments. Qubu renders MySQL row aliases for `values()` and `defaultValues()`.
+For `insertSelect()`, it wraps the query in a derived projection and maps its
+fields positionally to the target-column list. Incoming references then cover
+only that list; referencing an omitted target column fails during rendering.
+This syntax requires MySQL 8.0.19 or later.
+
+The result retains mysql2's `affectedRows`, `changedRows`, and `insertId` metadata
+when supplied by the driver. These facts do not identify which branch ran for
+every row of a batch. Read rows with a separate query when needed.
+
 ## Delete with a predicate
 
 ```ts

package/docs/guides/valtio-sync.md

@@ -0,0 +1,113 @@
+# Valtio Sync
+
+> Check Valtio Sync fields against Qubu tables and apply each client mutation
+> with its sync event in one Qubu-owned transaction.
+
+Install the optional integration beside Qubu, Valtio Sync, and Zod:
+
+```sh
+pnpm add qubu @qubu/valtio-sync valtio-sync zod
+```
+
+## Check synced fields against Qubu tables
+
+Use the integration's schema wrappers instead of `valtio-sync/schema` when a
+definition corresponds to a Qubu table. Every selected table field must appear
+in `fields`. Mark persistence-only or server-controlled fields with
+`serverOnly()` so they are excluded from Valtio Sync validation and records.
+
+```ts
+import { $type, defineCollection, serverOnly } from "@qubu/valtio-sync"
+import { boolean, integer, table, text } from "qubu"
+import { z } from "zod"
+
+const todosTable = table("todos", {
+  ownerId: integer(),
+  id: text(),
+  title: text(),
+  done: boolean(),
+})
+
+export const todos = defineCollection({
+  dbType: $type<typeof todosTable>(),
+  fields: {
+    ownerId: serverOnly(),
+    id: z.string(),
+    title: z.string().default(""),
+    done: z.boolean().default(false),
+  },
+})
+```
+
+The Zod output for each synced field must be assignable to its Qubu selected
+value. Narrow schemas are allowed, such as a Zod enum for a Qubu text field.
+Missing fields, extra fields, and wider outputs fail type checking. The same
+rules apply to `defineAccount()`.
+
+## Apply mutations in transactions
+
+`applyOpsWithQubu()` converts Qubu-aware mutation handlers into the public
+`ServerHandlers` contract accepted by `valtio-sync/server`. Supply a bound Qubu
+client whose adapter supports transactions:
+
+```ts
+import { applyOpsWithQubu } from "@qubu/valtio-sync"
+import { and, eq, insertInto, returning, update, values, where } from "qubu"
+import { valtioSync } from "valtio-sync/server"
+
+type SyncContext = { user: { id: number } }
+
+const handlers = applyOpsWithQubu<SyncContext>({
+  db,
+  syncEvents: {
+    write: async ({ tx, ctx, collection, recordId, op }) => {
+      const [event] = await tx.rows(
+        insertInto(
+          syncEvents,
+          values({ userId: ctx.user.id, collection, recordId, op }),
+          returning({ seq: syncEvents.seq }),
+        ),
+      )
+      return event.seq
+    },
+  },
+  authorize: ({ ctx, collection, op }) => assertCanSync(ctx.user, collection, op),
+  checkConflict: ({ tx, ctx, collection, op }) =>
+    assertFreshBaseVersion(tx, ctx.user.id, collection, op),
+  handlers: {
+    todos: {
+      readChanges: ({ ctx, since }) => readTodoChanges(ctx.user.id, since),
+      create: async ({ tx, ctx, record }) => {
+        const value = todos.recordSchema.parse(record)
+
+        await tx.execute(insertInto(todosTable, values({ ...value, ownerId: ctx.user.id })))
+        return {}
+      },
+      update: async ({ tx, ctx, op, patch }) => {
+        const value = todos.recordSchema.partial().parse(patch)
+
+        await tx.execute(
+          update(
+            todosTable,
+            value,
+            where(and(eq(todosTable.id, op.id), eq(todosTable.ownerId, ctx.user.id))),
+          ),
+        )
+        return {}
+      },
+    },
+  },
+})
+
+export const sync = valtioSync({ schema: { todos }, handlers })
+```
+
+Authorization, conflict checks, the application mutation, and
+`syncEvents.write()` run in that order inside one Qubu transaction. If any step
+fails, the adapter rolls the transaction back. The event sequence becomes
+`serverVersion` unless the mutation handler returns an explicit version. Read
+handlers pass through unchanged.
+
+The integration does not define persistence tables, import Drizzle, or execute
+driver APIs. The application owns table design, authorization, conflict policy,
+event retention, and every query issued through the supplied Qubu transaction.