qubu 0.5.1 → 0.6.1

package/docs/migrations/index.md

@@ -4,13 +4,13 @@
 
 Qubu migrations are split across explicit ownership boundaries:
 
-| Owner           | Imports                                            | Responsibility                                                                                                               |
-| --------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| `qubu`          | `qubu/snapshot`, `qubu/diff`, `qubu/introspection` | Pure schema snapshots, comparison, and catalog mapping                                                                       |
-| `@qubu/migrate` | Focused subpaths listed below                      | Pure planning and compilation plus portable artifacts, journals, execution, status, baselines, and bootstrap                 |
-| `@qubu/cli`     | `@qubu/cli/config`, `@qubu/cli/repository`         | Node.js configuration loading, artifact files, commands, output, and process exit behavior                                   |
-| Adapter package | `@qubu/adapter-*/migration`                        | Pinned driver sessions, parameter binding, transactions, leases, locks, database journal storage, and failure classification |
-| Application     | Its own configuration and deployment code          | Credentials, environment selection, approval policy, custom SQL, rollout timing, and legacy cutover decisions                |
+| Owner           | Imports                                                                                                                     | Responsibility                                                                                                               |
+| --------------- | --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `qubu`          | `qubu/snapshot`, `qubu/snapshot/postgres`, `qubu/snapshot/sqlite`, `qubu/snapshot/mysql`, `qubu/diff`, `qubu/introspection` | Pure schema snapshots, comparison, and catalog mapping                                                                       |
+| `@qubu/migrate` | Focused subpaths listed below                                                                                               | Pure planning and compilation plus portable artifacts, journals, execution, status, baselines, and bootstrap                 |
+| `@qubu/cli`     | `@qubu/cli/config`, `@qubu/cli/repository`                                                                                  | Node.js configuration loading, artifact files, commands, output, and process exit behavior                                   |
+| Adapter package | `@qubu/adapter-*/migration`                                                                                                 | Pinned driver sessions, parameter binding, transactions, leases, locks, database journal storage, and failure classification |
+| Application     | Its own configuration and deployment code                                                                                   | Credentials, environment selection, approval policy, custom SQL, rollout timing, and legacy cutover decisions                |
 
 The pre-alpha `qubu/migration` and `qubu/ddl` entrypoints no longer exist. Use
 the extracted compiler entrypoints:
@@ -25,18 +25,26 @@ The `@qubu/migrate` root intentionally exports only format/version constants
 and the central plan and artifact types. Import behavior from its focused
 entrypoint:
 
