@trazum/core 1.82.0 → 1.83.0

package/dist/receipt.d.ts

@@ -0,0 +1,253 @@
+import type { PricingCatalogue } from './pricing.js';
+import type { UsageProfileReport } from './usage.js';
+/**
+ * The receipt: a bill's counts, with the provenance of every figure attached.
+ *
+ * ## What it is for
+ *
+ * A profile answers a question on the terminal where it ran. A receipt is the
+ * same figures shaped so they can still answer it somewhere else: aggregated by
+ * somebody's dashboard, filed against an invoice, or compared against last
+ * month's by a reader who was not there when the command ran.
+ *
+ * That is why every line carries the rate behind its money and the date that
+ * rate was last read. A dollar figure with no provenance cannot tell a
+ * repricing from a team whose spend moved, and the consumer that most needs
+ * that distinction is the one that cannot read a sentence explaining it.
+ *
+ * ## Why a line carries money per bucket and not only a rate
+ *
+ * The first version of this module published the catalogue's `inputPerMTok`
+ * and `outputPerMTok` beside a dollar figure computed by `profileUsage`. Those
+ * are not always the same rates. A model in a promotional window, or one whose
+ * long-context tier applied, is billed at `effectivePricing`'s figure, and a
+ * cached read is billed at a fraction of input that no published field named at
+ * all. **A consumer multiplying the stated rates by the stated tokens got a
+ * different number from the stated total, with nothing saying which was
+ * wrong.**
+ *
+ * That is a bad defect in a document whose entire purpose is that a figure can
+ * be recomputed by whoever receives it, and it is the exact failure the
+ * doctrine line at the foot of this comment is about.
+ *
+ * So a line now carries the **money as it was actually apportioned** -- input,
+ * cache reads, cache writes and output -- and `usd` is their sum. The rates stay
+ * as provenance, labelled as the catalogue's published figures rather than as
+ * the arithmetic. `receipt-arithmetic.test.js` fails if the four stop adding up,
+ * which is a property a reader can check on any receipt they are handed rather
+ * than a promise they have to take.
+ *
+ * ## What it carries, and what it has no field for
+ *
+ * Counts, model, provider, the money split by bucket, the published rates, the
+ * review date, the label the log carried, the period, and what could not be
+ * priced. There is **no field
+ * for prompt text, for an answer, for a file path, for a branch name or for a
+ * credential** — not redacted, not hashed, absent, because the input this takes
+ * has nowhere to hold them either.
+ *
+ * `receipt-redaction.test.js` holds that by planting all 4 in a log — in the
+ * session field among other places, which is the value this package has
+ * promised since it shipped never comes back out — and failing if any reaches
+ * the output. A property about what a document does not contain is exactly the
+ * kind this repository proves by breaking rather than by asserting.
+ *
+ * ## What it is not
+ *
+ * **Not a transport.** Nothing here opens a socket, reads an environment
+ * variable or takes an endpoint. `receiptFrom` returns a value; where it goes
+ * is the caller's decision. A module in this package that phoned home would
+ * break the roadmap's first rule, which is that no feature may make a network
+ * call a prerequisite for anything.
+ *
+ * **Not a new measurement.** Every figure is one `profileUsage` already
+ * produced. This adds provenance around them and takes nothing away.
+ *
+ * Doctrine: [A machine reader gets the provenance too](../../../docs/doctrine.md#a-machine-reader-gets-the-provenance-too)
+ */
+/**
+ * The catalogue's published rates for this model, and when a human last read
+ * them off the provider's own page.
+ *
+ * **Provenance, not the arithmetic.** These are list rates. The money that was
+ * actually apportioned is in `ReceiptLine.money`, and the two differ whenever a
+ * promotion or a long-context tier applied, or for any token billed at a
+ * fraction of input -- which is every cached read. A consumer wanting the rate
+ * that was really charged divides a bucket's money by its tokens; a consumer
+ * wanting to know whether a provider repriced compares these.
+ */
+export interface ReceiptPricing {
+    provider: string;
+    inputPerMTok: number;
+    outputPerMTok: number;
+    /**
+     * The date this provider's rates were last read off its own page, `null`
+     * when the catalogue carries no date for that provider.
+     *
+     * Per provider rather than per catalogue, because that is how the prices are
+     * actually reviewed: looking at one page and finding nothing changed is not
+     * the same event as not looking. A server comparing two receipts a month
+     * apart reads a repricing as a repricing instead of as a team missing a
+     * target.
+     */
+    reviewedOn: string | null;
+}
+/** Where a line's money went. The four add to `ReceiptLine.usd`. */
+export interface ReceiptMoney {
+    inputUsd: number;
+    cacheReadUsd: number;
+    cacheWriteUsd: number;
+    outputUsd: number;
+}
+/** One slice of a bill: a label's calls to one model. */
+export interface ReceiptLine {
+    /**
+     * The attribution the log carried, or `null` for the unlabelled bucket.
+     *
+     * `null` rather than the sentinel, which is an internal grouping key and is
+     * never serialised. A consumer that saw the raw sentinel would have to know
+     * this package's internals to render it.
+     */
+    label: string | null;
+    model: string;
+    calls: number;
+    inputTokens: number;
+    cacheReadTokens: number;
+    /** Every cache write, whatever its TTL. The sum of the two fields below. */
+    cacheWriteTokens: number;
+    /**
+     * The two write TTLs kept apart, because they are billed at different rates.
+     *
+     * They are here for the same reason `UsageBreakdown` keeps them: the ratio
+     * between them is not a constant across providers, so a total that has lost
+     * the split can be repriced only by guessing at it. A consumer repricing this
+     * traffic against another model's rates needs both.
+     */
+    cacheWrite5mTokens: number;
+    cacheWrite1hTokens: number;
+    outputTokens: number;
+    /**
+     * What it cost, which is exactly the sum of `money` below.
+     *
+     * Every line here is priced; what is not is in `gaps`.
+     */
+    usd: number;
+    /**
+     * Where the money went, as it was apportioned rather than as it might be
+     * recomputed.
+     *
+     * This is the field that makes a receipt checkable. `usd` alone can only be
+     * believed; these four can be added up, and each can be divided by its own
+     * token count to recover the rate that was really charged -- including the
+     * one for cached reads, which no published rate names.
+     */
+    money: ReceiptMoney;
+    /** The catalogue's published rates, as provenance. */
+    pricing: ReceiptPricing;
+}
+/** Everything a receipt refuses to answer, typed rather than left implicit. */
+export type ReceiptGap = 
+/**
+ * Models the catalogue does not price, with the size of what they used.
+ *
+ * The counts are here rather than in a line, and the first draft of this
+ * module got that wrong in a way its own guard caught. `byLabelAndModel`
+ * excludes unpriced calls on purpose — the profile keeps them apart so that
+ * a total is never tokens from one set of calls over dollars from another —
+ * so a receipt built from that list alone silently loses them.
+ *
+ * The obvious repair was worse than the bug: emit a line with `label: null`.
+ * That reads as *this call carried no label*, when in fact it carried one the
+ * profile could not attach to a priced slice. Conflating "unlabelled" with
+ * "unattributable" is the exact failure this project refuses elsewhere, so
+ * the gap carries the magnitude instead and nothing pretends to an
+ * attribution it does not have.
+ */
+{
+    kind: 'unpriced';
+    models: string[];
+    calls: number;
+    inputTokens: number;
+    outputTokens: number;
+} | {
+    kind: 'unread-lines';
+    count: number;
+} | {
+    kind: 'no-clock';
+}
+/**
+ * Calls whose cache-write TTL the log did not state, so the cheaper rate was
+ * assumed.
+ *
+ * Reported because it changes what kind of figure this is. A total that
+ * includes an assumed TTL is a **floor** on those calls, not a measurement,
+ * and a document that says `counting: 'counted'` while quietly resting on an
+ * assumption is claiming a precision it does not have.
+ */
+ | {
+    kind: 'assumed-write-ttl';
+    calls: number;
+};
+export interface ReceiptDocument {
+    /** The one thing a consumer must branch on. Set here, by the builder. */
+    schemaVersion: 1;
+    /**
+     * When this receipt was made, or `null`.
+     *
+     * Optional on purpose, and the reason is the same one `plan.json` gives: a
+     * document without a stamp is undated, which a reader can act on. A document
+     * with an invented stamp is wrong, which they cannot.
+     */
+    emittedAt: string | null;
+    /** The period the counts cover, from the log's own clock. */
+    span: {
+        fromMs: number;
+        toMs: number;
+        calls: number;
+    } | null;
+    /**
+     * How the tokens were arrived at.
+     *
+     * `counted` for every receipt this function builds, because a usage log
+     * carries the provider's own counts. The field exists because a receipt built
+     * from an estimate would be a different kind of evidence, and a consumer must
+     * never have to guess which one it is holding.
+     */
+    counting: 'counted';
+    lines: ReceiptLine[];
+    total: {
+        calls: number;
+        usd: number;
+    };
+    /**
+     * What this receipt cannot say, and why.
+     *
+     * Present and empty rather than absent when there is nothing to report:
+     * "nothing was refused" and "this document does not record refusals" are
+     * different statements, and a server aggregating a thousand receipts has to
+     * be able to tell them apart.
+     */
+    gaps: ReceiptGap[];
+}
+/**
+ * The fields that leave this machine, listed once, in one place.
+ *
+ * The redaction guard reads this array rather than a copy of it, so a field
+ * added to `ReceiptLine` and not added here fails the guard. A whitelist
+ * maintained in two places is a whitelist with a hole in it.
+ */
+export declare const RECEIPT_LINE_FIELDS: readonly ["label", "model", "calls", "inputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite5mTokens", "cacheWrite1hTokens", "outputTokens", "usd", "money", "pricing"];
+export interface ReceiptOptions {
+    /** Stamp the document. Omit for an undated receipt, which is valid. */
+    emittedAt?: Date;
+}
+/**
+ * Build a receipt from a profile the caller already computed.
+ *
+ * Takes the report rather than the log text, and that is the guarantee rather
+ * than an ergonomic choice: `UsageProfileReport` has no field that can hold
+ * prompt content, so this function could not emit any even if it tried. The
+ * narrow input is what makes the promise checkable instead of merely stated.
+ */
+export declare function receiptFrom(report: UsageProfileReport, catalogue: PricingCatalogue, options?: ReceiptOptions): ReceiptDocument;
+//# sourceMappingURL=receipt.d.ts.map

