cluster_sites_by_latency
Identify which candidate sites can form a low-latency cluster by evaluating pairwise RTT floors and estimates against your latency budget.
Instructions
Physics-bounded latency clustering for 2-8 sites — returns viable low-latency clusters and pairwise RTT floors before any routing work. Use when your human wants to know which of N candidate sites can form a synchronous / low-latency cluster (sync replication, active-active pairs, HPC pods): deterministic pruning BEFORE detailed routing. Per site pair: haversine distance, round-trip physics floor (km × 4.9 µs/km — light in SMF-28 fiber, n≈1.468 — then ×2), estimated real RTT (floor × route_factor 1.4, a stamped inference), viable vs physics_impossible against your budget, and confidence_v — the provenance tier of the supporting evidence (published | tracked | inferred). Also returns clusters: the largest site subsets whose ALL pairwise estimates fit the budget, plus each site's inferred dark-fiber screening level. CANDIDATE CONTRACT: pass candidate_ids (from get_refined_queue) instead of raw coordinates — each resolves to its FROZEN mint coordinates (zero transposition), and cand_… tokens may also be mixed into the sites string; expired/unknown ids are dropped AND declared in candidate_contract (fail-closed). Example: cluster_sites_by_latency sites="39.04,-77.48:ashburn;39.29,-76.61:baltimore;40.42,-79.99:pittsburgh" max_latency_us=2000 — or cluster_sites_by_latency candidate_ids=["cand_…","cand_…"] max_latency_us=2000. Returns _entity=latency_clusters: {pairs:[{from, to, distance_km, floor_rtt_us, est_rtt_us, viable, physics_impossible, confidence_v, endpoint_dark_screen}], clusters:[{sites, size, max_est_rtt_us}], viable_count, pruned_count, assumptions, provenance}. Do NOT treat this as an engineered latency quote — the floors are physics (no fiber path can beat them) but the estimates are inference (route_factor 1.4); always quote each pair's confidence_v when relaying results. For actual route corridors use plan_fiber_leadin; for a single-site connectivity score use get_fiber_readiness.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sites | No | Semicolon-separated "lat,lon" pairs, 2-8 sites (same format as compare_sites locations); optional per-site labels via "lat,lon:label", e.g. "39.04,-77.48:ashburn;39.29,-76.61:baltimore". cand_… tokens are also accepted here and resolve to frozen mint coordinates. Optional if candidate_ids is given | |
| candidate_ids | No | Array (or comma-separated string) of candidate_id values from get_refined_queue — each resolves to its FROZEN mint coordinates (zero transcription drift); expired/unknown are dropped and declared in candidate_contract. Use instead of, or alongside, sites | |
| max_latency_us | No | Round-trip latency budget in microseconds (default 1000 µs = 1 ms; sync replication is typically 1000-2000 µs) | |
| min_confidence | No | Minimum evidence tier a pair must meet to count as viable: "published" | "tracked" | "inferred" (default inferred = include all) |