@memberjunction/search-engine 5.32.0 → 5.34.0

package/dist/generic/BaseReRanker.d.ts

@@ -0,0 +1,164 @@
+/**
+ * @fileoverview Optional re-ranker primitive for scope search.
+ *
+ * A re-ranker runs AFTER per-scope RRF and cross-scope RRF and BEFORE deduplication.
+ * It takes a fused candidate list plus the original query and produces a more accurate
+ * final ordering — typically via a cross-encoder LLM call (Cohere Rerank, BGE Reranker,
+ * Voyage Rerank). Implementations are registered via `@RegisterClass(BaseReRanker, 'DriverClassName')`
+ * and selected per-scope via `SearchScope.ScopeConfig.reRanker.driverClass`.
+ *
+ * This class is a thin adapter over `@memberjunction/ai`'s `BaseReranker`. Subclasses
+ * that wrap a real provider (Cohere, BGE, Voyage) return an AI-layer reranker from
+ * `getAIReranker()` and inherit the AI layer's validation, timing, and error shape.
+ * The default `ReRank()` handles the conversion between `SearchResultItem[]` and the
+ * AI layer's `RerankDocument[]` / `RerankResult[]` so subclasses don't have to.
+ *
+ * Subclasses that don't need the AI layer (e.g. `NoopReRanker`) can override `ReRank()`
+ * directly.
+ *
+ * See Section 8.3 of plans/search-scopes-rag-plus.md.
+ *
+ * @module @memberjunction/search-engine
+ */
+import { UserInfo } from '@memberjunction/core';
+import { BaseReranker as AIBaseReranker } from '@memberjunction/ai';
+import { SearchResultItem } from './search.types.js';
+/**
+ * Lightweight catalog entry for a registered reranker, returned by
+ * `BaseReRanker.GetAvailableRerankers()`. Designed for UI dropdown population on
+ * the SearchScope form (P2D.7) — a single call gives the form everything it
+ * needs to render selectable options without separately instantiating each
+ * registered class.
+ */
+export interface RegisteredReRankerInfo {
+    /** ClassFactory registration key — what goes into ScopeConfig.reRanker.driverClass */
+    DriverClass: string;
+    /** Human-friendly label for UI display (BaseReRanker.Name) */
+    Name: string;
+    /** Reranker version (BaseReRanker.Version) */
+    Version: string;
+    /** Whether this reranker incurs API cost (true) or runs free locally (false) */
+    HasCost: boolean;
+}
+/**
+ * Abstract primitive for a search re-ranker. Provides a default implementation of
+ * `ReRank()` that delegates to an AI-layer `BaseReranker` returned by
+ * `getAIReranker()`. When `getAIReranker()` returns null (the base default), the
+ * candidates are sliced to `topN` and returned unchanged.
+ *
+ * The `NoopReRanker` default implementation (in `NoopReRanker.ts`) returns candidates
+ * unchanged and serves as the wiring verification point — the SearchEngine's re-rank
+ * stage always resolves a concrete class, even when no real re-ranker is configured.
+ */
+/**
+ * Optional per-call cost-reporting callback. Real-provider rerankers (Cohere, Voyage,
+ * OpenAI) invoke this with the actual cents charged for a single Rerank call so the
+ * SearchEngine / scope-level budget guard can accumulate spend and short-circuit
+ * runaway agents. NoopReRanker and BGE (local) report 0.
+ */
+export type ReRankerCostReporter = (cents: number) => void;
+export declare abstract class BaseReRanker {
+    /**
+     * The `DriverClass` key used by `@RegisterClass(BaseReRanker, 'DriverClassName')` so
+     * the SearchEngine can resolve this subclass via `ClassFactory` from the scope's
+     * `ScopeConfig.reRanker.driverClass` value.
+     */
+    abstract get DriverClass(): string;
+    /**
+     * Human-friendly display name. Defaults to `DriverClass` so subclasses don't have to
+     * override unless they want a different label in UI dropdowns / cost reports.
+     */
+    get Name(): string;
+    /**
+     * Reranker semantic version (independent of the package version). Bump this on a
+     * subclass when the prompt, scoring formula, or upstream model identifier changes
+     * in a way that invalidates cached scores. Defaults to `'1'`.
+     */
+    get Version(): string;
+    /**
+     * Maximum number of candidates a single Rerank call can score. Real providers cap
+     * this (Cohere: 1000, Voyage: 1000, OpenAI: varies). The SearchEngine should respect
+     * this cap by chunking large candidate lists. Defaults to `Number.MAX_SAFE_INTEGER`
+     * (no cap) — subclasses should override.
+     */
+    GetMaxResultCount(): number;
+    /**
+     * Pre-call cost estimate in cents for reranking the given candidate count. Used by
+     * the budget guard to short-circuit BEFORE making the call when the projected cost
+     * exceeds `SearchScope.RerankerBudgetCents`.
+     *
+     * Default: 0 (free / local). Real-provider subclasses override based on their pricing.
+     *
+     * @param resultCount - The number of candidates to be reranked.
+     * @returns Estimated cost in cents (whole + fractional, e.g. `0.25` for ¼¢).
+     */
+    EstimateCostCents(resultCount: number): number;
+    /**
+     * Optional cost reporter. When set, the reranker invokes it after each successful
+     * Rerank call with the actual cents charged. The SearchEngine wires this from the
+     * `RerankerBudgetGuard` to the scope-level spend tracker — see Phase 2D.6.
+     */
+    CostReporter: ReRankerCostReporter | null;
+    /**
+     * Helper for subclasses: report a cost AND record it on the optional callback. Always
+     * safe to call even when no callback is set.
+     */
+    protected reportCost(cents: number): void;
+    /**
+     * Enumerate every reranker currently registered with ClassFactory under
+     * `BaseReRanker`. Designed for the SearchScope form's reranker dropdown (P2D.7) —
+     * the form populates the dropdown from this single call rather than hardcoding
+     * a list, so any ClassFactory-registered reranker (including third-party ones
+     * published as separate packages) shows up automatically.
+     *
+     * Each entry includes the driver-class registration key, the friendly Name,
+     * Version, and a `HasCost` flag (true when EstimateCostCents(1) > 0). Sorted
+     * by Name for stable UI ordering.
+     */
+    static GetAvailableRerankers(): RegisteredReRankerInfo[];
+    /**
+     * Score and re-order candidates against the query.
+     *
+     * Default implementation:
+     * 1. Returns empty when `topN <= 0` or `candidates` is empty.
+     * 2. Resolves an AI-layer reranker via `getAIReranker()`. If none, slices to `topN`.
+     * 3. Maps `SearchResultItem[]` to `RerankDocument[]` (preserving each original item
+     *    in `metadata.__mjSearchItem`).
+     * 4. Calls the AI reranker's `Rerank()` — inherits validation, timing, error handling.
+     * 5. On success, maps the `RerankResult[]` back to `SearchResultItem[]`, replacing
+     *    `Score` with `relevanceScore` and augmenting `ScoreBreakdown` with a `ReRank` key.
+     * 6. On failure, logs and falls back to the unchanged top-N slice.
+     *
+     * Subclasses that bypass the AI layer (e.g. `NoopReRanker`) may override this method.
+     *
+     * @param query - The original query text.
+     * @param candidates - The fused candidate list (post-RRF, pre-dedup).
+     * @param topN - Maximum number of candidates to return after re-ranking.
+     * @param contextUser - The calling user (for auth / tenant propagation).
+     * @param config - Optional provider-specific config from `ScopeConfig.reRanker.config`.
+     */
+    ReRank(query: string, candidates: SearchResultItem[], topN: number, contextUser: UserInfo, config?: Record<string, unknown>): Promise<SearchResultItem[]>;
+    /**
+     * Return the underlying `@memberjunction/ai` `BaseReranker` instance to use.
+     *
+     * Provider-specific subclasses (Cohere, BGE, Voyage) override this to return a
+     * configured AI reranker. Returning `null` (the default) tells `ReRank()` to
+     * skip the AI layer and fall back to a simple top-N slice — useful for Noop
+     * and test implementations.
+     *
+     * @param _config - Provider-specific config from `ScopeConfig.reRanker.config`.
+     * @param _contextUser - The calling user (for auth / tenant propagation).
+     */
+    protected getAIReranker(_config: Record<string, unknown> | undefined, _contextUser: UserInfo): AIBaseReranker | null;
+    /**
+     * Build the text representation of a `SearchResultItem` for the rerank model.
+     * Default concatenates `Title` and `Snippet` separated by newline. Override to
+     * customize (e.g. include tags or entity context).
+     */
+    protected buildRerankText(item: SearchResultItem): string;
+    /** Convert the search result candidates into the AI layer's document shape. */
+    private toRerankDocuments;
+    /** Recover the original `SearchResultItem` and attach the rerank score. */
+    private fromRerankResult;
+}
+//# sourceMappingURL=BaseReRanker.d.ts.map

