qubu 0.6.1 → 0.6.3

package/docs/migrations/adapters.md

@@ -1,45 +1,67 @@
 # Adapter capability profiles
 
-> Select a migration adapter from capabilities proven by its driver and environment, not from dialect name alone.
+> Choose a migration adapter based on what its driver and environment have been tested to support.
 
-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
+
+Qubu validates program structure and adapter capabilities. It trusts the SQL
+you supply, including SQL conditions, and does not parse it for safety.
+
+Migration SQL must preserve the executor’s transactions, connection settings,
+and journal state. For example, an explicit `COMMIT` can apply schema changes
+without their journal record, breaking the executor’s recovery guarantees.
+
 ## 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.
+- A journal and migrator lease stored in the database.
+- An atomic update of the applied record and journal head.
+- A recovery-required result when a commit’s outcome is uncertain.
+
+Parameter kinds are:
 
-All five support every current tagged parameter kind (`null`, `boolean`,
-`string`, `number`, `bigint`, `bytes`, and `json`), a database journal and
-lease, atomic applied-record/head advancement, and recovery-required commit
-ambiguity classification. Support still depends on the artifact's server,
-feature, transaction, and lock constraints.
+- `null` and `boolean`.
+- `string` and `number`.
+- `bigint` and `bytes`.
+- `json`.
+
+The artifact’s server, feature, transaction, and lock requirements must still
+match the adapter.
+
+### Unavailable profiles
 
 These exported profiles are unavailable and must not be passed to the
 executor:
@@ -53,6 +75,8 @@ executor:
 Unavailable profiles expose `reason` and `missingCapabilities`; they do not
 fall back to a generic executor.
 
+### Configure libSQL inspection
+
 For libSQL, let the migration entrypoint exclude all reserved journal objects
 during strict inspection:
 
