qubu 0.6.2 → 0.6.3

package/docs/schema/constraints-and-indexes.md

@@ -60,9 +60,11 @@ each item a stable application name in the constraints or indexes record. The
 record key becomes `constraint.id` or `index.id`. Qubu resolves `physicalName` from
 the explicit option or the version-one snake_case policy.
 
-Index terms may use `asc()` or `desc()`. Set `unique: true` for a unique index,
-`where` for a partial index, and `include` for columns stored in the index payload but not
-used as key terms.
+Index terms may use `asc()` or `desc()`. Set these options as needed:
+
+- `unique: true` creates a unique index.
+- `where` supplies a partial-index predicate.
+- `include` lists columns stored in the index payload but not used as key terms.
 
 ## Distinguish candidate keys from unique constraints
 
@@ -100,8 +102,11 @@ same length and matching known `SqlSemanticType` identities. `SqlUnknown` cannot
 prove a foreign-key match.
 
 The target tuple must exactly match a primary key, unique() constraint, or
-eligible unique index. Options such as onUpdate, onDelete, match, deferrable,
-and initially remain metadata:
+eligible unique index. These options record database behavior as metadata:
+
+- `onUpdate` and `onDelete`.
+- `match`.
+- `deferrable` and `initially`.
 
 ```ts
 const memberships = table("memberships", { accountId: integer() }, (memberships) => ({
@@ -118,6 +123,8 @@ const memberships = table("memberships", { accountId: integer() }, (memberships)
 Use the preliminary callback table for direct self-references. Wrap the target
 in a function when two modules import each other's tables.
 
+### Restrictions on schema expressions
+
 Checks, index expressions, and partial-index predicates may read only columns
 from their callback table. They cannot contain aggregates, window functions, or
 subqueries. Check expressions and partial predicates must have the boolean SQL

package/docs/schema/ddl-emission.md

@@ -1,6 +1,6 @@
 # DDL emission
 
-> Preview deterministic SQL from a migration plan without confusing preview policy with a sealed executable program.
+> Preview the SQL for a migration plan before preparing it for execution.
 
 The `@qubu/migrate/ddl` entrypoint accepts only a `MigrationPlan` and a `SchemaDialect`.
 It does not read a catalog, open a connection, start a transaction, or write a
@@ -22,8 +22,13 @@ for (const statement of result.statements) {
 }
 ```
 
-`statements` is a deterministic preview surface. Each statement carries its
-operation ID, topological position, SQL text, and an ordered parameter list.
+`statements` contains the SQL preview in dependency order. Each statement has:
+
+- Its operation ID.
+- Its position in that order.
+- SQL text.
+- An ordered parameter list.
+
 Schema literals and expressions are parameter-free by contract. `sql` joins
 the statements with a newline and adds a semicolon for migration-file writers.
 
@@ -31,12 +36,16 @@ the statements with a newline and adds a semicolon for migration-file writers.
 
 The emitter rejects a plan with `ready: false`, `decision-required` operations,
 unknown or lossy facts, unsupported safety, or destructive changes unless the
-caller supplies the matching explicit option. `allowUnsafe` is available for
+caller supplies the matching explicit option.
+
+`allowUnsafe` is available for
 preview integrations, but it is not accepted as an artifact approval and does
 not make an opaque object renderable. Opaque and deferred catalog records need
 an explicit tagged `custom-sql` operation for preview and an operation-scoped
 custom program for sealed execution.
 
+### Check execution requirements
+
 Lock and transaction requirements describe what a later executor must provide.
 Pass `lock` or `transaction` to preflight those requirements against the
 executor's context. A required transaction with `transaction: 'autocommit'`
@@ -74,7 +83,9 @@ an inline constraint declaration or an explicit rebuild/custom-SQL operation.
 Custom SQL stays opaque and appears at its plan position. The emitter does not
 inspect it for object names or infer SQL from an opaque catalog record.
 
