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

package/README.md

@@ -41,7 +41,9 @@ This package also owns the parts of an application that only the authority can r
 - **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. See
+  `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`,

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

@@ -10,7 +10,7 @@
     "contract": "axiom.server.v7",
     "id": "migration-conformance",
     "name": "Migration Conformance",
-    "version": "0.11.1-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.1-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.1-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.1-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.1-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.1-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.1-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.1-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.1-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.1-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.1-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.1-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.1-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.1-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.1-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.1-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.1-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.js

@@ -1,7 +1,8 @@
 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';
+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. */
@@ -26,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.
@@ -61,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,
@@ -82,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

package/dist/migration-executor.js

@@ -1,6 +1,7 @@
 import { MigrationTransformError, evaluateMigrationExpression, migrationRowScope, } from './migration-eval.js';
 import { MIGRATION_DIAGNOSTIC_CODES } from './migration.js';
 import { createMemoryRowStore } from './migration-row-store.js';
+import { SqliteContentionError, isSqliteContentionError } from './sqlite-contention.js';
 export { createMemoryRowStore } from './migration-row-store.js';
 /** Thrown when `crashAfter` fires. The checkpoint is already durable; resume is a re-run. */
 export class MigrationCrash extends Error {
@@ -95,6 +96,42 @@ async function applySchemaOperation(store, operation) {
         default:
     }
 }
