dsh-all-usage 1.1.3 → 1.1.5

package/lib/pricing.js

@@ -1,7 +1,7 @@
 import { createHash } from 'node:crypto'
 
 const PRICING_SCHEMA_VERSION = 1
-const COST_SCHEMA_VERSION = 1
+const COST_SCHEMA_VERSION = 2
 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
@@ -14,6 +14,11 @@ const MAX_CATALOG_CANDIDATES = 30000
 const MAX_OVERRIDES = 500
 const MAX_MAPPINGS = 500
 const MAX_CONTEXT_TIERS = 32
+const MAX_TEMPORAL_RULES = 16
+const MAX_TEMPORAL_WINDOWS = 16
+const MAX_TEMPORAL_POLICIES = 8
+const TEMPORAL_TIMEZONE = 'UTC'
+const TEMPORAL_TIME_SOURCES = ['request-context', 'usage-event', 'legacy-unknown']
 const RATE_KEYS = ['input', 'output', 'cacheRead', 'cacheWrite']
 const INPUT_SEMANTICS = ['legacy', 'total', 'fresh']
 const COST_STATUSES = ['priced', 'unpriced', 'ambiguous', 'unsupported']
@@ -25,7 +30,7 @@ const OFFICIAL_PROVIDER_RULES = [
   { providers: ['anthropic'], prefixes: ['claude-'] },
   { providers: ['google'], prefixes: ['gemini-', 'gemma-'] },
   { providers: ['xai'], prefixes: ['grok-'] },
-  { providers: ['deepseek'], prefixes: ['deepseek-'] },
+  { providers: ['deepseek', 'deepseek-official'], prefixes: ['deepseek-'] },
   { providers: ['moonshotai', 'moonshot'], prefixes: ['kimi-', 'moonshot-'] },
   { providers: ['qwen', 'alibaba'], prefixes: ['qwen'] },
   { providers: ['zai', 'zhipuai', 'zhipu'], prefixes: ['glm-', 'chatglm-'] },
@@ -325,6 +330,227 @@ function decimalRate(raw, keys, fallback = undefined) {
   return decimalText(value)
 }
 
+function temporalRatesOf(raw, fallback) {
+  const rates = isRecord(raw) ? raw : {}
+  const input = decimalRate(rates, ['input', 'inputPerMillion'], fallback && fallback.input)
+  const output = decimalRate(rates, ['output', 'outputPerMillion'], fallback && fallback.output)
+  const cacheRead = decimalRate(rates, ['cacheRead', 'cache_read', 'cacheReadPerMillion'], fallback && fallback.cacheRead)
+  const cacheWrite = decimalRate(rates, ['cacheWrite', 'cache_write', 'cacheCreation', 'cacheWritePerMillion'], fallback && fallback.cacheWrite)
+  if (input === null || output === null || cacheRead === null || cacheWrite === null) return null
+  const parts = [decimalParts(input), decimalParts(output), decimalParts(cacheRead), decimalParts(cacheWrite)]
+  if (parts.some((entry) => entry === null || entry.digits < 0n)) return null
+  return { input, output, cacheRead, cacheWrite }
+}
+
+function normalizeTemporalWindows(raw) {
+  if (!Array.isArray(raw)) return null
+  const windows = []
+  for (const candidate of raw.slice(0, MAX_TEMPORAL_WINDOWS)) {
+    if (!isRecord(candidate)) return null
+    const startMinute = finiteNumber(candidate.startMinute)
+    const endMinute = finiteNumber(candidate.endMinute)
+    if (startMinute === null || endMinute === null || !Number.isInteger(startMinute) || !Number.isInteger(endMinute) || startMinute < 0 || startMinute >= 1440 || endMinute <= startMinute || endMinute > 1440) return null
+    windows.push({ startMinute, endMinute })
+  }
+  if (windows.length === 0) return null
+  // Half-open [start, end) windows that overlap would make the band ambiguous;
+  // deterministic order plus adjacency-only constraint keeps selection stable.
+  windows.sort((left, right) => left.startMinute - right.startMinute || left.endMinute - right.endMinute)
+  for (let index = 1; index < windows.length; index += 1) {
+    if (windows[index].startMinute < windows[index - 1].endMinute) return null
+  }
+  return windows
+}
+
+/** One versioned temporal policy: effective-windowed, UTC-band rules. */
+function normalizeTemporalPolicy(raw, entryDefaultRates = undefined) {
+  if (!isRecord(raw)) return null
+  const policyId = typeof raw.policyId === 'string' && raw.policyId.trim() !== '' ? raw.policyId.trim().slice(0, 128) : ''
+  if (policyId === '') return null
+  const sourceUrl = typeof raw.sourceUrl === 'string' && raw.sourceUrl.trim() !== '' ? raw.sourceUrl.trim().slice(0, 512) : ''
+  const timezone = typeof raw.timezone === 'string' && raw.timezone.trim() !== '' ? raw.timezone.trim().toUpperCase() : TEMPORAL_TIMEZONE
+  // DeepSeek peak/off-peak windows are defined in UTC; any other timezone is
+  // rejected outright so band selection can never depend on the viewer's clock.
+  if (timezone !== TEMPORAL_TIMEZONE) return null
+  const effectiveFrom = raw.effectiveFrom === undefined || raw.effectiveFrom === null ? 0 : finiteNumber(raw.effectiveFrom)
+  const effectiveUntil = raw.effectiveUntil === undefined || raw.effectiveUntil === null ? null : finiteNumber(raw.effectiveUntil)
+  if (effectiveFrom === null || !Number.isSafeInteger(effectiveFrom) || effectiveFrom < 0) return null
+  if (effectiveUntil !== null && (!Number.isSafeInteger(effectiveUntil) || effectiveUntil <= effectiveFrom)) return null
+  let defaultPlan = null
+  if (raw.defaultPlan !== undefined && raw.defaultPlan !== null) {
+    if (!isRecord(raw.defaultPlan)) return null
+    const rates = temporalRatesOf(raw.defaultPlan.rates || raw.defaultPlan, entryDefaultRates)
+    if (rates === null) return null
+    defaultPlan = { id: typeof raw.defaultPlan.id === 'string' && raw.defaultPlan.id.trim() !== '' ? raw.defaultPlan.id.trim().slice(0, 64) : 'default', rates }
+  }
+  if (raw.rules !== undefined && !Array.isArray(raw.rules)) return null
+  if (!Array.isArray(raw.rules)) return null
+  if (raw.rules.length > MAX_TEMPORAL_RULES) return null
+  const rules = []
+  for (const rawRule of raw.rules) {
+    if (!isRecord(rawRule)) return null
+    const id = typeof rawRule.id === 'string' && rawRule.id.trim() !== '' ? rawRule.id.trim().slice(0, 64) : ''
+    if (id === '') return null
+    const weekdays = Array.from(new Set((Array.isArray(rawRule.weekdays) ? rawRule.weekdays : []).map(Number)))
+    if (weekdays.length === 0 || weekdays.some((day) => !Number.isInteger(day) || day < 0 || day > 6)) return null
+    weekdays.sort((left, right) => left - right)
+    const windows = normalizeTemporalWindows(rawRule.windows)
+    if (windows === null) return null
+    const rates = temporalRatesOf(rawRule.rates || rawRule, defaultPlan ? defaultPlan.rates : entryDefaultRates)
+    if (rates === null) return null
+    rules.push({ id, weekdays, windows, rates })
+  }
+  if (rules.length === 0) return null
+  // Rules must never both claim the same weekday minute: a JSON array order
+  // that decides a price is nondeterministic and must be rejected instead.
+  const dayWindows = new Map()
+  for (const rule of rules) {
+    for (const day of rule.weekdays) {
+      let list = dayWindows.get(day)
+      if (list === undefined) { list = []; dayWindows.set(day, list) }
+      for (const window of rule.windows) list.push(window)
+    }
+  }
+  for (const list of dayWindows.values()) {
+    list.sort((left, right) => left.startMinute - right.startMinute || left.endMinute - right.endMinute)
+    for (let index = 1; index < list.length; index += 1) {
+      if (list[index].startMinute < list[index - 1].endMinute) return null
+    }
+  }
+  return { policyId, sourceUrl, timezone, effectiveFrom, effectiveUntil, defaultPlan, rules }
+}
+
+/** Temporal pricing plan: an ordered, non-overlapping archive of policies. */
+function normalizeTemporalPricing(raw, entryDefaultRates = undefined) {
+  if (!isRecord(raw)) return null
+  const rawPolicies = Array.isArray(raw.policies) ? raw.policies : (typeof raw.policyId === 'string' ? [raw] : null)
+  if (rawPolicies === null || rawPolicies.length === 0 || rawPolicies.length > MAX_TEMPORAL_POLICIES) return null
+  const policies = []
+  for (const rawPolicy of rawPolicies) {
+    const policy = normalizeTemporalPolicy(rawPolicy, entryDefaultRates)
+    if (policy === null) return null
+    policies.push(policy)
+  }
+  policies.sort((left, right) => left.effectiveFrom - right.effectiveFrom || (left.policyId < right.policyId ? -1 : left.policyId > right.policyId ? 1 : 0))
+  // A policy whose window never ends must be the last one; successive windows
+  // may leave a gap (which fails closed) but must never overlap.
+  for (let index = 1; index < policies.length; index += 1) {
+    const previous = policies[index - 1]
+    if (previous.effectiveUntil === null || policies[index].effectiveFrom < previous.effectiveUntil) return null
+  }
+  return { policies }
+}
+
+const DEEPSEEK_TEMPORAL_POLICY_ID = 'deepseek-v4-2026-08-pricing'
+const DEEPSEEK_TEMPORAL_POLICY_URL = 'https://api-docs.deepseek.com/quick_start/pricing/'
+// DeepSeek announced peak/off-peak pricing effective 2026-08-16T16:00:00Z; the
+// V4-Flash-Vision-Exp model itself became available on 2026-08-21. Before those
+// instants there is no verifiable band archive, so usage fails closed instead
+// of inheriting today's V4 rates.
+const DEEPSEEK_TEMPORAL_EFFECTIVE_FROM = Date.UTC(2026, 7, 16, 16, 0, 0)
+const DEEPSEEK_VISION_EFFECTIVE_FROM = Date.UTC(2026, 7, 21, 0, 0, 0)
+// Built-in first-party profiles: each model carries its own explicit off-peak
+// (inherited from the live catalog entry) and peak rates; the peak rates are
+// stored as data, never derived as an automatic 'half price' rule.
+const DEEPSEEK_TEMPORAL_MODELS = new Map([
+  ['deepseek-v4-flash', { input: '0.44', output: '1.32', cacheRead: '0.014', cacheWrite: '0', effectiveFrom: DEEPSEEK_TEMPORAL_EFFECTIVE_FROM }],
+  ['deepseek-v4-flash-vision-exp', { input: '0.44', output: '1.32', cacheRead: '0.014', cacheWrite: '0', effectiveFrom: DEEPSEEK_VISION_EFFECTIVE_FROM }],
+  ['deepseek-v4-pro', { input: '1.32', output: '3.96', cacheRead: '0.044', cacheWrite: '0', effectiveFrom: DEEPSEEK_TEMPORAL_EFFECTIVE_FROM }],
+])
+
+function builtinTemporalProfileFor(modelId) {
+  const spec = DEEPSEEK_TEMPORAL_MODELS.get(normalizeModelId(modelId))
+  if (spec === undefined) return null
+  return {
+    policies: [{
+      policyId: DEEPSEEK_TEMPORAL_POLICY_ID,
+      sourceUrl: DEEPSEEK_TEMPORAL_POLICY_URL,
+      timezone: TEMPORAL_TIMEZONE,
+      effectiveFrom: spec.effectiveFrom,
+      effectiveUntil: null,
+      defaultPlan: null,
+      rules: [{ id: 'peak', weekdays: [1, 2, 3, 4, 5], windows: [{ startMinute: 60, endMinute: 240 }, { startMinute: 360, endMinute: 600 }], rates: { input: spec.input, output: spec.output, cacheRead: spec.cacheRead, cacheWrite: spec.cacheWrite } }],
+    }],
+  }
+}
+
+/** Policy covering an instant inside a profile's ordered policy archive. */
+function temporalPolicyFor(profile, atMs) {
+  const policies = isRecord(profile) ? profile.policies : null
+  if (!Array.isArray(policies) || policies.length === 0 || !Number.isFinite(atMs)) return null
+  const at = Math.trunc(atMs)
+  for (const policy of policies) {
+    if (at < policy.effectiveFrom) continue
+    if (policy.effectiveUntil !== null && at >= policy.effectiveUntil) continue
+    return policy
+  }
+  return null
+}
+
+/** UTC half-open band: weekday in rule set AND minute within [start, end). */
+function temporalBand(profile, atMs) {
+  if (!Number.isFinite(atMs) || atMs < 0) return null
+  const policy = temporalPolicyFor(profile, atMs)
+  if (policy === null) return null
+  const matched = matchingTemporalRule(policy, atMs)
+  return matched === null ? 'off-peak' : 'peak'
+}
+
+function matchingTemporalRule(policy, atMs) {
+  const date = new Date(Math.trunc(atMs))
+  const weekday = date.getUTCDay()
+  const minute = date.getUTCHours() * 60 + date.getUTCMinutes()
+  for (const rule of (policy && Array.isArray(policy.rules) ? policy.rules : [])) {
+    if (!(Array.isArray(rule.weekdays) ? rule.weekdays : []).includes(weekday)) continue
+    if ((Array.isArray(rule.windows) ? rule.windows : []).some((window) => minute >= window.startMinute && minute < window.endMinute)) return rule
+  }
+  return null
+}
+
+/**
+ * Deterministic hash of one policy: the policy content only, never the live
+ * catalog rates. A snapshot's policy hash is therefore stable across catalog
+ * refreshes, which keeps historical costs auditable (see the reconciliation
+ * rules); changing the policy itself yields a new hash.
+ */
+function temporalPolicyHash(policy) {
+  const stable = JSON.stringify([
+    policy.policyId,
+    policy.timezone,
+    policy.effectiveFrom,
+    policy.effectiveUntil,
+    policy.defaultPlan,
+    policy.rules,
+  ])
+  return createHash('sha256').update(stable).digest('hex')
+}
+
+/**
+ * Resolve one usage instant against a resolved pricing entry: which policy
+ * covers it, which band applies and which rates that band carries. Returns the
+ * stable signature that both calculateCost() and the snapshot-reuse check
+ * consume.
+ */
+function temporalPlanFor(resolved, pricingAtMs) {
+  if (isRecord(resolved) && resolved.temporalConfigInvalid === true) {
+    return { status: 'config-invalid', band: null, ruleRates: null, policyId: null, policyHash: null, timezone: null, exemptReason: 'temporal-config-invalid' }
+  }
+  const profile = isRecord(resolved) && resolved.temporalProfile ? resolved.temporalProfile : null
+  if (profile === null) {
+    return { status: 'none', band: null, ruleRates: null, policyId: null, policyHash: null, timezone: null, exemptReason: 'no-temporal-profile' }
+  }
+  const route = resolved.temporalRoute === 'official' || resolved.temporalRoute === 'mapped' ? resolved.temporalRoute : 'other'
+  if (route === 'other') return { status: 'other-route', band: null, ruleRates: null, policyId: null, policyHash: null, timezone: null, exemptReason: 'route-not-official' }
+  if (!Number.isFinite(pricingAtMs) || pricingAtMs < 0) return { status: 'time-missing', band: null, ruleRates: null, policyId: null, policyHash: null, timezone: null, exemptReason: null }
+  const at = Math.trunc(pricingAtMs)
+  const policy = temporalPolicyFor(profile, at)
+  if (policy === null) return { status: 'history-gap', band: null, ruleRates: null, policyId: null, policyHash: null, timezone: null, exemptReason: null }
+  const common = { policyId: policy.policyId || null, policyHash: policy.policyHash || null, timezone: policy.timezone === TEMPORAL_TIMEZONE ? TEMPORAL_TIMEZONE : null }
+  const rule = matchingTemporalRule(policy, at)
+  if (rule !== null) return { status: 'applied', band: 'peak', ruleRates: rule.rates, exemptReason: null, ...common }
+  return { status: 'applied', band: 'off-peak', ruleRates: policy.defaultPlan ? policy.defaultPlan.rates : null, exemptReason: null, ...common }
+}
+
 function normalizeContextTier(raw, fallbackRates, legacySize = null) {
   if (!isRecord(raw)) return null
   const descriptor = isRecord(raw.tier) ? raw.tier : raw
@@ -377,6 +603,12 @@ function normalizePriceEntry(raw, sourceDefault = 'models.dev') {
     tiers.length = 0
     tieredInvalid = false
   } else if (tiers.length === 0) tieredInvalid = true
+  const hasTemporalConfig = raw.temporalPricing !== undefined && raw.temporalPricing !== null
+  const temporalPricing = hasTemporalConfig ? normalizeTemporalPricing(raw.temporalPricing, fallbackRates) || undefined : undefined
+  // An explicit invalid config keeps its sentinel across the normalize →
+  // serialize → normalize cycle, so a restart cannot silently re-enable the
+  // built-in profile after a rejected temporalPricing edit.
+  const temporalPricingInvalid = hasTemporalConfig && temporalPricing === undefined ? true : raw.temporalPricingInvalid === true && temporalPricing === undefined
   return {
     providerId: typeof raw.providerId === 'string' ? raw.providerId.trim().toLowerCase() : '',
     providerName: typeof raw.providerName === 'string' ? raw.providerName.trim().slice(0, 200) : '',
@@ -392,6 +624,8 @@ function normalizePriceEntry(raw, sourceDefault = 'models.dev') {
     ...(tiered ? { tiers, tieredInvalid } : {}),
     reasoningRateAvailable: raw.reasoningRateAvailable === true || raw.reasoning !== undefined,
     fetchedAt: Number.isFinite(raw.fetchedAt) ? raw.fetchedAt : 0,
+    ...(temporalPricing === undefined ? {} : { temporalPricing }),
+    ...(temporalPricingInvalid === true ? { temporalPricingInvalid: true } : {}),
   }
 }
 
@@ -559,7 +793,10 @@ function serializePricingState(state) {
 }
 
 function sameRates(left, right) {
-  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
+  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 || left.temporalPricingInvalid !== right.temporalPricingInvalid) return false
+  // Two entries with identical flat rates but different band plans are NOT the
+  // same price: the winner must never depend on enumeration order.
+  if (JSON.stringify(left.temporalPricing || null) !== JSON.stringify(right.temporalPricing || null)) 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
@@ -590,6 +827,32 @@ function findMappedEntry(mapping, state) {
   return null
 }
 
+const DEEPSEEK_OFFICIAL_PROVIDERS = ['deepseek', 'deepseek-official']
+
+function attachTemporalProfile(entry, mapped, identity) {
+  if (entry === null || entry === undefined || !isRecord(entry)) return null
+  // An explicit but invalid temporal config must never silently fall back to
+  // the built-in profile: the configuration error stays visible and the model
+  // fails closed instead of pricing with a plan the user did not write.
+  if (entry.temporalPricingInvalid === true) return { invalid: true }
+  let profile = isRecord(entry.temporalPricing) ? entry.temporalPricing : null
+  if (profile === null && DEEPSEEK_OFFICIAL_PROVIDERS.includes(normalizeProvider(entry.providerId))) profile = builtinTemporalProfileFor(entry.modelId)
+  if (profile === null) return null
+  const providerId = normalizeProvider(entry.providerId)
+  const identityProvider = normalizeProvider(identity && identity.provider)
+  // Safety boundary: the peak/off-peak table applies only when the DSH route
+  // is the first-party provider, or when the user explicitly mapped this route
+  // to the DeepSeek official entry. OpenRouter and other resellers never get
+  // the DeepSeek temporal band automatically.
+  const route = DEEPSEEK_OFFICIAL_PROVIDERS.includes(providerId) && DEEPSEEK_OFFICIAL_PROVIDERS.includes(identityProvider) ? 'official' : mapped !== undefined && mapped !== null ? 'mapped' : 'other'
+  return {
+    route,
+    profile: {
+      policies: profile.policies.map((policy) => ({ ...policy, policyHash: temporalPolicyHash(policy) })),
+    },
+  }
+}
+
 function resolvePricing(identity, rawState) {
   const state = rawState && rawState._normalized === true ? rawState : normalizePricingState(rawState)
   const identityKey = identityKeyOf(identity)
@@ -649,6 +912,7 @@ function resolvePricing(identity, rawState) {
       reasoningRateAvailable: entry.reasoningRateAvailable,
       inputTokenSemantics: mapped && INPUT_SEMANTICS.includes(mapped.inputTokenSemantics) ? mapped.inputTokenSemantics : 'fresh',
       multiplier: mapped ? mapped.multiplier : '1',
+      ...(() => { const temporal = attachTemporalProfile(entry, mapped, identity); return temporal === null ? {} : temporal.invalid === true ? { temporalConfigInvalid: true } : { temporalProfile: temporal.profile, temporalRoute: temporal.route } })(),
     }
   }
   const model = models[0] || null
@@ -706,7 +970,7 @@ function selectContextTier(tiers, contextTokens) {
   return selected
 }
 
-function calculateCost(values, resolved) {
+function calculateCost(values, resolved, pricingAtMs = null, pricingTimeSource = 'usage-event') {
   const input = finiteNumber(values && values.input) || 0
   const output = finiteNumber(values && values.output) || 0
   const cacheRead = finiteNumber(values && values.cacheRead) || 0
@@ -717,10 +981,36 @@ function calculateCost(values, resolved) {
   const tiered = resolved && resolved.tiered === true
   const tiers = tiered && Array.isArray(resolved.tiers) ? resolved.tiers : []
   const tierScheduleValid = !tiered || validContextTierSchedule(tiers)
+  const plan = temporalPlanFor(resolved, pricingAtMs)
+  const pricingAt = Number.isFinite(pricingAtMs) && pricingAtMs >= 0 ? Math.trunc(pricingAtMs) : null
+  const timeSource = TEMPORAL_TIME_SOURCES.includes(pricingTimeSource) ? pricingTimeSource : 'usage-event'
+  let status = tierScheduleValid && resolved && COST_STATUSES.includes(resolved.status) ? resolved.status : tiered ? 'unsupported' : 'unpriced'
+  let reason = tiered && !tierScheduleValid ? 'tiered-pricing-not-modeled' : resolved && typeof resolved.reason === 'string' ? resolved.reason : 'model-not-found'
+  if (status === 'priced') {
+    if (plan.status === 'config-invalid') {
+      // The user submitted a temporal config that failed validation; never
+      // silently price with the built-in profile or the static fallback.
+      status = 'unsupported'
+      reason = 'temporal-config-invalid'
+    } else if (tiered && (plan.status === 'applied' || plan.status === 'history-gap' || plan.status === 'time-missing')) {
+      // Band plans and context tiers are two independent pricing axes; a model
+      // carrying both is not modeled and fails closed instead of guessing.
+      status = 'unsupported'
+      reason = 'temporal-tiered-unsupported'
+    } else if (plan.status === 'history-gap') {
+      // A profile exists but the usage instant falls outside its effective
+      // window: never discount into an unverifiable period.
+      status = 'unsupported'
+      reason = 'temporal-price-history-unavailable'
+    } else if (plan.status === 'time-missing') {
+      status = 'unsupported'
+      reason = 'temporal-time-unavailable'
+    }
+  }
   const base = {
     schemaVersion: COST_SCHEMA_VERSION,
     pricingMode: 'official-model',
-    status: tierScheduleValid && resolved && COST_STATUSES.includes(resolved.status) ? resolved.status : tiered ? 'unsupported' : 'unpriced',
+    status,
     currency: resolved && resolved.currency ? resolved.currency : 'USD',
     source: resolved && resolved.source ? resolved.source : 'none',
     pricingModel: resolved && resolved.pricingModel ? resolved.pricingModel : null,
@@ -729,11 +1019,19 @@ function calculateCost(values, resolved) {
     multiplier: decimalText(resolved && resolved.multiplier !== undefined ? resolved.multiplier : '1') || '1',
     billableInputTokens: Math.trunc(billableInput),
     billableOutputTokens: Math.trunc(billableOutput),
+    pricingAt,
+    pricingTimeSource: timeSource,
+    pricingBand: plan.band,
+    pricingTimezone: plan.timezone,
+    pricingPolicyId: plan.policyId,
+    pricingPolicyHash: plan.policyHash,
+    temporalApplicable: plan.status === 'applied',
+    temporalExemptReason: plan.exemptReason,
     rates: resolved && resolved.rates ? { ...resolved.rates } : { input: '0', output: '0', cacheRead: '0', cacheWrite: '0' },
     breakdown: { input: '0', output: '0', cacheRead: '0', cacheWrite: '0' },
     baseTotal: '0',
     total: '0',
-    reason: tiered && !tierScheduleValid ? 'tiered-pricing-not-modeled' : resolved && typeof resolved.reason === 'string' ? resolved.reason : 'model-not-found',
+    reason,
     tiered,
     reasoningRateAvailable: resolved && resolved.reasoningRateAvailable === true,
   }
@@ -745,6 +1043,10 @@ function calculateCost(values, resolved) {
     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 }
+  } else if (plan.status === 'applied' && plan.ruleRates !== null && typeof plan.ruleRates === 'object') {
+    // Peak windows carry their own rates; off-peak plans without an explicit
+    // default inherit the live entry rates (catalog updates flow through).
+    base.rates = { input: plan.ruleRates.input, output: plan.ruleRates.output, cacheRead: plan.ruleRates.cacheRead, cacheWrite: plan.ruleRates.cacheWrite }
   }
   base.breakdown.input = costPerMillion(base.billableInputTokens, base.rates.input)
   base.breakdown.output = costPerMillion(base.billableOutputTokens, base.rates.output)
@@ -825,6 +1127,21 @@ function normalizeCostSnapshot(raw) {
     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 }
   }
+  const isV2 = raw.schemaVersion === COST_SCHEMA_VERSION
+  const legacy = !isV2
+  let pricingAt = null
+  if (raw.pricingAt !== undefined && raw.pricingAt !== null) {
+    if (!Number.isFinite(raw.pricingAt) || raw.pricingAt < 0 || !Number.isSafeInteger(raw.pricingAt)) return null
+    pricingAt = raw.pricingAt
+  }
+  if (raw.pricingTimeSource !== undefined && raw.pricingTimeSource !== null && raw.pricingTimeSource !== 'legacy-unknown' && !TEMPORAL_TIME_SOURCES.includes(raw.pricingTimeSource)) return null
+  if (raw.pricingBand !== undefined && raw.pricingBand !== null && raw.pricingBand !== 'peak' && raw.pricingBand !== 'off-peak') return null
+  if (raw.pricingTimezone !== undefined && raw.pricingTimezone !== null && raw.pricingTimezone !== 'UTC') return null
+  const pricingTimeSource = TEMPORAL_TIME_SOURCES.includes(raw.pricingTimeSource) ? raw.pricingTimeSource : legacy ? 'legacy-unknown' : null
+  const pricingBand = raw.pricingBand === 'peak' || raw.pricingBand === 'off-peak' ? raw.pricingBand : null
+  const pricingTimezone = raw.pricingTimezone === 'UTC' ? 'UTC' : null
+  const pricingPolicyId = typeof raw.pricingPolicyId === 'string' && raw.pricingPolicyId !== '' ? raw.pricingPolicyId.slice(0, 128) : null
+  const pricingPolicyHash = typeof raw.pricingPolicyHash === 'string' && raw.pricingPolicyHash !== '' ? raw.pricingPolicyHash.slice(0, 128) : null
   return {
     schemaVersion: COST_SCHEMA_VERSION,
     pricingMode: raw.pricingMode === 'official-model' ? 'official-model' : 'legacy-provider-aware',
@@ -837,6 +1154,14 @@ 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,
+    pricingAt,
+    pricingTimeSource,
+    pricingBand,
+    pricingTimezone,
+    pricingPolicyId,
+    pricingPolicyHash,
+    temporalApplicable: raw.temporalApplicable === true,
+    temporalExemptReason: raw.temporalExemptReason === null || raw.temporalExemptReason === undefined ? null : typeof raw.temporalExemptReason === 'string' ? raw.temporalExemptReason.slice(0, 64) : null,
     ...(contextTokens === null ? {} : { contextTokens }),
     ...(selectedTier === null ? {} : { selectedTier }),
     rates: normalizedRates,
@@ -901,8 +1226,12 @@ export {
   normalizeCostSnapshot,
   normalizeModelId,
   normalizePricingState,
+  normalizeTemporalPricing,
   parseModelsDevCatalog,
   resolvePricing,
   serializeCostAggregate,
   serializePricingState,
+  temporalBand,
+  temporalPlanFor,
+  temporalPolicyHash,
 }