@unbrained/pm-cli 2026.10.12 → 2026.10.14

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

@@ -8,82 +8,82 @@ import { type SearchOptions } from "../search-contracts.js";
 import { type SearchMode } from "../search-rendering.js";
 import type { SearchHit } from "./types.js";
 interface ExtensionSearchProviderContext {
-    query: string;
-    mode: SearchMode;
-    tokens: string[];
-    options: SearchOptions;
-    settings: PmSettings;
-    documents: ItemDocument[];
+query: string;
+mode: SearchMode;
+tokens: string[];
+options: SearchOptions;
+settings: PmSettings;
+documents: ItemDocument[];
 }
 interface ExtensionSearchProviderHit {
-    id: string;
-    score: number;
-    matched_fields?: string[];
+id: string;
+score: number;
+matched_fields?: string[];
 }
 type ExtensionSearchProviderQuery = (context: ExtensionSearchProviderContext) => Promise<ExtensionSearchProviderHit[] | {
-    hits?: ExtensionSearchProviderHit[];
+hits?: ExtensionSearchProviderHit[];
 }> | ExtensionSearchProviderHit[] | {
-    hits?: ExtensionSearchProviderHit[];
+hits?: ExtensionSearchProviderHit[];
 };
 interface ExtensionSearchProviderQueryExpansionContext {
-    query: string;
-    mode: Exclude<SearchMode, "keyword">;
-    settings: PmSettings;
+query: string;
+mode: Exclude<SearchMode, "keyword">;
+settings: PmSettings;
 }
 /** Optional provider hook used to expand a query before semantic retrieval. */
 type ExtensionSearchProviderQueryExpansion = (context: ExtensionSearchProviderQueryExpansionContext) => Promise<string[] | {
-    queries?: string[];
+queries?: string[];
 }> | string[] | {
-    queries?: string[];
+queries?: string[];
 };
 interface ExtensionSearchProviderRerankCandidate {
-    id: string;
-    text: string;
-    score: number;
+id: string;
+text: string;
+score: number;
 }
 interface ExtensionSearchProviderRerankContext {
-    query: string;
-    mode: "hybrid";
-    model: string;
-    top_k: number;
-    settings: PmSettings;
-    candidates: ExtensionSearchProviderRerankCandidate[];
+query: string;
+mode: "hybrid";
+model: string;
+top_k: number;
+settings: PmSettings;
+candidates: ExtensionSearchProviderRerankCandidate[];
 }
 /** Optional provider hook used to rerank retrieved candidates. */
 type ExtensionSearchProviderRerank = (context: ExtensionSearchProviderRerankContext) => Promise<Array<{
-    id?: unknown;
-    score?: unknown;
+id?: unknown;
+score?: unknown;
 }> | {
-    hits?: Array<{
-        id?: unknown;
-        score?: unknown;
-    }>;
+hits?: Array<{
+id?: unknown;
+score?: unknown;
+}>;
 }> | Array<{
-    id?: unknown;
-    score?: unknown;
+id?: unknown;
+score?: unknown;
 }> | {
-    hits?: Array<{
-        id?: unknown;
-        score?: unknown;
-    }>;
+hits?: Array<{
+id?: unknown;
+score?: unknown;
+}>;
 };
 type ExtensionVectorQuery = (context: {
-    vector: number[];
-    limit: number;
-    settings: PmSettings;
+vector: number[];
+limit: number;
+settings: PmSettings;
 }) => Promise<VectorQueryHit[]> | VectorQueryHit[];
 type ExtensionVectorUpsert = (context: {
-    points: Array<{
-        id: string;
-        vector: number[];
-        payload: Record<string, unknown>;
-    }>;
-    settings: PmSettings;
+points: Array<{
+id: string;
+vector: number[];
+payload: Record<string, unknown>;
+}>;
+settings: PmSettings;
 }) => Promise<void> | void;
 type ExtensionVectorAdapter = {
-    adapterName: string;
-    query?: ExtensionVectorQuery;
-    upsert?: ExtensionVectorUpsert;
+adapterName: string;
+query?: ExtensionVectorQuery;
+upsert?: ExtensionVectorUpsert;
 };
 type ImplicitSemanticFallbackReason = "timeout" | "connection" | "error";
 /**
@@ -105,15 +105,15 @@ export declare function classifyImplicitSemanticFallbackReason(error: unknown):
 /** Describe why an explicitly requested semantic mode fell back to keyword retrieval. */
 declare function buildExplicitSemanticFallbackWarning(requestedMode: SearchMode, error: unknown): string;
 interface VectorIndexRecoveryRegistrations {
-    commands?: readonly {
-        command: string;
-    }[];
+commands?: readonly {
+command: string;
+}[];
 }
 interface VectorIndexRecovery {
-    command: string;
-    args: string[];
-    follow_up_command?: string;
-    follow_up_args?: string[];
+command: string;
+args: string[];
+follow_up_command?: string;
+follow_up_args?: string[];
 }
 /** Resolve an executable reindex path from the active extension capability surface. */
 export declare function resolveVectorIndexRecovery(registrations: VectorIndexRecoveryRegistrations | null): VectorIndexRecovery;
