@molecule/api-resource-ai-models 1.0.2 → 1.1.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-12T22:38:26.212Z
 -->
 
 # @molecule/api-resource-ai-models
@@ -310,6 +310,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
 }
 ```
 
@@ -424,7 +453,8 @@ function effectiveModelRegion(modelDef: ModelDefinition | undefined, requested?:
 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 +464,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 +495,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'`
@@ -518,6 +563,22 @@ function priceMultiplierAt(modelDef: ModelDefinition | undefined, at: Date): num
 
 **Returns:** The multiplier (`1` outside peak windows or when none are declared).
 
+#### `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).
+
 ### Constants
 
 #### `MODEL_IDS`
@@ -525,8 +586,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 +616,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):
@@ -585,12 +659,13 @@ Sources (verified 2026-07-28; OpenAI re-verified 2026-07-31 after the
   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
+- 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,11 @@
  * `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`. No further projection is applied — every
+ * `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;;;;;;;;;;;;;;;;;;;GAmBG;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,CActF"}

package/dist/handlers/list.js

@@ -2,10 +2,11 @@
  * `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`. No further projection is applied — every
+ * `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 +20,7 @@
  */
 import { getAll } from '@molecule/api-bond';
 import { t } from '@molecule/api-i18n';
+import { isSelectableModel } from '../lookup.js';
 import { MODELS } from '../models.js';
 /**
  * Returns models whose `provider` has a bond registered under the `'ai'`
@@ -42,7 +44,7 @@ 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 models = MODELS.filter((m) => bondedProviders.has(m.provider) && isSelectableModel(m));
     const response = { models: [...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,10 +59,11 @@ 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[];
 /**

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;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"}

package/dist/lookup.js

@@ -4,21 +4,57 @@
  * @module
  */
 import { MODELS } from './models.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 function isSelectableModel(model) {
+    return !model.disabled && !model.supersededBy;
+}
+/**
+ * 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 function resolveSelectableModelId(id) {
+    let model = getModel(id);
+    // Bounded by the catalog size: a supersession cycle would otherwise spin here,
+    // and the invariant that forbids one is a test, not a runtime guarantee.
+    for (let hops = 0; model && !isSelectableModel(model) && hops <= MODELS.length; hops++) {
+        if (!model.supersededBy)
+            return undefined; // disabled — no successor declared
+        model = getModel(model.supersededBy);
+    }
+    return model && isSelectableModel(model) ? model.id : 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 const MODEL_IDS = new Set(MODELS.filter((m) => !m.disabled).map((m) => m.id));
+export const MODEL_IDS = new Set(MODELS.filter(isSelectableModel).map((m) => m.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*.
  *
  * @param id - The API model ID.
  * @returns The model definition, or `undefined` if not found.
@@ -39,14 +75,15 @@ export function getModelsByProvider(provider) {
  * 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 function getAvailableModels(availableProviders) {
     const providerSet = availableProviders instanceof Set ? availableProviders : new Set(availableProviders);
-    return MODELS.filter((m) => providerSet.has(m.provider) && !m.disabled);
+    return MODELS.filter((m) => providerSet.has(m.provider) && isSelectableModel(m));
 }
 /**
  * The price multiplier in effect for a model at a given instant.

package/dist/models.d.ts

@@ -28,6 +28,18 @@ import type { ModelDefinition } from './types.js';
  *   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):
@@ -58,12 +70,13 @@ import type { ModelDefinition } from './types.js';
  *   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
+ * - 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/models.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6EG;AACH,eAAO,MAAM,MAAM,EAAE,SAAS,eAAe,EAmtCnC,CAAA"}
+{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0FG;AACH,eAAO,MAAM,MAAM,EAAE,SAAS,eAAe,EAqxCnC,CAAA"}

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):
@@ -57,12 +69,13 @@
  *   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
+ * - 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 +204,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 +270,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 +303,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 +334,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 +491,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 +522,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 +553,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
@@ -608,9 +632,10 @@ 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 by gemini-3.6-flash (2026-07-21) — same flash tier, same input
+        // price, cheaper output. Still served upstream, so it stays priceable.
         deprecatedAt: '2026-07-21',
+        supersededBy: 'gemini-3.6-flash',
     },
     {
         id: 'gemini-3.1-pro-preview',
@@ -640,6 +665,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 +732,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 +765,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',
     },
     {
@@ -891,9 +927,13 @@ export const MODELS = [
         // 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, 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 NOT active (see deepseek-v4-pro) — windows removed.
         // Not published by DeepSeek — best-effort estimate.
@@ -910,6 +950,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 +982,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 +1021,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 +1067,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 +1096,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
@@ -1101,9 +1169,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 +1194,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).
@@ -1207,6 +1276,11 @@ export const MODELS = [
         regions: ['us', 'cn'],
         // 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 +1310,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 +1386,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',
     },
 ];

package/dist/types.d.ts

@@ -282,6 +282,35 @@ export 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;
 }
 /**
  * The model ids the SERVER falls back to per mode/job when the user hasn't

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-resource-ai-models",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "AI model catalog — server-side source of truth plus an authentication-gated discovery endpoint",
   "type": "module",
   "main": "dist/index.js",