@trazum/core 1.82.0 → 1.85.0

package/dist/pricing.d.ts

@@ -7,7 +7,33 @@ import type { ModelPricing } from './types.js';
  * Amazon Bedrock and Vertex AI pricing is set by each partner and is NOT the
  * pricing in this table.
  */
-export declare const PRICING_LAST_REVIEWED = "2026-06-24";
+/**
+ * When each provider's prices were last checked against that provider's own
+ * published table.
+ *
+ * One date for the whole catalogue was the wrong shape, and it cost a real
+ * error. Seven providers publish independently and are checked independently;
+ * a single date forces a partial review to either overstate itself by moving
+ * the date for everyone, or throw itself away by leaving it. What happened is
+ * the second: this constant was written on 2026-08-04 already reading
+ * 2026-06-24, and never moved again.
+ *
+ * Meanwhile Anthropic cancelled the increase that was going to take Sonnet 5
+ * from its 2/10 introductory price to 3/15 on 2026-09-01, and made 2/10
+ * standard. The catalogue still carried the promotion with its end date, so on
+ * 2026-09-01 every Sonnet 5 figure this tool printed would have risen 50% with
+ * no code change and no way for a reader to tell. A price nobody charges is
+ * the one error this product cannot make, and it was four days out on a timer.
+ *
+ * So: a date per provider, checked against that provider's own page, and the
+ * catalogue's headline date derived as the oldest of them rather than typed.
+ */
+export declare const PROVIDER_REVIEWED: Readonly<Record<string, string>>;
+/**
+ * The catalogue's age is its oldest provider's, because a reader asking how
+ * old this table is wants the answer for the worst part of it, not the best.
+ */
+export declare const PRICING_LAST_REVIEWED: string;
 /** Cost multipliers relative to the input price. */
 /**
  * The defaults, which are Anthropic's numbers.
@@ -75,6 +101,25 @@ export interface PricingCatalogue {
 export declare function indexModels(models: ModelPricing[]): Map<string, ModelPricing>;
 /** The prices compiled into this release. */
 export declare const BUNDLED_CATALOGUE: PricingCatalogue;
+/**
+ * Whether this model may be offered to a reader as something to move to.
+ *
+ * One home for a two-part rule that used to be written in four places as one
+ * part. `recommendable: false` — a private programme, a waitlist — was honoured
+ * at every one of them. `retired` is the stronger statement: the provider
+ * answered a real request for the id with an error, so a switch to it is not a
+ * worse recommendation, it is one that cannot be carried out at all.
+ *
+ * Written as a function rather than as a second `&&` at four call sites,
+ * because the fifth call site is always the one that gets written with only the
+ * first half. `pricing.test.js` fails a source file that filters on
+ * `recommendable` without coming through here, and that guard was proved by
+ * planting exactly that filter.
+ *
+ * Pricing is a separate question and stays answered: a retired model keeps its
+ * price, because a log full of its calls records money that was really spent.
+ */
+export declare function isOffered(model: ModelPricing): boolean;
 /** Looks a model up in a specific catalogue. */
 export declare function modelFrom(catalogue: PricingCatalogue, id: string): ModelPricing;
 /**
@@ -93,11 +138,46 @@ export declare function cheapestOfTierIn(catalogue: PricingCatalogue, tier: Mode
 provider?: string): ModelPricing;
 export declare function getModel(id: string): ModelPricing;
 export declare function listModels(): ModelPricing[];
-export declare function effectivePricing(model: ModelPricing, on?: Date): {
+/** Effective price on a given date, applying any live promotion. */
+/**
+ * Memoised per model, because this runs once per record when a usage log is
+ * priced: a 200k-line profile called it 200k times, and the `new Date(...)`
+ * parse of the promo's end date alone was 0.7 of the 2.4 seconds the whole
+ * profile took — measured with --cpu-prof, not guessed. The cache keys on
+ * the model object (a WeakMap, so an overlay's models are collected with
+ * the overlay) and stores the parsed end-of-promo instant plus the two
+ * possible answers; `on` still decides which answer applies on every call,
+ * so behaviour is unchanged to the millisecond.
+ */
+interface Rates {
     inputPerMTok: number;
     outputPerMTok: number;
     promoApplied: boolean;
-};
+    tier: {
+        applied: string | null;
+        decided: boolean;
+        because: string;
+    } | null;
+}
+/**
+ * What one call is billed at, and what decided it.
+ *
+ * `tier` is the field this grew for, and it carries three states rather than
+ * two. A model with no tiers gets `null`. A model whose condition could be
+ * evaluated gets the tier that applied, or the base rate with `applied: null`
+ * and `decided: true`. A model whose condition could **not** be evaluated —
+ * a size tier priced without a token count — gets `decided: false`, the
+ * **dearer** of the candidate rates, and `because` naming what would settle it.
+ *
+ * The dearer one is not a shrug. A cost figure that is a ceiling can prove
+ * "under budget" and can never surprise a bill; a floor chosen for looking
+ * better is the flattering direction this product spends its time refusing.
+ * The reader still has to be told, which is what `decided: false` is for, and
+ * `pricing.test.js` fails a tiered model whose report drops it.
+ */
+export declare function effectivePricing(model: ModelPricing, on?: Date, context?: {
+    inputTokens?: number;
+}): Rates;
 /** Cheapest model of each capability tier, for recommendations. */
 export declare function cheapestOfTier(tier: ModelPricing['tier']): ModelPricing;
 /**
@@ -116,5 +196,20 @@ export declare function cheapestOfTier(tier: ModelPricing['tier']): ModelPricing
  * a date — an overlay supplies this string, and a wrong one should read as
  * unknown rather than as a confident number computed from `NaN`.
  */
