omp-llm-role 1.0.0 → 1.2.0

package/src/engine.ts

@@ -87,6 +87,10 @@ export type LlmStatsRow = {
   index_vision: number | null;
   index_tool_calling: number | null;
   index_long_context: number | null;
+  index_communication: number | null;
+  index_finance: number | null;
+  index_healthcare: number | null;
+  index_legal: number | null;
   // Benchmarks (0-1)
   gpqa_score: number | null;
   aime_2025_score: number | null;
@@ -95,6 +99,21 @@ export type LlmStatsRow = {
   mrcr_v2_score: number | null;
   terminal_bench_score: number | null;
   tau_bench_retail_score: number | null;
+  simpleqa_score: number | null;
+  hle_score: number | null;
+  mmmu_score: number | null;
+  mmmu_pro_score: number | null;
+  mmmlu_score: number | null;
+  browsecomp_score: number | null;
+  swe_bench_pro_score: number | null;
+  mcp_atlas_score: number | null;
+  apex_agents_score: number | null;
+  osworld_score: number | null;
+  scicode_score: number | null;
+  screenspot_pro_score: number | null;
+  charxiv_r_score: number | null;
+  frontiermath_score: number | null;
+  toolathlon_score: number | null;
 };
 
 export type Model = {
@@ -103,6 +122,9 @@ export type Model = {
   org: string;
   orgId: string;
   context: number | null;
+  /** llm-stats `release_date` (ISO date), carried for the focus-metric freshness
+   * gate; null when the row has no date. */
+  releaseDate: string | null;
   multimodal: boolean;
   /** supports reasoning (OpenRouter `supports_reasoning`) — the fallback gate
    * for the role's thinking price factor and the selector suffix at write
@@ -131,6 +153,10 @@ export type Model = {
    * is then capability-filled, see `applyWritingScores`. */
   writingBench: number | null;
   metrics: Record<string, number | null>;
+  /** Eligible standard-tier OpenRouter routes (the 1/price² blend pool) with their
+   * per-endpoint capability ceilings; set by `applyOpenRouterData`. Undefined when
+   * the model has no OpenRouter page data. The role endpoint filters gate on this. */
+  routes?: OpenRouterEndpointRecord[];
 };
 
 export type RoleDef = {
@@ -145,13 +171,47 @@ export type RoleDef = {
   /** metrics the model must have to be ranked at all for this role */
   required: string[];
   /** schema-capability filters applied before ranking eligibility */
-  filters?: { image?: boolean };
+  filters?: {
+    image?: boolean;
+    /** require every kept route's endpoint to support tools (`supported_parameters`) */
+    tools?: boolean;
+    /** drop routes whose endpoint `context_length` is below this (tokens); 0 = off */
+    minContextTokens?: number;
+    /** drop routes whose endpoint `max_completion_tokens` is below this (tokens); 0 = off */
+    minOutputTokens?: number;
+    /** drop the model when its role-priced blend exceeds this ($/M); 0 = off */
+    maxPriceUsdPerM?: number;
+    /** soft throughput floor (tok/s); 0/absent = off. A route at or above the
+     * floor sorts before a route below it, but is never dropped. */
+    preferredMinThroughput?: number;
+  };
   /** explicit λ override ($ per quality point); default derives from the price weight */
   lambda?: number;
   /** thinking level appended to the role's selector (`:level`) when the chosen
    * catalog entry supports thinking; absent = bare (session default level).
    * Also scales the price axis for ranking (thinkingPriceFactor). */
   thinking?: SuffixLevel;
+  /** Provider slug the role's requests are pinned to (OpenRouter `@<slug>`
+   * routing); may be tiered like `deepinfra/fp8`. When set, the role is priced
+   * by that route — its billed price and p50 throughput — not the 1/price²
+   * blend, and a model with no matching route is ineligible. Absent = OpenRouter
+   * default routing (the blend, unchanged). */
+  providerPin?: string;
+  /** Assumed cache-hit rate (0–1) for the role's input tokens; 0/absent = off. When
+   * set, the role's effective input price blends the endpoint's cache-read price and
+   * its full input price (`hitRate·cacheRead + (1−hitRate)·input`) before the 3:1
+   * blend and the thinking factor — the ranking then reflects a cache-heavy agent
+   * loop's invoice, not the sticker price. A route with no cache-read price keeps its
+   * full input price. The weight basis stays the listed input price (the router's
+   * sort key), so a cheap cache on a lightly-weighted route does not dominate. */
+  cacheHitRate?: number;
+  /** Opt-in capability flags (`roles.<role>.features.<id>`); expanded by
+   * `expandFeatures` before ranking. `true`/`false` overrides the global flag. */
+  features?: Record<string, boolean>;
+  /** Soft provider preference (issue #40, re-based by #58): price a model on its
+   * best route by the role's own value when the role's `providerPinning` feature
+   * is on, else the 1/price² blend. Unlike `providerPin` this NEVER drops a model. */
+  preferOwnProvider?: boolean;
   /** Locked role: the plugin still ranks it (so it stays in the universe and its
    * sources are fetched) but never rewrites its `modelRoles` selector or fallback
    * chain, and never removes it. Enable/disable still applies. */
@@ -183,12 +243,18 @@ export type RankData = {
 // OpenRouter's default routing is price-based load balancing: a request goes to
 // ONE provider, picked among the stable standard-tier routes with probability
 // proportional to 1/price² (docs: "select one weighted by inverse square of the
-// price"). The enrichment is therefore the expected value over that distribution:
-// price = Σ(1/p²)·p / Σ(1/p²), throughput = Σ(1/p²)·t / Σ(1/p²) over the routes
-// that have throughput data (renormalized — a provider without recent traffic
-// can't contribute). flex/priority service tiers are excluded (only the :floor /
-// :nitro variants make them eligible), as are degraded routes (status ≠ 0 — they
-// are fallbacks), :batch variants and $0 :free tiers (1/p² blows up at 0).
+// price"). The router sorts on the INPUT (prompt) price alone — verified against
+// Tarun Chitra's "Caching Cheaters on OpenRouter" (64/64 splits, a 1,648-choice
+// fit r=1.968); OpenRouter's docs are silent on the basis. The enrichment is
+// therefore the expected value over that distribution, weighted by the input
+// price: reported price = Σ(1/p_in²)·p_billed / Σ(1/p_in²) (the billed 3:1 blend
+// is what a caller pays, so it stays the reported price), throughput =
+// Σ(1/p_in²)·t / Σ(1/p_in²) over the routes that have throughput data
+// (renormalized — a provider without recent traffic can't contribute).
+// flex/priority service tiers are excluded (only the :floor / :nitro variants
+// make them eligible), as are degraded routes (status ≠ 0 — they are fallbacks),
+// :batch variants, $0 :free tiers and routes with no input price (1/p² blows up
+// at 0, and the router cannot score a route without an input price).
 // Without page data the pool is the find route(s) alone (a :free variant never
 // contributes there either — it is a separate slug default routing never requests);
 // the pre-page max-p50/min-price path remains only for pools where no eligible
@@ -205,6 +271,13 @@ type OpenRouterFindData = {
   endpoint_perf: Record<string, OpenRouterPerf>;
   /** endpoint id -> blended $/M (3:1 in:out); only endpoints with usable prompt+completion pricing */
   endpoint_price: Record<string, number>;
+  /** endpoint id -> input-only $/M (prompt price) — the router's sort key and the 1/price² weight basis;
+   * only endpoints with usable prompt pricing */
+  endpoint_weight_price: Record<string, number>;
+  /** endpoint id -> cache-read input-only $/M (the endpoint's `pricing.input_cache_read`);
+   * only endpoints with usable cache-read pricing. A role's cache-hit rate blends this with
+   * `endpoint_weight_price` before the 3:1 blend (see `blendRoutePool`). */
+  endpoint_cache_read_price: Record<string, number>;
 };
 
 /** One provider route from a model page, narrowed: pricing blended to $/M (3:1
@@ -217,22 +290,81 @@ export type OpenRouterEndpointRecord = {
   status: number;
   free: boolean;
   variant: string;
+  /** billed $/M, 3:1 in:out blend — the reported price */
   price: number | null;
+  /** input-only $/M (prompt price) — the router's sort key, the 1/price² weight basis */
+  weightPrice: number | null;
+  /** cache-read input-only $/M (the endpoint's `pricing.input_cache_read`); null when the
+   * endpoint reports none — a role's cache-hit rate then uses the full input price
+   * (`weightPrice`), so missing data is not a silent discount. */
+  cacheReadPrice: number | null;
   tput: number | null;
   latency: number | null;
+  /** endpoint `context_length` (tokens); null when the field is absent */
+  contextLength: number | null;
+  /** endpoint `max_completion_tokens` (tokens); null when the field is absent */
+  maxCompletionTokens: number | null;
+  /** endpoint `supported_parameters` contains `tools`; null when the field is absent */
+  supportsTools: boolean | null;
 };
 
 /** OR slug -> its provider routes, from the model pages. */
 export type OpenRouterEndpointPages = Record<string, OpenRouterEndpointRecord[]>;
 
-export type OrEnrichment = { tput: number; latency: number | null; price: number | null; thinking: boolean };
+export type OrEnrichment = { tput: number; latency: number | null; price: number | null; thinking: boolean; routes: OpenRouterEndpointRecord[] };
+
+/** The effective billed $/M of one route under an assumed cache-hit rate. The route's
+ * billed 3:1 price is `price = (3·input + output)/4` on the listed input price; a hit
+ * rate `h` blends the cache-read input into the input term,
+ * `effInput = h·cacheRead + (1−h)·input`, so `billed = price + 3·(effInput − input)/4`
+ * (the output term is unchanged). With `h = 0`, no cache-read price, or no input price
+ * this is the route's listed `price` — missing data keeps the full input price, never a
+ * silent discount. Shared by the blend (`blendRoutePool`), the pin path (`rankRole`) and
+ * `roleMetricValue`. */
+export function routeEffectivePrice(route: OpenRouterEndpointRecord, cacheHitRate = 0): number | null {
+  if (route.price == null) return null;
+  if (cacheHitRate <= 0 || route.cacheReadPrice == null || route.weightPrice == null) return route.price;
+  const input = route.weightPrice;
+  const effInput = cacheHitRate * route.cacheReadPrice + (1 - cacheHitRate) * input;
+  return route.price + (3 * (effInput - input)) / 4;
+}
+
+/** Expected price/throughput/latency of one request over a route pool under the
+ * router's default price-based load balancing: P(route i) ∝ 1/input_price_i² — the
+ * router sorts on the input (prompt) price alone, so the weight basis is
+ * `weightPrice`, not the reported 3:1 billed blend (and the cache-hit rate does not
+ * change routing: a cheap cache on a lightly-weighted route must not dominate). The
+ * billed per-route price is `routeEffectivePrice(route, cacheHitRate)`, so a role's
+ * assumed cache-hit rate blends the cache-read price in before the weighting;
+ * `cacheHitRate = 0` makes this byte-identical to the uncached blend. `price` is the
+ * w-weighted mean of those billed prices; throughput and latency renormalize over the
+ * routes that carry p50 data (a provider without recent traffic cannot contribute).
+ * Only routes with a usable billed and input price can be scored; an unscorable pool
+ * returns all-null. This is the model-level blend AND the pool a role with endpoint
+ * filters is priced on (issue #18). */
+export function blendRoutePool(routes: OpenRouterEndpointRecord[], cacheHitRate = 0): { price: number | null; tput: number | null; latency: number | null } {
+  const usable = routes.filter((r) => r.price !== null && r.price > 0 && r.weightPrice !== null && r.weightPrice > 0);
+  if (usable.length === 0) return { price: null, tput: null, latency: null };
+  const weighted = usable.map((r) => ({ r, w: 1 / ((r.weightPrice as number) * (r.weightPrice as number)) }));
+  const wSum = weighted.reduce((a, x) => a + x.w, 0);
+  const price = weighted.reduce((a, x) => a + x.w * (routeEffectivePrice(x.r, cacheHitRate) as number), 0) / wSum;
+  const tputKnown = weighted.filter((x) => x.r.tput !== null);
+  const tputW = tputKnown.reduce((a, x) => a + x.w, 0);
+  const tput = tputW > 0 ? tputKnown.reduce((a, x) => a + x.w * (x.r.tput as number), 0) / tputW : null;
+  const latKnown = tputKnown.filter((x) => x.r.latency !== null);
+  const latW = latKnown.reduce((a, x) => a + x.w, 0);
+  const latency = latW > 0 ? latKnown.reduce((a, x) => a + x.w * (x.r.latency as number), 0) / latW : null;
+  return { price, tput, latency };
+}
 
 /**
  * Build llm-stats model_id -> OpenRouter enrichment (throughput, latency, blended
  * price, thinking support). :batch variants are skipped (no perf data, half-price
- * async tier). Price and throughput are the 1/price²-weighted means over the pool's
- * stable standard-tier billed routes — the expected values under OpenRouter's default
- * price-based load balancing. The pool is the page's per-provider routes plus any
+ * async tier). Price and throughput are the 1/input-price²-weighted means over the
+ * pool's stable standard-tier billed routes — the expected values under OpenRouter's
+ * default price-based load balancing, whose sort key is the input (prompt) price
+ * alone. The reported price is the w-weighted mean of the BILLED 3:1 blend (what a
+ * caller pays); the weight basis is the input price. The pool is the page's per-provider routes plus any
  * find-row endpoint the page doesn't list; without page data it is the find route(s)
  * alone, so a :free variant never contributes there either (it is a separate slug
  * default routing never requests). Only when no eligible route carries throughput
@@ -242,7 +374,7 @@ export type OrEnrichment = { tput: number; latency: number | null; price: number
  * variant row advertising `supports_reasoning`.
  */
 export function buildOpenRouterEnrichment(data: OpenRouterFindData, pages?: OpenRouterEndpointPages): Record<string, OrEnrichment> {
-  type Cand = { slug: string; id: string; free: boolean; think: boolean; status: number | null; variant: string; perf: OpenRouterPerf | null; price: number | null };
+  type Cand = { slug: string; id: string; free: boolean; think: boolean; status: number | null; variant: string; perf: OpenRouterPerf | null; price: number | null; weightPrice: number | null; cacheReadPrice: number | null };
   const bySuffix: Record<string, Cand[]> = {};
   for (const m of data.models) {
     const ep = m.endpoint;
@@ -259,6 +391,8 @@ export function buildOpenRouterEnrichment(data: OpenRouterFindData, pages?: Open
       variant,
       perf: data.endpoint_perf[ep.id] ?? null,
       price: data.endpoint_price[ep.id] ?? null,
+      weightPrice: data.endpoint_weight_price?.[ep.id] ?? null,
+      cacheReadPrice: data.endpoint_cache_read_price?.[ep.id] ?? null,
     });
   }
   const out: Record<string, OrEnrichment> = {};
@@ -281,27 +415,30 @@ export function buildOpenRouterEnrichment(data: OpenRouterFindData, pages?: Open
         free: c.free,
         variant: c.variant,
         price: c.price,
+        weightPrice: c.weightPrice,
+        cacheReadPrice: c.cacheReadPrice,
         tput: c.perf?.p50_throughput ?? null,
         latency: c.perf?.p50_latency ?? null,
+        // The find payload carries no capability ceilings — unstated (null), kept by the gate.
+        contextLength: null,
+        maxCompletionTokens: null,
+        supportsTools: null,
       };
     }
     const eligible = Object.values(pool).filter(
-      (r) => r.serviceTier === null && r.status === 0 && !r.free && r.price !== null && r.price > 0 && !r.variant.endsWith(":batch"),
+      (r) =>
+        r.serviceTier === null &&
+        r.status === 0 &&
+        !r.free &&
+        r.price !== null &&
+        r.price > 0 &&
+        r.weightPrice !== null &&
+        r.weightPrice > 0 &&
+        !r.variant.endsWith(":batch"),
     );
-    const withTput = eligible.filter((r) => r.tput !== null);
-    if (eligible.length > 0 && withTput.length > 0) {
-      // Expected price/throughput of one request under price-based load balancing:
-      // P(route i) ∝ 1/price_i². Throughput renormalizes over the routes with data.
-      const weighted = eligible.map((r) => ({ r, w: 1 / (r.price * r.price) }));
-      const wSum = weighted.reduce((a, x) => a + x.w, 0);
-      const price = weighted.reduce((a, x) => a + x.w * x.r.price, 0) / wSum;
-      const tputKnown = weighted.filter((x) => x.r.tput !== null);
-      const tputW = tputKnown.reduce((a, x) => a + x.w, 0);
-      const tput = tputKnown.reduce((a, x) => a + x.w * (x.r.tput ?? 0), 0) / tputW;
-      const latKnown = tputKnown.filter((x) => x.r.latency !== null);
-      const latW = latKnown.reduce((a, x) => a + x.w, 0);
-      const latency = latW > 0 ? latKnown.reduce((a, x) => a + x.w * (x.r.latency ?? 0), 0) / latW : null;
-      out[suffix] = { tput, latency, price, thinking: cands.some((c) => c.think) };
+    const blend = blendRoutePool(eligible);
+    if (eligible.length > 0 && blend.tput !== null && blend.price !== null) {
+      out[suffix] = { tput: blend.tput, latency: blend.latency, price: blend.price, thinking: cands.some((c) => c.think), routes: eligible };
       continue;
     }
     // Fallback: the find route alone. Throughput is the highest-p50 variant, :free
@@ -320,7 +457,7 @@ export function buildOpenRouterEnrichment(data: OpenRouterFindData, pages?: Open
     const billed: number[] = [];
     for (const c of cands) if (!c.free && c.price != null && c.price > 0) billed.push(c.price);
     const price = billed.length === 0 ? null : Math.min(...billed);
-    out[suffix] = { tput, latency, price, thinking: cands.some((c) => c.think) };
+    out[suffix] = { tput, latency, price, thinking: cands.some((c) => c.think), routes: eligible };
   }
   return out;
 }
@@ -336,6 +473,7 @@ export function applyOpenRouterData(models: Model[], orData: Record<string, OrEn
     m.thinking = or.thinking;
     m.throughput = or.tput;
     m.metrics.throughput = or.tput;
+    m.routes = or.routes;
     if (or.price != null) {
       priced++;
       m.price = or.price;
@@ -351,7 +489,7 @@ export function applyOpenRouterData(models: Model[], orData: Record<string, OrEn
 // ---------------------------------------------------------------------------
 
 /** Narrow one page endpoint record; null when the row isn't the expected shape. */
-function narrowEndpointRecord(row: unknown): OpenRouterEndpointRecord | null {
+export function narrowEndpointRecord(row: unknown): OpenRouterEndpointRecord | null {
   if (typeof row !== "object" || row === null) return null;
   if (!("id" in row) || typeof row.id !== "string") return null;
   if (!("provider_slug" in row) || typeof row.provider_slug !== "string") return null;
@@ -360,9 +498,14 @@ function narrowEndpointRecord(row: unknown): OpenRouterEndpointRecord | null {
   const free = "is_free" in row && row.is_free === true;
   const variant = "model_variant_permaslug" in row && typeof row.model_variant_permaslug === "string" ? row.model_variant_permaslug : "";
   let price: number | null = null;
+  let weightPrice: number | null = null;
+  let cacheReadPrice: number | null = null;
   if ("pricing" in row && typeof row.pricing === "object" && row.pricing !== null) {
     const prompt = "prompt" in row.pricing ? Number(row.pricing.prompt) : Number.NaN;
     const completion = "completion" in row.pricing ? Number(row.pricing.completion) : Number.NaN;
+    const cacheRead = "input_cache_read" in row.pricing ? Number(row.pricing.input_cache_read) : Number.NaN;
+    if (Number.isFinite(prompt) && prompt >= 0) weightPrice = prompt * 1e6; // input-only $/M: the router's sort key
+    if (Number.isFinite(cacheRead) && cacheRead >= 0) cacheReadPrice = cacheRead * 1e6; // cache-read input-only $/M
     if (Number.isFinite(prompt) && Number.isFinite(completion) && prompt >= 0 && completion >= 0) {
       price = ((3 * prompt + completion) / 4) * 1e6; // USD/token -> blended $/M, 3:1 in:out
     }
@@ -373,7 +516,13 @@ function narrowEndpointRecord(row: unknown): OpenRouterEndpointRecord | null {
     if ("p50_throughput" in row.stats && typeof row.stats.p50_throughput === "number") tput = row.stats.p50_throughput;
     if ("p50_latency" in row.stats && typeof row.stats.p50_latency === "number") latency = row.stats.p50_latency;
   }
-  return { id: row.id, providerSlug: row.provider_slug, serviceTier: tier, status, free, variant, price, tput, latency };
+  // Per-endpoint capability ceilings. A missing field yields null (kept by the
+  // role gate — missing data is not a capability failure).
+  const contextLength = "context_length" in row && typeof row.context_length === "number" ? row.context_length : null;
+  const maxCompletionTokens = "max_completion_tokens" in row && typeof row.max_completion_tokens === "number" ? row.max_completion_tokens : null;
+  const supportsTools =
+    "supported_parameters" in row && Array.isArray(row.supported_parameters) ? row.supported_parameters.includes("tools") : null;
+  return { id: row.id, providerSlug: row.provider_slug, serviceTier: tier, status, free, variant, price, weightPrice, cacheReadPrice, tput, latency, contextLength, maxCompletionTokens, supportsTools };
 }
 
 /** Extract the per-provider endpoint records from a model page's RSC flight. The
@@ -493,7 +642,7 @@ async function loadEndpointPages(slugs: string[], refresh: boolean): Promise<Ope
  * covered median overstates an unmeasured model; the uncovered cohort's own
  * mean general index sits at the 0.195 percentile of the covered field. A
  * below-median covered model therefore still scores below the fill — that
- * residual inversion is documented in README Known quirks. (A regression fill
+ * residual inversion is documented in `docs/dev/quirks.md`. (A regression fill
  * was rejected: a least-squares fit of percentile on the general index
  * saturates at 0 for ~19% of the uncovered eligible pool, and a
  * nearest-neighbour fill is discontinuous (0.49 jumps between models 0.06
@@ -567,6 +716,8 @@ export function parseFindData(v: unknown): ParsedFindData {
     perf[id] = { p50_latency: latency, p50_throughput: tput };
   }
   const price: Record<string, number> = {};
+  const weightPrice: Record<string, number> = {};
+  const cacheReadPrice: Record<string, number> = {};
   for (const row of d.models) {
     if (typeof row !== "object" || row === null || !("endpoint" in row)) continue;
     const ep: unknown = row.endpoint;
@@ -576,10 +727,13 @@ export function parseFindData(v: unknown): ParsedFindData {
     if (typeof id !== "string" || typeof pr !== "object" || pr === null) continue;
     const prompt = "prompt" in pr ? Number(pr.prompt) : Number.NaN;
     const completion = "completion" in pr ? Number(pr.completion) : Number.NaN;
+    const cacheRead = "input_cache_read" in pr ? Number(pr.input_cache_read) : Number.NaN;
+    if (Number.isFinite(prompt) && prompt >= 0) weightPrice[id] = prompt * 1e6; // input-only $/M: the router's sort key
+    if (Number.isFinite(cacheRead) && cacheRead >= 0) cacheReadPrice[id] = cacheRead * 1e6; // cache-read input-only $/M
     if (!Number.isFinite(prompt) || !Number.isFinite(completion) || prompt < 0 || completion < 0) continue;
     price[id] = ((3 * prompt + completion) / 4) * 1e6; // USD/token -> blended $/M, 3:1 in:out
   }
-  return { find: { models: d.models, endpoint_perf: perf, endpoint_price: price }, data: d, designElo: extractDesignElo(d.models, "benchmarks" in d ? d.benchmarks : null) };
+  return { find: { models: d.models, endpoint_perf: perf, endpoint_price: price, endpoint_weight_price: weightPrice, endpoint_cache_read_price: cacheReadPrice }, data: d, designElo: extractDesignElo(d.models, "benchmarks" in d ? d.benchmarks : null) };
 }
 
 /**
@@ -697,11 +851,15 @@ const INDEX_METRICS: Record<string, true> = {
   vision: true,
   tool_calling: true,
   long_context: true,
+  index_communication: true,
+  index_finance: true,
+  index_healthcare: true,
+  index_legal: true,
 };
 
 /** Chance-level pass rates for benchmark metrics (guessing baseline = true zero
  * of skill). Benchmarks absent here guess ≈ 0 and use the raw pass rate. */
-const BENCHMARK_CHANCE: Record<string, number> = {
+export const BENCHMARK_CHANCE: Record<string, number> = {
   gpqa: 0.25, // 4-way multiple choice
 };
 
@@ -789,6 +947,7 @@ export function buildModels(rows: LlmStatsRow[]): Model[] {
     org: r.organization,
     orgId: r.organization_id,
     context: r.context,
+    releaseDate: r.release_date,
     multimodal: r.multimodal === true,
     thinking: false,
     price: null,
@@ -806,6 +965,10 @@ export function buildModels(rows: LlmStatsRow[]): Model[] {
       vision: r.index_vision,
       tool_calling: r.index_tool_calling,
       long_context: r.index_long_context,
+      index_communication: r.index_communication,
+      index_finance: r.index_finance,
+      index_healthcare: r.index_healthcare,
+      index_legal: r.index_legal,
       gpqa: r.gpqa_score,
       aime: r.aime_2025_score,
       swe_bench: r.swe_bench_verified_score,
@@ -813,6 +976,21 @@ export function buildModels(rows: LlmStatsRow[]): Model[] {
       mrcr: r.mrcr_v2_score,
       terminal_bench: r.terminal_bench_score,
       tau_bench: r.tau_bench_retail_score,
+      simpleqa_score: r.simpleqa_score,
+      hle_score: r.hle_score,
+      mmmu_score: r.mmmu_score,
+      mmmu_pro_score: r.mmmu_pro_score,
+      mmmlu_score: r.mmmlu_score,
+      browsecomp_score: r.browsecomp_score,
+      swe_bench_pro_score: r.swe_bench_pro_score,
+      mcp_atlas_score: r.mcp_atlas_score,
+      apex_agents_score: r.apex_agents_score,
+      osworld_score: r.osworld_score,
+      scicode_score: r.scicode_score,
+      screenspot_pro_score: r.screenspot_pro_score,
+      charxiv_r_score: r.charxiv_r_score,
+      frontiermath_score: r.frontiermath_score,
+      toolathlon_score: r.toolathlon_score,
       price: null, // set by OpenRouter enrichment; the λ·$ penalty axis, never blended
       throughput: null,
       website: null, // set by applyDesignPercentiles (percentile + capability-consistent fill)
@@ -821,49 +999,291 @@ export function buildModels(rows: LlmStatsRow[]): Model[] {
   }));
 }
 
+/** True when the role declares any endpoint capability filter (tools/context/output). */
+export function hasEndpointFilters(filters: RoleDef["filters"]): boolean {
+  if (!filters) return false;
+  return filters.tools === true || (filters.minContextTokens ?? 0) > 0 || (filters.minOutputTokens ?? 0) > 0;
+}
+
+/** True when a route satisfies every declared endpoint filter. A null capability
+ * field is kept — missing data is not a capability failure. */
+export function routePassesEndpointFilters(route: OpenRouterEndpointRecord, filters: RoleDef["filters"]): boolean {
+  if (!filters) return true;
+  if (filters.tools === true && route.supportsTools === false) return false;
+  if ((filters.minContextTokens ?? 0) > 0 && route.contextLength !== null && route.contextLength < (filters.minContextTokens as number)) return false;
+  if ((filters.minOutputTokens ?? 0) > 0 && route.maxCompletionTokens !== null && route.maxCompletionTokens < (filters.minOutputTokens as number)) return false;
+  return true;
+}
+
+/** True when the model has at least one standard-tier route satisfying the role's
+ * endpoint filters. A model with no route data has no capable route (fails). */
+export function modelPassesEndpointFilters(model: Model, filters: RoleDef["filters"]): boolean {
+  if (!hasEndpointFilters(filters)) return true;
+  return (model.routes ?? []).some((r) => routePassesEndpointFilters(r, filters));
+}
+
+/** The model as a role with endpoint filters and/or a cache-hit rate sees it: the
+ * route pool is narrowed to the standard-tier routes that satisfy every declared
+ * filter, and `price`/`throughput` become the 1/price² blend over that pool — the
+ * routes the router would actually choose from — with the role's cache-hit rate
+ * blended into each route's billed price (`blendRoutePool`). Returns null when no
+ * route survives (the model is ineligible for the role). A role with no endpoint
+ * filter and no cache-hit rate gets the model unchanged. */
+export function endpointFilteredModel(m: Model, filters: RoleDef["filters"], cacheHitRate = 0): Model | null {
+  if (!hasEndpointFilters(filters) && cacheHitRate <= 0) return m;
+  const pool = (m.routes ?? []).filter((r) => routePassesEndpointFilters(r, filters));
+  if (pool.length === 0) return null;
+  const { price, tput } = blendRoutePool(pool, cacheHitRate);
+  const effPrice = price ?? m.price;
+  const effTput = tput ?? m.throughput;
+  return { ...m, price: effPrice, throughput: effTput, metrics: { ...m.metrics, price: effPrice, throughput: effTput } };
+}
+
+/** Ranking ids dropped by the role's endpoint filters: they pass every other
+ * eligibility gate (required metrics, image, billed price) but have no capable
+ * standard-tier route. For the decision log; empty when the role declares no
+ * endpoint filter. */
+export function endpointFilterDrops(def: RoleDef, models: Model[]): string[] {
+  if (!hasEndpointFilters(def.filters)) return [];
+  return models
+    .filter(
+      (m) =>
+        def.required.every((k) => m.metrics[k] != null) &&
+        !(def.filters?.image && !m.multimodal) &&
+        m.price != null &&
+        !modelPassesEndpointFilters(m, def.filters),
+    )
+    .map((m) => m.id);
+}
+
+/** The model's route matching the role's provider pin (exact, tiered verbatim);
+ * null when the role is unpinned or the model has no such route. */
+export function pinnedRoute(model: Model, providerPin: string | undefined): OpenRouterEndpointRecord | null {
+  if (providerPin === undefined) return null;
+  return (model.routes ?? []).find((r) => r.providerSlug === providerPin) ?? null;
+}
+
+/** The role's thinking-adjusted billed price for a model at `basePrice`: the
+ * thinking factor applies only when the model actually runs the role's level
+ * (catalog `thinkingLevels` wins; without it the `supports_reasoning` flag
+ * gates). Mirrors the factor `rankRole` applies, so the route basis and the
+ * ranking can never disagree. */
+export function thinkingAdjustedPrice(model: Model, def: RoleDef, basePrice: number): number {
+  const levelFactor = def.thinking === undefined ? 1 : thinkingPriceFactor(def.thinking);
+  if (levelFactor === 1) return basePrice;
+  const levels = model.thinkingLevels;
+  const runsAtLevel = levels
+    ? levels.length > 0 && (def.thinking === undefined || META_LEVELS[def.thinking] === true || levels.includes(def.thinking))
+    : model.thinking;
+  return runsAtLevel ? basePrice * levelFactor : basePrice;
+}
+
+/** The role's value of a model priced on `route` (null = the 1/price² blend):
+ * the price-free quality composite q over the model's metrics with the route's
+ * p50 throughput and cache-adjusted billed price, minus λ·priceEff. Returns null
+ * when the model has no usable billed price. */
+function roleValueOnRoute(
+  em: Model,
+  def: RoleDef,
+  route: OpenRouterEndpointRecord | null,
+  cacheHitRate: number,
+  lambda: number,
+  levelFactor: number,
+  qW: number,
+): { q: number; priceEff: number; value: number; parts: Record<string, number> } | null {
+  const basePrice = route !== null ? routeEffectivePrice(route, cacheHitRate) : em.price;
+  if (basePrice == null) return null;
+  const priceEff = levelFactor === 1 ? basePrice : thinkingAdjustedPrice(em, def, basePrice);
+  let q = 0;
+  const parts: Record<string, number> = {};
+  for (const [metric, w] of Object.entries(def.weights)) {
+    if (metric === "price") continue; // cost enters as the λ·$ penalty, not the blend
+    const raw = roleMetricValue(em, metric, route, cacheHitRate);
+    if (raw == null) {
+      // Sparse capability metrics are capability-filled (below-median, not 0)
+      // so absence is not a coverage penalty; every other metric contributes
+      // nothing when missing.
+      const fill = CAPABILITY_FILL[metric];
+      if (fill === undefined) continue;
+      const contrib = (w / qW) * fill;
+      parts[metric] = contrib;
+      q += contrib;
+      continue;
+    }
+    const contrib = (w / qW) * cardinalMetric(metric, raw);
+    parts[metric] = contrib;
+    q += contrib;
+  }
+  return { q, priceEff, value: q - lambda * priceEff, parts };
+}
+
+/** The model's routes that are candidates for the role's soft best-route basis,
+ * sorted by the value-for-money score desc (ties: providerSlug asc, id asc). A
+ * candidate is non-degraded (status === 0), passes
+ * `routePassesEndpointFilters(route, def.filters)`, has a usable billed price,
+ * and (when `filters.maxPriceUsdPerM > 0`) a thinking-adjusted price at or below
+ * the cap.
+ *
+ * The score is `vfm = wT·tNorm − wP·pNorm`, where `tNorm`/`pNorm` are the
+ * route's p50 throughput and cache-adjusted billed price min/max-normalized over
+ * the candidate set, and `wT = wTput/(wPrice+wTput)`, `wP = wPrice/(wPrice+wTput)`.
+ * A route with no p50 uses the model's blended throughput (an absent p50 is
+ * unknown, not slow). `filters.preferredMinThroughput` is a SOFT floor: routes at
+ * or above it sort before routes below it, but are never dropped. */
+export function rankedRoutes(model: Model, def: RoleDef): OpenRouterEndpointRecord[] {
+  const cacheHitRate = def.cacheHitRate ?? 0;
+  const cap = def.filters?.maxPriceUsdPerM ?? 0;
+  const floor = def.filters?.preferredMinThroughput ?? 0;
+  const out = (model.routes ?? []).filter((r) => {
+    if (r.status !== 0) return false;
+    if (!routePassesEndpointFilters(r, def.filters)) return false;
+    const p = routeEffectivePrice(r, cacheHitRate);
+    if (p === null || p <= 0) return false;
+    if (cap > 0 && thinkingAdjustedPrice(model, def, p) > cap) return false;
+    return true;
+  });
+  if (out.length === 0) return [];
+  // A route with no p50 falls back to the model's blended throughput over the
+  // endpoint-filtered pool — the same basis `roleMetricValue` used before.
+  const em = endpointFilteredModel(model, def.filters, cacheHitRate) ?? model;
+  const wTput = def.weights.throughput ?? 0;
+  const wPrice = def.weights.price ?? 0;
+  const wSum = wTput + wPrice;
+  const wT = wSum > 0 ? wTput / wSum : 0;
+  const wP = wSum > 0 ? wPrice / wSum : 0;
+  // Decorate-sort-undecorate: the throughput/price lookups are not free, so
+  // compute each route's terms once.
+  const decorated = out.map((route) => ({
+    route,
+    tput: roleMetricValue(em, "throughput", route, cacheHitRate) ?? 0,
+    priceEff: routeEffectivePrice(route, cacheHitRate) as number,
+  }));
+  const tMin = Math.min(...decorated.map((d) => d.tput));
+  const tMax = Math.max(...decorated.map((d) => d.tput));
+  const pMin = Math.min(...decorated.map((d) => d.priceEff));
+  const pMax = Math.max(...decorated.map((d) => d.priceEff));
+  const tSpan = tMax - tMin;
+  const pSpan = pMax - pMin;
+  return decorated
+    .map((d) => {
+      const tNorm = tSpan > 0 ? (d.tput - tMin) / tSpan : 0;
+      const pNorm = pSpan > 0 ? (d.priceEff - pMin) / pSpan : 0;
+      return { route: d.route, score: wT * tNorm - wP * pNorm, aboveFloor: floor <= 0 || d.tput >= floor };
+    })
+    .sort((a, b) => {
+      if (a.aboveFloor !== b.aboveFloor) return a.aboveFloor ? -1 : 1;
+      if (a.score !== b.score) return b.score - a.score;
+      if (a.route.providerSlug !== b.route.providerSlug) return a.route.providerSlug < b.route.providerSlug ? -1 : 1;
+      return a.route.id < b.route.id ? -1 : a.route.id > b.route.id ? 1 : 0;
+    })
+    .map((d) => d.route);
+}
+
+/** `rankedRoutes(model, def)[0]` or null. The auto-pin slug and the soft basis. */
+export function bestRoute(model: Model, def: RoleDef): OpenRouterEndpointRecord | null {
+  return rankedRoutes(model, def)[0] ?? null;
+}
+
+/** True when the role's soft best-route basis applies: the `preferOwnProvider`
+ * capability is on and no manual `providerPin` overrides it. The soft basis the
+ * engine prices on and the auto-pin the updater writes share this predicate. */
+export function autoPinApplies(def: RoleDef): boolean {
+  return def.providerPin === undefined && def.preferOwnProvider === true;
+}
+
+/** The route a role prices a model on: the hard pin's route when the role is
+ * pinned, else the model's best route by the role's own value when the soft
+ * `preferOwnProvider` preference is on, else null (the 1/price² blend). A
+ * preference never drops a model — a model with no candidate route keeps the
+ * blend. */
+export function roleRoute(model: Model, def: RoleDef): OpenRouterEndpointRecord | null {
+  const pin = pinnedRoute(model, def.providerPin);
+  if (pin !== null) return pin;
+  if (!autoPinApplies(def)) return null;
+  return bestRoute(model, def);
+}
+
+/** The metric value a role sees for a model. A pinned role's throughput is its
+ * route's p50, falling back to the model's blended throughput when the route has
+ * no p50 (a sparse route must not zero the metric), and its price is the route's
+ * cache-adjusted billed price (`routeEffectivePrice`); every other metric is the
+ * model's own. */
+export function roleMetricValue(m: Model, metric: string, route: OpenRouterEndpointRecord | null, cacheHitRate = 0): number | null {
+  if (route !== null) {
+    if (metric === "throughput") return route.tput ?? m.throughput;
+    if (metric === "price") return routeEffectivePrice(route, cacheHitRate);
+  }
+  return m.metrics[metric];
+}
+
+/** Ranking ids dropped by the role's provider pin: they pass every other
+ * eligibility gate (required metrics, image, billed price, endpoint filters) but
+ * have no route matching the pin, so the request cannot be routed to it. For the
+ * decision log; empty when the role is unpinned. */
+export function providerPinDrops(def: RoleDef, models: Model[]): string[] {
+  if (def.providerPin === undefined) return [];
+  return models
+    .filter(
+      (m) =>
+        def.required.every((k) => m.metrics[k] != null) &&
+        !(def.filters?.image && !m.multimodal) &&
+        m.price != null &&
+        modelPassesEndpointFilters(m, def.filters) &&
+        pinnedRoute(m, def.providerPin) === null,
+    )
+    .map((m) => m.id);
+}
+
 export function rankRole(def: RoleDef, models: Model[]): Ranked[] {
   const wPrice = def.weights.price ?? 0;
   const qW = 1 - wPrice;
   const lambda = roleLambda(def);
   const levelFactor = def.thinking === undefined ? 1 : thinkingPriceFactor(def.thinking);
+  // Assumed cache-hit rate (0 = off): blends each route's cache-read price into
+  // its billed price. 0 makes every cache path byte-identical to the uncached one.
+  const cacheHitRate = def.cacheHitRate ?? 0;
   const ranked: Ranked[] = [];
   for (const m of models) {
-    if (def.required.some((k) => m.metrics[k] == null)) continue;
     if (def.filters?.image && !m.multimodal) continue;
-    if (m.price == null) continue; // value needs a billed price
-
-    // The factor assumes the model runs at the role's level. omp clamps
-    // unsupported levels, so a model whose catalog thinking[] excludes the
-    // level is priced bare — matching the updater, which appends no suffix in
-    // that case. Catalog data wins when present; without it (standalone
-    // ranking), the OR supports_reasoning flag gates.
-    const levels = m.thinkingLevels;
-    const runsAtLevel = levels
-      ? levels.length > 0 && (def.thinking === undefined || META_LEVELS[def.thinking] === true || levels.includes(def.thinking))
-      : m.thinking;
-    const priceEff = levelFactor === 1 || !runsAtLevel ? m.price : m.price * levelFactor;
-
-    let q = 0;
-    const parts: Record<string, number> = {};
-    for (const [metric, w] of Object.entries(def.weights)) {
-      if (metric === "price") continue; // cost enters as the λ·$ penalty, not the blend
-      const raw = m.metrics[metric];
-      if (raw == null) {
-        // Sparse capability metrics are capability-filled (below-median, not 0)
-        // so absence is not a coverage penalty; every other metric contributes
-        // nothing when missing.
-        const fill = CAPABILITY_FILL[metric];
-        if (fill === undefined) continue;
-        const contrib = (w / qW) * fill;
-        parts[metric] = contrib;
-        q += contrib;
-        continue;
-      }
-      const contrib = (w / qW) * cardinalMetric(metric, raw);
-      parts[metric] = contrib;
-      q += contrib;
+    // Provider pin: a pinned role prices and gates on the model's matching route,
+    // not the 1/price² blend. A model with no matching route cannot be routed to
+    // the pin and is ineligible (recorded by `providerPinDrops`).
+    const pinRoute = pinnedRoute(m, def.providerPin);
+    if (def.providerPin !== undefined && pinRoute === null) continue;
+    // Soft best-route preference (issue #40, re-based by #58): with no hard pin,
+    // a role that prefers a bound route is priced on the model's best route by
+    // the role's own value, else on the 1/price² blend. This is a preference,
+    // never a gate: a model with no candidate route keeps the blend, so the
+    // eligible count is unchanged. `providerPinDrops`/`pinUnmatched` key on
+    // `def.providerPin` only, so the preference never drops a model.
+    const route = roleRoute(m, def);
+    // Endpoint capability gate: a role that declares endpoint filters is priced on
+    // the 1/price² blend over the routes that survive them — the pool the router
+    // would actually choose from. A model whose every route fails (or that has no
+    // route data) has no such pool and is ineligible; the find-route fallback does
+    // not resurrect it. No endpoint filter leaves the model's own blend unchanged.
+    // A cache-hit rate recomputes the blend over the same pool with the cache-read
+    // price blended per route.
+    const em = endpointFilteredModel(m, def.filters, cacheHitRate);
+    if (em === null) continue;
+    // The required-metric gate keys on the hard pin only (null when unpinned), so
+    // the soft best-route preference can never change eligibility — it only
+    // re-prices a model that already passes every gate.
+    if (def.required.some((k) => roleMetricValue(em, k, pinRoute, cacheHitRate) == null)) continue;
+    // The role's value on its route basis (the pin's route, the soft best route,
+    // or the 1/price² blend). Null when the model has no usable billed price.
+    const rv = roleValueOnRoute(em, def, route, cacheHitRate, lambda, levelFactor, qW);
+    if (rv === null) continue;
+    // maxPriceUsdPerM caps the model's own price basis, never the soft best-route
+    // basis: with no hard pin the gate uses the model's blend price (thinking-
+    // adjusted), so enabling `preferOwnProvider` cannot change eligibility. A hard
+    // pin keeps gating its route price — the price the request actually pays. 0 = off.
+    const cap = def.filters?.maxPriceUsdPerM ?? 0;
+    if (cap > 0) {
+      const capBase = pinRoute !== null ? routeEffectivePrice(pinRoute, cacheHitRate) : em.price;
+      if (capBase != null && thinkingAdjustedPrice(em, def, capBase) > cap) continue;
     }
-    ranked.push({ model: m, value: q - lambda * priceEff, q, priceEff, parts });
+    ranked.push({ model: em, value: rv.value, q: rv.q, priceEff: rv.priceEff, parts: rv.parts });
   }
   ranked.sort((a, b) => b.value - a.value);
   return ranked;
@@ -973,8 +1393,9 @@ export function writeOrCache(path: string, fetchedAt: string, data: object, mode
 
 type EndpointsCacheFile = { fetchedAt: string; source: string; slugCount: number; slugs: OpenRouterEndpointPages };
 
-/** Daily cache: current when fetchedAt is the current UTC day; requireFresh=false accepts stale. */
-function readEndpointsCache(path: string, requireFresh: boolean): EndpointsCacheFile | null {
+/** Daily cache: current when fetchedAt is the current UTC day; requireFresh=false accepts stale.
+ * Exported for the shape-guard test (a cache predating a narrowed field must be rejected). */
+export function readEndpointsCache(path: string, requireFresh: boolean): EndpointsCacheFile | null {
   let parsed: EndpointsCacheFile;
   try {
     parsed = JSON.parse(readFileSync(path, "utf8")) as EndpointsCacheFile;
@@ -982,6 +1403,23 @@ function readEndpointsCache(path: string, requireFresh: boolean): EndpointsCache
     return null;
   }
   if (typeof parsed?.slugs !== "object" || parsed.slugs === null || Object.keys(parsed.slugs).length === 0) return null;
+  // Records narrowed before the input-price weight basis lack `weightPrice`; refetch rather than
+  // silently dropping every route from the blend (the old cache cannot supply the router's sort key).
+  // Records narrowed before the endpoint capability ceilings lack `contextLength`; refetch so the
+  // role gate reads real values instead of treating every route's ceiling as unstated (null).
+  // Records narrowed before the cache-read price lack `cacheReadPrice`; refetch so a role's
+  // `cacheHitRate` reads real values instead of treating every route's cache price as unstated
+  // (null → full input price, which would leave the knob silently inert for the rest of the day).
+  const sample = Object.values(parsed.slugs).find((recs) => Array.isArray(recs) && recs.length > 0)?.[0];
+  if (
+    typeof sample !== "object" ||
+    sample === null ||
+    !("weightPrice" in sample) ||
+    !("contextLength" in sample) ||
+    !("cacheReadPrice" in sample)
+  ) {
+    return null;
+  }
   if (requireFresh && parsed.fetchedAt?.slice(0, 10) !== new Date().toISOString().slice(0, 10)) return null;
   return parsed;
 }
@@ -1157,18 +1595,21 @@ async function loadDesignArenaBoards(refresh: boolean): Promise<{ website: Desig
  * falls back to a stale cache (non-fatal — affected models just go unranked).
  * Throws only when llm-stats has neither fresh cache nor a usable fetch (§9 abort).
  */
-export async function loadRankData(opts?: { refresh?: boolean; url?: string; roles?: Record<string, RoleDef> }): Promise<RankData> {
+export async function loadRankData(opts?: { refresh?: boolean; url?: string; roles?: Record<string, RoleDef>; extraMetrics?: readonly string[] }): Promise<RankData> {
   const refresh = opts?.refresh ?? false;
   const url = opts?.url ?? DEFAULT_URL;
+  const extraMetrics = new Set(opts?.extraMetrics ?? []);
   // Design Arena is the only source a role can depend on exclusively (`website`).
   // When the caller names the roles it will rank and none weights `website`, skip
   // the endpoint fetch entirely — the OpenRouter mirror (part of the find payload
   // fetched anyway) still populates `designElo`. Undefined roles = fetch (the
-  // standalone default, e.g. a caller that ranks every shipped role).
-  const needsDesignArena = opts?.roles === undefined || Object.values(opts.roles).some((r) => r.weights.website !== undefined);
+  // standalone default, e.g. a caller that ranks every shipped role). An
+  // `extraMetrics` entry forces the fetch too: the explorer's UI can weight any
+  // shipped metric, so it passes the shipped keys even when no role weights them.
+  const needsDesignArena = opts?.roles === undefined || extraMetrics.has("website") || Object.values(opts.roles).some((r) => r.weights.website !== undefined);
   // The writing leaderboard is the only source a role can depend on exclusively
   // (`writing`); skip its fetch when no ranked role weights it.
-  const needsWriting = opts?.roles === undefined || Object.values(opts.roles).some((r) => r.weights.writing !== undefined);
+  const needsWriting = opts?.roles === undefined || extraMetrics.has("writing") || Object.values(opts.roles).some((r) => r.weights.writing !== undefined);
 
   const cached = refresh ? null : readCache(CACHE_PATH);
   let rows: LlmStatsRow[];
@@ -1310,8 +1751,10 @@ export async function loadRankData(opts?: { refresh?: boolean; url?: string; rol
   // does not ship resolves through the benchmark-source registry (a declared
   // source, or the generic llm-stats benchmark). Fetched only when a ranked role
   // weights the metric; `opts.roles === undefined` fetches every declared source.
-  // Non-fatal: a source that fails leaves its metric unfilled and the role ranks
-  // on the rest of its weights.
+  // `extraMetrics` adds metrics no role weights (the explorer's UI can weight any
+  // shipped key, so it passes them to keep its dataset a superset of any def it
+  // can rank). Non-fatal: a source that fails leaves its metric unfilled and the
+  // role ranks on the rest of its weights.
   const declared = loadDeclaredSources();
   const externalMetrics = new Set<string>();
   if (opts?.roles === undefined) {
@@ -1321,6 +1764,7 @@ export async function loadRankData(opts?: { refresh?: boolean; url?: string; rol
       for (const metric of Object.keys(def.weights)) externalMetrics.add(metric);
     }
   }
+  for (const metric of extraMetrics) externalMetrics.add(metric);
   for (const metric of externalMetrics) {
     const source = sourceForMetric(metric, declared);
     if (source === null || source.external !== true || source.fetch === undefined) continue;