package/dist/receipt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"receipt.d.ts","sourceRoot":"","sources":["../src/receipt.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,KAAK,EAAkB,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB;;;;;;;;;OASG;IACH,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,oEAAoE;AACpE,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,yDAAyD;AACzD,MAAM,WAAW,WAAW;IAC1B;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,4EAA4E;IAC5E,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;;;;;OAOG;IACH,kBAAkB,EAAE,MAAM,CAAC;IAC3B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;;OAQG;IACH,KAAK,EAAE,YAAY,CAAC;IACpB,sDAAsD;IACtD,OAAO,EAAE,cAAc,CAAC;CACzB;AAED,+EAA+E;AAC/E,MAAM,MAAM,UAAU;AACpB;;;;;;;;;;;;;;;GAeG;AACD;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAChG;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACvC;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE;AACtB;;;;;;;;GAQG;GACD;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjD,MAAM,WAAW,eAAe;IAC9B,yEAAyE;IACzE,aAAa,EAAE,CAAC,CAAC;IACjB;;;;;;OAMG;IACH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,6DAA6D;IAC7D,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC7D;;;;;;;OAOG;IACH,QAAQ,EAAE,SAAS,CAAC;IACpB,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACtC;;;;;;;OAOG;IACH,IAAI,EAAE,UAAU,EAAE,CAAC;CACpB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,mLAarB,CAAC;AA8CZ,MAAM,WAAW,cAAc;IAC7B,uEAAuE;IACvE,SAAS,CAAC,EAAE,IAAI,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,kBAAkB,EAC1B,SAAS,EAAE,gBAAgB,EAC3B,OAAO,GAAE,cAAmB,GAC3B,eAAe,CA8CjB"}

