@rulvar/openai 1.19.0 → 1.21.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import OpenAI, { ClientOptions } from "openai";
-import { CanonicalId, ChatEvent, ChatRequest, Effort, ModelCaps, PriceTable, ProviderAdapter, Usage, WireError } from "@rulvar/core";
+import { CanonicalId, ChatEvent, ChatRequest, Effort, JournalEntry, ModelCaps, ModelRef, PriceTable, ProviderAdapter, Usage, WireError } from "@rulvar/core";
 
 //#region src/caps.d.ts
 interface OpenAiModelInfo {
@@ -8,11 +8,13 @@ interface OpenAiModelInfo {
   /** Reasoning models reject non-default sampling parameters. */
   reasoning: boolean;
   /**
-  * The model accepts wire `reasoning.effort: "max"` (GPT-5.6 Sol per
-  * the official model docs). When false, canonical max downmaps to
-  * wire xhigh; the downmap is recorded in providerMetadata and the
-  * journal identity keeps max, so caps accept the full canonical set
-  * either way.
+  * The model accepts wire `reasoning.effort: "max"` (the whole GPT-5.6
+  * family per the official model guidance, each sibling verified live
+  * 2026-07-18). When false, canonical max downmaps to wire xhigh; the
+  * downmap is recorded in providerMetadata and the journal identity
+  * keeps max, so caps accept the full canonical set either way. Flip
+  * this to true ONLY on a per-model live verification, never from the
+  * family page alone.
   */
   wireMaxEffort: boolean;
 }
@@ -108,6 +110,41 @@ interface OpenAiCompatibleConfig {
 /** Creates a Chat Completions dialect adapter for a compatible endpoint. */
 declare function openaiCompatible(cfg: OpenAiCompatibleConfig): ProviderAdapter;
 //#endregion
+//#region src/audit.d.ts
+/**
+* The exact inverse of the v1.19.0 double count for one usage:
+* subtracts `cacheWriteTokens` back out of `inputTokens` and leaves
+* every other field untouched. A usage without cache writes is returned
+* unchanged (v1.19.0 recorded those correctly). Throws a typed
+* ConfigError when the arithmetic cannot be the v1.19.0 shape (the
+* recorded input has no room for the subtraction), which means the
+* usage was NOT recorded by the affected adapter; do not guess.
+*/
+declare function undoV1190CacheDoubleCount(usage: Usage): Usage;
+/** One journal's sidecar reconciliation; see auditV1190CacheJournal. */
+interface V1190CacheAudit {
+  /** Entries whose usage carried the affected shape and were inverted. */
+  affectedEntries: number;
+  /** The fold as recorded (what reports and budgets saw). */
+  recordedUsd: number;
+  /** The fold with every affected usage inverted to the true wire shape. */
+  correctedUsd: number;
+}
+/**
+* Folds a journal twice with the SAME price function: once as recorded
+* and once with every affected OpenAI usage passed through
+* `undoV1190CacheDoubleCount`, returning both totals and the affected
+* entry count. An entry (or per-model slice) counts as affected when it
+* was served by the `openai` adapter, carries cache writes, and has no
+* `usageSemantics` stamp; stamped entries are already correct and fold
+* identically in both totals. The journal itself is never touched.
+* `recordedUsd - correctedUsd` is the exact overcharge IF the journal
+* was recorded by v1.19.0; for a v1.20.0 journal the same shape folds
+* to a smaller `correctedUsd` that does NOT correspond to any real
+* charge, so version provenance stays the caller's responsibility.
+*/
+declare function auditV1190CacheJournal(entries: readonly JournalEntry[], priceUsd: (servedBy: ModelRef, usage: Usage) => number | undefined): V1190CacheAudit;
+//#endregion
 //#region src/wire.d.ts
 /** Bijective canonical-to-wire (call_*) id map. */
 declare class OpenAiIdMap {
@@ -121,9 +158,10 @@ declare class OpenAiIdMap {
 /**
 * Canonical-to-wire effort: low through xhigh pass through. Canonical
 * max passes through unchanged on models whose caps declare wire max
-* support (GPT-5.6 Sol); elsewhere it downmaps to xhigh (documented
-* lossy; recorded in providerMetadata). Provider 'none' is reachable
-* only via providerOptions.openai.reasoningEffort.
+* support (the whole GPT-5.6 family, each sibling verified live
+* 2026-07-18; v1.20.0 review P2-3); elsewhere it downmaps to xhigh
+* (documented lossy; recorded in providerMetadata). Provider 'none' is
+* reachable only via providerOptions.openai.reasoningEffort.
 */
 declare function mapOpenAiEffort(effort: Effort, options?: {
   wireMaxEffort?: boolean;
@@ -150,14 +188,29 @@ type ResponsesStreamEvent = Record<string, unknown> & {
 };
 /**
 * Normalizes Responses usage into the canonical Usage invariant, where
-* `inputTokens` is the FULL prompt: wire `input_tokens` already includes
-* cached READS, while cache WRITE tokens arrive SEPARATELY in
-* `input_tokens_details.cache_write_tokens` (GPT-5.6 and later families;
-* they bill at the 1.25x write premium, and earlier families report no
-* field and pay no premium). Dropping the field lost the whole write
-* charge and weakened the budget guard (v1.18.0 review P1-2), so writes
-* are added into `inputTokens` and surfaced as `cacheWriteTokens` for
-* the premium rate, exactly mirroring the Anthropic adapter's mapping.
+* `inputTokens` is the FULL prompt. On the OpenAI wire `input_tokens`
+* is ALREADY that full count: `input_tokens_details.cached_tokens` and
+* `input_tokens_details.cache_write_tokens` (GPT-5.6 and later
+* families) are priced SUBSETS of it, never additional tokens, so both
+* pass through untouched and nothing is added. Verified on the live
+* wire 2026-07-18: two identical long prompts report the SAME
+* `input_tokens` while the details flip from write to read, and
+* `total_tokens` equals `input_tokens + output_tokens` on both calls.
+* Adding writes on top (the v1.19.0 reading of the field) double-billed
+* every written token at 1x + 1.25x and inflated budget debits
+* (v1.19.0 review P1-1). Contrast with the Anthropic adapter, whose
+* wire genuinely EXCLUDES both cache counts from `input_tokens`, so
+* that adapter adds them; the two wires differ, the canonical Usage
+* invariant does not.
+*
+* Numeric hygiene is deliberately NOT this function's job: any `number`
+* the wire (or an injected client) reports passes through, and the core
+* enforces the full telemetry invariant at the adapter boundary for
+* every adapter uniformly, failing the call loud on non-finite,
+* negative, or fractional counts while accounting only sanitized values
+* (`usageViolations`/`sanitizeUsage` in @rulvar/core; v1.20.0 review
+* P1-1). Real wires report whole nonnegative integers; a violation here
+* means a broken transport, never plausible provider data.
 */
 declare function normalizeOpenAiUsage(raw: Record<string, unknown> | undefined): Usage;
 /**
@@ -189,4 +242,4 @@ declare function buildChatCompletionsParams(req: ChatRequest, ids: OpenAiIdMap):
 */
 declare function mapChatCompletionsStream(stream: AsyncIterable<Record<string, unknown>>, ids: OpenAiIdMap): 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, buildChatCompletionsParams, buildResponsesParams, mapChatCompletionsStream, mapOpenAiEffort, mapResponsesStream, normalizeOpenAiUsage, openAiErrorToWire, openAiModelInfo, openai, openaiCompatible };
+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 };

package/dist/index.js

@@ -1,5 +1,5 @@
 import OpenAI from "openai";
-import { ConfigError, createCanonicalIdMinter, isStrictCompatibleSchema } from "@rulvar/core";
+import { ConfigError, createCanonicalIdMinter, entryUsageSlices, isStrictCompatibleSchema } from "@rulvar/core";
 //#region src/caps.ts
 const REASONING_EFFORTS = [
 	"low",
@@ -34,7 +34,13 @@ const GPT_56_TIERS = [{
 * .../gpt-5.6-terra, .../gpt-5.6-luna; rates verified 2026-07-18). 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. Only Sol accepts wire reasoning effort `max`.
+* uncached input. All three accept wire reasoning effort `max`
+* (v1.20.0 review P2-3; verified live per sibling 2026-07-18: a
+* Responses call with `reasoning.effort: "max"` returns HTTP 200 with
+* the effort echoed on Terra and Luna alike, and the API's own 400
+* validator for an invalid effort enumerates `max` among the supported
+* values, so acceptance is enforcement, not silence). Earlier families
+* keep the conservative downmap until verified the same way.
 */
 const GPT_56_SOL = responses(105e4, 128e3, {
 	inputUsdPerMTok: 5,
@@ -52,14 +58,14 @@ const OPENAI_MODELS = {
 		cacheReadUsdPerMTok: .25,
 		cacheWriteUsdPerMTok: 3.125,
 		tiers: GPT_56_TIERS
-	}),
+	}, { wireMaxEffort: true }),
 	"gpt-5.6-luna": responses(105e4, 128e3, {
 		inputUsdPerMTok: 1,
 		outputUsdPerMTok: 6,
 		cacheReadUsdPerMTok: .1,
 		cacheWriteUsdPerMTok: 1.25,
 		tiers: GPT_56_TIERS
-	}),
+	}, { wireMaxEffort: true }),
 	"gpt-5.6": GPT_56_SOL,
 	"gpt-5.5": responses(4e5, 128e3, {
 		inputUsdPerMTok: 5,
@@ -168,9 +174,10 @@ var OpenAiIdMap = class {
 /**
 * Canonical-to-wire effort: low through xhigh pass through. Canonical
 * max passes through unchanged on models whose caps declare wire max
-* support (GPT-5.6 Sol); elsewhere it downmaps to xhigh (documented
-* lossy; recorded in providerMetadata). Provider 'none' is reachable
-* only via providerOptions.openai.reasoningEffort.
+* support (the whole GPT-5.6 family, each sibling verified live
+* 2026-07-18; v1.20.0 review P2-3); elsewhere it downmaps to xhigh
+* (documented lossy; recorded in providerMetadata). Provider 'none' is
+* reachable only via providerOptions.openai.reasoningEffort.
 */
 function mapOpenAiEffort(effort, options) {
 	if (effort === "max" && options?.wireMaxEffort !== true) return {
@@ -298,25 +305,58 @@ function buildResponsesParams(req, ids, options) {
 	};
 }
 /**
+* Clamps the cache detail counts into the subset domain the pricing
+* fold relies on (`reads + writes <= input`, everything nonnegative).
+* The provider contract already guarantees it; impossible telemetry is
+* clamped rather than rejected because a rejection would discard PAID
+* evidence, and clamping is the conservative direction for the budget:
+* dropped detail tokens price at the FULL input rate instead of the
+* cache-read discount. Reads keep priority over writes, so a violation
+* shrinks the write premium, never the base charge.
+*/
+function clampCacheSubsets(inputTokens, rawRead, rawWrite) {
+	const cacheReadTokens = Math.min(Math.max(0, rawRead), Math.max(0, inputTokens));
+	return {
+		cacheReadTokens,
+		cacheWriteTokens: Math.min(Math.max(0, rawWrite), Math.max(0, inputTokens) - cacheReadTokens)
+	};
+}
+/**
 * Normalizes Responses usage into the canonical Usage invariant, where
-* `inputTokens` is the FULL prompt: wire `input_tokens` already includes
-* cached READS, while cache WRITE tokens arrive SEPARATELY in
-* `input_tokens_details.cache_write_tokens` (GPT-5.6 and later families;
-* they bill at the 1.25x write premium, and earlier families report no
-* field and pay no premium). Dropping the field lost the whole write
-* charge and weakened the budget guard (v1.18.0 review P1-2), so writes
-* are added into `inputTokens` and surfaced as `cacheWriteTokens` for
-* the premium rate, exactly mirroring the Anthropic adapter's mapping.
+* `inputTokens` is the FULL prompt. On the OpenAI wire `input_tokens`
+* is ALREADY that full count: `input_tokens_details.cached_tokens` and
+* `input_tokens_details.cache_write_tokens` (GPT-5.6 and later
+* families) are priced SUBSETS of it, never additional tokens, so both
+* pass through untouched and nothing is added. Verified on the live
+* wire 2026-07-18: two identical long prompts report the SAME
+* `input_tokens` while the details flip from write to read, and
+* `total_tokens` equals `input_tokens + output_tokens` on both calls.
+* Adding writes on top (the v1.19.0 reading of the field) double-billed
+* every written token at 1x + 1.25x and inflated budget debits
+* (v1.19.0 review P1-1). Contrast with the Anthropic adapter, whose
+* wire genuinely EXCLUDES both cache counts from `input_tokens`, so
+* that adapter adds them; the two wires differ, the canonical Usage
+* invariant does not.
+*
+* Numeric hygiene is deliberately NOT this function's job: any `number`
+* the wire (or an injected client) reports passes through, and the core
+* enforces the full telemetry invariant at the adapter boundary for
+* every adapter uniformly, failing the call loud on non-finite,
+* negative, or fractional counts while accounting only sanitized values
+* (`usageViolations`/`sanitizeUsage` in @rulvar/core; v1.20.0 review
+* P1-1). Real wires report whole nonnegative integers; a violation here
+* means a broken transport, never plausible provider data.
 */
 function normalizeOpenAiUsage(raw) {
 	const inputDetails = raw?.input_tokens_details;
 	const outputDetails = raw?.output_tokens_details;
-	const cacheWrite = typeof inputDetails?.cache_write_tokens === "number" ? inputDetails.cache_write_tokens : 0;
+	const inputTokens = typeof raw?.input_tokens === "number" ? raw.input_tokens : 0;
+	const clamped = clampCacheSubsets(inputTokens, typeof inputDetails?.cached_tokens === "number" ? inputDetails.cached_tokens : 0, typeof inputDetails?.cache_write_tokens === "number" ? inputDetails.cache_write_tokens : 0);
 	const usage = {
-		inputTokens: (typeof raw?.input_tokens === "number" ? raw.input_tokens : 0) + cacheWrite,
+		inputTokens,
 		outputTokens: typeof raw?.output_tokens === "number" ? raw.output_tokens : 0,
-		cacheReadTokens: typeof inputDetails?.cached_tokens === "number" ? inputDetails.cached_tokens : 0,
-		cacheWriteTokens: cacheWrite
+		cacheReadTokens: clamped.cacheReadTokens,
+		cacheWriteTokens: clamped.cacheWriteTokens
 	};
 	const reasoning = outputDetails?.reasoning_tokens;
 	if (typeof reasoning === "number" && reasoning > 0) usage.reasoningTokens = reasoning;
@@ -644,12 +684,13 @@ async function* mapChatCompletionsStream(stream, ids) {
 		const chunkUsage = chunk.usage;
 		if (chunkUsage !== void 0 && chunkUsage !== null) {
 			const promptDetails = chunkUsage.prompt_tokens_details;
-			const cacheWrite = typeof promptDetails?.cache_write_tokens === "number" ? promptDetails.cache_write_tokens : 0;
+			const promptTokens = typeof chunkUsage.prompt_tokens === "number" ? chunkUsage.prompt_tokens : 0;
+			const clamped = clampCacheSubsets(promptTokens, typeof promptDetails?.cached_tokens === "number" ? promptDetails.cached_tokens : 0, typeof promptDetails?.cache_write_tokens === "number" ? promptDetails.cache_write_tokens : 0);
 			usage = {
-				inputTokens: (typeof chunkUsage.prompt_tokens === "number" ? chunkUsage.prompt_tokens : 0) + cacheWrite,
+				inputTokens: promptTokens,
 				outputTokens: typeof chunkUsage.completion_tokens === "number" ? chunkUsage.completion_tokens : 0,
-				cacheReadTokens: typeof promptDetails?.cached_tokens === "number" ? promptDetails.cached_tokens : 0,
-				cacheWriteTokens: cacheWrite
+				cacheReadTokens: clamped.cacheReadTokens,
+				cacheWriteTokens: clamped.cacheWriteTokens
 			};
 		}
 	}
@@ -715,6 +756,7 @@ function openai(options = {}) {
 	return {
 		id: "openai",
 		provider: "openai",
+		usageSemantics: "openai-cache-subsets-v2",
 		caps(model) {
 			return openAiModelInfo(model).caps;
 		},
@@ -785,6 +827,7 @@ function openaiCompatible(cfg) {
 	return {
 		id: cfg.id,
 		provider: "openai",
+		usageSemantics: "openai-cache-subsets-v2",
 		caps(model) {
 			const overrides = cfg.caps?.(model);
 			return overrides === void 0 ? CONSERVATIVE_COMPATIBLE_CAPS : {
@@ -810,4 +853,69 @@ function openaiCompatible(cfg) {
 	};
 }
 //#endregion
-export { CONSERVATIVE_COMPATIBLE_CAPS, OPENAI_MODELS, OPENAI_PRICING, OpenAiIdMap, buildChatCompletionsParams, buildResponsesParams, mapChatCompletionsStream, mapOpenAiEffort, mapResponsesStream, normalizeOpenAiUsage, openAiErrorToWire, openAiModelInfo, openai, openaiCompatible };
+//#region src/audit.ts
+/**
+* The exact inverse of the v1.19.0 double count for one usage:
+* subtracts `cacheWriteTokens` back out of `inputTokens` and leaves
+* every other field untouched. A usage without cache writes is returned
+* unchanged (v1.19.0 recorded those correctly). Throws a typed
+* ConfigError when the arithmetic cannot be the v1.19.0 shape (the
+* recorded input has no room for the subtraction), which means the
+* usage was NOT recorded by the affected adapter; do not guess.
+*/
+function undoV1190CacheDoubleCount(usage) {
+	if (usage.cacheWriteTokens <= 0) return usage;
+	const trueInput = usage.inputTokens - usage.cacheWriteTokens;
+	if (trueInput < usage.cacheReadTokens + usage.cacheWriteTokens) throw new ConfigError(`not a v1.19.0-inflated usage: subtracting cacheWriteTokens (${String(usage.cacheWriteTokens)}) out of inputTokens (${String(usage.inputTokens)}) leaves less than the cache subsets; this usage was not recorded by the affected adapter`);
+	return {
+		...usage,
+		inputTokens: trueInput
+	};
+}
+/**
+* Folds a journal twice with the SAME price function: once as recorded
+* and once with every affected OpenAI usage passed through
+* `undoV1190CacheDoubleCount`, returning both totals and the affected
+* entry count. An entry (or per-model slice) counts as affected when it
+* was served by the `openai` adapter, carries cache writes, and has no
+* `usageSemantics` stamp; stamped entries are already correct and fold
+* identically in both totals. The journal itself is never touched.
+* `recordedUsd - correctedUsd` is the exact overcharge IF the journal
+* was recorded by v1.19.0; for a v1.20.0 journal the same shape folds
+* to a smaller `correctedUsd` that does NOT correspond to any real
+* charge, so version provenance stays the caller's responsibility.
+*/
+function auditV1190CacheJournal(entries, priceUsd) {
+	let affectedEntries = 0;
+	let recordedUsd = 0;
+	let correctedUsd = 0;
+	for (const entry of entries) {
+		let entryAffected = false;
+		for (const slice of entryUsageSlices(entry)) {
+			const recorded = priceUsd(slice.servedBy, slice.usage);
+			if (recorded === void 0) continue;
+			recordedUsd += recorded;
+			if (entry.usageSemantics === void 0 && slice.servedBy.startsWith("openai:") && slice.usage.cacheWriteTokens > 0) {
+				let corrected;
+				try {
+					corrected = undoV1190CacheDoubleCount(slice.usage);
+				} catch {
+					corrected = void 0;
+				}
+				if (corrected === void 0) correctedUsd += recorded;
+				else {
+					entryAffected = true;
+					correctedUsd += priceUsd(slice.servedBy, corrected) ?? 0;
+				}
+			} else correctedUsd += recorded;
+		}
+		if (entryAffected) affectedEntries += 1;
+	}
+	return {
+		affectedEntries,
+		recordedUsd,
+		correctedUsd
+	};
+}
+//#endregion
+export { CONSERVATIVE_COMPATIBLE_CAPS, OPENAI_MODELS, OPENAI_PRICING, OpenAiIdMap, auditV1190CacheJournal, buildChatCompletionsParams, buildResponsesParams, mapChatCompletionsStream, mapOpenAiEffort, mapResponsesStream, normalizeOpenAiUsage, openAiErrorToWire, openAiModelInfo, openai, openaiCompatible, undoV1190CacheDoubleCount };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/openai",
-  "version": "1.19.0",
+  "version": "1.21.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.45.0",
-    "@rulvar/core": "1.19.0"
+    "@rulvar/core": "1.21.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.0",
     "tsdown": "^0.22.3",
     "typescript": "~6.0.3",
-    "@rulvar/testing": "1.19.0"
+    "@rulvar/testing": "1.21.0"
   },
   "repository": {
     "type": "git",