qubu 0.6.2 → 0.7.0

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:
@@ -39,19 +41,26 @@ entrypoint:
 | `@qubu/migrate/repository`         | Verify a complete artifact chain and its journal prefix                                                                       |
 | `@qubu/migrate/journal`            | Implement or inspect the storage-neutral journal contract                                                                     |
 | `@qubu/migrate/executor`           | Apply artifacts and reconcile uncertain attempts                                                                              |
-| `@qubu/migrate/baseline`           | Verify and record the initial non-executable baseline                                                                         |
+| `@qubu/migrate/baseline`           | Capture, preflight, and accept a reviewed live schema as the initial non-executable baseline                                  |
 | `@qubu/migrate/status`             | Inspect pending work, drift, requirements, and interrupted attempts                                                           |
 | `@qubu/migrate/bootstrap`          | Prepare a fresh schema diff and expose shared bootstrap types; accepts a caller-supplied `SchemaDialect` for generic planning |
 | `@qubu/migrate/bootstrap/postgres` | Plan a fresh PostgreSQL schema through the normal compiler                                                                    |
 | `@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.
+- [Adopt an existing database](adopt.md): capture, review, and accept the live
+  starting schema before applying separate migrations.
+- [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/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
 
@@ -21,7 +26,7 @@ Export a typed config and keep credentials inside the adapter factory:
 
 ```ts
 import { createClient } from "@libsql/client"
-import { libsqlMigrationAdapter, readLibsqlMigrationSnapshot } from "@qubu/adapter-libsql/migration"
+import { migrationAdapter, readMigrationSnapshot } from "@qubu/adapter-libsql/migration"
 import { defineConfig } from "@qubu/cli/config"
 import snapshot from "./schema.snapshot.js"
 
