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

package/README.md

@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-08-06T19:42:52.531Z
+Generated: 2026-08-13T22:10:11.926Z
 -->
 
 # @molecule/api-resource-ai-models
@@ -260,6 +260,57 @@ interface ModelDefinition {
     windows: { startMinuteUtc: number; endMinuteUtc: number }[]
     multiplier: number
   }
+  /**
+   * A price change the provider has ANNOUNCED with a dated effective instant,
+   * staged ahead of time. Until `effectiveFrom` the model bills at the base
+   * rates above; from that instant on, these rates replace them.
+   *
+   * This exists because the freshness gate can only ever see prices that are
+   * ALREADY live: it diffs the catalog against models.dev's *current* rates, so
+   * a change announced today and effective in three days is invisible to it
+   * until after it lands — and the cron runs every 8h, so the catalog would
+   * under-meter for up to a third of a day at whatever the new rate is. Landing
+   * the new numbers early is not an option either: that over-bills every turn
+   * until the switch (the exact mistake the removed DeepSeek peak windows made
+   * for weeks against the free-tier default model). Staging with a timestamp is
+   * the only form that is correct on BOTH sides of the instant, and it needs no
+   * one awake at the switch.
+   *
+   * Applies to the BASE rates only — a `regionPricing` entry is a different
+   * host's rate card (a US re-host does not reprice because the native provider
+   * did) and is never touched by a scheduled change.
+   *
+   * `peakPricing` here, when declared, replaces the model's peak windows from
+   * the same instant; when omitted, the model's existing windows carry through
+   * unchanged. To schedule the END of peak pricing, declare an explicit
+   * `{ windows: [], multiplier: 1 }`.
+   *
+   * Resolution is `effectiveBaseRates()` / `effectivePeakPricing()`, and every
+   * consumer reaches it through `modelRegionRates()` / `priceMultiplierAt()` /
+   * the `withEffectivePricing()` projection the list handler serves — so a
+   * scheduled change lands everywhere at once with no follow-up edit. Once the
+   * instant has passed, fold the rates into the base fields and delete this
+   * (the freshness gate now verifies them against models.dev normally).
+   */
+  scheduledPricing?: {
+    /** ISO-8601 UTC instant the new rates take effect. */
+    effectiveFrom: string
+    /** Input price per million *uncached* tokens in USD, from `effectiveFrom`. */
+    inputPricePerMTok: number
+    /** Output price per million tokens in USD, from `effectiveFrom`. */
+    outputPricePerMTok: number
+    /** Prompt-cache *read* price per million tokens in USD, from `effectiveFrom`. */
+    cacheReadPricePerMTok: number
+    /** Prompt-cache *write* price per million tokens in USD, from `effectiveFrom`. */
+    cacheWritePricePerMTok: number
+    /** Peak-hour pricing from `effectiveFrom` (omitted → existing windows carry through). */
+    peakPricing?: {
+      windows: { startMinuteUtc: number; endMinuteUtc: number }[]
+      multiplier: number
+    }
+    /** Where the change was announced, for the re-verify pass after it lands. */
+    source?: string
+  }
   /**
    * Fast-mode ("priority speed") pricing — the per-MTok rates billed when a
    * request runs with the provider's fast/priority tier (e.g. Anthropic's
@@ -310,6 +361,35 @@ interface ModelDefinition {
    * or its past usage silently meters as free. Omit entirely for active models.
    */
   disabled?: boolean
