akm-cli 0.9.1 → 0.9.2-alpha.2

package/dist/storage/managed-db.js

@@ -4,8 +4,8 @@
 /**
  * Managed-database seam — the single home for the SQLite open/lifecycle recipe.
  *
- * Before this module, two idioms were copy-pasted across state.db / logs.db /
- * workflow.db / index.db and their consumers:
+ * Two lifecycle steps are shared across the current managed databases
+ * (`state.db`, `logs.db`, and `index.db`) and their consumers:
  *
  *   1. The open recipe: `mkdir(dir) → openDatabase(path) → applyStandardPragmas
  *      → migrate`.
@@ -52,9 +52,31 @@ export function openManagedDatabase(spec) {
         fs.mkdirSync(dir, { recursive: true });
     }
     const db = spec.create === false ? openDatabase(spec.path, { create: false }) : openDatabase(spec.path);
-    applyStandardPragmas(db, spec.pragmas ?? { dataDir: dir });
-    spec.init?.(db);
-    return db;
+    try {
+        applyStandardPragmas(db, spec.pragmas ?? { dataDir: dir });
+        spec.init?.(db);
+        return db;
+    }
+    catch (error) {
+        // Initializers may open a transaction (source update does so before index
+        // schema work). Never strand that transaction/handle when later setup
+        // fails; closing rolls it back and releases its writer lock.
+        if (db.inTransaction) {
+            try {
+                db.exec("ROLLBACK");
+            }
+            catch {
+                // Closing remains the final rollback backstop.
+            }
+        }
+        try {
+            db.close();
+        }
+        catch {
+            // Preserve the initializer failure, which identifies the real boundary.
+        }
+        throw error;
+    }
 }
 /**
  * Run `fn` against a managed database, owning its lifecycle.
@@ -80,22 +102,3 @@ export function withManagedDb(open, fn, opts) {
         db.close();
     }
 }
-/**
- * Async sibling of {@link withManagedDb}. Use this — NOT `withManagedDb` — when
- * `fn` holds the handle across an `await`: the sync version closes in its
- * `finally` before the awaited work resolves (use-after-close). Here the handle
- * is closed only after `fn`'s promise settles. Borrowed handles pass straight
- * through and are not closed, as in the sync version.
- */
-export async function withManagedDbAsync(open, fn, opts) {
-    if (opts?.borrowed) {
-        return fn(opts.borrowed);
-    }
-    const db = open();
-    try {
-        return await fn(db);
-    }
-    finally {
-        db.close();
-    }
-}

package/dist/storage/repositories/events-repository.js

