@bitkyc08/opencodex 2.86.0 → 2.87.0

package/src/usage/cost.ts

@@ -15,6 +15,7 @@ import {
   resolveMetadataProvider,
 } from "../generated/model-metadata";
 import type { AttemptTierOutcome, OcxUsage } from "../types";
+import type { PromptLengthPricing } from "../types/provider";
 import { canonicalFastTierMarker } from "../providers/fastwire";
 import { baseProviderLabel } from "../providers/label";
 import type { PersistedUsageAttempt, UsageStatus } from "./log";
@@ -79,6 +80,7 @@ export interface MatchedPrice {
   modelId: string;
   jawcodeProvider?: string;
   cost4: Cost4;
+  promptLengthPricing?: PromptLengthPricing;
   source: "jawcode" | "expected" | "user";
   sourceRef?: string;
   verifiedAt?: string;
@@ -97,6 +99,8 @@ export interface AttemptCostEstimate {
   priorityMultiplier?: number;
   /** Set when the published long-context rate was applied (#908). */
   contextTier?: ContextTierName;
+  /** User absolute rates selected for this attempt, separate from catalog tiers. */
+  customThresholdApplied?: true;
   /** The numeric estimate is a known floor because the exact Priority price is unavailable. */
   priorityLowerBound?: boolean;
 }
@@ -111,6 +115,8 @@ export interface CostEstimate {
   priorityMultiplier?: number;
   /** Set when any priced attempt used the published long-context rate (#908). */
   contextTier?: ContextTierName;
+  /** At least one request/attempt selected the user threshold rates. */
+  customThresholdApplied?: true;
   /** The aggregate is a known floor because every priced attempt is a lower bound. */
   priorityLowerBound?: boolean;
 }
@@ -343,6 +349,7 @@ function userOverlayMatch(
     modelId,
     cost4: overlay.cost4,
     source: "user",
+    ...(overlay.promptLengthPricing ? { promptLengthPricing: overlay.promptLengthPricing } : {}),
     sourceRef: overlay.source,
     verifiedAt: overlay.verifiedAt,
     status: "verified",
@@ -397,6 +404,15 @@ function vendorPrefixedCost(modelId: string): ReturnType<typeof findVendorCostBy
   return normalize(found.provider) === normalize(claimedVendor) ? found : undefined;
 }
 
+/**
+ * Only measured usage is priced. An `unreported` or `unsupported` row can still carry tokens — a
+ * combo whose first leg failed without usage keeps the second leg's — and pricing them reports an
+ * understated cost as if it were complete.
+ */
+export function isMeasuredStatus(usageStatus: UsageStatus): boolean {
+  return usageStatus === "reported" || usageStatus === "estimated";
+}
+
 function isEstimated(usage: OcxUsage, usageStatus: UsageStatus, priceStatus: ExpectedPriceStatus | "verified"): boolean {
   return usage.estimated === true || usageStatus === "estimated" || priceStatus === "verified-derived";
 }
@@ -475,8 +491,8 @@ function isConfirmedFast(tier?: ServiceTierInput): boolean {
 }
 
 /**
- * Apply the published long-context rate when raw prompt size crosses the vendor
- * threshold. Returns [effectiveCost4, tierName].
+ * Select user prompt-length rates, or apply the published context rule in automatic mode.
+ * Returns [effectiveCost4, catalogTier, priorityLowerBound, customThresholdApplied].
  *
  * `rawInputTokens` MUST be `usage.inputTokens` (total prompt size), never the
  * normalized billable input — normalization subtracts cache read/write, so a
@@ -486,13 +502,27 @@ function isConfirmedFast(tier?: ServiceTierInput): boolean {
  * API rows can stack the bands. xAI publishes neither a combined rate nor an exclusion,
  * so its long-context rate remains the known lower bound instead of inventing a stacked multiplier.
  */
-function applyContextTier(
+function applyPromptLengthPricing(
   cost4: Cost4,
   provider: string,
   modelId: string,
   rawInputTokens: number | undefined,
   tier?: ServiceTierInput,
-): [Cost4, ContextTierName | undefined, boolean] {
+  policy?: PromptLengthPricing,
+): [Cost4, ContextTierName | undefined, boolean, true?] {
+  // A user policy replaces the catalog rule on BOTH sides of its threshold.
+  // Keep custom provenance separate while honoring the published Priority relation.
+  if (policy?.mode === "flat") return [cost4, undefined, false];
+  if (policy?.mode === "custom") {
+    const crossed = rawInputTokens !== undefined && Number.isFinite(rawInputTokens)
+      && (policy.comparison === "gte"
+        ? rawInputTokens >= policy.thresholdTokens : rawInputTokens > policy.thresholdTokens);
+    if (!crossed) return [cost4, undefined, false];
+    const relation = findContextTier(provider, modelId)?.confirmedPriorityRelation;
+    const confirmedFast = isConfirmedFast(tier);
+    if (confirmedFast && relation === "exclusive") return [cost4, undefined, false];
+    return [policy.rates, undefined, confirmedFast && relation === "lower-bound", true];
+  }
   if (rawInputTokens === undefined) return [cost4, undefined, false];
   const rule = findContextTier(provider, modelId);
   if (!rule || !isLongContext(rule, rawInputTokens)) return [cost4, undefined, false];
@@ -520,9 +550,12 @@ function applyPriorityMultiplier(
   modelId: string,
   serviceTier?: ServiceTierInput,
   contextTier?: ContextTierName,
+  customThresholdApplied?: true,
 ): [Cost4, number] {
   if (canonicalFastTierMarker(tierScalar(serviceTier)) !== "priority") return [cost4, 1];
   if (contextTier && findContextTier(provider, modelId)?.confirmedPriorityRelation !== "stack") return [cost4, 1];
+  if (customThresholdApplied && isConfirmedFast(serviceTier)
+    && findContextTier(provider, modelId)?.confirmedPriorityRelation === "lower-bound") return [cost4, 1];
   const rule = findPriorityPricingRule(provider, modelId);
   if (rule?.requiresResponseConfirmation && !isConfirmedFast(serviceTier)) return [cost4, 1];
   const multiplier = rule?.multiplier ?? 1;
@@ -568,7 +601,7 @@ export function estimateAttemptCost(
   serviceTier?: ServiceTierInput,
   userOverlays: readonly ExpectedPriceOverlay[] = activeUserCostOverlays(),
 ): AttemptCostEstimate | null {
-  if (!attempt.usage) return null;
+  if (!isMeasuredStatus(attempt.usageStatus) || !attempt.usage) return null;
   const tokens = normalizeCostTokens(attempt.usage);
   if (!tokens) return null;
   const price = resolveMatchedPrice(attempt.provider, attempt.model, overlays, userOverlays, attempt);
@@ -576,11 +609,11 @@ export function estimateAttemptCost(
   const attemptServiceTier = attempt.tierOutcome
     ? serviceTierContextFromOutcome(attempt.tierOutcome)
     : serviceTier;
-  const [tieredCost4, contextTier, contextPriorityLowerBound] = applyContextTier(
-    price.cost4, price.provider, attempt.model, attempt.usage.inputTokens, attemptServiceTier,
+  const [tieredCost4, contextTier, contextPriorityLowerBound, customThresholdApplied] = applyPromptLengthPricing(
+    price.cost4, price.provider, attempt.model, attempt.usage.inputTokens, attemptServiceTier, price.promptLengthPricing,
   );
   const [effectiveCost4, multiplier] = applyPriorityMultiplier(
-    tieredCost4, price.provider, attempt.model, attemptServiceTier, contextTier,
+    tieredCost4, price.provider, attempt.model, attemptServiceTier, contextTier, customThresholdApplied,
   );
   const priorityLowerBound = contextPriorityLowerBound
     || isOpenRouterPriorityLowerBound(price.provider, attempt.tierOutcome);
@@ -594,6 +627,7 @@ export function estimateAttemptCost(
     estimated: isEstimated(attempt.usage, attempt.usageStatus, price.status),
     ...(multiplier !== 1 ? { priorityMultiplier: multiplier } : {}),
     ...(contextTier ? { contextTier } : {}),
+    ...(customThresholdApplied ? { customThresholdApplied } : {}),
     ...(priorityLowerBound ? { priorityLowerBound: true } : {}),
   };
 }
@@ -637,6 +671,7 @@ export function estimateComboCost(
       ? { priorityMultiplier: estimates.find(est => est.priorityMultiplier)?.priorityMultiplier }
       : {}),
     ...(estimates.some(est => est.contextTier) ? { contextTier: "long" as const } : {}),
+    ...(estimates.some(est => est.customThresholdApplied) ? { customThresholdApplied: true as const } : {}),
     ...(estimates.every(est => est.priorityLowerBound === true)
       ? { priorityLowerBound: true as const }
       : {}),
@@ -656,16 +691,16 @@ export function estimateRequestCost(
   overlays: readonly ExpectedPriceOverlay[] = EXPECTED_PRICE_OVERLAYS,
   userOverlays: readonly ExpectedPriceOverlay[] = activeUserCostOverlays(),
 ): CostEstimate | null {
-  if (!input.usage) return null;
+  if (!isMeasuredStatus(input.usageStatus) || !input.usage) return null;
   const tokens = normalizeCostTokens(input.usage);
   if (!tokens) return null;
   const price = resolveMatchedPrice(input.provider, input.model, overlays, userOverlays, input);
   if (!price) return null;
-  const [tieredCost4, contextTier, contextPriorityLowerBound] = applyContextTier(
-    price.cost4, price.provider, input.model, input.usage.inputTokens, input.serviceTier,
+  const [tieredCost4, contextTier, contextPriorityLowerBound, customThresholdApplied] = applyPromptLengthPricing(
+    price.cost4, price.provider, input.model, input.usage.inputTokens, input.serviceTier, price.promptLengthPricing,
   );
   const [effectiveCost4, multiplier] = applyPriorityMultiplier(
-    tieredCost4, price.provider, input.model, input.serviceTier, contextTier,
+    tieredCost4, price.provider, input.model, input.serviceTier, contextTier, customThresholdApplied,
   );
   const priorityLowerBound = contextPriorityLowerBound || isOpenRouterPriorityLowerBound(
     price.provider,
@@ -678,6 +713,7 @@ export function estimateRequestCost(
     estimated: isEstimated(input.usage, input.usageStatus, price.status),
     ...(multiplier !== 1 ? { priorityMultiplier: multiplier } : {}),
     ...(contextTier ? { contextTier } : {}),
+    ...(customThresholdApplied ? { customThresholdApplied } : {}),
     ...(priorityLowerBound ? { priorityLowerBound: true } : {}),
   };
 }

package/src/usage/expected-prices.ts

@@ -10,6 +10,7 @@ import { isAnthropicInstanceId } from "../providers/anthropic-instance-id";
 export function pricingFamilyProvider(provider: string): string {
   return isAnthropicInstanceId(provider) ? "anthropic" : provider;
 }
+import type { PromptLengthPricing } from "../types/provider";
 
 /**
  * Expected-price overlay for models whose jawcode cost rows are missing or all-zero
@@ -46,6 +47,8 @@ export interface ExpectedPriceOverlay {
   provider: string;
   modelId: string;
   cost4: Cost4;
+  /** User-owned context policy; catalog rows leave this absent. */
+  promptLengthPricing?: PromptLengthPricing;
   source: string;
   verifiedAt: string;
   status: ExpectedPriceStatus;

package/src/usage/ledger-retention.ts

@@ -22,6 +22,7 @@ import { closeSync, fstatSync, openSync, readSync, writeSync } from "node:fs";
 import { atomicWriteFileStreamed } from "../config/atomic-write";
 import {
   currentUsageLogRevision,
+  exactFileIdentity,
   usageLogIdentityKey,
   usageLogPath,
   usageLogRevisionKey,
@@ -127,7 +128,7 @@ export function enforceUsageLedgerSizeLimit(
   let sourceClosed = false;
   try {
     const opened = fstatSync(sourceFd);
-    if (Number(opened.size) !== captured.size || Number(opened.ino) !== captured.ino) {
+    if (Number(opened.size) !== captured.size || exactFileIdentity(sourceFd).ino !== captured.ino) {
       return { kind: "deferred", currentBytes: captured.size, reason: "revision-changed" };
     }
     const start = firstRowBoundary(sourceFd, Math.max(0, captured.size - target), captured.size);

package/src/usage/ledger-scanner.ts

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { closeSync, fstatSync, openSync, readSync } from "node:fs";
 import {
   currentUsageLogRevision,
+  exactFileIdentity,
   normalizePersistedUsageRow,
   usageLogIdentityKey,
   usageLogPath,
@@ -63,13 +64,13 @@ export class UsageLedgerRebuildRequiredError extends Error {
 
 function revisionFromStat(
   path: string,
+  fd: number,
   stat: ReturnType<typeof fstatSync>,
 ): UsageLogRevision {
   if (!stat.isFile()) throw new Error("usage log is not a regular file");
   return {
     path,
-    dev: Number(stat.dev),
-    ino: Number(stat.ino),
+    ...exactFileIdentity(fd),
     birthtimeMs: Number(stat.birthtimeMs),
     size: Number(stat.size),
     mtimeMs: Number(stat.mtimeMs),
@@ -276,7 +277,7 @@ export async function scanUsageLedgerCooperatively(
   let pendingLineBytes = 0;
 
   try {
-    const openedRevision = revisionFromStat(path, fstatSync(fd));
+    const openedRevision = revisionFromStat(path, fd, fstatSync(fd));
     const scanEnd = openedRevision.size;
     const openedIdentityKey = usageLogIdentityKey(openedRevision);
     if (options.expectedIdentityKey && options.expectedIdentityKey !== openedIdentityKey) {
@@ -391,7 +392,7 @@ export async function scanUsageLedgerCooperatively(
     }
 
     throwIfAborted(options.signal);
-    const endingRevision = revisionFromStat(path, fstatSync(fd));
+    const endingRevision = revisionFromStat(path, fd, fstatSync(fd));
     if (usageLogIdentityKey(endingRevision) !== openedIdentityKey) {
       throw rebuildRequired("identity_mismatch");
     }
@@ -417,7 +418,7 @@ export async function scanUsageLedgerCooperatively(
         line,
         options.signal,
       );
-      const verifiedFdRevision = revisionFromStat(path, fstatSync(fd));
+      const verifiedFdRevision = revisionFromStat(path, fd, fstatSync(fd));
       const verifiedPathRevision = currentUsageLogRevision();
       if (capturedDigest !== verifiedDigest) throw rebuildRequired("content_changed");
       if (!verifiedPathRevision

package/src/usage/log.ts

@@ -1163,8 +1163,12 @@ export function appendUsageEntry(entry: PersistedUsageEntry): void {
 
 export type UsageLogRevision = {
   path: string;
-  dev: number;
-  ino: number;
+  /**
+   * Exact decimal device and file id. NTFS file ids carry a sequence number in their
+   * high bits and routinely exceed 2^53, so a Number would let two files compare equal.
+   */
+  dev: string;
+  ino: string;
   birthtimeMs: number;
   size: number;
   mtimeMs: number;
@@ -1367,12 +1371,17 @@ function readExactly(fd: number, length: number, position: number): Buffer | nul
   return output;
 }
 
-function usageLogRevision(path: string, stat: ReturnType<typeof fstatSync>): UsageLogRevision {
+/** Exact dev/ino of an open file, read through bigint stats so large ids keep every bit. */
+export function exactFileIdentity(fd: number): { dev: string; ino: string } {
+  const exact = fstatSync(fd, { bigint: true });
+  return { dev: exact.dev.toString(), ino: exact.ino.toString() };
+}
+
+function usageLogRevision(path: string, fd: number, stat: ReturnType<typeof fstatSync>): UsageLogRevision {
   if (!stat.isFile()) throw new Error("usage log is not a regular file");
   return {
     path,
-    dev: Number(stat.dev),
-    ino: Number(stat.ino),
+    ...exactFileIdentity(fd),
     birthtimeMs: Number(stat.birthtimeMs),
     size: Number(stat.size),
     mtimeMs: Number(stat.mtimeMs),
@@ -1405,7 +1414,7 @@ export function currentUsageLogRevision(): UsageLogRevision | null {
   let fd: number | undefined;
   try {
     fd = openSync(path, "r");
-    return usageLogRevision(path, fstatSync(fd));
+    return usageLogRevision(path, fd, fstatSync(fd));
   } finally {
     if (fd !== undefined) closeSync(fd);
   }
@@ -1530,7 +1539,7 @@ async function readUsageEntriesFullCooperatively(
     if (prefixDigest === null) throw new Error("usage log changed while it was being read");
     return {
       entries: parsed.entries,
-      revision: usageLogRevision(path, stat),
+      revision: usageLogRevision(path, fd, stat),
       truncatedPrefixBytes,
       entriesTruncated: parsed.entriesDropped > 0,
       entriesDropped: parsed.entriesDropped,
@@ -1562,7 +1571,7 @@ async function readUsageEntriesIncrementally(
   try {
     fd = openSync(path, "r");
     const stat = fstatSync(fd);
-    const revision = usageLogRevision(path, stat);
+    const revision = usageLogRevision(path, fd, stat);
     if (usageLogIdentityKey(revision) !== retained.identityKey) return null;
     const size = Number(stat.size);
     // A shrink means truncation or replacement-in-place; the retained rows may no

package/src/usage/summary.ts

@@ -10,7 +10,7 @@ import {
   type PersistedUsageEntry,
   type UsageStatus,
 } from "./log";
-import { type AttemptCostEstimate, type CostEstimate, estimateAttemptCost, estimateRequestCost, serviceTierContext, type ServiceTierContext, tokensPerSecond } from "./cost";
+import { type AttemptCostEstimate, type CostEstimate, estimateAttemptCost, estimateRequestCost, isMeasuredStatus, serviceTierContext, type ServiceTierContext, tokensPerSecond } from "./cost";
 
 /**
  * Canonical range members. The warm-up loop in the management usage route
@@ -303,7 +303,10 @@ export function computeEntryCost(entry: PersistedUsageEntry): EntryCostInfo {
         isPriced = true;
       }
     }
-    return { tier, estimate: null, attemptEstimates, costTotal, isPriced };
+    // An unmeasured leg that may have generated billed tokens leaves the total unknown, not short.
+    const unknownCost = entry.attempts.some((attempt, index) =>
+      !attemptEstimates[index] && (!attempt.usage || !isMeasuredStatus(attempt.usageStatus)) && !spentNothing(attempt));
+    return { tier, estimate: null, attemptEstimates, costTotal, isPriced: isPriced && !unknownCost };
   }
   const estimate = estimateRequestCost({
     ...usageModelPriceOptions(entry, entry),
@@ -428,10 +431,6 @@ function blankTotals(): UsageSummaryTotals {
   };
 }
 
-function isMeasuredStatus(status: UsageStatus): boolean {
-  return status === "reported" || status === "estimated";
-}
-
 export interface UsageAttribution {
   requestId: string;
   provider: string;
@@ -814,14 +813,28 @@ function blankRequestCounts(): UsageRequestCounts {
   };
 }
 
+/**
+ * A usage-less attempt that provably cost nothing: it never reached upstream, or upstream refused it
+ * with an HTTP error before any output (providers do not bill a pre-generation 429/401/5xx). One
+ * whose stream began, aborted, or ended without a status may have generated billed tokens, so it
+ * stays an unknown cost. A request made only of such zeros carries neither fact and counts unpriced.
+ */
+function spentNothing(attempt: NonNullable<PersistedUsageEntry["attempts"]>[number] | undefined): boolean {
+  if (!attempt || attempt.usage) return false;
+  if (attempt.sendCount === 0 || attempt.locallyAnswered === true) return true;
+  return attempt.status >= 400 && attempt.streamAborted !== true && attempt.firstOutputMs === undefined;
+}
+
 function bumpRequestCounts(counts: UsageRequestCounts, facts: number, amount = 1): void {
   counts.requests += amount;
   const status = statusFromRequestFacts(facts);
   if (isMeasuredStatus(status)) counts.measuredRequests += amount;
   if (status === "reported") counts.reportedRequests += amount;
   else if (status === "estimated") counts.estimatedRequests += amount;
-  if ((facts & REQUEST_PRICED) !== 0) counts.pricedRequests += amount;
-  if ((facts & REQUEST_UNPRICED) !== 0) counts.unpricedRequests += amount;
+  // Unpriced dominates: one unpriceable part makes the request's cost unknown, and counting it
+  // on both sides overstated price coverage.
+  if ((facts & REQUEST_PRICED) !== 0 && (facts & REQUEST_UNPRICED) === 0) counts.pricedRequests += amount;
+  else counts.unpricedRequests += amount;
 }
 
 function mergeRequestCounts(target: UsageRequestCounts, source: UsageRequestCounts): void {
@@ -1557,7 +1570,7 @@ class StreamingUsageSummaryAccumulator implements UsageSummaryAccumulator {
         : costInfo.estimate;
       const ordinal = this.nextOrdinal++;
       const facts = requestStatusFact(attribution.usageStatus)
-        | (estimate ? REQUEST_PRICED : REQUEST_UNPRICED);
+        | (estimate ? REQUEST_PRICED : spentNothing(entry.attempts?.[index]) ? 0 : REQUEST_UNPRICED);
       const modelKey = this.addModelAttribution(partition, attribution, estimate, ordinal);
       modelFacts.set(modelKey, (modelFacts.get(modelKey) ?? 0) | facts);
       if (this.mode === "row-unique") {

package/src/usage/user-cost-overlays.ts

@@ -18,8 +18,10 @@
  *
  * Display-time estimation only — these rows never affect billing.
  */
-import type { OcxConfig, OcxProviderConfig, ProviderCostOverlay } from "../types";
-import { MAX_COST4_RATE, type ExpectedPriceOverlay } from "./expected-prices";
+import type { OcxConfig, OcxProviderConfig, ProviderCostOverlay, PromptLengthPricing } from "../types";
+import type { ExpectedPriceOverlay } from "./expected-prices";
+import { validCost4 } from "./user-cost-validation";
+export { COST4_RATE_KEYS, isValidCost4Rate, validCost4, isValidPromptLengthPricing } from "./user-cost-validation";
 import { redactSecretString } from "../lib/redact";
 import { isSelectableCodexPoolAccount, MAIN_CODEX_ACCOUNT_ID } from "../codex/account-id";
 import { codexAccountLogLabel } from "../codex/account-label";
@@ -236,22 +238,13 @@ export function resetPreservedDiskOnlyProvidersForTests(): void {
   preservationOwnerStates.clear();
 }
 
-/** Exact four fields accepted for a user-configured cost tuple. */
-export const COST4_RATE_KEYS = ["input", "output", "cacheRead", "cacheWrite"] as const;
-
-/** Shared per-rate predicate used by config validation, display sanitization, and runtime lifting. */
-export function isValidCost4Rate(rate: unknown): rate is number {
-  return typeof rate === "number"
-    && Number.isFinite(rate)
-    && rate >= 0
-    && rate <= MAX_COST4_RATE;
-}
-
-/** True when `value` is a complete cost entry: all four rates are non-negative finite numbers. */
-function validCost4(value: unknown): value is ProviderCostOverlay {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
-  const entry = value as Record<string, unknown>;
-  return COST4_RATE_KEYS.every(key => isValidCost4Rate(entry[key]));
+/** Copy a validated override; automatic is represented by absence. */
+export function copyPromptLengthPricing(policy: PromptLengthPricing): PromptLengthPricing | undefined {
+  if (policy.mode === "automatic") return undefined;
+  if (policy.mode !== "custom") return { mode: policy.mode };
+  const { input, output, cacheRead, cacheWrite } = policy.rates;
+  return { mode: "custom", thresholdTokens: policy.thresholdTokens, comparison: policy.comparison,
+    rates: { input, output, cacheRead, cacheWrite } };
 }
 
 /**
@@ -273,10 +266,11 @@ export function refreshUserCostOverlays(config: OcxConfig): void {
       if (!costs || typeof costs !== "object" || Array.isArray(costs)) continue;
       for (const [modelId, cost4] of Object.entries(costs)) {
         if (!modelId.trim() || !validCost4(cost4)) continue;
+        const policy = cost4.promptLengthPricing && copyPromptLengthPricing(cost4.promptLengthPricing);
         rows.push({
           provider: providerName,
           modelId,
-          // Copy ONLY the four validated rate fields: a hand-edited row may
+          // Copy only validated rates and policy: a hand-edited row may
           // carry extra properties (e.g. a misplaced apiKey) that must never
           // reach display estimates or /api/logs through the registry.
           cost4: {
@@ -285,6 +279,7 @@ export function refreshUserCostOverlays(config: OcxConfig): void {
             cacheRead: cost4.cacheRead,
             cacheWrite: cost4.cacheWrite,
           },
+          ...(policy ? { promptLengthPricing: policy } : {}),
           // Display provenance only: redact token-shaped provider/model ids so
           // the source string can never echo a pasted key. Matching still uses
           // the raw fields, and the change-detection signature below MUST keep

package/src/usage/user-cost-validation.ts

@@ -0,0 +1,38 @@
+/** Pure model-cost validation shared by config, migration, and display lifting. */
+import type { ProviderCostOverlay, PromptLengthPricing } from "../types";
+import { MAX_COST4_RATE } from "./expected-prices";
+
+/** Exact four fields accepted for a user-configured cost tuple. */
+export const COST4_RATE_KEYS = ["input", "output", "cacheRead", "cacheWrite"] as const;
+
+/** Shared per-rate predicate used by config validation, display sanitization, and runtime lifting. */
+export function isValidCost4Rate(rate: unknown): rate is number {
+  return typeof rate === "number"
+    && Number.isFinite(rate)
+    && rate >= 0
+    && rate <= MAX_COST4_RATE;
+}
+
+/** Complete base rates with a valid optional policy; extra top-level fields are never copied. */
+export function validCost4(value: unknown): value is ProviderCostOverlay {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const entry = value as Record<string, unknown>;
+  return COST4_RATE_KEYS.every(key => Object.hasOwn(entry, key) && isValidCost4Rate(entry[key]))
+    && (!Object.hasOwn(entry, "promptLengthPricing") || isValidPromptLengthPricing(entry.promptLengthPricing));
+}
+
+/** Strict nested policy boundary; diagnostics never echo untrusted policy fields. */
+export function isValidPromptLengthPricing(value: unknown): value is PromptLengthPricing {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const policy = value as Record<string, unknown>;
+  if (!Object.hasOwn(policy, "mode")) return false;
+  if (policy.mode === "automatic" || policy.mode === "flat") return Object.keys(policy).length === 1;
+  if (policy.mode !== "custom" || Object.keys(policy).length !== 4
+    || !["mode", "thresholdTokens", "comparison", "rates"].every(key => Object.hasOwn(policy, key))
+    || typeof policy.thresholdTokens !== "number" || !Number.isSafeInteger(policy.thresholdTokens)
+    || policy.thresholdTokens <= 0 || (policy.comparison !== "gt" && policy.comparison !== "gte")) return false;
+  const rates = policy.rates;
+  return !!rates && typeof rates === "object" && !Array.isArray(rates)
+    && Object.keys(rates).length === COST4_RATE_KEYS.length
+    && COST4_RATE_KEYS.every(key => Object.hasOwn(rates, key) && isValidCost4Rate((rates as Record<string, unknown>)[key]));
+}

package/src/vision/eligibility.ts

@@ -226,6 +226,19 @@ export function isVisionSidecarConsumer(config: VisionCapabilityConfig, provider
   return isVisionSidecarConsumerWithCache(config, providerName, modelId, new Map());
 }
 
+/**
+ * `isVisionSidecarConsumer` for many rows of one config. Rows of the same provider share one
+ * registry enrichment instead of rebuilding it per row, which matters for `/api/models`
+ * listings with thousands of rows. Bind it to a single config snapshot; it does not observe
+ * provider changes made after the first lookup.
+ */
+export function visionSidecarConsumerClassifier(
+  config: VisionCapabilityConfig,
+): (providerName: string, modelId: string) => boolean {
+  const cache: EnrichedProviderCache = new Map();
+  return (providerName, modelId) => isVisionSidecarConsumerWithCache(config, providerName, modelId, cache);
+}
+
 /**
  * Can this model accept an image on the wire? Sources are consulted in descending
  * trustworthiness; the first that speaks wins. `undefined` means nothing knows,