package/dist/generic/BaseReRanker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseReRanker.d.ts","sourceRoot":"","sources":["../../src/generic/BaseReRanker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAY,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAE1D,OAAO,EAAE,YAAY,IAAI,cAAc,EAAgC,MAAM,oBAAoB,CAAC;AAClG,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAElD;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACnC,sFAAsF;IACtF,WAAW,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,OAAO,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;AAE3D,8BAAsB,YAAY;IAC9B;;;;OAIG;IACH,aAAoB,WAAW,IAAI,MAAM,CAAC;IAE1C;;;OAGG;IACH,IAAW,IAAI,IAAI,MAAM,CAExB;IAED;;;;OAIG;IACH,IAAW,OAAO,IAAI,MAAM,CAE3B;IAED;;;;;OAKG;IACI,iBAAiB,IAAI,MAAM;IAIlC;;;;;;;;;OASG;IACI,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM;IAKrD;;;;OAIG;IACI,YAAY,EAAE,oBAAoB,GAAG,IAAI,CAAQ;IAExD;;;OAGG;IACH,SAAS,CAAC,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAMzC;;;;;;;;;;OAUG;WACW,qBAAqB,IAAI,sBAAsB,EAAE;IA6B/D;;;;;;;;;;;;;;;;;;;;OAoBG;IACU,MAAM,CACf,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,gBAAgB,EAAE,EAC9B,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,QAAQ,EACrB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,OAAO,CAAC,gBAAgB,EAAE,CAAC;IA4B9B;;;;;;;;;;OAUG;IACH,SAAS,CAAC,aAAa,CACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC5C,YAAY,EAAE,QAAQ,GACvB,cAAc,GAAG,IAAI;IAIxB;;;;OAIG;IACH,SAAS,CAAC,eAAe,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM;IAKzD,+EAA+E;IAC/E,OAAO,CAAC,iBAAiB;IASzB,2EAA2E;IAC3E,OAAO,CAAC,gBAAgB;CAc3B"}

