model-compare-opencode-plugin 0.1.3 → 0.4.0

package/vendor/model_compare.py

@@ -54,6 +54,7 @@ import time
 import urllib.error
 import urllib.parse
 import urllib.request
+from concurrent.futures import ThreadPoolExecutor
 from datetime import datetime, timezone
 
 OPENROUTER_MODELS_URL = "https://openrouter.ai/api/v1/models"
@@ -67,7 +68,23 @@ OPENROUTER_ZDR_URL = "https://openrouter.ai/api/v1/endpoints/zdr"
 # (legacy endpoints 410 after 2026-11-04; see
 # https://artificialanalysis.ai/data-api/migrate-v2-data).
 AA_API_URL = "https://artificialanalysis.ai/api/v2/language/models/free"
-VERSION = "0.3.1"
+# Cache key for the AA API entries envelope. v3 adds the per-fetch `as_of`
+# timestamp on every entry and the envelope's intelligence_index_version;
+# payloads under the pre-v3 keys predate those fields and must never be read.
+AA_ENTRIES_CACHE = "aa-intelligence-v3"
+# The repo's own published catalog.json -- built by keyed CI runs, hydrated
+# by unkeyed local runs (design: quality source reconciliation, source 2).
+# The github.io host 301s to plain http://model-compare.dev/catalog.json, an
+# unauthenticated downgrade on ranking-critical data; the https direct URL is
+# verified 200 application/json. Do not point this back at github.io.
+QUALITY_CATALOG_URL = "https://model-compare.dev/catalog.json"
+# Cache key for the hydration envelope {"by_id", "generated_at",
+# "schema_version"}. Only usable (non-empty by_id) results are ever written.
+QUALITY_CATALOG_CACHE = "published-catalog"
+# A published catalog generated more than this many days ago is stale:
+# warn but use -- the records' as_of makes the staleness visible downstream.
+QUALITY_CATALOG_MAX_AGE_DAYS = 14
+VERSION = "0.5.0"
 USER_AGENT = f"model-compare/{VERSION} (https://github.com/canonical/model-compare)"
 
 # opencode expects provider-qualified model ids: openrouter/<provider/model>.
@@ -86,11 +103,15 @@ PRIORITY_WEIGHTS = {
     "quality": {"quality": 0.60, "price": 0.20, "context": 0.10, "age": 0.10},
 }
 
-CATALOG_SCHEMA_VERSION = 2
+CATALOG_SCHEMA_VERSION = 4
 
 # The drop-reason keys build_candidates counts, verbatim -- keep in sync with
 # its drop() call sites. pool.dropped lists all of them zero-filled so the
