@molecule/api-resource-ai-models 1.0.2 → 1.2.0

package/dist/models.js

@@ -27,6 +27,18 @@
  *   control) carries `thinkingConfigurable: false` and OMITS both fields —
  *   there is nothing to tune.
  *
+ * ONE GENERATION PER FAMILY. When a provider ships a newer generation of a
+ * model line, the older entry gets `supersededBy: '<newer id>'` and stops being
+ * offered — the picker never shows both `qwen3.7-max` and `qwen3.8-max`. The
+ * entry is NEVER deleted: `getModel()` still resolves it so saved selections and
+ * historical usage stay priceable, and a persisted id resolves forward to the
+ * successor. Supersede only within the same TIER: a cheaper or specialist model
+ * with no newer equivalent (`gemini-3.1-pro-preview`, `qwen3-coder-plus`,
+ * `kimi-k2.7-code`, `grok-build-0.1`) keeps at most `deprecatedAt`, so every
+ * provider keeps a real choice. `__tests__/lookup.test.ts` fails on any two
+ * selectable models of one family at different versions that aren't a
+ * documented exception.
+ *
  * Sources (verified 2026-07-28; OpenAI re-verified 2026-07-31 after the
  * 2026-07-30 GPT-5.6 repricing — cross-check prices against models.dev with
  * `npm run check:model-freshness` from the workspace root):
@@ -48,21 +60,31 @@
  *   2026-07-21 $1.50/$7.50 supersedes 3.5-flash as the agentic flagship;
  *   gemini-3.1-pro-preview still the pro tier — "3.5 Pro" has NOT shipped as
  *   of 2026-07-28 despite the coming-soon badge; do not add until it has an id)
+ *   (re-verified 2026-08-13: gemini-3.7-flash "New Stable" — supersedes
+ *   3.6-flash as the flash flagship at the SAME list price ($1.50/$7.50, cache
+ *   read $0.15), with a launch promo ($0.75/$3.75, cache read $0.075) through
+ *   2026-12-31 billed here at list; specs from /docs/models/gemini-3.7-flash:
+ *   1M ctx / 65,536 out, thinking low|medium|high (no minimal), vision, tools,
+ *   caching, search grounding, code execution, url context)
  * - xAI: https://docs.x.ai/developers/models + /developers/grok-4-5
  *   (grok-4.5 flagship 2026-07-08: $2/$6, 500K ctx, ≥200K prompts bill 2× —
  *   not modeled; reasoning_effort low|medium|high default high, image input;
  *   grok-4.3 still served at $1.25/$2.50 with the bigger 1M window;
  *   grok-code-fast-1 no longer listed — retires 2026-08-15)
- * - DeepSeek: https://api-docs.deepseek.com/quick_start/pricing (unchanged V4
- *   Pro/Flash pricing; legacy deepseek-chat/-reasoner ids fully retired
- *   2026-07-24 — never in this catalog; the announced peak-hour 2× surcharge is
- *   still NOT active as of 2026-07-28, see the entries)
- * - Moonshot: https://platform.kimi.ai/docs/models (kimi-k3 flagship 2026-07-16
+ * - DeepSeek: https://api-docs.deepseek.com/quick_start/pricing (verified
+ *   2026-08-14; legacy deepseek-chat/-reasoner ids fully retired 2026-07-24 —
+ *   never in this catalog. V4-Pro GA on 2026-08-13 came with a price RISE
+ *   effective 2026-08-16T16:00Z plus the long-announced peak-hour 2×: both
+ *   entries carry it as `scheduledPricing`, so today's rates bill until that
+ *   instant and the new ones after. Re-verify weekday-vs-daily peak windows and
+ *   the CN/US region default once it lands — see the entries.)
+ * - Moonshot: https://platform.kimi.ai/docs/models + DeepInfra's model API for
+ *   the US re-host (kimi-k3 flagship 2026-07-16
  *   — 2.8T MoE, 1M ctx, $3/$15 — NOT added: thinking is forced-on with
  *   reasoning_content that must be replayed through tool loops, the same
- *   constraint that keeps kimi-k2.7-code out; add BOTH once the moonshot bond
- *   supports preserved thinking + reasoning_effort low|high|max. kimi-k2.6
- *   remains the newest model the bond can run correctly.)
+ *   constraint that kept kimi-k2.7-code out. BOTH are now in the catalog: the
+ *   moonshot bond gained preserved thinking (reasoning replayed through tool
+ *   loops), so kimi-k3 is the Moonshot pick.)
  * - MiniMax: https://platform.minimax.io/docs/guides/pricing-paygo (unchanged;
  *   minimax-m3 $0.30/$1.20 is a "permanent 50% off" list rate)
  * - Alibaba: https://www.alibabacloud.com/help/en/model-studio/deep-thinking