package/dist/generic/BaseReRanker.js

@@ -0,0 +1,209 @@
+/**
+ * @fileoverview Optional re-ranker primitive for scope search.
+ *
+ * A re-ranker runs AFTER per-scope RRF and cross-scope RRF and BEFORE deduplication.
+ * It takes a fused candidate list plus the original query and produces a more accurate
+ * final ordering — typically via a cross-encoder LLM call (Cohere Rerank, BGE Reranker,
+ * Voyage Rerank). Implementations are registered via `@RegisterClass(BaseReRanker, 'DriverClassName')`
+ * and selected per-scope via `SearchScope.ScopeConfig.reRanker.driverClass`.
+ *
+ * This class is a thin adapter over `@memberjunction/ai`'s `BaseReranker`. Subclasses
+ * that wrap a real provider (Cohere, BGE, Voyage) return an AI-layer reranker from
+ * `getAIReranker()` and inherit the AI layer's validation, timing, and error shape.
+ * The default `ReRank()` handles the conversion between `SearchResultItem[]` and the
+ * AI layer's `RerankDocument[]` / `RerankResult[]` so subclasses don't have to.
+ *
+ * Subclasses that don't need the AI layer (e.g. `NoopReRanker`) can override `ReRank()`
+ * directly.
+ *
+ * See Section 8.3 of plans/search-scopes-rag-plus.md.
+ *
+ * @module @memberjunction/search-engine
+ */
+import { LogError } from '@memberjunction/core';
+import { MJGlobal } from '@memberjunction/global';
+export class BaseReRanker {
+    constructor() {
+        /**
+         * Optional cost reporter. When set, the reranker invokes it after each successful
+         * Rerank call with the actual cents charged. The SearchEngine wires this from the
+         * `RerankerBudgetGuard` to the scope-level spend tracker — see Phase 2D.6.
+         */
+        this.CostReporter = null;
+    }
+    /**
+     * Human-friendly display name. Defaults to `DriverClass` so subclasses don't have to
+     * override unless they want a different label in UI dropdowns / cost reports.
+     */
+    get Name() {
+        return this.DriverClass;
+    }
+    /**
+     * Reranker semantic version (independent of the package version). Bump this on a
+     * subclass when the prompt, scoring formula, or upstream model identifier changes
+     * in a way that invalidates cached scores. Defaults to `'1'`.
+     */
+    get Version() {
+        return '1';
+    }
+    /**
+     * Maximum number of candidates a single Rerank call can score. Real providers cap
+     * this (Cohere: 1000, Voyage: 1000, OpenAI: varies). The SearchEngine should respect
+     * this cap by chunking large candidate lists. Defaults to `Number.MAX_SAFE_INTEGER`
+     * (no cap) — subclasses should override.
+     */
+    GetMaxResultCount() {
+        return Number.MAX_SAFE_INTEGER;
+    }
+    /**
+     * Pre-call cost estimate in cents for reranking the given candidate count. Used by
+     * the budget guard to short-circuit BEFORE making the call when the projected cost
+     * exceeds `SearchScope.RerankerBudgetCents`.
+     *
+     * Default: 0 (free / local). Real-provider subclasses override based on their pricing.
+     *
+     * @param resultCount - The number of candidates to be reranked.
+     * @returns Estimated cost in cents (whole + fractional, e.g. `0.25` for ¼¢).
+     */
+    EstimateCostCents(resultCount) {
+        void resultCount;
+        return 0;
+    }
+    /**
+     * Helper for subclasses: report a cost AND record it on the optional callback. Always
+     * safe to call even when no callback is set.
+     */
+    reportCost(cents) {
+        if (cents > 0 && this.CostReporter) {
+            this.CostReporter(cents);
+        }
+    }
+    /**
+     * Enumerate every reranker currently registered with ClassFactory under
+     * `BaseReRanker`. Designed for the SearchScope form's reranker dropdown (P2D.7) —
+     * the form populates the dropdown from this single call rather than hardcoding
+     * a list, so any ClassFactory-registered reranker (including third-party ones
+     * published as separate packages) shows up automatically.
+     *
+     * Each entry includes the driver-class registration key, the friendly Name,
+     * Version, and a `HasCost` flag (true when EstimateCostCents(1) > 0). Sorted
+     * by Name for stable UI ordering.
+     */
+    static GetAvailableRerankers() {
+        const registrations = MJGlobal.Instance.ClassFactory.GetAllRegistrations(BaseReRanker);
+        const seen = new Set();
+        const out = [];
+        for (const reg of registrations) {
+            const key = reg.Key;
+            if (!key || seen.has(key))
+                continue;
+            seen.add(key);
+            try {
+                const Ctor = reg.SubClass;
+                const instance = new Ctor();
+                out.push({
+                    DriverClass: key,
+                    Name: instance.Name,
+                    Version: instance.Version,
+                    HasCost: instance.EstimateCostCents(1) > 0,
+                });
+            }
+            catch (err) {
+                // Some rerankers may require args we can't supply at enumeration time.
+                // Fall back to the registration key alone — the UI still gets an
+                // option, it just lacks the friendly label.
+                LogError(`BaseReRanker.GetAvailableRerankers: could not introspect "${key}" — ${err instanceof Error ? err.message : String(err)}`);
+                out.push({ DriverClass: key, Name: key, Version: '?', HasCost: false });
+            }
+        }
+        out.sort((a, b) => a.Name.localeCompare(b.Name));
+        return out;
+    }
+    /**
+     * Score and re-order candidates against the query.
+     *
+     * Default implementation:
+     * 1. Returns empty when `topN <= 0` or `candidates` is empty.
+     * 2. Resolves an AI-layer reranker via `getAIReranker()`. If none, slices to `topN`.
+     * 3. Maps `SearchResultItem[]` to `RerankDocument[]` (preserving each original item
+     *    in `metadata.__mjSearchItem`).
+     * 4. Calls the AI reranker's `Rerank()` — inherits validation, timing, error handling.
+     * 5. On success, maps the `RerankResult[]` back to `SearchResultItem[]`, replacing
+     *    `Score` with `relevanceScore` and augmenting `ScoreBreakdown` with a `ReRank` key.
+     * 6. On failure, logs and falls back to the unchanged top-N slice.
+     *
+     * Subclasses that bypass the AI layer (e.g. `NoopReRanker`) may override this method.
+     *
+     * @param query - The original query text.
+     * @param candidates - The fused candidate list (post-RRF, pre-dedup).
+     * @param topN - Maximum number of candidates to return after re-ranking.
+     * @param contextUser - The calling user (for auth / tenant propagation).
+     * @param config - Optional provider-specific config from `ScopeConfig.reRanker.config`.
+     */
+    async ReRank(query, candidates, topN, contextUser, config) {
+        if (topN <= 0 || candidates.length === 0)
+            return [];
+        const aiReranker = this.getAIReranker(config, contextUser);
+        if (!aiReranker) {
+            return candidates.slice(0, topN);
+        }
+        const documents = this.toRerankDocuments(candidates);
+        const response = await aiReranker.Rerank({
+            query,
+            documents,
+            topK: topN,
+            options: config,
+        });
+        if (!response.success) {
+            LogError(`SearchEngine: AI reranker "${this.DriverClass}" failed (${response.durationMs}ms): ${response.errorMessage ?? 'unknown error'}`);
+            return candidates.slice(0, topN);
+        }
+        return response.results.map(r => this.fromRerankResult(r));
+    }
+    /**
+     * Return the underlying `@memberjunction/ai` `BaseReranker` instance to use.
+     *
+     * Provider-specific subclasses (Cohere, BGE, Voyage) override this to return a
+     * configured AI reranker. Returning `null` (the default) tells `ReRank()` to
+     * skip the AI layer and fall back to a simple top-N slice — useful for Noop
+     * and test implementations.
+     *
+     * @param _config - Provider-specific config from `ScopeConfig.reRanker.config`.
+     * @param _contextUser - The calling user (for auth / tenant propagation).
+     */
+    getAIReranker(_config, _contextUser) {
+        return null;
+    }
+    /**
+     * Build the text representation of a `SearchResultItem` for the rerank model.
+     * Default concatenates `Title` and `Snippet` separated by newline. Override to
+     * customize (e.g. include tags or entity context).
+     */
+    buildRerankText(item) {
+        const parts = [item.Title, item.Snippet].filter(p => p != null && p.length > 0);
+        return parts.join('\n');
+    }
+    /** Convert the search result candidates into the AI layer's document shape. */
+    toRerankDocuments(candidates) {
+        return candidates.map(item => ({
+            id: item.ID,
+            text: this.buildRerankText(item),
+            metadata: { __mjSearchItem: item },
+            originalScore: item.Score,
+        }));
+    }
+    /** Recover the original `SearchResultItem` and attach the rerank score. */
+    fromRerankResult(result) {
+        const original = result.document.metadata?.__mjSearchItem;
+        if (!original) {
+            throw new Error('BaseReRanker: rerank result missing original SearchResultItem in metadata — ' +
+                'did a subclass strip the metadata.__mjSearchItem key?');
+        }
+        return {
+            ...original,
+            Score: result.relevanceScore,
+            ScoreBreakdown: { ...original.ScoreBreakdown, ReRank: result.relevanceScore },
+        };
+    }
+}
+//# sourceMappingURL=BaseReRanker.js.map