+/**
+ * The age at which this product stops treating its own price table as current.
+ *
+ * Three surfaces warn a reader that the figures above may be off — `profile`,
+ * the MCP report, the browser's bill — and each of them had typed `45` into
+ * its own comparison, with four locale sentences stating it again in prose.
+ * Seven copies of one claim, and nothing that would notice when they
+ * disagreed; the sentence a reader sees names the number, so a drift between
+ * them would have been a surface telling the reader one threshold and applying
+ * another.
+ *
+ * The value is what those surfaces already published, not a new judgement.
+ */
+export declare const STALE_PRICING_DAYS = 45;
 export declare function reviewAgeDays(lastReviewed: string, now: Date): number | null;
+export {};
 //# sourceMappingURL=pricing.d.ts.map

package/dist/pricing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pricing.d.ts","sourceRoot":"","sources":["../src/pricing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,eAAe,CAAC;AAElD,oDAAoD;AACpD;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB;IAC3B,uCAAuC;aACvC,YAAY,EAAE,IAAI;IAClB,qCAAqC;aACrC,YAAY,EAAE,CAAG;IACjB,2CAA2C;aAC3C,SAAS,EAAE,GAAG;IACd,mDAAmD;aACnD,KAAK,EAAE,GAAG;CACF,CAAC;AAeX,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG;IACnD,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB,CAYA;AAED,eAAO,MAAM,MAAM,EAAE,YAAY,EAqQhC,CAAC;AAEF,eAAO,MAAM,aAAa,kBAAkB,CAAC;AAE7C;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAChC,+DAA+D;IAC/D,YAAY,EAAE,MAAM,CAAC;IACrB,+EAA+E;IAC/E,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,0EAA0E;IAC1E,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAK7E;AAiBD,6CAA6C;AAC7C,eAAO,MAAM,iBAAiB,EAAE,gBAA+D,CAAC;AAEhG,gDAAgD;AAChD,wBAAgB,SAAS,CAAC,SAAS,EAAE,gBAAgB,EAAE,EAAE,EAAE,MAAM,GAAG,YAAY,CAQ/E;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,gBAAgB,EAC3B,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,EAC1B,EAAE,GAAE,IAAiB;AACrB;;;;;GAKG;AACH,QAAQ,CAAC,EAAE,MAAM,GAChB,YAAY,CAcd;AAED,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,CAEjD;AAED,wBAAgB,UAAU,IAAI,YAAY,EAAE,CAE3C;AAsBD,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,YAAY,EACnB,EAAE,GAAE,IAAiB,GACpB;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,OAAO,CAAA;CAAE,CAuBxE;AAED,mEAAmE;AACnE,wBAAgB,cAAc,CAAC,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,GAAG,YAAY,CAKvE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,CAU5E"}
+{"version":3,"file":"pricing.d.ts","sourceRoot":"","sources":["../src/pricing.ts"],"names":[],"mappings":"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"}

