Adds deterministic horizon-aware relevance_weight ∈[0,1] to get_competitors
(ТЗ §9.1): weighted mean of geo_proximity (0.30), class_similarity (0.25),
price_similarity (0.20), stage_at_horizon (0.25). stage_at_horizon projects
each competitor's sell-out to horizon_months (request param, default 12) so a
competitor sold-out by our launch ranks lower. class_similarity uses a domrf
class-ladder vs the local dominant class (no target class yet). Orders by
relevance_weight DESC (distance still present + tie-break). relevance_breakdown
(4 sub-scores) exposed for explainability (§16).
Additive: all legacy Competitor fields intact, new fields Optional; zero
frontend consumers of /competitors (UI uses /analyze). sold-count folded into
existing price query (no extra db.execute, #227 regression green). Graceful:
thin data → neutral 0.5. 57 new pure-helper tests. Completes #949.
Round 1 (commit bcd7dc8) был broken: на 2-bucket входах surplus уходил в free
полностью без учёта capacity → free превышал cap → следующая итерация
clamp'ировала его и наоборот. Infinite oscillation в FastAPI handler.
Round 2 fix per review BLOCK (#282 comment):
- Surplus распределяется пропорционально available capacity (cap - v),
не текущему v. Free никогда не вылетит выше cap.
- free = строго < cap (не <=) — иначе деление на 0 capacity.
- Hard guard `for _ in range(N+1)` — гарантированно завершается.
- Pathological (surplus > total_capacity): возвращаем оригинальный pct_map
+ cap_skipped=True (sum=100 invariant сохранён).
- Hamilton round вынесен в _hamilton_round() helper.
Tests:
- 2-bucket cases (90/10, 70/30, 99/1) expected cap_skipped=True
- test_cap_iteration_count_bounded — все pathological завершаются < 100ms
- All 13 cases verified standalone (3 fast-path + 7 reproduced + 3 pathological)
Раньше _VELOCITY_DIVISORS делил агрегаты mv_layout_velocity (24 мес)
на 4/12 для quarter/year, не меняя реальное окно данных. Теперь
inline SQL из objective_corpus_room_month с CAST(:window_interval AS interval).
velocity_per_month = deals_window / months_in_window (1.0/3.0/12.0).
Разные time_window → разные строки из БД → разный mix/velocity/jk_count.
Closes (epic part) #271 item 1
