@rulvar/openai 1.125.0 → 1.126.0

package/dist/index.d.ts

@@ -200,6 +200,20 @@ interface ReconcileStatementOptions {
   totalToleranceUsd?: number;
   /** Provider-side model name of a served ref; default strips the adapter prefix. */
   modelOf?: (servedBy: ModelRef) => string;
+  /**
+  * How provider-reported token counts weigh on the verdict (RV903).
+  * 'verdict' (default): any token disagreement between the export and
+  * our recorded usage is a divergence, because our counts ARE the
+  * provider's own wire-reported numbers, so an export that disagrees
+  * with them describes a different request than the wire served, and
+  * dollars derived from either cannot be trusted to mean the same
+  * thing. 'informational' preserves the pre-v1.126 dollar-only
+  * verdict for exports whose token semantics legitimately differ from
+  * the wire's (a different cache accounting, rounded aggregates):
+  * mismatches are still counted and sampled, but only dollar deltas
+  * decide.
+  */
+  tokenComparison?: "verdict" | "informational";
 }
 /** One (model, component) line of the reconciliation. */
 interface ComponentDelta {
@@ -244,7 +258,12 @@ interface StatementReconciliation {
   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). */
+  /**
+  * Token disagreements between the export and our recorded usage
+  * (requests mode). Under the default tokenComparison 'verdict' any
+  * mismatch makes the verdict 'divergence'; under 'informational' the
+  * count and sample still report, advisory only (RV903).
+  */
   tokenMismatches: number;
   tokenMismatchSample: Array<{
     responseId: string;
@@ -264,8 +283,11 @@ interface StatementReconciliation {
 * 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.
+* duplicate response id (an ambiguous join), a request export whose
+* rows carry neither dollars, components, nor usage, any non-finite or
+* negative dollar amount, any non-integer or negative token count, or
+* a non-finite or negative tolerance (RV903: a statement that cannot
+* be summed must refuse loudly, never verdict 'match' on NaN totals).
 */
 declare function reconcileStatement(invoice: {
   rows: readonly InvoiceRow[];

package/dist/index.js

@@ -1084,17 +1084,40 @@ const defaultModelOf = (servedBy) => {
 	return colon === -1 ? servedBy : servedBy.slice(colon + 1);
 };
 /**
+* A statement dollar amount must be a finite nonnegative number
+* (RV903). The thirteenth experiment's probe fed `usd: NaN` and got
+* verdict 'match' with NaN totals: NaN flowed through the sums and
+* `Math.abs(NaN) > tolerance` is false, so the divergence check
+* silently disarmed. Negative amounts are refused too: provider
+* credits and adjustments are real, but they are not per-request or
+* per-component BILLING evidence, and folding them into the join would
+* let an adjustment mask a rate divergence of the same size.
+*/
+function assertStatementUsd(where, field, value) {
+	if (!Number.isFinite(value)) throw new ConfigError(`statement reconciliation refused: ${where} carries ${field} ${String(value)}, which cannot be summed; a statement whose dollars are not finite is not evidence`);
+	if (value < 0) throw new ConfigError(`statement reconciliation refused: ${where} carries negative ${field} ${String(value)}; credits and adjustments reconcile separately, never as negative statement rows`);
+}
+/** A provider-reported token count must be a nonnegative integer (RV903). */
+function assertTokenCount(where, field, value) {
+	if (!Number.isInteger(value) || value < 0) throw new ConfigError(`statement reconciliation refused: ${where} carries ${field} ${String(value)}; provider-reported token counts are nonnegative integers`);
+}
+/**
 * 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.
+* duplicate response id (an ambiguous join), a request export whose
+* rows carry neither dollars, components, nor usage, any non-finite or
+* negative dollar amount, any non-integer or negative token count, or
+* a non-finite or negative tolerance (RV903: a statement that cannot
+* be summed must refuse loudly, never verdict 'match' on NaN totals).
 */
 function reconcileStatement(invoice, statement, options) {
+	for (const [name, value] of [["componentToleranceUsd", options.componentToleranceUsd], ["totalToleranceUsd", options.totalToleranceUsd]]) if (value !== void 0 && (!Number.isFinite(value) || value < 0)) throw new ConfigError(`statement reconciliation refused: ${name} ${String(value)} is not a finite nonnegative dollar tolerance`);
 	const componentToleranceUsd = options.componentToleranceUsd ?? .005;
 	const totalToleranceUsd = options.totalToleranceUsd ?? .01;
 	const modelOf = options.modelOf ?? defaultModelOf;
+	const tokenComparison = options.tokenComparison ?? "verdict";
 	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;
@@ -1122,6 +1145,21 @@ function reconcileStatement(invoice, statement, options) {
 		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`);
+			const where = `row '${row.responseId}'`;
+			if (row.usd !== void 0) assertStatementUsd(where, "usd", row.usd);
+			if (row.componentsUsd !== void 0) for (const component of COMPONENTS) {
+				const usd = row.componentsUsd[component];
+				if (usd !== void 0) assertStatementUsd(where, `componentsUsd.${component}`, usd);
+			}
+			if (row.usage !== void 0) for (const field of [
+				"inputTokens",
+				"cachedInputTokens",
+				"cacheWriteTokens",
+				"outputTokens"
+			]) {
+				const count = row.usage[field];
+				if (count !== void 0) assertTokenCount(where, `usage.${field}`, count);
+			}
 			byId.set(row.responseId, row);
 			if (row.usd !== void 0 || row.componentsUsd !== void 0 || row.usage !== void 0) carriesAnything = true;
 		}
@@ -1202,6 +1240,7 @@ function reconcileStatement(invoice, statement, options) {
 		statementComponents = /* @__PURE__ */ new Map();
 		let total = 0;
 		for (const row of statement.rows) {
+			assertStatementUsd(`category row '${row.model}' ${row.component}`, "usd", row.usd);
 			const sums = statementComponents.get(row.model) ?? {};
 			sums[row.component] = (sums[row.component] ?? 0) + row.usd;
 			statementComponents.set(row.model, sums);
@@ -1279,8 +1318,9 @@ function reconcileStatement(invoice, statement, options) {
 	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));
+	const tokensDivergent = tokenComparison === "verdict" && tokenMismatches > 0;
 	let verdict;
-	if (divergent.length > 0 || totalsDivergent) verdict = "divergence";
+	if (divergent.length > 0 || totalsDivergent || tokensDivergent) verdict = "divergence";
 	else if (matchedRows === 0) verdict = "no-overlap";
 	else if (!coverageComplete) verdict = "partial-coverage";
 	else verdict = "match";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/openai",
-  "version": "1.125.0",
+  "version": "1.126.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.125.0"
+    "@rulvar/core": "1.126.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",
     "tsdown": "^0.22.14",
     "typescript": "~6.0.3",
-    "@rulvar/testing": "1.125.0"
+    "@rulvar/testing": "1.126.0"
   },
   "repository": {
     "type": "git",