akm-cli 0.9.16 → 0.9.17-alpha.10

package/dist/commands/improve/ledger.js

@@ -0,0 +1,119 @@
+// 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/.
+/**
+ * The stages' view of the `improve_ledger` table: record an attempt, and load
+ * the rows candidate selection reads before it spends an LLM call. The
+ * repository owns the schema and the outcome → cadence rule.
+ */
+import fs from "node:fs";
+import { getStateDbPath, withImmediateTransaction, withStateDb } from "../../core/state-db.js";
+import { warn } from "../../core/warn.js";
+import { isLedgerBlocked, listImproveLedgerRows, PAIR_PASS_LEDGER_SOURCE, recordImproveLedger, } from "../../storage/repositories/improve-ledger-repository.js";
+import { openSqliteReadSnapshot } from "../../storage/sqlite-read-snapshot.js";
+export { isLedgerBlocked, PAIR_PASS_LEDGER_SOURCE };
+/** An improve candidate's durable state key: its index item_ref, else its conceptId. */
+export function stateKey(ref, itemRef) {
+    return itemRef ?? ref;
+}
+/** The conceptId part of a durable key (`bundle//conceptId` → `conceptId`). */
+export function stripBundle(ref) {
+    const boundary = ref.indexOf("//");
+    return boundary >= 0 ? ref.slice(boundary + 2) : ref;
+}
+function ledgerDbPath(access) {
+    return access?.proposalsCtx?.dbPath ?? access?.eventsCtx?.dbPath;
+}
+/**
+ * Run `fn` against the ledger's database: the run's borrowed handle, a read
+ * snapshot for a read-only caller (`undefined` when state.db does not exist),
+ * or a managed open.
+ */
+function withLedgerDb(access, fn) {
+    const borrowed = access?.eventsCtx?.db;
+    if (borrowed)
+        return fn(borrowed);
+    const dbPath = ledgerDbPath(access);
+    if (access?.readOnly) {
+        const db = openSqliteReadSnapshot(dbPath ?? getStateDbPath());
+        if (!db)
+            return undefined;
+        try {
+            return fn(db);
+        }
+        finally {
+            db.close();
+        }
+    }
+    return withStateDb(fn, dbPath !== undefined ? { path: dbPath } : undefined);
+}
+/**
+ * Record what a stage just did with one or more refs. Best-effort: a failure
+ * is a warning, never an error on top of an LLM result. (Proposal mints and
+ * decisions write the ledger in their own transactions.)
+ */
+export function recordLedgerAttempt(access, inputs) {
+    const list = Array.isArray(inputs) ? inputs : [inputs];
+    if (list.length === 0 || access?.readOnly || access?.eventsCtx?.readOnly)
+        return;
+    const now = access?.proposalsCtx?.now ?? access?.eventsCtx?.now ?? Date.now;
+    const at = new Date(now()).toISOString();
+    try {
+        withLedgerDb(access, (db) => withImmediateTransaction(db, () => {
+            for (const input of list) {
+                recordImproveLedger(db, {
+                    stashDir: input.stashDir,
+                    ref: input.ref,
+                    source: input.source,
+                    outcome: input.outcome,
+                    at,
+                    ...(input.proposalId !== undefined ? { proposalId: input.proposalId } : {}),
+                    ...(input.detail !== undefined ? { detail: input.detail } : {}),
+                    ...(input.contentHash !== undefined ? { contentHash: input.contentHash } : {}),
+                });
+            }
+        }));
+    }
+    catch (error) {
+        const first = list[0];
+        const more = list.length > 1 ? ` (+${list.length - 1} more)` : "";
+        warn(`[improve] ledger write failed for ${first.ref}${more} (${first.source} → ${first.outcome}): ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export function ledgerKey(source, ref) {
+    return `${source}\0${ref}`;
+}
+/** Read state.db through `fn` without creating it: `undefined` when there is none yet. */
+export function readLedgerDb(access, fn) {
+    if (!access?.eventsCtx?.db && !fs.existsSync(ledgerDbPath(access) ?? getStateDbPath()))
+        return undefined;
+    return withLedgerDb(access, fn);
+}
+/** Every ledger row for `sources` in one query; no state.db yet means nothing was attempted. */
+export function loadLedgerSnapshot(access, stashDir, sources) {
+    const out = new Map();
+    try {
+        readLedgerDb(access, (db) => {
+            for (const row of listImproveLedgerRows(db, stashDir, sources))
+                out.set(ledgerKey(row.source, row.ref), row);
+        });
+    }
+    catch (error) {
+        warn(`[improve] ledger read failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return out;
+}
+/** The row for a candidate under its durable key. */
+export function ledgerRowFor(snapshot, source, ref, itemRef) {
+    return snapshot.get(ledgerKey(source, stateKey(ref, itemRef)));
+}
+/** `ref → last_attempt_at` for one source over a candidate set (the signal-delta cursor). */
+export function lastAttemptByRef(snapshot, source, candidates) {
+    const out = new Map();
+    for (const candidate of candidates) {
+        const row = ledgerRowFor(snapshot, source, candidate.ref, candidate.itemRef);
+        if (row)
+            out.set(candidate.ref, row.lastAttemptAt);
+    }
+    return out;
+}

package/dist/commands/improve/locks.js

@@ -5,7 +5,6 @@ import path from "node:path";
 import { TransientError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { releaseLock } from "../../core/file-lock.js";
-import { tryWithMaintenanceStartBarrier, withMaintenanceStartBarrier } from "../../core/maintenance-barrier.js";
 import { formatLockHolderPid, tryAcquireRunLock } from "../../core/run-lock.js";
 import { warn } from "../../core/warn.js";
 export function improveLockPath(lockBaseDir) {
@@ -16,11 +15,7 @@ export function tryAcquireImproveLock(lockPath, skipIfLocked, eventsCtx) {
     const acquire = () => tryAcquireImproveLockUnlocked(lockPath, skipIfLocked, (event) => {
         recoveryEvent = event;
     });
-    const result = skipIfLocked ? tryWithMaintenanceStartBarrier(acquire) : withMaintenanceStartBarrier(acquire);
-    if (!result) {
-        warn("[improve] maintenance barrier held; skipping (--skip-if-locked)");
-        return { state: "skipped" };
-    }
+    const result = acquire();
     if (recoveryEvent) {
         try {
             // R25: lock acquisition runs BEFORE akmImprove opens its long-lived
@@ -70,8 +65,7 @@ function tryAcquireImproveLockUnlocked(lockPath, skipIfLocked, onRecovered) {
     // A `ConfigError` here surfaced as exit 78 (INVALID_CONFIG_FILE) and told
     // a supervisor to stop retrying a normal lock collision. Reclassified to
     // `TransientError`/`IMPROVE_LOCK_HELD` (exit 75), mirroring the
-    // `MAINTENANCE_BARRIER_BUSY`/`INDEX_DB_CONTENDED` treatment #956 already
-    // applied to the index rebuild lock and the maintenance-start barrier.
+    // `INDEX_DB_CONTENDED` treatment #956 applied to the index rebuild lock.
     throw new TransientError(`akm improve is already running (PID ${pid}, started ${startedAt}). Delete ${lockPath} to force.`, "IMPROVE_LOCK_HELD");
 }
 export function releaseImproveLock(ownership) {