@trazum/core 1.40.0 → 1.41.0

package/README.md

@@ -132,6 +132,21 @@ the caller names the file instead of absorbing it. No forecasts anywhere:
 shapes are stated with their first and last values, and where they go next
 is the reader's.
 
+## The bill, from the provider
+
+`normalizeAnthropicUsage(payload)` and `normalizeOpenAIUsage(payload)` turn a
+usage API response into `UsageBucket`s — token sums per window and model, with
+the two cache-write TTLs kept apart and a request count only where the
+provider actually serves one (`null` otherwise, never zero).
+`bucketedProfile(pull, { catalogue })` prices them, and
+`bucketedCacheEconomics(report)` runs the same counterfactual `cacheEconomics`
+runs per call. The result is deliberately its own shape rather than a
+`UsageProfileReport` with holes in it, so no per-call finding can read a zero
+this module wrote: every finding a sum cannot support is listed in
+`unavailable` with why and what would unlock it. Anything unreadable in the
+payload becomes a named `PullGap`, never a default of zero. Pure and
+browser-safe — the fetch, the credentials and the pagination live in the CLI.
+
 ## Comparing two versions
 
 ```ts

package/dist/connector.d.ts

@@ -0,0 +1,227 @@
+/**
+ * Your bill, read from the provider, without anybody exporting anything.
+ *
+ * Every command in this product reads a file somebody produced by hand, and
+ * the export step is where adoption dies: the person who would benefit most
+ * from a cost report is the person least likely to have a `usage.jsonl` lying
+ * around. Every provider that bills by the token also serves that data over an
+ * API, and this module turns those payloads into figures the rest of Trazum
+ * already knows how to reason about.
+ *
+ * **Pure, and in the core, so it is testable without a network.** The fetch,
+ * the credentials and the pagination live in the CLI — the same split
+ * `openrouterOverlay` has had since 1.13. Everything here is a transformation
+ * of a document the caller already holds.
+ *
+ * **The honest part is what the providers cannot tell you.** Usage APIs serve
+ * *aggregates*: tokens per bucket per model, and — depending on the provider —
+ * a request count or nothing at all. They do not serve per-call rows. That
+ * makes a whole class of Trazum's findings impossible on this source: the
+ * shape of the calls, the truncation retries, the conversations, the largest
+ * call's context pressure. Those findings need per-call data and no amount of
+ * arithmetic recovers them from a sum.
+ *
+ * So a connected report is a **restricted** report, and it is restricted out
+ * loud. It carries its own shape rather than a `UsageProfileReport` with holes
+ * in it, precisely so a per-call finding can never read a zero this module
+ * wrote and report "nothing found" about something nobody measured. Not
+ * recorded is not not-happened, at the level of the type system.
+ */
+import type { PricingCatalogue } from './pricing.js';
+/**
+ * `per-call` sources serve one row per request and unlock every finding in
+ * the product. `bucketed` sources serve sums over a window.
+ */
+export type ConnectorGranularity = 'per-call' | 'bucketed';
+/**
+ * A finding this source cannot support, why, and what would unlock it.
+ *
+ * Carried into the report and printed there. A restricted report that only
+ * omits things reads as a report that found nothing wrong.
+ */
+export interface UnavailableFinding {
+    finding: string;
+    because: string;
+    unlockedBy: string;
+}
+export interface ConnectorDescriptor {
+    id: string;
+    displayName: string;
+    granularity: ConnectorGranularity;
+    /**
+     * Environment variables the CLI reads the credential from, in order.
+     *
+     * Named here so `trazum connect` can say exactly what it looked for when it
+     * finds nothing. Trazum stores no secret: a key lives in the environment or
+     * in a keychain the operating system owns, and never in this repository's
+     * config, cache or output.
+     */
+    credentialEnv: readonly string[];
+    /** The narrowest key that works, so nobody hands this tool a wider one. */
+    keyKind: string;
+    /** Whether the source serves a request count, or only token sums. */
+    servesCallCounts: boolean;
+    /** Findings impossible on this source. */
+    unavailable: readonly UnavailableFinding[];
+    docs: string;
+}
+/**
+ * The two providers this release connects to, and the asymmetry between them
+ * that a report must not paper over.
+ *
+ * OpenAI's usage endpoint serves a request count per bucket; Anthropic's
+ * serves token sums without one. So a connected OpenAI report can say "$412
+ * over 9,004 calls" and a connected Anthropic report can only say "$412", and
+ * every per-call average is available on one and absent on the other. Printing
+ * a call count of zero, or dividing by a denominator that does not exist,
+ * would be this module inventing the number it is here to stop inventing.
+ */
+export declare const CONNECTORS: readonly ConnectorDescriptor[];
+export declare function connectorFor(id: string): ConnectorDescriptor | null;
+/**
+ * One provider bucket: a window, a model, and the tokens billed inside it.
+ *
+ * The cache-write TTL split is kept apart for the same reason `UsageBreakdown`
+ * keeps it apart — the two are billed at different multipliers, and a total
+ * that has lost the split cannot be repriced, only guessed at.
+ */
+export interface UsageBucket {
+    fromMs: number;
+    toMs: number;
+    model: string;
+    /** null when the provider serves no request count. Never zero for absent. */
+    calls: number | null;
+    inputTokens: number;
+    cacheReadTokens: number;
+    cacheWrite5mTokens: number;
+    cacheWrite1hTokens: number;
+    /** False when the provider reported writes without saying which TTL. */
+    writeTtlKnown: boolean;
+    outputTokens: number;
+    /** Whatever the provider grouped by beyond the model — workspace, key, tier. */
+    group: Record<string, string>;
+}
+/**
+ * Something the pull did not get.
+ *
+ * A bill quietly short by an unknown amount is the failure this repository
+ * refuses everywhere it can occur, and a paginated API behind a rate limit is
+ * exactly where it occurs. Every gap is carried to the report and printed.
+ */
+export interface PullGap {
+    kind: 'rate-limited' | 'retention-boundary' | 'cursor-expired' | 'page-limit' | 'unreadable-entry' | 'unreadable-field';
+    detail: string;
+}
+export interface ConnectorPull {
+    provider: string;
+    granularity: ConnectorGranularity;
+    buckets: UsageBucket[];
+    /** The window the buckets actually cover, or null when none parsed. */
+    window: {
+        fromMs: number;
+        toMs: number;
+    } | null;
+    gaps: PullGap[];
+    unavailable: readonly UnavailableFinding[];
+}
+/**
+ * Anthropic's messages usage report.
+ *
+ * Shape: `{ data: [ { starting_at, ending_at, results: [ {...tokens, model} ] } ] }`.
+ * The fields read are the documented ones; anything unreadable is reported as
+ * a gap rather than defaulted to zero, because a zero here is a bill that is
+ * quietly smaller than the real one.
+ */
+export declare function normalizeAnthropicUsage(payload: unknown): ConnectorPull;
+/**
+ * OpenAI's completions usage endpoint.
+ *
+ * Shape: `{ data: [ { start_time, end_time, results: [ { input_tokens,
+ * output_tokens, input_cached_tokens, num_model_requests, model } ] } ] }`.
+ *
+ * This one serves a request count, so every per-call average is available on
+ * it — and the report says so, rather than making both providers look alike.
+ */
+export declare function normalizeOpenAIUsage(payload: unknown): ConnectorPull;
+export interface BucketedSlice {
+    model: string;
+    /** null when the source serves no request count. */
+    calls: number | null;
+    inputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    outputTokens: number;
+    inputUsd: number;
+    cacheReadUsd: number;
+    cacheWriteUsd: number;
+    outputUsd: number;
+    totalUsd: number;
+    /** What the cache-touched tokens would have cost as ordinary input. */
+    cachedTokensAtInputRateUsd: number;
+    /** Writes priced at the 1-hour rate, when the source did not state the TTL. */
+    cacheWriteUsdIfAssumed1h: number;
+    writeTtlKnown: boolean;
+}
+export interface BucketedReport {
+    schemaVersion: 1;
+    provider: string;
+    granularity: ConnectorGranularity;
+    span: {
+        fromMs: number;
+        toMs: number;
+    } | null;
+    total: {
+        totalUsd: number;
+        /** null when unknown — never zero, which would read as "no traffic". */
+        calls: number | null;
+        inputTokens: number;
+        cacheReadTokens: number;
+        cacheWriteTokens: number;
+        outputTokens: number;
+    };
+    byModel: BucketedSlice[];
+    /** Spend per UTC day, oldest first — the shape a total hides. */
+    byDay: {
+        day: string;
+        usd: number;
+        calls: number | null;
+    }[];
+    /** Models the catalogue could not price: named, with their tokens kept. */
+    unpricedModels: {
+        model: string;
+        inputTokens: number;
+        outputTokens: number;
+    }[];
+    gaps: PullGap[];
+    unavailable: readonly UnavailableFinding[];
+}
+/**
+ * Prices the buckets a connector pulled.
+ *
+ * Every figure here is the provider's own billed token count at the
+ * catalogue's rates — the same arithmetic `profile` does, over sums instead of
+ * rows. What it deliberately does not do is synthesise the per-call findings:
+ * they are listed as unavailable and left absent, so nothing downstream can
+ * read a zero this function wrote.
+ */
+export declare function bucketedProfile(pull: ConnectorPull, options: {
+    catalogue: PricingCatalogue;
+    on?: Date;
+}): BucketedReport;
+/**
+ * The cache verdict over a connected report.
+ *
+ * Same counterfactual `cacheEconomics` runs on a per-call report: what the
+ * cache-touched tokens cost, against what they would have cost as ordinary
+ * input. The worst case is carried separately for the same reason it is
+ * there — when the source did not state the write TTL, the cheaper rate was
+ * assumed for the headline and the verdict can move under the other one.
+ */
+export declare function bucketedCacheEconomics(report: BucketedReport): {
+    spentUsd: number;
+    withoutCachingUsd: number;
+    deltaUsd: number;
+    verdict: 'paid-off' | 'lost-money' | 'no-cache';
+    worstCaseVerdict: 'paid-off' | 'lost-money' | 'no-cache';
+};
+//# sourceMappingURL=connector.d.ts.map

package/dist/connector.d.ts.map

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

package/dist/connector.js

@@ -0,0 +1,431 @@
+/**
+ * Your bill, read from the provider, without anybody exporting anything.
+ *
+ * Every command in this product reads a file somebody produced by hand, and
+ * the export step is where adoption dies: the person who would benefit most
+ * from a cost report is the person least likely to have a `usage.jsonl` lying
+ * around. Every provider that bills by the token also serves that data over an
+ * API, and this module turns those payloads into figures the rest of Trazum
+ * already knows how to reason about.
+ *
+ * **Pure, and in the core, so it is testable without a network.** The fetch,
+ * the credentials and the pagination live in the CLI — the same split
+ * `openrouterOverlay` has had since 1.13. Everything here is a transformation
+ * of a document the caller already holds.
+ *
+ * **The honest part is what the providers cannot tell you.** Usage APIs serve
+ * *aggregates*: tokens per bucket per model, and — depending on the provider —
+ * a request count or nothing at all. They do not serve per-call rows. That
+ * makes a whole class of Trazum's findings impossible on this source: the
+ * shape of the calls, the truncation retries, the conversations, the largest
+ * call's context pressure. Those findings need per-call data and no amount of
+ * arithmetic recovers them from a sum.
+ *
+ * So a connected report is a **restricted** report, and it is restricted out
+ * loud. It carries its own shape rather than a `UsageProfileReport` with holes
+ * in it, precisely so a per-call finding can never read a zero this module
+ * wrote and report "nothing found" about something nobody measured. Not
+ * recorded is not not-happened, at the level of the type system.
+ */
+import { effectivePricing, multipliersFor } from './pricing.js';
+/** Every finding that needs a row per call, named once. */
+const PER_CALL_FINDINGS = [
+    {
+        finding: 'inputShapes',
+        because: 'the provider serves sums over a window, and the spread of call sizes is not in a sum',
+        unlockedBy: 'a per-call usage log, or the gateway',
+    },
+    {
+        finding: 'truncationRetries',
+        because: 'pairing a truncated answer with its retry needs both calls, their order and their stop reasons',
+        unlockedBy: 'a per-call usage log recording stop_reason and session',
+    },
+    {
+        finding: 'repeatedTurns',
+        because: 'the same request sent twice is invisible once both are added together',
+        unlockedBy: 'a per-call usage log recording session',
+    },
+    {
+        finding: 'sessionCosts',
+        because: 'conversations are not a dimension any usage API groups by',
+        unlockedBy: 'a per-call usage log recording session',
+    },
+    {
+        finding: 'contextPressure',
+        because: 'it reads the largest single call, and a total has lost the maximum',
+        unlockedBy: 'a per-call usage log, or the gateway',
+    },
+    {
+        finding: 'duplicateLines',
+        because: 'a doubled bill is caught by finding identical rows, and there are no rows here',
+        unlockedBy: 'a per-call usage log',
+    },
+];
+/**
+ * The two providers this release connects to, and the asymmetry between them
+ * that a report must not paper over.
+ *
+ * OpenAI's usage endpoint serves a request count per bucket; Anthropic's
+ * serves token sums without one. So a connected OpenAI report can say "$412
+ * over 9,004 calls" and a connected Anthropic report can only say "$412", and
+ * every per-call average is available on one and absent on the other. Printing
+ * a call count of zero, or dividing by a denominator that does not exist,
+ * would be this module inventing the number it is here to stop inventing.
+ */
+export const CONNECTORS = [
+    {
+        id: 'anthropic',
+        displayName: 'Anthropic',
+        granularity: 'bucketed',
+        credentialEnv: ['TRAZUM_ANTHROPIC_ADMIN_KEY', 'ANTHROPIC_ADMIN_KEY'],
+        keyKind: 'an Admin API key (read access to the usage report)',
+        servesCallCounts: false,
+        unavailable: [
+            ...PER_CALL_FINDINGS,
+            {
+                finding: 'calls',
+                because: 'the usage report serves token sums per bucket and no request count',
+                unlockedBy: 'a per-call usage log, or the gateway',
+            },
+        ],
+        docs: 'https://docs.anthropic.com/en/api/admin-api/usage-cost/get-messages-usage-report',
+    },
+    {
+        id: 'openai',
+        displayName: 'OpenAI',
+        granularity: 'bucketed',
+        credentialEnv: ['TRAZUM_OPENAI_ADMIN_KEY', 'OPENAI_ADMIN_KEY'],
+        keyKind: 'an Admin key with the api.usage.read scope',
+        servesCallCounts: true,
+        unavailable: PER_CALL_FINDINGS,
+        docs: 'https://platform.openai.com/docs/api-reference/usage',
+    },
+];
+export function connectorFor(id) {
+    return CONNECTORS.find((c) => c.id === id) ?? null;
+}
+// --------------------------------------------------------------------------
+// Normalising provider payloads
+// --------------------------------------------------------------------------
+const num = (value) => typeof value === 'number' && Number.isFinite(value) ? value : null;
+const ms = (value) => {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value * 1000;
+    if (typeof value !== 'string')
+        return null;
+    const parsed = Date.parse(value);
+    return Number.isNaN(parsed) ? null : parsed;
+};
+/** Merges buckets that share a window, model and grouping. */
+function collect(buckets) {
+    const merged = new Map();
+    for (const bucket of buckets) {
+        const key = `${bucket.fromMs}\n${bucket.toMs}\n${bucket.model}\n${JSON.stringify(bucket.group)}`;
+        const seen = merged.get(key);
+        if (seen === undefined) {
+            merged.set(key, { ...bucket });
+            continue;
+        }
+        seen.inputTokens += bucket.inputTokens;
+        seen.cacheReadTokens += bucket.cacheReadTokens;
+        seen.cacheWrite5mTokens += bucket.cacheWrite5mTokens;
+        seen.cacheWrite1hTokens += bucket.cacheWrite1hTokens;
+        seen.outputTokens += bucket.outputTokens;
+        seen.writeTtlKnown = seen.writeTtlKnown && bucket.writeTtlKnown;
+        // A count merged with an absent count is still absent: adding a number to
+        // "unknown" produces a number that describes only part of the traffic.
+        seen.calls = seen.calls === null || bucket.calls === null ? null : seen.calls + bucket.calls;
+    }
+    return [...merged.values()].sort((a, b) => a.fromMs - b.fromMs || a.model.localeCompare(b.model));
+}
+function windowOf(buckets) {
+    if (buckets.length === 0)
+        return null;
+    return {
+        fromMs: Math.min(...buckets.map((b) => b.fromMs)),
+        toMs: Math.max(...buckets.map((b) => b.toMs)),
+    };
+}
+/**
+ * Anthropic's messages usage report.
+ *
+ * Shape: `{ data: [ { starting_at, ending_at, results: [ {...tokens, model} ] } ] }`.
+ * The fields read are the documented ones; anything unreadable is reported as
+ * a gap rather than defaulted to zero, because a zero here is a bill that is
+ * quietly smaller than the real one.
+ */
+export function normalizeAnthropicUsage(payload) {
+    const descriptor = connectorFor('anthropic');
+    const gaps = [];
+    const buckets = [];
+    const data = payload?.data;
+    if (!Array.isArray(data)) {
+        throw new Error('This payload has no "data" array — is it the response from the Anthropic usage report endpoint?');
+    }
+    for (const [index, entry] of data.entries()) {
+        const row = entry;
+        const fromMs = ms(row.starting_at);
+        const toMs = ms(row.ending_at) ?? (fromMs === null ? null : fromMs);
+        if (fromMs === null || toMs === null) {
+            gaps.push({
+                kind: 'unreadable-entry',
+                detail: `bucket ${index} has no readable time window, so its tokens are in no period and were left out`,
+            });
+            continue;
+        }
+        const results = Array.isArray(row.results) ? row.results : [];
+        if (results.length === 0 && row.results !== undefined && !Array.isArray(row.results)) {
+            gaps.push({ kind: 'unreadable-entry', detail: `bucket ${index} has an unreadable "results" field` });
+            continue;
+        }
+        for (const result of results) {
+            const r = result;
+            const model = typeof r.model === 'string' ? r.model : null;
+            if (model === null) {
+                gaps.push({
+                    kind: 'unreadable-entry',
+                    detail: `a result in bucket ${index} names no model, so its tokens could not be priced and were left out`,
+                });
+                continue;
+            }
+            const creation = (r.cache_creation ?? {});
+            const write5m = num(creation.ephemeral_5m_input_tokens) ?? 0;
+            const write1h = num(creation.ephemeral_1h_input_tokens) ?? 0;
+            const flatWrite = num(r.cache_creation_input_tokens) ?? 0;
+            const ttlKnown = !(flatWrite > 0 && write5m === 0 && write1h === 0);
+            buckets.push({
+                fromMs,
+                toMs,
+                model,
+                // Documented and deliberate: the usage report has no request count.
+                calls: null,
+                inputTokens: num(r.uncached_input_tokens) ?? num(r.input_tokens) ?? 0,
+                cacheReadTokens: num(r.cache_read_input_tokens) ?? 0,
+                cacheWrite5mTokens: ttlKnown ? write5m : flatWrite,
+                cacheWrite1hTokens: ttlKnown ? write1h : 0,
+                writeTtlKnown: ttlKnown,
+                outputTokens: num(r.output_tokens) ?? 0,
+                group: groupOf(r, ['workspace_id', 'api_key_id', 'service_tier', 'context_window']),
+            });
+        }
+    }
+    const merged = collect(buckets);
+    return {
+        provider: 'anthropic',
+        granularity: 'bucketed',
+        buckets: merged,
+        window: windowOf(merged),
+        gaps,
+        unavailable: descriptor.unavailable,
+    };
+}
+/**
+ * OpenAI's completions usage endpoint.
+ *
+ * Shape: `{ data: [ { start_time, end_time, results: [ { input_tokens,
+ * output_tokens, input_cached_tokens, num_model_requests, model } ] } ] }`.
+ *
+ * This one serves a request count, so every per-call average is available on
+ * it — and the report says so, rather than making both providers look alike.
+ */
+export function normalizeOpenAIUsage(payload) {
+    const descriptor = connectorFor('openai');
+    const gaps = [];
+    const buckets = [];
+    const data = payload?.data;
+    if (!Array.isArray(data)) {
+        throw new Error('This payload has no "data" array — is it the response from the OpenAI usage endpoint?');
+    }
+    for (const [index, entry] of data.entries()) {
+        const row = entry;
+        const fromMs = ms(row.start_time);
+        const toMs = ms(row.end_time) ?? (fromMs === null ? null : fromMs);
+        if (fromMs === null || toMs === null) {
+            gaps.push({
+                kind: 'unreadable-entry',
+                detail: `bucket ${index} has no readable time window, so its tokens are in no period and were left out`,
+            });
+            continue;
+        }
+        const results = Array.isArray(row.results) ? row.results : [];
+        for (const result of results) {
+            const r = result;
+            const model = typeof r.model === 'string' ? r.model : null;
+            if (model === null) {
+                gaps.push({
+                    kind: 'unreadable-entry',
+                    detail: `a result in bucket ${index} names no model, so its tokens could not be priced and were left out`,
+                });
+                continue;
+            }
+            const cached = num(r.input_cached_tokens) ?? 0;
+            const input = num(r.input_tokens) ?? 0;
+            buckets.push({
+                fromMs,
+                toMs,
+                model,
+                calls: num(r.num_model_requests),
+                // OpenAI reports cached tokens *inside* the input total, so the
+                // uncached half is the subtraction. Reporting both at face value
+                // would bill the cached tokens twice, at the dearer rate.
+                inputTokens: Math.max(0, input - cached),
+                cacheReadTokens: cached,
+                cacheWrite5mTokens: 0,
+                cacheWrite1hTokens: 0,
+                // Nothing was assumed: this API reports no cache writes at all, and an
+                // absent field is not an assumed TTL.
+                writeTtlKnown: true,
+                outputTokens: num(r.output_tokens) ?? 0,
+                group: groupOf(r, ['project_id', 'api_key_id', 'batch']),
+            });
+        }
+    }
+    const merged = collect(buckets);
+    return {
+        provider: 'openai',
+        granularity: 'bucketed',
+        buckets: merged,
+        window: windowOf(merged),
+        gaps,
+        unavailable: descriptor.unavailable,
+    };
+}
+function groupOf(row, keys) {
+    const group = {};
+    for (const key of keys) {
+        const value = row[key];
+        if (typeof value === 'string' && value !== '')
+            group[key] = value;
+        else if (typeof value === 'number' && Number.isFinite(value))
+            group[key] = String(value);
+        else if (typeof value === 'boolean')
+            group[key] = String(value);
+    }
+    return group;
+}
+/**
+ * Prices the buckets a connector pulled.
+ *
+ * Every figure here is the provider's own billed token count at the
+ * catalogue's rates — the same arithmetic `profile` does, over sums instead of
+ * rows. What it deliberately does not do is synthesise the per-call findings:
+ * they are listed as unavailable and left absent, so nothing downstream can
+ * read a zero this function wrote.
+ */
+export function bucketedProfile(pull, options) {
+    const { catalogue, on = new Date() } = options;
+    const slices = new Map();
+    const days = new Map();
+    const unpriced = new Map();
+    for (const bucket of pull.buckets) {
+        const model = catalogue.byId.get(bucket.model);
+        if (model === undefined) {
+            const seen = unpriced.get(bucket.model) ?? { inputTokens: 0, outputTokens: 0 };
+            seen.inputTokens += bucket.inputTokens + bucket.cacheReadTokens;
+            seen.outputTokens += bucket.outputTokens;
+            unpriced.set(bucket.model, seen);
+            continue;
+        }
+        const { inputPerMTok, outputPerMTok } = effectivePricing(model, on);
+        const rates = multipliersFor(model);
+        const per = (count, rate) => (count / 1_000_000) * rate;
+        const inputUsd = per(bucket.inputTokens, inputPerMTok);
+        const cacheReadUsd = per(bucket.cacheReadTokens, inputPerMTok * rates.cacheRead);
+        const cacheWriteUsd = per(bucket.cacheWrite5mTokens, inputPerMTok * rates.cacheWrite5m) +
+            per(bucket.cacheWrite1hTokens, inputPerMTok * rates.cacheWrite1h);
+        const outputUsd = per(bucket.outputTokens, outputPerMTok);
+        const writeTokens = bucket.cacheWrite5mTokens + bucket.cacheWrite1hTokens;
+        const atInputRate = per(bucket.cacheReadTokens + writeTokens, inputPerMTok);
+        const ifAssumed1h = bucket.writeTtlKnown
+            ? cacheWriteUsd
+            : per(writeTokens, inputPerMTok * rates.cacheWrite1h);
+        const slice = slices.get(bucket.model) ?? {
+            model: bucket.model,
+            calls: bucket.calls === null ? null : 0,
+            inputTokens: 0,
+            cacheReadTokens: 0,
+            cacheWriteTokens: 0,
+            outputTokens: 0,
+            inputUsd: 0,
+            cacheReadUsd: 0,
+            cacheWriteUsd: 0,
+            outputUsd: 0,
+            totalUsd: 0,
+            cachedTokensAtInputRateUsd: 0,
+            cacheWriteUsdIfAssumed1h: 0,
+            writeTtlKnown: true,
+        };
+        slice.calls = slice.calls === null || bucket.calls === null ? null : slice.calls + bucket.calls;
+        slice.inputTokens += bucket.inputTokens;
+        slice.cacheReadTokens += bucket.cacheReadTokens;
+        slice.cacheWriteTokens += writeTokens;
+        slice.outputTokens += bucket.outputTokens;
+        slice.inputUsd += inputUsd;
+        slice.cacheReadUsd += cacheReadUsd;
+        slice.cacheWriteUsd += cacheWriteUsd;
+        slice.outputUsd += outputUsd;
+        slice.totalUsd += inputUsd + cacheReadUsd + cacheWriteUsd + outputUsd;
+        slice.cachedTokensAtInputRateUsd += atInputRate;
+        slice.cacheWriteUsdIfAssumed1h += ifAssumed1h;
+        slice.writeTtlKnown = slice.writeTtlKnown && bucket.writeTtlKnown;
+        slices.set(bucket.model, slice);
+        const day = new Date(bucket.fromMs).toISOString().slice(0, 10);
+        const entry = days.get(day) ?? { usd: 0, calls: bucket.calls === null ? null : 0 };
+        entry.usd += inputUsd + cacheReadUsd + cacheWriteUsd + outputUsd;
+        entry.calls = entry.calls === null || bucket.calls === null ? null : entry.calls + bucket.calls;
+        days.set(day, entry);
+    }
+    const byModel = [...slices.values()].sort((a, b) => b.totalUsd - a.totalUsd);
+    const anyCallsUnknown = byModel.some((s) => s.calls === null) || byModel.length === 0;
+    return {
+        schemaVersion: 1,
+        provider: pull.provider,
+        granularity: pull.granularity,
+        span: pull.window,
+        total: {
+            totalUsd: byModel.reduce((sum, s) => sum + s.totalUsd, 0),
+            calls: anyCallsUnknown ? null : byModel.reduce((sum, s) => sum + (s.calls ?? 0), 0),
+            inputTokens: byModel.reduce((sum, s) => sum + s.inputTokens, 0),
+            cacheReadTokens: byModel.reduce((sum, s) => sum + s.cacheReadTokens, 0),
+            cacheWriteTokens: byModel.reduce((sum, s) => sum + s.cacheWriteTokens, 0),
+            outputTokens: byModel.reduce((sum, s) => sum + s.outputTokens, 0),
+        },
+        byModel,
+        byDay: [...days.entries()]
+            .sort((a, b) => a[0].localeCompare(b[0]))
+            .map(([day, entry]) => ({ day, usd: entry.usd, calls: entry.calls })),
+        unpricedModels: [...unpriced.entries()]
+            .map(([model, tokens]) => ({ model, ...tokens }))
+            .sort((a, b) => b.inputTokens + b.outputTokens - (a.inputTokens + a.outputTokens)),
+        gaps: pull.gaps,
+        unavailable: pull.unavailable,
+    };
+}
+/**
+ * The cache verdict over a connected report.
+ *
+ * Same counterfactual `cacheEconomics` runs on a per-call report: what the
+ * cache-touched tokens cost, against what they would have cost as ordinary
+ * input. The worst case is carried separately for the same reason it is
+ * there — when the source did not state the write TTL, the cheaper rate was
+ * assumed for the headline and the verdict can move under the other one.
+ */
+export function bucketedCacheEconomics(report) {
+    const spent = report.byModel.reduce((sum, s) => sum + s.cacheReadUsd + s.cacheWriteUsd, 0);
+    const without = report.byModel.reduce((sum, s) => sum + s.cachedTokensAtInputRateUsd, 0);
+    const worst = report.byModel.reduce((sum, s) => sum + s.cacheReadUsd + s.cacheWriteUsdIfAssumed1h, 0);
+    const touched = report.byModel.reduce((sum, s) => sum + s.cacheReadTokens + s.cacheWriteTokens, 0);
+    const verdictOf = (paid) => {
+        if (touched === 0)
+            return 'no-cache';
+        return paid <= without ? 'paid-off' : 'lost-money';
+    };
+    return {
+        spentUsd: spent,
+        withoutCachingUsd: without,
+        deltaUsd: spent - without,
+        verdict: verdictOf(spent),
+        worstCaseVerdict: verdictOf(worst),
+    };
+}
+//# sourceMappingURL=connector.js.map