-| Entrypoint                 | Use it for                                                                 |
-| -------------------------- | -------------------------------------------------------------------------- |
-| `@qubu/migrate/plan`       | Create, encode, decode, fingerprint, and validate migration plans          |
-| `@qubu/migrate/ddl`        | Preview deterministic dialect SQL without opening a database               |
-| `@qubu/migrate/artifact`   | Compile programs; canonicalize, digest, seal, encode, and decode artifacts |
-| `@qubu/migrate/repository` | Verify a complete artifact chain and its journal prefix                    |
-| `@qubu/migrate/journal`    | Implement or inspect the storage-neutral journal contract                  |
-| `@qubu/migrate/executor`   | Apply artifacts and reconcile uncertain attempts                           |
-| `@qubu/migrate/baseline`   | Verify and record the initial non-executable baseline                      |
-| `@qubu/migrate/status`     | Inspect pending work, drift, requirements, and interrupted attempts        |
-| `@qubu/migrate/bootstrap`  | Plan a fresh SQLite database through the normal compiler                   |
-| `@qubu/migrate/testing`    | Test adapter capabilities and deterministic failure boundaries             |
+| Entrypoint                         | Use it for                                                                                                                    |
+| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `@qubu/migrate/plan`               | Create, encode, decode, fingerprint, and validate migration plans                                                             |
+| `@qubu/migrate/ddl`                | Preview deterministic dialect SQL without opening a database                                                                  |
+| `@qubu/migrate/ddl/postgres`       | Preview PostgreSQL SQL from an approved migration plan                                                                        |
+| `@qubu/migrate/ddl/sqlite`         | Preview SQLite SQL from an approved migration plan                                                                            |
+| `@qubu/migrate/ddl/mysql`          | Preview MySQL SQL from an approved migration plan                                                                             |
+| `@qubu/migrate/artifact`           | Compile programs with a caller-supplied `SchemaDialect`; canonicalize, digest, seal, encode, and decode artifacts             |
+| `@qubu/migrate/artifact/postgres`  | Compile reviewed plans with PostgreSQL's schema dialect                                                                       |
+| `@qubu/migrate/artifact/sqlite`    | Compile reviewed plans with SQLite's schema dialect, including table rebuilds                                                 |
+| `@qubu/migrate/artifact/mysql`     | Compile reviewed plans with MySQL's schema dialect                                                                            |
+| `@qubu/migrate/repository`         | Verify a complete artifact chain and its journal prefix                                                                       |
+| `@qubu/migrate/journal`            | Implement or inspect the storage-neutral journal contract                                                                     |
+| `@qubu/migrate/executor`           | Apply artifacts and reconcile uncertain attempts                                                                              |
+| `@qubu/migrate/baseline`           | Verify and record the initial non-executable baseline                                                                         |
+| `@qubu/migrate/status`             | Inspect pending work, drift, requirements, and interrupted attempts                                                           |
+| `@qubu/migrate/bootstrap`          | Prepare a fresh schema diff and expose shared bootstrap types; accepts a caller-supplied `SchemaDialect` for generic planning |
+| `@qubu/migrate/bootstrap/postgres` | Plan a fresh PostgreSQL schema through the normal compiler                                                                    |
+| `@qubu/migrate/bootstrap/sqlite`   | Plan a fresh SQLite schema through the normal compiler                                                                        |
+| `@qubu/migrate/testing`            | Test adapter capabilities and deterministic failure boundaries                                                                |
 
 Start with [Artifacts and approval policy](artifacts-and-policy.md) when
 reviewing a migration format. Check [Adapter capability
@@ -44,3 +52,33 @@ profiles](adapters.md), use [Command line operations](operations.md) to
 configure an application, then keep [Recovery and reconciliation](recovery.md)
 with the deployment runbook. [Lotta Games adoption](lotta-adoption.md) records
 the downstream cutover boundary and current combo-matrix blocker.
+
+Choose the dialect-specific bootstrap entrypoint when using a built-in dialect:
+
+```ts
+import { planSchemaBootstrap } from "@qubu/migrate/bootstrap/postgres"
+
+const result = planSchemaBootstrap(targetSnapshot)
+```
+
+The neutral `@qubu/migrate/bootstrap` entrypoint contains the shared preparation
+logic and generic planner. The PostgreSQL and SQLite entrypoints each import
+only their matching schema dialect.
+
+Use the same entrypoint pattern for convenience artifact compilers:
+
+```ts
+import { compileMigrationProgram } from "@qubu/migrate/artifact/postgres"
+
+const compiled = compileMigrationProgram(plan)
+```
+
+The DDL entrypoints follow the same pattern. Use the neutral entrypoint when
+the application supplies a `SchemaDialect`; use a dialect subpath when the
+built-in dialect should be selected by the module:
+
+```ts
+import { emitMigrationPlan } from "@qubu/migrate/ddl/postgres"
+
+const preview = emitMigrationPlan(plan)
+```

package/docs/migrations/operations.md

@@ -70,7 +70,7 @@ working directory.
 | `qubu migrate apply [--dry-run]`                                                                    | Applies the complete verified pending chain; dry-run performs status/preflight only                                                         | It never limits discovery to Git-added or branch-diff files                                                    |
 | `qubu migrate baseline <id> --confirm <fact>... [--dry-run]`                                        | Without dry-run, strictly compares the live managed schema, initializes an empty journal, records baseline, then writes the artifact        | Requires an empty artifact repository and all seven exact confirmations; dry-run does not inspect the database |
 | `qubu migrate reconcile <attempt-id> --outcome applied\|rolled_back --reason <text>`                | Runs application-owned verification, then records the explicit outcome                                                                      | Requires `verifyReconciliation` in config; no automatic inference                                              |
-| `qubu schema bootstrap [--approve <operation-id=reason>...] [--dry-run]`                            | Plans an empty SQLite snapshot through diff/plan/program; executes through the normal executor unless dry-run                               | Currently rejects non-SQLite targets                                                                           |
+| `qubu schema bootstrap [--approve <operation-id=reason>...] [--dry-run]`                            | Plans an empty SQLite or PostgreSQL snapshot through diff/plan/program; executes through the normal executor unless dry-run                 | Rejects other dialects; unsafe or incomplete facts still require exact approvals or custom programs            |
 
 JSON output is stable, newline-terminated, recursively key-sorted, and redacts
 credential-like keys and credentials or secrets embedded in URLs. Human output
