qubu 0.4.2 → 0.5.0

package/docs/reference/supported-surface.md

@@ -1,31 +1,41 @@
 # Supported features
 
-> Choose a public package entrypoint, check what Qubu handles, and keep database work on the application side of each adapter.
+> Choose a public package entrypoint and keep application policy separate from portable migration and driver-owned capabilities.
 
 ## 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/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`          | Runtime          | Shared Drizzle conversion errors and dialect types                                                               |
-| `@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/better-auth`      | Runtime          | Better Auth schema derivation and native PostgreSQL, MySQL, and SQLite adapter behavior                          |
-| `qubu/globals`           | TypeScript types | Opt-in ambient declarations for directive-bearing modules                                                        |
+| 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/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/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/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/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/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                                                               |
+| `@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/better-auth`        | Runtime          | Better Auth schema derivation and native PostgreSQL, MySQL, and SQLite adapter behavior                          |
+| `qubu/globals`             | TypeScript types | Opt-in ambient declarations for directive-bearing modules                                                        |
 
 The package validator checks every declared entrypoint in each packed workspace
 package. Concrete dialect constructors live on their database subpaths. The
@@ -45,30 +55,32 @@ 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                                                                                                                                                                                                                               |
+| 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 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                                                                                                                                                                                                                                                                      |
+| 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                                                                                                                                                                                                   |
+| 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.
+interfaces the application provides. `@qubu/migrate` can orchestrate a sealed
+program only through a migration adapter's pinned session and advertised
+capabilities; `@qubu/cli` is the Node.js filesystem/process boundary.
 
 | Boundary                 | Qubu side                                                                                                                                                                                                                                                                      | Application side                                                                                                                                                                                                                                                             |
 | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -76,13 +88,16 @@ that DDL to a database.
 | Query execution          | Binds an adapter with `qubu()` when requested; passes rendered statements and result shapes to execution adapters; applies registered logical field decoders to buffered or streamed object rows; scopes transaction callbacks; returns typed results, plans, rows, or streams | Owns the adapter, driver, connections, pools, cursors, stream cleanup, transactions, savepoints, retries, parameter encoding, proprietary row normalization, decoder policy, plan-row decoding, backpressure, cancellation, 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                                                                                                                               |
+| Schema compilation       | Creates snapshots, compares them, builds deterministic migration plans, previews DDL, and compiles authoritative versioned programs                                                                                                                                            | Defines the target snapshot, operation approvals, custom programs, renderer/server constraints, and artifact provenance                                                                                                                                                      |
+| Migration operations     | Verifies complete artifact and journal chains; orchestrates pinned sessions, leases, locks, transactions, checkpoints, head CAS, status, baselines, bootstrap, and explicit reconciliation through adapter contracts                                                           | Owns credentials, environment selection, adapter construction, rollout timing, deployment-provider coordination, recovery proof, legacy cutover, and 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).
+emission](../schema/ddl-emission.md). Continue with [Migration
+operations](../migrations/index.md) for artifacts, adapters, CLI use, and
+recovery.
 
 ## SQL safety boundaries
 

package/docs/schema/catalog-model.md

@@ -46,7 +46,7 @@ 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
+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

package/docs/schema/columns-and-writes.md

@@ -69,6 +69,20 @@ Contradictory flags fail with a structured `ColumnBehaviorError`. Use
 `externalDefault()` or `externalGeneratedColumn()` when another schema authority
 owns the missing detail.
 
+Use `defaultFn` when Qubu should supply an omitted insert value at runtime:
+
+```ts
+const sessions = table("sessions", {
+  token: text({ defaultFn: () => crypto.randomUUID() }),
+})
+```
+
+Runtime defaults make the insert key optional and run once for each omitted
+row value. They remain live column behavior: snapshots and emitted DDL do not
+record a database default. A column may declare both `default` and `defaultFn`;
+Qubu writes use the runtime value while the database default remains available
+to other clients.
+
 Dialect-owned identity details stay on the identity descriptor. SQLite's
 autoIncrement requires an exact INTEGER rowid alias that is the sole column of
 a primary key. MySQL's AUTO_INCREMENT is a column-level identity extension, and

package/docs/schema/ddl-emission.md

