@agent-finops/core 0.7.3 → 0.8.0

package/dist/providerConnectors.js

@@ -1,5 +1,24 @@
 import { createProviderConnectorStub, slugifySourceId } from "./sourceRegistry.js";
 import { redactSecrets } from "./discovery.js";
+/**
+ * Trusted connector failure metadata. Provider prose remains untrusted and is
+ * used only as a sanitized human-readable message; callers classify failures
+ * from this product-authored code and the observed HTTP status instead.
+ */
+export class ProviderConnectorError extends Error {
+    code;
+    status;
+    constructor(message, options) {
+        super(message);
+        this.name = "ProviderConnectorError";
+        this.code = options.code;
+        this.status = options.status;
+    }
+}
+export function isProviderAuthenticationError(error) {
+    return error instanceof ProviderConnectorError &&
+        error.code === "authentication_error";
+}
 export function normalizeOpenAiCostResponse(response, options) {
     const data = isObject(response) && Array.isArray(response.data) ? response.data : [];
     const records = [];
@@ -59,29 +78,115 @@ export function normalizeOpenAiCostResponse(response, options) {
 export function normalizeOpenAiUsageResponse(response, options) {
     const data = isObject(response) && Array.isArray(response.data) ? response.data : [];
     const records = [];
-    for (const bucket of data) {
-        const startTime = typeof bucket.start_time === "number" ? bucket.start_time : 0;
+    for (const bucketValue of data) {
+        if (!isRecord(bucketValue) || !Array.isArray(bucketValue.results))
+            continue;
+        const startTime = validEpochSeconds(bucketValue.start_time);
+        if (typeof startTime !== "number")
+            continue;
         const timestamp = new Date(startTime * 1000).toISOString();
-        for (const result of bucket.results ?? []) {
-            const projectId = result.project_id ?? undefined;
-            const userId = result.user_id ?? undefined;
-            const apiKeyId = result.api_key_id ?? undefined;
-            const model = result.model ?? "openai-usage";
-            const inputTokens = nonNegativeIntegerValue(result.input_tokens) ?? 0;
-            const outputTokens = nonNegativeIntegerValue(result.output_tokens) ?? 0;
-            const cachedTokens = nonNegativeIntegerValue(result.input_cached_tokens) ?? 0;
-            const audioInputTokens = nonNegativeIntegerValue(result.input_audio_tokens) ?? 0;
-            const audioOutputTokens = nonNegativeIntegerValue(result.output_audio_tokens) ?? 0;
+        for (const resultValue of bucketValue.results) {
+            if (!isRecord(resultValue))
+                continue;
+            const result = resultValue;
+            const projectId = stringValue(result.project_id);
+            const userId = stringValue(result.user_id);
+            const apiKeyId = stringValue(result.api_key_id);
+            const model = stringValue(result.model) ?? "openai-usage";
+            const serviceTier = stringValue(result.service_tier);
+            const batch = typeof result.batch === "boolean" ? result.batch : undefined;
+            // OpenAI's organization completions Usage API defines these as
+            // inclusive totals across text, audio, image, cache reads, and cache
+            // writes. The modality/cache fields below are subsets for provenance;
+            // adding them again double-counts usage.
+            // https://developers.openai.com/cookbook/examples/completions_usage_api
+            const inputTokens = nonNegativeIntegerValue(result.input_tokens);
+            const outputTokens = nonNegativeIntegerValue(result.output_tokens);
+            // A request count does not prove a zero-token result. Preserve explicit
+            // 0/0 totals, but fail closed when either canonical total is absent or
+            // invalid so missing provider evidence never becomes a verified zero.
+            if (typeof inputTokens !== "number" || typeof outputTokens !== "number")
+                continue;
             const requestCount = nonNegativeIntegerValue(result.num_model_requests);
-            if (inputTokens + outputTokens + audioInputTokens + audioOutputTokens === 0 && typeof requestCount !== "number")
+            if (inputTokens + outputTokens === 0 && !(typeof requestCount === "number" && requestCount > 0))
                 continue;
+            const inputComponent = (value) => boundedTokenComponent(value, inputTokens);
+            const outputComponent = (value) => boundedTokenComponent(value, outputTokens);
+            const cacheReadTokens = inputComponent(result.input_cached_tokens);
+            const cachedComponent = (value) => {
+                const component = inputComponent(value);
+                return component !== undefined && (cacheReadTokens === undefined || component <= cacheReadTokens)
+                    ? component
+                    : undefined;
+            };
+            const inputAccountingValid = componentFamilyWithinParent([
+                result.input_uncached_tokens,
+                result.input_cache_write_tokens,
+                result.input_cached_tokens
+            ], inputTokens);
+            const inputModalitiesValid = componentFamilyWithinParent([
+                result.input_text_tokens,
+                result.input_image_tokens,
+                result.input_audio_tokens
+            ], inputTokens);
+            const cachedModalitiesPresent = [
+                result.input_cached_text_tokens,
+                result.input_cached_image_tokens,
+                result.input_cached_audio_tokens
+            ].some((value) => value !== undefined);
+            const cachedModalitiesValid = !cachedModalitiesPresent || (cacheReadTokens !== undefined && componentFamilyWithinParent([
+                result.input_cached_text_tokens,
+                result.input_cached_image_tokens,
+                result.input_cached_audio_tokens
+            ], cacheReadTokens));
+            const outputModalitiesValid = componentFamilyWithinParent([
+                result.output_text_tokens,
+                result.output_image_tokens,
+                result.output_audio_tokens
+            ], outputTokens);
             records.push({
-                id: slugifySourceId(["openai-usage", String(startTime), projectId, userId, apiKeyId, model].filter(Boolean).join("-")),
+                id: slugifySourceId(["openai-usage", String(startTime), projectId, userId, apiKeyId, model, serviceTier, batch === undefined ? undefined : `batch-${batch}`].filter(Boolean).join("-")),
                 timestamp,
                 source: { id: options.sourceId, name: "OpenAI organization usage API", provider: "openai", confidence: "verified", observedFrom: options.observedFrom },
                 model,
-                inputTokens: inputTokens + audioInputTokens,
-                outputTokens: outputTokens + audioOutputTokens,
+                inputTokens,
+                outputTokens,
+                ...(inputAccountingValid && inputComponent(result.input_uncached_tokens) !== undefined
+                    ? { inputUncachedTokens: inputComponent(result.input_uncached_tokens) }
+                    : {}),
+                ...(inputAccountingValid && inputComponent(result.input_cache_write_tokens) !== undefined
+                    ? { inputCacheWriteTokens: inputComponent(result.input_cache_write_tokens) }
+                    : {}),
+                ...(inputAccountingValid && cacheReadTokens !== undefined
+                    ? { cacheReadTokens }
+                    : {}),
+                ...(inputModalitiesValid && inputComponent(result.input_text_tokens) !== undefined
+                    ? { inputTextTokens: inputComponent(result.input_text_tokens) }
+                    : {}),
+                ...(inputModalitiesValid && inputComponent(result.input_image_tokens) !== undefined
+                    ? { inputImageTokens: inputComponent(result.input_image_tokens) }
+                    : {}),
+                ...(inputModalitiesValid && inputComponent(result.input_audio_tokens) !== undefined
+                    ? { inputAudioTokens: inputComponent(result.input_audio_tokens) }
+                    : {}),
+                ...(cachedModalitiesValid && cachedComponent(result.input_cached_text_tokens) !== undefined
+                    ? { inputCachedTextTokens: cachedComponent(result.input_cached_text_tokens) }
+                    : {}),
+                ...(cachedModalitiesValid && cachedComponent(result.input_cached_image_tokens) !== undefined
+                    ? { inputCachedImageTokens: cachedComponent(result.input_cached_image_tokens) }
+                    : {}),
+                ...(cachedModalitiesValid && cachedComponent(result.input_cached_audio_tokens) !== undefined
+                    ? { inputCachedAudioTokens: cachedComponent(result.input_cached_audio_tokens) }
+                    : {}),
+                ...(outputModalitiesValid && outputComponent(result.output_text_tokens) !== undefined
+                    ? { outputTextTokens: outputComponent(result.output_text_tokens) }
+                    : {}),
+                ...(outputModalitiesValid && outputComponent(result.output_image_tokens) !== undefined
+                    ? { outputImageTokens: outputComponent(result.output_image_tokens) }
+                    : {}),
+                ...(outputModalitiesValid && outputComponent(result.output_audio_tokens) !== undefined
+                    ? { outputAudioTokens: outputComponent(result.output_audio_tokens) }
+                    : {}),
                 amountUsd: null,
                 costConfidence: "missing",
                 projectId,
@@ -90,12 +195,24 @@ export function normalizeOpenAiUsageResponse(response, options) {
                 providerCostType: "openai_usage_evidence",
                 usageGranularity: "usage_bucket",
                 quantity: requestCount,
+                ...(serviceTier ? { serviceTier } : {}),
+                ...(batch !== undefined ? { batch } : {}),
                 operation: "OpenAI completions usage evidence"
             });
         }
     }
     return records;
 }
+function boundedTokenComponent(value, inclusiveTotal) {
+    const component = nonNegativeIntegerValue(value);
+    return typeof component === "number" && component <= inclusiveTotal ? component : undefined;
+}
+function componentFamilyWithinParent(values, parent) {
+    const components = values
+        .map(nonNegativeIntegerValue)
+        .filter((value) => typeof value === "number");
+    return components.reduce((sum, value) => sum + value, 0) <= parent;
+}
 export function normalizeAnthropicClaudeCodeUsageResponse(response, options) {
     const rows = extractArray(response, "data");
     const records = [];
@@ -377,7 +494,10 @@ function redactResolvedCredentialError(error, credentialVariants) {
     // provider can splice ANSI bytes through an opaque credential so the first
     // literal replacement misses it and control stripping reconstructs it.
     const safeMessage = exactRedactCredentialValues(sanitizeProviderMessage(withoutResolvedCredential), credentialVariants).trim();
-    return new Error(safeMessage || "Provider connector request failed without a safe error message.");
+    const message = safeMessage || "Provider connector request failed without a safe error message.";
+    return error instanceof ProviderConnectorError
+        ? new ProviderConnectorError(message, { code: error.code, status: error.status })
+        : new Error(message);
 }
 function redactResolvedCredentialValue(value, credentialVariants) {
     if (typeof value === "string") {
@@ -400,12 +520,15 @@ async function fetchOpenAi(input, token, fetcher, sourceId) {
     };
     const costFetch = await fetchPaginatedJson(fetcher, buildOpenAiCostsUrl(input.startTime, input.endTime), request, "openai", "OpenAI costs API");
     markMalformedCostRows(costFetch, "openai", "OpenAI costs API");
+    enforceOpenAiRequestedWindow(costFetch, input.startTime, input.endTime, "OpenAI costs API");
     const usageFetch = await fetchPaginatedJson(fetcher, buildOpenAiUsageUrl(input.startTime, input.endTime), request, "openai", "OpenAI usage API");
     markMalformedUsageRows(usageFetch, "openai", "OpenAI usage API");
-    const records = [
+    enforceOpenAiRequestedWindow(usageFetch, input.startTime, input.endTime, "OpenAI usage API");
+    const normalizedRecords = [
         ...costFetch.pages.flatMap((page) => normalizeOpenAiCostResponse(page, { sourceId, observedFrom: "OpenAI organization costs API" })),
         ...usageFetch.pages.flatMap((page) => normalizeOpenAiUsageResponse(page, { sourceId, observedFrom: "OpenAI organization usage API" }))
     ];
+    const records = dedupeProviderRecords(normalizedRecords, [costFetch, usageFetch]);
     return providerResult("openai", sourceId, input.authReference, records, qaSummary("openai", [costFetch, usageFetch]), requestedCoverageInterval(input));
 }
 async function fetchAnthropic(input, token, fetcher, sourceId) {
@@ -587,7 +710,7 @@ async function fetchTextOrThrow(fetcher, url, request, provider, label) {
             return response.text();
         }
         const payload = await response.json().catch(() => undefined);
-        lastError = new Error(providerPermissionPrompt(provider, label, response, payload));
+        lastError = providerRequestError(provider, label, response, payload);
         const retryable = response.status === 429 || response.status >= 500;
         if (!retryable || attempt === maxFetchRetries)
             break;
@@ -664,7 +787,20 @@ async function fetchPaginatedJson(fetcher, initialUrl, request, provider, label)
     let stoppedBecause = "complete";
     let note;
     const maxPages = 50;
+    const seenUrls = new Set();
     for (let pageCount = 0; nextUrl && pageCount < maxPages; pageCount += 1) {
+        if (seenUrls.has(nextUrl)) {
+            stoppedBecause = "missing_cursor";
+            note = `Stopped after ${pages.length} page(s): provider repeated a pagination URL.`;
+            responseDrift.push({
+                label,
+                field: "next_page",
+                issue: "provider repeated a pagination cursor; duplicate pages were not fetched"
+            });
+            nextUrl = undefined;
+            break;
+        }
+        seenUrls.add(nextUrl);
         let response;
         try {
             response = await fetchJsonOrThrow(fetcher, nextUrl, request, provider, label);
@@ -721,6 +857,64 @@ async function fetchPaginatedJson(fetcher, initialUrl, request, provider, label)
         responseDrift
     };
 }
+function enforceOpenAiRequestedWindow(fetchResult, requestedStart, requestedEnd, label) {
+    let excluded = 0;
+    const nowEpochSeconds = Math.floor(Date.now() / 1000);
+    fetchResult.pages = fetchResult.pages.map((page) => {
+        if (!isRecord(page) || !Array.isArray(page.data))
+            return page;
+        const data = page.data.filter((bucket) => {
+            if (!isRecord(bucket))
+                return true;
+            const start = validEpochSeconds(bucket.start_time);
+            const hasEnd = bucket.end_time !== undefined;
+            const end = hasEnd ? validEpochSeconds(bucket.end_time) : undefined;
+            const invalidEnd = hasEnd && (typeof end !== "number" || typeof start !== "number" || end <= start);
+            const missingRequiredEnd = typeof requestedEnd === "number" && typeof end !== "number";
+            const outsideStart = typeof start !== "number" || start < requestedStart ||
+                (typeof requestedEnd === "number" && start >= requestedEnd);
+            const outsideEnd = typeof requestedEnd === "number" && typeof end === "number" && end > requestedEnd;
+            const futureOpenEndedStart = requestedEnd === undefined && typeof start === "number" && start > nowEpochSeconds;
+            if (!invalidEnd && !missingRequiredEnd && !outsideStart && !outsideEnd && !futureOpenEndedStart)
+                return true;
+            excluded += 1;
+            fetchResult.responseDrift.push({
+                label,
+                field: "data[].start_time/end_time",
+                issue: "bucket boundary was missing, invalid, future-starting, or outside the requested interval; the bucket was excluded"
+            });
+            return false;
+        });
+        return { ...page, data };
+    });
+    if (excluded > 0)
+        fetchResult.coverageIncomplete = true;
+}
+function dedupeProviderRecords(records, fetches) {
+    const byId = new Map();
+    const conflicted = new Set();
+    for (const record of records) {
+        const existing = byId.get(record.id);
+        if (!existing && !conflicted.has(record.id)) {
+            byId.set(record.id, record);
+            continue;
+        }
+        const target = record.providerCostType === "openai_cost" ? fetches[0] : fetches[1];
+        target.coverageIncomplete = true;
+        target.responseDrift.push({
+            label: target.pagination.label,
+            field: "normalized records[].id",
+            issue: existing && JSON.stringify(existing) === JSON.stringify(record)
+                ? "duplicate provider record was excluded"
+                : "conflicting provider records shared one stable identity; all conflicting rows were excluded"
+        });
+        if (existing && JSON.stringify(existing) !== JSON.stringify(record)) {
+            byId.delete(record.id);
+            conflicted.add(record.id);
+        }
+    }
+    return Array.from(byId.values());
+}
 function validatePaginationUrl(initialUrl, candidate) {
     try {
         const initial = new URL(initialUrl);
@@ -793,7 +987,7 @@ async function fetchJsonOrThrow(fetcher, url, request, provider, label) {
         if (response.ok) {
             return { payload, rateLimit: rateLimitFromHeaders(label, response.headers), headers: response.headers };
         }
-        lastError = new Error(providerPermissionPrompt(provider, label, response, payload));
+        lastError = providerRequestError(provider, label, response, payload);
         // 429 and 5xx are transient: honor retry-after when present, otherwise
         // back off briefly and try again. 4xx auth/scope errors fail immediately.
         const retryable = response.status === 429 || response.status >= 500;
@@ -978,6 +1172,9 @@ function markMalformedUsageRows(fetchResult, provider, label) {
                     report(bucketPath, "usage response contained a malformed bucket or omitted its results array");
                     continue;
                 }
+                if (typeof validEpochSeconds(bucketValue.start_time) !== "number") {
+                    report(`${bucketPath}.start_time`, "usage bucket start_time must be a non-negative whole-second timestamp; the bucket was excluded");
+                }
                 for (const [resultIndex, resultValue] of bucketValue.results.entries()) {
                     const resultPath = `${bucketPath}.results[${resultIndex}]`;
                     if (!isRecord(resultValue)) {
@@ -1003,6 +1200,67 @@ function markMalformedUsageRows(fetchResult, provider, label) {
                         checkInteger(resultValue[field], `${resultPath}.${field}`, "token count");
                     }
                     checkInteger(resultValue.num_model_requests, `${resultPath}.num_model_requests`, "quantity");
+                    const inputTotal = nonNegativeIntegerValue(resultValue.input_tokens);
+                    const outputTotal = nonNegativeIntegerValue(resultValue.output_tokens);
+                    const cachedTotal = nonNegativeIntegerValue(resultValue.input_cached_tokens);
+                    if (typeof inputTotal !== "number") {
+                        report(`${resultPath}.input_tokens`, "canonical input_tokens total is required; the usage row was excluded");
+                    }
+                    if (typeof outputTotal !== "number") {
+                        report(`${resultPath}.output_tokens`, "canonical output_tokens total is required; the usage row was excluded");
+                    }
+                    for (const field of [
+                        "input_uncached_tokens",
+                        "input_cache_write_tokens",
+                        "input_cached_tokens",
+                        "input_text_tokens",
+                        "input_image_tokens",
+                        "input_audio_tokens",
+                        "input_cached_text_tokens",
+                        "input_cached_image_tokens",
+                        "input_cached_audio_tokens"
+                    ]) {
+                        const component = nonNegativeIntegerValue(resultValue[field]);
+                        if (typeof component === "number" && typeof inputTotal === "number" && component > inputTotal) {
+                            report(`${resultPath}.${field}`, "input component exceeds the inclusive input_tokens total; the component was excluded");
+                        }
+                    }
+                    for (const field of ["output_text_tokens", "output_image_tokens", "output_audio_tokens"]) {
+                        const component = nonNegativeIntegerValue(resultValue[field]);
+                        if (typeof component === "number" && typeof outputTotal === "number" && component > outputTotal) {
+                            report(`${resultPath}.${field}`, "output component exceeds the inclusive output_tokens total; the component was excluded");
+                        }
+                    }
+                    for (const field of [
+                        "input_cached_text_tokens",
+                        "input_cached_image_tokens",
+                        "input_cached_audio_tokens"
+                    ]) {
+                        const component = nonNegativeIntegerValue(resultValue[field]);
+                        if (typeof component === "number" && typeof cachedTotal === "number" && component > cachedTotal) {
+                            report(`${resultPath}.${field}`, "cached component exceeds input_cached_tokens; the component was excluded");
+                        }
+                    }
+                    if (typeof cachedTotal !== "number" && [
+                        resultValue.input_cached_text_tokens,
+                        resultValue.input_cached_image_tokens,
+                        resultValue.input_cached_audio_tokens
+                    ].some((value) => typeof nonNegativeIntegerValue(value) === "number")) {
+                        report(`${resultPath}.input_cached_*_tokens`, "cached modality components require input_cached_tokens; the component family was excluded");
+                    }
+                    const reportFamilyOverflow = (fields, parent, parentField) => {
+                        if (typeof parent !== "number")
+                            return;
+                        const values = fields.map((field) => nonNegativeIntegerValue(resultValue[field]));
+                        const present = values.filter((value) => typeof value === "number");
+                        if (present.reduce((sum, value) => sum + value, 0) > parent) {
+                            report(`${resultPath}.${fields.join("+")}`, `component family exceeds ${parentField}; the contradictory component family was excluded`);
+                        }
+                    };
+                    reportFamilyOverflow(["input_uncached_tokens", "input_cache_write_tokens", "input_cached_tokens"], inputTotal, "input_tokens");
+                    reportFamilyOverflow(["input_text_tokens", "input_image_tokens", "input_audio_tokens"], inputTotal, "input_tokens");
+                    reportFamilyOverflow(["input_cached_text_tokens", "input_cached_image_tokens", "input_cached_audio_tokens"], cachedTotal, "input_cached_tokens");
+                    reportFamilyOverflow(["output_text_tokens", "output_image_tokens", "output_audio_tokens"], outputTotal, "output_tokens");
                 }
             }
             continue;
@@ -1195,6 +1453,13 @@ function providerPermissionPrompt(provider, label, response, payload) {
     }
     return `${label} request failed with ${status}. ${rawMessage}`.trim();
 }
+function providerRequestError(provider, label, response, payload) {
+    const authenticationFailure = response.status === 401 || response.status === 403;
+    return new ProviderConnectorError(providerPermissionPrompt(provider, label, response, payload), {
+        code: authenticationFailure ? "authentication_error" : "provider_request_error",
+        status: response.status
+    });
+}
 function extractProviderMessage(payload) {
     if (!isRecord(payload))
         return "";
@@ -1238,6 +1503,17 @@ export function summarizeProviderFinancials(records) {
     }
     return { providerReportedBilledUsd, apiEquivalentEstimatedUsd, providerEstimatedUsd, headlineUsd: null, headlineBasis: "unavailable" };
 }
+export function providerFinancialCompleteness(records, coverage) {
+    const financials = summarizeProviderFinancials(records);
+    const headlineConfidence = financials.headlineBasis === "provider_reported_billed_cost"
+        ? "verified"
+        : financials.headlineBasis === "unavailable"
+            ? "missing"
+            : "estimated";
+    return coverage === "partial" && headlineConfidence !== "missing"
+        ? "detected_unverified"
+        : headlineConfidence;
+}
 /**
  * Keep evidence records available to callers, but never add estimates to a
  * provider's official billed total. This selection is intended for aggregate
@@ -1268,14 +1544,7 @@ function providerResult(provider, sourceId, authReference, records, qa, coverage
     const coverage = resolvedQa.coverage
         ?? (resolvedQa.pagination.every((pagination) => pagination.stoppedBecause === "complete") ? "complete" : "partial");
     const financials = summarizeProviderFinancials(records);
-    const headlineConfidence = financials.headlineBasis === "provider_reported_billed_cost"
-        ? "verified"
-        : financials.headlineBasis === "unavailable"
-            ? "missing"
-            : "estimated";
-    const completeness = coverage === "partial" && headlineConfidence !== "missing"
-        ? "detected_unverified"
-        : headlineConfidence;
+    const completeness = providerFinancialCompleteness(records, coverage);
     return {
         provider,
         source: createProviderConnection({ provider, sourceId, authReference, verifiedRecordCount: records.length, totalUsd: financials.headlineUsd, completeness }),
@@ -1328,7 +1597,7 @@ export function createProviderConnection(input) {
         validationCoverage: validationCoverageForCompletedProviderSync(input.provider),
         financialEvidence,
         authReference: input.authReference,
-        fieldsMissing: [],
+        fieldsMissing: financialEvidence === "missing" ? ["provider financial headline"] : [],
         scope: `${source.scope} Last successful pull produced ${input.verifiedRecordCount} record(s); financial evidence: ${financialEvidence}; financial headline: ${total}.`
     };
 }
@@ -1345,15 +1614,15 @@ function formatProviderUsd(value) {
 }
 export function resolveTokenReference(reference, env = process.env) {
     if (!reference.startsWith("env:")) {
-        throw new Error("Provider auth reference must be a local reference such as env:OPENAI_ADMIN_KEY; raw secrets are not accepted.");
+        throw new ProviderConnectorError("Provider auth reference must be a local reference such as env:OPENAI_ADMIN_KEY; raw secrets are not accepted.", { code: "authentication_error" });
     }
     const envName = reference.slice("env:".length);
     if (!/^[A-Z0-9_]+$/.test(envName)) {
-        throw new Error("Provider auth env reference must use an uppercase environment variable name.");
+        throw new ProviderConnectorError("Provider auth env reference must use an uppercase environment variable name.", { code: "authentication_error" });
     }
     const value = env[envName];
     if (!value) {
-        throw new Error(`Provider auth reference ${reference} is not set in the local environment.`);
+        throw new ProviderConnectorError(`Provider auth reference ${reference} is not set in the local environment.`, { code: "authentication_error" });
     }
     return value;
 }
@@ -1378,6 +1647,8 @@ function buildOpenAiUsageUrl(startTime, endTime) {
     url.searchParams.append("group_by", "user_id");
     url.searchParams.append("group_by", "api_key_id");
     url.searchParams.append("group_by", "model");
+    url.searchParams.append("group_by", "batch");
+    url.searchParams.append("group_by", "service_tier");
     if (endTime !== undefined)
         url.searchParams.set("end_time", String(endTime));
     return url.toString();
@@ -1449,7 +1720,7 @@ function stringValue(value) {
 }
 function validEpochSeconds(value) {
     const seconds = numberValue(value);
-    return typeof seconds === "number" && seconds >= 0 && Number.isFinite(new Date(seconds * 1000).getTime())
+    return typeof seconds === "number" && Number.isInteger(seconds) && seconds >= 0 && Number.isFinite(new Date(seconds * 1000).getTime())
         ? seconds
         : undefined;
 }

package/dist/providerContractStates.generated.d.ts

@@ -0,0 +1,8 @@
+export declare const generatedProviderContractStates: {
+    readonly anthropic: "current";
+    readonly cursor: "current";
+    readonly "gemini-cli": "current";
+    readonly "github-copilot": "current";
+    readonly openai: "current";
+};
+//# sourceMappingURL=providerContractStates.generated.d.ts.map

package/dist/providerContractStates.generated.js

@@ -0,0 +1,9 @@
+// GENERATED by scripts/generate-provider-contract-docs.mjs. Do not edit by hand.
+export const generatedProviderContractStates = {
+    "anthropic": "current",
+    "cursor": "current",
+    "gemini-cli": "current",
+    "github-copilot": "current",
+    "openai": "current",
+};
+//# sourceMappingURL=providerContractStates.generated.js.map

package/dist/schema.d.ts

@@ -69,6 +69,24 @@ export declare const usageRecordSchema: z.ZodObject<{
     model: z.ZodString;
     inputTokens: z.ZodNumber;
     outputTokens: z.ZodNumber;
+    cacheReadTokens: z.ZodOptional<z.ZodNumber>;
+    inputUncachedTokens: z.ZodOptional<z.ZodNumber>;
+    inputCacheWriteTokens: z.ZodOptional<z.ZodNumber>;
+    inputTextTokens: z.ZodOptional<z.ZodNumber>;
+    inputImageTokens: z.ZodOptional<z.ZodNumber>;
+    inputAudioTokens: z.ZodOptional<z.ZodNumber>;
+    inputCachedTextTokens: z.ZodOptional<z.ZodNumber>;
+    inputCachedImageTokens: z.ZodOptional<z.ZodNumber>;
+    inputCachedAudioTokens: z.ZodOptional<z.ZodNumber>;
+    outputTextTokens: z.ZodOptional<z.ZodNumber>;
+    outputImageTokens: z.ZodOptional<z.ZodNumber>;
+    outputAudioTokens: z.ZodOptional<z.ZodNumber>;
+    serviceTier: z.ZodOptional<z.ZodString>;
+    batch: z.ZodOptional<z.ZodBoolean>;
+    thoughtTokens: z.ZodOptional<z.ZodNumber>;
+    toolTokens: z.ZodOptional<z.ZodNumber>;
+    reportedTotalTokens: z.ZodOptional<z.ZodNumber>;
+    sourceVersions: z.ZodOptional<z.ZodArray<z.ZodString>>;
     amountUsd: z.ZodNullable<z.ZodNumber>;
     costConfidence: z.ZodEnum<{
         verified: "verified";

package/dist/schema.js

@@ -47,8 +47,34 @@ export const usageRecordSchema = z.object({
     timestamp: z.string().datetime({ offset: true }),
     source: spendSourceSchema,
     model: z.string().min(1),
+    /** Inclusive input-side total. Gemini includes cached + tool tokens here. */
     inputTokens: z.number().int().nonnegative(),
+    /** Inclusive output-side total. Gemini includes thought tokens here. */
     outputTokens: z.number().int().nonnegative(),
+    /**
+     * Optional component subsets retained as provenance. These fields are
+     * already included in inputTokens/outputTokens and must not be added again.
+     */
+    cacheReadTokens: z.number().int().nonnegative().optional(),
+    inputUncachedTokens: z.number().int().nonnegative().optional(),
+    inputCacheWriteTokens: z.number().int().nonnegative().optional(),
+    inputTextTokens: z.number().int().nonnegative().optional(),
+    inputImageTokens: z.number().int().nonnegative().optional(),
+    inputAudioTokens: z.number().int().nonnegative().optional(),
+    inputCachedTextTokens: z.number().int().nonnegative().optional(),
+    inputCachedImageTokens: z.number().int().nonnegative().optional(),
+    inputCachedAudioTokens: z.number().int().nonnegative().optional(),
+    outputTextTokens: z.number().int().nonnegative().optional(),
+    outputImageTokens: z.number().int().nonnegative().optional(),
+    outputAudioTokens: z.number().int().nonnegative().optional(),
+    /** Provider grouping dimensions retained so bucket identities stay unique. */
+    serviceTier: z.string().min(1).optional(),
+    batch: z.boolean().optional(),
+    thoughtTokens: z.number().int().nonnegative().optional(),
+    toolTokens: z.number().int().nonnegative().optional(),
+    reportedTotalTokens: z.number().int().nonnegative().optional(),
+    /** Sanitized CLI/source versions observed within this aggregate. */
+    sourceVersions: z.array(z.string().min(1).max(64).regex(/^[A-Za-z0-9][A-Za-z0-9.+_-]*$/)).max(8).optional(),
     amountUsd: z.number().nonnegative().nullable(),
     costConfidence: costConfidenceSchema,
     clientId: z.string().min(1).optional(),

package/dist/sourceStatus.d.ts

@@ -1,4 +1,5 @@
 import type { CostConfidence, UsageRecord } from "./schema.js";
+import type { SourceRegistry } from "./sourceRegistry.js";
 import type { LocalAgentFormatId } from "./localAgentFormats/types.js";
 /**
  * How thoroughly an ingestion path itself has been exercised.
@@ -12,6 +13,8 @@ export type SourceValidationCoverage = typeof sourceValidationCoverageValues[num
 export type FinancialEvidenceStatus = CostConfidence;
 export declare const sourceFreshnessStatusValues: readonly ["fresh", "stale", "not_checked"];
 export type SourceFreshnessStatus = typeof sourceFreshnessStatusValues[number];
+export declare const providerContractStateValues: readonly ["current", "stale_contract"];
+export type ProviderContractState = typeof providerContractStateValues[number];
 export type SourceStatusId = LocalAgentFormatId | "openai" | "anthropic" | "cursor" | "github-copilot";
 export type SourceStatusDefinition = {
     id: SourceStatusId;
@@ -19,6 +22,8 @@ export type SourceStatusDefinition = {
     validationCoverage: SourceValidationCoverage;
     validationNote: string;
     staleAfterHours: number;
+    /** Review state of the provider/parser financial semantics used by this source. */
+    contractState?: ProviderContractState;
 };
 export type SourceStatusObservation = {
     id: SourceStatusId;
@@ -32,6 +37,8 @@ export type SourceStatusObservation = {
     lastError?: string;
     /** Runtime failures may override the shipped validation baseline. */
     validationCoverage?: SourceValidationCoverage;
+    /** A drift monitor or reviewed contract update may fail this source closed. */
+    contractState?: ProviderContractState;
 };
 export type SourceStatusFreshness = {
     status: SourceFreshnessStatus;
@@ -46,6 +53,7 @@ export type SourceStatus = {
     validationNote: string;
     financialEvidence: FinancialEvidenceStatus;
     financialEvidenceNote: string;
+    contractState?: ProviderContractState;
     freshness: SourceStatusFreshness;
     lastError?: string;
 };
@@ -55,12 +63,26 @@ export type SourceStatus = {
  * reconciliation.
  */
 export declare const sourceStatusDefinitions: readonly SourceStatusDefinition[];
-export declare function buildSourceStatuses(observations?: readonly SourceStatusObservation[], now?: Date): SourceStatus[];
+export declare function buildSourceStatuses(observations?: readonly SourceStatusObservation[], now?: Date, definitions?: readonly SourceStatusDefinition[]): SourceStatus[];
 /**
  * Reduce one source's current rows to the evidence label used for its headline.
  * Verified billed cost wins; otherwise estimates win over an unpriced signal.
  */
 export declare function financialEvidenceForRecords(records: readonly UsageRecord[]): FinancialEvidenceStatus;
+/**
+ * Apply the reviewed provider-contract gate before any connected financial
+ * calculation. Local transcript evidence is unchanged. When a provider's
+ * financial semantics are stale, its priced rows remain present for audit and
+ * attribution but cannot carry a dollar amount or proof-level confidence.
+ */
+export declare function applyProviderContractGate(records: readonly UsageRecord[], definitions?: readonly SourceStatusDefinition[]): UsageRecord[];
+/**
+ * Project persisted source metadata through the same fail-closed contract
+ * gate as records. This is read-time only: the signed local receipt remains
+ * byte-exact, while an upgraded release cannot repeat an obsolete verified
+ * claim from an older sources.json.
+ */
+export declare function applyProviderContractGateToSourceRegistry(registry: SourceRegistry, definitions?: readonly SourceStatusDefinition[]): SourceRegistry;
 /** Stable, plain-text formatter shared by terminal surfaces. */
 export declare function formatSourceStatuses(statuses: readonly SourceStatus[]): string;
 //# sourceMappingURL=sourceStatus.d.ts.map