feat(search): Metal residual bound kernel + GPU cascade routing (chain 3/3)

[christopherkarani]

Chain Info

Chain: 3 of 3
Strategy: feature-branch-chain
Base: chain/2-residual-core (merge 1, then 2 first)

• ✅ PR refactor(search): extract flat-search top-k selection (chain 1/3) #28 — slice 1: selection extraction refactor
• ✅ PR feat(search): exact residual cascade CPU core (chain 2/3) #29 — slice 2: exact residual cascade CPU core
• 🔄 THIS PR — slice 3: Metal residual bound kernel + GPU routing

Summary

• Adds residual_bound_parameters / residual_compute_bounds to FlatSearch.metal: one bandwidth-bound GPU pass computes safe per-row lower bounds for the cascade.
• ResidualCascadeGPU.swift implements searchGPU(context:) with lazy per-device plane caching and exact host verification; any failure falls back to the flat GPU tier (never approximate).
• FlatGPUSearch.search routes eligible very-large-corpora queries through Tier 2.5 before the flat GPU tier.

Exactness

• Only mathematically safe lower bounds prune; survivors are rescored exactly on host.
• METALANNS_VERIFY_BOUNDS=1: zero bound violations across cosine/L2/inner-product diagnostics.
• recall@10 = recall@100 = 1.000 vs scalar reference at n=300k and n=1M.

Performance (fixed protocol: 1M×384 cosine k=24, M3 Max, seed 42)

	baseline	this chain
warm p50	6.07 ms	2.42 ms (~2.5×)
p95	6.36 ms	4.43 ms
QPS	163.9	365.3
recall@10	1.000	1.000

The ≥10× aspiration is not met; limiting factors are the full-corpus projected-bound scan and host seed selection. Best observed run: p50 2.35 ms.

Changes

File	Change
Sources/MetalANNSCore/Shaders/FlatSearch.metal	+74 lines: bound kernel + parameter structs
Sources/MetalANNSCore/ResidualCascadeGPU.swift	New: GPU cascade dispatch + plane cache
Sources/MetalANNSCore/FlatGPUSearch.swift	Tier 2.5 routing + lint suppressions

Test Plan

• Release build clean
• Full suite: 325 tests / 71 suites pass on this branch alone
• Zero bound violations (METALANNS_VERIFY_BOUNDS=1)

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.