@unbrained/pm-cli 2026.7.16 → 2026.7.17

package/dist/sdk/query/search.js

@@ -0,0 +1,2247 @@
+/**
+ * @module sdk/query/search
+ *
+ * Implements the pm search command surface and its agent-facing runtime behavior.
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="7d6721eb-1e28-58ea-a5fc-4494f249275c")}catch(e){}}();
+import fs from "node:fs/promises";
+import path from "node:path";
+import { coerceNumberInRange, toNonEmptyStringOrUndefined, } from "../../core/shared/primitives.js";
+import { isPathWithinDirectory } from "../../core/fs/path-utils.js";
+import { getActiveExtensionRegistrations, runActiveOnReadHooks, } from "../../core/extensions/index.js";
+import { collectRegisteredItemFieldNames } from "../../core/extensions/item-fields.js";
+import { resolveRegisteredSearchProvider, resolveRegisteredVectorStoreAdapter, } from "../../core/extensions/runtime-registrations.js";
+import { resolveItemTypeRegistry, } from "../../core/item/type-registry.js";
+import { parseLimit, parsePriority, parseType } from "./parsers.js";
+import { executeEmbeddingRequest, resolveEmbeddingProviders, } from "../../core/search/providers.js";
+import { buildDeterministicQueryExpansions, mergeQueryExpansions, normalizeQueryExpansionOutput, normalizeRerankOutput, rerankCandidatesWithEmbeddings, resolveQueryExpansionConfig, resolveRerankConfig, } from "../../core/search/relevance.js";
+import { resolveSettingsWithSemanticRuntimeDefaults } from "../../core/search/semantic-defaults.js";
+import { executeVectorQuery, resolveVectorStores, } from "../../core/search/vector-stores.js";
+import { readVectorizationStatusLedger } from "../../core/search/cache.js";
+import { buildEventCorpus, buildPlanFlatCorpus, buildReminderCorpus, buildSearchCorpus, resolveSearchCorpusFields, } from "../../core/search/corpus.js";
+import { buildBm25Index, flattenSearchCorpusText, resolveBm25Params, scoreBm25Query, tokenizeBm25, } from "../../core/search/bm25.js";
+import { collectStaleVectorizationIds } from "../../core/search/staleness.js";
+import { pathExists } from "../../core/fs/fs-utils.js";
+import { parseItemDocument } from "../../core/item/item-format.js";
+import { toItemRecord } from "../../core/item/item-record.js";
+import { isTerminalStatus } from "../../core/item/status.js";
+import { parseStatusFilterCsv } from "../../core/item/status-filter.js";
+import { collectRuntimeFilterValues, matchesRuntimeFilters, } from "../../core/schema/runtime-field-filters.js";
+import { hasMissingMetadataFilter, itemMatchesMissingMetadata, lifecycleClassifierFromStatusRegistry, } from "../../core/governance/metadata-coverage.js";
+import { hasContentFieldFilter, itemMatchesContentFilters, } from "../../core/governance/content-fields.js";
+import { resolveContentFieldFilters, resolveMissingMetadataFilters, } from "./list.js";
+import { buildCompactSearchFilterSummary, buildVerboseSearchFilters, } from "./search-rendering.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, matchesTimestampFilters, nowIso, resolveIsoOrRelative, } from "../../core/shared/time.js";
+import { listAllDocumentCandidatesCached } from "../../core/store/item-metadata-cache.js";
+import { listAllItemMetadata } from "../../core/store/item-store.js";
+import { getItemPath, getSettingsPath, resolveGlobalPmRoot, resolvePmRoot, } from "../../core/store/paths.js";
+import { readSettings } from "../../core/store/settings.js";
+import { resolveSearchPage } from "./search-pagination.js";
+const DEFAULT_COMPACT_SEARCH_FIELDS = [
+    "id",
+    "title",
+    "status",
+    "type",
+    "priority",
+    "updated_at",
+    "score",
+    "matched_fields",
+];
+const SEARCH_HIT_FIELD_KEYS = new Set([
+    "score",
+    "matched_fields",
+    "highlights",
+]);
+const SEARCH_ITEM_FIELD_KEYS = new Set([
+    "id",
+    "title",
+    "description",
+    "type",
+    "status",
+    "priority",
+    "tags",
+    "created_at",
+    "updated_at",
+    "deadline",
+    "assignee",
+    "author",
+    "estimated_minutes",
+    "acceptance_criteria",
+    "dependencies",
+    "comments",
+    "notes",
+    "learnings",
+    "reminders",
+    "events",
+    "files",
+    "tests",
+    "docs",
+    "close_reason",
+    "parent",
+    "reviewer",
+    "risk",
+    "confidence",
+    "sprint",
+    "release",
+    "blocked_by",
+    "blocked_reason",
+    "reporter",
+    "severity",
+    "environment",
+    "repro_steps",
+    "resolution",
+    "expected_result",
+    "actual_result",
+    "affected_version",
+    "fixed_version",
+    "component",
+    "regression",
+    "customer_impact",
+    "definition_of_ready",
+    "order",
+    "rank",
+    "goal",
+    "objective",
+    "value",
+    "impact",
+    "outcome",
+    "why_now",
+    "plan",
+]);
+const LONG_QUERY_TOKEN_THRESHOLD = 2;
+const LONG_QUERY_TITLE_EXACT_BONUS = 120;
+const LONG_QUERY_PHRASE_MULTIPLIER = 6;
+// GH-181: in default (OR) match mode, multi-token queries that match EVERY
+// distinct query token in some searchable field get an additive ranking bonus so
+// items covering all terms outrank items matching only a subset. This is a
+// RANKING preference, not a hard filter (use --match-mode and for that).
+const ALL_TERMS_COVERAGE_BONUS = 40;
+const EXACT_ID_MATCH_SCORE = 1_000;
+const SHORT_ID_MATCH_SCORE = 900;
+// GH-157 matched-text highlighting (--highlight): markers wrapping each matching
+// token run, and the number of characters of surrounding context retained on
+// each side of the first match in a field. The «…» guillemets are single
+// characters with negligible collision risk against item text, keeping the
+// snippet token-cheap while staying visually unambiguous for agents.
+const HIGHLIGHT_OPEN = "«";
+const HIGHLIGHT_CLOSE = "»";
+const HIGHLIGHT_SNIPPET_RADIUS = 60;
+// GH-157 inline query syntax: bare `field:value` tokens parsed out of the query
+// string and applied as the equivalent filter. The value may itself contain
+// colons (e.g. `tag:area:search`), so only the FIRST colon delimits field from
+// value. Explicit --field flags take precedence over an inline token (see
+// resolveInlineQueryFilters).
+const INLINE_QUERY_FILTER_FIELDS = [
+    "tag",
+    "status",
+    "type",
+    "priority",
+];
+/**
+ * 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 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(" ");
+}
+/**
+ * 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 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";
+}
+// Explicit --semantic/--hybrid searches must never hard-fail an agent when the
+// embedding/vector backend is unreachable or unconfigured: degrade to keyword
+// search and surface a machine-readable warning instead of an unknown_error.
+function buildExplicitSemanticFallbackWarning(requestedMode, error) {
+    const reason = classifyImplicitSemanticFallbackReason(error);
+    return `search_${requestedMode}_fallback:${reason}:using_keyword_mode`;
+}
+/** 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. */
+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;
+        }
+        warnings.push(`vector_index_stale:${staleIds.length}`);
+        /* c8 ignore start -- singular/plural warning text branches are cosmetic and validated in integration UX tests */
+        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 — they will be missing from semantic/hybrid results until you run 'pm reindex --mode hybrid'. (Write-time embedding is governed by search.mutation_refresh_policy; staleness means the embed was skipped, failed, or the backend was unreachable.)\n`);
+        /* c8 ignore stop */
+    }
+    catch {
+        // Best-effort: missing/unreadable ledger is not a query-blocking concern.
+    }
+}
+function parseMode(raw, _context) {
+    if (raw === undefined) {
+        return "keyword";
+    }
+    const normalized = raw.trim().toLowerCase();
+    if (normalized !== "keyword" &&
+        normalized !== "semantic" &&
+        normalized !== "hybrid") {
+        throw new PmCliError("Search mode must be one of keyword|semantic|hybrid", EXIT_CODE.USAGE);
+    }
+    return normalized;
+}
+function parseIncludeLinked(raw) {
+    return raw === true;
+}
+function parseTitleExact(raw) {
+    return raw === true;
+}
+function parsePhraseExact(raw) {
+    return raw === true;
+}
+function parseSemanticWeightOverride(raw) {
+    return coerceNumberInRange(raw, 0, 1) ?? undefined;
+}
+function parseMatchMode(raw) {
+    if (raw === undefined) {
+        return "or";
+    }
+    const normalized = raw.trim().toLowerCase();
+    if (normalized !== "and" && normalized !== "or" && normalized !== "exact") {
+        throw new PmCliError("Search --match-mode must be one of and|or|exact", EXIT_CODE.USAGE);
+    }
+    return normalized;
+}
+// Per-query --min-score overrides the persistent search.score_threshold for this
+// query only. Accepts a finite number >= 0; anything else is a usage error.
+function parseMinScoreOverride(raw) {
+    if (raw === undefined || raw === null || raw === "") {
+        return undefined;
+    }
+    /* c8 ignore start -- numeric-vs-string coercion branch is exercised via integration CLI parsing */
+    const parsed = typeof raw === "number" ? raw : Number(String(raw).trim());
+    /* c8 ignore stop */
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        throw new PmCliError("Search --min-score must be a finite number >= 0", EXIT_CODE.USAGE);
+    }
+    return parsed;
+}
+// updated/created date-window filters share the deadline ISO+relative resolver
+// so `pm search` matches `pm list` semantics exactly: pass an ISO timestamp or a
+// SIGNED relative offset ("-2h"/"-7d" reach into the past, "+1d" the future;
+// units h/d/w/m, m = months — there is no minutes unit).
+function parseTimestampWindow(raw, fieldLabel) {
+    if (raw == null)
+        return undefined;
+    const value = String(raw).trim();
+    if (value.length === 0)
+        return undefined;
+    return resolveIsoOrRelative(value, new Date(), fieldLabel);
+}
+function normalizeSearchPhrase(value) {
+    return value.toLowerCase().replace(/\s+/g, " ").trim();
+}
+function parseDeadline(raw, fieldLabel) {
+    if (raw === undefined)
+        return undefined;
+    return resolveIsoOrRelative(raw, new Date(), fieldLabel);
+}
+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: [],
+    };
+}
+/** Public contract for test only search command, shared by SDK and presentation-layer consumers. */
+export const _testOnlySearchCommand = {
+    applyFilters,
+    applyExactQueryFilters,
+    applyInlineQueryFilters,
+    buildHitHighlights,
+    buildVerboseSearchFilters,
+    buildExplicitSemanticFallbackWarning,
+    buildCompactSearchFilterSummary,
+    buildHybridLexicalScore,
+    buildRerankCorpus,
+    buildSemanticHits,
+    classifyImplicitSemanticFallbackReason,
+    collectErrorCauseCodes,
+    collectExactPhraseFields,
+    collectLinkedPaths,
+    combineHybridHits,
+    computeBuiltInBm25Hits,
+    computeSemanticOrHybridHits,
+    resolveBuiltInBm25Mode,
+    countOccurrences,
+    dependencyEntries,
+    documentContainsExactPhrase,
+    emptySearchResult,
+    highlightFieldSnippet,
+    loadDocuments,
+    markTokenRuns,
+    parseInlineQueryFilters,
+    maybeEmitVectorIndexStaleWarning,
+    loadLinkedCorpus,
+    mergeVectorHitsById,
+    normalizeExtensionProviderHits,
+    normalizeScoreMap,
+    parseProjectionConfig,
+    parseTimestampWindow,
+    parseTokens,
+    projectSearchHits,
+    readSearchFieldValue,
+    requireSemanticDependencies,
+    resolveExtensionSearchProvider,
+    resolveExtensionSearchProviderByName,
+    resolveExtensionVectorAdapter,
+    resolveLinkedCorpusRoots,
+    scoreDocument,
+    sortHits,
+    stringArray,
+    textEntries,
+    validateSearchProjectionFields,
+};
+/* c8 ignore start -- projection/runtime-field validation edge permutations are covered by integration query-contract tests */
+function validateSearchProjectionFields(projection, runtimeFieldRegistry) {
+    if (projection.mode !== "fields") {
+        return;
+    }
+    const runtimeKeys = new Set(runtimeFieldRegistry.definitions.flatMap((field) => [
+        field.key,
+        field.metadata_key,
+    ]));
+    const unknown = projection.fields.filter((field) => {
+        const normalized = field.trim();
+        const itemKey = normalized.startsWith("item.")
+            ? normalized.slice("item.".length)
+            : normalized;
+        return (!SEARCH_HIT_FIELD_KEYS.has(normalized) &&
+            !SEARCH_ITEM_FIELD_KEYS.has(itemKey) &&
+            !runtimeKeys.has(itemKey));
+    });
+    if (unknown.length > 0) {
+        throw new PmCliError(`Unknown search --fields value(s): ${unknown.join(", ")}`, EXIT_CODE.USAGE, {
+            examples: [
+                "pm search <query> --fields id,title,status,score",
+                "pm search <query> --fields id,title,item.description,matched_fields",
+            ],
+            nextSteps: [
+                "Use item.<field> for explicit item metadata fields, or run pm search --help for projection examples.",
+            ],
+        });
+    }
+}
+/* c8 ignore stop */
+function parseTokens(query) {
+    const normalized = normalizeSearchPhrase(query);
+    if (!normalized) {
+        throw new PmCliError("Search query must not be empty", EXIT_CODE.USAGE);
+    }
+    return normalized.split(/\s+/).filter(Boolean);
+}
+/**
+ * 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.
+ */
+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
+            : undefined;
+        if (matchedField &&
+            value.length > 0 &&
+            inlineFilters[matchedField] === undefined) {
+            inlineFilters[matchedField] = value;
+            continue;
+        }
+        residualTokens.push(token);
+    }
+    return {
+        residualQuery: residualTokens.join(" "),
+        inlineFilters,
+    };
+}
+/** 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. */
+function applyInlineQueryFilters(options, inlineFilters, warnings) {
+    const merged = { ...options };
+    for (const field of INLINE_QUERY_FILTER_FIELDS) {
+        const inlineValue = inlineFilters[field];
+        if (inlineValue === undefined) {
+            continue;
+        }
+        if (toNonEmptyStringOrUndefined(merged[field]) !== undefined) {
+            warnings.push(`search_inline_filter_ignored:${field}:flag_takes_precedence`);
+            continue;
+        }
+        merged[field] = inlineValue;
+    }
+    return merged;
+}
+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) {
+    // Match pm list: --assignee no longer accepts none/null (unassigned filtering
+    // belongs to a dedicated flag there; pm search has no presence flag so reject
+    // the sentinel values explicitly rather than silently matching a literal).
+    if (assigneeFilter &&
+        (assigneeFilter.toLowerCase() === "none" ||
+            assigneeFilter.toLowerCase() === "null")) {
+        throw new PmCliError('--assignee no longer accepts "none" or "null".', EXIT_CODE.USAGE);
+    }
+}
+function resolveSearchMetadataFilterSet(options, typeRegistry, statusFilter) {
+    const assigneeFilter = options.assignee?.trim();
+    assertSearchAssigneeFilter(assigneeFilter);
+    const missingMetadataFilters = resolveMissingMetadataFilters(options);
+    const contentFieldFilters = resolveContentFieldFilters(options);
+    return {
+        typeFilter: parseType(options.type, typeRegistry),
+        tagFilter: options.tag?.trim().toLowerCase(),
+        priorityFilter: parsePriority(options.priority),
+        deadlineBefore: parseDeadline(options.deadlineBefore, "deadline-before"),
+        deadlineAfter: parseDeadline(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: options.sprint?.trim(),
+        releaseFilter: options.release?.trim(),
+        parentFilter: options.parent?.trim(),
+        statusSet: statusFilter && statusFilter.length > 0
+            ? new Set(statusFilter)
+            : undefined,
+        missingMetadataFilters,
+        missingMetadataActive: hasMissingMetadataFilter(missingMetadataFilters),
+        contentFieldFilters,
+        contentFiltersActive: hasContentFieldFilter(contentFieldFilters),
+    };
+}
+function matchesScalarSearchFilters(item, filters) {
+    return (matchesIdentitySearchFilters(item, filters) &&
+        matchesTimestampSearchFilters(item, filters) &&
+        matchesOwnerSearchFilters(item, filters));
+}
+function matchesIdentitySearchFilters(item, filters) {
+    if (filters.statusSet && !filters.statusSet.has(item.status))
+        return false;
+    if (filters.typeFilter && item.type !== filters.typeFilter)
+        return false;
+    if (filters.tagFilter && !stringArray(item.tags).includes(filters.tagFilter))
+        return false;
+    if (filters.priorityFilter !== undefined &&
+        item.priority !== filters.priorityFilter)
+        return false;
+    return true;
+}
+function matchesTimestampSearchFilters(item, filters) {
+    return matchesTimestampFilters(item, filters);
+}
+function matchesOwnerSearchFilters(item, filters) {
+    if (filters.assigneeFilter !== undefined &&
+        item.assignee !== filters.assigneeFilter)
+        return false;
+    if (filters.sprintFilter !== undefined &&
+        item.sprint !== filters.sprintFilter)
+        return false;
+    /* c8 ignore start -- release/parent metadata filter combinations are covered by integration search fixtures */
+    if (filters.releaseFilter !== undefined &&
+        item.release !== filters.releaseFilter)
+        return false;
+    if (filters.parentFilter !== undefined &&
+        item.parent !== filters.parentFilter)
+        return false;
+    /* c8 ignore stop */
+    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));
+}
+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;
+    }
+}
+function tokenizeForExactTokenMatch(value) {
+    return tokenizeAlphaNumeric(value);
+}
+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 {
+            // Best-effort linked-content indexing: unreadable paths are ignored.
+        }
+    }
+    return chunks.join("\n");
+}
+/**
+ * Canonical definition of the document-derived searchable fields shared by the
+ * lexical scorer ({@link scoreDocument}) and the matched-text highlighter
+ * ({@link buildHitHighlights}). Keeping a single source of field name → text
+ * extractor → tuning weight guarantees the highlighter can only ever produce
+ * snippets for fields the scorer actually inspected. The `linked_content` field
+ * is appended separately by the scorer because its text is supplied per-query
+ * rather than derived from the document.
+ */
+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),
+    },
+];
+// Name → builder index so the highlighter can resolve a matched field to its
+// text extractor in O(1) and evaluate ONLY the matched fields' values, instead
+// of materializing all twelve (several of which join/build corpora) per hit.
+const SEARCHABLE_FIELD_BUILDER_BY_NAME = new Map(SEARCHABLE_FIELD_BUILDERS.map((builder) => [builder.name, builder]));
+function escapeRegExpLiteral(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * 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.
+ */
+function markTokenRuns(text, tokens) {
+    // Sort by length descending before building the alternation so a longer token
+    // wins over a shorter token that is its prefix (regex alternation is greedy
+    // left-to-right, so `auth|authority` would mark «auth»ority instead of
+    // «authority»). `.filter` already returns a fresh array, so the in-place sort
+    // never mutates the caller's token list.
+    const escaped = tokens
+        .filter((token) => token.length > 0)
+        .sort((left, right) => right.length - left.length)
+        .map(escapeRegExpLiteral);
+    if (escaped.length === 0) {
+        return text;
+    }
+    const pattern = new RegExp(escaped.join("|"), "gi");
+    return text.replace(pattern, (match) => `${HIGHLIGHT_OPEN}${match}${HIGHLIGHT_CLOSE}`);
+}
+/**
+ * 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).
+ */
+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 ? "…" : "";
+    const suffix = windowEnd < text.length ? "…" : "";
+    return `${prefix}${marked}${suffix}`;
+}
+/** 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. */
+function buildHitHighlights(document, matchedFields, tokens) {
+    const highlights = [];
+    for (const field of matchedFields) {
+        const builder = SEARCHABLE_FIELD_BUILDER_BY_NAME.get(field);
+        if (builder === undefined) {
+            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 tokenizeForExactTokenMatch(item.title)) {
+        titleTokenCounts.set(token, (titleTokenCounts.get(token) ?? 0) + 1);
+    }
+    const searchableFields = buildSearchableScoringFields(document, linkedCorpus, tuning);
+    const state = {
+        score: 0,
+        matched: new Set(),
+        matchedTokens: new Set(),
+    };
+    scoreTokenMatches(tokens, titleTokenCounts, searchableFields, tuning, state);
+    const distinctTokens = new Set(tokens);
+    // matchedTokens only ever holds entries drawn from `tokens`, so it is always a
+    // subset of distinctTokens — exact size equality means every distinct term matched.
+    const matchedAllTerms = distinctTokens.size > 0 && state.matchedTokens.size === distinctTokens.size;
+    // GH-181 default-mode all-terms ranking bonus: only meaningful for multi-token
+    // queries where every distinct token matched somewhere.
+    if (applyCoverageBonus && distinctTokens.size > 1 && matchedAllTerms) {
+        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) {
+    /* c8 ignore start -- linked corpus presence branch is covered by keyword/hybrid integration query tests */
+    return scoreDocument(document, tokens, normalizedQuery, includeLinked ? (linkedCorpusById.get(document.metadata.id) ?? "") : "", tuning, idPrefix, applyCoverageBonus);
+    /* c8 ignore stop */
+}
+function normalizeScoreMap(scoreById) {
+    if (scoreById.size === 0) {
+        return new Map();
+    }
+    const values = [...scoreById.values()];
+    const minScore = Math.min(...values);
+    const maxScore = Math.max(...values);
+    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;
+}
+/** Implements resolve search max results for the public runtime surface of this module. */
+export function resolveSearchMaxResults(settings) {
+    const candidate = settings.search
+        ?.max_results;
+    if (typeof candidate === "number" &&
+        Number.isFinite(candidate) &&
+        candidate > 0) {
+        return Math.floor(candidate);
+    }
+    return 50;
+}
+/** Implements resolve search score threshold for the public runtime surface of this module. */
+export function resolveSearchScoreThreshold(settings) {
+    const candidate = settings
+        .search?.score_threshold;
+    if (typeof candidate === "number" && Number.isFinite(candidate)) {
+        return candidate;
+    }
+    return 0;
+}
+/** Implements resolve hybrid semantic weight for the public runtime surface of this module. */
+export function resolveHybridSemanticWeight(settings) {
+    const candidate = settings.search?.hybrid_semantic_weight;
+    if (typeof candidate === "number" &&
+        Number.isFinite(candidate) &&
+        candidate >= 0 &&
+        candidate <= 1) {
+        return candidate;
+    }
+    return 0.7;
+}
+/** Implements resolve search tuning for the public runtime surface of this module. */
+export function resolveSearchTuning(settings) {
+    const defaults = {
+        title_exact_bonus: 10,
+        title_weight: 8,
+        description_weight: 5,
+        tags_weight: 6,
+        status_weight: 2,
+        body_weight: 1,
+        comments_weight: 1,
+        notes_weight: 1,
+        learnings_weight: 1,
+        reminders_weight: 2,
+        events_weight: 2,
+        dependencies_weight: 3,
+        linked_content_weight: 1,
+    };
+    const tuning = settings
+        .search?.tuning;
+    if (!tuning)
+        return defaults;
+    const resolveWeight = (candidate, fallback) => {
+        if (typeof candidate === "number" &&
+            Number.isFinite(candidate) &&
+            candidate >= 0) {
+            return candidate;
+        }
+        return fallback;
+    };
+    return {
+        title_exact_bonus: resolveWeight(tuning.title_exact_bonus, defaults.title_exact_bonus),
+        title_weight: resolveWeight(tuning.title_weight, defaults.title_weight),
+        description_weight: resolveWeight(tuning.description_weight, defaults.description_weight),
+        tags_weight: resolveWeight(tuning.tags_weight, defaults.tags_weight),
+        status_weight: resolveWeight(tuning.status_weight, defaults.status_weight),
+        body_weight: resolveWeight(tuning.body_weight, defaults.body_weight),
+        comments_weight: resolveWeight(tuning.comments_weight, defaults.comments_weight),
+        notes_weight: resolveWeight(tuning.notes_weight, defaults.notes_weight),
+        learnings_weight: resolveWeight(tuning.learnings_weight, defaults.learnings_weight),
+        reminders_weight: resolveWeight(tuning.reminders_weight, defaults.reminders_weight),
+        events_weight: resolveWeight(tuning.events_weight, defaults.events_weight),
+        dependencies_weight: resolveWeight(tuning.dependencies_weight, defaults.dependencies_weight),
+        linked_content_weight: resolveWeight(tuning.linked_content_weight, defaults.linked_content_weight),
+    };
+}
+/* c8 ignore start -- empty-result projection/count/warnings shape matrix is validated by integration response-contract tests */
+function emptySearchResult(query, mode, matchMode, options, includeLinked, scoreThreshold, hybridSemanticWeight, queryExpansion, rerank, projection, warnings, runtimeFieldFilters, countOnly = false) {
+    // --count consistency: a count-only query that matches nothing must still
+    // carry the same { count_only: true, total } shape as the non-empty path.
+    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,
+            items: [],
+            count: 0,
+            ...countExtras,
+            filters: compactFilters,
+            ...(warnings.length > 0 ? { warnings } : {}),
+        };
+    }
+    const projectionFields = projection.mode === "full" ? null : [...projection.fields];
+    return {
+        query: query.trim(),
+        mode,
+        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 } : {}),
+    };
+}
+/* c8 ignore stop */
+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;
+/* c8 ignore start -- extension search-provider registration permutations are covered by extension integration suites */
+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;
+    /* c8 ignore next 2 -- providerName is required for lookup and remains a non-empty fallback */
+    if (!registeredName) {
+        return null;
+    }
+    const hooks = {
+        providerName: registeredName,
+        ...(typeof query === "function"
+            ? { query: query }
+            : {}),
+        ...(typeof queryExpansion === "function"
+            ? {
+                queryExpansion: queryExpansion,
+            }
+            : {}),
+        ...(typeof rerank === "function"
+            ? { rerank: rerank }
+            : {}),
+    };
+    if (!hooks.query && !hooks.queryExpansion && !hooks.rerank) {
+        return null;
+    }
+    return hooks;
+}
+/* c8 ignore stop */
+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,
+    };
+}
+/* c8 ignore start -- vector adapter runtime definition permutations are covered by extension integration suites */
+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: query,
+        ...(typeof upsert === "function"
+            ? { upsert: upsert }
+            : {}),
+    };
+}
+/* c8 ignore stop */
+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,
+    };
+}
+// GH-281: in semantic & hybrid mode the blended/vector scores live on an
+// arbitrary scale (blended hybrid scores are [0,1]; raw vector similarities are
+// provider-defined), so an exact full-ID or short-ID keyword match can be
+// out-ranked by a high-semantic body mention. This reattaches the exact-ID
+// keyword hit(s) to the top of the ranked set in a reserved band ABOVE every
+// other hit, preserving matched_fields:["id"] and keeping full-ID above
+// short-ID. The reserved scores are derived from the current max so the
+// guarantee holds no matter what scale the backend returns, and the hit is
+// re-inserted even if it was dropped from `rankedHits` (e.g. it had no semantic
+// vector match) so it is never lost to the threshold or the result-limit slice.
+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));
+    // reduce (not Math.max(...spread)) so a very large pre-truncation candidate
+    // set can never overflow the call stack.
+    const maxRemainingScore = remaining.reduce((max, hit) => Math.max(max, hit.score), 0);
+    // Full-ID hits (score 1000) must rank above short-ID hits (score 900): rank
+    // within the exact-ID band by the original keyword score (descending) so a
+    // full-ID match always precedes a short-ID match for the same query, then
+    // offset the whole band above every remaining hit. ids are unique, so two
+    // exact-ID hits can never tie on score — sorting on score alone is total.
+    // exactIdHits is already a fresh array from keywordHits.filter(...), so sort
+    // it in place — no defensive copy needed.
+    const orderedExactHits = exactIdHits.sort((left, right) => right.score - left.score);
+    const bandBase = maxRemainingScore + orderedExactHits.length + 1;
+    const promoted = orderedExactHits.map((hit, index) => ({
+        // Spread the original keyword hit so flags like matched_all_terms /
+        // exact_id_match are preserved; only the band-slot score and the id-only
+        // matched_fields are overridden.
+        ...hit,
+        // Higher band slot for earlier (higher original keyword score) hits.
+        score: bandBase - index,
+        matched_fields: ["id"],
+    }));
+    return [...promoted, ...remaining];
+}
+function combineHybridHits(filteredById, semanticScores, keywordHits, hybridSemanticWeight, 
+// Matched-field label for the dense-ranking component. Defaults to "semantic"
+// (vector retrieval); the offline BM25 hybrid path passes "bm25" so hits carry
+// an honest provenance marker instead of implying a vector match (pm-75k9).
+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;
+}
+/**
+ * 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.
+ */
+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;
+}
+/* c8 ignore start -- rerank corpus metadata-shape permutations are covered by semantic integration tests */
+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");
+}
+/* c8 ignore stop */
+/* c8 ignore start -- semantic expansion/rerank fallback matrices are covered by end-to-end semantic search tests */
+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 === undefined) {
+            return hit;
+        }
+        const matchedFields = new Set(hit.matched_fields);
+        matchedFields.add("rerank");
+        return {
+            ...hit,
+            score: rerankScore,
+            matched_fields: [...matchedFields].sort((left, right) => left.localeCompare(right)),
+        };
+    });
+    rerankedHits.sort((left, right) => {
+        const leftWasReranked = rerankedIds.has(left.item.id);
+        const rightWasReranked = rerankedIds.has(right.item.id);
+        if (leftWasReranked !== rightWasReranked) {
+            return leftWasReranked ? -1 : 1;
+        }
+        if (left.score !== right.score) {
+            return right.score - left.score;
+        }
+        return left.item.id.localeCompare(right.item.id);
+    });
+    return rerankedHits;
+}
+async function applyHybridRerank(context, queryTrimmed, hybridHits, filteredById) {
+    if (!context.rerank.enabled || hybridHits.length <= 1) {
+        return hybridHits;
+    }
+    const candidateContexts = buildRerankCandidateContexts(hybridHits, filteredById, context.rerank.top_k);
+    const rerankScores = await resolveRerankScores(context, queryTrimmed, candidateContexts);
+    return rerankScores && rerankScores.size > 0
+        ? applyRerankScores(hybridHits, rerankScores)
+        : hybridHits;
+}
+async function computeSemanticOrHybridHits(context) {
+    const semanticLimit = Math.max(context.limit ?? context.maxResults, context.maxResults);
+    const embeddingOptions = context.embeddingTimeoutMs !== undefined
+        ? { timeout_ms: context.embeddingTimeoutMs }
+        : {};
+    const vectorQueryOptions = context.vectorQueryTimeoutMs !== undefined
+        ? { timeout_ms: context.vectorQueryTimeoutMs }
+        : {};
+    const queryTrimmed = context.query.trim();
+    const expandedQueries = await resolveExpandedSemanticQueries(context, queryTrimmed);
+    const queryVectors = await executeEmbeddingRequest(context.provider, expandedQueries, embeddingOptions);
+    const queryVectorGroups = await Promise.all(queryVectors.map(async (semanticVector) => await executeSemanticVectorQuery(context, semanticVector, semanticLimit, vectorQueryOptions)));
+    const vectorHits = mergeVectorHitsById(queryVectorGroups);
+    const filteredById = new Map(context.filteredDocuments.map((document) => [
+        document.metadata.id,
+        document,
+    ]));
+    const { semanticHits, semanticScores } = buildSemanticHits(vectorHits, filteredById);
+    const vectorMatchCount = semanticScores.size;
+    if (context.requestedMode === "semantic") {
+        // GH-281: guarantee an exact full-ID / short-ID match ranks #1 even in pure
+        // semantic mode, where it otherwise carries no vector hit at all.
+        return {
+            hits: forceExactIdHitsToTop(semanticHits, context.keywordHits),
+            vectorMatchCount,
+        };
+    }
+    const hybridHits = await applyHybridRerank(context, queryTrimmed, combineHybridHits(filteredById, semanticScores, context.keywordHits, context.hybridSemanticWeight), filteredById);
+    return {
+        // GH-281: applied LAST (after any rerank reordering) so an exact full-ID /
+        // short-ID keyword match always ranks #1 in hybrid mode regardless of the
+        // semantic blend weight or rerank scores.
+        hits: forceExactIdHitsToTop(hybridHits, context.keywordHits),
+        vectorMatchCount,
+    };
+}
+/* c8 ignore stop */
+/* c8 ignore start -- item body fallback read-path combinations are covered by document-cache integration tests */
+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)),
+    };
+}
+/* c8 ignore stop */
+/* c8 ignore start -- field projection lookup precedence is validated by output-shaping integration tests */
+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 = toItemRecord(hit.item);
+        return itemRecord[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;
+}
+/* c8 ignore stop */
+function projectSearchHits(hits, projection) {
+    if (projection.mode === "full") {
+        // matched_all_terms is an internal ranking signal (GH-181); strip it from
+        // full-mode output rows so the public hit shape stays { item, score, matched_fields }.
+        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 resolveQueryExpansionExtension(queryExpansion) {
+    const provider = resolveExtensionSearchProviderByName(queryExpansion.provider ?? undefined);
+    return provider?.queryExpansion
+        ? { providerName: provider.providerName, expand: provider.queryExpansion }
+        : null;
+}
+function resolveRerankExtension(settings) {
+    const provider = resolveExtensionSearchProviderByName(toOptionalNonEmptyString(settings.search?.provider));
+    return provider?.rerank
+        ? { providerName: provider.providerName, rerank: provider.rerank }
+        : null;
+}
+function prepareSearchInput(rawQuery, rawOptions) {
+    const inlineWarnings = [];
+    const inlineParse = parseInlineQueryFilters(rawQuery);
+    const hasInlineFilters = Object.keys(inlineParse.inlineFilters).length > 0;
+    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: parseIncludeLinked(options.includeLinked),
+        titleExact: parseTitleExact(options.titleExact),
+        phraseExact: parsePhraseExact(options.phraseExact),
+        matchMode: parseMatchMode(typeof options.matchMode === "string" ? options.matchMode : undefined),
+        minScoreOverride: parseMinScoreOverride(options.minScore),
+        countOnly: options.count === true,
+        tokens: parseTokens(query),
+        normalizedQuery: normalizeSearchPhrase(query),
+        limit: parseLimit(options.limit),
+        projection: parseProjectionConfig(options),
+        modeWasExplicit: typeof options.mode === "string" && options.mode.trim().length > 0,
+    };
+}
+async function resolveSearchRuntimeContext(prepared, global) {
+    const pmRoot = resolvePmRoot(process.cwd(), global.path);
+    if (!(await pathExists(getSettingsPath(pmRoot)))) {
+        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
+    }
+    const storedSettings = await readSettings(pmRoot);
+    const settings = resolveSettingsWithSemanticRuntimeDefaults(storedSettings).settings;
+    const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);
+    const runtimeFieldRegistry = resolveRuntimeFieldRegistry(settings.schema);
+    validateSearchProjectionFields(prepared.projection, runtimeFieldRegistry);
+    const runtimeFieldFilters = collectRuntimeFilterValues(prepared.options, runtimeFieldRegistry, "search");
+    const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
+    const providerResolution = resolveEmbeddingProviders(settings);
+    const vectorResolution = resolveVectorStores(settings, pmRoot);
+    const extensionSearchProvider = resolveExtensionSearchProvider(settings);
+    const extensionVectorAdapter = resolveExtensionVectorAdapter(settings);
+    const semanticWeightOverride = parseSemanticWeightOverride(prepared.options.semanticWeight);
+    const queryExpansion = resolveQueryExpansionConfig(settings, providerResolution.active?.name ?? null);
+    const rerank = resolveRerankConfig(settings, providerResolution.active?.model ??
+        toOptionalNonEmptyString(settings.search?.embedding_model) ??
+        "text-embedding-3-small");
+    return {
+        pmRoot,
+        settings,
+        statusRegistry,
+        runtimeFieldRegistry,
+        runtimeFieldFilters,
+        typeRegistry,
+        maxResults: resolveSearchMaxResults(settings),
+        scoreThreshold: prepared.minScoreOverride ?? resolveSearchScoreThreshold(settings),
+        semanticWeightProvided: prepared.options.semanticWeight !== undefined,
+        semanticWeightOverride,
+        hybridSemanticWeight: semanticWeightOverride ?? resolveHybridSemanticWeight(settings),
+        tuning: resolveSearchTuning(settings),
+        providerResolution,
+        vectorResolution,
+        extensionSearchProvider,
+        extensionVectorAdapter,
+        bm25Mode: resolveBuiltInBm25Mode({
+            configuredProvider: toOptionalNonEmptyString(settings.search?.provider),
+            hasEmbeddingProvider: providerResolution.active !== null,
+            hasExtensionSearchProvider: extensionSearchProvider !== null,
+        }),
+        queryExpansion,
+        queryExpansionExtension: resolveQueryExpansionExtension(queryExpansion),
+        rerank,
+        rerankExtension: resolveRerankExtension(settings),
+        effectiveMode: parseMode(prepared.options.mode, {
+            hasProvider: providerResolution.active !== null || extensionSearchProvider !== null,
+            hasVectorStore: vectorResolution.active !== null || extensionVectorAdapter !== null,
+        }),
+    };
+}
+async function loadFilteredSearchCorpus(prepared, runtime) {
+    const loadedDocuments = await loadDocuments(runtime.pmRoot, runtime.settings.item_format ?? "toon", runtime.typeRegistry.type_to_folder, runtime.settings.schema);
+    const statusFilter = parseStatusFilterCsv(typeof prepared.options.status === "string"
+        ? prepared.options.status
+        : undefined, runtime.statusRegistry, { strict: true });
+    const lifecycleClassifier = lifecycleClassifierFromStatusRegistry(runtime.statusRegistry);
+    const metadataFilteredDocuments = applyFilters(loadedDocuments.documents, prepared.options, runtime.typeRegistry, runtime.runtimeFieldFilters, statusFilter, lifecycleClassifier);
+    return {
+        warnings: loadedDocuments.warnings,
+        allDocuments: loadedDocuments.documents,
+        filteredDocuments: applyExactQueryFilters(metadataFilteredDocuments, prepared.normalizedQuery, {
+            titleExact: prepared.titleExact,
+            phraseExact: prepared.phraseExact || prepared.matchMode === "exact",
+        }),
+    };
+}
+async function collectLinkedCorpusById(includeLinked, effectiveMode, filteredDocuments) {
+    const linkedCorpusById = new Map();
+    if (!includeLinked ||
+        (effectiveMode !== "keyword" && effectiveMode !== "hybrid")) {
+        return linkedCorpusById;
+    }
+    const projectRoot = process.cwd();
+    const linkedCorpusRoots = await resolveLinkedCorpusRoots(projectRoot, resolveGlobalPmRoot(projectRoot));
+    const linkedCorpusEntries = await Promise.all(filteredDocuments.map(async (document) => [
+        document.metadata.id,
+        await loadLinkedCorpus(document, linkedCorpusRoots),
+    ]));
+    for (const [id, corpus] of linkedCorpusEntries) {
+        linkedCorpusById.set(id, corpus);
+    }
+    return linkedCorpusById;
+}
+async function computeKeywordSearchHits(prepared, runtime, filteredDocuments) {
+    const linkedCorpusById = await collectLinkedCorpusById(prepared.includeLinked, runtime.effectiveMode, filteredDocuments);
+    const applyCoverageBonus = prepared.matchMode === "or";
+    return filteredDocuments
+        .map((document) => buildHybridLexicalScore(document, prepared.tokens, prepared.normalizedQuery, prepared.includeLinked, linkedCorpusById, runtime.tuning, runtime.settings.id_prefix, applyCoverageBonus))
+        .filter((entry) => entry !== null)
+        .filter((entry) => prepared.matchMode !== "and" || entry.matched_all_terms === true);
+}
+function buildEmptySearchResultFromContext(response, countOnly) {
+    return emptySearchResult(response.query, response.effectiveMode, response.matchMode, response.options, response.includeLinked, response.scoreThreshold, response.hybridSemanticWeight, response.queryExpansion, response.rerank, response.projection, response.warnings, response.runtimeFieldFilters, countOnly);
+}
+async function executeBuiltInBm25Search(prepared, runtime, filteredDocuments, keywordHits, warnings) {
+    if (runtime.bm25Mode === null || runtime.effectiveMode === "keyword") {
+        return null;
+    }
+    const hits = computeBuiltInBm25Hits({
+        requestedMode: runtime.effectiveMode,
+        query: prepared.query,
+        filteredDocuments,
+        keywordHits,
+        corpusFields: resolveSearchCorpusFields(runtime.settings),
+        bm25Params: resolveBm25Params(runtime.settings),
+        hybridSemanticWeight: runtime.hybridSemanticWeight,
+    });
+    if (runtime.bm25Mode === "auto-fallback") {
+        warnings.push(`search_${runtime.effectiveMode}_offline_bm25:no_embedding_provider:using_lexical_bm25`);
+    }
+    return hits;
+}
+async function executeExtensionSearchProvider(prepared, runtime, filteredDocuments, filteredById) {
+    if (!runtime.extensionSearchProvider) {
+        return null;
+    }
+    const canUseBuiltInSemantic = runtime.providerResolution.active !== null &&
+        (runtime.vectorResolution.active !== null ||
+            runtime.extensionVectorAdapter !== null);
+    try {
+        const providerResponse = await Promise.resolve(runtime.extensionSearchProvider.query({
+            query: prepared.query,
+            mode: runtime.effectiveMode,
+            tokens: prepared.tokens,
+            options: prepared.options,
+            settings: runtime.settings,
+            documents: filteredDocuments,
+        }));
+        return normalizeExtensionProviderHits(runtime.extensionSearchProvider.providerName, providerResponse, filteredById);
+    }
+    catch (error) {
+        if (!canUseBuiltInSemantic) {
+            throw new PmCliError(`Extension search provider "${runtime.extensionSearchProvider.providerName}" failed: ${error instanceof Error ? error.message : String(error)}`, EXIT_CODE.GENERIC_FAILURE);
+        }
+        return null;
+    }
+}
+function maybeApplyNoVectorFallback(effectiveMode, semanticResult, keywordHits, warnings) {
+    if (semanticResult.vectorMatchCount > 0) {
+        return semanticResult.hits;
+    }
+    warnings.push(`search_${effectiveMode}_degraded:no_vector_matches:results_are_lexical`);
+    return effectiveMode === "semantic" ? keywordHits : semanticResult.hits;
+}
+async function prepareBuiltInSemanticSearch(runtime, effectiveMode, filteredDocuments, warnings, modeWasExplicit) {
+    const builtInSemanticWillRun = !runtime.extensionSearchProvider &&
+        runtime.providerResolution.active !== null &&
+        (runtime.vectorResolution.active !== null ||
+            runtime.extensionVectorAdapter !== null);
+    if (modeWasExplicit && builtInSemanticWillRun) {
+        await maybeEmitVectorIndexStaleWarning(runtime.pmRoot, filteredDocuments, warnings);
+    }
+    if (!runtime.extensionSearchProvider) {
+        requireSemanticDependencies(effectiveMode, runtime.providerResolution, runtime.vectorResolution, runtime.extensionVectorAdapter !== null);
+    }
+}
+async function executeSemanticSearch(input) {
+    const { prepared, runtime, filteredDocuments, keywordHits, warnings, modeWasExplicit, } = input;
+    let hits = keywordHits;
+    const bm25Hits = await executeBuiltInBm25Search(prepared, runtime, filteredDocuments, keywordHits, warnings);
+    const semanticMode = runtime.effectiveMode;
+    if (bm25Hits !== null || semanticMode === "keyword") {
+        return { effectiveMode: runtime.effectiveMode, hits: bm25Hits ?? hits };
+    }
+    try {
+        await prepareBuiltInSemanticSearch(runtime, semanticMode, filteredDocuments, warnings, modeWasExplicit);
+        if (filteredDocuments.length === 0 || prepared.limit === 0) {
+            return { effectiveMode: runtime.effectiveMode, hits: [] };
+        }
+        const filteredById = new Map(filteredDocuments.map((document) => [document.metadata.id, document]));
+        hits =
+            (await executeExtensionSearchProvider(prepared, runtime, filteredDocuments, filteredById)) ?? hits;
+        if (hits === keywordHits) {
+            const { provider, vectorStore } = requireSemanticDependencies(semanticMode, runtime.providerResolution, runtime.vectorResolution, runtime.extensionVectorAdapter !== null);
+            const semanticResult = await computeSemanticOrHybridHits({
+                requestedMode: semanticMode,
+                query: prepared.query,
+                filteredDocuments,
+                keywordHits,
+                hybridSemanticWeight: runtime.hybridSemanticWeight,
+                limit: prepared.limit,
+                maxResults: runtime.maxResults,
+                provider,
+                vectorStore,
+                extensionVectorAdapter: runtime.extensionVectorAdapter,
+                queryExpansion: runtime.queryExpansion,
+                queryExpansionExtension: runtime.queryExpansionExtension,
+                rerank: runtime.rerank,
+                rerankExtension: runtime.rerankExtension,
+                warnings,
+                settings: runtime.settings,
+            });
+            hits = maybeApplyNoVectorFallback(semanticMode, semanticResult, keywordHits, warnings);
+        }
+        return { effectiveMode: runtime.effectiveMode, hits };
+    }
+    catch (error) {
+        warnings.push(buildExplicitSemanticFallbackWarning(runtime.effectiveMode, error));
+        return { effectiveMode: "keyword", hits: keywordHits };
+    }
+}
+function buildCountOnlySearchResult(response, total) {
+    if (response.projection.mode === "compact" &&
+        response.options.compact === true) {
+        return withSearchWarnings({
+            query: response.query.trim(),
+            mode: response.effectiveMode,
+            items: [],
+            count: total,
+            total,
+            count_only: true,
+            filters: buildCompactSearchFilterSummary({
+                mode: response.effectiveMode,
+                matchMode: response.matchMode,
+                options: response.options,
+                includeLinked: response.includeLinked,
+                titleExact: response.titleExact,
+                phraseExact: response.phraseExact,
+                scoreThreshold: response.scoreThreshold,
+                hybridSemanticWeight: response.hybridSemanticWeight,
+                runtimeFieldFilters: response.runtimeFieldFilters,
+            }),
+        }, response.warnings);
+    }
+    const projectionFields = response.projection.mode === "full"
+        ? null
+        : [...response.projection.fields];
+    return withSearchWarnings({
+        query: response.query.trim(),
+        mode: response.effectiveMode,
+        items: [],
+        count: total,
+        total,
+        count_only: true,
+        filters: buildVerboseSearchFilters({
+            effectiveMode: response.effectiveMode,
+            matchMode: response.matchMode,
+            options: response.options,
+            includeLinked: response.includeLinked,
+            titleExact: response.titleExact,
+            phraseExact: response.phraseExact,
+            scoreThreshold: response.scoreThreshold,
+            hybridSemanticWeight: response.hybridSemanticWeight,
+            queryExpansion: response.queryExpansion,
+            rerank: response.rerank,
+            runtimeFieldFilters: response.runtimeFieldFilters,
+        }),
+        projection: {
+            mode: response.projection.mode,
+            fields: projectionFields,
+        },
+        now: nowIso(),
+    }, response.warnings);
+}
+function withSearchWarnings(result, warnings) {
+    if (warnings.length === 0) {
+        return result;
+    }
+    return { ...result, warnings };
+}
+function attachSearchHighlights(prepared, filteredDocuments, limited) {
+    if (!prepared.highlight) {
+        return { hits: limited, projection: prepared.projection };
+    }
+    const documentById = new Map(filteredDocuments.map((document) => [document.metadata.id, document]));
+    const hits = limited.map((hit) => ({
+        ...hit,
+        highlights: buildHitHighlights(documentById.get(hit.item.id), hit.matched_fields, prepared.tokens),
+    }));
+    if (prepared.projection.mode === "full" ||
+        prepared.projection.fields.includes("highlights")) {
+        return { hits, projection: prepared.projection };
+    }
+    return {
+        hits,
+        projection: {
+            mode: prepared.projection.mode,
+            fields: [...prepared.projection.fields, "highlights"],
+        },
+    };
+}
+function buildSearchResultForHits(response, projectedItems, total, limitedCount, effectiveProjection, pageExtras) {
+    const truncationExtras = limitedCount < total ? { total } : {};
+    if (response.projection.mode === "compact" &&
+        response.options.compact === true) {
+        return withSearchWarnings({
+            query: response.query.trim(),
+            mode: response.effectiveMode,
+            items: projectedItems,
+            count: projectedItems.length,
+            ...truncationExtras,
+            ...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,
+        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 } : {}),
+    };
+}
+function assertSearchPagingOptions(options) {
+    if (options.after !== undefined && options.count === true) {
+        throw new PmCliError("Search --after cannot be combined with --count.", EXIT_CODE.USAGE);
+    }
+}
+/** Implements run search for the public runtime surface of this module. */
+export async function runSearch(rawQuery, rawOptions, global) {
+    assertSearchPagingOptions(rawOptions);
+    const prepared = prepareSearchInput(rawQuery, rawOptions);
+    const runtime = await resolveSearchRuntimeContext(prepared, global);
+    const corpus = await loadFilteredSearchCorpus(prepared, runtime);
+    const warnings = corpus.warnings;
+    warnings.push(...prepared.inlineWarnings);
+    if (runtime.effectiveMode === "hybrid" &&
+        runtime.semanticWeightProvided &&
+        runtime.semanticWeightOverride === undefined) {
+        warnings.push("search_hybrid_semantic_weight_override_invalid:using_settings_default");
+    }
+    const responseBase = {
+        query: prepared.query,
+        matchMode: prepared.matchMode,
+        options: prepared.options,
+        includeLinked: prepared.includeLinked,
+        titleExact: prepared.titleExact,
+        phraseExact: prepared.phraseExact,
+        scoreThreshold: runtime.scoreThreshold,
+        hybridSemanticWeight: runtime.hybridSemanticWeight,
+        queryExpansion: runtime.queryExpansion,
+        rerank: runtime.rerank,
+        projection: prepared.projection,
+        warnings,
+        runtimeFieldFilters: runtime.runtimeFieldFilters,
+    };
+    if (runtime.effectiveMode === "keyword" &&
+        (corpus.filteredDocuments.length === 0 ||
+            (prepared.limit === 0 && !prepared.countOnly))) {
+        return buildEmptySearchResultFromContext({ ...responseBase, effectiveMode: runtime.effectiveMode }, prepared.countOnly);
+    }
+    const keywordHits = await computeKeywordSearchHits(prepared, runtime, corpus.filteredDocuments);
+    const modeResult = await executeSemanticSearch({
+        prepared,
+        runtime,
+        filteredDocuments: corpus.filteredDocuments,
+        keywordHits,
+        warnings,
+        modeWasExplicit: prepared.modeWasExplicit,
+    });
+    if (modeResult.effectiveMode !== "keyword" &&
+        modeResult.hits.length === 0 &&
+        (corpus.filteredDocuments.length === 0 ||
+            (prepared.limit === 0 && !prepared.countOnly))) {
+        return buildEmptySearchResultFromContext({ ...responseBase, effectiveMode: modeResult.effectiveMode }, prepared.countOnly);
+    }
+    const thresholded = modeResult.hits.filter((entry) => entry.exact_id_match === true || entry.score >= runtime.scoreThreshold);
+    const sorted = sortHits(thresholded, runtime.statusRegistry);
+    const total = sorted.length;
+    const page = resolveSearchPage({
+        sorted,
+        query: prepared.query,
+        mode: modeResult.effectiveMode,
+        searchOptions: prepared.options,
+        limit: prepared.limit ?? runtime.maxResults,
+    });
+    const response = { ...responseBase, effectiveMode: modeResult.effectiveMode };
+    if (prepared.countOnly) {
+        return buildCountOnlySearchResult(response, total);
+    }
+    const { hits: projectedHits, projection: effectiveProjection } = attachSearchHighlights(prepared, corpus.filteredDocuments, page.limited);
+    const projectedItems = projectSearchHits(projectedHits, effectiveProjection);
+    return buildSearchResultForHits(response, projectedItems, total, page.limited.length, effectiveProjection, page.pageExtras);
+}
+//# sourceMappingURL=search.js.map
+//# debugId=7d6721eb-1e28-58ea-a5fc-4494f249275c