@@ -68,3 +92,44 @@ 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()`.
+
+### Supported conditions
+
+Schema fingerprint and property preconditions are checked against the embedded
+before snapshot. Preparation verifies its physical facts, and the batch
+asserts that the catalog still matches.
+
+Object-presence and scalar SQL checks run inside the batch. Postconditions
+must use either:
+
+- Object-presence or absence checks without fingerprints.
+- Scalar SQL checks returning `1`.
+
+Unsupported conditions and multiple phases are rejected.
+
+SQL is passed to the driver without safety validation. Each program entry
+must follow the driver’s statement contract.
+
+### Crashes and uncertain outcomes
+
+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/artifacts-and-policy.md

@@ -1,10 +1,12 @@
 # Artifacts and approval policy
 
-> Review exactly what is authenticated and executable before an artifact enters a repository.
+> Review migration files and approve the exact operations they will run.
 
-Qubu has two strict artifact kinds. An executable migration contains a reviewed
-plan and authoritative program. A verified baseline records an observed schema
-without pretending that historical SQL ran.
+An artifact is a versioned migration file. Qubu supports two kinds:
+
+- An **executable migration** contains a reviewed plan and the program to run.
+- A **verified baseline** records the observed schema as a starting point. It
+  does not claim that historical SQL ran through Qubu.
 
 ## Published formats
 
@@ -38,18 +40,30 @@ An executable artifact records:
 - operation-scoped approvals and custom-program provenance;
 - artifact provenance and `artifactDigest`.
 
-The program—not `emitMigrationPlan(...).sql` and not joined statement text—is
-the execution authority. Each phase declares its position, dependencies,
-transaction and lock requirements, preconditions, postconditions, and ordered
-statements. Each statement declares its operation ID, dependencies, SQL, and
-tagged parameters.
+The executor runs the program stored in the artifact. The SQL preview from
+`emitMigrationPlan(...).sql` is not an executable artifact.
+
+Each phase declares:
+
+- Its position and dependencies.
+- Transaction and lock requirements.
+- Preconditions and postconditions.
+- Ordered statements.
+
+Each statement declares its operation ID, dependencies, SQL, and tagged parameters.
 
 ### Baseline artifact schema
 
-A baseline records `id`, sequence and parent lineage, encoding descriptors,
-dialect and optional constraints, one verified snapshot descriptor,
-`verifiedAt`, provenance, optional operator metadata, and `artifactDigest`. It
-has no migration plan, program, or SQL digest.
+A baseline records:
+
+- `id`, sequence, and parent lineage.
+- Encoding descriptors.
+- Dialect and optional constraints.
+- One verified snapshot descriptor and `verifiedAt`.
+- Provenance and optional operator metadata.
+- `artifactDigest`.
+
+It has no migration plan, program, or SQL digest.
 
 Artifact IDs are stable identities, not repository order. Sequence and parent
 digest establish the linear chain. Renumbering therefore changes lineage and
@@ -57,21 +71,36 @@ the artifact digest.
 
 ## Canonical bytes and digest domains
 
-`encodeCanonical()` sorts object keys by Unicode code-point order, preserves
-array order, emits compact JSON as UTF-8, normalizes `-0` to `0`, rejects
-non-finite numbers, and adds one LF at EOF. `digestCanonical()` prefixes those
-bytes with the UTF-8 bytes for:
+`encodeCanonical()` produces a repeatable byte representation:
+
+- Sort object keys by Unicode code-point order.
+- Preserve array order.
+- Emit compact UTF-8 JSON.
+- Normalize `-0` to `0` and reject non-finite numbers.
+- End the file with one line feed.
+
+`digestCanonical()` prefixes those bytes with the UTF-8 bytes for:
 
 ```text
 qubu:migrate:v1:<domain>\0
 ```
 
-The five domains are `artifact`, `baseline`, `migration-plan`,
-`migration-program`, and `schema-snapshot`. Domain separation prevents equal
-JSON values used for different purposes from sharing an integrity identity.
+The digest identifies its purpose through one of five domains:
+
+- `artifact`.
+- `baseline`.
+- `migration-plan`.
+- `migration-program`.
+- `schema-snapshot`.
+
+The prefix ensures that identical JSON used for different purposes gets
+different digests.
+
 Operational digests have the form `sha256:` plus 64 lowercase hexadecimal
 digits and are recomputed while sealing or decoding.
 
+### Fingerprints and integrity digests
+
 Snapshot and plan `fingerprint` APIs are deterministic FNV-1a64 change
 detectors. They remain useful for caches and fixture assertions, but they are
 not cryptographic integrity evidence and are never valid journal heads,

package/docs/migrations/index.md

@@ -1,8 +1,8 @@
 # Migration operations
 
-> Choose the package entrypoint that owns each migration concern without pulling database or Node.js behavior into pure schema code.
+> Find the packages and guides for planning, running, and recovering migrations.
 
-Qubu migrations are split across explicit ownership boundaries:
+These packages handle different parts of a migration:
 
 | Owner           | Imports                                                                                                                     | Responsibility                                                                                                               |
 | --------------- | --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
@@ -21,6 +21,8 @@ import { emitMigrationPlan } from "@qubu/migrate/ddl"
 import { compileMigrationProgram, sealExecutableArtifact } from "@qubu/migrate/artifact"
 ```
 
+## Choose an import
+
 The `@qubu/migrate` root intentionally exports only format/version constants
 and the central plan and artifact types. Import behavior from its focused
 entrypoint:
@@ -46,12 +48,17 @@ entrypoint:
 | `@qubu/migrate/bootstrap/sqlite`   | Plan a fresh SQLite schema through the normal compiler                                                                        |
 | `@qubu/migrate/testing`            | Test adapter capabilities and deterministic failure boundaries                                                                |
 
-Start with [Artifacts and approval policy](artifacts-and-policy.md) when
-reviewing a migration format. Check [Adapter capability
-profiles](adapters.md), use [Command line operations](operations.md) to
-configure an application, then keep [Recovery and reconciliation](recovery.md)
-with the deployment runbook. [Lotta Games adoption](lotta-adoption.md) records
-the downstream cutover boundary and current combo-matrix blocker.
+## Choose a guide
+
+- [Artifacts and approval policy](artifacts-and-policy.md): review migration
+  files and approve operations.
+- [Adapter capability profiles](adapters.md): choose a supported driver.
+- [Command line operations](operations.md): configure and use the CLI.
+- [Recovery and reconciliation](recovery.md): handle interrupted migrations.
+- [Lotta Games adoption](lotta-adoption.md): review the downstream cutover
+  plan and combo-matrix release blocker.
+
+## Select a built-in dialect
 
 Choose the dialect-specific bootstrap entrypoint when using a built-in dialect:
 

