qubu 0.6.2 → 0.6.3

package/dist/mysql.d.mts

@@ -1,5 +1,5 @@
 import { Cr as onDuplicateKeyUpdate, Pt as Dialect, Sr as incoming, br as IncomingIdentity, xr as OnDuplicateKeyUpdateClause, yr as IncomingColumns } from "./types-Dqr4o2I1.mjs";
 //#region src/dialects/mysql.d.ts
-declare function mysqlDialect(): Dialect<"row-locking" | "on-duplicate-key-update" | "json">;
+declare function mysqlDialect(): Dialect<"json" | "row-locking" | "on-duplicate-key-update">;
 //#endregion
 export { type IncomingColumns, type IncomingIdentity, type OnDuplicateKeyUpdateClause, incoming, mysqlDialect, onDuplicateKeyUpdate };

package/dist/postgres.d.mts

@@ -4,7 +4,7 @@ import { Ad as MetadataOf, Dr as UpdateFromClause, Gu as ExpressionWithOutput, K
  * PostgreSQL's only core rendering difference is positional parameters. PostgreSQL-specific
  * expressions and clauses should remain separate modules.
  */
-declare function postgresDialect(): Dialect<"row-locking" | "json" | "on-conflict" | "ilike" | "update-from">;
+declare function postgresDialect(): Dialect<"json" | "ilike" | "on-conflict" | "row-locking" | "update-from">;
 /** PostgreSQL's case-insensitive pattern-match operator. */
 declare function ilike<TLeft extends ExpressionWithOutput<string>, R extends Operand<string>>(left: TLeft & ComparisonValidation<TLeft, R, "ILIKE">, pattern: R): SchemaExpression<ResultMeta<boolean, ((MetadataOf<TLeft & SqlCapabilityValidation<(MetadataOf<TLeft> extends (infer T) ? T extends MetadataOf<TLeft> ? T extends {
   readonly kind: "result";

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,10 +77,10 @@ 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.
 
-When present, `request.statement.parameterSqlTypes` is an optional sidecar
-aligned with `statement.parameters`. Adapters can pass each domain to their
+`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`.
 
@@ -143,12 +143,14 @@ 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
 
@@ -434,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
@@ -465,11 +471,16 @@ 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.
+
+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
@@ -503,20 +514,32 @@ 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 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.
+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:
 
@@ -527,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[]`                   |
@@ -539,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

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,13 +47,21 @@ 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
@@ -66,13 +74,17 @@ 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 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.
+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
@@ -80,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

package/docs/guides/json.md

@@ -2,7 +2,9 @@
 
 > 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
+## Nest query results
+
+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:
 
@@ -57,45 +59,63 @@ const query = select(
 //        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.
+### Empty results and row limits
+
+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.
 
-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.
+An object query must be known to return at most one row. An unconditional
+`fetchFirst(1)` or `fetchFirst(0)` proves that limit; a conditional limit does not.
 
-### Preserve ordering and logical values
+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.
 
-Nested arrays retain explicit ORDER BY and pagination. Tied sort keys retain
+### Preserve ordering
+
+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.
+`DISTINCT` ordering must use the same expressions as the selection. Without an
+`ORDER BY`, array order is unspecified.
+
+### Supported databases
 
 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.
 
+### Decode nested values
+
 Built-in column domains decode to their declared types, including bigint,
-Uint8Array, Date, boolean, and nested JSON. Qubu transports precision-sensitive
+`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
+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;
+Custom `mapResult()` and column decoders receive the JSON transport value as
+`unknown`. The value may be:
+
+- A bigint or decimal string.
+- A hexadecimal binary string.
+- A serialized JSON string.
+- An ordinary JSON scalar.
+
+The custom decoder converts it to the declared 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
+Use a structured `jsonPath()` when a query needs a scalar or an existence check
 inside a JSON document:
 
 ```ts
@@ -135,7 +155,7 @@ interpolating caller-provided SQL.
 ## Understand missing values
 
 Scalar reads return SQL NULL when the path is missing, contains JSON null, or
-resolves to another JSON scalar type. jsonExists() returns true for a present
+resolves to another JSON scalar type. `jsonExists()` returns true for a present
 JSON null, false for a missing path, and false when the document itself is SQL
 NULL.
 
@@ -143,16 +163,21 @@ These rules keep path existence separate from extraction nullability.
 
 ## Check dialect support
 
-The standard dialect emits SQL/JSON JSON_VALUE and JSON_EXISTS syntax.
+The standard dialect emits SQL/JSON `JSON_VALUE` and `JSON_EXISTS` syntax.
 PostgreSQL, MySQL, and SQLite use their native JSON policies. The current
 policies require PostgreSQL 12 or newer, MySQL 8.0.21 or newer, and SQLite JSON
 functions. An application-created dialect must provide a JSON renderer.
 
 ## Know the current limits
 
-JSON paths cover deterministic key and index traversal. Wildcards, filters,
-recursive descent, JSON-returning extraction, document mutation, and row
-expansion remain dialect-specific extensions.
+JSON paths follow explicit keys and indexes. These features require
+dialect-specific extensions:
+
+- Wildcards and filters.
+- Recursive descent.
+- Extraction that returns JSON.
+- Document mutation.
+- Row expansion.
 
 For the SQL domain and nullability rules behind JSON columns, read
 [SQL semantic types](../sql-semantic-types.md).