qubu 0.0.0 → 0.3.3

package/docs/reference/supported-surface.md

@@ -0,0 +1,104 @@
+# Supported features
+
+> Choose a public package entrypoint, check what Qubu handles, and keep database work on the application side of each adapter.
+
+## Package entrypoints
+
+| Import                  | Kind             | Use it for                                                                                                       |
+| ----------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `qubu`                  | Runtime          | Ordinary query and schema definitions, reads, writes, SQL templates, rendering, EXPLAIN, and execution contracts |
+| `qubu/core`             | Runtime          | Fragment and rendering primitives, dialect construction, SQL types, and extension constructors                   |
+| `qubu/codegen`          | Runtime          | Deterministic machine-owned TypeScript schemas from complete, non-lossy introspection                            |
+| `qubu/ddl`              | Runtime          | DDL preflight and deterministic PostgreSQL, SQLite, or MySQL emission from a migration plan                      |
+| `qubu/diff`             | Runtime          | Canonical Snapshot v1 or v2 comparison, rename hints, suggestions, and safety diagnostics                        |
+| `qubu/drizzle`          | Runtime          | Shared Drizzle conversion errors and dialect types                                                               |
+| `qubu/introspection`    | Runtime          | Catalog readers, normalized catalogs, and mapping to Snapshot v1 or v2                                           |
+| `qubu/migration`        | Runtime          | Pure migration planning with dependencies, decisions, preconditions, and explicit custom SQL                     |
+| `qubu/mysql`            | Runtime          | The MySQL query dialect policy                                                                                   |
+| `qubu/postgres`         | Runtime          | PostgreSQL query dialect helpers such as `postgresDialect()` and `ilike()`                                       |
+| `qubu/schema`           | Runtime          | Advanced schema metadata, storage and constraint models, source models, and schema-expression extensions         |
+| `qubu/snapshot`         | Runtime          | Canonical Snapshot v1 and v2 traversal, encoding, decoding, diagnostics, and digests                             |
+| `qubu/sqlite`           | Runtime          | The SQLite query dialect policy                                                                                  |
+| `qubu/vite`             | Runtime          | The optional `qubu()` Vite compiler hint                                                                         |
+| `qubu/package.json`     | JSON             | The published package manifest                                                                                   |
+| `qubu/drizzle/mysql`    | Runtime          | Runtime conversion from Qubu schemas to MySQL Drizzle tables                                                     |
+| `qubu/drizzle/postgres` | Runtime          | Runtime conversion from Qubu schemas to PostgreSQL Drizzle tables                                                |
+| `qubu/drizzle/sqlite`   | Runtime          | Runtime conversion from Qubu schemas to SQLite Drizzle tables                                                    |
+| `qubu/globals`          | TypeScript types | Opt-in ambient declarations for directive-bearing modules                                                        |
+
+The package validator confirms 17 runtime entrypoints, 18 type entrypoints,
+`qubu/package.json` as JSON, and `qubu/globals` as type-only. Concrete dialect
+constructors live on their database subpaths. The root renderer uses Qubu's
+standard SQL policy by default.
+
+Snapshot dialect behavior is documented in the [PostgreSQL](postgres-snapshot.md),
+[SQLite](sqlite-snapshot.md), and [MySQL](mysql-snapshot.md) support matrices.
+
+## Canonical query vocabulary
+
+Use the root names in new query code: `eq`, `ne`, `lt`, `lte`, `gt`, `gte`,
+`avg`, `min`, `max`, `fetchFirst`, `alias`, `render`, `qubu`, `execute`,
+`deleteFrom`, and `allowAll`. The package does not document competing aliases
+for these operations. Keep advanced fragment, dialect-construction, and
+schema-extension imports on `qubu/core` or `qubu/schema` as shown in the
+entrypoint table.
+
+## Capability map
+
+| Area               | Supported building blocks                                                                                                                                                                                                                                                                                                                                                                |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Schema values      | `table`, immutable `schema` registries with namespaces, portable and dialect-native column storage descriptors, canonical default and generated-column metadata, identity descriptors, named primary, candidate-key, nullable unique, foreign-key, and check constraints, physical object names, included-column indexes, typed dialect extensions, and typed column helpers             |
+| Read queries       | Named projections, spreadable source columns, aliases, joins, typed custom and LATERAL `FROM` sources, correlated subqueries, `WHERE`, grouping with declared-key proofs, `HAVING`, ordering, window expressions, distinctness, pagination, row locking, ordinary and recursive CTEs, subqueries, and set operations                                                                     |
+| Expressions        | Comparison, boolean, arithmetic, null, range, membership, aggregate, window, string, JSON scalar reads, definition-backed and raw casts, cases, parameterized SQL templates, custom expressions, and branded deterministic schema expressions                                                                                                                                            |
+| SQL type metadata  | Portable domains and capabilities, physical column storage descriptors, `SqlTypeOf`, projected SQL type maps, `SourceLike` and `TableLike` field constraints, contextual literals, typed extension values, calls, and casts, plus a permissive `SqlUnknown` fallback                                                                                                                     |
+| Write queries      | `INSERT` values, defaults, and selects; `UPDATE`; `DELETE`; typed assignments; `RETURNING`; and explicit unrestricted-write opt-in                                                                                                                                                                                                                                                       |
+| Rendering          | Standard, PostgreSQL, SQLite, MySQL, and user-created policies for identifiers, placeholders, pagination, row locking, JSON, logical cast targets, schema literals, and EXPLAIN options                                                                                                                                                                                                  |
+| Execution boundary | `QueryAdapter`, opt-in `ExplainableQueryAdapter`, `StreamingQueryAdapter`, and `TransactionalQueryAdapter` capabilities, bound clients from `qubu()`, structured results from `execute()` or `db.execute()`, row-only results from `executeRows()` or `db.rows()`, typed read streams from `stream()` or `db.stream()`, and adapter-decoded plan rows from `explain()` or `db.explain()` |
+| Snapshots          | Pure Snapshot v1 and v2 creation, canonical encoding and strict decoding, immutable data, diagnostics, and content digests                                                                                                                                                                                                                                                               |
+| Introspection      | PostgreSQL, SQLite, and MySQL catalog readers for one selected namespace, normalized catalog data, structured diagnostics, and strict or explicit lossy snapshot mapping                                                                                                                                                                                                                 |
+| Snapshot diffing   | Pure Snapshot v1 and v2 comparison, explicit rename evidence, non-authoritative suggestions, and safety diagnostics                                                                                                                                                                                                                                                                      |
+| Migration planning | Pure, dialect-neutral plans with stable ordering, dependency edges, preconditions, explicit review decisions, and tagged custom SQL                                                                                                                                                                                                                                                      |
+| DDL emission       | Preflight plus deterministic PostgreSQL, SQLite, and MySQL statements from an approved `MigrationPlan` and matching `SchemaDialect`                                                                                                                                                                                                                                                      |
+| Build tooling      | The optional Vite directive transform and its matching TypeScript ambient declarations                                                                                                                                                                                                                                                                                                   |
+| Drizzle conversion | Optional, dialect-specific runtime conversion from Qubu schema registries to Drizzle tables                                                                                                                                                                                                                                                                                              |
+| Source generation  | Pure Snapshot v1 table source printing, deterministic camelCase IDs, exact physical metadata, controlled type mappings, and structured failure diagnostics                                                                                                                                                                                                                               |
+
+## Ownership boundary
+
+Snapshot creation, diffing, migration planning, and DDL emission are pure.
+`execute()`, clients, and catalog readers can reach a driver only through
+interfaces the application provides. Qubu can emit DDL, but it never applies
+that DDL to a database.
+
+| Boundary                 | Qubu side                                                                                                                                                                                                                                                                                                                         | Application side                                                                                                                                                                                                                                                                |
+| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Query rendering          | Builds a typed query and renders SQL text with ordered raw parameter values                                                                                                                                                                                                                                                       | Keeps the runtime database schema aligned with query definitions and validates any dynamic syntax passed to an unsafe helper                                                                                                                                                    |
+| Query execution          | Binds an adapter with `qubu()` when requested; renders and passes statements to `QueryAdapter`, `ExplainableQueryAdapter`, or a read-only `StreamingQueryAdapter`; scopes `db.transaction()` callbacks through `TransactionalQueryAdapter`; returns `ExecutionResult`, `ExplainResult`, rows, or an adapter-owned `AsyncIterable` | Owns the adapter, driver, connections, pools, cursors, stream cleanup, transaction begin/commit/rollback, savepoints, retries, parameter encoding, application-row and plan-row decoding, backpressure, cancellation behavior, driver error translation, and database lifecycle |
+| Catalog introspection    | Selects fixed parameterized catalog queries, normalizes rows, and maps catalog data to snapshots                                                                                                                                                                                                                                  | Supplies `CatalogConnection`, credentials, already-decoded catalog rows, logging, and connection lifecycle                                                                                                                                                                      |
+| Schema source generation | Prints deterministic TypeScript from complete, non-lossy Snapshot v1 introspection without writing files                                                                                                                                                                                                                          | Owns generated-file writes, replacement policy, hand-edit merging, and CLI integration                                                                                                                                                                                          |
+| Schema changes           | Creates snapshots, compares them, builds deterministic migration plans, and emits DDL from approved plans with preflight diagnostics                                                                                                                                                                                              | Reviews decisions, executes or rolls back statements, acquires locks, manages transactions and migration journals, and owns database lifecycle                                                                                                                                  |
+
+Start with [Dialects and execution](../dialects-and-execution.md) for the query
+adapter contract. The schema path is documented in [Canonical schema
+snapshots](../schema/snapshots.md), [Snapshot diffing](../schema/diff.md),
+[Migration plans](../schema/migration-plans.md), and [DDL
+emission](../schema/ddl-emission.md).
+
+## SQL safety boundaries
+
+Qubu binds values through the render context and quotes identifiers through the
+active dialect. `UPDATE` and `DELETE` require a `WHERE` clause unless the caller
+passes `allowAll()`.
+
+The `sql` tag treats static template text as trusted SQL syntax. Ordinary
+substitutions become parameters, and fragment substitutions compose through the
+active renderer. Dynamic identifiers and syntax remain explicit through
+`identifier()` and unsafe helpers. Those helpers are not sanitizers. Validate
+dynamic syntax against an application-owned allowlist before it reaches an
+unsafe helper.
+
+SQL semantic types provide compile-time portable capability and compatibility
+checks. They do not prove the runtime schema state or model every dialect's
+implicit coercions. Custom and untyped extensions default to permissive
+`SqlUnknown`; declare a domain when an extension should participate in stricter
+checks.

