@unbrained/pm-cli 2026.9.19 → 2026.9.21

package/dist/sdk/query/search/corpus.d.ts

@@ -0,0 +1,27 @@
+import type { ItemDocument, ItemFormat, ItemMetadata, PmSettings } from "../../../types/index.js";
+import { type SearchMode } from "../search-rendering.js";
+/** Collect linked file and document paths eligible for optional search corpus enrichment. */
+declare function collectLinkedPaths(item: ItemMetadata): Array<{
+    scope: "project" | "global";
+    path: string;
+}>;
+interface ContainmentRoot {
+    resolved: string;
+    realpath: string;
+}
+interface LinkedCorpusRoots {
+    projectContainmentRoot: ContainmentRoot | null;
+    globalContainmentRoot: ContainmentRoot | null;
+}
+/** Resolve the workspace and global roots used to contain linked-content reads. */
+declare function resolveLinkedCorpusRoots(projectRoot: string, globalRoot: string): Promise<LinkedCorpusRoots>;
+/** Read eligible linked content while retaining lexical and canonical path containment checks. */
+declare function loadLinkedCorpus(document: ItemDocument, roots: LinkedCorpusRoots): Promise<string>;
+/** Load the searchable item corpus for the resolved tracker. */
+declare function loadDocuments(pmRoot: string, itemFormat: ItemFormat, typeToFolder: Record<string, string>, schema: PmSettings["schema"]): Promise<{
+    documents: ItemDocument[];
+    warnings: string[];
+}>;
+/** Build an item-ID lookup of linked content for provider execution and reranking. */
+declare function collectLinkedCorpusById(includeLinked: boolean, effectiveMode: SearchMode, filteredDocuments: ItemDocument[]): Promise<Map<string, string>>;
+export { collectLinkedCorpusById, collectLinkedPaths, loadDocuments, loadLinkedCorpus, resolveLinkedCorpusRoots };

package/dist/sdk/query/search/corpus.js

@@ -0,0 +1,2 @@
+!(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]="6e743cc1-3ff0-58b1-bf11-351d1655864c")}catch(e2){}})();import fs from"node:fs/promises";import path from"node:path";import{getActiveExtensionRegistrations,runActiveOnReadHooks}from"../../../core/extensions/index.js";import{collectRegisteredItemFieldNames}from"../../../core/extensions/item-fields.js";import{isPathWithinDirectory}from"../../../core/fs/path-utils.js";import{parseItemDocument}from"../../../core/item/item-format.js";import{listAllDocumentCandidatesCached}from"../../../core/store/item-metadata-cache.js";import{listAllItemMetadata}from"../../../core/store/item-store.js";import{getItemPath,resolveGlobalPmRoot}from"../../../core/store/paths.js";function collectLinkedPaths(item){const fromFiles=(item.files??[]).map(entry=>({scope:entry.scope,path:entry.path.trim()}));const fromDocs=(item.docs??[]).map(entry=>({scope:entry.scope,path:entry.path.trim()}));const fromTests=(item.tests??[]).filter(entry=>typeof entry.path==="string"&&entry.path.trim().length>0).map(entry=>({scope:entry.scope,path:entry.path.trim()}));const sorted=[...fromFiles,...fromDocs,...fromTests].filter(entry=>entry.path.length>0).sort((a,b)=>a.scope.localeCompare(b.scope)||a.path.localeCompare(b.path));const deduped=new Map;for(const entry of sorted){deduped.set(`${entry.scope}:${entry.path}`,entry)}return[...deduped.values()]}async function resolveContainmentRoot(root){const resolved=path.resolve(root);try{const realpathRoot=await fs.realpath(resolved);return{resolved,realpath:realpathRoot}}catch{return null}}async function resolveLinkedCorpusRoots(projectRoot,globalRoot){const[projectContainmentRoot,globalContainmentRoot]=await Promise.all([resolveContainmentRoot(projectRoot),resolveContainmentRoot(globalRoot)]);return{projectContainmentRoot,globalContainmentRoot}}async function loadLinkedCorpus(document,roots){const linkedPaths=collectLinkedPaths(document.metadata);const chunks=[];for(const linkedPath of linkedPaths){const containmentRoot=linkedPath.scope==="global"?roots.globalContainmentRoot:roots.projectContainmentRoot;if(!containmentRoot){continue}const resolved=path.resolve(containmentRoot.resolved,linkedPath.path);if(!isPathWithinDirectory(containmentRoot.resolved,resolved)){continue}let linkedRealpath;try{linkedRealpath=await fs.realpath(resolved)}catch{continue}if(!isPathWithinDirectory(containmentRoot.realpath,linkedRealpath)){continue}try{await runActiveOnReadHooks({path:resolved,scope:linkedPath.scope});chunks.push(await fs.readFile(resolved,"utf8"))}catch{}}return chunks.join("\n")}async function loadDocuments(pmRoot,itemFormat,typeToFolder,schema){const extensionFieldNames=collectRegisteredItemFieldNames(getActiveExtensionRegistrations());const readDocumentBody=async(metadata,preferredPath,preferredFormat)=>{const tryRead=async(targetPath,format)=>{await runActiveOnReadHooks({path:targetPath,scope:"project"});const raw=await fs.readFile(targetPath,"utf8");const parsed=parseItemDocument(raw,{format,schema,extensionFieldNames,onWarning:warning=>listWarnings.push(warning)});return parsed.body};try{return await tryRead(preferredPath,preferredFormat)}catch{const alternateFormat=preferredFormat==="toon"?"json_markdown":"toon";const alternatePath=getItemPath(pmRoot,metadata.type,metadata.id,alternateFormat,typeToFolder);try{return await tryRead(alternatePath,alternateFormat)}catch{listWarnings.push(`item_list_item_read_failed:${path.relative(pmRoot,alternatePath)}`);return""}}};const listWarnings=[];const cachedDocuments=await listAllDocumentCandidatesCached(pmRoot,itemFormat,typeToFolder,listWarnings,schema);const documents=[];if(cachedDocuments.length===0){const itemMetadataDocuments=await listAllItemMetadata(pmRoot,itemFormat,typeToFolder,listWarnings,schema);for(const metadata of itemMetadataDocuments){const preferredPath=getItemPath(pmRoot,metadata.type,metadata.id,itemFormat,typeToFolder);const body=await readDocumentBody(metadata,preferredPath,itemFormat);documents.push({metadata,body})}return{documents,warnings:[...new Set(listWarnings)].sort((left,right)=>left.localeCompare(right))}}for(const cachedDocument of cachedDocuments){if(typeof cachedDocument.body==="string"){documents.push({metadata:cachedDocument.metadata,body:cachedDocument.body});continue}const body=await readDocumentBody(cachedDocument.metadata,cachedDocument.item_path,cachedDocument.item_format);documents.push({metadata:cachedDocument.metadata,body})}return{documents,warnings:[...new Set(listWarnings)].sort((left,right)=>left.localeCompare(right))}}async function collectLinkedCorpusById(includeLinked,effectiveMode,filteredDocuments){const linkedCorpusById=new Map;if(!includeLinked||effectiveMode!=="keyword"&&effectiveMode!=="hybrid"){return linkedCorpusById}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}export{collectLinkedCorpusById,collectLinkedPaths,loadDocuments,loadLinkedCorpus,resolveLinkedCorpusRoots};
+//# sourceMappingURL=corpus.js.map

package/dist/sdk/query/search/filters.d.ts

