@trazum/core 1.9.0 → 1.25.0

package/dist/usage.d.ts

@@ -0,0 +1,637 @@
+import type { SessionCostShape } from './session-cost.js';
+import type { CacheTtlFit } from './ttl-fit.js';
+import type { SingleTurnCacheWrites } from './session-ledger.js';
+import type { ConversationGrowth } from './conversation.js';
+import type { OutputShape } from './output-shape.js';
+import type { InputShape } from './input-shape.js';
+import type { RepeatedTurns } from './repeats.js';
+import type { PricingCatalogue } from './pricing.js';
+/**
+ * Where the money actually went, from calls that actually happened.
+ *
+ * ## Why this exists
+ *
+ * Everything else in this package reads a **prompt file** and reasons about what
+ * it would cost. That is the smallest line item on most bills, and the gap is not
+ * small enough to argue about: measured on an ordinary support prompt, the
+ * deterministic rules recover about **1%** of the monthly figure, while output
+ * tokens alone were **87%** of it. A tool that reads `prompts/*.txt` cannot see
+ * retrieved context, conversation history, tool results or answers, and on a RAG
+ * or agent workload those are nearly the whole invoice.
+ *
+ * So this reads the other direction: **what the provider actually charged**, per
+ * call, and says where it went. The sentence it is built to produce is "63% of
+ * your bill is retrieved context and nothing is watching it", which is a fact
+ * about a system rather than an estimate about a file.
+ *
+ * ## It reads a file, and that is the design
+ *
+ * Not a proxy, not an SDK wrapper, not a callback. Trazum's whole security
+ * position is that prompts do not leave the machine they are on — asserted by
+ * tests, not promised — and a tool that sits in the request path trades that away
+ * for convenience. A JSON Lines file is something you already have or can produce
+ * in three lines, and it keeps the guarantee intact.
+ *
+ * ## The format is the one the API already gives you
+ *
+ * Nothing is invented here. Every Anthropic response carries a `usage` object
+ * with exactly these fields, so recording a call is:
+ *
+ * ```ts
+ * appendFileSync('usage.jsonl', JSON.stringify({
+ *   model: response.model,
+ *   ...response.usage,
+ * }) + '\n');
+ * ```
+ *
+ * OpenAI's `usage` maps onto the same shape with different names, and
+ * `parseUsageLine` accepts both. Asking somebody to transform their logs into a
+ * bespoke schema before a tool will read them is how a tool goes unused.
+ *
+ * ## What it refuses to do
+ *
+ * **It does not read prompt text and there is nowhere to put it.** The record
+ * shape has no field for content, so a usage log handed to Trazum cannot contain
+ * a prompt even by accident. That is a stronger promise than "we do not look at
+ * it", and it is the reason this takes counts rather than calls.
+ *
+ * **It reports no saving.** Attributing "you could have saved X" to a call that
+ * already happened means guessing what the call should have been, and this module
+ * exists precisely because guessing is what the rest of the package has to do.
+ * It reports what was spent, split by where it went. What to do about it is a
+ * different question and belongs to the advisories.
+ *
+ * `cacheEconomics` is the one counterfactual here, and it is not an exception to
+ * that rule — it is the line the rule draws. A saving requires imagining a prompt
+ * nobody wrote; this requires imagining the **same tokens at a different rate**,
+ * which is arithmetic. Caching does not change what is sent, only the multiplier
+ * it is billed at, so "these tokens cost 1.25x instead of 1x" is as measured as
+ * the total itself. Anything that would need a guess about content stays out.
+ */
+/** One recorded call, after parsing. All counts, no content. */
+export interface UsageRecord {
+    /** Model id as the provider reported it. */
+    model: string;
+    /** Uncached input tokens billed at the full rate. */
+    inputTokens: number;
+    /** Tokens billed at the cache-read rate. Zero when nothing was cached. */
+    cacheReadTokens: number;
+    /** Cache writes at the 5-minute rate — 1.25x input on Anthropic. */
+    cacheWrite5mTokens: number;
+    /** Cache writes at the 1-hour rate, which is **2x** input, not 1.25x. */
+    cacheWrite1hTokens: number;
+    /**
+     * Whether the log said which TTL those writes used.
+     *
+     * `false` when only the flat `cache_creation_input_tokens` was present and it
+     * was non-zero: the writes are then priced at the cheaper 5-minute rate because
+     * one of the two has to be assumed, and the report says so. Choosing the cheaper
+     * rate silently understates a 1-hour workload by 37.5% on its largest line.
+     */
+    writeTtlKnown: boolean;
+    outputTokens: number;
+    /**
+     * Optional label for grouping — an endpoint, a feature, a prompt name.
+     *
+     * The whole value of a profile is answering "which part of the product costs
+     * this", and without a label every call looks alike. Unlabelled records are
+     * grouped under a single bucket rather than dropped, because a profile that
+     * refuses to read a log until it is annotated is a profile nobody runs.
+     */
+    label: string | null;
+    /**
+     * Optional conversation identifier, for measuring what re-sent history costs.
+     *
+     * On a chat or agent workload the input grows with every turn, because the whole
+     * conversation goes back up on each call. That is frequently the largest line on
+     * the bill and nothing watches it — a prompt file cannot show it, and a total
+     * cannot either.
+     *
+     * **Trazum never prints this value.** A session key is somebody's conversation
+     * and could easily be an account id or an email; it is used to group calls and
+     * to count turns, and every figure derived from it is reported per *label*. That
+     * keeps the guarantee this module is built on: a usage log handed to Trazum
+     * carries no content, and nothing identifying comes back out of it either.
+     */
+    session: string | null;
+    /**
+     * When the call happened, as epoch milliseconds, or `null` when the log does
+     * not say.
+     *
+     * Read from `ts`, `timestamp`, `created_at` or OpenAI's `created`; ISO 8601
+     * strings and epoch numbers both work, with seconds told from milliseconds by
+     * magnitude. The clock unlocks the two findings counts alone cannot make:
+     * what period this log actually covers, and whether the cache TTL fits how
+     * fast the turns arrive — the single most common reason a cache loses money.
+     */
+    ts: number | null;
+    /**
+     * Whether the answer hit the output ceiling, when the log says.
+     *
+     * `true` for Anthropic's `stop_reason: "max_tokens"` and OpenAI's
+     * `finish_reason: "length"`; `false` for any other recorded reason; `null`
+     * when the log does not carry the field. Three states, because "no truncation
+     * recorded" and "no truncation happened" are different answers — the report
+     * must not congratulate a log that never measured.
+     */
+    truncated: boolean | null;
+}
+/** What a set of calls cost, split by where the money went. */
+export interface UsageBreakdown {
+    calls: number;
+    inputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    /**
+     * The two write TTLs kept apart, because they are billed at different rates
+     * — 1.25x input for a 5-minute entry and **2x** for a 1-hour one.
+     *
+     * `cacheWriteTokens` is their sum and stays the figure to read for volume.
+     * These exist so the same tokens can be priced again at another model's
+     * rates without the ratio between the two being invented: it is not a
+     * constant across providers, so a total that has lost the split cannot be
+     * repriced, only guessed at.
+     *
+     * Writes whose TTL the log did not state are in the 5-minute bucket, the
+     * same assumption `cacheWriteUsdIfAssumed1h` measures the cost of.
+     */
+    cacheWrite5mTokens: number;
+    cacheWrite1hTokens: number;
+    outputTokens: number;
+    /**
+     * Calls whose cache-write TTL the log did not state, so the cheaper rate was
+     * assumed. Non-zero means this total is a floor on those calls, not a figure.
+     */
+    assumedWriteTtlCalls: number;
+    /**
+     * The largest single call's input, cache reads and writes included — the one
+     * number that says whether these calls would fit somewhere else.
+     *
+     * A cheaper model with a smaller context window does not make this traffic
+     * cheaper; it makes some of it impossible, and a price comparison that only
+     * multiplies rates would call that a saving. The maximum is the right
+     * statistic rather than the mean: one call over the ceiling is a failed
+     * call, and an average hides it.
+     */
+    maxCallInputTokens: number;
+    inputUsd: number;
+    cacheReadUsd: number;
+    cacheWriteUsd: number;
+    outputUsd: number;
+    totalUsd: number;
+    /**
+     * What the cache-touched tokens would have cost as ordinary input.
+     *
+     * Reads plus writes, at each model's own full input rate, accumulated per call
+     * because the rate is per model and a total loses that. Not part of `totalUsd`
+     * and not a bill — it is the other half of `cacheEconomics`, kept here because
+     * it can only be computed while the model is still in hand.
+     */
+    cachedTokensAtInputRateUsd: number;
+    /**
+     * `cacheWriteUsd` with every **unstated-TTL** write priced at the 1-hour rate.
+     *
+     * Equal to `cacheWriteUsd` when the log recorded which TTL each write used.
+     * When it did not, the cheaper 5-minute rate is assumed for the headline figure
+     * — and this is what the same calls cost if that assumption is wrong.
+     *
+     * It exists because the assumption reaches further than the total. It moves the
+     * *verdict*: a workload reading back between 0.28 and 1.11 tokens per token
+     * written is reported as paying for itself at 1.25x and as losing money at 2x,
+     * and the log is silent about which. A verdict that cannot see the assumption
+     * behind it states the flattering half as a fact.
+     */
+    cacheWriteUsdIfAssumed1h: number;
+    /**
+     * Calls whose answer hit the output ceiling, and what their output cost.
+     *
+     * The one category of a bill that is waste without a counterpart: an answer
+     * cut off mid-generation was paid for in full, is frequently retried — billed
+     * again — and the truncated attempt bought nothing. Output is the largest
+     * line on most bills, and this is the slice of it nobody sees.
+     */
+    truncatedCalls: number;
+    truncatedOutputUsd: number;
+    /** Calls that recorded a stop reason at all, truncated or not. */
+    stopReasonCalls: number;
+}
+export interface UsageProfileReport {
+    /** Everything, combined. */
+    total: UsageBreakdown;
+    /** Per `label`, largest bill first — the order somebody would act in. */
+    byLabel: Array<{
+        label: string;
+        breakdown: UsageBreakdown;
+    }>;
+    /** Per model, largest bill first. */
+    byModel: Array<{
+        model: string;
+        breakdown: UsageBreakdown;
+    }>;
+    /**
+     * Per label **and** model, largest bill first.
+     *
+     * The grouping a decision is actually made at. "Route `classify` to something
+     * cheaper" is a question about the calls `classify` makes to one model, and a
+     * label that spans two models has no single answer — pricing it against a
+     * cheaper candidate would mean picking one of the two current prices and
+     * applying it to tokens that were never billed at it.
+     */
+    byLabelAndModel: Array<{
+        label: string;
+        model: string;
+        breakdown: UsageBreakdown;
+    }>;
+    /**
+     * Models in the log that the pricing catalogue does not know.
+     *
+     * Named rather than silently costed at zero. A profile that quietly omits a
+     * model reports a total lower than the real bill, which is the flattering
+     * direction and the one this repository refuses.
+     */
+    unpricedModels: string[];
+    /**
+     * What those models used, kept entirely out of `total`.
+     *
+     * The first version added their **tokens** to the totals and their **dollars**
+     * to nothing, because pricing failed after the counts had been accumulated. So
+     * `total.inputTokens` included them and `total.inputUsd` did not, and anybody
+     * dividing one by the other got a cost per token that was wrong by however much
+     * of the log was unpriced — silently, and low.
+     *
+     * They are separated now. `total` is what could be priced, tokens and dollars
+     * describing the same calls. This is what could not, so the size of the gap is
+     * visible instead of being folded into a number that looks complete.
+     */
+    unpriced: UsageBreakdown;
+    /**
+     * Lines that could not be read, with their 1-based position.
+     *
+     * Reported rather than thrown on. A log with three malformed lines out of forty
+     * thousand should still produce a profile, and a parser that dies on the first
+     * one makes the tool unusable on real data — but a parser that skips quietly
+     * produces a total that is wrong by an unknown amount.
+     */
+    skippedLines: number[];
+    /**
+     * What re-sending the conversation costs, where the log carries a session.
+     *
+     * Empty when it does not, which is a different statement from zero growth — the
+     * report says which, because "nothing to report" and "nothing recorded" are the
+     * two answers a reader would act on differently.
+     */
+    conversations: ConversationGrowth[];
+    /** Whether any record carried a session at all. */
+    hasSessions: boolean;
+    /**
+     * Where the output spend concentrates, for slices whose output is a real share
+     * of the bill. The actionable half of "output dominates": six per cent of calls
+     * holding half the spend is a tail worth hunting, forty-five per cent is a task
+     * whose answers are inherently long — and the total cannot tell them apart.
+     */
+    outputShapes: OutputShape[];
+    /**
+     * How big a call's input is, and how uneven that is across a slice — the
+     * half of the bill a total could only name. "Input is 63% of this bill" is
+     * unactionable; whether the p95 call carries twelve times the median call's
+     * input decides between capping something and rewriting a prompt.
+     *
+     * Every figure is a bucket ceiling rather than an interpolated percentile,
+     * and slices with too few calls for a percentile to mean anything are left
+     * out entirely rather than reported at a precision they do not have.
+     */
+    inputShapes: InputShape[];
+    /**
+     * Calls that re-sent the previous call's exact input size, in the same
+     * conversation, seconds later — the shape of a retry or a loop.
+     *
+     * A conversation's input grows with every turn, so two consecutive calls
+     * carrying the same size a moment apart is a thing going wrong rather than
+     * a thing working. Needs both a session and a clock; empty when the log
+     * carries neither, which is a different statement from "none happened".
+     */
+    repeatedTurns: RepeatedTurns[];
+    /**
+     * The period the log covers, when its records carry a clock, over every
+     * parsed record — priced and unpriced alike, because when a call happened is
+     * a fact about the log rather than about the catalogue.
+     *
+     * `calls` is how many records carried a timestamp; compared against the
+     * parsed total it says whether the span describes the whole log or a slice
+     * of it, and the report states which. **The span is stated, never
+     * extrapolated**: "this log covers 13 days" makes the reader's own monthly
+     * arithmetic valid, while a per-month figure printed from a partial month
+     * would be this module doing the guessing it exists to end.
+     */
+    span: {
+        fromMs: number;
+        toMs: number;
+        calls: number;
+    } | null;
+    /**
+     * Spend per UTC day, oldest first, over priced records that carry a clock.
+     *
+     * The shape of a bill over time is the finding the total hides: a steady $3 a
+     * day and a quiet week broken by one $40 spike sum to the same number and
+     * call for opposite responses. Each day carries its most expensive label so a
+     * spike arrives with a suspect attached — per *label*, never per session.
+     *
+     * UTC deliberately: the log's timestamps carry no zone once parsed, and
+     * bucketing by the reader's local midnight would make the same log answer
+     * differently in two offices.
+     */
+    spendByDay: Array<{
+        /** `YYYY-MM-DD`, UTC. */
+        day: string;
+        usd: number;
+        calls: number;
+        /** The label that spent the most this day, or null when nothing had one. */
+        topLabel: string | null;
+        topLabelUsd: number;
+    }>;
+    /**
+     * Lines that are exact duplicates of an earlier line, and what they added
+     * to the total.
+     *
+     * Reading a directory of rotated logs — or catting them together by hand —
+     * makes double-counting easy: a log exported twice, an overlapping export,
+     * a copy left in the folder. The bill then reads high, and nothing else in
+     * this report can see it, because two identical calls are indistinguishable
+     * from one call recorded twice *unless* the record carries a clock.
+     *
+     * So this counts only records with a `ts`: identical token counts, identical
+     * label and session, and the same millisecond. Two real calls colliding on
+     * all of that is possible and vanishingly unlikely; without a clock it is
+     * ordinary, which is why clockless records are excluded rather than guessed
+     * at. The report states the count and the money and stops — whether it is a
+     * double export or a busy millisecond is the reader's to know.
+     *
+     * The comparison is over the **raw line**, not a hash of it: a hash
+     * collision would report a duplicate that is not one, and this figure exists
+     * to make somebody distrust a total.
+     */
+    duplicateLines: {
+        count: number;
+        usd: number;
+    };
+    /**
+     * How many parsed records carried each optional field.
+     *
+     * Every finding this module makes beyond the totals needs a field the log
+     * format does not require, and a reader who never adds them sees a report
+     * quietly missing half of itself. Counting them turns "Trazum did not tell
+     * me about conversation growth" into "none of your 40,000 records carry a
+     * session", which is a fact somebody can act on in an afternoon.
+     *
+     * Counted over records that **parsed**, priced or not: whether a field is
+     * present is a property of the log, not of the price catalogue. Partial
+     * coverage is the interesting case and is why these are counts rather than
+     * booleans — 12 records out of 40,000 carrying a label is not "labelled",
+     * and a boolean would call it that.
+     */
+    fieldCoverage: {
+        /** Records with a usable `label`. */
+        label: number;
+        /** Records with a usable `session` or `conversation_id`. */
+        session: number;
+        /** Records with a readable timestamp. */
+        ts: number;
+        /** Records with a `stop_reason` or `finish_reason`. */
+        stopReason: number;
+        /** Records whose cache writes stated which TTL they used. */
+        cacheTtl: number;
+        /** Records that wrote to the cache at all — the denominator for `cacheTtl`. */
+        cacheWrites: number;
+        /** Every record that parsed, priced or not — the denominator for the rest. */
+        parsed: number;
+    };
+    /**
+     * Spend per hour of the UTC day, 0–23, over priced records that carry a
+     * clock — and only the hours that saw traffic.
+     *
+     * The shape a day has says what kind of workload this is. Spend packed into
+     * the hours a country is awake is interactive traffic somebody is waiting
+     * on; spend spread evenly across all twenty-four is background work, and
+     * background work is exactly what the Batch API halves the price of. The
+     * total cannot tell those apart, and neither can the per-day series.
+     *
+     * UTC deliberately, like `spendByDay`: bucketing by the reader's local hour
+     * would make the same log answer differently in two offices, and the log's
+     * timestamps carry no zone once parsed. A reader who knows their traffic is
+     * in one region can shift the hours themselves; Trazum inventing an offset
+     * would be guessing.
+     */
+    spendByHour: Array<{
+        hour: number;
+        usd: number;
+        calls: number;
+    }>;
+    /**
+     * Whether each slice's cache TTL fits how fast its turns arrive — the
+     * mechanism behind a losing cache verdict, and the one place an overlong TTL
+     * (2x writes surviving gaps measured in seconds) is ever visible. Needs
+     * `session` and a timestamp on the records; empty otherwise, which the
+     * report distinguishes from "measured and fine".
+     */
+    cacheTtlFit: CacheTtlFit[];
+    /**
+     * The time filter this report was computed under, or `null` when there was
+     * none — so a rendering can say "this is a window, not the log" instead of
+     * presenting a slice as the whole.
+     *
+     * `undatedExcluded` is the honesty cost of filtering by a clock some records
+     * do not carry: calls that passed every other filter but could not be
+     * placed in or out of the window. Non-zero means the window's figures are a
+     * floor on the period, and every rendering says so out loud.
+     */
+    timeWindow: {
+        sinceMs: number | null;
+        untilMs: number | null;
+        undatedExcluded: number;
+    } | null;
+    /**
+     * Cache writes made by conversations that ended after one turn — reuse paid
+     * for that their own conversation never made. A ceiling named as one: the
+     * provider's cache is keyed by prefix, so another session sharing the
+     * prefix within the TTL could have read these writes, and the log cannot
+     * see whose write a read hit. When the slice's `cacheReadTokens` is zero
+     * the ceiling collapses into a fact — nothing read those writes at all —
+     * and the renderings say which of the two they are stating.
+     */
+    singleTurnCacheWrites: SingleTurnCacheWrites[];
+    /**
+     * What one conversation costs — median, p95 and maximum per slice, exact
+     * and billed. The question a total cannot answer: whether $4,000 is forty
+     * thousand cheap conversations or four hundred expensive ones, which is
+     * what a per-seat price or a quota is set from. Empty when the log carries
+     * no session, or when no slice has enough conversations for a median to
+     * mean anything.
+     */
+    sessionCosts: SessionCostShape[];
+}
+/** The share of the bill each part accounts for, as fractions of 1. */
+export interface UsageShares {
+    input: number;
+    cacheRead: number;
+    cacheWrite: number;
+    output: number;
+}
+export declare function parseUsageLine(line: string): UsageRecord | null;
+/**
+ * The bucket unlabelled calls land in.
+ *
+ * The empty string, because it is the one value a parsed label can never be —
+ * `parseUsageLine` trims and rejects empty. The first version used the literal
+ * string `'unlabelled'`, and a workload somebody had actually named `unlabelled`
+ * merged silently into the missing-label bucket: 200 labelled calls and 200
+ * unlabelled ones reported as one row of 400, and the "none of these calls
+ * carried a label" warning fired over a log where half of them had.
+ *
+ * Presentation stays in the CLI, which translates this sentinel through the
+ * message catalogue; data consumers can tell `''` from any real label.
+ */
+export declare const UNLABELLED = "";
+export interface UsageProfileOptions {
+    catalogue: PricingCatalogue;
+    /** Date the prices are read at, so a promotional rate resolves the same way. */
+    on?: Date;
+    /**
+     * Profile only the records carrying this label — the drill-down, once the
+     * full report has named a suspect. `UNLABELLED` (the empty string) selects
+     * the records with no label at all. Unreadable lines still land in
+     * `skippedLines` whatever they might have been labelled: a filter must not
+     * make corruption disappear.
+     */
+    label?: string;
+    /**
+     * Profile only the records whose clock falls in `[sinceMs, untilMs)` — the
+     * drill-down in time, once the peak day or the span has named a period.
+     *
+     * Epoch milliseconds, half-open on the right so two adjacent windows share
+     * no record. Either bound alone works. **A record with no clock cannot be
+     * placed inside or outside a window**, so under a time filter it is
+     * excluded and counted in `timeWindow.undatedExcluded` — excluded, because
+     * including it would put unknown-time spend inside a window it may not
+     * belong to; counted, because dropping it silently would understate the
+     * period's bill by an invisible amount, which is the flattering direction.
+     */
+    sinceMs?: number;
+    untilMs?: number;
+}
+/**
+ * Reads a usage log and says where the money went.
+ *
+ * Takes the whole text rather than a stream: a usage log is measured in megabytes
+ * and this package imports no Node builtins, so streaming would mean an interface
+ * the browser build cannot satisfy. `@trazum/core/node` is where file reading
+ * lives, and it can chunk if it ever needs to.
+ */
+export declare function profileUsage(text: string, options: UsageProfileOptions): UsageProfileReport;
+/**
+ * What share of the bill each part is.
+ *
+ * The point of the whole module in one function: a caller can print "output is
+ * 87% of this" without doing arithmetic that would drift from the arithmetic
+ * here.
+ *
+ * All zeroes when nothing was spent, rather than `NaN`. A profile of an empty log
+ * is a legitimate result — no calls yet — and a report full of `NaN%` is a bug
+ * report from somebody who did nothing wrong.
+ */
+export declare function sharesOf(breakdown: UsageBreakdown): UsageShares;
+/**
+ * How much of the input that could have been cached was.
+ *
+ * `null` when nothing was cacheable-looking at all — no reads and no writes —
+ * because a hit rate over zero attempts is not zero, it is undefined, and
+ * printing "0% cache hit rate" for somebody who never turned caching on is a
+ * finding about nothing.
+ *
+ * Reads against reads-plus-full-price-input, deliberately. Cache *writes* are
+ * excluded from the denominator: a write is the cost of establishing an entry,
+ * not a missed read, and counting it as a miss makes a healthy cache look broken
+ * on the day it warms.
+ */
+export declare function cacheHitRate(breakdown: UsageBreakdown): number | null;
+/** What caching did to this bill, measured against the same tokens uncached. */
+export interface CacheEconomics {
+    /** What the cache-touched tokens actually cost: reads plus writes. */
+    spentUsd: number;
+    /** What those same tokens would have cost billed as ordinary input. */
+    withoutCachingUsd: number;
+    /**
+     * `spentUsd - withoutCachingUsd`.
+     *
+     * **Positive means caching cost more than it saved** — the opposite of the sign
+     * convention everywhere else in Trazum, and deliberately so, because this is the
+     * number nobody expects to come out positive and the one worth interrupting for.
+     */
+    deltaUsd: number;
+    /**
+     * Read tokens per write token, or `null` when nothing was written.
+     *
+     * Context for the delta, not a verdict of its own: the delta already decides,
+     * and it decides at the real per-model rates. This says *why* — a ratio near
+     * zero on an Anthropic workload is a prefix being rebuilt faster than it is
+     * reused, which is the shape of a cache that never gets to work.
+     */
+    readsPerWrite: number | null;
+    verdict: CacheVerdict;
+    /**
+     * `deltaUsd` with every write whose TTL the log did not state priced at the
+     * 1-hour rate instead of the assumed 5-minute one.
+     *
+     * Equal to `deltaUsd` when every TTL was recorded, and never smaller: the
+     * 1-hour multiplier is at or above the 5-minute one on every model in the
+     * catalogue, so this is a genuine worst case rather than the other end of a
+     * range.
+     */
+    worstCaseDeltaUsd: number;
+    /**
+     * The verdict at that worst case.
+     *
+     * **When this differs from `verdict`, the log cannot settle the question** and
+     * neither can any report built from it. That is not a rare shape: a workload
+     * reading back between 0.28 and 1.11 tokens per token written flips between
+     * `paid-off` and `lost-money` on the TTL alone, and a log carrying only the flat
+     * `cache_creation_input_tokens` never says which. Measured on a million written
+     * tokens against three hundred thousand read back, the difference was a $0.10
+     * saving against a $3.65 loss — a $3.75 swing across the sign, and the assumed
+     * half is the flattering one.
+     */
+    worstCaseVerdict: CacheVerdict;
+}
+/**
+ * - `paid-off` — caching took money off the bill.
+ * - `lost-money` — caching added to it. Possible on Anthropic, where a write
+ *   costs 1.25x input (5-minute) or 2x (1-hour); a prefix that never gets read
+ *   back is billed at a premium for nothing.
+ * - `no-difference` — the multipliers cancelled out. This is where automatic
+ *   caching with a 1x write rate lands when nothing was ever read.
+ * - `not-attempted` — no cache tokens at all, in either direction.
+ * - `unpriced` — cache tokens with no prices behind them, so there is no
+ *   comparison to make. Saying nothing is the only honest answer.
+ */
+export type CacheVerdict = 'paid-off' | 'lost-money' | 'no-difference' | 'not-attempted' | 'unpriced';
+/**
+ * Did caching pay for itself?
+ *
+ * The question nothing else in this package can answer, and the one that decides
+ * whether the advice the rest of it gives was right. Trazum tells people to cache;
+ * on Anthropic a cache **write** costs 1.25x plain input at the 5-minute TTL and
+ * **2x** at the 1-hour one, so a prefix that changes faster than it is reused is
+ * billed at a premium and returns nothing. That workload would be cheaper with
+ * caching switched off, and no other report in this repository would ever say so.
+ *
+ * The counterfactual is exact, which is why this is allowed to exist here at all:
+ * caching changes the multiplier on a token, never the token. Had `cache_control`
+ * not been set, the identical prefix would have gone up as ordinary input at 1x.
+ * So `withoutCachingUsd` is not an estimate of a different call — it is the same
+ * call, arithmetic away.
+ *
+ * Worth running per label as well as over the whole log. A profitable cache on one
+ * workload and a bleeding one on another net out to a comfortable-looking total,
+ * and the aggregate is exactly where a loss hides.
+ */
+export declare function cacheEconomics(breakdown: UsageBreakdown): CacheEconomics;
+//# sourceMappingURL=usage.d.ts.map

package/dist/usage.d.ts.map

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