-# contract is self-describing.
+# contract is self-describing. The last two come from the endpoint stage
+# (apply_endpoint_pricing's drop sites), not build_candidates: snake_case
+# while the older reasons are human phrases. The mixed naming convention is
+# a deliberate, documented extension -- machine-readable reasons for the
+# endpoint-stage drops the publish drop-rate gate keys on.
 CATALOG_DROP_REASONS = (
     "malformed id",
     "context",
@@ -104,11 +125,74 @@ CATALOG_DROP_REASONS = (
     "tool calling",
     "expired",
     "age",
+    "no_baseline_eligible_endpoint",
+    "endpoint_fetch_failed",
+)
+
+# The only reasons the endpoint stage itself produces (the last two
+# CATALOG_DROP_REASONS entries) -- the empty-pool warning keys on them;
+# web/publish.py keeps its own copy of this tuple by design.
+ENDPOINT_DROP_REASONS = (
+    "no_baseline_eligible_endpoint",
+    "endpoint_fetch_failed",
 )
 
 PAREN_RE = re.compile(r"\([^)]*\)")
 PROVIDER_PREFIX_RE = re.compile(r"^[^:\s]{1,30}:\s*")
 
+# Quantization precision ladder: label -> rank, highest fidelity first. The
+# ladder ordering in the design doc is authoritative: fp6 > int8 is strict,
+# and formats within one fidelity tier share the same rank. "unknown" never
+# enters the ladder -- it only routes through the first-party eligibility
+# carve-out, never through rank comparison.
+PRECISION_LADDER: dict[str, int] = {
+    "fp32": 4,
+    "bf16": 3,
+    "fp16": 3,
+    "fp8": 2,
+    "mxfp8": 2,
+    "fp6": 1,
+    "int8": 0,
+    "fp4": -1,
+    "mxfp4": -1,
+    "nvfp4": -1,
+    "int4": -2,
+}
+
+# Every quantization value an endpoint may report: the ladder keys plus the
+# "unknown" sentinel. Whether a recorded value is recognized at all is
+# membership here, not ladder rank.
+QUANTIZATION_ENUM: frozenset[str] = frozenset(PRECISION_LADDER) | {"unknown"}
+
+# Official partner hosts that serve closed labs' models: an endpoint on one
+# of these providers counts as first-party for the eligibility carve-out
+# even though it is not the maker itself. Entries are compared after
+# normalize_provider (casefold + strip non-alphanumerics), so the slugs here
+# are display forms -- "aws-bedrock" and "AWS Bedrock" both hit. Extend only
+# with live-data evidence (e.g. an endpoint tag matching <lab>-official).
+FIRST_PARTY_HOSTS = frozenset(
+    {"bedrock", "azure", "vertex", "azure-ai", "google-vertex", "aws-bedrock"}
+)
+
+# Explicit first-party alias pairs that normalization alone cannot bridge
+# (design §4.2): makers that self-name differently than their OpenRouter
+# author slug. Key = the exact live provider_name string, value = the
+# author slug the pair is first-party FOR; both sides are compared
+# normalized (case/punctuation variants match), and the alias only fires
+# when the model's author equals the value. Verified against live data
+# 2026-10-20 (task-13-fix-report.md section 8b; endpoints fetched fresh,
+# every endpoint quantization "unknown", status 0):
+#   ("Amazon Bedrock", "amazon")   -- amazon/nova-2-lite-v1, 2 endpoints
+#   ("Google AI Studio", "google") -- google/gemini-2.5-pro-preview, 3 endpoints
+#   ("Mistral", "mistralai")       -- mistralai/mistral-large-4-0, 3 endpoints
+# Add entries only after the same live verification -- never pin an
+# unverified string.
+FIRST_PARTY_ALIASES: dict[str, str] = {
+    "Amazon Bedrock": "amazon",
+    "Google AI Studio": "google",
+    "Mistral": "mistralai",
+}
+
 
 def warn(msg: str) -> None:
     print(f"warning: {msg}", file=sys.stderr)
@@ -118,6 +202,44 @@ def norm_key(s: str) -> str:
     return re.sub(r"[^a-z0-9]+", " ", (s or "").lower()).strip()
 
 
+# ---------------------------------------------------------------------------
+# Provider normalization + first-party detection
+# ---------------------------------------------------------------------------
+
+
+def normalize_provider(name: str) -> str:
+    """Casefold a provider name and strip ALL non-alphanumeric characters.
+
+    "Z.AI", "z-ai" and "z ai" all normalize to "zai", so a live-recorded
+    maker name matches its author slug regardless of punctuation or case.
+    None or empty input normalizes to "".
+    """
+    return re.sub(r"[^a-z0-9]+", "", (name or "").casefold())
+
+
+def is_first_party(provider_name: str, author: str) -> bool:
+    """True iff the provider is the model's own maker or a partner host.
+
+    Criterion 1: the normalized provider name equals the normalized author
+    slug. Criterion 2: it matches a normalized FIRST_PARTY_HOSTS entry, or
+    a FIRST_PARTY_ALIASES key whose value equals the normalized author slug
+    (the §4.2 alias pairs: a maker self-naming differently than its author
+    slug is first-party only for that author). Everything else is
+    third-party.
+    """
+    provider = normalize_provider(provider_name)
+    if provider == normalize_provider(author):
+        return True
+    if provider in {normalize_provider(host) for host in FIRST_PARTY_HOSTS}:
+        return True
+    author_slug = normalize_provider(author)
+    return any(
+        provider == normalize_provider(alias_provider)
+        and author_slug == normalize_provider(alias_author)
+        for alias_provider, alias_author in FIRST_PARTY_ALIASES.items()
+    )
+
+
 # ---------------------------------------------------------------------------
 # HTTP + cache
 # ---------------------------------------------------------------------------
@@ -224,6 +346,1049 @@ def save_cache(name: str, payload) -> None:
         warn(f"could not write cache: {exc}")
 
 
+# ---------------------------------------------------------------------------
+# OpenRouter endpoints (per-model provider list)
+# ---------------------------------------------------------------------------
+
+
+OPENROUTER_ENDPOINTS_URL = "https://openrouter.ai/api/v1/models/{id}/endpoints"
+
+
+def load_cache_expired(name: str) -> dict | None:
+    """Return the cached payload regardless of age; None when absent/corrupt.
+
+    load_cache drops payloads past their TTL; this variant serves them anyway
+    so a dropped model's last known endpoint annotations can still be shown
+    (marked stale by the caller). Never used for ranking.
+    """
+    path = cache_path(name)
+    if not path:
+        return None
+    try:
+        with open(path) as fh:
+            blob = json.load(fh)
+        return blob["payload"]
+    except (OSError, ValueError, KeyError, TypeError):
+        return None
+
+
+def parse_endpoints(payload) -> list[dict]:
+    """Keep the verified per-endpoint fields of an endpoints response.
+
+    The live GET /api/v1/models/{id}/endpoints response nests the list one
+    level below the usual envelope: `data` is the model object (id, name,
+    architecture, ...) and the per-provider entries live in
+    `data["endpoints"]`. `pricing` keeps prompt/completion (parsed through
+    parse_price) and the raw `overrides` list -- the tiered-pricing
+    machinery parses the entries itself. Fields beyond the verified
+    per-entry shape are dropped, and the parse keeps `status` as-is (the
+    caller filters).
+    """
+    # Task 13 lesson: the first unit fixtures fed the models/find shape
+    # ({"data": [entry, ...]}) -- a list directly under "data" -- so the
+    # suite stayed green while every live parse returned [] and the whole
+    # pool died as no_baseline_eligible_endpoint. Pin the live envelope:
+    # the list is read ONLY from data["endpoints"], and every other shape
+    # parses to [] (no compat branch for the wrong fixture shape).
+    data = payload.get("data") if isinstance(payload, dict) else None
+    entries = data.get("endpoints") if isinstance(data, dict) else None
+    endpoints = []
+    for entry in entries or []:
+        if not isinstance(entry, dict):
+            continue
+        raw = entry.get("pricing")
+        raw_pricing = raw if isinstance(raw, dict) else {}
+        endpoints.append(
+            {
+                "provider_name": entry.get("provider_name"),
+                "tag": entry.get("tag"),
+                "quantization": entry.get("quantization"),
+                "pricing": {
+                    "prompt": parse_price(raw_pricing.get("prompt")),
+                    "completion": parse_price(raw_pricing.get("completion")),
+                    "overrides": raw_pricing.get("overrides"),
+                },
+                "context_length": entry.get("context_length"),
+                "status": entry.get("status"),
+                "service_tier": entry.get("service_tier"),
+            }
+        )
+    return endpoints
+
+
+def fetch_model_endpoints(model_id: str, args) -> list[dict]:
+    """Fetch + parse one model's endpoint list, cached per model.
+
+    The cache name flattens the model id ("/" -> "_") to keep the cache
+    files flat. Fetches retry 3 times (4 attempts total) via fetch_json,
+    which raises at once on 4xx and after the retries on 5xx/network
+    errors -- the caller owns the fail-closed policy.
+    """
+    cache_name = f"endpoints:{model_id.replace('/', '_')}"
+    if not args.no_cache:
+        cached = load_cache(cache_name, args.cache_ttl)
+        if cached:
+            return cached
+    payload = fetch_json(
+        OPENROUTER_ENDPOINTS_URL.format(id=model_id), timeout=30, retries=3
+    )
+    endpoints = parse_endpoints(payload)
+    save_cache(cache_name, endpoints)
+    return endpoints
+
+
+def is_variant_endpoint(endpoint) -> bool:
+    """True iff the endpoint is a :free/:batch variant or entirely free.
+
+    Variant iff its slug or tag carries a `:free`/`:batch` marker OR both
+    input and output prices are zero. `:batch` is cheaper-but-restricted,
+    not zero-priced -- only the marker test catches it. Missing or
+    unparseable prices are not zero.
+    """
+    for field in ("slug", "tag"):
+        marker = endpoint.get(field)
+        if isinstance(marker, str) and (":free" in marker or ":batch" in marker):
+            return True
+    pricing = endpoint.get("pricing")
+    prices = pricing if isinstance(pricing, dict) else {}
+    return (
+        parse_price(prices.get("prompt")) == 0.0
+        and parse_price(prices.get("completion")) == 0.0
+    )
+
+
+def endpoint_schedule_ok(endpoint, args) -> bool:
+    """False iff the endpoint's pricing.overrides fails the v2 schedule rule.
+
+    Reuses effective_pricing in full: the gate fires on malformed windows,
+    exactly-one-of utc_start/utc_end pairs, bad utc_days, combined
+    token+time entries and missing inheritance -- not just non-tiling
+    windows. An endpoint without overrides has no schedule to fail.
+    """
+    result = effective_pricing(
+        endpoint.get("pricing"), args.min_context, args.input_share
+    )
+    return not result["schedule_error"]
+
+
+# Schedule gate for args-less callers: effective_pricing's schedule_error
+# depends only on the SHAPE of pricing.overrides (malformed windows, bad
+# utc_days, ...), never on min_context/input_share -- those only affect the
+# resolved prices. derive_default_precision has no args parameter (pinned
+# interface), so it gates through this fixed stand-in; any args would give
+# the same schedule_error verdict.
+_SCHEDULE_GATE_ARGS = argparse.Namespace(min_context=0, input_share=0.75)
+
+
+def _baseline_universe(endpoints: list[dict], args=None) -> list[dict]:
+    """The shared derivation universe (design section 4.1).
+
+    Live (status == 0), not a variant endpoint (:free/:batch marker or
+    zero-priced), and passing the schedule gate. Schedule-broken endpoints
+    must not pin the default that governs healthy endpoints, same rationale
+    as the variant exclusion. args defaults to the structural stand-in
+    (see _SCHEDULE_GATE_ARGS); callers with real args pass them.
+    """
+    if args is None:
+        args = _SCHEDULE_GATE_ARGS
+    return [
+        endpoint
+        for endpoint in endpoints
+        if endpoint.get("status") == 0
+        and not is_variant_endpoint(endpoint)
+        and endpoint_schedule_ok(endpoint, args)
+    ]
+
+
+def derive_default_precision(endpoints: list[dict], author: str) -> str | None:
+    """Derive a model's default precision from its endpoint list (section 4.1).
+
+    Universe: live non-variant schedule-passing endpoints (_baseline_universe).
+    Primary rule: the highest-ranked KNOWN quantization among the maker's
+    endpoints -- matched by normalized author-slug equality only, so partner
+    hosts never pin the maker's default (section 4.2 criterion 2 does not
+    apply here). Fallback: when the maker has no known quantization, the
+    highest-ranked known quantization across the FULL universe (partners
+    included -- best-available). None when no endpoint in the universe has a
+    known quantization (the all-unknown closed-model case): eligibility then
+    relies solely on the first-party carve-out.
+
+    Known means a PRECISION_LADDER key: "unknown" and unparseable/absent
+    values never enter the ladder. An endpoint whose provider_name is
+    absent/empty (or normalizes to empty) is skipped for maker matching
+    (never first-party -- fail-closed), but still feeds the fallback
+    universe.
+    """
+    universe = _baseline_universe(endpoints, _SCHEDULE_GATE_ARGS)
+    maker = normalize_provider(author)
+    maker_best = None
+    fallback_best = None
+    for endpoint in universe:
+        quantization = endpoint.get("quantization")
+        if not isinstance(quantization, str) or quantization not in PRECISION_LADDER:
+            continue  # "unknown", null, unrecognized: no rank, no pinning
+        rank = PRECISION_LADDER[quantization]
+        if fallback_best is None or rank > fallback_best[0]:
+            fallback_best = (rank, quantization)
+        # Maker matching only: a provider_name that normalizes to nothing
+        # must never match an (equally empty) author slug.
+        provider_slug = (
+            normalize_provider(endpoint.get("provider_name"))
+            if isinstance(endpoint.get("provider_name"), str)
+            else ""
+        )
+        if (
+            provider_slug
+            and provider_slug == maker
+            and (maker_best is None or rank > maker_best[0])
+        ):
+            maker_best = (rank, quantization)
+    return (maker_best or fallback_best or (None, None))[1]
+
+
+def baseline_eligible(endpoint, default_precision, author, args) -> bool:
+    """Baseline-eligibility rule (design section 4.3, fail-closed).
+
+    True iff the endpoint is live (status == 0), not a variant, passes the
+    schedule gate, and then either:
+
+    * its quantization is a known ladder label with rank >=
+      rank(default_precision) -- provider-blind (default_routing considers
+      every endpoint OpenRouter may send traffic to), or
+    * its quantization is "unknown" or null AND the endpoint is first-party
+      (the D3 carve-out: the maker or a partner host).
+
+    When default_precision is None (all-unknown model) the rank comparison is
+    meaningless -- only the carve-out applies. A provider_name that is
+    absent/empty (or normalizes to empty) is never first-party, so such an
+    endpoint can only qualify through the rank branch. An unrecognized
+    quantization string (neither a ladder label nor "unknown"/null) is a
+    schema anomaly: no rank comparison and no carve-out -- fail-closed
+    (fleet-wide new-label drift is what the publish drop-rate gate exists
+    to catch).
+    """
+    if (
+        endpoint.get("status") != 0
+        or is_variant_endpoint(endpoint)
+        or not endpoint_schedule_ok(endpoint, args)
+    ):
+        return False
+    quantization = endpoint.get("quantization")
+    if isinstance(quantization, str) and quantization in PRECISION_LADDER:
+        # Known quantization: the rank branch, provider-blind.
+        if default_precision is None:
+            return False
+        return PRECISION_LADDER[quantization] >= PRECISION_LADDER[default_precision]
+    # Unverifiable: the carve-out applies to "unknown" and null only --
+    # an unrecognized string fails closed. A provider_name that normalizes
+    # to nothing is never first-party (fail-closed; the literal
+    # is_first_party("", "") iff is guarded out here).
+    provider_name = endpoint.get("provider_name")
+    provider_slug = (
+        normalize_provider(provider_name) if isinstance(provider_name, str) else ""
+    )
+    return (
+        (quantization is None or quantization == "unknown")
+        and bool(provider_slug)
+        and is_first_party(provider_name, author)
+    )
+
+
+def pick_baseline(
+    endpoints: list[dict], eligible_flags: list[bool], args
+) -> dict | None:
+    """Pick the baseline endpoint among the eligible ones (design section 4.5).
+
+    Cheapest blended per-token price wins, computed from effective_pricing
+    with the args' min_context and input_share (the shared --input-share
+    convention). Ties broken by (normalized provider name, tag), then --
+    still tied -- first in list order (deterministic; Python's sort is
+    stable and the endpoints list order is the API's). Returns None when no
+    eligible endpoint has a usable price (the caller owns the drop).
+    """
+    candidates = []
+    for endpoint, eligible in zip(endpoints, eligible_flags):
+        if not eligible:
+            continue
+        eff = effective_pricing(
+            endpoint.get("pricing"), args.min_context, args.input_share
+        )
+        price_in, price_out = eff["price_in"], eff["price_out"]
+        if (
+            price_in is None
+            or price_out is None
+            or not math.isfinite(price_in)
+            or not math.isfinite(price_out)
+        ):
+            continue  # unpriceable: no executable blended price
+        blended = args.input_share * price_in + (1 - args.input_share) * price_out
+        provider_name = endpoint.get("provider_name")
+        candidates.append(
+            (
+                blended,
+                normalize_provider(provider_name)
+                if isinstance(provider_name, str)
+                else "",
+                endpoint.get("tag") or "",
+                endpoint,
+            )
+        )
+    if not candidates:
+        return None
+    return min(candidates, key=lambda candidate: candidate[:3])[3]
+
+
+def _blended_price(endpoint, args) -> float | None:
+    """Blended per-token price of one endpoint (pick_baseline's price rule).
+
+    effective_pricing with the args' min_context and input_share, then
+    input_share * price_in + (1 - input_share) * price_out. None when either
+    resolved price is missing or non-finite -- no executable blended price,
+    the same skip pick_baseline applies. A zero result is returned as-is:
+    zero-priced endpoints are variants (already excluded upstream), so the
+    callers apply their own zero guards defensively.
+    """
+    eff = effective_pricing(endpoint.get("pricing"), args.min_context, args.input_share)
+    price_in, price_out = eff["price_in"], eff["price_out"]
+    if (
+        price_in is None
+        or price_out is None
+        or not math.isfinite(price_in)
+        or not math.isfinite(price_out)
+    ):
+        return None
+    blended = args.input_share * price_in + (1 - args.input_share) * price_out
+    return blended if math.isfinite(blended) else None
+
+
+def _flag_list(endpoints: list[dict], eligible_flags: list[bool]):
+    """Zip endpoints with their parallel eligibility flags, hardened.
+
+    eligible_flags is a parallel list to endpoints (the baseline_eligible
+    verdict per endpoint, same order -- Task 4 contract). A length mismatch
+    must raise, never truncate silently (Task 4 review ruling).
+    """
+    if len(endpoints) != len(eligible_flags):
+        raise ValueError(
+            "eligible_flags must be a parallel list to endpoints: "
+            f"{len(endpoints)} endpoints, {len(eligible_flags)} flags"
+        )
+    return zip(endpoints, eligible_flags, strict=True)
+
+
+def NON_ELIGIBLE_UNIVERSE(endpoints: list[dict], eligible_flags: list[bool]) -> list:
+    """The shared annotations universe (design section 4.6).
+
+    Live (status == 0), non-variant endpoints that are NOT baseline-eligible:
+    sub-default known quantization, third-party unknown/null quantization, or
+    schedule-gate-failed. All annotations derive from this one universe.
+    Eligibility comes from the parallel eligible_flags list (the
+    baseline_eligible verdicts); variants and non-live endpoints are excluded
+    even though they too are not eligible -- unlike the steering `ignore`
+    list, which includes live variants (section 4.7).
+
+    Raises ValueError when eligible_flags does not match endpoints in length.
+    """
+    return [
+        endpoint
+        for endpoint, eligible in _flag_list(endpoints, eligible_flags)
+        if endpoint.get("status") == 0
+        and not is_variant_endpoint(endpoint)
+        and not eligible
+    ]
+
+
+def build_annotations(
+    endpoints: list[dict],
+    eligible_flags: list[bool],
+    baseline,
+    catalog_context,
+    args,
+) -> dict:
+    """Per-model endpoint annotations (design section 4.6).
+
+    All four annotations derive from one shared universe -- the live
+    non-variant endpoints that are not baseline-eligible
+    (NON_ELIGIBLE_UNIVERSE):
+
+    * price_spread: cheapest non-eligible blended price divided by the
+      cheapest eligible blended price, both blended with the args'
+      min_context and input_share (the shared --input-share convention).
+      None when the universe is empty -- generalized to None when either
+      side has no priceable member at all -- and None when either cheapest
+      price is 0 (zero-priced endpoints are variants by definition, so the
+      zero half of the guard is defensive only). Unpriceable endpoints are
+      skipped when looking for a cheapest price.
+    * cheapest_quantized: {provider, quantization, price} of the cheapest
+      member of the quantization-caused subset of the universe -- endpoints
+      non-eligible due to quantization only (sub-default known quantization
+      or third-party unknown/null), NOT schedule-gate-failed ones, which are
+      excluded even when cheaper. Unpriceable subset members are skipped
+      (defensively also non-positive ones, matching the repo-wide treatment
+      of negative prices as malformed); None when the subset has no
+      priceable member. Price ties keep the first in list order
+      (deterministic).
+    * risk_flag: True iff the sum of 1/blended**2 over the universe strictly
+      exceeds the sum over the baseline-eligible endpoints (exact tie ->
+      False). Any endpoint whose blended price is 0/None (defensively also
+      negative) is skipped from BOTH sums -- variants are already excluded,
+      so this only guards malformed data, and the flag stays deterministic.
+    * baseline_context_below_catalog: True iff the baseline endpoint's
+      context_length is smaller than the catalog context (the models-API
+      value). A None baseline -- or missing context on either side -- yields
+      False: the caveat marks a positive finding, never missing data.
+
+    Raises ValueError when eligible_flags does not match endpoints in length.
+    """
+    universe = NON_ELIGIBLE_UNIVERSE(endpoints, eligible_flags)
+
+    universe_prices = []
+    for endpoint in universe:
+        price = _blended_price(endpoint, args)
+        if price is not None:
+            universe_prices.append(price)
+    eligible_prices = []
+    for endpoint, eligible in _flag_list(endpoints, eligible_flags):
+        if not eligible:
+            continue
+        price = _blended_price(endpoint, args)
+        if price is not None:
+            eligible_prices.append(price)
+    cheapest_non_eligible = min(universe_prices) if universe_prices else None
+    cheapest_eligible = min(eligible_prices) if eligible_prices else None
+    price_spread = (
+        cheapest_non_eligible / cheapest_eligible
+        if cheapest_non_eligible is not None
+        and cheapest_eligible is not None
+        and cheapest_non_eligible > 0
+        and cheapest_eligible > 0
+        else None
+    )
+
+    quantized_best = None
+    for endpoint in universe:
+        if not endpoint_schedule_ok(endpoint, args):
+            continue  # schedule-gate-failed: not a quantization-caused exclusion
+        price = _blended_price(endpoint, args)
+        if price is None or price <= 0:
+            continue  # unpriceable/non-positive: no comparable price
+        if quantized_best is None or price < quantized_best[0]:
+            quantized_best = (price, endpoint)  # ties keep the first in list order
+    if quantized_best is None:
+        cheapest_quantized = None
+    else:
+        price, endpoint = quantized_best
+        cheapest_quantized = {
+            "provider": endpoint.get("provider_name"),
+            "quantization": endpoint.get("quantization"),
+            "price": price,
+        }
+
+    non_eligible_weight = 0.0
+    for endpoint in universe:
+        price = _blended_price(endpoint, args)
+        if price is None or price <= 0:
+            continue  # skipped from BOTH sums, deterministically
+        non_eligible_weight += 1.0 / (price * price)
+    eligible_weight = 0.0
+    for endpoint, eligible in _flag_list(endpoints, eligible_flags):
+        if not eligible:
+            continue
+        price = _blended_price(endpoint, args)
+        if price is None or price <= 0:
+            continue
+        eligible_weight += 1.0 / (price * price)
+    risk_flag = non_eligible_weight > eligible_weight
+
+    baseline_context = baseline.get("context_length") if baseline is not None else None
+    baseline_context_below_catalog = (
+        baseline_context is not None
+        and catalog_context is not None
+        and baseline_context < catalog_context
+    )
+
+    return {
+        "price_spread": price_spread,
+        "cheapest_quantized": cheapest_quantized,
+        "risk_flag": risk_flag,
+        "baseline_context_below_catalog": baseline_context_below_catalog,
+    }
+
+
+def build_steering(
+    model_id: str,
+    endpoints: list[dict],
+    eligible_flags: list[bool],
+    default_precision: str | None,
+    args,
+) -> dict:
+    """OpenRouter provider steering object (design section 4.7).
+
+    {"model": model_id, "provider": {"order": [...], "ignore": [...],
+    "quantizations": [...], "allow_fallbacks": True}}.
+
+    * order: tags of the baseline-eligible endpoints, cheapest blended first
+      (blended price asc, ties broken by (normalized provider name, tag) --
+      the same comparator as pick_baseline, stable so the final tie is list
+      order). Eligible endpoints whose blended price is unpriceable cannot
+      be price-ranked; they are appended after the ranked ones (still
+      (provider, tag)-ordered) so every eligible endpoint keeps a place --
+      ranked last, never silently left to default priority.
+    * ignore: tags of EVERY live endpoint that is not baseline-eligible --
+      sub-default quantization, third-party unknown/null, schedule-gate-
+      failed AND variants (variants are live but not eligible; the universal
+      quantifier includes them). Non-live (status != 0) endpoints are never
+      listed. List order (the API's).
+    * quantizations: sorted KNOWN quantizations (PRECISION_LADDER labels)
+      with rank >= rank(default_precision) among live non-variant endpoints,
+      deduplicated -- no schedule or eligibility filter. OMITTED from the
+      provider dict entirely when default_precision is None -- never an
+      empty list (OpenRouter semantics would filter out every endpoint).
+    * allow_fallbacks: True.
+
+    Signature deviation from the plan (controller ruling at Task 5 spawn):
+    args is a required parameter -- the order ranking is real pricing math
+    (effective_pricing via min_context/input_share), and reusing the
+    shape-only _SCHEDULE_GATE_ARGS stand-in for pricing was explicitly
+    ruled out in the Task 4 review.
+
+    Raises ValueError when eligible_flags does not match endpoints in length.
+    """
+    ignore = []
+    ranked = []  # (blended, normalized provider name, tag) -- pick_baseline order
+    unranked = []  # (normalized provider name, tag) -- eligible but unpriceable
+    for endpoint, eligible in _flag_list(endpoints, eligible_flags):
+        if endpoint.get("status") == 0 and not eligible:
+            ignore.append(endpoint.get("tag") or "")
+        if not eligible:
+            continue
+        provider_name = endpoint.get("provider_name")
+        provider_key = (
+            normalize_provider(provider_name) if isinstance(provider_name, str) else ""
+        )
+        tag = endpoint.get("tag") or ""
+        price = _blended_price(endpoint, args)
+        if price is None:
+            unranked.append((provider_key, tag))
+        else:
+            ranked.append((price, provider_key, tag))
+    ranked.sort()  # stable: the final tie is list order, as in pick_baseline
+    order = [tag for _, _, tag in ranked] + [tag for _, tag in sorted(unranked)]
+
+    provider = {"order": order, "ignore": ignore}
+    if default_precision is not None:
+        default_rank = PRECISION_LADDER[default_precision]
+        quants = set()
+        for endpoint in endpoints:
+            if endpoint.get("status") != 0 or is_variant_endpoint(endpoint):
+                continue
+            quantization = endpoint.get("quantization")
+            if (
+                not isinstance(quantization, str)
+                or quantization not in PRECISION_LADDER
+            ):
+                continue  # "unknown"/null/unrecognized: not a known quantization
+            if PRECISION_LADDER[quantization] >= default_rank:
+                quants.add(quantization)
+        provider["quantizations"] = sorted(quants)
+    provider["allow_fallbacks"] = True
+    return {"model": model_id, "provider": provider}
+
+
+def _stale_filtered_annotations(model_id, catalog_context, args):
+    """Annotations for a dropped model's filtered entry, or None.
+
+    Built from the model's last cached endpoint list (load_cache_expired --
+    TTL ignored), never from a fresh fetch: the model is out of the ranking,
+    so the block is marked "stale": True for display in the filtered section
+    only (design section 4.9). Same builders as the live stage: eligibility
+    and baseline are re-derived from the cached list, so the shape matches a
+    ranked candidate's annotations. A model whose cache holds no endpoint
+    list at all yields None (the entry carries the drop reason alone).
+    """
+    cached = load_cache_expired(f"endpoints:{model_id.replace('/', '_')}")
+    if not isinstance(cached, list):
+        return None
+    author = model_id.partition("/")[0]
+    try:
+        default_precision = derive_default_precision(cached, author)
+        eligible_flags = [
+            baseline_eligible(endpoint, default_precision, author, args)
+            for endpoint in cached
+        ]
+        baseline = pick_baseline(cached, eligible_flags, args)
+        annotations = build_annotations(
+            cached, eligible_flags, baseline, catalog_context, args
+        )
+    except Exception:
+        # Display-only block for an already-dropped model: never fail the run.
+        return None
+    annotations["stale"] = True
+    return annotations
+
+
+def _endpoint_stage_drop(extra_dropped, filtered, cand, reason, args):
+    """Count one endpoint-stage drop and append its filtered entry.
+
+    Same validated entry shape as build_candidates' drop() plus the optional
+    stale annotations block (absent cache -> reasons only).
+    """
+    extra_dropped[reason] = extra_dropped.get(reason, 0) + 1
+    entry = {"id": cand["id"], "name": cand["name"] or cand["id"], "reasons": [reason]}
+    annotations = _stale_filtered_annotations(cand["id"], cand.get("context"), args)
+    if annotations is not None:
+        entry["annotations"] = annotations
+    filtered.append(entry)
+
+
+def apply_endpoint_pricing(candidates, args, filtered):
+    """Reprice every candidate at its baseline endpoint (design section 4.9).
+
+    The CLI stage between build_candidates and resolve_quality. Endpoint
+    fetches run concurrently (ThreadPoolExecutor, 8 workers) through
+    fetch_model_endpoints' per-model cache, but the results are applied PER
+    CANDIDATE ID in the original candidates order -- never in completion
+    order -- so the stage is deterministic.
+
+    Per candidate: endpoints = fetch. On fetch failure after fetch_json's
+    internal retries the model is dropped "endpoint_fetch_failed" and removed
+    from the returned list. With endpoints, default_precision is derived,
+    every endpoint scored for baseline eligibility and the baseline picked;
+    no usable baseline drops the model "no_baseline_eligible_endpoint"
+    (the stale-annotations filtered-entry rule covers both drop reasons).
+    Otherwise the candidate is mutated in place: the pricing block
+    (price_in/price_out/blended/base_*/tier/schedule/notes) is replaced with
+    the baseline endpoint's effective_pricing outputs scaled per-1M exactly
+    like build_candidates, and the additive keys "endpoints", "default_precision",
+    "annotations" (catalog context = the candidate's existing "context"),
+    "advertised_pricing" (the models-API scalars the candidate carried before
+    the mutation, source-tagged) and "steering" are attached.
+
+    A baseline whose prices are missing/non-finite counts as unusable
+    (pick_baseline's blended-price skip is authoritative for the top-level
+    effective prices). The same bar applies to the base prices the mutation
+    would publish: parse_price returns float | None, so a None base price
+    (tier-over-None-base endpoint) is reachable -- the isinstance(..., float)
+    half of the guard is load-bearing for None, not a redundant type check.
+    Returns (surviving candidates in the original order, dropped counts for
+    the two new reasons).
+    """
+    extra_dropped: dict[str, int] = {}
+    if not candidates:
+        return candidates, extra_dropped
+    endpoints_by_id: dict[str, list] = {}
+    failed_ids: set[str] = set()
+    with ThreadPoolExecutor(max_workers=8) as pool:
+        futures = {}
+        for cand in candidates:
+            # Duplicate ids fetch once and share the result.
+            futures.setdefault(
+                cand["id"], pool.submit(fetch_model_endpoints, cand["id"], args)
+            )
+        for cand_id, future in futures.items():
+            try:
+                endpoints_by_id[cand_id] = future.result()
+            except Exception:
+                # fetch_json already retried 3 times; the caller owns the
+                # fail-closed policy.
+                failed_ids.add(cand_id)
+    survivors = []
+    for cand in candidates:
+        cand_id = cand["id"]
+        if cand_id in failed_ids:
+            _endpoint_stage_drop(
+                extra_dropped, filtered, cand, "endpoint_fetch_failed", args
+            )
+            continue
+        endpoints = endpoints_by_id[cand_id]
+        author = cand_id.partition("/")[0]
+        default_precision = derive_default_precision(endpoints, author)
+        eligible_flags = [
+            baseline_eligible(endpoint, default_precision, author, args)
+            for endpoint in endpoints
+        ]
+        baseline = pick_baseline(endpoints, eligible_flags, args)
+        eff = (
+            effective_pricing(
+                baseline.get("pricing"), args.min_context, args.input_share
+            )
+            if baseline is not None
+            else None
+        )
+        if baseline is None or not all(
+            isinstance(eff[key], float) and math.isfinite(eff[key])
+            for key in ("price_in", "price_out", "base_price_in", "base_price_out")
+        ):
+            _endpoint_stage_drop(
+                extra_dropped, filtered, cand, "no_baseline_eligible_endpoint", args
+            )
+            continue
+        # The advertised models-API scalars, captured before the mutation.
+        advertised_pricing = {
+            "input_per_1m": cand["price_in"],
+            "output_per_1m": cand["price_out"],
+            "blended_per_1m": cand["blended"],
+            "source": "models-api",
+        }
+        # Replace the pricing block with the baseline endpoint's outputs,
+        # scaled per-1M exactly like build_candidates.
+        cand["price_in"] = eff["price_in"] * 1_000_000.0
+        cand["price_out"] = eff["price_out"] * 1_000_000.0
+        cand["blended"] = (
+            args.input_share * cand["price_in"]
+            + (1.0 - args.input_share) * cand["price_out"]
+        )
+        cand["base_price_in"] = eff["base_price_in"] * 1_000_000.0
+        cand["base_price_out"] = eff["base_price_out"] * 1_000_000.0
+        cand["tier_prompt_tokens"] = eff["tier_prompt_tokens"]
+        cand["tiers"] = eff["tiers"]
+        cand["schedule"] = eff["schedule"]
+        cand["max_discount"] = eff["max_discount"]
+        cand["tier_note"] = fmt_tier_note(eff["tier_prompt_tokens"])
+        cand["sched_note"] = fmt_sched_note(eff["max_discount"])
+        cand["sched_detail"] = fmt_sched_detail(eff["schedule"], eff["peak_blended"])
+        cand["endpoints"] = endpoints
+        cand["default_precision"] = default_precision
+        cand["annotations"] = build_annotations(
+            endpoints, eligible_flags, baseline, cand["context"], args
+        )
+        cand["advertised_pricing"] = advertised_pricing
+        cand["steering"] = build_steering(
+            cand_id, endpoints, eligible_flags, default_precision, args
+        )
+        survivors.append(cand)
+    return survivors, extra_dropped
+
+
+# ---------------------------------------------------------------------------
+# OpenRouter session-cost dataset (per-task cost, outside the score)
+# ---------------------------------------------------------------------------
+
+
+SESSION_COST_URL = "https://openrouter.ai/api/v1/datasets/session-cost"
+SESSION_COST_HARNESS_SLUG = "hermes-agent"
+# The turn range the catalog/CLI surfaces (Task 8).
+SESSION_COST_DISPLAY_TURN_RANGE = "10-49-turns"
+# The dataset's four turn ranges (brainstorm section 2.6) -- the catalog
+# contract's closed set (web/build_site_data.py pins the same tuple).
+# Cells naming anything else are dropped: an unknown range is dataset
+# drift, and the block must never fail the publish (design section 4.8).
+SESSION_COST_TURN_RANGES = ("1-turn", "2-9-turns", "10-49-turns", "50-plus-turns")
+SESSION_COST_ATTRIBUTION = "Data © OpenRouter, CC BY 4.0"
+
+
+def strip_permaslug_date(permaslug: str) -> str:
+    """Permaslug without its trailing -YYYYMMDD (undated ids map to themselves)."""
+    match = re.match(r"^(.*)-(\d{8})$", permaslug)
+    return match.group(1) if match else permaslug
+
+
+def fetch_session_cost(args) -> dict | None:
+    """Per-task session-cost medians from OpenRouter's dataset, or None.
+
+    A separate published dimension (design section 4.8): the median USD
+    cost of real sessions through the pinned published harness -- never
+    part of the weighted score. One bulk paginated fetch per invocation
+    (?app_slug=<harness>&limit=500&offset=k) regardless of the model list;
+    pagination stops on a page shorter than the limit or once the next
+    offset would exceed the API's 5000 cap. Cells key on dated permaslugs
+    (z-ai/glm-5.3-flash-20260826), stripped to the bare catalog id with
+    strip_permaslug_date; when several strip to the same id, the latest
+    date wins each turn-range cell (same rule as build_aa_benchmarks).
+
+    Returns None (graceful degradation, design section 4.9) when no key is
+    configured (the --openrouter-api-key flag, else OPENROUTER_API_KEY),
+    when the fetch fails after fetch_json's retries, or when the response
+    shape is unexpected -- a malformed payload must never crash the run.
+    The merged result is cached under "session-cost" with the standard TTL.
+    """
+    api_key = args.openrouter_api_key or os.environ.get("OPENROUTER_API_KEY")
+    if not api_key:
+        return None
+    if not args.no_cache:
+        cached = load_cache("session-cost", args.cache_ttl)
+        if isinstance(cached, dict) and isinstance(cached.get("medians"), dict):
+            return cached
+    cells = []
+    # The API caps limit at 500 and offset at 5000 (11 full pages max).
+    offset = 0
+    while offset <= 5000:
+        try:
+            payload = fetch_json(
+                f"{SESSION_COST_URL}?app_slug={SESSION_COST_HARNESS_SLUG}"
+                f"&limit=500&offset={offset}",
+                headers={"Authorization": f"Bearer {api_key}"},
+                timeout=30,
+                retries=3,
+            )
+        except Exception as exc:
+            warn(f"session-cost dataset request failed ({exc})")
+            return None
+        data = payload.get("data") if isinstance(payload, dict) else None
+        if not isinstance(data, list):
+            warn("session-cost dataset returned an unexpected response shape")
+            return None
+        cells.extend(cell for cell in data if isinstance(cell, dict))
+        if len(data) < 500:
+            break
+        offset += 500
+    medians: dict[str, dict[str, float]] = {}
+    seen_date: dict[tuple[str, str], str] = {}
+
+    def accept(bare, date, turn_range, median):
+        key = (bare, turn_range)
+        if key in seen_date and seen_date[key] >= date:
+            return
+        seen_date[key] = date
+        medians.setdefault(bare, {})[turn_range] = median
+
+    for cell in cells:
+        permaslug = cell.get("model_permaslug")
+        turn_range = cell.get("turn_range")
+        raw = cell.get("median_session_cost_usd")
+        if not (
+            isinstance(permaslug, str)
+            and permaslug
+            and isinstance(turn_range, str)
+            and turn_range
+        ):
+            continue
+        # Closed contract set: a cell naming a new turn range is dropped,
+        # never published (the catalog validator rejects unknown ranges,
+        # and session cost must never fail the publish).
+        if turn_range not in SESSION_COST_TURN_RANGES:
+            continue
+        # Non-finite medians would serialize as NaN and poison the catalog.
+        if not isinstance(raw, (int, float)) or isinstance(raw, bool):
+            continue
+        try:
+            median = float(raw)  # huge ints raise OverflowError
+        except OverflowError:
+            continue
+        if not math.isfinite(median):
+            continue
+        match = re.match(r"^(.*)-(\d{8})$", permaslug)
+        accept(
+            strip_permaslug_date(permaslug),
+            match.group(2) if match else "",
+            turn_range,
+            median,
+        )
+    if not medians:
+        warn("session-cost dataset returned no usable cells")
+        return None
+    meta = payload.get("meta") if isinstance(payload, dict) else None
+    if not isinstance(meta, dict):
+        warn("session-cost dataset returned an unexpected response shape")
+        return None
+    as_of = meta.get("as_of")
+    window_days = meta.get("window_days")
+    window_end_date = meta.get("window_end_date")
+    # The catalog validator demands non-empty as_of/window_end_date strings
+    # and a positive integer window_days; anything else is dataset drift.
+    # Degrade to None (block omitted, "not available this refresh") rather
+    # than emit a block the validator would reject -- session cost must
+    # never fail the publish (design section 4.8).
+    if not (
+        isinstance(as_of, str)
+        and as_of
+        and isinstance(window_end_date, str)
+        and window_end_date
+        and isinstance(window_days, int)
+        and not isinstance(window_days, bool)
+        and window_days > 0
+    ):
+        warn("session-cost dataset returned malformed meta; omitting the block")
+        return None
+    result = {
+        "attribution": SESSION_COST_ATTRIBUTION,
+        "app_slug": SESSION_COST_HARNESS_SLUG,
+        "as_of": as_of,
+        "window_days": window_days,
+        "window_end_date": window_end_date,
+        "medians": medians,
+    }
+    save_cache("session-cost", result)
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Published catalog quality (hydration for unkeyed runs)
+# ---------------------------------------------------------------------------
+
+
+# Pre-reconciliation published catalogs (schema v3, written before the AA
+# tier was relabeled) record the AA tier as "api"; hydration normalizes it
+# to the final "aa" label. Every other recorded label passes through as-is.
+_QUALITY_SOURCE_NORMALIZATION = {"api": "aa"}
+
+
+def catalog_quality_by_id(doc) -> dict:
+    """Pure parser: a published catalog document -> {id: quality record}.
+
+    No fetch, no cache, no args object -- the fetcher owns transport and
+    freshness; this owns shape. Records are {"index", "source", "as_of"}
+    and feed resolve_quality's catalog_quality parameter on unkeyed runs;
+    the values were produced by a keyed CI run, so hydration is an exact
+    catalog-id join with no re-matching.
+
+    Gates (design: failure modes):
+    - schema_version must be an int >= 3; anything older warns
+      "published catalog schema vX, expected >= 3; skipping hydration"
+      and yields {}. Accepting v3 is the deploy-day skew case: the live
+      artifact predates the v4 per-row quality_as_of.
+    - Any shape surprise -- a non-dict document, a non-int schema_version,
+      a non-list models, a row without a usable id, or a matched row whose
+      quality is not a finite number or whose quality_match is not a
+      non-empty string -- warns and yields {} for the WHOLE artifact.
+      Never a partial hydration, never a raise: the catalog is
+      machine-generated, so one malformed row means this is not the
+      artifact we think it is.
+    - Rows with quality None and quality_match None are legitimate
+      unmatched models; they are skipped silently (nothing to hydrate).
+
+    Normalization: v3 rows map quality_match "api" -> "aa" and date every
+    row with the catalog's generated_at -- the live v3 artifact carries
+    quality_as_of: null, which must be ignored, not passed through.
+    v4+ rows keep their recorded quality_as_of (None when absent) and
+    source label as-is: that label is the row-level truth inside the
+    published artifact (a keyed CI run emits "aa"/"openrouter", never
+    "catalog"). resolve_quality's catalog tier owns the run-level label:
+    it relabels every hydrated record to the chain label "catalog".
+    """
+    if not isinstance(doc, dict):
+        warn("published catalog returned an unexpected response shape")
+        return {}
+    schema_version = doc.get("schema_version")
+    if type(schema_version) is not int:
+        warn("published catalog returned an unexpected response shape")
+        return {}
+    if schema_version < 3:
+        warn(
+            f"published catalog schema v{schema_version}, expected >= 3; "
+            "skipping hydration"
+        )
+        return {}
+    models = doc.get("models")
+    if not isinstance(models, list):
+        warn("published catalog returned an unexpected response shape")
+        return {}
+    generated_at = doc.get("generated_at")
+    v3_as_of = generated_at if isinstance(generated_at, str) and generated_at else None
+    by_id: dict = {}
+    for entry in models:
+        if not isinstance(entry, dict):
+            warn("published catalog returned an unexpected response shape")
+            return {}
+        model_id = entry.get("id")
+        if not (isinstance(model_id, str) and model_id):
+            warn("published catalog returned an unexpected response shape")
+            return {}
+        quality = entry.get("quality")
+        match = entry.get("quality_match")
+        if match is None and quality is None:
+            continue  # legitimate unmatched row: nothing to hydrate
+        if not (isinstance(match, str) and match):
+            warn("published catalog returned an unexpected response shape")
+            return {}
+        if not isinstance(quality, (int, float)) or isinstance(quality, bool):
+            warn("published catalog returned an unexpected response shape")
+            return {}
+        try:
+            index = float(quality)  # huge ints raise OverflowError
+        except OverflowError:
+            warn("published catalog returned an unexpected response shape")
+            return {}
+        # Non-finite indexes would serialize as NaN and poison quality.
+        if not math.isfinite(index):
+            warn("published catalog returned an unexpected response shape")
+            return {}
+        # The AA indexes run 0..100 (the range the catalog validator
+        # enforces on quality); an out-of-range value is poisoned data and
+        # degrades the whole artifact. The surface is unkeyed runs: only
+        # they hydrate from the published catalog.
+        if not 0.0 <= index <= 100.0:
+            warn("published catalog returned an unexpected response shape")
+            return {}
+        if schema_version == 3:
+            as_of = v3_as_of
+        else:
+            recorded = entry.get("quality_as_of")
+            as_of = recorded if isinstance(recorded, str) and recorded else None
+        by_id[model_id] = {
+            "index": index,
+            "source": _QUALITY_SOURCE_NORMALIZATION.get(match, match),
+            "as_of": as_of,
+        }
+    return by_id
+
+
+def fetch_quality_catalog(args) -> dict | None:
+    """Quality records from the published catalog.json, or None.
+
+    The third quality source (design: source 2): the repo's own published
+    catalog artifact, built by keyed CI runs and hydrated by unkeyed local
+    runs. Never called on keyed runs -- a CI/site build hydrating from the
+    published catalog would consume its own output (self-reference loop);
+    Task 4 owns that wiring.
+
+    Returns None only on TRANSPORT failure (after fetch_json's retries);
+    otherwise the envelope {"by_id": {id: record}, "generated_at":
+    str|None, "schema_version": int}. An empty by_id means
+    fetched-but-unusable (schema gate fail, malformed shape) -- Task 4's
+    footer treats None and empty by_id identically ("catalog unavailable").
+
+    The envelope is cached under QUALITY_CATALOG_CACHE with the standard
+    TTL, and only a usable (non-empty by_id) result is ever written: a
+    degraded payload must self-heal on the next run. --no-cache neither
+    reads nor writes. Staleness: generated_at older than
+    QUALITY_CATALOG_MAX_AGE_DAYS warns but uses -- as_of makes the
+    staleness visible downstream (the check runs only when rows actually
+    hydrate -- warning about the age of a catalog we are not using is
+    noise); an unusable generated_at warns that
+    staleness cannot be checked and still uses the rows (their as_of then
+    shows None rather than a wrong date).
+    """
+    if not args.no_cache:
+        cached = load_cache(QUALITY_CATALOG_CACHE, args.cache_ttl)
+        if isinstance(cached, dict) and isinstance(cached.get("by_id"), dict):
+            return cached
+    try:
+        doc = fetch_json(QUALITY_CATALOG_URL, timeout=30, retries=3)
+    except Exception as exc:
+        warn(f"published catalog request failed ({exc})")
+        return None
+    by_id = catalog_quality_by_id(doc)
+    generated_at = doc.get("generated_at") if isinstance(doc, dict) else None
+    if not isinstance(generated_at, str):
+        generated_at = None
+    schema_version = doc.get("schema_version") if isinstance(doc, dict) else 0
+    if type(schema_version) is not int:
+        schema_version = 0
+    result = {
+        "by_id": by_id,
+        "generated_at": generated_at,
+        "schema_version": schema_version,
+    }
+    if by_id:
+        generated = parse_iso_datetime(generated_at)
+        if generated is None:
+            warn(
+                "published catalog generated_at is missing or unparseable; "
+                "cannot check staleness"
+            )
+        else:
+            age_days = (datetime.now(timezone.utc) - generated).total_seconds() / 86400
+            if age_days > QUALITY_CATALOG_MAX_AGE_DAYS:
+                warn(
+                    f"published catalog is stale (generated {generated_at}, "
+                    f"{age_days:.0f} days old); using it anyway"
+                )
+        if not args.no_cache:
+            save_cache(QUALITY_CATALOG_CACHE, result)
+    return result
+
+
 # ---------------------------------------------------------------------------
 # OpenRouter catalog
 # ---------------------------------------------------------------------------
@@ -243,7 +1408,9 @@ def fetch_openrouter_models(args):
 
 
 FRONTEND_DISCOUNTS_CACHE = "openrouter-frontend-discounts"
-FRONTEND_AA_CACHE = "openrouter-frontend-aa"
+# v2: AA records are keyed by exact catalog slug and carry as_of (#17);
+# v1 cached the conflated date-stripped shape, so the old key is never read.
+FRONTEND_AA_CACHE = "openrouter-frontend-aa-v2"
 
 
 def fetch_openrouter_frontend(args):
@@ -301,7 +1468,8 @@ def fetch_openrouter_frontend(args):
                 key = slug if variant in ("", "standard") else f"{slug}:{variant}"
                 fresh_discounts.setdefault(key, float(raw))
             fresh_aa = build_aa_benchmarks(
-                data.get("benchmarks") if isinstance(data, dict) else None
+                data.get("benchmarks") if isinstance(data, dict) else None,
+                entries,
             )
             if fresh_discounts:
                 discounts = fresh_discounts
@@ -792,7 +1960,7 @@ def parse_iso_datetime(value):
 # ---------------------------------------------------------------------------
 
 
-def aa_api_entries(api_key: str) -> list:
+def aa_api_entries(api_key: str) -> tuple[list, float | int | None]:
     """Intelligence entries from AA's V2 language models endpoint.
 
     Documented envelope: {tier, intelligence_index_version, pagination,
@@ -803,8 +1971,16 @@ def aa_api_entries(api_key: str) -> list:
     has_more/total_pages contract with a 25-page hard cap; a failure past
     page 1 is best-effort (warn, keep earlier pages), a page-1 failure
     propagates.
+
+    Returns (entries, version): version is the envelope's
+    intelligence_index_version (number-or-null) -- provenance for the whole
+    fetch. Every surviving entry carries `as_of`, one ISO fetch timestamp
+    shared by the whole fetch, so the cache and any downstream record can
+    date the data even after the envelope's version is lost.
     """
     entries = {}
+    version = None
+    as_of = datetime.now(timezone.utc).isoformat()
     page = 1
     while page <= 25:  # hard cap: halt after processing page 25
         try:
@@ -819,6 +1995,15 @@ def aa_api_entries(api_key: str) -> list:
             warn(f"AA API page {page} failed ({exc}); using entries collected so far")
             break
         data = payload.get("data") if isinstance(payload, dict) else None
+        # The envelope's version is one provenance fact for the whole
+        # fetch; the last page's value wins (they are identical in practice).
+        raw_version = (
+            payload.get("intelligence_index_version")
+            if isinstance(payload, dict)
+            else None
+        )
+        if isinstance(raw_version, (int, float)) and not isinstance(raw_version, bool):
+            version = raw_version
         for item in data if isinstance(data, list) else []:
             if not isinstance(item, dict):
                 continue
@@ -851,6 +2036,10 @@ def aa_api_entries(api_key: str) -> list:
                     "key": key,
                     "name": name if isinstance(name, str) and name else key,
                     "index": index,
+                    # One fetch timestamp for the whole fetch: every entry
+                    # from this run shares it, so the cache payload and any
+                    # downstream record can date the data exactly.
+                    "as_of": as_of,
                 },
             )
         pag = payload.get("pagination") if isinstance(payload, dict) else None
