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

package/dist/commands/improve/eligibility.js

@@ -1,13 +1,13 @@
 // 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 refs an improve run may consider, read from the index, and the small predicates over them. */
 import fs from "node:fs";
 import path from "node:path";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
-import { conceptIdFromTypeName, parseRefInput, resolveRef } from "../../core/asset/resolve-ref.js";
+import { conceptIdFromTypeName, parseRefInput, resolveRef, typeNameFromConceptId } from "../../core/asset/resolve-ref.js";
 import { loadConfig } from "../../core/config/config.js";
 import { ConfigError, NotFoundError, rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
-import { readEvents } from "../../core/events.js";
 import { isPathAbsent } from "../../core/path-access.js";
 import { getDbPath } from "../../core/paths.js";
 import { deriveInstallations, deriveWritableBundleIds } from "../../indexer/installations.js";
@@ -15,70 +15,71 @@ import { resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { resolveAssetPath } from "../../indexer/walk/path-resolver.js";
 import { closeDatabase, openExistingDatabase, openReadonlyExistingDatabase, } from "../../storage/repositories/index-connection.js";
 import { getAllEntries } from "../../storage/repositories/index-entries-repository.js";
+import { hasCurrentEntriesTable } from "../../storage/repositories/index-entry-schema.js";
 import { getUtilityScoresByIds } from "../../storage/repositories/index-utility-repository.js";
 import { SqliteReadSnapshotUnavailableError } from "../../storage/sqlite-read-snapshot.js";
 import { isDistillRefusedInputType } from "./distill.js";
 import { isStrategyFilteredForAllPasses } from "./improve-strategies.js";
 import { parseMemoryRef } from "./memory/derived-ref.js";
-import { improveStateReadRefs } from "./source-identity.js";
-// Eligibility / candidate-selection predicates for improve. Free functions
-// (no akmImprove closure state) extracted from improve.ts to shrink the
-// orchestrator and make candidate selection independently testable.
+/** The asset type of a short or bundle-qualified conceptId (`""` when unknown). */
+export function assetTypeOf(ref) {
+    return typeNameFromConceptId(ref.includes("//") ? ref.slice(ref.indexOf("//") + 2) : ref)?.type ?? "";
+}
 /**
- * Open the index for eligibility queries, or `undefined` when no index exists
- * yet. `openExistingDatabase` refuses to create a missing `index.db` (see
- * index-connection.ts) — for eligibility, "no index" simply means nothing is
- * eligible, exactly like the readOnly arm's `undefined`.
- *
- * `undefined` is reserved for a genuinely ABSENT index. The readOnly arm has
- * refused to conflate that with an unreadable one since #791; this arm used
- * `fs.existsSync`, so the same run reported "nothing eligible to improve" at
- * exit 0 depending only on which branch it took. Both arms now raise.
+ * Run `fn` against index.db — the live index, or a non-mutating snapshot for
+ * a dry run. `undefined` when there is none or the read fails (best-effort).
  */
-function openEligibilityDb(readOnly) {
-    if (readOnly)
-        return openReadonlyExistingDatabase(undefined, { isolatedSnapshot: true });
-    return isPathAbsent(getDbPath()) ? undefined : openExistingDatabase();
-}
-function describeIndexSnapshot(readOnly, status) {
-    if (status === "ready") {
-        return {
-            status,
-            reason: readOnly ? "loaded a non-mutating point-in-time copy of the existing index" : "loaded the prepared index",
-        };
+export function withIndexDb(readOnly, fn) {
+    let db;
+    try {
+        db = readOnly ? openReadonlyExistingDatabase(undefined, { isolatedSnapshot: true }) : openExistingDatabase();
+        return db ? fn(db) : undefined;
+    }
+    catch (err) {
+        rethrowIfTestIsolationError(err);
+        return undefined;
+    }
+    finally {
+        if (db)
+            closeDatabase(db);
     }
-    return {
-        status,
-        reason: readOnly
-            ? "index.db is missing; dry-run uses an empty snapshot and does not create it"
-            : "index.db is missing after index preparation; the selector uses an empty snapshot",
-    };
-}
-function describeUnavailableSnapshot(error) {
-    return {
-        status: "incompatible",
-        reason: `index.db cannot provide a stable non-mutating snapshot (${error.message}); dry-run uses an empty snapshot`,
-    };
 }
 /**
- * A dry-run is explicitly a non-mutating planning operation, so it may report
- * an unusable derived index as an empty snapshot.  This is deliberately a
- * typed boundary mapping: readers otherwise receive no incompatible handle,
- * and we must not turn an arbitrary SQLite error into a successful plan by
- * matching its text.
+ * The index for candidate selection, or `undefined` when it is absent. An
+ * index without a readable `entries` table needs a rebuild and says so.
  */
-function isIncompatibleIndexError(error) {
-    return error instanceof ConfigError && error.code === "INDEX_SCHEMA_INCOMPATIBLE";
+function openEligibilityDb(readOnly) {
+    const db = readOnly
+        ? openReadonlyExistingDatabase(undefined, { isolatedSnapshot: true })
+        : isPathAbsent(getDbPath())
+            ? undefined
+            : openExistingDatabase();
+    if (db && !hasCurrentEntriesTable(db)) {
+        closeDatabase(db);
+        throw new ConfigError("index.db has no entries table this akm can read, so nothing can be selected for improvement.", "INDEX_SCHEMA_INCOMPATIBLE", "Run `akm index` to rebuild the derived index from the currently materialized sources.");
+    }
+    return db;
 }
-function describeIncompatibleIndexSnapshot(error) {
-    // `INDEX_SCHEMA_INCOMPATIBLE` establishes that this is the derived-index
-    // boundary, and the error's hint preserves whether this binary should
-    // rebuild an older/unknown generation or upgrade for a newer one.
-    const action = error.hint() ?? error.message;
-    return {
-        status: "incompatible",
-        reason: `index.db is incompatible; ${action} Dry-run uses an empty snapshot and does not migrate it.`,
-    };
+/**
+ * How a dry run describes an index it could not read. Only the typed
+ * failures map to an empty plan; any other error still throws.
+ */
+function unreadableSnapshot(readOnly, error) {
+    if (!readOnly)
+        return undefined;
+    if (error instanceof SqliteReadSnapshotUnavailableError) {
+        return {
+            status: "incompatible",
+            reason: `index.db cannot provide a stable non-mutating snapshot (${error.message}); dry-run uses an empty snapshot`,
+        };
+    }
+    if (error instanceof ConfigError && error.code === "INDEX_SCHEMA_INCOMPATIBLE") {
+        return {
+            status: "incompatible",
+            reason: `index.db is incompatible; ${error.hint() ?? error.message} Dry-run uses an empty snapshot and does not migrate it.`,
+        };
+    }
+    return undefined;
 }
 export function resolveImproveScope(scope) {
     const trimmed = scope?.trim();
@@ -89,80 +90,68 @@ export function resolveImproveScope(scope) {
         return { mode: "ref", value: trimmed };
     }
     catch (err) {
-        // A bare word with no ref separator is a `--scope <type>` filter attempt,
-        // not a ref. Any such word is accepted, including foreign/unknown type strings,
-        // which simply match zero entries downstream (a read-only query filter,
-        // not a data-acceptance gate, so no deny-list is needed here: an
-        // unrecognized type just matches nothing, since nothing is ever indexed
-        // with it). No test pinned the old "Unknown asset type" rejection for
-        // this case (chunk-1.5 anchors §A.5 — 0 hits).
-        //
-        // A colon-shaped value that still fails `parseRefInput` is a genuinely
-        // malformed ref attempt (bad name, path traversal, or a deny-listed
-        // deliberately-removed type like tool/vault, D1.5-6) — that must still
-        // surface as a real error, not be silently absorbed into a type filter
-        // that will never match anything.
-        if (!/[/:#]/.test(trimmed)) {
+        // A bare word is a `--scope <type>` filter (an unknown type matches
+        // nothing); a ref-shaped value that fails to parse is a real error.
+        if (!/[/:#]/.test(trimmed))
             return { mode: "type", value: trimmed };
-        }
         const message = err instanceof Error ? err.message : String(err);
         throw new UsageError(`Invalid --scope "${trimmed}": ${message}`, "INVALID_FLAG_VALUE");
     }
 }
-/**
- * Dedupe eligible refs by their durable item ref when available, preserving
- * the first candidate and its display ref. Used to
- * merge the eligibility sources (feedback-signal, Layer-2 proactive-maintenance,
- * high-salience) without admitting a ref into the loop twice.
- */
+/** Dedupe by durable identity (item_ref, else ref), keeping the first. */
 export function dedupeRefs(refs) {
     const seen = new Set();
-    const out = [];
-    for (const r of refs) {
+    return refs.filter((r) => {
         const key = r.itemRef ?? r.ref;
         if (seen.has(key))
-            continue;
+            return false;
         seen.add(key);
-        out.push(r);
-    }
-    return out;
+        return true;
+    });
 }
 export async function collectEligibleRefs(scope, stashDir, improveProfile, config) {
     return collectEligibleRefsFromIndex(scope, stashDir, improveProfile, false, config);
 }
-/** Dry-run planner path: query an existing index without creating or mutating it. */
+/** Dry-run selector: query an existing index without creating or mutating it. */
 export async function collectEligibleRefsReadOnly(scope, stashDir, improveProfile, config) {
     return collectEligibleRefsFromIndex(scope, stashDir, improveProfile, true, config);
 }
 async function collectEligibleRefsFromIndex(scope, stashDir, improveProfile, readOnly, configOverride) {
+    const empty = (indexSnapshot) => ({
+        plannedRefs: [],
+        memorySummary: { eligible: 0, derived: 0 },
+        strategyFilteredRefs: [],
+        ...(indexSnapshot ? { indexSnapshot } : {}),
+    });
     const config = configOverride ?? loadConfig();
     let sources;
     try {
         sources = resolveSourceEntries(stashDir, config);
     }
     catch {
-        return { plannedRefs: [], memorySummary: { eligible: 0, derived: 0 }, strategyFilteredRefs: [] };
-    }
-    if (sources.length === 0) {
-        return { plannedRefs: [], memorySummary: { eligible: 0, derived: 0 }, strategyFilteredRefs: [] };
+        return empty();
     }
+    if (sources.length === 0)
+        return empty();
     const installations = deriveInstallations(sources);
     const writableBundleIds = deriveWritableBundleIds(sources);
-    if (scope.mode === "ref" && scope.value) {
-        let db;
-        try {
-            db = openEligibilityDb(readOnly);
-            if (!db) {
-                return {
-                    plannedRefs: [],
-                    memorySummary: { eligible: 0, derived: 0 },
-                    strategyFilteredRefs: [],
-                    indexSnapshot: describeIndexSnapshot(readOnly, "missing"),
-                };
-            }
-            const indexSnapshot = describeIndexSnapshot(readOnly, "ready");
-            const entries = getAllEntries(db);
-            const entriesByItemRef = new Map(entries.map((entry) => [entry.itemRef, entry]));
+    const ready = {
+        status: "ready",
+        reason: readOnly ? "loaded a non-mutating point-in-time copy of the existing index" : "loaded the prepared index",
+    };
+    const missing = {
+        status: "missing",
+        reason: readOnly
+            ? "index.db is missing; dry-run uses an empty snapshot and does not create it"
+            : "index.db is missing after index preparation; the selector uses an empty snapshot",
+    };
+    let db;
+    try {
+        db = openEligibilityDb(readOnly);
+        if (!db)
+            return empty(missing);
+        if (scope.mode === "ref" && scope.value) {
+            const entriesByItemRef = new Map(getAllEntries(db).map((entry) => [entry.itemRef, entry]));
             const resolved = resolveRef(scope.value, {
                 defaultBundle: config.defaultBundle,
                 bundles: installations.map((installation) => ({
@@ -172,77 +161,31 @@ async function collectEligibleRefsFromIndex(scope, stashDir, improveProfile, rea
             });
             const indexed = entriesByItemRef.get(`${resolved.bundle}//${resolved.conceptId}`);
             if (!indexed?.bundleId || !indexed.conceptId || !fs.existsSync(indexed.filePath)) {
-                if (await findAssetFilePath(scope.value, stashDir)) {
-                    return {
-                        plannedRefs: [],
-                        memorySummary: { eligible: 0, derived: 0 },
-                        strategyFilteredRefs: [],
-                        indexSnapshot,
-                    };
-                }
+                if (await findAssetFilePath(scope.value, stashDir))
+                    return empty(ready);
                 throw new NotFoundError(`Asset not found in the selected writable source: ${scope.value}`, "ASSET_NOT_FOUND");
             }
-            if (!writableBundleIds.has(indexed.bundleId)) {
-                return { plannedRefs: [], memorySummary: { eligible: 0, derived: 0 }, strategyFilteredRefs: [], indexSnapshot };
-            }
+            if (!writableBundleIds.has(indexed.bundleId))
+                return empty(ready);
+            const isMemory = indexed.entry.type === "memory";
             return {
                 plannedRefs: [
                     { ref: indexed.conceptId, itemRef: indexed.itemRef, reason: "scope-ref", filePath: indexed.filePath },
                 ],
                 memorySummary: {
-                    eligible: indexed.entry.type === "memory" ? 1 : 0,
-                    derived: indexed.entry.type === "memory" && indexed.entry.name.endsWith(".derived") ? 1 : 0,
+                    eligible: isMemory ? 1 : 0,
+                    derived: isMemory && indexed.entry.name.endsWith(".derived") ? 1 : 0,
                 },
                 strategyFilteredRefs: [],
-                indexSnapshot,
-            };
-        }
-        catch (error) {
-            if (readOnly && error instanceof SqliteReadSnapshotUnavailableError) {
-                return {
-                    plannedRefs: [],
-                    memorySummary: { eligible: 0, derived: 0 },
-                    strategyFilteredRefs: [],
-                    indexSnapshot: describeUnavailableSnapshot(error),
-                };
-            }
-            if (readOnly && isIncompatibleIndexError(error)) {
-                return {
-                    plannedRefs: [],
-                    memorySummary: { eligible: 0, derived: 0 },
-                    strategyFilteredRefs: [],
-                    indexSnapshot: describeIncompatibleIndexSnapshot(error),
-                };
-            }
-            throw error;
-        }
-        finally {
-            if (db)
-                closeDatabase(db);
-        }
-    }
-    let db;
-    try {
-        db = openEligibilityDb(readOnly);
-        if (!db) {
-            return {
-                plannedRefs: [],
-                memorySummary: { eligible: 0, derived: 0 },
-                strategyFilteredRefs: [],
-                indexSnapshot: describeIndexSnapshot(readOnly, "missing"),
+                indexSnapshot: ready,
             };
         }
-        const indexSnapshot = describeIndexSnapshot(readOnly, "ready");
         const entries = getAllEntries(db, scope.mode === "type" ? scope.value : undefined).filter((indexed) => writableBundleIds.has(indexed.bundleId));
         const planned = new Map();
         const strategyFiltered = new Map();
         let memoryEligible = 0;
         let memoryDerived = 0;
         for (const indexed of entries) {
-            // Chunk-8 WI-8.5c: the candidate `ref` is the SHORT conceptId
-            // (`<stash-subdir>/<name>`, D-R2) — it now matches the disk lookup,
-            // xrefs, and `displayRef` output spelling. `.itemRef` below stays the
-            // fully-qualified durable key.
             const ref = conceptIdFromTypeName(indexed.entry.type, indexed.entry.name);
             try {
                 parseRefInput(ref);
@@ -252,40 +195,16 @@ async function collectEligibleRefsFromIndex(scope, stashDir, improveProfile, rea
                     continue;
                 throw error;
             }
-            // Derive the durable item_ref from indexed provenance without another query.
-            // A provenance-free row uses the short conceptId ref for improve state.
-            const itemRef = indexed.itemRef;
             const isDerived = indexed.entry.name.endsWith(".derived");
-            // `.derived` memories are LLM-inferred and intentionally skip reflect
-            // (see the synthetic `derived-memory-reflect-skipped` branch in the
-            // improve loop). Enqueueing them here just produced one synthetic skip
-            // per derived memory per hour with no real work — pure churn observed
-            // 2026-05-21: 11 derived refs re-planned every hour during idle periods.
-            // The cleanup phase (analyzeMemoryCleanup) inspects derived memories
-            // independently of `plannedRefs`, so dropping them here loses nothing.
+            // `.derived` memories skip reflect; cleanup inspects them on its own.
             if (!isDerived && !planned.has(ref) && !strategyFiltered.has(ref)) {
-                // 2026-05-27: extend the .derived precedent to strategy-incompatible
-                // refs. If every per-ref pass (reflect + distill) on the active
-                // strategy would refuse this ref, drop it from `plannedRefs`. The
-                // caller emits `improve_skipped { reason: strategy_filtered_all_passes }`
-                // once `eventsCtx` is available so the audit trail is preserved in a
-                // single event per ref instead of 2× synthetic actions per run.
-                // Background: see /tmp/akm-health-investigations/planner-profile-metrics-deep-analysis.md
+                const candidate = { ref, filePath: indexed.filePath, itemRef: indexed.itemRef };
                 if (improveProfile && isStrategyFilteredForAllPasses(ref, improveProfile)) {
-                    strategyFiltered.set(ref, {
-                        ref,
-                        reason: "strategy_filtered_all_passes",
-                        filePath: indexed.filePath,
-                        itemRef,
-                    });
+                    strategyFiltered.set(ref, { ...candidate, reason: "strategy_filtered_all_passes" });
                 }
                 else {
-                    planned.set(ref, {
-                        ref,
-                        reason: scope.mode === "type" ? "scope-type" : indexed.entry.type === "memory" ? "memory-cleanup" : "scope-type",
-                        filePath: indexed.filePath,
-                        itemRef,
-                    });
+                    const reason = scope.mode !== "type" && indexed.entry.type === "memory" ? "memory-cleanup" : "scope-type";
+                    planned.set(ref, { ...candidate, reason });
                 }
             }
             if (indexed.entry.type === "memory") {
@@ -298,28 +217,14 @@ async function collectEligibleRefsFromIndex(scope, stashDir, improveProfile, rea
             plannedRefs: [...planned.values()],
             memorySummary: { eligible: memoryEligible, derived: memoryDerived },
             strategyFilteredRefs: [...strategyFiltered.values()],
-            indexSnapshot,
+            indexSnapshot: ready,
         };
     }
     catch (error) {
-        // Empty-stash setup paths can open index.db before its schema exists.
         rethrowIfTestIsolationError(error);
-        if (readOnly && error instanceof SqliteReadSnapshotUnavailableError) {
-            return {
-                plannedRefs: [],
-                memorySummary: { eligible: 0, derived: 0 },
-                strategyFilteredRefs: [],
-                indexSnapshot: describeUnavailableSnapshot(error),
-            };
-        }
-        if (readOnly && isIncompatibleIndexError(error)) {
-            return {
-                plannedRefs: [],
-                memorySummary: { eligible: 0, derived: 0 },
-                strategyFilteredRefs: [],
-                indexSnapshot: describeIncompatibleIndexSnapshot(error),
-            };
-        }
+        const snapshot = unreadableSnapshot(readOnly, error);
+        if (snapshot)
+            return empty(snapshot);
         throw error;
     }
     finally {
@@ -327,30 +232,20 @@ async function collectEligibleRefsFromIndex(scope, stashDir, improveProfile, rea
             closeDatabase(db);
     }
 }
+/** The parent memory a `--scope <memory ref>` cleanup is restricted to. */
 export function memoryCleanupParentRef(scope, stashDir) {
     if (scope.mode !== "ref" || !scope.value)
         return undefined;
     const parsed = parseRefInput(scope.value);
     if (parsed.type !== "memory")
         return undefined;
-    // Non-derived parent scope: emit the canonical `memories/<name>` conceptId so
-    // it matches `resolveParentRef`'s output in analyzeMemoryCleanup's parentRef
-    // filter (Group-C item 2 — the reader and every comparison site flipped
-    // together; emitting the raw scope value would re-open the mismatch the
-    // chunk-8 history warns about).
     if (!parsed.name.endsWith(".derived"))
         return conceptIdFromTypeName(parsed.type, parsed.name);
-    const sources = resolveSourceEntries(stashDir);
-    for (const source of sources) {
+    for (const source of resolveSourceEntries(stashDir)) {
         const candidate = path.join(source.path, "memories", `${parsed.name}.md`);
         if (!fs.existsSync(candidate))
             continue;
-        const raw = fs.readFileSync(candidate, "utf8");
-        const fm = parseFrontmatter(raw).data;
-        // The `source:` backref is normalized to the `memories/<name>` conceptId.
-        // That is exactly what
-        // analyzeMemoryCleanup's parentRef filter compares against — resolveParentRef
-        // emits the same conceptId — so the two sites stay in lockstep.
+        const fm = parseFrontmatter(fs.readFileSync(candidate, "utf8")).data;
         const parent = parseMemoryRef(typeof fm.source === "string" ? fm.source : undefined);
         if (parent)
             return parent;
@@ -358,179 +253,29 @@ export function memoryCleanupParentRef(scope, stashDir) {
     return conceptIdFromTypeName("memory", parsed.name.slice(0, -".derived".length));
 }
 export function isLessonCandidate(ref) {
-    // Only lesson assets need lesson-schema validation (description + when_to_use).
-    // Memories have their own distill path via shouldDistillMemoryRef.
-    // All other types go through reflect, not distill.
     return parseRefInput(ref).type === "lesson";
 }
-/**
- * Planner-side check: should this ref enter the distill queue?
- *
- * Distill produces lessons from non-lesson sources. Two cases are eligible:
- *
- *   1. Memory refs that pass {@link shouldDistillMemoryRef} (the existing
- *      memory→lesson/knowledge promotion path).
- *
- * Refs whose `type` is in {@link DISTILL_REFUSED_INPUT_TYPES} (currently
- * `lesson:*`) are explicitly excluded — distill refuses them at runtime and
- * queuing them just produces a no-op `skipped` outcome per ref per hour. That
- * planner waste was the bug fixed in commit
- * fix(improve): drop distill-refused types from planner.
- *
- * Note: prior to this fix the gate used `isLessonCandidate(ref)` directly,
- * which was true *only* for `lesson:*` refs — exactly the set distill refuses.
- * The result: every hourly run re-queued the same lesson refs, the same skip
- * message returned, and no work was ever done. See
- * `tests/integration/commands/improve-distill-planner-skip-lessons.test.ts`.
- */
+/** Should this ref enter the distill queue? Types distill refuses never do. */
 export function isDistillCandidateRef(ref, stashDir) {
-    const parsed = parseRefInput(ref);
-    if (isDistillRefusedInputType(parsed.type))
+    if (isDistillRefusedInputType(parseRefInput(ref).type))
         return false;
     return shouldDistillMemoryRef(ref, stashDir);
 }
+/** A non-derived memory that is not marked `quality: proposed`. */
 export function shouldDistillMemoryRef(ref, stashDir) {
     const parsed = parseRefInput(ref);
     if (parsed.type !== "memory")
         return false;
-    const sources = resolveSourceEntries(stashDir);
-    for (const source of sources) {
+    for (const source of resolveSourceEntries(stashDir)) {
         const candidate = `${source.path}/memories/${parsed.name}.md`;
         if (!fs.existsSync(candidate))
             continue;
-        const raw = fs.readFileSync(candidate, "utf8");
-        const fm = parseFrontmatter(raw).data;
-        const quality = typeof fm.quality === "string" ? fm.quality : undefined;
-        if (quality === "proposed")
+        if (parseFrontmatter(fs.readFileSync(candidate, "utf8")).data.quality === "proposed")
             return false;
-        return !parsed.name.endsWith(".derived");
+        break;
     }
     return !parsed.name.endsWith(".derived");
 }
-// ── Signal-delta eligibility helpers (0.8.0) ────────────────────────────────
-//
-// The 0.8.0 redesign replaced flat time-based cooldowns for reflect/distill
-// with a *signal-delta* gate: a ref is re-eligible iff new feedback has
-// landed since the last proposal was generated for it. These helpers build
-// the two timestamp maps the gate needs in bulk, so the planner avoids
-// N+1 queries across the full postCleanupRefs set.
-/**
- * Latest feedback event timestamp per ref in the active window. Reads all
- * `feedback` events newer than `sinceIso` in one query and indexes by ref,
- * keeping the maximum `ts` per ref.
- *
- * Only events with a meaningful payload count as "signal" — `metadata.signal`
- * (positive/negative) OR `metadata.note` (a free-form annotation). Empty
- * metadata events are ignored so a stray `akm feedback <ref>` invocation
- * without a flag doesn't trigger downstream re-processing.
- */
-export function buildLatestFeedbackTsMap(refs, sinceIso, itemRefByRef, eventsCtx) {
-    const out = new Map();
-    if (refs.length === 0)
-        return out;
-    // Correlate item_ref-keyed events and conceptId-keyed direct invocations.
-    const refByDurableKey = new Map(refs.flatMap((ref) => improveStateReadRefs(ref, itemRefByRef?.get(ref)).map((key) => [key, ref])));
-    const { events } = readEvents({ type: "feedback", since: sinceIso }, eventsCtx);
-    for (const e of events) {
-        const ref = e.ref ? refByDurableKey.get(e.ref) : undefined;
-        if (!ref)
-            continue;
-        const meta = e.metadata;
-        const hasSignal = meta !== undefined && (typeof meta.signal === "string" || typeof meta.note === "string");
-        if (!hasSignal)
-            continue;
-        const ts = e.ts ?? "";
-        if (ts > (out.get(ref) ?? ""))
-            out.set(ref, ts);
-    }
-    return out;
-}
-/**
- * Latest proposal timestamp per input-ref, filtered by source ('reflect' or
- * 'distill'). Reads the corresponding `*_invoked` events from state.db —
- * these events are emitted at proposal creation time and carry the *input*
- * asset ref (`memories/foo`, `skills/bar`, etc.) directly. We use them rather than
- * `listProposals` because distill proposals are keyed by the derived
- * lesson/knowledge ref, not the source memory — joining back through the
- * payload would be fragile.
- */
-export function buildLatestProposalTsMap(refs, source, itemRefByRef, eventsCtx) {
-    const out = new Map();
-    if (refs.length === 0)
-        return out;
-    // Correlate item_ref-keyed events and conceptId-keyed direct invocations.
-    const refByDurableKey = new Map(refs.flatMap((ref) => improveStateReadRefs(ref, itemRefByRef?.get(ref)).map((key) => [key, ref])));
-    const eventType = source === "reflect" ? "reflect_invoked" : "distill_invoked";
-    const { events } = readEvents({ type: eventType }, eventsCtx);
-    for (const e of events) {
-        const ref = e.ref ? refByDurableKey.get(e.ref) : undefined;
-        if (!ref)
-            continue;
-        // For distill_invoked we only count attempts that produced (or attempted
-        // to produce) a real proposal — config_disabled outcomes (no LLM work was
-        // actually invoked) and llm_failed (transport/timeout — nothing to show
-        // for the attempt) should not move the signal-delta cursor forward.
-        // R10: quality_rejected and review_needed now also mint a real proposal
-        // row (see quality-gate.ts's `writeQualityRejection`), so — like queued —
-        // a real attempt was made and the cursor must advance, or the same
-        // already-rejected ref is re-selected and re-rejected on every run.
-        if (eventType === "distill_invoked") {
-            const outcome = e.metadata?.outcome;
-            if (outcome !== "queued" &&
-                outcome !== "skipped" &&
-                outcome !== "validation_failed" &&
-                outcome !== "quality_rejected" &&
-                outcome !== "review_needed") {
-                continue;
-            }
-        }
-        const ts = e.ts ?? "";
-        if (ts > (out.get(ref) ?? ""))
-            out.set(ref, ts);
-    }
-    return out;
-}
-/**
- * Signal-delta eligibility predicate.
- *
- * True iff `latestFeedback[ref]` is defined AND either no prior proposal
- * exists for this (ref, source) OR `latestFeedback[ref] > lastProposal[ref]`.
- *
- * Refs with no feedback signal at all are ineligible by definition — the
- * proactive-maintenance and high-salience fallback lanes (see
- * `noFeedbackCandidates` later in the planner) handle never-rated assets
- * separately.
- */
-export function isSignalDeltaEligible(ref, latestFeedback, lastProposal) {
-    const fb = latestFeedback.get(ref);
-    if (!fb)
-        return false;
-    const lp = lastProposal.get(ref);
-    if (!lp)
-        return true;
-    return fb > lp;
-}
-/**
- * H7 (#566): cooperative budget watchdog with a captured, RAII-cleared hard-kill.
- *
- * When the wall-clock budget expires, `onExhausted` (normally an
- * `AbortController.abort`) signals cooperative cancellation so the run can drain
- * its in-flight log/`state.db` flush and unwind naturally. A second hard-kill
- * timer is then armed as a watchdog: it only `exit(0)`s if the drain itself
- * overruns `hardKillGraceMs`, preventing the process from outliving the task
- * timeout window (lock-cascade fix).
- *
- * Both timers are captured; the returned dispose() clears whichever is still
- * pending. Callers invoke it from a `finally`, so a *clean* drain reaches the
- * `finally` and cancels the pending hard-kill before it can fire — the previous
- * detached `setTimeout(() => process.exit(0), 5000)` always fired, truncating a
- * clean flush. The hard-kill timer is `unref()`-ed so it never keeps the event
- * loop alive on its own: once the run drains it exits with its own code, not the
- * forced 0.
- *
- * Dependencies are injectable purely so the concurrency-sensitive timing
- * contract can be exercised deterministically in unit tests.
- */
 export function shouldAnalyzeMemoryCleanup(scope, eligibleMemories, primaryStashDir) {
     if (!primaryStashDir || eligibleMemories === 0)
         return false;
@@ -538,47 +283,28 @@ export function shouldAnalyzeMemoryCleanup(scope, eligibleMemories, primaryStash
         return true;
     if (scope.mode === "type")
         return scope.value === "memory";
-    if (!scope.value)
-        return false;
-    return parseRefInput(scope.value).type === "memory";
+    return scope.value ? parseRefInput(scope.value).type === "memory" : false;
 }
 export function buildUtilityMap(refs, readOnly = false) {
     const map = new Map();
     if (refs.length === 0)
         return map;
     const refSet = new Set(refs.map((r) => r.ref));
-    let db;
-    try {
-        db = readOnly ? openReadonlyExistingDatabase(undefined, { isolatedSnapshot: true }) : openExistingDatabase();
-        if (!db)
-            return map;
-        const allDbEntries = getAllEntries(db);
+    withIndexDb(readOnly, (db) => {
         const idToRef = new Map();
-        for (const indexed of allDbEntries) {
-            // Chunk-8 WI-8.5c: correlate on the SHORT conceptId to match the
-            // `ImproveEligibleRef.ref` set built in collectEligibleRefsFromIndex.
+        for (const indexed of getAllEntries(db)) {
             const ref = conceptIdFromTypeName(indexed.entry.type, indexed.entry.name);
             if (refSet.has(ref))
                 idToRef.set(indexed.id, ref);
         }
-        const ids = [...idToRef.keys()];
-        if (ids.length > 0) {
-            const { global: scores } = getUtilityScoresByIds(db, ids);
-            for (const [id, score] of scores) {
-                const ref = idToRef.get(id);
-                if (ref)
-                    map.set(ref, score.utility);
-            }
+        if (idToRef.size === 0)
+            return;
+        for (const [id, score] of getUtilityScoresByIds(db, [...idToRef.keys()])) {
+            const ref = idToRef.get(id);
+            if (ref)
+                map.set(ref, score.utility);
         }
-    }
-    catch (err) {
-        rethrowIfTestIsolationError(err);
-        // best-effort: if DB unavailable, all utilities default to 0
-    }
-    finally {
-        if (db)
-            closeDatabase(db);
-    }
+    });
     return map;
 }
 export async function findAssetFilePath(ref, stashDir, writableBundleIds) {