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

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

@@ -14,18 +14,26 @@
  * implementation, not a "local vs. remote" distinction.
  */
 import fs from "node:fs";
+import path from "node:path";
 import { buildActionFromContributors, defaultActionContributors } from "../../core/action-contributors.js";
-import { makeAssetRef } from "../../core/asset/asset-ref.js";
-import { defaultRendererRegistry } from "../../core/asset/asset-registry.js";
+import { stashDirFor } from "../../core/asset/asset-placement.js";
+import { displayRef } from "../../core/asset/resolve-ref.js";
 import { getDbPath } from "../../core/paths.js";
+import { defaultRendererRegistry } from "../../core/type-presentation.js";
 import { warn } from "../../core/warn.js";
+import { closeDatabase, openExistingDatabase } from "../../storage/repositories/index-connection.js";
+import { getAllEntries, getBaseBeliefStatesForDerivedTwins, getEntryById, getEntryCount, getPositiveFeedbackCountsByIds, } from "../../storage/repositories/index-entries-repository.js";
+import { searchFts } from "../../storage/repositories/index-fts-repository.js";
+import { getMeta } from "../../storage/repositories/index-meta-repository.js";
+import { searchVec } from "../../storage/repositories/index-vec-repository.js";
 import { getCurrentWorkflowScopeKey } from "../../workflows/authoring/scope-key.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 { collectGraphRelatedHit, loadGraphBoostContext } from "../graph/graph-boost.js";
 import { isProposedQuality } from "../passes/metadata.js";
 import { resolveProjectContext } from "../walk/project-context.js";
+import { parseRefPrefixQuery, parseRetiredTypePrefixQuery, sanitizeFtsQuery } from "./fts-query.js";
 import { applyRankingRules, combineSearchScores, normalizeFtsScores } from "./ranking.js";
+import { attachSearchHitAttribution, copySearchHitAttribution, getSearchHitAttribution } from "./search-attribution.js";
 import { enrichSearchHit } from "./search-hit-enrichers.js";
 import { buildEditHint, findSourceForPath, isEditable } from "./search-source.js";
 import { deriveSemanticProviderFingerprint, getEffectiveSemanticStatus, isSemanticRuntimeReady, readSemanticStatus, } from "./semantic-status.js";
