akm-cli 0.9.0-rc.0 → 0.9.0-rc.13

package/dist/storage/database.js

@@ -10,14 +10,14 @@
  *
  * Runtime selection:
  *   - On Bun (the primary/test runtime) we use the built-in `bun:sqlite`.
- *   - On Node.js (additive, not CI-tested this pass) we use `better-sqlite3`,
- *     loaded via a runtime-gated dynamic `require` so the Bun path never
+ *   - On Node.js (CI-tested by the node-smoke job's smoke + compat suites) we
+ *     use `better-sqlite3`, loaded via a runtime-gated dynamic `require` so the Bun path never
  *     imports it (it is an optionalDependency and may be uninstalled or
  *     uncompiled when running under Bun).
  *
  * Both driver handles are structurally compatible across the small surface AKM
  * uses (`prepare`, `exec`, `run`, `transaction`, `close` on the handle;
- * `get`, `all`, `run` on prepared statements). The Bun-specific `db.query()`
+ * `get`, `all`, `iterate`, `run` on prepared statements). The Bun-specific `db.query()`
  * helper is normalised away — callers use `db.prepare(sql).all(...)` instead.
  *
  * This file is intentionally NOT an adapter/DI/ports-and-adapters layer. It is
@@ -69,6 +69,50 @@ function selectProvider() {
 export function openDatabase(path, opts) {
     return selectProvider().open(path, opts);
 }
+/**
+ * {@link openDatabase} with a finalize-on-close guard (issue #720).
+ *
+ * bun:sqlite's `Database.close()` is a `sqlite3_close_v2`: with any UNFINALIZED
+ * `prepare()` statement outstanding, the underlying connection — and its WAL
+ * shared-memory mapping — survives as a zombie until GC finalizes the
+ * statements. A later connection in the same process then cannot leave WAL
+ * mode (`PRAGMA journal_mode = DELETE` → "database is locked"), which is
+ * exactly what silently defeated the migrate-apply single-file conversion.
+ * (`db.query()` statements are Database-cached and immune; `prepare()` is the
+ * dominant idiom in the migration helpers.)
+ *
+ * This variant tracks `prepare()` results and finalizes them (idempotently)
+ * before the real `close()`, so close always means CLOSED. It is deliberately
+ * OPT-IN for the migrate-apply flow's short-lived helper connections and the
+ * migration test fixtures — NOT the global default: long-lived/hot paths cache
+ * prepared statements per connection (e.g. the entries upsert WeakMap) and
+ * worker flows may still be stepping a statement when a sibling close lands;
+ * force-finalizing under them changes behavior they were built on.
+ */
+export function openDatabaseFinalizing(path, opts) {
+    const db = selectProvider().open(path, opts);
+    const tracked = new Set();
+    const origPrepare = db.prepare.bind(db);
+    const origClose = db.close.bind(db);
+    db.prepare = ((sql, ...rest) => {
+        const stmt = origPrepare(sql, ...rest);
+        tracked.add(stmt);
+        return stmt;
+    });
+    db.close = ((...args) => {
+        for (const stmt of tracked) {
+            try {
+                stmt.finalize?.();
+            }
+            catch {
+                // Already finalized (double-finalize is the idempotent no-op case).
+            }
+        }
+        tracked.clear();
+        return origClose(...args);
+    });
+    return db;
+}
 function openBunDatabase(path, opts) {
     const { Database: BunDatabase } = loadBunSqlite();
     // Only pass an options object when an option is actually set. bun:sqlite
@@ -133,5 +177,17 @@ function openNodeDatabase(path, opts) {
     if (opts?.create === false)
         options.fileMustExist = true;
     const db = opts ? new BetterSqlite3(path, options) : new BetterSqlite3(path);
-    return db;
+    return {
+        prepare: db.prepare.bind(db),
+        exec: db.exec.bind(db),
+        // better-sqlite3 exposes mutations on prepared statements, while
+        // bun:sqlite also provides db.run(). Normalize the latter at the provider
+        // boundary so callers and maintenance wrappers can rely on one contract.
+        run: (sql, ...params) => db.prepare(sql).run(...params),
+        transaction: db.transaction.bind(db),
+        get inTransaction() {
+            return db.inTransaction;
+        },
+        close: db.close.bind(db),
+    };
 }

package/dist/storage/engines/sqlite-migrations.js

@@ -1,6 +1,131 @@
 // 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/.
+/**
+ * Shared SQLite migration engine.
+ *
+ * state.db (`src/core/state-db.ts`) evolves its schema through this idempotent,
+ * transaction-per-migration runner backed by a `schema_migrations` ledger. The
+ * migrator's frozen pre-cutover workflow-schema roll
+ * (`scripts/akm-migrate/migrate/legacy/workflow-migrations-bodies.ts`, driven by
+ * `scripts/akm-migrate/config-migrate.ts`) reuses the SAME runner.
+ *
+ * This module factors that runner out once. Each caller supplies only its own
+ * `MIGRATIONS` array.
+ *
+ * Migration-safety contract:
+ *   - `id` is permanent and must never be reused.
+ *   - `up` must be idempotent (use IF NOT EXISTS, INSERT OR IGNORE, etc.).
+ *   - `up` must not DROP any table that holds durable (non-regenerable) data.
+ *   - `up` must not RENAME or change the type of an existing column.
+ *   - To add a column: use `ALTER TABLE … ADD COLUMN … DEFAULT …`.
+ *   - Applied IDs must be an exact ordered prefix of the registry.
+ *   - Released migration bodies are sealed by SHA-256 in the same ledger.
+ */
+import crypto from "node:crypto";
+export function migrationChecksum(migration) {
+    return crypto.createHash("sha256").update(migration.id).update("\0").update(migration.up).digest("hex");
+}
+function migrationsTableExists(db) {
+    return !!db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'schema_migrations'").get();
+}
+function ledgerHasChecksum(db) {
+    return db.prepare("PRAGMA table_info(schema_migrations)").all().some((column) => column.name === "checksum");
+}
+/**
+ * Core ledger inspection against the expected ordered `{ id, checksum }`
+ * registry. Both {@link inspectMigrationLedger} (bodies → checksums) and
+ * {@link inspectSealedMigrationLedger} (frozen pre-computed checksums) route
+ * here so the two entry points can never diverge.
+ */
+function inspectLedgerAgainst(db, expected) {
+    const registryIds = expected.map((entry) => entry.id);
+    if (new Set(registryIds).size !== registryIds.length) {
+        return {
+            status: "inconsistent",
+            migrationIds: [],
+            checksums: [],
+            detail: "migration registry contains duplicate IDs",
+        };
+    }
+    if (!migrationsTableExists(db))
+        return { status: registryIds.length === 0 ? "current" : "old", migrationIds: [], checksums: [] };
+    const hasChecksum = ledgerHasChecksum(db);
+    const rows = db
+        .prepare(`SELECT id${hasChecksum ? ", checksum" : ""} FROM schema_migrations ORDER BY rowid`)
+        .all();
+    const migrationIds = rows.map((row) => row.id);
+    const checksums = rows.map((row) => row.checksum ?? null);
+    for (let index = 0; index < rows.length; index += 1) {
+        const entry = expected[index];
+        const row = rows[index];
+        if (!entry) {
+            return { status: "newer", migrationIds, checksums, detail: `unknown migration ID ${row.id}` };
+        }
+        if (row.id !== entry.id) {
+            const knownLater = registryIds.includes(row.id);
+            return {
+                status: knownLater ? "inconsistent" : "newer",
+                migrationIds,
+                checksums,
+                detail: knownLater
+                    ? `migration ledger is not an exact ordered prefix at position ${index + 1}`
+                    : `unknown migration ID ${row.id}`,
+            };
+        }
+        if (row.checksum && row.checksum !== entry.checksum) {
+            return {
+                status: "inconsistent",
+                migrationIds,
+                checksums,
+                detail: `migration ${row.id} checksum does not match the released migration body`,
+            };
+        }
+    }
+    const missingChecksum = checksums.indexOf(null);
+    if (missingChecksum >= 0) {
+        return {
+            status: "old",
+            migrationIds,
+            checksums,
+            detail: `migration ${migrationIds[missingChecksum]} has not been sealed with a checksum`,
+        };
+    }
+    return {
+        status: rows.length === expected.length ? "current" : "old",
+        migrationIds,
+        checksums,
+    };
+}
+export function inspectMigrationLedger(db, migrations) {
+    return inspectLedgerAgainst(db, migrations.map((migration) => ({ id: migration.id, checksum: migrationChecksum(migration) })));
+}
+/**
+ * Ledger inspection against a FROZEN `{ id, checksum }` copy of a migration
+ * array whose live source is gone (plan §3.3 item 1). Behaviourally identical
+ * to {@link inspectMigrationLedger} — the checksums are simply pre-computed
+ * rather than derived from `up` bodies.
+ */
+export function inspectSealedMigrationLedger(db, sealed) {
+    return inspectLedgerAgainst(db, sealed);
+}
+export function assertMigrationLedger(db, migrations) {
+    const state = inspectMigrationLedger(db, migrations);
+    if (state.status === "newer") {
+        throw new Error(`Refusing to open a database with a newer migration ledger: ${state.detail}.`);
+    }
+    if (state.status === "inconsistent") {
+        throw new Error(`Refusing a database whose migrations are not an exact ordered prefix: ${state.detail}.`);
+    }
+    return state;
+}
+export function assertCurrentMigrationLedger(db, migrations) {
+    const state = assertMigrationLedger(db, migrations);
+    if (state.status !== "current") {
+        throw new Error(`Refusing to open an obsolete writable schema; run \`akm migrate apply\`: ${state.detail ?? "pending migrations"}.`);
+    }
+    return state;
+}
 /**
  * Create the migrations ledger table if it does not exist. Must be called
  * unconditionally on every open so a fresh database bootstraps correctly.
@@ -9,9 +134,12 @@ 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'))
+      applied_at TEXT    NOT NULL DEFAULT (datetime('now')),
+      checksum   TEXT
     );
   `);
+    if (!ledgerHasChecksum(db))
+        db.exec("ALTER TABLE schema_migrations ADD COLUMN checksum TEXT");
 }
 /**
  * Apply every pending migration, one transaction per migration.
@@ -24,19 +152,42 @@ export function ensureMigrationsTable(db) {
  *
  * @param db          The open SQLite database.
  * @param migrations  The module's ordered, append-only migration list.
- * @param opts        Optional `bootstrap` hook (see {@link RunMigrationsOptions}).
+ * @param opts        Migration execution options.
  */
 export function runMigrations(db, migrations, opts) {
+    if (opts?.applyPending === false) {
+        assertMigrationLedger(db, migrations);
+        return;
+    }
+    if (migrationsTableExists(db))
+        assertMigrationLedger(db, migrations);
     ensureMigrationsTable(db);
-    opts?.bootstrap?.(db);
-    const appliedRows = db.prepare("SELECT id FROM schema_migrations").all();
+    const ledger = assertMigrationLedger(db, migrations);
+    db.transaction(() => {
+        const update = db.prepare("UPDATE schema_migrations SET checksum = ? WHERE id = ? AND checksum IS NULL");
+        for (let index = 0; index < ledger.migrationIds.length; index += 1) {
+            update.run(migrationChecksum(migrations[index]), ledger.migrationIds[index]);
+        }
+        if (opts?.generationMarker) {
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS akm_migration_generation (
+          singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+          operation_id TEXT NOT NULL,
+          phase TEXT NOT NULL
+        )
+      `);
+            db.prepare("INSERT INTO akm_migration_generation(singleton, operation_id, phase) VALUES (1, ?, ?) ON CONFLICT(singleton) DO UPDATE SET operation_id=excluded.operation_id, phase=excluded.phase").run(opts.generationMarker.operationId, opts.generationMarker.phase);
+        }
+    })();
+    const appliedRows = db.prepare("SELECT id FROM schema_migrations ORDER BY rowid").all();
     const applied = new Set(appliedRows.map((r) => r.id));
     for (const migration of migrations) {
         if (applied.has(migration.id))
             continue;
+        opts?.beforeMigration?.(migration);
         db.transaction(() => {
             db.exec(migration.up);
-            db.prepare("INSERT INTO schema_migrations (id) VALUES (?)").run(migration.id);
+            db.prepare("INSERT INTO schema_migrations (id, checksum) VALUES (?, ?)").run(migration.id, migrationChecksum(migration));
         })();
     }
 }

package/dist/storage/locations.js

@@ -1,7 +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 { getCacheDir, getConfigDir, getDataDir, getDbPath, getDefaultStashDir, getLockfileLockPath, getLockfilePath, getWorkflowDbPath, } from "../core/paths.js";
+import { getCacheDir, getConfigDir, getDataDir, getDbPath, getDefaultStashDir, getLockfileLockPath, getLockfilePath, } from "../core/paths.js";
 import { getStateDbPath } from "../core/state-db.js";
 /**
  * Resolve the current {@link StorageLocations} by delegating to the existing
@@ -14,7 +14,6 @@ export function resolveStorageLocations() {
     return {
         indexDb: getDbPath(),
         stateDb: getStateDbPath(),
-        workflowDb: getWorkflowDbPath(),
         lockfile: getLockfilePath(),
         lockfileSentinel: getLockfileLockPath(),
         dataDir: getDataDir(),

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

@@ -45,7 +45,7 @@ export function listActiveCanarySetIds(db) {
 /**
  * Deactivate every canary row in a set. Rows are RETAINED (active = 0) so
  * historical improve_cycle_metrics rows keyed on the old canary_set_id stay
- * interpretable; only `akm improve canary --refresh` calls this.
+ * interpretable; only `bun scripts/refresh-canary-set.ts --refresh` calls this.
  */
 export function deactivateCanarySet(db, canarySetId) {
     const result = db

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

@@ -38,12 +38,7 @@ export function eventRowToEnvelope(row) {
  */
 export function insertEvent(db, input) {
     try {
-        const result = db
-            .prepare(`INSERT INTO events (event_type, ts, ref, metadata_json)
-         VALUES (?, ?, ?, ?)
-         RETURNING id`)
-            .get(input.eventType, input.ts, input.ref ?? null, JSON.stringify(input.metadata ?? {}));
-        return result?.id;
+        return insertEventStrict(db, input);
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
@@ -51,12 +46,52 @@ export function insertEvent(db, input) {
         return undefined;
     }
 }
+/** Insert an event without best-effort error swallowing for transaction-coupled mutations. */
+export function insertEventStrict(db, input) {
+    const result = db
+        .prepare(`INSERT INTO events (event_type, ts, ref, metadata_json)
+       VALUES (?, ?, ?, ?)
+       RETURNING id`)
+        .get(input.eventType, input.ts, input.ref ?? null, JSON.stringify(input.metadata ?? {}));
+    if (!result)
+        throw new Error(`Failed to persist ${input.eventType} event.`);
+    return result.id;
+}
+/** Strict idempotent event insert for durable mutation journals. */
+export function insertEventOnce(db, input) {
+    const rows = db
+        .prepare("SELECT id, metadata_json FROM events WHERE event_type = ? AND ref IS ? ORDER BY id")
+        .all(input.eventType, input.ref ?? null);
+    for (const row of rows) {
+        try {
+            const metadata = JSON.parse(row.metadata_json);
+            if (metadata[input.idempotencyMetadataKey ?? "proposalTransactionId"] === input.idempotencyKey)
+                return row.id;
+        }
+        catch {
+            // Corrupt unrelated event metadata cannot satisfy this idempotency key.
+        }
+    }
+    const result = db
+        .prepare(`INSERT INTO events (event_type, ts, ref, metadata_json)
+       VALUES (?, ?, ?, ?)
+       RETURNING id`)
+        .get(input.eventType, input.ts, input.ref ?? null, JSON.stringify(input.metadata));
+    if (!result)
+        throw new Error(`Failed to persist ${input.eventType} event.`);
+    return result.id;
+}
 /**
  * Read events from the database matching the filter. Returns events in
- * ascending id order so consumers can process them in emission order.
+ * ascending id order so consumers can process them in emission order —
+ * true even when `options.limit` selects the most-recent page (see
+ * {@link ReadStateEventsOptions.limit}).
  *
  * The returned `nextId` is the maximum id seen (or `sinceId` when no rows
- * match), suitable as the next `sinceId` cursor value.
+ * match), suitable as the next `sinceId` cursor value. This is unaffected by
+ * `limit`: it is always the id of the last row actually returned, which —
+ * because a `limit` page is the MOST RECENT matching rows — is the same
+ * value an unbounded read of the same filter would have produced.
  */
 export function readStateEvents(db, options = {}) {
     const conditions = [];
@@ -78,10 +113,15 @@ export function readStateEvents(db, options = {}) {
         params.push(options.ref);
     }
     const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+    const hasLimit = options.limit !== undefined && options.limit > 0;
+    const orderAndLimit = hasLimit ? "ORDER BY id DESC LIMIT ?" : "ORDER BY id ASC";
+    const queryParams = hasLimit ? [...params, options.limit] : params;
     const rows = db
-        .prepare(`SELECT id, event_type, ts, ref, metadata_json FROM events ${where} ORDER BY id ASC`)
-        .all(...params);
-    const events = rows.map(eventRowToEnvelope);
+        .prepare(`SELECT id, event_type, ts, ref, metadata_json FROM events ${where} ${orderAndLimit}`)
+        .all(...queryParams);
+    // A DESC-ordered LIMIT page comes back newest-first; reverse it so the
+    // returned array is always ascending by id, matching the unbounded path.
+    const events = (hasLimit ? rows.slice().reverse() : rows).map(eventRowToEnvelope);
     const nextId = events.length > 0 ? events[events.length - 1].id : (options.sinceId ?? 0);
     return { events, nextId };
 }

package/dist/storage/repositories/improve-runs-repository.js

@@ -2,26 +2,6 @@
 // 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 { classifyImproveAction } from "../../core/improve-types.js";
-// ── Per-phase gate threshold store (Migration 012) ───────────────────────────
-/**
- * Read the persisted auto-tuned threshold for a gate phase.
- *
- * Returns `undefined` when no row exists yet (first run, or the phase has
- * never been tuned). The caller falls back to the global `options.autoAccept`
- * in that case.
- */
-export function getPhaseThreshold(db, phase) {
-    const row = db.prepare("SELECT threshold FROM improve_gate_thresholds WHERE phase = ?").get(phase);
-    return row?.threshold;
-}
-/**
- * Persist the auto-tuned threshold for a gate phase.
- * Uses INSERT OR REPLACE so the call is idempotent (upsert semantics).
- */
-export function persistPhaseThreshold(db, phase, threshold) {
-    db.prepare(`INSERT OR REPLACE INTO improve_gate_thresholds (phase, threshold, updated_at)
-     VALUES (?, ?, ?)`).run(phase, Math.round(threshold), Date.now());
-}
 /**
  * Compute the cheap aggregate metrics blob from a full improve result.
  *
@@ -61,19 +41,13 @@ export function computeImproveRunMetrics(result) {
             case "noop":
                 break;
         }
-        // Legacy: pre-gate action results may carry autoAccepted: true (reflect path).
-        const r = action.result;
-        if (r && r.autoAccepted === true)
-            autoAcceptedCount++;
     }
     // Add gate-promoted count from the unified PostPhaseAutoAcceptGate (all phases).
     autoAcceptedCount += result.gateAutoAcceptedCount ?? 0;
     // C1 (13-bus-factor): distill-skipped rows are folded into the bounded
     // `distillSkipped` aggregate and no longer live in `actions`. Add the
     // aggregate total to the skipped + total-actions counters so metrics_json
-    // reports the same numbers as before the fold. (Legacy rows that still carry
-    // per-ref distill-skipped in `actions` have no aggregate, so they are counted
-    // by the classify loop above — never double-counted.)
+    // keeps aggregate metrics aligned with the logical action count.
     const distillSkippedTotal = result.distillSkipped?.total ?? 0;
     skippedCount += distillSkippedTotal;
     return {
@@ -103,10 +77,10 @@ export function recordImproveRun(db, input) {
     const metricsObj = input.metrics ?? computeImproveRunMetrics(input.result);
     db.prepare(`
     INSERT INTO improve_runs
-      (id, started_at, completed_at, stash_dir, dry_run, profile,
+       (id, started_at, completed_at, stash_dir, dry_run, strategy,
        scope_mode, scope_value, guidance, ok, result_json, metrics_json, metadata_json)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-  `).run(input.id, input.startedAt, input.completedAt, input.stashDir, input.dryRun ? 1 : 0, input.profile, input.scopeMode, input.scopeValue, input.guidance, input.ok ? 1 : 0, JSON.stringify(input.result), JSON.stringify(metricsObj), JSON.stringify(input.metadata ?? {}));
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(input.id, input.startedAt, input.completedAt, input.stashDir, input.dryRun ? 1 : 0, input.strategy, input.scopeMode, input.scopeValue, input.guidance, input.ok ? 1 : 0, JSON.stringify(input.result), JSON.stringify(metricsObj), JSON.stringify(input.metadata ?? {}));
 }
 /**
  * Read real (non-dry-run) improve_runs rows whose `started_at` falls in the
@@ -124,8 +98,8 @@ export function recordImproveRun(db, input) {
  */
 export function queryImproveRuns(db, since, until) {
     const sql = until
-        ? "SELECT id, started_at, completed_at, ok, scope_mode, scope_value, result_json FROM improve_runs WHERE started_at >= ? AND started_at < ? AND dry_run = 0 ORDER BY started_at DESC"
-        : "SELECT id, started_at, completed_at, ok, scope_mode, scope_value, result_json FROM improve_runs WHERE started_at >= ? AND dry_run = 0 ORDER BY started_at DESC";
+        ? "SELECT id, started_at, completed_at, ok, scope_mode, scope_value, strategy, result_json FROM improve_runs WHERE started_at >= ? AND started_at < ? AND dry_run = 0 ORDER BY started_at DESC"
+        : "SELECT id, started_at, completed_at, ok, scope_mode, scope_value, strategy, result_json FROM improve_runs WHERE started_at >= ? AND dry_run = 0 ORDER BY started_at DESC";
     return (until ? db.prepare(sql).all(since, until) : db.prepare(sql).all(since));
 }
 /**

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

@@ -0,0 +1,79 @@
+// 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/.
+/**
+ * `index.db` connection lifecycle for the storage layer.
+ *
+ * Opens/closes the index database, arming the sqlite-vec extension and (for the
+ * managed open path) running `ensureSchema`. This module lives BELOW the
+ * indexer, so the storage loan helpers (`index-db.ts`, `registry-cache.ts`)
+ * import their opener from a sibling here instead of reaching up into the
+ * indexer — inverting the old storage→indexer arrow.
+ */
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import { getDbPath } from "../../core/paths.js";
+import { openDatabase } from "../database.js";
+import { openManagedDatabase } from "../managed-db.js";
+import { ensureSchema } from "./index-schema.js";
+import { loadVecExtension, warnIfVecMissing } from "./index-vec-repository.js";
+export function openIndexDatabase(dbPath, options) {
+    return openManagedDatabase({
+        path: dbPath ?? getDbPath(),
+        init: (db) => {
+            // Try to load sqlite-vec extension
+            loadVecExtension(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
+            // both are absent do we fall through to the no-clobber path, which keeps
+            // ensureSchema from touching `index_meta.embeddingDim` at all.
+            const resolvedDim = options?.embeddingDim ?? resolveConfiguredEmbeddingDim();
+            ensureSchema(db, resolvedDim);
+            // Warn once at init if using JS fallback with many entries
+            warnIfVecMissing(db, { once: true });
+        },
+    });
+}
+/**
+ * Read the operator-configured embedding dimension from the on-disk config.
+ * Returns `undefined` when no config file is present, when the config has
+ * no `embedding.dimension` set, or when reading the config throws (e.g.
+ * inside isolated test fixtures with no XDG home). Failure is silent on
+ * purpose — every openDatabase() call would otherwise have to handle a
+ * config-not-found error path, and the fallback (no-clobber semantics) is
+ * already correct.
+ */
+function resolveConfiguredEmbeddingDim() {
+    try {
+        const esmRequire = createRequire(import.meta.url);
+        const { loadConfig } = esmRequire("../../core/config/config");
+        const dim = loadConfig().embedding?.dimension;
+        if (typeof dim === "number" && Number.isInteger(dim) && dim > 0 && dim <= 4096) {
+            return dim;
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+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.
+    return openManagedDatabase({ path: dbPath ?? getDbPath(), init: loadVecExtension });
+}
+/**
+ * Open an existing index for queries without creating directories, a database
+ * file, journals, or running write-capable pragmas/schema initialization.
+ */
+export function openReadonlyExistingDatabase(dbPath) {
+    const resolvedPath = dbPath ?? getDbPath();
+    if (!fs.existsSync(resolvedPath))
+        return undefined;
+    return openDatabase(resolvedPath, { readonly: true, create: false });
+}
+export function closeDatabase(db) {
+    db.close();
+}

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

@@ -1,9 +1,9 @@
 // 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 { openExistingDatabase } from "../../indexer/db/db.js";
 import { resolveStorageLocations } from "../locations.js";
 import { withManagedDb } from "../managed-db.js";
+import { openExistingDatabase } from "./index-connection.js";
 /**
  * Busy-timeout (ms) for read-path telemetry writers. Small on purpose: a
  * usage-event insert contending with a background reindex should be dropped,
@@ -13,8 +13,9 @@ export const TELEMETRY_BUSY_TIMEOUT_MS = 250;
 /**
  * Scoped-resource (loan pattern) helper for the index database (`index.db`).
  *
- * This is the `index.db` twin of {@link ../../workflows/db withWorkflowDb} /
- * {@link ./workflow-runs-repository withWorkflowRunsRepo}: it opens the index
+ * This is the `index.db` twin of the state.db loan helpers ({@link
+ * ../../core/state-db withStateDb} / {@link ./workflow-runs-repository
+ * withWorkflowRunsRepo}): it opens the index
  * database bound to {@link StorageLocations.indexDb}, runs `fn` against the live
  * {@link Database}, and closes the connection exactly once when `fn` returns —
  * even if `fn` throws. Callers no longer hand-roll `open / try / finally / close`