qubu 0.6.1 → 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/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

@@ -176,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/index.md

@@ -33,7 +33,7 @@ define a table, build a `SELECT`, and inspect its SQL and parameters.
   derivation and a native transactional database adapter.
 - [Extend Qubu](guides/extensions/overview.md) with a custom source, clause,
   dialect policy, or typed expression.
-- [Read JSON scalars](guides/json.md) from structured JSON paths.
+- [Query nested JSON](guides/json.md) or read scalars from structured paths.
 - [Enable the Vite compiler hint](guides/vite-plugin.md) when query modules
   should opt into named imports through a directive.
 - [Inspect an existing database](schema/introspection.md) through the optional

package/docs/migrations/adapters.md

@@ -2,38 +2,47 @@
 
 > Select a migration adapter from capabilities proven by its driver and environment, not from dialect name alone.
 
-Every executable migration adapter opens one pinned migration session and
+Every executable migration adapter opens a migration session and
 advertises the exact behavior the executor may use:
 
-| Field                                  | Contract                                                                            |
-| -------------------------------------- | ----------------------------------------------------------------------------------- |
-| `dialect`, `serverVersion`             | Physical target and optional version used for compatibility checks                  |
-| `session`                              | Must be `pinned` until `close()` resolves                                           |
-| `transactionalDdl`                     | Whether DDL effects can roll back                                                   |
-| `optionalTransactions`, `transactions` | Whether optional phases join a transaction and which requirements are proven        |
-| `lease`, `leaseKind`                   | Database-backed exclusion of another migration runner                               |
-| `locks`                                | Independently supported program DDL lock requirements                               |
-| `journal`                              | Database storage, head compare-and-swap, and atomic applied-record/head advancement |
-| `parameters`                           | Supported tagged parameter kinds                                                    |
-| `commitAmbiguity`                      | Ambiguous commit becomes `recovery-required`                                        |
-| `forbiddenPhases`                      | Checkpointed support or explicit rejection                                          |
-| `features`                             | Named constraints an artifact may require                                           |
+| Field                                  | Contract                                                                               |
+| -------------------------------------- | -------------------------------------------------------------------------------------- |
+| `dialect`, `serverVersion`             | Physical target and optional version used for compatibility checks                     |
+| `session`                              | `pinned` for the full lifecycle, or `atomic-batch` for one complete artifact per batch |
+| `transactionalDdl`                     | Whether DDL effects can roll back                                                      |
+| `optionalTransactions`, `transactions` | Whether optional phases join a transaction and which requirements are proven           |
+| `lease`, `leaseKind`                   | Database-backed exclusion of another migration runner                                  |
+| `locks`                                | Independently supported program DDL lock requirements                                  |
+| `journal`                              | Database storage, head compare-and-swap, and atomic applied-record/head advancement    |
+| `parameters`                           | Supported tagged parameter kinds                                                       |
+| `commitAmbiguity`                      | Ambiguous commit becomes `recovery-required`                                           |
+| `forbiddenPhases`                      | Checkpointed support or explicit rejection                                             |
+| `features`                             | Named constraints an artifact may require                                              |
 
 The migrator lease and a program's DDL lock are different controls. The lease
 excludes another Qubu runner; a DDL lock protects the database operation. The
 executor never treats one as proof of the other.
 
+## Trusted migration SQL
+
+Migration SQL, including SQL conditions, is trusted across all adapters. Qubu
+validates program structure and adapter capabilities, but does not parse SQL
+to enforce safety. Callers must preserve executor-owned transactions, connection
+settings, and migration journal state. For example, an explicit `COMMIT` can
+leave schema changes applied without their journal record; atomicity and recovery
+guarantees depend on respecting this contract.
+
 ## Current profiles
 
 The following stable profiles have live conformance coverage in this checkout:
 
