dsh-usage-badge 0.1.0

package/lib/fold.js

@@ -0,0 +1,512 @@
+/**
+ * dsh-usage-badge — session-log folding and its incremental cache.
+ *
+ * DSH persists one append-only log per session under `$DSH_HOME/sessions`. This
+ * module folds every log it finds into per-day / per-(provider, model) token
+ * buckets holding the raw per-request usage records, which is what lets the
+ * pricing layer apply a different multiplier to each request instead of pricing
+ * a day at one flat rate.
+ *
+ * Ported from the desktop shell's `usage-sidecar.mjs` fold, with the same
+ * discovery rules (generation selection per session directory) and the same
+ * size/mtime cursor that keeps a refresh proportional to what actually changed.
+ * The cache file is this plugin's own (`usage-badge-cache.json`) rather than the
+ * shell's `usage-cache.json`: both read the same logs, but sharing one cache file
+ * would mean two writers racing over it.
+ *
+ * @module dsh-usage-badge/fold
+ */
+
+import { mkdirSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { zstdDecompressSync } from 'node:zlib'
+
+import { dayKey, initHourly, localHour } from './pricing.js'
+
+/** Bucket key and display name used when a log records no provider/model. */
+export const UNKNOWN = 'unknown'
+
+/** Matches `session.jsonl`, `session.jsonl.zstd`, `session.v2.jsonl(.zstd)`, … */
+const SESSION_LOG_RE = /^session(?:\.v(\d+))?\.jsonl(?:\.zstd)?$/
+
+const ZSTD_MAGIC = Buffer.from([0x28, 0xb5, 0x2f, 0xfd])
+
+/** This plugin's cache format version. Unknown versions are ignored, not migrated. */
+const CACHE_VERSION = 1
+
+/** Files folded between event-loop yields, so a cold scan never stalls the host. */
+const YIELD_EVERY = 25
+
+/** Expand `~`, `~/`, `~\` against the OS home. */
+function expandHome(path) {
+  if (path === '~') return homedir()
+  if (path.startsWith('~/') || path.startsWith('~\\')) return join(homedir(), path.slice(2))
+  return path
+}
+
+/**
+ * Resolve the DeepSeek Harness home.
+ *
+ * This mirrors `resolveDshHome()` from `@deepseek-ai/dsh-home-paths`, inlined so
+ * the plugin needs no peer dependency: an explicit path, then a non-blank
+ * `$DSH_HOME`, then `~/.dsh`. A whitespace-only `$DSH_HOME` counts as unset, so a
+ * blank override can never resolve the home to the current directory.
+ */
+export function resolveDshHome(configured, env = process.env) {
+  const fromEnv = env?.DSH_HOME
+  const chosen =
+    configured ?? (typeof fromEnv === 'string' && fromEnv.trim().length > 0 ? fromEnv : join(homedir(), '.dsh'))
+  return resolve(expandHome(chosen))
+}
+
+/**
+ * Decode a log body that may hold one or more concatenated zstd frames.
+ *
+ * DSH appends frames as a session grows, so a `.zstd` log is a frame sequence
+ * rather than one stream; `zstdDecompressSync` handles a single frame, so the
+ * buffer is split on the frame magic first. A body with no frame magic is
+ * returned as UTF-8, which keeps plain `.jsonl` and any partially written file
+ * readable instead of throwing.
+ */
+export function decodeLogBody(buf) {
+  const starts = []
+  let i = 0
+  while ((i = buf.indexOf(ZSTD_MAGIC, i)) !== -1) {
+    starts.push(i)
+    i += 1
+  }
+  if (starts.length === 0) return buf.toString('utf8')
+  if (typeof zstdDecompressSync !== 'function') {
+    throw new Error('this Node build has no zlib.zstdDecompressSync; a zstd session log cannot be read')
+  }
+  let out = ''
+  for (let k = 0; k < starts.length; k++) {
+    const end = k + 1 < starts.length ? starts[k + 1] : buf.length
+    out += zstdDecompressSync(buf.subarray(starts[k], end)).toString('utf8')
+  }
+  return out
+}
+
+function logParent(file) {
+  const index = Math.max(file.lastIndexOf('\\'), file.lastIndexOf('/'))
+  return index >= 0 ? file.slice(0, index) : ''
+}
+
+/** Rank a log file within its session directory: generation first, then `.zstd` over plain. */
+function logRank(file) {
+  const index = Math.max(file.lastIndexOf('\\'), file.lastIndexOf('/'))
+  const name = index >= 0 ? file.slice(index + 1) : file
+  const match = SESSION_LOG_RE.exec(name)
+  if (!match) return -1
+  return (Number(match[1]) || 0) * 2 + (name.endsWith('.zstd') ? 1 : 0)
+}
+
+/**
+ * Every log file under `dir`, keeping only the newest generation per session
+ * directory.
+ *
+ * A migrated session can leave older artifacts beside its current log; those are
+ * generations of one session, not sessions to add up. Picking the highest
+ * generation per directory is also what keeps a future `v3`/`v4` log correct
+ * without a code change.
+ */
+export function listLogFiles(dir, root = dir, out = []) {
+  let entries
+  try {
+    entries = readdirSync(dir, { withFileTypes: true })
+  } catch {
+    return out
+  }
+  for (const entry of entries) {
+    const full = join(dir, entry.name)
+    if (entry.isDirectory()) listLogFiles(full, root, out)
+    else if (SESSION_LOG_RE.test(entry.name)) out.push(full)
+  }
+  if (dir === root) {
+    const best = new Map()
+    for (const file of out) {
+      const parent = logParent(file)
+      const current = best.get(parent)
+      if (!current || logRank(file) > logRank(current)) best.set(parent, file)
+    }
+    return out.filter((file) => best.get(logParent(file)) === file)
+  }
+  return out
+}
+
+/** The session id a log path belongs to (its containing directory name). */
+export function sessionIdFromLogPath(file) {
+  const parts = file.split(/[\\/]/)
+  return parts.length >= 2 ? parts[parts.length - 2] : file
+}
+
+function emptyBucket(provider, model) {
+  return {
+    provider,
+    model,
+    input: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    output: 0,
+    requests: 0,
+    hourly: initHourly(),
+    usageRecords: [],
+  }
+}
+
+/**
+ * Add `source` into `target`.
+ *
+ * A missing per-request list marks a legacy aggregate row: mixing one into a
+ * bucket that has a list would silently drop the aggregate's share from the
+ * context-tier price, so the list is dropped to `null` for the whole bucket
+ * instead, and that bucket falls back to flat pricing. Appending is looped rather
+ * than spread because one day bucket can hold hundreds of thousands of requests,
+ * which would overflow the argument list long before it exhausted memory.
+ */
+function addBucket(target, source) {
+  target.input += Number(source?.input) || 0
+  target.cacheRead += Number(source?.cacheRead) || 0
+  target.cacheWrite += Number(source?.cacheWrite) || 0
+  target.output += Number(source?.output) || 0
+  target.requests += Number(source?.requests) || 0
+  if (!Array.isArray(target.hourly)) target.hourly = initHourly()
+  if (Array.isArray(source?.hourly)) {
+    for (let hour = 0; hour < 24; hour++) {
+      const from = source.hourly[hour]
+      const to = target.hourly[hour]
+      if (!from || !to) continue
+      to.input += Number(from.input) || 0
+      to.cacheRead += Number(from.cacheRead) || 0
+      to.cacheWrite += Number(from.cacheWrite) || 0
+      to.output += Number(from.output) || 0
+      to.requests += Number(from.requests) || 0
+    }
+  }
+  if (!Array.isArray(target.usageRecords) || !Array.isArray(source?.usageRecords)) {
+    target.usageRecords = null
+  } else {
+    for (const usage of source.usageRecords) {
+      if (usage && typeof usage === 'object') target.usageRecords.push(usage)
+    }
+  }
+}
+
+/**
+ * Fold one session log into per-day, per-route buckets.
+ *
+ * Route attribution follows the log's own control events: `request/header` (and
+ * `request/context`) carry the provider and model, and each `assistant/message`
+ * carries the provider-reported `usage` for one completed request. Requests are
+ * stamped with the hour they were *sent* where the log allows it, because a
+ * streaming call can cross a peak/valley boundary and filing it by completion
+ * would price it in the wrong band.
+ *
+ * @returns {object|null} the session record, or null when the file is unreadable.
+ */
+export function foldSession(file, previous) {
+  const sessionId = sessionIdFromLogPath(file)
+  let stat
+  try {
+    stat = statSync(file)
+  } catch {
+    return null
+  }
+  let body
+  try {
+    body = readFileSync(file)
+  } catch {
+    return null
+  }
+  let text
+  try {
+    text = decodeLogBody(body)
+  } catch {
+    // An unreadable body keeps whatever this session contributed before, so a
+    // transient decompression failure cannot erase history.
+    return previous ?? null
+  }
+
+  const sessionDays = new Map()
+  let provider = null
+  let model = null
+  let maxSeq = -1
+
+  for (const line of text.split('\n')) {
+    if (!line) continue
+    let ev
+    try {
+      ev = JSON.parse(line)
+    } catch {
+      continue // a torn tail line is expected on a log being appended
+    }
+    const seq = typeof ev?.seq === 'number' ? ev.seq : -1
+    if (seq > maxSeq) maxSeq = seq
+    const data = ev?.data ?? {}
+    if (ev?.type === 'request/header') {
+      const config = data.header?.config ?? {}
+      provider = config.provider ?? data.provider ?? null
+      model = config.model ?? data.model ?? null
+    } else if (ev?.type === 'request/context') {
+      provider = data.provider ?? provider
+      model = data.model ?? model
+    } else if (ev?.type === 'assistant/message') {
+      const usage = data.usage
+      if (!usage || typeof usage !== 'object') continue
+      const pm = provider ?? UNKNOWN
+      const mm = model ?? UNKNOWN
+      const date = dayKey(ev.time ?? Date.now())
+      let dayObj = sessionDays.get(date)
+      if (!dayObj) {
+        dayObj = new Map()
+        sessionDays.set(date, dayObj)
+      }
+      const key = `${pm}|${mm}`
+      const bucket = dayObj.get(key) ?? emptyBucket(pm, mm)
+      const record = {
+        input: Number(usage.inputTokens) || 0,
+        cacheRead: Number(usage.cacheReadTokens) || 0,
+        cacheWrite: Number(usage.cacheWriteTokens) || 0,
+        output: Number(usage.outputTokens) || 0,
+      }
+      const hour = localHour(ev.time ?? Date.now())
+      bucket.input += record.input
+      bucket.cacheRead += record.cacheRead
+      bucket.cacheWrite += record.cacheWrite
+      bucket.output += record.output
+      bucket.requests += 1
+      if (Array.isArray(bucket.usageRecords)) bucket.usageRecords.push({ ...record, hour })
+      const hourBucket = bucket.hourly[hour]
+      hourBucket.input += record.input
+      hourBucket.cacheRead += record.cacheRead
+      hourBucket.cacheWrite += record.cacheWrite
+      hourBucket.output += record.output
+      hourBucket.requests += 1
+      dayObj.set(key, bucket)
+    }
+  }
+
+  return {
+    sessionId,
+    path: file,
+    fileSize: stat.size,
+    fileMtimeMs: stat.mtimeMs || 0,
+    seq: maxSeq,
+    provider,
+    model,
+    days: sessionDays,
+  }
+}
+
+function serializeSession(record) {
+  const days = {}
+  for (const [date, dayObj] of record.days ?? []) {
+    days[date] = {}
+    for (const [key, bucket] of dayObj) days[date][key] = bucket
+  }
+  return {
+    path: record.path,
+    fileSize: record.fileSize,
+    fileMtimeMs: record.fileMtimeMs,
+    seq: record.seq,
+    provider: record.provider,
+    model: record.model,
+    days,
+  }
+}
+
+function deserializeSession(sessionId, record) {
+  if (!record || typeof record !== 'object' || !record.days || typeof record.days !== 'object') return null
+  const days = new Map()
+  for (const [date, sourceDay] of Object.entries(record.days)) {
+    if (!sourceDay || typeof sourceDay !== 'object') continue
+    const dayObj = new Map()
+    for (const [key, source] of Object.entries(sourceDay)) {
+      if (!source || typeof source !== 'object') continue
+      const bucket = emptyBucket(String(source.provider ?? UNKNOWN), String(source.model ?? UNKNOWN))
+      addBucket(bucket, source)
+      dayObj.set(key, bucket)
+    }
+    days.set(date, dayObj)
+  }
+  return {
+    sessionId,
+    path: String(record.path ?? ''),
+    fileSize: Number(record.fileSize) || 0,
+    fileMtimeMs: Number(record.fileMtimeMs) || 0,
+    seq: Number(record.seq) || -1,
+    provider: record.provider ?? null,
+    model: record.model ?? null,
+    days,
+  }
+}
+
+/**
+ * An incremental view over every session log.
+ *
+ * `refresh()` re-reads only logs whose size, mtime or path changed, so a steady
+ * state costs one `stat` per session. The merged `days` map is rebuilt from the
+ * per-session records on every refresh; that is deliberate, because rebuilding is
+ * what makes a deleted log keep its cached contribution instead of erasing
+ * history that the log no longer exists to prove.
+ */
+export function createAggregator({ sessionsRoot, cachePath, log = () => {} }) {
+  const records = new Map()
+  const cursors = new Map()
+  let days = new Map()
+  let saveTimer = null
+  let lastRefresh = null
+
+  function mergeDays() {
+    const merged = new Map()
+    for (const record of records.values()) {
+      for (const [date, sourceDay] of record.days ?? []) {
+        let dayObj = merged.get(date)
+        if (!dayObj) {
+          dayObj = new Map()
+          merged.set(date, dayObj)
+        }
+        for (const [key, source] of sourceDay) {
+          const target = dayObj.get(key) ?? emptyBucket(source.provider, source.model)
+          addBucket(target, source)
+          dayObj.set(key, target)
+        }
+      }
+    }
+    days = merged
+  }
+
+  function loadCache() {
+    let raw
+    try {
+      raw = JSON.parse(readFileSync(cachePath, 'utf8'))
+    } catch {
+      return false
+    }
+    if (!raw || raw.version !== CACHE_VERSION || !raw.sessions || typeof raw.sessions !== 'object') return false
+    for (const [sessionId, source] of Object.entries(raw.sessions)) {
+      const record = deserializeSession(sessionId, source)
+      if (!record) continue
+      records.set(sessionId, record)
+      cursors.set(sessionId, {
+        seq: record.seq,
+        provider: record.provider,
+        model: record.model,
+        fileSize: record.fileSize,
+        fileMtimeMs: record.fileMtimeMs,
+        path: record.path,
+      })
+    }
+    mergeDays()
+    log(`cache loaded: ${records.size} session(s)`)
+    return true
+  }
+
+  function saveCache() {
+    const sessions = {}
+    for (const [sessionId, record] of records) sessions[sessionId] = serializeSession(record)
+    // The temporary name carries pid, time and entropy so a restarted host can
+    // never collide with a stale temp file another process still holds open.
+    const temp = `${cachePath}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`
+    try {
+      mkdirSync(join(cachePath, '..'), { recursive: true })
+      writeFileSync(temp, JSON.stringify({ version: CACHE_VERSION, sessions }))
+      try {
+        renameSync(temp, cachePath)
+      } catch {
+        // Windows cannot rename over an existing file; the complete temp file is
+        // already on disk, so removing the old one first is safe here.
+        try {
+          unlinkSync(cachePath)
+        } catch {
+          // absent is fine
+        }
+        renameSync(temp, cachePath)
+      }
+    } catch (error) {
+      try {
+        unlinkSync(temp)
+      } catch {
+        // best-effort cleanup only
+      }
+      log(`cache save failed: ${error?.message ?? error}`)
+    }
+  }
+
+  function scheduleCacheSave() {
+    if (saveTimer) return
+    saveTimer = setTimeout(() => {
+      saveTimer = null
+      saveCache()
+    }, 2000)
+    saveTimer.unref?.()
+  }
+
+  /**
+   * Fold every changed log.
+   *
+   * @returns {Promise<{files:number, folded:number, ms:number}>} what this pass did.
+   */
+  async function refresh() {
+    const started = Date.now()
+    const files = listLogFiles(sessionsRoot)
+    const seen = new Set()
+    let folded = 0
+    let sinceYield = 0
+    for (const file of files) {
+      const sessionId = sessionIdFromLogPath(file)
+      seen.add(sessionId)
+      const cursor = cursors.get(sessionId)
+      let stat
+      try {
+        stat = statSync(file)
+      } catch {
+        continue
+      }
+      if (cursor && cursor.fileSize === stat.size && cursor.fileMtimeMs === (stat.mtimeMs || 0) && cursor.path === file) {
+        continue
+      }
+      const record = foldSession(file, records.get(sessionId))
+      if (record) {
+        records.set(sessionId, record)
+        cursors.set(sessionId, {
+          seq: record.seq,
+          provider: record.provider,
+          model: record.model,
+          fileSize: record.fileSize,
+          fileMtimeMs: record.fileMtimeMs,
+          path: record.path,
+        })
+        folded++
+      }
+      if (++sinceYield >= YIELD_EVERY) {
+        sinceYield = 0
+        await new Promise((r) => setImmediate(r))
+      }
+    }
+    // A session whose log disappeared keeps its record (and therefore its
+    // history) but stops being refreshed.
+    if (folded > 0) {
+      mergeDays()
+      scheduleCacheSave()
+    }
+    lastRefresh = { files: files.length, folded, ms: Date.now() - started, at: Date.now() }
+    return lastRefresh
+  }
+
+  return {
+    loadCache,
+    refresh,
+    saveCache,
+    get days() {
+      return days
+    },
+    get sessionCount() {
+      return records.size
+    },
+    get lastRefresh() {
+      return lastRefresh
+    },
+  }
+}

package/lib/holidays-cn.json

@@ -0,0 +1,41 @@
+{
+  "schemaVersion": 1,
+  "note": "中国法定节假日与调休上班日。数据来自国务院办公厅的年度放假安排通知；DeepSeek 的高峰时段定义依赖该日历：「北京时间周一至周五（不含中国法定节假日）9:00-12:00、14:00-18:00 为高峰时段；其余时段，包括周末及中国法定节假日全天均为空闲时段」。注意：政策把「周末」整体划为空闲时段，所以 blocks 里的放假日才影响计价，workdays 里的调休上班日只是存档（调休后的周日仍是周末，仍按空闲价）。新增年份时按同样格式补充 years.<year> 即可，blocks 用日期区间表示，加载时展开。",
+  "source": {
+    "2025": {
+      "document": "国办发明电〔2024〕7号",
+      "published": "2024-11-12",
+      "url": "https://www.gov.cn/gongbao/2024/issue_11726/202411/content_6989767.html"
+    },
+    "2026": {
+      "document": "国办发明电〔2025〕7号",
+      "published": "2025-11-04",
+      "url": "https://www.gov.cn/zhengce/zhengceku/202511/content_7047091.htm"
+    }
+  },
+  "years": {
+    "2025": {
+      "blocks": [
+        { "name": "元旦", "from": "2025-01-01", "to": "2025-01-01" },
+        { "name": "春节", "from": "2025-01-28", "to": "2025-02-04" },
+        { "name": "清明节", "from": "2025-04-04", "to": "2025-04-06" },
+        { "name": "劳动节", "from": "2025-05-01", "to": "2025-05-05" },
+        { "name": "端午节", "from": "2025-05-31", "to": "2025-06-02" },
+        { "name": "国庆节、中秋节", "from": "2025-10-01", "to": "2025-10-08" }
+      ],
+      "workdays": ["2025-01-26", "2025-02-08", "2025-04-27", "2025-09-28", "2025-10-11"]
+    },
+    "2026": {
+      "blocks": [
+        { "name": "元旦", "from": "2026-01-01", "to": "2026-01-03" },
+        { "name": "春节", "from": "2026-02-15", "to": "2026-02-23" },
+        { "name": "清明节", "from": "2026-04-04", "to": "2026-04-06" },
+        { "name": "劳动节", "from": "2026-05-01", "to": "2026-05-05" },
+        { "name": "端午节", "from": "2026-06-19", "to": "2026-06-21" },
+        { "name": "中秋节", "from": "2026-09-25", "to": "2026-09-27" },
+        { "name": "国庆节", "from": "2026-10-01", "to": "2026-10-07" }
+      ],
+      "workdays": ["2026-01-04", "2026-02-14", "2026-02-28", "2026-05-09", "2026-09-20", "2026-10-10"]
+    }
+  }
+}

package/lib/holidays.js

@@ -0,0 +1,141 @@
+/**
+ * dsh-usage-badge — the legal-holiday calendar behind the peak/valley rule.
+ *
+ * DeepSeek's published policy is explicit about holidays:
+ *
+ * > 空闲时段价格为高峰时段价格的一半。北京时间周一至周五（**不含中国法定节假日**）
+ * > 9:00 - 12:00、14:00 - 18:00 为高峰时段；其余时段，包括周末及**中国法定节假日全天均为空闲时段**。
+ *
+ * So a weekday holiday must be billed entirely off-peak, and a 调休 weekend that
+ * the State Council turns into a working day must be billed as a working day
+ * again. Both directions need the real calendar, which is why this module ships
+ * one rather than inferring from the weekday alone.
+ *
+ * The bundled table is per-year data transcribed from the State Council notices
+ * (see `holidays-cn.json`, which records document numbers and URLs). A year the
+ * table does not cover is reported rather than guessed, and `config.holidays`
+ * can always add or override dates by hand.
+ *
+ * @module dsh-usage-badge/holidays
+ */
+
+import { readFileSync } from 'node:fs'
+
+import { dayKey } from './pricing.js'
+
+const TABLE_URL = new URL('./holidays-cn.json', import.meta.url)
+
+let bundledCache = null
+
+/** Expand an inclusive `YYYY-MM-DD` range into its dates, walking in UTC to dodge DST. */
+function expandRange(from, to) {
+  const out = []
+  const start = Date.parse(`${from}T00:00:00Z`)
+  const end = Date.parse(`${to}T00:00:00Z`)
+  if (!Number.isFinite(start) || !Number.isFinite(end) || end < start) return out
+  for (let ms = start; ms <= end; ms += 86400000) out.push(new Date(ms).toISOString().slice(0, 10))
+  return out
+}
+
+/**
+ * Load and expand the bundled calendar.
+ *
+ * @returns {{holidays: Map<string,string>, workdays: Set<string>, years: Set<string>, source: object}|null}
+ *   `holidays` maps a date to its festival name; `null` when the bundled file
+ *   cannot be read, which is treated as "no bundled calendar" rather than a crash.
+ */
+export function loadBundledTable() {
+  if (bundledCache !== null) return bundledCache
+  try {
+    const raw = JSON.parse(readFileSync(TABLE_URL, 'utf8'))
+    const holidays = new Map()
+    const workdays = new Set()
+    const years = new Set()
+    for (const [year, data] of Object.entries(raw.years ?? {})) {
+      years.add(year)
+      for (const block of data.blocks ?? []) {
+        for (const date of expandRange(block.from, block.to)) holidays.set(date, block.name ?? '')
+      }
+      for (const date of data.workdays ?? []) workdays.add(date)
+    }
+    bundledCache = { holidays, workdays, years, source: raw.source ?? {}, note: raw.note ?? '' }
+  } catch {
+    bundledCache = { holidays: new Map(), workdays: new Set(), years: new Set(), source: {}, note: '' }
+  }
+  return bundledCache
+}
+
+/**
+ * Resolve the day-classification rules a pricing document asks for.
+ *
+ * The document opts in through a top-level `holidays` object, kept separate from
+ * `timeOfUse` because it answers a different question: `timeOfUse` says *when*
+ * peak windows are, `holidays` says *which days* they can apply to at all. It also
+ * means one holiday calendar governs every per-model `timeOfUse` row.
+ *
+ * | `holidays.source` | meaning |
+ * |---|---|
+ * | absent / `"none"` | no holiday handling — the historical behavior |
+ * | `"cn"` | the bundled China calendar, plus any `extra` dates |
+ * | `"custom"` | only `extra` dates, no bundled calendar |
+ *
+ * Only *holidays* affect pricing. The bundled table also records the 调休 working
+ * days, and they are deliberately not resolved into a rule here: the published
+ * policy makes every weekend off-peak in full, and a 调休 day is still a 周末, so
+ * treating one as a working day would charge peak rates on a day the page calls
+ * off-peak. The dates stay in the data file as provenance.
+ *
+ * @param {object|undefined} config - the pricing document's `holidays` field.
+ * @returns {{enabled:boolean, holidays:Map<string,string>, source:object, years:Set<string>, missingYears:string[]}}
+ */
+export function resolveHolidayRules(config) {
+  const source = config?.source === 'cn' || config?.source === 'custom' ? config.source : 'none'
+  const bundled = source === 'cn' ? loadBundledTable() : { holidays: new Map(), workdays: new Set(), years: new Set(), source: {} }
+  const enabled = source !== 'none'
+
+  const holidays = new Map(enabled && source === 'cn' ? bundled.holidays : [])
+  for (const date of config?.extra ?? []) if (typeof date === 'string' && date) holidays.set(date.trim(), '自定义')
+
+  // A year with no bundled block is worth surfacing: its holidays would otherwise
+  // silently be treated as ordinary weekdays.
+  const missingYears = []
+  if (enabled && source === 'cn') {
+    const thisYear = new Date().getFullYear()
+    for (const year of [thisYear, thisYear + 1]) {
+      if (!bundled.years.has(String(year))) missingYears.push(String(year))
+    }
+  }
+
+  return { enabled, holidays, source: bundled.source, years: bundled.years, missingYears, source_kind: source }
+}
+
+/**
+ * Classify one date under the resolved rules.
+ *
+ * @param {string} date - local `YYYY-MM-DD` day key.
+ * @param {object} rules - result of {@link resolveHolidayRules}.
+ * @returns {{class:'holiday'|'normal', name:string|null}}
+ */
+export function classifyDate(date, rules) {
+  if (!rules?.enabled) return { class: 'normal', name: null }
+  const name = rules.holidays?.get?.(date)
+  if (name !== undefined) return { class: 'holiday', name: name || null }
+  return { class: 'normal', name: null }
+}
+
+/**
+ * The holiday-related facts the browser half displays: whether the calendar is on,
+ * which years it covers, and how the current day is classified.
+ */
+export function describeCalendar(rules, now = Date.now()) {
+  const date = dayKey(now)
+  const today = classifyDate(date, rules)
+  return {
+    enabled: Boolean(rules?.enabled),
+    source: rules?.source_kind ?? 'none',
+    years: [...(rules?.years ?? [])].sort(),
+    missingYears: rules?.missingYears ?? [],
+    today: { date, class: today.class, name: today.name },
+    counts: { holidays: rules?.holidays?.size ?? 0 },
+  }
+}