@trazum/core 2.4.3 → 2.5.0

package/src/receipt.ts

@@ -210,7 +210,18 @@ export type ReceiptGap =
    * 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 };
+  | { kind: 'assumed-write-ttl'; calls: number }
+  /**
+   * Rows billed at the dearer of two rates because which one applied could
+   * not be decided: a model priced by prompt length, and a row that sums
+   * requests without saying any one prompt's length.
+   *
+   * Reported because it changes what kind of figure this is, in the other
+   * direction from `assumed-write-ttl`: the total is a **ceiling** on these
+   * rows. `ceilingUsd` is their share of it, `floorUsd` the same tokens at the
+   * cheaper rate; the true figure for them is between the two.
+   */
+  | { kind: 'tier-ceiling'; calls: number; models: string[]; ceilingUsd: number; floorUsd: number };
 
 export interface ReceiptDocument {
   /** The one thing a consumer must branch on. Set here, by the builder. */
@@ -389,6 +400,17 @@ export function receiptFrom(
   );
   if (assumed > 0) gaps.push({ kind: 'assumed-write-ttl', calls: assumed });
 
+  const ceilinged = report.byModel.filter((row) => row.breakdown.tierCeilingCalls > 0);
+  if (ceilinged.length > 0) {
+    gaps.push({
+      kind: 'tier-ceiling',
+      calls: report.total.tierCeilingCalls,
+      models: ceilinged.map((row) => row.model),
+      ceilingUsd: report.total.tierCeilingUsd,
+      floorUsd: report.total.tierFloorUsd,
+    });
+  }
+
   return {
     schemaVersion: 1,
     emittedAt: options.emittedAt?.toISOString() ?? null,

package/src/repeats.ts

@@ -1,4 +1,5 @@
 import { effectivePricing, multipliersFor } from './pricing.js';
+import { billedAt, promptSizeOf } from './billing.js';
 import { UNLABELLED } from './usage.js';
 import type { PricingCatalogue } from './pricing.js';
 import type { UsageRecord } from './usage.js';
@@ -119,8 +120,9 @@ export function createRepeatsTracker(options: RepeatsOptions): RepeatsTracker {
     if (gap < 0 || gap >= withinMs) return;
     if (before.tokens !== tokens) return;
 
-    const { inputPerMTok, outputPerMTok } = effectivePricing(model, on);
-    const rates = multipliersFor(model);
+    const at = billedAt(record, on);
+    const { inputPerMTok, outputPerMTok } = effectivePricing(model, at, promptSizeOf(record));
+    const rates = multipliersFor(model, at);
     const per = (count: number, rate: number): number => (count / 1_000_000) * rate;
     slice.repeats += 1;
     slice.usd +=

package/src/reprice.ts

@@ -1,5 +1,5 @@
 import { effectivePricing, multipliersFor } from './pricing.js';
-import type { PricingCatalogue } from './pricing.js';
+import type { PricingCatalogue, PromptSize } from './pricing.js';
 import type { ModelPricing } from './types.js';
 import type { ReceiptDocument } from './receipt.js';
 import type { UsageBreakdown, UsageProfileReport } from './usage.js';
@@ -158,6 +158,19 @@ export interface RepriceReport {
    * is the reader's.
    */
   batchOnTarget: { targetUsd: number } | null;
+  /**
+   * Slices priced at the target's dearer band because which band applied
+   * could not be decided, and what `targetUsd` would be with them at the
+   * cheaper one. `null` when every slice was decided.
+   *
+   * A target priced by prompt length bills each request on its own prompt; a
+   * slice is a sum, and its largest call is all it says about any one prompt.
+   * A slice whose largest call is under the line is under it throughout, and
+   * decided. One whose largest call is over is not, and is priced at the
+   * dearer band, so the comparison is a ceiling and never a saving it cannot
+   * stand behind; this is the other end.
+   */
+  tierCeiling: { slices: number; targetFloorUsd: number } | null;
   /** Always true. A field, not a comment, so a rendering can print it. */
   sameTokensAssumed: true;
 }
@@ -177,17 +190,35 @@ export function priceTokensOn(
   >,
   model: ModelPricing,
   on: Date = new Date(),
+  size: PromptSize = {},
 ): number {
-  const { inputPerMTok, outputPerMTok } = effectivePricing(model, on);
-  const rates = multipliersFor(model);
+  return priceTokensRanged(breakdown, model, on, size).usd;
+}
+
+/** The same price, and the cheaper one when a size band could not be decided. */
+function priceTokensRanged(
+  breakdown: Pick<
+    UsageBreakdown,
+    'inputTokens' | 'cacheReadTokens' | 'cacheWrite5mTokens' | 'cacheWrite1hTokens' | 'outputTokens'
+  >,
+  model: ModelPricing,
+  on: Date,
+  size: PromptSize,
+): { usd: number; floorUsd: number | null } {
+  const priced = effectivePricing(model, on, size);
+  const rates = multipliersFor(model, on);
   const per = (tokens: number, rate: number): number => (tokens / 1_000_000) * rate;
-  return (
+  const at = (inputPerMTok: number, outputPerMTok: number): number =>
     per(breakdown.inputTokens, inputPerMTok) +
     per(breakdown.cacheReadTokens, inputPerMTok * rates.cacheRead) +
     per(breakdown.cacheWrite5mTokens, inputPerMTok * rates.cacheWrite5m) +
     per(breakdown.cacheWrite1hTokens, inputPerMTok * rates.cacheWrite1h) +
-    per(breakdown.outputTokens, outputPerMTok)
-  );
+    per(breakdown.outputTokens, outputPerMTok);
+  const floor = priced.tier?.decided === false ? priced.tier.floor : undefined;
+  return {
+    usd: at(priced.inputPerMTok, priced.outputPerMTok),
+    floorUsd: floor === undefined ? null : at(floor.inputPerMTok, floor.outputPerMTok),
+  };
 }
 
 /**
@@ -249,6 +280,8 @@ function repriceSlices(
   const overContext: OverContextSlice[] = [];
   const alreadyOnTarget = { calls: 0, usd: 0 };
   let assumedWriteTtlCalls = 0;
+  let ceilingSlices = 0;
+  let floorSaving = 0;
 
   for (const breakdown of input.slices) {
     if (breakdown.model === target.id) {
@@ -266,7 +299,14 @@ function repriceSlices(
       });
       continue;
     }
-    const targetUsd = priceTokensOn(breakdown, target, on);
+    /* The slice's largest call bounds every prompt in it. */
+    const bound: PromptSize = { inputTokensAtMost: breakdown.maxCallInputTokens };
+    const ranged = priceTokensRanged(breakdown, target, on, bound);
+    const targetUsd = ranged.usd;
+    if (ranged.floorUsd !== null) {
+      ceilingSlices += 1;
+      floorSaving += ranged.usd - ranged.floorUsd;
+    }
     assumedWriteTtlCalls += breakdown.assumedWriteTtlCalls;
     /**
      * Cache traffic the target could not grant. The comparison is against the
@@ -297,6 +337,7 @@ function repriceSlices(
               },
               target,
               on,
+              bound,
             ),
           }
         : null;
@@ -323,20 +364,19 @@ function repriceSlices(
    * aggregates rather than by discounting `targetUsd`, because the discount
    * covers input and output while cache traffic rides through unchanged.
    */
-  const batchRate = multipliersFor(target).batch;
+  const batchRate = multipliersFor(target, on).batch;
   let batchOnTarget: { targetUsd: number } | null = null;
   if (batchRate !== null && batchRate < 1 && slices.length > 0) {
-    const { inputPerMTok, outputPerMTok } = effectivePricing(target, on);
     const movable = input.slices.filter(
       (slice) => slice.model !== target.id && slice.maxCallInputTokens <= target.contextWindow,
     );
-    const inOutUsd = movable.reduce(
-      (sum, slice) =>
-        sum +
-        (slice.inputTokens / 1_000_000) * inputPerMTok +
-        (slice.outputTokens / 1_000_000) * outputPerMTok,
-      0,
-    );
+    // Each slice at the band its own pricing above used, so the two cannot disagree.
+    const inOutUsd = movable.reduce((sum, slice) => {
+      const { inputPerMTok, outputPerMTok } = effectivePricing(target, on, {
+        inputTokensAtMost: slice.maxCallInputTokens,
+      });
+      return sum + (slice.inputTokens / 1_000_000) * inputPerMTok + (slice.outputTokens / 1_000_000) * outputPerMTok;
+    }, 0);
     batchOnTarget = { targetUsd: targetUsd - inOutUsd * (1 - batchRate) };
   }
 
@@ -356,6 +396,7 @@ function repriceSlices(
     unpricedModels: [...input.unpricedModels],
     unpricedCalls: input.unpricedCalls,
     batchOnTarget,
+    tierCeiling: ceilingSlices === 0 ? null : { slices: ceilingSlices, targetFloorUsd: targetUsd - floorSaving },
     sameTokensAssumed: true,
   };
 }

package/src/rollup.ts

@@ -316,6 +316,9 @@ const BREAKDOWN_SUM = [
   'truncatedCalls',
   'truncatedOutputUsd',
   'stopReasonCalls',
+  'tierCeilingCalls',
+  'tierCeilingUsd',
+  'tierFloorUsd',
 ] as const;
 
 /** Fields whose combination is a maximum, because a sum would invent a call. */

package/src/savings.ts

@@ -53,7 +53,14 @@ export function computeSavings(
   pricing: PricingCatalogue = BUNDLED_CATALOGUE,
 ): SavingsReport {
   const model = modelFrom(pricing, usage.model);
-  const { inputPerMTok, outputPerMTok, promoApplied } = effectivePricing(model, on);
+  /*
+   * Each prompt at its own length. On a model priced by prompt length the two
+   * sides can sit in different bands, and an edit that brings a prompt under
+   * the line saves the whole difference in rate, not only the tokens cut.
+   */
+  const ratesBefore = effectivePricing(model, on, { inputTokens: tokensBefore });
+  const ratesAfter = effectivePricing(model, on, { inputTokens: tokensAfter });
+  const promoApplied = ratesBefore.promoApplied || ratesAfter.promoApplied;
   // A provider with no batch API gets no discount even when the caller ticked
   // the box: `batchEligible` describes the work, not what the provider sells.
   const batchDiscount = multipliersFor(model).batch ?? 1;
@@ -61,16 +68,16 @@ export function computeSavings(
   const before = costOfCall(
     tokensBefore,
     usage.avgOutputTokens,
-    inputPerMTok,
-    outputPerMTok,
+    ratesBefore.inputPerMTok,
+    ratesBefore.outputPerMTok,
     usage.batchEligible,
     batchDiscount,
   );
   const after = costOfCall(
     tokensAfter,
     usage.avgOutputTokens,
-    inputPerMTok,
-    outputPerMTok,
+    ratesAfter.inputPerMTok,
+    ratesAfter.outputPerMTok,
     usage.batchEligible,
     batchDiscount,
   );

package/src/session-cost.ts

@@ -1,4 +1,5 @@
 import { effectivePricing, multipliersFor } from './pricing.js';
+import { billedAt, promptSizeOf } from './billing.js';
 import { UNLABELLED } from './usage.js';
 import type { PricingCatalogue } from './pricing.js';
 import type { UsageRecord } from './usage.js';
@@ -75,8 +76,10 @@ export interface SessionCostTracker {
 export function costOf(record: UsageRecord, catalogue: PricingCatalogue, on: Date): number | null {
   const model = catalogue.byId.get(record.model);
   if (!model) return null;
-  const { inputPerMTok, outputPerMTok } = effectivePricing(model, on);
-  const rates = multipliersFor(model);
+  // At the call's own moment and on its own prompt, as the bill prices it.
+  const at = billedAt(record, on);
+  const { inputPerMTok, outputPerMTok } = effectivePricing(model, at, promptSizeOf(record));
+  const rates = multipliersFor(model, at);
   const per = (tokens: number, rate: number): number => (tokens / 1_000_000) * rate;
   return (
     per(record.inputTokens, inputPerMTok) +

package/src/session-ledger.ts

@@ -1,4 +1,5 @@
 import { effectivePricing, multipliersFor } from './pricing.js';
+import { billedAt, promptSizeOf } from './billing.js';
 import { UNLABELLED } from './usage.js';
 import type { PricingCatalogue } from './pricing.js';
 import type { UsageRecord } from './usage.js';
@@ -77,6 +78,12 @@ interface SessionTally {
   write5mTokens: number;
   write1hTokens: number;
   assumedTokens: number;
+  /**
+   * What this conversation's writes cost, each call at its own moment and on
+   * its own prompt, so a one-turn conversation is priced exactly as the bill
+   * priced its one call.
+   */
+  writeUsd: number;
 }
 
 const median = (sorted: number[]): number => {
@@ -107,10 +114,18 @@ export function createSessionLedgerTracker(options: SessionLedgerOptions): Sessi
     }
     let tally = sessions.get(record.session);
     if (!tally) {
-      tally = { turns: 0, write5mTokens: 0, write1hTokens: 0, assumedTokens: 0 };
+      tally = { turns: 0, write5mTokens: 0, write1hTokens: 0, assumedTokens: 0, writeUsd: 0 };
       sessions.set(record.session, tally);
     }
     tally.turns += 1;
+    const model = catalogue.byId.get(record.model)!;
+    const at = billedAt(record, on);
+    const { inputPerMTok } = effectivePricing(model, at, promptSizeOf(record));
+    const rates = multipliersFor(model, at);
+    // The bill's own convention: unstated TTLs sit in the 5m bucket at the cheaper rate.
+    tally.writeUsd +=
+      ((record.cacheWrite5mTokens * rates.cacheWrite5m + record.cacheWrite1hTokens * rates.cacheWrite1h) / 1_000_000)
+      * inputPerMTok;
     if (record.writeTtlKnown) {
       tally.write5mTokens += record.cacheWrite5mTokens;
       tally.write1hTokens += record.cacheWrite1hTokens;
@@ -129,6 +144,7 @@ export function createSessionLedgerTracker(options: SessionLedgerOptions): Sessi
       let write5m = 0;
       let write1h = 0;
       let assumed = 0;
+      let singleTurnWriteUsd = 0;
       const turnCounts: number[] = [];
       for (const tally of sessions.values()) {
         turnCounts.push(tally.turns);
@@ -137,6 +153,7 @@ export function createSessionLedgerTracker(options: SessionLedgerOptions): Sessi
         write5m += tally.write5mTokens;
         write1h += tally.write1hTokens;
         assumed += tally.assumedTokens;
+        singleTurnWriteUsd += tally.writeUsd;
       }
       const singleTurnWriteTokens = write5m + write1h + assumed;
       // One-turn conversations that wrote nothing wasted nothing; a row about
@@ -146,14 +163,6 @@ export function createSessionLedgerTracker(options: SessionLedgerOptions): Sessi
       const split = key.indexOf('\n');
       const modelId = key.slice(split + 1);
       const model = catalogue.byId.get(modelId)!;
-      const { inputPerMTok } = effectivePricing(model, on);
-      const rates = multipliersFor(model);
-      const per = (tokens: number, rate: number): number =>
-        (tokens / 1_000_000) * inputPerMTok * rate;
-      // The bill's own convention: unstated TTLs at the cheaper rate, so this
-      // is the same floor the totals already stand on — never a new guess.
-      const singleTurnWriteUsd =
-        per(write5m + assumed, rates.cacheWrite5m) + per(write1h, rates.cacheWrite1h);
 
       turnCounts.sort((a, b) => a - b);
       out.push({

package/src/truncation-retry.ts

@@ -1,4 +1,5 @@
 import { effectivePricing, multipliersFor } from './pricing.js';
+import { billedAt, promptSizeOf } from './billing.js';
 import { UNLABELLED } from './usage.js';
 import type { PricingCatalogue } from './pricing.js';
 import type { UsageRecord } from './usage.js';
@@ -90,8 +91,9 @@ export function createTruncationRetryTracker(options: TruncationRetryOptions): T
   const priceOf = (record: UsageRecord): number | null => {
     const model = catalogue.byId.get(record.model);
     if (!model) return null;
-    const { inputPerMTok, outputPerMTok } = effectivePricing(model, on);
-    const rates = multipliersFor(model);
+    const at = billedAt(record, on);
+    const { inputPerMTok, outputPerMTok } = effectivePricing(model, at, promptSizeOf(record));
+    const rates = multipliersFor(model, at);
     const per = (count: number, rate: number): number => (count / 1_000_000) * rate;
     return (
       per(record.inputTokens, inputPerMTok) +

package/src/ttl-fit.ts

@@ -1,4 +1,5 @@
-import { effectivePricing, multipliersFor } from './pricing.js';
+import { cacheTtlOf, effectivePricing, multipliersFor } from './pricing.js';
+import { billedAt, promptSizeOf } from './billing.js';
 import { UNLABELLED } from './usage.js';
 import type { PricingCatalogue } from './pricing.js';
 import type { UsageRecord } from './usage.js';
@@ -79,6 +80,14 @@ export interface CacheTtlFit {
   /** Write tokens whose TTL the log did not record. */
   assumedTtlTokens: number;
   verdict: TtlFitVerdict;
+  /**
+   * How long this model's entries live: the one a write buys, and the longer
+   * one the provider also sells, or `null` when it sells none. Five minutes
+   * and an hour on Anthropic; thirty minutes and nothing longer on OpenAI's
+   * GPT-5.6 and later. A verdict reads them, and so does the sentence about it.
+   */
+  entryTtlMs: number;
+  longerTtlMs: number | null;
   /**
    * What the 1-hour writes would save at the 5-minute rate, when the gaps show
    * the hour is never needed. Exact — the same tokens at 1.25x instead of 2x,
@@ -104,6 +113,12 @@ interface Slice {
   write5mTokens: number;
   write1hTokens: number;
   assumedTtlTokens: number;
+  /**
+   * What the 1-hour writes would have saved at the 5-minute rate, each call at
+   * its own moment and on its own prompt: one rate for the whole slice priced
+   * a call on another band, or in another price period, at the wrong figure.
+   */
+  overlongUsd: number;
   /** Timestamps per session, sorted only at the end. */
   sessions: Map<string, number[]>;
 }
@@ -138,13 +153,21 @@ export function createTtlFitTracker(options: TtlFitOptions): TtlFitTracker {
     const key = `${record.label ?? UNLABELLED}\n${record.model}`;
     let slice = slices.get(key);
     if (!slice) {
-      slice = { write5mTokens: 0, write1hTokens: 0, assumedTtlTokens: 0, sessions: new Map() };
+      slice = { write5mTokens: 0, write1hTokens: 0, assumedTtlTokens: 0, overlongUsd: 0, sessions: new Map() };
       slices.set(key, slice);
     }
 
     if (record.writeTtlKnown) {
       slice.write5mTokens += record.cacheWrite5mTokens;
       slice.write1hTokens += record.cacheWrite1hTokens;
+      if (record.cacheWrite1hTokens > 0) {
+        const model = catalogue.byId.get(record.model)!;
+        const at = billedAt(record, on);
+        const { inputPerMTok } = effectivePricing(model, at, promptSizeOf(record));
+        const rates = multipliersFor(model, at);
+        slice.overlongUsd +=
+          (record.cacheWrite1hTokens / 1_000_000) * inputPerMTok * (rates.cacheWrite1h - rates.cacheWrite5m);
+      }
     } else {
       // The flat count sits in the 5m bucket by pricing convention; here it is
       // kept apart, because the whole question is which TTL it really was.
@@ -192,22 +215,21 @@ export function createTtlFitTracker(options: TtlFitOptions): TtlFitTracker {
        * uncertain one and money comes last: writes that expire are broken at
        * any price, and only writes that demonstrably work can be overpaying.
        */
+      /*
+       * Each model's own entry lives, not Anthropic's: an OpenAI entry outlives
+       * a ten-minute pause that a five-minute one would not.
+       */
+      const ttl = cacheTtlOf(model);
+      const longer = ttl.longerMs ?? ttl.writeMs;
       let verdict: TtlFitVerdict;
-      if (slice.write5mTokens > 0 && gap > TTL_5M_MS) verdict = 'expires-before-reuse';
-      else if (slice.write1hTokens > 0 && gap > TTL_1H_MS) verdict = 'expires-before-reuse';
-      else if (slice.assumedTtlTokens > 0 && gap > TTL_1H_MS) verdict = 'expires-before-reuse';
-      else if (slice.write1hTokens > 0 && gap <= TTL_5M_MS) verdict = 'overlong-ttl';
-      else if (slice.assumedTtlTokens > 0 && gap > TTL_5M_MS) verdict = 'unsettled';
+      if (slice.write5mTokens > 0 && gap > ttl.writeMs) verdict = 'expires-before-reuse';
+      else if (slice.write1hTokens > 0 && gap > longer) verdict = 'expires-before-reuse';
+      else if (slice.assumedTtlTokens > 0 && gap > longer) verdict = 'expires-before-reuse';
+      else if (slice.write1hTokens > 0 && gap <= ttl.writeMs) verdict = 'overlong-ttl';
+      else if (slice.assumedTtlTokens > 0 && gap > ttl.writeMs) verdict = 'unsettled';
       else verdict = 'fits';
 
-      const { inputPerMTok } = effectivePricing(model, on);
-      const rates = multipliersFor(model);
-      const overpayUsd =
-        verdict === 'overlong-ttl'
-          ? (slice.write1hTokens / 1_000_000) *
-            inputPerMTok *
-            (rates.cacheWrite1h - rates.cacheWrite5m)
-          : 0;
+      const overpayUsd = verdict === 'overlong-ttl' ? slice.overlongUsd : 0;
 
       out.push({
         label: key.slice(0, split),
@@ -220,6 +242,8 @@ export function createTtlFitTracker(options: TtlFitOptions): TtlFitTracker {
         write1hTokens: slice.write1hTokens,
         assumedTtlTokens: slice.assumedTtlTokens,
         verdict,
+        entryTtlMs: ttl.writeMs,
+        longerTtlMs: ttl.longerMs,
         overpayUsd,
       });
     }

package/src/types.ts

@@ -169,6 +169,12 @@ export type TierCondition =
    * `effectivePricing` says which happened rather than guessing.
    */
   | { kind: 'input-tokens-above'; tokens: number }
+  /**
+   * The prompt is `tokens` input tokens or more: xAI's wording, "requests
+   * whose prompt reaches 200k tokens". The same as above at one token less,
+   * kept apart so the sentence a reader sees is the provider's own.
+   */
+  | { kind: 'input-tokens-at-least'; tokens: number }
   /**
    * The call falls inside one of `hours` in UTC, optionally on weekdays only.
    *
@@ -238,6 +244,18 @@ export interface ModelPricing {
   caching?: CachingMode;
   /** Provider-specific cache and batch pricing. Defaults to Anthropic's. */
   multipliers?: CostMultipliers;
+  /**
+   * How long a cache entry lives, for a provider that bills writes.
+   *
+   * `writeMs` is the life of the entry a `cacheWrite5m` write buys, and
+   * `longerMs` the longer entry the provider also sells, or `null` when it
+   * sells none. Absent means Anthropic's: five minutes, and an hour at 2x.
+   * OpenAI's GPT-5.6 and later write one kind of entry, which lives at least
+   * 30 minutes after its last write or read, and the TTL verdict judged it
+   * against five minutes until this field existed: a conversation pausing for
+   * ten minutes was told its cache expired before it was read.
+   */
+  cacheTtl?: { writeMs: number; longerMs: number | null };
   /**
    * Whether to offer this model as a cheaper alternative.
    *