@@ -1,6 +1,7 @@
 // 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 { isReadOnlyFilesystemError } from "../../core/system-error.js";
 import { error } from "../../core/warn.js";
 /**
  * Convert a raw `EventRow` from the database to the public `EventEnvelope`
@@ -41,6 +42,8 @@ export function insertEvent(db, input) {
         return insertEventStrict(db, input);
     }
     catch (err) {
+        if (isReadOnlyFilesystemError(err))
+            return undefined;
         const message = err instanceof Error ? err.message : String(err);
         error(`akm: state.db event insert failed (${message})`);
         return undefined;

package/dist/storage/repositories/index-connection.js

@@ -17,6 +17,8 @@ import { getDbPath } from "../../core/paths.js";
 import { openDatabase } from "../database.js";
 import { openManagedDatabase } from "../managed-db.js";
 import { SQLITE_BUSY_TIMEOUT_MS } from "../sqlite-pragmas.js";
+import { openSqliteReadSnapshot } from "../sqlite-read-snapshot.js";
+import { isCanonicalIndexGeneration } from "./index-entry-schema.js";
 import { ensureSchema } from "./index-schema.js";
 import { loadVecExtension, warnIfVecMissing } from "./index-vec-repository.js";
 export function openIndexDatabase(dbPath, options) {
@@ -25,6 +27,10 @@ export function openIndexDatabase(dbPath, options) {
         init: (db) => {
             // Try to load sqlite-vec extension
             loadVecExtension(db);
+            // Source update uses this narrow lifecycle seam to ATTACH state.db and
+            // open its coordinator-owned outer transaction before ensureSchema or
+            // any indexer write can mutate the live generation.
+            options?.beforeSchema?.(db);
             // Dim resolution: explicit option wins; otherwise consult the on-disk
             // config so unparameterised opens (registry providers, graph helpers,
             // ad-hoc CLI subcommands) honour the operator-declared dimension. Only if
@@ -61,9 +67,10 @@ function resolveConfiguredEmbeddingDim() {
     }
 }
 export function openExistingDatabase(dbPath) {
-    // Existing-DB callers must not mutate schema or embedding metadata on open,
-    // but some paths still need write access to usage_events and other tables —
-    // so init only loads the vec extension, it does not run ensureSchema.
+    // Existing-DB callers do not mutate schema or embedding metadata on open.
+    // They do validate the exact current derived generation before returning a
+    // handle, so no current reader can accidentally serve a populated legacy
+    // table and fail later on its first canonical-column query.
     //
     // "Existing" is load-bearing: a missing file throws instead of being
     // created. Create-on-open used to leave a schema-less index.db behind (a
@@ -77,7 +84,19 @@ export function openExistingDatabase(dbPath) {
     if (classifyPathAccess(resolvedPath).access === "absent") {
         throw new Error(`Index database not found at ${resolvedPath}. Run 'akm index' to build it.`);
     }
-    return openManagedDatabase({ path: resolvedPath, init: loadVecExtension, create: false });
+    return openManagedDatabase({
+        path: resolvedPath,
+        init: (db) => {
+            loadVecExtension(db);
+            assertCanonicalIndexGeneration(db, resolvedPath);
+        },
+        create: false,
+    });
+}
+function assertCanonicalIndexGeneration(db, resolvedPath) {
+    if (isCanonicalIndexGeneration(db))
+        return;
+    throw new ConfigError(`Index database uses an incompatible derived schema: ${resolvedPath}.`, "INDEX_SCHEMA_INCOMPATIBLE");
 }
 /**
  * Refuse to treat an UNREADABLE index as a missing one (#791).
@@ -100,17 +119,23 @@ export function assertIndexPathReadable(resolvedPath) {
     throw new ConfigError(`Index database exists but is not readable: ${describeInaccessiblePath(resolvedPath, code)}.`, "DATA_DIR_UNREADABLE");
 }
 /**
- * Open an existing index for queries without creating directories, a database
- * file, journals, or running write-capable pragmas/schema initialization.
+ * Open an existing index for queries without changing the source database or
+ * running schema initialization. The default path attaches read-only to the
+ * source. `isolatedSnapshot` instead opens a disposable main/WAL copy so even
+ * SQLite's read-lock bookkeeping cannot touch the source SHM file.
  */
-export function openReadonlyExistingDatabase(dbPath) {
+export function openReadonlyExistingDatabase(dbPath, options) {
     const resolvedPath = dbPath ?? getDbPath();
     // `undefined` means "no index" — reserve it for a genuinely absent one, and
     // let an unreadable index raise instead of masquerading as absent (#791).
     assertIndexPathReadable(resolvedPath);
     if (classifyPathAccess(resolvedPath).access === "absent")
         return undefined;
-    const db = openDatabase(resolvedPath, { readonly: true, create: false });
+    const db = options?.isolatedSnapshot
+        ? openSqliteReadSnapshot(resolvedPath)
+        : openDatabase(resolvedPath, { readonly: true, create: false });
+    if (!db)
+        return undefined;
     // This opener bypasses openManagedDatabase/applyStandardPragmas by design (no
     // journal or schema work on a read-only handle), but that also left
     // busy_timeout at SQLite's default of 0. In WAL that is harmless — readers
@@ -118,8 +143,15 @@ export function openReadonlyExistingDatabase(dbPath) {
     // AKM_SQLITE_JOURNAL_MODE can select, a concurrent writer makes every read
     // fail instantly with SQLITE_BUSY. busy_timeout is legal on a read-only
     // connection, so apply just that one.
-    db.exec(`PRAGMA busy_timeout = ${SQLITE_BUSY_TIMEOUT_MS}`);
-    return db;
+    try {
+        db.exec(`PRAGMA busy_timeout = ${SQLITE_BUSY_TIMEOUT_MS}`);
+        assertCanonicalIndexGeneration(db, resolvedPath);
+        return db;
+    }
+    catch (error) {
+        db.close();
+        throw error;
+    }
 }
 export function closeDatabase(db) {
     db.close();