@trazum/core 1.82.0 → 1.83.0

package/src/receipt.ts

@@ -0,0 +1,351 @@
+import { PROVIDER_REVIEWED, modelFrom } from './pricing.js';
+import type { PricingCatalogue } from './pricing.js';
+import { UNLABELLED } from './usage.js';
+import type { UsageBreakdown, 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 const RECEIPT_LINE_FIELDS = Object.freeze([
+  'label',
+  'model',
+  'calls',
+  'inputTokens',
+  'cacheReadTokens',
+  'cacheWriteTokens',
+  'cacheWrite5mTokens',
+  'cacheWrite1hTokens',
+  'outputTokens',
+  'usd',
+  'money',
+  'pricing',
+] as const);
+
+const lineFrom = (
+  label: string,
+  model: string,
+  breakdown: UsageBreakdown,
+  catalogue: PricingCatalogue,
+): ReceiptLine => {
+  /*
+   * 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,
+    },
+  };
+};
+
+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 function receiptFrom(
+  report: UsageProfileReport,
+  catalogue: PricingCatalogue,
+  options: ReceiptOptions = {},
+): ReceiptDocument {
+  const lines = report.byLabelAndModel.map((slice) =>
+    lineFrom(slice.label, slice.model, slice.breakdown, catalogue),
+  );
+
+  const gaps: ReceiptGap[] = [];
+  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,
+  };
+}

package/src/types.ts

@@ -64,6 +64,7 @@ export type AdvisoryId =
   | 'tier-signals-conflict'
   | 'output-dominated'
   | 'promo-pricing'
+  | 'model-retired'
   | 'contradictory-instructions'
   | 'redundant-examples'
   | 'restated-output-format'
@@ -149,6 +150,59 @@ export type CachingMode =
  */
 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;
@@ -180,6 +234,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;
   /**
@@ -195,6 +275,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.
    *