qubu 0.6.2 → 0.6.3

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,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;

package/docs/reference/mysql-snapshot.md

@@ -1,8 +1,6 @@
 # MySQL snapshot support
 
-> Use this matrix before selecting `mysqlSnapshotAdapter`; it records the
-> MySQL facts Qubu v1 can encode and the combinations that need a later server
-> version or engine policy.
+> Check which MySQL schema features the Snapshot v1 adapter can save.
 
 Import the adapter from the MySQL snapshot subpath:
 
@@ -21,7 +19,7 @@ to this adapter.
 
 | Schema fact         | MySQL v1 behavior                                                                                                                                                                                                                                   |
 | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Portable storage    | Maps `integer` to `INT`, `numeric` to `DECIMAL`, `text` to `TEXT`, `boolean` to `BOOLEAN`, `date` to `DATE`, `timestamp` to `DATETIME`, `uuid` to `CHAR(36)`, `json` to `JSON`, `bigint` to `BIGINT`, and `binary` to `VARBINARY`.                  |
+| Portable storage    | Uses the mappings below.                                                                                                                                                                                                                            |
 | Native storage      | Preserves a non-empty declaration tagged `mysql` exactly. Native declarations owned by another dialect fail.                                                                                                                                        |
 | Literals            | Encodes `NULL`, finite numbers, strings, booleans, and `bigint` without query parameters. Strings use SQL quote doubling.                                                                                                                           |
 | Defaults            | Canonical literals, branded deterministic expressions, and explicit external behavior are retained. Default expressions cannot reference columns or parameters.                                                                                     |
@@ -34,6 +32,23 @@ to this adapter.
 | Indexes             | Ordered terms, expressions, uniqueness, and candidate-key evidence are retained. Partial predicates, included columns, and `NULLS FIRST/LAST` are diagnosed. Algorithm, locking, access method, parser, and key-block options live under `dialect`. |
 | Names               | Table, column, constraint, and index names are checked against MySQL's 64-character identifier limit. Table names are database-scoped; index names are table-scoped.                                                                                |
 
+## Portable storage types
+
+| Qubu storage | Database declaration |
+| ------------ | -------------------- |
+| `integer`    | `INT`                |
+| `numeric`    | `DECIMAL`            |
+| `text`       | `TEXT`               |
+| `boolean`    | `BOOLEAN`            |
+| `date`       | `DATE`               |
+| `timestamp`  | `DATETIME`           |
+| `uuid`       | `CHAR(36)`           |
+| `json`       | `JSON`               |
+| `bigint`     | `BIGINT`             |
+| `binary`     | `VARBINARY`          |
+
+## Diagnostics
+
 Capability checks run before common traversal. Use the non-throwing form when
 a schema may include a MySQL engine or version-specific feature:
 

package/docs/reference/postgres-snapshot.md

@@ -1,8 +1,6 @@
 # PostgreSQL snapshot support
 
-> Use this matrix before selecting `postgresSnapshotAdapter`; it records the
-> PostgreSQL facts Qubu v1 can encode and the cases that need a later server
-> version policy.
+> Check which PostgreSQL schema features the Snapshot v1 adapter can save.
 
 Import the adapter from the PostgreSQL snapshot subpath:
 
@@ -24,7 +22,7 @@ snapshot metadata and `unsafeSchemaSql()` use `postgresql` consistently.
 
 | Schema fact         | PostgreSQL v1 behavior                                                                                                                                                                                                       |
 | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Portable storage    | Emits PostgreSQL declarations: `INTEGER`, `NUMERIC`, `TEXT`, `BOOLEAN`, `DATE`, `TIMESTAMP`, `UUID`, `JSONB`, `BIGINT`, and `BYTEA`.                                                                                         |
