@rulvar/openai 1.133.0 → 1.134.0

package/dist/index.d.ts

@@ -277,6 +277,18 @@ interface StatementReconciliation {
   usageUnknownRows: number;
   componentToleranceUsd: number;
   verdict: "match" | "divergence" | "partial-coverage" | "no-overlap";
+  /**
+  * The settlement-grade composite, first class (RV1006): true exactly
+  * when the verdict is 'match' AND coverage is complete AND no row's
+  * usage is unknown AND no model went unpriced. A 'match' alone is
+  * not enough: an export can cover every KNOWN row to the cent while
+  * a usage-unknown attempt still holds unattributed money, and a safe
+  * consumer must not assemble this predicate by hand. The last two
+  * conditions overlap today's verdict semantics deliberately: the
+  * predicate states the full contract so it cannot drift apart from
+  * a future verdict refinement.
+  */
+  settleable: boolean;
 }
 /**
 * Reconciles the invoice against a normalized provider export. Pure and
@@ -285,9 +297,12 @@ interface StatementReconciliation {
 * headline total with no rows), a request row without a response id, a
 * 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).
+* negative dollar amount, any non-integer or negative token count, a
+* non-finite or negative tolerance (RV903: a statement that cannot
+* be summed must refuse loudly, never verdict 'match' on NaN totals),
+* or a row whose usd and componentsUsd contradict each other beyond
+* totalToleranceUsd (RV1005: an internally contradictory export is
+* not evidence either).
 */
 declare function reconcileStatement(invoice: {
   rows: readonly InvoiceRow[];

package/dist/index.js

@@ -1108,9 +1108,12 @@ function assertTokenCount(where, field, value) {
 * headline total with no rows), a request row without a response id, a
 * 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).
+* negative dollar amount, any non-integer or negative token count, a
+* non-finite or negative tolerance (RV903: a statement that cannot
+* be summed must refuse loudly, never verdict 'match' on NaN totals),
+* or a row whose usd and componentsUsd contradict each other beyond
+* totalToleranceUsd (RV1005: an internally contradictory export is
+* not evidence either).
 */
 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`);
@@ -1136,6 +1139,8 @@ function reconcileStatement(invoice, statement, options) {
 	const statementOnlyIdSample = [];
 	let statementTotalUsd;
 	let statementComponents;
+	let matchedStatementRows = 0;
+	let matchedUsdRows = 0;
 	let tokenMismatches = 0;
 	let partialOverlap = false;
 	const tokenMismatchSample = [];
@@ -1148,9 +1153,18 @@ function reconcileStatement(invoice, statement, options) {
 			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.componentsUsd !== void 0) {
+				let componentsSum = 0;
+				let componentsSeen = 0;
+				for (const component of COMPONENTS) {
+					const usd = row.componentsUsd[component];
+					if (usd !== void 0) {
+						assertStatementUsd(where, `componentsUsd.${component}`, usd);
+						componentsSum += usd;
+						componentsSeen += 1;
+					}
+				}
+				if (row.usd !== void 0 && componentsSeen > 0 && Math.abs(row.usd - componentsSum) > totalToleranceUsd) throw new ConfigError(`statement reconciliation refused: ${where} carries usd ${String(row.usd)} and a component split summing to ${String(componentsSum)}, claims that contradict each other beyond the ${String(totalToleranceUsd)} totals tolerance; an export whose own total disagrees with its own components is not evidence: normalize it to one dollar claim per row or fix the export`);
 			}
 			if (row.usage !== void 0) for (const field of [
 				"inputTokens",
@@ -1222,7 +1236,9 @@ function reconcileStatement(invoice, statement, options) {
 		statementComponents = /* @__PURE__ */ new Map();
 		for (const row of statement.rows) {
 			if (!matchedStatement.has(row.responseId)) continue;
+			matchedStatementRows += 1;
 			if (row.usd !== void 0) {
+				matchedUsdRows += 1;
 				totalSeen = true;
 				total += row.usd;
 			}
@@ -1318,7 +1334,7 @@ function reconcileStatement(invoice, statement, options) {
 	}
 	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 totalsDivergent = unpricedModels.size === 0 && (statement.kind === "requests" ? matchedUsdRows === matchedStatementRows : statementOnlyRows === 0 && components.every((line) => line.statementUsd !== 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;
@@ -1350,7 +1366,8 @@ function reconcileStatement(invoice, statement, options) {
 		unpricedModels: [...unpricedModels].sort(),
 		usageUnknownRows,
 		componentToleranceUsd,
-		verdict
+		verdict,
+		settleable: verdict === "match" && coverageComplete && usageUnknownRows === 0 && unpricedModels.size === 0
 	};
 }
 //#endregion

package/package.json

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