@linxin666/dsh-usage 0.4.3 → 0.4.5

package/src/client/usage.module.css

@@ -102,6 +102,50 @@
   opacity: 0.6;
 }
 
+/* Day picker: a label plus the native select, sized to the card and
+   inheriting the section's currentColor chrome. */
+.dayPicker {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.dayPickerLabel {
+  font-size: 11px;
+  opacity: 0.6;
+}
+
+.daySelect {
+  border: 1px solid color-mix(in srgb, currentColor 25%, transparent);
+  border-radius: 6px;
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  font-size: 12px;
+  padding: 3px 8px;
+  font-variant-numeric: tabular-nums;
+}
+
+.daySelect:focus-visible {
+  outline: none;
+  box-shadow: 0 0 0 2px color-mix(in srgb, currentColor 45%, transparent);
+}
+
+/* A native select paints its option list itself: it does NOT inherit the
+   control's background, so an unset option background falls back to the
+   browser's own (light) list surface while the option text still inherits the
+   section's light text color — light text on a light list, unreadable on a
+   dark skin. Both the day picker and the settings-row select therefore give
+   their option list one explicit surface/label pair, read from the tokens the
+   platform and the skins ship (a skin that omits the surface token falls back
+   to the platform's, a host with no theme layer to Canvas). Text and
+   background always travel together, per theme half. */
+.daySelect option,
+.settingItem select option {
+  background-color: var(--dsw-alias-bg-multi-select, Canvas);
+  color: var(--dsw-alias-label-primary, CanvasText);
+}
+
 .statRow {
   display: flex;
   flex-wrap: wrap;
@@ -129,6 +173,9 @@
   display: flex;
   align-items: center;
   justify-content: space-between;
+  /* A long per-day figure (tokens · calls · cost) drops to its own line in a
+     narrow panel instead of running into the provider name. */
+  flex-wrap: wrap;
   gap: 12px;
   padding: 6px 0;
   border-top: 1px solid color-mix(in srgb, currentColor 8%, transparent);

package/src/core/adapters.ts

@@ -48,6 +48,24 @@ export interface PlanParse {
 export interface ProviderAdapter {
   /** Provider route keys this adapter serves. */
   ids: readonly string[]
+  /**
+   * Route keys that belong to this family for accounting (token folding, the
+   * spend price book, the whale-yuan bank) but must never be probed with this
+   * adapter's endpoints.
+   *
+   * A route reaches the DeepSeek family without an API key when the user is
+   * signed in to a DeepSeek account: the llm-deepseek-account plugin registers
+   * the route id deepseek-account, which authenticates with the account token
+   * rather than a key. Its tokens bill the same account the official route
+   * bills, so the family must own it, but the balance endpoint reads an
+   * API-key account: probing it would either fail on the account token or,
+   * when the user also configured DEEPSEEK_API_KEY, print the API-key account's
+   * money under the account route's name (issue #1772, the same
+   * mis-attribution class as #1688). adapterFor() deliberately does not
+   * resolve these ids, so no probe, credential fallback, or alias fold can
+   * reach them; family membership is read through isDeepSeekProviderRoute().
+   */
+  familyOnlyIds?: readonly string[]
   /** Fallback display name when the LLM runtime has none. */
   displayName: string
   balance?: {
@@ -134,6 +152,10 @@ export const DEEPSEEK_API_ORIGIN = 'https://api.deepseek.com'
 
 const DEEPSEEK: ProviderAdapter = {
   ids: ['deepseek', 'deepseek-official'],
+  // The signed-in DeepSeek account route bills the same account but holds no
+  // API key, so it joins the family for accounting and stays out of the probe
+  // directory (issue #1772).
+  familyOnlyIds: ['deepseek-account'],
   displayName: 'DeepSeek',
   balance: {
     origin: DEEPSEEK_API_ORIGIN,
@@ -518,11 +540,20 @@ export function balanceAppliesToRoute(adapter: ProviderAdapter, baseURL: string
 /**
  * Whether a provider route belongs to the official DeepSeek family: the only
  * family with a spend price book and a settings-section-owned env credential
- * (llm-deepseek) rather than a pi-ai profile. Drives the env fallback in
- * credential resolution and the fold-time cost stamping.
+ * (llm-deepseek) rather than a pi-ai profile. Drives the fold-time cost
+ * stamping, the client fold-time spend estimate, and the whale-yuan bank.
+ *
+ * Family membership is wider than the probe directory. The account route
+ * (deepseek-account) bills the same account but authenticates with the account
+ * token, so it prices and mints while `adapterFor()` still returns undefined
+ * for it and no probe or env-credential fallback can reach it. Every caller of
+ * this predicate is an accounting decision; the credential and probing
+ * decisions read `adapterFor()` instead, so the two never widen together
+ * (issue #1772).
  */
 export function isDeepSeekProviderRoute(provider: string): boolean {
-  return adapterFor(provider) === DEEPSEEK
+  if (adapterFor(provider) === DEEPSEEK) return true
+  return DEEPSEEK.familyOnlyIds?.includes(provider) === true
 }
 
 /**

package/src/core/holidays.ts

@@ -0,0 +1,248 @@
+/**
+ * Chinese public-holiday dates, Beijing calendar days, as `YYYY-MM-DD`.
+ *
+ * The DeepSeek peak rule bills a public holiday off-peak in full, and the
+ * State Council publishes these dates per year, so they cannot be derived
+ * from a rule. This module is that data; `pricing.ts` keeps the arithmetic.
+ *
+ * Adjusted workdays are deliberately absent: the provider counts the
+ * calendar day, so an adjusted Saturday or Sunday is off-peak exactly like
+ * any other weekend and listing it would price it as peak.
+ *
+ * Source: the yearly schedules in bastengao/chinese-holidays-node
+ * (`data/<year>.json`, MIT). Only the `holiday` entries are taken; that
+ * package's runtime code (which fetches over the network) and its
+ * dependencies are not vendored.
+ *
+ * Coverage ends at the newest year below. A year with no entry is priced as
+ * if it had no holidays, which is the documented default of
+ * {@link PublicHolidayCalendar} in `pricing.ts`.
+ * @module @linxin666/dsh-usage/core/holidays
+ */
+
+/** Public-holiday dates keyed by Beijing calendar year. */
+export const CHINESE_PUBLIC_HOLIDAYS: Readonly<Record<string, readonly string[]>> = {
+  "2020": [
+    "2020-01-24",
+    "2020-01-25",
+    "2020-01-26",
+    "2020-01-27",
+    "2020-01-28",
+    "2020-01-29",
+    "2020-01-30",
+    "2020-04-04",
+    "2020-04-05",
+    "2020-04-06",
+    "2020-05-01",
+    "2020-05-02",
+    "2020-05-03",
+    "2020-05-04",
+    "2020-05-05",
+    "2020-06-25",
+    "2020-06-26",
+    "2020-06-27",
+    "2020-10-01",
+    "2020-10-02",
+    "2020-10-03",
+    "2020-10-04",
+    "2020-10-05",
+    "2020-10-06",
+    "2020-10-07",
+    "2020-10-08"
+  ],
+  "2021": [
+    "2021-01-01",
+    "2021-01-02",
+    "2021-01-03",
+    "2021-02-11",
+    "2021-02-12",
+    "2021-02-13",
+    "2021-02-14",
+    "2021-02-15",
+    "2021-02-16",
+    "2021-02-17",
+    "2021-04-03",
+    "2021-04-04",
+    "2021-04-05",
+    "2021-05-01",
+    "2021-05-02",
+    "2021-05-03",
+    "2021-05-04",
+    "2021-05-05",
+    "2021-06-12",
+    "2021-06-13",
+    "2021-06-14",
+    "2021-09-19",
+    "2021-09-20",
+    "2021-09-21",
+    "2021-10-01",
+    "2021-10-02",
+    "2021-10-03",
+    "2021-10-04",
+    "2021-10-05",
+    "2021-10-06",
+    "2021-10-07"
+  ],
+  "2022": [
+    "2022-01-01",
+    "2022-01-02",
+    "2022-01-03",
+    "2022-01-31",
+    "2022-02-01",
+    "2022-02-02",
+    "2022-02-03",
+    "2022-02-04",
+    "2022-02-05",
+    "2022-02-06",
+    "2022-04-03",
+    "2022-04-04",
+    "2022-04-05",
+    "2022-04-30",
+    "2022-05-01",
+    "2022-05-02",
+    "2022-05-03",
+    "2022-05-04",
+    "2022-06-03",
+    "2022-06-04",
+    "2022-06-05",
+    "2022-09-10",
+    "2022-09-11",
+    "2022-09-12",
+    "2022-10-01",
+    "2022-10-02",
+    "2022-10-03",
+    "2022-10-04",
+    "2022-10-05",
+    "2022-10-06",
+    "2022-10-07"
+  ],
+  "2023": [
+    "2022-12-31",
+    "2023-01-01",
+    "2023-01-02",
+    "2023-01-21",
+    "2023-01-22",
+    "2023-01-23",
+    "2023-01-24",
+    "2023-01-25",
+    "2023-01-26",
+    "2023-01-27",
+    "2023-04-29",
+    "2023-04-30",
+    "2023-05-01",
+    "2023-05-02",
+    "2023-05-03",
+    "2023-06-22",
+    "2023-06-23",
+    "2023-06-24",
+    "2023-09-29",
+    "2023-09-30",
+    "2023-10-01",
+    "2023-10-02",
+    "2023-10-03",
+    "2023-10-04",
+    "2023-10-05",
+    "2023-10-06"
+  ],
+  "2024": [
+    "2023-12-30",
+    "2023-12-31",
+    "2024-01-01",
+    "2024-02-10",
+    "2024-02-11",
+    "2024-02-12",
+    "2024-02-13",
+    "2024-02-14",
+    "2024-02-15",
+    "2024-02-16",
+    "2024-02-17",
+    "2024-04-04",
+    "2024-04-05",
+    "2024-04-06",
+    "2024-05-01",
+    "2024-05-02",
+    "2024-05-03",
+    "2024-05-04",
+    "2024-05-05",
+    "2024-06-08",
+    "2024-06-09",
+    "2024-06-10",
+    "2024-09-15",
+    "2024-09-16",
+    "2024-09-17",
+    "2024-10-01",
+    "2024-10-02",
+    "2024-10-03",
+    "2024-10-04",
+    "2024-10-05",
+    "2024-10-06",
+    "2024-10-07"
+  ],
+  "2025": [
+    "2025-01-28",
+    "2025-01-29",
+    "2025-01-30",
+    "2025-01-31",
+    "2025-02-01",
+    "2025-02-02",
+    "2025-02-03",
+    "2025-02-04",
+    "2025-04-04",
+    "2025-04-05",
+    "2025-04-06",
+    "2025-05-01",
+    "2025-05-02",
+    "2025-05-03",
+    "2025-05-04",
+    "2025-05-05",
+    "2025-05-31",
+    "2025-06-01",
+    "2025-06-02",
+    "2025-10-01",
+    "2025-10-02",
+    "2025-10-03",
+    "2025-10-04",
+    "2025-10-05",
+    "2025-10-06",
+    "2025-10-07",
+    "2025-10-08"
+  ],
+  "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"
+  ]
+}
+
+/** The newest year this table covers; later years carry no entry. */
+export const HOLIDAY_TABLE_LAST_YEAR = 2026

package/src/core/ledger.ts

@@ -15,6 +15,19 @@ export function localDateKey(ms: number): string {
   return `${date.getFullYear()}-${month}-${day}`
 }
 
+/**
+ * Whether `key` is a real local-date key (`YYYY-MM-DD`). The shape check is
+ * round-tripped: an impossible date (9999-99-99) parses to NaN and a rollover
+ * (2026-02-30) lands on another day, so both would otherwise fold into a bogus,
+ * never-pruned bucket. Shared by the persisted-document reader and the day
+ * route's query gate.
+ */
+export function isLedgerDateKey(key: string): boolean {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(key)) return false
+  const atMs = new Date(key + 'T12:00:00').getTime()
+  return Number.isFinite(atMs) && localDateKey(atMs) === key
+}
+
 /** An empty ledger document. */
 export function createLedgerDocument(): UsageLedgerDocument {
   return { version: 1, days: {} }
@@ -152,12 +165,8 @@ export function deserializeLedger(value: unknown): UsageLedgerDocument {
   const days = (value as Record<string, unknown>).days
   if (typeof days !== 'object' || days === null) return doc
   for (const [dateKey, providers] of Object.entries(days as Record<string, unknown>)) {
-    if (!/^\d{4}-\d{2}-\d{2}$/.test(dateKey) || typeof providers !== 'object' || providers === null) continue
-    // Round-trip the date key: an impossible date (9999-99-99) parses to NaN
-    // and a rollover (2026-02-30) lands on another day; both would otherwise
-    // fold into a bogus, never-pruned bucket.
+    if (!isLedgerDateKey(dateKey) || typeof providers !== 'object' || providers === null) continue
     const atMs = new Date(dateKey + 'T12:00:00').getTime()
-    if (!Number.isFinite(atMs) || localDateKey(atMs) !== dateKey) continue
     for (const [provider, models] of Object.entries(providers as Record<string, unknown>)) {
       if (typeof models !== 'object' || models === null) continue
       for (const [model, totals] of Object.entries(models as Record<string, unknown>)) {

package/src/core/pricing.ts

@@ -4,10 +4,19 @@
  * at fold time (the provider bills each request in the period the request ran
  * in, so pricing at the fold is the honest estimate).
  *
- * Policy (api-docs.deepseek.com pricing page, effective 2026-09-10 12:00
- * Beijing): peak hours are Beijing time Monday-Friday 09:00-12:00 and
- * 14:00-18:00; every other hour (nights, weekends) is off-peak and billed at
- * half the peak price. All prices here are CNY per million tokens.
+ * Policy (api-docs.deepseek.com pricing page): peak hours are Beijing time
+ * Monday-Friday 09:00-12:00 and 14:00-18:00, excluding Chinese public
+ * holidays; every other hour is off-peak and billed at half the peak price.
+ * The published rule counts a calendar day, not the working schedule: a
+ * Saturday or Sunday is off-peak in full even on an adjusted workday, and a
+ * public holiday is off-peak in full even on a Monday-Friday. All prices
+ * here are CNY per million tokens.
+ *
+ * Public-holiday dates are not derivable from the rule, so the rule takes them as
+ * a `PublicHolidayCalendar`. The default is the published table in `./holidays.ts`,
+ * covering 2020 through ${HOLIDAY_TABLE_LAST_YEAR}; a caller with newer dates
+ * passes its own. A holiday weekday therefore prices off-peak, which is the half
+ * of the published rule that is easy to get wrong.
  *
  * The published rows are `deepseek-flash` (DeepSeek-V4.1-Flash) and
  * `deepseek-v4-pro` (DeepSeek-V4-Pro-0813). The retired flash ids
@@ -18,6 +27,7 @@
  */
 
 import type { UsageTokenTotals } from './types.ts'
+import { CHINESE_PUBLIC_HOLIDAYS, HOLIDAY_TABLE_LAST_YEAR } from './holidays.ts'
 
 /** One peak window in minutes-of-day, Beijing time. */
 interface PeakWindow {
@@ -71,32 +81,82 @@ function withinWindow(minuteOfDay: number): PeakWindow | undefined {
   return PEAK_WINDOWS.find((window) => minuteOfDay >= window.from && minuteOfDay < window.to)
 }
 
+/**
+ * Supplies the Chinese public-holiday dates the peak rule excludes. The dates
+ * are not derivable from any rule (the State Council publishes them per year),
+ * so this repository ships no table of its own: the default calendar is empty,
+ * and a caller that has real dates passes them in. A date is compared as a
+ * Beijing-time `YYYY-MM-DD` string, which is the granularity the published
+ * rule needs (a holiday is off-peak for the whole day, so times never matter).
+ */
+export interface PublicHolidayCalendar {
+  /** True when the Beijing-time calendar day `date` is a Chinese public holiday. */
+  isPublicHoliday(date: string): boolean
+}
+
+/**
+ * The default calendar: the published Chinese public-holiday table, so a holiday
+ * weekday prices off-peak instead of over-reporting at the peak rate. A year the
+ * table does not cover holds no dates and falls back to peak on weekdays, which
+ * is the safe direction to be wrong in: the estimate reads high rather than low.
+ */
+export const CN_PUBLIC_HOLIDAYS: PublicHolidayCalendar = {
+  isPublicHoliday: (date) => {
+    const year = date.slice(0, 4)
+    if (Number(year) > HOLIDAY_TABLE_LAST_YEAR) return false
+    return CHINESE_PUBLIC_HOLIDAYS[year]?.includes(date) ?? false
+  },
+}
+
+/** The Beijing-time `YYYY-MM-DD` calendar day of `ms` (UTC+8 has no DST, so the shift is exact). */
+function beijingDate(ms: number): string {
+  const shifted = new Date(ms + BEIJING_UTC_OFFSET_MS)
+  const month = `${shifted.getUTCMonth() + 1}`.padStart(2, '0')
+  const day = `${shifted.getUTCDate()}`.padStart(2, '0')
+  return `${shifted.getUTCFullYear()}-${month}-${day}`
+}
+
+/**
+ * Whether `ms` falls on a peak-eligible Beijing day: Monday-Friday that is
+ * not a public holiday. A Saturday or Sunday is never eligible, including on
+ * an adjusted workday — the provider counts the calendar day, not the
+ * working schedule.
+ */
+function isPeakDay(ms: number, calendar: PublicHolidayCalendar): boolean {
+  const shifted = new Date(ms + BEIJING_UTC_OFFSET_MS)
+  const weekday = shifted.getUTCDay()
+  if (weekday < 1 || weekday > 5) return false
+  return !calendar.isPublicHoliday(beijingDate(ms))
+}
+
 /**
  * The DeepSeek billing period at `ms`, plus when it next flips. The clock is
  * Beijing time regardless of the host timezone (UTC+8 has no DST, so a fixed
  * shift is exact). `boundaryMs` is the instant the current period ends — the
  * window's close while peaking, the next window's open otherwise.
  */
-export function deepseekPeriodAt(ms: number): { peak: boolean; boundaryMs: number } {
+export function deepseekPeriodAt(ms: number, calendar: PublicHolidayCalendar = CN_PUBLIC_HOLIDAYS): { peak: boolean; boundaryMs: number } {
   const shifted = new Date(ms + BEIJING_UTC_OFFSET_MS)
-  const weekday = shifted.getUTCDay()
   const minuteOfDay = shifted.getUTCHours() * 60 + shifted.getUTCMinutes()
-  const current = weekday >= 1 && weekday <= 5 ? withinWindow(minuteOfDay) : undefined
+  const current = isPeakDay(ms, calendar) ? withinWindow(minuteOfDay) : undefined
   if (current !== undefined) {
     return { peak: true, boundaryMs: ms + (current.to - minuteOfDay) * 60_000 - shifted.getUTCSeconds() * 1000 - shifted.getUTCMilliseconds() }
   }
-  // Next window start: later today (weekday only), else the following days'
-  // first morning window; the scan bound makes a malformed clock terminate.
+  // Next window start: later today (on a peak-eligible day), else the first
+  // peak-eligible day's morning window; the scan bound makes a malformed clock
+  // terminate.
   for (let dayOffset = 0; dayOffset < 8; dayOffset += 1) {
-    const day = new Date(ms + BEIJING_UTC_OFFSET_MS + dayOffset * 86_400_000)
-    if (day.getUTCDay() < 1 || day.getUTCDay() > 5) continue
+    const dayStartMs = ms + dayOffset * 86_400_000
+    if (!isPeakDay(dayStartMs, calendar)) continue
+    const day = new Date(dayStartMs + BEIJING_UTC_OFFSET_MS)
     const realDayStart = Date.UTC(day.getUTCFullYear(), day.getUTCMonth(), day.getUTCDate()) - BEIJING_UTC_OFFSET_MS
     for (const window of PEAK_WINDOWS) {
       if (dayOffset === 0 && window.from <= minuteOfDay) continue
       return { peak: false, boundaryMs: realDayStart + window.from * 60_000 }
     }
   }
-  // Unreachable (the scan covers a full week); a conservative off-peak answer.
+  // Unreachable (the scan covers a full week of peak-eligible days); a
+  // conservative off-peak answer.
   return { peak: false, boundaryMs: ms + 86_400_000 }
 }
 
@@ -112,12 +172,12 @@ function priceFor(model: string, atMs: number): ModelPrice {
  * row; ids from other providers never reach this function (the service gates
  * by route family). Rounded to micro-CNY so the ledger stays readable.
  */
-export function deepseekModelSpend(model: string, totals: Readonly<UsageTokenTotals>, atMs: number): number {
+export function deepseekModelSpend(model: string, totals: Readonly<UsageTokenTotals>, atMs: number, calendar: PublicHolidayCalendar = CN_PUBLIC_HOLIDAYS): number {
   const price = priceFor(model, atMs)
-  const period = deepseekPeriodAt(atMs)
+  const period = deepseekPeriodAt(atMs, calendar)
   const column = period.peak ? 'peak' : 'offPeak'
   const spend = (totals.cacheReadTokens * price.cacheHit[column]
     + (totals.inputTokens + totals.cacheWriteTokens) * price.inputMiss[column]
     + totals.outputTokens * price.output[column]) / 1_000_000
   return Math.round(spend * 1e6) / 1e6
-}
+}

package/src/core/types.ts

@@ -67,6 +67,26 @@ export interface UsageDaySummary {
   totals: UsageTokenTotals
 }
 
+/**
+ * One local day aggregated per provider and model. The overview serves today
+ * through this shape and the day route serves any retained day with it, so a
+ * day the user picks in the browser and the live today card are the same
+ * document.
+ */
+export interface UsageDayView {
+  /** Local-date key `YYYY-MM-DD`. */
+  date: string
+  totals: UsageTokenTotals
+  /** Per-provider rows, heaviest by total tokens first. */
+  providers: UsageProviderSummary[]
+}
+
+/** The day route's response body. */
+export interface UsageDayResponse {
+  ok: true
+  day: UsageDayView
+}
+
 /** A balance fact normalized from a provider probe. */
 export interface BalanceView {
   /** ISO 4217 code the provider bills in (`CNY`, `USD`, ...). */
@@ -161,9 +181,16 @@ export interface UsageOverviewView {
     today?: UsageTokenTotals
   }
   usage: {
-    today: { date: string; totals: UsageTokenTotals; providers: UsageProviderSummary[] }
+    today: UsageDayView
     /** Last N local days ascending, including today. */
     days: UsageDaySummary[]
+    /**
+     * Every retained local day that recorded usage, ascending — the day
+     * picker's option list, reaching past the trend cap to the whole
+     * retention window. Optional so an older host document still renders
+     * (the section then offers no picker).
+     */
+    availableDays?: string[]
     /**
      * The same window aggregated per provider and model — the trend card's
      * bar-chart data. Optional so an older host document still renders.

package/src/host/routes.ts

@@ -3,6 +3,8 @@ import type { Context } from '@deepseek-ai/cordis'
 import type { WebRoute } from '@deepseek-ai/dsh-host-webserver'
 import { isUsageAllowed } from './access.ts'
 import { writeJson } from './http.ts'
+import { isLedgerDateKey } from '../core/ledger.ts'
+import type { UsageDayResponse } from '../core/types.ts'
 import type { UsageService } from './usage-service.ts'
 
 export const USAGE_API_PREFIX = '/api/dsh-usage'
@@ -31,6 +33,35 @@ export function makeUsageOverviewRoute(ctx: Context, service: UsageService): Web
   }
 }
 
+/**
+ * One retained day route: `GET /api/dsh-usage/day?date=YYYY-MM-DD` answers
+ * that local day's per-provider and per-model totals, so the section's day
+ * pickers can show a past day instead of only today. Same trust fence as the
+ * overview route, and a key that is not a real local date is refused with 400
+ * rather than folded into a bogus day.
+ * @param ctx - host context; may expose remoteWebUiPairing.
+ * @param service - the usage service.
+ * @returns the route.
+ */
+export function makeUsageDayRoute(ctx: Context, service: UsageService): WebRoute {
+  return {
+    kind: 'exact',
+    path: USAGE_API_PREFIX + '/day',
+    handler: (req: IncomingMessage, res: ServerResponse): void => {
+      if (!isUsageAllowed(ctx, req)) {
+        writeJson(res, 403, { ok: false, error: 'forbidden: loopback-only' })
+        return
+      }
+      const date = new URL(req.url ?? '/', 'http://127.0.0.1').searchParams.get('date') ?? ''
+      if (!isLedgerDateKey(date)) {
+        writeJson(res, 400, { ok: false, error: 'date must be YYYY-MM-DD' })
+        return
+      }
+      writeJson(res, 200, { ok: true, day: service.day(date) } satisfies UsageDayResponse, { 'cache-control': 'no-store' })
+    },
+  }
+}
+
 /**
  * Manual refresh: forces one probe cycle now and answers with the fresh
  * overview. Same trust fence as the overview route.