Hybrid Search Rules

FATAL Constraints

• NEVER use IVFFlat indexes for the vector column. This tile is incompatible with supabase/ivfflat-index. HALT if an IVFFlat index is detected on the target column.
• NEVER hardcode the k constant inside the function body. It MUST be an input parameter with a default of 60.
• NEVER return results without computing both semantic_score and fulltext_score individually. The caller MUST receive both component scores alongside combined_score.
• NEVER use INNER JOIN to fuse the two CTEs. A FULL OUTER JOIN is mandatory so rows appearing in only one result set are still returned.
• NEVER skip the tsvector GIN index check. If no GIN index exists, HALT and instruct the caller to create one before proceeding.

Mandatory Behaviors

• The RRF score formula MUST be score = 1.0 / (k + rank). No other weighting formula is permitted.
• The semantic CTE MUST use the <=> cosine distance operator from pgvector.
• The full-text CTE MUST use plainto_tsquery (not to_tsquery) to safely handle raw user input.
• When a row has a NULL rank from one CTE, the corresponding score component MUST default to 0, not be excluded.
• The final RPC MUST be a STABLE PL/pgSQL function to allow query-plan caching.
• All hybrid search RPCs MUST be tested with EXPLAIN (ANALYZE, FORMAT JSON) to confirm both HNSW and GIN indexes are used.