qubu 0.6.1 → 0.6.3

package/docs/schema/columns-and-writes.md

@@ -1,6 +1,6 @@
 # Column behavior and write types
 
-> Separate selected values from insert and update inputs, then record the database rules that make fields optional or generated.
+> Choose the values a column returns and accepts, including defaults and generated values.
 
 ## Give each operation its own type
 
@@ -32,7 +32,7 @@ updates accept number | null.
 
 ## Describe defaults and generated columns
 
-The legacy hasDefault and generated flags describe the write contract. Use
+The `hasDefault` and `generated` flags describe which values writes accept. Use
 complete metadata when schema tooling also needs the database fact:
 
 ```ts
@@ -60,15 +60,18 @@ Primitive values in `default` are canonical literals. Strings are never
 interpreted as SQL, and booleans remain semantic values so each dialect can
 choose its own spelling. Pass a branded deterministic schema expression
 directly when the default is SQL, and use `unsafeSchemaSql()` only for trusted
-syntax Qubu does not model. Generated expressions record stored or virtual
-mode. An identity descriptor stays separate because identity behavior is not
-an ordinary generated expression.
+syntax Qubu does not model.
+
+Generated expressions record stored or virtual mode. An identity descriptor
+stays separate because identity behavior is not an ordinary generated expression.
 
 Complete defaults cannot be combined with generated or identity metadata.
 Contradictory flags fail with a structured `ColumnBehaviorError`. Use
 `externalDefault()` or `externalGeneratedColumn()` when another schema authority
 owns the missing detail.
 
+### Supply defaults at runtime
+
 Use `defaultFn` when Qubu should supply an omitted insert value at runtime:
 
 ```ts