package/dist/generic/BaseReRanker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseReRanker.js","sourceRoot":"","sources":["../../src/generic/BaseReRanker.ts"],"names":[],"mappings":"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"}

package/dist/generic/EntitySearchProvider.d.ts

@@ -9,7 +9,7 @@
  */
 import { UserInfo } from '@memberjunction/core';
 import { BaseSearchProvider } from './ISearchProvider.js';
-import { SearchSource, SearchFilters, SearchResultItem } from './search.types.js';
+import { SearchSource, SearchFilters, SearchResultItem, ScopeConstraints } from './search.types.js';
 /**
  * Provides entity-level LIKE-based search using RunView + UserSearchString.
  * Searches all entities where AllowUserSearchAPI=true, returning results
@@ -17,6 +17,19 @@ import { SearchSource, SearchFilters, SearchResultItem } from './search.types.js
  */
 export declare class EntitySearchProvider extends BaseSearchProvider {
     readonly SourceType: SearchSource;
+    /**
+     * Minimum trimmed term length we accept. One- and two-character substrings against
+     * a `LIKE '%term%'` pattern across every searchable entity is essentially a
+     * full-database scan with negligible relevance, so we early-return for those.
+     */
+    private static readonly MIN_TERM_LENGTH;
+    /**
+     * Per-entity hard timeout. If one entity's RunView is taking longer than this,
+     * we drop its results rather than hold the entire fan-out hostage. The query
+     * keeps running in SQL Server until completion (we can't cancel mssql Requests
+     * here), but other entities' results still land for the user.
+     */
+    private static readonly PER_ENTITY_TIMEOUT_MS;
     /**
      * Execute an entity search across all entities with AllowUserSearchAPI=true.
      *
@@ -26,15 +39,32 @@ export declare class EntitySearchProvider extends BaseSearchProvider {
      * @param contextUser - The user performing the search
      * @returns Scored result items from entity search
      */
-    Search(query: string, topK: number, filters: SearchFilters | undefined, contextUser: UserInfo): Promise<SearchResultItem[]>;
+    Search(query: string, topK: number, filters: SearchFilters | undefined, contextUser: UserInfo, scopeConstraints?: ScopeConstraints): Promise<SearchResultItem[]>;
+    /**
+     * Resolve the entity list to actually search.
+     *
+     * - If `scopeConstraints.Entities` is provided, use those directly (each carries its own
+     *   rendered ExtraFilter + UserSearchString) — this is the "scoped" path.
+     * - Otherwise fall back to the legacy unscoped path (`AllowUserSearchAPI=true` with
+     *   optional `filters.EntityNames` restriction) and wrap each in a trivial constraint.
+     */
+    private buildScopedEntityList;
     /**
      * Get the list of entities eligible for search, optionally filtered by name.
      */
     private getSearchableEntities;
     /**
-     * Search a single entity using RunView with UserSearchString.
+     * Search a single entity using RunView with UserSearchString. Wraps the
+     * underlying RunView in a hard PER_ENTITY_TIMEOUT_MS timeout so a slow
+     * entity cannot hold up the whole fan-out — partial results from the
+     * other entities still land.
+     *
+     * Note: `contextUser` is passed to RunView so row-level security (RLS) is applied
+     * automatically — this is the Entity provider's permission push-down per Section 3.6
+     * of plans/search-scopes-rag-plus.md.
      */
     private searchOneEntity;
+    private searchOneEntityRaw;
     /**
      * Convert RunView results to SearchResultItem format with field-match relevance scores.
      * Score is based on how many searchable fields contain the query and whether
@@ -50,5 +80,23 @@ export declare class EntitySearchProvider extends BaseSearchProvider {
      * Extract a display snippet from record data using entity metadata.
      */
     private extractSnippet;
+    /**
+     * Remove SQL LIKE wildcard characters from a user-supplied search string.
+     *
+     * The downstream `GenericDatabaseProvider.createViewUserSearchSQL`
+     * interpolates user input directly into `LIKE '%${input}%'`, only
+     * escaping single quotes. Unstripped LIKE wildcards (`%`, `_`, `[`, `]`)
+     * would either match too much (e.g. `Query="%"` matches every row) or
+     * trigger LIKE character-class parsing (`Query="[abc]"`).
+     *
+     * Behavior intent: these characters are treated as not-meaningful for
+     * entity LIKE search. A query containing literal `%` (e.g. `100%`) will
+     * not find records that contain `100%` — the trade-off is documented
+     * to keep the behavior predictable and safe.
+     *
+     * Trailing/leading whitespace is collapsed; an all-wildcard query
+     * returns empty and the caller short-circuits to zero results.
+     */
+    private sanitizeUserSearchString;
 }
 //# sourceMappingURL=EntitySearchProvider.d.ts.map

