qubu 0.6.0 → 0.6.2

package/docs/index.md

@@ -33,7 +33,7 @@ define a table, build a `SELECT`, and inspect its SQL and parameters.
   derivation and a native transactional database adapter.
 - [Extend Qubu](guides/extensions/overview.md) with a custom source, clause,
   dialect policy, or typed expression.
-- [Read JSON scalars](guides/json.md) from structured JSON paths.
+- [Query nested JSON](guides/json.md) or read scalars from structured paths.
 - [Enable the Vite compiler hint](guides/vite-plugin.md) when query modules
   should opt into named imports through a directive.
 - [Inspect an existing database](schema/introspection.md) through the optional

package/docs/migrations/adapters.md

@@ -2,38 +2,47 @@
 
 > Select a migration adapter from capabilities proven by its driver and environment, not from dialect name alone.
 
-Every executable migration adapter opens one pinned migration session and
+Every executable migration adapter opens a migration session and
 advertises the exact behavior the executor may use:
 
-| Field                                  | Contract                                                                            |
-| -------------------------------------- | ----------------------------------------------------------------------------------- |
-| `dialect`, `serverVersion`             | Physical target and optional version used for compatibility checks                  |
-| `session`                              | Must be `pinned` until `close()` resolves                                           |
-| `transactionalDdl`                     | Whether DDL effects can roll back                                                   |
-| `optionalTransactions`, `transactions` | Whether optional phases join a transaction and which requirements are proven        |
-| `lease`, `leaseKind`                   | Database-backed exclusion of another migration runner                               |
-| `locks`                                | Independently supported program DDL lock requirements                               |
-| `journal`                              | Database storage, head compare-and-swap, and atomic applied-record/head advancement |
-| `parameters`                           | Supported tagged parameter kinds                                                    |
-| `commitAmbiguity`                      | Ambiguous commit becomes `recovery-required`                                        |
-| `forbiddenPhases`                      | Checkpointed support or explicit rejection                                          |
-| `features`                             | Named constraints an artifact may require                                           |
+| Field                                  | Contract                                                                               |
+| -------------------------------------- | -------------------------------------------------------------------------------------- |
+| `dialect`, `serverVersion`             | Physical target and optional version used for compatibility checks                     |
+| `session`                              | `pinned` for the full lifecycle, or `atomic-batch` for one complete artifact per batch |
+| `transactionalDdl`                     | Whether DDL effects can roll back                                                      |
+| `optionalTransactions`, `transactions` | Whether optional phases join a transaction and which requirements are proven           |
+| `lease`, `leaseKind`                   | Database-backed exclusion of another migration runner                                  |
+| `locks`                                | Independently supported program DDL lock requirements                                  |
+| `journal`                              | Database storage, head compare-and-swap, and atomic applied-record/head advancement    |
+| `parameters`                           | Supported tagged parameter kinds                                                       |
+| `commitAmbiguity`                      | Ambiguous commit becomes `recovery-required`                                           |
+| `forbiddenPhases`                      | Checkpointed support or explicit rejection                                             |
+| `features`                             | Named constraints an artifact may require                                              |
 
 The migrator lease and a program's DDL lock are different controls. The lease
 excludes another Qubu runner; a DDL lock protects the database operation. The
 executor never treats one as proof of the other.
 
+## Trusted migration SQL
+
+Migration SQL, including SQL conditions, is trusted across all adapters. Qubu
+validates program structure and adapter capabilities, but does not parse SQL
+to enforce safety. Callers must preserve executor-owned transactions, connection
+settings, and migration journal state. For example, an explicit `COMMIT` can
+leave schema changes applied without their journal record; atomicity and recovery
+guarantees depend on respecting this contract.
+
 ## Current profiles
 
 The following stable profiles have live conformance coverage in this checkout:
 
