Ranks every bond in the active Tesouro Direto catalog by where its latest published rate sits within its own history — in ONE call. Prefer this for questions like "which bonds have rates near their historical highs?", "how does today's rate compare with the past, across the catalog?", or any cross-bond comparison of rate levels. Do NOT loop `price_history_series` per paper for that.
For each catalog paper and each requested window it returns rate stats for one side: `min`/`max`, nearest-rank percentiles `p10`/`p25`/`p50`/`p75`/`p90` (always actually published rates), `last` (most recent published rate on or before `to`) and `lastPercentile` (0-100: share of the window strictly below `last` — 92 means the current rate is above 92% of the period, i.e. near the top of its historical range).
Inputs (all optional):
- `windows`: 1-3 of '30d' | '90d' | '1y' | '5y' | 'max', default ['1y']. Ranking is ordered by the FIRST window's `lastPercentile` (desc); extra windows add context (e.g. ['1y','max']).
- `side`: 'investorBuy' (default — investor PURCHASE rate, STN's Taxa de Venda; the standard quoted rate) or 'investorSell' (sell-back). Only papers currently available for that side are ranked.
- `productId`: filter to one family. Only the six catalog families are rankable — 'selic' and 'igpm-mais-com-juros-semestrais' have history but no active catalog entries; for those use `price_history_series`.
- `to`: anchor date YYYY-MM-DD (default today UTC) — set a past date for "how did the ranking look then?".
Output: `ranking[]` with `productId`, `maturityDate`, `year` (label year — CONVERSION year for renda-mais/educa-mais) and per-window stats; `meta.missing` lists catalog papers with no data in any window (e.g. just launched).
Caveats: this is a statistical description of published rates, NOT investment advice, a return forecast, or a recommendation — never present the ranking as "best bonds to buy". `lastPercentile` compares each paper against ITS OWN history only; a high percentile means the rate is high relative to that paper's past, nothing more. Comparing entries across families is meaningful only in that relative sense (a prefixado percentile reflects nominal rates; an ipca-mais percentile reflects real rates).
**Rates are decimal fraction strings** (same as `price_history_series`, `simulate_bond`, `live_quotes_lookup`).