@@ -0,0 +1,27 @@
+import { type LifecycleClassifier } from "../../../core/governance/metadata-coverage.js";
+import { type ItemTypeRegistry } from "../../../core/item/type-registry.js";
+import type { ItemDocument, ItemStatus } from "../../../types/index.js";
+import { type SearchOptions } from "../search-contracts.js";
+/** Normalize an unknown collection to its string entries for field filtering and scoring. */
+declare function stringArray(value: unknown): string[];
+/** Extract annotation text entries used by exact-phrase matching and lexical scoring. */
+declare function textEntries(value: unknown): Array<{
+    text: string;
+}>;
+/** Extract dependency metadata entries used by filtering and lexical scoring. */
+declare function dependencyEntries(value: unknown): Array<{
+    id: string;
+    kind: string;
+}>;
+/** Collect searchable text fields used by exact-phrase filtering. */
+declare function collectExactPhraseFields(document: ItemDocument): string[];
+/** Check whether any searchable field contains the normalized exact phrase. */
+declare function documentContainsExactPhrase(document: ItemDocument, normalizedQuery: string): boolean;
+/** Apply exact-title and exact-phrase restrictions before search ranking. */
+declare function applyExactQueryFilters(items: ItemDocument[], normalizedQuery: string, options: {
+    titleExact: boolean;
+    phraseExact: boolean;
+}): ItemDocument[];
+/** Apply metadata and runtime field predicates to the loaded item corpus. */
+declare function applyFilters(items: ItemDocument[], options: SearchOptions, typeRegistry: ItemTypeRegistry, runtimeFieldFilters: Record<string, unknown>, statusFilter: ItemStatus[] | undefined, lifecycleClassifier: LifecycleClassifier): ItemDocument[];
+export { applyExactQueryFilters, applyFilters, collectExactPhraseFields, dependencyEntries, documentContainsExactPhrase, stringArray, textEntries };

package/dist/sdk/query/search/filters.js

@@ -0,0 +1,2 @@
+!(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]="a5e4bd88-a099-559f-8194-7b56f325eb0e")}catch(e2){}})();import{hasContentFieldFilter,itemMatchesContentFilters}from"../../../core/governance/content-fields.js";import{hasMissingMetadataFilter,itemMatchesMissingMetadata}from"../../../core/governance/metadata-coverage.js";import{matchesRuntimeFilters}from"../../../core/schema/runtime-field-filters.js";import{buildEventCorpus,buildPlanFlatCorpus,buildReminderCorpus}from"../../../core/search/corpus.js";import{EXIT_CODE}from"../../../core/shared/constants.js";import{PmCliError}from"../../../core/shared/errors.js";import{matchesTimestampFilters}from"../../../core/shared/time.js";import{resolveContentFieldFilters,resolveMissingMetadataFilters}from"../list.js";import{parsePriorityFilterSet,parseStringFilterSet,parseTypeFilterSet}from"../multi-value-filters.js";import{normalizeSearchPhrase,parseSearchDeadline,parseTimestampWindow}from"../search-contracts.js";function stringArray(value){return Array.isArray(value)?value.filter(entry=>typeof entry==="string"):[]}function textEntries(value){return Array.isArray(value)?value.filter(entry=>typeof entry==="object"&&entry!==null&&typeof entry.text==="string"):[]}function dependencyEntries(value){return Array.isArray(value)?value.filter(entry=>typeof entry==="object"&&entry!==null&&typeof entry.id==="string"&&typeof entry.kind==="string"):[]}function collectExactPhraseFields(document){const item=document.metadata;return[item.title,item.description,item.status,stringArray(item.tags).join(" "),document.body,textEntries(item.comments).map(entry=>entry.text).join(" "),textEntries(item.notes).map(entry=>entry.text).join(" "),textEntries(item.learnings).map(entry=>entry.text).join(" "),buildReminderCorpus(item).join(" "),buildEventCorpus(item).join(" "),dependencyEntries(item.dependencies).map(entry=>`${entry.id} ${entry.kind}`).join(" "),buildPlanFlatCorpus(item)]}function documentContainsExactPhrase(document,normalizedQuery){return collectExactPhraseFields(document).some(fieldValue=>normalizeSearchPhrase(fieldValue).includes(normalizedQuery))}function applyExactQueryFilters(items,normalizedQuery,options){if(!options.titleExact&&!options.phraseExact){return items}return items.filter(document=>{if(options.titleExact&&normalizeSearchPhrase(document.metadata.title)!==normalizedQuery){return false}if(options.phraseExact&&!documentContainsExactPhrase(document,normalizedQuery)){return false}return true})}function assertSearchAssigneeFilter(assigneeFilter){if(assigneeFilter&&[...assigneeFilter].some(value=>value.toLowerCase()==="none"||value.toLowerCase()==="null")){throw new PmCliError('--assignee no longer accepts "none" or "null".',EXIT_CODE.USAGE)}}function resolveSearchMetadataFilterSet(options,typeRegistry,statusFilter){const assigneeFilter=parseStringFilterSet(options.assignee,{label:"--assignee"});assertSearchAssigneeFilter(assigneeFilter);const missingMetadataFilters=resolveMissingMetadataFilters(options);const contentFieldFilters=resolveContentFieldFilters(options);return{typeFilter:parseTypeFilterSet(options.type,typeRegistry),tagFilter:parseStringFilterSet(options.tag,{label:"--tag",normalize:tag=>tag.toLowerCase()}),priorityFilter:parsePriorityFilterSet(options.priority),deadlineBefore:parseSearchDeadline(options.deadlineBefore,"deadline-before"),deadlineAfter:parseSearchDeadline(options.deadlineAfter,"deadline-after"),updatedAfter:parseTimestampWindow(options.updatedAfter,"updated-after"),updatedBefore:parseTimestampWindow(options.updatedBefore,"updated-before"),createdAfter:parseTimestampWindow(options.createdAfter,"created-after"),createdBefore:parseTimestampWindow(options.createdBefore,"created-before"),assigneeFilter,sprintFilter:parseStringFilterSet(options.sprint,{label:"--sprint"}),releaseFilter:parseStringFilterSet(options.release,{label:"--release"}),parentFilter:options.parent?.trim(),statusSet:statusFilter&&statusFilter.length>0?new Set(statusFilter):void 0,missingMetadataFilters,missingMetadataActive:hasMissingMetadataFilter(missingMetadataFilters),contentFieldFilters,contentFiltersActive:hasContentFieldFilter(contentFieldFilters)}}function matchesScalarSearchFilters(item,filters){return matchesIdentitySearchFilters(item,filters)&&matchesTimestampFilters(item,filters)&&matchesOwnerSearchFilters(item,filters)}function matchesIdentitySearchFilters(item,filters){if(filters.statusSet&&!filters.statusSet.has(item.status))return false;if(filters.typeFilter&&!filters.typeFilter.has(item.type))return false;const tagFilter=filters.tagFilter;if(tagFilter&&!stringArray(item.tags).some(tag=>tagFilter.has(tag)))return false;if(filters.priorityFilter!==void 0&&!filters.priorityFilter.has(item.priority))return false;return true}function matchesOwnerSearchFilters(item,filters){if(filters.assigneeFilter!==void 0&&(item.assignee===void 0||!filters.assigneeFilter.has(item.assignee)))return false;if(filters.sprintFilter!==void 0&&(item.sprint===void 0||!filters.sprintFilter.has(item.sprint)))return false;if(filters.releaseFilter!==void 0&&(item.release===void 0||!filters.releaseFilter.has(item.release)))return false;if(filters.parentFilter!==void 0&&item.parent!==filters.parentFilter)return false;return true}function matchesSearchMetadataFilters(document,filters,runtimeFieldFilters,lifecycleClassifier){const item=document.metadata;if(!matchesScalarSearchFilters(item,filters)){return false}if(!matchesRuntimeFilters(item,runtimeFieldFilters)){return false}if(filters.missingMetadataActive&&!itemMatchesMissingMetadata(item,filters.missingMetadataFilters,lifecycleClassifier)){return false}if(filters.contentFiltersActive&&!itemMatchesContentFilters(item,filters.contentFieldFilters)){return false}return true}function applyFilters(items,options,typeRegistry,runtimeFieldFilters,statusFilter,lifecycleClassifier){const filters=resolveSearchMetadataFilterSet(options,typeRegistry,statusFilter);return items.filter(document=>matchesSearchMetadataFilters(document,filters,runtimeFieldFilters,lifecycleClassifier))}export{applyExactQueryFilters,applyFilters,collectExactPhraseFields,dependencyEntries,documentContainsExactPhrase,stringArray,textEntries};
+//# sourceMappingURL=filters.js.map

package/dist/sdk/query/search/input.d.ts

