@rulvar/openai 1.117.0 → 1.119.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import OpenAI, { ClientOptions } from "openai";
-import { CanonicalId, ChatEvent, ChatRequest, Effort, JournalEntry, ModelCaps, ModelRef, PriceTable, ProviderAdapter, Usage, WireError } from "@rulvar/core";
+import { CanonicalId, ChatEvent, ChatRequest, Effort, InvoiceRow, JournalEntry, ModelCaps, ModelRef, PriceTable, Pricing, ProviderAdapter, Usage, WireError } from "@rulvar/core";
 
 //#region src/caps.d.ts
 interface OpenAiModelInfo {
@@ -145,6 +145,132 @@ interface V1190CacheAudit {
 */
 declare function auditV1190CacheJournal(entries: readonly JournalEntry[], priceUsd: (servedBy: ModelRef, usage: Usage) => number | undefined): V1190CacheAudit;
 //#endregion
+//#region src/reconcile.d.ts
+/** The four billing components a provider statement itemizes. */
+type BillingComponent = "input" | "cached-input" | "cache-write" | "output";
+/**
+* One normalized per-request row of a usage/billing export. `usd` is
+* the row's billed dollars where the export carries amounts;
+* `componentsUsd` its per-component split where it carries one; `usage`
+* the provider-reported token counts where it carries those. A row must
+* carry at least one of the three, and every row needs the provider's
+* response id, the join key.
+*/
+interface StatementRequestRow {
+  responseId: string;
+  /** Provider-side model name (without the adapter prefix); optional. */
+  model?: string;
+  usd?: number;
+  componentsUsd?: Partial<Record<BillingComponent, number>>;
+  usage?: {
+    inputTokens?: number;
+    cachedInputTokens?: number;
+    cacheWriteTokens?: number;
+    outputTokens?: number;
+  };
+}
+/** One per-model per-component total: the Spend categories shape. */
+interface StatementCategoryRow {
+  model: string;
+  component: BillingComponent;
+  usd: number;
+}
+/** A normalized provider export: never a headline total. */
+type ProviderStatement = {
+  kind: "requests";
+  rows: readonly StatementRequestRow[];
+} | {
+  kind: "categories";
+  rows: readonly StatementCategoryRow[];
+};
+interface ReconcileStatementOptions {
+  /** Our rate card, the same resolution the engine prices with. */
+  pricingOf: (servedBy: ModelRef) => Pricing | undefined;
+  /**
+  * Per-component divergence threshold in USD. The default 0.005
+  * absorbs the dashboard's 3-decimal rounding (at most 0.0005 per
+  * figure) with an order of margin, while any real rate-card
+  * divergence on a run worth reconciling sits orders above it.
+  */
+  componentToleranceUsd?: number;
+  /**
+  * Totals threshold for a per-request export that carries row dollars
+  * but no per-component split; default 0.01.
+  */
+  totalToleranceUsd?: number;
+  /** Provider-side model name of a served ref; default strips the adapter prefix. */
+  modelOf?: (servedBy: ModelRef) => string;
+}
+/** One (model, component) line of the reconciliation. */
+interface ComponentDelta {
+  model: string;
+  component: BillingComponent;
+  /** Our token base for the component, from the invoice rows' usage. */
+  ourTokens: number;
+  /** Our dollars, from the shared price decomposition (priceComponentsOf). */
+  ourUsd: number;
+  /** The statement's dollars; absent when the export does not carry this line. */
+  statementUsd?: number;
+  deltaUsd?: number;
+  /** statementUsd over ourTokens, per MTok: the rate the provider ACTUALLY applied. */
+  impliedUsdPerMTok?: number;
+  /** ourUsd over ourTokens, per MTok: our effective rate over the same base, tier mix included. */
+  effectiveUsdPerMTok?: number;
+  divergent: boolean;
+}
+interface StatementCoverage {
+  /** Invoice rows carrying usage or dollars: the billable set. */
+  billableRows: number;
+  rowsWithResponseId: number;
+  /** Requests mode: rows the export covered. Categories mode: equals billableRows (totals claim the set). */
+  matchedRows: number;
+  unmatchedRows: number;
+  /** First unmatched response ids (at most 20), requests mode. */
+  unmatchedIdSample: string[];
+  /** Statement rows matching nothing of ours: ids (requests) or model names (categories). */
+  statementOnlyRows: number;
+  statementOnlyIdSample: string[];
+  complete: boolean;
+}
+interface StatementReconciliation {
+  mode: "requests" | "categories";
+  coverage: StatementCoverage;
+  totals: {
+    ourUsd: number;
+    statementUsd?: number;
+    deltaUsd?: number;
+  };
+  /** Every (model, component) line, models sorted, components in canonical order. */
+  components: ComponentDelta[];
+  /** The lines beyond tolerance, largest |delta| first: the named divergences. */
+  divergent: ComponentDelta[];
+  /** Sample of token disagreements between the export and our recorded usage (requests mode). */
+  tokenMismatches: number;
+  tokenMismatchSample: Array<{
+    responseId: string;
+    field: string;
+    ours: number;
+    statement: number;
+  }>;
+  /** Models the rate card does not cover: declared, excluded from divergence. */
+  unpricedModels: string[];
+  /** Rows whose usage the ledger never saw (usageUnknown): counted apart, never folded. */
+  usageUnknownRows: number;
+  componentToleranceUsd: number;
+  verdict: "match" | "divergence" | "partial-coverage" | "no-overlap";
+}
+/**
+* Reconciles the invoice against a normalized provider export. Pure and
+* journal-free; see the module doc for the contract. Throws a typed
+* ConfigError on inputs that cannot be evidence: an empty statement (a
+* headline total with no rows), a request row without a response id, a
+* duplicate response id (an ambiguous join), or a request export whose
+* rows carry neither dollars, components, nor usage.
+*/
+declare function reconcileStatement(invoice: {
+  rows: readonly InvoiceRow[];
+}, statement: ProviderStatement, options: ReconcileStatementOptions): StatementReconciliation;
+//#endregion
 //#region src/wire.d.ts
 /** Bijective canonical-to-wire (call_*) id map. */
 declare class OpenAiIdMap {
@@ -260,4 +386,4 @@ declare function mapChatCompletionsStream(stream: AsyncIterable<Record<string, u
   signal?: AbortSignal;
 }): AsyncGenerator<ChatEvent, void>;
 //#endregion
-export { CONSERVATIVE_COMPATIBLE_CAPS, OPENAI_MODELS, OPENAI_PRICING, type OpenAiAdapterOptions, type OpenAiClientLike, type OpenAiCompatibleConfig, OpenAiIdMap, type OpenAiModelInfo, type OpenAiSdkOptions, type ResponsesStreamEvent, type V1190CacheAudit, auditV1190CacheJournal, buildChatCompletionsParams, buildResponsesParams, mapChatCompletionsStream, mapOpenAiEffort, mapResponsesStream, normalizeOpenAiUsage, openAiErrorToWire, openAiModelInfo, openai, openaiCompatible, undoV1190CacheDoubleCount };
+export { type BillingComponent, CONSERVATIVE_COMPATIBLE_CAPS, type ComponentDelta, OPENAI_MODELS, OPENAI_PRICING, type OpenAiAdapterOptions, type OpenAiClientLike, type OpenAiCompatibleConfig, OpenAiIdMap, type OpenAiModelInfo, type OpenAiSdkOptions, type ProviderStatement, type ReconcileStatementOptions, type ResponsesStreamEvent, type StatementCategoryRow, type StatementCoverage, type StatementReconciliation, type StatementRequestRow, type V1190CacheAudit, auditV1190CacheJournal, buildChatCompletionsParams, buildResponsesParams, mapChatCompletionsStream, mapOpenAiEffort, mapResponsesStream, normalizeOpenAiUsage, openAiErrorToWire, openAiModelInfo, openai, openaiCompatible, reconcileStatement, undoV1190CacheDoubleCount };

package/dist/index.js

@@ -1,5 +1,5 @@
 import OpenAI from "openai";
-import { ConfigError, createCanonicalIdMinter, entryUsageSlices, isStrictCompatibleSchema } from "@rulvar/core";
+import { ConfigError, createCanonicalIdMinter, entryUsageSlices, isStrictCompatibleSchema, priceComponentsOf } from "@rulvar/core";
 //#region src/caps.ts
 const REASONING_EFFORTS = [
 	"low",
@@ -1038,4 +1038,259 @@ function auditV1190CacheJournal(entries, priceUsd) {
 	};
 }
 //#endregion
-export { CONSERVATIVE_COMPATIBLE_CAPS, OPENAI_MODELS, OPENAI_PRICING, OpenAiIdMap, auditV1190CacheJournal, buildChatCompletionsParams, buildResponsesParams, mapChatCompletionsStream, mapOpenAiEffort, mapResponsesStream, normalizeOpenAiUsage, openAiErrorToWire, openAiModelInfo, openai, openaiCompatible, undoV1190CacheDoubleCount };
+//#region src/reconcile.ts
+const COMPONENTS = [
+	"input",
+	"cached-input",
+	"cache-write",
+	"output"
+];
+const SAMPLE_CAP = 20;
+const emptySums = () => ({
+	tokens: {
+		input: 0,
+		"cached-input": 0,
+		"cache-write": 0,
+		output: 0
+	},
+	usd: {
+		input: 0,
+		"cached-input": 0,
+		"cache-write": 0,
+		output: 0
+	}
+});
+const defaultModelOf = (servedBy) => {
+	const colon = servedBy.indexOf(":");
+	return colon === -1 ? servedBy : servedBy.slice(colon + 1);
+};
+/**
+* Reconciles the invoice against a normalized provider export. Pure and
+* journal-free; see the module doc for the contract. Throws a typed
+* ConfigError on inputs that cannot be evidence: an empty statement (a
+* headline total with no rows), a request row without a response id, a
+* duplicate response id (an ambiguous join), or a request export whose
+* rows carry neither dollars, components, nor usage.
+*/
+function reconcileStatement(invoice, statement, options) {
+	const componentToleranceUsd = options.componentToleranceUsd ?? .005;
+	const totalToleranceUsd = options.totalToleranceUsd ?? .01;
+	const modelOf = options.modelOf ?? defaultModelOf;
+	if (statement.rows.length === 0) throw new ConfigError("statement reconciliation refused: the statement carries no rows. A headline total is not evidence (dashboard aggregates are eventually consistent); export per-request rows or per-component categories and reconcile those");
+	const billable = [];
+	let usageUnknownRows = 0;
+	for (const row of invoice.rows) {
+		if (row.usageUnknown === true) {
+			usageUnknownRows += 1;
+			continue;
+		}
+		billable.push(row);
+	}
+	let covered = billable;
+	let matchedRows;
+	let unmatchedRows = 0;
+	const unmatchedIdSample = [];
+	let statementOnlyRows = 0;
+	const statementOnlyIdSample = [];
+	let statementTotalUsd;
+	let statementComponents;
+	let tokenMismatches = 0;
+	const tokenMismatchSample = [];
+	const rowsWithResponseId = billable.filter((row) => row.responseId !== void 0).length;
+	if (statement.kind === "requests") {
+		const byId = /* @__PURE__ */ new Map();
+		let carriesAnything = false;
+		for (const row of statement.rows) {
+			if (row.responseId === "") throw new ConfigError("statement reconciliation refused: a per-request export row has no response id, the join key; normalize the export or reconcile per-component categories instead");
+			if (byId.has(row.responseId)) throw new ConfigError(`statement reconciliation refused: duplicate response id '${row.responseId}' in the export makes the join ambiguous`);
+			byId.set(row.responseId, row);
+			if (row.usd !== void 0 || row.componentsUsd !== void 0 || row.usage !== void 0) carriesAnything = true;
+		}
+		if (!carriesAnything) throw new ConfigError("statement reconciliation refused: no export row carries dollars, components, or usage; there is nothing to reconcile against");
+		const matched = [];
+		const matchedStatement = /* @__PURE__ */ new Set();
+		for (const row of billable) {
+			const hit = row.responseId === void 0 ? void 0 : byId.get(row.responseId);
+			if (hit === void 0) {
+				unmatchedRows += 1;
+				if (row.responseId !== void 0 && unmatchedIdSample.length < SAMPLE_CAP) unmatchedIdSample.push(row.responseId);
+				continue;
+			}
+			matchedStatement.add(hit.responseId);
+			matched.push(row);
+			if (hit.usage !== void 0) {
+				const pairs = [
+					[
+						"inputTokens",
+						hit.usage.inputTokens,
+						row.usage.inputTokens
+					],
+					[
+						"cachedInputTokens",
+						hit.usage.cachedInputTokens,
+						row.usage.cacheReadTokens
+					],
+					[
+						"cacheWriteTokens",
+						hit.usage.cacheWriteTokens,
+						row.usage.cacheWriteTokens
+					],
+					[
+						"outputTokens",
+						hit.usage.outputTokens,
+						row.usage.outputTokens
+					]
+				];
+				for (const [field, statementValue, ours] of pairs) if (statementValue !== void 0 && statementValue !== ours) {
+					tokenMismatches += 1;
+					if (tokenMismatchSample.length < SAMPLE_CAP) tokenMismatchSample.push({
+						responseId: hit.responseId,
+						field,
+						ours,
+						statement: statementValue
+					});
+				}
+			}
+		}
+		for (const row of statement.rows) if (!matchedStatement.has(row.responseId)) {
+			statementOnlyRows += 1;
+			if (statementOnlyIdSample.length < SAMPLE_CAP) statementOnlyIdSample.push(row.responseId);
+		}
+		covered = matched;
+		matchedRows = matched.length;
+		let totalSeen = false;
+		let total = 0;
+		statementComponents = /* @__PURE__ */ new Map();
+		for (const row of statement.rows) {
+			if (!matchedStatement.has(row.responseId)) continue;
+			if (row.usd !== void 0) {
+				totalSeen = true;
+				total += row.usd;
+			}
+			if (row.componentsUsd !== void 0) {
+				const model = row.model ?? "";
+				const sums = statementComponents.get(model) ?? {};
+				for (const component of COMPONENTS) {
+					const usd = row.componentsUsd[component];
+					if (usd !== void 0) sums[component] = (sums[component] ?? 0) + usd;
+				}
+				statementComponents.set(model, sums);
+			}
+		}
+		if (totalSeen) statementTotalUsd = total;
+		if (statementComponents.size === 0) statementComponents = void 0;
+	} else {
+		statementComponents = /* @__PURE__ */ new Map();
+		let total = 0;
+		for (const row of statement.rows) {
+			const sums = statementComponents.get(row.model) ?? {};
+			sums[row.component] = (sums[row.component] ?? 0) + row.usd;
+			statementComponents.set(row.model, sums);
+			total += row.usd;
+		}
+		statementTotalUsd = total;
+		matchedRows = billable.length;
+	}
+	const ourByModel = /* @__PURE__ */ new Map();
+	const unpricedModels = /* @__PURE__ */ new Set();
+	let ourUsd = 0;
+	for (const row of covered) {
+		const model = modelOf(row.servedBy);
+		const pricing = options.pricingOf(row.servedBy);
+		if (pricing === void 0) {
+			unpricedModels.add(model);
+			continue;
+		}
+		const parts = priceComponentsOf(pricing, row.usage);
+		const sums = ourByModel.get(model) ?? emptySums();
+		const byName = [
+			["input", parts.input],
+			["cached-input", parts.cachedInput],
+			["cache-write", parts.cacheWrite],
+			["output", parts.output]
+		];
+		for (const [component, part] of byName) {
+			sums.tokens[component] += part.tokens;
+			sums.usd[component] += part.usd;
+		}
+		ourByModel.set(model, sums);
+	}
+	for (const sums of ourByModel.values()) for (const component of COMPONENTS) ourUsd += sums.usd[component];
+	if (statement.kind === "categories") {
+		for (const model of statementComponents?.keys() ?? []) if (!ourByModel.has(model) && !unpricedModels.has(model)) {
+			statementOnlyRows += 1;
+			if (statementOnlyIdSample.length < SAMPLE_CAP) statementOnlyIdSample.push(model);
+		}
+	}
+	const components = [];
+	const ourLines = statement.kind === "requests" && statementComponents?.has("") === true ? /* @__PURE__ */ new Map([["", [...ourByModel.values()].reduce((acc, sums) => {
+		for (const component of COMPONENTS) {
+			acc.tokens[component] += sums.tokens[component];
+			acc.usd[component] += sums.usd[component];
+		}
+		return acc;
+	}, emptySums())]]) : ourByModel;
+	for (const model of [...ourLines.keys()].sort()) {
+		const sums = ourLines.get(model);
+		if (sums === void 0) continue;
+		for (const component of COMPONENTS) {
+			const ourTokens = sums.tokens[component];
+			const ours = sums.usd[component];
+			const statementUsd = statementComponents?.get(model)?.[component];
+			const line = {
+				model,
+				component,
+				ourTokens,
+				ourUsd: ours,
+				divergent: false
+			};
+			if (statementUsd !== void 0) {
+				line.statementUsd = statementUsd;
+				line.deltaUsd = statementUsd - ours;
+				line.divergent = Math.abs(line.deltaUsd) > componentToleranceUsd;
+			}
+			if (ourTokens > 0) {
+				line.effectiveUsdPerMTok = ours / (ourTokens / 1e6);
+				if (statementUsd !== void 0) line.impliedUsdPerMTok = statementUsd / (ourTokens / 1e6);
+			}
+			components.push(line);
+		}
+	}
+	const divergent = components.filter((line) => line.divergent).sort((a, b) => Math.abs(b.deltaUsd ?? 0) - Math.abs(a.deltaUsd ?? 0));
+	const totalsDelta = statementTotalUsd === void 0 ? void 0 : statementTotalUsd - ourUsd;
+	const totalsDivergent = statementComponents === void 0 && totalsDelta !== void 0 && Math.abs(totalsDelta) > totalToleranceUsd;
+	const coverageComplete = unmatchedRows === 0 && statementOnlyRows === 0 && unpricedModels.size === 0 && (statement.kind === "categories" || matchedRows === rowsWithResponseId && rowsWithResponseId === billable.length) && (statement.kind === "requests" || components.every((line) => line.statementUsd !== void 0));
+	let verdict;
+	if (divergent.length > 0 || totalsDivergent) verdict = "divergence";
+	else if (matchedRows === 0) verdict = "no-overlap";
+	else if (!coverageComplete) verdict = "partial-coverage";
+	else verdict = "match";
+	return {
+		mode: statement.kind,
+		coverage: {
+			billableRows: billable.length,
+			rowsWithResponseId,
+			matchedRows,
+			unmatchedRows,
+			unmatchedIdSample,
+			statementOnlyRows,
+			statementOnlyIdSample,
+			complete: coverageComplete
+		},
+		totals: {
+			ourUsd,
+			...statementTotalUsd === void 0 ? {} : { statementUsd: statementTotalUsd },
+			...totalsDelta === void 0 ? {} : { deltaUsd: totalsDelta }
+		},
+		components,
+		divergent,
+		tokenMismatches,
+		tokenMismatchSample,
+		unpricedModels: [...unpricedModels].sort(),
+		usageUnknownRows,
+		componentToleranceUsd,
+		verdict
+	};
+}
+//#endregion
+export { CONSERVATIVE_COMPATIBLE_CAPS, OPENAI_MODELS, OPENAI_PRICING, OpenAiIdMap, auditV1190CacheJournal, buildChatCompletionsParams, buildResponsesParams, mapChatCompletionsStream, mapOpenAiEffort, mapResponsesStream, normalizeOpenAiUsage, openAiErrorToWire, openAiModelInfo, openai, openaiCompatible, reconcileStatement, undoV1190CacheDoubleCount };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/openai",
-  "version": "1.117.0",
+  "version": "1.119.0",
   "description": "Rulvar first-class provider adapter for the OpenAI Responses API, plus the openaiCompatible factory.",
   "type": "module",
   "license": "Apache-2.0",
@@ -23,13 +23,13 @@
   },
   "dependencies": {
     "openai": "^6.49.0",
-    "@rulvar/core": "1.117.0"
+    "@rulvar/core": "1.119.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",
     "tsdown": "^0.22.14",
     "typescript": "~6.0.3",
-    "@rulvar/testing": "1.117.0"
+    "@rulvar/testing": "1.119.0"
   },
   "repository": {
     "type": "git",