akm-cli 0.9.6 → 0.9.8-beta.1

package/dist/setup/setup.js

@@ -24,7 +24,7 @@ import { deriveBundleIds } from "../core/bundle-id.js";
 import { bundleEntryToSourceEntry, DEFAULT_CONFIG, loadUserConfig, mutateConfigWithPrecommit, parseAndValidateConfigText, primaryBundlePath, validateCompleteConfig, } from "../core/config/config.js";
 import { readConfigText } from "../core/config/config-io.js";
 import { listTopLevelConfigKeys } from "../core/config/config-schema.js";
-import { deepMergeConfig } from "../core/config/deep-merge.js";
+import { deepMergeConfig, isPlainObject } from "../core/config/deep-merge.js";
 import { ConfigError, UsageError } from "../core/errors.js";
 import { getConfigPath, getDefaultStashDir, isTransientStashPath } from "../core/paths.js";
 import { warn } from "../core/warn.js";
@@ -131,17 +131,11 @@ export function assertSetupConfigPreflight() {
             `(e.g. \`mv ${configPath} ${configPath}.bak\`) and re-run \`akm setup\`.`);
     }
 }
-function isPlainRecord(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
-        return false;
-    const prototype = Object.getPrototypeOf(value);
-    return prototype === Object.prototype || prototype === null;
-}
 function sameConfigValue(left, right) {
     return isDeepStrictEqual(left, right);
 }
 function configArrayItemKey(value) {
-    if (!isPlainRecord(value))
+    if (!isPlainObject(value))
         return `value:${JSON.stringify(value)}`;
     if (typeof value.id === "string")
         return `id:${value.id}`;
@@ -199,14 +193,14 @@ export function rebaseSetupChanges(original, desired, latest, pathParts = []) {
         }
         return result;
     }