@@ -191,9 +213,11 @@ export const MODELS = [
         cacheReadPricePerMTok: 0.5,
         cacheWritePricePerMTok: 6.25,
         knowledgeCutoff: '2026-01-01',
-        // Superseded by claude-opus-5 (same price); still served upstream and the
-        // recommended refusal-fallback target. Selectable under "Older models".
+        // Superseded by claude-opus-5 (same price, same tier); still served upstream
+        // and the recommended refusal-fallback target, so it stays priceable and
+        // callable by id — it is just not OFFERED, since opus-5 is a drop-in.
         deprecatedAt: '2026-07-28',
+        supersededBy: 'claude-opus-5',
     },
     {
         id: 'claude-sonnet-5',
@@ -255,9 +279,12 @@ export const MODELS = [
         knowledgeCutoff: '2026-01-01',
         // Superseded by claude-opus-4-8 (launched 2026-05-28) at identical pricing;
         // still Active upstream (deprecations page 2026-08-06: retires no sooner
-        // than 2027-04-16). Selectable under "Older models". NO fast mode —
-        // speed:"fast" on 4.7 returns an error (pricing page, fast-mode section).
+        // than 2027-04-16). NO fast mode — speed:"fast" on 4.7 returns an error
+        // (pricing page, fast-mode section). `supersededBy` names the CURRENT
+        // selectable Opus (opus-5), not the also-superseded 4.8, so a saved
+        // selection resolves forward in one hop.
         deprecatedAt: '2026-05-28',
+        supersededBy: 'claude-opus-5',
     },
     {
         id: 'claude-opus-4-6',
@@ -285,8 +312,9 @@ export const MODELS = [
         cacheReadPricePerMTok: 0.5,
         cacheWritePricePerMTok: 6.25,
         knowledgeCutoff: '2025-05-01',
-        // Superseded by claude-opus-4-8; kept selectable (Older models) + priceable.
+        // Superseded by the current Opus (opus-5) — kept priceable, not offered.
         deprecatedAt: '2026-06-16',
+        supersededBy: 'claude-opus-5',
     },
     {
         id: 'claude-sonnet-4-6',
@@ -315,8 +343,9 @@ export const MODELS = [
         cacheReadPricePerMTok: 0.3,
         cacheWritePricePerMTok: 3.75,
         knowledgeCutoff: '2025-08-01',
-        // Superseded by claude-sonnet-5; kept selectable (Older models) + priceable.
+        // Superseded by claude-sonnet-5 (same tier) — kept priceable, not offered.
         deprecatedAt: '2026-07-07',
+        supersededBy: 'claude-sonnet-5',
     },
     {
         id: 'claude-haiku-4-5-20251001',
@@ -471,9 +500,10 @@ export const MODELS = [
         cacheReadPricePerMTok: 0.5,
         cacheWritePricePerMTok: 5,
         knowledgeCutoff: '2025-12-01',
-        // Superseded by gpt-5.6-sol (same price); still listed as current by
-        // OpenAI. Selectable under "Older models".
+        // Superseded by gpt-5.6-sol (same frontier tier, same $5/$30); still listed
+        // as current by OpenAI, so it stays priceable — it is just not offered.
         deprecatedAt: '2026-07-09',
+        supersededBy: 'gpt-5.6-sol',
     },
     {
         id: 'gpt-5.4',
@@ -501,9 +531,11 @@ export const MODELS = [
         cacheWritePricePerMTok: 2.5,
         knowledgeCutoff: '2025-08-31',
         // OpenAI still lists gpt-5.4 as current, but gpt-5.6-terra covers this
-        // tier at the same price — moved to "Older models" (deprecatedAt is OUR
-        // picker taxonomy, not OpenAI's deprecations page).
+        // balanced tier for LESS ($2/$12 vs $2.50/$15) — superseded, so the picker
+        // offers only the 5.6 generation (this is OUR taxonomy, not OpenAI's
+        // deprecations page; the model stays priceable).
         deprecatedAt: '2026-07-28',
+        supersededBy: 'gpt-5.6-terra',
     },
     {
         id: 'gpt-5.4-mini',
@@ -530,11 +562,12 @@ export const MODELS = [
         cacheReadPricePerMTok: 0.075,
         cacheWritePricePerMTok: 0.75,
         knowledgeCutoff: '2025-08-31',
-        // OpenAI still lists gpt-5.4-mini as current, but like gpt-5.4 above it's
-        // superseded in our lineup (cheap/fast tier is better served by the newer
-        // models) — moved to "Older models" (deprecatedAt is OUR picker taxonomy,
-        // not OpenAI's deprecations page).
+        // Superseded by gpt-5.6-luna, which IS the newer cheap/fast tier and is
+        // strictly better on every axis that made this the budget pick: $0.20/$1.20
+        // vs $0.75/$4.50 after the 2026-07-30 repricing, and a 1M window vs 400K.
+        // Hiding it therefore costs OpenAI no cheap option. Stays priceable.
         deprecatedAt: '2026-08-01',
+        supersededBy: 'gpt-5.6-luna',
     },
     // ---------------------------------------------------------------------------
     // Google
@@ -548,11 +581,46 @@ export const MODELS = [
     // replace outright: the google bond has never been implemented/wired, so no
     // historical usage can reference the old ids.
     // ---------------------------------------------------------------------------
+    {
+        id: 'gemini-3.7-flash',
+        provider: 'google',
+        label: 'Gemini 3.7 Flash',
+        description: 'Google agentic flagship — complex coding & multi-step execution',
+        // Verified against /docs/models/gemini-3.7-flash (2026-08-13).
+        contextWindow: 1_048_576,
+        maxOutputTokens: 65_536,
+        supportsThinking: true,
+        thinkingBudgetTokens: 10_000,
+        thinkingConfigurable: true,
+        // thinking_level low|medium|high — minimal NOT supported on this model.
+        supportedEffortLevels: ['low', 'medium', 'high'],
+        defaultEffortLevel: 'medium',
+        supportsVision: true,
+        supportsPromptCaching: true,
+        supportsTools: true,
+        webSearchToolType: 'google_search',
+        codeExecutionToolType: 'code_execution',
+        webFetchToolType: 'url_context',
+        // "New Stable" 2026-08-13. LIST price $1.50/$7.50 — same as 3.6-flash.
+        // Google runs a launch promo ($0.75/$3.75, cache read $0.075) through
+        // 2026-12-31; billed here at standard list so metering never under-charges
+        // (same policy as claude-sonnet-5's intro pricing — see the matching
+        // KNOWN_DIVERGENCES entry in scripts/check-model-freshness.mjs, expiring
+        // 2026-12-31).
+        inputPricePerMTok: 1.5,
+        outputPricePerMTok: 7.5,
+        // Gemini context cache: read $0.15/M (0.1× input), no write premium
+        // (storage billed separately per hour — not modeled).
+        cacheReadPricePerMTok: 0.15,
+        cacheWritePricePerMTok: 1.5,
+        // Not on Google's docs — models.dev reports 2026-03 (lead, not authority).
+        knowledgeCutoff: '2026-03-01',
+    },
     {
         id: 'gemini-3.6-flash',
         provider: 'google',
         label: 'Gemini 3.6 Flash',
-        description: 'Google agentic flagship — frontier intelligence + grounding',
+        description: 'Previous Google agentic flagship — frontier intelligence + grounding',
         // Window/output not on the pricing page — carried over from 3.5-flash;
         // re-verify against /docs/models.
         contextWindow: 1_048_576,
@@ -579,6 +647,11 @@ export const MODELS = [
         cacheWritePricePerMTok: 1.5,
         // Not published — best-effort estimate.
         knowledgeCutoff: '2026-01-01',
+        // Superseded by gemini-3.7-flash (2026-08-13) — same flash tier, same list
+        // price; Google's own models page now calls 3.6 "previous-generation".
+        // Still served upstream, so it stays priceable.
+        deprecatedAt: '2026-08-13',
+        supersededBy: 'gemini-3.7-flash',
     },
     {
         id: 'gemini-3.5-flash',
@@ -608,9 +681,12 @@ export const MODELS = [
         cacheReadPricePerMTok: 0.15,
         cacheWritePricePerMTok: 1.5,
         knowledgeCutoff: '2025-01-01',
-        // Superseded by gemini-3.6-flash (2026-07-21); still served upstream.
-        // Selectable under "Older models".
+        // Superseded within the flash tier (first by 3.6-flash on 2026-07-21, now
+        // pointed one hop to gemini-3.7-flash — supersededBy must target a
+        // SELECTABLE model, never a chain). Still served upstream, so it stays
+        // priceable.
         deprecatedAt: '2026-07-21',
+        supersededBy: 'gemini-3.7-flash',
     },
     {
         id: 'gemini-3.1-pro-preview',
@@ -640,6 +716,10 @@ export const MODELS = [
         cacheReadPricePerMTok: 0.2,
         cacheWritePricePerMTok: 2,
         knowledgeCutoff: '2025-01-01',
+        // NOT superseded despite the lower version number: this is Google's only
+        // PRO-tier id (no GA "3.5/3.6 Pro" exists), and the 3.6 flash flagship is a
+        // different tier. Superseding it would leave Google with no deep-reasoning
+        // option at all — see `ModelDefinition.supersededBy` (same-tier rule).
     },
     // ---------------------------------------------------------------------------
     // xAI (Grok)
@@ -703,9 +783,13 @@ export const MODELS = [
         cacheReadPricePerMTok: 0.2,
         cacheWritePricePerMTok: 1.25,
         knowledgeCutoff: '2025-12-01',
-        // Superseded by grok-4.5 as the xAI pick (4.3 keeps the bigger 1M window
-        // — the reason it stays selectable under "Older models").
+        // Superseded by grok-4.5: the previous version of the same general-purpose
+        // Grok line, not a separately-named tier. It keeps a bigger window (1M vs
+        // 500K) and a lower price, which is why it was previously left selectable —
+        // but offering two generations of one family is exactly what the picker no
+        // longer does, and grok-4.5 is xAI's own recommendation. Stays priceable.
         deprecatedAt: '2026-07-28',
+        supersededBy: 'grok-4.5',
     },
     {
         id: 'grok-build-0.1',
@@ -732,6 +816,9 @@ export const MODELS = [
         // Not published by xAI — best-effort estimate (grok-4-generation base).
         knowledgeCutoff: '2025-06-01',
         // Niche coding beta; grok-4.5 is the xAI pick — kept out of the main list.
+        // NOT superseded: its own family (grok-build) has no newer version, and it
+        // is xAI's cheapest tool-capable model, so it stays selectable under
+        // "Older models" (and is the deliberately-weak live selftest target).
         deprecatedAt: '2026-07-28',
     },
     {
@@ -799,20 +886,44 @@ export const MODELS = [
     // DeepSeek
     // Verified: https://api-docs.deepseek.com/quick_start/pricing
     //           https://api-docs.deepseek.com/guides/thinking_mode
-    //           https://api-docs.deepseek.com/updates/ (2026-07-31)
+    //           https://api-docs.deepseek.com/updates/ (2026-08-14)
+    // 2026-08-13: V4-Pro GA — and with it the price rise that the "coming soon"
+    // note below had been waiting on. It is STAGED, not applied: both models
+    // carry `scheduledPricing` effective 2026-08-16T16:00Z, so the catalog bills
+    // today's verified rates until that instant and the new ones after it, with
+    // nobody landing an edit at 16:00 UTC on a Sunday. The new card is
+    // off-peak/peak (peak = exactly 2× off-peak), so it maps onto base rates +
+    // `peakPricing` multiplier 2 — which is why the peak windows removed below
+    // come back here rather than as flat rates.
+    //   pro   off-peak 0.66 / 1.98, cache hit 0.022  (peak 1.32 / 3.96 / 0.044)
+    //   flash off-peak 0.22 / 0.66, cache hit 0.007  (peak 0.44 / 1.32 / 0.014)
+    // Cache HITS are the real move — pro 0.003625 → 0.022 (6.1×) off-peak, 0.044
+    // (12.1×) at peak — and agentic input is ~94% cache hits, so effective input
+    // cost rises far more than the list prices suggest. Both are free-tier models
+    // (flash is `freeTier`, pro is the free-tier planner) on the CN default.
+    // TWO things to re-verify once it lands (2026-08-17):
+    //   1. WEEKDAYS OR DAILY. The rate card says only "Peak hours are 01:00 -
+    //      04:00 and 06:00 - 10:00 UTC (all other hours are off-peak)" with no
+    //      day qualifier, so the windows below are DAILY per the provider's own
+    //      doc; press coverage described them as weekday-only. `peakPricing` has
+    //      no day-of-week concept, so if it is weekday-only this over-bills every
+    //      weekend peak window and needs the field extended, not the numbers
+    //      nudged.
+    //   2. THE CN-VS-US DEFAULT. `regions: ['cn', 'us']` defaults to CN on an
+    //      owner decision (2026-08-01) taken when CN ran ~5.7× cheaper on real
+    //      traffic. Post-change DeepInfra's US flash rates (0.08/0.18/0.016) are
+    //      BELOW CN's new off-peak on both input and output — CN wins only on
+    //      cache reads. Re-derive against measured cache-hit ratios before
+    //      leaving the default where it is.
     // 2026-07-31: DeepSeek-V4-Flash OFFICIAL API launched in public beta — the
     // SAME `deepseek-v4-flash` id now serves the re-post-trained 0731 build
     // (same architecture/size; much stronger agent benchmarks — beats
-    // V4-Pro-Preview on Terminal Bench 2.1 / DeepSWE). No pricing/limit/
-    // capability changes. V4-Pro official release "coming soon" — re-verify
-    // pricing THEN (the announced peak-hour 2× was tied to the V4 official
-    // rollout and is still not on the rate card).
+    // V4-Pro-Preview on Terminal Bench 2.1 / DeepSWE).
     // OpenAI/Anthropic-compatible API; text/code only (no vision); 1M context,
     // 384K max output, automatic context (prompt) caching with ABSOLUTE cache-hit
     // prices (~1/50–1/120 of miss — not the old 0.1× rule). Launch discount made
-    // PERMANENT 2026-05-23 (Pro $1.74/$3.48 → $0.435/$0.87). Peak-hour 2×
-    // pricing announced for the mid-Jul 2026 "V4 official" release — re-verify
-    // then. Thinking now defaults ENABLED upstream and supports tool calling
+    // PERMANENT 2026-05-23 (Pro $1.74/$3.48 → $0.435/$0.87), and ENDED by the
+    // 2026-08-16 rise above. Thinking now defaults ENABLED upstream and supports tool calling
     // (reasoning_effort: high|max), BUT tool loops in thinking mode must replay
     // assistant reasoning_content on every subsequent request (400 on omission).
     // The bond explicitly sends thinking:{type:"disabled"} — Synthase runs
@@ -838,28 +949,49 @@ export const MODELS = [
         // DeepSeek automatic context cache: absolute cache-hit price ($/M).
         cacheReadPricePerMTok: 0.003625,
         cacheWritePricePerMTok: 0.435,
-        // Native-China DEFAULT (owner decision 2026-08-01): the US re-host
-        // (DeepInfra) bills ~3× list and ~28× cache reads, and agentic input is
-        // ~94% cache hits, so US processing ran ~5.7× native on real traffic.
-        // Users opt into US per model via the picker's region control.
+        // Native-China DEFAULT (owner decision 2026-08-01, re-derived 2026-08-14):
+        // the US re-host (DeepInfra) bills ~3× list and ~28× cache reads, and
+        // agentic input is ~94% cache hits, so US processing ran ~5.7× native on
+        // real traffic. The 2026-08-16 rise narrows that to ~2.3× — still decisive,
+        // so Pro stays CN while Flash flipped to US (see its note). Users opt into
+        // US per model via the picker's region control.
         regions: ['cn', 'us'],
-        // The free tier PLANS with this model on the cheap native host (it is the
-        // molecule-dev FREE_TIER_MODELS.plan), so CN is free-tier selectable; the
-        // ~3× US re-host stays paid-only (free users switch to Flash for US).
-        freeTierRegions: ['cn'],
+        // No freeTierRegions: the free tier stopped planning with this model on
+        // 2026-08-14 (minimax-m3 took over — cheaper, and it beat this model on the
+        // selection self-test). The carve-out only ever existed to keep the free
+        // tier's OWN plan default usable, and `freeTierAllows` checks
+        // `FREE_TIER_MODELS[mode] === modelId` before it looks at regions, so
+        // leaving it here would widen nothing — it would just claim a free-tier
+        // relationship that no longer exists.
         // US = DeepInfra, verified 2026-08-01 via api.deepinfra.com/models/
         // deepseek-ai/DeepSeek-V4-Pro. No cache-write premium (omitted → region
         // input rate).
         regionPricing: {
             us: { inputPricePerMTok: 1.3, outputPricePerMTok: 2.6, cacheReadPricePerMTok: 0.1 },
         },
-        // The announced peak-hour 2× surcharge (Beijing business hours) is STILL
-        // NOT ACTIVE as of 2026-07-28 — the official rate card lists a single flat
-        // rate, and no switch-over date is published. The pre-wired windows were
-        // REMOVED: they had been over-billing every peak-window turn 2× for weeks
-        // (this is the free-tier default model, so that directly shrank free
-        // users' allowances). Re-add via `peakPricing` the day DeepSeek's rate
-        // card actually shows the surcharge.
+        // The peak-hour 2× surcharge is now ON the rate card with a dated switch
+        // (2026-08-13 announcement, effective 2026-08-16T16:00Z) — so it is staged
+        // below rather than live. The previously pre-wired windows had been REMOVED
+        // for over-billing every peak-window turn 2× for weeks against a rate card
+        // that showed a single flat rate; staging is what keeps this from repeating
+        // in the other direction. Peak = 01:00-04:00 and 06:00-10:00 UTC (Beijing
+        // business hours), which is 2× the off-peak rates exactly.
+        scheduledPricing: {
+            effectiveFrom: '2026-08-16T16:00:00Z',
+            inputPricePerMTok: 0.66,
+            outputPricePerMTok: 1.98,
+            cacheReadPricePerMTok: 0.022,
+            // DeepSeek charges no cache-write premium — write bills at input.
+            cacheWritePricePerMTok: 0.66,
+            peakPricing: {
+                windows: [
+                    { startMinuteUtc: 60, endMinuteUtc: 240 },
+                    { startMinuteUtc: 360, endMinuteUtc: 600 },
+                ],
+                multiplier: 2,
+            },
+            source: 'https://api-docs.deepseek.com/quick_start/pricing/',
+        },
         // Not published by DeepSeek — best-effort estimate.
         knowledgeCutoff: '2025-07-01',
     },
@@ -887,15 +1019,44 @@ export const MODELS = [
         // DeepSeek automatic context cache: absolute cache-hit price ($/M).
         cacheReadPricePerMTok: 0.0028,
         cacheWritePricePerMTok: 0.14,
-        // Native-China default, matching deepseek-v4-pro (see its note) — even
-        // though Flash's US list price is BELOW native, its cache reads are 6.4×,
-        // and the plan/execute pair defaults to one region deliberately.
-        regions: ['cn', 'us'],
-        // US = DeepInfra, verified 2026-08-01 (api.deepinfra.com/models/…V4-Flash).
+        // US (DeepInfra) DEFAULT as of 2026-08-16 — flipped from CN when DeepSeek's
+        // rise landed (owner decision 2026-08-14). CN was cheaper on real traffic
+        // only because of its cache reads; the rise takes those from $0.0028 to
+        // $0.007 (peak $0.014) against DeepInfra's flat $0.016, which is no longer
+        // enough to carry the 1.6-3.1x it now loses on fresh input and output. On
+        // the agentic mix this model actually serves (~94% cache hits) US is
+        // cheaper at EVERY hour: 0.114c/turn flat vs 0.152c off-peak and 0.303c at
+        // peak. It is also flat-rate, so free-tier cost stops varying by Beijing
+        // business hours. Re-derive if the cache-hit ratio drops much below ~90%,
+        // where CN's cheaper reads start winning again. This deliberately splits
+        // the plan/execute pair across regions — Pro stays CN because its US
+        // re-host is ~2.3x its own native rate even after the rise.
+        regions: ['us', 'cn'],
+        // US = DeepInfra, verified 2026-08-13 against the id the bond actually
+        // sends: `deepseek-ai/DeepSeek-V4-Flash-0731`, the official release that
+        // supersedes the preview weights still served under the un-dated id
+        // (cents_per_input_token 0.000008, cents_per_output_token 0.000018,
+        // rate_per_input_token_cached 0.2 → cache read = 0.2 × input).
         regionPricing: {
-            us: { inputPricePerMTok: 0.09, outputPricePerMTok: 0.18, cacheReadPricePerMTok: 0.018 },
+            us: { inputPricePerMTok: 0.08, outputPricePerMTok: 0.18, cacheReadPricePerMTok: 0.016 },
+        },
+        // Peak-hour surcharge staged, not live (see deepseek-v4-pro).
+        scheduledPricing: {
+            effectiveFrom: '2026-08-16T16:00:00Z',
+            inputPricePerMTok: 0.22,
+            outputPricePerMTok: 0.66,
+            cacheReadPricePerMTok: 0.007,
+            // DeepSeek charges no cache-write premium — write bills at input.
+            cacheWritePricePerMTok: 0.22,
+            peakPricing: {
+                windows: [
+                    { startMinuteUtc: 60, endMinuteUtc: 240 },
+                    { startMinuteUtc: 360, endMinuteUtc: 600 },
+                ],
+                multiplier: 2,
+            },
+            source: 'https://api-docs.deepseek.com/quick_start/pricing/',
         },
-        // Peak-hour surcharge NOT active (see deepseek-v4-pro) — windows removed.
         // Not published by DeepSeek — best-effort estimate.
         knowledgeCutoff: '2025-07-01',
     },
@@ -910,6 +1071,12 @@ export const MODELS = [
     // and kimi-k2.7-code (coding flagship — forced thinking, no depth knob).
     // kimi-k2.x thinking stays on/off only; the bond disables it for those by
     // default (KIMI_REASONING_EFFORT env tunes it).
+    // EVERY moonshot entry declares `regions` explicitly. A model that omits the
+    // field defaults to `['us']` (effectiveModelRegion), which would route it to
+    // the bare `moonshot` bond — DeepInfra when its key is set — with an id that
+    // host has never heard of, i.e. a 404 at dispatch. The freshness gate's
+    // region-re-host coverage check fails on exactly that (a us-region moonshot
+    // model missing from the bond's modelMap).
     // ---------------------------------------------------------------------------
     {
         id: 'kimi-k3',
@@ -936,8 +1103,21 @@ export const MODELS = [
         // Automatic context cache: absolute cache-hit price ($0.30/M = 0.1× input).
         cacheReadPricePerMTok: 0.3,
         cacheWritePricePerMTok: 3,
-        // No US re-host exists (not on DeepInfra) — pinned to native China.
-        regions: ['cn'],
+        // US default = DeepInfra, verified 2026-08-13 against
+        // api.deepinfra.com/models/moonshotai/Kimi-K3: cents_per_input_token
+        // 0.000285 → $2.85/MTok, cents_per_output_token 0.001425 → $14.25/MTok,
+        // rate_per_input_token_cached 0.1 → cache read $0.285/MTok, and
+        // rate_per_input_token_cache_write null → no write premium (the omitted
+        // cache-write field falls back to the region's input rate). Cheaper than
+        // Moonshot native on every axis, which is why US leads (see the
+        // cheapest-default-region invariant in __tests__/lookup.test.ts).
+        // The host serves the full 1M context, unquantized, and returns
+        // reasoning_content while accepting reasoning_effort — probed live
+        // 2026-08-13 — so the preserved-thinking tool loop works there unchanged.
+        regions: ['us', 'cn'],
+        regionPricing: {
+            us: { inputPricePerMTok: 2.85, outputPricePerMTok: 14.25, cacheReadPricePerMTok: 0.285 },
+        },
         // Not published — best-effort estimate.
         knowledgeCutoff: '2026-01-01',
     },
@@ -962,15 +1142,21 @@ export const MODELS = [
         // Automatic context cache: absolute cache-hit price ($0.19/M = 0.2× input).
         cacheReadPricePerMTok: 0.19,
         cacheWritePricePerMTok: 0.95,
-        // US default (DeepInfra bills below native here). Verified 2026-08-01.
+        // US default (DeepInfra bills below native here). Re-verified 2026-08-13
+        // against api.deepinfra.com/models/moonshotai/Kimi-K2.7-Code — the host
+        // repriced since 2026-08-01 ($0.74/$3.50/$0.15): cents_per_input_token
+        // 0.000068, cents_per_output_token 0.00034, rate_per_input_token_cached
+        // 0.2 → cache read $0.136, no write premium.
         regions: ['us', 'cn'],
         regionPricing: {
-            us: { inputPricePerMTok: 0.74, outputPricePerMTok: 3.5, cacheReadPricePerMTok: 0.15 },
+            us: { inputPricePerMTok: 0.68, outputPricePerMTok: 3.4, cacheReadPricePerMTok: 0.136 },
         },
         // Not published — best-effort estimate.
         knowledgeCutoff: '2025-10-01',
-        // kimi-k3 is the Moonshot pick; the coding specialist stays selectable
-        // under "Older models" for anyone who wants the cheaper tier.
+        // kimi-k3 is the Moonshot pick, but this is NOT superseded: the coding
+        // specialist is a distinct, much cheaper tier ($0.95/$4 vs $3/$15) with no
+        // K3 equivalent, so it stays selectable under "Older models" — superseding
+        // it would leave Moonshot with only the flagship.
         deprecatedAt: '2026-07-28',
     },
     {
@@ -1002,8 +1188,9 @@ export const MODELS = [
             us: { inputPricePerMTok: 0.75, outputPricePerMTok: 3.5, cacheReadPricePerMTok: 0.15 },
         },
         knowledgeCutoff: '2025-04-01',
-        // Superseded by kimi-k3; moved to "Older models".
+        // Superseded by kimi-k3 (same general-purpose line) — kept priceable.
         deprecatedAt: '2026-07-28',
+        supersededBy: 'kimi-k3',
     },
     {
         id: 'kimi-k2.5',
@@ -1030,9 +1217,11 @@ export const MODELS = [
             us: { inputPricePerMTok: 0.45, outputPricePerMTok: 2.25, cacheReadPricePerMTok: 0.07 },
         },
         knowledgeCutoff: '2024-04-01',
-        // Superseded by kimi-k2.6 (still served upstream, no announced retirement);
-        // kept selectable (Older models) + priceable.
+        // Two generations behind. `supersededBy` names the current selectable Kimi
+        // (k3) rather than the also-superseded k2.6, so a saved selection resolves
+        // forward in one hop. Still served upstream; stays priceable.
         deprecatedAt: '2026-04-01',
+        supersededBy: 'kimi-k3',
     },
     // ---------------------------------------------------------------------------
     // MiniMax
@@ -1069,8 +1258,21 @@ export const MODELS = [
         // US default. DeepInfra list matches native; only the cache write differs
         // (no premium → region input rate). Verified 2026-08-01.
         regions: ['us', 'cn'],
+        // The free tier PLANS with this model (molecule-dev FREE_TIER_MODELS.plan,
+        // 2026-08-14), so its default US region must be free-tier selectable. It
+        // took over from deepseek-v4-pro@cn: measured on the real starting-point
+        // selection it scored 8/8 against Pro's 7/8 — including the case Pro failed
+        // — at 1.28c/plan-turn flat versus Pro's 2.62c off-peak and 5.24c inside
+        // DeepSeek's Beijing-hours windows, and it adds vision, which Pro (text
+        // only) could not offer discovery. CN is NOT listed: it is dearer than US
+        // here, so free planning stays on the cheaper host.
+        freeTierRegions: ['us'],
         regionPricing: {
-            us: { inputPricePerMTok: 0.3, outputPricePerMTok: 1.2, cacheReadPricePerMTok: 0.06 },
+            // Verified 2026-08-14 against api.deepinfra.com/models/MiniMaxAI/MiniMax-M3
+            // (cache read = 0.2 × input). Was 0.3/1.2/0.06 — DeepInfra had repriced
+            // and nothing noticed, because the freshness gate's re-host check only
+            // covered deepseek and moonshot until this date.
+            us: { inputPricePerMTok: 0.28, outputPricePerMTok: 1.1, cacheReadPricePerMTok: 0.056 },
         },
         // From the official HF chat template ("Knowledge cutoff: January 2026").
         knowledgeCutoff: '2026-01-01',
@@ -1101,9 +1303,9 @@ export const MODELS = [
             us: { inputPricePerMTok: 0.25, outputPricePerMTok: 1, cacheReadPricePerMTok: 0.05 },
         },
         knowledgeCutoff: '2025-09-01',
-        // Superseded by minimax-m3 (same price, 1M ctx, multimodal); moved to
-        // "Older models".
+        // Superseded by minimax-m3 (same price, 1M ctx, multimodal) — kept priceable.
         deprecatedAt: '2026-07-28',
+        supersededBy: 'minimax-m3',
     },
     {
         id: 'minimax-m2.5',
@@ -1126,17 +1328,18 @@ export const MODELS = [
         // No US re-host exists (not on DeepInfra) — pinned to native China.
         regions: ['cn'],
         knowledgeCutoff: '2025-01-01',
-        // Superseded by minimax-m3 (legacy upstream, still served); kept selectable
-        // (Older models) + priceable.
+        // Superseded by minimax-m3 (legacy upstream, still served) — kept priceable.
         deprecatedAt: '2026-03-18',
+        supersededBy: 'minimax-m3',
     },
     // ---------------------------------------------------------------------------
     // Alibaba (Qwen)
     // Verified: https://www.alibabacloud.com/help/en/model-studio/deep-thinking
     //           https://www.alibabacloud.com/help/en/model-studio/qwen-coder
     //           https://openrouter.ai/qwen/qwen3.7-max
-    // qwen3.7-max (2026-05-21) is the agentic flagship — Alibaba's own Qwen-Coder
-    // docs now recommend the general-purpose models over Qwen-Coder. Its thinking
+    // qwen3.8-max (2026-08-03) is the agentic flagship, succeeding qwen3.7-max —
+    // Alibaba's own Qwen-Coder docs now recommend the general-purpose models over
+    // Qwen-Coder. Their thinking
     // uses enable_thinking (default ON for the 3.7 series) + thinking_budget
     // (token cap) — a real budget param, so effort scales the budget. The
     // qwen3-coder models are NON-thinking (previous catalog entry was wrong).
@@ -1176,6 +1379,14 @@ export const MODELS = [
         cacheReadPricePerMTok: 0.4,
         cacheWritePricePerMTok: 2,
         regions: ['us', 'cn'],
+        // US = DeepInfra (Qwen/Qwen3.8-Max), verified 2026-08-14 against
+        // api.deepinfra.com/models/ (cache read = 0.1248 x input). ABSENT until then:
+        // every US turn was metered at Alibaba's native rates while running on
+        // DeepInfra, and the model 404'd outright because the bond's modelMap had
+        // never been updated past qwen3.7-max.
+        regionPricing: {
+            us: { inputPricePerMTok: 1.65, outputPricePerMTok: 4.951, cacheReadPricePerMTok: 0.206 },
+        },
         // Not published by Alibaba — best-effort estimate.
         knowledgeCutoff: '2026-04-01',
     },
@@ -1205,8 +1416,18 @@ export const MODELS = [
         // US default. DeepInfra bills identical rates (no regionPricing needed).
         // Verified 2026-08-01.
         regions: ['us', 'cn'],
+        // US = DeepInfra, verified 2026-08-14 (cache read = 0.2 x input). Superseded,
+        // but still priceable for historical usage, so its region rates must be real.
+        regionPricing: {
+            us: { inputPricePerMTok: 2.5, outputPricePerMTok: 7.5, cacheReadPricePerMTok: 0.5 },
+        },
         // Not published by Alibaba — best-effort estimate.
         knowledgeCutoff: '2026-01-01',
+        // Superseded by qwen3.8-max (GA 2026-08-03): same tier and mechanism, and
+        // CHEAPER at list ($2/$6 vs $2.50/$7.50). Still served upstream (the 50%-off
+        // promo runs on this id), so it stays priceable — it is just not offered.
+        deprecatedAt: '2026-08-03',
+        supersededBy: 'qwen3.8-max',
     },
     {
         id: 'qwen3-coder-plus',
@@ -1236,8 +1457,11 @@ export const MODELS = [
             us: { inputPricePerMTok: 0.3, outputPricePerMTok: 1, cacheReadPricePerMTok: 0.1 },
         },
         knowledgeCutoff: '2025-06-01',
-        // Alibaba itself recommends the general-purpose models over Qwen-Coder;
-        // qwen3.7-max is the pick — moved to "Older models".
+        // Alibaba itself recommends the general-purpose models over Qwen-Coder, so
+        // this sits in "Older models" — but it is NOT superseded: it is a distinct
+        // coding specialist and Alibaba's cheap tier (US $0.30/$1 vs qwen3.8-max's
+        // $2/$6), with no newer coder id. Superseding it would leave Alibaba with
+        // only the flagship.
         deprecatedAt: '2026-07-28',
     },
     // ---------------------------------------------------------------------------
@@ -1309,7 +1533,9 @@ export const MODELS = [
             us: { inputPricePerMTok: 0.6, outputPricePerMTok: 2.08, cacheReadPricePerMTok: 0.12 },
         },
         knowledgeCutoff: '2025-01-01',
-        // Superseded by glm-5.2; moved to "Older models".
+        // Superseded by glm-5.2 (same line, bigger window, reasoning_effort) — kept
+        // priceable.
         deprecatedAt: '2026-07-28',
+        supersededBy: 'glm-5.2',
     },
 ];