package/docs/schema/catalog-model.md

@@ -0,0 +1,58 @@
+# Complete catalog model
+
+Qubu keeps database discovery in a normalized catalog before producing a
+snapshot. The catalog is a read-only record of observed facts; it does not
+contain a connection, execute catalog SQL, or assign database catalog keys as
+persisted logical IDs.
+
+The optional `qubu/introspection` entry point exposes the complete object
+families and an immutable materializer:
+
+```ts
+import {
+  createCompleteIntrospectionCatalog,
+  mapCatalogToCompleteSnapshot,
+} from 'qubu/introspection'
+
+const completeCatalog = createCompleteIntrospectionCatalog(catalog)
+const result = mapCatalogToCompleteSnapshot(completeCatalog)
+```
+
+Tables, columns, views, materialized views, sequences, enums, domains,
+collations, triggers, routines, partitions, row-level policies, extension
+objects, comments, and ownership metadata have typed records. A reader may
+also retain a deferred or opaque object when it observes a family that Qubu
+cannot yet normalize. Such an object remains visible and can carry opaque
+catalog data, SQL text, provenance, and a dialect extension; it is never
+silently dropped.
+
+Physical names and references describe the current database. Stable logical
+IDs are evidence selected by the adapter's identity policy. PostgreSQL OIDs,
+SQLite implementation names, and similar catalog keys stay in current-run
+references and are not used as logical IDs.
+
+## Snapshot v2
+
+`qubu/snapshot` provides the strict complete format as a separate API:
+
+```ts
+import {
+  decodeCompleteSchemaSnapshot,
+  encodeCompleteSchemaSnapshot,
+} from 'qubu/snapshot'
+
+const encoded = encodeCompleteSchemaSnapshot(snapshotV2)
+const decoded = decodeCompleteSchemaSnapshot(encoded)
+```
+
+Snapshot v2 uses the same `qubu-schema` envelope with `version: 2`. Its
+namespace, capability facts, object-family arrays, cross-object references,
+provenance, typed dialect extensions, and deferred/opaque boundaries are
+strictly validated. Arrays are ordered by logical ID (with ordinal sequences
+and index terms ordered by their semantic position), and the digest is computed
+from the deterministic encoding.
+
+Snapshot v1 remains a separate strict format. `decodeSchemaSnapshot` still
+accepts only v1 and continues to reject unknown fields and future versions;
+v2 callers must select `decodeCompleteSchemaSnapshot` explicitly. Neither
+snapshot format evaluates database-provided SQL.

