@molecule/api-resource-ai-models 1.14.0 → 1.15.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-10-08T07:16:27.706Z
+Generated: 2026-10-08T16:53:19.950Z
 -->
 
 # @molecule/api-resource-ai-models
@@ -343,7 +343,16 @@ interface ModelDefinition {
    * unchanged. To schedule the END of peak pricing, declare an explicit
    * `{ windows: [], multiplier: 1 }`.
    *
-   * Resolution is `effectiveBaseRates()` / `effectivePeakPricing()`, and every
+   * `longContextPricing` here, when declared, replaces the model's long-context
+   * band from the same instant; when omitted, the existing band carries through
+   * unchanged. The band that bills AFTER the instant (declared here, or the
+   * carried-through one) must stay strictly dearer than the scheduled base
+   * rates — the catalog invariant test enforces that at staging time, so a
+   * banded model's price change can never land with a stale band silently
+   * under-metering its most expensive prompts.
+   *
+   * Resolution is `effectiveBaseRates()` / `effectivePeakPricing()` /
+   * `effectiveLongContextPricing()`, 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
@@ -368,6 +377,12 @@ interface ModelDefinition {
       excludedDatesUtc?: string[]
       rule?: { url: string; text: string }
     }
+    /**
+     * Long-context band from `effectiveFrom` (omitted → the model's existing
+     * band carries through unchanged). Indexed off the model-level field so
+     * the two shapes can never drift apart.
+     */
+    longContextPricing?: ModelDefinition['longContextPricing']
     /** Where the change was announced, for the re-verify pass after it lands. */
     source?: string
   }
