dsh-all-usage 1.1.13 → 1.1.15

package/lib/http.js

@@ -138,6 +138,7 @@ export function registerRoutes(host) {
     updatePricingState,
     persistPricing,
     syncPricing,
+    loadHolidayCalendar,
   } = host.pricing
   const { runBaseline } = host.sessionSync
   const { fetchBalance } = host.balance
@@ -239,6 +240,23 @@ export function registerRoutes(host) {
         sendJson(res, result.ok ? 200 : 502, result)
       },
     }))
+    ctx.effect(() => webServer.register({
+      kind: 'exact',
+      path: '/api/all-usage/pricing/holidays',
+      handler: async (req, res) => {
+        if (req.method !== 'POST') { res.statusCode = 405; res.end(); return }
+        if (!isTrustedLocalApiRequest(req, true) || !hasWriteToken(req, state.requestToken)) { rejectRequest(res); return }
+        const body = await readBody(req, 8 * 1024)
+        if (body.tooLarge) { sendJson(res, 413, { ok: false, message: 'request-too-large' }); return }
+        let args = null
+        try { args = JSON.parse(body.text) } catch (err) { /* invalid json */ }
+        const year = args !== null && typeof args === 'object' && !Array.isArray(args) ? Number(args.year) : NaN
+        if (!Number.isSafeInteger(year) || year < 2000 || year > 2100) { sendJson(res, 400, { ok: false, message: 'bad-holiday-request' }); return }
+        // Fetch only: the client freezes the returned dates into a pricing policy.
+        const result = await loadHolidayCalendar(year)
+        sendJson(res, result.ok ? 200 : 502, result)
+      },
+    }))
     ctx.effect(() => webServer.register({
       kind: 'exact',
       path: '/api/all-usage/status',

package/lib/plugin.js

@@ -100,6 +100,7 @@ function apply(ctx) {
     ledgerWriteFailedSessions: new Set(),
     pricingState: createEmptyPricingState(),
     pricingResolutionCache: new Map(),
+    holidayCache: new Map(),
     pricingUnit: null,
     pricingReady: Promise.resolve(),
     pricingWriteChain: Promise.resolve(),

package/lib/pricing-runtime.js

@@ -1,7 +1,12 @@
-import { COST_SCHEMA_VERSION, calculateCost, fetchModelsDevCatalog, normalizeCostSnapshot, normalizePricingState, officialProviderIds, serializeCostAggregate, serializePricingState, temporalPlanFor } from './pricing.js'
+import { COST_SCHEMA_VERSION, builtinTemporalProfileFor, calculateCost, fetchHolidayCalendar, fetchModelsDevCatalog, normalizeCostSnapshot, normalizeModelId, normalizePricingState, officialProviderIds, serializeCostAggregate, serializePricingState, temporalPlanFor } from './pricing.js'
 import { billingInstantOf } from './usage-core.js'
 
 const LEDGER_VERSION = 3
+// One price table row per usage identity; the cap keeps the panel payload bounded.
+const MAX_PRICING_ROWS = 500
+// The holiday arrangement changes at most once a year (and only for the next
+// one); a day-long cache keeps the panel from re-fetching on every open.
+const HOLIDAY_CALENDAR_TTL_MS = 24 * 60 * 60 * 1000
 
 export function createPricingRuntime(host) {
   const { state, markStatsChanged } = host
@@ -44,7 +49,7 @@ export function createPricingRuntime(host) {
     }
     for (const target of targets) addCostAggregateDirection(target, cost, direction)
   }
-  function usedPricingModels(tierSchedules = null) {
+  function usedPricingModels(tierSchedules = null, temporalSchedules = null, detailed = false) {
     const rows = []
     const seen = new Set()
     const scheduleIds = new Map()
@@ -58,19 +63,58 @@ export function createPricingRuntime(host) {
       tierSchedules.push({ id, tiers: tiers.map((tier) => ({ ...tier })) })
       return id
     }
-    for (const item of state.usageByStep.values()) {
-      const identity = coerceIdentity(item.identity || item.modelId)
-      if (seen.has(identity.identityKey)) continue
-      seen.add(identity.identityKey)
-      const resolved = resolveCurrentPricing(identity)
+    // Peak/off-peak plans are shared by every route priced from the same entry,
+    // so they travel once per distinct plan exactly like tier schedules do.
+    const temporalIds = new Map()
+    const temporalScheduleIdFor = (profile) => {
+      if (!Array.isArray(temporalSchedules) || profile === null || typeof profile !== 'object') return null
+      const policies = Array.isArray(profile.policies) ? profile.policies : []
+      if (policies.length === 0) return null
+      // Every attached policy carries the hash of its own content, so the plan
+      // identity is a cheap join instead of a full serialization per row
+      // (falling back to JSON when a hash is missing).
+      const key = policies.every((policy) => typeof policy.policyHash === 'string' && policy.policyHash !== '')
+        ? policies.map((policy) => policy.policyId + ':' + policy.policyHash).join('|')
+        : JSON.stringify(policies)
+      const existing = temporalIds.get(key)
+      if (existing !== undefined) return existing
+      const id = 'temporal-' + temporalSchedules.length
+      temporalIds.set(key, id)
+      temporalSchedules.push({ id, policies: policies.map((policy) => ({ ...policy })) })
+      return id
+    }
+    const providerKey = (value) => (typeof value === 'string' ? value.trim().toLowerCase() : '')
+    // Route identity keys are JSON tuples; rebuilding the exact tuple keeps a
+    // synthetic row on the same resolution-cache entry a real usage row uses.
+    const parseIdentityKey = (identityKey) => {
+      if (typeof identityKey !== 'string' || identityKey === '') return null
+      let parsed = null
+      try { parsed = JSON.parse(identityKey) } catch (err) { return null }
+      if (!Array.isArray(parsed) || parsed.length !== 4) return null
+      const textOrNull = (value) => (typeof value === 'string' && value.trim() !== '' ? value.trim() : null)
+      return { provider: textOrNull(parsed[0]), requestedModel: textOrNull(parsed[1]), actualModel: textOrNull(parsed[2]), legacyLabel: textOrNull(parsed[3]) }
+    }
+    // The price edit target of a row: the entry that is actually in effect. A
+    // priced row edits its resolved entry, an unpriced row gets a new
+    // provider-agnostic manual entry keyed by its own model id.
+    const basisKeyFor = (identity, resolved) => {
+      const priced = resolved.status === 'priced' && typeof resolved.pricingModel === 'string' && resolved.pricingModel !== ''
+      const modelId = priced ? resolved.pricingModel : (identity.actualModel || identity.requestedModel || resolved.pricingModel || identity.label || '')
+      const provider = priced ? resolved.providerId || '' : ''
+      return providerKey(provider) + '\u0000' + normalizeModelId(modelId)
+    }
+    const coveredBases = new Set()
+    const rowOf = (identity, resolved, options = {}) => {
       const tiers = Array.isArray(resolved.tiers) ? resolved.tiers : []
       const tierScheduleId = resolved.tiered === true ? scheduleIdFor(tiers) : null
-      rows.push({
-        identityKey: identity.identityKey,
+      const temporalScheduleId = detailed ? temporalScheduleIdFor(resolved.temporalProfile) : null
+      coveredBases.add(basisKeyFor(identity, resolved))
+      return {
+        identityKey: typeof options.identityKey === 'string' ? options.identityKey : identity.identityKey,
         provider: identity.provider,
         requestedModel: identity.requestedModel,
         actualModel: identity.actualModel,
-        model: identity.label,
+        model: typeof options.model === 'string' && options.model !== '' ? options.model : identity.label,
         status: resolved.status,
         reason: resolved.reason || '',
         pricingModel: resolved.pricingModel || null,
@@ -84,12 +128,67 @@ export function createPricingRuntime(host) {
         tieredInvalid: resolved.tieredInvalid === true,
         inputTokenSemantics: resolved.inputTokenSemantics || 'fresh',
         multiplier: resolved.multiplier || '1',
+        temporalExplicit: resolved.temporalExplicit === true,
+        temporalBuiltin: resolved.temporalBuiltin === true,
+        temporalConfigInvalid: resolved.temporalConfigInvalid === true,
+        ...(detailed ? { usageBacked: options.usageBacked === true } : {}),
+        ...(temporalScheduleId === null ? {} : { temporalScheduleId }),
         ...(resolved.temporalRoute !== undefined && resolved.temporalRoute !== null ? { temporalRoute: resolved.temporalRoute } : {}),
         ...(resolved.temporalProfile && Array.isArray(resolved.temporalProfile.policies) && resolved.temporalProfile.policies.length > 0 ? { temporalPolicyId: String(resolved.temporalProfile.policies[0].policyId || ''), temporalTimezone: resolved.temporalProfile.policies[0].timezone === 'UTC' ? 'UTC' : null } : {}),
-      })
-      if (rows.length >= 500) break
+      }
     }
-    rows.sort((a, b) => String(a.model).localeCompare(String(b.model)))
+    for (const item of state.usageByStep.values()) {
+      const identity = coerceIdentity(item.identity || item.modelId)
+      if (seen.has(identity.identityKey)) continue
+      seen.add(identity.identityKey)
+      rows.push(rowOf(identity, resolveCurrentPricing(identity), { usageBacked: true }))
+      if (rows.length >= MAX_PRICING_ROWS) break
+    }
+    if (detailed) {
+      // Configured rows the ledger never saw: an override or an
+      // identity-scoped mapping would otherwise become invisible and
+      // un-editable in the merged price table.
+      for (const mapping of state.pricingState.mappings) {
+        if (rows.length >= MAX_PRICING_ROWS) break
+        const identityKey = typeof mapping.identityKey === 'string' ? mapping.identityKey.trim() : ''
+        if (identityKey === '' || seen.has(identityKey)) continue
+        seen.add(identityKey)
+        const parsed = parseIdentityKey(identityKey)
+        const provider = parsed !== null ? parsed.provider : (mapping.provider === '' ? null : mapping.provider)
+        const model = parsed !== null ? (parsed.actualModel || parsed.requestedModel || parsed.legacyLabel) : (mapping.model !== '' ? mapping.model : (mapping.catalogModelId === '' ? null : mapping.catalogModelId))
+        const identity = {
+          identityKey,
+          provider,
+          requestedModel: parsed !== null ? parsed.requestedModel : model,
+          actualModel: parsed !== null ? parsed.actualModel : null,
+          label: (provider === null ? '' : provider + ' / ') + (model === null || model === '' ? identityKey : model),
+          legacy: parsed !== null && parsed.legacyLabel !== null && parsed.provider === null && parsed.requestedModel === null && parsed.actualModel === null,
+        }
+        rows.push(rowOf(identity, resolveCurrentPricing(identity), { identityKey, model: identity.label, usageBacked: false }))
+      }
+      for (const entry of state.pricingState.overrides) {
+        if (rows.length >= MAX_PRICING_ROWS) break
+        const key = providerKey(entry.providerId) + '\u0000' + normalizeModelId(entry.modelId)
+        if (coveredBases.has(key)) continue
+        coveredBases.add(key)
+        // A non-JSON key: it can never collide with a real route key (those are
+        // always JSON tuples), so a configured row cannot poison the shared
+        // resolution cache the way a constant key would.
+        const identity = {
+          identityKey: 'override:' + key,
+          provider: entry.providerId === '' ? null : entry.providerId,
+          requestedModel: entry.modelId,
+          actualModel: null,
+          label: entry.displayName || entry.modelId,
+          legacy: false,
+        }
+        rows.push(rowOf(identity, resolveCurrentPricing(identity), { identityKey: '', model: entry.displayName || entry.modelId, usageBacked: false }))
+      }
+    }
+    rows.sort((left, right) => {
+      if (left.usageBacked !== right.usageBacked) return left.usageBacked === true ? -1 : 1
+      return String(left.model).localeCompare(String(right.model))
+    })
     return rows
   }
   function pricingModelSearch(query, limit = 20) {
@@ -105,7 +204,20 @@ export function createPricingRuntime(host) {
       if (!modelId.includes(normalized) && !displayName.includes(normalized)) continue
       const score = modelId === normalized ? 0 : modelId.startsWith(normalized) ? 1 : displayName.startsWith(normalized) ? 2 : 3
       const previous = selected.get(entry.modelId)
-      if (previous === undefined || score < previous.score) selected.set(entry.modelId, { value: entry.modelId, label: entry.displayName, providerId: entry.providerId, tiered: entry.tiered === true, tierCount: Array.isArray(entry.tiers) ? entry.tiers.length : 0, score })
+      // The mapping column previews the target price before saving, so the
+      // search result must carry the rates and the built-in peak/off-peak
+      // capability (never the whole catalog entry).
+      if (previous === undefined || score < previous.score) selected.set(entry.modelId, {
+        value: entry.modelId,
+        label: entry.displayName,
+        providerId: entry.providerId,
+        providerName: entry.providerName || '',
+        tiered: entry.tiered === true,
+        tierCount: Array.isArray(entry.tiers) ? entry.tiers.length : 0,
+        rates: { input: entry.input, output: entry.output, cacheRead: entry.cacheRead, cacheWrite: entry.cacheWrite },
+        builtinTemporal: builtinTemporalProfileFor(entry.modelId) !== null,
+        score,
+      })
     }
     return Array.from(selected.values()).sort((a, b) => a.score - b.score || a.value.localeCompare(b.value)).slice(0, Math.max(1, Math.min(50, Number.isInteger(limit) ? limit : 20))).map(({ score, ...entry }) => entry)
   }
@@ -113,6 +225,7 @@ export function createPricingRuntime(host) {
     const pricingStateSnapshot = state.pricingState
     const detailed = options.detailed !== false
     const tierSchedules = detailed ? [] : null
+    const temporalSchedules = detailed ? [] : null
     const snapshot = {
       schemaVersion: pricingStateSnapshot.schemaVersion,
       source: { ...pricingStateSnapshot.source },
@@ -121,16 +234,25 @@ export function createPricingRuntime(host) {
       overrideCount: pricingStateSnapshot.overrides.length,
       mappingCount: pricingStateSnapshot.mappings.length,
       configured: pricingStateSnapshot.catalogEntries.length > 0 || pricingStateSnapshot.overrides.length > 0 || pricingStateSnapshot.mappings.length > 0,
-      usedModels: usedPricingModels(tierSchedules),
+      usedModels: usedPricingModels(tierSchedules, temporalSchedules, detailed),
       cost: serializeCostAggregate(state.totals.cost),
     }
     if (detailed) {
       snapshot.config = {
         sync: { ...pricingStateSnapshot.sync },
         mappings: pricingStateSnapshot.mappings.map((mapping) => ({ ...mapping })),
-        overrides: pricingStateSnapshot.overrides.map(({ providerId, ...entry }) => ({ ...entry, ...(Array.isArray(entry.tiers) ? { tiers: entry.tiers.map((tier) => ({ ...tier })) } : {}) })),
+        // providerId and the peak/off-peak plan must round-trip: dropping
+        // providerId would turn a provider-scoped manual price into a
+        // provider-agnostic one on the next save (and would stop it from
+        // being found as a mapping target).
+        overrides: pricingStateSnapshot.overrides.map((entry) => ({
+          ...entry,
+          ...(Array.isArray(entry.tiers) ? { tiers: entry.tiers.map((tier) => ({ ...tier })) } : {}),
+          ...(entry.temporalPricing === undefined ? {} : { temporalPricing: JSON.parse(JSON.stringify(entry.temporalPricing)) }),
+        })),
       }
       snapshot.tierSchedules = tierSchedules
+      snapshot.temporalSchedules = temporalSchedules
     }
     return snapshot
   }
@@ -264,7 +386,7 @@ export function createPricingRuntime(host) {
   }
   function costSnapshotEquivalent(left, right) {
     if (left === null || right === null || typeof left !== 'object' || typeof right !== 'object') return false
-    if (left.status !== right.status || left.currency !== right.currency || left.pricingModel !== right.pricingModel || left.providerId !== right.providerId || left.inputTokenSemantics !== right.inputTokenSemantics || left.multiplier !== right.multiplier || left.billableInputTokens !== right.billableInputTokens || left.billableOutputTokens !== right.billableOutputTokens || left.baseTotal !== right.baseTotal || left.total !== right.total || left.reason !== right.reason || left.tiered !== right.tiered || left.contextTokens !== right.contextTokens || left.pricingAt !== right.pricingAt || left.pricingTimeSource !== right.pricingTimeSource || left.pricingBand !== right.pricingBand || left.pricingPolicyId !== right.pricingPolicyId || left.pricingPolicyHash !== right.pricingPolicyHash || left.pricingTimezone !== right.pricingTimezone || left.temporalApplicable !== right.temporalApplicable || left.temporalExemptReason !== right.temporalExemptReason) return false
+    if (left.status !== right.status || left.currency !== right.currency || left.pricingModel !== right.pricingModel || left.providerId !== right.providerId || left.inputTokenSemantics !== right.inputTokenSemantics || left.multiplier !== right.multiplier || left.billableInputTokens !== right.billableInputTokens || left.billableOutputTokens !== right.billableOutputTokens || left.baseTotal !== right.baseTotal || left.total !== right.total || left.reason !== right.reason || left.tiered !== right.tiered || left.contextTokens !== right.contextTokens || left.pricingAt !== right.pricingAt || left.pricingTimeSource !== right.pricingTimeSource || left.pricingBand !== right.pricingBand || left.pricingHoliday !== right.pricingHoliday || left.pricingPolicyId !== right.pricingPolicyId || left.pricingPolicyHash !== right.pricingPolicyHash || left.pricingTimezone !== right.pricingTimezone || left.temporalApplicable !== right.temporalApplicable || left.temporalExemptReason !== right.temporalExemptReason) return false
     for (const key of ['input', 'output', 'cacheRead', 'cacheWrite']) {
       if (left.breakdown !== null && left.breakdown !== undefined && right.breakdown !== null && right.breakdown !== undefined) {
         if (left.breakdown[key] !== right.breakdown[key]) return false
@@ -377,6 +499,28 @@ export function createPricingRuntime(host) {
     schedulePricingSync()
     return { ...result, temporalReconciled: temporal.reconciled }
   }
+  /**
+   * Fetch one year of the Chinese holiday arrangement for the editor. Nothing is
+   * persisted here: the panel freezes the returned dates into a pricing policy,
+   * which is what makes later reconciliation reproducible.
+   */
+  async function loadHolidayCalendar(year) {
+    const cache = state.holidayCache instanceof Map ? state.holidayCache : (state.holidayCache = new Map())
+    const key = String(Number(year))
+    const cached = cache.get(key)
+    if (cached !== undefined && Date.now() - cached.fetchedAt < HOLIDAY_CALENDAR_TTL_MS) return { ok: true, cached: true, ...cached }
+    const result = await fetchHolidayCalendar(year)
+    if (!result.ok) return result
+    const entry = {
+      year: result.calendar.year,
+      dates: result.calendar.dates,
+      paperUrl: result.calendar.paperUrl,
+      sourceUrl: result.calendar.sourceUrl,
+      fetchedAt: result.calendar.fetchedAt,
+    }
+    cache.set(key, entry)
+    return { ok: true, cached: false, ...entry }
+  }
   function schedulePricingSync() {
     if (state.pricingSyncTimer !== null) { clearTimeout(state.pricingSyncTimer); state.pricingSyncTimer = null }
     if (state.disposed || state.pricingState.sync.autoEnabled !== true) return
@@ -401,6 +545,7 @@ export function createPricingRuntime(host) {
     backfillUnpricedCosts,
     reconcileTemporalPricing,
     updatePricingState,
-    schedulePricingSync
+    schedulePricingSync,
+    loadHolidayCalendar
   }
 }

package/lib/pricing.js

@@ -17,7 +17,18 @@ const MAX_CONTEXT_TIERS = 32
 const MAX_TEMPORAL_RULES = 16
 const MAX_TEMPORAL_WINDOWS = 16
 const MAX_TEMPORAL_POLICIES = 8
+const MAX_TEMPORAL_HOLIDAYS = 400
 const TEMPORAL_TIMEZONE = 'UTC'
+// Statutory-holiday dates are China Standard Time calendar days; a UTC policy
+// band therefore runs from 16:00Z the day before to 16:00Z on the day itself.
+const TEMPORAL_HOLIDAY_OFFSET_MS = 8 * 60 * 60 * 1000
+// Public, no-key datasets of the State Council holiday arrangement (the file per
+// year carries `days[].isOffDay`, and the official gov.cn notice in `papers`).
+const HOLIDAY_CALENDAR_BASES = [
+  'https://cdn.jsdelivr.net/gh/NateScarlet/holiday-cn@master/',
+  'https://raw.githubusercontent.com/NateScarlet/holiday-cn/master/',
+]
+const MAX_HOLIDAY_CALENDAR_BYTES = 512 * 1024
 const TEMPORAL_TIME_SOURCES = ['request-context', 'usage-event', 'legacy-unknown']
 const RATE_KEYS = ['input', 'output', 'cacheRead', 'cacheWrite']
 const INPUT_SEMANTICS = ['legacy', 'total', 'fresh']
@@ -362,6 +373,60 @@ function normalizeTemporalWindows(raw) {
   return windows
 }
 
+function normalizeHolidayDate(value) {
+  if (typeof value !== 'string') return null
+  const text = value.trim()
+  const match = text.match(/^([0-9]{4})-([0-9]{2})-([0-9]{2})$/)
+  if (match === null) return null
+  const year = Number(match[1])
+  const month = Number(match[2])
+  const day = Number(match[3])
+  if (year < 2000 || year > 2100) return null
+  const date = new Date(Date.UTC(year, month - 1, day))
+  if (date.getUTCFullYear() !== year || date.getUTCMonth() !== month - 1 || date.getUTCDate() !== day) return null
+  return text
+}
+
+/** Explicit statutory-holiday dates: sorted, de-duplicated, strictly shaped. */
+function normalizeTemporalHolidays(raw) {
+  if (raw === undefined || raw === null) return []
+  if (!Array.isArray(raw)) return null
+  const seen = new Set()
+  const days = []
+  for (const candidate of raw) {
+    const text = normalizeHolidayDate(candidate)
+    if (text === null) return null
+    if (seen.has(text)) continue
+    seen.add(text)
+    days.push(text)
+    if (days.length > MAX_TEMPORAL_HOLIDAYS) return null
+  }
+  days.sort()
+  return days
+}
+
+const TEMPORAL_HOLIDAY_SETS = new WeakMap()
+/** Cached lookup set for one policy's holiday list. */
+function holidaySetFor(policy) {
+  if (!isRecord(policy)) return null
+  const holidays = Array.isArray(policy.holidays) ? policy.holidays : null
+  if (holidays === null || holidays.length === 0) return null
+  let set = TEMPORAL_HOLIDAY_SETS.get(policy)
+  if (set === undefined) {
+    set = new Set(holidays)
+    TEMPORAL_HOLIDAY_SETS.set(policy, set)
+  }
+  return set
+}
+/** True when the instant falls on one of the policy's statutory holidays (CST day). */
+function holidayCoversInstant(policy, atMs) {
+  const set = holidaySetFor(policy)
+  if (set === null || !Number.isFinite(atMs)) return false
+  const local = new Date(Math.trunc(atMs) + TEMPORAL_HOLIDAY_OFFSET_MS)
+  const text = String(local.getUTCFullYear()) + '-' + String(local.getUTCMonth() + 1).padStart(2, '0') + '-' + String(local.getUTCDate()).padStart(2, '0')
+  return set.has(text)
+}
+
 /** One versioned temporal policy: effective-windowed, UTC-band rules. */
 function normalizeTemporalPolicy(raw, entryDefaultRates = undefined) {
   if (!isRecord(raw)) return null
@@ -417,7 +482,13 @@ function normalizeTemporalPolicy(raw, entryDefaultRates = undefined) {
       if (list[index].startMinute < list[index - 1].endMinute) return null
     }
   }
-  return { policyId, sourceUrl, timezone, effectiveFrom, effectiveUntil, defaultPlan, rules }
+  const holidays = normalizeTemporalHolidays(raw.holidays)
+  if (holidays === null) return null
+  // Provenance of a fetched holiday list. Deliberately NOT part of the policy
+  // hash: where the dates came from does not change what they price, but it is
+  // kept next to them so a frozen list can be traced back.
+  const holidaysSource = typeof raw.holidaysSource === 'string' ? raw.holidaysSource.trim().slice(0, 512) : ''
+  return { policyId, sourceUrl, timezone, effectiveFrom, effectiveUntil, defaultPlan, holidays, holidaysSource, rules }
 }
 
 /** Temporal pricing plan: an ordered, non-overlapping archive of policies. */
@@ -452,13 +523,34 @@ 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.
+// models.dev publishes `deepseek-flash` (DeepSeek V4.1 Flash) in the same
+// `deepseek-flash` family and at the same standard rates as
+// `deepseek-v4-flash`, so it shares that band; a variant that arrives with
+// different standard rates still needs its own row.
 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-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) {
+// DeepSeek's own peak table excludes Chinese public holidays (`周一至周五（不含中国
+// 法定节假日）`), so the built-in plan has to carry the arrangement itself; otherwise
+// holiday requests are charged at peak rates. The list below is the 2026 arrangement
+// from the State Council notice. Later years ship with a plugin update, and any plan
+// (a built-in copy or a custom one) can be extended by hand or fetched at runtime
+// through POST /api/all-usage/pricing/holidays.
+const CHINA_HOLIDAY_SOURCE_2026 = 'https://www.gov.cn/zhengce/zhengceku/202511/content_7047091.htm'
+const CHINA_HOLIDAYS_2026 = [
+  '2026-01-01', '2026-01-02', '2026-01-03', '2026-02-15', '2026-02-16', '2026-02-17',
+  '2026-02-18', '2026-02-19', '2026-02-20', '2026-02-21', '2026-02-22', '2026-02-23',
+  '2026-04-04', '2026-04-05', '2026-04-06', '2026-05-01', '2026-05-02', '2026-05-03',
+  '2026-05-04', '2026-05-05', '2026-06-19', '2026-06-20', '2026-06-21', '2026-09-25',
+  '2026-09-26', '2026-09-27', '2026-10-01', '2026-10-02', '2026-10-03', '2026-10-04',
+  '2026-10-05', '2026-10-06', '2026-10-07',
+]
+
+export function builtinTemporalProfileFor(modelId) {
   const spec = DEEPSEEK_TEMPORAL_MODELS.get(normalizeModelId(modelId))
   if (spec === undefined) return null
   return {
@@ -469,6 +561,8 @@ function builtinTemporalProfileFor(modelId) {
       effectiveFrom: spec.effectiveFrom,
       effectiveUntil: null,
       defaultPlan: null,
+      holidays: CHINA_HOLIDAYS_2026,
+      holidaysSource: CHINA_HOLIDAY_SOURCE_2026 + ' · 2026 中国法定节假日安排',
       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 } }],
     }],
   }
@@ -492,6 +586,8 @@ function temporalBand(profile, atMs) {
   if (!Number.isFinite(atMs) || atMs < 0) return null
   const policy = temporalPolicyFor(profile, atMs)
   if (policy === null) return null
+  // A statutory holiday is a full off-peak day: no rule can claim its instants.
+  if (holidayCoversInstant(policy, atMs)) return 'off-peak'
   const matched = matchingTemporalRule(policy, atMs)
   return matched === null ? 'off-peak' : 'peak'
 }
@@ -520,6 +616,7 @@ function temporalPolicyHash(policy) {
     policy.effectiveFrom,
     policy.effectiveUntil,
     policy.defaultPlan,
+    policy.holidays,
     policy.rules,
   ])
   return createHash('sha256').update(stable).digest('hex')
@@ -546,9 +643,12 @@ function temporalPlanFor(resolved, 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 }
+  // A statutory holiday is a full off-peak day; its audit flag is stored with
+  // the cost snapshot so a ledger row can explain why it was off-peak.
+  if (holidayCoversInstant(policy, at)) return { status: 'applied', band: 'off-peak', ruleRates: policy.defaultPlan ? policy.defaultPlan.rates : null, holiday: true, exemptReason: null, ...common }
   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 }
+  if (rule !== null) return { status: 'applied', band: 'peak', ruleRates: rule.rates, holiday: false, exemptReason: null, ...common }
+  return { status: 'applied', band: 'off-peak', ruleRates: policy.defaultPlan ? policy.defaultPlan.rates : null, holiday: false, exemptReason: null, ...common }
 }
 
 function normalizeContextTier(raw, fallbackRates, legacySize = null) {
@@ -836,7 +936,15 @@ function attachTemporalProfile(entry, mapped, identity) {
   // 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)
+  // The editor needs to tell a user-authored plan from the built-in DeepSeek
+  // table: only the former can be reset, the latter is re-attached on every
+  // resolution and must never be silently frozen into an override.
+  const explicit = profile !== null
+  let builtin = false
+  if (profile === null && DEEPSEEK_OFFICIAL_PROVIDERS.includes(normalizeProvider(entry.providerId))) {
+    profile = builtinTemporalProfileFor(entry.modelId)
+    builtin = profile !== null
+  }
   if (profile === null) return null
   const providerId = normalizeProvider(entry.providerId)
   const identityProvider = normalizeProvider(identity && identity.provider)
@@ -847,6 +955,8 @@ function attachTemporalProfile(entry, mapped, identity) {
   const route = DEEPSEEK_OFFICIAL_PROVIDERS.includes(providerId) && DEEPSEEK_OFFICIAL_PROVIDERS.includes(identityProvider) ? 'official' : mapped !== undefined && mapped !== null ? 'mapped' : 'other'
   return {
     route,
+    explicit,
+    builtin,
     profile: {
       policies: profile.policies.map((policy) => ({ ...policy, policyHash: temporalPolicyHash(policy) })),
     },
@@ -912,7 +1022,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 temporal = attachTemporalProfile(entry, mapped, identity); return temporal === null ? {} : temporal.invalid === true ? { temporalConfigInvalid: true } : { temporalProfile: temporal.profile, temporalRoute: temporal.route, temporalExplicit: temporal.explicit === true, temporalBuiltin: temporal.builtin === true } })(),
     }
   }
   const model = models[0] || null
@@ -1022,6 +1132,7 @@ function calculateCost(values, resolved, pricingAtMs = null, pricingTimeSource =
     pricingAt,
     pricingTimeSource: timeSource,
     pricingBand: plan.band,
+    pricingHoliday: plan.holiday === true,
     pricingTimezone: plan.timezone,
     pricingPolicyId: plan.policyId,
     pricingPolicyHash: plan.policyHash,
@@ -1157,6 +1268,7 @@ function normalizeCostSnapshot(raw) {
     pricingAt,
     pricingTimeSource,
     pricingBand,
+    pricingHoliday: raw.pricingHoliday === true,
     pricingTimezone,
     pricingPolicyId,
     pricingPolicyHash,
@@ -1201,6 +1313,69 @@ async function fetchModelsDevCatalog(fetchImpl = globalThis.fetch, options = {})
   }
 }
 
+/** Turn one holiday-cn dataset into the explicit off-day list the policy stores. */
+export function parseHolidayCalendar(raw, year) {
+  if (!isRecord(raw)) return { ok: false, error: 'holiday-calendar-not-object' }
+  if (raw.year !== undefined && raw.year !== null && Number(raw.year) !== Number(year)) return { ok: false, error: 'holiday-calendar-year-mismatch' }
+  if (!Array.isArray(raw.days)) return { ok: false, error: 'holiday-calendar-days-missing' }
+  const seen = new Set()
+  const dates = []
+  for (const day of raw.days) {
+    if (!isRecord(day) || day.isOffDay !== true) continue
+    const text = normalizeHolidayDate(day.date)
+    if (text === null) return { ok: false, error: 'holiday-calendar-date-invalid' }
+    if (seen.has(text)) continue
+    seen.add(text)
+    dates.push(text)
+  }
+  if (dates.length === 0) return { ok: false, error: 'holiday-calendar-empty' }
+  if (dates.length > MAX_TEMPORAL_HOLIDAYS) return { ok: false, error: 'holiday-calendar-too-large' }
+  dates.sort()
+  const papers = Array.isArray(raw.papers) ? raw.papers.filter((item) => typeof item === 'string' && item.trim() !== '').map((item) => item.trim().slice(0, 512)) : []
+  return { ok: true, calendar: { year: Number(year), dates, paperUrl: papers.length > 0 ? papers[0] : '', fetchedAt: 0 } }
+}
+
+/**
+ * Fetch one year of the Chinese holiday arrangement. The result is never applied
+ * automatically: the caller freezes the returned dates into a pricing policy, so
+ * later ledger reconciliation stays reproducible even if the upstream changes.
+ */
+export async function fetchHolidayCalendar(year, fetchImpl = globalThis.fetch, options = {}) {
+  const value = Number(year)
+  if (!Number.isSafeInteger(value) || value < 2000 || value > 2100) return { ok: false, error: 'holiday-year-invalid' }
+  if (typeof fetchImpl !== 'function') return { ok: false, error: 'fetch-unavailable' }
+  const timeoutMs = Number.isFinite(options.timeoutMs) && options.timeoutMs > 0 ? options.timeoutMs : 15000
+  const bases = Array.isArray(options.bases) && options.bases.length > 0 ? options.bases : HOLIDAY_CALENDAR_BASES
+  let lastError = 'holiday-calendar-unavailable'
+  for (const base of bases) {
+    const url = String(base) + value + '.json'
+    let controller = null
+    let timer = null
+    try {
+      if (typeof AbortController === 'function') {
+        controller = new AbortController()
+        timer = setTimeout(() => controller.abort(), timeoutMs)
+      }
+      const response = await fetchImpl(url, { headers: { accept: 'application/json' }, signal: controller ? controller.signal : undefined })
+      if (!response || response.ok !== true) { lastError = 'http-' + String((response && response.status) || 0); continue }
+      const length = response.headers && typeof response.headers.get === 'function' ? Number(response.headers.get('content-length')) : 0
+      if (Number.isFinite(length) && length > MAX_HOLIDAY_CALENDAR_BYTES) { lastError = 'holiday-calendar-too-large'; continue }
+      const text = await response.text()
+      if (new TextEncoder().encode(text).length > MAX_HOLIDAY_CALENDAR_BYTES) { lastError = 'holiday-calendar-too-large'; continue }
+      let parsed = null
+      try { parsed = JSON.parse(text.replace(/^\uFEFF/, '')) } catch (err) { lastError = 'holiday-calendar-invalid-json'; continue }
+      const result = parseHolidayCalendar(parsed, value)
+      if (!result.ok) { lastError = result.error; continue }
+      return { ok: true, calendar: { ...result.calendar, sourceUrl: url, fetchedAt: Date.now() } }
+    } catch (err) {
+      lastError = 'holiday-calendar-fetch-failed'
+    } finally {
+      if (timer !== null) clearTimeout(timer)
+    }
+  }
+  return { ok: false, error: lastError }
+}
+
 export {
   COST_SCHEMA_VERSION,
   COST_STATUSES,