@cynodia/axiom-server 0.11.0-alpha.1 → 0.11.2-alpha.1

package/README.md

@@ -22,21 +22,39 @@ SQLite), `TransportAdapter` (in-process and HTTP), `ServerHost` for time, identi
 scheduling and authentication, and `IntegrationAdapter` for external systems. Nothing in
 an ApplicationGraph mentions HTTP, SQL, a route or an SDK.
 
-As of 0.8 this package also owns timed and event-driven execution: it schedules and
-dispatches `TriggerDef`s, records `integration-effect` intent atomically with the state
-write that requested it (the transactional outbox), dispatches an effect's committed
-intents to its `IntegrationAdapter` post-commit with retry, and translates verified
-webhook deliveries into semantic events. See
-[`docs/INTEGRATIONS.md`](https://github.com/cynodia/axiom/blob/main/docs/INTEGRATIONS.md),
-[`docs/EFFECTS.md`](https://github.com/cynodia/axiom/blob/main/docs/EFFECTS.md) and
-[`docs/TRIGGERS.md`](https://github.com/cynodia/axiom/blob/main/docs/TRIGGERS.md).
+This package also owns the parts of an application that only the authority can run:
+
+- **Timed and event-driven execution** (0.8) — scheduling and dispatching `TriggerDef`s,
+  the transactional outbox for `integration-effect` intent, post-commit effect delivery
+  with retry, and verified-webhook → semantic-event translation. See
+  [`docs/INTEGRATIONS.md`](https://github.com/cynodia/axiom/blob/main/docs/INTEGRATIONS.md),
+  [`docs/EFFECTS.md`](https://github.com/cynodia/axiom/blob/main/docs/EFFECTS.md),
+  [`docs/TRIGGERS.md`](https://github.com/cynodia/axiom/blob/main/docs/TRIGGERS.md).
+- **Inbound streams and binary storage** (0.9) — long-lived `SubscriptionDef` sources
+  feeding the event pipeline, and `StorageDef` object stores behind host blob transports.
+  See [`docs/SUBSCRIPTIONS.md`](https://github.com/cynodia/axiom/blob/main/docs/SUBSCRIPTIONS.md),
+  [`docs/STORAGE.md`](https://github.com/cynodia/axiom/blob/main/docs/STORAGE.md).
+- **The query layer** (0.10) — demand-driven `QueryDef` reads over authoritative data too
+  large to materialize, `DataProvider`s (`createMemoryDataProvider` / `createSqliteDataProvider`),
+  fingerprinted keyset cursors, and a principal/policy-scoped result cache. See
+  [`docs/QUERIES.md`](https://github.com/cynodia/axiom/blob/main/docs/QUERIES.md).
+- **Schema evolution** (0.11) — `planMigration` / `explainMigration`, the host-controlled
+  `executeMigration`, the durable `MigrationMetadataStore` and lease lock, keyset-batched
+  crash-resumable migration, memory and SQLite `MigrationRowStore`s, and the
+  `createAxiomServer` startup gate. Concurrent migrators — including two OS processes on one
+  SQLite file — resolve to `completed` / `MIGRATION_IN_PROGRESS` / `alreadyAtTarget`; the
+  SQLite provider absorbs physical `SQLITE_BUSY` contention internally (0.11.2). See
+  [`docs/MIGRATIONS.md`](https://github.com/cynodia/axiom/blob/main/docs/MIGRATIONS.md).
 
 Main exports: `createAxiomServer`, `createMemoryPersistence`, `createSqlitePersistence`,
 `createServerHost`, `createDeterministicServerHost`, `createDirectTransport`,
 `createHttpTransport`, `createRemoteGateway`, `serveOverHttp`, `serveAxiomApplication`,
 `createFakeIntegrationAdapter`, `createHttpIntegrationAdapter`, `createTriggerRuntime`,
-`createEffectRunner`, `runConformanceFixture`, `runConformanceSuite`,
-`SERVER_DIAGNOSTIC_CODES`.
+`createEffectRunner`, `createMemoryDataProvider`, `createSqliteDataProvider`,
+`createMemoryMigrationStore`, `createSqliteMigrationStore`, `createMemoryRowStore`,
+`createSqliteRowStore`, `planMigration`, `explainMigration`, `executeMigration`,
+`getMigrationStatus`, `migrationAuthority`, `runConformanceFixture`, `runConformanceSuite`,
+`runQueryConformanceFixture`, `runMigrationConformanceFixture`, `SERVER_DIAGNOSTIC_CODES`.
 
 `serveAxiomApplication` is the whole deployment story: it serves the generated page at `GET /`
 and the semantic endpoint at `POST /axiom`, from one process, for any Axiom application. No
@@ -44,17 +62,26 @@ route, controller, handler or SQL statement is written by an application author.
 
 ### Portable artifacts
 
-`axiom.server.v1` is a frozen, language-independent contract, and this package ships what an
-implementation in another language needs to conform to it:
+The Server IR contract is versioned. **`axiom.server.v1` is frozen** — its bytes and
+semantics never change — but it is **not the current contract**: a document declares the
+oldest contract that can carry its vocabulary, computed from the document. The current
+contract is **`axiom.server.v7`** (0.11 schema-evolution vocabulary); `v1`–`v6` are frozen
+and shipped for compatibility. This package ships what an implementation in another language
+needs to conform:
 
 ```
-@cynodia/axiom-server/conformance                       the fixture manifest
-@cynodia/axiom-server/conformance/<name>.json           one fixture: IR, state, invocations, expectations
-@cynodia/axiom-server/schema/server-ir.v1.schema.json   JSON Schema for the frozen v1 IR
-@cynodia/axiom-server/schema/server-ir.v2.schema.json   JSON Schema for v2 (+ group, expression-ref)
-@cynodia/axiom-server/schema/server-ir.v3.schema.json   JSON Schema for v3 (+ integrations, effects, triggers, events)
-@cynodia/axiom-server/schema/server-ir.v4.schema.json   JSON Schema for v4 (+ invocation source, structured effect outcome)
-@cynodia/axiom-server/schema/protocol.v1.schema.json    JSON Schema for the protocol
+@cynodia/axiom-server/conformance                          the base fixture manifest
+@cynodia/axiom-server/conformance/<name>.json              one base fixture: IR, state, invocations, expectations
+@cynodia/axiom-server/conformance/queries/<name>.json      one query conformance fixture (axiom.conformance.v4)
+@cynodia/axiom-server/conformance/migrations/<name>.json   one migration conformance fixture (axiom.conformance.v5)
+@cynodia/axiom-server/schema/server-ir.v1.schema.json      JSON Schema for the frozen v1 IR
+@cynodia/axiom-server/schema/server-ir.v2.schema.json      v2 (+ group, expression-ref)
+@cynodia/axiom-server/schema/server-ir.v3.schema.json      v3 (+ integrations, effects, triggers, events)
+@cynodia/axiom-server/schema/server-ir.v4.schema.json      v4 (+ invocation source, structured effect outcome)
+@cynodia/axiom-server/schema/server-ir.v5.schema.json      v5 (+ subscriptions, storage, blob operations)
+@cynodia/axiom-server/schema/server-ir.v6.schema.json      v6 (+ queries, relationships, read policies)
+@cynodia/axiom-server/schema/server-ir.v7.schema.json      v7 (+ migrations, schema version + fingerprint) — current
+@cynodia/axiom-server/schema/protocol.v1.schema.json       JSON Schema for the protocol
 ```
 
 The fixtures are pure data. Running them requires no part of this implementation — which is

package/conformance/migrations/add-optional-field.json

@@ -10,7 +10,7 @@
     "contract": "axiom.server.v7",
     "id": "migration-conformance",
     "name": "Migration Conformance",
-    "version": "0.11.0-alpha.1",
+    "version": "0.11.2-alpha.1",
     "schemaVersion": 2,
     "schemaFingerprint": "7e4d24d95c273ff084e7758508a02e35015d5db2ceda46ca61e7ee8a2c2a4929",
     "migrations": [

package/conformance/migrations/add-required-field-with-default.json

@@ -10,7 +10,7 @@
     "contract": "axiom.server.v7",
     "id": "migration-conformance",
     "name": "Migration Conformance",
-    "version": "0.11.0-alpha.1",
+    "version": "0.11.2-alpha.1",
     "schemaVersion": 2,
     "schemaFingerprint": "2c478dc5301786b76c6990e38e1659d621d7712fdfa785bf115b1275b9804877",
     "migrations": [

package/conformance/migrations/crash-and-resume.json

@@ -12,7 +12,7 @@
     "contract": "axiom.server.v7",
     "id": "migration-conformance",
     "name": "Migration Conformance",
-    "version": "0.11.0-alpha.1",
+    "version": "0.11.2-alpha.1",
     "schemaVersion": 2,
     "schemaFingerprint": "2c478dc5301786b76c6990e38e1659d621d7712fdfa785bf115b1275b9804877",
     "migrations": [

package/conformance/migrations/destructive-removal-approved.json

@@ -10,7 +10,7 @@
     "contract": "axiom.server.v7",
     "id": "migration-conformance",
     "name": "Migration Conformance",
-    "version": "0.11.0-alpha.1",
+    "version": "0.11.2-alpha.1",
     "schemaVersion": 2,
     "schemaFingerprint": "f9f0f88b1d0cd25eb570c1401fe3f96ca899330d8c210e79ef50a10e91ad236d",
     "migrations": [

package/conformance/migrations/destructive-removal-refused.json

@@ -12,7 +12,7 @@
     "contract": "axiom.server.v7",
     "id": "migration-conformance",
     "name": "Migration Conformance",
-    "version": "0.11.0-alpha.1",
+    "version": "0.11.2-alpha.1",
     "schemaVersion": 2,
     "schemaFingerprint": "f9f0f88b1d0cd25eb570c1401fe3f96ca899330d8c210e79ef50a10e91ad236d",
     "migrations": [

package/conformance/migrations/idempotent-rerun.json

@@ -10,7 +10,7 @@
     "contract": "axiom.server.v7",
     "id": "migration-conformance",
     "name": "Migration Conformance",
-    "version": "0.11.0-alpha.1",
+    "version": "0.11.2-alpha.1",
     "schemaVersion": 2,
     "schemaFingerprint": "2c478dc5301786b76c6990e38e1659d621d7712fdfa785bf115b1275b9804877",
     "migrations": [

package/conformance/migrations/invalid-target-record.json

@@ -11,7 +11,7 @@
     "contract": "axiom.server.v7",
     "id": "migration-conformance",
     "name": "Migration Conformance",
-    "version": "0.11.0-alpha.1",
+    "version": "0.11.2-alpha.1",
     "schemaVersion": 2,
     "schemaFingerprint": "2c478dc5301786b76c6990e38e1659d621d7712fdfa785bf115b1275b9804877",
     "migrations": [

package/conformance/migrations/large-batched-transformation.json

@@ -11,7 +11,7 @@
     "contract": "axiom.server.v7",
     "id": "migration-conformance",
     "name": "Migration Conformance",
-    "version": "0.11.0-alpha.1",
+    "version": "0.11.2-alpha.1",
     "schemaVersion": 2,
     "schemaFingerprint": "2c478dc5301786b76c6990e38e1659d621d7712fdfa785bf115b1275b9804877",
     "migrations": [

package/conformance/migrations/manifest.json

@@ -1,7 +1,7 @@
 {
   "conformance": "axiom.conformance.v5",
   "baseContract": "axiom.server.v7",
-  "release": "0.11.0-alpha.1",
+  "release": "0.11.2-alpha.1",
   "description": "Portable migration conformance fixtures (spec11 §84-86). Each file carries a compiled axiom.server.v7 target Server IR with its MigrationDef chain, the schema version the persisted data starts at, the source rows, any destructive approvals, and the exact expected outcome. Running one needs only a row store and the semantics in docs/MIGRATIONS.md + docs/AUTHORITY.md. Every fixture must produce equivalent target data on the memory and SQLite providers (spec11 §83).",
   "fixtures": [
     {

package/conformance/migrations/metadata-only-change.json

@@ -10,7 +10,7 @@
     "contract": "axiom.server.v7",
     "id": "migration-conformance",
     "name": "Migration Conformance",
-    "version": "0.11.0-alpha.1",
+    "version": "0.11.2-alpha.1",
     "schemaVersion": 2,
     "schemaFingerprint": "f9f0f88b1d0cd25eb570c1401fe3f96ca899330d8c210e79ef50a10e91ad236d",
     "migrations": [

package/conformance/migrations/migration-lock.json

@@ -11,7 +11,7 @@
     "contract": "axiom.server.v7",
     "id": "migration-conformance",
     "name": "Migration Conformance",
-    "version": "0.11.0-alpha.1",
+    "version": "0.11.2-alpha.1",
     "schemaVersion": 2,
     "schemaFingerprint": "2c478dc5301786b76c6990e38e1659d621d7712fdfa785bf115b1275b9804877",
     "migrations": [

package/conformance/migrations/missing-migration-path.json

@@ -10,7 +10,7 @@
     "contract": "axiom.server.v7",
     "id": "migration-conformance",
     "name": "Migration Conformance",
-    "version": "0.11.0-alpha.1",
+    "version": "0.11.2-alpha.1",
     "schemaVersion": 3,
     "schemaFingerprint": "5f584b6aacbe13facfb360b562bdfa020f96e5f4e6d7f63c3d0dc7edacc207eb",
     "migrations": [

package/conformance/migrations/record-transformation.json

@@ -11,7 +11,7 @@
     "contract": "axiom.server.v7",
     "id": "migration-conformance",
     "name": "Migration Conformance",
-    "version": "0.11.0-alpha.1",
+    "version": "0.11.2-alpha.1",
     "schemaVersion": 2,
     "schemaFingerprint": "428fde4036f9c14ec63905ce893e907318542fd1a89e6f946b4400713c80a4de",
     "migrations": [

package/conformance/migrations/relationship-addition.json

@@ -10,7 +10,7 @@
     "contract": "axiom.server.v7",
     "id": "migration-conformance",
     "name": "Migration Conformance",
-    "version": "0.11.0-alpha.1",
+    "version": "0.11.2-alpha.1",
     "schemaVersion": 2,
     "schemaFingerprint": "4b8e155b1b02f04b28cadd78f580b4ac35f5ba0149e4809e31bbabd145852af4",
     "migrations": [

package/conformance/migrations/remove-empty-field.json

@@ -10,7 +10,7 @@
     "contract": "axiom.server.v7",
     "id": "migration-conformance",
     "name": "Migration Conformance",
-    "version": "0.11.0-alpha.1",
+    "version": "0.11.2-alpha.1",
     "schemaVersion": 2,
     "schemaFingerprint": "f9f0f88b1d0cd25eb570c1401fe3f96ca899330d8c210e79ef50a10e91ad236d",
     "migrations": [

package/conformance/migrations/schema-fingerprint-mismatch.json

@@ -11,7 +11,7 @@
     "contract": "axiom.server.v7",
     "id": "migration-conformance",
     "name": "Migration Conformance",
-    "version": "0.11.0-alpha.1",
+    "version": "0.11.2-alpha.1",
     "schemaVersion": 2,
     "schemaFingerprint": "2c478dc5301786b76c6990e38e1659d621d7712fdfa785bf115b1275b9804877",
     "migrations": [

package/conformance/migrations/transform-field.json

@@ -10,7 +10,7 @@
     "contract": "axiom.server.v7",
     "id": "migration-conformance",
     "name": "Migration Conformance",
-    "version": "0.11.0-alpha.1",
+    "version": "0.11.2-alpha.1",
     "schemaVersion": 2,
     "schemaFingerprint": "f9f0f88b1d0cd25eb570c1401fe3f96ca899330d8c210e79ef50a10e91ad236d",
     "migrations": [

package/dist/index.d.ts

@@ -31,6 +31,8 @@ export * from './migration-eval.js';
 export * from './migration-executor.js';
 export * from './migration-execute.js';
 export * from './migration-conformance.js';
+export { SqliteContentionError, isSqliteContentionError, runWithBusyHandling, DEFAULT_BUSY_TIMEOUT_MS, DEFAULT_BUSY_ATTEMPTS, DEFAULT_BUSY_BACKOFF_MS, } from './sqlite-contention.js';
+export type { BusyHandlingOptions } from './sqlite-contention.js';
 export { createSqliteMigrationStore, createSqliteRowStore, isSqliteMigrationAvailable, } from './sqlite-migration.js';
 export type { SqliteMigrationStoreOptions, SqliteRowStoreOptions } from './sqlite-migration.js';
 export { createSqliteDataProvider, isSqliteAvailable as isSqliteDataProviderAvailable } from './sqlite-data-provider.js';

package/dist/index.js

@@ -22,6 +22,7 @@ export * from './migration-eval.js';
 export * from './migration-executor.js';
 export * from './migration-execute.js';
 export * from './migration-conformance.js';
+export { SqliteContentionError, isSqliteContentionError, runWithBusyHandling, DEFAULT_BUSY_TIMEOUT_MS, DEFAULT_BUSY_ATTEMPTS, DEFAULT_BUSY_BACKOFF_MS, } from './sqlite-contention.js';
 export { createSqliteMigrationStore, createSqliteRowStore, isSqliteMigrationAvailable, } from './sqlite-migration.js';
 export { createSqliteDataProvider, isSqliteAvailable as isSqliteDataProviderAvailable } from './sqlite-data-provider.js';
 export * from './effects.js';

package/dist/migration-execute.d.ts

@@ -18,16 +18,28 @@ import type { SchemaGateResult } from './migration-gate.js';
  */
 /**
  * The authority to run a migration. Deliberately **not** the nullable `PRINCIPAL` an action
- * authorization reads (spec11 §74): it is a distinct, host-minted token, so migration
- * authority can never be confused with ordinary application authorization.
+ * authorization reads (spec11 §74): it is a distinct, host-minted capability.
+ *
+ * Authorization is by **provenance, not shape** (spec11.1 §16-17). The object returned by
+ * `migrationAuthority()` is registered in a process-private `WeakSet` and frozen;
+ * `isMigrationPrincipal` checks membership of that set. An object a consumer builds with the
+ * same visible fields — `{ kind: 'axiom.migration-authority', grantedBy: 'operator' }` — or a
+ * spread copy `{ ...migrationAuthority('operator') }` is **not** in the set and is rejected.
+ * `grantedBy` remains visible as a descriptive audit label; it is not the source of
+ * authorization.
+ *
+ * The capability is process-local (spec11.1 §19) and is never serialized (spec11.1 §18):
+ * migration durability lives in the `MigrationMetadataStore`, the lease and the checkpoints,
+ * not in a portable token.
  */
 export interface MigrationPrincipal {
     readonly kind: 'axiom.migration-authority';
-    /** A free-form label the host records for the audit trail — an operator id, a deploy job. */
+    /** A descriptive audit label — an operator id, a deploy job. Not the source of authorization. */
     readonly grantedBy: string;
 }
-/** Construct migration authority. Only a host calls this. */
+/** Mint migration authority. Only a host calls this; the result cannot be reconstructed by shape. */
 export declare function migrationAuthority(grantedBy: string): MigrationPrincipal;
+/** True only for the exact object `migrationAuthority()` returned — provenance, not duck typing. */
 export declare function isMigrationPrincipal(value: unknown): value is MigrationPrincipal;
 export interface ExecuteMigrationOptions {
     ir: ServerIR;

package/dist/migration-execute.js

@@ -1,16 +1,22 @@
 import { MIGRATION_DIAGNOSTIC_CODES } from './migration.js';
 import { planMigration } from './migration.js';
-import { runMigration } from './migration-executor.js';
+import { classifyMigrationContention, runMigration } from './migration-executor.js';
 import { evaluateSchemaGate } from './migration-gate.js';
-/** Construct migration authority. Only a host calls this. */
+import { isSqliteContentionError } from './sqlite-contention.js';
+/** Process-private registry of genuine, host-minted migration capabilities. */
+const MINTED_AUTHORITIES = new WeakSet();
+/** Mint migration authority. Only a host calls this; the result cannot be reconstructed by shape. */
 export function migrationAuthority(grantedBy) {
-    return { kind: 'axiom.migration-authority', grantedBy };
+    const principal = Object.freeze({
+        kind: 'axiom.migration-authority',
+        grantedBy: String(grantedBy),
+    });
+    MINTED_AUTHORITIES.add(principal);
+    return principal;
 }
+/** True only for the exact object `migrationAuthority()` returned — provenance, not duck typing. */
 export function isMigrationPrincipal(value) {
-    return (typeof value === 'object' &&
-        value !== null &&
-        value.kind === 'axiom.migration-authority' &&
-        typeof value.grantedBy === 'string');
+    return typeof value === 'object' && value !== null && MINTED_AUTHORITIES.has(value);
 }
 export async function executeMigration(options) {
     if (!isMigrationPrincipal(options.principal)) {
@@ -21,7 +27,28 @@ export async function executeMigration(options) {
         };
     }
     const requiredVersion = options.ir.schemaVersion ?? 1;
-    const record = await options.metadata.readSchema();
+    // `executeMigration` itself never holds the migration lease — `runMigration` does — so a
+    // SQLite lock this orchestrator hits is always another runner establishing/holding
+    // ownership (spec11.2 §6, §15). Reconcile it to a semantic outcome, never a leaked
+    // provider error.
+    let record;
+    try {
+        record = await options.metadata.readSchema();
+    }
+    catch (error) {
+        if (!isSqliteContentionError(error))
+            throw error;
+        const resolution = await classifyMigrationContention(options.metadata, requiredVersion, undefined, error);
+        if (resolution.kind === 'in-progress') {
+            return { ok: false, code: MIGRATION_DIAGNOSTIC_CODES.MIGRATION_IN_PROGRESS, message: resolution.message };
+        }
+        if (resolution.kind === 'failed') {
+            return { ok: false, code: MIGRATION_DIAGNOSTIC_CODES.MIGRATION_FAILED, message: resolution.message };
+        }
+        // already-at-target: a competing runner won the race. Re-read once — it succeeds now
+        // that the winner has released the writer lock — and fall through to the no-op path.
+        record = await options.metadata.readSchema();
+    }
     const fromVersion = options.fromVersion ?? record?.schemaVersion ?? 1;
     if (fromVersion === requiredVersion) {
         // Nothing to do — surface it as success with an empty plan.
@@ -56,9 +83,34 @@ export async function executeMigration(options) {
     return { ok: true, plan: planned.plan, run, gate };
 }
 export async function getMigrationStatus(metadata) {
-    const record = await metadata.readSchema();
-    const lock = await metadata.readLock();
-    const checkpoint = await metadata.readCheckpoint();
+    // Host inspection must stay usable during a concurrent migration — a consumer may not be
+    // required to catch SQLite-native errors to read migration state (spec11.2 §12, §32).
+    // After the store's own bounded busy handling, residual contention on the
+    // `_axiom_migration_*` tables means a migration is active, so a read that still contends
+    // is reported as a coherent in-progress status rather than a thrown provider error.
+    let contended = false;
+    const read = async (fn) => {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            if (isSqliteContentionError(error)) {
+                contended = true;
+                return null;
+            }
+            throw error;
+        }
+    };
+    const record = await read(() => metadata.readSchema());
+    const lock = await read(() => metadata.readLock());
+    const checkpoint = await read(() => metadata.readCheckpoint());
+    const phase = lock
+        ? 'in-progress'
+        : contended
+            ? 'in-progress'
+            : checkpoint
+                ? 'checkpointed'
+                : 'idle';
     return {
         schemaVersion: record?.schemaVersion ?? null,
         schemaFingerprint: record?.schemaFingerprint ?? null,
@@ -77,6 +129,6 @@ export async function getMigrationStatus(metadata) {
                 batchCursor: checkpoint.batchCursor,
             }
             : null,
-        phase: lock ? 'in-progress' : checkpoint ? 'checkpointed' : 'idle',
+        phase,
     };
 }

package/dist/migration-executor.d.ts

@@ -57,5 +57,29 @@ export type RunMigrationResult = {
     code: MigrationDiagnosticCode;
     message: string;
 };
+/**
+ * A physical SQLite lock is not a semantic result (spec11.2 §5, §15). When a metadata or
+ * row-store call raises {@link SqliteContentionError} during a migration, this re-reads the
+ * migration metadata and answers in Axiom terms:
+ *
+ * - the persisted schema is already at (or past) the target → the race is already won →
+ *   `already-at-target`;
+ * - a valid lease is held by *someone else* → `in-progress`;
+ * - this runner holds the lease and SQLite is still contended → an unrelated writer, not a
+ *   migration owner → `failed`, with the physical cause retained (spec11.2 §35);
+ * - the metadata itself cannot be observed → only migration runners contend those tables, so
+ *   without a lease of our own that means another migration is active → `in-progress`
+ *   (spec11.2 §8, §11).
+ */
+export type ContentionResolution = {
+    kind: 'already-at-target';
+} | {
+    kind: 'in-progress';
+    message: string;
+} | {
+    kind: 'failed';
+    message: string;
+};
+export declare function classifyMigrationContention(metadata: MigrationMetadataStore, targetVersion: number, ownToken: string | undefined, error: unknown): Promise<ContentionResolution>;
 export declare function runMigration(ir: ServerIR, plan: SemanticMigrationPlan, metadata: MigrationMetadataStore, target: MigrationRowStore | MigrationDataset, options: RunMigrationOptions): Promise<RunMigrationResult>;
 //# sourceMappingURL=migration-executor.d.ts.map