@@ -862,37 +2051,53 @@ def aa_api_entries(api_key: str) -> list:
         if isinstance(total_pages, int) and page >= total_pages:
             break
         page += 1
-    return list(entries.values())
+    return list(entries.values()), version
 
 
 def fetch_aa_entries(args):
     """AA intelligence entries from the keyed AA API v2, or nothing.
 
-    Returns (entries, source, cached). With a key, an API failure or an
-    empty result warns and yields ([], None, False). Without a key this is
-    silent and yields ([], None, False): OpenRouter's benchmarks are the
-    primary source and the catalog records the absence (sources.aa).
+    Returns (entries, source, cached, index_version). With a key, an API
+    failure or an empty result warns and yields ([], None, False, None).
+    Without a key this is silent and yields ([], None, False, None):
+    OpenRouter's benchmarks cover what they cover and the catalog records
+    the absence (sources.aa).
+
+    `index_version` is the envelope's intelligence_index_version (number
+    or null) -- provenance for the whole fetch. Entries carry `as_of`, one
+    ISO fetch timestamp for the whole fetch; a cache hit reuses the
+    stamped payload verbatim so cached rows stay dated exactly like fresh
+    ones.
     """
     if not args.no_cache:
-        # v2: entries cached under the old key predate the V2 endpoint
-        # migration and must never be read. Only AA API entries are read;
-        # build_catalog rejects any other source as unknown.
-        cached = load_cache("aa-intelligence-v2", args.cache_ttl)
+        # v3: payloads cached under earlier keys predate the as_of stamp and
+        # the intelligence_index_version capture and must never be read.
+        # Only AA API entries are read; build_catalog rejects any other
+        # source as unknown.
+        cached = load_cache(AA_ENTRIES_CACHE, args.cache_ttl)
         if isinstance(cached, dict) and cached.get("source") == "AA API v2":