@@ -33,8 +38,8 @@ export default defineConfig({
   snapshot,
   environment: "production",
   adapter: () =>
-    libsqlMigrationAdapter(createClient({ url }), {
-      readSnapshot: readLibsqlMigrationSnapshot,
+    migrationAdapter(createClient({ url }), {
+      readSnapshot: readMigrationSnapshot,
     }),
   provenance: { source: "my-service" },
 })
@@ -46,35 +51,40 @@ approvals, custom programs, renderer/server constraints, baseline operator
 metadata, and reconciliation proof. `artifacts` is resolved from the CLI
 working directory.
 
-| Field                                      | Required            | Meaning                                                                                      |
-| ------------------------------------------ | ------------------- | -------------------------------------------------------------------------------------------- |
-| `artifacts`                                | yes                 | Artifact directory, relative to the command working directory unless absolute                |
-| `snapshot`                                 | one snapshot source | Snapshot value or sync/async factory                                                         |
-| `schema` + `snapshotFromSchema`            | one snapshot source | Application-owned conversion when the source is a Qubu `Schema`                              |
-| `adapter`                                  | database commands   | Sync/async factory returning a migration adapter                                             |
-| `approvals`                                | no                  | Sync/async operation policy; receives the operation, finding codes, and requested CLI reason |
-| `customPrograms`                           | no                  | Exact operation substitutions with execution requirements and provenance                     |
-| `renderer`, `serverVersion`, `constraints` | no                  | Renderer identity and target compatibility constraints                                       |
-| `provenance`                               | no                  | Artifact source/revision/actor/metadata; defaults to `{ source: "@qubu/cli" }`               |
-| `environment`                              | no                  | `development`, `test`, `staging`, or `production`; context only                              |
-| `baselineOperator`                         | no                  | JSON-safe operator metadata stored in a baseline                                             |
-| `verifyReconciliation`                     | reconcile only      | Application-owned proof of the selected live outcome                                         |
+| Field                                      | Required            | Meaning                                                                                             |
+| ------------------------------------------ | ------------------- | --------------------------------------------------------------------------------------------------- |
+| `artifacts`                                | yes                 | Artifact directory, relative to the command working directory unless absolute                       |
+| `snapshot`                                 | one snapshot source | Snapshot value or sync/async factory                                                                |
+| `schema` + `snapshotFromSchema`            | one snapshot source | Application-owned conversion when the source is a Qubu `Schema`                                     |
+| `adapter`                                  | database commands   | Sync/async factory returning a migration adapter, or an adoption-only adapter for baseline commands |
+| `approvals`                                | no                  | Sync/async operation policy; receives the operation, finding codes, and requested CLI reason        |
+| `customPrograms`                           | no                  | Exact operation substitutions with execution requirements and provenance                            |
+| `renderer`, `serverVersion`, `constraints` | no                  | Renderer identity and target compatibility constraints                                              |
+| `provenance`                               | no                  | Artifact source/revision/actor/metadata; defaults to `{ source: "@qubu/cli" }`                      |
+| `environment`                              | no                  | `development`, `test`, `staging`, or `production`; context only                                     |
+| `baselineOperator`                         | no                  | JSON-safe operator metadata stored in a baseline                                                    |
+| `verifyReconciliation`                     | reconcile only      | Application-owned proof of the selected live outcome                                                |
 
 ## Commands
 
-| Syntax                                                                                              | Reads or writes                                                                                                                             | Important failure behavior                                                                                     |
-| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| `qubu migrate create <id> [--approve <operation-id=reason>...] [--approved-by <actor>] [--dry-run]` | Verifies the full repository, plans from its embedded final snapshot, seals, then writes one canonical artifact unless dry-run              | Unknown operation IDs or missing exact approvals fail policy                                                   |
-| `qubu migrate verify`                                                                               | Strictly decodes and verifies every artifact and the complete chain                                                                         | Any malformed, tampered, forked, gapped, or mismatched artifact fails validation                               |
-| `qubu migrate status`                                                                               | Opens a session and lease; reports managed drift, unmanaged objects, pending artifacts, interrupted attempts, and incompatible requirements | Recovery, validation, drift, and capability policy are distinct failures                                       |
-| `qubu migrate apply [--dry-run]`                                                                    | Applies the complete verified pending chain; dry-run performs status/preflight only                                                         | It never limits discovery to Git-added or branch-diff files                                                    |
-| `qubu migrate baseline <id> --confirm <fact>... [--dry-run]`                                        | Without dry-run, strictly compares the live managed schema, initializes an empty journal, records baseline, then writes the artifact        | Requires an empty artifact repository and all seven exact confirmations; dry-run does not inspect the database |
-| `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            |
+| Syntax                                                                                              | Reads or writes                                                                                                                             | Important failure behavior                                                                                                 |
+| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `qubu migrate create <id> [--approve <operation-id=reason>...] [--approved-by <actor>] [--dry-run]` | Verifies the full repository, plans from its embedded final snapshot, seals, then writes one canonical artifact unless dry-run              | Unknown operation IDs or missing exact approvals fail policy                                                               |
+| `qubu migrate verify`                                                                               | Strictly decodes and verifies every artifact and the complete chain                                                                         | Any malformed, tampered, forked, gapped, or mismatched artifact fails validation                                           |
+| `qubu migrate status`                                                                               | Opens a session and lease; reports managed drift, unmanaged objects, pending artifacts, interrupted attempts, and incompatible requirements | Recovery, validation, drift, and capability policy are distinct failures                                                   |
+| `qubu migrate apply [--dry-run]`                                                                    | Applies the complete verified pending chain; dry-run performs status/preflight only                                                         | It never limits discovery to Git-added or branch-diff files                                                                |
+| `qubu migrate baseline-capture --out <path>`                                                        | Strictly reads live managed schema and writes a new candidate snapshot outside the artifact repository                                      | Strict inspection failures block capture; existing candidate files are not overwritten                                     |
+| `qubu migrate baseline <id> --candidate <path> [--confirm <fact>...] [--dry-run]`                   | Reinspects the reviewed candidate; acceptance records baseline then writes its artifact                                                     | Empty repository and adapter history required; acceptance requires seven confirmations; dry-run inspects without recording |
+| `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                        |
+
+## Output and exit codes
 
-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.
+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 +104,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:
 
@@ -114,34 +129,9 @@ The dry run prints the ordered phases without opening the adapter. Remove
 an application-owned custom program. Bootstrap does not import or replay
 Drizzle migration history.
 
-## Baseline and cutover checklist
-
-A baseline is a statement about the live database now, not a replay of its
-history. Before supplying all seven confirmations, the operator must verify:
-
-- `database-target`: the connection names the intended environment;
-- `snapshot-source`: the reviewed snapshot is the intended source of truth;
-- `zero-managed-drift`: strict inspection reports no managed mismatch;
-- `backup-restore-ready`: backup and restore procedures are ready;
-- `other-migrators-stopped`: no other migration runner can race the cutover;
-- `application-compatible`: deployed code is compatible with the live schema;
-- `legacy-history-cutover`: the team accepts the new baseline as the lineage start.
-
-For example, repeat `--confirm` once per exact value. The CLI rejects missing
-or unknown confirmation names even outside production; `environment` is
-reported as context rather than used to weaken the policy.
-
-```bash
-qubu migrate baseline lotta-cutover \
-  --confirm database-target \
-  --confirm snapshot-source \
-  --confirm zero-managed-drift \
-  --confirm backup-restore-ready \
-  --confirm other-migrators-stopped \
-  --confirm application-compatible \
-  --confirm legacy-history-cutover \
-  --format json --non-interactive
-```
+## Adopt an existing database
 
-After success, preserve the written baseline artifact with the repository. Its
-sequence is zero, its parent is null, and later migrations extend its digest.
+Follow the [adoption guide](adopt.md) to capture a live candidate, review its
+scope and facts, run preflight, and explicitly accept it.
+Keep the configured application snapshot as the desired schema for subsequent
+migration planning. Baseline acceptance does not certify application compatibility.

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,23 @@ 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
-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.
+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
@@ -76,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
@@ -73,7 +76,10 @@ render(query)
 // parameters: [7, '%Ada%']
 ```
 
-The optional domain metadata stays in a sidecar aligned with `parameters`:
+### 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"
@@ -96,6 +102,8 @@ 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"

package/docs/reference/introspection-support.md

@@ -1,6 +1,6 @@
 # Introspection support
 
-> Look up which catalog facts each adapter reads, which versions it accepts, and which database features remain outside Snapshot v1.
+> Check supported database versions, catalog objects, and snapshot-mapping limits.
 
 The optional `qubu/introspection` entrypoint reads one selected database
 namespace through a user-owned `CatalogConnection`. It returns normalized
@@ -67,19 +67,22 @@ table-valued PRAGMAs `database_list`, `table_list`, `table_xinfo`,
 receives bound namespace or object parameters through the caller's
 `CatalogConnection`. The reader does not interpolate a database name into SQL.
 
-SQLite views and triggers become typed complete catalog objects when their
-CREATE SQL has a recoverable definition and target. Their SQL remains tagged
-opaque data with a `sqlite` dialect and a catalog reference. Generated column
-expressions, declared storage types, SQLite affinity, rowid aliases, and
+SQLite views and triggers become typed catalog objects when Qubu can recover
+their definition and target from CREATE SQL. Their SQL remains opaque data,
+tagged with the `sqlite` dialect and a catalog reference.
+
+Generated column expressions, declared storage types, SQLite affinity, rowid aliases, and
 `AUTOINCREMENT` are kept as column or identity dialect extensions. User indexes
-retain ordered column or expression terms and partial predicates. Inline UNIQUE
-constraints are recovered from their internal indexes with deterministic Qubu
+retain ordered column or expression terms and partial predicates.
+
+Inline UNIQUE constraints are recovered from their internal indexes with deterministic Qubu
 names, so SQLite's `sqlite_autoindex_*` names do not become persisted logical
 IDs.
 
 SQLite virtual tables and shadow tables remain typed deferred objects with an
-`unmodeled-object` diagnostic. A selected attached database can expose table
-PRAGMA rows, but its schema SQL is outside the fixed `main` and `temp`
+`unmodeled-object` diagnostic.
+
+A selected attached database can expose table PRAGMA rows, but its schema SQL is outside the fixed `main` and `temp`
 statements. Qubu marks that result as limited and keeps other attached
 databases as opaque boundary records. It never combines attached databases into
 the selected namespace. SQLite does not provide the PostgreSQL object families
@@ -101,13 +104,20 @@ strict Snapshot v1 result through a separate controlled printer.
 
 The MySQL reader accepts MySQL 8.0.16 and later within the MySQL 8 series. It
 rejects MariaDB and older MySQL versions instead of applying MySQL catalog
-rules to a different product or server version. It reads `INFORMATION_SCHEMA`
-rows for one selected database and retains database-provided SQL as tagged,
+rules to a different product or server version.
+
+It reads `INFORMATION_SCHEMA` rows for one selected database and retains database-provided SQL as tagged,
 unevaluated MySQL data.
 
-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
+MySQL has typed records for:
+
+- Views.
+- Routines and their parameters.
+- Triggers and partitions.
+- Collations used by selected tables or columns.
+- 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 v1 cross-reference points at the view's own column
 IDs. Missing view definitions or unresolved trigger, partition, or other
@@ -154,12 +164,9 @@ canonical content, not an identity or rename marker.
 
 ## Deferred and limited features
 
-The following remain catalog facts or diagnostics rather than fabricated
-Snapshot v1 objects:
+Supported object families become typed Snapshot v1 records, as described in
+the database sections above. Limits still apply to individual features:
 
-- views and materialized views;
-- sequences, enums, domains, routines, triggers, policies, extensions,
-  collations, comments, and partition metadata;
 - PostgreSQL identity sequence options that have no typed field;
 - SQLite virtual/shadow tables, attached namespaces, and unrecoverable
   generated or expression definitions;