@@ -79,15 +82,22 @@ const sessions = table("sessions", {
 
 Runtime defaults make the insert key optional and run once for each omitted
 row value. They remain live column behavior: snapshots and emitted DDL do not
-record a database default. A column may declare both `default` and `defaultFn`;
+record a database default.
+
+A column may declare both `default` and `defaultFn`;
 Qubu writes use the runtime value while the database default remains available
 to other clients.
 
-Dialect-owned identity details stay on the identity descriptor. SQLite's
-autoIncrement requires an exact INTEGER rowid alias that is the sole column of
-a primary key. MySQL's AUTO_INCREMENT is a column-level identity extension, and
-MySQL's ON UPDATE clause accepts a branded deterministic expression. The
-database-specific restrictions are listed in the
+### Check database-specific rules
+
+Identity details stay on the identity descriptor:
+
+- SQLite `autoIncrement` requires an exact `INTEGER` rowid alias that is the
+  sole column of a primary key.
+- MySQL `AUTO_INCREMENT` is a column-level identity extension.
+- MySQL `ON UPDATE` accepts a branded deterministic expression.
+
+The database-specific restrictions are listed in the
 [snapshot overview](snapshots.md) and its dialect matrices.
 
 ## Narrow an application type

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 or v2 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
@@ -57,10 +63,12 @@ an `ambiguous` diagnostic and leaves both operations visible for review.
 
 Removing an object is marked `destructive`. Narrowing nullability, changing
 storage, removing a value, or changing a constraint can also receive that
-classification. Opaque and deferred Snapshot v2 records remain visible as
+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 an optional canonical Snapshot v1 or complete Snapshot v2 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"
@@ -85,8 +92,8 @@ catalog. Use `createCompleteIntrospectionCatalog()` to materialize and freeze
 all optional collections, then `mapCatalogToCompleteSnapshot()` when an
 adapter-supported family such as views, routines, triggers, partitions,
 collations, comments, or retained opaque and deferred objects must cross the
-strict Snapshot v2 boundary. Snapshot v1 is still selected explicitly by
-`mapCatalogToSnapshot()` and remains table-shaped.
+strict Snapshot v1 boundary. `mapCatalogToSnapshot()` delegates to the complete
+mapper, so the canonical result is always Snapshot v1.
 
 The result is successful only when Snapshot v1 validation succeeds. A failed
 result may retain the partial catalog and structured diagnostics, but it has no
@@ -108,9 +115,9 @@ rename. Pass the previous snapshot or an identity hint when a later diff must
 preserve identity across a rename. See [snapshot diffing](diff.md) for the
 comparison and hint boundary.
 
-The first version selects one namespace: a PostgreSQL schema, MySQL database,
-or SQLite database such as `main`. It does not combine attached databases or
-multiple PostgreSQL schemas into one Snapshot v1 value.
+Each Snapshot v1 result selects one namespace: a PostgreSQL schema, MySQL
+database, or SQLite database such as `main`. It does not combine attached
+databases or multiple PostgreSQL schemas into one value.
 
 ## Strict and lossy output
 
@@ -127,21 +134,44 @@ generated expressions, checks, predicates, and expression index terms remain
 dialect-tagged SQL. Falsy values such as `0`, `false`, `NULL`, and empty
 strings are preserved.
 
-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 v2. The existing `mapCatalogToSnapshot`
-mapper still emits the table-only Snapshot v1 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.
+### 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
+resolve within the table that contains them. Dialect provenance, extensions,
+native storage, and typed expressions are checked against the selected
+snapshot dialect; arbitrary catalog `data` and `configuration` JSON remains
+opaque.
+
+## 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.
 
@@ -155,13 +185,13 @@ collations used by the selected tables or columns, and comments.
 
 View definitions come from `INFORMATION_SCHEMA.VIEWS`. The reader cross-
 references each view with its `INFORMATION_SCHEMA.COLUMNS` rows by physical
-table name, so view columns remain attached to the view and Snapshot v2 can
+table name, so view columns remain attached to the view and Snapshot v1 can
 validate their own column IDs. A missing definition or an unresolved
 cross-object reference becomes a deferred record with a diagnostic.
 
 MySQL scheduled events are kept as `CatalogOpaqueObject` records with their
 metadata and definition tagged as opaque SQL. The reader emits an
-`unmodeled-object` warning, and Snapshot v2 retains the record in
+`unmodeled-object` warning, and Snapshot v1 retains the record in
 `opaqueObjects` without treating it as a typed routine, trigger, or migration
 operation.
 
@@ -178,17 +208,20 @@ The reader keeps that metadata as normalized typed data and never evaluates
 database-provided SQL. Optional source generation remains a later, pure step
 with a controlled literal printer.
 
-Use `mapCatalogToCompleteSnapshot()` for the typed MySQL families and its
-opaque or deferred boundaries. Use `mapCatalogToSnapshot()` when the caller
-needs the table-only Snapshot v1.
+Use `mapCatalogToSnapshot()` or `mapCatalogToCompleteSnapshot()` for the typed
+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,20 +14,33 @@ const snapshot = createSchemaSnapshot(appSchema)
 const json = encodeSchemaSnapshot(snapshot)
 ```
 
-The v1 envelope contains a format version, an independently versioned dialect
-extension, a versioned naming-policy description, an optional namespace, and
-arrays of tables. Tables, columns, constraints, and indexes are sorted by
-stable logical ID. Physical names are values in the snapshot, not identities:
+## 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"
 
@@ -45,6 +58,19 @@ 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
+are owned by their domain. References to top-level objects remain ownerless,
+and the decoder validates each nested scope independently. Dialect metadata is
+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.
@@ -59,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"
@@ -87,19 +121,23 @@ 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 as strict Snapshot v2 with the dedicated
-complete-snapshot APIs described in [the catalog model](catalog-model.md).
-Readers and connection lifecycle do not belong to this pure serialization
-layer. Diffing can compare either snapshot version. 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
-baseline. It does not replace snapshot serialization or generate Snapshot v2
+baseline. It does not replace snapshot serialization or populate non-table
 object families.

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
@@ -36,14 +40,21 @@ declaration:
 import { nativeColumn, nativeStorage, table } from "qubu"
 
 const accounts = table("accounts", {
-  handle: nativeColumn(nativeStorage("postgresql", 'citext COLLATE "C"')),
+  handle: nativeColumn(nativeStorage("postgresql", 'citext COLLATE "C"'), {
+    sqlType: "postgres.citext",
+  }),
 })
 ```
 
 `nativeStorage()` preserves the declaration text and freezes the descriptor. The
 `ColumnStorageOf`, `ColumnStorageTypeOf`, `ColumnStorageDialectOf`, and
 `ColumnStorageDeclarationOf` helpers read its metadata. Native storage is
-descriptive. It does not change selection, mutation, or query rendering.
+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.
 
 ## Render deterministic schema expressions
 

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