package/docs/migrations/lotta-adoption.md

@@ -1,11 +1,13 @@
 # Lotta Games adoption
 
-> Replace Lotta's provisional runner with Qubu while preserving product-owned deployment policy and historical truth.
+> Move Lotta to Qubu migrations while keeping deployment decisions in Lotta.
 
 Adopt the released `@qubu/migrate`, `@qubu/cli`, and libSQL migration entrypoint
 as a hard cutover. Do not add an upstream decoder for Lotta's provisional JSON,
 FNV artifact digests, journal, or broad unsafe flags.
 
+## Establish the starting state
+
 Before changing downstream state, inspect every environment for a provisional
 journal or baseline row. Regenerate unreleased migrations in the Qubu artifact
 format. For an existing database, create one standard baseline only after strict
@@ -13,6 +15,8 @@ live introspection matches the intended Qubu snapshot. That baseline records a
 verified starting state; it does not claim that old migrations ran through
 Qubu.
 
+## Keep deployment policy in Lotta
+
 Keep these concerns in Lotta:
 
 - Turso credentials and environment selection;
@@ -30,10 +34,17 @@ databases with `schema bootstrap`; keep connection PRAGMAs in the test harness.
 > Drizzle history. A verified baseline is the handoff from historical state to
 > Qubu lineage.
 
-The downstream verification set should cover a fresh bootstrap, an already
-baselined database, a no-op deploy, pending migrations in both deployment
-timing modes, drift refusal, concurrent invocation, rollback, and explicit
-recovery.
+## Verify the cutover
+
+Cover these scenarios downstream:
+
+- A fresh bootstrap.
+- An already baselined database.
+- A deploy with no pending migrations.
+- Pending migrations in both deployment timing modes.
+- Refusal when the schema has drifted.
+- Concurrent migration attempts.
+- Rollback and explicit recovery.
 
 ## Combo-matrix release blocker
 

package/docs/migrations/operations.md

@@ -1,6 +1,6 @@
 # Command line operations
 
-> Configure, inspect, baseline, and apply a complete migration chain with stable non-interactive behavior.
+> Configure the CLI, inspect migration status, and apply a migration chain.
 
 Install the CLI, migration library, and one verified migration adapter. For a
 libSQL application:
@@ -9,11 +9,16 @@ libSQL application:
 pnpm add @qubu/cli @qubu/migrate @qubu/adapter-libsql @libsql/client
 ```
 
-The `qubu` binary is implemented with `@alloc/cmd-ts`. It loads
-`qubu.config.js` by default; `--config <path>` selects another application-owned
-module. Every command accepts `--format human|json` (default `human`) and
-`--non-interactive`. Commands do not prompt today; `--non-interactive` records
-the deployment contract and missing explicit input still fails.
+The `qubu` command loads `qubu.config.js` by default. Use `--config <path>` to
+select another configuration module.
+
+Every command accepts:
+
+- `--format human|json`, defaulting to `human`.
+- `--non-interactive`, to state that the command must run without prompts.
+
+Commands currently never prompt. Missing required input fails even without
+`--non-interactive`.
 
 ## Configuration
 
@@ -72,9 +77,13 @@ working directory.
 | `qubu migrate reconcile <attempt-id> --outcome applied\|rolled_back --reason <text>`                | Runs application-owned verification, then records the explicit outcome                                                                      | Requires `verifyReconciliation` in config; no automatic inference                                              |
 | `qubu schema bootstrap [--approve <operation-id=reason>...] [--dry-run]`                            | Plans an empty SQLite or PostgreSQL snapshot through diff/plan/program; executes through the normal executor unless dry-run                 | Rejects other dialects; unsafe or incomplete facts still require exact approvals or custom programs            |
 
-JSON output is stable, newline-terminated, recursively key-sorted, and redacts
-credential-like keys and credentials or secrets embedded in URLs. Human output
-is deliberately terse. Signals propagate through adapters; an abort exits 130.
+## Output and exit codes
+
+JSON output has stable, recursively sorted keys and ends with a newline. It
+redacts credential-like keys and secrets embedded in URLs. Human output is
+brief.
+
+Signals pass through adapters. An abort exits with code 130.
 
 | Exit | Meaning                                                                       |
 | ---: | ----------------------------------------------------------------------------- |
@@ -94,14 +103,19 @@ snapshot. Logical IDs help reporting but do not prove equality. Objects not
 owned by the managed snapshot are returned separately as `unmanagedObjects`;
 Qubu journal objects are excluded by migration snapshot readers.
 
+### Bootstrap a fresh database
+
 `schema bootstrap` is for a fresh SQLite database or a fresh PostgreSQL schema.
 It produces the same reviewed plan, versioned program, sealed artifact, and
-executor path as a migration. A complete PostgreSQL snapshot retains standalone
-enums as authoritative objects; bootstrap creates each enum before a table that
-uses it as a native column type. SQLite inline constraints are compiled into
-table creation, while table rebuilds are explicit phases with copy/postcondition
-checks. Session settings such as SQLite PRAGMAs remain in the application or
-adapter setup.
+execution path as a migration.
+
+Database-specific behavior:
+
+- PostgreSQL bootstrap creates standalone enums before tables that use them
+  as native column types. The complete target snapshot defines those enums.
+- SQLite inline constraints are included in table creation. Table rebuilds
+  use explicit phases with data-copy and postcondition checks.
+- Session settings, such as SQLite PRAGMAs, stay in application or adapter setup.
 
 Use the reviewed complete snapshot directly as the PostgreSQL target:
 

package/docs/migrations/recovery.md

@@ -1,12 +1,12 @@
 # Recovery and reconciliation
 
-> Stop after an ambiguous attempt, prove the live outcome, and repair journal lineage without replaying SQL.
+> Verify what happened after an uncertain migration and record the outcome before continuing.
 
-The journal has one versioned metadata row with an atomic head, immutable
-applied artifact records, mutable attempts, phase/statement checkpoints, and
-append-only reconciliation records. Adapter implementations store it in the
-same database and reserve `__qubu_migration_`-prefixed objects from managed
-schema inspection.
+The journal records migration progress in the same database as the schema.
+Its head is the digest of the last applied artifact.
+
+Adapters reserve objects prefixed with `__qubu_migration_` and exclude them
+from managed schema inspection. The journal contains these records:
 
 | Record           | Fields and invariant                                                                                           |
 | ---------------- | -------------------------------------------------------------------------------------------------------------- |
@@ -45,13 +45,29 @@ 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
-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.
+Before applying migrations, the executor:
+
+1. Verifies the entire artifact repository.
+2. Opens one migration session and checks its capabilities.
+3. Acquires the migrator lease.
+4. Verifies that the journal matches the start of the repository chain.
+5. Checks the live before-snapshot digest.
+
+For each pending artifact, it:
+
+1. Creates an attempt record.
+2. Runs phases in order, checking their preconditions and postconditions.
+3. Writes durable checkpoints.
+4. Appends the applied history and updates the head only if it still matches
+   the expected parent.
+
+Cleanup releases the DDL lock, then the migrator lease, then the 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
@@ -70,10 +86,17 @@ must be resolved by the renderer or explicit custom program before sealing.
 Transactions are phase-scoped. Do not infer that an earlier committed phase
 will roll back because a later phase fails.
 
-Errors use stable codes: `validation`, `policy`, `drift`, `concurrency`,
-`capability`, `definite-rollback`, `uncertain-outcome`, `recovery-required`,
-`aborted`, and `adapter`. Context may include artifact, attempt, phase, and
-statement identifiers. Persisted failures omit SQL parameters and credentials.
+### Errors and retries
+
+Errors use stable codes:
+
+- `validation`, `policy`, and `capability`.
+- `drift` and `concurrency`.
+- `definite-rollback`, `uncertain-outcome`, and `recovery-required`.
+- `aborted` and `adapter`.
+
+Error context may identify the artifact, attempt, phase, and statement.
+Persisted failures omit SQL parameters and credentials.
 
 Do not automatically retry after any statement may have taken effect. Only an
 error explicitly marked `retry: "safe"`—normally validation or a failure proven

package/docs/query-model/fragments.md

@@ -1,6 +1,6 @@
 # Fragments and metadata
 
-> Build custom SQL from values while preserving the source, result, grouping, and capability facts that later composition checks.
+> Understand how SQL fragments carry the type information Qubu needs to check a query.
 
 ## A fragment has a renderer and metadata
 
@@ -39,9 +39,12 @@ Composition helpers keep the facts that their children already carry:
 | `groupBy()`                                                     | Record grouping expressions and the column dependencies they make available.                     |
 | `leftJoin()`                                                    | Add `NullableSourceMeta` for the joined source.                                                  |
 
-The type-level contract stays small. `OutputOf<T>` describes a result,
-`SqlTypeOf<T>` its SQL domain, `RequiresOf<T>` its required sources, and
-`NullabilityOf<T>` the sources that can make it null after an outer join.
+Use these types to read a fragment’s metadata:
+
+- `OutputOf<T>`: the result type.
+- `SqlTypeOf<T>`: the SQL domain.
+- `RequiresOf<T>`: the sources it requires.
+- `NullabilityOf<T>`: the sources that can make it null after an outer join.
 
 Qubu does not infer every SQL rule. Grouping checks use declared dependencies,
 and functional dependencies from database keys are handled where the source
@@ -51,7 +54,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,10 +76,34 @@ render(query)
 // parameters: [7, '%Ada%']
 ```
 