@@ -0,0 +1,28 @@
+import { type SearchOptions } from "../search-contracts.js";
+import type { PreparedSearchInput } from "./types.js";
+declare const INLINE_QUERY_FILTER_FIELDS: readonly ["tag", "status", "type", "priority"];
+type InlineQueryFilterField = (typeof INLINE_QUERY_FILTER_FIELDS)[number];
+/** Result of extracting inline `field:value` tokens from a raw search query. */
+interface InlineQueryParse {
+    /** The query with all recognized inline filter tokens removed. */
+    residualQuery: string;
+    /** Recognized inline filters keyed by field name; first occurrence per field wins. */
+    inlineFilters: Partial<Record<InlineQueryFilterField, string>>;
+}
+/**
+ * Split a raw search query into its residual keyword text and any inline
+ * `field:value` filter tokens (GH-157). Recognized fields are
+ * {@link INLINE_QUERY_FILTER_FIELDS}; the value runs to the end of the token so
+ * colon-bearing values like `tag:area:search` parse as `{ tag: "area:search" }`.
+ * Only the first occurrence of each field is captured — later duplicates are left
+ * in the residual query so they are never silently dropped. Tokens whose prefix
+ * is not a recognized field (`foo:bar`) stay in the residual query verbatim.
+ */
+declare function parseInlineQueryFilters(query: string): InlineQueryParse;
+/** Merge inline `field:value` filters into a search options object (GH-157). Explicit `--field` flags always win: an inline token is applied only when the corresponding option is not already set, and a conflicting inline token is recorded as a `search_inline_filter_ignored:<field>:flag_takes_precedence` warning so the override is observable rather than silent. Returns a fresh options object — the caller's input is never mutated. */
+declare function applyInlineQueryFilters(options: SearchOptions, inlineFilters: Partial<Record<InlineQueryFilterField, string>>, warnings: string[]): SearchOptions;
+/** Resolve inline filters, explicit options, tokenization and projection before accessing the search corpus. */
+declare function prepareSearchInput(rawQuery: string, rawOptions: SearchOptions): PreparedSearchInput;
+/** Reject incompatible paging options before search execution. */
+declare function assertSearchPagingOptions(options: SearchOptions): void;
+export { applyInlineQueryFilters, assertSearchPagingOptions, parseInlineQueryFilters, prepareSearchInput };

package/dist/sdk/query/search/input.js

@@ -0,0 +1,2 @@
+!(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]="5ff2b814-42b0-50fc-92dd-17e9fc521982")}catch(e2){}})();import{EXIT_CODE}from"../../../core/shared/constants.js";import{PmCliError}from"../../../core/shared/errors.js";import{toNonEmptyStringOrUndefined}from"../../../core/shared/primitives.js";import{parseLimit}from"../parsers.js";import{normalizeSearchPhrase,parseMinScoreOverride,parseSearchBoolean,parseSearchMatchMode,parseSearchProjection,parseSearchTokens}from"../search-contracts.js";const INLINE_QUERY_FILTER_FIELDS=["tag","status","type","priority"];function parseInlineQueryFilters(query){const inlineFilters={};const residualTokens=[];for(const token of query.split(/\s+/).filter(entry=>entry.length>0)){const separatorIndex=token.indexOf(":");const field=separatorIndex>0?token.slice(0,separatorIndex).toLowerCase():"";const value=separatorIndex>0?token.slice(separatorIndex+1):"";const matchedField=INLINE_QUERY_FILTER_FIELDS.includes(field)?field:void 0;if(matchedField&&value.length>0&&inlineFilters[matchedField]===void 0){inlineFilters[matchedField]=value;continue}residualTokens.push(token)}return{residualQuery:residualTokens.join(" "),inlineFilters}}function applyInlineQueryFilters(options,inlineFilters,warnings){const merged={...options};for(const field of INLINE_QUERY_FILTER_FIELDS){const inlineValue=inlineFilters[field];if(inlineValue===void 0){continue}if(toNonEmptyStringOrUndefined(merged[field])!==void 0){warnings.push(`search_inline_filter_ignored:${field}:flag_takes_precedence`);continue}merged[field]=inlineValue}return merged}function prepareSearchInput(rawQuery,rawOptions){const inlineWarnings=[];const inlineParse=parseInlineQueryFilters(rawQuery);const hasInlineFilters=Object.keys(inlineParse.inlineFilters).length>0;if(hasInlineFilters&&inlineParse.residualQuery.trim().length===0){throw new PmCliError("Inline field:value tokens consumed the entire query, leaving no search terms.",EXIT_CODE.USAGE,{examples:["pm search auth tag:area:search","pm list --tag area:search --status open"],nextSteps:["Add keyword terms alongside the inline filters, or use pm list for pure tag/status/type/priority filtering."]})}const query=hasInlineFilters?inlineParse.residualQuery:rawQuery;const options=applyInlineQueryFilters(rawOptions,inlineParse.inlineFilters,inlineWarnings);return{query,options,inlineWarnings,highlight:options.highlight===true,includeLinked:parseSearchBoolean(options.includeLinked),titleExact:parseSearchBoolean(options.titleExact),phraseExact:parseSearchBoolean(options.phraseExact),matchMode:parseSearchMatchMode(typeof options.matchMode==="string"?options.matchMode:void 0),minScoreOverride:parseMinScoreOverride(options.minScore),countOnly:options.count===true,tokens:parseSearchTokens(query),normalizedQuery:normalizeSearchPhrase(query),limit:parseLimit(options.limit),projection:parseSearchProjection(options,rawQuery),modeWasExplicit:typeof options.mode==="string"&&options.mode.trim().length>0}}function assertSearchPagingOptions(options){if(options.after!==void 0&&options.count===true){throw new PmCliError("Search --after cannot be combined with --count.",EXIT_CODE.USAGE)}}export{applyInlineQueryFilters,assertSearchPagingOptions,parseInlineQueryFilters,prepareSearchInput};
+//# sourceMappingURL=input.js.map

package/dist/sdk/query/search/lexical.d.ts

@@ -0,0 +1,34 @@
+import { type RuntimeStatusRegistry } from "../../../core/schema/runtime-schema.js";
+import type { ItemDocument } from "../../../types/index.js";
+import { type SearchTuning } from "../search-contracts.js";
+import type { SearchHit, SearchHitHighlight } from "./types.js";
+/** Count query-token occurrences in a searchable field for lexical scoring. */
+declare function countOccurrences(haystack: string, needle: string): number;
+/**
+ * Wrap every case-insensitive occurrence of any query token in `text` with the
+ * {@link HIGHLIGHT_OPEN}/{@link HIGHLIGHT_CLOSE} markers. Token boundaries follow
+ * the same substring semantics as the lexical scorer (a token highlights inside
+ * longer words, matching how it scored), and overlapping matches are coalesced
+ * by the single combined alternation so markers never nest.
+ */
+declare function markTokenRuns(text: string, tokens: string[]): string;
+/**
+ * Build a single highlighted snippet for one field value (GH-157), or null when
+ * no token matches. The snippet is a window of {@link HIGHLIGHT_SNIPPET_RADIUS}
+ * characters on each side of the first match with the matching token runs
+ * wrapped in markers, prefixed/suffixed with an ellipsis when the field text was
+ * trimmed. Returning null lets the caller skip fields with no concrete textual
+ * match (e.g. a field flagged purely by the phrase-coverage bonus).
+ */
+declare function highlightFieldSnippet(text: string, tokens: string[]): string | null;
+/** Produce per-field matched-text snippets for a hit (GH-157, `--highlight`). Iterates the hit's already-sorted `matched_fields`, retains only the document-derived searchable fields (skipping synthetic markers like `id`, `semantic`, `rerank`, and `linked_content`), and emits a snippet for each field that still contains a concrete token match. */
+declare function buildHitHighlights(document: ItemDocument, matchedFields: string[], tokens: string[]): SearchHitHighlight[];
+/** Score one item using weighted fields and the exact-ID ranking guarantee. */
+declare function scoreDocument(document: ItemDocument, tokens: string[], normalizedQuery: string, linkedCorpus: string, tuning: SearchTuning, idPrefix: string, applyCoverageBonus?: boolean): SearchHit | null;
+/** Order hits by descending relevance with deterministic item tie breakers. */
+declare function sortHits(items: SearchHit[], statusRegistry: RuntimeStatusRegistry): SearchHit[];
+/** Compute the lexical contribution used when blending keyword and semantic relevance. */
+declare function buildHybridLexicalScore(document: ItemDocument, tokens: string[], normalizedQuery: string, includeLinked: boolean, linkedCorpusById: Map<string, string>, tuning: SearchTuning, idPrefix: string, applyCoverageBonus?: boolean): SearchHit | null;
+/** Normalize provider score ranges before combining retrieval results. */
+declare function normalizeScoreMap(scoreById: Map<string, number>): Map<string, number>;
+export { buildHitHighlights, buildHybridLexicalScore, countOccurrences, highlightFieldSnippet, markTokenRuns, normalizeScoreMap, scoreDocument, sortHits };