-| Migration entrypoint                  | Dialect    | Transactions                  | Locks           | Forbidden phases | Notes                                               |
-| ------------------------------------- | ---------- | ----------------------------- | --------------- | ---------------- | --------------------------------------------------- |
-| `@qubu/adapter-libsql/migration`      | SQLite     | required, optional            | none, exclusive | unsupported      | Pinned application-owned client                     |
-| `@qubu/adapter-node-sqlite/migration` | SQLite     | required, optional            | none, exclusive | unsupported      | Pinned application-owned `DatabaseSync`             |
-| `@qubu/adapter-pg/migration`          | PostgreSQL | required, optional, forbidden | none, exclusive | checkpointed     | Caller supplies an already-pinned client            |
-| `@qubu/adapter-postgresjs/migration`  | PostgreSQL | required, optional, forbidden | none, exclusive | checkpointed     | Reserves and releases one connection                |
-| `@qubu/adapter-pglite/migration`      | PostgreSQL | required, optional, forbidden | none, exclusive | checkpointed     | Uses the database query queue as the pinned session |
+| Migration entrypoint                  | Dialect    | Transactions                  | Locks           | Forbidden phases | Notes                                                  |
+| ------------------------------------- | ---------- | ----------------------------- | --------------- | ---------------- | ------------------------------------------------------ |
+| `@qubu/adapter-libsql/migration`      | SQLite     | required, optional            | none, exclusive | unsupported      | Single-phase atomic batches through `client.migrate()` |
+| `@qubu/adapter-node-sqlite/migration` | SQLite     | required, optional            | none, exclusive | unsupported      | Pinned application-owned `DatabaseSync`                |
+| `@qubu/adapter-pg/migration`          | PostgreSQL | required, optional, forbidden | none, exclusive | checkpointed     | Caller supplies an already-pinned client               |
+| `@qubu/adapter-postgresjs/migration`  | PostgreSQL | required, optional, forbidden | none, exclusive | checkpointed     | Reserves and releases one connection                   |
+| `@qubu/adapter-pglite/migration`      | PostgreSQL | required, optional, forbidden | none, exclusive | checkpointed     | Uses the database query queue as the pinned session    |
 
 All five support every current tagged parameter kind (`null`, `boolean`,
 `string`, `number`, `bigint`, `bytes`, and `json`), a database journal and
