@unbrained/pm-cli 2026.6.30 → 2026.7.2

package/dist/cli-bundle/chunks/{chunk-6YRAMXRS.js → chunk-SYVUU7EK.js}

@@ -1,5 +1,5 @@
 
-!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]="a6961487-a640-50e7-980d-b3a9c0cc9651")}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]="02364b53-8625-5d05-90d9-1234e6d63964")}catch(e){}}();
 import {
   collectStaleVectorizationIds
 } from "./chunk-ROGZTCCB.js";
@@ -15,7 +15,7 @@ import {
   resolveSearchCorpusFields,
   resolveSettingsWithSemanticRuntimeDefaults,
   resolveVectorStores
-} from "./chunk-D5LYZVGB.js";
+} from "./chunk-TPOFWBMY.js";
 import {
   applyFilterValueEcho,
   buildContentFilterEcho,
@@ -26,7 +26,7 @@ import {
   parseStatusFilterCsv,
   resolveContentFieldFilters,
   resolveMissingMetadataFilters
-} from "./chunk-ZIE6WXJ2.js";
+} from "./chunk-Q6K2OACU.js";
 import {
   hasContentFieldFilter,
   itemMatchesContentFilters
@@ -35,27 +35,27 @@ import {
   hasMissingMetadataFilter,
   itemMatchesMissingMetadata,
   lifecycleClassifierFromStatusRegistry
-} from "./chunk-FDEVKXC4.js";
+} from "./chunk-EMPGXBUF.js";
 import {
   parseLimit,
   parsePriority,
   parseType
-} from "./chunk-JVQ7UOYC.js";
+} from "./chunk-2CHRYUXL.js";
 import {
   collectRegisteredItemFieldNames,
   listAllDocumentCandidatesCached,
   listAllFrontMatter,
   toItemRecord
-} from "./chunk-KGQ3W65B.js";
+} from "./chunk-NRZS637N.js";
 import {
   isTerminalStatus,
   parseItemDocument
-} from "./chunk-V3KLX7U7.js";
+} from "./chunk-KN3URLKS.js";
 import {
   compareTimestampStrings,
   nowIso,
   resolveIsoOrRelative
-} from "./chunk-KRASIL6M.js";
+} from "./chunk-K2VYLVX4.js";
 import {
   EXIT_CODE,
   PmCliError,
@@ -75,7 +75,7 @@ import {
   runActiveOnReadHooks,
   toNonEmptyString,
   toNonEmptyStringOrUndefined
-} from "./chunk-CY5IJMUM.js";
+} from "./chunk-I66WE2HE.js";
 
 // dist/cli/commands/search.js
 import fs from "node:fs/promises";
@@ -499,8 +499,6 @@ var LONG_QUERY_PHRASE_MULTIPLIER = 6;
 var ALL_TERMS_COVERAGE_BONUS = 40;
 var EXACT_ID_MATCH_SCORE = 1e3;
 var SHORT_ID_MATCH_SCORE = 900;
-var IMPLICIT_HYBRID_EMBEDDING_TIMEOUT_MS = 8e3;
-var IMPLICIT_HYBRID_VECTOR_TIMEOUT_MS = 8e3;
 var HIGHLIGHT_OPEN = "\xAB";
 var HIGHLIGHT_CLOSE = "\xBB";
 var HIGHLIGHT_SNIPPET_RADIUS = 60;
