-- pg_turbovec v1.16.0 -- Phase F-1: index-native late interaction.
--
-- This file is a *reference mirror*. The authoritative install
-- script is generated by `cargo pgrx schema`.
--
-- v1.16.0 adds turbovec.colbert_search -- the index-accelerated
-- stage-1 half of ColBERT late interaction (the stage-2 exact MaxSim
-- has shipped since Phase D / v1.14.0 as turbovec.max_sim):
--
--   turbovec.colbert_search(
--       rel         regclass,
--       id_col      text,                 -- bigint doc key
--       token_col   text,                 -- a turbovec.vector[] column
--       query       turbovec.vector[],    -- the query's token vectors
--       k           integer,
--       per_token_k integer DEFAULT 64,
--       candidate_n integer DEFAULT 256,
--       bit_width   integer DEFAULT 4
--   ) RETURNS TABLE(id bigint, score double precision)
--
-- Stage 1 builds a BACKEND-CACHED flat token index (one slot per
-- token across all docs, doc-id repeated; synthetic unique slot-ids
-- fed to IdMapIndex, real doc-ids kept separately -- the IVF
-- soft-assign trick), batch-searches all query tokens, and unions the
-- hit doc-ids into a candidate set. Stage 2 reads each candidate's
-- full token array from the heap and scores it with the exact
-- max_sim kernel (Phase D). The value over the pooled-vector +
-- max_sim re-rank pattern is STAGE-1 RECALL: a doc retrieved by its
-- best single token, not its pooled mean.
--
-- The token index lives ONLY in the backend cache (like
-- turbovec.knn) -- there is NO relfile, NO CREATE INDEX, and NO
-- wire-format change. MetaPageData::version stays 4. The persistent
-- token-index AM (Phase F-2) is gated on a measured recall/latency
-- win over this F-1 path.
--
-- colbert_search is a new SQL function; cargo pgrx schema emits its
-- CREATE FUNCTION into the authoritative 1.15.1--1.16.0 upgrade
-- script; this reference mirror does not duplicate it. There is no
-- on-disk migration and NO REINDEX. `ALTER EXTENSION pg_turbovec
-- UPDATE TO '1.16.0';` resolves cleanly.