-| Migration entrypoint                  | Dialect    | Transactions                  | Locks           | Forbidden phases | Notes                                               |
-| ------------------------------------- | ---------- | ----------------------------- | --------------- | ---------------- | --------------------------------------------------- |
-| `@qubu/adapter-libsql/migration`      | SQLite     | required, optional            | none, exclusive | unsupported      | Pinned application-owned client                     |
-| `@qubu/adapter-node-sqlite/migration` | SQLite     | required, optional            | none, exclusive | unsupported      | Pinned application-owned `DatabaseSync`             |
-| `@qubu/adapter-pg/migration`          | PostgreSQL | required, optional, forbidden | none, exclusive | checkpointed     | Caller supplies an already-pinned client            |
-| `@qubu/adapter-postgresjs/migration`  | PostgreSQL | required, optional, forbidden | none, exclusive | checkpointed     | Reserves and releases one connection                |
-| `@qubu/adapter-pglite/migration`      | PostgreSQL | required, optional, forbidden | none, exclusive | checkpointed     | Uses the database query queue as the pinned session |
+| Migration entrypoint                  | Dialect    | Transactions                  | Locks           | Forbidden phases | Notes                                                  |
+| ------------------------------------- | ---------- | ----------------------------- | --------------- | ---------------- | ------------------------------------------------------ |
+| `@qubu/adapter-libsql/migration`      | SQLite     | required, optional            | none, exclusive | unsupported      | Single-phase atomic batches through `client.migrate()` |
+| `@qubu/adapter-node-sqlite/migration` | SQLite     | required, optional            | none, exclusive | unsupported      | Pinned application-owned `DatabaseSync`                |
+| `@qubu/adapter-pg/migration`          | PostgreSQL | required, optional, forbidden | none, exclusive | checkpointed     | Caller supplies an already-pinned client               |
+| `@qubu/adapter-postgresjs/migration`  | PostgreSQL | required, optional, forbidden | none, exclusive | checkpointed     | Reserves and releases one connection                   |
+| `@qubu/adapter-pglite/migration`      | PostgreSQL | required, optional, forbidden | none, exclusive | checkpointed     | Uses the database query queue as the pinned session    |
 
 All five support every current tagged parameter kind (`null`, `boolean`,
 `string`, `number`, `bigint`, `bytes`, and `json`), a database journal and