@@ -565,20 +563,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,
@@ -591,10 +589,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;
+}
 function collectErrorCauseCodes(error) {
   const codes = [];
   let current = error;
@@ -619,16 +620,6 @@ 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";
-}
 function buildExplicitSemanticFallbackWarning(requestedMode, error) {
   const reason = classifyImplicitSemanticFallbackReason(error);
   return `search_${requestedMode}_fallback:${reason}:using_keyword_mode`;
@@ -760,7 +751,6 @@ var _testOnlySearchCommand = {
   buildExplicitSemanticFallbackWarning,
   buildCompactSearchFilterSummary,
   buildHybridLexicalScore,
-  buildImplicitSemanticFallbackWarning,
   buildRerankCorpus,
   buildSemanticHits,
   classifyImplicitSemanticFallbackReason,
@@ -935,6 +925,9 @@ 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)
@@ -943,6 +936,9 @@ function matchesScalarSearchFilters(item, filters) {
     return false;
   if (filters.priorityFilter !== void 0 && 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))
@@ -955,6 +951,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 !== void 0 && item.assignee !== filters.assigneeFilter)
     return false;
   if (filters.sprintFilter !== void 0 && item.sprint !== filters.sprintFilter)
@@ -1159,26 +1158,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 = /* @__PURE__ */ 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),
@@ -1186,54 +1167,84 @@ function scoreDocument(document, tokens, normalizedQuery, linkedCorpus, tuning,
     })),
     { name: "linked_content", value: linkedCorpus, weight: tuning.linked_content_weight }
   ];
-  let score = 0;
-  const matched = /* @__PURE__ */ new Set();
-  const matchedTokens = /* @__PURE__ */ 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 = /* @__PURE__ */ 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: /* @__PURE__ */ new Set(), matchedTokens: /* @__PURE__ */ new Set() };
+  scoreTokenMatches(tokens, titleTokenCounts, searchableFields, tuning, state);
   const distinctTokens = new Set(tokens);
-  const matchedAllTerms = distinctTokens.size > 0 && matchedTokens.size === distinctTokens.size;
+  const matchedAllTerms = distinctTokens.size > 0 && state.matchedTokens.size === distinctTokens.size;
   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
   };
 }
@@ -1451,8 +1462,12 @@ 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 {
-    query
+    adapterName: runtimeAdapterName,
+    query,
+    ...typeof upsert === "function" ? { upsert } : {}
   };
 }
 function normalizeExtensionProviderHits(providerName, raw, filteredById) {
@@ -1619,52 +1634,151 @@ function buildRerankCorpus(document) {
     document.body
   ].map((entry) => typeof entry === "string" ? entry.trim() : "").filter((entry) => entry.length > 0).join("\n");
 }
-async function computeSemanticOrHybridHits(context) {
-  const semanticLimit = context.limit ?? context.maxResults;
-  const embeddingOptions = context.embeddingTimeoutMs !== void 0 ? { timeout_ms: context.embeddingTimeoutMs } : {};
-  const vectorQueryOptions = context.vectorQueryTimeoutMs !== void 0 ? { 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`);
-      }
-    } 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`);
+  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);
+    } 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
+      }));
+    } 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);
       }
-    }
-    if (context.vectorStore) {
+      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 === void 0) {
+      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 !== void 0 ? { timeout_ms: context.embeddingTimeoutMs } : {};
+  const vectorQueryOptions = context.vectorQueryTimeoutMs !== void 0 ? { 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);
@@ -1672,86 +1786,7 @@ async function computeSemanticOrHybridHits(context) {
   if (context.requestedMode === "semantic") {
     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 === void 0) {
-          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
@@ -1862,7 +1897,15 @@ function projectSearchHits(hits, projection) {
     return projected;
   });
 }
-async function runSearch(rawQuery, rawOptions, global) {
+function resolveQueryExpansionExtension(queryExpansion) {
+  const provider = resolveExtensionSearchProviderByName(queryExpansion.provider ?? void 0);
+  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;
@@ -1876,311 +1919,381 @@ 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 : void 0);
-  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 : void 0),
+    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");
-  const statusFilter = parseStatusFilterCsv(typeof options.status === "string" ? options.status : void 0, statusRegistry, { strict: true });
+  validateSearchProjectionFields(prepared.projection, runtimeFieldRegistry);
+  const runtimeFieldFilters = collectRuntimeFilterValues(prepared.options, runtimeFieldRegistry, "search");
   const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
-  const maxResults = resolveSearchMaxResults(settings);
-  const scoreThreshold = minScoreOverride ?? resolveSearchScoreThreshold(settings);
-  const semanticWeightProvided = options.semanticWeight !== void 0;
-  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);
-  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 ?? void 0);
-  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 !== void 0,
+    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 : void 0, 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 = /* @__PURE__ */ new Map();
+  if (!includeLinked || effectiveMode !== "keyword" && effectiveMode !== "hybrid") {
+    return linkedCorpusById;
   }