package/dist/generic/EntitySearchProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EntitySearchProvider.d.ts","sourceRoot":"","sources":["../../src/generic/EntitySearchProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAA6D,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAE3G,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAoB,MAAM,gBAAgB,CAAC;AAEjG;;;;GAIG;AACH,qBACa,oBAAqB,SAAQ,kBAAkB;IACxD,SAAgB,UAAU,EAAE,YAAY,CAAY;IAEpD;;;;;;;;OAQG;IACU,MAAM,CACf,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,aAAa,GAAG,SAAS,EAClC,WAAW,EAAE,QAAQ,GACtB,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAyC9B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAc7B;;OAEG;YACW,eAAe;IA4B7B;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAwDtB;;;OAGG;IACH,OAAO,CAAC,YAAY;IAmCpB;;OAEG;IACH,OAAO,CAAC,cAAc;CAczB"}
+{"version":3,"file":"EntitySearchProvider.d.ts","sourceRoot":"","sources":["../../src/generic/EntitySearchProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAmD,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAEjG,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAoB,gBAAgB,EAAyB,MAAM,gBAAgB,CAAC;AAE1I;;;;GAIG;AACH,qBACa,oBAAqB,SAAQ,kBAAkB;IACxD,SAAgB,UAAU,EAAE,YAAY,CAAY;IAEpD;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAK;IAE5C;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAAU;IAEvD;;;;;;;;OAQG;IACU,MAAM,CACf,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,aAAa,GAAG,SAAS,EAClC,WAAW,EAAE,QAAQ,EACrB,gBAAgB,CAAC,EAAE,gBAAgB,GACpC,OAAO,CAAC,gBAAgB,EAAE,CAAC;IA8E9B;;;;;;;OAOG;IACH,OAAO,CAAC,qBAAqB;IAoB7B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAc7B;;;;;;;;;OASG;YACW,eAAe;YAsBf,kBAAkB;IA8BhC;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAwDtB;;;OAGG;IACH,OAAO,CAAC,YAAY;IAmCpB;;OAEG;IACH,OAAO,CAAC,cAAc;IAetB;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,wBAAwB;CAGnC"}