akm-cli 0.9.0-rc.2 → 0.9.0-rc.3

package/dist/core/migration-operation.js

@@ -0,0 +1,44 @@
+// 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 crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { ConfigError } from "./errors.js";
+import { getConfigPath, getDataDir } from "./paths.js";
+let afterPendingCheckHook;
+/** TEST-ONLY: run once after a clear pending-operation check. */
+export function _setAfterPendingOperationCheckHookForTests(hook) {
+    afterPendingCheckHook = hook;
+}
+function installationId() {
+    return crypto
+        .createHash("sha256")
+        .update(path.resolve(path.dirname(getConfigPath())))
+        .update("\0")
+        .update(path.resolve(getDataDir()))
+        .digest("hex")
+        .slice(0, 24);
+}
+export function getMigrationOperationRoot() {
+    return path.join(getDataDir(), "backups", "migrations", installationId());
+}
+export function getMigrationRestoreJournalPath() {
+    return path.join(getMigrationOperationRoot(), "restore-active.json");
+}
+export function getMigrationApplyJournalPath() {
+    return path.join(getMigrationOperationRoot(), "apply-active.json");
+}
+export function assertNoPendingMigrationOperation() {
+    for (const [kind, journalPath] of [
+        ["restore", getMigrationRestoreJournalPath()],
+        ["migration apply", getMigrationApplyJournalPath()],
+    ]) {
+        if (fs.existsSync(journalPath)) {
+            throw new ConfigError(`AKM ${kind} recovery is pending at ${journalPath}; refusing canonical config/database access until recovery completes.`, "INVALID_CONFIG_FILE");
+        }
+    }
+    const hook = afterPendingCheckHook;
+    afterPendingCheckHook = undefined;
+    hook?.();
+}

package/dist/core/state/migrations.js

@@ -2,8 +2,7 @@
 // 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 { runMigrations as runSqliteMigrations } from "../../storage/engines/sqlite-migrations.js";
