export interface BrandCollisionWarning {
    detected: true;
    reason: string;
    brand_domains_in_top_3: string[];
    suggested_rewrites: string[];
}
/**
 * Structural brand-collision predicate (unified — this is the single source of
 * truth; query-understanding re-exports it for its `is_brand_collision_prone`
 * field). Fires in two pattern-level cases:
 *
 *   1. Short common-noun query (<=2 tokens, every token a collision-prone
 *      common noun) — the original "next", "apple mint" case.
 *   2. Proper-noun-head + generic-tail (any token count) — the first token is
 *      an entity AND a later token is a generic category noun, e.g.
 *      "Phoenix framework deployment", "Apollo API documentation". This is the
 *      s5-class collision the old <=2-token gate could never reach.
 *
 * Never fires on an error-token query (S1 owns error intent) — an error string
 * like "TypeError undefined api" must not be treated as a brand collision.
 */
export declare function isBrandCollisionProne(query: string): boolean;
/**
 * Detect a brand-collision condition: the query is a common-noun token that
 * commonly clashes with a brand domain AND the top-3 results actually contain
 * a brand-domain host. Emits a structured warning with disambiguation
 * suggestions; returns null when no collision is detected.
 */
export declare function detectBrandCollision(query: string, topUrls: string[]): BrandCollisionWarning | null;
/**
 * Build an entity-qualified rewrite of an "Entity + generic tail" query. The
 * entity head is quoted so an engine treats it as one atom, keeping the whole
 * original query intent while anchoring on the ambiguous entity — e.g.
 * `Phoenix framework deployment` → `"Phoenix" framework deployment`. Returns
 * null when the query carries no detectable entity head.
 */
export declare function entityQualifiedRewrite(query: string): string | null;
/**
 * Detect an entity-collision condition (brand-collision v2): a proper-noun-head
 * + generic-tail query is structurally ambiguous — the head names an entity
 * that clashes with an everyday word. Unlike detectBrandCollision this does NOT
 * require a brand TLD in the top-3, since the collision is in the query itself.
 * Emits a warning whose rewrites anchor the entity head verbatim so the caller
 * can disambiguate. Returns null when the query is not entity-collision prone.
 */
export declare function detectEntityCollision(query: string): BrandCollisionWarning | null;
/**
 * The single top disambiguating rewrite for a query that is QUERY-ONLY
 * collision-prone — i.e. detectable without looking at any result URLs. Two
 * cases, both mirroring an existing detector's rewrites:
 *
 *   1. A short common-noun brand collision (`isBrandCollisionProne` case 1,
 *      e.g. "next", "apple mint") → the top of `suggestRewrites` — the same
 *      rewrites `detectBrandCollision` emits once a brand TLD is seen in the
 *      top-3. Anchored here on the query alone so it can dispatch CONCURRENTLY
 *      with the primary wave (the warning still gates on the top-3 as before).
 *   2. A single-token React-HOOK-name lexical collision (e.g. "useState") →
 *      the "<term> React hook" rewrite. Gated on the React-hook SUBSET of the
 *      lexicon (`REACT_HOOK_TERMS`), NOT the full lexicon: the "<term> React
 *      hook" rewrite is only semantically valid for hook names. Library/tool/
 *      ORM terms (docker, vite, prisma, redux, webpack, …) stay warning-only —
 *      auto-dispatching "docker React hook" would RRF-merge React-hooks docs
 *      into a clean tool query, which is actively harmful.
 *
 * Excluded on purpose (handled elsewhere or not query-only):
 *   - the proper-noun-head + generic-tail case (`detectEntityCollision`) —
 *     already auto-dispatched via `entityQualifiedRewrite`; returning null here
 *     avoids a duplicate third dispatch;
 *   - any error-token query (`isBrandCollisionProne` already rejects these).
 *
 * Returns null when the query is not query-only collision-prone or the rewrite
 * would be identical to the query.
 */
export declare function topCollisionRewrite(query: string): string | null;
export declare function detectLexicalCollision(query: string): BrandCollisionWarning | null;
//# sourceMappingURL=brand-collision.d.ts.map