akm-cli 0.9.17-alpha.2 → 0.9.17-alpha.4

package/dist/storage/sqlite-migrations.js

@@ -0,0 +1,136 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import { withImmediateTransaction } from "./sqlite-transaction.js";
+/**
+ * Reject a `MIGRATIONS` array containing a duplicate `id`.
+ *
+ * A compiled-in registry can't diverge at runtime, so this is a dev-time
+ * invariant, not a per-open guard: each consumer (state.db, logs.db) calls it
+ * once on its own array at module load, and `tests/storage/sqlite-migrations.test.ts`
+ * pins the duplicate-detection behavior directly. {@link inspectMigrationLedger}
+ * does NOT call this — re-scanning the same compiled-in array on every DB open
+ * added no safety over the module-load check, only repeated O(n) cost.
+ */
+export function assertMigrationRegistry(migrations) {
+    const seen = new Set();
+    for (const migration of migrations) {
+        if (seen.has(migration.id))
+            throw new Error(`Migration registry contains duplicate ID ${migration.id}.`);
+        seen.add(migration.id);
+    }
+}
+export function migrationLedgerExists(db) {
+    return !!db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'schema_migrations'").get();
+}
+/** Inspect the database's applied IDs against the exact ordered registry prefix. */
+function inspectLedgerAgainst(db, registryIds) {
+    if (!migrationLedgerExists(db))
+        return { status: registryIds.length === 0 ? "current" : "old", migrationIds: [] };
+    const rows = db.prepare("SELECT id FROM schema_migrations ORDER BY rowid").all();
+    const migrationIds = rows.map((row) => row.id);
+    for (const [index, row] of rows.entries()) {
+        const expectedId = registryIds[index];
+        // Every id this binary knows matched in order and the ledger carries more:
+        // the database was migrated by a newer akm. Nothing here is applicable —
+        // this binary's whole registry is already applied — so this is version
+        // skew, not divergence.
+        if (!expectedId) {
+            return {
+                status: "newer",
+                migrationIds,
+                detail: `applied migration ID${rows.length - registryIds.length === 1 ? "" : "s"} ${migrationIds
+                    .slice(registryIds.length)
+                    .join(", ")} unknown to this akm`,
+            };
+        }
+        // A mismatch at a position this binary has a migration for is divergence,
+        // whether or not the id is one this binary knows later: this binary's
+        // migration at `index` was never applied, and something else was.
+        if (row.id !== expectedId) {
+            return {
+                status: "inconsistent",
+                migrationIds,
+                detail: `migration ledger is not an exact ordered prefix at position ${index + 1} (found '${row.id}', expected '${expectedId}'). ` +
+                    `Applied, in order: [${migrationIds.join(", ")}]. This akm's expected order: [${registryIds.join(", ")}].`,
+            };
+        }
+    }
+    return {
+        status: rows.length === registryIds.length ? "current" : "old",
+        migrationIds,
+    };
+}
+export function inspectMigrationLedger(db, migrations) {
+    return inspectLedgerAgainst(db, migrations.map((migration) => migration.id));
+}
+/**
+ * Reject only a ledger this binary cannot reason about at all.
+ *
+ * A `newer` ledger — an exact ordered prefix of this binary's registry plus
+ * migrations a later akm added — is NOT rejected. Two akm versions sharing one
+ * data directory is a supported deployment (a bundled CLI alongside a newer
+ * global install), and refusing the open bricked the older one for every
+ * command while protecting nothing: its entire registry is already applied, so
+ * it has no pending migration to run. Callers that want to tell an operator
+ * about the skew read {@link MigrationLedgerState.status}.
+ *
+ * An `inconsistent` ledger is different: this binary has a migration that was
+ * never applied and something else was applied in its place, so running the
+ * pending set could conflict with schema it cannot see. That still refuses.
+ */
+export function assertMigrationLedger(db, migrations) {
+    const state = inspectMigrationLedger(db, migrations);
+    if (state.status === "inconsistent") {
+        throw new Error(`Refusing a database whose migrations are not an exact ordered prefix: ${state.detail} ` +
+            "Applying this binary's missing migration now could run it against a schema a later migration already " +
+            "changed underneath it, which is a real risk of producing a wrong schema — not something akm can guess " +
+            "its way out of safely. This usually means the database was migrated by an incompatible akm build or " +
+            "fork, or schema_migrations was edited by hand. Restore this file from a backup taken before the " +
+            "divergence, or — if there is no backup and the data is not needed — delete it and let akm rebuild it " +
+            "from scratch (a derived index.db regenerates from your sources on the next 'akm index'; state.db loses " +
+            "durable history such as improve/proposal state and must be treated as a last resort).");
+    }
+    return state;
+}
+/** Create the migrations ledger table if it does not exist. */
+export function ensureMigrationsTable(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS schema_migrations (
+      id         TEXT    PRIMARY KEY,
+      applied_at TEXT    NOT NULL DEFAULT (datetime('now'))
+    );
+  `);
+}
+/** The registry entries not yet recorded in the ledger, in order. Throws on a divergent ledger. */
+export function pendingMigrations(db, migrations) {
+    return migrations.slice(assertMigrationLedger(db, migrations).migrationIds.length);
+}
+/**
+ * Apply every pending migration in one `BEGIN IMMEDIATE` transaction.
+ *
+ * A database with nothing pending is only read, never write-locked. Otherwise
+ * the write lock is taken up front — a second process bootstrapping the same
+ * database WAITS for the first to commit instead of racing it — and the
+ * pending set is re-read under that lock, so the process that lost the race
+ * finds nothing left to do rather than re-running DDL. Each migration's ledger
+ * row is inserted right after its SQL inside the same transaction: a failing
+ * migration rolls back every migration this call applied, and their ledger
+ * rows with them. Contention that outlasts every BEGIN retry surfaces as
+ * `TransientError("STATE_DB_CONTENDED")` (`../sqlite-transaction`). Returns the
+ * IDs this call applied, in order — empty when another process got there first.
+ */
+export function runMigrations(db, migrations) {
+    if (pendingMigrations(db, migrations).length === 0)
+        return [];
+    return withImmediateTransaction(db, () => {
+        ensureMigrationsTable(db);
+        const applied = [];
+        for (const migration of pendingMigrations(db, migrations)) {
+            db.exec(migration.up);
+            db.prepare("INSERT INTO schema_migrations (id) VALUES (?)").run(migration.id);
+            applied.push(migration.id);
+        }
+        return applied;
+    });
+}

package/dist/storage/sqlite-pragmas.js

@@ -95,17 +95,19 @@ export function isNetworkFilesystem(fsType) {
         return false;
     return NETWORK_FS_MAGICS.has(fsType);
 }
-/** Options for {@link applyStandardPragmas}. */
+/** How long a statement waits for a lock before failing with SQLITE_BUSY. */
+export const SQLITE_BUSY_TIMEOUT_MS = 30_000;
 /**
- * How long a statement waits for a lock before failing with SQLITE_BUSY.
- *
- * Exported so read-only openers can apply it too. They cannot run the rest of
- * the standard set (journal_mode and foreign_keys are write operations), but
- * the default of 0 makes reads fail INSTANTLY under writer contention — which
- * matters in the DELETE/TRUNCATE journal modes 0.9.1's network-filesystem
- * fallback and `AKM_SQLITE_JOURNAL_MODE` can select, where readers do block.
+ * The standard set for a READ-ONLY handle: just `busy_timeout`. A read-only
+ * connection cannot run the rest (journal_mode and foreign_keys are write
+ * operations), but SQLite's default timeout of 0 makes reads fail INSTANTLY
+ * under writer contention — which matters in the DELETE/TRUNCATE journal modes
+ * the network-filesystem fallback and `AKM_SQLITE_JOURNAL_MODE` can select,
+ * where readers do block.
  */
-export const SQLITE_BUSY_TIMEOUT_MS = 30_000;
+export function applyReadonlyPragmas(db) {
+    db.exec(`PRAGMA busy_timeout = ${SQLITE_BUSY_TIMEOUT_MS}`);
+}
 /**
  * Apply AKM's standard opening PRAGMAs to `db`, in order:
  *   1. `journal_mode` = the configured mode (with WAL→DELETE network-FS fallback)

package/dist/storage/sqlite-transaction.js

@@ -0,0 +1,170 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * `BEGIN IMMEDIATE` transactions and the one SQLite contention classifier.
+ *
+ * `db.transaction()` is DEFERRED by default on both Bun and better-sqlite3,
+ * which means two writers can both perform stale preflight reads and only race
+ * when they finally attempt the write. Proposal creation, queue mutation and
+ * schema migration need the write lock BEFORE those reads so concurrent
+ * processes serialize on the live state rather than clobbering each other.
+ *
+ * Every open already carries a 30 s `busy_timeout` (`sqlite-pragmas.ts`), so a
+ * single blocked statement waits before failing. {@link beginImmediateTransaction}
+ * additionally retries `BEGIN IMMEDIATE` itself ({@link WITH_IMMEDIATE_TX_MAX_ATTEMPTS}
+ * attempts) for the rarer case of two writers racing the BEGIN statement
+ * back-to-back. If every attempt is still contention-shaped
+ * ({@link isSqliteContentionError} — SQLITE_BUSY/LOCKED, the matching message
+ * text, or the phantom-BEGIN marker), the exhaustion throw is reclassified
+ * into `TransientError("STATE_DB_CONTENDED")` (exit 75, #948 addendum) instead
+ * of surfacing the raw driver text: another akm process (an unrelated
+ * `improve`, `workflow run`, or task run — not necessarily contending for the
+ * same row) is writing the database right now. A genuinely unrelated error
+ * (real corruption, a body-thrown failure) is never reclassified and rethrows
+ * exactly as raised.
+ *
+ * This is the single place SQLITE_BUSY/LOCKED becomes exit 75 for state.db:
+ * `openStateDatabase`'s migration transaction, every repository write and the
+ * shared migration runner (`engines/sqlite-migrations.ts`) all go through it.
+ * `core/state-db.ts` re-exports these helpers for its callers.
+ *
+ * @module storage/sqlite-transaction
+ */
+import { TransientError } from "../core/errors.js";
+import { sleepSync } from "../runtime.js";
+/**
+ * Whether `err` is one of the SQLite conditions a concurrent-writer race can
+ * throw that are transient — the statement did NOT corrupt anything, another
+ * writer just holds the lock right now — and therefore safe to retry or
+ * reclassify as ordinary contention rather than a genuine failure:
+ *   - `SQLITE_BUSY` / `SQLITE_LOCKED` (either driver's `.code`).
+ *   - "database is locked" / "database table is locked" message text.
+ *   - the phantom-BEGIN marker synthesized below when `BEGIN IMMEDIATE`
+ *     returns without actually opening a transaction.
+ *
+ * This is the single shared classifier for "is this ordinary contention"
+ * (#948): `reclassifyIndexDbContention` (indexer) and the workflow-runs
+ * repository's lease-contention classifier (which additionally matches a
+ * couple of corruption-shaped texts specific to its own narrower cross-process
+ * race and keeps its own live-lease confirmation before reclassifying) both
+ * delegate to it. Matching this set alone is never sufficient to declare
+ * something DEFINITELY contention when a caller needs corroborating evidence
+ * (see the lease path); for `beginImmediateTransaction`'s own exhaustion case
+ * there is no such evidence available, so the five 30 s `busy_timeout` waits
+ * already spent stand as the evidence instead.
+ */
+export function isSqliteContentionError(err) {
+    const code = err?.code;
+    if (code === "SQLITE_BUSY" || code === "SQLITE_LOCKED")
+        return true;
+    const msg = (err instanceof Error ? err.message : String(err)).toLowerCase();
+    return (msg.includes("database is locked") ||
+        msg.includes("database table is locked") ||
+        // Phantom BEGIN (see below) — synthesized when BEGIN IMMEDIATE returns
+        // without opening a transaction. Safe to retry: fn() has not run.
+        msg.includes("did not open a transaction"));
+}
+const WITH_IMMEDIATE_TX_MAX_ATTEMPTS = 5;
+/**
+ * Reclassify an exhausted-retry BEGIN failure that is still contention-shaped
+ * (#948) into a `TransientError("STATE_DB_CONTENDED")`, the same class as a
+ * held workflow run lock (`RUN_LEASE_HELD`): the driver text is accurate but unhelpful (`{"ok":false,"error":"database is
+ * locked"}`, exit 70/INTERNAL) — this instead reads as a retryable-shortly
+ * signal (exit 75, sysexits EX_TEMPFAIL) with the original error preserved as
+ * `cause` for `--verbose`/debugging. A genuinely unrelated error (not
+ * contention-shaped) is rethrown exactly as raised, never reclassified.
+ */
+function throwBeginFailure(err) {
+    if (isSqliteContentionError(err)) {
+        const contended = new TransientError("akm's state database is busy (another akm process is writing it); retry shortly.", "STATE_DB_CONTENDED");
+        contended.cause = err;
+        throw contended;
+    }
+    throw err;
+}
+/**
+ * Open, but deliberately do not finish, an immediate transaction.
+ *
+ * This is the split-phase counterpart to {@link withImmediateTransaction} for
+ * the source-update coordinator: index finalization must mutate state.db in a
+ * transaction that remains pending until content, lockfile, and index
+ * publication have all succeeded. The caller that asked for this split phase
+ * owns the matching COMMIT/ROLLBACK.
+ *
+ * Only a contention-shaped BEGIN failure is retried. "cannot start a
+ * transaction within a transaction" is deliberately NOT: it means a
+ * transaction is already open on this connection (a re-entrant call — handled
+ * by the entry guard in {@link withImmediateTransaction}), and "retrying" it
+ * with a ROLLBACK would destroy the caller's transaction (issue #686).
+ */
+export function beginImmediateTransaction(db) {
+    if (db.inTransaction) {
+        throw new Error("beginImmediateTransaction requires a connection with no active transaction");
+    }
+    let lastBeginErr;
+    for (let attempt = 1; attempt <= WITH_IMMEDIATE_TX_MAX_ATTEMPTS; attempt++) {
+        try {
+            db.exec("BEGIN IMMEDIATE");
+            if (!db.inTransaction) {
+                throw new Error("BEGIN IMMEDIATE did not open a transaction (phantom contention state)");
+            }
+            return;
+        }
+        catch (err) {
+            lastBeginErr = err;
+            if (isSqliteContentionError(err) && attempt < WITH_IMMEDIATE_TX_MAX_ATTEMPTS) {
+                if (db.inTransaction) {
+                    try {
+                        db.exec("ROLLBACK");
+                    }
+                    catch {
+                        // Transaction already gone — safe to retry BEGIN.
+                    }
+                }
+                sleepSync(2 ** (attempt - 1));
+                continue;
+            }
+            throwBeginFailure(err);
+        }
+    }
+    throwBeginFailure(lastBeginErr);
+}
+/** Run `fn` inside a `BEGIN IMMEDIATE` transaction, joining one that is already open on `db`. */
+export function withImmediateTransaction(db, fn) {
+    // Re-entrancy guard (issue #686): if a transaction is already open on this
+    // connection (e.g. a nested withImmediateTransaction call inside an outer
+    // frame's fn), join it — run fn directly with no BEGIN/COMMIT/ROLLBACK of
+    // our own. Without this, the nested BEGIN throws "cannot start a transaction
+    // within a transaction", which the old retry path answered with an
+    // unconditional ROLLBACK — destroying the OUTER transaction and leaving its
+    // COMMIT to fail with "cannot commit - no transaction is active".
+    if (db.inTransaction) {
+        return fn();
+    }
+    beginImmediateTransaction(db);
+    try {
+        const result = fn();
+        if (!db.inTransaction) {
+            // The transaction we opened vanished while fn() ran (e.g. an
+            // auto-rollback or a stray ROLLBACK inside fn). fn's writes may have
+            // escaped serialization, so retrying is unsafe — fail loudly instead of
+            // letting COMMIT throw the opaque "cannot commit - no transaction is
+            // active" SQLiteError.
+            throw new Error("withImmediateTransaction invariant violated: transaction opened by BEGIN IMMEDIATE was no longer active after the transaction body ran; refusing to COMMIT (writes may have escaped serialization)");
+        }
+        db.exec("COMMIT");
+        return result;
+    }
+    catch (err) {
+        if (db.inTransaction) {
+            try {
+                db.exec("ROLLBACK");
+            }
+            catch {
+                // Ignore rollback failures so the original error is preserved.
+            }
+        }
+        throw err;
+    }
+}

package/dist/storage/state-db-integrity.js

@@ -2,42 +2,49 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
- * state.db integrity + reclaimable-space probes (R0, tier0-0917).
+ * state.db integrity + reclaimable-space probes (R0), and the VACUUM pass
+ * state.db and index.db share.
  *
  * `akm health`'s `state-db-integrity` check (src/commands/health/checks.ts)
  * is a pure projection like every other check, so the actual IO lives here:
  * a read-only `PRAGMA quick_check` and a read-only freelist/page-count read.
- * Both open their own short-lived connection via the plain {@link openDatabase}
- * opener — deliberately bypassing `openStateDatabase`'s managed-open/migration
- * machinery (src/core/state-db.ts), since a corrupt database must not need a
- * clean migration-ledger read just to report itself as corrupt.
+ * Both open their own short-lived read-only connection via the plain
+ * {@link openDatabase} opener rather than `openStateDatabase`
+ * (src/core/state-db.ts), since a corrupt database must not need a clean
+ * migration-ledger read, let alone a migration, just to report itself as
+ * corrupt.
  *
- * {@link vacuumStateDbIfReclaimable} is the post-purge VACUUM step: given an
- * already-open read-write connection (VACUUM cannot run inside a transaction,
- * and a read-only handle cannot run it at all) and a freelist reading, it
- * VACUUMs only when the freelist ratio crosses {@link STATE_DB_FREELIST_WARN_RATIO}
- * and never throws — a locked/busy database is reported, not raised.
+ * {@link vacuumIfReclaimable} is the VACUUM step: given an already-open
+ * read-write connection (VACUUM cannot run inside a transaction, and a
+ * read-only handle cannot run it at all) and a freelist reading, it VACUUMs
+ * when asked to or when the freelist ratio crosses
+ * {@link STATE_DB_FREELIST_WARN_RATIO}, and never throws — a locked/busy
+ * database is reported, not raised. improve's post-purge pass runs it on
+ * state.db, and `akm index` on index.db.
  *
  * @module storage/state-db-integrity
  */
 import { appendEvent } from "../core/events.js";
 import { openDatabase } from "./database.js";
-import { SQLITE_BUSY_TIMEOUT_MS } from "./sqlite-pragmas.js";
+import { applyReadonlyPragmas } from "./sqlite-pragmas.js";
 /** How many corruption errors `PRAGMA quick_check` collects before it stops scanning and returns. */
 const QUICK_CHECK_ERROR_LIMIT = 10;
-/** Above this fraction of free pages, `state-db-integrity` warns and a post-purge pass VACUUMs. */
+/**
+ * Above this fraction of free pages, `state-db-integrity` warns, and
+ * {@link vacuumIfReclaimable} compacts state.db (after improve's retention
+ * purge) or index.db (at the end of `akm index`).
+ */
 export const STATE_DB_FREELIST_WARN_RATIO = 0.5;
-/** Event appended by {@link vacuumStateDbIfReclaimable} after a successful VACUUM. */
+/** Event appended by {@link vacuumIfReclaimable} after a successful VACUUM of state.db. */
 export const STATE_DB_VACUUMED_EVENT = "state_db_vacuumed";
+/** Event appended by {@link vacuumIfReclaimable} after a successful VACUUM of index.db. */
+export const INDEX_DB_VACUUMED_EVENT = "index_db_vacuumed";
 function firstColumn(row) {
     return row === undefined ? undefined : Object.values(row)[0];
 }
 function openReadonlyStateDb(dbPath) {
     const db = openDatabase(dbPath, { readonly: true, create: false });
-    // Read-only handles cannot run journal_mode/foreign_keys (write operations),
-    // but busy_timeout is legal — see openReadonlyExistingDatabase's identical
-    // rationale in src/storage/repositories/index-connection.ts.
-    db.exec(`PRAGMA busy_timeout = ${SQLITE_BUSY_TIMEOUT_MS}`);
+    applyReadonlyPragmas(db);
     return db;
 }
 /**
@@ -89,21 +96,21 @@ export function getStateDbFreelistInfo(dbPath) {
     }
 }
 /**
- * VACUUM `db` when `freelist.ratio` exceeds {@link STATE_DB_FREELIST_WARN_RATIO},
- * appending a {@link STATE_DB_VACUUMED_EVENT} recording pages before/after.
- * Intended to run immediately after the retention purge, on the same
- * read-write connection the purge just used. Never throws: a locked/busy
- * database (another writer holds the file right now) is reported via
- * `reason: "busy"` rather than raised, since this is opportunistic
- * maintenance and must not fail the purge pass it follows.
+ * VACUUM `db` when `vacuum.force` is set or `freelist.ratio` exceeds
+ * {@link STATE_DB_FREELIST_WARN_RATIO}, appending `vacuum.eventType` with
+ * the pages before/after. Runs on the caller's read-write connection — for
+ * state.db right after the retention purge, for index.db at the end of an
+ * index run. Never throws: a locked/busy database (another writer holds the
+ * file right now) is reported via `reason: "busy"` rather than raised, since
+ * this is opportunistic maintenance and must not fail the pass it follows.
  *
  * The event is appended via `appendEvent` (not a direct `insertEvent` on
  * `db`) so it honors the caller's `EventsContext` — `readOnly` suppresses
  * the write and an injected `now` is used for `ts` — the same as every
  * other event `runRetentionPurgePass` appends in this callback.
  */
-export function vacuumStateDbIfReclaimable(db, freelist, eventsCtx) {
-    if (freelist.ratio <= STATE_DB_FREELIST_WARN_RATIO) {
+export function vacuumIfReclaimable(db, freelist, vacuum, eventsCtx) {
+    if (!vacuum.force && freelist.ratio <= STATE_DB_FREELIST_WARN_RATIO) {
         return { ran: false, reason: "below-threshold", pagesBefore: freelist.pageCount };
     }
     try {
@@ -116,7 +123,7 @@ export function vacuumStateDbIfReclaimable(db, freelist, eventsCtx) {
     }
     const pagesAfter = Number(firstColumn(db.prepare("PRAGMA page_count").get()) ?? 0);
     appendEvent({
-        eventType: STATE_DB_VACUUMED_EVENT,
+        eventType: vacuum.eventType,
         metadata: { pagesBefore: freelist.pageCount, pagesAfter, freelistRatioBefore: freelist.ratio },
     }, eventsCtx);
     return { ran: true, pagesBefore: freelist.pageCount, pagesAfter };