+### Give parameters a SQL domain
+
+Optional SQL domains are stored in `parameterSqlTypes`. Each entry matches
+the parameter at the same position:
+
+```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.
 
+### Compose SQL templates
+
 The public [`sql` template tag](../guides/sql-templates.md) uses the same
 renderer. Ordinary substitutions call `context.parameter()`, while expression,
 query, and fragment substitutions call back into the active render context.

package/docs/query-model/result-shapes.md

@@ -1,6 +1,6 @@
 # Result shapes and cardinality
 
-> Choose a projection, understand how joins change its nullability, and check when a nested query can return no row.
+> Choose result fields and understand when a join or subquery can make them null.
 
 ## Name the selected row
 
@@ -27,7 +27,7 @@ type Row = typeof query.row
 ```
 
 The projection key also names the SQL output column. Use explicit fields for a
-shaped result. Reserve `all(source)` for a whole-source result contract. It
+shaped result. Use `all(source)` when you want every source column. It
 expands to named columns, so the SQL columns and inferred row keys stay aligned:
 
 ```ts

package/docs/query-model/source-scope.md

@@ -1,6 +1,6 @@
 # Source scope
 
-> Keep each column tied to the table, alias, CTE, or derived source that provides it; use this page to fix scope errors and intentional correlations.
+> Learn why a column must belong to a source in the query, and how to refer to an enclosing query.
 
 A column carries the identity of the source that provides it. Qubu checks that
 identity when you assemble a query. The source must appear in `FROM` or a join
@@ -118,7 +118,9 @@ const query = select({ value: entries.value }, from(entries), where(eq(entries.k
 ```
 
 `identity` is the type-level source key. `reference` is the SQL qualifier used
-by the generated columns. The nullable `value` column stays nullable, and a
+by the generated columns.
+
+The nullable `value` column stays nullable, and a
 `leftJoin()` adds outer-join nullability to every selected column from
 `entries`.
 
@@ -128,7 +130,7 @@ keeps those values in placeholder order.
 ## Correlate an inner query
 
 Use `correlate()` when an inner query intentionally reads a source from its
-enclosing query. The provision changes type checking but emits no SQL:
+enclosing query. `correlate()` changes type checking but emits no SQL:
 
 ```ts
 import { correlate, crossJoin, eq, from, integer, lateral, select, table, where } from "qubu"