qubu 0.6.2 → 0.7.0

package/docs/guides/sql-templates.md

@@ -1,6 +1,6 @@
 # Compose SQL templates
 
-> Use trusted SQL syntax with bound runtime values while retaining the Qubu metadata carried by interpolated expressions, fragments, and queries.
+> Write SQL templates that bind values safely and preserve type information from Qubu expressions.
 
 ## Bind every runtime value
 
@@ -108,10 +108,16 @@ reaches `unsafeExpression()`.
 
 ## Preserve metadata through interpolated fragments
 
-The tag inherits source dependencies, conservative outer-join nullability,
-grouping facts, aggregate and window state, subquery state, and dialect
-capability requirements from Qubu fragment substitutions. It does not infer
-those facts from unchecked template text.
+Qubu fragment substitutions pass these facts to the template:
+
+- Required sources.
+- Possible nulls from outer joins.
+- Grouping dependencies.
+- Aggregate and window state.
+- Subquery state.
+- Required dialect capabilities.
+
+Qubu does not infer these facts from template text.
 
 Use a built-in expression as the substitution when its semantics matter:
 

package/docs/guides/valtio-sync.md

@@ -102,11 +102,17 @@ const handlers = applyOpsWithQubu<SyncContext>({
 export const sync = valtioSync({ schema: { todos }, handlers })
 ```
 
-Authorization, conflict checks, the application mutation, and
-`syncEvents.write()` run in that order inside one Qubu transaction. If any step
-fails, the adapter rolls the transaction back. The event sequence becomes
-`serverVersion` unless the mutation handler returns an explicit version. Read
-handlers pass through unchanged.
+Each mutation runs these steps in one Qubu transaction:
+
+1. Check authorization.
+2. Check conflicts.
+3. Apply the application mutation.
+4. Write the sync event with `syncEvents.write()`.
+
+If any step fails, the adapter rolls the transaction back.
+
+The event sequence becomes `serverVersion` unless the mutation handler returns
+an explicit version. Read handlers pass through unchanged.
 
 The integration does not define persistence tables, import Drizzle, or execute
 driver APIs. The application owns table design, authorization, conflict policy,

package/docs/guides/vite-plugin.md

@@ -1,6 +1,6 @@
 # Vite compiler hint
 
-> Opt a JavaScript or TypeScript module into Qubu's ambient query API while keeping the transform limited to explicit directive-bearing files.
+> Use a "use qubu" directive to add the Qubu imports a module needs.
 
 The optional Vite plugin recognizes the `"use qubu"` directive and injects only
 the referenced named imports from the configured module.
@@ -33,7 +33,7 @@ ambient value and type declarations for the TypeScript compiler.
 
 ## Mark a module explicitly
 
-Put the directive in the module's initial directive prologue:
+Put the directive at the start of the module, alongside any other directives:
 
 ```ts
 "use qubu"

package/docs/index.md

@@ -1,11 +1,17 @@
 # Qubu
 
-> Build parameterized SQL from typed tables, expressions, and clauses.
+> Build SQL queries from typed tables and reusable values.
 
-Qubu builds SQL from values. Tables, expressions, clauses, and complete queries
-compose without a mutable query builder. TypeScript tracks selected row shapes,
-source scope, and nullability, while rendering returns SQL text and ordered
-parameters.
+Qubu builds SQL from reusable values. You can combine query parts without
+changing a shared query-builder object.
+
+TypeScript checks:
+
+- Which fields the query returns and their types.
+- Whether each column belongs to a source in the query.
+- Whether a result can be `null`.
+
+Render a query to inspect its SQL text and ordered parameters.
 
 The preferred source style names each projected field and writes the final
 `select()` clauses in SQL order. Clause values remain order-independent at
@@ -17,7 +23,7 @@ and placed in that final call where it reads best.
 If this is your first query, follow [Getting started](getting-started.md) to
 define a table, build a `SELECT`, and inspect its SQL and parameters.
 
-## Choose a task
+## Build and run queries
 
 - [Build a `SELECT`](guides/select/overview.md) with projections, joins,
   predicates, ordering, and grouping.
@@ -36,18 +42,18 @@ define a table, build a `SELECT`, and inspect its SQL and parameters.
 - [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
-  user-owned catalog boundary.
-- [Generate a schema module](schema/code-generation.md) from one complete,
-  non-lossy Snapshot v1 introspection result.
+
+## Work with schemas and migrations
+
+- [Inspect an existing database](schema/introspection.md) using a connection you provide.
+- [Generate a schema module](schema/code-generation.md) from an introspection result without losing schema facts.
 - [Compare snapshots](schema/diff.md) with explicit rename hints and reviewable
   safety diagnostics.
 - [Build migration plans](schema/migration-plans.md) as reviewed, deterministic
   data before DDL emission.
 - [Emit DDL](schema/ddl-emission.md) from an approved migration plan without
   handing Qubu a database connection.
-- [Operate migrations](migrations/index.md) with versioned artifacts, verified
-  adapter profiles, baselines, a portable executor, and explicit recovery.
+- [Operate migrations](migrations/index.md) with reviewed migration files and a verified adapter.
 
 ## The query pipeline
 
@@ -106,8 +112,9 @@ render(query)
 The inferred row is `{ id: number; name: string }`. The value `7` stays out
 of the SQL text and appears in the `parameters` array in placeholder order.
 
-The [supported features](reference/supported-surface.md) page is the canonical
-package-entrypoint and ownership map. Applications may use Qubu's portable
-migration executor while retaining credentials, approval policy, custom SQL,
-and deployment lifecycle ownership. [Troubleshooting](troubleshooting.md)
-starts from common errors and points to the concept page behind each one.
+## Find support details
+
+- [Supported features](reference/supported-surface.md) lists package imports and
+  explains which responsibilities stay with your application.
+- [Troubleshooting](troubleshooting.md) starts from common errors and explains
+  how to fix them.

package/docs/migrations/adapters.md

@@ -1,6 +1,6 @@
 # Adapter capability profiles
 
-> Select a migration adapter from capabilities proven by its driver and environment, not from dialect name alone.
+> Choose a migration adapter based on what its driver and environment have been tested to support.
 
 Every executable migration adapter opens a migration session and
 advertises the exact behavior the executor may use:
@@ -25,12 +25,12 @@ 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.
+Qubu validates program structure and adapter capabilities. It trusts the SQL
+you supply, including SQL conditions, and does not parse it for safety.
+
+Migration SQL must preserve the executor’s transactions, connection settings,
+and journal state. For example, an explicit `COMMIT` can apply schema changes
+without their journal record, breaking the executor’s recovery guarantees.
 
 ## Current profiles
 
@@ -44,11 +44,32 @@ The following stable profiles have live conformance coverage in this checkout:
 | `@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
-lease, atomic applied-record/head advancement, and recovery-required commit
-ambiguity classification. Support still depends on the artifact's server,
-feature, transaction, and lock constraints.
+All five support:
+
+- Every current tagged parameter kind.
+- A journal and migrator lease stored in the database.
+- An atomic update of the applied record and journal head.
+- A recovery-required result when a commit’s outcome is uncertain.
+
+Parameter kinds are:
+
+- `null` and `boolean`.
+- `string` and `number`.
+- `bigint` and `bytes`.
+- `json`.
+
+The artifact’s server, feature, transaction, and lock requirements must still
+match the adapter.
+
+### Unavailable profiles
+
+MySQL has a [basic SQL migration runner](../../adapters/mysql2/README.md#run-sql-migrations),
+`migrate`, which executes pending statements and records completed
+migrations. It runs independently of the shared executor and its stronger
+capability contract. The MySQL profile below remains unavailable; possible
+improvements are tracked in [issue #1](https://github.com/aleclarson/qubu/issues/1).
+The same entry point exports `baselineAdapter` for [reviewed MySQL adoption](adopt.md#mysql)
+through the shared CLI and `@qubu/migrate/baseline` API.
 
 These exported profiles are unavailable and must not be passed to the
 executor:
@@ -62,16 +83,18 @@ executor:
 Unavailable profiles expose `reason` and `missingCapabilities`; they do not
 fall back to a generic executor.
 
+### Configure libSQL inspection
+
 For libSQL, let the migration entrypoint exclude all reserved journal objects
 during strict inspection:
 
 ```ts
 import { createClient } from "@libsql/client"
-import { libsqlMigrationAdapter, readLibsqlMigrationSnapshot } from "@qubu/adapter-libsql/migration"
+import { migrationAdapter, readMigrationSnapshot } from "@qubu/adapter-libsql/migration"
 
 const client = createClient({ url: process.env.DATABASE_URL! })
-const adapter = libsqlMigrationAdapter(client, {
-  readSnapshot: readLibsqlMigrationSnapshot,
+const adapter = migrationAdapter(client, {
+  readSnapshot: readMigrationSnapshot,
 })
 ```
 
@@ -84,7 +107,9 @@ 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
+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
@@ -92,13 +117,24 @@ 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()`.
 
+### Supported conditions
+
 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.
+before snapshot. Preparation verifies its physical facts, and the batch
+asserts that the catalog still matches.
+
+Object-presence and scalar SQL checks run inside the batch. Postconditions
+must use either:
+
+- Object-presence or absence checks without fingerprints.
+- Scalar SQL checks returning `1`.
+
+Unsupported conditions and multiple phases are rejected.
+
+SQL is passed to the driver without safety validation. Each program entry
+must follow the driver’s statement contract.
+
+### Crashes and uncertain outcomes
 
 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

package/docs/migrations/adopt.md

@@ -0,0 +1,331 @@
+# Adopt an existing database
+
+> Capture and accept the live schema as migration history's starting point, then
+> reconcile it with the application's desired schema separately.
+
+If the live `game` table lacks `manifest`, the captured baseline must also lack
+it. Adoption changes no application schema/data and does not certify that the
+desired application version can run. Keep incompatible code stopped until a
+separate reviewed migration reconciles the schema.
+
+## Choose an adapter
+
+All supported adoption adapters use the same [CLI](#shared-cli) and
+[API](#shared-api). Each checks an empty artifact repository and its own history.
+
+| Database and adapter    | History storage            | Coordination                                         |
+| ----------------------- | -------------------------- | ---------------------------------------------------- |
+| SQLite through `libsql` | Migration journal          | Adapter lease coordinates participating Qubu runners |
+| PostgreSQL through `pg` | Migration journal          | Pinned client and advisory lease                     |
+| MySQL through `mysql2`  | `__qubu_mysql2_migrations` | Caller serializes runners; no database lease         |
+
+Adoption does not require migration execution capabilities. MySQL supports the
+shared adoption commands while retaining its basic SQL runner for subsequent
+migrations. See [adapter profiles](adapters.md) for execution contracts.
+
+Configure the desired application Snapshot v1 as the managed `scope`
+(`config.snapshot` for the CLI). Preserve the same database, namespace, adapter,
+and original scope through acceptance, including tables that are currently
+absent. A candidate does not persist that original selection or bind itself to
+a particular database. Verify the connection independently; reported selectors
+do not prove database identity. Keep credentials out of snapshots and metadata.
+
+### Inspection scope
+
+Standard readers select managed tables by their expected physical names and
+preserve logical identities. Expected facts never fill missing tables or columns.
+Other live tables are reported as unmanaged.
+
+| Adapter  | Connection and namespace                                                                                                                                           | Other inspected objects                                                                                                                                                                                       |
+| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `libsql` | Configure the existing database as in [CLI configuration](operations.md#configuration)                                                                             | Non-table objects retain the adapter's inspection policy; strict inspection can reject unsupported facts outside selected tables                                                                              |
+| `pg`     | Connected `Client` or acquired `PoolClient`; keep `search_path` equal to the scope's existing namespace; see [PostgreSQL configuration](#postgresql-configuration) | Excluded tables take their sequences, triggers, policies, comments, and ownership with them. Namespace-level views, free sequences, enums, domains, routines, extensions, and opaque evidence remain included |
+| `mysql2` | Dedicated connection, autocommit enabled, no active transaction; the selected database must equal the scope's database                                             | Excluded tables take attached triggers, partitions, and comments with them. Namespace-level views, routines, used collations, and opaque evidence remain included                                             |
+
+Readers exclude reserved `__qubu_migration_` objects and their attached metadata;
+MySQL also excludes `__qubu_mysql2_migrations`. Strict catalog failures remain
+errors. A managed reference to an excluded object can require a broader scope.
+
+The adapters expose `readMigrationSnapshot` directly. Without an expected scope,
+the `pg` reader inspects non-journal objects in `public`; the `mysql2` reader uses
+the selected database. Use `captureBaseline` for adoption so journal setup
+precedes inspection, including any catalog facts introduced by that setup.
+
+## Capture, review, and verify
+
+1. **Capture** the actual managed schema to a new candidate file. The candidate
+   is an ordinary Snapshot v1, not a migration artifact. Keep it outside the
+   shared artifact directory and refuse to overwrite an existing candidate.
+2. **Review** its tables, columns, defaults, constraints, indexes, comments,
+   dialect facts, included namespace objects, and reported unmanaged tables.
+3. **Preflight** the explicitly reviewed file against a fresh inspection of the
+   original scope. Require empty history and an identical canonical snapshot,
+   including metadata. Changed facts or a newly appeared managed table block
+   acceptance. Investigate, recapture, and review; do not patch expected facts
+   into the candidate to hide differences.
+4. **Accept** only after verifying the acknowledgments below. Acceptance repeats
+   preflight and records a non-executable baseline at sequence zero with a null
+   parent. Preserve the returned or written artifact.
+
+Capture and preflight record no baseline and change no application schema/data.
+Session setup may initialize Qubu history tables and perform lease bookkeeping.
+Stop other migrators and prevent concurrent DDL throughout cutover. Leases
+coordinate participating Qubu runners, not every possible schema writer.
+Preflight needs no acceptance confirmations. Comparison failures include
+diagnostics and actual snapshot evidence when available.
+
+### Acceptance acknowledgments
+
+All seven facts must be true. The application acknowledgment means incompatible
+code remains stopped; it does not assert that desired code is already compatible.
+
+| CLI confirmation                     | What the operator verifies                                                         |
+| ------------------------------------ | ---------------------------------------------------------------------------------- |
+| `database-target`                    | The configured connection targets the intended database and environment            |
+| `snapshot-source`                    | The selected candidate was captured and reviewed using the unchanged managed scope |
+| `zero-managed-drift`                 | Fresh strict inspection has zero differences from the reviewed candidate           |
+| `backup-restore-ready`               | Backup and restore procedures are ready                                            |
+| `other-migrators-stopped`            | Other runners are stopped and concurrent DDL is prevented                          |
+| `incompatible-application-prevented` | Incompatible code will remain stopped until reconciliation is complete             |
+| `legacy-history-cutover`             | The team accepts this baseline as the new lineage start                            |
+
+## Shared CLI
+
+Install `@qubu/cli`, `@qubu/migrate`, and the selected adapter and driver.
+Configure the [CLI](operations.md#configuration) with the existing database,
+desired application snapshot, and an empty artifact directory. Standard `libsql`
+and `pg` migration adapters provide strict inspection; intentional `readSnapshot`
+overrides remain caller-owned. The CLI accepts either a migration adapter or an
+adoption-only `baselineAdapter` in `config.adapter`. See the connection examples
+for [PostgreSQL](#postgresql-configuration) and [MySQL](#mysql).
+
+Capture and review:
+
+```bash
+qubu migrate baseline-capture --out ./baseline-candidate.json \
+  --config ./qubu.config.js --format json
+```
+
+The CLI refuses to overwrite the file and reports the config path, environment,
+dialect, namespace, configured managed tables, included tables, and exclusions.
+After reviewing that output and candidate, run preflight:
+
+```bash
+qubu migrate baseline initial --candidate ./baseline-candidate.json \
+  --config ./qubu.config.js --dry-run --format json
+```
+
+Once all [acknowledgments](#acceptance-acknowledgments) are verified, accept:
+
+```bash
+qubu migrate baseline initial --candidate ./baseline-candidate.json \
+  --config ./qubu.config.js \
+  --confirm database-target \
+  --confirm snapshot-source \
+  --confirm zero-managed-drift \
+  --confirm backup-restore-ready \
+  --confirm other-migrators-stopped \
+  --confirm incompatible-application-prevented \
+  --confirm legacy-history-cutover \
+  --format json --non-interactive
+```
+
+### Shared API
+
+Import adoption operations from `@qubu/migrate/baseline` and `baselineAdapter`
+from the selected driver's `/migration` entry point. For example, with a
+dedicated MySQL connection:
+
+```ts
+import { baselineAdapter } from "@qubu/adapter-mysql2/migration"
+import { captureBaseline } from "@qubu/migrate/baseline"
+import { encodeSchemaSnapshot } from "qubu/snapshot"
+import { writeFile } from "node:fs/promises"
+
+const adapter = baselineAdapter(connection)
+const inspection = await captureBaseline({ adapter, scope: desiredSnapshot })
+await writeFile("baseline-candidate.json", encodeSchemaSnapshot(inspection.snapshot), {
+  flag: "wx",
+})
+```
+
+Review the candidate before continuing. Reuse the same database and original
+scope, and reload the reviewed file for preflight and acceptance:
+
+```ts
+import { readFile, writeFile } from "node:fs/promises"
+import { preflightBaseline, createBaseline } from "@qubu/migrate/baseline"
+import { encodeBaselineArtifact } from "@qubu/migrate/artifact"
+import { assertSchemaSnapshot } from "qubu/snapshot"
+
+const candidate = assertSchemaSnapshot(await readFile("baseline-candidate.json", "utf8"))
+const input = { adapter, scope: desiredSnapshot, candidate, repository: [] }
+await preflightBaseline(input)
+
+const { artifact } = await createBaseline({
+  ...input,
+  id: "initial",
+  provenance: { source: "my-service" },
+  confirmation: {
+    databaseTargetVerified: true,
+    snapshotSourceVerified: true,
+    zeroManagedDriftVerified: true,
+    backupRestoreReady: true,
+    otherMigratorsStopped: true,
+    incompatibleApplicationPrevented: true,
+    legacyHistoryCutoverAccepted: true,
+  },
+})
+await writeFile("baseline-accepted.json", encodeBaselineArtifact(artifact), { flag: "wx" })
+```
+
+Supply the real artifact repository when one exists; `[]` represents an empty
+repository. The adapter separately verifies its database history. The caller
+owns connection cleanup, including after failed capture or acceptance.
+
+Existing custom migration adapters can use `fromMigrationAdapter(adapter)` from
+`@qubu/migrate/baseline`. It reuses their strict reader, lease, and journal. A
+custom adoption-only adapter implements `openBaselineSession`; its session
+provides schema inspection, empty-history verification, baseline recording,
+and cleanup. It does not need SQL execution or migration recovery methods.
+
+### PostgreSQL configuration
+
+The caller owns connecting, releasing, and ending the pinned `pg` client. Keep
+it exclusively available until the migration session closes. Qubu releases its
+locks and closes its session; it never releases or ends the supplied client.
+
+This CLI wrapper opens a client per session and ends it after cleanup. Set
+`search_path` to the snapshot namespace: inspection selects it explicitly, while
+journal SQL and unqualified migration statements use `search_path`.
+
+```ts
+import { defineConfig } from "@qubu/cli/config"
+import { migrationAdapter } from "@qubu/adapter-pg/migration"
+import { Client } from "pg"
+import snapshot from "./schema.snapshot.js"
+
+export default defineConfig({
+  artifacts: "./migrations",
+  snapshot,
+  environment: "production",
+  provenance: { source: "my-service" },
+  adapter: () => ({
+    async openMigrationSession(signal) {
+      const connectionString = process.env.DATABASE_URL
+      if (!connectionString) throw new Error("DATABASE_URL is required")
+      const client = new Client({ connectionString })
+      try {
+        await client.connect()
+        const namespace = '"' + snapshot.namespace.name.replaceAll('"', '""') + '"'
+        await client.query("SELECT set_config('search_path', $1, false)", [namespace])
+        const session = await migrationAdapter(client).openMigrationSession(signal)
+        const close = session.close.bind(session)
+        let closed = false
+        session.close = async () => {
+          if (closed) return
+          closed = true
+          try {
+            await close()
+          } finally {
+            await client.end()
+          }
+        }
+        return session
+      } catch (error) {
+        await client.end()
+        throw error
+      }
+    },
+  }),
+})
+```
+
+## MySQL
+
+Use a dedicated `mysql2/promise` connection with autocommit enabled and no active
+transaction. This configuration opens a connection per adoption session and
+ends it after cleanup. Run the [shared CLI commands](#shared-cli) with this config:
+
+```ts
+import { defineConfig } from "@qubu/cli/config"
+import { baselineAdapter } from "@qubu/adapter-mysql2/migration"
+import mysql from "mysql2/promise"
+import snapshot from "./schema.snapshot.js"
+
+export default defineConfig({
+  artifacts: "./migrations",
+  snapshot,
+  environment: "production",
+  provenance: { source: "my-service" },
+  adapter: () => ({
+    async openBaselineSession(scope, signal) {
+      const connection = await mysql.createConnection(process.env.DATABASE_URL!)
+      try {
+        const session = await baselineAdapter(connection).openBaselineSession(scope, signal)
+        return {
+          ...session,
+          async close() {
+            try {
+              await session.close()
+            } finally {
+              await connection.end()
+            }
+          },
+        }
+      } catch (error) {
+        await connection.end()
+        throw error
+      }
+    },
+  }),
+})
+```
+
+Acceptance inserts one baseline record in `__qubu_mysql2_migrations`. Its
+`baseline` column contains the full sealed artifact, including the reviewed
+snapshot, provenance, and acknowledgments. The CLI also writes that artifact to
+the configured repository.
+
+This adoption-only configuration cannot run `migrate apply`, `status`, or
+`reconcile`, which require the shared migration executor. Use the basic MySQL
+runner for subsequent SQL migrations as shown below.
+
+## After acceptance
+
+If recording or artifact-file writing fails, inspect history and saved files
+before retrying. The shared CLI records the journal before writing the artifact;
+MySQL can lose an insert response after the record commits. Rerunning adoption
+against nonempty history is not a recovery procedure. For MySQL, inspect:
+
+```sql
+SELECT id, hash, baseline FROM __qubu_mysql2_migrations WHERE id = 'initial';
+```
+
+Reconcile the desired application schema in a separate reviewed migration.
+For SQLite/PostgreSQL, keep `config.snapshot` as the desired snapshot and plan
+from the accepted baseline:
+
+```bash
+qubu migrate create add-manifest --config ./qubu.config.js --dry-run --format json
+```
+
+Review approvals or custom programs, create the artifact, and apply it through
+the [normal workflow](operations.md). The tested path extends the captured
+catalog snapshot with a supported change. Independently authored snapshots can
+differ in constraint names, native types, defaults, or dialect metadata even
+when their SQL seems equivalent. Adoption adds no general SQL equivalence rules
+or automatic repairs.
+
+For MySQL, review changes against the accepted snapshot and append SQL migrations
+with distinct, permanent IDs:
+
+```ts
+import { migrate } from "@qubu/adapter-mysql2/migration"
+
+await migrate(connection, [{ id: "add-manifest", sql: ["ALTER TABLE game ADD manifest JSON"] }])
+```
+
+The basic runner skips completed IDs. It does not check live schema drift before
+subsequent migrations or consume sealed executable artifacts. Partial failures
+still require inspection before retrying.