akm-cli 0.9.0-rc.0 → 0.9.0-rc.13

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

@@ -1,8 +1,20 @@
 // 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 { isKnownType } from "../../core/recognition-util.js";
 import { computeGraphBoost } from "../graph/graph-boost.js";
-const TYPE_BOOST = {
+import { attachSearchHitAttribution } from "./search-attribution.js";
+/**
+ * Chunk 1.5 (D1.5-5) — retyped from `Record<string, number>` to a FULL
+ * `Record<KnownType, number>`. Only 8/14 types carried an entry before this
+ * chunk (`env`, `secret`, `wiki`, `lesson`, `task`, `session` silently fell
+ * through to the `?? 0` fallback at the sole consumer,
+ * {@link typeRankingContributor}). The 6 additions below are explicit `0`
+ * entries — behavior-preserving (they already defaulted to `0`), but now
+ * compile-time-exhaustive: adding a new `KNOWN_TYPE` forces an explicit
+ * boost decision instead of silently defaulting.
+ */
+export const TYPE_BOOST = {
     skill: 0.4,
     command: 0.35,
     workflow: 0.35,
@@ -12,19 +24,46 @@ const TYPE_BOOST = {
     // Facts are authoritative, durable declarations about the stash — rank them
     // alongside knowledge so they surface reliably when relevant.
     fact: 0.22,
+    // Instruction files (CLAUDE.md / AGENTS.md) are project instructions read
+    // like knowledge (maintainer resolution 2026-07) — rank them alongside
+    // knowledge so they surface reliably when relevant.
+    instruction: 0.22,
     memory: -0.02,
+    // Chunk 1.5: previously-absent entries, all defaulted to 0 pre-chunk —
+    // explicit now, unchanged in effect.
+    env: 0,
+    secret: 0,
+    lesson: 0,
+    task: 0,
+    session: 0,
 };
+/**
+ * Open-string accessor over {@link TYPE_BOOST} (plan §2.3 "ranking
+ * accessor"). Foreign/unknown types (outside `KNOWN_TYPES`) fall back to `0`
+ * — identical to the old `TYPE_BOOST[item.entry.type] ?? 0` behavior on a
+ * loosely-typed `Record<string, number>`, now expressed safely over the
+ * exhaustive `Record<KnownType, number>`.
+ */
+export function typeBoostFor(type) {
+    return isKnownType(type) ? TYPE_BOOST[type] : 0;
+}
 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].
+ * R2 / #692 — weight of the improve loop's `asset_salience.rank_score`.
+ * rank_score ∈ [0,1] → boost ∈ [1, 1.2]. Bounded well below the utility boost
+ * so the composed signal would refine, never dominate, lexical/semantic
+ * relevance.
+ *
+ * As of #692 this is NOT wired into default user-facing ranking — see
+ * {@link salienceRankingContributor}'s doc comment. Kept exported (with the
+ * contributor) for a future gated experiment; do not reintroduce it into
+ * {@link defaultUtilityRankingContributors} without a measured
+ * curate-golden-bench delta and an explicit config gate.
  */
-const SALIENCE_WEIGHT = 0.2;
-const SALIENCE_MAX_BOOST = 1.2;
+export const SALIENCE_WEIGHT = 0.2;
+export 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
@@ -61,6 +100,54 @@ function beliefStateBoost(item) {
         return 0.06;
     return 0;
 }
