qubu 0.0.0 → 0.3.3

package/docs/schema/ddl-emission.md

@@ -0,0 +1,75 @@
+# DDL emission
+
+> Turn an approved migration plan into deterministic SQL while keeping database execution outside Qubu.
+
+The `qubu/ddl` entrypoint accepts only a `MigrationPlan` and a `SchemaDialect`.
+It does not read a catalog, open a connection, start a transaction, or write a
+migration journal. Preflight runs before rendering, so a blocked or incompatible
+plan returns diagnostics and no SQL.
+
+```ts
+import { emitMigrationPlan } from 'qubu/ddl'
+import { postgresSchemaDialect } from 'qubu/snapshot'
+
+const result = emitMigrationPlan(plan, postgresSchemaDialect)
+if (!result.ok) {
+  // Review result.diagnostics. result.sql is an empty string.
+  throw new Error(result.diagnostics.map(item => item.message).join('\n'))
+}
+
+for (const statement of result.statements) {
+  console.log(statement.operationId, statement.sql, statement.parameters)
+}
+```
+
+`statements` is the stable handoff for an application-owned executor. Each
+statement carries its operation ID, topological position, SQL text, and 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.
+
+## Review gates
+
+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 a
+reviewed integration that owns all of those decisions, but it does not make an
+opaque object renderable. Opaque and deferred catalog records always need an
+explicit tagged `custom-sql` operation.
+
+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'`
+produces `transaction-conflict`; no transaction is opened by the emitter.
+
+```ts
+const result = emitMigrationPlan(plan, postgresSchemaDialect, {
+  transaction: 'managed',
+  lock: 'exclusive',
+  serverVersion: '16',
+})
+```
+
+## First-party support
+
+| Object or operation                             | PostgreSQL               | SQLite                                                                   | MySQL                    |
+| ----------------------------------------------- | ------------------------ | ------------------------------------------------------------------------ | ------------------------ |
+| Tables, columns, constraints, indexes           | yes                      | tables, columns, and indexes; constraints require an inline/rebuild path | yes                      |
+| Views                                           | yes                      | yes                                                                      | yes                      |
+| Materialized views                              | yes                      | no                                                                       | no                       |
+| Sequences, enums, domains, policies, extensions | yes                      | no                                                                       | no                       |
+| Routines                                        | functions and procedures | no                                                                       | functions and procedures |
+| Partitions                                      | yes                      | no                                                                       | add/drop partition forms |
+| Triggers                                        | yes                      | yes                                                                      | yes                      |
+| Comments and ownership                          | yes                      | no                                                                       | table comments only      |
+| Explicit custom SQL                             | dialect tag must match   | dialect tag must match                                                   | dialect tag must match   |
+
+The support table describes syntax Qubu can render from modeled snapshot facts.
+Server-version checks still apply, such as SQLite column rename and drop-column
+limits and MySQL check-constraint support. An unsupported operation is reported
+as a diagnostic rather than silently omitted. SQLite table constraints are not
+emitted as `ALTER TABLE ... ADD CONSTRAINT`; use a schema snapshot that carries
+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.

package/docs/schema/diff.md