@@ -1,14 +1,14 @@
 # DDL emission
 
-> Turn an approved migration plan into deterministic SQL while keeping database execution outside Qubu.
+> Preview deterministic SQL from a migration plan without confusing preview policy with a sealed executable program.
 
-The `qubu/ddl` entrypoint accepts only a `MigrationPlan` and a `SchemaDialect`.
+The `@qubu/migrate/ddl` entrypoint accepts only a `MigrationPlan` and a `SchemaDialect`.
 It does not read a catalog, open a connection, start a transaction, or write a
 migration journal. Preflight runs before rendering, so a blocked or incompatible
 plan returns diagnostics and no SQL.
 
 ```ts
-import { emitMigrationPlan } from "qubu/ddl"
+import { emitMigrationPlan } from "@qubu/migrate/ddl"
 import { postgresSchemaDialect } from "qubu/snapshot"
 
 const result = emitMigrationPlan(plan, postgresSchemaDialect)
@@ -22,9 +22,8 @@ for (const statement of result.statements) {
 }
 ```
 
-`statements` is the stable handoff for an application-owned executor. Each
-statement carries its operation ID, topological position, SQL text, and an
-ordered parameter list.
+`statements` is a deterministic preview surface. Each statement carries its
+operation ID, topological position, SQL text, and an ordered parameter list.
 Schema literals and expressions are parameter-free by contract. `sql` joins
 the statements with a newline and adds a semicolon for migration-file writers.
 
@@ -32,10 +31,11 @@ the statements with a newline and adds a semicolon for migration-file writers.
 
 The emitter rejects a plan with `ready: false`, `decision-required` operations,
 unknown or lossy facts, unsupported safety, or destructive changes unless the
-caller supplies the matching explicit option. `allowUnsafe` is available for a
-reviewed integration that owns all of those decisions, but it does not make an
-opaque object renderable. Opaque and deferred catalog records always need an
-explicit tagged `custom-sql` operation.
+caller supplies the matching explicit option. `allowUnsafe` is available for
+preview integrations, but it is not accepted as an artifact approval and does
+not make an opaque object renderable. Opaque and deferred catalog records need
+an explicit tagged `custom-sql` operation for preview and an operation-scoped
+custom program for sealed execution.
 
 Lock and transaction requirements describe what a later executor must provide.
 Pass `lock` or `transaction` to preflight those requirements against the
@@ -73,3 +73,8 @@ an inline constraint declaration or an explicit rebuild/custom-SQL operation.
 
 Custom SQL stays opaque and appears at its plan position. The emitter does not
 inspect it for object names or infer SQL from an opaque catalog record.
+
+For execution, lower the plan with `compileMigrationProgram()` from
+`@qubu/migrate/artifact`. The versioned program—not the aggregate `sql`
+string—is authoritative. See [Artifacts and approval
+policy](../migrations/artifacts-and-policy.md).

package/docs/schema/introspection.md

@@ -5,8 +5,8 @@
 Database introspection is an optional capability exported from
 `qubu/introspection`. It discovers database facts; it does not recreate the
 original TypeScript declarations. Planning and DDL emission use the separate
-`qubu/migration` and `qubu/ddl` entrypoints, while migration execution remains
-application-owned. The separate
+`@qubu/migrate/plan` and `@qubu/migrate/ddl` entrypoints, while migration
+execution remains application-owned. The separate
 `qubu/codegen` entrypoint can create a new machine-owned schema module from a
 complete Snapshot v1 result.
 