package/dist/sdk/query/search/lexical.js

@@ -0,0 +1,2 @@
+!(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]="5a927991-1dbe-5906-a0eb-7da2534b6905")}catch(e2){}})();import{isTerminalStatus}from"../../../core/item/status.js";import{buildEventCorpus,buildPlanFlatCorpus,buildReminderCorpus}from"../../../core/search/corpus.js";import{tokenizeAlphaNumeric}from"../../../core/shared/text-normalization.js";import{compareTimestampStrings}from"../../../core/shared/time.js";import{normalizeSearchPhrase}from"../search-contracts.js";import{dependencyEntries,stringArray,textEntries}from"./filters.js";const LONG_QUERY_TOKEN_THRESHOLD=2;const LONG_QUERY_TITLE_EXACT_BONUS=120;const LONG_QUERY_PHRASE_MULTIPLIER=6;const ALL_TERMS_COVERAGE_BONUS=40;const EXACT_ID_MATCH_SCORE=1e3;const SHORT_ID_MATCH_SCORE=900;const HIGHLIGHT_OPEN="\xAB";const HIGHLIGHT_CLOSE="\xBB";const HIGHLIGHT_SNIPPET_RADIUS=60;function countOccurrences(haystack,needle){let count=0;let index=0;while(true){const foundAt=haystack.indexOf(needle,index);if(foundAt<0){return count}count+=1;index=foundAt+needle.length}}const SEARCHABLE_FIELD_BUILDERS=[{name:"title",weightKey:"title_weight",value:document=>document.metadata.title},{name:"description",weightKey:"description_weight",value:document=>document.metadata.description},{name:"tags",weightKey:"tags_weight",value:document=>stringArray(document.metadata.tags).join(" ")},{name:"status",weightKey:"status_weight",value:document=>typeof document.metadata.status==="string"?document.metadata.status:""},{name:"body",weightKey:"body_weight",value:document=>document.body},{name:"comments",weightKey:"comments_weight",value:document=>textEntries(document.metadata.comments).map(entry=>entry.text).join(" ")},{name:"notes",weightKey:"notes_weight",value:document=>textEntries(document.metadata.notes).map(entry=>entry.text).join(" ")},{name:"learnings",weightKey:"learnings_weight",value:document=>textEntries(document.metadata.learnings).map(entry=>entry.text).join(" ")},{name:"reminders",weightKey:"reminders_weight",value:document=>buildReminderCorpus(document.metadata).join(" ")},{name:"events",weightKey:"events_weight",value:document=>buildEventCorpus(document.metadata).join(" ")},{name:"dependencies",weightKey:"dependencies_weight",value:document=>dependencyEntries(document.metadata.dependencies).map(entry=>`${entry.id} ${entry.kind}`).join(" ")},{name:"plan",weightKey:"body_weight",value:document=>buildPlanFlatCorpus(document.metadata)}];const SEARCHABLE_FIELD_BUILDER_BY_NAME=new Map(SEARCHABLE_FIELD_BUILDERS.map(builder=>[builder.name,builder]));function markTokenRuns(text,tokens){const escaped=tokens.filter(token=>token.length>0).sort((left,right)=>right.length-left.length).map(value=>value.replace(/[.*+?^${}()|[\]\\]/g,"\\$&"));if(escaped.length===0){return text}const pattern=new RegExp(escaped.join("|"),"gi");return text.replace(pattern,match=>`${HIGHLIGHT_OPEN}${match}${HIGHLIGHT_CLOSE}`)}function highlightFieldSnippet(text,tokens){if(text.length===0){return null}const lowerText=text.toLowerCase();let firstMatchIndex=-1;let firstMatchLength=0;for(const token of tokens){if(token.length===0){continue}const index=lowerText.indexOf(token);if(index>=0&&(firstMatchIndex<0||index<firstMatchIndex)){firstMatchIndex=index;firstMatchLength=token.length}}if(firstMatchIndex<0){return null}const windowStart=Math.max(0,firstMatchIndex-HIGHLIGHT_SNIPPET_RADIUS);const windowEnd=Math.min(text.length,firstMatchIndex+firstMatchLength+HIGHLIGHT_SNIPPET_RADIUS);const marked=markTokenRuns(text.slice(windowStart,windowEnd),tokens);const prefix=windowStart>0?"\u2026":"";const suffix=windowEnd<text.length?"\u2026":"";return`${prefix}${marked}${suffix}`}function buildHitHighlights(document,matchedFields,tokens){const highlights=[];for(const field of matchedFields){const builder=SEARCHABLE_FIELD_BUILDER_BY_NAME.get(field);if(builder===void 0){continue}const snippet=highlightFieldSnippet(builder.value(document),tokens);if(snippet!==null){highlights.push({field,snippet})}}return highlights}function buildSearchableScoringFields(document,linkedCorpus,tuning){return[...SEARCHABLE_FIELD_BUILDERS.map(builder=>({name:builder.name,value:builder.value(document),weight:tuning[builder.weightKey]})),{name:"linked_content",value:linkedCorpus,weight:tuning.linked_content_weight}]}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){state.score+=exactTitleMatches*tuning.title_exact_bonus;state.matched.add("title");state.matchedTokens.add(token)}for(const field of searchableFields){const occurrences=countOccurrences(field.value.toLowerCase(),token);if(occurrences>0){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 tokenizeAlphaNumeric(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);const matchedAllTerms=distinctTokens.size>0&&state.matchedTokens.size===distinctTokens.size;if(applyCoverageBonus&&distinctTokens.size>1&&matchedAllTerms){state.score+=ALL_TERMS_COVERAGE_BONUS}const isLongPhraseQuery=tokens.length>=LONG_QUERY_TOKEN_THRESHOLD&&normalizedQuery.includes(" ");if(isLongPhraseQuery){scorePhraseMatches(item,normalizedQuery,searchableFields,state)}if(state.score<=0){return null}return{item,score:state.score,matched_fields:[...state.matched].sort((a,b)=>a.localeCompare(b)),matched_all_terms:matchedAllTerms}}function sortHits(items,statusRegistry){return[...items].sort((a,b)=>{const byScore=b.score-a.score;if(byScore!==0)return byScore;const aTerminal=isTerminalStatus(a.item.status,statusRegistry);const bTerminal=isTerminalStatus(b.item.status,statusRegistry);if(aTerminal!==bTerminal){return aTerminal?1:-1}const byPriority=a.item.priority-b.item.priority;if(byPriority!==0)return byPriority;const byUpdated=compareTimestampStrings(b.item.updated_at,a.item.updated_at);if(byUpdated!==0)return byUpdated;return a.item.id.localeCompare(b.item.id)})}function buildHybridLexicalScore(document,tokens,normalizedQuery,includeLinked,linkedCorpusById,tuning,idPrefix,applyCoverageBonus=false){return scoreDocument(document,tokens,normalizedQuery,includeLinked?linkedCorpusById.get(document.metadata.id)??"":"",tuning,idPrefix,applyCoverageBonus)}function normalizeScoreMap(scoreById){if(scoreById.size===0){return new Map}let minScore=Number.POSITIVE_INFINITY;let maxScore=Number.NEGATIVE_INFINITY;for(const score of scoreById.values()){minScore=Math.min(minScore,score);maxScore=Math.max(maxScore,score)}if(maxScore===minScore){return new Map([...scoreById.keys()].map(id=>[id,1]))}const normalized=new Map;for(const[id,score]of scoreById){normalized.set(id,(score-minScore)/(maxScore-minScore))}return normalized}export{buildHitHighlights,buildHybridLexicalScore,countOccurrences,highlightFieldSnippet,markTokenRuns,normalizeScoreMap,scoreDocument,sortHits};
+//# sourceMappingURL=lexical.js.map

package/dist/sdk/query/search/response.d.ts

@@ -0,0 +1,34 @@
+import { type QueryExpansionConfig, type RerankConfig } from "../../../core/search/relevance.js";
+import type { ItemDocument } from "../../../types/index.js";
+import { type WorkspaceMemoryRollup } from "../../workspace-memory.js";
+import { type SearchMatchMode, type SearchModeSource, type SearchOptions, type SearchProjectionConfig } from "../search-contracts.js";
+import { type SearchMode } from "../search-rendering.js";
+import type { PreparedSearchInput, SearchHit, SearchResponseContext, SearchResult, SearchResultItem } from "./types.js";
+/** Build a zero-hit response preserving the requested search mode and filters. */
+declare function emptySearchResult(query: string, mode: SearchMode, matchMode: SearchMatchMode, options: SearchOptions, includeLinked: boolean, scoreThreshold: number, hybridSemanticWeight: number, queryExpansion: QueryExpansionConfig, rerank: RerankConfig, projection: SearchProjectionConfig, warnings: string[], runtimeFieldFilters: Record<string, unknown> | undefined, countOnly: boolean, modeSource: SearchModeSource): SearchResult;
+/** Resolve a projected search field from item metadata or search-hit evidence. */
+declare function readSearchFieldValue(hit: SearchHit, field: string): unknown;
+/** Convert ranked hits into the requested compact, full or custom-field rows. */
+declare function projectSearchHits(hits: SearchHit[], projection: SearchProjectionConfig): SearchResultItem[];
+/** Build an empty result with the resolved search settings and warnings. */
+declare function buildEmptySearchResultFromContext(response: SearchResponseContext, countOnly: boolean): SearchResult;
+/** Return the matched total without materializing projected hit rows. */
+declare function buildCountOnlySearchResult(response: SearchResponseContext, total: number): SearchResult;
+/** Attach bounded historical workspace rollups when the query and workspace qualify. */
+declare function withSearchWorkspaceMemory(result: SearchResult, memory: {
+    cache_status: "fresh" | "rebuilt";
+    matches: WorkspaceMemoryRollup[];
+} | undefined): SearchResult;
+/** Add matched-field snippets only when highlighting was requested. */
+declare function attachSearchHighlights(prepared: PreparedSearchInput, filteredDocuments: ItemDocument[], limited: SearchHit[]): {
+    hits: SearchHit[];
+    projection: SearchProjectionConfig;
+};
+/** Apply search pagination and projection to the final ranked hit set. */
+declare function buildSearchResultForHits(response: SearchResponseContext, projectedItems: SearchResultItem[], total: number, limitedCount: number, effectiveProjection: SearchProjectionConfig, pageExtras: {
+    has_more?: boolean;
+    next_cursor?: string;
+    applied_limit: number;
+    truncated?: true;
+}): SearchResult;
+export { attachSearchHighlights, buildCountOnlySearchResult, buildEmptySearchResultFromContext, buildSearchResultForHits, emptySearchResult, projectSearchHits, readSearchFieldValue, withSearchWorkspaceMemory };

package/dist/sdk/query/search/response.js

@@ -0,0 +1,2 @@
+!(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]="984a6fdc-9383-5f89-8e71-b0d3ed2a35cc")}catch(e2){}})();import{toItemRecord}from"../../../core/item/item-record.js";import{nowIso}from"../../../core/shared/time.js";import{buildCompactSearchFilterSummary,buildVerboseSearchFilters}from"../search-rendering.js";import{buildHitHighlights}from"./lexical.js";function emptySearchResult(query,mode,matchMode,options,includeLinked,scoreThreshold,hybridSemanticWeight,queryExpansion,rerank,projection,warnings,runtimeFieldFilters,countOnly,modeSource){const countExtras=countOnly?{total:0,count_only:true}:{};const compactSummaryMode=projection.mode==="compact"&&options.compact===true;if(compactSummaryMode){const compactFilters=buildCompactSearchFilterSummary({mode,matchMode,options,includeLinked,titleExact:options.titleExact===true,phraseExact:options.phraseExact===true,scoreThreshold,hybridSemanticWeight,runtimeFieldFilters});return{query:query.trim(),mode,...compactModeSource(modeSource),items:[],count:0,...countExtras,filters:compactFilters,...warnings.length>0?{warnings}:{}}}const projectionFields=projection.mode==="full"?null:[...projection.fields];return{query:query.trim(),mode,mode_source:modeSource,items:[],count:0,...countExtras,filters:buildVerboseSearchFilters({effectiveMode:mode,matchMode,options,includeLinked,titleExact:options.titleExact===true,phraseExact:options.phraseExact===true,scoreThreshold,hybridSemanticWeight,queryExpansion,rerank,runtimeFieldFilters:runtimeFieldFilters??{}}),projection:{mode:projection.mode,fields:projectionFields},now:nowIso(),...warnings.length>0?{warnings}:{}}}function readSearchFieldValue(hit,field){const normalized=field.trim();if(normalized.length===0){return null}if(normalized==="score"){return hit.score}if(normalized==="matched_fields"){return hit.matched_fields}if(normalized.startsWith("item.")){const itemKey=normalized.slice("item.".length);if(itemKey.length===0){return null}const itemRecord2=toItemRecord(hit.item);return itemRecord2[itemKey]??null}const hitRecord=hit;const itemRecord=toItemRecord(hit.item);if(Object.prototype.hasOwnProperty.call(itemRecord,normalized)){return itemRecord[normalized]??null}if(Object.prototype.hasOwnProperty.call(hitRecord,normalized)){return hitRecord[normalized]??null}return null}function projectSearchHits(hits,projection){if(projection.mode==="full"){return hits.map(({matched_all_terms:_matchedAllTerms,exact_id_match:_exactIdMatch,...hit})=>hit)}return hits.map(hit=>{const projected={};for(const field of projection.fields){projected[field]=readSearchFieldValue(hit,field)}return projected})}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,response.modeSource)}function buildCountOnlySearchResult(response,total){if(response.projection.mode==="compact"&&response.options.compact===true){return withSearchWarnings({query:response.query.trim(),mode:response.effectiveMode,...compactModeSource(response.modeSource),items:[],count:total,total,count_only:true,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,mode_source:response.modeSource,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 compactModeSource(source){return source==="settings"?{mode_source:source}:{}}function withSearchWarnings(result,warnings){if(warnings.length===0){return result}return{...result,warnings}}function withSearchWorkspaceMemory(result,memory){return memory?{...result,workspace_memory:memory}:result}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,pageExtras){const truncationExtras=limitedCount<total?{total}:{};if(response.projection.mode==="compact"&&response.options.compact===true){return withSearchWarnings({query:response.query.trim(),mode:response.effectiveMode,...compactModeSource(response.modeSource),items:projectedItems,count:projectedItems.length,...truncationExtras,...pageExtras,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:response.query.trim(),mode:response.effectiveMode,mode_source:response.modeSource,items:projectedItems,count:projectedItems.length,...truncationExtras,...pageExtras,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:effectiveProjection.mode,fields:finalProjectionFields},now:nowIso(),...response.warnings.length>0?{warnings:response.warnings}:{}}}export{attachSearchHighlights,buildCountOnlySearchResult,buildEmptySearchResultFromContext,buildSearchResultForHits,emptySearchResult,projectSearchHits,readSearchFieldValue,withSearchWorkspaceMemory};
+//# sourceMappingURL=response.js.map

package/dist/sdk/query/search/semantic.d.ts

@@ -0,0 +1,229 @@
+import { type Bm25Params } from "../../../core/search/bm25.js";
+import { type EmbeddingProviderConfig, type EmbeddingProviderResolution } from "../../../core/search/providers.js";
+import { type QueryExpansionConfig, type RerankConfig } from "../../../core/search/relevance.js";
+import { type VectorQueryHit, type VectorStoreConfig, type VectorStoreResolution } from "../../../core/search/vector-stores.js";
+import { toNonEmptyStringOrUndefined } from "../../../core/shared/primitives.js";
+import type { ItemDocument, PmSettings } from "../../../types/index.js";
+import { type SearchOptions } from "../search-contracts.js";
+import { type SearchMode } from "../search-rendering.js";
+import type { SearchHit } from "./types.js";
+interface ExtensionSearchProviderContext {
+    query: string;
+    mode: SearchMode;
+    tokens: string[];
+    options: SearchOptions;
+    settings: PmSettings;
+    documents: ItemDocument[];
+}
+interface ExtensionSearchProviderHit {
+    id: string;
+    score: number;
+    matched_fields?: string[];
+}
+type ExtensionSearchProviderQuery = (context: ExtensionSearchProviderContext) => Promise<ExtensionSearchProviderHit[] | {
+    hits?: ExtensionSearchProviderHit[];
+}> | ExtensionSearchProviderHit[] | {
+    hits?: ExtensionSearchProviderHit[];
+};
+interface ExtensionSearchProviderQueryExpansionContext {
+    query: string;
+    mode: Exclude<SearchMode, "keyword">;
+    settings: PmSettings;
+}
+/** Optional provider hook used to expand a query before semantic retrieval. */
+type ExtensionSearchProviderQueryExpansion = (context: ExtensionSearchProviderQueryExpansionContext) => Promise<string[] | {
+    queries?: string[];
+}> | string[] | {
+    queries?: string[];
+};
+interface ExtensionSearchProviderRerankCandidate {
+    id: string;
+    text: string;
+    score: number;
+}
+interface ExtensionSearchProviderRerankContext {
+    query: string;
+    mode: "hybrid";
+    model: string;
+    top_k: number;
+    settings: PmSettings;
+    candidates: ExtensionSearchProviderRerankCandidate[];
+}
+/** Optional provider hook used to rerank retrieved candidates. */
+type ExtensionSearchProviderRerank = (context: ExtensionSearchProviderRerankContext) => Promise<Array<{
+    id?: unknown;
+    score?: unknown;
+}> | {
+    hits?: Array<{
+        id?: unknown;
+        score?: unknown;
+    }>;
+}> | Array<{
+    id?: unknown;
+    score?: unknown;
+}> | {
+    hits?: Array<{
+        id?: unknown;
+        score?: unknown;
+    }>;
+};
+type ExtensionVectorQuery = (context: {
+    vector: number[];
+    limit: number;
+    settings: PmSettings;
+}) => Promise<VectorQueryHit[]> | VectorQueryHit[];
+type ExtensionVectorUpsert = (context: {
+    points: Array<{
+        id: string;
+        vector: number[];
+        payload: Record<string, unknown>;
+    }>;
+    settings: PmSettings;
+}) => Promise<void> | void;
+type ExtensionVectorAdapter = {
+    adapterName: string;
+    query?: ExtensionVectorQuery;
+    upsert?: ExtensionVectorUpsert;
+};
+type ImplicitSemanticFallbackReason = "timeout" | "connection" | "error";
+/**
+ * Aggregate the `code` strings found along an error's `cause` chain.
+ *
+ * undici (Node's fetch) collapses connection errors to the generic message
+ * "fetch failed" and stashes the real syscall code (e.g. `ECONNREFUSED`) on
+ * `error.cause.code`. Walking the chain (bounded depth) lets the fallback
+ * classifier label a downed/unreachable Ollama backend as "connection" rather
+ * than the catch-all "error".
+ */
+export declare function collectErrorCauseCodes(error: unknown): string;
+/**
+ * Classify why an implicit/explicit semantic search degraded to keyword mode,
+ * inspecting both the error message and the {@link collectErrorCauseCodes} chain
+ * so undici's generic "fetch failed" is recognised as a connection failure.
+ */
+export declare function classifyImplicitSemanticFallbackReason(error: unknown): ImplicitSemanticFallbackReason;
+/** Describe why an explicitly requested semantic mode fell back to keyword retrieval. */
+declare function buildExplicitSemanticFallbackWarning(requestedMode: SearchMode, error: unknown): string;
+interface VectorIndexRecoveryRegistrations {
+    commands?: readonly {
+        command: string;
+    }[];
+}
+interface VectorIndexRecovery {
+    command: string;
+    args: string[];
+    follow_up_command?: string;
+    follow_up_args?: string[];
+}
+/** Resolve an executable reindex path from the active extension capability surface. */
+export declare function resolveVectorIndexRecovery(registrations: VectorIndexRecoveryRegistrations | null): VectorIndexRecovery;
+/** Compare the vectorization-status ledger against the filtered corpus and, when the vector index is behind, emit a one-line stderr warning plus a structured `vector_index_stale:N` entry in the JSON warnings array. Best-effort: ledger read failures fall through silently — the existing semantic/hybrid fallback paths cover backend errors. */
+declare function maybeEmitVectorIndexStaleWarning(pmRoot: string, filteredDocuments: ItemDocument[], warnings: string[]): Promise<void>;
+/** Format token-efficient vector-index staleness and executable recovery warnings. */
+export declare function formatVectorIndexRecoveryWarnings(staleCount: number, recovery: VectorIndexRecovery): string[];
+/** Resolve the configured semantic provider and vector-store dependencies or report their absence. */
+declare function requireSemanticDependencies(requestedMode: Exclude<SearchMode, "keyword">, providerResolution: EmbeddingProviderResolution, vectorResolution: VectorStoreResolution, hasExtensionVectorQuery: boolean): {
+    provider: EmbeddingProviderConfig;
+    vectorStore: VectorStoreConfig | null;
+};
+/** Normalize optional provider identifiers to trimmed non-empty strings. */
+declare const toOptionalNonEmptyString: typeof toNonEmptyStringOrUndefined;
+interface ExtensionSearchProviderHooks {
+    providerName: string;
+    query?: ExtensionSearchProviderQuery;
+    queryExpansion?: ExtensionSearchProviderQueryExpansion;
+    rerank?: ExtensionSearchProviderRerank;
+}
+/** Find an active extension search provider by its declared name. */
+declare function resolveExtensionSearchProviderByName(providerName: string | undefined): ExtensionSearchProviderHooks | null;
+/** Resolve the configured extension-owned search provider. */
+declare function resolveExtensionSearchProvider(settings: PmSettings): {
+    providerName: string;
+    query: ExtensionSearchProviderQuery;
+} | null;
+/** Resolve the configured extension-owned vector-store adapter. */
+declare function resolveExtensionVectorAdapter(settings: PmSettings): ExtensionVectorAdapter | null;
+/** Normalize extension retrieval results to item IDs and numeric scores. */
+declare function normalizeExtensionProviderHits(providerName: string, raw: unknown, filteredById: Map<string, ItemDocument>): SearchHit[];
+/** Join semantic scores to the filtered item corpus. */
+declare function buildSemanticHits(vectorHits: VectorQueryHit[], filteredById: Map<string, ItemDocument>): {
+    semanticHits: SearchHit[];
+    semanticScores: Map<string, number>;
+};
+/** Blend lexical and semantic results while preserving exact-ID precedence. */
+declare function combineHybridHits(filteredById: Map<string, ItemDocument>, semanticScores: Map<string, number>, keywordHits: SearchHit[], hybridSemanticWeight: number, semanticFieldLabel?: string): SearchHit[];
+/** Built-in BM25 activation outcome for semantic/hybrid search (pm-75k9): - `"explicit"`: `search.provider` is `bm25` — the user opted into offline lexical ranking, so it is used even if an embedding provider is configured. - `"auto-fallback"`: `search.provider` is `auto` and neither an embedding provider nor an extension search provider is available — BM25 is used in place of degrading to the naive field-weighted keyword scorer. - `null`: BM25 does not apply; the existing embedding/extension path runs. */
+type BuiltInBm25Mode = "explicit" | "auto-fallback";
+/** Select the built-in BM25 path from effective search settings. */
+declare function resolveBuiltInBm25Mode(params: {
+    configuredProvider: string | undefined;
+    hasEmbeddingProvider: boolean;
+    hasExtensionSearchProvider: boolean;
+}): BuiltInBm25Mode | null;
+/**
+ * Rank the filtered corpus with the offline BM25 provider (pm-75k9). Builds a
+ * BM25 index over each document's resolved search corpus (honoring
+ * `search.corpus_fields`), scores the query, and shapes hits for the requested
+ * mode: semantic mode returns pure BM25-ranked hits tagged
+ * `matched_fields: ["bm25"]`, while hybrid mode blends the BM25 scores with the
+ * locally computed keyword scores via {@link combineHybridHits}. The exact
+ * full-ID / short-ID guarantee is preserved in both modes via
+ * {@link forceExactIdHitsToTop}. No network, embedding service, or vector store
+ * is involved, so this path cannot fail on a backend error.
+ */
+declare function computeBuiltInBm25Hits(params: {
+    requestedMode: Exclude<SearchMode, "keyword">;
+    query: string;
+    filteredDocuments: ItemDocument[];
+    keywordHits: SearchHit[];
+    corpusFields: string[];
+    bm25Params: Bm25Params;
+    hybridSemanticWeight: number;
+}): SearchHit[];
+interface SemanticQueryContext {
+    requestedMode: Exclude<SearchMode, "keyword">;
+    query: string;
+    filteredDocuments: ItemDocument[];
+    keywordHits: SearchHit[];
+    hybridSemanticWeight: number;
+    limit: number | undefined;
+    maxResults: number;
+    provider: EmbeddingProviderConfig;
+    vectorStore: VectorStoreConfig | null;
+    extensionVectorAdapter: ExtensionVectorAdapter | null;
+    queryExpansion: QueryExpansionConfig;
+    queryExpansionExtension: {
+        providerName: string;
+        expand: ExtensionSearchProviderQueryExpansion;
+    } | null;
+    rerank: RerankConfig;
+    rerankExtension: {
+        providerName: string;
+        rerank: ExtensionSearchProviderRerank;
+    } | null;
+    warnings: string[];
+    settings: PmSettings;
+    embeddingTimeoutMs?: number;
+    vectorQueryTimeoutMs?: number;
+}
+interface SemanticQueryResult {
+    hits: SearchHit[];
+    vectorMatchCount: number;
+}
+/** Merge vector retrieval batches by item ID for query expansion. */
+declare function mergeVectorHitsById(vectorHitGroups: VectorQueryHit[][]): VectorQueryHit[];
+/** Build the candidate text corpus supplied to reranking providers. */
+declare function buildRerankCorpus(document: ItemDocument): string;
+/** Execute provider retrieval and ranking with the existing fallback and warning contracts. */
+declare function computeSemanticOrHybridHits(context: SemanticQueryContext): Promise<SemanticQueryResult>;
+/** Resolve the active provider implementation for configured query expansion. */
+declare function resolveQueryExpansionExtension(queryExpansion: QueryExpansionConfig): {
+    providerName: string;
+    expand: ExtensionSearchProviderQueryExpansion;
+} | null;
+/** Resolve the active provider implementation for configured reranking. */
+declare function resolveRerankExtension(settings: PmSettings): {
+    providerName: string;
+    rerank: ExtensionSearchProviderRerank;
+} | null;
+export { buildExplicitSemanticFallbackWarning, buildRerankCorpus, buildSemanticHits, BuiltInBm25Mode, combineHybridHits, computeBuiltInBm25Hits, computeSemanticOrHybridHits, ExtensionSearchProviderQueryExpansion, ExtensionSearchProviderRerank, maybeEmitVectorIndexStaleWarning, mergeVectorHitsById, normalizeExtensionProviderHits, requireSemanticDependencies, resolveBuiltInBm25Mode, resolveExtensionSearchProvider, resolveExtensionSearchProviderByName, resolveExtensionVectorAdapter, resolveQueryExpansionExtension, resolveRerankExtension, toOptionalNonEmptyString };

package/dist/sdk/query/search/semantic.js

@@ -0,0 +1,3 @@
+!(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]="0175d395-3f87-5a93-8d4f-a3150aaf16ae")}catch(e2){}})();import{getActiveExtensionRegistrations}from"../../../core/extensions/index.js";import{resolveRegisteredSearchProvider,resolveRegisteredVectorStoreAdapter}from"../../../core/extensions/runtime-registrations.js";import{buildBm25Index,flattenSearchCorpusText,scoreBm25Query,tokenizeBm25}from"../../../core/search/bm25.js";import{readVectorizationStatusLedger}from"../../../core/search/cache.js";import{buildSearchCorpus}from"../../../core/search/corpus.js";import{executeEmbeddingRequest}from"../../../core/search/providers.js";import{buildDeterministicQueryExpansions,mergeQueryExpansions,normalizeQueryExpansionOutput,normalizeRerankOutput,rerankCandidatesWithEmbeddings}from"../../../core/search/relevance.js";import{collectStaleVectorizationIds}from"../../../core/search/staleness.js";import{executeVectorQuery}from"../../../core/search/vector-stores.js";import{EXIT_CODE}from"../../../core/shared/constants.js";import{PmCliError}from"../../../core/shared/errors.js";import{toNonEmptyStringOrUndefined}from"../../../core/shared/primitives.js";import{normalizeScoreMap}from"./lexical.js";function collectErrorCauseCodes(error){const codes=[];let current=error;for(let depth=0;depth<5&&current&&typeof current==="object";depth+=1){const code=current.code;if(typeof code==="string"){codes.push(code.toLowerCase())}current=current.cause}return codes.join(" ")}function classifyImplicitSemanticFallbackReason(error){const message=(error instanceof Error?error.message:String(error)).toLowerCase();const causeCodes=collectErrorCauseCodes(error);const haystack=`${message} ${causeCodes}`;if(haystack.includes("timed out")||haystack.includes("timeout")||haystack.includes("etimedout")){return"timeout"}if(haystack.includes("econnrefused")||haystack.includes("connection refused")||haystack.includes("connect ")||haystack.includes("enotfound")||haystack.includes("eai_again")||haystack.includes("econnreset")||haystack.includes("fetch failed")){return"connection"}return"error"}function buildExplicitSemanticFallbackWarning(requestedMode,error){const reason=classifyImplicitSemanticFallbackReason(error);return`search_${requestedMode}_fallback:${reason}:using_keyword_mode`}function resolveVectorIndexRecovery(registrations){const hasReindex=registrations?.commands?.some(registration=>registration.command.trim()==="reindex")===true;return hasReindex?{command:"pm reindex --mode hybrid",args:["reindex","--mode","hybrid"]}:{command:"pm install search-advanced --project",args:["install","search-advanced","--project"],follow_up_command:"pm reindex --mode hybrid",follow_up_args:["reindex","--mode","hybrid"]}}async function maybeEmitVectorIndexStaleWarning(pmRoot,filteredDocuments,warnings){try{const ledger=await readVectorizationStatusLedger(pmRoot);if(ledger.warnings.length>0){warnings.push(...ledger.warnings)}const staleIds=collectStaleVectorizationIds(filteredDocuments.map(document=>({id:document.metadata.id,updated_at:document.metadata.updated_at})),ledger.entries);if(staleIds.length===0){return}const recovery=resolveVectorIndexRecovery(getActiveExtensionRegistrations());warnings.push(...formatVectorIndexRecoveryWarnings(staleIds.length,recovery));process.stderr.write(`[pm] warning: ${staleIds.length} item${staleIds.length===1?" is":"s are"} new or modified since the last reindex and ${staleIds.length===1?"is":"are"} NOT in the semantic index yet \u2014 run '${recovery.command}'${recovery.follow_up_command?`, then '${recovery.follow_up_command}'`:""}. (Write-time embedding is governed by search.mutation_refresh_policy; staleness means the embed was skipped, failed, or the backend was unreachable.)
+`)}catch{}}function formatVectorIndexRecoveryWarnings(staleCount,recovery){return[`vector_index_stale:${staleCount}`,`vector_index_recovery:${recovery.args.join(" ")}`,...recovery.follow_up_args?[`vector_index_recovery_follow_up:${recovery.follow_up_args.join(" ")}`]:[]]}function requireSemanticDependencies(requestedMode,providerResolution,vectorResolution,hasExtensionVectorQuery){if(!providerResolution.active){throw new PmCliError(`Search mode '${requestedMode}' requires a configured embedding provider in settings.providers.openai or settings.providers.ollama`,EXIT_CODE.USAGE)}if(!vectorResolution.active&&!hasExtensionVectorQuery){throw new PmCliError(`Search mode '${requestedMode}' requires a configured vector store in settings.vector_store.qdrant/settings.vector_store.lancedb or an extension adapter selected by settings.vector_store.adapter`,EXIT_CODE.USAGE)}return{provider:providerResolution.active,vectorStore:vectorResolution.active??null}}const toOptionalNonEmptyString=toNonEmptyStringOrUndefined;function resolveExtensionSearchProviderByName(providerName){const registrations=getActiveExtensionRegistrations();const resolved=resolveRegisteredSearchProvider(registrations,providerName);if(!resolved){return null}const runtimeDefinition=resolved.runtime_definition??resolved.definition;const query=runtimeDefinition.query;const queryExpansion=runtimeDefinition.queryExpansion??runtimeDefinition.query_expansion;const rerank=runtimeDefinition.rerank;const registeredName=toOptionalNonEmptyString(runtimeDefinition.name)??toOptionalNonEmptyString(resolved.definition.name)??providerName;if(!registeredName){return null}const hooks={providerName:registeredName,...typeof query==="function"?{query}:{},...typeof queryExpansion==="function"?{queryExpansion}:{},...typeof rerank==="function"?{rerank}:{}};if(!hooks.query&&!hooks.queryExpansion&&!hooks.rerank){return null}return hooks}function resolveExtensionSearchProvider(settings){const providerName=toOptionalNonEmptyString(settings.search?.provider);const resolved=resolveExtensionSearchProviderByName(providerName);if(!resolved?.query){return null}return{providerName:resolved.providerName,query:resolved.query}}function resolveExtensionVectorAdapter(settings){const registrations=getActiveExtensionRegistrations();const adapterName=toOptionalNonEmptyString(settings.vector_store?.adapter);const resolved=resolveRegisteredVectorStoreAdapter(registrations,adapterName);if(!resolved){return null}const runtimeDefinition=resolved.runtime_definition??resolved.definition;const query=runtimeDefinition.query;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,...typeof upsert==="function"?{upsert}:{}}}function normalizeExtensionProviderHits(providerName,raw,filteredById){const rawHits=Array.isArray(raw)?raw:raw?.hits;if(!Array.isArray(rawHits)){throw new PmCliError(`Extension search provider "${providerName}" must return an array of hits or { hits: [...] }`,EXIT_CODE.GENERIC_FAILURE)}const seen=new Set;const hits=[];for(const rawHit of rawHits){if(typeof rawHit!=="object"||rawHit===null){continue}const id=toOptionalNonEmptyString(rawHit.id);const score=rawHit.score;if(!id||typeof score!=="number"||!Number.isFinite(score)||seen.has(id)){continue}const document=filteredById.get(id);if(!document){continue}const matchedFieldsRaw=rawHit.matched_fields;const matchedFields=Array.isArray(matchedFieldsRaw)&&matchedFieldsRaw.every(entry=>typeof entry==="string")?[...new Set(matchedFieldsRaw.map(entry=>entry.trim()).filter(entry=>entry.length>0))].sort((a,b)=>a.localeCompare(b)):[`provider:${providerName}`];seen.add(id);hits.push({item:document.metadata,score,matched_fields:matchedFields})}return hits}function buildSemanticHits(vectorHits,filteredById){const semanticHits=[];const semanticScores=new Map;for(const vectorHit of vectorHits){if(semanticScores.has(vectorHit.id)){continue}const document=filteredById.get(vectorHit.id);if(!document){continue}semanticScores.set(vectorHit.id,vectorHit.score);semanticHits.push({item:document.metadata,score:vectorHit.score,matched_fields:["semantic"]})}return{semanticHits,semanticScores}}function forceExactIdHitsToTop(rankedHits,keywordHits){const exactIdHits=keywordHits.filter(hit=>hit.exact_id_match===true);if(exactIdHits.length===0){return rankedHits}const exactIdIds=new Set(exactIdHits.map(hit=>hit.item.id));const remaining=rankedHits.filter(hit=>!exactIdIds.has(hit.item.id));const maxRemainingScore=remaining.reduce((max,hit)=>Math.max(max,hit.score),0);const orderedExactHits=exactIdHits.sort((left,right)=>right.score-left.score);const bandBase=maxRemainingScore+orderedExactHits.length+1;const promoted=orderedExactHits.map((hit,index)=>({...hit,score:bandBase-index,matched_fields:["id"]}));return[...promoted,...remaining]}function combineHybridHits(filteredById,semanticScores,keywordHits,hybridSemanticWeight,semanticFieldLabel="semantic"){const keywordScores=new Map(keywordHits.map(entry=>[entry.item.id,entry.score]));const keywordMatches=new Map(keywordHits.map(entry=>[entry.item.id,entry.matched_fields]));const normalizedSemantic=normalizeScoreMap(semanticScores);const normalizedKeyword=normalizeScoreMap(keywordScores);const candidateIds=new Set([...semanticScores.keys(),...keywordScores.keys()]);const keywordWeight=1-hybridSemanticWeight;return[...candidateIds].map(id=>{const document=filteredById.get(id);const semanticScore=normalizedSemantic.get(id)??0;const keywordScore=normalizedKeyword.get(id)??0;const combinedScore=semanticScore*hybridSemanticWeight+keywordScore*keywordWeight;if(combinedScore<=0){return null}const matchedFields=new Set;if(semanticScores.has(id)){matchedFields.add(semanticFieldLabel)}for(const field of keywordMatches.get(id)??[]){matchedFields.add(field)}return{item:document.metadata,score:combinedScore,matched_fields:[...matchedFields].sort((a,b)=>a.localeCompare(b))}}).filter(entry=>entry!==null)}function resolveBuiltInBm25Mode(params){const normalized=params.configuredProvider?.trim().toLowerCase();if(normalized==="bm25"){return"explicit"}if(normalized==="auto"&&!params.hasEmbeddingProvider&&!params.hasExtensionSearchProvider){return"auto-fallback"}return null}function computeBuiltInBm25Hits(params){const bm25Documents=params.filteredDocuments.map(document=>({id:document.metadata.id,text:flattenSearchCorpusText(buildSearchCorpus(document,{fields:params.corpusFields}))}));const index=buildBm25Index(bm25Documents);const bm25Scores=scoreBm25Query(index,tokenizeBm25(params.query),params.bm25Params);const filteredById=new Map(params.filteredDocuments.map(document=>[document.metadata.id,document]));if(params.requestedMode==="semantic"){const semanticHits=[...bm25Scores].map(([id,score])=>({item:filteredById.get(id).metadata,score,matched_fields:["bm25"]}));return forceExactIdHitsToTop(semanticHits,params.keywordHits)}const hybridHits=combineHybridHits(filteredById,bm25Scores,params.keywordHits,params.hybridSemanticWeight,"bm25");return forceExactIdHitsToTop(hybridHits,params.keywordHits)}function mergeVectorHitsById(vectorHitGroups){const bestById=new Map;for(const group of vectorHitGroups){for(const hit of group){const existing=bestById.get(hit.id);if(!existing||hit.score>existing.score){bestById.set(hit.id,hit)}}}const merged=[...bestById.values()];merged.sort((left,right)=>{if(left.score!==right.score){return right.score-left.score}return left.id.localeCompare(right.id)});return merged}function buildRerankCorpus(document){const metadata=document.metadata;const tags=Array.isArray(metadata?.tags)?metadata.tags.join(" "):"";return[metadata?.title,metadata?.description,metadata?.type,metadata?.status,tags,document.body].map(entry=>typeof entry==="string"?entry.trim():"").filter(entry=>entry.length>0).join("\n")}async function resolveExpandedSemanticQueries(context,queryTrimmed){const baseExpandedQueries=context.queryExpansion.enabled?buildDeterministicQueryExpansions(queryTrimmed,context.queryExpansion.max_queries):[queryTrimmed];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}}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)}context.warnings.push(`search_vector_adapter_failed:${context.extensionVectorAdapter.adapterName}:using_builtin`);return await executeVectorQuery(context.vectorStore,semanticVector,semanticLimit,vectorQueryOptions)}}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=Math.max(context.limit??context.maxResults,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);const vectorMatchCount=semanticScores.size;if(context.requestedMode==="semantic"){return{hits:forceExactIdHitsToTop(semanticHits,context.keywordHits),vectorMatchCount}}const hybridHits=await applyHybridRerank(context,queryTrimmed,combineHybridHits(filteredById,semanticScores,context.keywordHits,context.hybridSemanticWeight),filteredById);return{hits:forceExactIdHitsToTop(hybridHits,context.keywordHits),vectorMatchCount}}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}export{buildExplicitSemanticFallbackWarning,buildRerankCorpus,buildSemanticHits,classifyImplicitSemanticFallbackReason,collectErrorCauseCodes,combineHybridHits,computeBuiltInBm25Hits,computeSemanticOrHybridHits,formatVectorIndexRecoveryWarnings,maybeEmitVectorIndexStaleWarning,mergeVectorHitsById,normalizeExtensionProviderHits,requireSemanticDependencies,resolveBuiltInBm25Mode,resolveExtensionSearchProvider,resolveExtensionSearchProviderByName,resolveExtensionVectorAdapter,resolveQueryExpansionExtension,resolveRerankExtension,resolveVectorIndexRecovery,toOptionalNonEmptyString};
+//# sourceMappingURL=semantic.js.map