package/dist/pricing.js

@@ -6,7 +6,54 @@
  * Amazon Bedrock and Vertex AI pricing is set by each partner and is NOT the
  * pricing in this table.
  */
-export const PRICING_LAST_REVIEWED = '2026-06-24';
+/**
+ * When each provider's prices were last checked against that provider's own
+ * published table.
+ *
+ * One date for the whole catalogue was the wrong shape, and it cost a real
+ * error. Seven providers publish independently and are checked independently;
+ * a single date forces a partial review to either overstate itself by moving
+ * the date for everyone, or throw itself away by leaving it. What happened is
+ * the second: this constant was written on 2026-08-04 already reading
+ * 2026-06-24, and never moved again.
+ *
+ * Meanwhile Anthropic cancelled the increase that was going to take Sonnet 5
+ * from its 2/10 introductory price to 3/15 on 2026-09-01, and made 2/10
+ * standard. The catalogue still carried the promotion with its end date, so on
+ * 2026-09-01 every Sonnet 5 figure this tool printed would have risen 50% with
+ * no code change and no way for a reader to tell. A price nobody charges is
+ * the one error this product cannot make, and it was four days out on a timer.
+ *
+ * So: a date per provider, checked against that provider's own page, and the
+ * catalogue's headline date derived as the oldest of them rather than typed.
+ */
+export const PROVIDER_REVIEWED = Object.freeze({
+    /* platform.claude.com/docs/en/about-claude/pricing, read 2026-08-27. */
+    anthropic: '2026-08-27',
+    openai: '2026-06-24',
+    /* ai.google.dev/gemini-api/docs/pricing, read 2026-08-28. */
+    google: '2026-08-28',
+    moonshot: '2026-06-24',
+    /* api-docs.deepseek.com/quick_start/pricing, read 2026-08-28. */
+    deepseek: '2026-08-28',
+    xai: '2026-06-24',
+    /*
+     * `mistral.ai/pricing`, read 2026-08-28 — by a human, because the page
+     * renders its table in the browser and serves a fetch only an FAQ example
+     * with no model id attached.
+     *
+     * This date stayed at 2026-06-24 for a few hours after the other two moved,
+     * which is the point of having one per provider: looking and finding nothing
+     * servable is not the same as checking, and moving the date then would have
+     * said it was.
+     */
+    mistral: '2026-08-28',
+});
+/**
+ * The catalogue's age is its oldest provider's, because a reader asking how
+ * old this table is wants the answer for the worst part of it, not the best.
+ */
+export const PRICING_LAST_REVIEWED = Object.values(PROVIDER_REVIEWED).reduce((oldest, date) => (date < oldest ? date : oldest));
 /** Cost multipliers relative to the input price. */
 /**
  * The defaults, which are Anthropic's numbers.
@@ -125,14 +172,14 @@ export const MODELS = [
         id: 'claude-sonnet-5',
         provider: 'anthropic',
         displayName: 'Claude Sonnet 5',
-        inputPerMTok: 3,
-        outputPerMTok: 15,
+        inputPerMTok: 2,
+        outputPerMTok: 10,
         contextWindow: 1_000_000,
         cacheMinTokens: 1024,
         capability: 'mid',
         tier: 'sonnet',
-        promo: { inputPerMTok: 2, outputPerMTok: 10, until: '2026-08-31' },
-        notes: 'Introductory pricing of 2/10 until 2026-08-31; 3/15 afterwards.',
+        notes: 'Launched with 2/10 as introductory pricing through 2026-08-31; the scheduled'
+            + ' increase to 3/15 on 2026-09-01 was cancelled and 2/10 is the standard price.',
     },
     {
         id: 'claude-sonnet-4-6',
@@ -222,6 +269,11 @@ export const MODELS = [
         cacheMinTokens: 2048,
         caching: 'explicit',
         multipliers: { cacheRead: 0.25, cacheWrite5m: 1, cacheWrite1h: 1, batch: 0.5 },
+        /* Refused on 2026-08-28: still in `GET /v1beta/models`, and a 404 to a request. */
+        retired: {
+            on: '2026-08-28',
+            because: 'This model models/gemini-2.5-pro is no longer available to new users. Please update your code to use models/gemini-3.1-pro-preview for the latest features and improvements. We recommend you to use the Interactions API.',
+        },
         capability: 'large',
         tier: 'opus',
         notes: 'Context caching is billed for storage per hour as well as per read.',