@@ -123,23 +123,23 @@ declare function maybeEmitVectorIndexStaleWarning(pmRoot: string, filteredDocume
 export declare function formatVectorIndexRecoveryWarnings(staleCount: number, recovery: VectorIndexRecovery): string[];
 /** Resolve the configured semantic provider and vector-store dependencies or report their absence. */
 declare function requireSemanticDependencies(requestedMode: Exclude<SearchMode, "keyword">, providerResolution: EmbeddingProviderResolution, vectorResolution: VectorStoreResolution, hasExtensionVectorQuery: boolean): {
-    provider: EmbeddingProviderConfig;
-    vectorStore: VectorStoreConfig | null;
+provider: EmbeddingProviderConfig;
+vectorStore: VectorStoreConfig | null;
 };
 /** Normalize optional provider identifiers to trimmed non-empty strings. */
 declare const toOptionalNonEmptyString: typeof toNonEmptyStringOrUndefined;
 interface ExtensionSearchProviderHooks {
-    providerName: string;
-    query?: ExtensionSearchProviderQuery;
-    queryExpansion?: ExtensionSearchProviderQueryExpansion;
-    rerank?: ExtensionSearchProviderRerank;
+providerName: string;
+query?: ExtensionSearchProviderQuery;
+queryExpansion?: ExtensionSearchProviderQueryExpansion;
+rerank?: ExtensionSearchProviderRerank;
 }
 /** Find an active extension search provider by its declared name. */
 declare function resolveExtensionSearchProviderByName(providerName: string | undefined): ExtensionSearchProviderHooks | null;
 /** Resolve the configured extension-owned search provider. */
 declare function resolveExtensionSearchProvider(settings: PmSettings): {
-    providerName: string;
-    query: ExtensionSearchProviderQuery;
+providerName: string;
+query: ExtensionSearchProviderQuery;
 } | null;
 /** Resolve the configured extension-owned vector-store adapter. */
 declare function resolveExtensionVectorAdapter(settings: PmSettings): ExtensionVectorAdapter | null;
@@ -147,8 +147,8 @@ declare function resolveExtensionVectorAdapter(settings: PmSettings): ExtensionV
 declare function normalizeExtensionProviderHits(providerName: string, raw: unknown, filteredById: Map<string, ItemDocument>): SearchHit[];
 /** Join semantic scores to the filtered item corpus. */
 declare function buildSemanticHits(vectorHits: VectorQueryHit[], filteredById: Map<string, ItemDocument>): {
-    semanticHits: SearchHit[];
-    semanticScores: Map<string, number>;
+semanticHits: SearchHit[];
+semanticScores: Map<string, number>;
 };
 /** Blend lexical and semantic results while preserving exact-ID precedence. */
 declare function combineHybridHits(filteredById: Map<string, ItemDocument>, semanticScores: Map<string, number>, keywordHits: SearchHit[], hybridSemanticWeight: number, semanticFieldLabel?: string): SearchHit[];
@@ -156,9 +156,9 @@ declare function combineHybridHits(filteredById: Map<string, ItemDocument>, sema
 type BuiltInBm25Mode = "explicit" | "auto-fallback";
 /** Select the built-in BM25 path from effective search settings. */
 declare function resolveBuiltInBm25Mode(params: {
-    configuredProvider: string | undefined;
-    hasEmbeddingProvider: boolean;
-    hasExtensionSearchProvider: boolean;
+configuredProvider: string | undefined;
+hasEmbeddingProvider: boolean;
+hasExtensionSearchProvider: boolean;
 }): BuiltInBm25Mode | null;
 /**
  * Rank the filtered corpus with the offline BM25 provider (pm-75k9). Builds a
@@ -172,43 +172,43 @@ declare function resolveBuiltInBm25Mode(params: {
  * is involved, so this path cannot fail on a backend error.
  */
 declare function computeBuiltInBm25Hits(params: {
-    requestedMode: Exclude<SearchMode, "keyword">;
-    query: string;
-    filteredDocuments: ItemDocument[];
-    keywordHits: SearchHit[];
-    corpusFields: string[];
-    bm25Params: Bm25Params;
-    hybridSemanticWeight: number;
+requestedMode: Exclude<SearchMode, "keyword">;
+query: string;
+filteredDocuments: ItemDocument[];
+keywordHits: SearchHit[];
+corpusFields: string[];
+bm25Params: Bm25Params;
+hybridSemanticWeight: number;
 }): SearchHit[];
 interface SemanticQueryContext {
-    requestedMode: Exclude<SearchMode, "keyword">;
-    query: string;
-    filteredDocuments: ItemDocument[];
-    keywordHits: SearchHit[];
-    hybridSemanticWeight: number;
-    limit: number | undefined;
-    maxResults: number;
-    provider: EmbeddingProviderConfig;
-    vectorStore: VectorStoreConfig | null;
-    extensionVectorAdapter: ExtensionVectorAdapter | null;
-    queryExpansion: QueryExpansionConfig;
-    queryExpansionExtension: {
-        providerName: string;
-        expand: ExtensionSearchProviderQueryExpansion;
-    } | null;
-    rerank: RerankConfig;
-    rerankExtension: {
-        providerName: string;
-        rerank: ExtensionSearchProviderRerank;
-    } | null;
-    warnings: string[];
-    settings: PmSettings;
-    embeddingTimeoutMs?: number;
-    vectorQueryTimeoutMs?: number;
+requestedMode: Exclude<SearchMode, "keyword">;
+query: string;
+filteredDocuments: ItemDocument[];
+keywordHits: SearchHit[];
+hybridSemanticWeight: number;
+limit: number | undefined;
+maxResults: number;
+provider: EmbeddingProviderConfig;
+vectorStore: VectorStoreConfig | null;
+extensionVectorAdapter: ExtensionVectorAdapter | null;
+queryExpansion: QueryExpansionConfig;
+queryExpansionExtension: {
+providerName: string;
+expand: ExtensionSearchProviderQueryExpansion;
+} | null;
+rerank: RerankConfig;
+rerankExtension: {
+providerName: string;
+rerank: ExtensionSearchProviderRerank;
+} | null;
+warnings: string[];
+settings: PmSettings;
+embeddingTimeoutMs?: number;
+vectorQueryTimeoutMs?: number;
 }
 interface SemanticQueryResult {
-    hits: SearchHit[];
-    vectorMatchCount: number;
+hits: SearchHit[];
+vectorMatchCount: number;
 }
 /** Merge vector retrieval batches by item ID for query expansion. */
 declare function mergeVectorHitsById(vectorHitGroups: VectorQueryHit[][]): VectorQueryHit[];
@@ -218,12 +218,12 @@ declare function buildRerankCorpus(document: ItemDocument): string;
 declare function computeSemanticOrHybridHits(context: SemanticQueryContext): Promise<SemanticQueryResult>;
 /** Resolve the active provider implementation for configured query expansion. */
 declare function resolveQueryExpansionExtension(queryExpansion: QueryExpansionConfig): {
-    providerName: string;
-    expand: ExtensionSearchProviderQueryExpansion;
+providerName: string;
+expand: ExtensionSearchProviderQueryExpansion;
 } | null;
 /** Resolve the active provider implementation for configured reranking. */
 declare function resolveRerankExtension(settings: PmSettings): {
-    providerName: string;
-    rerank: ExtensionSearchProviderRerank;
+providerName: string;
+rerank: ExtensionSearchProviderRerank;
 } | null;
 export { buildExplicitSemanticFallbackWarning, buildRerankCorpus, buildSemanticHits, BuiltInBm25Mode, combineHybridHits, computeBuiltInBm25Hits, computeSemanticOrHybridHits, ExtensionSearchProviderQueryExpansion, ExtensionSearchProviderRerank, maybeEmitVectorIndexStaleWarning, mergeVectorHitsById, normalizeExtensionProviderHits, requireSemanticDependencies, resolveBuiltInBm25Mode, resolveExtensionSearchProvider, resolveExtensionSearchProviderByName, resolveExtensionVectorAdapter, resolveQueryExpansionExtension, resolveRerankExtension, toOptionalNonEmptyString };

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

@@ -9,18 +9,18 @@ import { type SearchMatchMode, type SearchModeSource, type SearchOptions, type S
 import { type SearchMode } from "../search-rendering.js";
 /** Documents the search hit payload exchanged by command, SDK, and package integrations. */
 export interface SearchHit {
-    /** Value that configures or reports item for this contract. */
-    item: ItemMetadata;
-    /** Value that configures or reports score for this contract. */
-    score: number;
-    /** Value that configures or reports matched fields for this contract. */
-    matched_fields: string[];
-    /** Value that configures or reports matched all terms for this contract. */
-    matched_all_terms?: boolean;
-    /** Value that configures or reports exact id match for this contract. */
-    exact_id_match?: boolean;
-    /** Value that configures or reports highlights for this contract. */
-    highlights?: SearchHitHighlight[];
+/** Value that configures or reports item for this contract. */
+item: ItemMetadata;
+/** Value that configures or reports score for this contract. */
+score: number;
+/** Value that configures or reports matched fields for this contract. */
+matched_fields: string[];
+/** Value that configures or reports matched all terms for this contract. */
+matched_all_terms?: boolean;
+/** Value that configures or reports exact id match for this contract. */
+exact_id_match?: boolean;
+/** Value that configures or reports highlights for this contract. */
+highlights?: SearchHitHighlight[];
 }
 /**
  * Pairs a matched field name with a snippet of its text where every matching
@@ -28,96 +28,96 @@ export interface SearchHit {
  * markers. Emitted on {@link SearchHit.highlights} when `--highlight` is set.
  */
 export interface SearchHitHighlight {
-    /** Value that configures or reports field for this contract. */
-    field: string;
-    /** Value that configures or reports snippet for this contract. */
-    snippet: string;
+/** Value that configures or reports field for this contract. */
+field: string;
+/** Value that configures or reports snippet for this contract. */
+snippet: string;
 }
 /** Restricts search result item values accepted by command, SDK, and storage contracts. */
 export type SearchResultItem = SearchHit | Record<string, unknown>;
 interface SearchResultBase {
-    query: string;
-    mode: SearchMode;
-    /** Which layer chose `mode` before any runtime fallback: the caller, `search.default_mode`, or the workspace-state default. */
-    mode_source?: SearchModeSource;
-    items: SearchResultItem[];
-    count: number;
-    total?: number;
-    /** Whether additional ranked hits remain after this page. */
-    has_more?: boolean;
-    /** Opaque continuation cursor when additional hits remain. */
-    next_cursor?: string;
-    /** Effective page size for this response. */
-    applied_limit?: number;
-    /** Explicit marker that the response is a bounded page. */
-    truncated?: true;
-    count_only?: boolean;
-    warnings?: string[];
-    /** Historical epoch and epic rollups matching the query in large workspaces. */
-    workspace_memory?: {
-        /** Persistence freshness for the derived projection. */
-        cache_status: "fresh" | "rebuilt";
-        /** Matching bounded rollups, ordered by term coverage and recency. */
-        matches: WorkspaceMemoryRollup[];
-    };
+query: string;
+mode: SearchMode;
+/** Which layer chose `mode` before any runtime fallback: the caller, `search.default_mode`, or the workspace-state default. */
+mode_source?: SearchModeSource;
+items: SearchResultItem[];
+count: number;
+total?: number;
+/** Whether additional ranked hits remain after this page. */
+has_more?: boolean;
+/** Opaque continuation cursor when additional hits remain. */
+next_cursor?: string;
+/** Effective page size for this response. */
+applied_limit?: number;
+/** Explicit marker that the response is a bounded page. */
+truncated?: true;
+count_only?: boolean;
+warnings?: string[];
+/** Historical epoch and epic rollups matching the query in large workspaces. */
+workspace_memory?: {
+/** Persistence freshness for the derived projection. */
+cache_status: "fresh" | "rebuilt";
+/** Matching bounded rollups, ordered by term coverage and recency. */
+matches: WorkspaceMemoryRollup[];
+};
 }
 /** Documents the search compact result payload exchanged by command, SDK, and package integrations. */
 export interface SearchCompactResult extends SearchResultBase {
-    /** Value that configures or reports filters for this contract. */
-    filters: Record<string, unknown>;
-    /** Value that configures or reports projection for this contract. */
-    projection?: undefined;
-    /** Value that configures or reports now for this contract. */
-    now?: undefined;
+/** Value that configures or reports filters for this contract. */
+filters: Record<string, unknown>;
+/** Value that configures or reports projection for this contract. */
+projection?: undefined;
+/** Value that configures or reports now for this contract. */
+now?: undefined;
 }
 /** Documents the search verbose result payload exchanged by command, SDK, and package integrations. */
 export interface SearchVerboseResult extends SearchResultBase {
-    /** Value that configures or reports filters for this contract. */
-    filters: Record<string, unknown>;
-    /** Value that configures or reports projection for this contract. */
-    projection: {
-        mode: SearchProjectionMode;
-        fields: string[] | null;
-    };
-    /** Value that configures or reports now for this contract. */
-    now: string;
+/** Value that configures or reports filters for this contract. */
+filters: Record<string, unknown>;
+/** Value that configures or reports projection for this contract. */
+projection: {
+mode: SearchProjectionMode;
+fields: string[] | null;
+};
+/** Value that configures or reports now for this contract. */
+now: string;
 }
 /** Restricts search result values accepted by command, SDK, and storage contracts. */
 export type SearchResult = SearchCompactResult | SearchVerboseResult;
 /** Validated search input shared by corpus selection, retrieval and result construction. */
 interface PreparedSearchInput {
-    query: string;
-    options: SearchOptions;
-    inlineWarnings: string[];
-    highlight: boolean;
-    includeLinked: boolean;
-    titleExact: boolean;
-    phraseExact: boolean;
-    matchMode: SearchMatchMode;
-    minScoreOverride: number | undefined;
-    countOnly: boolean;
-    tokens: string[];
-    normalizedQuery: string;
-    limit: number | undefined;
-    projection: SearchProjectionConfig;
-    modeWasExplicit: boolean;
+query: string;
+options: SearchOptions;
+inlineWarnings: string[];
+highlight: boolean;
+includeLinked: boolean;
+titleExact: boolean;
+phraseExact: boolean;
+matchMode: SearchMatchMode;
+minScoreOverride: number | undefined;
+countOnly: boolean;
+tokens: string[];
+normalizedQuery: string;
+limit: number | undefined;
+projection: SearchProjectionConfig;
+modeWasExplicit: boolean;
 }
 /** Resolved query settings and evidence retained while shaping the final response. */
 interface SearchResponseContext {
-    query: string;
-    effectiveMode: SearchMode;
-    modeSource: SearchModeSource;
-    matchMode: SearchMatchMode;
-    options: SearchOptions;
-    includeLinked: boolean;
-    titleExact: boolean;
-    phraseExact: boolean;
-    scoreThreshold: number;
-    hybridSemanticWeight: number;
-    queryExpansion: QueryExpansionConfig;
-    rerank: RerankConfig;
-    projection: SearchProjectionConfig;
-    warnings: string[];
-    runtimeFieldFilters: Record<string, unknown>;
+query: string;
+effectiveMode: SearchMode;
+modeSource: SearchModeSource;
+matchMode: SearchMatchMode;
+options: SearchOptions;
+includeLinked: boolean;
+titleExact: boolean;
+phraseExact: boolean;
+scoreThreshold: number;
+hybridSemanticWeight: number;
+queryExpansion: QueryExpansionConfig;
+rerank: RerankConfig;
+projection: SearchProjectionConfig;
+warnings: string[];
+runtimeFieldFilters: Record<string, unknown>;
 }
 export { PreparedSearchInput, SearchResponseContext };