-import { ensureMigrationBackup } from "../migration-backup.js";
-const MIGRATIONS = [
+export const STATE_MIGRATIONS = [
     // ── Migration 001 — initial schema ──────────────────────────────────────────
     {
         id: "001-initial-schema",
@@ -776,10 +775,8 @@ const MIGRATIONS = [
  * Called automatically by `openStateDatabase()`.
  */
 export function runMigrations(db, options) {
-    runSqliteMigrations(db, MIGRATIONS, {
-        beforeMigration(migration) {
-            if (options?.ensureCutoverBackup && migration.id === "017-improve-run-strategy")
-                ensureMigrationBackup();
-        },
+    runSqliteMigrations(db, STATE_MIGRATIONS, {
+        applyPending: options?.applyPending,
+        generationMarker: options?.generationMarker,
     });
 }

package/dist/core/state-db.js

@@ -57,10 +57,13 @@
  */
 import fs from "node:fs";
 import path from "node:path";
+import { openDatabase } from "../storage/database.js";
+import { assertCurrentMigrationLedger, assertMigrationLedger } from "../storage/engines/sqlite-migrations.js";
 import { openManagedDatabase, withManagedDb, withManagedDbAsync } from "../storage/managed-db.js";
 import { acquireMaintenanceActivitySync } from "./maintenance-barrier.js";
-import { ensureMigrationBackup, getMigrationBackupDir } from "./migration-backup.js";
+import { assertNoPendingMigrationOperation } from "./migration-operation.js";
 import { getDataDir } from "./paths.js";
+import { runMigrations, STATE_MIGRATIONS } from "./state/migrations.js";
 // ── Path helper ──────────────────────────────────────────────────────────────
 /**
  * Default path: `<dataDir>/state.db`.
@@ -102,15 +105,28 @@ export function openStateDatabase(dbPath) {
     const canonicalPath = getStateDbPath();
     const resolvedPath = dbPath ?? canonicalPath;
     const isCanonical = path.resolve(resolvedPath) === path.resolve(canonicalPath);
+    if (isCanonical)
+        assertNoPendingMigrationOperation();
     const releaseActivity = isCanonical ? acquireMaintenanceActivitySync("state-db") : undefined;
     try {
-        // This must precede mkdir/open: opening an absent SQLite path creates it and
-        // would make the recovery manifest falsely record a fresh DB as pre-existing.
-        if (isCanonical && !fs.existsSync(getMigrationBackupDir()))
-            ensureMigrationBackup();
+        if (isCanonical)
+            assertNoPendingMigrationOperation();
+        const existed = fs.existsSync(resolvedPath);
+        if (existed) {
+            const preflight = openDatabase(resolvedPath, { readonly: true });
+            try {
+                if (isCanonical)
+                    assertCurrentMigrationLedger(preflight, STATE_MIGRATIONS);
+                else
+                    assertMigrationLedger(preflight, STATE_MIGRATIONS);
+            }
+            finally {
+                preflight.close();
+            }
+        }
         const db = openManagedDatabase({
             path: resolvedPath,
-            init: (db) => runMigrations(db, { ensureCutoverBackup: isCanonical }),
+            init: (db) => runMigrations(db, { applyPending: !(isCanonical && existed) }),
         });
         if (!releaseActivity)
             return db;
@@ -164,7 +180,6 @@ export function withStateDbAsync(fn, opts) {
 // The MIGRATIONS registry + runMigrations live in ./state/migrations (the single
 // append-only ordered source of truth). Imported for internal use by
 // openStateDatabase.
-import { runMigrations } from "./state/migrations.js";
 // ── BEGIN IMMEDIATE transaction helper ───────────────────────────────────────
 /**
  * Run `fn` inside a `BEGIN IMMEDIATE` transaction.

package/dist/core/write-source.js

@@ -13,8 +13,8 @@
  * commit behaviour — they only ever touch the filesystem. Git-backed targets
  * are committed in a SINGLE batch at the operation boundary via
  * {@link commitWriteTargetBoundary} (which delegates to `saveGitStash`). This
- * stages `.akm/` + sibling assets together as one complete commit instead of
- * one noisy, incomplete commit per asset.
+ * stages only operation-owned paths that still have a Git status entry as one
+ * complete commit instead of one noisy, incomplete commit per asset.
  *
  * This module is still the **single dispatch point** for write/delete: callers
  * (remember, import, source-add, etc.) MUST go through `writeAssetToSource` /
@@ -24,7 +24,7 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { getCachePaths, parseGitRepoUrl, saveGitStash } from "../sources/providers/git.js";
+import { getCachePaths, listGitChangedPaths, parseGitRepoUrl, saveGitStash } from "../sources/providers/git.js";
 import { makeAssetRef } from "./asset/asset-ref.js";
 import { resolveAssetPathFromName, TYPE_DIRS } from "./asset/asset-spec.js";
 import { isWithin, resolveStashDir } from "./common.js";
@@ -45,6 +45,30 @@ const REJECTED_WRITABLE_KINDS = new Set(["website", "npm"]);
  * stream a downstream consumer parses.
  */
 const COMMIT_MESSAGE_MAX_LENGTH = 4096;
+const pendingGitPaths = new Map();
+function gitTargetKey(source) {
+    return `${path.resolve(source.repoPath ?? source.path)}\0${path.resolve(source.path)}`;
+}
+/** Register a successful direct mutation for the target's exact-path boundary commit. */
+export function recordWriteTargetPath(source, filePath) {
+    if (source.kind !== "git")
+        return;
+    const key = gitTargetKey(source);
+    const paths = pendingGitPaths.get(key) ?? new Set();
+    paths.add(path.resolve(filePath));
+    pendingGitPaths.set(key, paths);
+}
+function takeGitTargetPaths(source) {
+    const key = gitTargetKey(source);
+    const absolutePaths = pendingGitPaths.get(key);
+    pendingGitPaths.delete(key);
+    if (!absolutePaths)
+        return [];
+    const repoDir = path.resolve(source.repoPath ?? source.path);
+    return [...absolutePaths]
+        .map((filePath) => path.relative(repoDir, filePath).replaceAll(path.sep, "/"))
+        .filter((filePath) => filePath && filePath !== ".." && !filePath.startsWith("../"));
+}
 /**
  * Sanitize a string before passing it as `git commit -m <message>`.
  *
@@ -161,6 +185,7 @@ export async function writeAssetToSource(source, config, ref, content) {
     fs.mkdirSync(path.dirname(filePath), { recursive: true });
     const normalized = content.endsWith("\n") ? content : `${content}\n`;
     fs.writeFileSync(filePath, normalized, "utf8");
+    recordWriteTargetPath(source, filePath);
     // Non-fatal portability advisory (review 13, D1): flag absolute host home
     // paths in the written content. These make the stash non-portable and leak
     // the local username. We warn AFTER the write so the advisory never blocks it.
@@ -185,6 +210,7 @@ export async function deleteAssetFromSource(source, config, ref) {
         throw new UsageError(`Asset "${formatRefForMessage(ref)}" not found in source "${source.name}" (expected at ${filePath}).`, "MISSING_REQUIRED_ARGUMENT");
     }
     fs.unlinkSync(filePath);
+    recordWriteTargetPath(source, filePath);
     return { path: filePath, ref: makeAssetRef(ref.type, ref.name, ref.origin) };
 }
 /**
@@ -196,9 +222,10 @@ export async function deleteAssetFromSource(source, config, ref) {
  * primary stash stay non-committing here — the primary stash is committed by
  * the existing improve auto-sync boundary).
  *
- * For a git target it delegates to `saveGitStash(name, message, writable, …)`,
- * which stages `.akm/` + sibling assets together (`git add -A`), commits once,
- * and pushes when the target is writable, has a remote, and `push !== false`.
+ * For a git target it delegates to `saveGitStash(name, message, writable, …)`
+ * with the exact paths recorded by the write/delete helpers (plus any explicit
+ * caller paths), commits once, and pushes when the target is writable, has a
+ * remote, and `push !== false`.
  *
  * The push intent honours a deprecated `options.pushOnCommit` on the source
  * config (mapped onto the batch push gate) when `push` is not explicitly set.
@@ -212,12 +239,16 @@ export function commitWriteTargetBoundary(target, message, options) {
     // gates the actual push on writable + remote, so this only ever opts *in*.
     const push = options?.push ?? (target.config.options?.pushOnCommit === true ? true : undefined);
     const writable = resolveWritable(target.config);
-    // Commit against the already-resolved repo directory (target.source.path)
-    // rather than re-resolving the stash by name through config. The write helper
-    // resolved this exact path; the boundary commit must operate on the SAME
-    // directory so the staged batch matches what was just written.
+    const repoDir = target.source.repoPath ?? target.source.path;
+    const changedPaths = new Set(listGitChangedPaths(repoDir));
+    const paths = [...new Set([...(options?.paths ?? []), ...takeGitTargetPaths(target.source)])]
+        .map((filePath) => filePath.replaceAll(path.sep, "/"))
+        .filter((filePath) => changedPaths.has(filePath));
+    // Assets may live under <repo>/content, but git synchronization always runs
+    // against the repository root.
     saveGitStash(undefined, message, writable, {
-        repoDir: target.source.path,
+        repoDir,
+        paths,
         ...(push === undefined ? {} : { push }),
     });
 }
@@ -239,6 +270,32 @@ function warnIfPushOnCommit(config) {
         "akm now commits writes in a single batch at the operation boundary and pushes when the target is " +
         "writable with a remote. Remove the option or rely on sync push instead.\n");
 }
+/** Enumerate enabled writable targets, deduplicated by materialized content root. */
+export function resolveWritableTargets(akmConfig) {
+    const byRoot = new Map();
+    for (const runtime of resolveConfiguredSources(akmConfig)) {
+        if (runtime.enabled === false || !resolveWritable({ type: runtime.type, writable: runtime.writable }))
+            continue;
+        const target = adaptConfiguredSource(runtime);
+        const root = path.resolve(target.source.path);
+        const existing = byRoot.get(root);
+        if (!existing || target.source.name === akmConfig.defaultWriteTarget)
+            byRoot.set(root, target);
+    }
+    if (byRoot.size === 0) {
+        try {
+            const stashDir = resolveStashDir({ readOnly: true });
+            byRoot.set(path.resolve(stashDir), {
+                source: { kind: "filesystem", name: "stash", path: stashDir },
+                config: { type: "filesystem", path: stashDir, name: "stash", writable: true },
+            });
+        }
+        catch {
+            // No active working stash; configured writable targets above are complete.
+        }
+    }
+    return [...byRoot.values()];
+}
 /**
  * Resolve the destination for a write per locked decision 3:
  *
@@ -250,8 +307,9 @@ function warnIfPushOnCommit(config) {
  * The legacy `first-writable-in-source-array-order` fallback is *not* used —
  * see plan §6 decision 3 for the rationale.
  */
-export function resolveWriteTarget(akmConfig, explicitTarget) {
+export function resolveWriteTarget(akmConfig, explicitTarget, options = {}) {
     const configuredSources = resolveConfiguredSources(akmConfig);
+    const requireWritable = options.requireWritable !== false;
     // 1. Explicit --target wins.
     if (explicitTarget) {
         const match = configuredSources.find((s) => s.name === explicitTarget);
@@ -264,7 +322,7 @@ export function resolveWriteTarget(akmConfig, explicitTarget) {
         // effective writable flag (filesystem defaults to true; everything else
         // defaults to false) so unset values are interpreted correctly.
         const effectiveWritable = resolveWritable({ type: match.type, writable: match.writable });
-        if (!effectiveWritable) {
+        if (requireWritable && !effectiveWritable) {
             throw new ConfigError(`source ${explicitTarget} is not writable`, "INVALID_CONFIG_FILE", `Set \`writable: true\` on the "${explicitTarget}" source in your config, or pass --target to a different source.`);
         }
         return adaptConfiguredSource(match);
@@ -279,7 +337,7 @@ export function resolveWriteTarget(akmConfig, explicitTarget) {
             // ConfigError, rather than surfacing as a generic UsageError after
             // path-building has already begun.
             const effectiveWritable = resolveWritable({ type: match.type, writable: match.writable });
-            if (!effectiveWritable) {
+            if (requireWritable && !effectiveWritable) {
                 throw new ConfigError(`defaultWriteTarget "${akmConfig.defaultWriteTarget}" is not writable`, "INVALID_CONFIG_FILE", `Set \`writable: true\` on the "${akmConfig.defaultWriteTarget}" source in your config, or change \`defaultWriteTarget\` to a writable source.`);
             }
             return adaptConfiguredSource(match);
@@ -366,8 +424,8 @@ export function formatRefForMessage(ref) {
  * `git` by the config loader, so this mapping is straightforward.
  */
 function adaptConfiguredSource(runtime) {
-    const writePath = pathFromConfiguredSource(runtime);
-    if (!writePath) {
+    const repoPath = pathFromConfiguredSource(runtime);
+    if (!repoPath) {
         throw new ConfigError(`Source "${runtime.name}" has no resolvable on-disk path; writes are unsupported for this entry.`, "INVALID_CONFIG_FILE");
     }
     // Map the runtime kind to the write helper's `kind` discriminator. Only
@@ -383,15 +441,25 @@ function adaptConfiguredSource(runtime) {
     const config = {
         type: runtime.type,
         name: runtime.name,
-        ...(writePath !== undefined ? { path: writePath } : {}),
+        ...(repoPath !== undefined ? { path: repoPath } : {}),
         ...(runtime.writable !== undefined ? { writable: runtime.writable } : {}),
         ...(runtime.options ? { options: runtime.options } : {}),
     };
     return {
-        source: { kind, name: runtime.name, path: writePath },
+        source: {
+            kind,
+            name: runtime.name,
+            path: kind === "git" ? resolveGitContentRoot(repoPath) : repoPath,
+            ...(kind === "git" ? { repoPath } : {}),
+        },
         config,
     };
 }
+/** Resolve the asset root inside a git checkout while preserving root-layout repos. */
+export function resolveGitContentRoot(repoPath) {
+    const contentPath = path.join(repoPath, "content");
+    return fs.existsSync(contentPath) && fs.statSync(contentPath).isDirectory() ? contentPath : repoPath;
+}
 function pathFromConfiguredSource(runtime) {
     // ConfiguredSource.source is the parsed SourceSpec (filesystem|git|website|npm).
     // For writable kinds we only ever care about a local on-disk path: filesystem

package/dist/indexer/db/db.js

@@ -351,9 +351,14 @@ export function getBaseBeliefStatesForDerivedTwins(db, twinIds) {
  * full `akm index` picks the file up as a fresh entry).
  */
 export function rekeyEntryInPlace(db, opts) {
-    const row = db.prepare("SELECT id, entry_json, search_text FROM entries WHERE entry_key = ?").get(opts.oldEntryKey);
+    const row = db
+        .prepare("SELECT id, stash_dir, entry_json, search_text FROM entries WHERE entry_key = ?")
+        .get(opts.oldEntryKey);
     if (!row)
         return null;
+    if (opts.sourceRoot && path.resolve(row.stash_dir) !== path.resolve(opts.sourceRoot)) {
+        throw new Error(`Refusing to re-key entry ${opts.oldEntryKey}: source root does not match.`);
+    }
     // Patch the JSON payload. On corrupt entry_json still re-key key + paths so
     // the utility history survives; the next full index heals the JSON.
     let entryJson = row.entry_json;
@@ -391,7 +396,7 @@ export function rekeyEntryInPlace(db, opts) {
         // the part after the last `//` (stored origins never contain `//`, so a
         // qualified ref has exactly one — same normalization as
         // getRetrievalCounts). Legacy DBs may predate usage_events.
-        bestEffort(() => {
+        try {
             // Live-asset-wins collision policy, mirroring the stale-entries eviction
             // above and mv's state.db re-key: DETACHED orphan events (entry_id NULL
             // — a deleted asset's history retained by a full rebuild) already
@@ -401,17 +406,30 @@ export function rekeyEntryInPlace(db, opts) {
             // moved asset would adopt the stranger's history: getRetrievalCounts
             // reads by entry_ref immediately, and the next full rebuild's
             // relinkUsageEvents would attach every stranger event by ref.
-            db.prepare("DELETE FROM usage_events WHERE entry_id IS NULL AND entry_ref = ?").run(opts.newRef);
-            db.prepare(`DELETE FROM usage_events
-          WHERE entry_id IS NULL
-            AND instr(entry_ref, '//') > 0
-            AND substr(entry_ref, instr(entry_ref, '//') + 2) = ?`).run(opts.newRef);
-            db.prepare("UPDATE usage_events SET entry_ref = ? WHERE entry_ref = ?").run(opts.newRef, opts.oldRef);
-            db.prepare(`UPDATE usage_events
-            SET entry_ref = substr(entry_ref, 1, instr(entry_ref, '//') + 1) || ?
-          WHERE instr(entry_ref, '//') > 0
-            AND substr(entry_ref, instr(entry_ref, '//') + 2) = ?`).run(opts.newRef, opts.oldRef);
-        }, "usage_events table may be missing on legacy DBs — no usage history to re-key");
+            if (opts.sourceName) {
+                const origins = new Set([opts.sourceName]);
+                if (opts.sourceName === "stash" && opts.includeLegacyBare)
+                    origins.add("local");
+                for (const origin of origins) {
+                    const oldQualifiedRef = `${origin}//${opts.oldRef}`;
+                    const newQualifiedRef = `${origin}//${opts.newRef}`;
+                    db.prepare("DELETE FROM usage_events WHERE entry_id IS NULL AND entry_ref = ?").run(newQualifiedRef);
+                    db.prepare("UPDATE usage_events SET entry_ref = ? WHERE entry_ref = ?").run(newQualifiedRef, oldQualifiedRef);
+                }
+            }
+            if (opts.includeLegacyBare || !opts.sourceName) {
+                db.prepare("DELETE FROM usage_events WHERE entry_id IS NULL AND entry_ref = ?").run(opts.newRef);
+                db.prepare("UPDATE usage_events SET entry_ref = ? WHERE entry_ref = ?").run(opts.newRef, opts.oldRef);
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const missingLegacyUsageSchema = /no such table:\s*(?:main\.)?usage_events\b/i.test(message) ||
+                /no such column:\s*(?:usage_events\.)?(?:entry_id|entry_ref)\b/i.test(message) ||
+                /table\s+usage_events\s+has no column named\s+(?:entry_id|entry_ref)\b/i.test(message);
+            if (!missingLegacyUsageSchema)
+                throw error;
+        }
         db.prepare("INSERT OR IGNORE INTO entries_fts_dirty (entry_id) VALUES (?)").run(row.id);
     })();
     return row.id;
@@ -884,7 +902,7 @@ export function getEntitiesByEntryIds(db, entryIds) {
     }
     return result;
 }
-export function findEntryIdByRef(db, ref) {
+export function findEntryIdByRef(db, ref, stashDir) {
     const parsed = parseAssetRef(ref);
     const nameVariants = [parsed.name];
     if (parsed.name.endsWith(".md")) {
@@ -893,10 +911,14 @@ export function findEntryIdByRef(db, ref) {
     else {
         nameVariants.push(`${parsed.name}.md`);
     }
-    const stmt = db.prepare("SELECT id FROM entries WHERE entry_type = ? AND substr(entry_key, length(entry_key) - length(?) + 1) = ? LIMIT 1");
+    const stmt = db.prepare(`SELECT id FROM entries
+     WHERE entry_type = ?
+       AND substr(entry_key, length(entry_key) - length(?) + 1) = ?
+       ${stashDir ? "AND stash_dir = ?" : ""}
+     LIMIT 1`);
     for (const name of nameVariants) {
         const suffix = `${parsed.type}:${name}`;
-        const row = stmt.get(parsed.type, suffix, suffix);
+        const row = stmt.get(parsed.type, suffix, suffix, ...(stashDir ? [stashDir] : []));
         if (row)
             return row.id;
     }
@@ -914,7 +936,7 @@ export function getEmbeddingCount(db) {
     return row.cnt;
 }
 export function getEntryById(db, id) {
-    const row = db.prepare("SELECT file_path, entry_json FROM entries WHERE id = ?").get(id);
+    const row = db.prepare("SELECT file_path, stash_dir, entry_json FROM entries WHERE id = ?").get(id);
     if (!row)
         return undefined;
     // Guard against corrupt JSON
@@ -926,7 +948,7 @@ export function getEntryById(db, id) {
         warn(`[db] getEntryById: skipping entry id=${id} — corrupt entry_json`);
         return undefined;
     }
-    return { filePath: row.file_path, entry };
+    return { filePath: row.file_path, stashDir: row.stash_dir, entry };
 }
 export function getEntriesByDir(db, dirPath) {
     const rows = db.prepare(`SELECT ${ENTRY_COLUMNS} FROM entries WHERE dir_path = ?`).all(dirPath);
@@ -1192,33 +1214,12 @@ function bareRef(ref) {
         return ref;
     }
 }
-/**
- * Count retrieval events for the given entry refs.
- *
- * Counts `search`, `show`, and `curate` usage events. Returns a
- * Map<inputRef, count> keyed by the *input* ref strings (only those with at
- * least one matching event appear). Used by the improve loop to find
- * high-retrieval assets without feedback.
- *
- * Matching is normalization-aware: each stored `entry_ref` is reduced to its
- * bare `type:name` form before comparison, so a stash-prefixed stored ref
- * (`origin//type:name`) still matches a bare input ref (`type:name`) and vice
- * versa. Previously the raw `entry_ref IN (...)` comparison silently dropped
- * roughly half the signal whenever the two spellings disagreed.
- *
- * `curate` events are included: their per-item rows are written with
- * entry_ref populated (see logCurateEvent), so curation is a real retrieval
- * signal here. Legacy summary-only curate rows with a NULL entry_ref simply
- * contribute nothing.
- *
- * Machine-sourced events (`source` = 'improve' or 'task') are EXCLUDED: this
- * count feeds salience/ranking, and pipeline probe traffic counting as demand
- * creates a self-reinforcing loop (meta-review 05 DRIFT-6). NULL sources
- * (pre-column rows) count as user demand.
- */
-export function getRetrievalCounts(db, refs) {
+export function getRetrievalCounts(db, refs, options = {}) {
     if (refs.length === 0)
         return new Map();
+    if (options.sourceName || options.stashDir) {
+        return getSourceScopedRetrievalCounts(db, refs, options);
+    }
     // Map each distinct bare form back to the input ref(s) that produced it so we
     // can re-key DB results (grouped by bare form) onto the caller's ref strings.
     const bareToInputs = new Map();
@@ -1274,6 +1275,55 @@ export function getRetrievalCounts(db, refs) {
     }
     return result;
 }
+function getSourceScopedRetrievalCounts(db, refs, options) {
+    const bareToInputs = new Map();
+    for (const ref of refs) {
+        const bare = bareRef(ref);
+        const inputs = bareToInputs.get(bare);
+        if (inputs)
+            inputs.push(ref);
+        else
+            bareToInputs.set(bare, [ref]);
+    }
+    const countsByBare = new Map();
+    const bareForms = [...bareToInputs.keys()];
+    const selectedRoot = options.stashDir ? path.resolve(options.stashDir) : undefined;
+    for (let i = 0; i < bareForms.length; i += SQLITE_CHUNK_SIZE) {
+        const chunk = bareForms.slice(i, i + SQLITE_CHUNK_SIZE);
+        const placeholders = chunk.map(() => "?").join(", ");
+        const rows = db
+            .prepare(`SELECT ue.entry_ref, ue.entry_id, e.stash_dir
+           FROM usage_events ue
+           LEFT JOIN entries e ON e.id = ue.entry_id
+          WHERE ue.event_type IN ('search','show','curate')
+            AND ue.entry_ref IS NOT NULL
+            AND (ue.source IS NULL OR ue.source NOT IN ('improve','task'))
+            AND CASE
+                  WHEN instr(ue.entry_ref, '//') > 0
+                    THEN substr(ue.entry_ref, instr(ue.entry_ref, '//') + 2)
+                  ELSE ue.entry_ref
+                END IN (${placeholders})`)
+            .all(...chunk);
+        for (const row of rows) {
+            const bare = bareRef(row.entry_ref);
+            const linkedToSelectedRoot = row.entry_id !== null && selectedRoot !== undefined && row.stash_dir !== null
+                ? path.resolve(row.stash_dir) === selectedRoot
+                : false;
+            const detached = row.entry_id === null || selectedRoot === undefined;
+            const qualifiedForSource = detached && options.sourceName !== undefined && row.entry_ref === `${options.sourceName}//${bare}`;
+            const acceptedLegacyBare = detached && options.includeLegacyBare === true && row.entry_ref === bare;
+            if (!linkedToSelectedRoot && !qualifiedForSource && !acceptedLegacyBare)
+                continue;
+            countsByBare.set(bare, (countsByBare.get(bare) ?? 0) + 1);
+        }
+    }
+    const result = new Map();
+    for (const [bare, count] of countsByBare) {
+        for (const input of bareToInputs.get(bare) ?? [])
+            result.set(input, count);
+    }
+    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).
@@ -1434,13 +1484,23 @@ export function applyFeedbackToUtilityScore(db, entryId, positiveCount, negative
   `).run(entryId, result.nextUtility, now, now, result.nextUtility, now);
     return result;
 }
+function resolveUsageEventEntryId(db, ref, options) {
+    const parsed = parseAssetRef(ref);
+    if (!parsed.origin) {
+        return options.defaultStashDir ? findEntryIdByRef(db, ref, options.defaultStashDir) : undefined;
+    }
+    const source = parsed.origin === "local" || parsed.origin === "stash"
+        ? options.sources?.[0]
+        : options.sources?.find((candidate) => candidate.registryId === parsed.origin);
+    return source ? findEntryIdByRef(db, ref, source.path) : undefined;
+}
 /**
  * Re-link detached usage_events to their current entry_ids via entry_ref.
  *
  * After a full rebuild, entry IDs change. This restores each event's link
  * using the stable `entry_ref` column so usage history survives a reindex.
  */
-export function relinkUsageEvents(db) {
+export function relinkUsageEvents(db, options = {}) {
     bestEffort(() => {
         // Step 1: null out stale entry_ids (entry was deleted, re-keyed, etc).
         // Leaving them in place would let `recomputeUtilityScores` aggregate
@@ -1455,14 +1515,10 @@ export function relinkUsageEvents(db) {
       WHERE entry_id IS NOT NULL
         AND entry_id NOT IN (SELECT id FROM entries)
     `);
-        // Step 2: re-resolve any null entry_id from entry_ref against the current
-        // entries table, reusing the SAME canonical resolver the read path uses at
-        // insert time (`findEntryIdByRef` → `parseAssetRef`). Resolving per DISTINCT
-        // ref keeps this O(distinct-refs) indexed lookups instead of the previous
-        // O(events × entries) non-indexable `substr(entry_key, …)` scan. It also
-        // fixes a silent correctness bug: the old suffix match compared the RAW
-        // `entry_ref`, so origin-qualified refs ("source//type:name") never matched
-        // an `entry_key` and lost their usage history on every full rebuild.
+        // Step 2: re-resolve each distinct ref inside its source boundary. Qualified
+        // refs require an origin→root mapping; bare legacy refs require the explicit
+        // historical/default root. This keeps duplicate refs from adopting whichever
+        // entries row SQLite happens to return first while retaining indexed lookups.
         const refs = db
             .prepare("SELECT DISTINCT entry_ref AS ref FROM usage_events WHERE entry_id IS NULL AND entry_ref IS NOT NULL")
             .all();
@@ -1471,7 +1527,7 @@ export function relinkUsageEvents(db) {
             for (const { ref } of refs) {
                 let id;
                 try {
-                    id = findEntryIdByRef(db, ref);
+                    id = resolveUsageEventEntryId(db, ref, options);
                 }
                 catch (err) {
                     if (err instanceof Error && err.name === "UsageError")