@@ -236,9 +288,46 @@ export const MODELS = [
         cacheMinTokens: 1024,
         caching: 'explicit',
         multipliers: { cacheRead: 0.25, cacheWrite5m: 1, cacheWrite1h: 1, batch: 0.5 },
+        /* Refused on 2026-08-28: still in `GET /v1beta/models`, and a 404 to a request. */
+        retired: {
+            on: '2026-08-28',
+            because: 'This model models/gemini-2.5-flash is no longer available to new users. Please update your code to use models/gemini-3.6-flash for the latest features and improvements. We recommend you to use the Interactions API.',
+        },
         capability: 'mid',
         tier: 'sonnet',
     },
+    {
+        /*
+         * Google's own error message names this as the replacement for the two
+         * retired 2.5 models, and ai.google.dev/gemini-api/docs/pricing carries the
+         * rates, read 2026-08-28.
+         *
+         * The introductory price has a published end date and a published successor,
+         * which is exactly what `promo` is for and is the shape the catalogue nearly
+         * shipped Sonnet 5 wrong on: on 2027-01-01 every figure here doubles with no
+         * code change, and `pricing-review.test.js` fails before that arrives.
+         */
+        id: 'gemini-3.6-flash',
+        provider: 'google',
+        displayName: 'Gemini 3.6 Flash',
+        inputPerMTok: 1.5,
+        outputPerMTok: 7.5,
+        promo: { inputPerMTok: 0.75, outputPerMTok: 3.75, until: '2026-12-31' },
+        contextWindow: 1_048_576,
+        cacheMinTokens: 1024,
+        caching: 'explicit',
+        /*
+         * $0.075 against $0.75 inside the introductory window, and $0.15 against
+         * $1.50 after it: Google scales the cache price with the headline one, so
+         * a single ratio is right on both sides of 2027-01-01 and the multiplier
+         * does not need a date of its own.
+         */
+        multipliers: { cacheRead: 0.1, cacheWrite5m: 1, cacheWrite1h: 1, batch: 0.5 },
+        capability: 'mid',
+        tier: 'sonnet',
+        notes: 'Context caching is billed for storage per hour as well as per read:'
+            + ' $0.50 per 1M tokens per hour through 2026-12-31, $1.00 after.',
+    },
     // ------------------------------------------------------------------------
     // Moonshot
     // ------------------------------------------------------------------------
@@ -269,9 +358,69 @@ export const MODELS = [
         cacheMinTokens: 1024,
         caching: 'automatic',
         multipliers: { cacheRead: 0.1, cacheWrite5m: 1, cacheWrite1h: 1, batch: null },
+        /* Refused on 2026-08-28: the id itself is rejected, and the error names the survivors. */
+        retired: {
+            on: '2026-08-28',
+            because: 'The supported API model names are deepseek-v4-pro, deepseek-v4-flash, and deepseek-v4-flash-vision-exp, but you passed deepseek-v3.',
+        },
         capability: 'mid',
         tier: 'sonnet',
     },