-For execution, lower the plan with `compileMigrationProgram()` from
+## Prepare for execution
+
+For execution, compile the plan with `compileMigrationProgram()` from
 `@qubu/migrate/artifact`. The versioned program—not the aggregate `sql`
 string—is authoritative. See [Artifacts and approval
 policy](../migrations/artifacts-and-policy.md).

package/docs/schema/diff.md

@@ -1,11 +1,15 @@
 # Snapshot diffing
 
-> Compare canonical Snapshot v1 values and review identity changes before a later planning step.
+> Compare two snapshots and review changes before planning a migration.
 
 The optional `qubu/diff` entrypoint compares immutable snapshot data. It does
-not open a connection, render SQL, execute a change, or infer migration history.
-It keeps the object kind, namespace, logical ID, physical name, dialect, path,
-and catalog evidence on every result object.
+not access a database or execute changes. Each result keeps the information
+needed to review it:
+
+- Object kind and namespace.
+- Logical ID and physical name.
+- Dialect and path.
+- Catalog evidence.
 
 ```ts
 import { diffSnapshots } from "qubu/diff"
@@ -17,6 +21,8 @@ for (const change of result.changes) {
 }
 ```
 
+## How objects are matched
+
 The matcher first uses an explicit rename hint, then a stable logical ID. A
 physical-name change for a stable match is a `physical-rename` operation. Other
 matched fields become `property-change` operations. Unmatched records remain
@@ -61,6 +67,8 @@ classification. Opaque and deferred Snapshot v1 records remain visible as
 `add` or `remove` data and produce `lossy` or `unsupported` diagnostics. They
 cannot be silently promoted to a rename.
 
+### Equality and ordering
+
 `result.equal` means that no diff operation was emitted. A result can therefore
 be equal while still carrying a warning about an unchanged opaque record. The
 diagnostics remain part of the review boundary.

package/docs/schema/introspection.md

@@ -1,12 +1,16 @@
 # Database introspection
 
-> Read one existing database namespace into explainable catalog data and a canonical Snapshot v1 without giving Qubu ownership of the connection.
+> Read an existing database schema and turn it into a Qubu snapshot.
 
 Database introspection is an optional capability exported from
 `qubu/introspection`. It discovers database facts; it does not recreate the
-original TypeScript declarations. Planning and DDL emission use the separate
+original TypeScript declarations.
+
+Planning and DDL emission use the separate
 `@qubu/migrate/plan` and `@qubu/migrate/ddl` entrypoints, while migration
-execution remains application-owned. The separate
+execution remains application-owned.
+
+The separate
 `qubu/codegen` entrypoint can create a new machine-owned schema module from a
 complete Snapshot v1 result.
 
@@ -32,9 +36,12 @@ continuity, and strict versus lossy output.
 
 ## Supply a connection
 
