@unbrained/pm-cli 2026.3.12 → 2026.5.1

package/dist/cli/commands/search.js

@@ -1,25 +1,65 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { runActiveOnReadHooks } from "../../core/extensions/index.js";
+import { getActiveExtensionRegistrations, runActiveOnReadHooks } from "../../core/extensions/index.js";
+import { resolveRegisteredSearchProvider, resolveRegisteredVectorStoreAdapter, } from "../../core/extensions/runtime-registrations.js";
+import { resolveItemTypeRegistry, resolveTypeName } from "../../core/item/type-registry.js";
 import { executeEmbeddingRequest, resolveEmbeddingProviders, } from "../../core/search/providers.js";
+import { resolveSettingsWithSemanticRuntimeDefaults } from "../../core/search/semantic-defaults.js";
 import { executeVectorQuery, resolveVectorStores, } from "../../core/search/vector-stores.js";
 import { pathExists } from "../../core/fs/fs-utils.js";
 import { parseItemDocument } from "../../core/item/item-format.js";
-import { EXIT_CODE, TYPE_TO_FOLDER } from "../../core/shared/constants.js";
+import { normalizeStatusInput } from "../../core/item/status.js";
+import { collectRuntimeFilterValues, matchesRuntimeFilters } from "../../core/schema/runtime-field-filters.js";
+import { resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, } from "../../core/schema/runtime-schema.js";
+import { EXIT_CODE } from "../../core/shared/constants.js";
 import { PmCliError } from "../../core/shared/errors.js";
+import { tokenizeAlphaNumeric } from "../../core/shared/text-normalization.js";
 import { compareTimestampStrings, nowIso, resolveIsoOrRelative } from "../../core/shared/time.js";
 import { listAllFrontMatter } from "../../core/store/item-store.js";
-import { getSettingsPath, resolveGlobalPmRoot, resolvePmRoot } from "../../core/store/paths.js";
+import { getSettingsPath, resolveGlobalPmRoot, resolvePmRoot, getItemPath } from "../../core/store/paths.js";
 import { readSettings } from "../../core/store/settings.js";