+    {
+        /*
+         * DeepSeek V4 Flash, from api-docs.deepseek.com/quick_start/pricing, read
+         * 2026-08-28. It replaced `deepseek-v3`, which the API now refuses.
+         *
+         * The base rate is off-peak because off-peak is the common case: peak is
+         * 01:00-04:00 and 06:00-10:00 UTC on weekdays, which is 35 hours of 168.
+         * The peak tier is exactly double, published as such.
+         */
+        id: 'deepseek-v4-flash',
+        provider: 'deepseek',
+        displayName: 'DeepSeek V4 Flash',
+        inputPerMTok: 0.22,
+        outputPerMTok: 0.66,
+        tiers: [
+            {
+                id: 'peak',
+                when: { kind: 'utc-hours', hours: [1, 2, 3, 6, 7, 8, 9], weekdaysOnly: true },
+                inputPerMTok: 0.44,
+                outputPerMTok: 1.32,
+            },
+        ],
+        contextWindow: 1_000_000,
+        cacheMinTokens: 1024,
+        caching: 'automatic',
+        /* $0.007 cache hit against $0.22 input off-peak. */
+        multipliers: { cacheRead: 0.0318, cacheWrite5m: 1, cacheWrite1h: 1, batch: null },
+        capability: 'mid',
+        tier: 'sonnet',
+        notes: 'Maximum output 384K tokens.',
+    },
+    {
+        /* Same page, same clock. Pro is three times Flash at both ends. */
+        id: 'deepseek-v4-pro',
+        provider: 'deepseek',
+        displayName: 'DeepSeek V4 Pro',
+        inputPerMTok: 0.66,
+        outputPerMTok: 1.98,
+        tiers: [
+            {
+                id: 'peak',
+                when: { kind: 'utc-hours', hours: [1, 2, 3, 6, 7, 8, 9], weekdaysOnly: true },
+                inputPerMTok: 1.32,
+                outputPerMTok: 3.96,
+            },
+        ],
+        contextWindow: 1_000_000,
+        cacheMinTokens: 1024,
+        caching: 'automatic',
+        /* $0.022 cache hit against $0.66 input off-peak. */
+        multipliers: { cacheRead: 0.0333, cacheWrite5m: 1, cacheWrite1h: 1, batch: null },
+        capability: 'large',
+        tier: 'opus',
+        notes: 'Maximum output 384K tokens.',
+    },
     // ------------------------------------------------------------------------
     // xAI
     // ------------------------------------------------------------------------
@@ -301,10 +450,88 @@ export const MODELS = [
         cacheMinTokens: 0,
         caching: 'none',
         multipliers: { batch: 0.5 },
+        /* Refused on 2026-08-28: the id itself is rejected. */
+        retired: {
+            on: '2026-08-28',
+            because: 'Invalid model: mistral-large-2',
+        },
+        capability: 'large',
+        tier: 'opus',
+        notes: 'No prompt caching: reordering still helps readability but saves nothing here.',
+    },
+    {
+        /*
+         * Mistral Large 3, the replacement for the refused `mistral-large-2`.
+         *
+         * **Read by a human from `mistral.ai/pricing` on 2026-08-28, and that is the
+         * provenance.** The page renders its table in the browser, so a fetch sees
+         * only an FAQ example with no model id attached: this repository looked,
+         * found nothing servable, left the model unpriced and said so, and the table
+         * was then read off the page and handed over. A price is a reading of the
+         * provider's page; who did the reading is a fact about the reading, not a
+         * reason to accept a worse source.
+         *
+         * The identity is measured rather than inferred. `GET /v1/models` declares
+         * `mistral-large-latest` and `mistral-large-2512` as aliases of each other,
+         * both reporting the name `mistral-large-2512` and a 262,144 context, so the
+         * dated id is what a usage log carries and the moving pointer is the alias.
+         */
+        id: 'mistral-large-2512',
+        aliases: ['mistral-large-latest'],
+        provider: 'mistral',
+        displayName: 'Mistral Large 3',
+        inputPerMTok: 0.5,
+        outputPerMTok: 1.5,
+        contextWindow: 262_144,
+        cacheMinTokens: 0,
+        caching: 'none',
+        multipliers: { batch: 0.5 },
         capability: 'large',
         tier: 'opus',
         notes: 'No prompt caching: reordering still helps readability but saves nothing here.',
     },
