qubu 0.6.2 → 0.7.0

package/docs/schema/code-generation.md

@@ -1,6 +1,6 @@
 # Generate a schema from introspection
 
-> Turn one complete, non-lossy Snapshot v1 introspection result into a deterministic, machine-owned TypeScript schema module.
+> Generate a TypeScript schema module from a complete introspection result with no omitted facts.
 
 Source generation is an optional capability exported from `qubu/codegen`. It
 is a pure handoff after introspection: it opens no connection, runs no catalog
@@ -33,12 +33,20 @@ returns data. A successful result contains deterministic `source` and every
 retained diagnostic. A failed result contains diagnostics and no partial
 source.
 
-The module exports one declaration for every ordinary Snapshot v1 table and
-one schema registry. It reconstructs physical names, exact native storage,
-column write behavior, defaults, generated and identity metadata, constraints,
-indexes, opaque predicates and expressions, and dialect extensions. Checks use
-`catalogCheck()`. Foreign keys use lazy `catalogForeignKey()` targets so
-forward declarations and cycles remain valid.
+### What the module contains
+
+The module exports each ordinary Snapshot v1 table and one schema registry. It
+reconstructs:
+
+- Physical names and exact native storage.
+- Column write behavior and defaults.
+- Generated-column and identity metadata.
+- Constraints and indexes.
+- Opaque predicates and expressions.
+- Dialect extensions.
+
+Checks use `catalogCheck()`. Foreign keys use lazy `catalogForeignKey()` targets
+so forward declarations and cycles remain valid.
 
 ## Adopt the generated identity baseline
 
@@ -100,11 +108,15 @@ diagnostics and no source.
 
 ## Diagnostics and source safety
 
-Generation rejects failed or lossy introspection, an altered snapshot that no
-longer matches its catalog, omitted Snapshot v1 facts, unresolved references,
-unsafe names, invalid mapping tokens, and data that cannot be represented
-without source injection. Existing introspection diagnostics stay attached to
-the result.
+Generation fails when the input contains:
+
+- Failed or lossy introspection.
+- An edited snapshot that no longer matches its catalog.
+- Omitted Snapshot v1 facts or unresolved references.
+- Unsafe names or invalid mapping tokens.
+- Data that cannot be printed safely as source.
+
+Existing introspection diagnostics stay attached to the result.
 
 > [!IMPORTANT]
 > A database can allow a foreign key to reference a nullable `UNIQUE`
@@ -126,15 +138,22 @@ result contracts.
 
 ## Snapshot v1 boundary
 
-Generation covers ordinary Snapshot v1 tables in one namespace. Complete
-catalog families outside that model—views, materialized views, sequences,
-enums, domains, routines, triggers, partitions, policies, collations,
-extensions, comments, ownership, and retained opaque or deferred objects—are
-not emitted. Non-empty excluded families produce diagnostics so the generated
-module does not look complete by omission.
+Generation covers ordinary Snapshot v1 tables in one namespace. It does not emit:
+
+- Views and materialized views.
+- Sequences, enums, and domains.
+- Routines and triggers.
+- Partitions and policies.
+- Collations and extensions.
+- Comments and ownership.
+- Retained opaque or deferred objects.
+
+If any excluded family is non-empty, generation reports diagnostics rather than
+presenting the module as complete.
+
+The caller handles file writes and driver integration. Generation does not
+merge hand edits or run migrations.
 
-The entrypoint does not provide a CLI, filesystem ownership, live driver
-integration, multiple namespaces, runtime schema materialization, migrations,
-DDL, non-table object generation, or hand-edit merging. Use
+Use
 [Database introspection](introspection.md) for the catalog boundary and
 [Canonical schema snapshots](snapshots.md) for the identity artifact.

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 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.