-    if (!isPlainRecord(original) || !isPlainRecord(desired)) {
+    if (!isPlainObject(original) || !isPlainObject(desired)) {
         if (!sameConfigValue(latest, original) && !sameConfigValue(latest, desired))
             setupConflict(pathParts);
         return desired;
     }
-    if (latest !== undefined && !isPlainRecord(latest))
+    if (latest !== undefined && !isPlainObject(latest))
         setupConflict(pathParts);
-    const result = isPlainRecord(latest) ? { ...latest } : {};
+    const result = isPlainObject(latest) ? { ...latest } : {};
     for (const key of new Set([...Object.keys(original), ...Object.keys(desired)])) {
         if (!Object.hasOwn(desired, key)) {
             if (Object.hasOwn(result, key) && !sameConfigValue(result[key], original[key]))
@@ -855,7 +849,7 @@ export async function runSetupFromConfig(opts) {
     catch (e) {
         throw new UsageError(`Invalid JSON in --config: ${e.message}`, "INVALID_FLAG_VALUE");
     }
-    if (!isPlainRecord(parsed)) {
+    if (!isPlainObject(parsed)) {
         throw new ConfigError("Setup config must contain a top-level object.", "INVALID_CONFIG_FILE");
     }
     const incoming = parsed;

package/dist/sources/providers/git-install.js

@@ -48,8 +48,13 @@ export function inspectGitUpstream(repoDir) {
  * commit SHA peels to itself.
  */
 export function verifyClonedRevision(cloneDir, url, expectedRevision) {
-    if (!expectedRevision)
-        return;
+    if (!expectedRevision) {
+        // `resolveGitArtifact` (registry/resolve.ts) throws when it cannot resolve
+        // a revision via `git ls-remote`, so a plain git install never reaches
+        // this call with `undefined` — treat it as a bug, not a silently-skipped
+        // check that would defeat the R-011 post-clone integrity verification.
+        throw new UsageError(`No revision was resolved from ${url}; refusing to install without a verifiable checkout.`);
+    }
     const head = runGit(["-C", cloneDir, "rev-parse", "HEAD"]);
     if (head.status !== 0 || !head.stdout.trim()) {
         throw new UsageError(`Failed to read cloned HEAD at ${cloneDir}: ${head.stderr.trim() || "rev-parse failed"}`);

package/dist/sources/providers/tar-utils.js

@@ -91,13 +91,7 @@ export function extractTarGzSecure(archivePath, destinationDir) {
     scanExtractedFiles(destinationDir, destinationDir);
 }
 function scanExtractedFiles(dir, root) {
-    let entries;
-    try {
-        entries = fs.readdirSync(dir, { withFileTypes: true });
-    }
-    catch {
-        return;
-    }
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
     for (const entry of entries) {
         const fullPath = path.join(dir, entry.name);
         // Reject only entries whose name is exactly the parent-traversal segment

package/dist/sources/snapshot-fetchers/content-extract.js

@@ -609,20 +609,3 @@ export function htmlToMarkdownAndLinks(html, pageUrl) {
     const markdown = root ? markdownFromRoot(root, html, pageUrl) : plainTextFallback(html);
     return { markdown: finalizeMarkdown(markdown), links };
 }
-/**
- * Collect links from the WHOLE document, not the extracted content region.
- *
- * Deliberate and load-bearing: nav/header/footer links are how a crawl
- * discovers pages. Narrowing this to the content region would silently shrink
- * every crawl to whatever the first page happens to link inline.
- */
-export function extractDocumentLinks(html, pageUrl) {
-    let root;
-    try {
-        root = parse(scrubDangerousMarkup(html), { comment: false });
-    }
-    catch {
-        return [];
-    }
-    return collectLinksFromRoot(root, pageUrl);
-}

package/dist/sources/snapshot-fetchers/website-ingest.js

@@ -23,6 +23,9 @@ const CACHE_STALE_MS = 7 * 24 * 60 * 60 * 1000;
 const QUEUE_EXPANSION_FACTOR = 5;
 const MAX_PAGES_DEFAULT = 50;
 const MAX_DEPTH_DEFAULT = 3;
+/** Byte cap for the `llms.txt` manifest itself — a curated link list, never a large file. */
+const LLMS_TXT_BYTE_CAP = 512 * 1024;
+const LLMS_TXT_BODY_TIMEOUT_MS = 15_000;
 /**
  * Per-page body cap for website scraping. HTML pages this large are
  * almost never useful as agent knowledge sources and a runaway server
@@ -531,6 +534,38 @@ async function crawlWebsite(startUrl, options) {
         ? createAllowAllRobotsPolicy()
         : createRobotsPolicy((robotsUrl) => loadRobotsTxt(robotsUrl, { allowPrivateHosts: options.allowPrivateHosts, signal: crawlSignal }));
     await assertStartUrlAllowedByRobots(robots, start, options.rawStartUrl);
+    // llms.txt fast path: an increasing number of doc sites publish a curated,
+    // deduplicated link list at `/llms.txt` specifically for tools like this
+    // one. When present, use it as the crawl frontier instead of discovering
+    // links by parsing HTML — each linked page still goes through the exact
+    // same robots-compliant, host-guarded `fetchWebsitePage` call below, so
+    // ingested pages stay individually addressable. Gated to origin-root start
+    // URLs only (mirrors `extractGithubRepository`'s repo-root restriction):
+    // adding a specific page must fetch that page, not silently pull in the
+    // whole site's manifest.
+    if (isOriginRootUrl(start)) {
+        const manifest = await fetchLlmsManifest(start, robots, {
+            allowPrivateHosts: options.allowPrivateHosts,
+            signal: crawlSignal,
+        });
+        if (manifest) {
+            warn("[akm] Using llms.txt manifest from %s", manifest.manifestUrl);
+            queue.length = 0;
+            for (const link of manifest.links) {
+                // A manifest can name arbitrary hosts; only same-origin links are
+                // honored by default, same as links discovered mid-crawl below.
+                if (link.origin !== allowedOrigin)
+                    continue;
+                const candidate = normalizeCrawlUrl(link.toString());
+                if (!candidate)
+                    continue;
+                // depth = maxDepth: fetch each manifest page individually, but don't
+                // treat it as a fresh BFS seed — the manifest is already the
+                // author-curated set of pages worth ingesting.
+                queue.push({ url: candidate, rawUrl: link.toString(), depth: options.maxDepth, deferrals: 0 });
+            }
+        }
+    }
     // Counts actual `fetchWebsitePage` invocations (regardless of outcome) so
     // Crawl-delay pacing skips the first fetch and never charges a delay slot
     // to a URL that robots.txt skipped without ever being fetched (C-11).
@@ -870,6 +905,97 @@ function buildMarkdownSnapshot(page, slug, tags) {
         "",
     ].join("\n");
 }
+/**
+ * True for a start URL that names an origin's root (no path, no query).
+ * Matches how `extractGithubRepository` restricts its own special-case match
+ * to repository-root URLs — the llms.txt probe must not fire for a
+ * user-supplied deep link, or `akm bundle add <site>/guides/foo` would
+ * silently ingest the whole site's manifest instead of the page requested.
+ */
+export function isOriginRootUrl(url) {
+    return url.pathname === "/" && !url.search;
+}
+/**
+ * Parses the `llms.txt` link-list format: list items shaped like
+ * `- [title](path) - description` (the description, and its separator, are
+ * ignored — only the link target is needed). Any line that isn't a markdown
+ * link list item — headings, the leading `# Title`/`> summary` lines, prose —
+ * is simply not a link line and is skipped.
+ */
+export function parseLlmsTxtLinks(text, baseUrl) {
+    const links = [];
+    const seen = new Set();
+    for (const line of text.split(/\r?\n/)) {
+        const match = line.trim().match(/^-\s*\[[^\]]*\]\(([^)\s]+)\)/);
+        const href = match?.[1];
+        if (!href)
+            continue;
+        let resolved;
+        try {
+            resolved = new URL(href, baseUrl);
+        }
+        catch {
+            continue;
+        }
+        if (resolved.protocol !== "http:" && resolved.protocol !== "https:")
+            continue;
+        const key = resolved.toString();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        links.push(resolved);
+    }
+    return links;
+}
+/**
+ * Probes `<origin>/llms.txt` and, if present, returns its parsed link list.
+ * Reuses `fetchWebsiteResponse` so the manifest fetch itself gets the exact
+ * same SSRF host guard, redirect handling, and (via `robots`) robots.txt
+ * compliance as any other page fetch — this is still a fetch against a
+ * user-supplied host, no different from the rest of the crawl.
+ *
+ * `llms-full.txt` (the single-file concatenation of every page) is
+ * deliberately NOT read here. Its `## <path>` separators are ambiguous — page
+ * content legitimately contains `##` headings too — so recovered page
+ * boundaries can't be trusted, whereas per-page fetches through the existing
+ * pipeline are cheap, bounded by this author-curated list, and produce
+ * cleanly addressable assets. See the issue's "alternatives considered".
+ */
+async function fetchLlmsManifest(start, robots, options) {
+    const manifestUrl = new URL("/llms.txt", start.origin).toString();
+    const decision = await resolveCrawlRobotsDecision(robots, manifestUrl);
+    if (!decision.allowed)
+        return null;
+    let fetched;
+    try {
+        fetched = await fetchWebsiteResponse(decision.fetchUrl, 0, {
+            allowPrivateHosts: options.allowPrivateHosts,
+            signal: options.signal,
+            robots,
+        });
+    }
+    catch {
+        return null;
+    }
+    if (!fetched.response.ok) {
+        await fetched.response.body?.cancel().catch(() => undefined);
+        return null;
+    }
+    let text;
+    try {
+        text = await readBodyWithByteCap(fetched.response, LLMS_TXT_BYTE_CAP, {
+            bodyTimeoutMs: LLMS_TXT_BODY_TIMEOUT_MS,
+            signal: options.signal,
+        });
+    }
+    catch {
+        return null;
+    }
+    const links = parseLlmsTxtLinks(text, fetched.finalUrl);
+    if (links.length === 0)
+        return null;
+    return { manifestUrl: fetched.finalUrl, links };
+}
 function normalizeCrawlUrl(rawUrl) {
     try {
         const parsed = new URL(rawUrl);

package/dist/storage/managed-db.js

@@ -61,13 +61,19 @@ export function openManagedDatabase(spec) {
         // 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.inTransaction` is INSIDE the try: reading it on an already-closed
+        // handle throws "Database has closed", and it used to sit outside, so that
+        // throw escaped and replaced `error` — masking the real initializer failure
+        // this whole block exists to preserve. Every other step here was already
+        // guarded for exactly that reason; this one was not, and a concurrent
+        // close (WAL contention between two writers) reached it.
+        try {
+            if (db.inTransaction)
                 db.exec("ROLLBACK");
-            }
-            catch {
-                // Closing remains the final rollback backstop.
-            }
+        }
+        catch {
+            // Closing remains the final rollback backstop.
         }
         try {
             db.close();
@@ -99,6 +105,13 @@ export function withManagedDb(open, fn, opts) {
         return fn(db);
     }
     finally {
-        db.close();
+        try {
+            db.close();
+        }
+        catch {
+            // A close() throw here would REPLACE fn's in-flight exception — the same
+            // masking openManagedDatabase above was hardened against. The handle is
+            // being discarded either way; fn's error is the one that matters.
+        }
     }
 }

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

@@ -147,84 +147,3 @@ export function purgeOldEvents(db, retentionDays = 90) {
     const changes = result.changes ?? 0;
     return typeof changes === "bigint" ? Number(changes) : changes;
 }
-/**
- * Import all events from an `events.jsonl` file into the `events` table.
- *
- * The old byte-offset `id` is NOT preserved — the database assigns new
- * monotonic integer ids. Callers that persisted a byte-offset cursor must
- * discard it after migration and use the returned `maxId` as the new cursor.
- *
- * **Idempotency**: each line is pre-checked against the `events` table using
- * `(event_type, ts, ref, metadata_json)` as the duplicate key. Lines whose
- * exact tuple is already present are skipped and reported as `skipped` in the
- * return value. This makes the migration safe to re-run (the v0.7→v0.8
- * migration guide recommends re-running the script as a recovery path; without
- * this guard, every re-run would double-import the entire event log).
- *
- * Duplicate detection is per-import-tuple, not a table-wide UNIQUE constraint:
- * the events table has no UNIQUE constraint at runtime so that
- * `appendEvent` can write multiple events with the same ts (sub-millisecond
- * bursts produce identical `(event_type, ts, ref)` triples in practice). The
- * SELECT-first check is scoped to the import path only.
- *
- * The import is wrapped in a single transaction for atomicity.
- *
- * @param db       - Open state.db connection.
- * @param jsonlPath - Absolute path to the events.jsonl file to import.
- * @returns         Number of rows inserted, the max id assigned, and the
- *                  count of rows skipped because an identical event already
- *                  existed in the table.
- */
-export async function importEventsJsonl(db, jsonlPath) {
-    const { readFileSync, existsSync } = await import("node:fs");
-    if (!existsSync(jsonlPath)) {
-        return { imported: 0, maxId: 0, skipped: 0 };
-    }
-    const text = readFileSync(jsonlPath, "utf8");
-    const lines = text.split("\n").filter((l) => l.trim().length > 0);
-    let imported = 0;
-    let maxId = 0;
-    let skipped = 0;
-    const insertStmt = db.prepare(`INSERT INTO events (event_type, ts, ref, metadata_json)
-     VALUES (?, ?, ?, ?)
-     RETURNING id`);
-    // Dedup pre-check: matches by the full tuple including metadata_json so an
-    // import is idempotent over identical rows but does not collide with two
-    // genuinely different events that happen to share (event_type, ts, ref).
-    //
-    // Uses IS for ref so two NULL refs compare equal (a plain `=` would treat
-    // NULL = NULL as NULL and the row would be re-inserted on every run).
-    const existsStmt = db.prepare(`SELECT 1 FROM events
-     WHERE event_type = ?
-       AND ts = ?
-       AND ref IS ?
-       AND metadata_json = ?
-     LIMIT 1`);
-    db.transaction(() => {
-        for (const line of lines) {
-            let parsed;
-            try {
-                parsed = JSON.parse(line);
-            }
-            catch {
-                continue; // skip malformed lines — same behaviour as readEvents()
-            }
-            const eventType = typeof parsed.eventType === "string" ? parsed.eventType : "unknown";
-            const ts = typeof parsed.ts === "string" ? parsed.ts : new Date().toISOString();
-            const ref = typeof parsed.ref === "string" ? parsed.ref : null;
-            const metadata = parsed.metadata !== undefined && typeof parsed.metadata === "object" ? JSON.stringify(parsed.metadata) : "{}";
-            const duplicate = existsStmt.get(eventType, ts, ref, metadata);
-            if (duplicate) {
-                skipped++;
-                continue;
-            }
-            const result = insertStmt.get(eventType, ts, ref, metadata);
-            if (result) {
-                imported++;
-                if (result.id > maxId)
-                    maxId = result.id;
-            }
-        }
-    })();
-    return { imported, maxId, skipped };
-}

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

@@ -10,10 +10,12 @@
  * 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 { ConfigError } from "../../core/errors.js";
 import { classifyPathAccess, describeInaccessiblePath } from "../../core/path-access.js";
 import { getDbPath } from "../../core/paths.js";
+import { warn } from "../../core/warn.js";
 import { openDatabase } from "../database.js";
 import { openManagedDatabase } from "../managed-db.js";
 import { SQLITE_BUSY_TIMEOUT_MS } from "../sqlite-pragmas.js";
@@ -21,9 +23,23 @@ 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";
+/**
+ * Whether `error` is SQLite reporting on-disk corruption (`SQLITE_CORRUPT`,
+ * "database disk image is malformed") rather than a permission, lock, or
+ * schema problem. Matched on both `code` (bun:sqlite, better-sqlite3) and
+ * message text, since driver error shapes are not perfectly uniform.
+ */
+function isCorruptionError(error) {
+    const code = error?.code;
+    if (code === "SQLITE_CORRUPT")
+        return true;
+    const message = error instanceof Error ? error.message : String(error);
+    return message.includes("database disk image is malformed") || message.includes("SQLITE_CORRUPT");
+}
 export function openIndexDatabase(dbPath, options) {
-    return openManagedDatabase({
-        path: dbPath ?? getDbPath(),
+    const resolvedPath = dbPath ?? getDbPath();
+    const spec = {
+        path: resolvedPath,
         init: (db) => {
             // Try to load sqlite-vec extension
             loadVecExtension(db);
@@ -41,7 +57,33 @@ export function openIndexDatabase(dbPath, options) {
             // Warn once at init if using JS fallback with many entries
             warnIfVecMissing(db, { once: true });
         },
-    });
+    };
+    try {
+        return openManagedDatabase(spec);
+    }
+    catch (error) {
+        // index.db is a derived cache, fully regenerable from the stash on disk
+        // (see src/core/state-db.ts's "Why a separate database from index.db"
+        // note) — so real on-disk corruption is recovered by deleting the file
+        // and rebuilding, not by surfacing a raw SQLITE_CORRUPT to the caller or
+        // quietly falling through to an unreadable index. This mirrors the
+        // existing stale-version-marker rebuild below, one layer further down
+        // (that path opens fine and rewrites tables in place; corruption prevents
+        // even opening, so the file itself has to go first).
+        if (!isCorruptionError(error))
+            throw error;
+        warn(`Index database is corrupt at ${resolvedPath} — rebuilding.`);
+        for (const suffix of ["", "-wal", "-shm"]) {
+            try {
+                fs.rmSync(`${resolvedPath}${suffix}`, { force: true });
+            }
+            catch {
+                // Best-effort cleanup; the retried open below still fails loudly if
+                // the file could not actually be removed.
+            }
+        }
+        return openManagedDatabase(spec);
+    }
 }
 /**
  * Read the operator-configured embedding dimension from the on-disk config.

package/dist/storage/repositories/index-entries-repository.js

@@ -683,23 +683,6 @@ export function getEntryFilePathById(db, id) {
     const row = db.prepare("SELECT file_path FROM entries WHERE id = ?").get(id);
     return row?.file_path;
 }
-/**
- * Fetch every `(file_path, document_json)` row whose path is under a source
- * root. The path containment filter is applied in JS so SQLite LIKE wildcard
- * characters in filesystem paths cannot widen ownership.
- *
- * Lifted verbatim (WS5) from the inline query in commands/graph.ts'
- * `buildRefByPath`. The full result set is materialised with `.all()` before
- * return so callers can iterate it after the connection closes (WS5
- * connection-lifetime rule). JSON parsing stays with the caller, unchanged.
- */
-export function getEntryRefRowsForStashRoot(db, stashRoot) {
-    const root = path.resolve(stashRoot);
-    return db.prepare("SELECT file_path, document_json FROM entries").all().filter((row) => {
-        const file = path.resolve(row.file_path);
-        return file === root || file.startsWith(`${root}${path.sep}`);
-    });
-}
 // ── Indexer-phase helpers (moved from indexer.ts) ────────────────────────────
 /**
  * Return distinct zero-result search queries from the `usage_events` table

package/dist/storage/repositories/index-fts-repository.js

@@ -91,38 +91,32 @@ function runFtsQuery(db, ftsQuery, lexicalMatch, limit, entryType, excludeTypes)
     ORDER BY bm25Score, e.id ASC
     LIMIT ?
   `;
-    try {
-        const rows = db.prepare(sql).all(...params);
-        // Guard against corrupt JSON — skip the row rather than crashing
-        const results = [];
-        for (const row of rows) {
-            let entry;
-            try {
-                entry = JSON.parse(row.documentJson);
-            }
-            catch {
-                warn(`[db] searchFts: skipping entry id=${row.id} — corrupt document_json`);
-                continue;
-            }
-            results.push({
-                id: row.id,
-                filePath: row.filePath,
-                entry,
-                searchText: row.searchText,
-                bm25Score: row.bm25Score,
-                itemRef: row.itemRef,
-                bundleId: row.bundleId,
-                conceptId: row.conceptId,
-                adapterId: row.adapterId,
-                lexicalMatch,
-            });
+    const rows = db.prepare(sql).all(...params);
+    // Guard against corrupt JSON — skip the row rather than crashing
+    const results = [];
+    for (const row of rows) {
+        let entry;
+        try {
+            entry = JSON.parse(row.documentJson);
         }
-        return results;
-    }
-    catch (err) {
-        warn("[db] runFtsQuery failed:", err instanceof Error ? err.message : String(err));
-        return [];
+        catch {
+            warn(`[db] searchFts: skipping entry id=${row.id} — corrupt document_json`);
+            continue;
+        }
+        results.push({
+            id: row.id,
+            filePath: row.filePath,
+            entry,
+            searchText: row.searchText,
+            bm25Score: row.bm25Score,
+            itemRef: row.itemRef,
+            bundleId: row.bundleId,
+            conceptId: row.conceptId,
+            adapterId: row.adapterId,
+            lexicalMatch,
+        });
     }
+    return results;
 }
 /**
  * Explicitly rebuild the complete FTS5 projection from canonical entries.

package/dist/storage/repositories/index-utility-repository.js

@@ -263,63 +263,6 @@ function getSourceScopedRetrievalCounts(indexDb, stateDb, refs, options) {
     }
     return result;
 }
-/**
- * Apply a MemRL reward signal to a batch of entries via exponential moving
- * average (EMA): next = clamp(current + lr * (reward - current), 0, 1).
- *
- * Wrapped in a single transaction so all bumps succeed or fail together.
- * The indexer (`akm index`) will overwrite these values at next reindex run;
- * bumps are intentionally temporary hints between index runs, not permanent
- * overrides.
- *
- * When `scopeKey` is provided, also writes a scoped bump to
- * `utility_scores_scoped` so per-project usage signals accumulate alongside
- * the global ones. The global table is always updated regardless.
- */
-export function bumpUtilityScoresBatch(db, entryIds, reward, lr = 0.1, scopeKey) {
-    if (entryIds.length === 0)
-        return;
-    db.transaction(() => {
-        const { global: scoreMap } = getUtilityScoresByIds(db, entryIds);
-        const now = new Date().toISOString();
-        const nowMs = Date.now();
-        const stmt = db.prepare(`INSERT INTO utility_scores (entry_id, utility, show_count, search_count, select_rate, last_used_at, updated_at)
-       VALUES (?, ?, 0, 0, 0, ?, ?)
-       ON CONFLICT(entry_id) DO UPDATE SET
-         utility = excluded.utility,
-         updated_at = excluded.updated_at`);
-        // Prepare scoped upsert once outside the loop when scopeKey is present.
-        const scopedStmt = scopeKey
-            ? db.prepare(`INSERT INTO utility_scores_scoped (entry_id, scope_key, utility, last_used_at)
-           VALUES (?, ?, ?, ?)
-           ON CONFLICT(entry_id, scope_key) DO UPDATE SET
-             utility = excluded.utility,
-             last_used_at = excluded.last_used_at`)
-            : null;
-        for (const entryId of entryIds) {
-            const existing = scoreMap.get(entryId);
-            const current = existing?.utility ?? 0;
-            const next = Math.max(0, Math.min(1, current + lr * (reward - current)));
-            stmt.run(entryId, next, now, now);
-            if (scopedStmt && scopeKey) {
-                // Retrieve the current scoped utility so we can apply the same EMA.
-                const scopedCurrent = getScopedUtility(db, entryId, scopeKey);
-                const scopedNext = Math.max(0, Math.min(1, scopedCurrent + lr * (reward - scopedCurrent)));
-                scopedStmt.run(entryId, scopeKey, scopedNext, nowMs);
-            }
-        }
-    })();
-}
-/**
- * Return the current utility value for a single (entry_id, scope_key) pair.
- * Returns 0 when no row exists yet.
- */
-function getScopedUtility(db, entryId, scopeKey) {
-    const row = db
-        .prepare("SELECT utility FROM utility_scores_scoped WHERE entry_id = ? AND scope_key = ?")
-        .get(entryId, scopeKey);
-    return row?.utility ?? 0;
-}
 /**
  * Apply accumulated feedback counts to the utility score of an entry, persisting
  * the result. The bounded-step EMA policy itself (MemRL, F-5 / #386,