-  if (effectiveMode === "hybrid" && semanticWeightProvided && semanticWeightOverride === void 0) {
-    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 = /* @__PURE__ */ 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 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).filter((entry) => matchMode !== "and" || entry.matched_all_terms === true);
-  let hits = keywordHits;
-  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 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;
   }
-  if (effectiveMode !== "keyword" && !useBuiltInBm25) {
-    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;
-        if (semanticResult.vectorMatchCount === 0) {
-          if (effectiveMode === "semantic") {
-            hits = keywordHits;
-          }
-          warnings.push(`search_${effectiveMode}_degraded:no_vector_matches:results_are_lexical`);
-        }
-      }
-    } catch (error) {
-      const fallbackWarning = modeWasExplicit ? buildExplicitSemanticFallbackWarning(effectiveMode, error) : buildImplicitSemanticFallbackWarning(error);
-      effectiveMode = "keyword";
-      hits = keywordHits;
-      warnings.push(fallbackWarning);
-    }
+}
+function maybeApplyNoVectorFallback(effectiveMode, semanticResult, keywordHits, warnings) {
+  if (semanticResult.vectorMatchCount > 0) {
+    return semanticResult.hits;
   }
-  const thresholded = hits.filter((entry) => entry.exact_id_match === true || entry.score >= scoreThreshold);
-  const sorted = sortHits(thresholded, statusRegistry);
-  const total = sorted.length;
-  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;
-  if (countOnly) {
-    if (compactSummaryMode) {
-      const compactFilters = buildCompactSearchFilterSummary({
-        mode: effectiveMode,
-        matchMode,
-        options,
-        includeLinked,
-        titleExact,
-        phraseExact,
-        scoreThreshold,
-        hybridSemanticWeight,
-        runtimeFieldFilters
+  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;
+  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 };
+  }
+  try {
+    await prepareBuiltInSemanticSearch(runtime, semanticMode, filteredDocuments, warnings, modeWasExplicit);
+    if (filteredDocuments.length === 0 || prepared.limit === 0) {
+      return { effectiveMode: runtime.effectiveMode, hits: [] };
+    }
+    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
-      }),
-      projection: {
-        mode: projection.mode,
-        fields: projectionFields
-      },
-      now: nowIso(),
-      ...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);
+  }
+  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;
   }
-  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"] };
-    }
+  return { ...result, warnings };
+}
+function attachSearchHighlights(prepared, filteredDocuments, limited) {
+  if (!prepared.highlight) {
+    return { hits: limited, projection: prepared.projection };
   }
-  const projectedItems = projectSearchHits(projectedHits, effectiveProjection);
-  const finalProjectionFields = effectiveProjection.mode === "full" ? null : [...effectiveProjection.fields];
-  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,
+  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);
   }
+  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 } : {}
   };
 }
+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 === void 0) {
+    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);
+}
 
 export {
   collectErrorCauseCodes,
@@ -2192,6 +2305,6 @@ export {
   resolveSearchTuning,
   runSearch
 };
-//# sourceMappingURL=chunk-6YRAMXRS.js.map
+//# sourceMappingURL=chunk-SYVUU7EK.js.map
 
-//# debugId=a6961487-a640-50e7-980d-b3a9c0cc9651
+//# debugId=02364b53-8625-5d05-90d9-1234e6d63964