@@ -207,7 +207,8 @@ The canonical snapshot is the handoff to Qubu's pure schema pipeline:
 None of those layers opens a database connection or changes how introspection
 represents catalog facts. DDL emission produces statements; it does not apply
 them. The [ownership map](../reference/supported-surface.md#ownership-boundary)
-keeps this handoff separate from application-owned migration execution.
+keeps this pure handoff separate from the pinned adapter session used by the
+[portable migration executor](../migrations/recovery.md#execution-and-concurrency-guarantees).
 
 See the [introspection support matrix](../reference/introspection-support.md)
 for version baselines and dialect-specific limits. Snapshot serialization

package/docs/schema/migration-plans.md

@@ -2,13 +2,13 @@
 
 > Describe reviewed snapshot changes as deterministic data before selecting a DDL emitter.
 
-The optional `qubu/migration` entrypoint consumes a resolved `SnapshotDiff` and
+The `@qubu/migrate/plan` entrypoint consumes a resolved `SnapshotDiff` and
 returns an immutable migration-plan IR. It contains operation IDs, paths,
 logical and physical identity evidence, dependency edges, preconditions, safety,
 lock and transaction requirements, and reversibility markers.
 
 ```ts
-import { createMigrationPlan } from "qubu/migration"
+import { createMigrationPlan } from "@qubu/migrate/plan"
 
 const result = createMigrationPlan(diff)
 if (!result.ok) {
@@ -70,7 +70,7 @@ the stable topological ordering. `encodeMigrationPlan()` emits canonical JSON;
 `decodeMigrationPlan()` and `validateMigrationPlan()` reject unknown fields,
 future versions, malformed operations, missing edges, and dependency cycles.
 
-After review and approval, pass the plan to
-[`qubu/ddl`](./ddl-emission.md). DDL emission remains separate from
-application-owned migration execution in the package-wide [ownership
-map](../reference/supported-surface.md#ownership-boundary).
+Use [`@qubu/migrate/ddl`](./ddl-emission.md) for a SQL preview. For durable
+execution, compile and seal the authoritative program under the exact
+[artifact approval policy](../migrations/artifacts-and-policy.md#exact-approval-policy),
+then apply it through a verified adapter.

package/docs/schema/snapshots.md

@@ -45,8 +45,8 @@ dialect metadata, and broken foreign-key or column references as structured
 diagnostics. It does not call `process.exit()` and has no runtime validation
 library dependency.
 
-`schemaSnapshotDigest()` computes a deterministic content digest from canonical
-JSON. The digest is useful for cache keys and fixture assertions only. It is not
+`schemaSnapshotFingerprint()` computes a deterministic content fingerprint from canonical
+JSON. The fingerprint is useful for cache keys and fixture assertions only. It is not
 an entity identity, a rename marker, or migration lineage.
 
 ## Adapter boundary

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qubu",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/aleclarson/qubu"
@@ -24,10 +24,6 @@
       "types": "./dist/core.d.mts",
       "import": "./dist/core.mjs"
     },
-    "./ddl": {
-      "types": "./dist/ddl.d.mts",
-      "import": "./dist/ddl.mjs"
-    },
     "./diff": {
       "types": "./dist/diff.d.mts",
       "import": "./dist/diff.mjs"
@@ -36,10 +32,6 @@
       "types": "./dist/introspection.d.mts",
       "import": "./dist/introspection.mjs"
     },
-    "./migration": {
-      "types": "./dist/migration.d.mts",
-      "import": "./dist/migration.mjs"
-    },
     "./mysql": {
       "types": "./dist/mysql.d.mts",
       "import": "./dist/mysql.mjs"
@@ -76,7 +68,6 @@
     "@alloc/prettier-config": "^1.0.0",
     "@electric-sql/pglite": "^0.5.8",
     "@libsql/client": "^0.17.4",
-    "@pg-nano/pg-tmp": "^2.0.3",
     "@stylistic/eslint-plugin": "^6.0.0-beta.6",
     "@types/bun": "^1.3.0",
     "@types/node": "^24.6.2",
@@ -100,21 +91,21 @@
   "prettier": "@alloc/prettier-config",
   "scripts": {
     "build": "tsdown",
-    "build:workspace-packages": "pnpm --recursive --filter './adapters/*' build",
+    "build:workspace-packages": "pnpm --recursive --filter './adapters/*' --filter './packages/*' build",
     "check:package": "node ./scripts/test-package.mjs --check-built",
     "check:workspace-versions": "node ./scripts/set-release-version.mjs --check",
     "playground": "bun run ./playground/playground.ts",
     "test": "vitest",
     "test:e2e": "vitest --run test/e2e",
     "test:type-performance": "node ./scripts/test-type-performance.mjs",
-    "diff-check": "vitest --run test/diff.test.ts test/migration.test.ts",
+    "diff-check": "vitest --run test/diff.test.ts && pnpm --filter @qubu/migrate test -- plan.test.ts",
     "test:bun": "node ./scripts/test-package.mjs --runtime=bun",
     "test:package": "node ./scripts/test-package.mjs",
-    "test:workspace-children": "pnpm --recursive --filter './adapters/*' build && node ./scripts/test-workspace-packages.mjs",
+    "test:workspace-children": "pnpm run build:workspace-packages && node ./scripts/test-workspace-packages.mjs",
     "test:workspace-packages": "pnpm run test:package && pnpm run test:workspace-children",
     "test:package:node": "node ./scripts/test-package.mjs --runtime=node",
     "typecheck": "vitest --typecheck --run",
-    "typecheck:workspace-packages": "pnpm --recursive --filter './adapters/*' typecheck",
+    "typecheck:workspace-packages": "pnpm --recursive --filter './adapters/*' --filter './packages/*' typecheck",
     "typecheck:playground": "tsc --project ./playground/tsconfig.json",
     "format": "oxlint --fix && oxfmt",
     "release:version": "node ./scripts/set-release-version.mjs",

package/dist/ddl.d.mts

@@ -1,118 +0,0 @@
-import { Tr as SchemaDialect } from "./types-BK1COGZe.mjs";
-import { MigrationLockRequirement, MigrationOperation, MigrationPlan, MigrationTransactionRequirement } from "./migration.mjs";
-//#region src/ddl/types.d.ts
-/** Stable diagnostic categories produced before a migration is rendered. */
-type DdlDiagnosticCode = "invalid-plan" | "blocked-plan" | "decision-required" | "dialect-mismatch" | "unsupported" | "server-version" | "lock-conflict" | "transaction-conflict" | "lossy" | "unknown" | "destructive" | "review-required" | "ambiguous" | "malformed-operation" | "custom-sql" | "capability" | "non-canonical";
-/** A path-addressed finding from DDL preflight or rendering. */
-interface DdlDiagnostic {
-  readonly code: DdlDiagnosticCode;
-  readonly severity: "error" | "warning";
-  readonly message: string;
-  readonly operationId?: string;
-  readonly path: readonly (string | number)[];
-  readonly kind?: MigrationOperation["kind"];
-  readonly dialect?: string;
-  readonly requiredVersion?: string;
-  readonly actualVersion?: string;
-  readonly lock?: MigrationLockRequirement;
-  readonly transaction?: MigrationTransactionRequirement;
-}
-/** One deterministic statement emitted for one plan operation. */
-interface DdlStatement {
-  readonly operationId: string;
-  readonly position: number;
-  readonly kind: MigrationOperation["kind"];
-  /** SQL text with dialect placeholders, if a dialect ever needs them. */
-  readonly sql: string;
-  /** Alias for callers that use the query renderer's terminology. */
-  readonly text: string;
-  /** DDL literals are normally in SQL; this remains explicit and ordered. */
-  readonly parameters: readonly unknown[];
-}
-/** Policy and execution-context facts used by DDL preflight. */
-interface DdlEmissionOptions {
-  /** Permit a plan whose own `ready` flag is false after reviewing diagnostics. */
-  readonly allowBlocked?: boolean;
-  /** Alias for callers that intentionally permit all review gates. */
-  readonly allowUnsafe?: boolean;
-  readonly allowDecisionRequired?: boolean;
-  readonly allowUnknown?: boolean;
-  readonly allowLossy?: boolean;
-  readonly allowUnsupported?: boolean;
-  readonly allowDestructive?: boolean;
-  readonly allowReviewRequired?: boolean;
-  /** Server version used for syntax checks, such as SQLite DROP COLUMN. */
-  readonly serverVersion?: string | number;
-  /** Whether the caller will wrap statements in one transaction. */
-  readonly transaction?: "managed" | "autocommit" | "none";
-  /** Maximum lock the caller can acquire for this migration. */
-  readonly lock?: Exclude<MigrationLockRequirement, "unknown">;
-}
-/** Result of preflight plus deterministic statement rendering. */
-interface DdlEmission {
-  readonly ok: boolean;
-  readonly dialect: string;
-  readonly statements: readonly DdlStatement[];
-  readonly diagnostics: readonly DdlDiagnostic[];
-  /** Statements joined with a newline for simple migration-file writers. */
-  readonly sql: string;
-  /** Flattened parameters in statement order. */
-  readonly parameters: readonly unknown[];
-}
-/** Descriptive alias for callers that name rendered output as a result. */
-type DdlEmissionResult = DdlEmission;
-/** A dialect-specific DDL emitter. */
-interface DdlEmitter {
-  readonly dialect: string;
-  diagnose(plan: MigrationPlan, schemaDialect: SchemaDialect, options?: DdlEmissionOptions): readonly DdlDiagnostic[];
-  emit(plan: MigrationPlan, schemaDialect: SchemaDialect, options?: DdlEmissionOptions): DdlEmission;
-}
-//#endregion
-//#region src/ddl/emitter.d.ts
-interface DdlFeatures {
-  readonly dialect: "postgresql" | "sqlite" | "mysql";
-  readonly supports: ReadonlySet<string>;
-}
-/**
- * Build the shared strict preflight and rendering boundary for one engine. The renderer only
- * receives a validated MigrationPlan and a SchemaDialect.
- */
-declare function createDdlEmitter(features: DdlFeatures): DdlEmitter;
-//#endregion
-//#region src/ddl/postgres.d.ts
-/** PostgreSQL operation support used by the strict DDL preflight. */
-declare const postgresDdlEmitter: DdlEmitter;
-/** Emit a reviewed plan with PostgreSQL's schema dialect. */
-declare function emitPostgresMigrationPlan(plan: MigrationPlan, options?: DdlEmissionOptions): DdlEmission;
-/** Alias using the full PostgreSQL spelling. */
-declare const emitPostgresqlMigrationPlan: typeof emitPostgresMigrationPlan;
-declare const emitPostgresDdl: typeof emitPostgresMigrationPlan;
-declare const emitPostgresqlDdl: typeof emitPostgresMigrationPlan;
-//#endregion
-//#region src/ddl/sqlite.d.ts
-/** SQLite operation support used by the strict DDL preflight. */
-declare const sqliteDdlEmitter: DdlEmitter;
-/** Emit a reviewed plan with SQLite's schema dialect. */
-declare function emitSqliteMigrationPlan(plan: MigrationPlan, options?: DdlEmissionOptions): DdlEmission;
-declare const emitSqliteDdl: typeof emitSqliteMigrationPlan;
-//#endregion
-//#region src/ddl/mysql.d.ts
-/** MySQL operation support used by the strict DDL preflight. */
-declare const mysqlDdlEmitter: DdlEmitter;
-/** Emit a reviewed plan with MySQL's schema dialect. */
-declare function emitMysqlMigrationPlan(plan: MigrationPlan, options?: DdlEmissionOptions): DdlEmission;
-declare const emitMysqlDdl: typeof emitMysqlMigrationPlan;
-//#endregion
-//#region src/ddl/index.d.ts
-/** Select a first-party emitter by the selected schema dialect name. */
-declare function ddlEmitterForDialect(dialect: SchemaDialect): DdlEmitter;
-/** Emit a plan through the matching first-party schema dialect. */
-declare function emitMigrationPlan(plan: MigrationPlan, dialect: SchemaDialect, options?: DdlEmissionOptions): DdlEmission;
-/** Convenient defaults for callers that already selected a plan dialect. */
-declare const ddlDialects: Readonly<{
-  postgresql: SchemaDialect<"row-locking" | "json" | "ilike" | "on-conflict">;
-  sqlite: SchemaDialect<"json" | "on-conflict">;
-  mysql: SchemaDialect<"row-locking" | "json">;
-}>;
-//#endregion
-export { DdlDiagnostic, DdlDiagnosticCode, DdlEmission, DdlEmissionOptions, DdlEmissionResult, DdlEmitter, DdlFeatures, DdlStatement, createDdlEmitter, ddlDialects, ddlEmitterForDialect, emitMigrationPlan, emitMysqlDdl, emitMysqlMigrationPlan, emitPostgresDdl, emitPostgresMigrationPlan, emitPostgresqlDdl, emitPostgresqlMigrationPlan, emitSqliteDdl, emitSqliteMigrationPlan, mysqlDdlEmitter, postgresDdlEmitter, sqliteDdlEmitter };