@@ -94,11 +94,25 @@ snapshot. Logical IDs help reporting but do not prove equality. Objects not
 owned by the managed snapshot are returned separately as `unmanagedObjects`;
 Qubu journal objects are excluded by migration snapshot readers.
 
-`schema bootstrap` is for a fresh SQLite database. It produces the same
-versioned program and validation path as a migration. SQLite inline constraints
-are compiled into table creation, while table rebuilds are explicit phases with
-copy/postcondition checks. Session settings such as SQLite PRAGMAs remain in
-the application or adapter setup.
+`schema bootstrap` is for a fresh SQLite database or a fresh PostgreSQL schema.
+It produces the same reviewed plan, versioned program, sealed artifact, and
+executor path as a migration. A complete PostgreSQL snapshot retains standalone
+enums as authoritative objects; bootstrap creates each enum before a table that
+uses it as a native column type. SQLite inline constraints are compiled into
+table creation, while table rebuilds are explicit phases with copy/postcondition
+checks. Session settings such as SQLite PRAGMAs remain in the application or
+adapter setup.
+
+Use the reviewed complete snapshot directly as the PostgreSQL target:
+
+```bash
+qubu schema bootstrap --dry-run --format json --non-interactive
+```
+
+The dry run prints the ordered phases without opening the adapter. Remove
+`--dry-run` only after reviewing any operation IDs that require `--approve` or
+an application-owned custom program. Bootstrap does not import or replay
+Drizzle migration history.
 
 ## Baseline and cutover checklist
 

package/docs/reference/mysql-snapshot.md

@@ -4,13 +4,13 @@
 > MySQL facts Qubu v1 can encode and the combinations that need a later server
 > version or engine policy.
 
-Import the adapter from the optional snapshot entrypoint:
+Import the adapter from the MySQL snapshot subpath:
 
 ```ts
-import { createMysqlSchemaSnapshot, tryCreateMysqlSchemaSnapshot } from "qubu/snapshot"
+import { createSchemaSnapshot, tryCreateSchemaSnapshot } from "qubu/snapshot/mysql"
 
-const snapshot = createMysqlSchemaSnapshot(appSchema)
-const result = tryCreateMysqlSchemaSnapshot(appSchema)
+const snapshot = createSchemaSnapshot(appSchema)
+const result = tryCreateSchemaSnapshot(appSchema)
 ```
 
 The snapshot dialect is named `mysql`, the same name used by Qubu's query
@@ -38,7 +38,7 @@ Capability checks run before common traversal. Use the non-throwing form when
 a schema may include a MySQL engine or version-specific feature:
 
 ```ts
-const result = tryCreateMysqlSchemaSnapshot(appSchema)
+const result = tryCreateSchemaSnapshot(appSchema)
 if (!result.ok) {
   for (const issue of result.diagnostics) {
     console.error(issue.path.join("."), issue.code, issue.message)

package/docs/reference/postgres-snapshot.md

@@ -4,16 +4,16 @@
 > PostgreSQL facts Qubu v1 can encode and the cases that need a later server
 > version policy.
 
-Import the adapter from the optional snapshot entrypoint:
+Import the adapter from the PostgreSQL snapshot subpath:
 
 ```ts
+import { createSchemaSnapshot } from "qubu/snapshot"
 import {
-  createSchemaSnapshot,
-  createPostgresSchemaSnapshot,
+  createSchemaSnapshot as createPostgresSnapshot,
   postgresSnapshotAdapter,
-} from "qubu/snapshot"
+} from "qubu/snapshot/postgres"
 
-const snapshot = createPostgresSchemaSnapshot(appSchema)
+const snapshot = createPostgresSnapshot(appSchema)
 // Equivalent: createSchemaSnapshot(appSchema, { adapter: postgresSnapshotAdapter })
 ```
 
@@ -46,9 +46,9 @@ schema and application boundaries.
 Use the non-throwing form when a schema may contain a server-specific feature:
 
 ```ts