@@ -397,8 +412,9 @@ interface ModelDefinition {
    * whose prompt (fresh input + cache read + cache write tokens) EXCEEDS `aboveInputTokens` bills ALL of its tokens at
    * these rates, not just the excess. Resolved by `modelRegionRates(model, region, at, promptTokens)`; callers must pass
    * ONE provider call's prompt size, never a multi-call sum. All four rates are required for the same never-under-meter
-   * reasons as the base rates. A model with a staged `scheduledPricing` change or a region override restates this band
-   * itself when the long-context rates move; today the band applies on top of the base rates only.
+   * reasons as the base rates. A staged `scheduledPricing` change can carry its own replacement band from the same
+   * instant (omitted → this band carries through) — resolved by `effectiveLongContextPricing()`. A `regionPricing`
+   * override is a different host's complete rate card, so the band never applies on top of an override.
    */
   longContextPricing?: {
     /** A prompt larger than this many tokens bills at the long-context rates. */
@@ -581,6 +597,40 @@ function effectiveBaseRates(modelDef: ModelDefinition, at?: Date): ModelTokenRat
 
 **Returns:** The base rates in effect at that instant.
 
+#### `effectiveLongContextPricing(modelDef, at)`
+
+A model's long-context band in effect at a given instant: the staged
+{@link ModelDefinition.scheduledPricing} `longContextPricing` once its
+`effectiveFrom` has passed (when that entry declares one — an omitted one
+leaves the model's existing band in force), else the model's own
+{@link ModelDefinition.longContextPricing}.
+
+This is what lets a banded model's price change move BOTH cards at once:
+resolving the static band against landed scheduled base rates would leave
+
+> threshold prompts on a stale card (possibly cheaper than the new base —
+> silently under-metering the most expensive traffic).
+
+```typescript
+function effectiveLongContextPricing(
+  modelDef: ModelDefinition,
+  at?: Date,
+):
+  | {
+      aboveInputTokens: number
+      inputPricePerMTok: number
+      outputPricePerMTok: number
+      cacheReadPricePerMTok: number
+      cacheWritePricePerMTok: number
+    }
+  | undefined
+```
+
+- `modelDef` — The model definition.
+- `at` — The instant to evaluate (defaults to now).
+
+**Returns:** The long-context band in effect, or `undefined` when none is.
+
 #### `effectiveModelRegion(modelDef, requested)`
 
 Resolve a model's effective processing region: the requested region when the
@@ -721,7 +771,10 @@ each request's own timestamp, the same way it must for
 
 A model priced by prompt length ({@link ModelDefinition.longContextPricing}) bills a request whose
 `promptTokens` EXCEED the threshold at the long-context rates (all of its tokens, not the excess). Pass ONE
-provider call's prompt size (fresh input + cache read + cache write); omit it and the base rates apply.
+provider call's prompt size (fresh input + cache read + cache write); omit it and the base rates apply. The
+band itself is resolved at `at` via {@link effectiveLongContextPricing} — a landed
+{@link ModelDefinition.scheduledPricing} change that declares its own band replaces the static one from
+the same instant (an omitted one carries the static band through).
 
 ```typescript
 function modelRegionRates(
@@ -936,8 +989,9 @@ Sources (verified 2026-07-28; OpenAI re-verified 2026-07-31 after the
         moves claude-haiku-4-5 to "Legacy models (still available)" → superseded.
         Model page + pricing page: $0.10/$0.50 per MTok for prompts up to 100K
         tokens — the first Anthropic model priced BY PROMPT LENGTH (over 100K:
-        $0.50/$2.50, cache read $0.05, 5m write $0.625; not modeled, same as the
-        Gemini/Grok >200K and GPT-6 >272K bands) — 5m cache write $0.125, cache
+        $0.50/$2.50, cache read $0.05, 5m write $0.625 — modeled by
+        `longContextPricing`; the Gemini/Grok >200K and GPT-6 >272K bands are
+        NOT) — 5m cache write $0.125, cache
   hits $0.01 (standard 0.1×), web search $10/1k. 1M ctx / 128K out, text +
         image input, reliable knowledge cutoff Jun 2026. Effort page: all five
         levels, default MEDIUM. Model page "Good to know": non-default

package/dist/lookup.d.ts

@@ -91,6 +91,23 @@ export declare function effectiveBaseRates(modelDef: ModelDefinition, at?: Date)
  * @returns The peak-pricing config in effect, or `undefined` when none is.
  */
 export declare function effectivePeakPricing(modelDef: ModelDefinition, at?: Date): ModelDefinition['peakPricing'];
+/**
+ * A model's long-context band in effect at a given instant: the staged
+ * {@link ModelDefinition.scheduledPricing} `longContextPricing` once its
+ * `effectiveFrom` has passed (when that entry declares one — an omitted one
+ * leaves the model's existing band in force), else the model's own
+ * {@link ModelDefinition.longContextPricing}.
+ *
+ * This is what lets a banded model's price change move BOTH cards at once:
+ * resolving the static band against landed scheduled base rates would leave
+ * >threshold prompts on a stale card (possibly cheaper than the new base —
+ * silently under-metering the most expensive traffic).
+ *
+ * @param modelDef - The model definition.
+ * @param at - The instant to evaluate (defaults to now).
+ * @returns The long-context band in effect, or `undefined` when none is.
+ */
+export declare function effectiveLongContextPricing(modelDef: ModelDefinition, at?: Date): ModelDefinition['longContextPricing'];
 /**
  * A model projected onto the pricing in effect at a given instant: the staged
  * {@link ModelDefinition.scheduledPricing} rates folded into the base fields
@@ -172,7 +189,10 @@ export interface ModelTokenRates {
  *
  * A model priced by prompt length ({@link ModelDefinition.longContextPricing}) bills a request whose
  * `promptTokens` EXCEED the threshold at the long-context rates (all of its tokens, not the excess). Pass ONE
- * provider call's prompt size (fresh input + cache read + cache write); omit it and the base rates apply.
+ * provider call's prompt size (fresh input + cache read + cache write); omit it and the base rates apply. The
+ * band itself is resolved at `at` via {@link effectiveLongContextPricing} — a landed
+ * {@link ModelDefinition.scheduledPricing} change that declares its own band replaces the static one from
+ * the same instant (an omitted one carries the static band through).
  *
  * @param modelDef - The model definition.
  * @param requested - The user's per-model region choice, if any.

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;;;;;;;;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;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,eAAe,GAAG,SAAS,EACrC,EAAE,EAAE,IAAI,EACR,MAAM,CAAC,EAAE,MAAM,GACd,MAAM,CA2BR;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;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,eAAe,EACzB,SAAS,CAAC,EAAE,MAAM,EAClB,EAAE,GAAE,IAAiB,EACrB,YAAY,CAAC,EAAE,MAAM,GACpB,eAAe,CAqBjB"}
+{"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;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,eAAe,EACzB,EAAE,GAAE,IAAiB,GACpB,eAAe,CAAC,oBAAoB,CAAC,CAMvC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,eAAe,EACzB,EAAE,GAAE,IAAiB,GACpB,eAAe,CAWjB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,eAAe,GAAG,SAAS,EACrC,EAAE,EAAE,IAAI,EACR,MAAM,CAAC,EAAE,MAAM,GACd,MAAM,CA2BR;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;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,eAAe,EACzB,SAAS,CAAC,EAAE,MAAM,EAClB,EAAE,GAAE,IAAiB,EACrB,YAAY,CAAC,EAAE,MAAM,GACpB,eAAe,CAqBjB"}

package/dist/lookup.js

@@ -151,6 +151,29 @@ export function effectivePeakPricing(modelDef, at = new Date()) {
     }
     return modelDef.peakPricing;
 }
+/**
+ * A model's long-context band in effect at a given instant: the staged
+ * {@link ModelDefinition.scheduledPricing} `longContextPricing` once its
+ * `effectiveFrom` has passed (when that entry declares one — an omitted one
+ * leaves the model's existing band in force), else the model's own
+ * {@link ModelDefinition.longContextPricing}.
+ *
+ * This is what lets a banded model's price change move BOTH cards at once:
+ * resolving the static band against landed scheduled base rates would leave
+ * >threshold prompts on a stale card (possibly cheaper than the new base —
+ * silently under-metering the most expensive traffic).
+ *
+ * @param modelDef - The model definition.
+ * @param at - The instant to evaluate (defaults to now).
+ * @returns The long-context band in effect, or `undefined` when none is.
+ */
+export function effectiveLongContextPricing(modelDef, at = new Date()) {
+    const scheduled = modelDef.scheduledPricing;
+    if (scheduled?.longContextPricing && scheduledPricingApplies(modelDef, at)) {
+        return scheduled.longContextPricing;
+    }
+    return modelDef.longContextPricing;
+}
 /**
  * A model projected onto the pricing in effect at a given instant: the staged
  * {@link ModelDefinition.scheduledPricing} rates folded into the base fields
@@ -171,10 +194,12 @@ export function withEffectivePricing(modelDef, at = new Date()) {
         return modelDef;
     const { scheduledPricing: _scheduledPricing, ...rest } = modelDef;
     const peakPricing = effectivePeakPricing(modelDef, at);
+    const longContextPricing = effectiveLongContextPricing(modelDef, at);
     return {
         ...rest,
         ...effectiveBaseRates(modelDef, at),
         ...(peakPricing ? { peakPricing } : {}),
+        ...(longContextPricing ? { longContextPricing } : {}),
     };
 }
 /**
@@ -267,7 +292,10 @@ export function effectiveModelRegion(modelDef, requested) {
  *
  * A model priced by prompt length ({@link ModelDefinition.longContextPricing}) bills a request whose
  * `promptTokens` EXCEED the threshold at the long-context rates (all of its tokens, not the excess). Pass ONE
- * provider call's prompt size (fresh input + cache read + cache write); omit it and the base rates apply.
+ * provider call's prompt size (fresh input + cache read + cache write); omit it and the base rates apply. The
+ * band itself is resolved at `at` via {@link effectiveLongContextPricing} — a landed
+ * {@link ModelDefinition.scheduledPricing} change that declares its own band replaces the static one from
+ * the same instant (an omitted one carries the static band through).
  *
  * @param modelDef - The model definition.
  * @param requested - The user's per-model region choice, if any.
@@ -279,7 +307,7 @@ export function modelRegionRates(modelDef, requested, at = new Date(), promptTok
     const region = effectiveModelRegion(modelDef, requested);
     const override = modelDef.regionPricing?.[region];
     if (!override) {
-        const longBand = modelDef.longContextPricing;
+        const longBand = effectiveLongContextPricing(modelDef, at);
         if (longBand && typeof promptTokens === 'number' && promptTokens > longBand.aboveInputTokens) {
             return {
                 inputPricePerMTok: longBand.inputPricePerMTok,

package/dist/models.d.ts

@@ -122,8 +122,9 @@ import type { ModelDefinition } from './types.js';
  *   moves claude-haiku-4-5 to "Legacy models (still available)" → superseded.
  *   Model page + pricing page: $0.10/$0.50 per MTok for prompts up to 100K
  *   tokens — the first Anthropic model priced BY PROMPT LENGTH (over 100K:
- *   $0.50/$2.50, cache read $0.05, 5m write $0.625; not modeled, same as the
- *   Gemini/Grok >200K and GPT-6 >272K bands) — 5m cache write $0.125, cache
+ *   $0.50/$2.50, cache read $0.05, 5m write $0.625 — modeled by
+ *   `longContextPricing`; the Gemini/Grok >200K and GPT-6 >272K bands are
+ *   NOT) — 5m cache write $0.125, cache
  *   hits $0.01 (standard 0.1×), web search $10/1k. 1M ctx / 128K out, text +
  *   image input, reliable knowledge cutoff Jun 2026. Effort page: all five
  *   levels, default MEDIUM. Model page "Good to know": non-default

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;AAwDjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2TG;AACH,eAAO,MAAM,MAAM,EAAE,SAAS,eAAe,EA80EnC,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;AAwDjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4TG;AACH,eAAO,MAAM,MAAM,EAAE,SAAS,eAAe,EA80EnC,CAAA"}

package/dist/models.js

@@ -171,8 +171,9 @@ const CHINA_PUBLIC_HOLIDAYS = [
  *   moves claude-haiku-4-5 to "Legacy models (still available)" → superseded.
  *   Model page + pricing page: $0.10/$0.50 per MTok for prompts up to 100K
  *   tokens — the first Anthropic model priced BY PROMPT LENGTH (over 100K:
- *   $0.50/$2.50, cache read $0.05, 5m write $0.625; not modeled, same as the
- *   Gemini/Grok >200K and GPT-6 >272K bands) — 5m cache write $0.125, cache
+ *   $0.50/$2.50, cache read $0.05, 5m write $0.625 — modeled by
+ *   `longContextPricing`; the Gemini/Grok >200K and GPT-6 >272K bands are
+ *   NOT) — 5m cache write $0.125, cache
  *   hits $0.01 (standard 0.1×), web search $10/1k. 1M ctx / 128K out, text +
  *   image input, reliable knowledge cutoff Jun 2026. Effort page: all five
  *   levels, default MEDIUM. Model page "Good to know": non-default

package/dist/types.d.ts

@@ -319,7 +319,16 @@ export interface ModelDefinition {
      * unchanged. To schedule the END of peak pricing, declare an explicit
      * `{ windows: [], multiplier: 1 }`.
      *
-     * Resolution is `effectiveBaseRates()` / `effectivePeakPricing()`, and every
+     * `longContextPricing` here, when declared, replaces the model's long-context
+     * band from the same instant; when omitted, the existing band carries through
+     * unchanged. The band that bills AFTER the instant (declared here, or the
+     * carried-through one) must stay strictly dearer than the scheduled base
+     * rates — the catalog invariant test enforces that at staging time, so a
+     * banded model's price change can never land with a stale band silently
+     * under-metering its most expensive prompts.
+     *
+     * Resolution is `effectiveBaseRates()` / `effectivePeakPricing()` /
+     * `effectiveLongContextPricing()`, 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
@@ -351,6 +360,12 @@ export interface ModelDefinition {
                 text: string;
             };
         };
+        /**
+         * Long-context band from `effectiveFrom` (omitted → the model's existing
+         * band carries through unchanged). Indexed off the model-level field so
+         * the two shapes can never drift apart.
+         */
+        longContextPricing?: ModelDefinition['longContextPricing'];
         /** Where the change was announced, for the re-verify pass after it lands. */
         source?: string;
     };
@@ -380,8 +395,9 @@ export interface ModelDefinition {
      * whose prompt (fresh input + cache read + cache write tokens) EXCEEDS `aboveInputTokens` bills ALL of its tokens at
      * these rates, not just the excess. Resolved by `modelRegionRates(model, region, at, promptTokens)`; callers must pass
      * ONE provider call's prompt size, never a multi-call sum. All four rates are required for the same never-under-meter
-     * reasons as the base rates. A model with a staged `scheduledPricing` change or a region override restates this band
-     * itself when the long-context rates move; today the band applies on top of the base rates only.
+     * reasons as the base rates. A staged `scheduledPricing` change can carry its own replacement band from the same
+     * instant (omitted → this band carries through) — resolved by `effectiveLongContextPricing()`. A `regionPricing`
+     * override is a different host's complete rate card, so the band never applies on top of an override.
      */
     longContextPricing?: {
         /** A prompt larger than this many tokens bills at the long-context rates. */

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":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GACpB,WAAW,GACX,QAAQ,GACR,QAAQ,GACR,KAAK,GACL,UAAU,GACV,MAAM,GACN,UAAU,GACV,SAAS,GACT,SAAS,GACT,OAAO;AACT;;;;;GAKG;GACD,QAAQ,CAAA;AAEZ;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAA;AAEhC;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,8DAA8D;IAC9D,EAAE,EAAE,MAAM,CAAA;IACV,2CAA2C;IAC3C,QAAQ,EAAE,YAAY,CAAA;IACtB,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAA;IACb,wCAAwC;IACxC,WAAW,EAAE,MAAM,CAAA;IACnB,8CAA8C;IAC9C,aAAa,EAAE,MAAM,CAAA;IACrB,0CAA0C;IAC1C,eAAe,EAAE,MAAM,CAAA;IACvB,uEAAuE;IACvE,gBAAgB,EAAE,OAAO,CAAA;IACzB,yFAAyF;IACzF,oBAAoB,EAAE,MAAM,CAAA;IAC5B;;;OAGG;IACH,oBAAoB,EAAE,OAAO,CAAA;IAC7B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,qBAAqB,CAAC,EAAE,WAAW,EAAE,CAAA;IACrC;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,WAAW,CAAA;IAChC;;;;;;;;;;;OAWG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC3C,mEAAmE;IACnE,cAAc,EAAE,OAAO,CAAA;IACvB,iDAAiD;IACjD,qBAAqB,EAAE,OAAO,CAAA;IAC9B,8DAA8D;IAC9D,aAAa,EAAE,OAAO,CAAA;IACtB;;;;;;;;;;;;;OAaG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAA;IAClC;;;;;;;;;;;OAWG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAA;IACjC;;;;;;;;;;OAUG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B;;;;;;;;OAQG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B;;;;;;;OAOG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B;;;OAGG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,wFAAwF;IACxF,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,CAAA;IAC1B;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,MAAM,CACpB,MAAM,EACN;QACE,6DAA6D;QAC7D,iBAAiB,EAAE,MAAM,CAAA;QACzB,qDAAqD;QACrD,kBAAkB,EAAE,MAAM,CAAA;QAC1B,gEAAgE;QAChE,qBAAqB,CAAC,EAAE,MAAM,CAAA;QAC9B,iEAAiE;QACjE,sBAAsB,CAAC,EAAE,MAAM,CAAA;KAChC,CACF,CAAA;IACD,sEAAsE;IACtE,iBAAiB,EAAE,MAAM,CAAA;IACzB,8CAA8C;IAC9C,kBAAkB,EAAE,MAAM,CAAA;IAC1B;;;;;;;;;;;OAWG;IACH,qBAAqB,EAAE,MAAM,CAAA;IAC7B;;;;;;;;;;OAUG;IACH,sBAAsB,EAAE,MAAM,CAAA;IAC9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACH,WAAW,CAAC,EAAE;QACZ,OAAO,EAAE;YAAE,cAAc,EAAE,MAAM,CAAC;YAAC,YAAY,EAAE,MAAM,CAAC;YAAC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;SAAE,EAAE,CAAA;QACrF,UAAU,EAAE,MAAM,CAAA;QAClB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAA;QAC3B,IAAI,CAAC,EAAE;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAA;KACrC,CAAA;IACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwCG;IACH,gBAAgB,CAAC,EAAE;QACjB,sDAAsD;QACtD,aAAa,EAAE,MAAM,CAAA;QACrB,8EAA8E;QAC9E,iBAAiB,EAAE,MAAM,CAAA;QACzB,oEAAoE;QACpE,kBAAkB,EAAE,MAAM,CAAA;QAC1B,iFAAiF;QACjF,qBAAqB,EAAE,MAAM,CAAA;QAC7B,kFAAkF;QAClF,sBAAsB,EAAE,MAAM,CAAA;QAC9B,yFAAyF;QACzF,WAAW,CAAC,EAAE;YACZ,OAAO,EAAE;gBAAE,cAAc,EAAE,MAAM,CAAC;gBAAC,YAAY,EAAE,MAAM,CAAC;gBAAC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;aAAE,EAAE,CAAA;YACrF,UAAU,EAAE,MAAM,CAAA;YAClB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAA;YAC3B,IAAI,CAAC,EAAE;gBAAE,GAAG,EAAE,MAAM,CAAC;gBAAC,IAAI,EAAE,MAAM,CAAA;aAAE,CAAA;SACrC,CAAA;QACD;;;;WAIG;QACH,kBAAkB,CAAC,EAAE,eAAe,CAAC,oBAAoB,CAAC,CAAA;QAC1D,6EAA6E;QAC7E,MAAM,CAAC,EAAE,MAAM,CAAA;KAChB,CAAA;IACD;;;;;;;;;;OAUG;IACH,WAAW,CAAC,EAAE;QACZ,gEAAgE;QAChE,iBAAiB,EAAE,MAAM,CAAA;QACzB,wDAAwD;QACxD,kBAAkB,EAAE,MAAM,CAAA;QAC1B,mEAAmE;QACnE,qBAAqB,EAAE,MAAM,CAAA;QAC7B,oEAAoE;QACpE,sBAAsB,EAAE,MAAM,CAAA;KAC/B,CAAA;IACD;;;;;;;;OAQG;IACH,kBAAkB,CAAC,EAAE;QACnB,6EAA6E;QAC7E,gBAAgB,EAAE,MAAM,CAAA;QACxB,mEAAmE;QACnE,iBAAiB,EAAE,MAAM,CAAA;QACzB,2DAA2D;QAC3D,kBAAkB,EAAE,MAAM,CAAA;QAC1B,sEAAsE;QACtE,qBAAqB,EAAE,MAAM,CAAA;QAC7B,uEAAuE;QACvE,sBAAsB,EAAE,MAAM,CAAA;KAC/B,CAAA;IACD,mDAAmD;IACnD,eAAe,EAAE,MAAM,CAAA;IACvB;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAA;IACZ,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAA;IACf,8EAA8E;IAC9E,MAAM,EAAE,MAAM,CAAA;IACd,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,eAAe,EAAE,CAAA;IACzB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,iBAAiB,CAAA;CAC7B"}

package/package.json

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