Gemini grounded search: anchor extracted claims back to the grounded text via verbatim quotes — never paraphrase-then-match

A two-phase grounded-news pipeline (Phase A: Gemini + googleSearch tool returns grounded text + groundingChunks/groundingSupports; Phase B: a second LLM call extracts structured stories) repeatedly attached the WRONG source URL to accurate claims — three production incidents in three weeks, each 'fixed' by patching a keyword matcher.

Root cause: the API's attribution mechanism is span-based — groundingSupports[].segment.{startIndex,endIndex} map spans of the GENERATED text to groundingChunkIndices. Paraphrasing in Phase B destroys span alignment, forcing lossy post-hoc keyword matching between rewritten headlines and chunk URLs.

Working pattern:

1. Have the extraction step also return a source_quote — a VERBATIM contiguous quote from the grounded text containing the claim's key figure. Verbatimness is machine-checkable (grounded_text.find(quote)), so hallucinated quotes are detectable, unlike hallucinated URLs.
2. Locate the quote's span and take the union of chunk indices from all overlapping supports, ranked by summed overlap.
3. Verify content: fetch the candidate article (you already fetch it to resolve the vertexaisearch redirect — keep the body!) and check the claim's distinctive figures (e.g. '60%'/'60 percent') appear in the page text. This catches both matcher errors AND genuine model mis-grounding.

Gotchas (verified against real recorded responses via litellm _hidden_params['vertex_ai_grounding_metadata']):

• segment start/end are UTF-8 BYTE offsets (start inclusive, end exclusive) — do byte-space matching, not str indices.
• groundingChunkIndices routinely lists MULTIPLE chunks per segment; using indices[0] silently discards the right answer.
• groundingChunks[].web.title is the bare DOMAIN, not the article title — with several chunks from one outlet, only the resolved URL slug discriminates.
• Segments overlap each other (nested spans over the same text).
• Persist grounded_text + supports in your debug artifacts; without them you cannot distinguish model mis-grounding from matcher bugs post-hoc.