@rulvar/openai 1.124.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

@@ -32,13 +32,19 @@ const GPT_56_TIERS = [{
 /**
 * GPT-5.6 Sol, Terra, and Luna are three sibling models, not snapshots
 * of one model (developers.openai.com/api/docs/models/gpt-5.6-sol,
-* .../gpt-5.6-terra, .../gpt-5.6-luna; rates verified 2026-07-18
-* against those pages, and CONFIRMED against the provider's own
-* billing categories on 2026-07-30, when the twelfth-experiment
-* statement reconciliation matched all eight per-model per-component
-* dashboard categories to the cent, which is why the family rows carry
-* ratesVerifiedAt '2026-07-30' (RV814); the weekly rates audit
-* re-verifies the three pages). All
+* .../gpt-5.6-terra, .../gpt-5.6-luna; the weekly rates audit
+* re-verifies the three pages). The family rows carry ratesVerifiedAt
+* '2026-07-31' (RV814): on that date every row was re-verified against
+* its documented model page, picking up the provider's 2026-07-30
+* price cut on Terra (0.8x across input, cached input, cache write,
+* and output) and Luna (0.2x across the same four) that the
+* thirteenth-experiment live audit caught as drift (RV911). Sol's
+* rates are unchanged and additionally remain billing-CONFIRMED by the
+* 2026-07-30 twelfth-experiment statement reconciliation, which
+* matched all eight per-model per-component dashboard categories to
+* the cent; the new Terra and Luna rates are docs-verified only, and
+* their billing truth is established by the next statement
+* reconciliation over saved exports, never assumed. All
 * three: prompts strictly above 272K input tokens price the FULL
 * request at 2x input and 1.5x output; cache writes bill at 1.25x
 * uncached input. All three accept wire reasoning effort `max`
@@ -55,26 +61,26 @@ const GPT_56_SOL = responses(105e4, 128e3, {
 	cacheReadUsdPerMTok: .5,
 	cacheWriteUsdPerMTok: 6.25,
 	tiers: GPT_56_TIERS,
-	ratesVerifiedAt: "2026-07-30"
+	ratesVerifiedAt: "2026-07-31"
 }, { wireMaxEffort: true });
 /** Static seed table of the current model set. */
 const OPENAI_MODELS = {
 	"gpt-5.6-sol": GPT_56_SOL,
 	"gpt-5.6-terra": responses(105e4, 128e3, {
-		inputUsdPerMTok: 2.5,
-		outputUsdPerMTok: 15,
-		cacheReadUsdPerMTok: .25,
-		cacheWriteUsdPerMTok: 3.125,
+		inputUsdPerMTok: 2,
+		outputUsdPerMTok: 12,
+		cacheReadUsdPerMTok: .2,
+		cacheWriteUsdPerMTok: 2.5,
 		tiers: GPT_56_TIERS,
-		ratesVerifiedAt: "2026-07-30"
+		ratesVerifiedAt: "2026-07-31"
 	}, { wireMaxEffort: true }),
 	"gpt-5.6-luna": responses(105e4, 128e3, {
-		inputUsdPerMTok: 1,
-		outputUsdPerMTok: 6,
-		cacheReadUsdPerMTok: .1,
-		cacheWriteUsdPerMTok: 1.25,
+		inputUsdPerMTok: .2,
+		outputUsdPerMTok: 1.2,
+		cacheReadUsdPerMTok: .02,
+		cacheWriteUsdPerMTok: .25,
 		tiers: GPT_56_TIERS,
-		ratesVerifiedAt: "2026-07-30"
+		ratesVerifiedAt: "2026-07-31"
 	}, { wireMaxEffort: true }),
 	"gpt-5.6": GPT_56_SOL,
 	"gpt-5.5": responses(4e5, 128e3, {
@@ -121,7 +127,7 @@ const OPENAI_MODELS = {
 * silent reinterpretation.
 */
 const OPENAI_PRICING = {
-	pricingVersion: "openai-2026-07-18-r2",
+	pricingVersion: "openai-2026-07-31",
 	models: (() => {
 		const models = {};
 		for (const [name, info] of Object.entries(OPENAI_MODELS)) if (info.caps.pricing !== void 0) models[`openai:${name}`] = info.caps.pricing;
@@ -1078,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;
@@ -1116,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;
 		}
@@ -1196,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);
@@ -1273,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.124.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.124.0"
+    "@rulvar/core": "1.126.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",
     "tsdown": "^0.22.14",
     "typescript": "~6.0.3",
-    "@rulvar/testing": "1.124.0"
+    "@rulvar/testing": "1.126.0"
   },
   "repository": {
     "type": "git",