attio-mcp 1.1.0 → 1.1.2

package/CHANGELOG.md

@@ -17,6 +17,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Deprecated
 
+## [1.1.2] - 2025-10-08
+
+### Fixed
+
+- **Multi-token search query logic** - Fixed fallback search to require ALL tokens in multi-word queries instead of ANY token
+  - **Problem**: Multi-word searches (e.g., "Alpha Beta Company") returned 100+ records matching ANY token ("Alpha" OR "Beta" OR "Company"), pushing exact matches out of results
+  - **Solution**: Multi-token queries now use AND-of-OR structure - each token must match somewhere (in name OR domains), but all tokens must match (cross-field flexibility with precision)
+  - **Result**: Multi-word name searches now return exact matches in top results instead of being buried at position #101+
+  - Single-token queries unchanged (still use simple `$contains`)
+  - This improves precision for company/people searches with multi-word names
+- **records_search relevance** (#885) - Added client-side scoring with uFuzzy and LRU caching so exact domain/name/email matches rank first while repeated queries stay within the 3 s budget
+- **Deal search fast path optimization** (#885) - Extended fast path optimization to deals with 72-80% performance improvement
+  - Sequential candidate execution: exact match ($eq) → substring match ($contains)
+  - LRU caching with 5-minute TTL delivers 8ms cached responses (99.9% faster than ~2.8s cold searches)
+  - Created `DealSearchStrategy` following same pattern as companies/people
+  - Removed obsolete `searchDeals()` and `queryDealRecords()` methods (100+ lines)
+  - Fixed original bug where deals only supported exact name matches
+- **Notes search functionality - Partial fix with API limitation** (#888)
+  - Created `NoteSearchStrategy` following established search strategy pattern
+  - **API Limitation Discovered**: Attio Notes API `/v2/notes` endpoint returns empty array when called without filters
+    - Confirmed via direct API testing: `GET /v2/notes` returns `{"data": []}`
+    - API requires `parent_object` and/or `parent_record_id` filters to return notes
+    - This prevents searching across all notes in a workspace
+  - **What Works**: `list-notes` tool with parent record filtering (e.g., list all notes on a specific company)
+  - **What Doesn't Work**: Global note search without parent filters (e.g., "find all notes containing 'demo'")
+  - **Workaround**: Use `list-notes` with explicit parent filters to search within a specific record's notes
+  - Implemented client-side filtering for title/content when parent filters are provided
+  - Added smart caching (30s TTL) with parent-aware cache keys to prevent cross-contamination
+  - Removed obsolete `searchNotes()` fallback method (85 lines)
+  - **Recommendation**: Request Attio to add workspace-wide notes endpoint or search capability
+
 ## [1.1.0] - 2025-10-06
 
 This release enhances developer experience with intelligent prompts, comprehensive tool standardization, and strengthens enterprise readiness with security hardening and validation improvements.

package/README.md

@@ -177,8 +177,8 @@ For complete prompt documentation, see [docs/prompts/v1-catalog.md](./docs/promp
 ### 🤝 **OpenAI MCP Compatibility**
 
 - **Developer Mode Ready**: Every tool now publishes MCP safety annotations (`readOnlyHint`, `destructiveHint`) so OpenAI Developer Mode can auto-approve reads and request confirmation for writes.
-- **Search Compatibility Surface**: The `search` and `fetch` tools remain available for OpenAI's baseline MCP support. Set `ATTIO_MCP_TOOL_MODE=search` to expose only these read-only endpoints (plus `aaa-health-check`) when Developer Mode is unavailable.
-- **Default Behaviour**: With `ATTIO_MCP_TOOL_MODE` unset, the full universal tool set is exposed—matching Claude’s experience—while OpenAI users still see the compatibility wrappers.
+- **Full Tool Access (Default)**: All 33 universal tools are exposed by default. Do NOT set `ATTIO_MCP_TOOL_MODE` in Smithery configuration for full access.
+- **Search-Only Mode**: To restrict to read-only tools (`search`, `fetch`, `aaa-health-check`), explicitly configure `ATTIO_MCP_TOOL_MODE: 'search'` in Smithery dashboard when Developer Mode is unavailable.
 - **Detailed Guide**: See [docs/chatgpt-developer-mode.md](./docs/chatgpt-developer-mode.md) for environment variables, approval flows, and validation tips.
 - **User Documentation**: See the [ChatGPT Developer Mode docs](./docs/chatgpt-developer-mode.md) for a complete walkthrough of approval flows and setup instructions.
 
@@ -608,6 +608,7 @@ Comprehensive documentation is available in the [docs directory](./docs):
 
 - [Warning Filter Configuration](./docs/configuration/warning-filters.md) - Understanding cosmetic vs semantic mismatches, ESLint budgets, and suppression strategies
 - [Field Verification Configuration](./docs/configuration/field-verification.md) - Field persistence verification and validation settings
+- [Search Scoring Configuration](./docs/configuration/search-scoring.md) - Environment variables for relevance scoring, caching, and operator validation
 
 ### **API Reference**
 

package/dist/api/operations/search.d.ts

@@ -10,10 +10,13 @@ import { AttioRecord, ResourceType } from '../../types/attio.js';
  *
  * @param objectType - The type of object to search (people or companies)
  * @param query - Search query string
- * @param retryConfig - Optional retry configuration
+ * @param options - Optional search options (limit, retryConfig)
  * @returns Array of matching records
  */
-export declare function searchObject<T extends AttioRecord>(objectType: ResourceType, query: string, retryConfig?: Partial<RetryConfig>): Promise<T[]>;
+export declare function searchObject<T extends AttioRecord>(objectType: ResourceType, query: string, options?: {
+    limit?: number;
+    retryConfig?: Partial<RetryConfig>;
+}): Promise<T[]>;
 /**
  * Generic function to search any object type with advanced filtering capabilities
  *

package/dist/api/operations/search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../src/api/operations/search.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAiB,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAK5D,OAAO,EACL,WAAW,EACX,YAAY,EAEb,MAAM,wBAAwB,CAAC;AA4GhC;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,CAAC,SAAS,WAAW,EACtD,UAAU,EAAE,YAAY,EACxB,KAAK,EAAE,MAAM,EACb,WAAW,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GACjC,OAAO,CAAC,CAAC,EAAE,CAAC,CAsBd;AAED;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CAAC,CAAC,SAAS,WAAW,EAC9D,UAAU,EAAE,YAAY,EACxB,OAAO,CAAC,EAAE,gBAAgB,EAC1B,KAAK,CAAC,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,EACf,WAAW,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GACjC,OAAO,CAAC,CAAC,EAAE,CAAC,CAuId;AAED;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAAC,CAAC,SAAS,WAAW,EACrD,UAAU,EAAE,YAAY,EACxB,KAAK,CAAC,EAAE,MAAM,EACd,WAAW,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GACjC,OAAO,CAAC,CAAC,EAAE,CAAC,CA0Bd"}
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../src/api/operations/search.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAiB,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAK5D,OAAO,EACL,WAAW,EACX,YAAY,EAEb,MAAM,wBAAwB,CAAC;AAyhBhC;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,CAAC,SAAS,WAAW,EACtD,UAAU,EAAE,YAAY,EACxB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAA;CAAE,GAC/D,OAAO,CAAC,CAAC,EAAE,CAAC,CA4Ld;AAED;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CAAC,CAAC,SAAS,WAAW,EAC9D,UAAU,EAAE,YAAY,EACxB,OAAO,CAAC,EAAE,gBAAgB,EAC1B,KAAK,CAAC,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,EACf,WAAW,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GACjC,OAAO,CAAC,CAAC,EAAE,CAAC,CAuId;AAED;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAAC,CAAC,SAAS,WAAW,EACrD,UAAU,EAAE,YAAY,EACxB,KAAK,CAAC,EAAE,MAAM,EACd,WAAW,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GACjC,OAAO,CAAC,CAAC,EAAE,CAAC,CA0Bd"}

package/dist/api/operations/search.js

@@ -9,6 +9,248 @@ import { FilterValidationError } from '../../errors/api-errors.js';
 import { ErrorEnhancer } from '../../errors/enhanced-api-errors.js';
 import { transformFiltersToApiFormat } from '../../utils/record-utils.js';
 import { ResourceType, } from '../../types/attio.js';
+import { LRUCache } from 'lru-cache';
+import { scoreAndRank } from '../../services/search-utilities/SearchScorer.js';
+import { createScopedLogger } from '../../utils/logger.js';
+const logger = createScopedLogger('api.operations', 'search');
+const ENABLE_SEARCH_SCORING = process.env.ENABLE_SEARCH_SCORING !== 'false';
+const SEARCH_CACHE_TTL_MS = Number.parseInt(process.env.SEARCH_CACHE_TTL_MS ?? `${5 * 60 * 1000}`, 10);
+const SEARCH_CACHE_MAX = Number.parseInt(process.env.SEARCH_CACHE_MAX ?? '500', 10);
+const SEARCH_FETCH_MULTIPLIER = Number.parseInt(process.env.SEARCH_FETCH_MULTIPLIER ?? '5', 10);
+const SEARCH_FETCH_MIN = Number.parseInt(process.env.SEARCH_FETCH_MIN ?? '50', 10);
+const SEARCH_FAST_PATH_LIMIT = Number.parseInt(process.env.SEARCH_FAST_PATH_LIMIT ?? '5', 10);
+const DEFAULT_FETCH_LIMIT = Number.parseInt(process.env.SEARCH_DEFAULT_LIMIT ?? '20', 10);
+const searchCache = new LRUCache({
+    max: Number.isFinite(SEARCH_CACHE_MAX) ? SEARCH_CACHE_MAX : 500,
+    ttl: Number.isFinite(SEARCH_CACHE_TTL_MS)
+        ? SEARCH_CACHE_TTL_MS
+        : 5 * 60 * 1000,
+});
+function getCacheKey(objectType, query, limit) {
+    return `${objectType}:${limit}:${query.toLowerCase()}`;
+}
+function normalizeDomainValue(value) {
+    return value
+        .toLowerCase()
+        .replace(/^https?:\/\//, '')
+        .replace(/^www\./, '')
+        .trim();
+}
+function normalizePlainValue(value) {
+    return value.toLowerCase().trim();
+}
+function extractStringsFromField(fieldValue, keys = []) {
+    const results = [];
+    const pushString = (candidate) => {
+        if (typeof candidate === 'string' && candidate.trim()) {
+            results.push(candidate);
+        }
+    };
+    if (!fieldValue) {
+        return results;
+    }
+    if (typeof fieldValue === 'string') {
+        pushString(fieldValue);
+        return results;
+    }
+    if (Array.isArray(fieldValue)) {
+        fieldValue.forEach((item) => {
+            if (typeof item === 'string') {
+                pushString(item);
+            }
+            else if (item && typeof item === 'object') {
+                keys.forEach((key) => {
+                    pushString(item[key]);
+                });
+            }
+        });
+        return results;
+    }
+    if (fieldValue && typeof fieldValue === 'object') {
+        keys.forEach((key) => {
+            pushString(fieldValue[key]);
+        });
+    }
+    return results;
+}
+function extractNormalizedName(record) {
+    const values = (record?.values ?? {});
+    const candidates = [];
+    if ('name' in values) {
+        candidates.push(values.name);
+    }
+    if ('full_name' in values) {
+        candidates.push(values.full_name);
+    }
+    if ('title' in values) {
+        candidates.push(values.title);
+    }
+    const normalizeCandidate = (candidate) => {
+        if (typeof candidate === 'string' && candidate.trim()) {
+            return normalizePlainValue(candidate);
+        }
+        if (Array.isArray(candidate)) {
+            for (const item of candidate) {
+                const normalized = normalizeCandidate(item);
+                if (normalized) {
+                    return normalized;
+                }
+            }
+        }
+        if (candidate && typeof candidate === 'object') {
+            const obj = candidate;
+            const nested = obj.full_name ?? obj.formatted ?? obj.value ?? obj.name;
+            if (typeof nested === 'string' && nested.trim()) {
+                return normalizePlainValue(nested);
+            }
+        }
+        return null;
+    };
+    for (const candidate of candidates) {
+        const normalized = normalizeCandidate(candidate);
+        if (normalized) {
+            return normalized;
+        }
+    }
+    return '';
+}
+/**
+ * Build fast-path candidates for structured queries.
+ *
+ * Issue #885: Attio API supports $eq operator (verified 2025-10-07)
+ * Supported operators: $eq, $contains, $starts_with, $ends_with, $not_empty
+ * NOT supported: $equals, $in
+ *
+ * @see scripts/test-attio-operators.mjs for operator verification tests
+ */
+function buildFastPathCandidates(objectType, parsed, originalQuery) {
+    const candidates = [];
+    const trimmedQuery = originalQuery.trim();
+    if (objectType === ResourceType.COMPANIES && parsed.domains.length === 1) {
+        const normalizedDomain = normalizeDomainValue(parsed.domains[0]);
+        candidates.push({
+            filter: { domains: { $eq: normalizedDomain } },
+            kind: 'domain',
+            strategy: 'eq',
+            value: normalizedDomain,
+        });
+        candidates.push({
+            filter: { domains: { $contains: normalizedDomain } },
+            kind: 'domain',
+            strategy: 'contains',
+            value: normalizedDomain,
+        });
+    }
+    if (parsed.emails.length === 1) {
+        const emailValue = parsed.emails[0].toLowerCase();
+        candidates.push({
+            filter: { email_addresses: { $eq: emailValue } },
+            kind: 'email',
+            strategy: 'eq',
+            value: emailValue,
+        });
+        candidates.push({
+            filter: { email_addresses: { $contains: emailValue } },
+            kind: 'email',
+            strategy: 'contains',
+            value: emailValue,
+        });
+    }
+    // Try all phone variants as fast path candidates (parser creates normalized forms)
+    if (parsed.phones.length > 0) {
+        parsed.phones.forEach((phoneValue) => {
+            candidates.push({
+                filter: { phone_numbers: { $eq: phoneValue } },
+                kind: 'phone',
+                strategy: 'eq',
+                value: phoneValue,
+            });
+        });
+    }
+    const hasStructuredQuery = parsed.domains.length > 0 ||
+        parsed.emails.length > 0 ||
+        parsed.phones.length > 0;
+    if (trimmedQuery &&
+        !hasStructuredQuery &&
+        (objectType === ResourceType.COMPANIES ||
+            objectType === ResourceType.PEOPLE ||
+            objectType === ResourceType.DEALS)) {
+        const normalizedName = normalizePlainValue(trimmedQuery);
+        candidates.push({
+            filter: { name: { $eq: trimmedQuery } },
+            kind: 'name',
+            strategy: 'eq',
+            value: normalizedName,
+        });
+        candidates.push({
+            filter: { name: { $contains: trimmedQuery } },
+            kind: 'name',
+            strategy: 'contains',
+            value: normalizedName,
+        });
+    }
+    return candidates;
+}
+function recordMatchesFastPath(record, candidate) {
+    const values = (record?.values ?? {});
+    switch (candidate.kind) {
+        case 'domain': {
+            const domains = extractStringsFromField(values.domains, [
+                'domain',
+                'value',
+            ]).map(normalizeDomainValue);
+            if (candidate.strategy === 'eq') {
+                return domains.includes(candidate.value);
+            }
+            return domains.some((domain) => domain.includes(candidate.value));
+        }
+        case 'email': {
+            const emails = extractStringsFromField(values.email_addresses, [
+                'email_address',
+                'value',
+            ]).map(normalizePlainValue);
+            if (candidate.strategy === 'eq') {
+                return emails.includes(candidate.value);
+            }
+            return emails.some((email) => email.includes(candidate.value));
+        }
+        case 'phone': {
+            const phones = extractStringsFromField(values.phone_numbers, [
+                'phone_number', // Main normalized field
+                'original_phone_number', // Original input
+                'number', // Legacy fallback
+                'normalized', // Legacy fallback
+                'value', // Legacy fallback
+            ]);
+            const normalizedSet = new Set();
+            phones.forEach((phone) => {
+                normalizedSet.add(phone);
+                normalizedSet.add(phone.replace(/\s+/g, ''));
+                // Also try with/without leading +
+                if (phone.startsWith('+')) {
+                    normalizedSet.add(phone.substring(1));
+                }
+                else {
+                    normalizedSet.add(`+${phone}`);
+                }
+            });
+            return (normalizedSet.has(candidate.value) ||
+                normalizedSet.has(candidate.value.replace(/\s+/g, '')));
+        }
+        case 'name': {
+            const recordName = extractNormalizedName(record);
+            if (!recordName) {
+                return false;
+            }
+            if (candidate.strategy === 'eq') {
+                return recordName === candidate.value;
+            }
+            return recordName.includes(candidate.value);
+        }
+        default:
+            return false;
+    }
+}
 function createLegacyFilter(objectType, query) {
     if (objectType === ResourceType.PEOPLE) {
         return {
@@ -28,12 +270,12 @@ function addCondition(collection, seen, condition) {
         collection.push(condition);
     }
 }
-function buildSearchFilter(objectType, query) {
+function buildSearchFilter(objectType, query, parsedOverride) {
     const trimmedQuery = query.trim();
     if (!trimmedQuery) {
         return createLegacyFilter(objectType, query);
     }
-    const parsed = parseQuery(trimmedQuery);
+    const parsed = parsedOverride ?? parseQuery(trimmedQuery);
     const conditions = [];
     const seen = new Set();
     parsed.emails.forEach((email) => {
@@ -63,6 +305,99 @@ function buildSearchFilter(objectType, query) {
         tokenTargets.add('domains');
     }
     const uniqueTokens = Array.from(new Set(parsed.tokens.filter((token) => token.length > 1)));
+    // AND-of-OR search strategy (#885 fix):
+    // For each token, allow it to match ANY field (name OR domains OR email/phone)
+    // But ALL tokens must match SOMEWHERE
+    // This provides precision (all tokens required) + cross-field flexibility (name + domain tokens)
+    //
+    // Example: "Elite Styles Beauty Mindful Program"
+    // - "Elite" can match name OR domains
+    // - "Styles" can match name OR domains
+    // - "Mindful" can match name OR domains (will match domain mindfulbeautyprogram.com)
+    // - etc.
+    //
+    // Result: Company "Elite Styles And Beauty" (mindfulbeautyprogram.com) matches because:
+    // - "Elite" matches name ✓
+    // - "Styles" matches name ✓
+    // - "Beauty" matches name ✓
+    // - "Mindful" matches domain ✓
+    // - "Program" matches domain ✓
+    if (uniqueTokens.length > 0) {
+        if (uniqueTokens.length === 1) {
+            // Single token: create OR condition across all relevant fields
+            const token = uniqueTokens[0];
+            tokenTargets.forEach((field) => {
+                addCondition(conditions, seen, {
+                    [field]: { $contains: token },
+                });
+            });
+        }
+        else {
+            // Multiple tokens: each token must match at least one field (AND of ORs)
+            const tokenAndConditions = uniqueTokens.map((token) => {
+                const tokenFieldConditions = [];
+                tokenTargets.forEach((field) => {
+                    tokenFieldConditions.push({
+                        [field]: { $contains: token },
+                    });
+                });
+                return {
+                    $or: tokenFieldConditions,
+                };
+            });
+            // Combine all token conditions with AND
+            addCondition(conditions, seen, {
+                $and: tokenAndConditions,
+            });
+        }
+    }
+    if (conditions.length === 0) {
+        return createLegacyFilter(objectType, trimmedQuery);
+    }
+    if (conditions.length === 1) {
+        return conditions[0];
+    }
+    return {
+        $or: conditions,
+    };
+}
+/**
+ * Build OR-only fallback filter for when AND-of-OR returns zero results
+ * Uses the same parsed structure but allows ANY token to match (no AND requirement)
+ */
+function buildORFallbackFilter(objectType, parsed) {
+    const conditions = [];
+    const seen = new Set();
+    // Include all structured fields as before
+    parsed.emails.forEach((email) => {
+        addCondition(conditions, seen, {
+            email_addresses: { $contains: email },
+        });
+    });
+    parsed.phones.forEach((phone) => {
+        addCondition(conditions, seen, {
+            phone_numbers: { $contains: phone },
+        });
+    });
+    if (objectType === ResourceType.COMPANIES) {
+        parsed.domains.forEach((domain) => {
+            addCondition(conditions, seen, {
+                domains: { $contains: domain },
+            });
+        });
+    }
+    const tokenTargets = new Set();
+    tokenTargets.add('name');
+    if (objectType === ResourceType.PEOPLE) {
+        tokenTargets.add('email_addresses');
+        tokenTargets.add('phone_numbers');
+    }
+    if (objectType === ResourceType.COMPANIES) {
+        tokenTargets.add('domains');
+    }
+    const uniqueTokens = Array.from(new Set(parsed.tokens.filter((token) => token.length > 1)));
+    // OR-only fallback: each token can match any field (no AND requirement)
+    // This provides maximum recall when the stricter AND-of-OR filter returns zero results
     uniqueTokens.forEach((token) => {
         tokenTargets.forEach((field) => {
             addCondition(conditions, seen, {
@@ -71,7 +406,8 @@ function buildSearchFilter(objectType, query) {
         });
     });
     if (conditions.length === 0) {
-        return createLegacyFilter(objectType, trimmedQuery);
+        // Shouldn't happen, but return safe fallback
+        return { name: { $contains: parsed.tokens.join(' ') } };
     }
     if (conditions.length === 1) {
         return conditions[0];
@@ -85,27 +421,151 @@ function buildSearchFilter(objectType, query) {
  *
  * @param objectType - The type of object to search (people or companies)
  * @param query - Search query string
- * @param retryConfig - Optional retry configuration
+ * @param options - Optional search options (limit, retryConfig)
  * @returns Array of matching records
  */
-export async function searchObject(objectType, query, retryConfig) {
+export async function searchObject(objectType, query, options) {
+    const retryConfig = options?.retryConfig;
     const api = getLazyAttioClient();
     const path = `/objects/${objectType}/records/query`;
-    const filter = buildSearchFilter(objectType, query);
+    const trimmedQuery = query.trim();
+    const scoringEnabled = ENABLE_SEARCH_SCORING && trimmedQuery.length > 0;
+    // Use caller's limit if provided, otherwise fall back to default
+    const requestedLimit = options?.limit;
+    const baseLimit = requestedLimit !== undefined && requestedLimit > 0
+        ? requestedLimit
+        : Number.isFinite(DEFAULT_FETCH_LIMIT) && DEFAULT_FETCH_LIMIT > 0
+            ? DEFAULT_FETCH_LIMIT
+            : 20;
+    const multiplier = Number.isFinite(SEARCH_FETCH_MULTIPLIER) && SEARCH_FETCH_MULTIPLIER > 0
+        ? SEARCH_FETCH_MULTIPLIER
+        : 5;
+    const minimumFetch = Number.isFinite(SEARCH_FETCH_MIN) && SEARCH_FETCH_MIN > 0
+        ? SEARCH_FETCH_MIN
+        : 50;
+    const fastPathLimit = Number.isFinite(SEARCH_FAST_PATH_LIMIT) && SEARCH_FAST_PATH_LIMIT > 0
+        ? Math.max(baseLimit, SEARCH_FAST_PATH_LIMIT)
+        : baseLimit;
+    const parsedQuery = trimmedQuery ? parseQuery(trimmedQuery) : null;
+    const cacheKey = scoringEnabled && trimmedQuery
+        ? getCacheKey(objectType, trimmedQuery, baseLimit)
+        : null;
+    if (scoringEnabled && cacheKey) {
+        const cached = searchCache.get(cacheKey);
+        if (cached) {
+            return cached;
+        }
+    }
+    if (scoringEnabled && parsedQuery) {
+        const fastCandidates = buildFastPathCandidates(objectType, parsedQuery, trimmedQuery);
+        for (const candidate of fastCandidates) {
+            const candidateLimit = candidate.kind === 'name' && candidate.strategy === 'contains'
+                ? Math.min(100, Math.max(minimumFetch, baseLimit * multiplier))
+                : candidate.kind === 'name' && candidate.strategy === 'eq'
+                    ? baseLimit
+                    : fastPathLimit;
+            logger.debug('[FastPath] Trying candidate', {
+                kind: candidate.kind,
+                strategy: candidate.strategy,
+                filter: candidate.filter,
+                limit: candidateLimit,
+            });
+            try {
+                const fastResponse = await callWithRetry(async () => {
+                    return api.post(path, {
+                        filter: candidate.filter,
+                        limit: candidateLimit,
+                    });
+                }, retryConfig);
+                const fastData = Array.isArray(fastResponse?.data?.data)
+                    ? fastResponse?.data?.data
+                    : [];
+                logger.debug('[FastPath] Received results', {
+                    count: fastData.length,
+                });
+                if (!fastData.length) {
+                    logger.debug('[FastPath] No results for candidate');
+                    continue;
+                }
+                const hasMatch = fastData.some((record) => recordMatchesFastPath(record, candidate));
+                if (!hasMatch) {
+                    logger.debug('[FastPath] Validation failed', {
+                        candidateKind: candidate.kind,
+                        candidateStrategy: candidate.strategy,
+                        candidateValue: candidate.value,
+                        resultCount: fastData.length,
+                    });
+                    continue;
+                }
+                logger.debug('[FastPath] Validation passed, ranking');
+                const rankedFast = scoreAndRank(trimmedQuery, fastData, parsedQuery);
+                const truncatedFast = rankedFast.slice(0, baseLimit);
+                if (cacheKey) {
+                    searchCache.set(cacheKey, truncatedFast);
+                }
+                return truncatedFast;
+            }
+            catch (error) {
+                logger.debug('[FastPath] Error executing candidate', {
+                    kind: candidate.kind,
+                    strategy: candidate.strategy,
+                    filter: candidate.filter,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                void error; // Non-fatal fast-path failure; fall back to next candidate
+            }
+        }
+    }
+    const filter = buildSearchFilter(objectType, query, parsedQuery ?? undefined);
+    const fetchLimit = scoringEnabled
+        ? Math.max(minimumFetch, baseLimit * multiplier)
+        : baseLimit;
     return callWithRetry(async () => {
         try {
             const response = await api.post(path, {
                 filter,
+                limit: fetchLimit,
             });
-            return response?.data?.data || [];
+            const rawData = response?.data?.data;
+            let data = Array.isArray(rawData) ? rawData : [];
+            // OR-only fallback when AND-of-OR returns zero results (#885 recall fix)
+            // This handles over-constrained queries like "Beauty Glow Aesthetics Frisco"
+            // where some tokens don't exist but the record should still match
+            // Runs regardless of scoring state - scoring only affects ranking, not recall
+            if (data.length === 0 && parsedQuery) {
+                logger.debug('[Fallback] Zero results from AND-of-OR, trying OR-only', {
+                    query: trimmedQuery,
+                    objectType,
+                });
+                const fallbackFilter = buildORFallbackFilter(objectType, parsedQuery);
+                const fallbackResponse = await api.post(path, {
+                    filter: fallbackFilter,
+                    limit: fetchLimit,
+                });
+                const fallbackRawData = fallbackResponse?.data?.data;
+                data = Array.isArray(fallbackRawData)
+                    ? fallbackRawData
+                    : [];
+                logger.debug('[Fallback] OR-only results', {
+                    count: data.length,
+                });
+            }
+            if (!scoringEnabled || data.length <= 1) {
+                const truncated = data.slice(0, baseLimit);
+                return truncated;
+            }
+            const ranked = scoreAndRank(trimmedQuery, data, parsedQuery ?? undefined);
+            const truncated = ranked.slice(0, baseLimit);
+            if (cacheKey) {
+                searchCache.set(cacheKey, truncated);
+            }
+            return truncated;
         }
         catch (error) {
             const apiError = error;
-            // Handle 404 errors with custom message
             if (apiError.response && apiError.response.status === 404) {
                 throw new Error(`No ${objectType} found matching '${query}'`);
             }
-            // Let upstream handlers create specific, rich error objects from the original Axios error.
             throw error;
         }
     }, retryConfig);