Share the partner label and partner starts in the join minimum

[shreyashankar]

Problem

The join minimum in quail_b.minimum is too high. It counts the partner label, the partner document, and the answer cue in full for each pair. A prefix cache over whole requests shares two of these parts:

• The partner label directly after the frame is the same for every pair of one anchor.
• Partners of one anchor that start with the same tokens share those tokens.

For example, on LEP-6 at sf 0.5 (Qwen3 4B fp8), the stock vLLM run computed 70.74M fresh tokens, but the minimum was 72.03M. Thus its KV regret showed 0. A rebuild of all 1,014,968 vLLM join requests, tokenized from the text that vLLM got, gives 315,088,130 tokens, the same as the vLLM count. With unlimited KV and 16-token cache blocks, these requests need at least 69,996,610 fresh tokens. vLLM computed 69,996,914. Per token, they need 63,892,234, which is 8.42M less than the old minimum:

• 6.09M tokens from the 6-token label (6 × 1,014,968 pairs);
• 2.34M tokens from shared partner starts.

Solution

• The label is now part of the anchor's suffix (frame and label together). It counts one time for each anchor, and it shares its lead with the anchor's other questions.
• The partner documents of one anchor, each followed by the answer cue, count as a prefix trie.
• _PartnerTrie sorts all partner documents for one answer cue one time. The trie size of a subset is its length minus, for each pair of sorted neighbours, the shortest common prefix in the sorted run between them. A range-minimum table gives that value. Thus a join with many anchors does not sort its partners again for each anchor.
• docs/reference.md states the new rule.

Impact

Only joins and classifications of joined rows change. Saved runs of Qwen3 4B fp8 at sf 0.5, scored again (KV regret as a percentage of fresh tokens):

Query	Quail before	Quail now	stock vLLM before	stock vLLM now
IMDB-13	1.1%	10.9%	29.3%	36.3%
IMDB-15	3.9%	13.1%	35.9%	42.0%
BIO-6	0.2%	18.4%	33.8%	43.2%
LEP-6	0.0%	11.7%	0.0%	10.0%

Sources: /results/benchmarks/quailb/20261002T061804Z-a6ccc1fe-minfix/quail and /results/benchmarks/quailb/20261001T010217Z-1e7f7ba8-minfix/stock_vllm on the quail-results volume. The other eight classification queries do not change. For the LEP-6 vLLM run, the new minimum before scaling is 63,892,234, the same as the direct per-token check above.

Testing

• The quail-bench checks pass (ruff, long strings, vulture, 100 tests).
• New: test_minimum_input_tokens_of_a_join_is_the_trie_of_its_requests compares the minimum with prefix_trie_size over all full requests of a join. The join has partners with a shared start and one repeated text.
• New: test_partner_trie_size_matches_the_trie_of_any_subset compares _PartnerTrie with prefix_trie_size on 200 random subsets of 60 short documents, with repeats and prefixes.
• Three existing tests now expect the new rule.

Limits and follow-ups

• The minimum counts tokens. vLLM caches full 16-token blocks, so part of a vLLM regret is block rounding: about 7.7M tokens on LEP-6.
• Two anchor documents with the same text but different ids still count their suffixes separately.
• Quail (fsdatalab/quail#178) pins f3ad796. After this PR merges, Quail moves the pin to the merge commit.

🤖 Generated with Claude Code

https://claude.ai/code/session_01BGcUxUrkntTY43pDwWgfK5

---

Generated by Claude Code