-Qubu does not open or close a connection, select a driver, manage a pool, retry
-queries, authenticate, or start a transaction. Adapt the driver you already
-use to `CatalogConnection`:
+Adapt your existing driver to `CatalogConnection`. Your application handles:
+
+- Opening and closing connections.
+- Driver selection and connection pools.
+- Authentication.
+- Retries and transactions.
 
 ```ts
 import type { CatalogConnection } from "qubu/introspection"
@@ -127,6 +134,8 @@ generated expressions, checks, predicates, and expression index terms remain
 dialect-tagged SQL. Falsy values such as `0`, `false`, `NULL`, and empty
 strings are preserved.
 
+### References and dialect metadata
+
 References to nested columns, constraints, and indexes include their owning
 table, view, or domain in the complete Snapshot v1 output. References to
 top-level objects remain unscoped, and table-local backing relationships must
@@ -135,21 +144,34 @@ native storage, and typed expressions are checked against the selected
 snapshot dialect; arbitrary catalog `data` and `configuration` JSON remains
 opaque.
 
-PostgreSQL readers expose views, materialized views, sequences, enums, domains,
-collations, routines, triggers, policies, partitions, extensions, comments,
-and ownership as typed complete catalog records. `mapCatalogToCompleteSnapshot`
-retains those records in Snapshot v1. `mapCatalogToSnapshot()` uses the same
-complete mapping and does not fabricate these objects into tables. If a
-PostgreSQL catalog row lacks the evidence needed for
-safe normalization, the reader retains a deferred or opaque record and emits a
-diagnostic.
+## PostgreSQL catalog support
+
+PostgreSQL readers expose typed catalog records for:
+
+- Views and materialized views.
+- Sequences, enums, and domains.
+- Collations.
+- Routines and triggers.
+- Policies and partitions.
+- Extensions.
+- Comments and ownership.
+
+`mapCatalogToCompleteSnapshot()` retains those records in Snapshot v1.
+`mapCatalogToSnapshot()` uses the same complete mapping and keeps each object
+as its own kind.
+
+If a PostgreSQL catalog row lacks the evidence needed for safe normalization,
+the reader retains a deferred or opaque record and emits a diagnostic.
+
+## SQLite catalog support
 
 SQLite readers expose recoverable views and triggers as typed complete records.
 They retain virtual and shadow tables as deferred objects, and keep attached
 databases outside the selected namespace as opaque boundary records. SQLite
 declared types, derived affinity, generated expressions, rowid identity, and
-`AUTOINCREMENT` stay tagged with SQLite dialect metadata. When an attached
-database is selected, table PRAGMAs may be visible but CREATE SQL remains
+`AUTOINCREMENT` stay tagged with SQLite dialect metadata.
+
+When an attached database is selected, table PRAGMAs may be visible but CREATE SQL remains
 limited to the fixed `main` and `temp` catalog statements, so the reader marks
 the catalog visibility as limited instead of combining namespaces.
 
@@ -191,11 +213,15 @@ MySQL families and their opaque or deferred boundaries.
 
 ## Diagnostics and safety
 
-Diagnostics include a severity, stable code, catalog path, physical reference
-when available, and a remediation hint. They distinguish connection/query
-failures, permission limits, unsupported products or versions, unresolved
-references, expression recovery failures, unmodeled objects, and lossy
-mappings.
+Each diagnostic includes:
+
+- Severity and a stable code.
+- A catalog path.
+- A physical reference, when available.
+- A hint for fixing the problem.
+
+Codes distinguish connection failures and permission limits from unsupported
+features or incomplete mappings.
 
 Introspection is read-only from Qubu's perspective. Do not pass credentials or
 DSNs through diagnostic fields. Keep driver-specific error text in the

package/docs/schema/migration-plans.md

@@ -1,11 +1,16 @@
 # Migration plans
 
-> Describe reviewed snapshot changes as deterministic data before selecting a DDL emitter.
+> Turn a reviewed schema diff into an ordered migration plan.
 
-The `@qubu/migrate/plan` entrypoint consumes a resolved `SnapshotDiff` and
-returns an immutable migration-plan IR. It contains operation IDs, paths,
-logical and physical identity evidence, dependency edges, preconditions, safety,
-lock and transaction requirements, and reversibility markers.
+The `@qubu/migrate/plan` entrypoint takes a resolved `SnapshotDiff` and returns
+an immutable plan. Each operation records:
+
+- Its ID and path.
+- Evidence for logical and physical identities.
+- Dependencies and preconditions.
+- Safety classification.
+- Lock and transaction requirements.
+- Whether the change can be reversed.
 
 ```ts
 import { createMigrationPlan } from "@qubu/migrate/plan"
