dsh-all-usage 1.1.2 → 1.1.3

package/lib/pricing.js

@@ -6,11 +6,20 @@ const MODEL_CATALOG_URL = 'https://models.dev/api.json'
 const DEFAULT_SYNC_INTERVAL_MS = 6 * 60 * 60 * 1000
 const MAX_CATALOG_BYTES = 24 * 1024 * 1024
 const MAX_PRICE_ENTRIES = 10000
+// Hard candidate ceiling before the sorting-heavy selection: a pathological
+// upstream catalog is rejected instead of consuming unbounded memory.
+// Hard candidate ceiling before any normalization-heavy sort: a pathological
+// upstream catalog is rejected instead of consuming unbounded memory.
+const MAX_CATALOG_CANDIDATES = 30000
 const MAX_OVERRIDES = 500
 const MAX_MAPPINGS = 500
+const MAX_CONTEXT_TIERS = 32
 const RATE_KEYS = ['input', 'output', 'cacheRead', 'cacheWrite']
 const INPUT_SEMANTICS = ['legacy', 'total', 'fresh']
 const COST_STATUSES = ['priced', 'unpriced', 'ambiguous', 'unsupported']
+const COST_FIELDS = ['input', 'output', 'cacheRead', 'cacheWrite', 'baseTotal', 'total']
+const COST_ACCUMULATOR = Symbol('costAccumulator')
+const COST_PARTS_CACHE = new WeakMap()
 const OFFICIAL_PROVIDER_RULES = [
   { providers: ['openai'], prefixes: ['gpt-', 'o1', 'o3', 'o4', 'o5'] },
   { providers: ['anthropic'], prefixes: ['claude-'] },
@@ -77,6 +86,89 @@ function decimalText(value) {
   return padded.slice(0, split) + '.' + padded.slice(split)
 }
 
+function normalizedDecimalParts(parts) {
+  let digits = parts && typeof parts.digits === 'bigint' ? parts.digits : 0n
+  let scale = parts && Number.isSafeInteger(parts.scale) && parts.scale >= 0 ? parts.scale : 0
+  if (digits < 0n) digits = 0n
+  while (scale > 0 && digits !== 0n && digits % 10n === 0n) {
+    digits /= 10n
+    scale -= 1
+  }
+  return { digits, scale }
+}
+
+function decimalAccumulatorText(value) {
+  const parts = normalizedDecimalParts(value)
+  if (parts.digits === 0n) return '0'
+  const raw = parts.digits.toString()
+  if (parts.scale === 0) return raw
+  const padded = raw.padStart(parts.scale + 1, '0')
+  const split = padded.length - parts.scale
+  return padded.slice(0, split) + '.' + padded.slice(split)
+}
+
+function isCostAccumulator(value) {
+  return value !== null && typeof value === 'object' && value[COST_ACCUMULATOR] === true
+}
+
+function createCostAccumulator(currency = 'USD') {
+  const result = { currency, input: { digits: 0n, scale: 0 }, output: { digits: 0n, scale: 0 }, cacheRead: { digits: 0n, scale: 0 }, cacheWrite: { digits: 0n, scale: 0 }, baseTotal: { digits: 0n, scale: 0 }, total: { digits: 0n, scale: 0 }, pricedCalls: 0, unpricedCalls: 0, ambiguousCalls: 0, unsupportedCalls: 0 }
+  Object.defineProperty(result, COST_ACCUMULATOR, { value: true })
+  return result
+}
+
+function costAccumulatorParts(cost) {
+  if (isCostAccumulator(cost)) return cost
+  if (cost !== null && typeof cost === 'object') {
+    const cached = COST_PARTS_CACHE.get(cost)
+    if (cached !== undefined) return cached
+  }
+  const value = isRecord(cost) ? cost : {}
+  const status = COST_STATUSES.includes(value.status) ? value.status : 'unpriced'
+  const breakdown = isRecord(value.breakdown) ? value.breakdown : {}
+  const result = {
+    currency: typeof value.currency === 'string' && value.currency !== '' ? value.currency : 'USD',
+    status,
+    input: decimalParts(breakdown.input) || { digits: 0n, scale: 0 },
+    output: decimalParts(breakdown.output) || { digits: 0n, scale: 0 },
+    cacheRead: decimalParts(breakdown.cacheRead) || { digits: 0n, scale: 0 },
+    cacheWrite: decimalParts(breakdown.cacheWrite) || { digits: 0n, scale: 0 },
+    baseTotal: decimalParts(value.baseTotal) || { digits: 0n, scale: 0 },
+    total: decimalParts(value.total) || { digits: 0n, scale: 0 },
+  }
+  if (cost !== null && typeof cost === 'object') COST_PARTS_CACHE.set(cost, result)
+  return result
+}
+
+function addDecimalAccumulator(target, field, value, direction) {
+  const left = normalizedDecimalParts(target[field])
+  const right = normalizedDecimalParts(value)
+  const scale = Math.max(left.scale, right.scale)
+  let digits = left.digits * 10n ** BigInt(scale - left.scale) + BigInt(direction) * right.digits * 10n ** BigInt(scale - right.scale)
+  if (digits < 0n) digits = 0n
+  target[field] = normalizedDecimalParts({ digits, scale })
+}
+
+function addCostAccumulator(target, cost, direction = 1) {
+  if (!isCostAccumulator(target)) return target
+  if (isCostAccumulator(cost)) {
+    for (const field of COST_FIELDS) addDecimalAccumulator(target, field, cost[field], direction)
+    target.pricedCalls = Math.max(0, target.pricedCalls + direction * cost.pricedCalls)
+    target.unpricedCalls = Math.max(0, target.unpricedCalls + direction * cost.unpricedCalls)
+    target.ambiguousCalls = Math.max(0, target.ambiguousCalls + direction * cost.ambiguousCalls)
+    target.unsupportedCalls = Math.max(0, target.unsupportedCalls + direction * cost.unsupportedCalls)
+    return target
+  }
+  const value = costAccumulatorParts(cost)
+  if (value.status === 'priced') {
+    for (const field of COST_FIELDS) addDecimalAccumulator(target, field, value[field], direction)
+    target.pricedCalls = Math.max(0, target.pricedCalls + direction)
+  } else if (value.status === 'ambiguous') target.ambiguousCalls = Math.max(0, target.ambiguousCalls + direction)
+  else if (value.status === 'unsupported') target.unsupportedCalls = Math.max(0, target.unsupportedCalls + direction)
+  else target.unpricedCalls = Math.max(0, target.unpricedCalls + direction)
+  return target
+}
+
 function decimalAdd(left, right) {
   const a = decimalParts(left) || { digits: 0n, scale: 0 }
   const b = decimalParts(right) || { digits: 0n, scale: 0 }
@@ -212,30 +304,81 @@ function identityModels(identity) {
 }
 
 function identityKeyOf(identity) {
-  return isRecord(identity) && typeof identity.identityKey === 'string' ? identity.identityKey : ''
+  if (!isRecord(identity)) return ''
+  const key = typeof identity.identityKey === 'string' && identity.identityKey.trim() !== '' ? identity.identityKey : identity.usageIdentityKey
+  return typeof key === 'string' ? key.trim() : ''
 }
 
 function priceEntryKey(entry) {
   return normalizeProvider(entry.providerId) + '\0' + normalizeModelId(entry.modelId)
 }
 
+function decimalRate(raw, keys, fallback = undefined) {
+  let value
+  for (const key of keys) {
+    if (raw && raw[key] !== undefined) {
+      value = raw[key]
+      break
+    }
+  }
+  if (value === undefined || value === null || value === '') value = fallback
+  return decimalText(value)
+}
+
+function normalizeContextTier(raw, fallbackRates, legacySize = null) {
+  if (!isRecord(raw)) return null
+  const descriptor = isRecord(raw.tier) ? raw.tier : raw
+  const type = legacySize === null ? (typeof descriptor.type === 'string' ? descriptor.type.trim().toLowerCase() : '') : 'context'
+  const sizeValue = legacySize === null ? descriptor.size : legacySize
+  const size = finiteNumber(sizeValue)
+  if (type !== 'context' || size === null || !Number.isSafeInteger(size) || size <= 0 || size > 1000000000) return null
+  const input = decimalRate(raw, ['input', 'inputPerMillion'], fallbackRates.input)
+  const output = decimalRate(raw, ['output', 'outputPerMillion'], fallbackRates.output)
+  const cacheRead = decimalRate(raw, ['cacheRead', 'cache_read', 'cacheReadPerMillion'], fallbackRates.cacheRead)
+  const cacheWrite = decimalRate(raw, ['cacheWrite', 'cache_write', 'cacheCreation', 'cacheWritePerMillion'], fallbackRates.cacheWrite)
+  if (input === null || output === null || cacheRead === null || cacheWrite === null) return null
+  if (decimalParts(input).digits < 0n || decimalParts(output).digits < 0n || decimalParts(cacheRead).digits < 0n || decimalParts(cacheWrite).digits < 0n) return null
+  return { type: 'context', size, input, output, cacheRead, cacheWrite }
+}
+
 function normalizePriceEntry(raw, sourceDefault = 'models.dev') {
   if (!isRecord(raw)) return null
   const modelId = normalizeModelId(raw.modelId || raw.id)
   if (modelId === '') return null
-  const input = decimalText(raw.input !== undefined ? raw.input : raw.inputPerMillion)
-  const output = decimalText(raw.output !== undefined ? raw.output : raw.outputPerMillion)
+  const input = decimalRate(raw, ['input', 'inputPerMillion'])
+  const output = decimalRate(raw, ['output', 'outputPerMillion'])
   if (input === null || output === null || decimalParts(input).digits < 0n || decimalParts(output).digits < 0n) return null
-  const optionalDecimal = (primary, secondary) => {
-    const value = primary !== undefined ? primary : secondary
-    if (value === undefined || value === null || value === '') return '0'
-    return decimalText(value)
-  }
-  const cacheRead = optionalDecimal(raw.cacheRead, raw.cacheReadPerMillion)
-  const cacheWrite = optionalDecimal(raw.cacheWrite !== undefined ? raw.cacheWrite : raw.cacheCreation, raw.cacheWritePerMillion)
+  const cacheRead = decimalRate(raw, ['cacheRead', 'cache_read', 'cacheReadPerMillion'], '0')
+  const cacheWrite = decimalRate(raw, ['cacheWrite', 'cache_write', 'cacheCreation', 'cacheWritePerMillion'], '0')
   if (cacheRead === null || cacheWrite === null || decimalParts(cacheRead).digits < 0n || decimalParts(cacheWrite).digits < 0n) return null
+  const fallbackRates = { input, output, cacheRead, cacheWrite }
+  const tiers = []
+  let tieredInvalid = false
+  const hasTierData = raw.tiers !== undefined || raw.context_over_200k !== undefined
+  if (raw.tiers !== undefined) {
+    if (!Array.isArray(raw.tiers)) tieredInvalid = true
+    else {
+      if (raw.tiers.length > MAX_CONTEXT_TIERS) tieredInvalid = true
+      for (const rawTier of raw.tiers.slice(0, MAX_CONTEXT_TIERS)) {
+        const tier = normalizeContextTier(rawTier, fallbackRates)
+        if (tier === null || tiers.some((existing) => existing.size === tier.size)) tieredInvalid = true
+        else tiers.push(tier)
+      }
+    }
+  }
+  if (raw.context_over_200k !== undefined && raw.tiers === undefined) {
+    const tier = normalizeContextTier(raw.context_over_200k, fallbackRates, 200000)
+    if (tier === null) tieredInvalid = true
+    else tiers.push(tier)
+  }
+  tiers.sort((left, right) => left.size - right.size)
+  const tiered = raw.tiered !== undefined ? raw.tiered === true : hasTierData || tiers.length > 0
+  if (!tiered) {
+    tiers.length = 0
+    tieredInvalid = false
+  } else if (tiers.length === 0) tieredInvalid = true
   return {
-    providerId: typeof raw.providerId === 'string' ? raw.providerId.trim() : '',
+    providerId: typeof raw.providerId === 'string' ? raw.providerId.trim().toLowerCase() : '',
     providerName: typeof raw.providerName === 'string' ? raw.providerName.trim().slice(0, 200) : '',
     modelId,
     displayName: typeof raw.displayName === 'string' && raw.displayName.trim() !== '' ? raw.displayName.trim().slice(0, 200) : modelId,
@@ -245,7 +388,8 @@ function normalizePriceEntry(raw, sourceDefault = 'models.dev') {
     cacheRead,
     cacheWrite,
     source: raw.source === 'manual' ? 'manual' : sourceDefault,
-    tiered: raw.tiered === true || raw.tiers !== undefined,
+    tiered,
+    ...(tiered ? { tiers, tieredInvalid } : {}),
     reasoningRateAvailable: raw.reasoningRateAvailable === true || raw.reasoning !== undefined,
     fetchedAt: Number.isFinite(raw.fetchedAt) ? raw.fetchedAt : 0,
   }
@@ -254,7 +398,6 @@ function normalizePriceEntry(raw, sourceDefault = 'models.dev') {
 function parseModelsDevCatalog(raw, fetchedAt = Date.now()) {
   if (!isRecord(raw)) return { ok: false, error: 'catalog-not-object' }
   const entries = []
-  const seen = new Set()
   for (const [providerKey, provider] of Object.entries(raw)) {
     if (!isRecord(provider) || !isRecord(provider.models)) continue
     const providerId = typeof provider.id === 'string' && provider.id.trim() !== '' ? provider.id.trim() : providerKey
@@ -271,22 +414,56 @@ function parseModelsDevCatalog(raw, fetchedAt = Date.now()) {
         output: model.cost && model.cost.output,
         cacheRead: model.cost && model.cost.cache_read,
         cacheWrite: model.cost && model.cost.cache_write,
+        tiers: model.cost && model.cost.tiers,
+        context_over_200k: model.cost && model.cost.context_over_200k,
         tiered: model.cost && model.cost.tiers !== undefined || model.cost && model.cost.context_over_200k !== undefined,
         reasoningRateAvailable: model.cost && model.cost.reasoning !== undefined,
         source: 'models.dev',
         fetchedAt,
       })
       if (entry === null || entry.currency !== 'USD') continue
-      const key = priceEntryKey(entry)
-      if (seen.has(key)) continue
-      seen.add(key)
+      // Duplicate normalized keys are NOT resolved here: they are kept and
+      // resolved deterministically after the stable sort below.
       entries.push(entry)
-      if (entries.length >= MAX_PRICE_ENTRIES) break
+      if (entries.length > MAX_CATALOG_CANDIDATES) return { ok: false, error: 'catalog-exceeds-candidate-limit', candidateCount: entries.length }
     }
-    if (entries.length >= MAX_PRICE_ENTRIES) break
   }
   if (entries.length === 0) return { ok: false, error: 'catalog-has-no-priced-models' }
-  const canonical = JSON.stringify(entries)
+  // Sort by the stable key first: upstream object order must not decide which
+  // models survive a large catalog or which conflicting duplicate is kept.
+  // Code-unit comparison: default-locale localeCompare can report ties for
+  // distinct strings (e.g. composed/decomposed accents), which would let
+  // upstream enumeration order decide the surviving entry.
+  entries.sort((left, right) => { const ka = priceEntryKey(left); const kb = priceEntryKey(right); return ka < kb ? -1 : ka > kb ? 1 : 0 })
+  // Deterministic duplicate selection: within one normalized key, compare only
+  // the small conflict group by their full content (fetchedAt excluded), so
+  // ordering swaps cannot change the surviving price.
+  const stableText = (entry) => {
+    const copy = Object.assign({}, entry)
+    delete copy.fetchedAt
+    if (typeof copy.providerId === 'string') copy.providerId = copy.providerId.trim().toLowerCase()
+    return JSON.stringify(copy)
+  }
+  const ordered = []
+  {
+    let index = 0
+    while (index < entries.length) {
+      const key = priceEntryKey(entries[index])
+      let end = index + 1
+      while (end < entries.length && priceEntryKey(entries[end]) === key) end += 1
+      let group = end - index > 1 ? entries.slice(index, end).sort((left, right) => { const la = stableText(left); const lb = stableText(right); return la < lb ? -1 : la > lb ? 1 : 0 }) : entries.slice(index, end)
+      ordered.push(group[0])
+      index = end
+    }
+  }
+  ordered.length = Math.min(ordered.length, MAX_PRICE_ENTRIES)
+  // The fetchedAt stamp differs on every fetch; exclude it from the content
+  // hash so identical catalog contents hash identically across syncs.
+  const canonical = JSON.stringify(ordered.map((entry) => {
+    if (entry.fetchedAt === undefined) return entry
+    const { fetchedAt, ...stable } = entry
+    return stable
+  }))
   return {
     ok: true,
     catalog: {
@@ -294,7 +471,7 @@ function parseModelsDevCatalog(raw, fetchedAt = Date.now()) {
       sourceUrl: MODEL_CATALOG_URL,
       fetchedAt,
       catalogHash: createHash('sha256').update(canonical).digest('hex'),
-      entries,
+      entries: ordered,
     },
   }
 }
@@ -312,9 +489,11 @@ function normalizePricingState(raw) {
     const model = normalizeModelId(mapping.model || mapping.modelId)
     const catalogProviderId = typeof mapping.catalogProviderId === 'string' ? mapping.catalogProviderId.trim() : ''
     const catalogModelId = normalizeModelId(mapping.catalogModelId || mapping.catalogModel)
-    if (provider === '' && model === '' && catalogProviderId === '' && catalogModelId === '') return null
+    const identityKey = (typeof mapping.identityKey === 'string' && mapping.identityKey.trim() !== '' ? mapping.identityKey : mapping.usageIdentityKey)
+    const normalizedIdentityKey = typeof identityKey === 'string' ? identityKey.trim().slice(0, 1024) : ''
+    if (provider === '' && model === '' && catalogProviderId === '' && catalogModelId === '' && normalizedIdentityKey === '') return null
     return {
-      identityKey: typeof mapping.identityKey === 'string' ? mapping.identityKey.slice(0, 1024) : '',
+      identityKey: normalizedIdentityKey,
       provider,
       model,
       catalogProviderId,
@@ -380,10 +559,22 @@ function serializePricingState(state) {
 }
 
 function sameRates(left, right) {
-  return left.input === right.input && left.output === right.output && left.cacheRead === right.cacheRead && left.cacheWrite === right.cacheWrite && left.currency === right.currency
+  if (left.input !== right.input || left.output !== right.output || left.cacheRead !== right.cacheRead || left.cacheWrite !== right.cacheWrite || left.currency !== right.currency || left.tiered !== right.tiered || left.tieredInvalid !== right.tieredInvalid) return false
+  const leftTiers = Array.isArray(left.tiers) ? left.tiers : []
+  const rightTiers = Array.isArray(right.tiers) ? right.tiers : []
+  if (leftTiers.length !== rightTiers.length) return false
+  return leftTiers.every((leftTier, index) => {
+    const rightTier = rightTiers[index]
+    return rightTier && leftTier.type === rightTier.type && leftTier.size === rightTier.size && leftTier.input === rightTier.input && leftTier.output === rightTier.output && leftTier.cacheRead === rightTier.cacheRead && leftTier.cacheWrite === rightTier.cacheWrite
+  })
 }
 
 function mappingMatches(mapping, identity) {
+  if (mapping.identityKey !== '') {
+    if (mapping.identityKey !== identityKeyOf(identity)) return false
+    return mapping.provider === '' || (isRecord(identity) && typeof identity.provider === 'string' && identity.provider.trim().toLowerCase() === mapping.provider.toLowerCase())
+  }
+  if (mapping.provider !== '' && (!isRecord(identity) || typeof identity.provider !== 'string' || identity.provider.trim().toLowerCase() !== mapping.provider.toLowerCase())) return false
   const models = identityModels(identity)
   return mapping.model !== '' && models.includes(mapping.model)
 }
@@ -401,7 +592,9 @@ function findMappedEntry(mapping, state) {
 
 function resolvePricing(identity, rawState) {
   const state = rawState && rawState._normalized === true ? rawState : normalizePricingState(rawState)
-  const mapped = state.mappings.find((mapping) => mappingMatches(mapping, identity))
+  const identityKey = identityKeyOf(identity)
+  const exactMapped = identityKey === '' ? undefined : state.mappings.find((mapping) => mapping.identityKey !== '' && mapping.identityKey === identityKey && mappingMatches(mapping, identity))
+  const mapped = exactMapped || state.mappings.find((mapping) => mapping.identityKey === '' && mappingMatches(mapping, identity))
   const mappedEntry = mapped === undefined ? null : findMappedEntry(mapped, state)
   if (mapped !== undefined && mappedEntry === null && (mapped.catalogModelId !== '' || mapped.catalogProviderId !== '')) {
     return { status: 'unpriced', reason: 'mapping-target-not-found', pricingModel: mapped.catalogModelId || null, providerId: mapped.catalogProviderId || null }
@@ -438,9 +631,12 @@ function resolvePricing(identity, rawState) {
     for (const match of sameRank) if (!unique.some((entry) => sameRates(entry, match.entry))) unique.push(match.entry)
     if (unique.length > 1) return { status: 'ambiguous', reason: 'multiple-official-prices', pricingModel: best.entry.modelId, providerId: null, candidates: unique.map((entry) => ({ providerId: entry.providerId, modelId: entry.modelId })) }
     const entry = unique[0] || best.entry
+    const tiered = entry.tiered === true
+    const tiers = Array.isArray(entry.tiers) ? entry.tiers.map((tier) => ({ ...tier })) : []
+    const tieredSupported = !tiered || (entry.tieredInvalid !== true && tiers.length > 0)
     return {
-      status: 'priced',
-      reason: '',
+      status: tieredSupported ? 'priced' : 'unsupported',
+      reason: tieredSupported ? '' : 'tiered-pricing-not-modeled',
       pricingModel: entry.modelId,
       providerId: entry.providerId || null,
       providerName: entry.providerName || null,
@@ -448,7 +644,8 @@ function resolvePricing(identity, rawState) {
       currency: entry.currency,
       rates: { input: entry.input, output: entry.output, cacheRead: entry.cacheRead, cacheWrite: entry.cacheWrite },
       source: entry.source,
-      tiered: entry.tiered,
+      tiered,
+      ...(tiered ? { tiers, tieredInvalid: entry.tieredInvalid === true } : {}),
       reasoningRateAvailable: entry.reasoningRateAvailable,
       inputTokenSemantics: mapped && INPUT_SEMANTICS.includes(mapped.inputTokenSemantics) ? mapped.inputTokenSemantics : 'fresh',
       multiplier: mapped ? mapped.multiplier : '1',
@@ -473,6 +670,42 @@ function costPerMillion(tokens, rate) {
   return decimalText(numerator.toString() + (scale > 0 ? 'e-' + scale : '')) || '0'
 }
 
+function contextTokenCount(input, cacheRead, cacheWrite, inputSemantics) {
+  const values = inputSemantics === 'total' ? [input] : inputSemantics === 'legacy' ? [input, cacheWrite] : [input, cacheRead, cacheWrite]
+  let total = 0
+  for (const value of values) {
+    const tokens = Math.max(0, Math.trunc(value))
+    if (!Number.isFinite(tokens) || total > Number.MAX_SAFE_INTEGER - tokens) return Number.MAX_SAFE_INTEGER
+    total += tokens
+  }
+  return total
+}
+
+function validContextTier(tier, previousSize = 0) {
+  if (!isRecord(tier) || tier.type !== 'context' || !Number.isSafeInteger(tier.size) || tier.size <= previousSize || tier.size > 1000000000) return false
+  return RATE_KEYS.every((key) => decimalText(tier[key]) !== null)
+}
+
+function validContextTierSchedule(tiers) {
+  if (!Array.isArray(tiers) || tiers.length === 0) return false
+  let previousSize = 0
+  for (const tier of tiers) {
+    if (!validContextTier(tier, previousSize)) return false
+    previousSize = tier.size
+  }
+  return true
+}
+
+function selectContextTier(tiers, contextTokens) {
+  let selected = null
+  for (const tier of tiers) {
+    // models.dev defines size as the point where the next band starts.
+    if (contextTokens > tier.size) selected = tier
+    else break
+  }
+  return selected
+}
+
 function calculateCost(values, resolved) {
   const input = finiteNumber(values && values.input) || 0
   const output = finiteNumber(values && values.output) || 0
@@ -481,10 +714,13 @@ function calculateCost(values, resolved) {
   const inputSemantics = INPUT_SEMANTICS.includes(resolved && resolved.inputTokenSemantics) ? resolved.inputTokenSemantics : 'fresh'
   const billableInput = inputSemantics === 'total' ? Math.max(0, input - cacheRead - cacheWrite) : inputSemantics === 'legacy' ? Math.max(0, input - cacheRead) : input
   const billableOutput = output
+  const tiered = resolved && resolved.tiered === true
+  const tiers = tiered && Array.isArray(resolved.tiers) ? resolved.tiers : []
+  const tierScheduleValid = !tiered || validContextTierSchedule(tiers)
   const base = {
     schemaVersion: COST_SCHEMA_VERSION,
     pricingMode: 'official-model',
-    status: resolved && COST_STATUSES.includes(resolved.status) ? resolved.status : 'unpriced',
+    status: tierScheduleValid && resolved && COST_STATUSES.includes(resolved.status) ? resolved.status : tiered ? 'unsupported' : 'unpriced',
     currency: resolved && resolved.currency ? resolved.currency : 'USD',
     source: resolved && resolved.source ? resolved.source : 'none',
     pricingModel: resolved && resolved.pricingModel ? resolved.pricingModel : null,
@@ -497,11 +733,19 @@ function calculateCost(values, resolved) {
     breakdown: { input: '0', output: '0', cacheRead: '0', cacheWrite: '0' },
     baseTotal: '0',
     total: '0',
-    reason: resolved && typeof resolved.reason === 'string' ? resolved.reason : 'model-not-found',
-    tiered: resolved && resolved.tiered === true,
+    reason: tiered && !tierScheduleValid ? 'tiered-pricing-not-modeled' : resolved && typeof resolved.reason === 'string' ? resolved.reason : 'model-not-found',
+    tiered,
     reasoningRateAvailable: resolved && resolved.reasoningRateAvailable === true,
   }
   if (base.status !== 'priced') return base
+  if (tiered) {
+    const contextTokens = contextTokenCount(input, cacheRead, cacheWrite, inputSemantics)
+    const selectedTier = selectContextTier(tiers, contextTokens)
+    const selectedRates = selectedTier || base.rates
+    base.rates = { input: selectedRates.input, output: selectedRates.output, cacheRead: selectedRates.cacheRead, cacheWrite: selectedRates.cacheWrite }
+    base.contextTokens = contextTokens
+    base.selectedTier = { type: 'context', size: selectedTier ? selectedTier.size : 0 }
+  }
   base.breakdown.input = costPerMillion(base.billableInputTokens, base.rates.input)
   base.breakdown.output = costPerMillion(base.billableOutputTokens, base.rates.output)
   base.breakdown.cacheRead = costPerMillion(cacheRead, base.rates.cacheRead)
@@ -516,6 +760,7 @@ function emptyCostAggregate(currency = 'USD') {
 }
 
 function addCostAggregate(target, cost) {
+  if (isCostAccumulator(target)) return addCostAccumulator(target, cost)
   const value = isRecord(cost) ? cost : {}
   const status = COST_STATUSES.includes(value.status) ? value.status : 'unpriced'
   if (status === 'priced') {
@@ -534,14 +779,16 @@ function addCostAggregate(target, cost) {
 
 function serializeCostAggregate(cost) {
   const value = cost || emptyCostAggregate()
+  const accumulator = isCostAccumulator(value)
+  const text = (field) => accumulator ? decimalAccumulatorText(value[field]) : decimalText(value[field]) || '0'
   return {
     currency: typeof value.currency === 'string' && value.currency !== '' ? value.currency : 'USD',
-    input: decimalText(value.input) || '0',
-    output: decimalText(value.output) || '0',
-    cacheRead: decimalText(value.cacheRead) || '0',
-    cacheWrite: decimalText(value.cacheWrite) || '0',
-    baseTotal: decimalText(value.baseTotal) || '0',
-    total: decimalText(value.total) || '0',
+    input: text('input'),
+    output: text('output'),
+    cacheRead: text('cacheRead'),
+    cacheWrite: text('cacheWrite'),
+    baseTotal: text('baseTotal'),
+    total: text('total'),
     pricedCalls: Number.isFinite(value.pricedCalls) ? value.pricedCalls : 0,
     unpricedCalls: Number.isFinite(value.unpricedCalls) ? value.unpricedCalls : 0,
     ambiguousCalls: Number.isFinite(value.ambiguousCalls) ? value.ambiguousCalls : 0,
@@ -567,6 +814,17 @@ function normalizeCostSnapshot(raw) {
   const total = decimalText(raw.total)
   const multiplier = decimalText(raw.multiplier)
   if (baseTotal === null || total === null || multiplier === null) return null
+  let contextTokens = null
+  if (raw.contextTokens !== undefined) {
+    const parsed = finiteNumber(raw.contextTokens)
+    if (parsed === null || parsed < 0 || !Number.isSafeInteger(parsed)) return null
+    contextTokens = parsed
+  }
+  let selectedTier = null
+  if (raw.selectedTier !== undefined && raw.selectedTier !== null) {
+    if (!isRecord(raw.selectedTier) || raw.selectedTier.type !== 'context' || !Number.isSafeInteger(raw.selectedTier.size) || raw.selectedTier.size < 0 || raw.selectedTier.size > 1000000000) return null
+    selectedTier = { type: 'context', size: raw.selectedTier.size }
+  }
   return {
     schemaVersion: COST_SCHEMA_VERSION,
     pricingMode: raw.pricingMode === 'official-model' ? 'official-model' : 'legacy-provider-aware',
@@ -579,6 +837,8 @@ function normalizeCostSnapshot(raw) {
     multiplier,
     billableInputTokens: Number.isFinite(raw.billableInputTokens) ? Math.max(0, Math.trunc(raw.billableInputTokens)) : 0,
     billableOutputTokens: Number.isFinite(raw.billableOutputTokens) ? Math.max(0, Math.trunc(raw.billableOutputTokens)) : 0,
+    ...(contextTokens === null ? {} : { contextTokens }),
+    ...(selectedTier === null ? {} : { selectedTier }),
     rates: normalizedRates,
     breakdown: normalizedBreakdown,
     baseTotal,
@@ -625,7 +885,9 @@ export {
   PRICING_SCHEMA_VERSION,
   RATE_KEYS,
   addCostAggregate,
+  addCostAccumulator,
   calculateCost,
+  createCostAccumulator,
   createEmptyPricingState,
   decimalAdd,
   decimalMultiply,
@@ -633,6 +895,7 @@ export {
   decimalText,
   emptyCostAggregate,
   fetchModelsDevCatalog,
+  isCostAccumulator,
   modelPricingCandidates,
   officialProviderIds,
   normalizeCostSnapshot,