+    {
+        /*
+         * Same page, same day, same reading.
+         *
+         * **This provider's ladder is not monotonic in price, and that is not a
+         * typo.** Medium 3.5 costs three times Large 3 on input and five times on
+         * output, because Mistral positions Large as the open-weight flagship and
+         * Medium as the model for long-horizon agentic work. `capability` follows
+         * the vendor's own description rather than the price, which is what the
+         * field means; the consequence is that a step down from `large` to `mid`
+         * here is dearer, and `levers.ts` simply does not offer a route whose saving
+         * is not above zero. Nothing to fix, and worth saying so before somebody
+         * "corrects" the ladder into producing a saving that does not exist.
+         */
+        id: 'mistral-medium-2604',
+        aliases: ['mistral-medium-latest', 'mistral-medium-3-5'],
+        provider: 'mistral',
+        displayName: 'Mistral Medium 3.5',
+        inputPerMTok: 1.5,
+        outputPerMTok: 7.5,
+        contextWindow: 262_144,
+        cacheMinTokens: 0,
+        caching: 'none',
+        multipliers: { batch: 0.5 },
+        capability: 'mid',
+        tier: 'sonnet',
+    },
+    {
+        /* Same page, same day. `mistral-small-2603` is what the API reports. */
+        id: 'mistral-small-2603',
+        aliases: ['mistral-small-latest'],
+        provider: 'mistral',
+        displayName: 'Mistral Small 4',
+        inputPerMTok: 0.15,
+        outputPerMTok: 0.6,
+        contextWindow: 262_144,
+        cacheMinTokens: 0,
+        caching: 'none',
+        multipliers: { batch: 0.5 },
+        capability: 'small',
+        tier: 'haiku',
+    },
 ];
 export const DEFAULT_MODEL = 'claude-opus-5';
 /**
@@ -336,6 +563,27 @@ function makeCatalogue(models, lastReviewed, overriddenModels = [], addedModels
 }
 /** The prices compiled into this release. */
 export const BUNDLED_CATALOGUE = makeCatalogue(MODELS, PRICING_LAST_REVIEWED);