@@ -16,8 +21,9 @@ if (!result.ok) {
 }
 ```
 
-Creation is pure. The planner does not open a connection, execute a transaction,
-render SQL, or create migration history. A physical rename remains a
+The planner only returns data. It does not access the database or render SQL.
+
+A physical rename remains a
 `physical-rename` operation; it is never represented as custom SQL or silently
 changed into a drop and add.
 
@@ -64,9 +70,11 @@ extracts SQL from opaque catalog payloads.
 
 ## Ordering and validation
 
-Parent creation precedes child creation, while child removal precedes parent
-removal. Reference edges and explicit custom-SQL dependencies are included in
-the stable topological ordering. `encodeMigrationPlan()` emits canonical JSON;
+The planner creates parents before children and removes children before
+parents. It also orders operations by their references and explicit custom-SQL
+dependencies. The same inputs produce the same order.
+
+`encodeMigrationPlan()` emits canonical JSON;
 `decodeMigrationPlan()` and `validateMigrationPlan()` reject unknown fields,
 future versions, malformed operations, missing edges, and dependency cycles.
 

package/docs/schema/snapshots.md

@@ -1,6 +1,6 @@
 # Canonical schema snapshots
 
-> Serialize schema metadata into strict, deterministic data and keep serialization separate from diffing, planning, and DDL emission.
+> Save a schema as versioned data that you can compare and check into source control.
 
 Qubu's schema tooling lives behind the `qubu/snapshot` entrypoint. It converts
 an immutable `schema()` registry into versioned data that can be inspected,
@@ -14,21 +14,33 @@ const snapshot = createSchemaSnapshot(appSchema)
 const json = encodeSchemaSnapshot(snapshot)
 ```
 
-The Snapshot v1 envelope contains a format version, an independently versioned
-dialect extension, a versioned naming-policy description, a namespace,
-capability facts, and arrays for every supported object family. Tables,
-columns, constraints, and indexes are sorted by stable logical ID. Physical
+## What a snapshot contains
+
+The Snapshot v1 envelope contains:
+
+- A format version.
+- An independently versioned dialect extension.
+- A versioned naming-policy description.
+- A namespace.
+- Supported-capability facts.
+- Arrays for each supported object family.
+
+Tables, columns, constraints, and indexes are sorted by stable logical ID. Physical
 names are values in the snapshot, not identities:
 changing a physical name does not change the TypeScript field or metadata key.
 
-Snapshot data is deliberately not executable Qubu state. Expressions are
-parameter-free data records, and decoding never creates tables, column
-references, or render closures. The neutral fallback renders branded built-in
-expressions through the standard schema context; a dialect adapter may replace
+Snapshot expressions are data records without parameters. Decoding does not
+create executable table or column objects, or rendering functions.
+
+The neutral fallback renders branded built-in expressions through the standard schema context; a dialect adapter may replace
 that hook with its own literal and expression policy. An explicitly unsafe
 expression retains its dialect tag and is rejected when it does not match the
 selected snapshot dialect.
 
+## Decode and validate a snapshot
+
+Use `decodeSchemaSnapshot()` to read saved JSON and inspect validation failures:
+
 ```ts
 import { decodeSchemaSnapshot } from "qubu/snapshot"
 
@@ -46,6 +58,8 @@ dialect metadata, and broken foreign-key or column references as structured
 diagnostics. It does not call `process.exit()` and has no runtime validation
 library dependency.
 
+### References and ownership
+
 References to nested columns, constraints, and indexes carry an explicit
 `owner: { kind, id }` scope. Table columns, constraints, and indexes are owned
 by their table; view columns are owned by their view; and domain constraints
@@ -55,6 +69,8 @@ checked only in typed snapshot fields. Extension `data`, `configuration`, and
 other opaque JSON payloads are retained as data and are not interpreted as
 typed metadata.
 
+### Content fingerprints
+
 `schemaSnapshotFingerprint()` computes a deterministic content fingerprint from canonical
 JSON. The fingerprint is useful for cache keys and fixture assertions only. It is not
 an entity identity, a rename marker, or migration lineage.
@@ -69,15 +85,23 @@ and advertised capabilities while adding schema encoders and validation under
 second query dialect. The schema snapshot format version remains independent
 from the dialect identity.
 
-The common traversal owns logical IDs, fixed property order, canonical sorting,
-portable constraints, cross-reference checks, and the immutable snapshot
-envelope. A dialect adapter owns physical storage mapping, SQL literal and
-expression encoding, dialect extensions, capability checks, and any dialect
-naming policy. PostgreSQL, SQLite, and MySQL adapters can implement
-`SchemaSnapshotAdapter` without duplicating traversal or decoder rules.
-The neutral API stays at `qubu/snapshot`; built-in dialect adapters have
-dedicated subpaths so importing neutral snapshot utilities does not widen that
-API:
+The shared serializer handles:
+
+- Logical IDs and fixed property order.
+- Canonical sorting and portable constraints.
+- Cross-reference checks.
+- The immutable snapshot envelope.
+
+A dialect adapter handles:
+
+- Physical storage mapping.
+- SQL literal and expression encoding.
+- Dialect extensions and capability checks.
+- Any dialect-specific naming policy.
+
+PostgreSQL, SQLite, and MySQL adapters can implement `SchemaSnapshotAdapter`
+without duplicating traversal or decoder rules. Import built-in adapters from
+their dedicated subpaths:
 
 ```ts
 import { createSchemaSnapshot } from "qubu/snapshot"