@@ -68,3 +77,31 @@ const adapter = libsqlMigrationAdapter(client, {
 
 `DATABASE_URL` remains application configuration; neither the adapter nor CLI
 assigns deployment-provider meaning to it.
+
+## libSQL batch execution
+
+Each executable artifact must contain exactly one phase and an embedded before
+snapshot. The adapter submits its statements, SQL assertions, applied-history
+record, head update, and terminal attempt state in one `client.migrate()` call.
+For example, creating a table and recording that migration either both commit
+or both roll back. Multiple artifacts are separate batches; earlier successful
+artifacts remain applied if a later one fails.
+
+Preparation reads the schema in a read transaction. The submitted batch checks
+that the catalog still matches that inspection, the lease is still owned, and
+the head still equals the expected parent. Foreign-key validation runs before
+commit because libSQL temporarily disables enforcement during `migrate()`.
+
+Schema fingerprint and property preconditions are checked against the embedded
+before snapshot, whose physical facts are verified during preparation and
+guarded by the in-batch catalog assertion. Object-presence and scalar SQL checks
+run inside the batch. Postconditions must be object-presence/absence checks
+without fingerprints, or scalar SQL checks returning `1`. Unsupported conditions
+and multiple phases are rejected. SQL content is passed to the driver without
+safety validation; each program entry must follow the driver's statement contract.
+
+The database-row lease has no expiry or heartbeat. A process crash can leave
+it held; ownership must be resolved before another runner can proceed. A lost
+batch response is an uncertain outcome requiring journal inspection and, when
+the attempt remains unresolved, explicit recovery. It is never assumed to be
+a successful rollback.

package/docs/migrations/index.md

@@ -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/migrations/recovery.md

@@ -46,13 +46,19 @@ head, or a non-prefix repository fail before any statement executes.
 ## Execution and concurrency guarantees
 
 For each invocation, the executor verifies the entire repository, opens one
-pinned session, checks capabilities, acquires the migrator lease, validates the
+migration session, checks capabilities, acquires the migrator lease, validates the
 journal and repository prefix, checks the live before-snapshot digest, then
 applies each pending artifact. Within an artifact it creates an attempt,
 executes ordered phases with preconditions and postconditions, writes durable
 checkpoints, appends immutable history, and compare-and-swaps the head.
 Resources are released in reverse order: DDL lock, migrator lease, then session.
 
+An `atomic-batch` profile instead applies one single-phase artifact in one
+database transaction, including its checks and terminal journal writes. It
+records a completed phase checkpoint rather than intermediate statement
+checkpoints. See [libSQL batch execution](./adapters.md#libsql-batch-execution)
+for its supported conditions and concurrency guards.
+
 A second runner cannot rely on the lease alone. Atomic applied-record/head
 advancement uses the expected parent as a compare-and-swap guard. A runner that
 observes the already-matching head exits idempotently; a conflicting head is a

package/docs/query-model/fragments.md

@@ -51,7 +51,8 @@ producer, consumer, and regression test all exist.
 ## Parameters are runtime data
 
 Parameter values are not fragment metadata. A renderer calls
-`context.parameter(value)`, and `render()` collects values in placeholder order:
+`context.parameter(value)`, and `render()` collects values in placeholder order.
+Pass a second argument when the adapter needs the runtime SQL domain too:
 
 ```ts
 import { and, eq, from, integer, like, render, select, table, text, where } from "qubu"
@@ -72,6 +73,25 @@ render(query)
 // parameters: [7, '%Ada%']
 ```
 
+The optional domain metadata stays in a sidecar aligned with `parameters`:
+
+```ts
+import { typedValue } from "qubu/core"
+import type { SqlUuid } from "qubu"
+
+const id = typedValue<SqlUuid, string>("108cb836-20d2-41b2-8c23-f0c94700aa7e", "uuid")
+render(id)
+// parameterSqlTypes: ["uuid"]
+```
+
+The domain is a binding hint, not an instruction to convert the returned
+JavaScript value. Result decoding comes from a field's `type` or an explicit
+decoder.
+
+Plain JavaScript values remain untyped at runtime. Use an explicit domain when
+`Date` could mean either `DATE` or `TIMESTAMP`, or when a string is a UUID
+rather than text.
+
 The parameter array follows the placeholders in the rendered text. `select()`
 normalizes independent clause values, but keep the final call in SQL order in
 new code so source scope and repair hints are visible at a glance.

package/docs/reference/introspection-support.md

@@ -4,7 +4,7 @@
 
 The optional `qubu/introspection` entrypoint reads one selected database
 namespace through a user-owned `CatalogConnection`. It returns normalized
-catalog data and can map that data to canonical Snapshot v1 or v2. The
+catalog data and can map that data to canonical Snapshot v1. The
 application owns the driver and connection lifecycle. Snapshot diffing,
 migration planning, and DDL emission are separate Qubu capabilities; see the
 [ownership map](supported-surface.md#ownership-boundary).
@@ -46,7 +46,7 @@ SQL.
 ## PostgreSQL complete catalog surface
 
 The PostgreSQL reader also fills the complete normalized catalog used by
-Snapshot v2. It keeps PostgreSQL OIDs in current-run physical references and
+Snapshot v1. It keeps PostgreSQL OIDs in current-run physical references and
 keeps decompiler output such as `pg_get_viewdef`, `pg_get_triggerdef`, and
 `pg_get_functiondef` as tagged SQL data. It does not evaluate that text.
 
@@ -55,9 +55,9 @@ The query and normalization layout follows the catalog-oriented parts of the
 while Qubu keeps the result as typed data instead of generating TypeScript
 declarations.
 
-Use `mapCatalogToCompleteSnapshot()` for this object set. Use
-`mapCatalogToSnapshot()` when a caller explicitly needs the existing table-only
-Snapshot v1.
+Use `mapCatalogToSnapshot()` or its explicit
+`mapCatalogToCompleteSnapshot()` alias for this object set. Both produce the
+canonical Snapshot v1 shape.
 
 ## SQLite complete catalog surface
 
@@ -86,10 +86,9 @@ the selected namespace. SQLite does not provide the PostgreSQL object families
 such as routines, materialized views, policies, or ownership, so the reader
 does not fabricate them.
 
-`mapCatalogToCompleteSnapshot()` retains the typed views, triggers, deferred
-objects, opaque boundaries, and dialect extensions in Snapshot v2. The existing
-`mapCatalogToSnapshot()` still maps only tables and preserves Snapshot v1
-behavior.
+`mapCatalogToSnapshot()` delegates to `mapCatalogToCompleteSnapshot()` and
+retains typed views, triggers, deferred objects, opaque boundaries, and dialect
+extensions in Snapshot v1.
 
 The query and normalization seams follow the catalog-reading portions of the
 [Drizzle SQLite introspector](https://github.com/drizzle-team/drizzle-orm/blob/main/drizzle-kit/src/introspect-sqlite.ts).
@@ -110,13 +109,13 @@ MySQL has typed complete records for views, routines and their parameters,
 triggers, partitions, collations used by selected tables or columns, and
 comments. View definitions come from `INFORMATION_SCHEMA.VIEWS`; each view's
 columns are joined back to the matching `COLUMNS` rows by physical table name,
-so the complete Snapshot v2 cross-reference points at the view's own column
+so the complete Snapshot v1 cross-reference points at the view's own column
 IDs. Missing view definitions or unresolved trigger, partition, or other
 object references become deferred records with diagnostics.
 
 Scheduled events are retained as `CatalogOpaqueObject` records. Their event
 metadata and definition remain opaque, and the reader emits an
-`unmodeled-object` warning. Snapshot v2 keeps these records in
+`unmodeled-object` warning. Snapshot v1 keeps these records in
 `opaqueObjects`; they are not treated as typed routines, triggers, or
 migration operations.
 
@@ -132,13 +131,12 @@ The query and normalization layout follows the catalog-reading portions of the
 while Qubu keeps the result as typed data instead of generating TypeScript
 declarations.
 
-Use `mapCatalogToCompleteSnapshot()` to retain these typed MySQL families and
-the opaque or deferred boundaries in Snapshot v2. Use `mapCatalogToSnapshot()`
-when a caller explicitly needs the existing table-only Snapshot v1.
+Use `mapCatalogToSnapshot()` or `mapCatalogToCompleteSnapshot()` to retain these
+typed MySQL families and the opaque or deferred boundaries in Snapshot v1.
 
 ## Snapshot v1 surface
 
-The mapper can emit these facts in canonical Snapshot v1:
+The mapper emits these facts in canonical Snapshot v1:
 
 - one namespace and ordinary tables;
 - exact dialect-native column storage;
@@ -162,14 +160,14 @@ Snapshot v1 objects:
 - views and materialized views;
 - sequences, enums, domains, routines, triggers, policies, extensions,
   collations, comments, and partition metadata;
-- PostgreSQL identity sequence options that have no typed Snapshot v1 field;
+- PostgreSQL identity sequence options that have no typed field;
 - SQLite virtual/shadow tables, attached namespaces, and unrecoverable
   generated or expression definitions;
 - MySQL/MariaDB differences, prefix indexes, invisible indexes, and advanced
   functional, full-text, or spatial index semantics.
 
-Use the complete catalog and Snapshot v2 mapper to retain supported PostgreSQL
-and MySQL families. MySQL scheduled events stay opaque, and MySQL sequences,
+Use the Snapshot v1 mapper to retain supported PostgreSQL and MySQL families.
+MySQL scheduled events stay opaque, and MySQL sequences,
 materialized views, row-level security (RLS) policies, extension objects, and
 ownership stay unsupported or deferred. When a row cannot be normalized safely, the reader
 keeps a typed deferred or opaque record and emits a diagnostic instead of

package/docs/reference/supported-surface.md

@@ -9,12 +9,15 @@
 | `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/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/diff`                               | Runtime          | Canonical Snapshot v1 comparison, rename hints, suggestions, and safety diagnostics                              |
+| `qubu/introspection`                      | Runtime          | Shared catalog contracts, normalized catalog models, diagnostics, and mapping to Snapshot v1                     |
+| `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`                           | Runtime          | Canonical Snapshot v1 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                               |
@@ -22,15 +25,24 @@
 | `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/pgvector`                          | Runtime          | PostgreSQL pgvector columns, dense-vector codecs, distance expressions, and HNSW/IVFFlat index metadata          |
 | `@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                                                               |
@@ -67,17 +79,17 @@ entrypoint table.
 | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | 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                                                                                                                                            |
+| Expressions          | Comparison, boolean, arithmetic, null, range, membership, aggregate, window, string, JSON scalar reads and typed nested JSON query results, 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; PostgreSQL/SQLite conflict clauses; MySQL duplicate-key updates and incoming rows; `RETURNING` on supporting dialects; 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                                                                                                                                                                                                                                             |
+| Snapshots            | Pure Snapshot v1 creation, canonical encoding and strict decoding, immutable data, diagnostics, and FNV change-detection fingerprints                                                                                                                                                                                                                                                    |
 | 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                                                                                                                                                                                                                                                                      |
+| Snapshot diffing     | Pure Snapshot v1 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/catalog-model.md

@@ -31,25 +31,38 @@ 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
+## Snapshot v1
 
 `qubu/snapshot` provides the strict complete format as a separate API:
 
 ```ts
 import { decodeCompleteSchemaSnapshot, encodeCompleteSchemaSnapshot } from "qubu/snapshot"
 
-const encoded = encodeCompleteSchemaSnapshot(snapshotV2)
+const encoded = encodeCompleteSchemaSnapshot(snapshotV1)
 const decoded = decodeCompleteSchemaSnapshot(encoded)
 ```
 
-Snapshot v2 uses the same `qubu-schema` envelope with `version: 2`. Its
+Snapshot v1 uses the same `qubu-schema` envelope with `version: 1`. 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 fingerprint 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.
+Normalized references to nested catalog objects retain their owner scope. A
+table-local index or constraint reference is mapped with
+`owner: { kind: "table", id }`; view columns use the view kind and ID; domain
+constraints use the domain kind and ID. The legacy `tableId` shorthand on
+catalog entity references is converted to that owner form at the Snapshot v1
+boundary. Top-level references have no owner. This scope prevents equal child
+IDs from different tables or object families from overwriting one another.
+
+Catalog extension payloads and configuration records are opaque JSON. Their
+keys and values are preserved through normalization and canonical encoding;
+objects inside those payloads are not treated as Snapshot expressions or
+native storage declarations.
+
+Snapshot v1 is the only strict schema snapshot format. `decodeSchemaSnapshot`
+and `decodeCompleteSchemaSnapshot` both validate the same version-1 envelope,
+reject unknown fields and future versions, and never evaluate database-provided
+SQL.

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)
 
@@ -134,6 +135,6 @@ 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
+DDL, non-table 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/diff.md

@@ -1,6 +1,6 @@
 # Snapshot diffing
 
-> Compare canonical Snapshot v1 or v2 values and review identity changes before a later planning step.
+> Compare canonical Snapshot v1 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.
@@ -57,7 +57,7 @@ an `ambiguous` diagnostic and leaves both operations visible for review.
 
 Removing an object is marked `destructive`. Narrowing nullability, changing
 storage, removing a value, or changing a constraint can also receive that
-classification. Opaque and deferred Snapshot v2 records remain visible as
+classification. Opaque and deferred Snapshot v1 records remain visible as
 `add` or `remove` data and produce `lossy` or `unsupported` diagnostics. They
 cannot be silently promoted to a rename.