package/docs/schema/code-generation.md

@@ -0,0 +1,139 @@
+# Generate a schema from introspection
+
+> Turn one complete, non-lossy Snapshot v1 introspection result into a deterministic, machine-owned TypeScript schema module.
+
+Source generation is an optional capability exported from `qubu/codegen`. It
+is a pure handoff after introspection: it opens no connection, runs no catalog
+query, and writes no file. The caller owns those boundaries.
+
+## Generate a module
+
+Read and map one namespace in strict mode, then pass that exact result to the
+generator:
+
+```ts
+import { writeFile } from 'node:fs/promises'
+import { generateSchemaSource } from 'qubu/codegen'
+import { mapCatalogToSnapshot, readSqliteCatalog } from 'qubu/introspection'
+
+const catalog = await readSqliteCatalog(connection, { namespace: 'main' })
+const introspection = mapCatalogToSnapshot(catalog, { namespace: 'main' })
+const generated = generateSchemaSource(introspection)
+
+if (!generated.ok) {
+  throw new Error(generated.diagnostics.map(issue => issue.message).join('\n'))
+}
+
+await writeFile('src/schema.generated.ts', generated.source, 'utf8')
+```
+
+`writeFile()` belongs to the application; `generateSchemaSource()` only
+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.
+
+## Adopt the generated identity baseline
+
+The first introspection snapshot commonly uses physical names as logical IDs.
+Generated declarations use deterministic camelCase registry, table, column,
+constraint, and index IDs while retaining every physical database name. Once
+the generated module is accepted, its serialized snapshot becomes the identity
+baseline for the next catalog read:
+
+```ts
+import { mapCatalogToSnapshot } from 'qubu/introspection'
+import { createSqliteSchemaSnapshot } from 'qubu/snapshot'
+import { mainSchema } from './schema.generated.ts'
+
+const previousSnapshot = createSqliteSchemaSnapshot(mainSchema)
+const next = mapCatalogToSnapshot(nextCatalog, {
+  namespace: 'main',
+  previousSnapshot,
+})
+```
+
+This handoff is deliberate. Do not keep using the pre-generation snapshot as
+the long-term identity source, or later diffs will compare physical IDs with
+the new generated IDs.
+
+## Control names and column types
+
+Application output, insert, and update types default independently to
+`unknown`. Qubu may attach a SQL semantic domain only when catalog evidence is
+exact. Native storage always keeps the catalog declaration, even when the
+semantic domain remains `SqlUnknown`.
+
+Use the controlled callbacks to adopt trusted names or application mappings:
+
+```ts
+const generated = generateSchemaSource(introspection, {
+  naming(context) {
+    if (context.kind === 'table' && context.physicalName === 'user_records') {
+      return 'users'
+    }
+  },
+  mapColumn(context) {
+    if (context.columnPhysicalName === 'account_id') {
+      return {
+        output: 'string',
+        insert: 'string',
+        update: 'string',
+        sqlDomain: 'uuid',
+      }
+    }
+  },
+})
+```
+
+Callbacks select names and fixed type tokens; they never take over printing and
+cannot return imports, expressions, comments, or arbitrary source. A returned
+name must still be a safe camelCase ID. Collisions and unsafe names fail with
+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.
+
+> [!IMPORTANT]
+> A database can allow a foreign key to reference a nullable `UNIQUE`
+> constraint. Snapshot v1 retains that constraint as nullable uniqueness, not
+> as a Qubu candidate key. Source generation returns an
+> `unrepresentable-fact` diagnostic instead of weakening the generated
+> `references()` proof. Use a non-null primary key, strict unique key, or
+> candidate index as the foreign-key target before adopting generated source.
+
+Catalog names, native declarations, SQL, and extension metadata are untrusted
+input. The printer serializes them only as controlled literals beneath a
+static header. It does not interpolate catalog text as code or comments, parse
+opaque SQL, or merge a previous generated file with hand edits. Treat the file
+as replaceable output and keep application customizations in separate modules.
+
+The public types and TSDoc on `generateSchemaSource()`,
+`SchemaCodegenOptions`, and `CodegenDiagnostic` define the exact callback and
+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.
+
+The entrypoint does not provide a CLI, filesystem ownership, live driver
+integration, multiple namespaces, runtime schema materialization, migrations,
+DDL, Snapshot v2 object generation, or hand-edit merging. 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

