@unbrained/pm-cli 2026.6.30 → 2026.7.2

package/dist/cli/commands/search.js

@@ -4,7 +4,7 @@
  * Implements the pm search command surface and its agent-facing runtime behavior.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="0417fe76-c2a2-5a0a-82f3-0861f46175e9")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="fe9c6a3a-fb99-53ed-9a6c-8c32bb745364")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { coerceNumberInRange, toNonEmptyStringOrUndefined } from "../../core/shared/primitives.js";
@@ -117,8 +117,6 @@ const LONG_QUERY_PHRASE_MULTIPLIER = 6;
 const ALL_TERMS_COVERAGE_BONUS = 40;
 const EXACT_ID_MATCH_SCORE = 1_000;
 const SHORT_ID_MATCH_SCORE = 900;
-const IMPLICIT_HYBRID_EMBEDDING_TIMEOUT_MS = 8_000;
-const IMPLICIT_HYBRID_VECTOR_TIMEOUT_MS = 8_000;
 // GH-157 matched-text highlighting (--highlight): markers wrapping each matching
 // token run, and the number of characters of surrounding context retained on
 // each side of the first match in a field. The «…» guillemets are single
@@ -195,20 +193,20 @@ function buildVerboseSearchFilters(params) {
     return {
         mode: effectiveMode,
         match_mode: matchMode,
-        status: isStatusAllFilterInput(options.status) ? "all" : options.status ?? null,
-        type: options.type ?? null,
-        tag: options.tag ?? null,
-        priority: options.priority ?? null,
-        deadline_before: options.deadlineBefore ?? null,
-        deadline_after: options.deadlineAfter ?? null,
-        updated_after: options.updatedAfter ?? null,
-        updated_before: options.updatedBefore ?? null,
-        created_after: options.createdAfter ?? null,
-        created_before: options.createdBefore ?? null,
-        assignee: options.assignee ?? null,
-        sprint: options.sprint ?? null,
-        release: options.release ?? null,
-        parent: options.parent ?? null,
+        status: isStatusAllFilterInput(options.status) ? "all" : valueOrNull(options.status),
+        type: valueOrNull(options.type),
+        tag: valueOrNull(options.tag),
+        priority: valueOrNull(options.priority),
+        deadline_before: valueOrNull(options.deadlineBefore),
+        deadline_after: valueOrNull(options.deadlineAfter),
+        updated_after: valueOrNull(options.updatedAfter),
+        updated_before: valueOrNull(options.updatedBefore),
+        created_after: valueOrNull(options.createdAfter),
+        created_before: valueOrNull(options.createdBefore),
+        assignee: valueOrNull(options.assignee),
+        sprint: valueOrNull(options.sprint),
+        release: valueOrNull(options.release),
+        parent: valueOrNull(options.parent),
         ...buildGovernanceMissingFilterEcho(options),
         ...buildContentFilterEcho(options),
         include_linked: includeLinked,
@@ -221,10 +219,13 @@ function buildVerboseSearchFilters(params) {
         rerank_enabled: rerank.enabled,
         rerank_model: rerank.model,
         rerank_top_k: rerank.top_k,
-        limit: options.limit ?? null,
+        limit: valueOrNull(options.limit),
         runtime_filters: runtimeFieldFilters,
     };
 }
+function valueOrNull(value) {
+    return value ?? null;
+}
 /**
  * Aggregate the `code` strings found along an error's `cause` chain.
  *
@@ -269,16 +270,6 @@ export function classifyImplicitSemanticFallbackReason(error) {
     }
     return "error";
 }
-function buildImplicitSemanticFallbackWarning(error) {
-    const reason = classifyImplicitSemanticFallbackReason(error);
-    if (reason === "timeout") {
-        return "search_implicit_semantic_fallback:timeout:using_keyword_mode";
-    }
-    if (reason === "connection") {
-        return "search_implicit_semantic_fallback:connection:using_keyword_mode";
-    }
-    return "search_implicit_semantic_fallback:error:using_keyword_mode";
-}
 // Explicit --semantic/--hybrid searches must never hard-fail an agent when the
 // embedding/vector backend is unreachable or unconfigured: degrade to keyword
 // search and surface a machine-readable warning instead of an unknown_error.
@@ -437,7 +428,6 @@ export const _testOnlySearchCommand = {
     buildExplicitSemanticFallbackWarning,
     buildCompactSearchFilterSummary,
     buildHybridLexicalScore,
-    buildImplicitSemanticFallbackWarning,
     buildRerankCorpus,
     buildSemanticHits,
     classifyImplicitSemanticFallbackReason,
@@ -643,6 +633,11 @@ function resolveSearchMetadataFilterSet(options, typeRegistry, statusFilter) {
     };
 }
 function matchesScalarSearchFilters(item, filters) {
+    return (matchesIdentitySearchFilters(item, filters) &&
+        matchesTimestampSearchFilters(item, filters) &&
+        matchesOwnerSearchFilters(item, filters));
+}
+function matchesIdentitySearchFilters(item, filters) {
     if (filters.statusSet && !filters.statusSet.has(item.status))
         return false;
     if (filters.typeFilter && item.type !== filters.typeFilter)
@@ -651,6 +646,9 @@ function matchesScalarSearchFilters(item, filters) {
         return false;
     if (filters.priorityFilter !== undefined && item.priority !== filters.priorityFilter)
         return false;
+    return true;
+}
+function matchesTimestampSearchFilters(item, filters) {
     if (filters.deadlineBefore && (!item.deadline || compareTimestampStrings(item.deadline, filters.deadlineBefore) > 0))
         return false;
     if (filters.deadlineAfter && (!item.deadline || compareTimestampStrings(item.deadline, filters.deadlineAfter) < 0))
@@ -663,6 +661,9 @@ function matchesScalarSearchFilters(item, filters) {
         return false;
     if (filters.createdBefore && compareTimestampStrings(item.created_at, filters.createdBefore) > 0)
         return false;
+    return true;
+}
+function matchesOwnerSearchFilters(item, filters) {
     if (filters.assigneeFilter !== undefined && item.assignee !== filters.assigneeFilter)
         return false;
     if (filters.sprintFilter !== undefined && item.sprint !== filters.sprintFilter)
@@ -919,28 +920,8 @@ function buildHitHighlights(document, matchedFields, tokens) {
     }
     return highlights;
 }
-function scoreDocument(document, tokens, normalizedQuery, linkedCorpus, tuning, idPrefix, applyCoverageBonus = false) {
-    const item = document.metadata;
-    const normalizedId = normalizeSearchPhrase(item.id);
-    const normalizedIdPrefix = typeof idPrefix === "string" ? idPrefix.trim().toLowerCase() : "";
-    const normalizedIdPrefixPhrase = normalizeSearchPhrase(normalizedIdPrefix);
-    const normalizedShortId = normalizedIdPrefixPhrase.length > 0 && normalizedId.startsWith(normalizedIdPrefixPhrase)
-        ? normalizedId.slice(normalizedIdPrefixPhrase.length).trim()
-        : normalizedId;
-    if (normalizedQuery === normalizedId || normalizedQuery === normalizedShortId) {
-        return {
-            item,
-            score: normalizedQuery === normalizedId ? EXACT_ID_MATCH_SCORE : SHORT_ID_MATCH_SCORE,
-            matched_fields: ["id"],
-            matched_all_terms: true,
-            exact_id_match: true,
-        };
-    }
-    const titleTokenCounts = new Map();
-    for (const token of tokenizeForExactTokenMatch(item.title)) {
-        titleTokenCounts.set(token, (titleTokenCounts.get(token) ?? 0) + 1);
-    }
-    const searchableFields = [
+function buildSearchableScoringFields(document, linkedCorpus, tuning) {
+    return [
         ...SEARCHABLE_FIELD_BUILDERS.map((builder) => ({
             name: builder.name,
             value: builder.value(document),
@@ -948,58 +929,90 @@ function scoreDocument(document, tokens, normalizedQuery, linkedCorpus, tuning,
         })),
         { name: "linked_content", value: linkedCorpus, weight: tuning.linked_content_weight },
     ];
-    let score = 0;
-    const matched = new Set();
-    const matchedTokens = new Set();
+}
+function buildExactIdSearchHit(item, normalizedQuery, idPrefix) {
+    const normalizedId = normalizeSearchPhrase(item.id);
+    const normalizedIdPrefix = typeof idPrefix === "string" ? idPrefix.trim().toLowerCase() : "";
+    const normalizedIdPrefixPhrase = normalizeSearchPhrase(normalizedIdPrefix);
+    const normalizedShortId = normalizedIdPrefixPhrase.length > 0 && normalizedId.startsWith(normalizedIdPrefixPhrase)
+        ? normalizedId.slice(normalizedIdPrefixPhrase.length).trim()
+        : normalizedId;
+    if (normalizedQuery !== normalizedId && normalizedQuery !== normalizedShortId) {
+        return null;
+    }
+    return {
+        item,
+        score: normalizedQuery === normalizedId ? EXACT_ID_MATCH_SCORE : SHORT_ID_MATCH_SCORE,
+        matched_fields: ["id"],
+        matched_all_terms: true,
+        exact_id_match: true,
+    };
+}
+function scoreTokenMatches(tokens, titleTokenCounts, searchableFields, tuning, state) {
     for (const token of tokens) {
         const exactTitleMatches = titleTokenCounts.get(token) ?? 0;
         if (exactTitleMatches > 0) {
-            score += exactTitleMatches * tuning.title_exact_bonus;
-            matched.add("title");
-            matchedTokens.add(token);
+            state.score += exactTitleMatches * tuning.title_exact_bonus;
+            state.matched.add("title");
+            state.matchedTokens.add(token);
         }
         for (const field of searchableFields) {
-            const fieldValue = field.value.toLowerCase();
-            const occurrences = countOccurrences(fieldValue, token);
+            const occurrences = countOccurrences(field.value.toLowerCase(), token);
             if (occurrences > 0) {
-                score += occurrences * field.weight;
-                matched.add(field.name);
-                matchedTokens.add(token);
+                state.score += occurrences * field.weight;
+                state.matched.add(field.name);
+                state.matchedTokens.add(token);
             }
         }
     }
+}
+function scorePhraseMatches(item, normalizedQuery, searchableFields, state) {
+    const normalizedTitle = normalizeSearchPhrase(item.title);
+    if (normalizedTitle === normalizedQuery) {
+        state.score += LONG_QUERY_TITLE_EXACT_BONUS;
+        state.matched.add("title");
+    }
+    for (const field of searchableFields) {
+        const phraseOccurrences = countOccurrences(normalizeSearchPhrase(field.value), normalizedQuery);
+        if (phraseOccurrences > 0) {
+            state.score += phraseOccurrences * field.weight * LONG_QUERY_PHRASE_MULTIPLIER;
+            state.matched.add(field.name);
+        }
+    }
+}
+function scoreDocument(document, tokens, normalizedQuery, linkedCorpus, tuning, idPrefix, applyCoverageBonus = false) {
+    const item = document.metadata;
+    const exactIdHit = buildExactIdSearchHit(item, normalizedQuery, idPrefix);
+    if (exactIdHit) {
+        return exactIdHit;
+    }
+    const titleTokenCounts = new Map();
+    for (const token of tokenizeForExactTokenMatch(item.title)) {
+        titleTokenCounts.set(token, (titleTokenCounts.get(token) ?? 0) + 1);
+    }
+    const searchableFields = buildSearchableScoringFields(document, linkedCorpus, tuning);
+    const state = { score: 0, matched: new Set(), matchedTokens: new Set() };
+    scoreTokenMatches(tokens, titleTokenCounts, searchableFields, tuning, state);
     const distinctTokens = new Set(tokens);
     // matchedTokens only ever holds entries drawn from `tokens`, so it is always a
     // subset of distinctTokens — exact size equality means every distinct term matched.
-    const matchedAllTerms = distinctTokens.size > 0 && matchedTokens.size === distinctTokens.size;
+    const matchedAllTerms = distinctTokens.size > 0 && state.matchedTokens.size === distinctTokens.size;
     // GH-181 default-mode all-terms ranking bonus: only meaningful for multi-token
     // queries where every distinct token matched somewhere.
     if (applyCoverageBonus && distinctTokens.size > 1 && matchedAllTerms) {
-        score += ALL_TERMS_COVERAGE_BONUS;
+        state.score += ALL_TERMS_COVERAGE_BONUS;
     }
     const isLongPhraseQuery = tokens.length >= LONG_QUERY_TOKEN_THRESHOLD && normalizedQuery.includes(" ");
     if (isLongPhraseQuery) {
-        const normalizedTitle = normalizeSearchPhrase(item.title);
-        if (normalizedTitle === normalizedQuery) {
-            score += LONG_QUERY_TITLE_EXACT_BONUS;
-            matched.add("title");
-        }
-        for (const field of searchableFields) {
-            const normalizedField = normalizeSearchPhrase(field.value);
-            const phraseOccurrences = countOccurrences(normalizedField, normalizedQuery);
-            if (phraseOccurrences > 0) {
-                score += phraseOccurrences * field.weight * LONG_QUERY_PHRASE_MULTIPLIER;
-                matched.add(field.name);
-            }
-        }
+        scorePhraseMatches(item, normalizedQuery, searchableFields, state);
     }
-    if (score <= 0) {
+    if (state.score <= 0) {
         return null;
     }
     return {
         item,
-        score,
-        matched_fields: [...matched].sort((a, b) => a.localeCompare(b)),
+        score: state.score,
+        matched_fields: [...state.matched].sort((a, b) => a.localeCompare(b)),
         matched_all_terms: matchedAllTerms,
     };
 }
@@ -1244,8 +1257,15 @@ function resolveExtensionVectorAdapter(settings) {
     if (typeof query !== "function") {
         return null;
     }
+    const upsert = runtimeDefinition.upsert;
+    const runtimeAdapterName = toOptionalNonEmptyString(runtimeDefinition.name) ??
+        toOptionalNonEmptyString(resolved.definition.name) ??
+        adapterName ??
+        "extension";
     return {
+        adapterName: runtimeAdapterName,
         query: query,
+        ...(typeof upsert === "function" ? { upsert: upsert } : {}),
     };
 }
 /* c8 ignore stop */
@@ -1459,59 +1479,162 @@ function buildRerankCorpus(document) {
 }
 /* c8 ignore stop */
 /* c8 ignore start -- semantic expansion/rerank fallback matrices are covered by end-to-end semantic search tests */
-async function computeSemanticOrHybridHits(context) {
-    const semanticLimit = context.limit ?? context.maxResults;
-    const embeddingOptions = context.embeddingTimeoutMs !== undefined ? { timeout_ms: context.embeddingTimeoutMs } : {};
-    const vectorQueryOptions = context.vectorQueryTimeoutMs !== undefined ? { timeout_ms: context.vectorQueryTimeoutMs } : {};
-    const queryTrimmed = context.query.trim();
+async function resolveExpandedSemanticQueries(context, queryTrimmed) {
     const baseExpandedQueries = context.queryExpansion.enabled
         ? buildDeterministicQueryExpansions(queryTrimmed, context.queryExpansion.max_queries)
         : [queryTrimmed];
-    let expandedQueries = baseExpandedQueries.length > 0 ? baseExpandedQueries : [queryTrimmed];
-    if (context.queryExpansion.enabled) {
-        if (context.queryExpansionExtension?.expand) {
-            try {
-                const rawExpansion = await Promise.resolve(context.queryExpansionExtension.expand({
-                    query: queryTrimmed,
-                    mode: context.requestedMode,
-                    settings: context.settings,
-                }));
-                const extensionExpansion = normalizeQueryExpansionOutput(rawExpansion);
-                expandedQueries = mergeQueryExpansions(expandedQueries, extensionExpansion, context.queryExpansion.max_queries);
-            }
-            catch {
-                context.warnings.push(`search_query_expansion_provider_failed:${context.queryExpansionExtension.providerName}:using_builtin`);
-            }
+    const expandedQueries = baseExpandedQueries.length > 0 ? baseExpandedQueries : [queryTrimmed];
+    if (!context.queryExpansion.enabled) {
+        return expandedQueries;
+    }
+    if (context.queryExpansionExtension?.expand) {
+        try {
+            const rawExpansion = await Promise.resolve(context.queryExpansionExtension.expand({
+                query: queryTrimmed,
+                mode: context.requestedMode,
+                settings: context.settings,
+            }));
+            return mergeQueryExpansions(expandedQueries, normalizeQueryExpansionOutput(rawExpansion), context.queryExpansion.max_queries);
         }
-        else if (context.queryExpansion.provider &&
-            context.queryExpansion.provider !== "openai" &&
-            context.queryExpansion.provider !== "ollama") {
-            context.warnings.push(`search_query_expansion_provider_unavailable:${context.queryExpansion.provider}:using_builtin`);
+        catch {
+            context.warnings.push(`search_query_expansion_provider_failed:${context.queryExpansionExtension.providerName}:using_builtin`);
+            return expandedQueries;
         }
     }
-    const queryVectors = await executeEmbeddingRequest(context.provider, expandedQueries, embeddingOptions);
-    const executeVectorQueryWithFallback = async (semanticVector) => {
-        if (context.extensionVectorAdapter?.query) {
-            try {
-                return await Promise.resolve(context.extensionVectorAdapter.query({
-                    vector: semanticVector,
-                    limit: semanticLimit,
-                    settings: context.settings,
-                }));
-            }
-            catch (error) {
-                if (!context.vectorStore) {
-                    throw new PmCliError(`Extension vector adapter query failed and no built-in fallback store is configured (${error instanceof Error ? error.message : String(error)})`, EXIT_CODE.GENERIC_FAILURE);
-                }
-                return await executeVectorQuery(context.vectorStore, semanticVector, semanticLimit, vectorQueryOptions);
-            }
+    if (context.queryExpansion.provider &&
+        context.queryExpansion.provider !== "openai" &&
+        context.queryExpansion.provider !== "ollama") {
+        context.warnings.push(`search_query_expansion_provider_unavailable:${context.queryExpansion.provider}:using_builtin`);
+    }
+    return expandedQueries;
+}
+async function executeSemanticVectorQuery(context, semanticVector, semanticLimit, vectorQueryOptions) {
+    if (context.extensionVectorAdapter?.query) {
+        try {
+            return await Promise.resolve(context.extensionVectorAdapter.query({
+                vector: semanticVector,
+                limit: semanticLimit,
+                settings: context.settings,
+            }));
         }
-        if (context.vectorStore) {
+        catch (error) {
+            if (!context.vectorStore) {
+                throw new PmCliError(`Extension vector adapter query failed and no built-in fallback store is configured (${error instanceof Error ? error.message : String(error)})`, EXIT_CODE.GENERIC_FAILURE);
+            }
+            context.warnings.push(`search_vector_adapter_failed:${context.extensionVectorAdapter.adapterName}:using_builtin`);
             return await executeVectorQuery(context.vectorStore, semanticVector, semanticLimit, vectorQueryOptions);
         }
-        throw new PmCliError("Semantic search requires either a configured vector store or an extension vector adapter query handler", EXIT_CODE.USAGE);
-    };
-    const queryVectorGroups = await Promise.all(queryVectors.map(async (semanticVector) => await executeVectorQueryWithFallback(semanticVector)));
+    }
+    if (context.vectorStore) {
+        return await executeVectorQuery(context.vectorStore, semanticVector, semanticLimit, vectorQueryOptions);
+    }
+    throw new PmCliError("Semantic search requires either a configured vector store or an extension vector adapter query handler", EXIT_CODE.USAGE);
+}
+function buildRerankCandidateContexts(hybridHits, filteredById, topK) {
+    const sortedForCandidates = [...hybridHits].sort((left, right) => {
+        if (left.score !== right.score) {
+            return right.score - left.score;
+        }
+        return left.item.id.localeCompare(right.item.id);
+    });
+    return sortedForCandidates
+        .slice(0, topK)
+        .map((hit) => {
+        const document = filteredById.get(hit.item.id);
+        return document ? { hit, text: buildRerankCorpus(document) } : null;
+    })
+        .filter((entry) => entry !== null);
+}
+async function resolveExtensionRerankScores(context, queryTrimmed, candidateContexts) {
+    if (!context.rerankExtension?.rerank) {
+        return null;
+    }
+    try {
+        const rawRerank = await Promise.resolve(context.rerankExtension.rerank({
+            query: queryTrimmed,
+            mode: "hybrid",
+            model: context.rerank.model,
+            top_k: context.rerank.top_k,
+            settings: context.settings,
+            candidates: candidateContexts.map((entry) => ({
+                id: entry.hit.item.id,
+                text: entry.text,
+                score: entry.hit.score,
+            })),
+        }));
+        const normalizedRerank = normalizeRerankOutput(rawRerank);
+        if (normalizedRerank.length > 0) {
+            return new Map(normalizedRerank.map((entry) => [entry.id, entry.score]));
+        }
+        context.warnings.push(`search_rerank_provider_invalid_response:${context.rerankExtension.providerName}:using_builtin`);
+        return null;
+    }
+    catch {
+        context.warnings.push(`search_rerank_provider_failed:${context.rerankExtension.providerName}:using_builtin`);
+        return null;
+    }
+}
+async function resolveRerankScores(context, queryTrimmed, candidateContexts) {
+    const extensionScores = await resolveExtensionRerankScores(context, queryTrimmed, candidateContexts);
+    if (extensionScores) {
+        return extensionScores;
+    }
+    const rerankCandidates = candidateContexts.map((entry) => ({
+        id: entry.hit.item.id,
+        text: entry.text,
+    }));
+    try {
+        return await rerankCandidatesWithEmbeddings(context.provider, context.rerank.model, queryTrimmed, rerankCandidates, context.embeddingTimeoutMs);
+    }
+    catch {
+        context.warnings.push("search_rerank_failed:using_hybrid_scores");
+        return null;
+    }
+}
+function applyRerankScores(hybridHits, rerankScores) {
+    const rerankedIds = new Set(rerankScores.keys());
+    const rerankedHits = hybridHits.map((hit) => {
+        const rerankScore = rerankScores.get(hit.item.id);
+        if (rerankScore === undefined) {
+            return hit;
+        }
+        const matchedFields = new Set(hit.matched_fields);
+        matchedFields.add("rerank");
+        return {
+            ...hit,
+            score: rerankScore,
+            matched_fields: [...matchedFields].sort((left, right) => left.localeCompare(right)),
+        };
+    });
+    rerankedHits.sort((left, right) => {
+        const leftWasReranked = rerankedIds.has(left.item.id);
+        const rightWasReranked = rerankedIds.has(right.item.id);
+        if (leftWasReranked !== rightWasReranked) {
+            return leftWasReranked ? -1 : 1;
+        }
+        if (left.score !== right.score) {
+            return right.score - left.score;
+        }
+        return left.item.id.localeCompare(right.item.id);
+    });
+    return rerankedHits;
+}
+async function applyHybridRerank(context, queryTrimmed, hybridHits, filteredById) {
+    if (!context.rerank.enabled || hybridHits.length <= 1) {
+        return hybridHits;
+    }
+    const candidateContexts = buildRerankCandidateContexts(hybridHits, filteredById, context.rerank.top_k);
+    const rerankScores = await resolveRerankScores(context, queryTrimmed, candidateContexts);
+    return rerankScores && rerankScores.size > 0 ? applyRerankScores(hybridHits, rerankScores) : hybridHits;
+}
+async function computeSemanticOrHybridHits(context) {
+    const semanticLimit = context.limit ?? context.maxResults;
+    const embeddingOptions = context.embeddingTimeoutMs !== undefined ? { timeout_ms: context.embeddingTimeoutMs } : {};
+    const vectorQueryOptions = context.vectorQueryTimeoutMs !== undefined ? { timeout_ms: context.vectorQueryTimeoutMs } : {};
+    const queryTrimmed = context.query.trim();
+    const expandedQueries = await resolveExpandedSemanticQueries(context, queryTrimmed);
+    const queryVectors = await executeEmbeddingRequest(context.provider, expandedQueries, embeddingOptions);
+    const queryVectorGroups = await Promise.all(queryVectors.map(async (semanticVector) => await executeSemanticVectorQuery(context, semanticVector, semanticLimit, vectorQueryOptions)));
     const vectorHits = mergeVectorHitsById(queryVectorGroups);
     const filteredById = new Map(context.filteredDocuments.map((document) => [document.metadata.id, document]));
     const { semanticHits, semanticScores } = buildSemanticHits(vectorHits, filteredById);
@@ -1521,91 +1644,7 @@ async function computeSemanticOrHybridHits(context) {
         // semantic mode, where it otherwise carries no vector hit at all.
         return { hits: forceExactIdHitsToTop(semanticHits, context.keywordHits), vectorMatchCount };
     }
-    let hybridHits = combineHybridHits(filteredById, semanticScores, context.keywordHits, context.hybridSemanticWeight);
-    if (context.rerank.enabled && hybridHits.length > 1) {
-        const sortedForCandidates = [...hybridHits].sort((left, right) => {
-            if (left.score !== right.score) {
-                return right.score - left.score;
-            }
-            return left.item.id.localeCompare(right.item.id);
-        });
-        const candidateHits = sortedForCandidates.slice(0, context.rerank.top_k);
-        const candidateContexts = candidateHits
-            .map((hit) => {
-            const document = filteredById.get(hit.item.id);
-            if (!document) {
-                return null;
-            }
-            return { hit, text: buildRerankCorpus(document) };
-        })
-            .filter((entry) => entry !== null);
-        const rerankCandidates = candidateContexts.map((entry) => ({
-            id: entry.hit.item.id,
-            text: entry.text,
-        }));
-        let rerankScores = null;
-        if (context.rerankExtension?.rerank) {
-            try {
-                const rawRerank = await Promise.resolve(context.rerankExtension.rerank({
-                    query: queryTrimmed,
-                    mode: "hybrid",
-                    model: context.rerank.model,
-                    top_k: context.rerank.top_k,
-                    settings: context.settings,
-                    candidates: candidateContexts.map((entry) => ({
-                        id: entry.hit.item.id,
-                        text: entry.text,
-                        score: entry.hit.score,
-                    })),
-                }));
-                const normalizedRerank = normalizeRerankOutput(rawRerank);
-                if (normalizedRerank.length > 0) {
-                    rerankScores = new Map(normalizedRerank.map((entry) => [entry.id, entry.score]));
-                }
-                else {
-                    context.warnings.push(`search_rerank_provider_invalid_response:${context.rerankExtension.providerName}:using_builtin`);
-                }
-            }
-            catch {
-                context.warnings.push(`search_rerank_provider_failed:${context.rerankExtension.providerName}:using_builtin`);
-            }
-        }
-        if (!rerankScores) {
-            try {
-                rerankScores = await rerankCandidatesWithEmbeddings(context.provider, context.rerank.model, queryTrimmed, rerankCandidates, context.embeddingTimeoutMs);
-            }
-            catch {
-                context.warnings.push("search_rerank_failed:using_hybrid_scores");
-            }
-        }
-        if (rerankScores && rerankScores.size > 0) {
-            const rerankedIds = new Set(rerankScores.keys());
-            hybridHits = hybridHits.map((hit) => {
-                const rerankScore = rerankScores.get(hit.item.id);
-                if (rerankScore === undefined) {
-                    return hit;
-                }
-                const matchedFields = new Set(hit.matched_fields);
-                matchedFields.add("rerank");
-                return {
-                    ...hit,
-                    score: rerankScore,
-                    matched_fields: [...matchedFields].sort((left, right) => left.localeCompare(right)),
-                };
-            });
-            hybridHits.sort((left, right) => {
-                const leftWasReranked = rerankedIds.has(left.item.id);
-                const rightWasReranked = rerankedIds.has(right.item.id);
-                if (leftWasReranked !== rightWasReranked) {
-                    return leftWasReranked ? -1 : 1;
-                }
-                if (left.score !== right.score) {
-                    return right.score - left.score;
-                }
-                return left.item.id.localeCompare(right.item.id);
-            });
-        }
-    }
+    const hybridHits = await applyHybridRerank(context, queryTrimmed, combineHybridHits(filteredById, semanticScores, context.keywordHits, context.hybridSemanticWeight), filteredById);
     return {
         // GH-281: applied LAST (after any rerank reordering) so an exact full-ID /
         // short-ID keyword match always ranks #1 in hybrid mode regardless of the
@@ -1725,14 +1764,15 @@ function projectSearchHits(hits, projection) {
         return projected;
     });
 }
-/**
- * Implements run search for the public runtime surface of this module.
- */
-export async function runSearch(rawQuery, rawOptions, global) {
-    // GH-157 inline query syntax: pull `field:value` filter tokens out of the raw
-    // query before any other parsing. Explicit flags win — an inline token only
-    // applies when its flag is unset, and a conflicting token surfaces as a
-    // warning. The residual keyword text drives tokenization/scoring as usual.
+function resolveQueryExpansionExtension(queryExpansion) {
+    const provider = resolveExtensionSearchProviderByName(queryExpansion.provider ?? undefined);
+    return provider?.queryExpansion ? { providerName: provider.providerName, expand: provider.queryExpansion } : null;
+}
+function resolveRerankExtension(settings) {
+    const provider = resolveExtensionSearchProviderByName(toOptionalNonEmptyString(settings.search?.provider));
+    return provider?.rerank ? { providerName: provider.providerName, rerank: provider.rerank } : null;
+}
+function prepareSearchInput(rawQuery, rawOptions) {
     const inlineWarnings = [];
     const inlineParse = parseInlineQueryFilters(rawQuery);
     const hasInlineFilters = Object.keys(inlineParse.inlineFilters).length > 0;
@@ -1746,372 +1786,391 @@ export async function runSearch(rawQuery, rawOptions, global) {
     }
     const query = hasInlineFilters ? inlineParse.residualQuery : rawQuery;
     const options = applyInlineQueryFilters(rawOptions, inlineParse.inlineFilters, inlineWarnings);
-    const highlight = options.highlight === true;
-    const includeLinked = parseIncludeLinked(options.includeLinked);
-    const titleExact = parseTitleExact(options.titleExact);
-    const phraseExact = parsePhraseExact(options.phraseExact);
-    const matchMode = parseMatchMode(typeof options.matchMode === "string" ? options.matchMode : undefined);
-    const minScoreOverride = parseMinScoreOverride(options.minScore);
-    const countOnly = options.count === true;
-    const tokens = parseTokens(query);
-    const normalizedQuery = normalizeSearchPhrase(query);
-    const limit = parseLimit(options.limit);
-    const projection = parseProjectionConfig(options);
-    const modeWasExplicit = typeof options.mode === "string" && options.mode.trim().length > 0;
+    return {
+        query,
+        options,
+        inlineWarnings,
+        highlight: options.highlight === true,
+        includeLinked: parseIncludeLinked(options.includeLinked),
+        titleExact: parseTitleExact(options.titleExact),
+        phraseExact: parsePhraseExact(options.phraseExact),
+        matchMode: parseMatchMode(typeof options.matchMode === "string" ? options.matchMode : undefined),
+        minScoreOverride: parseMinScoreOverride(options.minScore),
+        countOnly: options.count === true,
+        tokens: parseTokens(query),
+        normalizedQuery: normalizeSearchPhrase(query),
+        limit: parseLimit(options.limit),
+        projection: parseProjectionConfig(options),
+        modeWasExplicit: typeof options.mode === "string" && options.mode.trim().length > 0,
+    };
+}
+async function resolveSearchRuntimeContext(prepared, global) {
     const pmRoot = resolvePmRoot(process.cwd(), global.path);
     if (!(await pathExists(getSettingsPath(pmRoot)))) {
         throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
     }
     const storedSettings = await readSettings(pmRoot);
-    const runtimeDefaultsResolution = resolveSettingsWithSemanticRuntimeDefaults(storedSettings);
-    const settings = runtimeDefaultsResolution.settings;
+    const settings = resolveSettingsWithSemanticRuntimeDefaults(storedSettings).settings;
     const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);
     const runtimeFieldRegistry = resolveRuntimeFieldRegistry(settings.schema);
-    validateSearchProjectionFields(projection, runtimeFieldRegistry);
-    const runtimeFieldFilters = collectRuntimeFilterValues(options, runtimeFieldRegistry, "search");
-    // `pm search --status` resolves strictly (a typo'd status surfaces a
-    // did-you-mean hint) so agents can scope retrieval to open work and drop
-    // closed-history noise without re-listing. Resolved before the corpus scan so
-    // an invalid value fails fast.
-    const statusFilter = parseStatusFilterCsv(typeof options.status === "string" ? options.status : undefined, statusRegistry, { strict: true });
+    validateSearchProjectionFields(prepared.projection, runtimeFieldRegistry);
+    const runtimeFieldFilters = collectRuntimeFilterValues(prepared.options, runtimeFieldRegistry, "search");
     const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
-    const maxResults = resolveSearchMaxResults(settings);
-    // pm-cstl: --min-score overrides the persistent search.score_threshold for this
-    // query only; the effective threshold is reflected in filters.score_threshold.
-    const scoreThreshold = minScoreOverride ?? resolveSearchScoreThreshold(settings);
-    const semanticWeightProvided = options.semanticWeight !== undefined;
-    const semanticWeightOverride = parseSemanticWeightOverride(options.semanticWeight);
-    const hybridSemanticWeight = semanticWeightOverride ?? resolveHybridSemanticWeight(settings);
-    const tuning = resolveSearchTuning(settings);
     const providerResolution = resolveEmbeddingProviders(settings);
     const vectorResolution = resolveVectorStores(settings);
     const extensionSearchProvider = resolveExtensionSearchProvider(settings);
     const extensionVectorAdapter = resolveExtensionVectorAdapter(settings);
-    // pm-75k9: offline BM25 lexical provider. When active, a semantic/hybrid query
-    // ranks the corpus locally with BM25 instead of requiring an embedding service
-    // + vector store — enabling dense-quality offline retrieval in air-gapped, CI,
-    // and zero-setup environments. Resolved here so the semantic block can branch.
-    const bm25Mode = resolveBuiltInBm25Mode({
-        configuredProvider: toOptionalNonEmptyString(settings.search?.provider),
-        hasEmbeddingProvider: providerResolution.active !== null,
-        hasExtensionSearchProvider: extensionSearchProvider !== null,
-    });
+    const semanticWeightOverride = parseSemanticWeightOverride(prepared.options.semanticWeight);
     const queryExpansion = resolveQueryExpansionConfig(settings, providerResolution.active?.name ?? null);
     const rerank = resolveRerankConfig(settings, providerResolution.active?.model ?? toOptionalNonEmptyString(settings.search?.embedding_model) ?? "text-embedding-3-small");
-    const queryExpansionProvider = resolveExtensionSearchProviderByName(queryExpansion.provider ?? undefined);
-    const queryExpansionExtension = queryExpansionProvider?.queryExpansion
-        ? { providerName: queryExpansionProvider.providerName, expand: queryExpansionProvider.queryExpansion }
-        : null;
-    const rerankProvider = resolveExtensionSearchProviderByName(toOptionalNonEmptyString(settings.search?.provider));
-    const rerankExtension = rerankProvider?.rerank
-        ? { providerName: rerankProvider.providerName, rerank: rerankProvider.rerank }
-        : null;
-    let effectiveMode = parseMode(options.mode, {
-        hasProvider: providerResolution.active !== null || extensionSearchProvider !== null,
-        hasVectorStore: vectorResolution.active !== null || extensionVectorAdapter !== null,
-    });
-    const loadedDocuments = await loadDocuments(pmRoot, settings.item_format ?? "toon", typeRegistry.type_to_folder, settings.schema);
-    const warnings = loadedDocuments.warnings;
-    if (inlineWarnings.length > 0) {
-        warnings.push(...inlineWarnings);
+    return {
+        pmRoot,
+        settings,
+        statusRegistry,
+        runtimeFieldRegistry,
+        runtimeFieldFilters,
+        typeRegistry,
+        maxResults: resolveSearchMaxResults(settings),
+        scoreThreshold: prepared.minScoreOverride ?? resolveSearchScoreThreshold(settings),
+        semanticWeightProvided: prepared.options.semanticWeight !== undefined,
+        semanticWeightOverride,
+        hybridSemanticWeight: semanticWeightOverride ?? resolveHybridSemanticWeight(settings),
+        tuning: resolveSearchTuning(settings),
+        providerResolution,
+        vectorResolution,
+        extensionSearchProvider,
+        extensionVectorAdapter,
+        bm25Mode: resolveBuiltInBm25Mode({
+            configuredProvider: toOptionalNonEmptyString(settings.search?.provider),
+            hasEmbeddingProvider: providerResolution.active !== null,
+            hasExtensionSearchProvider: extensionSearchProvider !== null,
+        }),
+        queryExpansion,
+        queryExpansionExtension: resolveQueryExpansionExtension(queryExpansion),
+        rerank,
+        rerankExtension: resolveRerankExtension(settings),
+        effectiveMode: parseMode(prepared.options.mode, {
+            hasProvider: providerResolution.active !== null || extensionSearchProvider !== null,
+            hasVectorStore: vectorResolution.active !== null || extensionVectorAdapter !== null,
+        }),
+    };
+}
+async function loadFilteredSearchCorpus(prepared, runtime) {
+    const loadedDocuments = await loadDocuments(runtime.pmRoot, runtime.settings.item_format ?? "toon", runtime.typeRegistry.type_to_folder, runtime.settings.schema);
+    const statusFilter = parseStatusFilterCsv(typeof prepared.options.status === "string" ? prepared.options.status : undefined, runtime.statusRegistry, { strict: true });
+    const lifecycleClassifier = lifecycleClassifierFromStatusRegistry(runtime.statusRegistry);
+    const metadataFilteredDocuments = applyFilters(loadedDocuments.documents, prepared.options, runtime.typeRegistry, runtime.runtimeFieldFilters, statusFilter, lifecycleClassifier);
+    return {
+        warnings: loadedDocuments.warnings,
+        allDocuments: loadedDocuments.documents,
+        filteredDocuments: applyExactQueryFilters(metadataFilteredDocuments, prepared.normalizedQuery, {
+            titleExact: prepared.titleExact,
+            phraseExact: prepared.phraseExact || prepared.matchMode === "exact",
+        }),
+    };
+}
+async function collectLinkedCorpusById(includeLinked, effectiveMode, filteredDocuments) {
+    const linkedCorpusById = new Map();
+    if (!includeLinked || (effectiveMode !== "keyword" && effectiveMode !== "hybrid")) {
+        return linkedCorpusById;
     }
-    if (effectiveMode === "hybrid" && semanticWeightProvided && semanticWeightOverride === undefined) {
-        warnings.push("search_hybrid_semantic_weight_override_invalid:using_settings_default");
+    const projectRoot = process.cwd();
+    const linkedCorpusRoots = await resolveLinkedCorpusRoots(projectRoot, resolveGlobalPmRoot(projectRoot));
+    const linkedCorpusEntries = await Promise.all(filteredDocuments.map(async (document) => [document.metadata.id, await loadLinkedCorpus(document, linkedCorpusRoots)]));
+    for (const [id, corpus] of linkedCorpusEntries) {
+        linkedCorpusById.set(id, corpus);
+    }
+    return linkedCorpusById;
+}
+async function computeKeywordSearchHits(prepared, runtime, filteredDocuments) {
+    const linkedCorpusById = await collectLinkedCorpusById(prepared.includeLinked, runtime.effectiveMode, filteredDocuments);
+    const applyCoverageBonus = prepared.matchMode === "or";
+    return filteredDocuments
+        .map((document) => buildHybridLexicalScore(document, prepared.tokens, prepared.normalizedQuery, prepared.includeLinked, linkedCorpusById, runtime.tuning, runtime.settings.id_prefix, applyCoverageBonus))
+        .filter((entry) => entry !== null)
+        .filter((entry) => prepared.matchMode !== "and" || entry.matched_all_terms === true);
+}
+function buildEmptySearchResultFromContext(response, countOnly) {
+    return emptySearchResult(response.query, response.effectiveMode, response.matchMode, response.options, response.includeLinked, response.scoreThreshold, response.hybridSemanticWeight, response.queryExpansion, response.rerank, response.projection, response.warnings, response.runtimeFieldFilters, countOnly);
+}
+async function executeBuiltInBm25Search(prepared, runtime, filteredDocuments, keywordHits, warnings) {
+    if (runtime.bm25Mode === null || runtime.effectiveMode === "keyword") {
+        return null;
     }
-    const allDocuments = loadedDocuments.documents;
-    const lifecycleClassifier = lifecycleClassifierFromStatusRegistry(statusRegistry);
-    const metadataFilteredDocuments = applyFilters(allDocuments, options, typeRegistry, runtimeFieldFilters, statusFilter, lifecycleClassifier);
-    const filteredDocuments = applyExactQueryFilters(metadataFilteredDocuments, normalizedQuery, {
-        titleExact,
-        // --match-mode exact reuses the exact-phrase containment logic so the whole
-        // normalized query must appear as a contiguous phrase in some searchable field.
-        phraseExact: phraseExact || matchMode === "exact",
+    const hits = computeBuiltInBm25Hits({
+        requestedMode: runtime.effectiveMode,
+        query: prepared.query,
+        filteredDocuments,
+        keywordHits,
+        corpusFields: resolveSearchCorpusFields(runtime.settings),
+        bm25Params: resolveBm25Params(runtime.settings),
+        hybridSemanticWeight: runtime.hybridSemanticWeight,
     });
-    if (effectiveMode === "keyword" && (filteredDocuments.length === 0 || limit === 0)) {
-        return emptySearchResult(query, effectiveMode, matchMode, options, includeLinked, scoreThreshold, hybridSemanticWeight, queryExpansion, rerank, projection, warnings, runtimeFieldFilters, countOnly);
+    if (runtime.bm25Mode === "auto-fallback") {
+        warnings.push(`search_${runtime.effectiveMode}_offline_bm25:no_embedding_provider:using_lexical_bm25`);
     }
-    const projectRoot = process.cwd();
-    const globalRoot = resolveGlobalPmRoot(projectRoot);
-    const linkedCorpusById = new Map();
-    if (includeLinked && (effectiveMode === "keyword" || effectiveMode === "hybrid")) {
-        const linkedCorpusRoots = await resolveLinkedCorpusRoots(projectRoot, globalRoot);
-        const linkedCorpusEntries = await Promise.all(filteredDocuments.map(async (document) => [document.metadata.id, await loadLinkedCorpus(document, linkedCorpusRoots)]));
-        for (const [id, corpus] of linkedCorpusEntries) {
-            linkedCorpusById.set(id, corpus);
+    return hits;
+}
+async function executeExtensionSearchProvider(prepared, runtime, filteredDocuments, filteredById) {
+    if (!runtime.extensionSearchProvider) {
+        return null;
+    }
+    const canUseBuiltInSemantic = runtime.providerResolution.active !== null &&
+        (runtime.vectorResolution.active !== null || runtime.extensionVectorAdapter !== null);
+    try {
+        const providerResponse = await Promise.resolve(runtime.extensionSearchProvider.query({
+            query: prepared.query,
+            mode: runtime.effectiveMode,
+            tokens: prepared.tokens,
+            options: prepared.options,
+            settings: runtime.settings,
+            documents: filteredDocuments,
+        }));
+        return normalizeExtensionProviderHits(runtime.extensionSearchProvider.providerName, providerResponse, filteredById);
+    }
+    catch (error) {
+        if (!canUseBuiltInSemantic) {
+            throw new PmCliError(`Extension search provider "${runtime.extensionSearchProvider.providerName}" failed: ${error instanceof Error ? error.message : String(error)}`, EXIT_CODE.GENERIC_FAILURE);
         }
+        return null;
     }
-    // GH-181: the all-terms coverage RANKING bonus only applies in default OR mode
-    // (no hard term filter) so multi-term queries prefer items covering all tokens.
-    // and/exact modes hard-filter instead, so the additive bonus would be redundant.
-    const applyCoverageBonus = matchMode === "or";
-    const keywordHits = filteredDocuments
-        .map((document) => buildHybridLexicalScore(document, tokens, normalizedQuery, 
-    // Linked corpus is only collected into linkedCorpusById when the user
-    // passed --include-linked (and mode is keyword/hybrid), so pass the
-    // parsed flag directly rather than re-deriving it from the mode.
-    includeLinked, linkedCorpusById, tuning, settings.id_prefix, applyCoverageBonus))
-        .filter((entry) => entry !== null)
-        // --match-mode and: hard-filter to items where EVERY distinct query token
-        // matched some searchable field.
-        .filter((entry) => matchMode !== "and" || entry.matched_all_terms === true);
+}
+function maybeApplyNoVectorFallback(effectiveMode, semanticResult, keywordHits, warnings) {
+    if (semanticResult.vectorMatchCount > 0) {
+        return semanticResult.hits;
+    }
+    warnings.push(`search_${effectiveMode}_degraded:no_vector_matches:results_are_lexical`);
+    return effectiveMode === "semantic" ? keywordHits : semanticResult.hits;
+}
+async function prepareBuiltInSemanticSearch(runtime, effectiveMode, filteredDocuments, warnings, modeWasExplicit) {
+    const builtInSemanticWillRun = !runtime.extensionSearchProvider &&
+        runtime.providerResolution.active !== null &&
+        (runtime.vectorResolution.active !== null || runtime.extensionVectorAdapter !== null);
+    if (modeWasExplicit && builtInSemanticWillRun) {
+        await maybeEmitVectorIndexStaleWarning(runtime.pmRoot, filteredDocuments, warnings);
+    }
+    if (!runtime.extensionSearchProvider) {
+        requireSemanticDependencies(effectiveMode, runtime.providerResolution, runtime.vectorResolution, runtime.extensionVectorAdapter !== null);
+    }
+}
+async function executeSemanticSearch(input) {
+    const { prepared, runtime, filteredDocuments, keywordHits, warnings, modeWasExplicit } = input;
     let hits = keywordHits;
-    // pm-75k9: offline BM25 path. Runs entirely in-process (no embedding service,
-    // vector store, or HTTP), so it sits OUTSIDE the semantic try/catch fallback
-    // block below — it cannot fail on a backend error. Empty corpus / limit-0 are
-    // handled by the shared threshold+limit path that follows, so no early-return
-    // guard is needed here.
-    const useBuiltInBm25 = bm25Mode !== null && effectiveMode !== "keyword";
-    if (bm25Mode !== null && effectiveMode !== "keyword") {
-        hits = computeBuiltInBm25Hits({
-            requestedMode: effectiveMode,
-            query,
-            filteredDocuments,
-            keywordHits,
-            corpusFields: resolveSearchCorpusFields(settings),
-            bm25Params: resolveBm25Params(settings),
-            hybridSemanticWeight,
-        });
-        if (bm25Mode === "auto-fallback") {
-            warnings.push(`search_${effectiveMode}_offline_bm25:no_embedding_provider:using_lexical_bm25`);
-        }
+    const bm25Hits = await executeBuiltInBm25Search(prepared, runtime, filteredDocuments, keywordHits, warnings);
+    const semanticMode = runtime.effectiveMode;
+    if (bm25Hits !== null || semanticMode === "keyword") {
+        return { effectiveMode: runtime.effectiveMode, hits: bm25Hits ?? hits };
     }
-    /* c8 ignore start -- semantic/provider fallback + compact/count warning-shape permutations are covered by integration command-contract tests */
-    if (effectiveMode !== "keyword" && !useBuiltInBm25) {
-        // Surface vector-index staleness once per query so agents notice when a
-        // refresh is overdue. Only emitted when:
-        //   (1) the user explicitly asked for semantic/hybrid mode (implicit
-        //       upgrades fall back silently to keyword on any failure path below
-        //       and shouldn't carry noise), AND
-        //   (2) the BUILT-IN semantic path is what will run — an extension search
-        //       provider has its own indexing lifecycle and the local ledger we
-        //       read is irrelevant to it.
-        const builtInSemanticWillRun = !extensionSearchProvider &&
-            providerResolution.active !== null &&
-            (vectorResolution.active !== null || extensionVectorAdapter !== null);
-        if (modeWasExplicit && builtInSemanticWillRun) {
-            await maybeEmitVectorIndexStaleWarning(pmRoot, filteredDocuments, warnings);
-        }
-        try {
-            if (!extensionSearchProvider) {
-                requireSemanticDependencies(effectiveMode, providerResolution, vectorResolution, extensionVectorAdapter !== null);
-            }
-            if (filteredDocuments.length === 0 || limit === 0) {
-                return emptySearchResult(query, effectiveMode, matchMode, options, includeLinked, scoreThreshold, hybridSemanticWeight, queryExpansion, rerank, projection, warnings, runtimeFieldFilters, countOnly);
-            }
-            const filteredById = new Map(filteredDocuments.map((document) => [document.metadata.id, document]));
-            const canUseBuiltInSemantic = providerResolution.active !== null && (vectorResolution.active !== null || extensionVectorAdapter !== null);
-            if (extensionSearchProvider) {
-                try {
-                    const providerResponse = await Promise.resolve(extensionSearchProvider.query({
-                        query,
-                        mode: effectiveMode,
-                        tokens,
-                        options,
-                        settings,
-                        documents: filteredDocuments,
-                    }));
-                    hits = normalizeExtensionProviderHits(extensionSearchProvider.providerName, providerResponse, filteredById);
-                }
-                catch (error) {
-                    if (!canUseBuiltInSemantic) {
-                        throw new PmCliError(`Extension search provider "${extensionSearchProvider.providerName}" failed: ${error instanceof Error ? error.message : String(error)}`, EXIT_CODE.GENERIC_FAILURE);
-                    }
-                }
-            }
-            if (hits === keywordHits) {
-                const implicitHybridMode = !modeWasExplicit && effectiveMode === "hybrid";
-                const { provider, vectorStore } = requireSemanticDependencies(effectiveMode, providerResolution, vectorResolution, extensionVectorAdapter !== null);
-                const semanticResult = await computeSemanticOrHybridHits({
-                    requestedMode: effectiveMode,
-                    query,
-                    filteredDocuments,
-                    keywordHits,
-                    hybridSemanticWeight,
-                    limit,
-                    maxResults,
-                    provider,
-                    vectorStore,
-                    extensionVectorAdapter,
-                    queryExpansion,
-                    queryExpansionExtension,
-                    rerank,
-                    rerankExtension,
-                    warnings,
-                    settings,
-                    /* c8 ignore next 5 -- reserved for future implicit-hybrid auto-mode; current parseMode defaults keyword when mode is omitted */
-                    ...(implicitHybridMode
-                        ? {
-                            embeddingTimeoutMs: IMPLICIT_HYBRID_EMBEDDING_TIMEOUT_MS,
-                            vectorQueryTimeoutMs: IMPLICIT_HYBRID_VECTOR_TIMEOUT_MS,
-                        }
-                        : {}),
-                });
-                hits = semanticResult.hits;
-                // The semantic/hybrid query ran without error, but vector ranking
-                // contributed no hits for this query/filter set. Pure semantic mode would
-                // otherwise return an empty set, so degrade to the locally computed
-                // keyword hits (hybrid already blends them in) and warn so agents do not
-                // mistake them for true vector ranking. The reported mode is left
-                // unchanged; the warning is the signal.
-                if (semanticResult.vectorMatchCount === 0) {
-                    if (effectiveMode === "semantic") {
-                        hits = keywordHits;
-                    }
-                    warnings.push(`search_${effectiveMode}_degraded:no_vector_matches:results_are_lexical`);
-                }
-            }
-        }
-        catch (error) {
-            // Any semantic/hybrid attempt that fails (backend down, timeout, or the
-            // project is not configured for semantic search) degrades to keyword mode
-            // so agents are never blocked. Keyword hits are always computed locally
-            // before this point, so the fallback is guaranteed to succeed.
-            const fallbackWarning = modeWasExplicit
-                ? buildExplicitSemanticFallbackWarning(effectiveMode, error)
-                /* c8 ignore next -- reserved for future implicit semantic/hybrid auto-mode fallback */
-                : buildImplicitSemanticFallbackWarning(error);
-            effectiveMode = "keyword";
-            hits = keywordHits;
-            warnings.push(fallbackWarning);
+    try {
+        await prepareBuiltInSemanticSearch(runtime, semanticMode, filteredDocuments, warnings, modeWasExplicit);
+        if (filteredDocuments.length === 0 || prepared.limit === 0) {
+            return { effectiveMode: runtime.effectiveMode, hits: [] };
         }
-    }
-    // GH-281: an exact full-ID / short-ID match is always retained regardless of
-    // the (possibly user-raised --min-score) threshold so the exact-target lookup
-    // is never silently dropped in any mode.
-    const thresholded = hits.filter((entry) => entry.exact_id_match === true || entry.score >= scoreThreshold);
-    const sorted = sortHits(thresholded, statusRegistry);
-    // total = matched hits after filters + threshold, BEFORE limit truncation.
-    const total = sorted.length;
-    // GH-181: keyword mode now also falls back to the configured max_results (50)
-    // default when --limit is omitted, so a broad query no longer returns ALL hits.
-    const resolvedLimit = limit ?? maxResults;
-    const limited = sorted.slice(0, resolvedLimit);
-    const projectionFields = projection.mode === "full" ? null : [...projection.fields];
-    const compactSummaryMode = projection.mode === "compact" && options.compact === true;
-    // --count: count-only response. Skips projecting/returning hit rows entirely so
-    // an agent asking "how many" pays minimal tokens. `count` carries the matched
-    // total (post-filter, post-threshold, pre-limit).
-    if (countOnly) {
-        if (compactSummaryMode) {
-            const compactFilters = buildCompactSearchFilterSummary({
-                mode: effectiveMode,
-                matchMode,
-                options,
-                includeLinked,
-                titleExact,
-                phraseExact,
-                scoreThreshold,
-                hybridSemanticWeight,
-                runtimeFieldFilters,
+        const filteredById = new Map(filteredDocuments.map((document) => [document.metadata.id, document]));
+        hits = await executeExtensionSearchProvider(prepared, runtime, filteredDocuments, filteredById) ?? hits;
+        if (hits === keywordHits) {
+            const { provider, vectorStore } = requireSemanticDependencies(semanticMode, runtime.providerResolution, runtime.vectorResolution, runtime.extensionVectorAdapter !== null);
+            const semanticResult = await computeSemanticOrHybridHits({
+                requestedMode: semanticMode,
+                query: prepared.query,
+                filteredDocuments,
+                keywordHits,
+                hybridSemanticWeight: runtime.hybridSemanticWeight,
+                limit: prepared.limit,
+                maxResults: runtime.maxResults,
+                provider,
+                vectorStore,
+                extensionVectorAdapter: runtime.extensionVectorAdapter,
+                queryExpansion: runtime.queryExpansion,
+                queryExpansionExtension: runtime.queryExpansionExtension,
+                rerank: runtime.rerank,
+                rerankExtension: runtime.rerankExtension,
+                warnings,
+                settings: runtime.settings,
             });
-            return {
-                query: query.trim(),
-                mode: effectiveMode,
-                items: [],
-                count: total,
-                total,
-                count_only: true,
-                filters: compactFilters,
-                ...(warnings.length > 0 ? { warnings } : {}),
-            };
+            hits = maybeApplyNoVectorFallback(semanticMode, semanticResult, keywordHits, warnings);
         }
-        return {
-            query: query.trim(),
-            mode: effectiveMode,
+        return { effectiveMode: runtime.effectiveMode, hits };
+    }
+    catch (error) {
+        warnings.push(buildExplicitSemanticFallbackWarning(runtime.effectiveMode, error));
+        return { effectiveMode: "keyword", hits: keywordHits };
+    }
+}
+function buildCountOnlySearchResult(response, total) {
+    if (response.projection.mode === "compact" && response.options.compact === true) {
+        return withSearchWarnings({
+            query: response.query.trim(),
+            mode: response.effectiveMode,
             items: [],
             count: total,
             total,
             count_only: true,
-            filters: buildVerboseSearchFilters({
-                effectiveMode,
-                matchMode,
-                options,
-                includeLinked,
-                titleExact,
-                phraseExact,
-                scoreThreshold,
-                hybridSemanticWeight,
-                queryExpansion,
-                rerank,
-                runtimeFieldFilters,
+            filters: buildCompactSearchFilterSummary({
+                mode: response.effectiveMode,
+                matchMode: response.matchMode,
+                options: response.options,
+                includeLinked: response.includeLinked,
+                titleExact: response.titleExact,
+                phraseExact: response.phraseExact,
+                scoreThreshold: response.scoreThreshold,
+                hybridSemanticWeight: response.hybridSemanticWeight,
+                runtimeFieldFilters: response.runtimeFieldFilters,
             }),
-            projection: {
-                mode: projection.mode,
-                fields: projectionFields,
-            },
-            now: nowIso(),
-            ...(warnings.length > 0 ? { warnings } : {}),
-        };
+        }, response.warnings);
     }
-    // GH-157 --highlight: attach per-field matched-text snippets to the returned
-    // page of hits (only the post-limit slice pays the cost). In compact/fields
-    // projections we add "highlights" to the projected field set so the snippets
-    // are actually emitted; full mode already carries them on the hit.
-    let projectedHits = limited;
-    let effectiveProjection = projection;
-    if (highlight) {
-        const documentById = new Map(filteredDocuments.map((document) => [document.metadata.id, document]));
-        projectedHits = limited.map((hit) => ({
-            ...hit,
-            highlights: buildHitHighlights(documentById.get(hit.item.id), hit.matched_fields, tokens),
-        }));
-        if (projection.mode !== "full" && !projection.fields.includes("highlights")) {
-            effectiveProjection = { mode: projection.mode, fields: [...projection.fields, "highlights"] };
-        }
+    const projectionFields = response.projection.mode === "full" ? null : [...response.projection.fields];
+    return withSearchWarnings({
+        query: response.query.trim(),
+        mode: response.effectiveMode,
+        items: [],
+        count: total,
+        total,
+        count_only: true,
+        filters: buildVerboseSearchFilters({
+            effectiveMode: response.effectiveMode,
+            matchMode: response.matchMode,
+            options: response.options,
+            includeLinked: response.includeLinked,
+            titleExact: response.titleExact,
+            phraseExact: response.phraseExact,
+            scoreThreshold: response.scoreThreshold,
+            hybridSemanticWeight: response.hybridSemanticWeight,
+            queryExpansion: response.queryExpansion,
+            rerank: response.rerank,
+            runtimeFieldFilters: response.runtimeFieldFilters,
+        }),
+        projection: {
+            mode: response.projection.mode,
+            fields: projectionFields,
+        },
+        now: nowIso(),
+    }, response.warnings);
+}
+function withSearchWarnings(result, warnings) {
+    if (warnings.length === 0) {
+        return result;
     }
-    const projectedItems = projectSearchHits(projectedHits, effectiveProjection);
-    const finalProjectionFields = effectiveProjection.mode === "full" ? null : [...effectiveProjection.fields];
-    // Surface the pre-limit total only when the limit actually dropped rows.
-    const truncationExtras = limited.length < total ? { total } : {};
-    if (compactSummaryMode) {
-        const compactFilters = buildCompactSearchFilterSummary({
-            mode: effectiveMode,
-            matchMode,
-            options,
-            includeLinked,
-            titleExact,
-            phraseExact,
-            scoreThreshold,
-            hybridSemanticWeight,
-            runtimeFieldFilters,
-        });
-        return {
-            query: query.trim(),
-            mode: effectiveMode,
+    return { ...result, warnings };
+}
+function attachSearchHighlights(prepared, filteredDocuments, limited) {
+    if (!prepared.highlight) {
+        return { hits: limited, projection: prepared.projection };
+    }
+    const documentById = new Map(filteredDocuments.map((document) => [document.metadata.id, document]));
+    const hits = limited.map((hit) => ({
+        ...hit,
+        highlights: buildHitHighlights(documentById.get(hit.item.id), hit.matched_fields, prepared.tokens),
+    }));
+    if (prepared.projection.mode === "full" || prepared.projection.fields.includes("highlights")) {
+        return { hits, projection: prepared.projection };
+    }
+    return { hits, projection: { mode: prepared.projection.mode, fields: [...prepared.projection.fields, "highlights"] } };
+}
+function buildSearchResultForHits(response, projectedItems, total, limitedCount, effectiveProjection) {
+    const truncationExtras = limitedCount < total ? { total } : {};
+    if (response.projection.mode === "compact" && response.options.compact === true) {
+        return withSearchWarnings({
+            query: response.query.trim(),
+            mode: response.effectiveMode,
             items: projectedItems,
             count: projectedItems.length,
             ...truncationExtras,
-            filters: compactFilters,
-            ...(warnings.length > 0 ? { warnings } : {}),
-        };
+            filters: buildCompactSearchFilterSummary({
+                mode: response.effectiveMode,
+                matchMode: response.matchMode,
+                options: response.options,
+                includeLinked: response.includeLinked,
+                titleExact: response.titleExact,
+                phraseExact: response.phraseExact,
+                scoreThreshold: response.scoreThreshold,
+                hybridSemanticWeight: response.hybridSemanticWeight,
+                runtimeFieldFilters: response.runtimeFieldFilters,
+            }),
+        }, response.warnings);
     }
-    /* c8 ignore stop */
+    const finalProjectionFields = effectiveProjection.mode === "full" ? null : [...effectiveProjection.fields];
     return {
-        query: query.trim(),
-        mode: effectiveMode,
+        query: response.query.trim(),
+        mode: response.effectiveMode,
         items: projectedItems,
         count: projectedItems.length,
         ...truncationExtras,
         filters: buildVerboseSearchFilters({
-            effectiveMode,
-            matchMode,
-            options,
-            includeLinked,
-            titleExact,
-            phraseExact,
-            scoreThreshold,
-            hybridSemanticWeight,
-            queryExpansion,
-            rerank,
-            runtimeFieldFilters,
+            effectiveMode: response.effectiveMode,
+            matchMode: response.matchMode,
+            options: response.options,
+            includeLinked: response.includeLinked,
+            titleExact: response.titleExact,
+            phraseExact: response.phraseExact,
+            scoreThreshold: response.scoreThreshold,
+            hybridSemanticWeight: response.hybridSemanticWeight,
+            queryExpansion: response.queryExpansion,
+            rerank: response.rerank,
+            runtimeFieldFilters: response.runtimeFieldFilters,
         }),
         projection: {
             mode: effectiveProjection.mode,
             fields: finalProjectionFields,
         },
         now: nowIso(),
-        ...(warnings.length > 0 ? { warnings } : {}),
+        ...(response.warnings.length > 0 ? { warnings: response.warnings } : {}),
     };
 }
+/**
+ * Implements run search for the public runtime surface of this module.
+ */
+export async function runSearch(rawQuery, rawOptions, global) {
+    const prepared = prepareSearchInput(rawQuery, rawOptions);
+    const runtime = await resolveSearchRuntimeContext(prepared, global);
+    const corpus = await loadFilteredSearchCorpus(prepared, runtime);
+    const warnings = corpus.warnings;
+    warnings.push(...prepared.inlineWarnings);
+    if (runtime.effectiveMode === "hybrid" && runtime.semanticWeightProvided && runtime.semanticWeightOverride === undefined) {
+        warnings.push("search_hybrid_semantic_weight_override_invalid:using_settings_default");
+    }
+    const responseBase = {
+        query: prepared.query,
+        matchMode: prepared.matchMode,
+        options: prepared.options,
+        includeLinked: prepared.includeLinked,
+        titleExact: prepared.titleExact,
+        phraseExact: prepared.phraseExact,
+        scoreThreshold: runtime.scoreThreshold,
+        hybridSemanticWeight: runtime.hybridSemanticWeight,
+        queryExpansion: runtime.queryExpansion,
+        rerank: runtime.rerank,
+        projection: prepared.projection,
+        warnings,
+        runtimeFieldFilters: runtime.runtimeFieldFilters,
+    };
+    if (runtime.effectiveMode === "keyword" && (corpus.filteredDocuments.length === 0 || prepared.limit === 0)) {
+        return buildEmptySearchResultFromContext({ ...responseBase, effectiveMode: runtime.effectiveMode }, prepared.countOnly);
+    }
+    const keywordHits = await computeKeywordSearchHits(prepared, runtime, corpus.filteredDocuments);
+    const modeResult = await executeSemanticSearch({
+        prepared,
+        runtime,
+        filteredDocuments: corpus.filteredDocuments,
+        keywordHits,
+        warnings,
+        modeWasExplicit: prepared.modeWasExplicit,
+    });
+    if (modeResult.effectiveMode !== "keyword" && modeResult.hits.length === 0 && (corpus.filteredDocuments.length === 0 || prepared.limit === 0)) {
+        return buildEmptySearchResultFromContext({ ...responseBase, effectiveMode: modeResult.effectiveMode }, prepared.countOnly);
+    }
+    const thresholded = modeResult.hits.filter((entry) => entry.exact_id_match === true || entry.score >= runtime.scoreThreshold);
+    const sorted = sortHits(thresholded, runtime.statusRegistry);
+    const total = sorted.length;
+    const resolvedLimit = prepared.limit ?? runtime.maxResults;
+    const limited = sorted.slice(0, resolvedLimit);
+    const response = { ...responseBase, effectiveMode: modeResult.effectiveMode };
+    if (prepared.countOnly) {
+        return buildCountOnlySearchResult(response, total);
+    }
+    const { hits: projectedHits, projection: effectiveProjection } = attachSearchHighlights(prepared, corpus.filteredDocuments, limited);
+    const projectedItems = projectSearchHits(projectedHits, effectiveProjection);
+    return buildSearchResultForHits(response, projectedItems, total, limited.length, effectiveProjection);
+}
 //# sourceMappingURL=search.js.map
-//# debugId=0417fe76-c2a2-5a0a-82f3-0861f46175e9
+//# debugId=fe9c6a3a-fb99-53ed-9a6c-8c32bb745364