+export async function classifyMigrationContention(metadata, targetVersion, ownToken, error) {
+    const cause = error instanceof SqliteContentionError ? error.providerCause : 'sqlite: database is locked';
+    try {
+        const record = await metadata.readSchema();
+        if (record && record.schemaVersion >= targetVersion) {
+            return { kind: 'already-at-target' };
+        }
+        const lock = await metadata.readLock();
+        if (lock && lock.token !== ownToken) {
+            return { kind: 'in-progress', message: `a migration is already running, held by ${lock.holder}` };
+        }
+        if (ownToken !== undefined) {
+            return {
+                kind: 'failed',
+                message: `SQLite remained locked while this runner held the migration lease (${cause})`,
+            };
+        }
+        return lock
+            ? { kind: 'in-progress', message: `a migration is already running, held by ${lock.holder}` }
+            : { kind: 'failed', message: `unresolved SQLite lock contention with no migration owner (${cause})` };
+    }
+    catch (reReadError) {
+        if (isSqliteContentionError(reReadError)) {
+            return ownToken !== undefined
+                ? {
+                    kind: 'failed',
+                    message: `SQLite remained locked while this runner held the migration lease (${cause})`,
+                }
+                : {
+                    kind: 'in-progress',
+                    message: 'another migration appears to be running (migration metadata is locked)',
+                };
+        }
+        throw reReadError;
+    }
+}
 export async function runMigration(ir, plan, metadata, target, options) {
     const store = 'readBatch' in target ? target : createMemoryRowStore(target);
     const now = options.now ?? (() => Date.now());
@@ -102,42 +139,78 @@ export async function runMigration(ir, plan, metadata, target, options) {
     const batchSize = Math.max(1, options.batchSize ?? 500);
     const approved = new Set(options.approveDestructive ?? []);
     const id = planId(plan);
-    // --- Idempotency & compatibility, before any lock or write (spec11 §35) --------------
-    const current = await metadata.readSchema();
-    if (current && current.schemaVersion === plan.toVersion) {
-        return { ok: true, phase: 'completed', rowsTransformed: 0, resumed: false, alreadyAtTarget: true };
-    }
-    if (current && current.schemaVersion !== plan.fromVersion) {
-        return {
-            ok: false,
-            phase: 'failed',
-            code: MIGRATION_DIAGNOSTIC_CODES.SCHEMA_INCOMPATIBLE,
-            message: `persisted schema ${current.schemaVersion} is not the plan's origin ${plan.fromVersion}`,
-        };
-    }
-    // --- Destructive approval, before any lock or write (spec11 §21, §106) ---------------
-    const unapproved = plan.destructive.filter((change) => !approved.has(change.operationId));
-    if (unapproved.length > 0) {
-        return {
-            ok: false,
-            phase: 'failed',
-            code: MIGRATION_DIAGNOSTIC_CODES.MIGRATION_APPROVAL_REQUIRED,
-            message: `destructive operations not approved: ${unapproved.map((change) => change.operationId).join(', ')}`,
-        };
-    }
-    // --- Take the migration lock (spec11 §66) -----------------------------------------
-    const lockResult = await metadata.acquireLock(options.holder, leaseMs);
-    if (!lockResult.ok || !lockResult.lock) {
+    // A physical SQLite lock this runner cannot wait out is reconciled to an Axiom outcome
+    // (spec11.2 §5, §15). `token` is `undefined` until this runner owns the lease, which is
+    // what lets `classifyMigrationContention` tell "someone else is migrating" from
+    // "I own the lease and an unrelated writer is blocking me".
+    let token;
+    const onContention = async (error) => {
+        const resolution = await classifyMigrationContention(metadata, plan.toVersion, token, error);
+        if (resolution.kind === 'already-at-target') {
+            return { ok: true, phase: 'completed', rowsTransformed: 0, resumed: false, alreadyAtTarget: true };
+        }
         return {
             ok: false,
             phase: 'failed',
-            code: MIGRATION_DIAGNOSTIC_CODES.MIGRATION_IN_PROGRESS,
-            message: `a migration is already running, held by ${lockResult.heldBy?.holder ?? 'another instance'}`,
+            code: resolution.kind === 'in-progress'
+                ? MIGRATION_DIAGNOSTIC_CODES.MIGRATION_IN_PROGRESS
+                : MIGRATION_DIAGNOSTIC_CODES.MIGRATION_FAILED,
+            message: resolution.message,
         };
-    }
-    const token = lockResult.lock.token;
-    const operations = plan.steps.flatMap((step) => step.operations);
+    };
     try {
+        // --- Idempotency & compatibility, before any lock or write (spec11 §35) ------------
+        const current = await metadata.readSchema();
+        if (current && current.schemaVersion === plan.toVersion) {
+            return { ok: true, phase: 'completed', rowsTransformed: 0, resumed: false, alreadyAtTarget: true };
+        }
+        if (current && current.schemaVersion !== plan.fromVersion) {
+            return {
+                ok: false,
+                phase: 'failed',
+                code: MIGRATION_DIAGNOSTIC_CODES.SCHEMA_INCOMPATIBLE,
+                message: `persisted schema ${current.schemaVersion} is not the plan's origin ${plan.fromVersion}`,
+            };
+        }
+        // --- Destructive approval, before any lock or write (spec11 §21, §106) -------------
+        const unapproved = plan.destructive.filter((change) => !approved.has(change.operationId));
+        if (unapproved.length > 0) {
+            return {
+                ok: false,
+                phase: 'failed',
+                code: MIGRATION_DIAGNOSTIC_CODES.MIGRATION_APPROVAL_REQUIRED,
+                message: `destructive operations not approved: ${unapproved.map((change) => change.operationId).join(', ')}`,
+            };
+        }
+        // --- Take the migration lock (spec11 §66) ---------------------------------------
+        const lockResult = await metadata.acquireLock(options.holder, leaseMs);
+        if (!lockResult.ok || !lockResult.lock) {
+            return {
+                ok: false,
+                phase: 'failed',
+                code: MIGRATION_DIAGNOSTIC_CODES.MIGRATION_IN_PROGRESS,
+                message: `a migration is already running, held by ${lockResult.heldBy?.holder ?? 'another instance'}`,
+            };
+        }
+        token = lockResult.lock.token;
+        const operations = plan.steps.flatMap((step) => step.operations);
+        // Re-check the persisted version *under the lock*. A competing runner can complete the
+        // whole transition — commit `toVersion` and release its lease — between this runner's
+        // pre-lock read and its acquisition. Without this check that runner would re-run a
+        // non-idempotent transform on already-migrated rows (spec11.2 §17, §19). The lock is
+        // what makes "check the version, then transform" atomic across processes.
+        const afterLock = await metadata.readSchema();
+        if (afterLock && afterLock.schemaVersion === plan.toVersion) {
+            return { ok: true, phase: 'completed', rowsTransformed: 0, resumed: false, alreadyAtTarget: true };
+        }
+        if (afterLock && afterLock.schemaVersion !== plan.fromVersion) {
+            return {
+                ok: false,
+                phase: 'failed',
+                code: MIGRATION_DIAGNOSTIC_CODES.SCHEMA_INCOMPATIBLE,
+                message: `persisted schema ${afterLock.schemaVersion} is not the plan's origin ${plan.fromVersion}`,
+            };
+        }
         const checkpoint = await metadata.readCheckpoint();
         if (checkpoint && checkpoint.planId !== id) {
             return {
@@ -278,6 +351,11 @@ export async function runMigration(ir, plan, metadata, target, options) {
                 message: error.message,
             };
         }
+        if (isSqliteContentionError(error)) {
+            // Ordinary cross-process SQLite contention resolves to an Axiom outcome, never a
+            // leaked provider error (spec11.2 §5, §29).
+            return onContention(error);
+        }
         return {
             ok: false,
             phase: 'failed',
@@ -286,6 +364,16 @@ export async function runMigration(ir, plan, metadata, target, options) {
         };
     }
     finally {
-        await metadata.releaseLock(token);
+        if (token !== undefined) {
+            // Best-effort lease release. If SQLite is still contended here the lease simply
+            // expires on its own (spec11.2 §16); nothing else may mask the real result.
+            try {
+                await metadata.releaseLock(token);
+            }
+            catch (releaseError) {
+                if (!isSqliteContentionError(releaseError))
+                    throw releaseError;
+            }
+        }
     }
 }

package/dist/migration-gate.js

@@ -1,5 +1,6 @@
 import { migrationPath } from './deps.js';
 import { MIGRATION_DIAGNOSTIC_CODES } from './migration.js';
+import { isSqliteContentionError } from './sqlite-contention.js';
 /** Every gate status, for enumeration in tests. */
 export const SCHEMA_GATE_STATUSES = [
     'compatible',
@@ -27,17 +28,39 @@ export async function evaluateSchemaGate(ir, metadata, context = {}) {
     const requiredVersion = ir.schemaVersion ?? 1;
     const requiredFingerprint = ir.schemaFingerprint ?? '';
     const identity = declaresSchemaIdentity(ir);
-    const lock = await metadata.readLock();
+    // Ordinary cross-process contention on the migration-metadata tables means another
+    // migration runner is active (nothing else touches `_axiom_migration_*`). After the
+    // store's own bounded busy handling, a residual contention error is reported as
+    // `migration-in-progress` — a coherent Axiom verdict that also preserves the 0.11.1
+    // fail-closed startup (the authority does not start) (spec11.2 §11, §13, §33).
+    const inProgress = (holder) => ({
+        status: 'migration-in-progress',
+        code: MIGRATION_DIAGNOSTIC_CODES.MIGRATION_IN_PROGRESS,
+        message: `a migration is running${holder ? `, held by ${holder}` : ''}; the authority will not start until it completes`,
+        requiredVersion,
+        persistedVersion: null,
+    });
+    let lock;
+    try {
+        lock = await metadata.readLock();
+    }
+    catch (error) {
+        if (isSqliteContentionError(error))
+            return inProgress('another instance');
+        throw error;
+    }
     if (lock) {
-        return {
-            status: 'migration-in-progress',
-            code: MIGRATION_DIAGNOSTIC_CODES.MIGRATION_IN_PROGRESS,
-            message: `a migration is running, held by ${lock.holder}; the authority will not start until it completes`,
-            requiredVersion,
-            persistedVersion: null,
-        };
+        return inProgress(lock.holder);
+    }
+    let record;
+    try {
+        record = await metadata.readSchema();
+    }
+    catch (error) {
+        if (isSqliteContentionError(error))
+            return inProgress('another instance');
+        throw error;
     }
-    const record = await metadata.readSchema();
     // --- The graph declares no semantic schema identity ---------------------------------
     if (!identity) {
         if (record !== null && record.schemaVersion > 1) {

package/dist/server.js

@@ -14,6 +14,7 @@ import { diffRows, identityValuesToLoad, providerEntitiesWritten, rewriteForStag
 import { cursorMatchesContext, fingerprint, openCursor, randomCursorSecret, sealCursor, } from './query-cursor.js';
 import { MIGRATION_DIAGNOSTIC_CODES } from './migration.js';
 import { evaluateSchemaGate, gateAllowsStart, schemaGateWithoutStore } from './migration-gate.js';
+import { isSqliteContentionError } from './sqlite-contention.js';
 import { getMigrationStatus } from './migration-execute.js';
 /**
  * Diagnostic codes the authority adds to the runtime vocabulary. They describe failures of
@@ -1325,7 +1326,21 @@ export function createAxiomServer(options) {
                     // While a migration is running, authoritative traffic is refused rather than
                     // applied to data that is mid-transition (spec11 §68, spec11.1 §12). 0.11 has no
                     // online migration; a host that wants zero-downtime must sequence it itself.
-                    if (await migrationMetadata.readLock()) {
+                    //
+                    // A residual SQLite contention error here (after the store's bounded busy
+                    // handling) means another process is holding/establishing migration ownership on
+                    // the shared database — a request-time race with a migrator resolves to
+                    // `MIGRATION_IN_PROGRESS`, never a leaked provider error (spec11.2 §34).
+                    let migrationLockHeld;
+                    try {
+                        migrationLockHeld = (await migrationMetadata.readLock()) !== null;
+                    }
+                    catch (error) {
+                        if (!isSqliteContentionError(error))
+                            throw error;
+                        migrationLockHeld = true;
+                    }
+                    if (migrationLockHeld) {
                         migrationLockSeen = true;
                         return {
                             kind: 'error',
@@ -1339,16 +1354,28 @@ export function createAxiomServer(options) {
                         // A migration that ran under this process has just finished. Either the schema
                         // still matches this build — invalidate the (now possibly stale) query cache
                         // (spec11 §45) — or it moved past this build and this authority must stop
-                        // serving until it is redeployed (spec11 §103).
-                        migrationLockSeen = false;
-                        const record = await migrationMetadata.readSchema();
-                        if (record &&
-                            (record.schemaVersion !== (ir.schemaVersion ?? 1) ||
-                                record.schemaFingerprint !== (ir.schemaFingerprint ?? ''))) {
-                            schemaOutdated = true;
+                        // serving until it is redeployed (spec11 §103). If the post-migration schema
+                        // read still contends, defer the decision to the next request rather than
+                        // leaking the error.
+                        let record;
+                        try {
+                            record = await migrationMetadata.readSchema();
+                        }
+                        catch (error) {
+                            if (!isSqliteContentionError(error))
+                                throw error;
+                            record = undefined;
                         }
-                        else {
-                            invalidateQueryCache();
+                        if (record !== undefined) {
+                            migrationLockSeen = false;
+                            if (record &&
+                                (record.schemaVersion !== (ir.schemaVersion ?? 1) ||
+                                    record.schemaFingerprint !== (ir.schemaFingerprint ?? ''))) {
+                                schemaOutdated = true;
+                            }
+                            else {
+                                invalidateQueryCache();
+                            }
                         }
                     }
                     if (schemaOutdated) {