+/**
+ * Post-boost score ceilings for the demoting belief states (SPEC-5,
+ * stash-conventions-code-spec.md — corrections demotion).
+ *
+ * Why the additive {@link beliefStateBoost} penalties alone are not enough:
+ * keyword base scores are min-max normalized into [0.3, 1.0]
+ * (`normalizeFtsScores`), so the spread between the best FTS hit and its
+ * runner-up can be as large as 0.7 — and the boost sum then MULTIPLIES the
+ * base (`score *= 1 + boostSum`, {@link applyScoreContributors}). A
+ * superseded incumbent that is the best keyword match for a query therefore
+ * stays clamp-pinned at 1.0 above its own correction no matter what additive
+ * penalty it receives — defeating the corrections pattern's point ("so the
+ * ranker demotes the stale version instead of letting it outrank your fix").
+ *
+ * The ceilings guarantee the demotion while keeping flagged entries VISIBLE:
+ * un-demoted keyword hits floor at a 0.3 base, so any un-demoted hit outranks
+ * a ceilinged one; demoted entries still list (belief FILTERING stays a
+ * separate opt-in axis, `--belief`), and scores already below a ceiling keep
+ * their relative ordering. Ceiling order mirrors the additive-penalty
+ * severity order pinned in tests/integration/belief-state-phase1a.test.ts:
+ * deprecated (mildest) > superseded > contradicted > archived.
+ */
+const BELIEF_STATE_SCORE_CEILINGS = {
+    deprecated: 0.28,
+    superseded: 0.25,
+    contradicted: 0.2,
+    archived: 0.15,
+};
+/**
+ * Clamp a ranked entry's FINAL score (after every additive and utility boost)
+ * to its demoting belief state's ceiling. No-op for `asserted`/`active`/unset
+ * entries. Applied once per item at the end of `applyRankingRules` so sort
+ * order and displayed scores stay consistent (single scoring pipeline).
+ *
+ * When the ceiling clamps, the pre-clamp score is recorded as
+ * `preCeilingScore` so db-search's semantic-only `minScore` floor can judge
+ * the hit by what it would have scored WITHOUT the demotion — a ceiling below
+ * the floor (archived 0.15 < default minScore 0.2) must demote a hit to last
+ * place, never silently drop it from the results.
+ */
+export function applyBeliefStateScoreCeiling(item) {
+    const state = item.entry.beliefState;
+    const ceiling = state !== undefined ? BELIEF_STATE_SCORE_CEILINGS[state] : undefined;
+    if (ceiling !== undefined && item.score > ceiling) {
+        item.preCeilingScore = item.score;
+        item.score = ceiling;
+    }
+}
 const exactNameRankingContributor = {
     name: "exact-name-ranking",
     appliesTo: () => true,
@@ -86,7 +173,7 @@ const typeRankingContributor = {
     name: "type-ranking",
     appliesTo: () => true,
     adjust(item) {
-        return TYPE_BOOST[item.entry.type] ?? 0;
+        return typeBoostFor(item.entry.type);
     },
 };
 const beliefStateRankingContributor = {
@@ -189,13 +276,27 @@ const graphRankingContributor = {
     adjust(item, ctx) {
         return ctx.graphContext ? computeGraphBoost(ctx.graphContext, item.filePath) : 0;
     },
+    applied(item, ctx, contribution) {
+        if (!ctx.graphContext || contribution <= 0)
+            return;
+        const graphNode = ctx.graphContext.nodesByPath.get(item.filePath);
+        attachSearchHitAttribution(item, {
+            graphExtraction: {
+                boost: contribution,
+                ...(graphNode?.bodyHash ? { bodyHash: graphNode.bodyHash } : {}),
+                ...((graphNode?.extractionRunId ?? ctx.graphContext.graph.telemetry?.extractionRunId)
+                    ? { extractionRunId: graphNode?.extractionRunId ?? ctx.graphContext.graph.telemetry?.extractionRunId }
+                    : {}),
+            },
+        });
+    },
 };
 /**
  * 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.
+ * without `captureMode` return 0.
  */
 const captureModeRankingContributor = {
     name: "capture-mode-ranking",
@@ -227,7 +328,7 @@ const lessonStrengthContributor = {
  * 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
+ * (see docs/architecture/specs/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.
@@ -309,7 +410,7 @@ const utilityRankingContributor = {
  *
  * 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`).
+ * `--no-project-context`).
  */
 const projectContextRankingContributor = {
     name: "project-context-ranking",
@@ -349,15 +450,31 @@ export const defaultRankingContributors = [
     projectContextRankingContributor,
 ];
 /**
- * R2 — compose the improve loop's salience core into user-facing ranking.
+ * R2 — the improve loop's salience core, as a bounded multiplicative ranking
+ * boost. `asset_salience.rank_score` (encoding + outcome + retrieval
+ * projection, maintained every improve run) otherwise drives only improve's
+ * INTERNAL maintenance selection.
  *
- * `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`.
+ * **#692 — NOT in {@link defaultUtilityRankingContributors}.** Removed from
+ * default user-facing ranking (search/curate): the boost was
+ * retrieval-dominated (`w_r = 0.60` in salience.ts, with no source filter, so
+ * it double-counted the same `usage_events` the utility EMA contributor
+ * already reinforces), warm-started non-zero with no outcome evidence, had
+ * zero pack coverage (favoring only self-generated personal assets), and
+ * measured as noise on live data (max observed multiplier ×1.071). Removing
+ * its default state.db load also deleted a confirmed hot-path defect — see
+ * the now-deleted `loadSalienceRankScores` in `ranking.ts` git history.
+ *
+ * `rank_score` itself is UNCHANGED as improve's internal selection signal.
+ * This contributor, and its weight/cap constants, stay exported so a FUTURE
+ * gated experiment (config-gated, outcome-gated) can wire it back in
+ * explicitly — see `RankEntriesOptions.salienceRankScores`'s doc comment in
+ * `ranking.ts`. Reachable today only via explicit contributor-list injection
+ * (tests / eval harnesses calling `applyUtilityContributors` directly with a
+ * list that includes it) — never through `applyRankingRules` / `akm search` /
+ * `akm curate`.
  */
-const salienceRankingContributor = {
+export const salienceRankingContributor = {
     name: "salience-ranking",
     appliesTo(item, ctx) {
         const rank = ctx.salienceRankScores?.get(item.id);
@@ -369,10 +486,10 @@ const salienceRankingContributor = {
         item.score *= Math.min(rawBoost, SALIENCE_MAX_BOOST);
     },
 };
-export const defaultUtilityRankingContributors = [
-    utilityRankingContributor,
-    salienceRankingContributor,
-];
+// #692 — salienceRankingContributor deliberately excluded; see its doc
+// comment. Do not add it back here without a config gate + a measured
+// curate-golden-bench delta justifying it.
+export const defaultUtilityRankingContributors = [utilityRankingContributor];
 /**
  * EVAL/DEBUG ONLY — remove named ranking contributors from a list.
  *
@@ -380,11 +497,10 @@ export const defaultUtilityRankingContributors = [
  * `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
+ * curate ablation harness (`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
+ * NOTE (from the 2026-06 ablation analysis): 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.
  */
@@ -404,7 +520,11 @@ export function applyScoreContributors(item, ctx, contributors = defaultRankingC
     for (const contributor of contributors) {
         if (!contributor.appliesTo(item, ctx))
             continue;
+        const cappedBefore = Math.min(boostSum, MAX_BOOST_SUM);
         boostSum += contributor.adjust(item, ctx);
+        // Attribution receives only the share admitted by the common boost cap,
+        // never a raw contributor value that scoring discarded.
+        contributor.applied?.(item, ctx, Math.min(boostSum, MAX_BOOST_SUM) - cappedBefore);
     }
     item.score *= 1 + Math.min(boostSum, MAX_BOOST_SUM);
 }

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

@@ -0,0 +1,4 @@
+// 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/.
+export {};

package/dist/indexer/search/ranking.js

@@ -1,68 +1,8 @@
 // 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 fs from "node:fs";
-import { makeAssetRef } from "../../core/asset/asset-ref.js";
-import { getStateDbPath } from "../../core/state-db.js";
-import { openDatabase } from "../../storage/database.js";
-import { getUtilityScoresByIds } from "../db/db.js";
-import { applyContributorAblation, applyScoreContributors, applyUtilityContributors, defaultRankingContributors, defaultUtilityRankingContributors, } from "./ranking-contributors.js";
-/**
- * R2 — best-effort load of `asset_salience.rank_score` from state.db for the
- * ranked items. Fail-open: any error (state.db locked by a concurrent improve
- * run, missing table, unreadable path) returns an empty map, which makes the
- * salience contributor a no-op — byte-identical to pre-R2 ranking.
- *
- * Deliberately NOT `openStateDatabase()`: that helper runs migrations and sets
- * a 30 s busy timeout — too heavy for a search hot path. This opens read-only,
- * never creates or migrates state.db (missing file / missing table = empty
- * map), and caps lock waits at 250 ms so a concurrent improve run can only
- * ever cost the search a quarter second, not a stall.
- */
-export function loadSalienceRankScores(items) {
-    const result = new Map();
-    if (items.length === 0)
-        return result;
-    try {
-        const dbPath = getStateDbPath();
-        if (!fs.existsSync(dbPath))
-            return result; // improve loop has never run here
-        const idByRef = new Map();
-        for (const item of items) {
-            idByRef.set(makeAssetRef(item.entry.type, item.entry.name), item.id);
-        }
-        const stateDb = openDatabase(dbPath, { readonly: true });
-        try {
-            try {
-                stateDb.exec("PRAGMA busy_timeout = 250");
-            }
-            catch {
-                // pragma failure on a readonly handle is fine — default timeout applies
-            }
-            const refs = [...idByRef.keys()];
-            const CHUNK = 500;
-            for (let i = 0; i < refs.length; i += CHUNK) {
-                const chunk = refs.slice(i, i + CHUNK);
-                const placeholders = chunk.map(() => "?").join(",");
-                const rows = stateDb
-                    .prepare(`SELECT asset_ref, rank_score FROM asset_salience WHERE asset_ref IN (${placeholders})`)
-                    .all(...chunk);
-                for (const row of rows) {
-                    const id = idByRef.get(row.asset_ref);
-                    if (id !== undefined)
-                        result.set(id, row.rank_score);
-                }
-            }
-        }
-        finally {
-            stateDb.close();
-        }
-    }
-    catch {
-        // Fail open — search must never break because state.db is unavailable.
-    }
-    return result;
-}
+import { getUtilityScoresByIds } from "../../storage/repositories/index-utility-repository.js";
+import { applyBeliefStateScoreCeiling, applyContributorAblation, applyScoreContributors, applyUtilityContributors, defaultRankingContributors, defaultUtilityRankingContributors, } from "./ranking-contributors.js";
 export function normalizeFtsScores(results) {
     const ftsScoreMap = new Map();
     if (results.length === 0)
@@ -93,6 +33,9 @@ export function combineSearchScores(options) {
             filePath: result.filePath,
             score: combinedScore,
             rankingMode: embedScore !== undefined ? "hybrid" : "fts",
+            itemRef: result.itemRef,
+            bundleId: result.bundleId,
+            conceptId: result.conceptId,
         });
     }
     for (const [id, cosine] of options.embedScoreMap) {
@@ -112,6 +55,9 @@ export function combineSearchScores(options) {
             filePath: found.filePath,
             score: cosine * VEC_WEIGHT,
             rankingMode: "semantic",
+            itemRef: found.itemRef,
+            bundleId: found.bundleId,
+            conceptId: found.conceptId,
         });
     }
     return scored;
@@ -127,21 +73,26 @@ export function applyRankingRules(options) {
         graphContext: options.graphContext,
         projectContext: options.projectContext,
     };
-    // Eval/debug only: AKM_ABLATE_CONTRIBUTORS lets the ablation harness drop
-    // named contributors to measure their effect. Resolved once per query;
-    // a no-op (full lists) when the env var is unset — see applyContributorAblation.
-    const ablateEnv = process.env.AKM_ABLATE_CONTRIBUTORS;
+    // Eval/debug only: lets the ablation harness drop named contributors to
+    // measure their effect. Resolved once per query; a no-op (full lists) when
+    // unset — see applyContributorAblation. C9: DI via
+    // `options.ablateContributors` is now the primary path (see the field's
+    // doc comment on RankEntriesOptions); AKM_ABLATE_CONTRIBUTORS is a
+    // temporary fallback for the one caller that cannot yet thread the option
+    // through (see that doc comment for why).
+    const ablateEnv = options.ablateContributors ?? process.env.AKM_ABLATE_CONTRIBUTORS;
     const activeScoreContributors = applyContributorAblation(defaultRankingContributors, ablateEnv);
     const activeUtilityContributors = applyContributorAblation(defaultUtilityRankingContributors, ablateEnv);
     for (const item of options.items) {
         applyScoreContributors(item, rankingContext, activeScoreContributors);
     }
     const { global: utilScoresMap, scoped: scopedUtilScoresMap } = getUtilityScoresByIds(options.db, options.items.map((item) => item.id), options.scopeKey);
-    // R2 — compose the improve loop's salience into user-facing ranking.
-    // undefined = load from state.db (default); null = explicitly disabled.
-    const salienceRankScores = options.salienceRankScores === null
-        ? new Map()
-        : (options.salienceRankScores ?? loadSalienceRankScores(options.items));
+    // R2 / #692 — salience-ranking is not in defaultUtilityRankingContributors
+    // (see ranking-contributors.ts), so this is never consumed by the default
+    // ranking path below; it exists only for a caller that explicitly builds a
+    // contributor list including salienceRankingContributor. undefined/null
+    // both normalize to "no data" — there is no state.db fallback load.
+    const salienceRankScores = options.salienceRankScores ?? new Map();
     const utilityContext = {
         ...rankingContext,
         utilityScores: utilScoresMap,
@@ -152,6 +103,12 @@ export function applyRankingRules(options) {
     };
     for (const item of options.items) {
         applyUtilityContributors(item, utilityContext, activeUtilityContributors);
+        // SPEC-5: demoting belief states (superseded/contradicted/archived/
+        // deprecated) cap the FINAL score. The additive belief penalty inside the
+        // multiplicative boost sum cannot overcome the FTS min-max normalization
+        // spread, so without the ceiling a superseded incumbent that is the best
+        // keyword match outranks its own correction forever.
+        applyBeliefStateScoreCeiling(item);
     }
     return options.items;
 }

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

@@ -0,0 +1,67 @@
+// 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/.
+const ATTRIBUTION = Symbol("search-hit-attribution");
+export function attachSearchHitAttribution(target, attribution) {
+    const host = target;
+    host[ATTRIBUTION] = {
+        ...host[ATTRIBUTION],
+        ...attribution,
+    };
+}
+export function copySearchHitAttribution(from, to, outputDescription) {
+    const attribution = from[ATTRIBUTION];
+    if (!attribution)
+        return;
+    const memoryInference = attribution.memoryInference;
+    const memorySurvives = memoryInference?.exposure !== "surface" ||
+        (memoryInference.surfaceDescription !== undefined && memoryInference.surfaceDescription === outputDescription);
+    const applicable = {
+        ...(memorySurvives && memoryInference ? { memoryInference } : {}),
+        ...(attribution.graphExtraction ? { graphExtraction: attribution.graphExtraction } : {}),
+    };
+    if (applicable.memoryInference || applicable.graphExtraction)
+        attachSearchHitAttribution(to, applicable);
+}
+export function getSearchHitAttribution(target) {
+    return target[ATTRIBUTION];
+}
+export function buildUsageEventAttribution(attribution, entryRef, projection = "full") {
+    if (!attribution)
+        return undefined;
+    const memoryInference = attribution.memoryInference;
+    const childRef = memoryInference?.exposure === "direct" ? entryRef : memoryInference?.childRef;
+    const graphExtraction = attribution.graphExtraction;
+    const graphApplies = graphExtraction !== undefined && Number.isFinite(graphExtraction.boost) && graphExtraction.boost > 0;
+    const surfaceFields = memoryInference?.surfaceFields ?? [];
+    const surfaceVisible = memoryInference?.exposure !== "surface" ||
+        (projection === "full"
+            ? surfaceFields.length > 0
+            : projection === "normal" || projection === "agent"
+                ? surfaceFields.includes("description")
+                : false);
+    const memoryApplies = memoryInference !== undefined && childRef?.includes("//") === true && surfaceVisible;
+    if (!memoryApplies && !graphApplies)
+        return undefined;
+    return {
+        ...(memoryApplies
+            ? {
+                memoryInference: {
+                    exposure: memoryInference.exposure,
+                    childRef,
+                },
+            }
+            : {}),
+        ...(graphApplies ? { graphExtraction } : {}),
+    };
+}
+export function usageEventAttributionMetadata(attribution, entryRef, projection = "full") {
+    const applicable = buildUsageEventAttribution(attribution, entryRef, projection);
+    return JSON.stringify({
+        downstreamAttribution: {
+            version: 1,
+            control: applicable === undefined,
+            ...applicable,
+        },
+    });
+}

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

@@ -9,14 +9,16 @@
  *  - description: entry description
  *  - tags: tags + aliases joined
  *  - hints: searchHints + examples + usage + intent fields
- *  - content: TOC headings (lowest-weight catch-all)
+ *  - content: TOC headings + parameters + the config-gated body opening
+ *    (lowest-weight catch-all)
  */
 // NOTE (R5): the collapse detector's frozen canary queries are built from the
 // same surface this function indexes (name tokens / tags / description) and
 // scored via FTS against it. Changing what buildSearchFields includes shifts
 // the detector's recall baseline for ALL existing canary sets — coordinate
 // with src/commands/improve/collapse-detector.ts (buildCanaryQuery) and expect
-// operators to re-mint via `akm improve canary --refresh` after such a change.
+// operators to re-mint via `bun scripts/refresh-canary-set.ts --refresh` after
+// such a change.
 export function buildSearchFields(entry) {
     const name = entry.name.replace(/[-_]/g, " ").toLowerCase();
     const description = (entry.description ?? "").toLowerCase();
@@ -27,6 +29,8 @@ export function buildSearchFields(entry) {
         tagParts.push(entry.aliases.join(" "));
     const tags = tagParts.join(" ").toLowerCase();
     const hintParts = [];
+    if (entry.hints)
+        hintParts.push(entry.hints.join(" "));
     if (entry.searchHints)
         hintParts.push(entry.searchHints.join(" "));
     if (entry.examples)
@@ -49,6 +53,8 @@ export function buildSearchFields(entry) {
         hintParts.push(entry.whenToUse);
     const hints = hintParts.join(" ").toLowerCase();
     const contentParts = [];
+    if (entry.content)
+        contentParts.push(entry.content);
     if (entry.toc) {
         contentParts.push(entry.toc.map((h) => h.text).join(" "));
     }
@@ -59,12 +65,21 @@ export function buildSearchFields(entry) {
                 contentParts.push(param.description);
         }
     }
+    // Stash-organization conventions (SPEC-8): the self-situating body opening
+    // (captured by the metadata pass only when `index.indexBodyOpening` is on)
+    // folds into the lowest-weight catch-all column — never name/description/
+    // tags/hints — so orientation prose is retrievable without outranking
+    // structured-field matches. The fold is unconditional on the entry field:
+    // `rebuildFts` rebuilds FTS rows from stored entry_json and must reproduce
+    // the same fields without re-reading config.
+    if (entry.bodyOpening)
+        contentParts.push(entry.bodyOpening);
     const content = contentParts.join(" ").toLowerCase();
     return { name, description, tags, hints, content };
 }
 /**
  * Build a single concatenated search text string for an entry.
- * Used for the `search_text` column in the entries table (backward compat)
+ * Used for the `search_text` column in the entries table.
  * and for generating embedding text.
  */
 export function buildSearchText(entry) {

package/dist/indexer/search/search-hit-enrichers.js

@@ -1,9 +1,10 @@
 // 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 { makeAssetRef } from "../../core/asset/asset-ref.js";
-import { getDerivedForParent } from "../db/db.js";
+import { displayRef } from "../../core/asset/resolve-ref.js";
+import { getDerivedForParent, getItemRefById } from "../../storage/repositories/index-entries-repository.js";
 import { getRenderer } from "../walk/file-context.js";
+import { attachSearchHitAttribution } from "./search-attribution.js";
 const rendererSearchHitEnricher = {
     name: "renderer-search-hit-enricher",
     appliesTo(ctx) {
@@ -46,16 +47,23 @@ export const derivedMemoryEnricher = {
         // it untouched also avoids `<parent>.derived.derived` chains.
         if (hit.name.toLowerCase().endsWith(".derived"))
             return;
-        // Parent ref shape: `memory:<name>`. Re-build from the entry's name
-        // so we don't depend on whatever wiki/registry prefix `hit.ref` carries.
-        const parentRef = makeAssetRef("memory", hit.name);
-        const derived = getDerivedForParent(ctx.db, parentRef);
+        // Parent ref shape: the 0.9.0 `memories/<name>` conceptId. Re-build from the
+        // entry's name so we don't depend on whatever wiki/registry prefix `hit.ref`
+        // carries. INTERNAL lookup key into `getDerivedForParent`: the `derived_from`
+        // column now stores this same conceptId grammar (Group-C item 2 flip — the
+        // metadata producer + this consumer move together).
+        const parentRef = `memories/${hit.name}`;
+        const derived = getDerivedForParent(ctx.db, parentRef, ctx.stashDir);
         if (!derived)
             return;
         // Swap description / searchHints / tags from the derived child.
         // The parent ref itself is preserved — only the surface text is swapped.
+        const surfaceFields = [];
+        let surfaceDescription;
         if (typeof derived.entry.description === "string" && derived.entry.description.length > 0) {
             hit.description = derived.entry.description;
+            surfaceDescription = derived.entry.description;
+            surfaceFields.push("description");
         }
         if (Array.isArray(derived.entry.searchHints) && derived.entry.searchHints.length > 0) {
             // We don't have a `searchHints` field on SourceSearchHit today — it's
@@ -65,44 +73,26 @@ export const derivedMemoryEnricher = {
         }
         if (Array.isArray(derived.entry.tags) && derived.entry.tags.length > 0) {
             hit.tags = derived.entry.tags;
+            surfaceFields.push("tags");
+        }
+        // F4b output-spelling flip: `expandTo` is a user-facing `akm show <ref>`
+        // target, so emit the 0.9.0 short conceptId grammar (`memories/<name>`).
+        hit.expandTo = displayRef({ type: "memory", name: derived.entry.name });
+        const childRef = getItemRefById(ctx.db, derived.id);
+        if (childRef && surfaceFields.length > 0) {
+            attachSearchHitAttribution(hit, {
+                memoryInference: {
+                    exposure: "surface",
+                    childRef,
+                    surfaceFields,
+                    ...(surfaceDescription ? { surfaceDescription } : {}),
+                },
+            });
         }
-        hit.expandTo = makeAssetRef("memory", derived.entry.name);
     },
 };
-/**
- * Registry of additional enrichers — populated by
- * {@link registerSearchHitEnricher} and consumed in addition to
- * {@link defaultSearchHitEnrichers} when `enrichSearchHit` is invoked
- * without an explicit enricher list.
- *
- * Kept module-local so callers must use `registerSearchHitEnricher` rather
- * than mutating the array directly.
- */
-const additionalEnrichers = [];
 export const defaultSearchHitEnrichers = [rendererSearchHitEnricher, derivedMemoryEnricher];
-/**
- * Register an additional enricher to be applied alongside the defaults.
- *
- * Idempotent on `name`: subsequent calls with the same name replace the
- * previously-registered enricher (so tests can re-register cleanly without
- * stacking duplicates).
- */
-export function registerSearchHitEnricher(enricher) {
-    const existingIndex = additionalEnrichers.findIndex((e) => e.name === enricher.name);
-    if (existingIndex >= 0) {
-        additionalEnrichers[existingIndex] = enricher;
-    }
-    else {
-        additionalEnrichers.push(enricher);
-    }
-}
-/**
- * Test-only: clear the registered-enrichers list. Not part of the public API.
- */
-export function _resetRegisteredSearchHitEnrichers() {
-    additionalEnrichers.length = 0;
-}
-export async function enrichSearchHit(hit, ctx, enrichers = [...defaultSearchHitEnrichers, ...additionalEnrichers]) {
+export async function enrichSearchHit(hit, ctx, enrichers = defaultSearchHitEnrichers) {
     for (const enricher of enrichers) {
         if (!enricher.appliesTo(ctx))
             continue;