package/dist/receipt.js

@@ -0,0 +1,111 @@
+import { PROVIDER_REVIEWED, modelFrom } from './pricing.js';
+import { UNLABELLED } from './usage.js';
+/**
+ * The fields that leave this machine, listed once, in one place.
+ *
+ * The redaction guard reads this array rather than a copy of it, so a field
+ * added to `ReceiptLine` and not added here fails the guard. A whitelist
+ * maintained in two places is a whitelist with a hole in it.
+ */
+export const RECEIPT_LINE_FIELDS = Object.freeze([
+    'label',
+    'model',
+    'calls',
+    'inputTokens',
+    'cacheReadTokens',
+    'cacheWriteTokens',
+    'cacheWrite5mTokens',
+    'cacheWrite1hTokens',
+    'outputTokens',
+    'usd',
+    'money',
+    'pricing',
+]);
+const lineFrom = (label, model, breakdown, catalogue) => {
+    /*
+     * Every slice reaching here is priced: `byLabelAndModel` holds only what the
+     * catalogue knows. What it does not know is reported by the `unpriced` gap,
+     * with its size, so the receipt's total is never mistaken for the whole bill.
+     */
+    const priced = modelFrom(catalogue, model);
+    return {
+        label: label === UNLABELLED ? null : label,
+        model,
+        calls: breakdown.calls,
+        inputTokens: breakdown.inputTokens,
+        cacheReadTokens: breakdown.cacheReadTokens,
+        cacheWriteTokens: breakdown.cacheWriteTokens,
+        cacheWrite5mTokens: breakdown.cacheWrite5mTokens,
+        cacheWrite1hTokens: breakdown.cacheWrite1hTokens,
+        outputTokens: breakdown.outputTokens,
+        usd: breakdown.totalUsd,
+        /*
+         * Copied from the breakdown rather than recomputed from the rates below.
+         * Recomputing would reintroduce the defect this field exists to fix: the
+         * published rates are list rates, and a promotion, a long-context tier or
+         * any cached token is billed at something else.
+         */
+        money: {
+            inputUsd: breakdown.inputUsd,
+            cacheReadUsd: breakdown.cacheReadUsd,
+            cacheWriteUsd: breakdown.cacheWriteUsd,
+            outputUsd: breakdown.outputUsd,
+        },
+        pricing: {
+            provider: priced.provider ?? 'unknown',
+            inputPerMTok: priced.inputPerMTok,
+            outputPerMTok: priced.outputPerMTok,
+            reviewedOn: PROVIDER_REVIEWED[priced.provider ?? ''] ?? null,
+        },
+    };
+};
+/**
+ * Build a receipt from a profile the caller already computed.
+ *
+ * Takes the report rather than the log text, and that is the guarantee rather
+ * than an ergonomic choice: `UsageProfileReport` has no field that can hold
+ * prompt content, so this function could not emit any even if it tried. The
+ * narrow input is what makes the promise checkable instead of merely stated.
+ */
+export function receiptFrom(report, catalogue, options = {}) {
+    const lines = report.byLabelAndModel.map((slice) => lineFrom(slice.label, slice.model, slice.breakdown, catalogue));
+    const gaps = [];
+    if (report.unpricedModels.length > 0) {
+        gaps.push({
+            kind: 'unpriced',
+            models: [...report.unpricedModels],
+            calls: report.unpriced.calls,
+            inputTokens: report.unpriced.inputTokens,
+            outputTokens: report.unpriced.outputTokens,
+        });
+    }
+    if (report.skippedLines.length > 0) {
+        gaps.push({ kind: 'unread-lines', count: report.skippedLines.length });
+    }
+    if (report.span === null)
+        gaps.push({ kind: 'no-clock' });
+    /*
+     * Summed across the lines rather than read off a total, because the profile
+     * keeps this per slice and a receipt reports it once for the document.
+     */
+    const assumed = report.byLabelAndModel.reduce((sum, slice) => sum + slice.breakdown.assumedWriteTtlCalls, 0);
+    if (assumed > 0)
+        gaps.push({ kind: 'assumed-write-ttl', calls: assumed });
+    return {
+        schemaVersion: 1,
+        emittedAt: options.emittedAt?.toISOString() ?? null,
+        span: report.span === null ? null : { ...report.span },
+        counting: 'counted',
+        lines,
+        /*
+         * `report.total` already excludes what could not be priced — the profile
+         * keeps those in `unpriced` precisely so a total is never tokens from one
+         * set of calls divided by dollars from another. The receipt inherits that
+         * separation rather than re-deriving it, and `gaps` carries the size of
+         * what is missing.
+         */
+        total: { calls: report.total.calls, usd: report.total.totalUsd },
+        gaps,
+    };
+}
+//# sourceMappingURL=receipt.js.map