@@ -0,0 +1,75 @@
+# Snapshot diffing
+
+> Compare canonical Snapshot v1 or v2 values and review identity changes before a later planning step.
+
+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.
+
+```ts
+import { diffSnapshots } from 'qubu/diff'
+
+const result = diffSnapshots(previousSnapshot, currentSnapshot)
+
+for (const change of result.changes) {
+  console.log(change.type, change.kind, change.logicalId)
+}
+```
+
+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
+separate `remove` and `add` operations.
+
+## Explicit rename hints
+
+Use a hint when an introspector or schema edit changed the logical ID as well as
+the physical name. Hints are scoped by object kind and namespace. A target may
+use an ID, a physical name, or an exact path when a nested scope repeats an ID.
+
+```ts
+const result = diffSnapshots(previousSnapshot, currentSnapshot, {
+  renameHints: [
+    {
+      kind: 'table',
+      namespace: 'public',
+      from: 'legacy_accounts',
+      to: 'accounts',
+    },
+  ],
+})
+
+result.renames[0]?.source // 'explicit-hint'
+```
+
+Hints must resolve to one object on each side. A wrong namespace, unsupported
+kind, empty target, duplicate mapping, or target that resolves more than once
+produces a diagnostic. `encodeSnapshotRenameHints()` writes deterministic JSON;
+`decodeSnapshotRenameHints()` validates it without throwing.
+
+## Suggestions and safety diagnostics
+
+Structural matching can report a `rename-suggestion` with a confidence score and
+evidence. Suggestions never enter `result.renames` and never replace the
+corresponding add and remove operations. An ambiguous structural match reports
+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
+`add` or `remove` data and produce `lossy` or `unsupported` diagnostics. They
+cannot be silently promoted to a rename.
+
+`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.
+
+Snapshot arrays are normalized by stable IDs or positions before comparison, so
+reordering tables, object groups, columns, or other canonical collections does
+not create changes. Ordered index terms, foreign-key columns, enum positions,
+and routine parameter positions retain their meaning.
+
+Diff output is data only. Feed a resolved result into the
+[migration-plan boundary](migration-plans.md) when a reviewed change list is
+needed; DDL rendering and database execution remain later boundaries.

package/docs/schema/introspection.md

@@ -0,0 +1,214 @@
+# 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.
+
+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
+`qubu/migration` and `qubu/ddl` entrypoints, while migration execution remains
+application-owned. The separate
+`qubu/codegen` entrypoint can create a new machine-owned schema module from a
+complete Snapshot v1 result.
+
+## The pipeline
+
+The caller owns the connection and supplies a small catalog query adapter:
+
+```mermaid
+flowchart LR
+  A[User-owned connection] --> B[Dialect catalog reader]
+  B --> C[Normalized catalog]
+  C --> D[Pure snapshot mapper]
+  D --> E[Canonical snapshot]
+  E -. later .-> F[Snapshot diffing or migration planning]
+  E -. optional .-> G[Generated TypeScript schema]
+```
+
+The reader owns catalog SQL and dialect-specific row normalization. The
+normalized catalog retains physical names, native types, opaque SQL text,
+provenance, current-run catalog references, capabilities, deferred objects,
+and diagnostics. The mapper owns Snapshot v1 shape, stable ordering, identity
+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`:
+
+```ts
+import type { CatalogConnection } from 'qubu/introspection'
+
+const connection: CatalogConnection = {
+  dialect: 'sqlite',
+  query(statement, options) {
+    // Adapt this call to the driver used by the application.
+    return db.query(statement, options)
+  },
+}
+```
+
+The adapter receives fixed catalog statements and bound parameters. Catalog
+text returned by the database is data. Qubu never evaluates it or turns it
+into an executable schema expression.
+
+## Read and map a catalog
+
+Readers return normalized facts. Mapping is a separate operation so the same
+catalog can later support inspection, source generation, or another snapshot
+format:
+
+```ts
+import { mapCatalogToSnapshot, readSqliteCatalog } from 'qubu/introspection'
+
+const catalog = await readSqliteCatalog(connection, { namespace: 'main' })
+const result = mapCatalogToSnapshot(catalog, {
+  namespace: 'main',
+  mode: 'strict',
+})
+
+if (!result.ok) {
+  throw new Error(result.diagnostics.map(issue => issue.message).join('\n'))
+}
+
+result.snapshot.tables // canonical Snapshot v1 data
+```
+
+Pass the successful result itself—not a detached or edited snapshot—to
+`generateSchemaSource()` when a replaceable TypeScript schema is needed. See
+[Generate a schema from introspection](code-generation.md) for that workflow
+and its identity handoff.
+
+Readers may expose additional typed object families through the normalized
+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.
+
+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
+snapshot.
+
+## Identity and physical names
+
+Introspection uses this identity precedence:
+
+1. an explicit identity hint;
+2. a matching entity in a previous snapshot;
+3. the physical database name;
+4. a deterministic fallback for unnamed or invalid names.
+
+Physical names remain unchanged in the snapshot. OIDs, SQLite rowids, and
+internal `sqlite_autoindex_*` names are current-run or implementation details,
+not persisted Qubu identities. A changed physical name is not automatically a
+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.
+
+## Strict and lossy output
+
+Strict mode is the default. If an included table, column, default, generated
+expression, identity, constraint, foreign key, or index cannot be represented
+soundly, mapping returns diagnostics and no snapshot.
+
+Lossy mode is explicit. It may return a snapshot with warnings, but the result
+is marked lossy. Migration planning blocks lossy facts unless the caller
+explicitly handles the omitted behavior.
+
+Only unambiguous literal defaults become snapshot literals. Other defaults,
+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.
+
+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
+limited to the fixed `main` and `temp` catalog statements, so the reader marks
+the catalog visibility as limited instead of combining namespaces.
+
+## MySQL 8 complete catalog surface
+
+The MySQL reader supports MySQL 8.0.16 and later within the MySQL 8 series and
+rejects MariaDB. It reads one selected database from `INFORMATION_SCHEMA` and
+keeps catalog SQL as tagged, unevaluated MySQL data. The complete catalog has
+typed records for views, routines and parameters, triggers, partitions,
+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
+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
+`opaqueObjects` without treating it as a typed routine, trigger, or migration
+operation.
+
+Sequences and materialized views are not typed MySQL families. A sequence-like
+or other non-base table row reported by the catalog is retained as a deferred
+object. MySQL row-level security (RLS) policies, extension objects, and
+ownership are unsupported. Definers are retained as dialect metadata on
+objects that expose them; they do not become ownership records. MySQL capability flags mark
+these families as unsupported.
+
+The query and normalization layout follows the catalog-reading portions of the
+[Drizzle MySQL introspector](https://github.com/drizzle-team/drizzle-orm/blob/main/drizzle-kit/src/introspect-mysql.ts).
+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.
+
+## 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.
+
+Introspection is read-only from Qubu's perspective. Do not pass credentials or
+DSNs through diagnostic fields. Keep driver-specific error text in the
+application's logging boundary, and treat database-provided SQL as opaque
+input.
+
+## What comes next
+
+The canonical snapshot is the handoff to Qubu's pure schema pipeline:
+
+- diffing compares canonical snapshots;
+- rename resolution consumes previous/current snapshots and explicit hints;
+- migration planning consumes semantic diff operations;
+- DDL emitters consume approved plans and dialect capabilities;
+- source generation creates a new machine-owned Snapshot v1 schema baseline.
+
+None of those layers opens a database connection or changes how introspection
+represents catalog facts. DDL emission produces statements; it does not apply
+them. The [ownership map](../reference/supported-surface.md#ownership-boundary)
+keeps this handoff separate from application-owned migration execution.
+
+See the [introspection support matrix](../reference/introspection-support.md)
+for version baselines and dialect-specific limits. Snapshot serialization
+itself remains documented in [Canonical schema snapshots](snapshots.md).

package/docs/schema/migration-plans.md

@@ -0,0 +1,76 @@
+# Migration plans
+
+> Describe reviewed snapshot changes as deterministic data before selecting a DDL emitter.
+
+The optional `qubu/migration` 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.
+
+```ts
+import { createMigrationPlan } from 'qubu/migration'
+
+const result = createMigrationPlan(diff)
+if (!result.ok) {
+  // Review result.plan.diagnostics and provide explicit decisions.
+}
+```
+
+Creation is pure. The planner does not open a connection, execute a transaction,
+render SQL, or create migration history. A physical rename remains a
+`physical-rename` operation; it is never represented as custom SQL or silently
+changed into a drop and add.
+
+## Safety decisions
+
+Safe operations can be inspected immediately. Destructive, review-required,
+unsupported, unknown, and lossy facts remain blocked until an explicit decision
+or matching option is supplied. Decisions are tied to an operation ID or to a
+kind, namespace, and path, and each decision carries a review reason.
+
+```ts
+const reviewed = createMigrationPlan(diff, {
+  decisions: result.plan.operations
+    .filter(operation => operation.status === 'decision-required')
+    .map(operation => ({
+      operationId: operation.id,
+      action: 'allow',
+      reason: 'Reviewed against the deployment change request',
+    })),
+})
+```
+
+Unknown or lossy records are not converted into SQL. If a dialect-specific step
+is genuinely needed, attach it explicitly with `customSql`, including its
+dialect, safety declaration, reason, reversibility, and dependency position:
+
+```ts
+createMigrationPlan(diff, {
+  customSql: [
+    {
+      sql: 'ALTER TABLE accounts VALIDATE CONSTRAINT accounts_check',
+      dialect: { name: 'postgresql', version: 1 },
+      safety: 'review-required',
+      reason: 'The dialect emitter does not model this catalog fact yet',
+      reversible: false,
+      position: 3,
+    },
+  ],
+})
+```
+
+The string is retained as an explicit custom operation only. The planner never
+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;
+`decodeMigrationPlan()` and `validateMigrationPlan()` reject unknown fields,
+future versions, malformed operations, missing edges, and dependency cycles.
+
+After review and approval, pass the plan to
+[`qubu/ddl`](./ddl-emission.md). DDL emission remains separate from
+application-owned migration execution in the package-wide [ownership
+map](../reference/supported-surface.md#ownership-boundary).

package/docs/schema/snapshots.md

@@ -0,0 +1,93 @@
+# Canonical schema snapshots
+
+> Serialize schema metadata into strict, deterministic data and keep serialization separate from diffing, planning, and DDL emission.
+
+Qubu's schema tooling lives behind the `qubu/snapshot` entrypoint. It converts
+an immutable `schema()` registry into versioned data that can be inspected,
+hashed, checked into source control, and handed to a dialect adapter. Importing
+the snapshot entrypoint is optional; ordinary query imports do not load it.
+
+```ts
+import { createSchemaSnapshot, encodeSchemaSnapshot } from 'qubu/snapshot'
+
+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:
+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
+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.
+
+```ts
+import { decodeSchemaSnapshot } from 'qubu/snapshot'
+
+const decoded = decodeSchemaSnapshot(json)
+if (!decoded.ok) {
+  for (const issue of decoded.diagnostics) {
+    console.error(issue.path.join('.'), issue.code, issue.message)
+  }
+}
+```
+
+The decoder is strict. It reports unknown fields, malformed nodes, unsupported
+future format or extension versions, non-canonical entity ordering, wrong
+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.
+
+`schemaSnapshotDigest()` computes a deterministic content digest from canonical
+JSON. The digest is useful for cache keys and fixture assertions only. It is not
+an entity identity, a rename marker, or migration lineage.
+
+## Adapter boundary
+
+`SchemaDialect` is a capability superset of `Dialect`. Create one with
+`createSchemaDialect(queryDialect, hooks)`; the resulting object retains the
+query dialect's name, identifier quoting, placeholders, literals, JSON, casts,
+and advertised capabilities while adding schema encoders and validation under
+`.schema`. Snapshot adapters reference that object instead of constructing a
+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 PostgreSQL adapter is documented in the [PostgreSQL snapshot support
+matrix](../reference/postgres-snapshot.md). Its schema dialect extends the
+`postgresql` query dialect, and snapshot metadata uses that same identity.
+The SQLite adapter is documented in the [SQLite snapshot support
+matrix](../reference/sqlite-snapshot.md).
+The MySQL adapter is documented in the [MySQL snapshot support
+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.
+
+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
+object families.

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

@@ -0,0 +1,104 @@
+# Storage and schema SQL
+
+> Keep application types, SQL domains, physical storage, and schema expressions separate so each adapter can make its own rendering decision.
+
+## 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.
+
+For example, `numeric()` decodes to a TypeScript number, carries `SqlDecimal`,
+uses portable numeric storage, and has a logical decimal cast target. Read
+[SQL semantic types](../sql-semantic-types.md) for operator compatibility and
+contextual literals.
+
+## Record physical storage
+
+Built-in helpers use portable storage descriptors:
+
+| Helper      | Portable storage |
+| ----------- | ---------------- |
+| integer()   | integer          |
+| numeric()   | numeric          |
+| text()      | text             |
+| boolean()   | boolean          |
+| date()      | date             |
+| timestamp() | timestamp        |
+| uuid()      | uuid             |
+| json<T>()   | json             |
+| bigint()    | bigint           |
+| binary()    | binary           |
+
+Use a dialect-native descriptor when a column needs an exact vendor
+declaration:
+
+```ts
+import { nativeColumn, nativeStorage, table } from 'qubu'
+
+const accounts = table('accounts', {
+  handle: nativeColumn(nativeStorage('postgresql', 'citext COLLATE "C"')),
+})
+```
+
+`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.
+
+## Render deterministic schema expressions
+
+Schema SQL uses a different context from query SQL. Built-in scalar expressions
+can be rendered for checks, generated columns, indexes, and other declaration
+metadata:
+
+```ts
+import { eq, table, text } from 'qubu'
+import { renderSchemaSql } from 'qubu/schema'
+
+const accounts = table('accounts', { status: text() })
+
+renderSchemaSql(eq(accounts.status, 'active'), { mode: 'check' })
+// ("status" = 'active')
+```
+
+The schema context emits SQL literals instead of placeholders. It supports
+strings, finite numbers, booleans, bigint, and NULL through the portable
+fallback. A dialect can provide renderSchemaLiteral for another spelling.
+Unsupported values and direct calls to parameter() fail.
+
+Column references render as bare physical identifiers for generated, check, and
+index expressions. Default expressions reject column references because a
+column default cannot depend on another row value. Aggregates, windows, and
+subqueries are rejected in every schema mode.
+
+An extension must opt into the schema contract with `defineSchemaExpression()`:
+
+```ts
+import { defineSchemaExpression, renderSchemaSql } from 'qubu/schema'
+
+const currentDate = defineSchemaExpression('function', context => {
+  context.append('CURRENT_DATE')
+})
+
+renderSchemaSql(currentDate, { mode: 'default' })
+```
+
+## Use raw schema SQL only when necessary
+
+Use `unsafeSchemaSql(dialect, sql)` only for trusted, parameter-free syntax that
+Qubu does not model. Its dialect tag is checked when rendering, and its text is
+preserved apart from normalizing line endings. A normal `makeExpression()`
+extension must pass through the explicit `schemaExpression()` audit boundary
+before schema rendering accepts it.
+
+> [!WARNING]
+> Raw schema SQL does not quote identifiers or bind values. Keep it in trusted
+> extension code.
+
+## Read next
+
+- [Tables and names](tables-and-names.md) covers logical IDs and SQL naming.
+- [Constraints, keys, and indexes](constraints-and-indexes.md) covers metadata
+  consumed by grouped queries and schema adapters.
+- [Canonical schema snapshots](snapshots.md) explains how storage and
+  constraints become serialized data.