+  /**
+   * The id of the NEWER-generation model that replaces this one, set on the
+   * OLDER entry and naming its successor (e.g. `qwen3.7-max` carries
+   * `supersededBy: 'qwen3.8-max'`).
+   *
+   * A superseded model is NOT selectable — like {@link disabled} it is excluded
+   * from `MODEL_IDS`, `getAvailableModels()`, the `GET /ai/models` listing and
+   * the client-side picker partitions, so a user is only ever offered the
+   * newest generation of a family. It differs from `disabled` in *why* and in
+   * what it points at: a disabled model is one the provider retired (it can no
+   * longer answer), whereas a superseded model is usually still served upstream
+   * and simply has nothing to offer over its successor — and the successor id
+   * is a real migration target, so a saved selection can resolve forward
+   * (`resolveSelectableModelId`) instead of silently falling back to the
+   * platform default.
+   *
+   * `getModel(id)` STILL returns a superseded entry — historical usage must stay
+   * priceable, so NEVER delete one.
+   *
+   * Set this ONLY when the successor covers the same TIER. A cheaper or
+   * specialist tier with no newer equivalent is NOT superseded merely because
+   * its version number is lower (Google's sole pro tier `gemini-3.1-pro-preview`
+   * alongside the newer flash flagship; `qwen3-coder-plus`; `kimi-k2.7-code`) —
+   * hiding those would leave a provider with no cheap option. Mark those
+   * {@link deprecatedAt} at most. The invariant is enforced by
+   * `__tests__/lookup.test.ts`: two selectable models of the same family at
+   * different versions fail unless listed there as a documented exception.
+   */
+  supersededBy?: string
 }
 ```
 
@@ -402,6 +482,25 @@ type EffortLevel = string
 
 ### Functions
 
+#### `effectiveBaseRates(modelDef, at)`
+
+A model's BASE token rates in effect at a given instant — the staged
+{@link ModelDefinition.scheduledPricing} rates once their `effectiveFrom` has
+passed, else the base fields.
+
+These are the native provider's rates. A `regionPricing` override is a
+different host's rate card and is resolved separately by
+{@link modelRegionRates}.
+
+```typescript
+function effectiveBaseRates(modelDef: ModelDefinition, at?: Date): ModelTokenRates
+```
+
+- `modelDef` — The model definition.
+- `at` — The instant to price at (defaults to now).
+
+**Returns:** The base rates in effect at that instant.
+
 #### `effectiveModelRegion(modelDef, requested)`
 
 Resolve a model's effective processing region: the requested region when the
@@ -419,12 +518,32 @@ function effectiveModelRegion(modelDef: ModelDefinition | undefined, requested?:
 
 **Returns:** The effective region code.
 
+#### `effectivePeakPricing(modelDef, at)`
+
+A model's peak-hour pricing in effect at a given instant: the staged
+{@link ModelDefinition.scheduledPricing} `peakPricing` once its
+`effectiveFrom` has passed (when that entry declares one — an omitted one
+leaves the existing windows in force), else the model's own `peakPricing`.
+
+```typescript
+function effectivePeakPricing(
+  modelDef: ModelDefinition,
+  at?: Date,
+): { windows: { startMinuteUtc: number; endMinuteUtc: number }[]; multiplier: number } | undefined
+```
+
+- `modelDef` — The model definition.
+- `at` — The instant to evaluate (defaults to now).
+
+**Returns:** The peak-pricing config in effect, or `undefined` when none is.
+
 #### `getAvailableModels(availableProviders)`
 
 Get models that are currently usable — filtered to only providers that are available.
 
 The caller passes in which provider IDs are active (i.e. have a bond wired).
-`disabled` models are excluded — they are never offered for selection.
+Models that are not {@link isSelectableModel} — `disabled` or superseded by a
+newer generation — are excluded; they are never offered for selection.
 
 ```typescript
 function getAvailableModels(
@@ -434,16 +553,16 @@ function getAvailableModels(
 
 - `availableProviders` — Set or array of provider IDs that have active bonds.
 
-**Returns:** Non-disabled models whose provider is in the available set.
+**Returns:** Selectable models whose provider is in the available set.
 
 #### `getModel(id)`
 
 Look up a model definition by ID.
 
-Returns `disabled` models too: a saved selection or a historical usage row
-may reference a since-retired model, and it must stay priceable. Use
-{@link MODEL_IDS} / {@link getAvailableModels} (which exclude disabled
-models) to decide what is _selectable_.
+Returns `disabled` and `supersededBy` models too: a saved selection or a
+historical usage row may reference a since-retired or since-superseded model,
+and it must stay priceable. Use {@link MODEL_IDS} / {@link getAvailableModels}
+(or {@link isSelectableModel}) to decide what is _selectable_.
 
 ```typescript
 function getModel(id: string): ModelDefinition | undefined
@@ -465,6 +584,21 @@ function getModelsByProvider(provider: AIProviderID): readonly ModelDefinition[]
 
 **Returns:** Array of model definitions for that provider.
 
+#### `isSelectableModel(model)`
+
+Whether a model may be offered for selection: not `disabled` (retired
+upstream) and not `supersededBy` a newer generation of its own family. Both
+kinds stay in the catalog for pricing — this predicate is the single place
+that decides _exposure_, so every listing/validation surface agrees.
+
+```typescript
+function isSelectableModel(model: Pick<ModelDefinition, 'disabled' | 'supersededBy'>): boolean
+```
+
+- `model` — The model definition (or the two flags from one).
+
+**Returns:** True when the model may be listed and chosen.
+
 #### `list(_req, res)`
 
 Returns models whose `provider` has a bond registered under the `'ai'`
@@ -482,41 +616,95 @@ function list(_req: MoleculeRequest, res: MoleculeResponse): Promise<void>
 - `_req` — The request object (unused).
 - `res` — The response object.
 
-#### `modelRegionRates(modelDef, requested)`
+#### `modelRegionRates(modelDef, requested, at)`
 
 The token rates for a model in a given processing region: the model's
 {@link ModelDefinition.regionPricing} override for the region when one
-exists, else the base rates (the native provider's list prices). Omitted
-cache fields in an override fall back to the override's input price (hosts
-with no cache discount / no write premium). The region is resolved via
-{@link effectiveModelRegion}, so callers may pass the raw user choice.
+exists, else the base rates in effect at `at` (the native provider's list
+prices, including any staged {@link ModelDefinition.scheduledPricing} change
+that has landed). Omitted cache fields in an override fall back to the
+override's input price (hosts with no cache discount / no write premium). The
+region is resolved via {@link effectiveModelRegion}, so callers may pass the
+raw user choice.
+
+`at` defaults to NOW rather than being required, so an existing caller cannot
+keep billing a superseded rate by omitting it — metering should still pass
+each request's own timestamp, the same way it must for
+{@link priceMultiplierAt}.
 
 ```typescript
-function modelRegionRates(modelDef: ModelDefinition, requested?: string): ModelTokenRates
+function modelRegionRates(modelDef: ModelDefinition, requested?: string, at?: Date): ModelTokenRates
 ```
 
 - `modelDef` — The model definition.
 - `requested` — The user's per-model region choice, if any.
+- `at` — The instant to price at (defaults to now).
 
 **Returns:** The region-effective rates.
 
-#### `priceMultiplierAt(modelDef, at)`
+#### `priceMultiplierAt(modelDef, at, region)`
 
-The price multiplier in effect for a model at a given instant.
+The price multiplier in effect for a model at a given instant, in a region.
 
 Consults the model's {@link ModelDefinition.peakPricing} windows (UTC,
 half-open, may wrap midnight). Metering MUST call this with each request's
 own timestamp so peak-hour usage bills at the provider's real rate — pricing
 everything at the flat rate silently under-meters peak traffic.
 
+Peak windows belong to the NATIVE provider, so they apply only where the base
+rates do. A region with a {@link ModelDefinition.regionPricing} override is a
+different host billing its own complete rate card, including whether it has
+time-of-day pricing at all — and re-hosts generally do not. Applying the
+native provider's surcharge on top of a re-host's flat rates would over-bill
+every turn in its windows (DeepSeek's 2× Beijing-hours pricing charged
+against DeepInfra, which has no peak pricing).
+
 ```typescript
-function priceMultiplierAt(modelDef: ModelDefinition | undefined, at: Date): number
+function priceMultiplierAt(modelDef: ModelDefinition | undefined, at: Date, region?: string): number
 ```
 
 - `modelDef` — The model definition (or undefined).
 - `at` — The instant the request was made.
+- `region` — The user's per-model region choice, if any (omitted → the model's default region).
 
-**Returns:** The multiplier (`1` outside peak windows or when none are declared).
+**Returns:** The multiplier (`1` outside peak windows, when none are declared, or in a region that prices off its own override).
+
+#### `resolveSelectableModelId(id)`
+
+Resolve a model id FORWARD to the selectable model that replaces it, following
+the {@link ModelDefinition.supersededBy} chain (a saved `qwen3.7-max` →
+`qwen3.8-max`). Lets a persisted selection keep the user's intent — the same
+tier from the same provider — instead of falling back to the platform default
+once the older generation stops being offered.
+
+```typescript
+function resolveSelectableModelId(id: string): string | undefined
+```
+
+- `id` — The persisted model id.
+
+**Returns:** The selectable successor's id, the id itself when it is already selectable, or `undefined` for an unknown or `disabled` model (nothing to forward to).
+
+#### `withEffectivePricing(modelDef, at)`
+
+A model projected onto the pricing in effect at a given instant: the staged
+{@link ModelDefinition.scheduledPricing} rates folded into the base fields
+(and its peak windows into `peakPricing`) once effective, with the staged
+entry stripped.
+
+This is what the `GET /ai/models` handler serves, so a client renders the
+rates that are actually billing right now without needing to resolve a
+schedule against its own clock — the server's clock is the only one that
+decides when a price change lands.
+
+```typescript
+function withEffectivePricing(modelDef: ModelDefinition, at?: Date): ModelDefinition
+```
+
+- `modelDef` — The model definition.
+- `at` — The instant to project at (defaults to now).
+
+**Returns:** The model with effective pricing and no `scheduledPricing`.
 
 ### Constants
 
@@ -525,8 +713,9 @@ function priceMultiplierAt(modelDef: ModelDefinition | undefined, at: Date): num
 Set of _selectable_ model IDs for fast validation.
 
 Excludes `disabled` models so a retired model (e.g. `grok-code-fast-1`) can
-never be chosen for a new chat, while {@link getModel} still resolves it for
-historical pricing.
+never be chosen for a new chat, and `supersededBy` models so an older
+generation of a family (e.g. `qwen3.7-max` next to `qwen3.8-max`) is never
+offered — while {@link getModel} still resolves both for historical pricing.
 
 ```typescript
 const MODEL_IDS: ReadonlySet<string>
@@ -554,6 +743,18 @@ Effort is each model's OWN native value — there is no abstract scale (see
   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):
@@ -576,21 +777,31 @@ Sources (verified 2026-07-28; OpenAI re-verified 2026-07-31 after the
   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

package/dist/handlers/list.d.ts

@@ -2,10 +2,18 @@
  * `GET /ai/models` — returns the catalog of available AI models.
  *
  * Filters the central `MODELS` list to only those whose provider is currently
- * bonded under the `'ai'` category AND are not `disabled` (a retired model is
- * never listed for selection, though `getModel` still prices it). No further
- * projection is applied — every `ModelDefinition` field is fine to expose to
- * authenticated clients today.
+ * bonded under the `'ai'` category AND are selectable — neither `disabled` (a
+ * model the provider retired) nor superseded by a newer generation of the same
+ * family, so the picker offers exactly one generation per family. Both kinds
+ * stay priceable via `getModel`.
+ *
+ * The one projection applied is `withEffectivePricing`: a model carrying a
+ * staged `scheduledPricing` change is served at whichever rates are billing at
+ * request time, with the schedule stripped. The server's clock decides when an
+ * announced price change lands, so a client never renders a rate that is not
+ * yet in force (nor keeps rendering one that has been superseded), and no
+ * client needs to know that scheduled pricing exists. Every other
+ * `ModelDefinition` field is fine to expose to authenticated clients today.
  *
  * Secure-by-default: this handler enforces authentication IN the handler
  * (`res.locals.session.userId`) and fails closed with `401` for an

package/dist/handlers/list.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../src/handlers/list.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAK/E;;;;;;;;;;;GAWG;AACH,wBAAsB,IAAI,CAAC,IAAI,EAAE,eAAe,EAAE,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CActF"}
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../src/handlers/list.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAM/E;;;;;;;;;;;GAWG;AACH,wBAAsB,IAAI,CAAC,IAAI,EAAE,eAAe,EAAE,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBtF"}

package/dist/handlers/list.js

@@ -2,10 +2,18 @@
  * `GET /ai/models` — returns the catalog of available AI models.
  *
  * Filters the central `MODELS` list to only those whose provider is currently
- * bonded under the `'ai'` category AND are not `disabled` (a retired model is
- * never listed for selection, though `getModel` still prices it). No further
- * projection is applied — every `ModelDefinition` field is fine to expose to
- * authenticated clients today.
+ * bonded under the `'ai'` category AND are selectable — neither `disabled` (a
+ * model the provider retired) nor superseded by a newer generation of the same
+ * family, so the picker offers exactly one generation per family. Both kinds
+ * stay priceable via `getModel`.
+ *
+ * The one projection applied is `withEffectivePricing`: a model carrying a
+ * staged `scheduledPricing` change is served at whichever rates are billing at
+ * request time, with the schedule stripped. The server's clock decides when an
+ * announced price change lands, so a client never renders a rate that is not
+ * yet in force (nor keeps rendering one that has been superseded), and no
+ * client needs to know that scheduled pricing exists. Every other
+ * `ModelDefinition` field is fine to expose to authenticated clients today.
  *
  * Secure-by-default: this handler enforces authentication IN the handler
  * (`res.locals.session.userId`) and fails closed with `401` for an
@@ -19,6 +27,7 @@
  */
 import { getAll } from '@molecule/api-bond';
 import { t } from '@molecule/api-i18n';
+import { isSelectableModel, withEffectivePricing } from '../lookup.js';
 import { MODELS } from '../models.js';
 /**
  * Returns models whose `provider` has a bond registered under the `'ai'`
@@ -42,7 +51,8 @@ export async function list(_req, res) {
         return;
     }
     const bondedProviders = new Set(getAll('ai').keys());
-    const models = MODELS.filter((m) => bondedProviders.has(m.provider) && !m.disabled);
-    const response = { models: [...models] };
+    const now = new Date();
+    const models = MODELS.filter((m) => bondedProviders.has(m.provider) && isSelectableModel(m)).map((m) => withEffectivePricing(m, now));
+    const response = { models };
     res.json(response);
 }

package/dist/lookup.d.ts

@@ -4,21 +4,45 @@
  * @module
  */
 import type { AIProviderID, ModelDefinition } from './types.js';
+/**
+ * Whether a model may be offered for selection: not `disabled` (retired
+ * upstream) and not `supersededBy` a newer generation of its own family. Both
+ * kinds stay in the catalog for pricing — this predicate is the single place
+ * that decides *exposure*, so every listing/validation surface agrees.
+ *
+ * @param model - The model definition (or the two flags from one).
+ * @returns True when the model may be listed and chosen.
+ */
+export declare function isSelectableModel(model: Pick<ModelDefinition, 'disabled' | 'supersededBy'>): boolean;
+/**
+ * Resolve a model id FORWARD to the selectable model that replaces it, following
+ * the {@link ModelDefinition.supersededBy} chain (a saved `qwen3.7-max` →
+ * `qwen3.8-max`). Lets a persisted selection keep the user's intent — the same
+ * tier from the same provider — instead of falling back to the platform default
+ * once the older generation stops being offered.
+ *
+ * @param id - The persisted model id.
+ * @returns The selectable successor's id, the id itself when it is already
+ *   selectable, or `undefined` for an unknown or `disabled` model (nothing to
+ *   forward to).
+ */
+export declare function resolveSelectableModelId(id: string): string | undefined;
 /**
  * Set of *selectable* model IDs for fast validation.
  *
  * Excludes `disabled` models so a retired model (e.g. `grok-code-fast-1`) can
- * never be chosen for a new chat, while {@link getModel} still resolves it for
- * historical pricing.
+ * never be chosen for a new chat, and `supersededBy` models so an older
+ * generation of a family (e.g. `qwen3.7-max` next to `qwen3.8-max`) is never
+ * offered — while {@link getModel} still resolves both for historical pricing.
  */
 export declare const MODEL_IDS: ReadonlySet<string>;
 /**
  * Look up a model definition by ID.
  *
- * Returns `disabled` models too: a saved selection or a historical usage row
- * may reference a since-retired model, and it must stay priceable. Use
- * {@link MODEL_IDS} / {@link getAvailableModels} (which exclude disabled
- * models) to decide what is *selectable*.
+ * Returns `disabled` and `supersededBy` models too: a saved selection or a
+ * historical usage row may reference a since-retired or since-superseded model,
+ * and it must stay priceable. Use {@link MODEL_IDS} / {@link getAvailableModels}
+ * (or {@link isSelectableModel}) to decide what is *selectable*.
  *
  * @param id - The API model ID.
  * @returns The model definition, or `undefined` if not found.
@@ -35,25 +59,78 @@ export declare function getModelsByProvider(provider: AIProviderID): readonly Mo
  * Get models that are currently usable — filtered to only providers that are available.
  *
  * The caller passes in which provider IDs are active (i.e. have a bond wired).
- * `disabled` models are excluded — they are never offered for selection.
+ * Models that are not {@link isSelectableModel} — `disabled` or superseded by a
+ * newer generation — are excluded; they are never offered for selection.
  *
  * @param availableProviders - Set or array of provider IDs that have active bonds.
- * @returns Non-disabled models whose provider is in the available set.
+ * @returns Selectable models whose provider is in the available set.
  */
 export declare function getAvailableModels(availableProviders: ReadonlySet<AIProviderID> | readonly AIProviderID[]): readonly ModelDefinition[];
 /**
- * The price multiplier in effect for a model at a given instant.
+ * A model's BASE token rates in effect at a given instant — the staged
+ * {@link ModelDefinition.scheduledPricing} rates once their `effectiveFrom` has
+ * passed, else the base fields.
+ *
+ * These are the native provider's rates. A `regionPricing` override is a
+ * different host's rate card and is resolved separately by
+ * {@link modelRegionRates}.
+ *
+ * @param modelDef - The model definition.
+ * @param at - The instant to price at (defaults to now).
+ * @returns The base rates in effect at that instant.
+ */
+export declare function effectiveBaseRates(modelDef: ModelDefinition, at?: Date): ModelTokenRates;
+/**
+ * A model's peak-hour pricing in effect at a given instant: the staged
+ * {@link ModelDefinition.scheduledPricing} `peakPricing` once its
+ * `effectiveFrom` has passed (when that entry declares one — an omitted one
+ * leaves the existing windows in force), else the model's own `peakPricing`.
+ *
+ * @param modelDef - The model definition.
+ * @param at - The instant to evaluate (defaults to now).
+ * @returns The peak-pricing config in effect, or `undefined` when none is.
+ */
+export declare function effectivePeakPricing(modelDef: ModelDefinition, at?: Date): ModelDefinition['peakPricing'];
+/**
+ * A model projected onto the pricing in effect at a given instant: the staged
+ * {@link ModelDefinition.scheduledPricing} rates folded into the base fields
+ * (and its peak windows into `peakPricing`) once effective, with the staged
+ * entry stripped.
+ *
+ * This is what the `GET /ai/models` handler serves, so a client renders the
+ * rates that are actually billing right now without needing to resolve a
+ * schedule against its own clock — the server's clock is the only one that
+ * decides when a price change lands.
+ *
+ * @param modelDef - The model definition.
+ * @param at - The instant to project at (defaults to now).
+ * @returns The model with effective pricing and no `scheduledPricing`.
+ */
+export declare function withEffectivePricing(modelDef: ModelDefinition, at?: Date): ModelDefinition;
+/**
+ * The price multiplier in effect for a model at a given instant, in a region.
  *
  * Consults the model's {@link ModelDefinition.peakPricing} windows (UTC,
  * half-open, may wrap midnight). Metering MUST call this with each request's
  * own timestamp so peak-hour usage bills at the provider's real rate — pricing
  * everything at the flat rate silently under-meters peak traffic.
  *
+ * Peak windows belong to the NATIVE provider, so they apply only where the base
+ * rates do. A region with a {@link ModelDefinition.regionPricing} override is a
+ * different host billing its own complete rate card, including whether it has
+ * time-of-day pricing at all — and re-hosts generally do not. Applying the
+ * native provider's surcharge on top of a re-host's flat rates would over-bill
+ * every turn in its windows (DeepSeek's 2× Beijing-hours pricing charged
+ * against DeepInfra, which has no peak pricing).
+ *
  * @param modelDef - The model definition (or undefined).
  * @param at - The instant the request was made.
- * @returns The multiplier (`1` outside peak windows or when none are declared).
+ * @param region - The user's per-model region choice, if any (omitted → the
+ *   model's default region).
+ * @returns The multiplier (`1` outside peak windows, when none are declared, or
+ *   in a region that prices off its own override).
  */
-export declare function priceMultiplierAt(modelDef: ModelDefinition | undefined, at: Date): number;
+export declare function priceMultiplierAt(modelDef: ModelDefinition | undefined, at: Date, region?: string): number;
 /**
  * Resolve a model's effective processing region: the requested region when the
  * model's {@link ModelDefinition.regions} list offers it, else the model's
@@ -80,14 +157,22 @@ export interface ModelTokenRates {
 /**
  * The token rates for a model in a given processing region: the model's
  * {@link ModelDefinition.regionPricing} override for the region when one
- * exists, else the base rates (the native provider's list prices). Omitted
- * cache fields in an override fall back to the override's input price (hosts
- * with no cache discount / no write premium). The region is resolved via
- * {@link effectiveModelRegion}, so callers may pass the raw user choice.
+ * exists, else the base rates in effect at `at` (the native provider's list
+ * prices, including any staged {@link ModelDefinition.scheduledPricing} change
+ * that has landed). Omitted cache fields in an override fall back to the
+ * override's input price (hosts with no cache discount / no write premium). The
+ * region is resolved via {@link effectiveModelRegion}, so callers may pass the
+ * raw user choice.
+ *
+ * `at` defaults to NOW rather than being required, so an existing caller cannot
+ * keep billing a superseded rate by omitting it — metering should still pass
+ * each request's own timestamp, the same way it must for
+ * {@link priceMultiplierAt}.
  *
  * @param modelDef - The model definition.
  * @param requested - The user's per-model region choice, if any.
+ * @param at - The instant to price at (defaults to now).
  * @returns The region-effective rates.
  */
-export declare function modelRegionRates(modelDef: ModelDefinition, requested?: string): ModelTokenRates;
+export declare function modelRegionRates(modelDef: ModelDefinition, requested?: string, at?: Date): ModelTokenRates;
 //# sourceMappingURL=lookup.d.ts.map

package/dist/lookup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lookup.d.ts","sourceRoot":"","sources":["../src/lookup.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAE/D;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,EAAE,WAAW,CAAC,MAAM,CAEzC,CAAA;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAEhE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,YAAY,GAAG,SAAS,eAAe,EAAE,CAEtF;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,kBAAkB,EAAE,WAAW,CAAC,YAAY,CAAC,GAAG,SAAS,YAAY,EAAE,GACtE,SAAS,eAAe,EAAE,CAI5B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,eAAe,GAAG,SAAS,EAAE,EAAE,EAAE,IAAI,GAAG,MAAM,CAYzF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,eAAe,GAAG,SAAS,EACrC,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,CAGR;AAED,2DAA2D;AAC3D,MAAM,WAAW,eAAe;IAC9B,sDAAsD;IACtD,iBAAiB,EAAE,MAAM,CAAA;IACzB,8CAA8C;IAC9C,kBAAkB,EAAE,MAAM,CAAA;IAC1B,yDAAyD;IACzD,qBAAqB,EAAE,MAAM,CAAA;IAC7B,0DAA0D;IAC1D,sBAAsB,EAAE,MAAM,CAAA;CAC/B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,eAAe,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,eAAe,CAiB/F"}
+{"version":3,"file":"lookup.d.ts","sourceRoot":"","sources":["../src/lookup.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAE/D;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,IAAI,CAAC,eAAe,EAAE,UAAU,GAAG,cAAc,CAAC,GACxD,OAAO,CAET;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CASvE;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,EAAE,WAAW,CAAC,MAAM,CAEzC,CAAA;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAEhE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,YAAY,GAAG,SAAS,eAAe,EAAE,CAEtF;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,kBAAkB,EAAE,WAAW,CAAC,YAAY,CAAC,GAAG,SAAS,YAAY,EAAE,GACtE,SAAS,eAAe,EAAE,CAI5B;AAoBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,eAAe,EACzB,EAAE,GAAE,IAAiB,GACpB,eAAe,CAgBjB;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,eAAe,EACzB,EAAE,GAAE,IAAiB,GACpB,eAAe,CAAC,aAAa,CAAC,CAMhC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,eAAe,EACzB,EAAE,GAAE,IAAiB,GACpB,eAAe,CASjB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,eAAe,GAAG,SAAS,EACrC,EAAE,EAAE,IAAI,EACR,MAAM,CAAC,EAAE,MAAM,GACd,MAAM,CAcR;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,eAAe,GAAG,SAAS,EACrC,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,CAGR;AAED,2DAA2D;AAC3D,MAAM,WAAW,eAAe;IAC9B,sDAAsD;IACtD,iBAAiB,EAAE,MAAM,CAAA;IACzB,8CAA8C;IAC9C,kBAAkB,EAAE,MAAM,CAAA;IAC1B,yDAAyD;IACzD,qBAAqB,EAAE,MAAM,CAAA;IAC7B,0DAA0D;IAC1D,sBAAsB,EAAE,MAAM,CAAA;CAC/B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,eAAe,EACzB,SAAS,CAAC,EAAE,MAAM,EAClB,EAAE,GAAE,IAAiB,GACpB,eAAe,CAYjB"}