-import { tryCreatePostgresSchemaSnapshot } from "qubu/snapshot"
+import { tryCreateSchemaSnapshot } from "qubu/snapshot/postgres"
 
-const result = tryCreatePostgresSchemaSnapshot(appSchema)
+const result = tryCreateSchemaSnapshot(appSchema)
 if (!result.ok) {
   for (const issue of result.diagnostics) {
     console.error(issue.path.join("."), issue.code, issue.message)

package/docs/reference/sqlite-snapshot.md

@@ -2,13 +2,13 @@
 
 > Use this matrix to decide which SQLite schema facts Qubu v1 can serialize and which combinations must be diagnosed before a snapshot is written.
 
-Import the adapter from the optional snapshot entrypoint:
+Import the adapter from the SQLite snapshot subpath:
 
 ```ts
-import { createSqliteSchemaSnapshot, tryCreateSqliteSchemaSnapshot } from "qubu/snapshot"
+import { createSchemaSnapshot, tryCreateSchemaSnapshot } from "qubu/snapshot/sqlite"
 
-const snapshot = createSqliteSchemaSnapshot(appSchema)
-const result = tryCreateSqliteSchemaSnapshot(appSchema)
+const snapshot = createSchemaSnapshot(appSchema)
+const result = tryCreateSchemaSnapshot(appSchema)
 ```
 
 The snapshot dialect is `sqlite`, the same name used by Qubu's query dialect.
@@ -36,7 +36,7 @@ Capability checks run before common traversal. Use the non-throwing form when a
 schema may include a feature that depends on a SQLite version or table shape:
 
 ```ts
-const result = tryCreateSqliteSchemaSnapshot(appSchema)
+const result = tryCreateSchemaSnapshot(appSchema)
 if (!result.ok) {
   for (const issue of result.diagnostics) {
     console.error(issue.path.join("."), issue.code, issue.message)

package/docs/reference/supported-surface.md

@@ -10,24 +10,38 @@
 | `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/diff`                               | Runtime          | Canonical Snapshot v1 or v2 comparison, rename hints, suggestions, and safety diagnostics                        |
-| `qubu/introspection`                      | Runtime          | Catalog readers, normalized catalogs, and mapping to Snapshot v1 or v2                                           |
+| `qubu/introspection`                      | Runtime          | Shared catalog contracts, normalized catalog models, diagnostics, and mapping to Snapshot v1 or v2               |
+| `qubu/introspection/postgres`             | Runtime          | PostgreSQL catalog reader and catalog queries for one selected namespace                                         |
+| `qubu/introspection/sqlite`               | Runtime          | SQLite catalog reader and catalog queries for one selected namespace                                             |
+| `qubu/introspection/mysql`                | Runtime          | MySQL catalog reader and catalog queries for one selected namespace                                              |
 | `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 fingerprints                        |
+| `qubu/snapshot/mysql`                     | Runtime          | MySQL snapshot adapter, schema dialect, and convenience creators                                                 |
+| `qubu/snapshot/postgres`                  | Runtime          | PostgreSQL snapshot adapter, schema dialect, and convenience creators                                            |
+| `qubu/snapshot/sqlite`                    | Runtime          | SQLite snapshot adapter, schema dialect, affinity helper, and convenience creators                               |
 | `qubu/sqlite`                             | Runtime          | The SQLite query dialect policy and native SQLite column factories                                               |
 | `qubu/vite`                               | Runtime          | The optional `qubu()` Vite compiler hint                                                                         |
 | `qubu/package.json`                       | JSON             | The published package manifest                                                                                   |
 | `@qubu/migrate`                           | Runtime          | Migration compiler format identity and shared plan types                                                         |
 | `@qubu/migrate/plan`                      | Runtime          | Pure migration planning with dependencies, decisions, preconditions, and explicit custom SQL                     |
-| `@qubu/migrate/ddl`                       | Runtime          | DDL preflight and deterministic PostgreSQL, SQLite, or MySQL emission from a migration plan                      |
-| `@qubu/migrate/artifact`                  | Runtime          | Versioned programs, strict artifacts and baselines, canonical encoding, and SHA-256 integrity                    |
+| `@qubu/migrate/ddl`                       | Runtime          | DDL preflight and generic emission from a migration plan and supplied schema dialect                             |
+| `@qubu/migrate/ddl/postgres`              | Runtime          | PostgreSQL DDL emission from an approved migration plan                                                          |
+| `@qubu/migrate/ddl/sqlite`                | Runtime          | SQLite DDL emission from an approved migration plan                                                              |
+| `@qubu/migrate/ddl/mysql`                 | Runtime          | MySQL DDL emission from an approved migration plan                                                               |
+| `@qubu/migrate/artifact`                  | Runtime          | Generic versioned program compilation with a caller-supplied schema dialect, plus strict artifacts and baselines |
+| `@qubu/migrate/artifact/postgres`         | Runtime          | PostgreSQL versioned program compilation                                                                         |
+| `@qubu/migrate/artifact/sqlite`           | Runtime          | SQLite versioned program compilation, including table rebuilds                                                   |
+| `@qubu/migrate/artifact/mysql`            | Runtime          | MySQL versioned program compilation                                                                              |
 | `@qubu/migrate/repository`                | Runtime          | Strict full-chain and journal-prefix verification                                                                |
 | `@qubu/migrate/journal`                   | Runtime          | Storage-neutral journal records, transitions, validation, and reference storage                                  |
 | `@qubu/migrate/executor`                  | Runtime          | Portable execution, structured errors, checkpointing, and explicit reconciliation                                |
 | `@qubu/migrate/baseline`                  | Runtime          | Strict live baseline verification and physical managed-schema comparison                                         |
 | `@qubu/migrate/status`                    | Runtime          | Pending chain, managed drift, unmanaged objects, interrupted attempts, and incompatible requirements             |
-| `@qubu/migrate/bootstrap`                 | Runtime          | Fresh SQLite schema planning through the normal diff, plan, and program compiler                                 |
+| `@qubu/migrate/bootstrap`                 | Runtime          | Shared bootstrap preparation, result types, and generic planning with a caller-supplied schema dialect           |
+| `@qubu/migrate/bootstrap/postgres`        | Runtime          | Fresh PostgreSQL schema planning through the normal diff, plan, and program compiler                             |
+| `@qubu/migrate/bootstrap/sqlite`          | Runtime          | Fresh SQLite schema planning through the normal diff, plan, and program compiler                                 |
 | `@qubu/migrate/testing`                   | Runtime          | Deterministic fake adapters, fault boundaries, and adapter conformance checks                                    |
 | `@qubu/cli`                               | Runtime and CLI  | `@alloc/cmd-ts` commands, typed config, filesystem repositories, stable output, and exit codes                   |
 | `@qubu/drizzle`                           | Runtime          | Shared Drizzle conversion errors and dialect types                                                               |
@@ -66,7 +80,7 @@ entrypoint table.
 | 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                                                                                                                                                                                                                                                       |
+| Write queries        | `INSERT` values, defaults, and selects; typed `UPDATE`, PostgreSQL `UPDATE ... FROM`, and `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 FNV change-detection fingerprints                                                                                                                                                                                                                                             |
@@ -74,7 +88,7 @@ entrypoint table.
 | 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`                                                                                                                                                                                                                                                      |
-| Migration operations | Strict artifacts and baselines, authoritative programs, repository and journal validation, adapter capability preflight, execution, status/drift, reconciliation, and SQLite bootstrap                                                                                                                                                                                                   |
+| Migration operations | Strict artifacts and baselines, authoritative programs, repository and journal validation, adapter capability preflight, execution, status/drift, reconciliation, SQLite bootstrap, and complete PostgreSQL bootstrap with standalone enum ordering                                                                                                                                      |
 | 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                                                                                                                                                                                                                               |

package/docs/schema/code-generation.md

@@ -14,9 +14,10 @@ generator:
 ```ts
 import { writeFile } from "node:fs/promises"
 import { generateSchemaSource } from "qubu/codegen"
-import { mapCatalogToSnapshot, readSqliteCatalog } from "qubu/introspection"
+import { mapCatalogToSnapshot } from "qubu/introspection"
+import { readCatalog } from "qubu/introspection/sqlite"
 
-const catalog = await readSqliteCatalog(connection, { namespace: "main" })
+const catalog = await readCatalog(connection, { namespace: "main" })
 const introspection = mapCatalogToSnapshot(catalog, { namespace: "main" })
 const generated = generateSchemaSource(introspection)
 
@@ -49,10 +50,10 @@ baseline for the next catalog read:
 
 ```ts
 import { mapCatalogToSnapshot } from "qubu/introspection"
-import { createSqliteSchemaSnapshot } from "qubu/snapshot"
+import { createSchemaSnapshot } from "qubu/snapshot/sqlite"
 import { mainSchema } from "./schema.generated.ts"
 
-const previousSnapshot = createSqliteSchemaSnapshot(mainSchema)
+const previousSnapshot = createSchemaSnapshot(mainSchema)
 const next = mapCatalogToSnapshot(nextCatalog, {
   namespace: "main",
   previousSnapshot,

package/docs/schema/ddl-emission.md

@@ -9,7 +9,7 @@ plan returns diagnostics and no SQL.
 
 ```ts
 import { emitMigrationPlan } from "@qubu/migrate/ddl"
-import { postgresSchemaDialect } from "qubu/snapshot"
+import { postgresSchemaDialect } from "qubu/snapshot/postgres"
 
 const result = emitMigrationPlan(plan, postgresSchemaDialect)
 if (!result.ok) {

package/docs/schema/introspection.md

@@ -59,9 +59,10 @@ catalog can later support inspection, source generation, or another snapshot
 format:
 
 ```ts
-import { mapCatalogToSnapshot, readSqliteCatalog } from "qubu/introspection"
+import { mapCatalogToSnapshot } from "qubu/introspection"
+import { readCatalog } from "qubu/introspection/sqlite"
 
-const catalog = await readSqliteCatalog(connection, { namespace: "main" })
+const catalog = await readCatalog(connection, { namespace: "main" })
 const result = mapCatalogToSnapshot(catalog, {
   namespace: "main",
   mode: "strict",

package/docs/schema/snapshots.md

@@ -65,6 +65,18 @@ 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:
+
+```ts
+import { createSchemaSnapshot } from "qubu/snapshot"
+import { createSchemaSnapshot as createPostgresSnapshot } from "qubu/snapshot/postgres"
+
+const neutral = createSchemaSnapshot(appSchema)
+const postgres = createPostgresSnapshot(appSchema)
+```
+
 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.

package/docs/sql-semantic-types.md

@@ -89,6 +89,14 @@ operation. This contextual typing does not relabel an expression: comparing a
 `SqlUuid` expression with a `SqlText` expression is still rejected. Cast when
 the database operation intentionally changes domains:
 
+Scalar text functions bind primitive operands automatically, and `coalesce()`
+uses its first expression to type primitive fallbacks:
+
+```ts
+upper("Ada") // UPPER(?)
+coalesce(metrics.label, "Anonymous") // COALESCE("metrics"."label", ?)
+```
+
 ```ts
 import { cast, like, text } from "qubu"
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qubu",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "repository": {
     "type": "git",
     "url": "https://github.com/aleclarson/qubu"
@@ -32,6 +32,18 @@
       "types": "./dist/introspection.d.mts",
       "import": "./dist/introspection.mjs"
     },
+    "./introspection/mysql": {
+      "types": "./dist/introspection/mysql.d.mts",
+      "import": "./dist/introspection/mysql.mjs"
+    },
+    "./introspection/postgres": {
+      "types": "./dist/introspection/postgres.d.mts",
+      "import": "./dist/introspection/postgres.mjs"
+    },
+    "./introspection/sqlite": {
+      "types": "./dist/introspection/sqlite.d.mts",
+      "import": "./dist/introspection/sqlite.mjs"
+    },
     "./mysql": {
       "types": "./dist/mysql.d.mts",
       "import": "./dist/mysql.mjs"
@@ -48,6 +60,18 @@
       "types": "./dist/snapshot.d.mts",
       "import": "./dist/snapshot.mjs"
     },
+    "./snapshot/mysql": {
+      "types": "./dist/snapshot/mysql.d.mts",
+      "import": "./dist/snapshot/mysql.mjs"
+    },
+    "./snapshot/postgres": {
+      "types": "./dist/snapshot/postgres.d.mts",
+      "import": "./dist/snapshot/postgres.mjs"
+    },
+    "./snapshot/sqlite": {
+      "types": "./dist/snapshot/sqlite.d.mts",
+      "import": "./dist/snapshot/sqlite.mjs"
+    },
     "./sqlite": {
       "types": "./dist/sqlite.d.mts",
       "import": "./dist/sqlite.mjs"