qubu 0.6.1 → 0.6.3

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

@@ -1,6 +1,6 @@
 # Dialects and execution
 
-> Keep portable query construction separate from placeholder, identifier, pagination, cast-target, and driver decisions at the rendering boundary.
+> Choose a SQL dialect and connect Qubu queries to your database driver.
 
 ## Render once, choose a policy at the boundary
 
@@ -77,7 +77,12 @@ Qubu does not open connections or bind values for a particular client. An
 adapter receives an `ExecutionRequest` and returns driver-normalized object
 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:
+pin one driver connection for a callback transaction.
+
+`request.statement.parameterSqlTypes`, when present, lists SQL domains in
+the same order as `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"
@@ -138,19 +143,23 @@ per request, binds Qubu's ordered parameters, copies object rows, and finalizes
 the statement in a `finally` block. SQLite's change count and generated row ID
 are returned as mutation metadata when the request is a mutation.
 
-The package does not create or terminate workers. Initialize the official
-SQLite module inside a dedicated worker, construct the adapter around its
-`sqlite3.oo1.DB`, and close the adapter before terminating that worker. The
-browser build must serve the package's `sqlite3.wasm` asset beside the bundled
-worker module; the combo runner's verified browser scenario demonstrates this
-lifecycle.
+Your application manages the worker:
+
+1. Initialize the official SQLite module inside a dedicated worker.
+2. Construct the adapter around its `sqlite3.oo1.DB`.
+3. Close the adapter before terminating the worker.
+
+Serve the package’s `sqlite3.wasm` asset beside the bundled worker module. The
+combo runner’s verified browser scenario demonstrates this setup.
 
 ### 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 +189,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
@@ -422,12 +436,16 @@ queries identify their parent transaction operation. Hooks are synchronous,
 and their failures are sent to `onHookError` without changing the database
 operation's result.
 
+### What observations include
+
 Hook metadata accepts only strings, numbers, and booleans. Observations include
 rendered SQL and parameter count, but never parameter values, result rows,
 decoded values, or insert identifiers. Rendered SQL can still contain literals
 introduced by unsafe SQL helpers, so treat it according to the application's
 logging policy.
 
+### Stream observation timing
+
 Streaming adapters are still called eagerly. A consumed stream completes its
 observation when it is exhausted, closed early, or fails. A stream created but
 never consumed has no completion observation. Hooks are available only on
@@ -453,19 +471,74 @@ const result = await transactionalDb.transaction(async (transaction) => {
 })
 ```
 
-The adapter owns the driver lifecycle. It acquires and pins one connection,
-begins the transaction, invokes the callback, commits after it resolves, rolls
-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 adapter manages the transaction:
+
+1. Acquire and pin one connection.
+2. Begin the transaction.
+3. Run the callback.
+4. Commit if the callback resolves, or roll back if it rejects.
+5. Release the connection in either case.
 
-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.
+Qubu creates the scoped client and returns the callback result. The adapter
+emits `BEGIN`, `COMMIT`, and `ROLLBACK`.
+
+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`.
+
+#### Finish work before leaving a scope
+
+Await every query and nested transaction before returning. These three adapters
+reject:
+
+- Calls on a finished scoped client.
+- Overlapping sibling scopes.
+- A child scope started while its parent has pending queries.
+- Parent queries while a child is active.
+
+If a callback finishes with work pending, the adapter waits for that work and
+rolls back.
+
+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
+can still run independent queries on other connections.
+
+Your application remains responsible for raw driver calls and separately
+constructed adapters.
+
+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.
+
+## Execute without a bound client
 
 The standalone functions remain useful when the adapter varies by call or a
 small module does not need a bound client:
@@ -477,6 +550,8 @@ const result = await execute(query, adapter)
 const rows = await executeRows(readQuery, adapter)
 ```
 
+### Result fields
+
 | Result field   | Adapter type                         | Contract                                                                              |
 | -------------- | ------------------------------------ | ------------------------------------------------------------------------------------- |
 | `rows`         | `readonly Record<string, unknown>[]` | Key by rendered aliases; Qubu returns the decoded `readonly TRow[]`                   |