@@ -0,0 +1,130 @@
+# Column behavior and write types
+
+> Separate selected values from insert and update inputs, then record the database rules that make fields optional or generated.
+
+## Give each operation its own type
+
+Every column has a selected output type. It can also describe what inserts and
+updates accept:
+
+| Option           | Selected output | Insert input      | Update input      |
+| ---------------- | --------------- | ----------------- | ----------------- |
+| nullable: true   | T or null       | accepts T or null | accepts T or null |
+| hasDefault: true | unchanged       | key is optional   | unchanged         |
+| generated: true  | unchanged       | key is omitted    | key is omitted    |
+
+Use `column<Output, Insert, Update>()` when the driver returns a different type
+from the type the application writes:
+
+```ts
+import { column, integer, table, text } from 'qubu'
+
+const accounts = table('accounts', {
+  id: integer({ generated: true }),
+  email: text(),
+  nickname: text({ nullable: true, hasDefault: true }),
+  externalScore: column<number, string, number>({ nullable: true }),
+})
+```
+
+The selected `externalScore` is number | null. Inserts accept string | null, and
+updates accept number | null.
+
+## Describe defaults and generated columns
+
+The legacy hasDefault and generated flags describe the write contract. Use
+complete metadata when schema tooling also needs the database fact:
+
+```ts
+import {
+  boolean,
+  generatedColumn,
+  identityColumn,
+  integer,
+  table,
+  text,
+  value,
+} from 'qubu'
+import { defineSchemaExpression } from 'qubu/schema'
+
+const currentTimestamp = defineSchemaExpression('function', context => {
+  context.append('CURRENT_TIMESTAMP')
+})
+
+const accounts = table('accounts', {
+  id: integer({ identity: identityColumn('always') }),
+  status: text({ default: 'pending' }),
+  active: boolean({ default: true }),
+  score: integer({
+    generatedColumn: generatedColumn(value(1), 'stored'),
+  }),
+  createdAt: text({
+    default: currentTimestamp,
+  }),
+})
+```
+
+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.
+
+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.
+
+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
+[snapshot overview](snapshots.md) and its dialect matrices.
+
+## Narrow an application type
+
+Use `$type<T>()` to narrow a helper's TypeScript type without changing its
+runtime column definition:
+
+```ts
+import { table, text } from 'qubu'
+
+const users = table('users', {
+  status: text().$type<'active' | 'disabled'>(),
+})
+```
+
+The narrowed type applies to selected values and insert and update inputs. It
+does not validate values at runtime or add a database constraint.
+
+## Derive write input types
+
+`TableInsertInput` and `TableUpdateInput` expose the same rules to application
+code. The following example uses the accounts table from the earlier example:
+
+```ts
+import type { TableInsertInput, TableUpdateInput } from 'qubu'
+
+type AccountInsert = TableInsertInput<typeof accounts.definitions>
+type AccountUpdate = TableUpdateInput<typeof accounts.definitions>
+
+const insert: AccountInsert = {
+  email: 'ada@example.com',
+  externalScore: '10',
+}
+
+const update: AccountUpdate = {
+  nickname: null,
+  externalScore: 10,
+}
+```
+
+`id` is not accepted because it is generated. `nickname` is optional on insert
+because the database supplies a default, but it remains a valid nullable update
+field.
+
+Continue with [Write mutations](../guides/mutations.md) for typed INSERT,
+UPDATE, and DELETE statements.

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