@@ -97,17 +121,21 @@ matrix](../reference/mysql-snapshot.md). Its query and snapshot dialects both
 use `mysql`, while MySQL-only `ON UPDATE` and `AUTO_INCREMENT` details remain
 inside the column and identity metadata they describe.
 
-Snapshot serialization remains separate from database introspection,
-comparison, rename resolution, migration planning, and DDL emission. The
-optional `qubu/introspection` entrypoint can produce the same canonical
-Snapshot v1 data from a user-owned catalog connection. The complete normalized
-catalog can also be encoded with the explicit complete-snapshot APIs described
-in [the catalog model](catalog-model.md).
-Readers and connection lifecycle do not belong to this pure serialization
-layer. Diffing consumes Snapshot v1. Resolved diffs feed
-migration plans, and approved plans feed DDL emission. The package-wide
-[ownership map](../reference/supported-surface.md#ownership-boundary) keeps
-those pure steps separate from application-owned database execution.
+## Use a snapshot in later steps
+
+The optional `qubu/introspection` entrypoint can produce Snapshot v1 data from
+a catalog connection you provide. The [catalog model](catalog-model.md)
+describes the complete-snapshot APIs.
+
+A snapshot then passes through separate steps:
+
+1. Diffing compares Snapshot v1 values.
+2. Migration planning uses the resolved diff.
+3. DDL emission renders an approved plan.
+
+These steps return data without accessing the database. The
+[ownership map](../reference/supported-surface.md#ownership-boundary) explains
+how they connect to application-owned execution.
 
 The optional [schema source generator](code-generation.md) consumes a complete,
 non-lossy introspection result and makes its generated schema the next identity

package/docs/schema/storage-and-schema-sql.md

@@ -1,11 +1,15 @@
 # Storage and schema SQL
 
-> Keep application types, SQL domains, physical storage, and schema expressions separate so each adapter can make its own rendering decision.
+> Describe database storage types and write expressions for schema definitions.
 
 ## Keep application and SQL types separate
 
-A column can have an application value type, a SQL semantic domain, a physical
-storage descriptor, and a cast target. These facts answer different questions.
+A column can describe four different things:
+
+- Its application value type.
+- Its SQL semantic domain, which controls compatible operations.
+- Its physical database storage type.
+- Its target type when used in a cast.
 
 For example, `numeric()` decodes to a TypeScript number, carries `SqlDecimal`,
 uses portable numeric storage, and has a logical decimal cast target. Read
@@ -45,7 +49,9 @@ const accounts = table("accounts", {
 `nativeStorage()` preserves the declaration text and freezes the descriptor. The
 `ColumnStorageOf`, `ColumnStorageTypeOf`, `ColumnStorageDialectOf`, and
 `ColumnStorageDeclarationOf` helpers read its metadata. Native storage is
-descriptive. The optional `sqlType` field is the runtime semantic domain passed
+descriptive.
+
+The optional `sqlType` field is the runtime semantic domain passed
 to adapters; provide it for custom domains because the compile-time SQL type is
 not available at runtime. It does not change selection, mutation, or query
 rendering.

package/docs/schema/tables-and-names.md

@@ -1,6 +1,6 @@
 # Tables and names
 
-> Define query-facing tables, keep their TypeScript identities stable, and control how fields become SQL names.
+> Define tables and control how TypeScript field names map to database names.
 
 `table()` definitions describe the columns Qubu can select and write. They are
 not database introspection and they do not create or migrate a database.

package/docs/sql-semantic-types.md

@@ -1,6 +1,6 @@
 # SQL semantic types
 
-> Use SQL domains to constrain valid query composition without conflating database semantics with driver-decoded application values.
+> Understand which SQL operations a column supports, even when its JavaScript type looks the same as another column’s.
 
 Qubu tracks four independent facts for a field or result expression:
 
@@ -11,7 +11,7 @@ Qubu tracks four independent facts for a field or result expression:
 | Nullability     | Can the selected value be `null`?                         | `false`                   |
 | SQL domain      | Which portable SQL operations may consume the expression? | `SqlText` or `SqlUuid`    |
 
-The axes are deliberately separate. Both `text()` and `uuid()` decode to a
+These facts are separate. Both `text()` and `uuid()` decode to a
 JavaScript `string`, but their SQL behavior differs. Likewise, two
 `timestamp()` definitions may share `SqlTimestamp` while a custom column uses
 different JavaScript output and write types for its driver.
@@ -111,12 +111,15 @@ target is vendor-specific.
 
 ## Known incompatibility is rejected
 
-Qubu checks capabilities and compatibility when it knows both SQL domains.
-Arithmetic and `SUM`/`AVG` require numeric-like expressions; text functions,
-concatenation, `LIKE`, and PostgreSQL `ILIKE` require text-like expressions;
-ordering and range comparisons require compatible ordering groups; and
-equality, `IN`, `CASE`, `COALESCE`, and set-operation fields require compatible
-equality groups. Boolean clauses require a boolean SQL domain.
+When Qubu knows both SQL domains, it checks these rules:
+
+- Arithmetic and `SUM`/`AVG` require numeric-like expressions.
+- Text functions, concatenation, and pattern matching (`LIKE` or `ILIKE`)
+  require text-like expressions.
+- Ordering and range comparisons require compatible ordering groups.
+- Equality comparisons and `IN` require compatible equality groups. The same
+  rule applies to `CASE`, `COALESCE`, and set-operation fields.
+- Boolean clauses require a boolean SQL domain.
 
 These checks model portable capability and group relationships, not every
 database's implicit casts. An expression accepted by one database after an

package/docs/troubleshooting.md

@@ -1,6 +1,6 @@
 # Troubleshooting
 
-> Start from the observed error or output, verify the boundary that produced it, and apply the smallest fix that changes the result.
+> Find a common error, check its cause, and fix the query.
 
 ## Column is not available in this query scope
 
@@ -73,9 +73,13 @@ driver that expects `?` placeholders.
 ## Read and repair query diagnostics
 
 Type-level query failures carry stable properties in the diagnostic type, and
-runtime authoring failures throw `QueryValidationError`. Read the code, context,
-path, and hint before changing the query. The hint names the repair boundary;
-the path points to the clause or field that needs attention.
+runtime authoring failures throw `QueryValidationError`. Check these fields
+before changing the query:
+
+- `code`: the kind of error.
+- `context`: where the error occurred.
+- `path`: the clause or field that needs attention.
+- `hint`: how to fix it.
 
 ```ts
 import { QueryValidationError, fetchFirst } from "qubu"
@@ -130,8 +134,12 @@ Verify all three opt-ins:
 3. TypeScript includes `qubu/globals` in its `types` list or includes the
    declaration explicitly.
 
-The transform skips non-script files, dependencies under `node_modules`, files
-excluded by filters, and modules that reference no eligible Qubu global.
+The transform skips:
+
+- Non-script files.
+- Dependencies under `node_modules`.
+- Files excluded by filters.
+- Modules that reference no eligible Qubu global.
 
 ## Parameters are in an unexpected order
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qubu",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "repository": {
     "type": "git",
     "url": "https://github.com/aleclarson/qubu"