-const ITEM_TYPES_BY_LOWER = new Map([
-    ["epic", "Epic"],
-    ["feature", "Feature"],
-    ["task", "Task"],
-    ["chore", "Chore"],
-    ["issue", "Issue"],
-]);
-function isTerminal(status) {
-    return status === "closed" || status === "canceled";
+const DEFAULT_COMPACT_SEARCH_FIELDS = [
+    "id",
+    "title",
+    "status",
+    "type",
+    "priority",
+    "updated_at",
+    "score",
+    "matched_fields",
+];
+const LONG_QUERY_TOKEN_THRESHOLD = 4;
+const LONG_QUERY_TITLE_EXACT_BONUS = 120;
+const LONG_QUERY_PHRASE_MULTIPLIER = 6;
+const IMPLICIT_AUTO_HYBRID_EMBEDDING_TIMEOUT_MS = 8_000;
+const IMPLICIT_AUTO_HYBRID_VECTOR_TIMEOUT_MS = 8_000;
+function isTerminal(status, statusRegistry) {
+    const normalized = normalizeStatusInput(status, statusRegistry) ?? status;
+    return statusRegistry.terminal_statuses.has(normalized);
+}
+function classifyImplicitSemanticFallbackReason(error) {
+    const message = (error instanceof Error ? error.message : String(error)).toLowerCase();
+    if (message.includes("timed out") || message.includes("timeout")) {
+        return "timeout";
+    }
+    if (message.includes("econnrefused") ||
+        message.includes("connection refused") ||
+        message.includes("connect ") ||
+        message.includes("enotfound") ||
+        message.includes("eai_again")) {
+        return "connection";
+    }
+    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 parseMode(raw, context) {
     if (raw === undefined) {
@@ -34,6 +74,18 @@ function parseMode(raw, context) {
 function parseIncludeLinked(raw) {
     return raw === true;
 }
+function parseTitleExact(raw) {
+    return raw === true;
+}
+function parsePhraseExact(raw) {
+    return raw === true;
+}
+function normalizeSearchPhrase(value) {
+    return value
+        .toLowerCase()
+        .replace(/\s+/g, " ")
+        .trim();
+}
 function parsePriority(raw) {
     if (raw === undefined)
         return undefined;
@@ -43,19 +95,19 @@ function parsePriority(raw) {
     }
     return parsed;
 }
-function parseType(raw) {
+function parseType(raw, typeRegistry) {
     if (raw === undefined)
         return undefined;
-    const parsed = ITEM_TYPES_BY_LOWER.get(raw.trim().toLowerCase());
+    const parsed = resolveTypeName(raw, typeRegistry);
     if (!parsed) {
-        throw new PmCliError("Type filter must be one of Epic|Feature|Task|Chore|Issue", EXIT_CODE.USAGE);
+        throw new PmCliError(`Type filter must be one of ${typeRegistry.types.join("|")}`, EXIT_CODE.USAGE);
     }
     return parsed;
 }
-function parseDeadline(raw) {
+function parseDeadline(raw, fieldLabel) {
     if (raw === undefined)
         return undefined;
-    return resolveIsoOrRelative(raw);
+    return resolveIsoOrRelative(raw, new Date(), fieldLabel);
 }
 function parseLimit(raw) {
     if (raw === undefined)
@@ -66,19 +118,94 @@ function parseLimit(raw) {
     }
     return Math.floor(parsed);
 }
+function parseFieldSelectors(raw) {
+    if (raw === undefined) {
+        return undefined;
+    }
+    const selectors = raw
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+    if (selectors.length === 0) {
+        throw new PmCliError("Search --fields requires a comma-separated list of field names", EXIT_CODE.USAGE);
+    }
+    return [...new Set(selectors)];
+}
+function parseProjectionConfig(options) {
+    const compactRequested = options.compact === true;
+    const fullRequested = options.full === true;
+    const fieldSelectors = parseFieldSelectors(options.fields);
+    const enabledModes = Number(compactRequested) + Number(fullRequested) + Number(fieldSelectors !== undefined);
+    if (enabledModes > 1) {
+        throw new PmCliError("Search projection options are mutually exclusive. Use one of --compact, --full, or --fields.", EXIT_CODE.USAGE);
+    }
+    if (compactRequested) {
+        return {
+            mode: "compact",
+            fields: [...DEFAULT_COMPACT_SEARCH_FIELDS],
+        };
+    }
+    if (fullRequested) {
+        return {
+            mode: "full",
+            fields: [],
+        };
+    }
+    if (fieldSelectors) {
+        return {
+            mode: "fields",
+            fields: fieldSelectors,
+        };
+    }
+    return {
+        mode: "full",
+        fields: [],
+    };
+}
 function parseTokens(query) {
-    const normalized = query.trim().toLowerCase();
+    const normalized = normalizeSearchPhrase(query);
     if (!normalized) {
         throw new PmCliError("Search query must not be empty", EXIT_CODE.USAGE);
     }
     return normalized.split(/\s+/).filter(Boolean);
 }
-function applyFilters(items, options) {
-    const typeFilter = parseType(options.type);
+function collectExactPhraseFields(document) {
+    const item = document.front_matter;
+    return [
+        item.title,
+        item.description,
+        item.status,
+        item.tags.join(" "),
+        document.body,
+        (item.comments ?? []).map((entry) => entry.text).join(" "),
+        (item.notes ?? []).map((entry) => entry.text).join(" "),
+        (item.learnings ?? []).map((entry) => entry.text).join(" "),
+        (item.dependencies ?? []).map((entry) => `${entry.id} ${entry.kind}`).join(" "),
+    ];
+}
+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.front_matter.title) !== normalizedQuery) {
+            return false;
+        }
+        if (options.phraseExact && !documentContainsExactPhrase(document, normalizedQuery)) {
+            return false;
+        }
+        return true;
+    });
+}
+function applyFilters(items, options, typeRegistry, runtimeFieldFilters) {
+    const typeFilter = parseType(options.type, typeRegistry);
     const tagFilter = options.tag?.trim().toLowerCase();
     const priorityFilter = parsePriority(options.priority);
-    const deadlineBefore = parseDeadline(options.deadlineBefore);
-    const deadlineAfter = parseDeadline(options.deadlineAfter);
+    const deadlineBefore = parseDeadline(options.deadlineBefore, "deadline-before");
+    const deadlineAfter = parseDeadline(options.deadlineAfter, "deadline-after");
     return items.filter((document) => {
         const item = document.front_matter;
         if (typeFilter && item.type !== typeFilter)
@@ -91,6 +218,8 @@ function applyFilters(items, options) {
             return false;
         if (deadlineAfter && (!item.deadline || compareTimestampStrings(item.deadline, deadlineAfter) < 0))
             return false;
+        if (!matchesRuntimeFilters(item, runtimeFieldFilters))
+            return false;
         return true;
     });
 }
@@ -107,10 +236,7 @@ function countOccurrences(haystack, needle) {
     }
 }
 function tokenizeForExactTokenMatch(value) {
-    return value
-        .toLowerCase()
-        .split(/[^a-z0-9]+/)
-        .filter((token) => token.length > 0);
+    return tokenizeAlphaNumeric(value);
 }
 function collectLinkedPaths(item) {
     const fromFiles = (item.files ?? []).map((entry) => ({
@@ -193,7 +319,7 @@ async function loadLinkedCorpus(document, projectRoot, globalRoot) {
     }
     return chunks.join("\n");
 }
-function scoreDocument(document, tokens, linkedCorpus, tuning) {
+function scoreDocument(document, tokens, normalizedQuery, linkedCorpus, tuning) {
     const item = document.front_matter;
     const titleTokenCounts = new Map();
     for (const token of tokenizeForExactTokenMatch(item.title)) {
@@ -232,6 +358,22 @@ function scoreDocument(document, tokens, linkedCorpus, tuning) {
             }
         }
     }
+    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);
+            }
+        }
+    }
     if (score <= 0) {
         return null;
     }
@@ -241,13 +383,13 @@ function scoreDocument(document, tokens, linkedCorpus, tuning) {
         matched_fields: [...matched].sort((a, b) => a.localeCompare(b)),
     };
 }
-function sortHits(items) {
+function sortHits(items, statusRegistry) {
     return [...items].sort((a, b) => {
         const byScore = b.score - a.score;
         if (byScore !== 0)
             return byScore;
-        const aTerminal = isTerminal(a.item.status);
-        const bTerminal = isTerminal(b.item.status);
+        const aTerminal = isTerminal(a.item.status, statusRegistry);
+        const bTerminal = isTerminal(b.item.status, statusRegistry);
         if (aTerminal !== bTerminal) {
             return aTerminal ? 1 : -1;
         }
@@ -260,8 +402,8 @@ function sortHits(items) {
         return a.item.id.localeCompare(b.item.id);
     });
 }
-function buildHybridLexicalScore(document, tokens, includeLinked, linkedCorpusById, tuning) {
-    return scoreDocument(document, tokens, includeLinked ? linkedCorpusById.get(document.front_matter.id) ?? "" : "", tuning);
+function buildHybridLexicalScore(document, tokens, normalizedQuery, includeLinked, linkedCorpusById, tuning) {
+    return scoreDocument(document, tokens, normalizedQuery, includeLinked ? linkedCorpusById.get(document.front_matter.id) ?? "" : "", tuning);
 }
 function normalizeScoreMap(scoreById) {
     if (scoreById.size === 0) {
@@ -337,7 +479,8 @@ export function resolveSearchTuning(settings) {
         linked_content_weight: resolveWeight(tuning.linked_content_weight, defaults.linked_content_weight),
     };
 }
-function emptySearchResult(query, mode, options, includeLinked, scoreThreshold, hybridSemanticWeight) {
+function emptySearchResult(query, mode, options, includeLinked, scoreThreshold, hybridSemanticWeight, projection, warnings) {
+    const projectionFields = projection.mode === "full" ? null : [...projection.fields];
     return {
         query: query.trim(),
         mode,
@@ -351,25 +494,115 @@ function emptySearchResult(query, mode, options, includeLinked, scoreThreshold,
             deadline_before: options.deadlineBefore ?? null,
             deadline_after: options.deadlineAfter ?? null,
             include_linked: includeLinked,
+            title_exact: options.titleExact === true,
+            phrase_exact: options.phraseExact === true,
             score_threshold: scoreThreshold,
             hybrid_semantic_weight: mode === "hybrid" ? hybridSemanticWeight : null,
             limit: options.limit ?? null,
+            projection: projection.mode,
+            fields: projectionFields,
+        },
+        projection: {
+            mode: projection.mode,
+            fields: projectionFields,
         },
         now: nowIso(),
+        ...(warnings.length > 0 ? { warnings } : {}),
     };
 }
-function requireSemanticDependencies(requestedMode, providerResolution, vectorResolution) {
+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) {
-        throw new PmCliError(`Search mode '${requestedMode}' requires a configured vector store in settings.vector_store.qdrant or settings.vector_store.lancedb`, 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,
+        vectorStore: vectorResolution.active ?? null,
     };
 }
+function toOptionalNonEmptyString(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const normalized = value.trim();
+    return normalized.length > 0 ? normalized : undefined;
+}
+function resolveExtensionSearchProvider(settings) {
+    const registrations = getActiveExtensionRegistrations();
+    const providerName = toOptionalNonEmptyString(settings.search?.provider);
+    const resolved = resolveRegisteredSearchProvider(registrations, providerName);
+    if (!resolved) {
+        return null;
+    }
+    const runtimeDefinition = resolved.runtime_definition ?? resolved.definition;
+    const query = runtimeDefinition.query;
+    if (typeof query !== "function") {
+        return null;
+    }
+    const registeredName = toOptionalNonEmptyString(runtimeDefinition.name) ??
+        toOptionalNonEmptyString(resolved.definition.name) ??
+        providerName;
+    if (!registeredName) {
+        return null;
+    }
+    return {
+        providerName: registeredName,
+        query: 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;
+    }
+    return {
+        query: query,
+    };
+}
+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.front_matter,
+            score,
+            matched_fields: matchedFields,
+        });
+    }
+    return hits;
+}
 function buildSemanticHits(vectorHits, filteredById) {
     const semanticHits = [];
     const semanticScores = new Map();
@@ -426,9 +659,32 @@ function combineHybridHits(filteredById, semanticScores, keywordHits, hybridSema
 }
 async function computeSemanticOrHybridHits(context) {
     const semanticLimit = context.limit ?? context.maxResults;
-    const queryVectors = await executeEmbeddingRequest(context.provider, context.query.trim());
+    const embeddingOptions = context.embeddingTimeoutMs !== undefined ? { timeout_ms: context.embeddingTimeoutMs } : {};
+    const vectorQueryOptions = context.vectorQueryTimeoutMs !== undefined ? { timeout_ms: context.vectorQueryTimeoutMs } : {};
+    const queryVectors = await executeEmbeddingRequest(context.provider, context.query.trim(), embeddingOptions);
     const semanticVector = queryVectors[0];
-    const vectorHits = await executeVectorQuery(context.vectorStore, semanticVector, semanticLimit);
+    let vectorHits;
+    if (context.extensionVectorAdapter?.query) {
+        try {
+            vectorHits = 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);
+            }
+            vectorHits = await executeVectorQuery(context.vectorStore, semanticVector, semanticLimit, vectorQueryOptions);
+        }
+    }
+    else if (context.vectorStore) {
+        vectorHits = await executeVectorQuery(context.vectorStore, semanticVector, semanticLimit, vectorQueryOptions);
+    }
+    else {
+        throw new PmCliError("Semantic search requires either a configured vector store or an extension vector adapter query handler", EXIT_CODE.USAGE);
+    }
     const filteredById = new Map(context.filteredDocuments.map((document) => [document.front_matter.id, document]));
     const { semanticHits, semanticScores } = buildSemanticHits(vectorHits, filteredById);
     if (context.requestedMode === "semantic") {
@@ -436,96 +692,234 @@ async function computeSemanticOrHybridHits(context) {
     }
     return combineHybridHits(filteredById, semanticScores, context.keywordHits, context.hybridSemanticWeight);
 }
-async function loadDocuments(pmRoot) {
-    const items = await listAllFrontMatter(pmRoot);
+function alternateFormat(itemFormat) {
+    return itemFormat === "toon" ? "json_markdown" : "toon";
+}
+async function loadDocuments(pmRoot, itemFormat, typeToFolder, schema) {
+    const listWarnings = [];
+    const items = await listAllFrontMatter(pmRoot, itemFormat, typeToFolder, listWarnings, schema);
+    const warnings = [...new Set(listWarnings)].sort((left, right) => left.localeCompare(right));
     const documents = [];
     for (const item of items) {
-        const itemPath = path.join(pmRoot, TYPE_TO_FOLDER[item.type], `${item.id}.md`);
-        const raw = await fs.readFile(itemPath, "utf8");
+        const preferredPath = getItemPath(pmRoot, item.type, item.id, itemFormat, typeToFolder);
+        try {
+            const raw = await fs.readFile(preferredPath, "utf8");
+            await runActiveOnReadHooks({
+                path: preferredPath,
+                scope: "project",
+            });
+            documents.push(parseItemDocument(raw, { format: itemFormat, schema, onWarning: (warning) => listWarnings.push(warning) }));
+            continue;
+        }
+        catch {
+            // Fallback to the alternate format when preferred format path is absent.
+        }
+        const fallbackFormat = alternateFormat(itemFormat);
+        const fallbackPath = getItemPath(pmRoot, item.type, item.id, fallbackFormat, typeToFolder);
+        const raw = await fs.readFile(fallbackPath, "utf8");
         await runActiveOnReadHooks({
-            path: itemPath,
+            path: fallbackPath,
             scope: "project",
         });
-        const parsed = parseItemDocument(raw);
-        documents.push(parsed);
+        documents.push(parseItemDocument(raw, { format: fallbackFormat, schema, onWarning: (warning) => listWarnings.push(warning) }));
+    }
+    return {
+        documents,
+        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 itemRecord = hit.item;
+        return itemRecord[itemKey] ?? null;
+    }
+    const hitRecord = hit;
+    const itemRecord = hit.item;
+    if (Object.prototype.hasOwnProperty.call(itemRecord, normalized)) {
+        return itemRecord[normalized] ?? null;
     }
-    return documents;
+    if (Object.prototype.hasOwnProperty.call(hitRecord, normalized)) {
+        return hitRecord[normalized] ?? null;
+    }
+    return null;
+}
+function projectSearchHits(hits, projection) {
+    if (projection.mode === "full") {
+        return hits;
+    }
+    return hits.map((hit) => {
+        const projected = {};
+        for (const field of projection.fields) {
+            projected[field] = readSearchFieldValue(hit, field);
+        }
+        return projected;
+    });
 }
 export async function runSearch(query, options, global) {
     const includeLinked = parseIncludeLinked(options.includeLinked);
+    const titleExact = parseTitleExact(options.titleExact);
+    const phraseExact = parsePhraseExact(options.phraseExact);
     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;
     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 settings = await readSettings(pmRoot);
+    const storedSettings = await readSettings(pmRoot);
+    const runtimeDefaultsResolution = resolveSettingsWithSemanticRuntimeDefaults(storedSettings);
+    const settings = runtimeDefaultsResolution.settings;
+    const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);
+    const runtimeFieldRegistry = resolveRuntimeFieldRegistry(settings.schema);
+    const runtimeFieldFilters = collectRuntimeFilterValues(options, runtimeFieldRegistry, "search");
+    const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
     const maxResults = resolveSearchMaxResults(settings);
     const scoreThreshold = resolveSearchScoreThreshold(settings);
     const hybridSemanticWeight = resolveHybridSemanticWeight(settings);
     const tuning = resolveSearchTuning(settings);
     const providerResolution = resolveEmbeddingProviders(settings);
     const vectorResolution = resolveVectorStores(settings);
-    const requestedMode = parseMode(options.mode, {
-        hasProvider: providerResolution.active !== null,
-        hasVectorStore: vectorResolution.active !== null,
+    const extensionSearchProvider = resolveExtensionSearchProvider(settings);
+    const extensionVectorAdapter = resolveExtensionVectorAdapter(settings);
+    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 ?? "json_markdown", typeRegistry.type_to_folder, settings.schema);
+    const warnings = loadedDocuments.warnings;
+    const allDocuments = loadedDocuments.documents;
+    const metadataFilteredDocuments = applyFilters(allDocuments, options, typeRegistry, runtimeFieldFilters);
+    const filteredDocuments = applyExactQueryFilters(metadataFilteredDocuments, normalizedQuery, {
+        titleExact,
+        phraseExact,
     });
-    const allDocuments = await loadDocuments(pmRoot);
-    const filteredDocuments = applyFilters(allDocuments, options);
-    if (requestedMode === "keyword" && (filteredDocuments.length === 0 || limit === 0)) {
-        return emptySearchResult(query, requestedMode, options, includeLinked, scoreThreshold, hybridSemanticWeight);
+    if (effectiveMode === "keyword" && (filteredDocuments.length === 0 || limit === 0)) {
+        return emptySearchResult(query, effectiveMode, options, includeLinked, scoreThreshold, hybridSemanticWeight, projection, warnings);
     }
     const projectRoot = process.cwd();
     const globalRoot = resolveGlobalPmRoot(projectRoot);
     const linkedCorpusById = new Map();
-    if (includeLinked && (requestedMode === "keyword" || requestedMode === "hybrid")) {
+    if (includeLinked && (effectiveMode === "keyword" || effectiveMode === "hybrid")) {
         for (const document of filteredDocuments) {
             linkedCorpusById.set(document.front_matter.id, await loadLinkedCorpus(document, projectRoot, globalRoot));
         }
     }
     const keywordHits = filteredDocuments
-        .map((document) => buildHybridLexicalScore(document, tokens, requestedMode !== "semantic", linkedCorpusById, tuning))
+        .map((document) => buildHybridLexicalScore(document, tokens, normalizedQuery, effectiveMode !== "semantic", linkedCorpusById, tuning))
         .filter((entry) => entry !== null);
     let hits = keywordHits;
-    if (requestedMode !== "keyword") {
-        const { provider, vectorStore } = requireSemanticDependencies(requestedMode, providerResolution, vectorResolution);
-        if (filteredDocuments.length === 0 || limit === 0) {
-            return emptySearchResult(query, requestedMode, options, includeLinked, scoreThreshold, hybridSemanticWeight);
-        }
-        hits = await computeSemanticOrHybridHits({
-            requestedMode,
-            query,
-            filteredDocuments,
-            keywordHits,
-            hybridSemanticWeight,
-            limit,
-            maxResults,
-            provider,
-            vectorStore,
-        });
+    if (effectiveMode !== "keyword") {
+        try {
+            if (!extensionSearchProvider) {
+                requireSemanticDependencies(effectiveMode, providerResolution, vectorResolution, extensionVectorAdapter !== null);
+            }
+            if (filteredDocuments.length === 0 || limit === 0) {
+                return emptySearchResult(query, effectiveMode, options, includeLinked, scoreThreshold, hybridSemanticWeight, projection, warnings);
+            }
+            const filteredById = new Map(filteredDocuments.map((document) => [document.front_matter.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 implicitAutoHybridMode = runtimeDefaultsResolution.auto_ollama_defaults_applied && !modeWasExplicit && effectiveMode === "hybrid";
+                const { provider, vectorStore } = requireSemanticDependencies(effectiveMode, providerResolution, vectorResolution, extensionVectorAdapter !== null);
+                hits = await computeSemanticOrHybridHits({
+                    requestedMode: effectiveMode,
+                    query,
+                    filteredDocuments,
+                    keywordHits,
+                    hybridSemanticWeight,
+                    limit,
+                    maxResults,
+                    provider,
+                    vectorStore,
+                    extensionVectorAdapter,
+                    settings,
+                    ...(implicitAutoHybridMode
+                        ? {
+                            embeddingTimeoutMs: IMPLICIT_AUTO_HYBRID_EMBEDDING_TIMEOUT_MS,
+                            vectorQueryTimeoutMs: IMPLICIT_AUTO_HYBRID_VECTOR_TIMEOUT_MS,
+                        }
+                        : {}),
+                });
+            }
+        }
+        catch (error) {
+            const canFallbackToKeyword = runtimeDefaultsResolution.auto_ollama_defaults_applied && !modeWasExplicit && effectiveMode === "hybrid";
+            if (!canFallbackToKeyword) {
+                throw error;
+            }
+            effectiveMode = "keyword";
+            hits = keywordHits;
+            warnings.push(buildImplicitSemanticFallbackWarning(error));
+        }
     }
     const thresholded = hits.filter((entry) => entry.score >= scoreThreshold);
-    const sorted = sortHits(thresholded);
-    const effectiveLimit = requestedMode === "keyword" ? limit : (limit ?? maxResults);
-    const limited = effectiveLimit === undefined ? sorted : sorted.slice(0, effectiveLimit);
+    const sorted = sortHits(thresholded, statusRegistry);
+    const resolvedLimit = effectiveMode === "keyword" ? limit : (limit ?? maxResults);
+    const limited = resolvedLimit === undefined ? sorted : sorted.slice(0, resolvedLimit);
+    const projectedItems = projectSearchHits(limited, projection);
+    const projectionFields = projection.mode === "full" ? null : [...projection.fields];
     return {
         query: query.trim(),
-        mode: requestedMode,
-        items: limited,
-        count: limited.length,
+        mode: effectiveMode,
+        items: projectedItems,
+        count: projectedItems.length,
         filters: {
-            mode: requestedMode,
+            mode: effectiveMode,
             type: options.type ?? null,
             tag: options.tag ?? null,
             priority: options.priority ?? null,
             deadline_before: options.deadlineBefore ?? null,
             deadline_after: options.deadlineAfter ?? null,
             include_linked: includeLinked,
+            title_exact: titleExact,
+            phrase_exact: phraseExact,
             score_threshold: scoreThreshold,
-            hybrid_semantic_weight: requestedMode === "hybrid" ? hybridSemanticWeight : null,
+            hybrid_semantic_weight: effectiveMode === "hybrid" ? hybridSemanticWeight : null,
             limit: options.limit ?? null,
+            runtime_filters: runtimeFieldFilters,
+            projection: projection.mode,
+            fields: projectionFields,
+        },
+        projection: {
+            mode: projection.mode,
+            fields: projectionFields,
         },
         now: nowIso(),
+        ...(warnings.length > 0 ? { warnings } : {}),
     };
 }
 //# sourceMappingURL=search.js.map