qubu 0.4.3 → 0.5.0

package/docs/migrations/adapters.md

@@ -0,0 +1,70 @@
+# Adapter capability profiles
+
+> 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
+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                                           |
+
+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.
+
+## 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 |
+
+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.
+
+These exported profiles are unavailable and must not be passed to the
+executor:
+
+| Export                      | Status            | Reason                                                                              |
+| --------------------------- | ----------------- | ----------------------------------------------------------------------------------- |
+| `d1MigrationProfile`        | `incompatible`    | D1 exposes no pinned interactive transaction/session contract                       |
+| `mysql2MigrationProfile`    | `not-yet-written` | MySQL implicit-commit lease, checkpoint, and recovery semantics are not live-proven |
+| `bunSqliteMigrationProfile` | `not-yet-written` | A Bun-native pinned-session and journal conformance run is missing                  |
+
+Unavailable profiles expose `reason` and `missingCapabilities`; they do not
+fall back to a generic executor.
+
+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"
+
+const client = createClient({ url: process.env.DATABASE_URL! })
+const adapter = libsqlMigrationAdapter(client, {
+  readSnapshot: readLibsqlMigrationSnapshot,
+})
+```
+
+`DATABASE_URL` remains application configuration; neither the adapter nor CLI
+assigns deployment-provider meaning to it.

package/docs/migrations/artifacts-and-policy.md

@@ -0,0 +1,123 @@
+# Artifacts and approval policy
+
+> Review exactly what is authenticated and executable before an artifact enters a repository.
+
+Qubu has two strict artifact kinds. An executable migration contains a reviewed
+plan and authoritative program. A verified baseline records an observed schema
+without pretending that historical SQL ran.
+
+## Published formats
+
+These format versions are independent of npm package semver:
+
+| Value                       | Current version | Meaning                                  |
+| --------------------------- | --------------: | ---------------------------------------- |
+| `qubu-executable-migration` |               1 | Executable artifact envelope             |
+| `qubu-verified-baseline`    |               1 | Non-executable verified starting point   |
+| `qubu-migration-program`    |               1 | Ordered executable phases and statements |
+| `qubu-migration-plan`       |               2 | Dialect-neutral reviewed plan            |
+| `qubu-canonical-json`       |               1 | Canonical JSON byte encoding             |
+| `sha-256`                   |               1 | Operational digest algorithm contract    |
+| `qubu-migration-journal`    |               1 | Logical journal format                   |
+
+Strict decoders reject unknown keys, malformed values, non-canonical encoded
+text, unsupported versions, and digest mismatches. There is no compatibility
+decoder for provisional application formats.
+
+### Executable artifact schema
+
+An executable artifact records:
+
+- `id`, zero-based `sequence`, and `parentArtifactDigest` lineage;
+- canonicalization and digest descriptors, dialect, and optional minimum server
+  version or required capability constraints;
+- the plan plus `planDigest`;
+- renderer identity, the program, and `programDigest`;
+- before/after snapshot descriptors, each with a strong digest and either an
+  embedded snapshot or a reference;
+- operation-scoped approvals and custom-program provenance;
+- artifact provenance and `artifactDigest`.
+
+The program—not `emitMigrationPlan(...).sql` and not joined statement text—is
+the execution authority. Each phase declares its position, dependencies,
+transaction and lock requirements, preconditions, postconditions, and ordered
+statements. Each statement declares its operation ID, dependencies, SQL, and
+tagged parameters.
+
+### Baseline artifact schema
+
+A baseline records `id`, sequence and parent lineage, encoding descriptors,
+dialect and optional constraints, one verified snapshot descriptor,
+`verifiedAt`, provenance, optional operator metadata, and `artifactDigest`. It
+has no migration plan, program, or SQL digest.
+
+Artifact IDs are stable identities, not repository order. Sequence and parent
+digest establish the linear chain. Renumbering therefore changes lineage and
+the artifact digest.
+
+## Canonical bytes and digest domains
+
+`encodeCanonical()` sorts object keys by Unicode code-point order, preserves
+array order, emits compact JSON as UTF-8, normalizes `-0` to `0`, rejects
+non-finite numbers, and adds one LF at EOF. `digestCanonical()` prefixes those
+bytes with the UTF-8 bytes for:
+
+```text
+qubu:migrate:v1:<domain>\0
+```
+
+The five domains are `artifact`, `baseline`, `migration-plan`,
+`migration-program`, and `schema-snapshot`. Domain separation prevents equal
+JSON values used for different purposes from sharing an integrity identity.
+Operational digests have the form `sha256:` plus 64 lowercase hexadecimal
+digits and are recomputed while sealing or decoding.
+
+Snapshot and plan `fingerprint` APIs are deterministic FNV-1a64 change
+detectors. They remain useful for caches and fixture assertions, but they are
+not cryptographic integrity evidence and are never valid journal heads,
+artifact parents, or substitutes for a SHA-256 field.
+
+## Exact approval policy
+
+Preview planning may retain unresolved safety findings. Sealing is stricter:
+
+| Operation state                        | Sealing rule                                                                      |
+| -------------------------------------- | --------------------------------------------------------------------------------- |
+| Safe and supported                     | No approval required                                                              |
+| Review-required, destructive, or lossy | Exact `operationId` approval with a non-empty reason                              |
+| Unknown or unsupported                 | Exact custom-program substitution and `custom-program` approval                   |
+| Explicit custom SQL                    | Always requires exact review and a reason                                         |
+| Skipped operation                      | Recompute the target snapshot before sealing; never preserve a false after-digest |
+
+An approval also records the operation's safety and the exact sorted finding
+codes. It may record `approvedBy` and `approvedAt`. A mismatched operation ID,
+safety classification, finding set, or decision fails compilation. A broad
+"allow unsafe" option on the preview DDL emitter is not an artifact-sealing
+approval.
+
+Custom programs replace one exact operation. They must declare transaction and
+lock requirements, statements, tagged parameters, and any pre/postconditions,
+plus source and reason provenance. Qubu does not split arbitrary SQL, infer its
+effects, or approve it automatically.
+
+## Version and golden-fixture maintenance
+
+Treat canonical bytes and the meaning of every published field as release
+contracts. When changing an encoder, tag, ordering rule, parameter encoding,
+renderer meaning, or schema:
+
+1. Keep golden values for every already-published artifact, baseline, program,
+   plan, snapshot, canonicalization, and digest version.
+2. Verify the same canonical bytes and SHA-256 results in Node.js, Bun, and a
+   worker-compatible Web Crypto runtime.
+3. If encoded bytes or semantics change, introduce a new explicit format,
+   canonicalization, digest, plan, program, renderer, or artifact version as
+   appropriate. Do not silently update a version 1 fixture.
+4. Keep old fixtures as decode/verification evidence for supported published
+   versions; add a new fixture for the new version.
+5. Run artifact tamper/non-canonical tests and packed-package checks before
+   release.
+
+The current canonical SHA-256 vectors live with
+`packages/migrate/test/artifact.test.ts`; changes to them require the same
+intentional version decision as file-based golden fixtures.

package/docs/migrations/index.md

@@ -0,0 +1,46 @@
+# Migration operations
+
+> Choose the package entrypoint that owns each migration concern without pulling database or Node.js behavior into pure schema code.
+
+Qubu migrations are split across explicit ownership boundaries:
+
+| Owner           | Imports                                            | Responsibility                                                                                                               |
+| --------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `qubu`          | `qubu/snapshot`, `qubu/diff`, `qubu/introspection` | Pure schema snapshots, comparison, and catalog mapping                                                                       |
+| `@qubu/migrate` | Focused subpaths listed below                      | Pure planning and compilation plus portable artifacts, journals, execution, status, baselines, and bootstrap                 |
+| `@qubu/cli`     | `@qubu/cli/config`, `@qubu/cli/repository`         | Node.js configuration loading, artifact files, commands, output, and process exit behavior                                   |
+| Adapter package | `@qubu/adapter-*/migration`                        | Pinned driver sessions, parameter binding, transactions, leases, locks, database journal storage, and failure classification |
+| Application     | Its own configuration and deployment code          | Credentials, environment selection, approval policy, custom SQL, rollout timing, and legacy cutover decisions                |
+
+The pre-alpha `qubu/migration` and `qubu/ddl` entrypoints no longer exist. Use
+the extracted compiler entrypoints:
+
+```ts
+import { createMigrationPlan } from "@qubu/migrate/plan"
+import { emitMigrationPlan } from "@qubu/migrate/ddl"
+import { compileMigrationProgram, sealExecutableArtifact } from "@qubu/migrate/artifact"
+```
+
+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             |
+
+Start with [Artifacts and approval policy](artifacts-and-policy.md) when
+reviewing a migration format. Check [Adapter capability
+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.

package/docs/migrations/lotta-adoption.md

@@ -0,0 +1,50 @@
+# Lotta Games adoption
+
+> Replace Lotta's provisional runner with Qubu while preserving product-owned deployment policy and historical truth.
+
+Adopt the released `@qubu/migrate`, `@qubu/cli`, and libSQL migration entrypoint
+as a hard cutover. Do not add an upstream decoder for Lotta's provisional JSON,
+FNV artifact digests, journal, or broad unsafe flags.
+
+Before changing downstream state, inspect every environment for a provisional
+journal or baseline row. Regenerate unreleased migrations in the Qubu artifact
+format. For an existing database, create one standard baseline only after strict
+live introspection matches the intended Qubu snapshot. That baseline records a
+verified starting state; it does not claim that old migrations ran through
+Qubu.
+
+Keep these concerns in Lotta:
+
+- Turso credentials and environment selection;
+- Cloudflare deployment waiting and migrate-first/migrate-last prompts;
+- the destructive-deny approval policy and product-specific custom programs;
+- rollout timing and the one-time legacy journal cutover decision.
+
+Replace the private migration and runner modules with thin configuration and
+CLI/library invocation. Make the release script apply the complete pending
+repository chain and preserve non-zero failures. Generate fresh local test
+databases with `schema bootstrap`; keep connection PRAGMAs in the test harness.
+
+> [!WARNING]
+> Keep Drizzle migration SQL and snapshots read-only. Do not import or replay
+> Drizzle history. A verified baseline is the handoff from historical state to
+> Qubu lineage.
+
+The downstream verification set should cover a fresh bootstrap, an already
+baselined database, a no-op deploy, pending migrations in both deployment
+timing modes, drift refusal, concurrent invocation, rollback, and explicit
+recovery.
+
+## Combo-matrix release blocker
+
+The main repository currently pins the `combos` submodule gitlink to
+`2e2856e5692ef5cbef03a055fa71e5baab8ec10a`. Commit `d9d2e02` added and verified
+migration profiles in the main repository without advancing that gitlink, so
+the orphan-branch adapter × environment matrix is not yet synchronized with the
+new profile claims. This is an unresolved pinned-SHA issue, not evidence that
+the matrix has verified the new migration entrypoints.
+
+Do not edit the gitlink or matrix as part of Lotta adoption. Before release,
+update the `combos` branch in its own review, run the declared environments and
+real database round trips, classify every candidate pair, then advance the main
+repository gitlink to that reviewed commit in a separate change.

package/docs/migrations/operations.md

@@ -0,0 +1,133 @@
+# Command line operations
+
+> Configure, inspect, baseline, and apply a complete migration chain with stable non-interactive behavior.
+
+Install the CLI, migration library, and one verified migration adapter. For a
+libSQL application:
+
+```bash
+pnpm add @qubu/cli @qubu/migrate @qubu/adapter-libsql @libsql/client
+```
+
+The `qubu` binary is implemented with `@alloc/cmd-ts`. It loads
+`qubu.config.js` by default; `--config <path>` selects another application-owned
+module. Every command accepts `--format human|json` (default `human`) and
+`--non-interactive`. Commands do not prompt today; `--non-interactive` records
+the deployment contract and missing explicit input still fails.
+
+## Configuration
+
+Export a typed config and keep credentials inside the adapter factory:
+
+```ts
+import { createClient } from "@libsql/client"
+import { libsqlMigrationAdapter, readLibsqlMigrationSnapshot } from "@qubu/adapter-libsql/migration"
+import { defineConfig } from "@qubu/cli/config"
+import snapshot from "./schema.snapshot.js"
+
+const url = process.env.DATABASE_URL
+if (!url) throw new Error("DATABASE_URL is required")
+
+export default defineConfig({
+  artifacts: "./migrations",
+  snapshot,
+  environment: "production",
+  adapter: () =>
+    libsqlMigrationAdapter(createClient({ url }), {
+      readSnapshot: readLibsqlMigrationSnapshot,
+    }),
+  provenance: { source: "my-service" },
+})
+```
+
+`snapshot` may be a value or async factory. Alternatively provide both
+`schema` and `snapshotFromSchema`. Optional configuration owns operation
+approvals, custom programs, renderer/server constraints, baseline operator
+metadata, and reconciliation proof. `artifacts` is resolved from the CLI
+working directory.
+
+| Field                                      | Required            | Meaning                                                                                      |
+| ------------------------------------------ | ------------------- | -------------------------------------------------------------------------------------------- |
+| `artifacts`                                | yes                 | Artifact directory, relative to the command working directory unless absolute                |
+| `snapshot`                                 | one snapshot source | Snapshot value or sync/async factory                                                         |
+| `schema` + `snapshotFromSchema`            | one snapshot source | Application-owned conversion when the source is a Qubu `Schema`                              |
+| `adapter`                                  | database commands   | Sync/async factory returning a migration adapter                                             |
+| `approvals`                                | no                  | Sync/async operation policy; receives the operation, finding codes, and requested CLI reason |
+| `customPrograms`                           | no                  | Exact operation substitutions with execution requirements and provenance                     |
+| `renderer`, `serverVersion`, `constraints` | no                  | Renderer identity and target compatibility constraints                                       |
+| `provenance`                               | no                  | Artifact source/revision/actor/metadata; defaults to `{ source: "@qubu/cli" }`               |
+| `environment`                              | no                  | `development`, `test`, `staging`, or `production`; context only                              |
+| `baselineOperator`                         | no                  | JSON-safe operator metadata stored in a baseline                                             |
+| `verifyReconciliation`                     | reconcile only      | Application-owned proof of the selected live outcome                                         |
+
+## Commands
+
+| Syntax                                                                                              | Reads or writes                                                                                                                             | Important failure behavior                                                                                     |
+| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `qubu migrate create <id> [--approve <operation-id=reason>...] [--approved-by <actor>] [--dry-run]` | Verifies the full repository, plans from its embedded final snapshot, seals, then writes one canonical artifact unless dry-run              | Unknown operation IDs or missing exact approvals fail policy                                                   |
+| `qubu migrate verify`                                                                               | Strictly decodes and verifies every artifact and the complete chain                                                                         | Any malformed, tampered, forked, gapped, or mismatched artifact fails validation                               |
+| `qubu migrate status`                                                                               | Opens a session and lease; reports managed drift, unmanaged objects, pending artifacts, interrupted attempts, and incompatible requirements | Recovery, validation, drift, and capability policy are distinct failures                                       |
+| `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                                                                           |
+
+JSON output is stable, newline-terminated, recursively key-sorted, and redacts
+credential-like keys and credentials or secrets embedded in URLs. Human output
+is deliberately terse. Signals propagate through adapters; an abort exits 130.
+
+| Exit | Meaning                                                                       |
+| ---: | ----------------------------------------------------------------------------- |
+|    0 | Success                                                                       |
+|    2 | CLI usage or argument error                                                   |
+|    3 | Artifact, repository, journal, or other validation failure                    |
+|    4 | Policy or adapter-capability refusal                                          |
+|    5 | Managed schema drift                                                          |
+|    6 | Recovery or reconciliation required                                           |
+|    7 | Adapter, concurrency, rollback, uncertain-outcome, or other execution failure |
+|  130 | Aborted                                                                       |
+
+## Status, drift, and bootstrap
+
+Status compares managed physical schema facts against the embedded expected
+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.
+
+## Baseline and cutover checklist
+
+A baseline is a statement about the live database now, not a replay of its
+history. Before supplying all seven confirmations, the operator must verify:
+
+- `database-target`: the connection names the intended environment;
+- `snapshot-source`: the reviewed snapshot is the intended source of truth;
+- `zero-managed-drift`: strict inspection reports no managed mismatch;
+- `backup-restore-ready`: backup and restore procedures are ready;
+- `other-migrators-stopped`: no other migration runner can race the cutover;
+- `application-compatible`: deployed code is compatible with the live schema;
+- `legacy-history-cutover`: the team accepts the new baseline as the lineage start.
+
+For example, repeat `--confirm` once per exact value. The CLI rejects missing
+or unknown confirmation names even outside production; `environment` is
+reported as context rather than used to weaken the policy.
+
+```bash
+qubu migrate baseline lotta-cutover \
+  --confirm database-target \
+  --confirm snapshot-source \
+  --confirm zero-managed-drift \
+  --confirm backup-restore-ready \
+  --confirm other-migrators-stopped \
+  --confirm application-compatible \
+  --confirm legacy-history-cutover \
+  --format json --non-interactive
+```
+
+After success, preserve the written baseline artifact with the repository. Its
+sequence is zero, its parent is null, and later migrations extend its digest.