@@ -68,3 +77,31 @@ const adapter = libsqlMigrationAdapter(client, {
 
 `DATABASE_URL` remains application configuration; neither the adapter nor CLI
 assigns deployment-provider meaning to it.
+
+## libSQL batch execution
+
+Each executable artifact must contain exactly one phase and an embedded before
+snapshot. The adapter submits its statements, SQL assertions, applied-history
+record, head update, and terminal attempt state in one `client.migrate()` call.
+For example, creating a table and recording that migration either both commit
+or both roll back. Multiple artifacts are separate batches; earlier successful
+artifacts remain applied if a later one fails.
+
+Preparation reads the schema in a read transaction. The submitted batch checks
+that the catalog still matches that inspection, the lease is still owned, and
+the head still equals the expected parent. Foreign-key validation runs before
+commit because libSQL temporarily disables enforcement during `migrate()`.
+
+Schema fingerprint and property preconditions are checked against the embedded
+before snapshot, whose physical facts are verified during preparation and
+guarded by the in-batch catalog assertion. Object-presence and scalar SQL checks
+run inside the batch. Postconditions must be object-presence/absence checks
+without fingerprints, or scalar SQL checks returning `1`. Unsupported conditions
+and multiple phases are rejected. SQL content is passed to the driver without
+safety validation; each program entry must follow the driver's statement contract.
+
+The database-row lease has no expiry or heartbeat. A process crash can leave
+it held; ownership must be resolved before another runner can proceed. A lost
+batch response is an uncertain outcome requiring journal inspection and, when
+the attempt remains unresolved, explicit recovery. It is never assumed to be
+a successful rollback.

package/docs/migrations/recovery.md

@@ -46,13 +46,19 @@ head, or a non-prefix repository fail before any statement executes.
 ## Execution and concurrency guarantees
 
 For each invocation, the executor verifies the entire repository, opens one
-pinned session, checks capabilities, acquires the migrator lease, validates the
+migration session, checks capabilities, acquires the migrator lease, validates the
 journal and repository prefix, checks the live before-snapshot digest, then
 applies each pending artifact. Within an artifact it creates an attempt,
 executes ordered phases with preconditions and postconditions, writes durable
 checkpoints, appends immutable history, and compare-and-swaps the head.
 Resources are released in reverse order: DDL lock, migrator lease, then session.
 
+An `atomic-batch` profile instead applies one single-phase artifact in one
+database transaction, including its checks and terminal journal writes. It
+records a completed phase checkpoint rather than intermediate statement
+checkpoints. See [libSQL batch execution](./adapters.md#libsql-batch-execution)
+for its supported conditions and concurrency guards.
+
 A second runner cannot rely on the lease alone. Atomic applied-record/head
 advancement uses the expected parent as a compare-and-swap guard. A runner that
 observes the already-matching head exits idempotently; a conflicting head is a

package/docs/query-model/fragments.md

@@ -51,7 +51,8 @@ producer, consumer, and regression test all exist.
 ## Parameters are runtime data
 
 Parameter values are not fragment metadata. A renderer calls
-`context.parameter(value)`, and `render()` collects values in placeholder order:
+`context.parameter(value)`, and `render()` collects values in placeholder order.
+Pass a second argument when the adapter needs the runtime SQL domain too:
 
 ```ts
 import { and, eq, from, integer, like, render, select, table, text, where } from "qubu"
@@ -72,6 +73,25 @@ render(query)
 // parameters: [7, '%Ada%']
 ```
 
+The optional domain metadata stays in a sidecar aligned with `parameters`:
+
+```ts
+import { typedValue } from "qubu/core"
+import type { SqlUuid } from "qubu"
+
+const id = typedValue<SqlUuid, string>("108cb836-20d2-41b2-8c23-f0c94700aa7e", "uuid")
+render(id)
+// parameterSqlTypes: ["uuid"]
+```
+
+The domain is a binding hint, not an instruction to convert the returned
+JavaScript value. Result decoding comes from a field's `type` or an explicit
+decoder.
+
+Plain JavaScript values remain untyped at runtime. Use an explicit domain when
+`Date` could mean either `DATE` or `TIMESTAMP`, or when a string is a UUID
+rather than text.
+
 The parameter array follows the placeholders in the rendered text. `select()`
 normalizes independent clause values, but keep the final call in SQL order in
 new code so source scope and repair hints are visible at a glance.

package/docs/reference/introspection-support.md

@@ -4,7 +4,7 @@
 
 The optional `qubu/introspection` entrypoint reads one selected database
 namespace through a user-owned `CatalogConnection`. It returns normalized
-catalog data and can map that data to canonical Snapshot v1 or v2. The
+catalog data and can map that data to canonical Snapshot v1. The
 application owns the driver and connection lifecycle. Snapshot diffing,
 migration planning, and DDL emission are separate Qubu capabilities; see the
 [ownership map](supported-surface.md#ownership-boundary).
@@ -46,7 +46,7 @@ SQL.
 ## PostgreSQL complete catalog surface
 
 The PostgreSQL reader also fills the complete normalized catalog used by
-Snapshot v2. It keeps PostgreSQL OIDs in current-run physical references and
+Snapshot v1. It keeps PostgreSQL OIDs in current-run physical references and
 keeps decompiler output such as `pg_get_viewdef`, `pg_get_triggerdef`, and
 `pg_get_functiondef` as tagged SQL data. It does not evaluate that text.
 
@@ -55,9 +55,9 @@ The query and normalization layout follows the catalog-oriented parts of the
 while Qubu keeps the result as typed data instead of generating TypeScript
 declarations.
 
-Use `mapCatalogToCompleteSnapshot()` for this object set. Use
-`mapCatalogToSnapshot()` when a caller explicitly needs the existing table-only
-Snapshot v1.
+Use `mapCatalogToSnapshot()` or its explicit
+`mapCatalogToCompleteSnapshot()` alias for this object set. Both produce the
+canonical Snapshot v1 shape.
 
 ## SQLite complete catalog surface
 
@@ -86,10 +86,9 @@ the selected namespace. SQLite does not provide the PostgreSQL object families
 such as routines, materialized views, policies, or ownership, so the reader
 does not fabricate them.
 
-`mapCatalogToCompleteSnapshot()` retains the typed views, triggers, deferred
-objects, opaque boundaries, and dialect extensions in Snapshot v2. The existing
-`mapCatalogToSnapshot()` still maps only tables and preserves Snapshot v1
-behavior.
+`mapCatalogToSnapshot()` delegates to `mapCatalogToCompleteSnapshot()` and
+retains typed views, triggers, deferred objects, opaque boundaries, and dialect
+extensions in Snapshot v1.
 
 The query and normalization seams follow the catalog-reading portions of the
 [Drizzle SQLite introspector](https://github.com/drizzle-team/drizzle-orm/blob/main/drizzle-kit/src/introspect-sqlite.ts).
@@ -110,13 +109,13 @@ MySQL has typed complete records for views, routines and their parameters,
 triggers, partitions, collations used by selected tables or columns, and
 comments. View definitions come from `INFORMATION_SCHEMA.VIEWS`; each view's
 columns are joined back to the matching `COLUMNS` rows by physical table name,
-so the complete Snapshot v2 cross-reference points at the view's own column
+so the complete Snapshot v1 cross-reference points at the view's own column
 IDs. Missing view definitions or unresolved trigger, partition, or other
 object references become deferred records with diagnostics.
 
 Scheduled events are retained as `CatalogOpaqueObject` records. Their event
 metadata and definition remain opaque, and the reader emits an
-`unmodeled-object` warning. Snapshot v2 keeps these records in
+`unmodeled-object` warning. Snapshot v1 keeps these records in
 `opaqueObjects`; they are not treated as typed routines, triggers, or
 migration operations.
 
@@ -132,13 +131,12 @@ The query and normalization layout follows the catalog-reading portions of the
 while Qubu keeps the result as typed data instead of generating TypeScript
 declarations.
 
-Use `mapCatalogToCompleteSnapshot()` to retain these typed MySQL families and
-the opaque or deferred boundaries in Snapshot v2. Use `mapCatalogToSnapshot()`
-when a caller explicitly needs the existing table-only Snapshot v1.
+Use `mapCatalogToSnapshot()` or `mapCatalogToCompleteSnapshot()` to retain these
+typed MySQL families and the opaque or deferred boundaries in Snapshot v1.
 
 ## Snapshot v1 surface
 
-The mapper can emit these facts in canonical Snapshot v1:
+The mapper emits these facts in canonical Snapshot v1:
 
 - one namespace and ordinary tables;
 - exact dialect-native column storage;
@@ -162,14 +160,14 @@ Snapshot v1 objects:
 - views and materialized views;
 - sequences, enums, domains, routines, triggers, policies, extensions,
   collations, comments, and partition metadata;
-- PostgreSQL identity sequence options that have no typed Snapshot v1 field;
+- PostgreSQL identity sequence options that have no typed field;
 - SQLite virtual/shadow tables, attached namespaces, and unrecoverable
   generated or expression definitions;
 - MySQL/MariaDB differences, prefix indexes, invisible indexes, and advanced
   functional, full-text, or spatial index semantics.
 
-Use the complete catalog and Snapshot v2 mapper to retain supported PostgreSQL
-and MySQL families. MySQL scheduled events stay opaque, and MySQL sequences,
+Use the Snapshot v1 mapper to retain supported PostgreSQL and MySQL families.
+MySQL scheduled events stay opaque, and MySQL sequences,
 materialized views, row-level security (RLS) policies, extension objects, and
 ownership stay unsupported or deferred. When a row cannot be normalized safely, the reader
 keeps a typed deferred or opaque record and emits a diagnostic instead of