+| Portable storage    | Uses the mappings below.                                                                                                                                                                                                     |
 | Native storage      | Preserves a non-empty declaration tagged `postgresql` exactly. Other dialect tags fail.                                                                                                                                      |
 | Literals            | Encodes finite numbers, strings, booleans, `bigint`, and `NULL` without query parameters.                                                                                                                                    |
 | Defaults            | Canonical literals, branded deterministic expressions, and explicit external behavior are retained. Column references in defaults fail.                                                                                      |
@@ -41,6 +39,21 @@ deterministic data for the `qubu/snapshot` decoder. The package-wide
 [ownership map](supported-surface.md#ownership-boundary) shows the separate
 schema and application boundaries.
 
+## Portable storage types
+
+| Qubu storage | Database declaration |
+| ------------ | -------------------- |
+| `integer`    | `INTEGER`            |
+| `numeric`    | `NUMERIC`            |
+| `text`       | `TEXT`               |
+| `boolean`    | `BOOLEAN`            |
+| `date`       | `DATE`               |
+| `timestamp`  | `TIMESTAMP`          |
+| `uuid`       | `UUID`               |
+| `json`       | `JSONB`              |
+| `bigint`     | `BIGINT`             |
+| `binary`     | `BYTEA`              |
+
 ## Diagnostics
 
 Use the non-throwing form when a schema may contain a server-specific feature:

package/docs/reference/sqlite-snapshot.md

@@ -1,6 +1,6 @@
 # SQLite snapshot support
 
-> Use this matrix to decide which SQLite schema facts Qubu v1 can serialize and which combinations must be diagnosed before a snapshot is written.
+> Check which SQLite schema features the Snapshot v1 adapter can save.
 
 Import the adapter from the SQLite snapshot subpath:
 
@@ -20,7 +20,7 @@ to distinguish it from the query renderer. A dialect-tagged
 
 | Schema fact         | SQLite v1 behavior                                                                                                                                                                                                                            |
 | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Portable storage    | Maps `integer`, `boolean`, and `bigint` to `INTEGER`; `text`, `date`, `timestamp`, `uuid`, and `json` to `TEXT`; `numeric` to `NUMERIC`; and `binary` to `BLOB`. The snapshot also records SQLite's derived affinity.                         |
+| Portable storage    | Uses the mappings below. SQLite affinity is also recorded.                                                                                                                                                                                    |
 | Native storage      | Preserves a non-empty declaration tagged `sqlite` exactly and records its affinity using SQLite's ordered declared-type rules. Other dialect tags fail.                                                                                       |
 | Literals            | Encodes `NULL`, finite numbers, strings, `bigint`, and booleans as parameter-free SQL. Boolean literals use `1` and `0`; strings retain SQL escaping.                                                                                         |
 | Defaults            | Canonical literals, branded deterministic expressions, and explicit external behavior are retained. Default expressions cannot reference columns or parameters.                                                                               |
@@ -32,6 +32,23 @@ to distinguish it from the query renderer. A dialect-tagged
 | Indexes             | Ordered terms, expressions, uniqueness, predicates for partial indexes, and candidate-key evidence are retained. Included columns are diagnosed as unsupported. The typed SQLite index extension is encoded under `dialect`.                  |
 | Namespaces          | An optional unqualified namespace is retained; Qubu does not attach or inspect SQLite databases.                                                                                                                                              |
 
+## Portable storage types
+
+| Qubu storage | Database declaration |
+| ------------ | -------------------- |
+| `integer`    | `INTEGER`            |
+| `numeric`    | `NUMERIC`            |
+| `text`       | `TEXT`               |
+| `boolean`    | `INTEGER`            |
+| `date`       | `TEXT`               |
+| `timestamp`  | `TEXT`               |
+| `uuid`       | `TEXT`               |
+| `json`       | `TEXT`               |
+| `bigint`     | `INTEGER`            |
+| `binary`     | `BLOB`               |
+
+## Diagnostics
+
 Capability checks run before common traversal. Use the non-throwing form when a
 schema may include a feature that depends on a SQLite version or table shape: