@trazum/core 1.10.0 → 1.25.0

package/dist/reprice.js

@@ -0,0 +1,82 @@
+import { effectivePricing, multipliersFor } from './pricing.js';
+/**
+ * What a set of token counts costs on one model, at the rates in force on a
+ * date.
+ *
+ * The same arithmetic `profileUsage` does per call, over an aggregate — which
+ * is only sound because every token class is priced independently of the
+ * others and of how many calls produced them.
+ */
+export function priceTokensOn(breakdown, model, on = new Date()) {
+    const { inputPerMTok, outputPerMTok } = effectivePricing(model, on);
+    const rates = multipliersFor(model);
+    const per = (tokens, rate) => (tokens / 1_000_000) * rate;
+    return (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));
+}
+/**
+ * Reprices a profile's label-and-model slices onto one target model.
+ *
+ * Returns `null` when the catalogue does not know the target: a comparison
+ * against a price nobody has is worse than no comparison, and the caller is
+ * better placed to say so in its own words than this is to invent a zero.
+ */
+export function repriceProfile(report, targetId, catalogue, on = new Date()) {
+    const target = catalogue.byId.get(targetId);
+    if (!target)
+        return null;
+    const slices = [];
+    const overContext = [];
+    const alreadyOnTarget = { calls: 0, usd: 0 };
+    let assumedWriteTtlCalls = 0;
+    for (const slice of report.byLabelAndModel) {
+        const { breakdown } = slice;
+        if (slice.model === target.id) {
+            alreadyOnTarget.calls += breakdown.calls;
+            alreadyOnTarget.usd += breakdown.totalUsd;
+            continue;
+        }
+        if (breakdown.maxCallInputTokens > target.contextWindow) {
+            overContext.push({
+                label: slice.label,
+                model: slice.model,
+                calls: breakdown.calls,
+                currentUsd: breakdown.totalUsd,
+                maxCallInputTokens: breakdown.maxCallInputTokens,
+            });
+            continue;
+        }
+        const targetUsd = priceTokensOn(breakdown, target, on);
+        assumedWriteTtlCalls += breakdown.assumedWriteTtlCalls;
+        slices.push({
+            label: slice.label,
+            model: slice.model,
+            calls: breakdown.calls,
+            currentUsd: breakdown.totalUsd,
+            targetUsd,
+            deltaUsd: targetUsd - breakdown.totalUsd,
+            maxCallInputTokens: breakdown.maxCallInputTokens,
+        });
+    }
+    slices.sort((a, b) => a.deltaUsd - b.deltaUsd || b.currentUsd - a.currentUsd);
+    overContext.sort((a, b) => b.currentUsd - a.currentUsd);
+    const currentUsd = slices.reduce((sum, s) => sum + s.currentUsd, 0);
+    const targetUsd = slices.reduce((sum, s) => sum + s.targetUsd, 0);
+    return {
+        target: { id: target.id, displayName: target.displayName, contextWindow: target.contextWindow },
+        slices,
+        currentUsd,
+        targetUsd,
+        deltaUsd: targetUsd - currentUsd,
+        overContext,
+        alreadyOnTarget,
+        assumedWriteTtlCalls,
+        unpricedModels: report.unpricedModels,
+        unpricedCalls: report.unpriced.calls,
+        sameTokensAssumed: true,
+    };
+}
+//# sourceMappingURL=reprice.js.map

package/dist/reprice.js.map

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

package/dist/session-cost.d.ts

@@ -0,0 +1,70 @@
+import type { PricingCatalogue } from './pricing.js';
+import type { UsageRecord } from './usage.js';
+/**
+ * What one conversation costs.
+ *
+ * ## The question a total cannot answer
+ *
+ * "Support cost $4,000 last month" does not say whether that is forty thousand
+ * cheap conversations or four hundred expensive ones, and every decision made
+ * on top of it needs the answer: what to charge per seat, where to put a quota,
+ * whether one runaway agent loop is eating the budget. The bill has the data —
+ * the log groups by `session` already — and nothing was reporting it.
+ *
+ * ## Median and p95, not mean
+ *
+ * A mean conversation cost is the total divided by the session count, which is
+ * the total again wearing a hat: one 400-turn agent loop drags it up and hides
+ * the ordinary case. The **median** is the conversation in the middle — what a
+ * typical one costs — and the **p95** is the one a quota has to survive. The
+ * gap between them is the finding: `$0.02 median, $1.80 p95` is a workload with
+ * a tail worth hunting; `$0.40 median, $0.55 p95` is a workload that is simply
+ * expensive, and no amount of tail-hunting will fix it.
+ *
+ * Every figure is **exact** — the provider's own billed counts, summed per
+ * conversation at each model's published rates. No counterfactual, no estimate.
+ *
+ * ## What it refuses to claim
+ *
+ * A conversation that started before this log or continues after it is counted
+ * only for the turns recorded here, so its cost is a floor. That is stated
+ * rather than corrected: guessing at unseen turns would be exactly the kind of
+ * invention this package exists to end. Session keys group turns and never
+ * leave this module, as everywhere the field is touched.
+ */
+export interface SessionCostShape {
+    label: string;
+    model: string;
+    modelName: string;
+    /** Conversations measured. Never which ones. */
+    sessions: number;
+    calls: number;
+    /** What those conversations cost in total — exact, billed. */
+    totalUsd: number;
+    /** The conversation in the middle. */
+    medianUsd: number;
+    /** The conversation a quota has to survive: 95th percentile, by nearest rank. */
+    p95Usd: number;
+    /** The single most expensive conversation in the slice. */
+    maxUsd: number;
+    /** Turns in the median conversation, for scale. */
+    medianTurns: number;
+}
+export interface SessionCostOptions {
+    catalogue: PricingCatalogue;
+    on?: Date;
+    /**
+     * Slices with fewer conversations than this are dropped: a median over three
+     * sessions is not a median, it is one of the three, and a p95 over them is
+     * the maximum wearing a percentile's name. Default 5.
+     */
+    minSessions?: number;
+}
+export interface SessionCostTracker {
+    add(record: UsageRecord): void;
+    finish(): SessionCostShape[];
+}
+export declare function createSessionCostTracker(options: SessionCostOptions): SessionCostTracker;
+/** The same measurement over a list, for a caller holding one already. */
+export declare function sessionCostShapes(records: readonly UsageRecord[], options: SessionCostOptions): SessionCostShape[];
+//# sourceMappingURL=session-cost.d.ts.map

package/dist/session-cost.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-cost.d.ts","sourceRoot":"","sources":["../src/session-cost.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,iFAAiF;IACjF,MAAM,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,gBAAgB,CAAC;IAC5B,EAAE,CAAC,EAAE,IAAI,CAAC;IACV;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,kBAAkB;IACjC,GAAG,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IAC/B,MAAM,IAAI,gBAAgB,EAAE,CAAC;CAC9B;AAgCD,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,kBAAkB,GAAG,kBAAkB,CAwDxF;AAED,0EAA0E;AAC1E,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,SAAS,WAAW,EAAE,EAC/B,OAAO,EAAE,kBAAkB,GAC1B,gBAAgB,EAAE,CAIpB"}

package/dist/session-cost.js

@@ -0,0 +1,90 @@
+import { effectivePricing, multipliersFor } from './pricing.js';
+import { UNLABELLED } from './usage.js';
+/** Every billed dollar of one call, at its own model's rates. */
+function costOf(record, catalogue, on) {
+    const model = catalogue.byId.get(record.model);
+    if (!model)
+        return null;
+    const { inputPerMTok, outputPerMTok } = effectivePricing(model, on);
+    const rates = multipliersFor(model);
+    const per = (tokens, rate) => (tokens / 1_000_000) * rate;
+    return (per(record.inputTokens, inputPerMTok) +
+        per(record.cacheReadTokens, inputPerMTok * rates.cacheRead) +
+        per(record.cacheWrite5mTokens, inputPerMTok * rates.cacheWrite5m) +
+        per(record.cacheWrite1hTokens, inputPerMTok * rates.cacheWrite1h) +
+        per(record.outputTokens, outputPerMTok));
+}
+const median = (sorted) => {
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 1 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+};
+/**
+ * The 95th percentile by **nearest rank**: the smallest value at or above which
+ * 95% of the conversations sit. Interpolating between two conversations would
+ * report a cost no conversation had, and this figure exists to be compared
+ * against a real quota.
+ */
+const p95 = (sorted) => sorted[Math.min(sorted.length - 1, Math.ceil(sorted.length * 0.95) - 1)];
+export function createSessionCostTracker(options) {
+    const { catalogue, on = new Date(), minSessions = 5 } = options;
+    const slices = new Map();
+    const add = (record) => {
+        if (record.session === null)
+            return;
+        const cost = costOf(record, catalogue, on);
+        // An unpriced model contributes no dollars anywhere else either.
+        if (cost === null)
+            return;
+        const sliceKey = `${record.label ?? UNLABELLED}\n${record.model}`;
+        let sessions = slices.get(sliceKey);
+        if (!sessions) {
+            sessions = new Map();
+            slices.set(sliceKey, sessions);
+        }
+        const existing = sessions.get(record.session);
+        if (existing) {
+            existing.usd += cost;
+            existing.turns += 1;
+        }
+        else {
+            sessions.set(record.session, { usd: cost, turns: 1 });
+        }
+    };
+    const finish = () => {
+        const out = [];
+        for (const [sliceKey, sessions] of slices) {
+            if (sessions.size < minSessions)
+                continue;
+            const split = sliceKey.indexOf('\n');
+            const modelId = sliceKey.slice(split + 1);
+            const model = catalogue.byId.get(modelId);
+            if (!model)
+                continue;
+            const costs = [...sessions.values()].map((s) => s.usd).sort((a, b) => a - b);
+            const turns = [...sessions.values()].map((s) => s.turns).sort((a, b) => a - b);
+            out.push({
+                label: sliceKey.slice(0, split),
+                model: modelId,
+                modelName: model.displayName,
+                sessions: sessions.size,
+                calls: turns.reduce((sum, t) => sum + t, 0),
+                totalUsd: costs.reduce((sum, c) => sum + c, 0),
+                medianUsd: median(costs),
+                p95Usd: p95(costs),
+                maxUsd: costs[costs.length - 1],
+                medianTurns: median(turns),
+            });
+        }
+        // The most money first — the order somebody would act in.
+        return out.sort((a, b) => b.totalUsd - a.totalUsd || a.label.localeCompare(b.label));
+    };
+    return { add, finish };
+}
+/** The same measurement over a list, for a caller holding one already. */
+export function sessionCostShapes(records, options) {
+    const tracker = createSessionCostTracker(options);
+    for (const record of records)
+        tracker.add(record);
+    return tracker.finish();
+}
+//# sourceMappingURL=session-cost.js.map

package/dist/session-cost.js.map

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

package/dist/session-ledger.d.ts

@@ -0,0 +1,77 @@
+import type { PricingCatalogue } from './pricing.js';
+import type { UsageRecord } from './usage.js';
+/**
+ * Cache writes made by conversations that never came back.
+ *
+ * ## The waste the aggregate hides
+ *
+ * A cache write is a bet: pay 1.25x input now (2x at the 1-hour TTL) so the
+ * *next* call reads the prefix at 0.1x. A conversation that ends after its
+ * first turn never places that next call — its write bought reuse that its own
+ * conversation never made. On a workload with many short sessions this is a
+ * steady leak, and it hides inside healthy-looking totals: the long sessions'
+ * reads pay for the cache overall, so `cacheEconomics` reports `paid-off`
+ * while every one-turn drive-by pays the premium for nothing.
+ *
+ * ## The caveat that keeps the figure honest
+ *
+ * The provider's cache is keyed by prefix content, not by conversation. A
+ * one-turn session's write **can** be read back by a different session that
+ * sends the same prefix within the TTL — a shared system prompt does exactly
+ * that — and a usage log cannot see whose write a read hit. So the figure
+ * reported here is a **ceiling, named as one**: these writes paid off only if
+ * another conversation shared the prefix in time, and the log cannot say
+ * whether one did.
+ *
+ * There is one case where the ceiling collapses into a fact, and the caller
+ * can detect it from the slice it already has: when the slice recorded **zero
+ * cache reads**, nothing read those writes — within the session, across
+ * sessions, at all. The row deliberately does not decide this itself; the
+ * breakdown holding the slice's reads belongs to the caller, and deriving it
+ * twice is how two figures drift.
+ *
+ * Session keys group turns and never leave this module, like everywhere else
+ * the field is touched.
+ */
+export interface SingleTurnCacheWrites {
+    label: string;
+    model: string;
+    modelName: string;
+    /** Conversations seen in this slice — with a session key, priced model. */
+    sessions: number;
+    /** Median turns per conversation, for scale: 1-turn sessions in a sea of 40-turn ones read differently than in a sea of 2s. */
+    medianTurns: number;
+    /** Conversations that ended after exactly one recorded turn. */
+    singleTurnSessions: number;
+    /** Cache-write tokens those one-turn conversations paid for. */
+    singleTurnWriteTokens: number;
+    /**
+     * What those writes cost, at the same rates the bill used — the 5-minute
+     * rate for writes whose TTL the log did not state, so like the bill it is
+     * a floor when `assumedTtlTokens` is non-zero. A **ceiling on the waste**
+     * (another conversation may have read the prefix; the log cannot see it)
+     * built on a **floor of a price** — both directions named, neither guessed.
+     */
+    singleTurnWriteUsd: number;
+    /** The part of `singleTurnWriteTokens` whose TTL the log did not record. */
+    assumedTtlTokens: number;
+}
+export interface SessionLedgerOptions {
+    catalogue: PricingCatalogue;
+    /** Date the prices are read at, so a promotional rate resolves the same way. */
+    on?: Date;
+}
+export interface SessionLedgerTracker {
+    add(record: UsageRecord): void;
+    finish(): SingleTurnCacheWrites[];
+}
+/**
+ * An accumulator, like the TTL-fit tracker and for the same reason: one pass
+ * over a log measured in megabytes, holding one small tally per conversation.
+ * No timestamp needed — "came back" is a fact about turn count, not the clock,
+ * so this measures logs the TTL-fit cannot.
+ */
+export declare function createSessionLedgerTracker(options: SessionLedgerOptions): SessionLedgerTracker;
+/** The same measurement over a list, for a caller holding one already. */
+export declare function singleTurnCacheWrites(records: readonly UsageRecord[], options: SessionLedgerOptions): SingleTurnCacheWrites[];
+//# sourceMappingURL=session-ledger.d.ts.map

package/dist/session-ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-ledger.d.ts","sourceRoot":"","sources":["../src/session-ledger.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC;IACjB,+HAA+H;IAC/H,WAAW,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gEAAgE;IAChE,qBAAqB,EAAE,MAAM,CAAC;IAC9B;;;;;;OAMG;IACH,kBAAkB,EAAE,MAAM,CAAC;IAC3B,4EAA4E;IAC5E,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,gBAAgB,CAAC;IAC5B,gFAAgF;IAChF,EAAE,CAAC,EAAE,IAAI,CAAC;CACX;AAED,MAAM,WAAW,oBAAoB;IACnC,GAAG,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IAC/B,MAAM,IAAI,qBAAqB,EAAE,CAAC;CACnC;AAcD;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,oBAAoB,GAAG,oBAAoB,CAsF9F;AAED,0EAA0E;AAC1E,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,SAAS,WAAW,EAAE,EAC/B,OAAO,EAAE,oBAAoB,GAC5B,qBAAqB,EAAE,CAIzB"}

package/dist/session-ledger.js

@@ -0,0 +1,99 @@
+import { effectivePricing, multipliersFor } from './pricing.js';
+import { UNLABELLED } from './usage.js';
+const median = (sorted) => {
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 1 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+};
+/**
+ * An accumulator, like the TTL-fit tracker and for the same reason: one pass
+ * over a log measured in megabytes, holding one small tally per conversation.
+ * No timestamp needed — "came back" is a fact about turn count, not the clock,
+ * so this measures logs the TTL-fit cannot.
+ */
+export function createSessionLedgerTracker(options) {
+    const { catalogue, on = new Date() } = options;
+    const slices = new Map();
+    const add = (record) => {
+        // An unpriced model has no rate to price the waste at, and contributes no
+        // dollars anywhere else either.
+        if (record.session === null || !catalogue.byId.has(record.model))
+            return;
+        const key = `${record.label ?? UNLABELLED}\n${record.model}`;
+        let sessions = slices.get(key);
+        if (!sessions) {
+            sessions = new Map();
+            slices.set(key, sessions);
+        }
+        let tally = sessions.get(record.session);
+        if (!tally) {
+            tally = { turns: 0, write5mTokens: 0, write1hTokens: 0, assumedTokens: 0 };
+            sessions.set(record.session, tally);
+        }
+        tally.turns += 1;
+        if (record.writeTtlKnown) {
+            tally.write5mTokens += record.cacheWrite5mTokens;
+            tally.write1hTokens += record.cacheWrite1hTokens;
+        }
+        else {
+            // The flat count sits in the 5m bucket by pricing convention; kept
+            // apart here so the row can say how much of its price is a floor.
+            tally.assumedTokens += record.cacheWrite5mTokens;
+        }
+    };
+    const finish = () => {
+        const out = [];
+        for (const [key, sessions] of slices) {
+            let singleTurnSessions = 0;
+            let write5m = 0;
+            let write1h = 0;
+            let assumed = 0;
+            const turnCounts = [];
+            for (const tally of sessions.values()) {
+                turnCounts.push(tally.turns);
+                if (tally.turns !== 1)
+                    continue;
+                singleTurnSessions += 1;
+                write5m += tally.write5mTokens;
+                write1h += tally.write1hTokens;
+                assumed += tally.assumedTokens;
+            }
+            const singleTurnWriteTokens = write5m + write1h + assumed;
+            // One-turn conversations that wrote nothing wasted nothing; a row about
+            // them would be a finding about the absence of a finding.
+            if (singleTurnWriteTokens === 0)
+                continue;
+            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, rate) => (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({
+                label: key.slice(0, split),
+                model: modelId,
+                modelName: model.displayName,
+                sessions: sessions.size,
+                medianTurns: median(turnCounts),
+                singleTurnSessions,
+                singleTurnWriteTokens,
+                singleTurnWriteUsd,
+                assumedTtlTokens: assumed,
+            });
+        }
+        // The most money first — the order somebody would act in.
+        return out.sort((a, b) => b.singleTurnWriteUsd - a.singleTurnWriteUsd || a.label.localeCompare(b.label));
+    };
+    return { add, finish };
+}
+/** The same measurement over a list, for a caller holding one already. */
+export function singleTurnCacheWrites(records, options) {
+    const tracker = createSessionLedgerTracker(options);
+    for (const record of records)
+        tracker.add(record);
+    return tracker.finish();
+}
+//# sourceMappingURL=session-ledger.js.map

package/dist/session-ledger.js.map

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

package/dist/ttl-fit.d.ts

@@ -0,0 +1,103 @@
+import type { PricingCatalogue } from './pricing.js';
+import type { UsageRecord } from './usage.js';
+/**
+ * Does the cache TTL fit how fast the turns actually arrive?
+ *
+ * ## The mechanism nothing else can see
+ *
+ * A cache entry lives 5 minutes, or an hour at twice the write price. Whether
+ * either is the right choice depends on one number the bill never shows: **how
+ * long the workload waits between turns.** A support agent whose users answer in
+ * nine minutes writes a 5-minute entry on every turn and reads it back on none of
+ * them — every write expires unread, which from the bill is indistinguishable
+ * from any other losing cache. `cacheEconomics` can say *that* money was lost;
+ * only the clock can say *why*, and the why decides the fix: the 1-hour TTL, or
+ * caching switched off.
+ *
+ * The opposite mistake is quieter and this is the only place it appears at all:
+ * turns arriving seconds apart, written at the 1-hour rate. Those writes work —
+ * the verdict above reads `paid-off` — and every one of them pays 2x input for
+ * endurance the workload never uses. **Switching them to the 5-minute TTL is the
+ * one exact saving in this module**: the same tokens at 1.25x instead of 2x,
+ * which is the same-tokens-different-rate arithmetic `cacheEconomics` already
+ * draws the counterfactual line at.
+ *
+ * ## What it measures, and how it stays honest
+ *
+ * The gap between consecutive turns **of the same conversation**, from the
+ * recorded clock — sessions are what a cache entry actually serves, and gaps
+ * between unrelated calls of a label say nothing about whether *this*
+ * conversation's next turn found the entry alive. Timestamps are sorted within
+ * each session before differencing, so the measurement is independent of the
+ * order of the log — the property the conversation tracker had to learn the
+ * hard way.
+ *
+ * The reported number is the **median** gap, named as such: a median survives
+ * the overnight gap between a user's Tuesday and Wednesday in a way a mean does
+ * not, and a verdict hung on a mean would flip on one lunch break.
+ *
+ * When the log did not record which TTL the writes used, the gap can sit where
+ * the verdict depends on the answer — over 5 minutes and under an hour survives
+ * one TTL and not the other. That is reported as `unsettled`, the same refusal
+ * `cacheEconomics` makes for the same missing field, and never resolved in the
+ * flattering direction.
+ *
+ * The session key is used to group turns and never leaves this module, like
+ * everywhere else the field is touched.
+ */
+/** Cache-entry lifetimes, in milliseconds. Anthropic's two published TTLs. */
+export declare const TTL_5M_MS: number;
+export declare const TTL_1H_MS: number;
+export type TtlFitVerdict = 
+/** The median gap outlives the entry: writes expire before the next turn. */
+'expires-before-reuse'
+/** 1-hour writes on gaps inside the 5-minute window: paying 2x for nothing. */
+ | 'overlong-ttl'
+/** The TTL the log did not record decides the verdict, so nothing does. */
+ | 'unsettled'
+/** The entry outlives the gap at the TTL the writes actually used. */
+ | 'fits';
+export interface CacheTtlFit {
+    label: string;
+    model: string;
+    modelName: string;
+    /** Conversations with at least two timestamped turns. Never which ones. */
+    sessions: number;
+    /** Gaps measured across them. */
+    gaps: number;
+    medianGapMs: number;
+    /** Write tokens the log said were 5-minute entries. */
+    write5mTokens: number;
+    /** Write tokens the log said were 1-hour entries. */
+    write1hTokens: number;
+    /** Write tokens whose TTL the log did not record. */
+    assumedTtlTokens: number;
+    verdict: TtlFitVerdict;
+    /**
+     * 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,
+     * at the model's own input rate — and zero for every other verdict.
+     */
+    overpayUsd: number;
+}
+export interface TtlFitOptions {
+    catalogue: PricingCatalogue;
+    /** Date the prices are read at, so a promotional rate resolves the same way. */
+    on?: Date;
+}
+export interface TtlFitTracker {
+    /** Feed one parsed record. */
+    add(record: UsageRecord): void;
+    /** The finished measurement. */
+    finish(): CacheTtlFit[];
+}
+/**
+ * An accumulator, like the conversation tracker and for the same reason: a
+ * usage log is measured in megabytes and `profileUsage` makes one pass. What
+ * this holds is one number per timestamped call that belongs to a session,
+ * which is the minimum the gaps can be computed from at all.
+ */
+export declare function createTtlFitTracker(options: TtlFitOptions): TtlFitTracker;
+/** The same measurement over a list, for a caller holding one already. */
+export declare function cacheTtlFit(records: readonly UsageRecord[], options: TtlFitOptions): CacheTtlFit[];
+//# sourceMappingURL=ttl-fit.d.ts.map

package/dist/ttl-fit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ttl-fit.d.ts","sourceRoot":"","sources":["../src/ttl-fit.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,8EAA8E;AAC9E,eAAO,MAAM,SAAS,QAAgB,CAAC;AACvC,eAAO,MAAM,SAAS,QAAiB,CAAC;AAExC,MAAM,MAAM,aAAa;AACvB,6EAA6E;AAC3E,sBAAsB;AACxB,+EAA+E;GAC7E,cAAc;AAChB,2EAA2E;GACzE,WAAW;AACb,sEAAsE;GACpE,MAAM,CAAC;AAEX,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,aAAa,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,aAAa,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,aAAa,CAAC;IACvB;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,gBAAgB,CAAC;IAC5B,gFAAgF;IAChF,EAAE,CAAC,EAAE,IAAI,CAAC;CACX;AAED,MAAM,WAAW,aAAa;IAC5B,8BAA8B;IAC9B,GAAG,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IAC/B,gCAAgC;IAChC,MAAM,IAAI,WAAW,EAAE,CAAC;CACzB;AAeD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,aAAa,GAAG,aAAa,CAuHzE;AAED,0EAA0E;AAC1E,wBAAgB,WAAW,CACzB,OAAO,EAAE,SAAS,WAAW,EAAE,EAC/B,OAAO,EAAE,aAAa,GACrB,WAAW,EAAE,CAIf"}