@@ -489,11 +564,15 @@ The last three fields are optional. For example, an adapter can map PostgreSQL
 `changes` and `lastInsertRowid`. Omit a fact that the selected driver cannot
 report accurately. Qubu does not derive mutation metadata from returned rows.
 
+### Dialect overrides and errors
+
 The adapter's `dialect` becomes the default for standalone and bound execution.
 A `dialect` in the execution options overrides that rendering policy. Qubu
 passes `signal`, `queryKind`, and `resultShape` to the adapter without changing
-them. The adapter decides whether and how its driver supports cancellation.
-Driver errors pass through unchanged. Decoder failures become a
+them.
+
+The adapter decides whether and how its driver supports cancellation. Driver
+errors pass through unchanged. Decoder failures become a
 `ResultDecodingError` that identifies the row and field without exposing the
 raw value.
 

package/docs/getting-started.md

@@ -1,6 +1,6 @@
 # Getting started
 
-> Define a typed table, build one parameterized query, and inspect the exact SQL before connecting a driver.
+> Define a table and inspect your first query’s SQL and parameters.
 
 ## Install Qubu
 
@@ -13,10 +13,9 @@ pnpm add qubu
 Import query-building functions from the package root. Qubu does not need a
 database connection to construct or render a query.
 
-The examples use the same order as the rendered statement: projection, `FROM`,
-then `WHERE`, ordering, grouping, and pagination. `select()` still accepts
-independent clauses in any order, which lets reusable values be composed, but
-keeping the final call in SQL order makes the query easy to scan and repair.
+The examples write clauses in SQL order so the query is easy to scan.
+`select()` also accepts independent clauses in any order and puts them in SQL
+order when rendering.
 
 ## Define a table
 
@@ -38,10 +37,9 @@ nullable email column is inferred as `string | null` when selected.
 
 ## Build and render a query
 
-Pass a named projection and the final clauses to `select()` in SQL order. Qubu
-also accepts independent clause values in another order when composition needs
-it, then renders the normalized statement in SQL order. The example uses the
-`users` table from the previous section.
+Pass the fields you want to return as a named object, called the projection.
+Then add the clauses. This example uses the `users` table from the previous
+section.
 
 ```ts
 import { eq, from, render, select, where } from "qubu"
@@ -69,6 +67,8 @@ statement.parameters
 // [7]
 ```
 
+### Inspect the result type
+
 The selected row type is available on the query value:
 
 ```ts
@@ -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/better-auth.md

@@ -1,6 +1,8 @@
 # Better Auth
 
-> Derive Qubu-owned auth tables and run Better Auth through a transactional Qubu client.
+> Define auth tables with Qubu and connect Better Auth to a transactional Qubu client.
+
+## Install the integration
 
 Install the integration next to Qubu and Better Auth:
 
@@ -8,10 +10,15 @@ Install the integration next to Qubu and Better Auth:
 pnpm add qubu @qubu/better-auth better-auth
 ```
 
-Define the Better Auth options once. The schema derivation reads Better Auth's
-resolved public metadata, so core tables, renamed models and fields, additional
-fields, plugin tables, references, unique constraints, and compound indexes all
-participate.
+## Define the auth schema
+
+Define the Better Auth options once. Qubu derives its schema from Better Auth’s
+resolved public metadata, including:
+
+- Core tables and renamed models or fields.
+- Additional fields and plugin tables.
+- References and unique constraints.
+- Compound indexes.
 
 ```ts
 import { betterAuth } from "better-auth"
@@ -44,6 +51,8 @@ export const auth = betterAuth({
 migration-plan, and DDL workflows. The adapter's Better Auth `createSchema`
 hook emits a TypeScript module that reconstructs the same Qubu-owned metadata.
 
+## Database requirements
+
 The package never imports PostgreSQL, MySQL, or SQLite drivers. It executes
 through Qubu's query and transaction boundaries. PostgreSQL and SQLite use one
 limited mutation statement for atomic consume and guarded increment operations;
@@ -51,6 +60,8 @@ MySQL locks one selected row inside the Qubu-owned transaction. A client without
 transaction support, or a dialect other than PostgreSQL, MySQL, or SQLite, is
 rejected during adapter construction.
 
+## Enum limitation
+
 Better Auth enum metadata is currently rejected because Qubu cannot preserve
 the closed value set as a portable column without adding a database constraint.
 The error includes the model and field path instead of silently widening it to

package/docs/guides/compose-queries.md

@@ -1,6 +1,6 @@
 # Compose queries
 
-> Reuse a query's inferred row shape as a typed source for CTEs, derived tables, subqueries, and set operations.
+> Reuse a query as a CTE, a derived table, or a subquery, and combine query results.
 
 ## Turn a query into a CTE
 
@@ -28,6 +28,8 @@ 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.
 
+### Use a CTE in a mutation
+
 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()`:
@@ -66,11 +68,20 @@ const numbers = recursiveCte("numbers", select({ value: cast(value(1), integer()
 const query = select({ value: numbers.value }, withCte(numbers), from(numbers))
 ```
 
-The anchor names the fields, application types, nullability, and SQL domains
-that the returned source exposes. The member must project those same fields
-with compatible types. Give bound anchor values an explicit SQL type with
+The anchor defines the fields the CTE returns:
+
+- Field names.
+- Application types.
+- Nullability.
+- SQL domains.
+
+The recursive member must select the same fields with compatible types.
+
+Give bound anchor values an explicit SQL type with
 `cast()` when the database cannot infer it from surrounding columns; PostgreSQL
-requires this for recursive CTE anchors. Qubu renders `WITH RECURSIVE`, an
+requires this for recursive CTE anchors.
+
+Qubu renders `WITH RECURSIVE`, an
 explicit relation column list, and `anchor UNION ALL member`; ordinary and
 recursive CTEs can share one `withCte()` clause.
 
@@ -117,7 +128,9 @@ const query = select(
 `scalar()` throws at runtime when the query selects more than one field. Its
 type is the selected field's value type, widened with `null` when the query may
 return no rows. An ordinary select and `fetchFirst(1)` are both nullable: the
-limit proves at most one row, not that a row exists. A source-free select such
+limit proves at most one row, not that a row exists.
+
+A source-free select such
 as `select({ value: value(42) })` is known to produce exactly one row.
 
 Qubu does not treat an arbitrary predicate as proof of exactness. Use
@@ -163,9 +176,8 @@ code.
 ## Constrain a reusable fragment by required fields
 
 Use `TableLike` when a fragment requires a physical table and `SourceLike`
-when aliases, CTEs, derived tables, or custom sources are also valid. Both are
-lower-bound constraints: the source may contain additional fields, and the
-generic function retains its exact source identity.
+when aliases, CTEs, derived tables, or custom sources are also valid. Both allow the source to contain additional fields. The generic function
+retains the source’s exact identity.
 
 For an application-level requirement, describe the required JavaScript row:
 

package/docs/guides/drizzle.md

@@ -123,9 +123,14 @@ override.
 ## Runtime metadata
 
 Each dialect adapter maps Qubu storage descriptors to its own Drizzle builders.
-It also transfers concrete defaults, generated expressions, common primary and
-unique constraints, checks, foreign keys, and indexes. Native storage must
-belong to the selected dialect:
+It also transfers:
+
+- Concrete defaults and generated expressions.
+- Common primary and unique constraints.
+- Checks and foreign keys.
+- Indexes.
+
+Native storage must belong to the selected dialect:
 
 ```ts
 import { nativeColumn, schema, table } from "qubu"

package/docs/guides/extensions/dialects.md

@@ -1,6 +1,6 @@
 # Add a dialect policy
 
-> Change identifiers, placeholders, pagination, or cast targets at the rendering boundary without changing portable query construction.
+> Customize how Qubu renders SQL for your driver.
 
 Use `createDialect()` when the query is portable but the driver changes
 identifiers, placeholders, or pagination:

package/docs/guides/extensions/overview.md

@@ -1,6 +1,6 @@
 # Extend Qubu
 
-> Choose an extension boundary when the built-in API does not cover a driver-specific or uncommon SQL feature.
+> Add SQL features that Qubu’s built-in helpers do not cover.
 
 Qubu extensions are values that render SQL and carry the metadata later
 composition needs. Choose the page that matches the thing you are adding:

package/docs/guides/extensions/sources-and-clauses.md

@@ -1,6 +1,6 @@
 # Add sources and clauses
 
-> Publish a custom SQL clause or relation while preserving parameter order and source-scope checks.
+> Add a SQL clause or table-like source that works with Qubu’s query checks.
 
 ## Add a custom clause
 
@@ -67,9 +67,13 @@ render(query)
 ```
 
 `identity` is the source-scope key; `reference` is the SQL qualifier used by
-the generated columns. A nullable column remains nullable intrinsically, and a
+the generated columns.
+
+A nullable column remains nullable, and a
 `leftJoin(rows, ...)` adds outer-join nullability to every selected row
-column. Render the complete relation in the producer and bind values with
+column.
+
+Render the complete relation in the producer and bind values with
 `context.parameter()`; the normal renderer preserves parameter order.
 
 ## Read next

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

@@ -1,6 +1,6 @@
 # Add typed expressions
 
-> Extend Qubu with expressions that retain source, nullability, result, and SQL-domain metadata.
+> Build custom expressions that preserve result types and query checks.
 
 ## Build expressions from public helpers
 
@@ -47,30 +47,44 @@ const nameAsCitext = cast(users.name, citext)
 ```
 
 The first three `column` type arguments are output, insert, and update values;
-the fourth is the SQL domain. The `text` equality and ordering groups make the
-custom domain compatible with `SqlText`. Use a distinct group when cross-type
-comparison is not portable. `castType` also makes this definition a cast
-target; its SQL text is emitted verbatim, so keep it in trusted extension code.
+the fourth is the SQL domain.
+
+The `text` equality and ordering groups make the custom domain compatible with `SqlText`. Use a distinct group when cross-type
+comparison is not portable.
+
+### Use the definition as a cast target
+
+`castType` also makes this definition a cast target. Its SQL text is emitted
+unchanged, so keep it in trusted extension code.
+
 Definitions with schema flags are not accepted as cast targets because cast
 nullability comes from the operand and write flags have no cast meaning.
 
+### Type individual expressions
+
 Declare result domains at other extension boundaries too:
 
 ```ts
 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()")
 ```
 
-`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.
+Choose the helper for the operation:
+
+- `typedCall()` preserves source requirements from its arguments.
+- `typedCast()` supplies a cast target when no reusable definition describes
+  it. It preserves operand nullability and source metadata, and emits the
+  supplied type name unchanged.
+- `typedValue()` binds a parameter and declares its runtime SQL domain for
+  the adapter. It does not choose a JavaScript result decoder; schema columns
+  carry decoder metadata separately.
+- `unsafeExpression()` emits its string unchanged. Use it only when the other
+  helpers cannot express the syntax.
 
 The lower-level forms also expose the SQL domain in their generic lists:
 `call<Output, Name, Arguments, NullableFrom, SqlType>()` and
@@ -78,7 +92,7 @@ The lower-level forms also expose the SQL domain in their generic lists:
 argument or nullability types in its own generic signature.
 
 Untyped `column()`, `value()`, `call()`, and custom expressions use
-`SqlUnknown`, which stays permissive for backward compatibility. Declaring a
+`SqlUnknown`, which allows composition without SQL-domain checks. Declaring a
 known domain opts the extension into incompatible-operation errors. See
 [SQL semantic types](../../sql-semantic-types.md) for the capability model and
 its limits.

package/docs/guides/extensions/unsafe-syntax.md

@@ -14,12 +14,16 @@ const query = select({
 })
 ```
 
-Keep raw identifiers and values out of the string. Prefer a typed custom
-fragment when the syntax will be reused. Use the [`sql` template
-tag](../sql-templates.md) when fixed trusted syntax needs bound runtime values
-or existing Qubu fragments. Keep dynamic SQL text on `unsafeExpression()` and
-runtime identifiers on `identifier()` or `qualifiedIdentifier()` from
-`qubu/core`.
+## Choose the right helper
+
+Keep raw identifiers and values out of the string:
+
+- Use a typed custom fragment for syntax you will reuse.
+- Use the [`sql` template tag](../sql-templates.md) for fixed trusted syntax
+  with bound values or existing Qubu fragments.
+- Use `unsafeExpression()` for trusted dynamic SQL text.
+- Use `identifier()` or `qualifiedIdentifier()` from `qubu/core` for runtime
+  identifiers.
 
 Read [Dialects and execution](../../dialects-and-execution.md) for the boundary
 between rendering and driver behavior. Read [Add typed