package/dist/receipt.js.map

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

package/dist/types.d.ts

@@ -48,7 +48,7 @@ export interface RuleResult {
 /** Severity of an advisory: the higher it is, the more money is usually at stake. */
 export type AdvisorySeverity = 'info' | 'opportunity' | 'warning';
 /** Every advisory the core can emit. */
-export type AdvisoryId = 'context-overflow' | 'context-near-limit' | 'prompt-caching' | 'prompt-caching-not-worth-it' | 'below-cache-minimum' | 'cache-prefix-reorder' | 'batch-api' | 'model-downgrade' | 'tier-signals-conflict' | 'output-dominated' | 'promo-pricing' | 'contradictory-instructions' | 'redundant-examples' | 'restated-output-format' | 'movable-output-schema';
+export type AdvisoryId = 'context-overflow' | 'context-near-limit' | 'prompt-caching' | 'prompt-caching-not-worth-it' | 'below-cache-minimum' | 'cache-prefix-reorder' | 'batch-api' | 'model-downgrade' | 'tier-signals-conflict' | 'output-dominated' | 'promo-pricing' | 'model-retired' | 'contradictory-instructions' | 'redundant-examples' | 'restated-output-format' | 'movable-output-schema';
 /** A recommendation that does NOT modify the prompt, only informs. */
 export interface Advisory {
     id: AdvisoryId;
@@ -125,6 +125,64 @@ export type CachingMode =
  * what it says.
  */
 export type Capability = 'small' | 'mid' | 'large' | 'frontier' | 'unknown';
+/**
+ * What makes a conditional rate apply, as data a machine can evaluate.
+ *
+ * Deliberately a closed union rather than a predicate function. A catalogue
+ * entry is reviewed the way a price is reviewed, and a reviewer can check
+ * "peak is 01:00-04:00 and 06:00-10:00 UTC on weekdays" against a provider's
+ * page; nobody can review a closure. It also means the condition survives
+ * `JSON.stringify`, which matters because the catalogue can be overlaid from a
+ * file.
+ */
+export type TierCondition = 
+/**
+ * The prompt is larger than `tokens` input tokens.
+ *
+ * Decidable only where the token count is known, which is most of the places
+ * that price a specific call and none of the places that merely rank models.
+ * `effectivePricing` says which happened rather than guessing.
+ */
+{
+    kind: 'input-tokens-above';
+    tokens: number;
+}
+/**
+ * The call falls inside one of `hours` in UTC, optionally on weekdays only.
+ *
+ * Decidable everywhere, because every caller already passes the date it is
+ * pricing for. `hours` lists the hour each window *starts*, so 01:00-04:00
+ * is `[1, 2, 3]` and not `[1, 4]`: an endpoint convention is the kind of
+ * thing two readers disagree about silently.
+ */
+ | {
+    kind: 'utc-hours';
+    hours: number[];
+    weekdaysOnly: boolean;
+};
+/**
+ * A rate that applies when its condition holds.
+ *
+ * Deliberately carries no multipliers of its own, and the first draft did. The
+ * reasoning for adding them was that DeepSeek halves the cache-hit price at
+ * off-peak along with everything else, so a cache read priced off the base
+ * would be wrong about the money — which is true of the *price* and false of
+ * the *ratio*: $0.007 against $0.22 and $0.014 against $0.44 are the same
+ * 3.18% to the last digit, on both models. Multiplying a tier's own input rate
+ * by the model's multiplier already gives the right answer.
+ *
+ * It was removed because the guard written to prove it mattered could not: with
+ * the tier multiplier equal to the base one, dropping it changed nothing and
+ * the test passed either way. An option nothing can distinguish from its
+ * absence is a claim nobody checks, which is worse than not having it.
+ */
+export interface PricingTier {
+    /** Short, stable, and printed: a reader has to be able to see which applied. */
+    id: string;
+    when: TierCondition;
+    inputPerMTok: number;
+    outputPerMTok: number;
+}
 export interface ModelPricing {
     id: string;
     displayName: string;
@@ -156,6 +214,32 @@ export interface ModelPricing {
      * buy is advice that wastes their time.
      */
     recommendable?: boolean;
+    /**
+     * Set when the provider refused a real request for this id.
+     *
+     * A retired model keeps its price and loses its future. Both halves matter:
+     * a log full of `deepseek-v3` calls records money that was genuinely spent,
+     * so deleting the row would make somebody's own history unpriceable — and a
+     * *new* call on that id will not happen at all, so quoting it as an option is
+     * a number for a question nobody can ask.
+     *
+     * `on` is the day `scripts/check-model-availability.mjs` was refused, and
+     * `because` is the provider's own sentence, quoted rather than paraphrased.
+     * Neither is a judgement, and neither implies anything about what the
+     * replacement costs: that is a price, and a price comes off the provider's
+     * own page or not at all.
+     *
+     * A retired model is never recommended, never offered as a cheaper
+     * alternative and never chosen as a tier's representative, in the same places
+     * `recommendable: false` is honoured — this is a stronger statement than that
+     * one and must not be weaker in effect.
+     */
+    retired?: {
+        /** ISO date the refusal was recorded. */
+        on: string;
+        /** What the provider answered, in the provider's words. */
+        because: string;
+    };
     /** Capability, on a vendor-neutral scale. */
     capability: Capability;
     /**
@@ -171,6 +255,29 @@ export interface ModelPricing {
         /** ISO date (inclusive) the promotional price applies until. */
         until: string;
     };
+    /**
+     * Rates that apply only under a stated condition.
+     *
+     * The catalogue held one input price and one output price per model until a
+     * real credential was pointed at the providers and two of them turned out not
+     * to charge that way:
+     *
+     * - **DeepSeek V4 bills by the clock.** Peak is 01:00-04:00 and 06:00-10:00
+     *   UTC, Monday to Friday, and off-peak is exactly half. That is 35 hours of
+     *   168, so the common case is the cheap one and a single number would have
+     *   been wrong by 2x in whichever direction it was chosen.
+     * - **Gemini 3.1 Pro bills by prompt size**, $2/$12 up to 200k input tokens
+     *   and $4/$18 above it.
+     *
+     * Both are *conditions*, so both are written as data rather than as prose in
+     * `notes`: a note is something a reader has to apply by hand, and this
+     * product exists to stop people doing arithmetic by hand.
+     *
+     * The base `inputPerMTok` and `outputPerMTok` stay the rate that applies when
+     * no condition matches, which keeps every model that has no tiers unchanged
+     * and keeps this field optional in effect as well as in the type.
+     */
+    tiers?: PricingTier[];
     /**
      * Other ids that bill at exactly this rate.
      *

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": "@trazum/core",
-  "version": "1.82.0",
+  "version": "1.83.0",
   "description": "Trazum core: priced advisories for LLM prompts (caching, model tier, batching, schemas), plus deterministic trimming, token counting and pricing.",
   "license": "MIT",
   "author": "David Mu\u00f1oz Rey",

package/src/advisories.ts

@@ -2,7 +2,13 @@ import { analyzeCachePrefix } from './cache.js';
 import { getMessages } from './i18n/index.js';
 import type { Locale } from './i18n/types.js';
 import { COMPLEX_SIGNALS, SIMPLE_SIGNALS } from './phrases.js';
-import { BUNDLED_CATALOGUE, effectivePricing, modelFrom, multipliersFor } from './pricing.js';
+import {
+  BUNDLED_CATALOGUE,
+  effectivePricing,
+  isOffered,
+  modelFrom,
+  multipliersFor,
+} from './pricing.js';
 import type { PricingCatalogue } from './pricing.js';
 import { formatUsd } from './savings.js';
 import { analyzeExamples, findContradictions, findMovableSchema,
@@ -124,9 +130,10 @@ function cheapestInTier(
     (m) =>
       m.tier === tier &&
       m.provider === provider &&
-      // Not generally available: recommending a model the reader cannot call is
-      // worse than recommending nothing.
-      m.recommendable !== false,
+      // Not generally available, or refused outright by the provider:
+      // recommending a model the reader cannot call is worse than
+      // recommending nothing. Both halves live in `isOffered`.
+      isOffered(m),
   );
   if (candidates.length === 0) return undefined;
   return candidates.reduce((best, m) =>
@@ -639,6 +646,29 @@ export function buildAdvisories(
     });
   }
 
+  if (model.retired) {
+    /**
+     * The most severe thing this function can say about a model, and it is
+     * placed before the promotional note deliberately: a price that is about to
+     * change matters less than a model that cannot be called at all.
+     *
+     * Not suppressed when the reader asked for this model by name. They asked
+     * because something in their world still says this id, and the whole value
+     * of the answer is that it no longer works.
+     */
+    advisories.push({
+      id: 'model-retired',
+      severity: 'warning',
+      ...t.advisories.modelRetired({
+        modelName: model.displayName,
+        modelId: model.id,
+        on: model.retired.on,
+        because: model.retired.because,
+      }),
+      estimatedMonthlyUsd: null,
+    });
+  }
+
   if (promoApplied && model.promo) {
     advisories.push({
       id: 'promo-pricing',

package/src/i18n/en.ts

@@ -218,6 +218,15 @@ export const en: CoreMessages = {
       detail: `${modelName} has introductory pricing of ${promoInput}/${promoOutput} per million tokens until ${until}. After that date it moves to ${listInput}/${listOutput}: your bill goes up even if you change nothing.`,
     }),
 
+    modelRetired: ({ modelName, modelId, on, because }) => ({
+      title: `${modelName} is priced here and refused by its provider`,
+      detail:
+        `A real request for \`${modelId}\` was answered with an error on ${on}: "${because}" `
+        + 'The price above is still the right one for calls already in your log, because that '
+        + 'money was spent. A new call on this id will not run. Nothing here proposes what the '
+        + 'replacement costs: that figure comes off the provider\'s own pricing page or not at all.',
+    }),
+
     contradictoryInstructions: ({
       axis,
       firstValue,

package/src/i18n/es.ts

@@ -202,6 +202,16 @@ export const es: CoreMessages = {
       detail: `${modelName} tiene precio de lanzamiento ${promoInput}/${promoOutput} por millón de tokens hasta el ${until}. A partir de esa fecha pasa a ${listInput}/${listOutput}: tu factura subirá aunque no cambies nada.`,
     }),
 
+    modelRetired: ({ modelName, modelId, on, because }) => ({
+      title: `${modelName} está tarifado aquí y su proveedor lo rechaza`,
+      detail:
+        `Una petición real a \`${modelId}\` se respondió con un error el ${on}: "${because}" `
+        + 'El precio de arriba sigue siendo el correcto para las llamadas que ya están en tu '
+        + 'registro, porque ese dinero se gastó. Una llamada nueva a este id no se ejecutará. '
+        + 'Aquí no se propone lo que cuesta el reemplazo: esa cifra sale de la página de precios '
+        + 'del proveedor o no sale.',
+    }),
+
     contradictoryInstructions: ({
       axis,
       firstValue,