package/docs/migrations/recovery.md

@@ -0,0 +1,121 @@
+# Recovery and reconciliation
+
+> Stop after an ambiguous attempt, prove the live outcome, and repair journal lineage without replaying SQL.
+
+The journal has one versioned metadata row with an atomic head, immutable
+applied artifact records, mutable attempts, phase/statement checkpoints, and
+append-only reconciliation records. Adapter implementations store it in the
+same database and reserve `__qubu_migration_`-prefixed objects from managed
+schema inspection.
+
+| Record           | Fields and invariant                                                                                           |
+| ---------------- | -------------------------------------------------------------------------------------------------------------- |
+| Metadata         | `format`, `version`, and nullable SHA-256 `head`; the head equals the final applied digest                     |
+| Applied artifact | `artifactId`, `sequence`, artifact/parent digests, `kind`, `attemptId`, and `appliedAt`; records are immutable |
+| Attempt          | ID, artifact ID/digest, expected head, state, timestamps, and optional redacted failure                        |
+| Checkpoint       | Attempt/phase IDs, optional statement ID, `started` or `completed`, and timestamp                              |
+| Reconciliation   | Attempt ID, proven `applied` or `rolled_back` outcome, non-empty reason, and timestamp                         |
+
+## Attempt state machine
+
+The diagram shows every legal state transition. `started`, `running`, and
+`recovery_required` all block later migrations until the attempt reaches a
+terminal state.
+
+```mermaid
+stateDiagram-v2
+  [*] --> started
+  started --> running
+  started --> rolled_back: definite failure
+  started --> recovery_required: interrupted or uncertain
+  running --> applied: history + head recorded
+  running --> rolled_back: definite rollback
+  running --> recovery_required: effect or outcome uncertain
+  recovery_required --> applied: verified reconciliation
+  recovery_required --> rolled_back: verified reconciliation
+  applied --> [*]
+  rolled_back --> [*]
+```
+
+An `applied` attempt must have a matching immutable applied record. Applied
+records must form a zero-based linear sequence whose final digest equals the
+metadata head. The journal must be an exact prefix of the artifact repository.
+Duplicate IDs or digests, forks, gaps, parent mismatches, tampering, a stale
+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
+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.
+
+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
+structured `concurrency` error.
+
+| Phase requirement | Executor behavior                                                                                                                                   |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `required`        | Refuses an adapter without proven transactional DDL; runs that phase transactionally, with the applied/head update in the final phase's transaction |
+| `optional`        | Uses a transaction when `optionalTransactions` is true; otherwise relies on checkpoints                                                             |
+| `forbidden`       | Runs outside a transaction only on a profile advertising checkpointed forbidden phases                                                              |
+| Mixed program     | Reports phase-level behavior and returns `mixed` atomicity rather than claiming whole-migration atomicity                                           |
+
+Program compilation has no `unknown` transaction state: unresolved requirements
+must be resolved by the renderer or explicit custom program before sealing.
+Transactions are phase-scoped. Do not infer that an earlier committed phase
+will roll back because a later phase fails.
+
+Errors use stable codes: `validation`, `policy`, `drift`, `concurrency`,
+`capability`, `definite-rollback`, `uncertain-outcome`, `recovery-required`,
+`aborted`, and `adapter`. Context may include artifact, attempt, phase, and
+statement identifiers. Persisted failures omit SQL parameters and credentials.
+
+Do not automatically retry after any statement may have taken effect. Only an
+error explicitly marked `retry: "safe"`—normally validation or a failure proven
+before execution—is retryable. A definite transaction rollback ends as
+`rolled_back`; an interrupted non-transactional phase, ambiguous commit or
+rollback, or unproven effect ends as `recovery_required`.
+
+## Reconciliation runbook
+
+1. Stop deploys and every migration runner for the target database. Preserve
+   logs, the artifact repository, the database, and journal rows.
+2. Run `qubu migrate status --format json --non-interactive`. Record the
+   interrupted attempt ID, artifact digest, checkpoints, journal head, pending
+   chain, managed drift, and incompatible requirements.
+3. Find the exact artifact by digest. Verify the repository again; do not edit,
+   renumber, or reseal it to make the chain pass.
+4. Inspect the live database through adapter/application-owned checks. Use
+   completed checkpoints only as evidence of where to inspect, not as proof
+   that a statement committed. Verify the artifact's preconditions,
+   postconditions, and expected snapshot.
+5. Decide `applied` only if the application can prove the artifact's complete
+   post-state. Decide `rolled_back` only if it can prove the complete pre-state
+   and absence of all intended effects. If neither is provable, restore or
+   repair under an application-specific incident plan; do not guess.
+6. Configure `verifyReconciliation` to repeat that proof, then run:
+
+   ```bash
+   qubu migrate reconcile <attempt-id> \
+     --outcome applied \
+     --reason "Verified every postcondition against incident INC-123" \
+     --format json --non-interactive
+   ```
+
+   Use `--outcome rolled_back` only for a proven pre-state. The reconciler
+   requires a non-empty reason and the application verifier to return true.
+
+7. Run `migrate status` again. Confirm no interrupted attempt remains, the head
+   and applied history form the repository prefix, managed drift is zero, and
+   only the intended pending artifacts remain.
+8. Resume with `migrate apply`. Never replay individual SQL statements from the
+   uncertain artifact.
+
+When reconciliation records `applied`, Qubu appends the missing immutable
+history/head for the exact artifact if needed. When it records `rolled_back`,
+the head stays at the previous artifact. Both outcomes append an audit record.

package/docs/reference/introspection-support.md

@@ -151,7 +151,7 @@ The mapper can emit these facts in canonical Snapshot v1:
 - stable logical IDs with physical names preserved separately.
 
 Strict mode returns no snapshot when a supported table fact cannot be mapped
-soundly. Lossy mode is explicit and marks warnings in the result. A digest is
+soundly. Lossy mode is explicit and marks warnings in the result. A fingerprint is
 canonical content, not an identity or rename marker.
 
 ## Deferred and limited features