-            return cached.get("entries", []), cached.get("source"), True
+            return (
+                cached.get("entries", []),
+                cached.get("source"),
+                True,
+                cached.get("version"),
+            )
     api_key = args.aa_api_key or os.environ.get("AA_API_KEY")
     if not api_key:
-        return [], None, False
+        return [], None, False, None
     try:
-        entries = aa_api_entries(api_key)
+        entries, version = aa_api_entries(api_key)
     except Exception as exc:
         warn(f"AA API request failed ({exc})")
-        return [], None, False
+        return [], None, False, None
     if not entries:
         warn("AA API returned no intelligence scores")
-        return [], None, False
-    save_cache("aa-intelligence-v2", {"entries": entries, "source": "AA API v2"})
-    return entries, "AA API v2", False
+        return [], None, False, None
+    save_cache(
+        AA_ENTRIES_CACHE,
+        {"entries": entries, "source": "AA API v2", "version": version},
+    )
+    return entries, "AA API v2", False, version
 
 
 # ---------------------------------------------------------------------------
@@ -901,6 +2106,13 @@ def fetch_aa_entries(args):
 
 
 def build_aa_lookup(entries):
+    """Index the AA entries into exact and fuzzy lookup maps.
+
+    Values are (index, as_of) pairs, not bare floats: the as_of travels
+    with the match so resolve_quality can date every AA-sourced record
+    without re-scanning the raw entry list. Entries without a usable key
+    or a finite numeric index are skipped.
+    """
     exact = {}
     fuzzy = []
     for entry in entries:
@@ -913,11 +2125,12 @@ def build_aa_lookup(entries):
         # Non-finite indexes would serialize as NaN and poison quality.
         if not math.isfinite(index):
             continue
+        as_of = entry.get("as_of") if isinstance(entry.get("as_of"), str) else None
 
         def put(tier, raw):
             normalized = norm_key(raw)
             if normalized:
-                exact.setdefault((tier, normalized), index)
+                exact.setdefault((tier, normalized), (index, as_of))
 
         if "/" in key:
             put(0, key)
@@ -928,11 +2141,17 @@ def build_aa_lookup(entries):
         put(3, PAREN_RE.sub(" ", name))
         tokens = set(norm_key(key).split()) | set(norm_key(name).split())
         if tokens:
-            fuzzy.append((tokens, index))
+            fuzzy.append((tokens, (index, as_of)))
     return exact, fuzzy
 
 
 def match_quality(model, exact, fuzzy, allow_fuzzy=False):
+    """Match a candidate to an AA entry; exact tiers only unless fuzzy is on.
+
+    Returns the winning entry's (index, as_of) pair, or None when no tier
+    matches. Values come straight out of build_aa_lookup's maps, so the
+    as_of is the entry's own fetch stamp, never a re-lookup.
+    """
     model_id = model["id"]
     name = model.get("name") or ""
     display = PROVIDER_PREFIX_RE.sub("", name).strip()
@@ -955,14 +2174,14 @@ def match_quality(model, exact, fuzzy, allow_fuzzy=False):
     own = set(norm_key(base).split()) | set(norm_key(display).split())
     if own:
         best = 0.0
-        best_index = None
-        for tokens, index in fuzzy:
+        best_match = None
+        for tokens, match in fuzzy:
             overlap = len(own & tokens) / len(own | tokens)
             if overlap > best:
                 best = overlap
-                best_index = index
-        if best >= 0.5 and best_index is not None:
-            return best_index
+                best_match = match
+        if best >= 0.5 and best_match is not None:
+            return best_match
     return None
 
 
@@ -974,24 +2193,37 @@ def base_model_id(model_id: str) -> str:
 AA_BENCHMARK_FIELDS = ("intelligence_index", "coding_index", "agentic_index")
 
 
