akm-cli 0.7.5 → 0.8.0-rc.10

package/dist/indexer/project-context.js

@@ -0,0 +1,192 @@
+// 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/.
+/**
+ * Project-context resolution for search ranking.
+ *
+ * Extracts meaningful identifier tokens from the current working directory
+ * so the ranking pipeline can boost assets that are relevant to the active
+ * project. Token extraction tries, in order:
+ *
+ *   1. `.git/config` remote-origin URL basename (strips `.git` extension)
+ *   2. `package.json` `name` field (last `/`-separated segment, minus common
+ *      framework suffixes)
+ *   3. Basename of the directory returned by `resolveWorkflowScopeAnchor`
+ *   4. `null` — no meaningful project context (home dir, /tmp, etc.)
+ *
+ * Tokens are lowercased, split on `[-_/]`, then filtered through a noise-word
+ * blocklist. A maximum of 5 tokens is kept.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { resolveWorkflowScopeAnchor } from "../workflows/scope-key.js";
+// Words that appear in almost every project name and carry no discriminating
+// signal for ranking. Filtered out after token splitting.
+const TOKEN_BLOCKLIST = new Set([
+    "my",
+    "the",
+    "app",
+    "lib",
+    "sdk",
+    "api",
+    "cli",
+    "tool",
+    "kit",
+    "core",
+    "main",
+    "index",
+    "src",
+    "test",
+]);
+// Common suffixes stripped from package.json `name` before tokenisation so
+// that e.g. `akm-cli` contributes `akm` rather than `akm` + `cli` (which is
+// in the blocklist anyway, but explicit stripping keeps the raw name shorter).
+const STRIP_SUFFIXES = ["-cli", "-app", "-lib", "-sdk", "-plugin"];
+const MAX_TOKENS = 5;
+// Paths that are definitely NOT a meaningful project root (home dir, tmp).
+// When `resolveWorkflowScopeAnchor` returns one of these we return `null`.
+function isNoiseRoot(dir) {
+    const homedir = os.homedir();
+    const normalized = dir.replace(/\/+$/, "");
+    if (normalized === homedir || normalized === homedir.replace(/\/+$/, ""))
+        return true;
+    // /tmp or /tmp/… (any depth)
+    if (normalized === "/tmp" || normalized.startsWith("/tmp/"))
+        return true;
+    // Windows-style temp
+    const tmpdir = os.tmpdir();
+    if (normalized === tmpdir || normalized.startsWith(tmpdir + path.sep))
+        return true;
+    return false;
+}
+/**
+ * Resolve the project context for the given working directory.
+ *
+ * @param cwd       - Directory to inspect. Defaults to `process.cwd()`.
+ * @param fsOverride - Optional FS override for unit testing.
+ * @returns `ProjectContext` with a non-empty `tokens` set, or `null` when no
+ *          meaningful context can be derived (home dir, /tmp, extraction failed).
+ */
+export function resolveProjectContext(cwd, fsOverride) {
+    const effectiveCwd = cwd ?? process.cwd();
+    const readFile = fsOverride?.readFileSync ?? ((p, enc) => fs.readFileSync(p, enc));
+    // Attempt 1 — git remote-origin URL
+    const gitConfigPath = path.join(effectiveCwd, ".git", "config");
+    const gitTokens = tryExtractGitTokens(gitConfigPath, readFile);
+    if (gitTokens !== null && gitTokens.size > 0) {
+        return { tokens: gitTokens };
+    }
+    // Attempt 2 — package.json name
+    const pkgJsonPath = path.join(effectiveCwd, "package.json");
+    const pkgTokens = tryExtractPackageJsonTokens(pkgJsonPath, readFile);
+    if (pkgTokens !== null && pkgTokens.size > 0) {
+        return { tokens: pkgTokens };
+    }
+    // Attempt 3 — workflow scope anchor basename
+    try {
+        const anchor = resolveWorkflowScopeAnchor(effectiveCwd);
+        if (isNoiseRoot(anchor))
+            return null;
+        const baseName = path.basename(anchor);
+        const tokens = tokenize(baseName);
+        if (tokens.size > 0) {
+            return { tokens };
+        }
+    }
+    catch {
+        // Ignore errors from scope anchor resolution (e.g. during testing).
+    }
+    return null;
+}
+// ── Private helpers ──────────────────────────────────────────────────────────
+/**
+ * Parse `.git/config` for the `[remote "origin"]` section and extract the
+ * repo name from the `url =` line.
+ *
+ *   url = git@github.com:itlackey/akm.git   → "akm"
+ *   url = https://github.com/itlackey/akm   → "akm"
+ */
+function tryExtractGitTokens(gitConfigPath, readFile) {
+    try {
+        const content = readFile(gitConfigPath, "utf-8");
+        const urlMatch = extractRemoteOriginUrl(content);
+        if (!urlMatch)
+            return null;
+        // Strip .git extension, then take the last path segment.
+        const withoutGit = urlMatch.replace(/\.git$/, "");
+        const segments = withoutGit.replace(/\/$/, "").split(/[/:]/).filter(Boolean);
+        const repoName = segments[segments.length - 1] ?? "";
+        const tokens = tokenize(repoName);
+        return tokens.size > 0 ? tokens : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Extracts the `url =` value from the `[remote "origin"]` section of a git
+ * config file. Returns `null` when the section or key is absent.
+ */
+function extractRemoteOriginUrl(content) {
+    // Split into sections delimited by `[...]` headers.
+    const lines = content.split(/\r?\n/);
+    let inOrigin = false;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith("[")) {
+            // New section header
+            inOrigin = /^\[remote\s+"origin"\]$/i.test(trimmed);
+            continue;
+        }
+        if (inOrigin) {
+            const m = trimmed.match(/^url\s*=\s*(.+)$/i);
+            if (m)
+                return m[1].trim();
+        }
+    }
+    return null;
+}
+/**
+ * Read `package.json` and extract the `name` field as tokens.
+ */
+function tryExtractPackageJsonTokens(pkgPath, readFile) {
+    try {
+        const content = readFile(pkgPath, "utf-8");
+        const parsed = JSON.parse(content);
+        if (typeof parsed.name !== "string" || !parsed.name)
+            return null;
+        // For scoped packages (@org/pkg-name) take the last `/`-separated segment.
+        const rawName = parsed.name.split("/").pop() ?? parsed.name;
+        // Strip common framework suffixes before tokenising.
+        let strippedName = rawName;
+        for (const suffix of STRIP_SUFFIXES) {
+            if (strippedName.endsWith(suffix)) {
+                strippedName = strippedName.slice(0, -suffix.length);
+                break; // only strip one suffix
+            }
+        }
+        const tokens = tokenize(strippedName);
+        return tokens.size > 0 ? tokens : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Split a raw name string into lowercase tokens, then filter through the
+ * blocklist and cap at `MAX_TOKENS`.
+ *
+ *   "akm-cli"   → Set { "akm" }
+ *   "my-app"    → Set {}  (all tokens blocked)
+ *   "openpalm"  → Set { "openpalm" }
+ */
+function tokenize(raw) {
+    const parts = raw
+        .toLowerCase()
+        .split(/[-_/]+/)
+        .filter(Boolean)
+        .filter((t) => !TOKEN_BLOCKLIST.has(t))
+        .slice(0, MAX_TOKENS);
+    return new Set(parts);
+}

package/dist/indexer/ranking-contributors.js

@@ -0,0 +1,331 @@
+// 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 { computeGraphBoost } from "./graph-boost";
+const TYPE_BOOST = {
+    skill: 0.4,
+    command: 0.35,
+    workflow: 0.35,
+    agent: 0.3,
+    script: 0.2,
+    knowledge: 0.22,
+    memory: -0.02,
+};
+const MAX_BOOST_SUM = 3.0;
+const UTILITY_WEIGHT = 0.5;
+const UTILITY_MAX_BOOST = 1.5;
+/**
+ * Phase 2A / Rec 5: default recency half-life (days) used when no
+ * `utilityDecayConfig` is supplied to the ranking pipeline. Matches the
+ * pre-2A hardcoded `RECENCY_DECAY_DAYS = 30` constant — the formula is
+ * default-safe and collapses to `exp(-days / 30)` when no overrides apply.
+ */
+const DEFAULT_RECENCY_HALF_LIFE_DAYS = 30;
+/**
+ * Cap on the effective half-life after applying the feedback stability
+ * boost — prevents indefinite half-life inflation for memories with many
+ * positive feedback events. `effectiveHalfLife = min(halfLife * boost^count, halfLife * 4)`.
+ */
+const FEEDBACK_HALF_LIFE_CAP_MULTIPLIER = 4;
+function beliefStateBoost(item) {
+    const entry = item.entry;
+    if (entry.type !== "memory")
+        return 0;
+    // Phase 1A: `asserted` and `deprecated` are first-class states.
+    // `asserted` carries stronger user-explicit authority than `active`.
+    // `deprecated` is a frozen historical state — penalized but milder than `superseded`.
+    if (entry.beliefState === "contradicted")
+        return -0.45;
+    if (entry.beliefState === "superseded")
+        return -0.25;
+    if (entry.beliefState === "archived")
+        return -0.6;
+    if (entry.beliefState === "deprecated")
+        return -0.15;
+    if (entry.beliefState === "asserted")
+        return 0.08;
+    if (entry.beliefState === "active")
+        return 0.06;
+    return 0;
+}
+const exactNameRankingContributor = {
+    name: "exact-name-ranking",
+    appliesTo: () => true,
+    adjust(item, ctx) {
+        const entry = item.entry;
+        const nameLower = entry.name.toLowerCase();
+        const rawNameBase = nameLower.split("/").pop() ?? nameLower;
+        const nameBase = entry.type === "memory" && rawNameBase.endsWith(".derived")
+            ? rawNameBase.slice(0, -".derived".length)
+            : rawNameBase;
+        if (nameBase === ctx.queryLower || nameLower === ctx.queryLower) {
+            return 2.0;
+        }
+        if (nameBase.includes(ctx.queryLower) || ctx.queryLower.includes(nameBase)) {
+            return 1.0;
+        }
+        const nameTokens = nameBase.split(/[-_\s]+/).filter(Boolean);
+        const matchCount = ctx.queryTokens.filter((qt) => nameTokens.some((nt) => nt === qt || nt.includes(qt))).length;
+        return matchCount > 0 ? Math.min(0.9, matchCount * 0.3) : 0;
+    },
+};
+const typeRankingContributor = {
+    name: "type-ranking",
+    appliesTo: () => true,
+    adjust(item) {
+        return TYPE_BOOST[item.entry.type] ?? 0;
+    },
+};
+const memoryRankingContributor = {
+    name: "memory-ranking",
+    appliesTo(item) {
+        return item.entry.type === "memory";
+    },
+    adjust(item) {
+        const derivedBoost = item.entry.name.toLowerCase().endsWith(".derived") ? 0.12 : -0.08;
+        return derivedBoost + beliefStateBoost(item);
+    },
+};
+const tagRankingContributor = {
+    name: "tag-ranking",
+    appliesTo(item) {
+        return Array.isArray(item.entry.tags) && item.entry.tags.length > 0;
+    },
+    adjust(item, ctx) {
+        let tagBoost = 0;
+        for (const tag of item.entry.tags ?? []) {
+            if (ctx.queryTokens.some((token) => tag.toLowerCase() === token))
+                tagBoost += 0.15;
+        }
+        return Math.min(0.3, tagBoost);
+    },
+};
+const searchHintRankingContributor = {
+    name: "search-hint-ranking",
+    appliesTo(item) {
+        return Array.isArray(item.entry.searchHints) && item.entry.searchHints.length > 0;
+    },
+    adjust(item, ctx) {
+        let hintBoost = 0;
+        for (const hint of item.entry.searchHints ?? []) {
+            const hintLower = hint.toLowerCase();
+            for (const token of ctx.queryTokens) {
+                if (hintLower.includes(token)) {
+                    hintBoost += 0.12;
+                    break;
+                }
+            }
+        }
+        return Math.min(0.24, hintBoost);
+    },
+};
+const aliasRankingContributor = {
+    name: "alias-ranking",
+    appliesTo(item) {
+        return Array.isArray(item.entry.aliases) && item.entry.aliases.length > 0;
+    },
+    adjust(item, ctx) {
+        let boost = 0;
+        for (const alias of item.entry.aliases ?? []) {
+            const aliasLower = alias.toLowerCase();
+            if (aliasLower === ctx.queryLower) {
+                boost += 1.5;
+                break;
+            }
+            if (ctx.queryTokens.some((token) => aliasLower.includes(token)))
+                boost += 0.3;
+        }
+        return boost;
+    },
+};
+const descriptionRankingContributor = {
+    name: "description-ranking",
+    appliesTo(item) {
+        return typeof item.entry.description === "string" && item.entry.description.length > 0;
+    },
+    adjust(item, ctx) {
+        const descLower = item.entry.description?.toLowerCase() ?? "";
+        const descMatchCount = ctx.queryTokens.filter((token) => descLower.includes(token)).length;
+        if (descMatchCount === ctx.queryTokens.length && ctx.queryTokens.length > 1)
+            return 0.25;
+        if (descMatchCount > 0)
+            return 0.1;
+        return 0;
+    },
+};
+const metadataRankingContributor = {
+    name: "metadata-ranking",
+    appliesTo: () => true,
+    adjust(item) {
+        let boost = item.entry.quality === "curated" ? 0.05 : 0;
+        if (typeof item.entry.confidence === "number") {
+            boost += Math.min(0.05, Math.max(0, item.entry.confidence) * 0.05);
+        }
+        return boost;
+    },
+};
+const graphRankingContributor = {
+    name: "graph-ranking",
+    appliesTo(_item, ctx) {
+        return ctx.graphContext !== null;
+    },
+    adjust(item, ctx) {
+        return ctx.graphContext ? computeGraphBoost(ctx.graphContext, item.filePath) : 0;
+    },
+};
+/**
+ * Capture-mode boost — Phase 1B / Rec 7.
+ *
+ * Memories captured via the hot path (`akm remember`) get a modest additive
+ * boost so they outrank otherwise-equal background-derived memories. Memories
+ * without `captureMode` (legacy) return 0 and rank exactly as before.
+ */
+const captureModeRankingContributor = {
+    name: "capture-mode-ranking",
+    appliesTo(item) {
+        return item.entry.type === "memory" && item.entry.captureMode === "hot";
+    },
+    adjust() {
+        return 0.2;
+    },
+};
+/**
+ * Lesson strength boost — Phase 7A / Advantage D4b.
+ *
+ * Each ref that has credited a lesson via `akm feedback --applied-to` adds
+ * 0.06 to the boost (capped at 0.3 ≈ five credits). Lessons without a
+ * `lessonStrength` array (or a number) return 0.
+ */
+const lessonStrengthContributor = {
+    name: "lesson-strength-ranking",
+    appliesTo(item) {
+        return (item.entry.type === "lesson" && typeof item.entry.lessonStrength === "number" && item.entry.lessonStrength > 0);
+    },
+    adjust(item) {
+        const strength = item.entry.lessonStrength ?? 0;
+        return Math.min(0.3, 0.06 * strength);
+    },
+};
+/**
+ * Blend ratio for scoped vs. global utility signals.
+ *
+ * When a scoped row exists: `effectiveUtility = scoped * 0.7 + global * 0.3`
+ * This ensures the in-project signal strongly dominates while the global
+ * cold-start signal still helps when scoped history is sparse.
+ */
+const SCOPED_UTILITY_BLEND_SCOPED = 0.7;
+const SCOPED_UTILITY_BLEND_GLOBAL = 1 - SCOPED_UTILITY_BLEND_SCOPED;
+const utilityRankingContributor = {
+    name: "utility-ranking",
+    appliesTo(item, ctx) {
+        const utilScore = ctx.utilityScores.get(item.id);
+        const scopedScore = ctx.scopedUtilityScores?.get(item.id);
+        return Boolean((utilScore && utilScore.utility > 0) || (scopedScore && scopedScore.utility > 0));
+    },
+    apply(item, ctx) {
+        const utilScore = ctx.utilityScores.get(item.id);
+        const scopedScore = ctx.scopedUtilityScores?.get(item.id);
+        // Determine effective utility: prefer scoped when present, blend with global.
+        const globalUtility = utilScore?.utility ?? 0;
+        const scopedUtility = scopedScore?.utility ?? 0;
+        const effectiveUtility = scopedUtility > 0
+            ? scopedUtility * SCOPED_UTILITY_BLEND_SCOPED + globalUtility * SCOPED_UTILITY_BLEND_GLOBAL
+            : globalUtility;
+        if (effectiveUtility <= 0)
+            return;
+        // Recency decay: use the global lastUsedAt for the decay factor (it's an
+        // ISO string with full resolution), falling back to scoped lastUsedAt (ms).
+        let recencyFactor = 1;
+        const lastUsedRaw = utilScore?.lastUsedAt ?? (scopedScore ? new Date(scopedScore.lastUsedAt).toISOString() : undefined);
+        if (lastUsedRaw) {
+            const lastUsedMs = new Date(lastUsedRaw).getTime();
+            const daysSinceLastUse = Number.isNaN(lastUsedMs)
+                ? Infinity
+                : Math.max(0, (Date.now() - lastUsedMs) / (1000 * 60 * 60 * 24));
+            // Phase 2A / Rec 5: configurable forgetting curve with optional
+            // feedback-stability boost. Absent config + absent positive feedback
+            // collapses to `exp(-days / 30)` — pre-2A default-safe.
+            const halfLifeDays = ctx.utilityDecayConfig?.halfLifeDays ?? DEFAULT_RECENCY_HALF_LIFE_DAYS;
+            const stabilityBoost = ctx.utilityDecayConfig?.feedbackStabilityBoost ?? 1.5;
+            const positiveCount = ctx.positiveFeedbackCounts?.get(item.id) ?? 0;
+            // `boost^count` is 1 when count is 0 OR when boost is 1.0, so neither
+            // a missing feedback count nor a "no boost" config widens the half-life.
+            let stabilizedHalfLife = halfLifeDays * stabilityBoost ** positiveCount;
+            stabilizedHalfLife = Math.min(stabilizedHalfLife, halfLifeDays * FEEDBACK_HALF_LIFE_CAP_MULTIPLIER);
+            // Defensive: half-life must stay positive to avoid div-by-zero / Infinity.
+            const safeHalfLife = Math.max(0.0001, stabilizedHalfLife);
+            recencyFactor = Math.exp(-daysSinceLastUse / safeHalfLife);
+        }
+        const rawBoost = 1 + effectiveUtility * recencyFactor * UTILITY_WEIGHT;
+        item.score *= Math.min(rawBoost, UTILITY_MAX_BOOST);
+        item.utilityBoosted = true;
+    },
+};
+/**
+ * Project-context boost.
+ *
+ * Auto-boosts assets whose name, tags, aliases, or search hints contain tokens
+ * derived from the current working directory's project name. For example, when
+ * running `akm search` from the `akm` git repo, assets tagged `akm` or named
+ * `akm-*` receive an additive boost.
+ *
+ * The boost is capped at 0.5 so it can never overpower an exact-name match
+ * (which contributes 2.0). Each matching token adds 0.2 up to the cap.
+ *
+ * Skipped entirely when `projectContext` is absent or has no tokens (e.g.
+ * when running from home dir, /tmp, or when disabled via
+ * `--no-project-context` / `AKM_DISABLE_PROJECT_CONTEXT=1`).
+ */
+const projectContextRankingContributor = {
+    name: "project-context-ranking",
+    appliesTo(_item, ctx) {
+        return ctx.projectContext != null && ctx.projectContext.tokens.size > 0;
+    },
+    adjust(item, ctx) {
+        if (!ctx.projectContext)
+            return 0;
+        const fields = [
+            item.entry.name ?? "",
+            ...(item.entry.tags ?? []),
+            ...(item.entry.aliases ?? []),
+            ...(item.entry.searchHints ?? []),
+        ].map((s) => s.toLowerCase());
+        let hits = 0;
+        for (const token of ctx.projectContext.tokens) {
+            if (fields.some((f) => f.includes(token)))
+                hits++;
+        }
+        return Math.min(0.5, hits * 0.2);
+    },
+};
+export const defaultRankingContributors = [
+    exactNameRankingContributor,
+    typeRankingContributor,
+    memoryRankingContributor,
+    tagRankingContributor,
+    searchHintRankingContributor,
+    aliasRankingContributor,
+    descriptionRankingContributor,
+    metadataRankingContributor,
+    graphRankingContributor,
+    captureModeRankingContributor,
+    lessonStrengthContributor,
+    projectContextRankingContributor,
+];
+export const defaultUtilityRankingContributors = [utilityRankingContributor];
+export function applyScoreContributors(item, ctx, contributors = defaultRankingContributors) {
+    let boostSum = 0;
+    for (const contributor of contributors) {
+        if (!contributor.appliesTo(item, ctx))
+            continue;
+        boostSum += contributor.adjust(item, ctx);
+    }
+    item.score *= 1 + Math.min(boostSum, MAX_BOOST_SUM);
+}
+export function applyUtilityContributors(item, ctx, contributors = defaultUtilityRankingContributors) {
+    for (const contributor of contributors) {
+        if (!contributor.appliesTo(item, ctx))
+            continue;
+        contributor.apply(item, ctx);
+    }
+}

package/dist/indexer/ranking.js

@@ -0,0 +1,81 @@
+// 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 { getUtilityScoresByIds } from "./db";
+import { applyScoreContributors, applyUtilityContributors } from "./ranking-contributors";
+export function normalizeFtsScores(results) {
+    const ftsScoreMap = new Map();
+    if (results.length === 0)
+        return ftsScoreMap;
+    const bestBm25 = results[0].bm25Score;
+    const worstBm25 = results[results.length - 1].bm25Score;
+    const range = bestBm25 - worstBm25;
+    for (const result of results) {
+        const normalized = range !== 0 ? (result.bm25Score - worstBm25) / range : 1.0;
+        const ftsScore = 0.3 + normalized * 0.7;
+        ftsScoreMap.set(result.id, { score: ftsScore, result });
+    }
+    return ftsScoreMap;
+}
+export function combineSearchScores(options) {
+    const FTS_WEIGHT = 0.7;
+    const VEC_WEIGHT = 0.3;
+    const scored = [];
+    const seenIds = new Set();
+    for (const [id, { score: ftsScore, result }] of options.ftsScoreMap) {
+        seenIds.add(id);
+        const embedScore = options.embedScoreMap.get(id);
+        const combinedScore = embedScore !== undefined ? ftsScore * FTS_WEIGHT + embedScore * VEC_WEIGHT : ftsScore;
+        scored.push({
+            id,
+            entry: result.entry,
+            filePath: result.filePath,
+            score: combinedScore,
+            rankingMode: embedScore !== undefined ? "hybrid" : "fts",
+        });
+    }
+    for (const [id, cosine] of options.embedScoreMap) {
+        if (seenIds.has(id))
+            continue;
+        const found = options.getEntryById(id);
+        if (!found)
+            continue;
+        if (options.typeFilter && found.entry.type !== options.typeFilter)
+            continue;
+        scored.push({
+            id,
+            entry: found.entry,
+            filePath: found.filePath,
+            score: cosine * VEC_WEIGHT,
+            rankingMode: "semantic",
+        });
+    }
+    return scored;
+}
+export function applyRankingRules(options) {
+    const queryTokens = options.query.toLowerCase().split(/\s+/).filter(Boolean);
+    const queryLower = options.query.toLowerCase().trim();
+    const rankingContext = {
+        db: options.db,
+        query: options.query,
+        queryLower,
+        queryTokens,
+        graphContext: options.graphContext,
+        projectContext: options.projectContext,
+    };
+    for (const item of options.items) {
+        applyScoreContributors(item, rankingContext);
+    }
+    const { global: utilScoresMap, scoped: scopedUtilScoresMap } = getUtilityScoresByIds(options.db, options.items.map((item) => item.id), options.scopeKey);
+    const utilityContext = {
+        ...rankingContext,
+        utilityScores: utilScoresMap,
+        scopedUtilityScores: scopedUtilScoresMap,
+        utilityDecayConfig: options.utilityDecayConfig,
+        positiveFeedbackCounts: options.positiveFeedbackCounts,
+    };
+    for (const item of options.items) {
+        applyUtilityContributors(item, utilityContext);
+    }
+    return options.items;
+}

package/dist/indexer/search-fields.js

@@ -1,12 +1,6 @@
-/**
- * Per-field search text extraction for FTS5 indexing.
- *
- * Extracted from indexer.ts to break the circular dependency:
- *   db.ts -> indexer.ts -> db.ts
- *
- * This module imports only from metadata.ts (for the StashEntry type),
- * so it can be safely imported by both db.ts and indexer.ts.
- */
+// 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/.
 /**
  * Return per-field search text for multi-column FTS5 indexing.
  *
@@ -45,6 +39,8 @@ export function buildSearchFields(entry) {
         hintParts.push(entry.xrefs.join(" "));
     if (entry.pageKind)
         hintParts.push(entry.pageKind);
+    if (entry.whenToUse)
+        hintParts.push(entry.whenToUse);
     const hints = hintParts.join(" ").toLowerCase();
     const contentParts = [];
     if (entry.toc) {