+/**
+ * Whether this model may be offered to a reader as something to move to.
+ *
+ * One home for a two-part rule that used to be written in four places as one
+ * part. `recommendable: false` — a private programme, a waitlist — was honoured
+ * at every one of them. `retired` is the stronger statement: the provider
+ * answered a real request for the id with an error, so a switch to it is not a
+ * worse recommendation, it is one that cannot be carried out at all.
+ *
+ * Written as a function rather than as a second `&&` at four call sites,
+ * because the fifth call site is always the one that gets written with only the
+ * first half. `pricing.test.js` fails a source file that filters on
+ * `recommendable` without coming through here, and that guard was proved by
+ * planting exactly that filter.
+ *
+ * Pricing is a separate question and stays answered: a retired model keeps its
+ * price, because a log full of its calls records money that was really spent.
+ */
+export function isOffered(model) {
+    return model.recommendable !== false && model.retired === undefined;
+}
 /** Looks a model up in a specific catalogue. */
 export function modelFrom(catalogue, id) {
     const model = catalogue.byId.get(id);
@@ -359,7 +607,7 @@ export function cheapestOfTierIn(catalogue, tier, on = new Date(),
  */
 provider) {
     const candidates = catalogue.models.filter((m) => m.tier === tier &&
-        m.recommendable !== false &&
+        isOffered(m) &&
         (provider === undefined || m.provider === provider));
     const first = candidates[0];
     if (!first)
@@ -372,47 +620,143 @@ export function getModel(id) {
 export function listModels() {
     return [...MODELS];
 }
-/** Effective price on a given date, applying any live promotion. */
+const pricingMemo = new WeakMap();
+/** The two unconditional answers for one model, parsed once. */
+function cache(model) {
+    const entry = {
+        untilMs: model.promo ? new Date(`${model.promo.until}T23:59:59.999Z`).getTime() : null,
+        promo: model.promo
+            ? Object.freeze({
+                inputPerMTok: model.promo.inputPerMTok,
+                outputPerMTok: model.promo.outputPerMTok,
+                promoApplied: true,
+                tier: null,
+            })
+            : null,
+        base: Object.freeze({
+            inputPerMTok: model.inputPerMTok,
+            outputPerMTok: model.outputPerMTok,
+            promoApplied: false,
+            tier: null,
+        }),
+    };
+    pricingMemo.set(model, entry);
+    return entry;
+}
 /**
- * Memoised per model, because this runs once per record when a usage log is
- * priced: a 200k-line profile called it 200k times, and the `new Date(...)`
- * parse of the promo's end date alone was 0.7 of the 2.4 seconds the whole
- * profile took — measured with --cpu-prof, not guessed. The cache keys on
- * the model object (a WeakMap, so an overlay's models are collected with
- * the overlay) and stores the parsed end-of-promo instant plus the two
- * possible answers; `on` still decides which answer applies on every call,
- * so behaviour is unchanged to the millisecond.
+ * Whether one condition holds, for a call at `on` of `inputTokens` tokens.
+ *
+ * Returns `null` rather than `false` when the condition cannot be decided,
+ * because "this does not apply" and "nobody said" lead to different reports and
+ * collapsing them is the oldest mistake in this repository.
  */
-const pricingMemo = new WeakMap();
-export function effectivePricing(model, on = new Date()) {
-    let memo = pricingMemo.get(model);
-    if (memo === undefined) {
-        memo = {
-            untilMs: model.promo ? new Date(`${model.promo.until}T23:59:59.999Z`).getTime() : null,
-            promo: model.promo
-                ? {
-                    inputPerMTok: model.promo.inputPerMTok,
-                    outputPerMTok: model.promo.outputPerMTok,
-                    promoApplied: true,
-                }
-                : null,
-            base: Object.freeze({
+function holds(when, on, inputTokens) {
+    if (when.kind === 'utc-hours') {
+        const day = on.getUTCDay();
+        if (when.weekdaysOnly && (day === 0 || day === 6))
+            return false;
+        return when.hours.includes(on.getUTCHours());
+    }
+    if (inputTokens === undefined)
+        return null;
+    return inputTokens > when.tokens;
+}
+/**
+ * What one call is billed at, and what decided it.
+ *
+ * `tier` is the field this grew for, and it carries three states rather than
+ * two. A model with no tiers gets `null`. A model whose condition could be
+ * evaluated gets the tier that applied, or the base rate with `applied: null`
+ * and `decided: true`. A model whose condition could **not** be evaluated —
+ * a size tier priced without a token count — gets `decided: false`, the
+ * **dearer** of the candidate rates, and `because` naming what would settle it.
+ *
+ * The dearer one is not a shrug. A cost figure that is a ceiling can prove
+ * "under budget" and can never surprise a bill; a floor chosen for looking
+ * better is the flattering direction this product spends its time refusing.
+ * The reader still has to be told, which is what `decided: false` is for, and
+ * `pricing.test.js` fails a tiered model whose report drops it.
+ */
+export function effectivePricing(model, on = new Date(), context = {}) {
+    const memo = pricingMemo.get(model) ?? cache(model);
+    /**
+     * Tiers first, and a promotion never runs on top of one.
+     *
+     * No provider here does both, and combining them would be this repository
+     * inventing a price out of two real ones — the composed figure the first rule
+     * in the doctrine is about. A model that grew both would fail the guard in
+     * `pricing.test.js` rather than quietly getting a multiplied rate.
+     */
+    if (model.tiers !== undefined && model.tiers.length > 0) {
+        const undecided = [];
+        for (const tier of model.tiers) {
+            const verdict = holds(tier.when, on, context.inputTokens);
+            if (verdict === true) {
+                return {
+                    inputPerMTok: tier.inputPerMTok,
+                    outputPerMTok: tier.outputPerMTok,
+                    promoApplied: false,
+                    tier: { applied: tier.id, decided: true, because: describe(tier.when) },
+                };
+            }
+            if (verdict === null)
+                undecided.push(tier);
+        }
+        if (undecided.length === 0) {
+            return {
+                ...memo.base,
+                tier: { applied: null, decided: true, because: 'no conditional rate applies' },
+            };
+        }
+        /* The dearest candidate, so the figure is a ceiling rather than a wish. */
+        const dearest = undecided.reduce((worst, tier) => tier.inputPerMTok > worst.inputPerMTok ? tier : worst);
+        const ceiling = dearest.inputPerMTok > model.inputPerMTok
+            ? {
+                inputPerMTok: dearest.inputPerMTok,
+                outputPerMTok: dearest.outputPerMTok,
+                applied: dearest.id,
+            }
+            : {
                 inputPerMTok: model.inputPerMTok,
                 outputPerMTok: model.outputPerMTok,
-                promoApplied: false,
-            }),
+                applied: null,
+            };
+        return {
+            inputPerMTok: ceiling.inputPerMTok,
+            outputPerMTok: ceiling.outputPerMTok,
+            promoApplied: false,
+            tier: {
+                applied: ceiling.applied,
+                decided: false,
+                because: `${describe(dearest.when)}, and the token count was not given`,
+            },
         };
-        if (memo.promo)
-            Object.freeze(memo.promo);
-        pricingMemo.set(model, memo);
     }
     if (memo.untilMs !== null && on.getTime() <= memo.untilMs)
         return memo.promo;
     return memo.base;
 }
+/** One condition as a sentence a reader can check against a provider's page. */
+function describe(when) {
+    if (when.kind === 'input-tokens-above') {
+        return `prompts over ${when.tokens.toLocaleString('en-US')} input tokens`;
+    }
+    const windows = [];
+    let start = null;
+    const sorted = [...when.hours].sort((a, b) => a - b);
+    for (let i = 0; i < sorted.length; i += 1) {
+        if (start === null)
+            start = sorted[i];
+        if (sorted[i] + 1 !== sorted[i + 1]) {
+            windows.push(`${String(start).padStart(2, '0')}:00-${String(sorted[i] + 1).padStart(2, '0')}:00`);
+            start = null;
+        }
+    }
+    return `${windows.join(' and ')} UTC${when.weekdaysOnly ? ', Monday to Friday' : ''}`;
+}
 /** Cheapest model of each capability tier, for recommendations. */
 export function cheapestOfTier(tier) {
-    const candidates = MODELS.filter((m) => m.tier === tier && m.recommendable !== false);
+    const candidates = MODELS.filter((m) => m.tier === tier && isOffered(m));
     const first = candidates[0];
     if (!first)
         throw new Error(`No models for tier "${tier}"`);
@@ -434,6 +778,20 @@ export function cheapestOfTier(tier) {
  * a date — an overlay supplies this string, and a wrong one should read as
  * unknown rather than as a confident number computed from `NaN`.
  */
+/**
+ * The age at which this product stops treating its own price table as current.
+ *
+ * Three surfaces warn a reader that the figures above may be off — `profile`,
+ * the MCP report, the browser's bill — and each of them had typed `45` into
+ * its own comparison, with four locale sentences stating it again in prose.
+ * Seven copies of one claim, and nothing that would notice when they
+ * disagreed; the sentence a reader sees names the number, so a drift between
+ * them would have been a surface telling the reader one threshold and applying
+ * another.
+ *
+ * The value is what those surfaces already published, not a new judgement.
+ */
+export const STALE_PRICING_DAYS = 45;
 export function reviewAgeDays(lastReviewed, now) {
     if (!/^\d{4}-\d{2}-\d{2}$/.test(lastReviewed))
         return null;