-def build_aa_benchmarks(benchmarks) -> dict:
-    """Map bare OpenRouter id -> OR-published AA trio from data.benchmarks.
-
-    Keys are dated permaslugs (z-ai/glm-5.3-flash-20260826): the trailing
-    -YYYYMMDD is stripped and undated keys map to themselves; when two keys
-    strip to the same id the latest date wins. Values failing the
-    finite-number guard are treated as absent; entries with at least one
-    valid field are kept.
+def build_aa_benchmarks(benchmarks, models=None) -> dict:
+    """Map exact catalog slug -> OR-published AA trio from data.benchmarks.
+
+    Benchmark keys are dated permaslugs (deepseek/deepseek-v4.1-flash-
+    20261017) whose date-stripped form can collide across listings of one
+    model family: the snapshot listing deepseek/deepseek-v4.1-flash-1017
+    and the base listing deepseek/deepseek-v4.1-flash both strip to
+    deepseek/deepseek-v4.1-flash, so blind stripping with latest-date-wins
+    made the base listing borrow the snapshot's score (#17). Keys resolve
+    through three explicit passes over the surviving entries, and every
+    accepted id is claimed by the pass that resolved it, so later passes
+    never overwrite an earlier one:
+
+    1. Primary: a key equal to a models entry's permaslug maps to that
+       entry's slug -- the catalog's own pairing, no guessing. Several
+       dated permaslugs may legitimately pair with one slug (snapshot
+       variants of one listing); among those the latest date wins.
+    2. Undated: a key without a -YYYYMMDD suffix maps to itself, unless
+       pass 1 claimed the id.
+    3. Dated fallback: a dated key the catalog does not pair strips via
+       strip_permaslug_date, accepted only when the stripped id is
+       unclaimed and no other pass-3 key strips to the same id -- an
+       ambiguous strip is the #17 conflation shape, so every candidate
+       for that id drops rather than guess.
+
+    Entries whose values fail the finite-number guard are treated as
+    absent before the passes run; entries with at least one valid field
+    are kept. Records carry "as_of": the YYYYMMDD of the permaslug the
+    trio came from, or None for undated keys.
     """
-    aa_by_id = {}
-    seen_date = {}
-
-    def accept(bare, date, trio):
-        if bare in seen_date and seen_date[bare] >= date:
-            return
-        seen_date[bare] = date
-        aa_by_id[bare] = trio
-
+    valid = {}  # benchmark key -> (trio, permaslug date or "")
     for key, node in (benchmarks or {}).items():
         aa = node.get("aa") if isinstance(node, dict) else None
         if not isinstance(aa, dict):
@@ -1007,36 +2239,152 @@ def build_aa_benchmarks(benchmarks) -> dict:
                 trio[field] = float(value)
         if not trio:
             continue
-        match = re.match(r"^(.*)-(\d{8})$", key)
-        if match:
-            accept(match.group(1), match.group(2), trio)
-        else:
-            accept(key, "", trio)
-    return aa_by_id
+        bare = strip_permaslug_date(key)
+        # strip_permaslug_date removed a trailing -YYYYMMDD exactly when
+        # the key was dated; the date is then the final 8 characters.
+        valid[key] = (trio, "" if bare == key else key[-8:])
 
+    permaslug_to_slug = {}  # the catalog's own slug/permaslug pairing
+    for entry in models or []:
+        if not isinstance(entry, dict):
+            continue
+        slug = entry.get("slug") or ""
+        permaslug = entry.get("permaslug") or ""
+        if slug and permaslug:
+            # standard and batch variants repeat an identical pair; the
+            # overwrite is the dedup
+            permaslug_to_slug[permaslug] = slug
+
+    aa_by_id = {}
+    claimed = set()
 
-def resolve_quality(candidates, aa_by_id, exact, fuzzy, aa_source):
-    """Per-candidate quality: OR benchmarks first, AA exact fallback, else None.
+    def record(trio, date):
+        return {**trio, "as_of": date or None}
 
-    OR's per-slug values cannot mispair; the AA fallback is exact-tier only
-    (match_quality's fuzzy tier is the proven variant-conflation bug and
-    stays off in production). Source values match the catalog contract:
-    "openrouter", "api".
+    # Pass 1: permaslug keys pair with their own slug; same-slug
+    # snapshots resolve to the latest date (first wins on an equal date).
+    seen_date = {}
+    for key, (trio, date) in valid.items():
+        slug = permaslug_to_slug.get(key)
+        if slug is None or (slug in seen_date and seen_date[slug] >= date):
+            continue
+        seen_date[slug] = date
+        aa_by_id[slug] = record(trio, date)
+        claimed.add(slug)
+
+    # Pass 2: undated keys self-map unless pass 1 claimed the id.
+    for key, (trio, date) in valid.items():
+        if date or key in permaslug_to_slug or key in claimed:
+            continue
+        aa_by_id[key] = record(trio, date)
+        claimed.add(key)
+
+    # Pass 3: unpaired dated keys strip, but only onto an unclaimed id
+    # and only when the strip is unambiguous.
+    strip_candidates = {}
+    for key, (trio, date) in valid.items():
+        if not date or key in permaslug_to_slug:
+            continue
+        stripped = strip_permaslug_date(key)
+        strip_candidates.setdefault(stripped, []).append((date, trio))
+    for bare, candidates in strip_candidates.items():
+        if bare in claimed or len(candidates) > 1:
+            continue
+        date, trio = candidates[0]
+        aa_by_id[bare] = record(trio, date)
+        claimed.add(bare)
+
+    return aa_by_id
+
+
+def resolve_quality(
+    candidates, aa_by_id, exact, fuzzy, aa_source, catalog_quality=None
+):
+    """Per-candidate quality records: AA API primary, catalog next, OR last.
+
+    Resolution order per candidate (inverted from the pre-reconciliation
+    behavior where OpenRouter's benchmarks won):
+      1. AA API entries -- match_quality's exact tiers (fuzzy stays off in
+         production: it is the proven variant-conflation bug).
+      2. catalog_quality -- records hydrated from the published catalog on
+         unkeyed runs. Every winner is labeled "catalog": the run-level
+         provenance is the source chain (read from our published catalog),
+         overriding the row's own "aa"/"openrouter" label -- that label is
+         the keyed CI run's row-level truth inside the artifact, and no
+         real catalog row ever carries "catalog". as_of stays the row's
+         own stamp.
+      3. OpenRouter's benchmark trio -- per-slug, matched via
+         base_model_id, so a :variant suffix inherits its base's trio.
+      4. No match -- the candidate stays quality-blind downstream.
+
+    Every winner is a record {"index", "source", "as_of", "drift",
+    "or_index", "or_as_of"}; compute_scores and build_schedules read
+    record["index"], so cand["quality"] stays the float index they already
+    expect. Drift is computed only when the winner is NOT OpenRouter: the
+    OR trio for the same base model acts as the check value, and a
+    disagreement of >= 3.0 points flags the record. When the winner IS
+    OpenRouter (or no OR value exists) the drift pair is None -- there is
+    no second source to disagree with.
     """
-    fallback_source = {"AA API v2": "api"}.get(aa_source)
     quality_by_id = {}
     source_by_id = {}
     for cand in candidates:
-        bench = aa_by_id.get(base_model_id(cand["id"]))
-        intelligence = bench.get("intelligence_index") if bench else None
-        if intelligence is not None:
-            quality_by_id[cand["id"]] = intelligence
-            source_by_id[cand["id"]] = "openrouter"
+        record = None
+        # Tier 1: AA API exact match. match_quality returns the winning
+        # entry's (index, as_of) pair.
+        match = match_quality({"id": cand["id"], "name": cand["name"]}, exact, fuzzy)
+        if match is not None:
+            index, as_of = match
+            record = {"index": index, "source": "aa", "as_of": as_of}
+        # Tier 2: catalog record (unkeyed runs hydrate from the published
+        # catalog). The run-level provenance label is the source chain:
+        # every hydrated record is tagged "catalog" -- read from our
+        # published catalog -- overriding the row's own label, which is
+        # the keyed CI run's row-level truth inside the artifact ("aa"/
+        # "openrouter"; no real catalog row ever carries "catalog").
+        # as_of stays the row's own stamp (v4 rows carry the CI run's
+        # recorded quality_as_of; v3 rows the catalog's generated_at --
+        # catalog_quality_by_id normalizes that).
+        if record is None and catalog_quality is not None:
+            catalog_record = catalog_quality.get(cand["id"])
+            if catalog_record is not None:
+                record = {
+                    "index": catalog_record["index"],
+                    "source": "catalog",
+                    "as_of": catalog_record["as_of"],
+                }
+        # Tier 3: OpenRouter's per-slug benchmark trio (last resort).
+        if record is None:
+            bench = aa_by_id.get(base_model_id(cand["id"]))
+            intelligence = bench.get("intelligence_index") if bench else None
+            if intelligence is not None:
+                record = {
+                    "index": intelligence,
+                    "source": "openrouter",
+                    "as_of": bench.get("as_of"),
+                }
+        if record is None:
             continue
-        index = match_quality({"id": cand["id"], "name": cand["name"]}, exact, fuzzy)
-        if index is not None:
-            quality_by_id[cand["id"]] = index
-            source_by_id[cand["id"]] = fallback_source
+
+        # Drift: only meaningful when the winner is not OpenRouter itself.
+        bench = aa_by_id.get(base_model_id(cand["id"])) or {}
+        or_intelligence = bench.get("intelligence_index")
+        if (
+            record["source"] in ("aa", "catalog")
+            and isinstance(or_intelligence, (int, float))
+            and not isinstance(or_intelligence, bool)
+            and math.isfinite(or_intelligence)
+        ):
+            record["or_index"] = or_intelligence
+            record["or_as_of"] = bench.get("as_of")
+            record["drift"] = abs(record["index"] - or_intelligence) >= 3.0
+        else:
+            record["or_index"] = None
+            record["or_as_of"] = None
+            record["drift"] = None
+
+        quality_by_id[cand["id"]] = record
+        source_by_id[cand["id"]] = record["source"]
     return quality_by_id, source_by_id
 
 
@@ -1061,7 +2409,9 @@ def _per_1m(price_per_token: float) -> float:
     return round(price_per_token * 1_000_000.0, 6)
 
 
-def build_schedules(models, args, quality_by_id, aa_by_id, balanced_by_id):
+def build_schedules(
+    models, args, quality_by_id, aa_by_id, balanced_by_id, catalog_quality=None
+):
     """Catalog-wide off-peak index built from the RAW model list (spec 5.4).
 
     Deliberately unfiltered by the candidate pool: sub-floor-context and
@@ -1069,6 +2419,12 @@ def build_schedules(models, args, quality_by_id, aa_by_id, balanced_by_id):
     schedule models mostly sit below the 1M context floor). Router aliases
     (~ids) and malformed ids are excluded; :batch variants are included as
     distinct deals. Sorted by id.
+
+    Quality falls back through the same chain resolve_quality walks, minus
+    its AA tier (the AA lookup only ever matched candidates): candidate
+    records, then the hydrated catalog (unkeyed runs), then OpenRouter's
+    benchmark trio. Every schedule row carries the winner's provenance
+    (quality_source/quality_as_of) so the site's QUAL tooltip can render.
     """
     entries = []
     for model in models:
@@ -1093,10 +2449,38 @@ def build_schedules(models, args, quality_by_id, aa_by_id, balanced_by_id):
             continue
         peak = max(windows, key=lambda window: window["blended"])
         offpeak = min(windows, key=lambda window: window["blended"])
-        quality = quality_by_id.get(model_id)
+        # quality_by_id values are records {"index", "source", ...}; the
+        # schedule row keeps the bare float index verbatim (never a dict)
+        # and echoes the winning record's provenance for the QUAL tooltip.
+        # Fallback chain mirrors resolve_quality's minus its AA tier:
+        # candidate record, hydrated catalog record (unkeyed runs; every
+        # hydrated record is relabeled with the run-level chain label
+        # "catalog", exactly like resolve_quality's catalog tier), then
+        # OpenRouter's benchmark trio (row label "openrouter").
+        record = quality_by_id.get(model_id)
+        if isinstance(record, dict):
+            quality = record.get("index")
+            quality_source = record.get("source")
+            quality_as_of = record.get("as_of")
+        else:
+            quality = record
+            quality_source = None
+            quality_as_of = None
+        if quality is None and catalog_quality is not None:
+            catalog_record = catalog_quality.get(model_id)
+            if catalog_record is not None:
+                quality = catalog_record["index"]
+                quality_source = "catalog"
+                quality_as_of = catalog_record["as_of"]
         if quality is None:
             benchmark = aa_by_id.get(base_model_id(model_id)) or {}
             quality = benchmark.get("intelligence_index")
