akm-cli 0.9.0-beta.9 → 0.9.0-rc.1

package/dist/indexer/passes/dir-staleness.js

@@ -0,0 +1,114 @@
+// 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/.
+/**
+ * Incremental dir-staleness engine.
+ *
+ * Decides, per stash directory, whether the directory's indexed rows are still
+ * fresh relative to what is on disk — so an incremental `akm index` run can
+ * skip unchanged directories instead of regenerating their metadata.
+ *
+ * Two persisted signals back the decision:
+ *   1. The `entries` rows already indexed for the directory (`getEntriesByDir`).
+ *   2. The `index_dir_state` fingerprint row (`getIndexDirState`), which caches
+ *      the file-set hash + max mtime for directories that legitimately produced
+ *      zero rows, so they are not rescanned every run.
+ *
+ * `computeDirFingerprint` derives the fingerprint (basename set + max mtime)
+ * that both the freshness check and the persisted `index_dir_state` row use.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { getEntriesByDir, getIndexDirState } from "../db/db.js";
+export function getDirIndexState(db, dirPath, files, builtAtMs) {
+    const prevEntries = getEntriesByDir(db, dirPath);
+    const fingerprint = computeDirFingerprint(dirPath, files);
+    if (prevEntries.length > 0) {
+        const staleReason = getDirStaleReason(dirPath, files, prevEntries, builtAtMs);
+        if (!staleReason) {
+            return { stale: false, reason: { kind: "unchanged" }, persistedRowCount: prevEntries.length };
+        }
+        return { stale: true, reason: staleReason, persistedRowCount: prevEntries.length };
+    }
+    const cachedState = getIndexDirState(db, dirPath);
+    if (cachedState &&
+        cachedState.fileSetHash === fingerprint.fileSetHash &&
+        cachedState.fileMtimeMaxMs === fingerprint.fileMtimeMaxMs) {
+        return {
+            stale: false,
+            reason: { kind: "cached-zero-row-state", detail: cachedState.reason },
+            persistedRowCount: 0,
+        };
+    }
+    return {
+        stale: true,
+        reason: { kind: "no-previous-rows", detail: cachedState ? `cached=${cachedState.reason}` : undefined },
+        persistedRowCount: 0,
+    };
+}
+export function getCachedZeroRowDirState(db, dirPath, files, builtAtMs, priorDirsChanged) {
+    const state = getDirIndexState(db, dirPath, files, builtAtMs);
+    if (state.stale || state.reason.kind !== "cached-zero-row-state")
+        return undefined;
+    if (!canUseIncrementalSkip(state, priorDirsChanged))
+        return undefined;
+    return state;
+}
+export function canUseIncrementalSkip(state, priorDirsChanged) {
+    return !(priorDirsChanged &&
+        state.reason.kind === "cached-zero-row-state" &&
+        state.reason.detail === "deduped-zero-row");
+}
+export function computeDirFingerprint(_dirPath, files) {
+    const normalizedFiles = [...new Set(files.map((file) => path.basename(file)))].sort();
+    let fileMtimeMaxMs = 0;
+    for (const file of files) {
+        try {
+            fileMtimeMaxMs = Math.max(fileMtimeMaxMs, fs.statSync(file).mtimeMs);
+        }
+        catch {
+            fileMtimeMaxMs = Number.POSITIVE_INFINITY;
+            break;
+        }
+    }
+    return {
+        fileSetHash: normalizedFiles.join("\0"),
+        fileMtimeMaxMs,
+    };
+}
+function getDirStaleReason(_dirPath, currentFiles, previousEntries, builtAtMs) {
+    const prevFileNames = new Set(previousEntries
+        .map((ie) => {
+        const fromPath = path.basename(ie.filePath);
+        return fromPath || ie.entry.filename;
+    })
+        .filter((e) => !!e));
+    const currFileNames = new Set(currentFiles.map((f) => path.basename(f)));
+    if (prevFileNames.size !== currFileNames.size) {
+        return { kind: "file-set-changed", detail: `${prevFileNames.size} -> ${currFileNames.size} files` };
+    }
+    for (const name of currFileNames) {
+        if (!prevFileNames.has(name))
+            return { kind: "file-set-changed", detail: name };
+    }
+    for (const file of currentFiles) {
+        try {
+            if (fs.statSync(file).mtimeMs > builtAtMs)
+                return { kind: "mtime-changed", detail: path.basename(file) };
+        }
+        catch {
+            return { kind: "missing-file", detail: path.basename(file) };
+        }
+    }
+    return undefined;
+}
+export function inferZeroRowReason(stash, priorReason, warnings, dirPath, dedupedRows) {
+    if (dedupedRows > 0)
+        return "deduped-zero-row";
+    const workflowNoise = warnings.some((warning) => warning.startsWith("Skipped workflow ") && warning.includes(dirPath));
+    if (workflowNoise)
+        return "workflow-noise";
+    if (!stash || stash.entries.length === 0)
+        return "empty-generated-set";
+    return `zero-row:${priorReason?.kind ?? "unknown"}`;
+}

package/dist/indexer/passes/memory-inference.js

@@ -72,6 +72,7 @@ const FM_CAPTURE_MODE = "captureMode";
  */
 export async function runMemoryInferencePass(ctx) {
     const { config, sources, signal, db, reEnrich, onProgress, options = {} } = ctx;
+    const compressMemoryToDerivedMemory = options.compressMemoryToDerivedMemory ?? memoryInfer.compressMemoryToDerivedMemory;
     const result = {
         considered: 0,
         cacheHits: 0,
@@ -172,14 +173,14 @@ export async function runMemoryInferencePass(ctx) {
             retryAttempts += 1;
         };
         const derived = db
-            ? await withLlmCache(db, record.filePath, record.body, reEnrich ?? false, () => memoryInfer.compressMemoryToDerivedMemory(llmConfig, record.body, signal, config, (evt) => {
+            ? await withLlmCache(db, record.filePath, record.body, reEnrich ?? false, () => compressMemoryToDerivedMemory(llmConfig, record.body, signal, config, (evt) => {
                 warn(`[akm] LLM fallback for ${evt.feature}: ${evt.reason}`);
             }, inferTelemetry, onRetryAttempt), validate, undefined, "", {
                 onCacheHit: () => {
                     fromCache = true;
                 },
             })
-            : await memoryInfer.compressMemoryToDerivedMemory(llmConfig, record.body, signal, config, (evt) => {
+            : await compressMemoryToDerivedMemory(llmConfig, record.body, signal, config, (evt) => {
                 warn(`[akm] LLM fallback for ${evt.feature}: ${evt.reason}`);
             }, inferTelemetry, onRetryAttempt);
         if (!derived) {
@@ -425,10 +426,17 @@ function markParentProcessed(parent) {
         warn(`memory inference: failed to re-read parent ${parent.filePath}: ${err instanceof Error ? err.message : String(err)}`);
         return;
     }
-    const updatedFm = { ...parent.data, [FM_INFERENCE_PROCESSED]: true };
     const block = parseFrontmatterBlock(raw);
-    const body = block?.content ?? raw;
-    const next = assembleAsset(updatedFm, body);
+    if (!block) {
+        // Cannot safely rewrite malformed frontmatter — skip marking so the memory
+        // is retried on the next run once the frontmatter is repaired. Writing with
+        // `body = raw` would wrap the entire file (including the bad frontmatter)
+        // in a new block, producing a duplicate-frontmatter corruption.
+        warn(`memory inference: skipping markParentProcessed for ${parent.filePath} — could not parse frontmatter block`);
+        return;
+    }
+    const updatedFm = { ...parent.data, [FM_INFERENCE_PROCESSED]: true };
+    const next = assembleAsset(updatedFm, block.content);
     try {
         fs.writeFileSync(parent.filePath, next, "utf8");
     }

package/dist/indexer/passes/metadata.js

@@ -191,6 +191,15 @@ export function validateStashEntry(entry) {
     const contradictedBy = normalizeNonEmptyStringList(e.contradictedBy);
     if (contradictedBy)
         result.contradictedBy = contradictedBy;
+    // R5 — consolidation provenance fields must survive the whitelist too, or
+    // stash.json-overridden merge products lose merge-following + generation
+    // counting in the collapse detector.
+    if (typeof e.generation === "number" && Number.isFinite(e.generation) && e.generation > 0) {
+        result.generation = Math.floor(e.generation);
+    }
+    const sourceRefs = normalizeNonEmptyStringList(e.sourceRefs);
+    if (sourceRefs)
+        result.sourceRefs = sourceRefs;
     const currentBeliefRefs = normalizeNonEmptyStringList(e.currentBeliefRefs);
     if (currentBeliefRefs)
         result.currentBeliefRefs = currentBeliefRefs;
@@ -342,6 +351,17 @@ export function applyCuratedFrontmatter(entry, fmData) {
     const contradictedBy = normalizeStringListOrUndefined(fmData.contradictedBy);
     if (contradictedBy)
         entry.contradictedBy = contradictedBy;
+    // R5 — consolidation provenance. `generation` (merge depth counter) and
+    // `source_refs` (merge/distill provenance pointers) are written by the
+    // improve pipeline; captured into the index so the collapse detector can
+    // count over-generation assets and follow merges without filesystem reads.
+    const generation = fmData.generation;
+    if (typeof generation === "number" && Number.isFinite(generation) && generation > 0) {
+        entry.generation = Math.floor(generation);
+    }
+    const sourceRefs = normalizeStringListOrUndefined(fmData.source_refs);
+    if (sourceRefs)
+        entry.sourceRefs = sourceRefs;
     const currentBeliefRefs = normalizeStringListOrUndefined(fmData.currentBeliefRefs);
     if (currentBeliefRefs)
         entry.currentBeliefRefs = currentBeliefRefs;

package/dist/indexer/read-preflight.js

@@ -0,0 +1,23 @@
+// 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 { ensureIndex } from "./ensure-index.js";
+import { resolveSourceEntries } from "./search/search-source.js";
+/** Resolve the active read sources using the same resolution rules as search/show. */
+export function resolveReadSources(overrideStashDir, existingConfig) {
+    const sources = resolveSourceEntries(overrideStashDir, existingConfig);
+    return { sources, primarySource: sources[0] };
+}
+/** Ensure the primary source index is readable for reads, when a primary exists. */
+export async function ensurePrimaryIndexForRead(primarySource) {
+    if (!primarySource?.path)
+        return false;
+    return ensureIndex(primarySource.path);
+}
+/**
+ * Convenience helper for callers that only need to ensure a read index from a
+ * configured stash path and default config.
+ */
+export async function ensurePrimaryIndexFromConfig(overrideStashDir, existingConfig) {
+    return ensurePrimaryIndexForRead(resolveReadSources(overrideStashDir, existingConfig).primarySource);
+}

package/dist/indexer/search/db-search.js

@@ -20,7 +20,7 @@ import { defaultRendererRegistry } from "../../core/asset/asset-registry.js";
 import { getDbPath } from "../../core/paths.js";
 import { warn } from "../../core/warn.js";
 import { getCurrentWorkflowScopeKey } from "../../workflows/authoring/scope-key.js";
-import { closeDatabase, getAllEntries, getEntryById, getEntryCount, getMeta, getPositiveFeedbackCountsByIds, openExistingDatabase, sanitizeFtsQuery, searchFts, searchVec, } from "../db/db.js";
+import { closeDatabase, getAllEntries, getBaseBeliefStatesForDerivedTwins, getEntryById, getEntryCount, getMeta, getPositiveFeedbackCountsByIds, openExistingDatabase, sanitizeFtsQuery, searchFts, searchVec, } from "../db/db.js";
 import { ensureIndex } from "../ensure-index.js";
 import { collectGraphRelatedHit, computeGraphBoost, loadGraphBoostContext, } from "../graph/graph-boost.js";
 import { isProposedQuality } from "../passes/metadata.js";
@@ -29,6 +29,29 @@ import { applyRankingRules, combineSearchScores, normalizeFtsScores } from "./ra
 import { enrichSearchHit } from "./search-hit-enrichers.js";
 import { buildEditHint, findSourceForPath, isEditable } from "./search-source.js";
 import { deriveSemanticProviderFingerprint, getEffectiveSemanticStatus, isSemanticRuntimeReady, readSemanticStatus, } from "./semantic-status.js";
+/**
+ * Age past which search surfaces a "run akm index" hint. Reads serve the
+ * existing index as-is (freshness is the writers' job — `indexWrittenAssets`
+ * plus full runs), so on installs with no improve cron a hand-edited or
+ * git-pulled file stays invisible until someone reindexes. The hint makes that
+ * actionable without re-introducing read-triggered reindexing.
+ */
+const STALE_INDEX_HINT_MS = 7 * 24 * 60 * 60 * 1000;
+function buildStaleIndexHint(db) {
+    try {
+        const builtAt = getMeta(db, "builtAt");
+        if (!builtAt)
+            return undefined;
+        const ageMs = Date.now() - new Date(builtAt).getTime();
+        if (!Number.isFinite(ageMs) || ageMs < STALE_INDEX_HINT_MS)
+            return undefined;
+        const days = Math.floor(ageMs / (24 * 60 * 60 * 1000));
+        return `Search index was last built ${days} day(s) ago. Files added or edited outside akm since then are not searchable — run 'akm index' to refresh.`;
+    }
+    catch {
+        return undefined;
+    }
+}
 export function buildLocalAction(type, ref, registry = defaultRendererRegistry) {
     return buildActionFromContributors({ type, ref }, defaultActionContributors(registry)) ?? `akm show ${ref}`;
 }
@@ -65,6 +88,9 @@ export async function searchLocal(input) {
     const includeProposed = input.includeProposed === true;
     const beliefFilter = input.beliefFilter ?? "all";
     const restrictToSources = input.restrictToSources === true;
+    const includeExcludedTypes = input.includeExcludedTypes === true;
+    const disableProjectContext = input.disableProjectContext === true;
+    const disableScopedUtility = input.disableScopedUtility === true;
     const rendererRegistry = input.rendererRegistry ?? defaultRendererRegistry;
     const allSourceDirs = sources.map((s) => s.path);
     const rawStatus = readSemanticStatus();
@@ -92,7 +118,9 @@ export async function searchLocal(input) {
     if (config.semanticSearchMode === "auto" && semanticStatus === "blocked") {
         warnings.push("Semantic search is currently blocked. Using keyword search until the semantic backend is healthy again.");
     }
-    // Auto-index when stale so the DB is always current before querying.
+    // Bootstrap-only: builds the index inline when it cannot serve this stash.
+    // Content freshness is the writers' job (indexWrittenAssets + full runs);
+    // reads serve the existing index as-is.
     await ensureIndex(stashDir);
     const dbPath = getDbPath();
     if (!fs.existsSync(dbPath)) {
@@ -114,7 +142,10 @@ export async function searchLocal(input) {
                 mode: "keyword",
             };
         }
-        const { hits, embedMs, rankMs } = await searchDatabase(db, query, searchType, limit, stashDir, allSourceDirs, config, sources, rendererRegistry, filters, includeProposed, beliefFilter, restrictToSources);
+        const staleHint = buildStaleIndexHint(db);
+        if (staleHint)
+            warnings.push(staleHint);
+        const { hits, embedMs, rankMs } = await searchDatabase(db, query, searchType, limit, stashDir, allSourceDirs, config, sources, rendererRegistry, filters, includeProposed, beliefFilter, restrictToSources, includeExcludedTypes, disableProjectContext, disableScopedUtility);
         return {
             hits,
             tip: hits.length === 0
@@ -131,14 +162,19 @@ export async function searchLocal(input) {
     }
 }
 // ── Database search ─────────────────────────────────────────────────────────
-async function searchDatabase(db, query, searchType, limit, stashDir, allSourceDirs, config, sources, rendererRegistry = defaultRendererRegistry, filters, includeProposed = false, beliefFilter = "all", restrictToSources = false) {
+async function searchDatabase(db, query, searchType, limit, stashDir, allSourceDirs, config, sources, rendererRegistry = defaultRendererRegistry, filters, includeProposed = false, beliefFilter = "all", restrictToSources = false, includeExcludedTypes = false, disableProjectContext = false, disableScopedUtility = false) {
     const hasSearchableTokens = query.length > 0 && sanitizeFtsQuery(query).length > 0;
+    // #627 — resolve the default type-exclusion policy. It applies ONLY on the
+    // untyped ('any') path and only when the caller did not opt back in via
+    // `includeExcludedTypes`. When the config key is ABSENT a built-in default of
+    // ['session'] is applied; an explicit empty list disables exclusion.
+    const defaultExcludes = searchType === "any" && !includeExcludedTypes ? (config.search?.defaultExcludeTypes ?? ["session"]) : [];
     // Empty queries — including ones that sanitize down to no searchable FTS
     // tokens such as "." — should enumerate matching entries instead of
     // returning an empty result set from FTS.
     if (!hasSearchableTokens) {
         const typeFilter = searchType === "any" ? undefined : searchType;
-        const allEntries = getAllEntries(db, typeFilter);
+        const allEntries = getAllEntries(db, typeFilter, defaultExcludes);
         // Deduplicate by file path — multiple entries can share the same file
         const seenFilePaths = new Set();
         const uniqueEntries = allEntries.filter((ie) => {
@@ -165,7 +201,11 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
         const qualityFiltered = includeProposed
             ? scopeFiltered
             : scopeFiltered.filter((ie) => !isProposedQuality(ie.entry.quality));
-        const beliefFiltered = qualityFiltered.filter((ie) => matchBeliefFilter(ie.entry.type, ie.entry.beliefState, beliefFilter));
+        // 03-R3: derived twins inherit their base's demoting belief state here too,
+        // so the belief FILTER (and the reported hit state) stays consistent on the
+        // enumerate/browse path — not only on the FTS-scored path below.
+        inheritDerivedTwinBeliefStates(db, qualityFiltered);
+        const beliefFiltered = qualityFiltered.filter((ie) => matchBeliefFilter(ie.entry.beliefState, beliefFilter));
         const selected = beliefFiltered.slice(0, limit);
         const hits = await Promise.all(selected.map((ie) => buildDbHit({
             entry: ie.entry,
@@ -187,7 +227,7 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
     const typeFilter = searchType === "any" ? undefined : searchType;
     const tEmbed0 = Date.now();
     const embeddingPromise = tryVecScores(db, query, limit * 3, config);
-    const ftsResults = searchFts(db, query, limit * 3, typeFilter);
+    const ftsResults = searchFts(db, query, limit * 3, typeFilter, defaultExcludes);
     const embeddingScores = await embeddingPromise;
     const embedMs = Date.now() - tEmbed0;
     const tRank0 = Date.now();
@@ -208,6 +248,11 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
         embedScoreMap,
         getEntryById: (id) => getEntryById(db, id) ?? undefined,
         typeFilter,
+        // #627 — also exclude default-hidden types from the vector-only branch so a
+        // session asset that is a top-k vector neighbor (but not an FTS match) does
+        // not leak into default ('any') results. defaultExcludes is already []
+        // unless this is the untyped path without includeExcludedTypes.
+        excludeTypes: defaultExcludes,
     });
     // ── Scoring Phase ──────────────────────────────────────────────────────
     // Apply boosts as multiplicative factors (all boosts in a single phase
@@ -236,7 +281,7 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
     // Resolve project-context tokens from the current working directory once
     // per search invocation. Returns null when running from home dir / /tmp,
     // or when the caller has set AKM_DISABLE_PROJECT_CONTEXT=1.
-    const projectContext = process.env.AKM_DISABLE_PROJECT_CONTEXT === "1" ? null : resolveProjectContext(process.cwd());
+    const projectContext = disableProjectContext ? null : resolveProjectContext(process.cwd());
     // Phase 2A / Rec 5: resolve forgetting-curve config and skip the feedback
     // count query when the boost cannot make a difference (default ≤ 1.0 means
     // boost^count == 1 — zero overhead for the common case).
@@ -256,11 +301,14 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
     // AKM_DISABLE_SCOPED_UTILITY=1 opts out (e.g. for registry searches or tests).
     let scopeKey;
     try {
-        scopeKey = process.env.AKM_DISABLE_SCOPED_UTILITY === "1" ? undefined : getCurrentWorkflowScopeKey();
+        scopeKey = disableScopedUtility ? undefined : getCurrentWorkflowScopeKey();
     }
     catch {
         // Non-fatal — ranking proceeds without scoped utility on any error.
     }
+    // 03-R3: derived twins inherit their base's demoting belief state before
+    // ranking, so the (03) belief-state ranker demotes a stale flag-free twin.
+    inheritDerivedTwinBeliefStates(db, scored);
     applyRankingRules({
         db,
         query,
@@ -317,7 +365,7 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
     const qualityFiltered = includeProposed
         ? scopeFiltered
         : scopeFiltered.filter((item) => !isProposedQuality(item.entry.quality));
-    const beliefFiltered = qualityFiltered.filter((item) => matchBeliefFilter(item.entry.type, item.entry.beliefState, beliefFilter));
+    const beliefFiltered = qualityFiltered.filter((item) => matchBeliefFilter(item.entry.beliefState, beliefFilter));
     const rankMs = Date.now() - tRank0;
     const selected = beliefFiltered.slice(0, limit);
     const hits = await Promise.all(selected.map(({ entry, filePath, score, rankingMode, utilityBoosted }) => {
@@ -345,11 +393,39 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
     }));
     return { embedMs, rankMs, hits };
 }
-function matchBeliefFilter(type, beliefState, filter) {
+/**
+ * 03-R3: let each `.derived` twin inherit its base memory's demoting belief
+ * state for this ranking pass, so a stale flag-free twin is demoted like its
+ * corrected base. The base carries the flag (a contradicted base takes a real
+ * ranking penalty); its near-duplicate `.derived` twin carries none and would
+ * otherwise outrank the corrected copy. Done in-memory at search time — NOT by
+ * writing the twin's frontmatter — because the SCC belief resolver refreshes any
+ * non-frozen state written to a derived memory back to `active` on the next
+ * improve run, erasing it. Only twins with no state of their own inherit; an
+ * explicit twin state always wins. Reuses the (03) belief-state ranker + filter.
+ */
+function inheritDerivedTwinBeliefStates(db, items) {
+    const DEMOTING = new Set(["contradicted", "superseded", "deprecated", "archived"]);
+    const twins = items.filter((it) => it.entry.type === "memory" &&
+        it.entry.beliefState === undefined &&
+        it.entry.name.toLowerCase().endsWith(".derived"));
+    if (twins.length === 0)
+        return;
+    const baseBeliefByTwinId = getBaseBeliefStatesForDerivedTwins(db, twins.map((t) => t.id));
+    for (const t of twins) {
+        const baseBelief = baseBeliefByTwinId.get(t.id);
+        // Only inherit DEMOTIONS — never let a base's active/asserted state lift a twin.
+        if (baseBelief && DEMOTING.has(baseBelief)) {
+            t.entry.beliefState = baseBelief;
+        }
+    }
+}
+function matchBeliefFilter(beliefState, filter) {
     if (filter === "all")
         return true;
-    if (type !== "memory")
-        return true;
+    // 03: the belief filter applies to ANY flagged entry, not just memories, so
+    // `current`/`historical` filters catch contradicted/superseded KNOWLEDGE too.
+    // Unflagged entries (beliefState === undefined) still pass the `current` filter.
     if (filter === "current") {
         // Phase 1A: `asserted` is a "current" state (stronger authority than `active`);
         // `deprecated` is excluded from current results.

package/dist/indexer/search/fts-query.js

@@ -0,0 +1,51 @@
+// 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/.
+/**
+ * Pure FTS5 query-string helpers, extracted from indexer/db/db.ts.
+ *
+ * These transform a raw user query into an FTS5-safe MATCH expression. They
+ * touch no database state, so they are unit-testable with zero DB setup.
+ */
+/**
+ * Sanitize a raw user query into an FTS5-safe implicit-AND expression.
+ *
+ * Allows only characters safe in FTS5 queries: letters, digits, underscores,
+ * and whitespace. Everything else (hyphens, dots, quotes, parens, asterisks,
+ * colons, carets, @, !, etc.) is replaced with a space so that compound
+ * identifiers like "code-review" or "k8s.setup" become AND-joined tokens
+ * ("code review", "k8s setup") rather than triggering FTS5 syntax errors.
+ */
+export function sanitizeFtsQuery(query) {
+    let sanitized = query.replace(/[^a-zA-Z0-9_\s]/g, " ");
+    // Neutralize the NEAR operator (FTS5 proximity syntax)
+    sanitized = sanitized.replace(/\bNEAR\b/g, " ");
+    const tokens = sanitized.split(/\s+/).filter((t) => t.length >= 1);
+    if (tokens.length === 0)
+        return "";
+    // Use implicit AND (space-separated tokens) for precision. FTS5 treats
+    // space-separated tokens as an implicit AND, matching only rows that
+    // contain ALL terms.
+    return tokens.join(" ");
+}
+/**
+ * Build a prefix query from an FTS5 query string by appending `*` to each
+ * token that is 3+ characters long. Tokens shorter than 3 characters are
+ * kept as-is (no prefix expansion) to avoid overly broad matches.
+ *
+ * Returns null if no tokens qualify for prefix expansion.
+ */
+export function buildPrefixQuery(ftsQuery) {
+    const tokens = ftsQuery.split(/\s+/).filter(Boolean);
+    let hasPrefix = false;
+    const prefixTokens = tokens.map((t) => {
+        if (t.length >= 3) {
+            hasPrefix = true;
+            return `${t}*`;
+        }
+        return t;
+    });
+    if (!hasPrefix)
+        return null;
+    return prefixTokens.join(" ");
+}

package/dist/indexer/search/ranking-contributors.js

@@ -9,11 +9,22 @@ const TYPE_BOOST = {
     agent: 0.3,
     script: 0.2,
     knowledge: 0.22,
+    // Facts are authoritative, durable declarations about the stash — rank them
+    // alongside knowledge so they surface reliably when relevant.
+    fact: 0.22,
     memory: -0.02,
 };
 const MAX_BOOST_SUM = 3.0;
 const UTILITY_WEIGHT = 0.5;
 const UTILITY_MAX_BOOST = 1.5;
+/**
+ * R2 (docs/design/improve-self-learning-analysis.md) — weight of the improve
+ * loop's `asset_salience.rank_score` in user-facing ranking. Bounded well
+ * below the utility boost so the composed signal refines, never dominates,
+ * lexical/semantic relevance. rank_score ∈ [0,1] → boost ∈ [1, 1.2].
+ */
+const SALIENCE_WEIGHT = 0.2;
+const SALIENCE_MAX_BOOST = 1.2;
 /**
  * Phase 2A / Rec 5: default recency half-life (days) used when no
  * `utilityDecayConfig` is supplied to the ranking pipeline. Matches the
@@ -29,8 +40,10 @@ const DEFAULT_RECENCY_HALF_LIFE_DAYS = 30;
 const FEEDBACK_HALF_LIFE_CAP_MULTIPLIER = 4;
 function beliefStateBoost(item) {
     const entry = item.entry;
-    if (entry.type !== "memory")
-        return 0;
+    // 03: belief-state penalties/boosts apply to ANY flagged entry (memory OR
+    // knowledge), so contradicted/superseded KNOWLEDGE is demoted from results
+    // just like flagged memories. Entries without a belief state fall through to
+    // the `return 0` below (default-safe — no effect on unflagged assets).
     // 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`.
@@ -76,14 +89,18 @@ const typeRankingContributor = {
         return TYPE_BOOST[item.entry.type] ?? 0;
     },
 };
-const memoryRankingContributor = {
-    name: "memory-ranking",
+const beliefStateRankingContributor = {
+    name: "belief-state-ranking",
     appliesTo(item) {
-        return item.entry.type === "memory";
+        // Fire for any entry that carries a belief state, regardless of type — so
+        // contradicted/superseded knowledge is demoted, not just memories. The
+        // `.derived`-twin `derivedBoost` (±0.12/−0.08) is deleted (03-R3): it made
+        // stale flag-free twins outrank their corrected base memory; belief-state
+        // demotion is the principled signal, not the twin-name heuristic.
+        return item.entry.beliefState !== undefined;
     },
     adjust(item) {
-        const derivedBoost = item.entry.name.toLowerCase().endsWith(".derived") ? 0.12 : -0.08;
-        return derivedBoost + beliefStateBoost(item);
+        return beliefStateBoost(item);
     },
 };
 const tagRankingContributor = {
@@ -206,6 +223,24 @@ const lessonStrengthContributor = {
         return Math.min(0.3, 0.06 * strength);
     },
 };
+/**
+ * Pinned-fact boost.
+ *
+ * Facts marked `pinned: true` form the small always-injected "core context"
+ * (see docs/design/fact-asset-type.md). The fact metadata contributor records
+ * a `pinned` search hint; here we give those facts a modest additive boost so
+ * the core outranks ordinary facts on otherwise-equal queries. Capped small so
+ * it cannot overpower an exact-name match.
+ */
+const pinnedFactRankingContributor = {
+    name: "pinned-fact-ranking",
+    appliesTo(item) {
+        return item.entry.type === "fact" && (item.entry.searchHints?.includes("pinned") ?? false);
+    },
+    adjust() {
+        return 0.15;
+    },
+};
 /**
  * Blend ratio for scoped vs. global utility signals.
  *
@@ -301,7 +336,7 @@ const projectContextRankingContributor = {
 export const defaultRankingContributors = [
     exactNameRankingContributor,
     typeRankingContributor,
-    memoryRankingContributor,
+    beliefStateRankingContributor,
     tagRankingContributor,
     searchHintRankingContributor,
     aliasRankingContributor,
@@ -310,9 +345,60 @@ export const defaultRankingContributors = [
     graphRankingContributor,
     captureModeRankingContributor,
     lessonStrengthContributor,
+    pinnedFactRankingContributor,
     projectContextRankingContributor,
 ];
-export const defaultUtilityRankingContributors = [utilityRankingContributor];
+/**
+ * R2 — compose the improve loop's salience core into user-facing ranking.
+ *
+ * `asset_salience.rank_score` (encoding + outcome + retrieval projection,
+ * maintained every improve run) previously drove only improve's INTERNAL
+ * maintenance selection — the "better assets surface more" loop ran solely
+ * through the utility EMA. This bounded multiplicative boost closes the outer
+ * loop: usage/outcome-reinforced assets rank higher in `search`/`curate`.
+ */
+const salienceRankingContributor = {
+    name: "salience-ranking",
+    appliesTo(item, ctx) {
+        const rank = ctx.salienceRankScores?.get(item.id);
+        return rank !== undefined && rank > 0;
+    },
+    apply(item, ctx) {
+        const rank = ctx.salienceRankScores?.get(item.id) ?? 0;
+        const rawBoost = 1 + Math.min(1, Math.max(0, rank)) * SALIENCE_WEIGHT;
+        item.score *= Math.min(rawBoost, SALIENCE_MAX_BOOST);
+    },
+};
+export const defaultUtilityRankingContributors = [
+    utilityRankingContributor,
+    salienceRankingContributor,
+];
+/**
+ * EVAL/DEBUG ONLY — remove named ranking contributors from a list.
+ *
+ * Driven by the `AKM_ABLATE_CONTRIBUTORS` env var (comma-separated contributor
+ * `name`s). A no-op — returns the input list unchanged (same reference) — when
+ * the env value is unset/empty, so production ranking is never affected unless
+ * the operator opts in. Its sole purpose is per-contributor ablation for the
+ * curate ablation harness (see `docs/technical/ranking-ablation-and-saturation-analysis.md`
+ * and `scripts/akm-eval/`): run the same fixture with and without a contributor
+ * and diff the ranked results to measure whether that contributor is load-bearing.
+ *
+ * NOTE (see the analysis doc): a contributor's ablation delta is only observable
+ * in the UNSATURATED score regime — once entries saturate at the `displayScore`
+ * ceiling their contributor deltas are absorbed and ablation reads Δ=0.
+ */
+export function applyContributorAblation(contributors, ablateEnv) {
+    if (!ablateEnv)
+        return contributors;
+    const ablated = new Set(ablateEnv
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean));
+    if (ablated.size === 0)
+        return contributors;
+    return contributors.filter((c) => !ablated.has(c.name));
+}
 export function applyScoreContributors(item, ctx, contributors = defaultRankingContributors) {
     let boostSum = 0;
     for (const contributor of contributors) {