@@ -0,0 +1,180 @@
+# Constraints, keys, and indexes
+
+> Record database constraints and indexes when Qubu needs them to check foreign keys or grouped query projections.
+
+## Declare constraints and indexes
+
+Pass a metadata callback to `table()` when the application schema knows which
+rules the database enforces:
+
+```ts
+import {
+  check,
+  eq,
+  foreignKey,
+  index,
+  integer,
+  primaryKey,
+  references,
+  table,
+  text,
+  unique,
+  value,
+} from 'qubu'
+
+const accounts = table(
+  'accounts',
+  { id: integer(), slug: text() },
+  accounts => ({
+    constraints: {
+      accountsPrimary: primaryKey(accounts.id),
+    },
+    indexes: {
+      accountsSlug: index([accounts.slug], { unique: true }),
+    },
+  })
+)
+
+const memberships = table(
+  'memberships',
+  {
+    id: integer(),
+    accountId: integer(),
+    slug: text(),
+    displayName: text(),
+  },
+  memberships => ({
+    constraints: {
+      membershipsPrimary: primaryKey(memberships.id),
+      membershipsUnique: unique(memberships.accountId, memberships.slug),
+      membershipsAccount: foreignKey(
+        [memberships.accountId],
+        references(accounts, accounts.id)
+      ),
+      membershipsCheck: check(eq(memberships.slug, value('public'))),
+    },
+    indexes: {
+      membershipsAccountSlug: index([memberships.accountId, memberships.slug], {
+        unique: true,
+      }),
+    },
+  })
+)
+```
+
+The callback receives the preliminary table, including its typed columns. Give
+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.
+
+## Distinguish candidate keys from unique constraints
+
+`unique()` describes a non-null candidate key. Qubu can use it to prove that a
+grouped key determines other columns. Every key column must belong to the
+callback table and be non-nullable.
+
+Use `uniqueConstraint()` when the database enforces uniqueness but the rule should
+not prove a functional dependency:
+
+```ts
+import { table, text, uniqueConstraint } from 'qubu'
+
+const accounts = table(
+  'accounts',
+  { email: text({ nullable: true }) },
+  accounts => ({
+    constraints: {
+      emailUnique: uniqueConstraint(accounts.email, {
+        nulls: 'distinct',
+        physicalName: 'accounts_email_key',
+      }),
+    },
+    indexes: {},
+  })
+)
+```
+
+`nulls: 'distinct'` describes the common rule where multiple NULLs do not
+conflict. `'not-distinct'` describes a rule where NULL participates in the
+comparison. Neither form proves that a grouped column determines the rest of a
+row.
+
+## Add foreign keys
+
+`foreignKey(localColumns, target, options)` accepts single or composite tuples.
+Build the target with `references(table, ...columns)`. The tuples must have the
+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:
+
+```ts
+const memberships = table(
+  'memberships',
+  { accountId: integer() },
+  memberships => ({
+    constraints: {
+      accountForeign: foreignKey(
+        [memberships.accountId],
+        references(accounts, accounts.id),
+        { onDelete: 'cascade', onUpdate: 'cascade' }
+      ),
+    },
+    indexes: {},
+  })
+)
+```
+
+Use the preliminary callback table for direct self-references. Wrap the target
+in a function when two modules import each other's tables.
+
+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
+domain.
+
+## Use key metadata for grouped queries
+
+Grouping every column in a declared candidate key lets Qubu select other
+columns from that source:
+
+```ts
+import { count, from, groupBy, select } from 'qubu'
+
+const summary = select(
+  { displayName: memberships.displayName, total: count() },
+  from(memberships),
+  groupBy(memberships.accountId, memberships.slug)
+)
+```
+
+A primary key, `unique()` constraint, or eligible unique index supplies the
+proof. A partial index, expression index, nullable key, or included column does
+not silently become candidate-key evidence.
+
+The proof follows a table alias and remains source-local through a join,
+including a source made nullable by `leftJoin()`. It does not cross a derived
+query, CTE, LATERAL query, or custom-source boundary. Those relations need an
+explicit proof on their own source model.
+
+## Store dialect-specific metadata
+
+Index methods, operator classes, concurrency, storage parameters, and
+MySQL-specific algorithm or locking settings belong in the typed dialect
+extension on an index. Constraint extensions follow the same pattern. A
+dialect validator reports an error when the selected engine does not support an
+extension.
+
+## Read next
+
+- [Column behavior and write types](columns-and-writes.md) covers metadata
+  attached to individual columns.
+- [Storage and schema SQL](storage-and-schema-sql.md) covers physical storage
+  and deterministic expressions.
+- [SQL semantic types](../sql-semantic-types.md) explains type compatibility.