+            if quality is not None:
+                quality_source = "openrouter"
+                quality_as_of = benchmark.get("as_of")
+            else:
+                quality_source = None
+                quality_as_of = None
         name = model.get("name") or model_id
         entries.append(
             {
@@ -1104,6 +2488,10 @@ def build_schedules(models, args, quality_by_id, aa_by_id, balanced_by_id):
                 "name": PROVIDER_PREFIX_RE.sub("", name).strip() or name,
                 "context": coerce_int(model.get("context_length"), 0),
                 "quality": quality,
+                # Provenance for the site's QUAL tooltip (null when the
+                # quality came without any -- e.g. a bare-float test map).
+                "quality_source": quality_source,
+                "quality_as_of": quality_as_of,
                 "score": balanced_by_id.get(model_id),
                 "max_discount": eff["max_discount"],
                 "sched_note": fmt_sched_note(eff["max_discount"]),
@@ -1313,11 +2701,19 @@ def compute_scores(candidates, args, quality_by_id):
                 0.0, min(1.0, 1.0 - (math.log10(price + 0.01) - low) / price_span)
             )
         quality = quality_by_id.get(cand["id"])
-        cand["quality"] = quality
-        if quality is None:
+        # quality_by_id values are records {"index", "source", ...}; the
+        # candidate keeps the bare float index (that is what ranking_key,
+        # build_catalog's quality field and print_json's quality_index all
+        # expect) and the full record travels alongside for provenance.
+        record = quality if isinstance(quality, dict) else None
+        cand["quality"] = record["index"] if record else quality
+        cand["quality_record"] = record
+        if cand["quality"] is None:
             cand["quality_score"] = 0.0
         else:
-            cand["quality_score"] = max(0.0, min(1.0, quality / args.quality_ref))
+            cand["quality_score"] = max(
+                0.0, min(1.0, cand["quality"] / args.quality_ref)
+            )
         context = cand["context"]
         cand["context_score"] = (
             max(0.0, min(1.0, math.log(context / floor_ctx) / ctx_span))
@@ -1413,6 +2809,151 @@ def fmt_discount(value) -> str:
     return f"{value:.0%}" if has_discount(value) else "--"
 
 
+def fmt_prec(cand) -> str:
+    """PREC cell: the precision the ranked price is quoted at.
+
+    The maker's default precision when disclosed, the best available
+    otherwise, "n/a" when none could be derived; "!" flags default routing
+    that favors cheaper sub-default endpoints (annotations.risk_flag).
+    Candidates that never went through the endpoint stage degrade to "n/a".
+    """
+    cell = cand.get("default_precision") or "n/a"
+    if (cand.get("annotations") or {}).get("risk_flag"):
+        cell += "!"
+    return cell
+
+
+def fmt_quant_note(annotations: dict) -> str | None:
+    """One-line note on the cheapest sub-default endpoint (PREC tooltip).
+
+    The exact string the site shows (Task 11 renders it verbatim), so the
+    format is pinned by test. None when there is no non-eligible live
+    endpoint -- nothing cheaper to route to. cheapest_quantized.price is
+    stored per-token, the way build_annotations leaves it; the note shows
+    USD per 1M like every other price the CLI prints. A missing spread
+    (defensive) drops the parenthetical. A null quantization (third-party
+    null == "unknown" for eligibility) and a null provider_name on
+    malformed data render the design's "unknown" sentinel, never Python's
+    None repr.
+    """
+    quant = (annotations or {}).get("cheapest_quantized")
+    if not quant:
+        return None
+    quantization = quant["quantization"] or "unknown"
+    provider = quant["provider"] or "unknown"
+    note = (
+        f"cheapest non-baseline: {quantization} @ {provider}, "
+        f"${fmt_price(quant['price'] * 1_000_000)}/M"
+    )
+    spread = (annotations or {}).get("price_spread")
+    if spread is not None:
+        note += f" in ({spread:.2f}x baseline)"
+    return note
+
+
+def _footer_as_of(source, value):
+    """Format a record's as_of for its footer block (None when unusable).
+
+    Two stamp shapes circulate. A YYYYMMDD date (OpenRouter's benchmark
+    date, and catalog rows hydrated from OR rows) renders as a plain date
+    ("as of 2026-10-17") for ANY source -- a date-only stamp never
+    fabricates a time of day. ISO stamps: live AA records carry one fetch
+    timestamp for the whole fetch (checked today), so their block shows
+    the time of day only; other rows carry the full stamp ("as of
+    2026-10-23 13:15Z").
+    """
+    if not value:
+        return None
+    text = str(value)
+    if len(text) == 8 and text.isdigit():
+        return f"{text[:4]}-{text[4:6]}-{text[6:]}"
+    parsed = parse_iso_datetime(value)
+    if parsed is None:
+        return None
+    if source == "aa":
+        return parsed.strftime("%H:%MZ")
+    return parsed.strftime("%Y-%m-%d %H:%MZ")
+
+
+def _as_of_instant(value):
+    """Parse an as_of stamp to a comparable UTC instant (None when unusable).
+
+    The pipeline carries ISO stamps and the YYYYMMDD benchmark date; a
+    date-only stamp means "that day" and compares as midnight UTC.
+    """
+    text = str(value)
+    if len(text) == 8 and text.isdigit():
+        return parse_iso_datetime(f"{text[:4]}-{text[4:6]}-{text[6:]}")
+    return parse_iso_datetime(value)
+
+
+def _later_as_of(value, current) -> bool:
+    """True when the value stamp names a later instant than current.
+
+    Parsed instants, never raw strings: a YYYYMMDD stamp must not
+    lexicographically beat a fresher ISO stamp ("20261017" sorts above
+    every "2026-..." string). Ties keep the earlier pick; an unparseable
+    stamp never displaces anything.
+    """
+    new, old = _as_of_instant(value), _as_of_instant(current)
+    if new is None or old is None:
+        return new is not None
+    return new > old
+
+
+def quality_footer_note(quality_by_id, aa_index_version, unmatched):
+    """Compose the footer's quality note from the resolved records.
+
+    Lists per-source counts, each source's own as_of and the AA index
+    version when known, e.g. "AA index v4.3 - live AA (58, checked 13:15Z)
+    | our catalog (12, as of 2026-10-23 13:15Z) | OpenRouter snapshot (2,
+    as of 2026-10-17)". A trailing "unmatched score 0" names candidates
+    with no quality record, and a drift footnote appears when any resolved
+    record disagrees with the OpenRouter check value. Returns None when no
+    record resolved -- run() falls back to the quality-blind note.
+    """
+    labels = {
+        "aa": "live AA",
+        "catalog": "our catalog",
+        "openrouter": "OpenRouter snapshot",
+    }
+    stamp_words = {"aa": "checked", "catalog": "as of", "openrouter": "as of"}
+    counts = {}
+    latest = {}
+    for record in quality_by_id.values():
+        source = record.get("source")
+        if source not in labels:
+            continue
+        counts[source] = counts.get(source, 0) + 1
+        value = record.get("as_of")
+        if value:
+            current = latest.get(source)
+            if current is None or _later_as_of(value, current):
+                latest[source] = value
+    blocks = []
+    for source in ("aa", "catalog", "openrouter"):
+        count = counts.get(source, 0)
+        if not count:
+            continue
+        stamp = _footer_as_of(source, latest.get(source))
+        if stamp:
+            blocks.append(f"{labels[source]} ({count}, {stamp_words[source]} {stamp})")
+        else:
+            blocks.append(f"{labels[source]} ({count})")
+    if not blocks:
+        return None
+    note = "quality: "
+    if aa_index_version is not None:
+        note += f"AA index v{aa_index_version} - "
+    note += " | ".join(blocks)
+    if unmatched:
+        note += "; unmatched score 0"
+    drift = sum(1 for record in quality_by_id.values() if record.get("drift"))
+    if drift:
+        note += f"; drift vs OpenRouter snapshot ({drift})"
+    return note
+
+
 def print_table(top, total_candidates, weights, quality_note):
     headers = [
         "RANK",
@@ -1421,6 +2962,7 @@ def print_table(top, total_candidates, weights, quality_note):
         "$IN/M",
         "$OUT/M",
         "DISC",
+        "PREC",
         "TIER",
         "CTX",
         "AGE",
@@ -1436,6 +2978,7 @@ def print_table(top, total_candidates, weights, quality_note):
                 fmt_price(cand["price_in"]),
                 fmt_price(cand["price_out"]),
                 fmt_discount(cand["discount"]),
+                fmt_prec(cand),
                 cand["tier_note"] or cand["sched_note"] or "--",
                 fmt_context(cand["context"]),
                 fmt_age(cand["age_days"]),
@@ -1482,6 +3025,12 @@ def print_table(top, total_candidates, weights, quality_note):
         "schedule whose discount is under 1%. --json lists each model's "
         "schedule."
     )
+    print(
+        "PREC = precision the ranked price is quoted at (maker's default when "
+        "disclosed, best available otherwise; ! = default routing favors "
+        "cheaper sub-default endpoints); prices are the cheapest live endpoint "
+        "at that precision."
+    )
 
 
 def print_json(top):
@@ -1492,6 +3041,15 @@ def print_json(top):
             "name": cand["name"],
             "score": round(cand["score"], 4),
             "quality_index": cand["quality"],
+            # Provenance block, verbatim from the quality record resolved
+            # in compute_scores: the winning tier's source and as_of plus
+            # the drift check against OpenRouter's benchmarks. Rows without
+            # a record (pre-endpoint test paths) degrade to None.
+            "quality_source": (cand.get("quality_record") or {}).get("source"),
+            "quality_as_of": (cand.get("quality_record") or {}).get("as_of"),
+            "quality_drift": (cand.get("quality_record") or {}).get("drift"),
+            "quality_or_index": (cand.get("quality_record") or {}).get("or_index"),
+            "quality_or_as_of": (cand.get("quality_record") or {}).get("or_as_of"),
             "input_usd_per_m": round(cand["price_in"], 6),
             "output_usd_per_m": round(cand["price_out"], 6),
             "blended_usd_per_m": round(cand["blended"], 6),
@@ -1518,6 +3076,31 @@ def print_json(top):
             "age_days": round(cand["age_days"], 1)
             if cand["age_days"] is not None
             else None,
+            # Additive keys (Task 9's ROW_KEYS extension pins this exact
+            # key set and order). Risk/spread come from the annotations
+            # block; session_cost_usd is run()'s per-candidate slice of the
+            # Task 7 envelope, shown for the display turn range (run()
+            # attaches it before any output path). Candidates that never
+            # went through either stage (historical test paths) degrade to
+            # null, as does a model the dataset covers only in other turn
+            # ranges.
+            "default_precision": cand.get("default_precision"),
+            "risk_flag": (cand.get("annotations") or {}).get("risk_flag"),
+            "price_spread": (cand.get("annotations") or {}).get("price_spread"),
+            "session_cost_usd": (cand.get("session_cost") or {}).get(
+                SESSION_COST_DISPLAY_TURN_RANGE
+            ),
+            # The cheapest-sub-default note, exactly as the CLI prints it
+            # (Task 11 shows it verbatim). Emit-first: Task 9's ROW_KEYS
+            # pins this key last; pre-endpoint candidates degrade to None.
+            "quant_note": fmt_quant_note(cand.get("annotations")),
+            # One extra row key AFTER quant_note -- steering is NOT in
+            # ROW_KEYS. build_site_data's row check is missing-key-only, so
+            # extras pass through (tier_note precedent) and the site
+            # ignores it. The OpenRouter provider routing object (design
+            # section 4.7) the plugin contract reads; pre-endpoint
+            # candidates degrade to None.
+            "steering": cand.get("steering"),
         }
         for cand in top
     ]
@@ -1535,6 +3118,11 @@ def build_catalog(
     aa_source,
     aa_by_id,
     quality_source_by_id,
+    session_cost=None,
+    session_cost_mode="skipped",
+    index_version=None,
+    catalog_generated_at=None,
+    catalog_quality=None,
 ):
     """Assemble the full-catalog document (see README "Catalog output").
 
@@ -1542,21 +3130,56 @@ def build_catalog(
     component scores) and never mutates them. Deterministic apart from
     generated_at: models sort by (-overall.balanced, id), filtered by id,
     and age uses date precision so two runs in the same UTC day match.
+
+    session_cost is the Task 7 fetch envelope (verbatim, medians included)
+    or None; session_cost_mode is run()'s resolution of the key-presence
+    fact ("ok" / "unavailable" / "skipped") -- build_catalog stays pure and
+    never fetches or inspects the environment itself. index_version is the
+    AA envelope's intelligence_index_version (number or null) and
+    catalog_generated_at the published catalog's generated_at when this
+    run hydrated from it (else None); both pass verbatim into sources.aa.
+    catalog_quality is the hydrated record map (or None): candidates read
+    it through resolve_quality, and build_schedules falls back to it for
+    non-candidates.
     """
     now = datetime.now(timezone.utc)
     weights = catalog_weights(candidates, quality_by_id)