@@ -37,6 +45,9 @@ import { deriveSemanticProviderFingerprint, getEffectiveSemanticStatus, isSemant
  * actionable without re-introducing read-triggered reindexing.
  */
 const STALE_INDEX_HINT_MS = 7 * 24 * 60 * 60 * 1000;
+function hasIndexedProvenance(entry) {
+    return Boolean(entry.itemRef && entry.bundleId && entry.conceptId);
+}
 function buildStaleIndexHint(db) {
     try {
         const builtAt = getMeta(db, "builtAt");
@@ -52,17 +63,22 @@ function buildStaleIndexHint(db) {
         return undefined;
     }
 }
+function indexedProvenance(entry) {
+    return { itemRef: entry.itemRef, bundleId: entry.bundleId, conceptId: entry.conceptId };
+}
 export function buildLocalAction(type, ref, registry = defaultRendererRegistry) {
     return buildActionFromContributors({ type, ref }, defaultActionContributors(registry)) ?? `akm show ${ref}`;
 }
-function resolveSearchHitRef(entry, refName, source) {
-    if (source?.wikiName) {
-        return makeAssetRef(entry.type, entry.name);
-    }
-    return makeAssetRef(entry.type, refName, source?.registryId);
+function resolveSearchHitRef(entry, provenance, defaultBundleId) {
+    return displayRef({
+        type: entry.type,
+        name: entry.name,
+        conceptId: provenance.conceptId,
+        bundleId: provenance.bundleId,
+    }, defaultBundleId);
 }
 function resolveSearchHitOrigin(source) {
-    return source?.wikiName ? null : (source?.registryId ?? null);
+    return source?.registryId ?? null;
 }
 /**
  * Phase 2A / Rec 5: gate for the per-search `getPositiveFeedbackCountsByIds`
@@ -116,7 +132,26 @@ 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.");
+        if (!config.embedding?.endpoint || !config.embedding?.model) {
+            // F7/A2: same predicate as the `pending` branch above (#480) — a
+            // `blocked` status can outlive the provider config that produced it
+            // (e.g. the embedding config was later unset). This is not a fault;
+            // there is simply nothing configured to use.
+            warnings.push("Semantic search is enabled (semanticSearchMode='auto') but no embedding provider is configured. " +
+                'Either: (a) `akm config set embedding \'{"endpoint":"...","model":"..."}\'`, or ' +
+                "(b) `akm config set semanticSearchMode off` to use keyword-only search.");
+        }
+        else {
+            // F7/A2: surface the ACTUAL diagnostic instead of one fixed generic
+            // string. `rawStatus.reason`/`rawStatus.message` record why the
+            // semantic backend failed (auth, network, a stuck local-model
+            // download, …) — read at `readSemanticStatus()` above and, before
+            // this fix, discarded here in favor of a message that never varied.
+            const detail = rawStatus?.message ?? (rawStatus?.reason ? `reason: ${rawStatus.reason}` : undefined);
+            warnings.push(`Semantic search is blocked${detail ? ` (${detail})` : ""}. Using keyword search until the semantic ` +
+                "backend is healthy again. Run 'akm index --full' to retry, or " +
+                "`akm config set semanticSearchMode off` to silence this warning.");
+        }
     }
     // Bootstrap-only: builds the index inline when it cannot serve this stash.
     // Content freshness is the writers' job (indexWrittenAssets + full runs);
@@ -145,16 +180,16 @@ export async function searchLocal(input) {
         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);
+        const { hits, embedMs, rankMs, usedSemantic } = await searchDatabase(db, query, searchType, limit, stashDir, allSourceDirs, config, sources, rendererRegistry, filters, includeProposed, beliefFilter, restrictToSources, includeExcludedTypes, disableProjectContext, disableScopedUtility);
         return {
             hits,
-            tip: hits.length === 0
-                ? "No matching stash assets were found. Try a different query or run 'akm index' to rebuild."
-                : undefined,
+            tip: hits.length === 0 ? emptyResultTip(query) : undefined,
             warnings: warnings.length > 0 ? warnings : undefined,
             embedMs,
             rankMs,
-            mode: embedMs !== undefined && embedMs > 0 ? "semantic" : "keyword",
+            // Report the mode the search ACTUALLY used, carried explicitly from the
+            // vector scorer — not inferred from elapsed embedding milliseconds.
+            mode: usedSemantic ? "semantic" : "keyword",
         };
     }
     finally {
@@ -169,58 +204,56 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
     // `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"]) : [];
+    // D4 — conceptId-prefix queries (`memories/projecta/`, `bundle//`,
+    // `bundle//skills/`) translate to a deterministic enumeration narrowed by
+    // conceptId, instead of degenerating into the AND-token FTS query their
+    // sanitized form would produce ("memories projecta" — noise). The branch
+    // fires only on the untyped path: an explicit `--type` flag expresses
+    // stronger intent and wins. The PREFIX is itself explicit intent, so
+    // `defaultExcludeTypes` does not apply — `sessions/` enumerates sessions
+    // exactly like `--type session` does, and `bundle//` means the whole bundle.
+    const refPrefix = searchType === "any" ? parseRefPrefixQuery(query) : null;
+    // Shared args for the two browse paths below; browse never runs semantic
+    // ranking, so both return usedSemantic: false.
+    const browseArgs = {
+        db,
+        query,
+        limit,
+        stashDir,
+        allSourceDirs,
+        sources,
+        config,
+        rendererRegistry,
+        filters,
+        includeProposed,
+        beliefFilter,
+        restrictToSources,
+    };
+    if (refPrefix) {
+        // Browse path (conceptId-prefix enumeration).
+        return {
+            ...(await enumerateEntries({
+                ...browseArgs,
+                excludeTypes: [],
+                conceptIdPrefix: refPrefix.conceptIdPrefix,
+                ...(refPrefix.bundle !== undefined ? { bundle: refPrefix.bundle } : {}),
+            })),
+            usedSemantic: false,
+        };
+    }
     // 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, defaultExcludes);
-        // Deduplicate by file path — multiple entries can share the same file
-        const seenFilePaths = new Set();
-        const uniqueEntries = allEntries.filter((ie) => {
-            if (seenFilePaths.has(ie.filePath))
-                return false;
-            seenFilePaths.add(ie.filePath);
-            return true;
-        });
-        // Source filter: when the caller narrowed `sources` via `--source <name>`,
-        // drop entries whose filePath does not live under any of the requested
-        // sources. The FTS index spans every configured source, so without this
-        // filter a narrowed --source request would still leak results.
-        const sourceFiltered = restrictToSources
-            ? uniqueEntries.filter((ie) => findSourceForPath(ie.filePath, sources) !== undefined)
-            : uniqueEntries;
-        // Scope filter: drop entries whose stored scope does not satisfy every
-        // supplied scope key. Filtering happens BEFORE the limit slice so a
-        // restrictive filter still returns up to `limit` results.
-        const scopeFiltered = filters
-            ? sourceFiltered.filter((ie) => entryMatchesScope(ie.entry.scope, filters))
-            : sourceFiltered;
-        // Proposed-quality filter (v1 spec §4.2): exclude entries with
-        // `quality: "proposed"` unless the caller explicitly opts in.
-        const qualityFiltered = includeProposed
-            ? scopeFiltered
-            : scopeFiltered.filter((ie) => !isProposedQuality(ie.entry.quality));
-        // 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,
-            path: ie.filePath,
-            score: 1,
-            query,
-            rankingMode: "fts",
-            defaultStashDir: stashDir,
-            allSourceDirs,
-            sources,
-            config,
-            rendererRegistry,
-            db,
-        })));
-        return { hits };
+        // Browse path (empty/unsearchable query).
+        return {
+            ...(await enumerateEntries({
+                ...browseArgs,
+                typeFilter: searchType === "any" ? undefined : searchType,
+                excludeTypes: defaultExcludes,
+            })),
+            usedSemantic: false,
+        };
     }
     // Start the async embedding request without awaiting, then run FTS
     // synchronously while the HTTP/local embedding request is in-flight.
@@ -230,6 +263,12 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
     const ftsResults = searchFts(db, query, limit * 3, typeFilter, defaultExcludes);
     const embeddingScores = await embeddingPromise;
     const embedMs = Date.now() - tEmbed0;
+    // The vector scorer returns a (possibly empty) Map when the embedding + vector
+    // search actually executed, or null when semantic was not runnable (disabled,
+    // no embeddings, or the embed call threw). This is the AUTHORITATIVE "semantic
+    // mode was used" signal — carried out to telemetry instead of guessing from
+    // elapsed milliseconds (which timed the concurrent FTS work too).
+    const usedSemantic = embeddingScores !== null;
     const tRank0 = Date.now();
     // ── Score normalization ──────────────────────────────────────────────
     // Normalized BM25 + cosine similarity with weighted addition
@@ -253,11 +292,10 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
         // not leak into default ('any') results. defaultExcludes is already []
         // unless this is the untyped path without includeExcludedTypes.
         excludeTypes: defaultExcludes,
-    });
+    }).filter(hasIndexedProvenance);
     // ── Scoring Phase ──────────────────────────────────────────────────────
     // Apply boosts as multiplicative factors (all boosts in a single phase
     // so that sort order and displayed scores are always consistent).
-    //
     // Ranking philosophy: the goal is to surface the MOST USEFUL result for the
     // user's intent. An exact name match is the strongest signal. Actionable
     // asset types (skills, commands, agents) are more useful than passive
@@ -280,7 +318,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.
+    // or when the caller passed `--no-project-context` (disableProjectContext).
     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
@@ -295,10 +333,11 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
     // query here would be pure overhead. The boost > 1.0 sub-gate then skips the
     // query when the configured boost is a no-op (1.5^count when boost==1 is 1).
     const positiveFeedbackCounts = shouldQueryPositiveFeedbackCounts(utilityDecayRaw)
-        ? getPositiveFeedbackCountsByIds(db, scored.map((item) => item.id))
+        ? getPositiveFeedbackCountsByIds(scored.map((item) => item.id))
         : undefined;
     // Resolve per-project scope key for scoped utility scoring.
-    // AKM_DISABLE_SCOPED_UTILITY=1 opts out (e.g. for registry searches or tests).
+    // `disableScopedUtility` (wired from `akm search --no-project-context`)
+    // opts out (e.g. for registry searches or tests).
     let scopeKey;
     try {
         scopeKey = disableScopedUtility ? undefined : getCurrentWorkflowScopeKey();
@@ -323,8 +362,14 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
     // Drop semantic-only hits (cosine-only, no FTS match) whose score falls
     // below the configured floor. FTS hits and hybrid hits are always kept.
     // Default floor: 0.2. Set search.minScore = 0 in config to disable.
+    // Judged on the PRE-ceiling score when a demoting belief state clamped the
+    // item (`preCeilingScore`): the belief ceilings can sit below this floor
+    // (archived 0.15 < 0.2), and a demotion must rank the hit last, not
+    // silently remove a result that would otherwise have listed.
     const minScore = config.search?.minScore ?? 0.2;
-    const preFilter = minScore > 0 ? scored.filter((item) => item.rankingMode !== "semantic" || item.score >= minScore) : scored;
+    const preFilter = minScore > 0
+        ? scored.filter((item) => item.rankingMode !== "semantic" || (item.preCeilingScore ?? item.score) >= minScore)
+        : scored;
     // Deterministic tiebreaker on equal scores.
     //
     // CRITICAL: sort on the SAME clamped+rounded value the user sees (see the
@@ -341,34 +386,26 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
     const displayScore = (s) => Math.round(Math.min(1, Math.max(0, s)) * 10000) / 10000;
     preFilter.sort((a, b) => displayScore(b.score) - displayScore(a.score) || a.entry.name.localeCompare(b.entry.name));
     // Deduplicate by file path — keep only the highest-scored entry per file.
-    // Multiple .stash.json entries can map to the same file (e.g. entries without
-    // a filename field all collapse to files[0]). Showing the same path/ref
-    // multiple times clutters results.
     const deduped = deduplicateByPath(preFilter);
-    // Source filter: when the caller narrowed `sources` via `--source <name>`,
-    // drop hits whose filePath does not live under any of the requested
-    // sources. The FTS/vector index spans every configured source, so without
-    // this filter a narrowed --source request would still leak results from
-    // other sources that happened to match the query text.
-    const sourceFiltered = restrictToSources
-        ? deduped.filter((item) => findSourceForPath(item.filePath, sources) !== undefined)
-        : deduped;
-    // Scope filter: drop hits whose stored scope does not satisfy every supplied
-    // key. Applied AFTER ranking — filtering narrows the result set without
-    // touching the single FTS5+boosts scoring pipeline.
-    const scopeFiltered = filters
-        ? sourceFiltered.filter((item) => entryMatchesScope(item.entry.scope, filters))
-        : sourceFiltered;
-    // Proposed-quality filter (v1 spec §4.2): exclude entries with
-    // `quality: "proposed"` unless the caller passed `--include-proposed`.
-    // Applied AFTER ranking for the same reason as scope filtering.
-    const qualityFiltered = includeProposed
-        ? scopeFiltered
-        : scopeFiltered.filter((item) => !isProposedQuality(item.entry.quality));
-    const beliefFiltered = qualityFiltered.filter((item) => matchBeliefFilter(item.entry.beliefState, beliefFilter));
+    // Source → scope → proposed-quality → derived-twin belief inheritance →
+    // belief: the post-candidate filter chain shared with enumerateEntries (see
+    // applyEntryFilters). Applied AFTER ranking so filtering narrows the result
+    // set without touching the single FTS5+boosts scoring pipeline. The twin
+    // inheritance inside the chain re-runs here as an idempotent no-op — it
+    // already ran on the full candidate pool before ranking (:460) to feed the
+    // belief-state ranker.
+    const beliefFiltered = applyEntryFilters(deduped, {
+        db,
+        sources,
+        restrictToSources,
+        filters,
+        includeProposed,
+        beliefFilter,
+    });
     const rankMs = Date.now() - tRank0;
     const selected = beliefFiltered.slice(0, limit);
-    const hits = await Promise.all(selected.map(({ entry, filePath, score, rankingMode, utilityBoosted }) => {
+    const hits = await Promise.all(selected.map((ranked) => {
+        const { entry, filePath, score, rankingMode, utilityBoosted } = ranked;
         // CLAUDE.md locks SearchHit.score in [0,1]. The boost loop above can
         // exceed 1.0 (this was a pre-existing breach that #207's graph boost
         // — up to ~1.05 additive contribution — made detectable); clamp here
@@ -377,7 +414,7 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
         return buildDbHit({
             entry,
             path: filePath,
-            // Round to 4 decimal places
+            ...indexedProvenance(ranked),
             score: Math.round(finalScore * 10000) / 10000,
             query,
             rankingMode,
@@ -387,11 +424,148 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
             config,
             utilityBoosted,
             graphContext,
+            attributionSource: ranked,
             rendererRegistry,
             db,
         });
     }));
-    return { embedMs, rankMs, hits };
+    return { embedMs, rankMs, hits, usedSemantic };
+}
+/**
+ * The no-hits tip. A query in the retired `<type>:` / `<type>:<prefix>/` browse
+ * grammar gets the conceptId spelling that replaces it: without this it comes
+ * back empty and silent, which is the failure D4 removed the grammar to avoid.
+ */
+function emptyResultTip(query) {
+    const generic = "No matching stash assets were found. Try a different query or run 'akm index' to rebuild.";
+    const retired = parseRetiredTypePrefixQuery(query);
+    if (!retired)
+        return generic;
+    const root = stashDirFor(retired.type);
+    if (!root)
+        return generic;
+    return `No matching stash assets were found. The '<type>:' browse grammar was removed in 0.9.0 — use the conceptId spelling: 'akm search "${root}/${retired.rest}"'.`;
+}
+// ── Enumeration (browse) path ────────────────────────────────────────────────
+/**
+ * Enumerate index entries without FTS scoring — the browse path shared by
+ * empty/unsearchable queries and D4 conceptId-prefix queries (`memories/`,
+ * `bundle//`, `bundle//skills/`). Applies the same post-ranking filters as the scored
+ * path (source narrowing, scope, proposed-quality, belief) before the limit
+ * slice. Hits carry the fixed browse score 1 in type-then-name order — this is
+ * a deterministic listing, not a relevance ranking.
+ */
+async function enumerateEntries(opts) {
+    const { db, query, sources, config, rendererRegistry, filters, beliefFilter } = opts;
+    const allEntries = getAllEntries(db, opts.typeFilter, opts.excludeTypes).filter(hasIndexedProvenance);
+    // Explicit listing order: type, then name, then filePath. The underlying
+    // SELECT carries no ORDER BY, so its row order tracks the query plan and the
+    // index-insertion (file-walk) order — both machine-dependent. A browse
+    // listing must not change order across hosts or SQLite versions.
+    allEntries.sort((a, b) => a.entry.type.localeCompare(b.entry.type) ||
+        a.entry.name.localeCompare(b.entry.name) ||
+        a.filePath.localeCompare(b.filePath));
+    // D4: narrow to the requested bundle and subtree. Matching is against the
+    // conceptId — the spelling every emitted `ref` carries — so a ref copied out
+    // of search output round-trips back in. `startsWith` on the full
+    // slash-retaining prefix is exact: "memories/projecta/" cannot match a
+    // sibling "memories/projectalpha/…" scope.
+    const bundle = opts.bundle?.toLowerCase();
+    const bundleFiltered = bundle === undefined ? allEntries : allEntries.filter((ie) => ie.bundleId.toLowerCase() === bundle);
+    const conceptIdPrefix = opts.conceptIdPrefix?.toLowerCase() ?? "";
+    const prefixFiltered = conceptIdPrefix.length > 0
+        ? bundleFiltered.filter((ie) => ie.conceptId.toLowerCase().startsWith(conceptIdPrefix))
+        : bundleFiltered;
+    // Deduplicate by file path — multiple entries can share the same file
+    const seenFilePaths = new Set();
+    const uniqueEntries = prefixFiltered.filter((ie) => {
+        if (seenFilePaths.has(ie.filePath))
+            return false;
+        seenFilePaths.add(ie.filePath);
+        return true;
+    });
+    // Source → scope → proposed-quality → derived-twin belief inheritance →
+    // belief: the post-candidate filter chain shared with searchDatabase's
+    // scored path (see applyEntryFilters). Filtering happens BEFORE the limit
+    // slice so a restrictive filter still returns up to `limit` results. On this
+    // path the twin inheritance is the ONLY place it runs (there is no ranking
+    // pass), keeping the belief filter and reported hit state consistent with
+    // the scored path.
+    const beliefFiltered = applyEntryFilters(uniqueEntries, {
+        db,
+        sources,
+        restrictToSources: opts.restrictToSources,
+        filters,
+        includeProposed: opts.includeProposed,
+        beliefFilter,
+    });
+    const selected = beliefFiltered.slice(0, opts.limit);
+    const hits = await Promise.all(selected.map((ie) => buildDbHit({
+        entry: ie.entry,
+        path: ie.filePath,
+        itemRef: ie.itemRef,
+        bundleId: ie.bundleId,
+        conceptId: ie.conceptId,
+        score: 1,
+        query,
+        rankingMode: "fts",
+        defaultStashDir: opts.stashDir,
+        allSourceDirs: opts.allSourceDirs,
+        sources,
+        config,
+        rendererRegistry,
+        db,
+    })));
+    return { hits };
+}
+/**
+ * Post-candidate filter chain shared by BOTH search paths — the scored path
+ * (`searchDatabase`) and the browse path (`enumerateEntries`). Applies, in this
+ * exact order: source-narrowing → scope → proposed-quality → derived-twin
+ * belief inheritance → belief filter. Extracting the chain removes the two
+ * paths' formerly-duplicated filter sequences so the predicates, their order,
+ * and the twin-inheritance placement can never drift apart (plan §4.3).
+ *
+ * What this does NOT unify — and deliberately leaves divergent — is CANDIDATE-
+ * POOL construction, which is inherent search-vs-browse semantics: the scored
+ * path's pool is `searchFts`/vector matches for the query's own tokens (FTS
+ * indexes description/tags/searchHints/aliases, not raw body prose), while the
+ * enumerate path's pool is `getAllEntries` for the type, independent of query
+ * text. A derived twin sharing no indexed token with the query is therefore an
+ * enumerate-path candidate but never a scored-path candidate — see
+ * tests/fixtures/goldens/filter-behavior/scored-vs-enumerate.json, which pins
+ * that (retained) divergence.
+ *
+ * `inheritDerivedTwinBeliefStates` is idempotent, so running it here is safe on
+ * the scored path, which must ALSO call it before ranking (the belief-state
+ * ranker demotes inherited states): by the time this chain runs, those twins
+ * already carry a state and the call here is a no-op for them. The enumerate
+ * path never ranks, so this is the only place it inherits.
+ */
+function applyEntryFilters(items, opts) {
+    const { filters } = opts;
+    // Source filter: when the caller narrowed `sources` via `--from <name>`,
+    // drop entries whose filePath does not live under any requested source. The
+    // FTS/enumerate index spans every configured source, so without this filter a
+    // narrowed --from request would still leak results from other sources.
+    const sourceFiltered = opts.restrictToSources
+        ? items.filter((item) => findSourceForPath(item.filePath, opts.sources) !== undefined)
+        : items;
+    // Scope filter: drop entries whose stored scope does not satisfy every
+    // supplied key.
+    const scopeFiltered = filters
+        ? sourceFiltered.filter((item) => entryMatchesScope(item.entry.scope, filters))
+        : sourceFiltered;
+    // Proposed-quality filter (v1 spec §4.2): exclude `quality: "proposed"`
+    // entries unless the caller opts in.
+    const qualityFiltered = opts.includeProposed
+        ? scopeFiltered
+        : scopeFiltered.filter((item) => !isProposedQuality(item.entry.quality));
+    // 03-R3: derived twins inherit their base's demoting belief state BEFORE the
+    // belief filter, so the filter (and the reported hit state) stays consistent
+    // across both paths.
+    inheritDerivedTwinBeliefStates(opts.db, qualityFiltered);
+    return qualityFiltered.filter((item) => matchBeliefFilter(item.entry.beliefState, opts.beliefFilter));
 }
 /**
  * 03-R3: let each `.derived` twin inherit its base memory's demoting belief
@@ -466,7 +640,8 @@ async function tryVecScores(db, query, k, config) {
 // ── Hit building ────────────────────────────────────────────────────────────
 export async function buildDbHit(input) {
     const rendererRegistry = input.rendererRegistry ?? defaultRendererRegistry;
-    const entryStashDir = findSourceForPath(input.path, input.sources)?.path ?? input.defaultStashDir;
+    const absolutePath = path.resolve(input.path);
+    const entryStashDir = findSourceForPath(absolutePath, input.sources)?.path ?? input.defaultStashDir;
     // Quality and confidence boosts are now applied in the main scoring
     // phase (searchDatabase). buildDbHit receives the already-final score and
     // passes it through without further multiplication. We still compute the
@@ -477,23 +652,25 @@ export async function buildDbHit(input) {
     const confidenceBoost = typeof input.entry.confidence === "number" ? Math.min(0.05, Math.max(0, input.entry.confidence) * 0.05) : 0;
     // Round to 4 decimal places, no boost multiplication
     const score = Math.round(input.score * 10000) / 10000;
-    const graphBoost = input.graphContext ? computeGraphBoost(input.graphContext, input.path) : 0;
+    const graphBoost = getSearchHitAttribution(input.attributionSource ?? {})?.graphExtraction?.boost ?? 0;
     const whyMatched = buildWhyMatched(input.entry, input.query, input.rankingMode, qualityBoost, confidenceBoost, input.utilityBoosted, graphBoost);
-    const graphHit = input.graphContext ? collectGraphRelatedHit(input.graphContext, input.path) : null;
-    const source = findSourceForPath(input.path, input.sources);
-    const ref = resolveSearchHitRef(input.entry, input.entry.name, source);
-    const editable = isEditable(input.path, input.config);
+    const graphHit = input.graphContext ? collectGraphRelatedHit(input.graphContext, absolutePath) : null;
+    const source = findSourceForPath(absolutePath, input.sources);
+    const defaultBundleId = input.config?.defaultBundle ??
+        (source && path.resolve(source.path) === path.resolve(input.defaultStashDir)
+            ? (input.bundleId ?? undefined)
+            : undefined);
+    const ref = resolveSearchHitRef(input.entry, input, defaultBundleId);
+    const editable = isEditable(absolutePath, input.config, input.sources);
     const estimatedTokens = typeof input.entry.fileSize === "number" ? Math.round(input.entry.fileSize / 4) : undefined;
     const hit = {
         type: input.entry.type,
         name: input.entry.name,
-        path: input.path,
+        path: absolutePath,
         ref,
         origin: resolveSearchHitOrigin(source),
         editable,
-        ...(!editable
-            ? { editHint: buildEditHint(input.path, input.entry.type, input.entry.name, source?.registryId) }
-            : {}),
+        ...(!editable ? { editHint: buildEditHint(ref) } : {}),
         description: input.entry.description,
         tags: input.entry.tags,
         size: deriveSize(input.entry.fileSize),
@@ -508,6 +685,13 @@ export async function buildDbHit(input) {
         ...(input.entry.currentBeliefRefs ? { currentBeliefRefs: input.entry.currentBeliefRefs } : {}),
         ...(graphHit ? { graph: { entities: graphHit.entities, relations: graphHit.relations } } : {}),
     };
+    if (input.attributionSource)
+        copySearchHitAttribution(input.attributionSource, hit);
+    if (input.entry.derivedFrom) {
+        attachSearchHitAttribution(hit, {
+            memoryInference: { exposure: "direct" },
+        });
+    }
     await enrichSearchHit(hit, {
         type: input.entry.type,
         stashDir: entryStashDir,
@@ -605,7 +789,7 @@ function deduplicateByPath(items) {
     });
 }
 /**
- * Exact-match scope filter check. Legacy entries without a `scope` object only
+ * Exact-match scope filter check. Entries without a `scope` object only
  * match when no filter is supplied — which is what the caller guards on
  * before invoking this helper.
  */

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

@@ -6,6 +6,8 @@
  *
  * 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.
+ * `parseRefPrefixQuery` is the one non-FTS helper: it decides whether a raw
+ * query should bypass FTS entirely (SPEC-4 ref-prefix enumeration).
  */
 /**
  * Sanitize a raw user query into an FTS5-safe implicit-AND expression.
@@ -49,3 +51,65 @@ export function buildPrefixQuery(ftsQuery) {
         return null;
     return prefixTokens.join(" ");
 }
+/**
+ * D4 — parse a conceptId-prefix browse query.
+ *
+ * Decides whether a raw query is a subtree-enumeration request rather than an
+ * ordinary keyword search. Matching is deliberately conservative: the trimmed
+ * query must be EXACTLY
+ *
+ *   - `<conceptId prefix>/`           → that subtree in any bundle,
+ *   - `<bundle>//`                    → one bundle entirely,
+ *   - `<bundle>//<conceptId prefix>/` → that subtree of that bundle.
+ *
+ * The trailing slash is REQUIRED — and is RETAINED in `conceptIdPrefix` — so a
+ * plain `conceptId.startsWith(conceptIdPrefix)` check gives exact `/`-boundary
+ * subtree semantics (`"projecta/"` cannot match a sibling `projectalpha/…`
+ * scope). Bare refs like `memories/a/b` therefore stay ordinary searches
+ * (resolving one ref is `akm show` territory), and any interior whitespace
+ * disqualifies (prose mentioning a ref is still prose).
+ *
+ * The prefix matches the conceptId — the same string every emitted `ref`
+ * carries — so a ref copied out of search output round-trips back in as a
+ * prefix. Nothing here consults a type list: enumeration covers every
+ * adapter's items uniformly, which the retired `<type>:` grammar could not do.
+ *
+ * Returns `null` when the query is not a browse request.
+ */
+export function parseRefPrefixQuery(query) {
+    const trimmed = query.trim();
+    if (trimmed.length === 0 || /\s/.test(trimmed))
+        return null;
+    const separator = trimmed.indexOf("//");
+    if (separator < 0) {
+        return trimmed.endsWith("/") ? { conceptIdPrefix: trimmed } : null;
+    }
+    const bundle = trimmed.slice(0, separator);
+    if (bundle.length === 0)
+        return null;
+    const rest = trimmed.slice(separator + 2);
+    if (rest === "")
+        return { bundle, conceptIdPrefix: "" };
+    if (rest.endsWith("/") && !rest.includes("//"))
+        return { bundle, conceptIdPrefix: rest };
+    return null;
+}
+/**
+ * Recognize the retired `<type>:` / `<type>:<prefix>/` browse grammar so the
+ * caller can name the replacement spelling rather than letting the query
+ * degrade silently into a keyword search — the exact silent failure D4 removes.
+ * Shape recognition only; mapping the type to its conceptId root belongs to the
+ * caller, which keeps this module dependency-free.
+ */
+export function parseRetiredTypePrefixQuery(query) {
+    const trimmed = query.trim();
+    if (trimmed.length === 0 || /\s/.test(trimmed) || trimmed.includes("//"))
+        return null;
+    const colon = trimmed.indexOf(":");
+    if (colon <= 0)
+        return null;
+    const rest = trimmed.slice(colon + 1);
+    if (rest !== "" && !rest.endsWith("/"))
+        return null;
+    return { type: trimmed.slice(0, colon), rest };
+}