-    aa_modes = {"AA API v2": "api"}
-    if aa_source is not None and aa_source not in aa_modes:
-        # Never claim mode "none" for a source we do not know: the document
-        # would contradict itself (mode none with matched quality scores).
+    if aa_source is not None and aa_source != "AA API v2":
+        # Never publish a document whose AA source we cannot name: the
+        # consumers' mode enum has no slot for it.
         raise ValueError(f"unknown AA source: {aa_source!r}")
+    # The three counts are disjoint label buckets: resolve_quality's strict
+    # rank gives every candidate at most one record, so their sum is exactly
+    # the number of entries with a non-null quality_match -- the invariant
+    # the site validator enforces. A label outside the buckets would break
+    # it silently, so it fails loudly here.
+    matched_aa = sum(1 for s in quality_source_by_id.values() if s == "aa")
+    matched_catalog = sum(1 for s in quality_source_by_id.values() if s == "catalog")
     matched_openrouter = sum(
         1 for s in quality_source_by_id.values() if s == "openrouter"
     )
-    # fallback is what the AA API yielded on its own; mode
-    # hides it behind "openrouter" as soon as one OpenRouter match exists.
-    aa_fallback = aa_modes.get(aa_source, "none")
-    aa_mode = "openrouter" if matched_openrouter else aa_fallback
+    unknown = sorted(
+        {
+            s
+            for s in quality_source_by_id.values()
+            if s not in ("aa", "catalog", "openrouter")
+        }
+    )
+    if unknown:
+        raise ValueError(f"unknown quality source: {unknown[0]!r}")
+    # mode is the run's quality chain, not a match outcome: "aa" when the
+    # AA API returned usable entries, "catalog" when unkeyed runs hydrated
+    # the published catalog, "none" when neither tier produced data.
+    # OpenRouter's benchmarks are the chain's shared last resort, never a
+    # mode of their own -- matched_openrouter carries their count. The
+    # catalog branch also fires on the counts alone: hydrated records are
+    # proof of a usable catalog even when its generated_at was unusable.
+    if aa_source is not None:
+        aa_mode = "aa"
+    elif catalog_generated_at is not None or matched_catalog or matched_aa:
+        aa_mode = "catalog"
+    else:
+        aa_mode = "none"
 
     entries = []
     for cand in candidates:
@@ -1587,6 +3210,12 @@ def build_catalog(
                 4,
             )
         bench = aa_by_id.get(base_model_id(cand["id"])) or {}
+        # The quality record map is already a parameter; the winning
+        # record's as_of and drift verdict become entry fields verbatim.
+        # Unmatched candidates degrade to null -- same shape as the v3
+        # additive blocks below.
+        record = quality_by_id.get(cand["id"])
+        record = record if isinstance(record, dict) else None
         entries.append(
             {
                 "id": cand["id"],
@@ -1654,7 +3283,25 @@ def build_catalog(
                 },
                 "quality": cand["quality"],
                 "quality_match": quality_source_by_id.get(cand["id"]),
+                # Provenance (schema v4), verbatim from the record: the
+                # winning source's own as_of and the drift verdict against
+                # OpenRouter's check value.
+                "quality_as_of": record["as_of"] if record else None,
+                "quality_drift": record["drift"] if record else None,
                 "scores": {**scores, "overall": overall},
+                # Additive provider-aware blocks (schema v3), verbatim from
+                # the candidate. Candidates that never went through the
+                # endpoint stage (historical test paths) degrade to null --
+                # .get() with null defaults for these NEW keys only; the
+                # pre-existing keys above stay direct-indexed.
+                "endpoints": cand.get("endpoints"),
+                "default_precision": cand.get("default_precision"),
+                "advertised_pricing": cand.get("advertised_pricing"),
+                "annotations": cand.get("annotations"),
+                # The OpenRouter provider routing object (design section
+                # 4.7) the plugin contract reads -- same null-default
+                # degradation shape as the blocks above.
+                "steering": cand.get("steering"),
             }
         )
     entries.sort(key=lambda e: (-e["scores"]["overall"]["balanced"], e["id"]))
@@ -1665,7 +3312,7 @@ def build_catalog(
 
     return {
         "schedules": build_schedules(
-            models, args, quality_by_id, aa_by_id, balanced_by_id
+            models, args, quality_by_id, aa_by_id, balanced_by_id, catalog_quality
         ),
         "schema_version": CATALOG_SCHEMA_VERSION,
         "tool": "model-compare",
@@ -1686,13 +3333,31 @@ def build_catalog(
             "openrouter": "ok",
             "aa": {
                 "mode": aa_mode,
-                "fallback": aa_fallback,
-                "matched": len(quality_by_id),
+                "matched_aa": matched_aa,
+                "matched_catalog": matched_catalog,
                 "matched_openrouter": matched_openrouter,
+                # Provenance meta (schema v4): the published catalog's stamp
+                # when this run hydrated from it, and the AA envelope's
+                # intelligence index version when the AA API ran. Both null
+                # when their source was not consulted.
+                "catalog_generated_at": catalog_generated_at,
+                "intelligence_index_version": index_version,
             },
             "zdr": "skipped" if args.no_zdr else "ok",
             "discounts": "ok" if discounts else "unavailable",
+            # The endpoint stage always ran before build_catalog is reached;
+            # its failures surface as pool.dropped counts
+            # (endpoint_fetch_failed / no_baseline_eligible_endpoint), never
+            # as source state -- so this is deterministic "ok".
+            "endpoints": "ok",
+            # "ok" (envelope fetched) / "unavailable" (key configured, fetch
+            # failed) / "skipped" (no key) -- resolved in run().
+            "session_cost": session_cost_mode,
         },
+        # Per-task session-cost medians (Task 7), verbatim from the fetch
+        # envelope. Omitted entirely when unavailable: consumers branch on
+        # key presence, never on a null shape.
+        **({"session_cost": session_cost} if session_cost is not None else {}),
         "pool": {
             "listed": len(models),
             "candidates": len(candidates),
@@ -1787,6 +3452,11 @@ def parse_args(argv=None):
         default=None,
         help="Artificial Analysis API key (or set AA_API_KEY; free at artificialanalysis.ai)",
     )
+    parser.add_argument(
+        "--openrouter-api-key",
+        default=None,
+        help="OpenRouter API key (or set OPENROUTER_API_KEY; free at openrouter.ai/keys)",
+    )
     parser.add_argument(
         "--no-require-tools",
         action="store_true",
@@ -1857,23 +3527,82 @@ def run(args, models, or_cached) -> int:
             "(--no-zdr to override)"
         )
         return 1
-    aa_entries, aa_source, aa_cached = fetch_aa_entries(args)
+    # Mode-scoped quality chains: a keyed run consults the AA API only; an
+    # unkeyed run hydrates from the published catalog only. The catalog
+    # fetcher must NEVER run on keyed builds -- a CI/site build hydrating
+    # from the published catalog would consume its own output (a
+    # self-reference loop). Both chains end in OpenRouter's benchmarks as
+    # the last resort, then nothing.
+    if args.aa_api_key or os.environ.get("AA_API_KEY"):
+        aa_entries, aa_source, aa_cached, aa_index_version = fetch_aa_entries(args)
+        catalog_quality = None
+        catalog_generated_at = None
+    else:
+        aa_entries, aa_source, aa_cached, aa_index_version = [], None, False, None
+        # None (transport failure) and an empty by_id (fetched-but-unusable
+        # artifact) both degrade to no catalog tier -- resolve_quality and
+        # the footer treat them identically as "catalog unavailable".
+        catalog_doc = fetch_quality_catalog(args)
+        catalog_quality = (catalog_doc or {}).get("by_id") or None
+        # The catalog meta only means something when hydration actually
+        # produced rows: an unusable artifact contributes no meta, so the
+        # sources block and the mode never credit a catalog that yielded
+        # nothing.
+        catalog_generated_at = (
+            (catalog_doc or {}).get("generated_at") if catalog_quality else None
+        )
     exact, fuzzy = build_aa_lookup(aa_entries)
 
     filtered = []
     candidates, dropped = build_candidates(models, args, discounts, zdr_ids, filtered)
+    # The provider-aware stage: every surviving candidate is repriced at its
+    # baseline endpoint (or dropped fail-closed) before any scoring runs.
+    candidates, extra_dropped = apply_endpoint_pricing(candidates, args, filtered)
+    dropped.update(extra_dropped)
     if not candidates:
-        warn(
-            f"no models satisfy the filters (min-context={args.min_context}, "
-            f"tools={'off' if args.no_require_tools else 'required'}); relax them and retry"
-        )
+        # When the endpoint stage wiped the pool, naming the filter knobs is
+        # misleading (they passed; the drops came after) -- warn with the
+        # endpoint-stage drop counts instead (both reasons, zero-filled).
+        counts = {r: extra_dropped.get(r, 0) for r in ENDPOINT_DROP_REASONS}
+        if any(counts.values()):
+            bits = ", ".join(f"{k}={v}" for k, v in counts.items())
+            warn(f"no models after the endpoint stage: {bits}")
+        else:
+            warn(
+                f"no models satisfy the filters (min-context={args.min_context}, "
+                f"tools={'off' if args.no_require_tools else 'required'}); "
+                "relax them and retry"
+            )
         return 2
 
     quality_by_id, quality_source_by_id = resolve_quality(
-        candidates, aa_by_id, exact, fuzzy, aa_source
+        candidates, aa_by_id, exact, fuzzy, aa_source, catalog_quality
     )
     weights = compute_scores(candidates, args, quality_by_id)
 
+    # Per-task session-cost medians (Task 7): one fetch per invocation, but
+    # only on the output paths that surface it (--catalog block, --json
+    # rows; publish runs --json per priority, so the cache makes the repeat
+    # cost free). A keyed --best/plain run skips the paginated fetch
+    # entirely -- the medians never reach those outputs. Keyless,
+    # fetch_session_cost returns None before any network or cache access.
+    if args.catalog or args.json:
+        session_cost = fetch_session_cost(args)
+        # The key-presence fact distinguishes "skipped" from "unavailable";
+        # same expression fetch_session_cost uses for its own guard.
+        session_cost_mode = (
+            "skipped"
+            if not (args.openrouter_api_key or os.environ.get("OPENROUTER_API_KEY"))
+            else ("ok" if session_cost else "unavailable")
+        )
+    else:
+        session_cost = None
+        session_cost_mode = "skipped"
+    # run() owns the per-candidate attachment (build_catalog stays pure);
+    # print_json reads it for the session_cost_usd display cell.
+    for cand in candidates:
+        cand["session_cost"] = (session_cost or {}).get("medians", {}).get(cand["id"])
+
     if args.catalog:
         print_catalog(
             build_catalog(
@@ -1887,6 +3616,11 @@ def run(args, models, or_cached) -> int:
                 aa_source,
                 aa_by_id,
                 quality_source_by_id,
+                session_cost,
+                session_cost_mode,
+                aa_index_version,
+                catalog_generated_at,
+                catalog_quality,
             )
         )
         return 0
@@ -1905,23 +3639,14 @@ def run(args, models, or_cached) -> int:
                 f"{v} {k}" for k, v in sorted(dropped.items(), key=lambda kv: -kv[1])
             )
             drop_note = f" (dropped: {bits})"
-        matched_or = sum(1 for s in quality_source_by_id.values() if s == "openrouter")
-        matched_aa = len(quality_by_id) - matched_or
+        # The footer lists per-source counts, each source's own as_of and
+        # the AA index version when known; unmatched candidates and drift
+        # get trailing footnotes. No record resolved -> the quality-blind
+        # fallback note.
         unmatched = len(candidates) - len(quality_by_id)
-        bits = []
-        if matched_or:
-            bits.append(f"OpenRouter benchmarks ({matched_or})")
-        if matched_aa:
-            bits.append(f"{aa_source} exact ({matched_aa})")
-        if bits:
-            quality_note = (
-                f"quality via {' + '.join(bits)}: matched "
-                f"{len(quality_by_id)}/{len(candidates)} candidates"
-            )
-            if unmatched:
-                quality_note += "; unmatched candidates score 0 on quality"
-        else:
-            quality_note = "quality data unavailable, ranked on price/context/age"
+        quality_note = quality_footer_note(
+            quality_by_id, aa_index_version, unmatched
+        ) or ("quality data unavailable, ranked on price/context/age")
         source_note = []
         if or_cached:
             source_note.append("catalog cached")