@rayadesu/dsh-llm-billing 0.3.9 → 0.3.11

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # last confirmed-consistent state. Both languages carry equal authority; after
 # editing either side, bring the other along and re-record both hashes with:
 #   git hash-object README.md README.zh.md
-README.md: 453fdb62c6081c6f5704bf878888c326b523d5e1
-README.zh.md: c147bff571b7e00abebb1fad188a11058354bbc5
+README.md: 2c416fb7f45464abd06484bffb3db61ccea3a47b
+README.zh.md: 2cec64178289c1fb2e6081e3fd7af59dfb0e0613

package/README.md

@@ -16,7 +16,7 @@ Add the plugin to a composition (a `cordis.yml` row) and give it a credential. I
     # baseURL: https://api.deepseek.com
 ```
 
-The plugin registers the `billing` Remote with six methods: `getBalance(force?)` (the parsed `/user/balance` snapshot; a snapshot younger than the 15-second host TTL is reused, `force` bypasses it, and each request aborts after 5 seconds), `getSessionSpend(sessionId)` (one session's billed cost), `getTodaySpend(force?)` (every session's billed cost on the current Beijing-time calendar day; `force` bypasses the host-side cache, for the badge's manual refresh), `getTodaySessionsSpend(force?)` (today's billed cost per session, sorted by cost descending, each row carrying the session's durable title), `getTurnSpend(sessionId, messageId)` (one completed turn's billed cost, located by its closing assistant message id), and `getSessionTurnSpends(sessionId)` (every completed turn's cost as a `messageId → total` map, folded in one pass — the transcript renders one row per message, so the client fetches this once per session instead of calling `getTurnSpend` per row). The spend prices each provider-reported usage sample — an `assistant/message`'s usage, or a failed/retried `assistant/attempt`'s stream usage, priced with the model of the latest `request/header` — at the official rate of the sample's own Beijing-time peak/off-peak classification. Peak windows apply weekdays (Monday–Friday) only, and weekends are always off-peak. A sample for the same `(turn, step)` replaces the earlier one and `llm/retry-started` makes the retried attempt add, matching DSH's own turn-usage disclosure; costs then sum per model. A turn is the `turn/start`..`turn/end` range holding the closing message; the ranking folds each session's title from its latest `session/title` event (last-wins, so a rename is reflected as soon as its event commits and the session is re-read).
+The plugin registers the `billing` Remote with six methods: `getBalance(force?)` (the parsed `/user/balance` snapshot; a snapshot younger than the 15-second host TTL is reused, `force` bypasses it, and each request aborts after 5 seconds), `getSessionSpend(sessionId)` (one session's billed cost), `getTodaySpend(force?)` (every session's billed cost on the current Beijing-time calendar day; `force` bypasses the host-side cache, for the badge's manual refresh), `getTodaySessionsSpend(force?)` (today's billed cost per session, sorted by cost descending, each row carrying the session's durable title), `getTurnSpend(sessionId, messageId)` (one completed turn's billed cost, located by its closing assistant message id), and `getSessionTurnSpends(sessionId)` (every completed turn's cost as a `messageId → total` map, folded in one pass — the transcript renders one row per message, so the client fetches this once per session instead of calling `getTurnSpend` per row). The spend prices each provider-reported usage sample — an `assistant/message`'s usage, or a failed/retried `assistant/attempt`'s stream usage, priced with the model of the latest `request/header` — at the official rate revision in effect at the sample's own timestamp, classified peak/off-peak by its own Beijing-time hour. Peak windows apply weekdays (Monday–Friday) only, and weekends are always off-peak. A sample for the same `(turn, step)` replaces the earlier one and `llm/retry-started` makes the retried attempt add, matching DSH's own turn-usage disclosure; costs then sum per model. A turn is the `turn/start`..`turn/end` range holding the closing message; the ranking folds each session's title from its latest `session/title` event (last-wins, so a rename is reflected as soon as its event commits and the session is re-read).
 
 ### Today-spend read path (no full scans per message)
 
@@ -27,7 +27,7 @@ The plugin registers the `billing` Remote with six methods: `getBalance(force?)`
 
 After the first resolution per process, steady-state reads cost only the sessions whose logs actually changed. A session whose log cannot be read is skipped with a warning (and remembered) instead of failing the whole day's total.
 
-Note: the projection path prices a session's history once, at the rates in effect when its events were folded — changing `billing.models` re-prices only events folded after the change (the events path re-prices the whole log).
+Note: the projection path prices a session's history once, at the rates in effect when its events were folded. Published rate revisions travel inside the pricing closure and are resolved per sample timestamp, so a re-priced series bills its own history correctly however late a log is folded; only a configuration change (editing `billing.models`) re-prices just the events folded afterwards (the events path re-prices the whole log), and the unit's `stateVersion` is bumped whenever that resolution changes so checkpointed rows are refolded instead of kept.
 
 ## Forked sessions
 
@@ -47,11 +47,17 @@ The projection-cache reader likewise targets the current seam: `cachedSnapshot(h
 | --- | --- | --- |
 | `apiKeyEnv` | `DEEPSEEK_API_KEY` | Credential-reference (environment-variable) name resolved per call. |
 | `baseURL` | `$DEEPSEEK_BASE_URL` then `https://api.deepseek.com` | Endpoint base; `/user/balance` is appended. |
-| `models` | V4 Flash + V4.1 Flash + V4 Pro + V4 Flash Vision Exp + MiMo-V2.5 series | Advisory display rows, in presentation order. |
+| `models` | V4.1 Flash (`deepseek-flash`) + V4 Flash + V4 Pro + V4 Flash Vision Exp + MiMo-V2.5 series | Advisory display rows, in presentation order; they mirror DSH's `llm-deepseek` catalog (plus the retired `deepseek-v4.1-flash-expires-on-0910` preview id, kept for readable historical labels). |
 | `billing.peakHours` | 09:00–12:00, 14:00–18:00 (Beijing, weekdays) | Peak-hour windows, applied weekdays (Mon–Fri) only; weekends and all other hours are off-peak. |
-| `billing.models` | Published V4 + MiMo rates | Per-model peak/off-peak price rows (`cacheHitInput`, `cacheMissInput`, `output`, in CNY per 1M tokens). |
+| `billing.models` | Published V4 + MiMo rates | Per-model price rows (`cacheHitInput`, `cacheMissInput`, `output`, in CNY per 1M tokens) with an optional inclusive `effectiveFrom` (epoch ms). |
 
-Override one model without dropping the others by supplying a non-empty `billing.models` list; an empty or omitted list falls back to the published defaults.
+Override one model without dropping the others by supplying a non-empty `billing.models` list; an empty or omitted list falls back to the published defaults. Several rows may share one model: each row is a rate revision, and a usage sample is priced at the peak/off-peak pair of the revision in effect at the sample's own timestamp (a row without `effectiveFrom` is that model's base revision and also covers every earlier instant).
+
+The published table already ships DeepSeek's adjustments, so a session or a day spanning a change is priced exactly:
+
+- **2026-09-10 12:00 Beijing** (`FLASH_SERIES_RATE_CHANGE_AT`): the whole flash series — the V4.1 Flash route `deepseek-flash` (released that day and now DSH's default), V4 Flash, V4 Flash Vision Exp, and the retired preview id — drops to off-peak 0.02 / 1.0 / 4.0 with peak at twice those prices. Earlier samples, including this route's own usage from before that instant, keep the superseded rates.
+- **2026-09-14 12:00 Beijing** (`V4_PRO_ROUTE_SWITCH_AT`): the V4 Pro route is announced to be served by V4.1 Flash and billed at the V4.1 Flash rates; its row carries that second revision.
+- MiMo-V2.5 series: untouched by either adjustment (flat rate).
 
 ## Model Experience
 
@@ -64,7 +70,7 @@ None; its only provider call is a credential-authenticated `/user/balance` read,
 ## Known Limitations and Deferred Work
 
 - **Priced rows only** — the session and today spends only price models that have a `billing.models` row; a model without a rate row is omitted. An `assistant/attempt` is priced with the model of the latest `request/header`, so an attempt before any header contributes nothing.
-- **Up-to-60s staleness** — `getTodaySpend()` is served from the host-side cache for up to 60 seconds; only the manual refresh (`force`) recomputes immediately (still revision-gated, so an unchanged log costs nothing). The browser reads the live per-session value from the pushed projection instead, so the session line is never stale.
+- **Up-to-60s staleness** — `getTodaySpend()` is served from the host-side cache for up to 60 seconds; only the manual refresh (`force`) recomputes immediately (still revision-gated, so an unchanged log costs nothing). The browser reads the live per-session value from the pushed projection instead, so the session line is never stale; the parenthesized today share on that same line comes from the already-fetched today-session ranking (`getTodaySessionsSpend()`, under the same 60-second cache and revision gate), so that one number can trail by up to 60 seconds.
 - **Balance is TTL-cached** — one `/user/balance` snapshot is reused for up to 15 seconds and each request aborts after 5 seconds; `force` (the manual refresh) bypasses the TTL.
-- **Projection pricing is history-frozen** — when the projection path is active, a pricing-table change prices only events folded after the change; restart (or the events fallback) re-prices the full log.
+- **Projection pricing follows the published revisions** — the projection fold resolves the rate revision per sample timestamp, so published re-pricing needs no refold; a hand-edited `billing.models` change prices only events folded after the change until the state version or the process is reset (the events fallback re-prices the full log).
 - **A cached cold row may trail its log** — a cold session whose cached row covers the queried day is re-read from the log for exactness; a row whose own day is not the queried day is trusted without a read, so a session that crashed between its last checkpoint and its last event can under-report that tail until it is next read.

package/README.zh.md

@@ -16,7 +16,7 @@
     # baseURL: https://api.deepseek.com
 ```
 
-插件注册 `billing` Remote，含六个方法：`getBalance(force?)`（解析后的 `/user/balance` 快照；15 秒宿主 TTL 内复用，`force` 绕过，单次请求 5 秒超时）、`getSessionSpend(sessionId)`（单个会话的计费花费）、`getTodaySpend(force?)`（当前北京时间自然日内所有会话的计费花费合计；`force` 绕过宿主侧缓存，供徽标手动刷新使用）、`getTodaySessionsSpend(force?)`（今日按会话的计费花费，按花费从高到低排序，每行带会话的持久标题）、`getTurnSpend(sessionId, messageId)`（单个已完成回合的计费花费，按收尾助手消息 id 定位）与 `getSessionTurnSpends(sessionId)`（该会话所有已完成回合的 `messageId → 金额` 映射，一趟折叠——对话每个消息行都要显示金额，客户端因此每会话只拉一次，而不是逐行调用 `getTurnSpend`）。计价的样本来源有两处：`assistant/message` 自身的 usage，以及失败/重试的 `assistant/attempt` 内嵌 stream 里的 usage（后者用最近一条 `request/header` 的模型），各按样本自身发生时刻（北京时间）所在的峰/谷单价计价——高峰窗口仅周一至周五适用，周末全天按低谷价。同一 `(turn, step)` 的后一份样本替换前一份，`llm/retry-started` 之后重试的那次累加，与 DSH 自己的回合用量口径一致；随后按模型汇总。一个回合即收尾消息所在的 `turn/start`..`turn/end` 区间；排行从每个会话日志里最后一条 `session/title` 事件折叠标题（last-wins，重命名事件一旦提交、会话被重新读取即反映新名字）。
+插件注册 `billing` Remote，含六个方法：`getBalance(force?)`（解析后的 `/user/balance` 快照；15 秒宿主 TTL 内复用，`force` 绕过，单次请求 5 秒超时）、`getSessionSpend(sessionId)`（单个会话的计费花费）、`getTodaySpend(force?)`（当前北京时间自然日内所有会话的计费花费合计；`force` 绕过宿主侧缓存，供徽标手动刷新使用）、`getTodaySessionsSpend(force?)`（今日按会话的计费花费，按花费从高到低排序，每行带会话的持久标题）、`getTurnSpend(sessionId, messageId)`（单个已完成回合的计费花费，按收尾助手消息 id 定位）与 `getSessionTurnSpends(sessionId)`（该会话所有已完成回合的 `messageId → 金额` 映射，一趟折叠——对话每个消息行都要显示金额，客户端因此每会话只拉一次，而不是逐行调用 `getTurnSpend`）。计价的样本来源有两处：`assistant/message` 自身的 usage，以及失败/重试的 `assistant/attempt` 内嵌 stream 里的 usage（后者用最近一条 `request/header` 的模型），各按样本自身发生时刻（北京时间）所在的峰/谷单价、以及该时刻生效的官方费率版本计价——高峰窗口仅周一至周五适用，周末全天按低谷价。同一 `(turn, step)` 的后一份样本替换前一份，`llm/retry-started` 之后重试的那次累加，与 DSH 自己的回合用量口径一致；随后按模型汇总。一个回合即收尾消息所在的 `turn/start`..`turn/end` 区间；排行从每个会话日志里最后一条 `session/title` 事件折叠标题（last-wins，重命名事件一旦提交、会话被重新读取即反映新名字）。
 
 ### 今日花费读取路径（消息触发不再全量扫描）
 
@@ -27,7 +27,7 @@
 
 进程内首次解析之后，稳态读取只花在日志确实变化过的会话上。日志无法读取的会话带警告跳过（并被记住），而不是让整日合计失败。
 
-注意：投影路径对每个会话的历史只计价一次，按事件被折叠时的费率——修改 `billing.models` 只影响变更后折叠的事件（事件路径会重算整个日志）。
+注意：投影路径对每个会话的历史只计价一次，按事件被折叠时的费率。官方费率版本随定价闭包一起进入折叠，并按样本自身时刻解析，因此被调价的系列无论日志多晚折叠都能正确计价自身历史；只有**手工修改配置**（`billing.models`）才只影响变更后折叠的事件（事件路径会重算整个日志），而该解析口径变化时单元 `stateVersion` 会一并提升，使已落检查点被丢弃重折而不是沿用旧值。
 
 ## 分叉会话
 
@@ -47,11 +47,17 @@
 | --- | --- | --- |
 | `apiKeyEnv` | `DEEPSEEK_API_KEY` | 每次调用时解析的凭据引用（环境变量）名。 |
 | `baseURL` | `$DEEPSEEK_BASE_URL`，其次 `https://api.deepseek.com` | 端点基础地址；会追加 `/user/balance`。 |
-| `models` | V4 Flash + V4.1 Flash + V4 Pro + V4 Flash Vision Exp + MiMo-V2.5 系列 | 展示用的模型行，按展示顺序。 |
+| `models` | V4.1 Flash（`deepseek-flash`）+ V4 Flash + V4 Pro + V4 Flash Vision Exp + MiMo-V2.5 系列 | 展示用的模型行，按展示顺序；与 DSH `llm-deepseek` 目录对齐（另保留已退役的 `deepseek-v4.1-flash-expires-on-0910` 预览 id，让历史日志仍有可读标签）。 |
 | `billing.peakHours` | 09:00–12:00、14:00–18:00（北京，仅工作日） | 高峰时段窗口，仅周一至周五适用；周末与其余时段均为低谷。 |
-| `billing.models` | 官方 V4 + MiMo 费率 | 每个模型的峰/谷单价行（`cacheHitInput`、`cacheMissInput`、`output`，单位：元/百万 token）。 |
+| `billing.models` | 官方 V4 + MiMo 费率 | 每个模型的单价行（`cacheHitInput`、`cacheMissInput`、`output`，单位：元/百万 token），可带生效时刻 `effectiveFrom`（epoch 毫秒，含该时刻）。 |
 
-只想覆盖某个模型而不丢其它，就提供一个非空的 `billing.models` 列表；空或省略则回退到官方默认费率。
+只想覆盖某个模型而不丢其它，就提供一个非空的 `billing.models` 列表；空或省略则回退到官方默认费率。同一个模型可以有多行：每行是一个费率版本，用量样本按**样本自身时刻**生效的那一版取峰/谷单价（不带 `effectiveFrom` 的行是该模型的基础版本，同时覆盖更早的一切时刻）。
+
+内置价目表已包含 DeepSeek 的两轮调整，跨越任一变更点的会话或自然日都能精确计价：
+
+- **2026-09-10 12:00（北京时间）**（`FLASH_SERIES_RATE_CHANGE_AT`）：整个 flash 系列——V4.1 Flash 路由 `deepseek-flash`（当日发布，现为 DSH 默认模型）、V4 Flash、V4 Flash Vision Exp 以及已退役的预览 id——降为谷时 0.02 / 1.0 / 4.0，峰时为其两倍；更早的样本（含该路由 12:00 之前的自身用量）沿用被取代的旧价。
+- **2026-09-14 12:00（北京时间）**（`V4_PRO_ROUTE_SWITCH_AT`）：V4 Pro 路由按公告改由 V4.1 Flash 服务并按 V4.1 Flash 计费，该行因此带有第二个费率版本。
+- MiMo-V2.5 系列不受两轮调整影响（统一费率）。
 
 ## 模型体验
 
@@ -64,7 +70,7 @@
 ## 已知限制与暂缓事项
 
 - **有费率行才计价** —— 会话花费与今日花费只统计价目表（`billing.models`）里有的模型；没有费率行的模型不计入。`assistant/attempt` 用最近一条 `request/header` 的模型计价，因此首条 header 之前的 attempt 不计入。
-- **最多 60 秒延迟** —— `getTodaySpend()` 由宿主侧缓存服务最多 60 秒；只有手动刷新（`force`）立即重算（仍受 revision 门控，日志未变则零成本）。浏览器端「本会话花费」读的是推送的投影值，因此不会滞后。
+- **最多 60 秒延迟** —— `getTodaySpend()` 由宿主侧缓存服务最多 60 秒；只有手动刷新（`force`）立即重算（仍受 revision 门控，日志未变则零成本）。浏览器端「本会话花费」读的是推送的投影值，因此不会滞后；它括号里的今日份金额取自已拉取的今日会话排行（`getTodaySessionsSpend()`，同样受 60 秒缓存与 revision 门控），所以那一项最多滞后 60 秒。
 - **额度带 TTL 缓存** —— 一份 `/user/balance` 快照最多复用 15 秒，单次请求 5 秒超时；`force`（手动刷新）绕过 TTL。
-- **投影计价对历史冻结** —— 投影路径生效时，修改计价表只影响变更后折叠的事件；重启（或事件路径回退）才会重算整个日志。
+- **投影计价跟随官方费率版本** —— 投影折叠按样本时刻解析费率版本，官方调价因此无需重折；手工改 `billing.models` 则只影响变更后折叠的事件，直到状态版本或进程重置（事件路径回退会重算整个日志）。
 - **冷缓存行可能滞后于日志** —— 冷会话若缓存行覆盖查询日，会重读日志以求精确；若缓存行自身的日期不是查询日则直接采信、不读日志，因此进程在最后一次检查点之后、最后一条事件之前崩溃的会话，其尾部可能暂时少算，直到该会话被重新读取。

package/lib/index.js

@@ -322,33 +322,93 @@ const DEFAULT_PEAK_HOURS = [{
 	start: 14,
 	end: 18
 }];
-/** Official peak/off-peak rates (CNY per 1M tokens), effective 2026-08-17. */
+/**
+* Inclusive epoch ms of the published V4 Flash series re-pricing:
+* 2026-09-10 12:00 Beijing time (UTC+8, no DST) = 04:00 UTC. Samples before
+* this instant keep the base rates; samples at or after it bill at the second
+* revision.
+*/
+const FLASH_SERIES_RATE_CHANGE_AT = Date.UTC(2026, 8, 10, 4, 0, 0);
+/**
+* Inclusive epoch ms of the announced V4 Pro route switch: 2026-09-14 12:00
+* Beijing time (UTC+8, no DST) = 04:00 UTC. From that instant the V4 Pro route
+* is served by V4.1 Flash and billed at the V4.1 Flash rates.
+*/
+const V4_PRO_ROUTE_SWITCH_AT = Date.UTC(2026, 8, 14, 4, 0, 0);
+/** The V4 Flash series' base rates (effective 2026-08-17), CNY per 1M tokens. */
+const FLASH_BASE_RATES = {
+	peak: {
+		cacheHitInput: .1,
+		cacheMissInput: 3,
+		output: 9
+	},
+	offPeak: {
+		cacheHitInput: .05,
+		cacheMissInput: 1.5,
+		output: 4.5
+	}
+};
+/**
+* The V4 Flash series' second revision (effective
+* {@link FLASH_SERIES_RATE_CHANGE_AT}): off-peak 0.02 / 1.0 / 4.0, peak at
+* twice those prices.
+*/
+const FLASH_REPRICED_RATES = {
+	effectiveFrom: FLASH_SERIES_RATE_CHANGE_AT,
+	peak: {
+		cacheHitInput: .04,
+		cacheMissInput: 2,
+		output: 8
+	},
+	offPeak: {
+		cacheHitInput: .02,
+		cacheMissInput: 1,
+		output: 4
+	}
+};
+/**
+* The V4.1 Flash rates as they reach the retired V4 Pro route from
+* {@link V4_PRO_ROUTE_SWITCH_AT}: the same price pair as the flash series'
+* second revision, carried at its own effective instant.
+*/
+const V4_PRO_SWITCHED_RATES = {
+	effectiveFrom: V4_PRO_ROUTE_SWITCH_AT,
+	peak: FLASH_REPRICED_RATES.peak,
+	offPeak: FLASH_REPRICED_RATES.offPeak
+};
+/**
+* Official peak/off-peak rates (CNY per 1M tokens) per model, as dated
+* revisions. Base rows are the schedule effective 2026-08-17; the V4 Flash
+* series (V4.1 Flash, V4 Flash, V4 Flash Vision Exp) carries the second
+* revision effective 2026-09-10 12:00 Beijing, and the V4 Pro row the V4.1
+* Flash rates from its announced route switch (2026-09-14 12:00 Beijing) —
+* the MiMo-V2.5 series is untouched by either adjustment. Rows sharing a model
+* are that model's rate history.
+*/
 const DEFAULT_MODEL_PRICING = [
+	{
+		model: "deepseek-flash",
+		...FLASH_BASE_RATES
+	},
+	{
+		model: "deepseek-flash",
+		...FLASH_REPRICED_RATES
+	},
 	{
 		model: "deepseek-v4-flash",
-		peak: {
-			cacheHitInput: .1,
-			cacheMissInput: 3,
-			output: 9
-		},
-		offPeak: {
-			cacheHitInput: .05,
-			cacheMissInput: 1.5,
-			output: 4.5
-		}
+		...FLASH_BASE_RATES
+	},
+	{
+		model: "deepseek-v4-flash",
+		...FLASH_REPRICED_RATES
 	},
 	{
 		model: "deepseek-v4.1-flash-expires-on-0910",
-		peak: {
-			cacheHitInput: .1,
-			cacheMissInput: 3,
-			output: 9
-		},
-		offPeak: {
-			cacheHitInput: .05,
-			cacheMissInput: 1.5,
-			output: 4.5
-		}
+		...FLASH_BASE_RATES
+	},
+	{
+		model: "deepseek-v4.1-flash-expires-on-0910",
+		...FLASH_REPRICED_RATES
 	},
 	{
 		model: "deepseek-v4-pro",
@@ -363,18 +423,17 @@ const DEFAULT_MODEL_PRICING = [
 			output: 13.5
 		}
 	},
+	{
+		model: "deepseek-v4-pro",
+		...V4_PRO_SWITCHED_RATES
+	},
 	{
 		model: "deepseek-v4-flash-vision-exp",
-		peak: {
-			cacheHitInput: .1,
-			cacheMissInput: 3,
-			output: 9
-		},
-		offPeak: {
-			cacheHitInput: .05,
-			cacheMissInput: 1.5,
-			output: 4.5
-		}
+		...FLASH_BASE_RATES
+	},
+	{
+		model: "deepseek-v4-flash-vision-exp",
+		...FLASH_REPRICED_RATES
 	},
 	{
 		model: "mimo-v2.5-pro",
@@ -409,22 +468,67 @@ const DEFAULT_MODEL_PRICING = [
 * `z.array` as `[]` rather than `undefined`, so emptiness — not just absence —
 * selects the defaults. Explicit non-empty rows override the same model; a
 * supplied non-empty `models` list is authoritative.
+*
+* Rows sharing a model are that model's rate revisions, kept in ascending
+* `effectiveFrom` order (an undated base revision first). Two rows declaring
+* the same effective instant are one revision and the later row wins — the
+* historical override rule — so re-declaring a model can neither duplicate a
+* revision nor install a second undated base.
 * @param config - optional raw billing configuration.
-* @returns the resolved table and peak-hour windows.
+* @returns the resolved table (per model: its revisions plus the newest rates) and peak-hour windows.
 */
 function resolveBilling(config) {
 	const peakHours = config?.peakHours !== void 0 && config.peakHours.length > 0 ? config.peakHours : DEFAULT_PEAK_HOURS;
 	const rows = config?.models !== void 0 && config.models.length > 0 ? config.models : DEFAULT_MODEL_PRICING;
+	const schedules = /* @__PURE__ */ new Map();
+	for (const row of rows) {
+		const revision = row.effectiveFrom === void 0 ? {
+			peak: row.peak,
+			offPeak: row.offPeak
+		} : {
+			effectiveFrom: row.effectiveFrom,
+			peak: row.peak,
+			offPeak: row.offPeak
+		};
+		const revisions = schedules.get(row.model);
+		if (revisions === void 0) {
+			schedules.set(row.model, [revision]);
+			continue;
+		}
+		const duplicate = revisions.findIndex((candidate) => candidate.effectiveFrom === revision.effectiveFrom);
+		if (duplicate >= 0) revisions[duplicate] = revision;
+		else revisions.push(revision);
+	}
 	const models = /* @__PURE__ */ new Map();
-	for (const row of rows) models.set(row.model, {
-		peak: row.peak,
-		offPeak: row.offPeak
-	});
+	for (const [model, revisions] of schedules) {
+		revisions.sort((left, right) => (left.effectiveFrom ?? Number.NEGATIVE_INFINITY) - (right.effectiveFrom ?? Number.NEGATIVE_INFINITY));
+		const newest = revisions[revisions.length - 1];
+		models.set(model, {
+			peak: newest.peak,
+			offPeak: newest.offPeak,
+			revisions
+		});
+	}
 	return {
 		peakHours,
 		models
 	};
 }
+/**
+* The rate revision in effect at one instant: the newest revision that took
+* effect at or before it. Revisions are ascending, so the scan stops at the
+* first future one. An instant before the earliest dated revision bills at that
+* earliest revision — a model with only dated rows is never left unpriced.
+*/
+function ratesAt(revisions, time) {
+	let chosen = revisions[0];
+	for (let index = 1; index < revisions.length; index += 1) {
+		const revision = revisions[index];
+		if (revision.effectiveFrom === void 0 || revision.effectiveFrom > time) break;
+		chosen = revision;
+	}
+	return chosen;
+}
 /** Beijing is a fixed UTC+8 offset with no DST. */
 const BEIJING_OFFSET_MS = 288e5;
 /** Milliseconds in one day. */
@@ -472,6 +576,7 @@ function beijingPartsOf(time) {
 	const msOfDay = shifted - epochDay * DAY_MS;
 	const civil = civilDateOf(epochDay);
 	return {
+		time,
 		hour: Math.floor(msOfDay / 36e5),
 		weekday: ((epochDay + 4) % 7 + 7) % 7,
 		dayKey: `${civil.year}-${pad2(civil.month)}-${pad2(civil.day)}`
@@ -525,7 +630,8 @@ function isPeak(billing, now) {
 /**
 * Price one event at the official per-model rates, applying the peak/off-peak
 * table by its Beijing-time hour and weekday (peak windows apply Monday–Friday
-* only; weekends are off-peak). Each `assistant/message` event with usage
+* only; weekends are off-peak) and the rate revision in effect at its own
+* timestamp. Each `assistant/message` event with usage
 * contributes cache-hit input, cache-miss input (uncached input plus cache
 * writes), and output (reasoning included) tokens at the rate of its own
 * timestamp; a model with usage but no pricing row contributes nothing.
@@ -556,8 +662,10 @@ function priceEventAt(parts, event, billing, names) {
 }
 /**
 * Price one provider-reported usage sample for one model at the rates of the
-* sample's own Beijing-time hour and weekday. `undefined` when the model has
-* no pricing row.
+* sample's own Beijing-time hour and weekday — the peak or off-peak price of
+* the rate revision in effect at the sample's own timestamp (a re-priced series
+* bills its history at the rates that applied then). `undefined` when the model
+* has no pricing row.
 * @param parts - the sample's Beijing-time view.
 * @param usage - the reported token buckets.
 * @param model - the wire model id the sample belongs to.
@@ -569,7 +677,8 @@ function priceUsage(parts, usage, model, billing, names) {
 	const pricing = billing.models.get(model);
 	if (pricing === void 0) return void 0;
 	const peak = isPeakParts(billing, parts.hour, parts.weekday);
-	const price = peak ? pricing.peak : pricing.offPeak;
+	const revision = ratesAt(pricing.revisions, parts.time);
+	const price = peak ? revision.peak : revision.offPeak;
 	const hit = usage.cacheReadTokens ?? 0;
 	const miss = usage.inputTokens + (usage.cacheWriteTokens ?? 0);
 	const output = usage.outputTokens;
@@ -1119,13 +1228,15 @@ const billingUnitSchema = z$1.object({
 	}).strict().nullable()
 }).strict();
 /**
-* Build the `billingTodaySpend` unit for one resolved pricing table. The
-* pricing closure is fixed at registration; a pricing-table change therefore
-* prices only events folded after the change (historical spend keeps its
-* historical rates), unlike the events-scan paths which re-price the whole
-* log. Bump {@link ProjectionDefinition.stateVersion} whenever the state
-* shape or fold semantics change, so persisted checkpoint rows are discarded
-* instead of folded forward.
+* Build the `billingTodaySpend` unit for one resolved pricing table. Published
+* rate revisions travel inside the closure and are resolved per sample
+* timestamp, so a re-priced series bills its own history correctly however late
+* a log is folded; only a configuration change (editing `billing.models`) is
+* fixed at registration, and it re-prices just the events folded afterwards
+* (the events-scan paths re-price the whole log). Bump
+* {@link ProjectionDefinition.stateVersion} whenever the state shape or fold
+* semantics change, so persisted checkpoint rows are discarded instead of
+* folded forward.
 * @param billing - resolved pricing with peak-hour windows.
 * @param catalog - model display rows, in presentation order.
 * @returns the unit definition to register on `ctx.sessionProjections`.
@@ -1134,7 +1245,7 @@ function billingTodaySpendDefinition(billing, catalog) {
 	const names = new Map(catalog.map((model) => [model.id, model.name]));
 	return {
 		key: BILLING_UNIT_KEY,
-		stateVersion: 3,
+		stateVersion: 4,
 		stateSchema: billingUnitSchema,
 		init: (_header, inheritedEventCount) => emptyBillingFoldState(Number(inheritedEventCount ?? 0)),
 		apply: (state, event) => applyBillingEvent(state, event, billing, names),
@@ -1698,7 +1809,18 @@ const DEFAULT_API_KEY_ENV = "DEEPSEEK_API_KEY";
 const BASE_URL_ENV = "DEEPSEEK_BASE_URL";
 /** Public API default; deployments may point elsewhere via $DEEPSEEK_BASE_URL. */
 const PUBLIC_BASE_URL = "https://api.deepseek.com";
+/**
+* Advisory display rows mirroring the DSH `llm-deepseek` catalog (V4.1 Flash
+* first, its current default route), plus the MiMo-V2.5 series. The retired
+* preview id `deepseek-v4.1-flash-expires-on-0910` stays so the logs that used
+* it keep a readable label; rows never restrict which models are priced — the
+* pricing table does.
+*/
 const DEFAULT_MODELS = [
+	{
+		id: "deepseek-flash",
+		name: "DeepSeek-V41-Flash"
+	},
 	{
 		id: "deepseek-v4-flash",
 		name: "DeepSeek-V4-Flash"
@@ -1733,16 +1855,18 @@ const tokenPrice = z.object({
 	cacheMissInput: z.number().min(0),
 	output: z.number().min(0)
 });
+const billingRateRow = z.object({
+	model: z.string().required(),
+	peak: tokenPrice,
+	offPeak: tokenPrice,
+	effectiveFrom: z.number().min(0)
+});
 const billingConfig = z.object({
 	peakHours: z.array(z.object({
 		start: z.number().step(1).min(0).max(23),
 		end: z.number().step(1).min(0).max(24)
 	})).default([...DEFAULT_PEAK_HOURS]),
-	models: z.array(z.object({
-		model: z.string().required(),
-		peak: tokenPrice,
-		offPeak: tokenPrice
-	})).default([...DEFAULT_MODEL_PRICING])
+	models: z.array(billingRateRow).default([...DEFAULT_MODEL_PRICING])
 });
 const Config = z.object({
 	apiKeyEnv: z.string().role("credential-ref").default(DEFAULT_API_KEY_ENV),
@@ -2017,4 +2141,4 @@ function apply(ctx, config) {
 	});
 }
 //#endregion
-export { BALANCE_CACHE_MS, BALANCE_TIMEOUT_MS, BILLING_UNIT_KEY, BillingFolder, Config, DEFAULT_MODEL_PRICING, DEFAULT_PEAK_HOURS, DeepSeekBalanceGateway, PUBLIC_BASE_URL, SESSION_SPEND_CACHE_LIMIT, SESSION_TURN_SPEND_CACHE_LIMIT, SessionTurnSpendFolder, SpendAccumulator, TODAY_SPEND_CACHE_MS, TODAY_SPEND_MAX_EVENTS, TodaySpendCache, TodaySpendScanner, addEventContribution, apply, applyBillingEvent, beijingDayKey, billingTodaySpendDefinition, computeSessionSpend, computeSessionTurnSpends, computeTodaySpend, computeTurnSpend, emptyBillingFoldState, emptyTodaySpend, fetchDeepSeekBalance, foldBillingUnit, foldOwnBilling, foldSessionTitle, forkBoundaryOf, isPeak, isSeededSession, liveSessionEvents, mergeTodaySpend, name, negateSpend, parseDeepSeekBalance, persistenceInspect, persistenceListSnapshots, priceEvent, priceUsage, resolveBilling, subtractSpend };
+export { BALANCE_CACHE_MS, BALANCE_TIMEOUT_MS, BILLING_UNIT_KEY, BillingFolder, Config, DEFAULT_MODEL_PRICING, DEFAULT_PEAK_HOURS, DeepSeekBalanceGateway, FLASH_SERIES_RATE_CHANGE_AT, PUBLIC_BASE_URL, SESSION_SPEND_CACHE_LIMIT, SESSION_TURN_SPEND_CACHE_LIMIT, SessionTurnSpendFolder, SpendAccumulator, TODAY_SPEND_CACHE_MS, TODAY_SPEND_MAX_EVENTS, TodaySpendCache, TodaySpendScanner, V4_PRO_ROUTE_SWITCH_AT, addEventContribution, apply, applyBillingEvent, beijingDayKey, billingTodaySpendDefinition, computeSessionSpend, computeSessionTurnSpends, computeTodaySpend, computeTurnSpend, emptyBillingFoldState, emptyTodaySpend, fetchDeepSeekBalance, foldBillingUnit, foldOwnBilling, foldSessionTitle, forkBoundaryOf, isPeak, isSeededSession, liveSessionEvents, mergeTodaySpend, name, negateSpend, parseDeepSeekBalance, persistenceInspect, persistenceListSnapshots, priceEvent, priceUsage, resolveBilling, subtractSpend };

package/lib/types/billing.d.ts

@@ -24,21 +24,41 @@ export interface DeepSeekTokenPrice {
     /** 1M output tokens. */
     output: number;
 }
-/** Peak and off-peak price pair for one model. */
-export interface DeepSeekModelPricing {
+/**
+ * One published peak/off-peak rate revision of a model: the price pair plus the
+ * instant it took effect. A provider re-prices a series without repricing its
+ * history, so the table keeps every revision and prices each sample at the
+ * rates of the sample's own timestamp.
+ */
+export interface DeepSeekRateRevision {
     /** Price during peak hours. */
     peak: DeepSeekTokenPrice;
     /** Price during off-peak hours. */
     offPeak: DeepSeekTokenPrice;
+    /**
+     * Inclusive epoch ms this revision takes effect: it prices every sample at or
+     * after that instant. `undefined` on a model's base revision, which also
+     * covers every earlier instant.
+     */
+    effectiveFrom?: number;
+}
+/** Resolved pricing for one model: its published rate revisions, oldest first. */
+export interface DeepSeekModelPricing {
+    /** Peak-hour price of the newest revision (the rates in effect now). */
+    peak: DeepSeekTokenPrice;
+    /** Off-peak price of the newest revision (the rates in effect now). */
+    offPeak: DeepSeekTokenPrice;
+    /**
+     * Every published revision of this model, ascending by `effectiveFrom` (an
+     * undated base revision first); always at least one. {@link priceUsage} picks
+     * the revision in effect at the priced sample's own timestamp.
+     */
+    revisions: readonly DeepSeekRateRevision[];
 }
 /** One model's pricing-table row in configuration form. */
-export interface BillingConfigModel {
+export interface BillingConfigModel extends DeepSeekRateRevision {
     /** Wire model id. */
     model: string;
-    /** Peak-hour price. */
-    peak: DeepSeekTokenPrice;
-    /** Off-peak price. */
-    offPeak: DeepSeekTokenPrice;
 }
 /** One peak-hour window on a 24h Beijing-time clock, applied weekdays only. */
 export interface PeakHourWindow {
@@ -54,7 +74,11 @@ export interface BillingConfig {
      * only; weekends (Saturday and Sunday) are always off-peak.
      */
     peakHours?: PeakHourWindow[];
-    /** Per-model pricing rows; omission uses the V4 Flash, V4.1 Flash, V4 Pro, and V4 Flash Vision defaults. */
+    /**
+     * Per-model pricing rows; omission uses the published V4 and MiMo rates.
+     * Several rows for one model declare that model's rate history, priced per
+     * sample by `effectiveFrom` (see {@link BillingConfigModel}).
+     */
     models?: BillingConfigModel[];
 }
 /**
@@ -63,7 +87,28 @@ export interface BillingConfig {
  * (effective 2026-08-23).
  */
 export declare const DEFAULT_PEAK_HOURS: readonly PeakHourWindow[];
-/** Official peak/off-peak rates (CNY per 1M tokens), effective 2026-08-17. */
+/**
+ * Inclusive epoch ms of the published V4 Flash series re-pricing:
+ * 2026-09-10 12:00 Beijing time (UTC+8, no DST) = 04:00 UTC. Samples before
+ * this instant keep the base rates; samples at or after it bill at the second
+ * revision.
+ */
+export declare const FLASH_SERIES_RATE_CHANGE_AT: number;
+/**
+ * Inclusive epoch ms of the announced V4 Pro route switch: 2026-09-14 12:00
+ * Beijing time (UTC+8, no DST) = 04:00 UTC. From that instant the V4 Pro route
+ * is served by V4.1 Flash and billed at the V4.1 Flash rates.
+ */
+export declare const V4_PRO_ROUTE_SWITCH_AT: number;
+/**
+ * Official peak/off-peak rates (CNY per 1M tokens) per model, as dated
+ * revisions. Base rows are the schedule effective 2026-08-17; the V4 Flash
+ * series (V4.1 Flash, V4 Flash, V4 Flash Vision Exp) carries the second
+ * revision effective 2026-09-10 12:00 Beijing, and the V4 Pro row the V4.1
+ * Flash rates from its announced route switch (2026-09-14 12:00 Beijing) —
+ * the MiMo-V2.5 series is untouched by either adjustment. Rows sharing a model
+ * are that model's rate history.
+ */
 export declare const DEFAULT_MODEL_PRICING: readonly BillingConfigModel[];
 /** Resolved billing configuration: a pricing table plus peak-hour windows. */
 export interface ResolvedBilling {
@@ -79,12 +124,24 @@ export interface ResolvedBilling {
  * `z.array` as `[]` rather than `undefined`, so emptiness — not just absence —
  * selects the defaults. Explicit non-empty rows override the same model; a
  * supplied non-empty `models` list is authoritative.
+ *
+ * Rows sharing a model are that model's rate revisions, kept in ascending
+ * `effectiveFrom` order (an undated base revision first). Two rows declaring
+ * the same effective instant are one revision and the later row wins — the
+ * historical override rule — so re-declaring a model can neither duplicate a
+ * revision nor install a second undated base.
  * @param config - optional raw billing configuration.
- * @returns the resolved table and peak-hour windows.
+ * @returns the resolved table (per model: its revisions plus the newest rates) and peak-hour windows.
  */
 export declare function resolveBilling(config: BillingConfig | undefined): ResolvedBilling;
 /** One shifted-timestamp view of a Beijing (UTC+8, no DST) instant. */
 export interface BeijingParts {
+    /**
+     * The instant in epoch milliseconds. Pricing needs it back to resolve the
+     * rate revision in effect at the sample's own timestamp (see
+     * {@link ratesAt}), so the view carries it instead of a second parse.
+     */
+    time: number;
     /** Beijing hour, `0`–`23`. */
     hour: number;
     /** Beijing weekday as `getUTCDay()`: `0` is Sunday, `6` is Saturday. */
@@ -199,7 +256,8 @@ export interface BillingEventContribution {
 /**
  * Price one event at the official per-model rates, applying the peak/off-peak
  * table by its Beijing-time hour and weekday (peak windows apply Monday–Friday
- * only; weekends are off-peak). Each `assistant/message` event with usage
+ * only; weekends are off-peak) and the rate revision in effect at its own
+ * timestamp. Each `assistant/message` event with usage
  * contributes cache-hit input, cache-miss input (uncached input plus cache
  * writes), and output (reasoning included) tokens at the rate of its own
  * timestamp; a model with usage but no pricing row contributes nothing.
@@ -223,8 +281,10 @@ export declare function priceEvent(event: SessionEvent, billing: ResolvedBilling
 export declare function priceEventAt(parts: BeijingParts, event: SessionEvent, billing: ResolvedBilling, names: ReadonlyMap<string, string>): BillingEventContribution | undefined;
 /**
  * Price one provider-reported usage sample for one model at the rates of the
- * sample's own Beijing-time hour and weekday. `undefined` when the model has
- * no pricing row.
+ * sample's own Beijing-time hour and weekday — the peak or off-peak price of
+ * the rate revision in effect at the sample's own timestamp (a re-priced series
+ * bills its history at the rates that applied then). `undefined` when the model
+ * has no pricing row.
  * @param parts - the sample's Beijing-time view.
  * @param usage - the reported token buckets.
  * @param model - the wire model id the sample belongs to.

package/lib/types/billing.js

@@ -21,33 +21,77 @@ export const DEFAULT_PEAK_HOURS = [
     { start: 9, end: 12 },
     { start: 14, end: 18 },
 ];
-/** Official peak/off-peak rates (CNY per 1M tokens), effective 2026-08-17. */
+/**
+ * Inclusive epoch ms of the published V4 Flash series re-pricing:
+ * 2026-09-10 12:00 Beijing time (UTC+8, no DST) = 04:00 UTC. Samples before
+ * this instant keep the base rates; samples at or after it bill at the second
+ * revision.
+ */
+export const FLASH_SERIES_RATE_CHANGE_AT = Date.UTC(2026, 8, 10, 4, 0, 0);
+/**
+ * Inclusive epoch ms of the announced V4 Pro route switch: 2026-09-14 12:00
+ * Beijing time (UTC+8, no DST) = 04:00 UTC. From that instant the V4 Pro route
+ * is served by V4.1 Flash and billed at the V4.1 Flash rates.
+ */
+export const V4_PRO_ROUTE_SWITCH_AT = Date.UTC(2026, 8, 14, 4, 0, 0);
+/** The V4 Flash series' base rates (effective 2026-08-17), CNY per 1M tokens. */
+const FLASH_BASE_RATES = {
+    peak: { cacheHitInput: 0.10, cacheMissInput: 3.0, output: 9.0 },
+    offPeak: { cacheHitInput: 0.05, cacheMissInput: 1.5, output: 4.5 },
+};
+/**
+ * The V4 Flash series' second revision (effective
+ * {@link FLASH_SERIES_RATE_CHANGE_AT}): off-peak 0.02 / 1.0 / 4.0, peak at
+ * twice those prices.
+ */
+const FLASH_REPRICED_RATES = {
+    effectiveFrom: FLASH_SERIES_RATE_CHANGE_AT,
+    peak: { cacheHitInput: 0.04, cacheMissInput: 2.0, output: 8.0 },
+    offPeak: { cacheHitInput: 0.02, cacheMissInput: 1.0, output: 4.0 },
+};
+/**
+ * The V4.1 Flash rates as they reach the retired V4 Pro route from
+ * {@link V4_PRO_ROUTE_SWITCH_AT}: the same price pair as the flash series'
+ * second revision, carried at its own effective instant.
+ */
+const V4_PRO_SWITCHED_RATES = {
+    effectiveFrom: V4_PRO_ROUTE_SWITCH_AT,
+    peak: FLASH_REPRICED_RATES.peak,
+    offPeak: FLASH_REPRICED_RATES.offPeak,
+};
+/**
+ * Official peak/off-peak rates (CNY per 1M tokens) per model, as dated
+ * revisions. Base rows are the schedule effective 2026-08-17; the V4 Flash
+ * series (V4.1 Flash, V4 Flash, V4 Flash Vision Exp) carries the second
+ * revision effective 2026-09-10 12:00 Beijing, and the V4 Pro row the V4.1
+ * Flash rates from its announced route switch (2026-09-14 12:00 Beijing) —
+ * the MiMo-V2.5 series is untouched by either adjustment. Rows sharing a model
+ * are that model's rate history.
+ */
 export const DEFAULT_MODEL_PRICING = [
-    {
-        model: 'deepseek-v4-flash',
-        peak: { cacheHitInput: 0.10, cacheMissInput: 3.0, output: 9.0 },
-        offPeak: { cacheHitInput: 0.05, cacheMissInput: 1.5, output: 4.5 },
-    },
-    // deepseek-v4.1-flash-expires-on-0910 bills at the same rates as
-    // deepseek-v4-flash; image inputs are converted to tokens at the same
-    // per-token price.
-    {
-        model: 'deepseek-v4.1-flash-expires-on-0910',
-        peak: { cacheHitInput: 0.10, cacheMissInput: 3.0, output: 9.0 },
-        offPeak: { cacheHitInput: 0.05, cacheMissInput: 1.5, output: 4.5 },
-    },
+    // deepseek-flash is the V4.1 Flash route, DSH's default catalog entry; image
+    // inputs are converted to tokens at the same per-token price.
+    { model: 'deepseek-flash', ...FLASH_BASE_RATES },
+    { model: 'deepseek-flash', ...FLASH_REPRICED_RATES },
+    { model: 'deepseek-v4-flash', ...FLASH_BASE_RATES },
+    { model: 'deepseek-v4-flash', ...FLASH_REPRICED_RATES },
+    // deepseek-v4.1-flash-expires-on-0910 was the V4.1 Flash preview route,
+    // retired when the model was released on 2026-09-10; its rows stay so the
+    // logs that used it keep pricing.
+    { model: 'deepseek-v4.1-flash-expires-on-0910', ...FLASH_BASE_RATES },
+    { model: 'deepseek-v4.1-flash-expires-on-0910', ...FLASH_REPRICED_RATES },
     {
         model: 'deepseek-v4-pro',
         peak: { cacheHitInput: 0.30, cacheMissInput: 9.0, output: 27.0 },
         offPeak: { cacheHitInput: 0.15, cacheMissInput: 4.5, output: 13.5 },
     },
+    // From the announced route switch V4 Pro is served by V4.1 Flash and billed
+    // at the V4.1 Flash rates.
+    { model: 'deepseek-v4-pro', ...V4_PRO_SWITCHED_RATES },
     // deepseek-v4-flash-vision-exp bills at the same rates as deepseek-v4-flash;
     // images are converted to tokens at the same per-token price.
-    {
-        model: 'deepseek-v4-flash-vision-exp',
-        peak: { cacheHitInput: 0.10, cacheMissInput: 3.0, output: 9.0 },
-        offPeak: { cacheHitInput: 0.05, cacheMissInput: 1.5, output: 4.5 },
-    },
+    { model: 'deepseek-v4-flash-vision-exp', ...FLASH_BASE_RATES },
+    { model: 'deepseek-v4-flash-vision-exp', ...FLASH_REPRICED_RATES },
     // MiMo-V2.5 series (Xiaomi): flat rate, no peak/off-peak distinction.
     {
         model: 'mimo-v2.5-pro',
@@ -66,8 +110,14 @@ export const DEFAULT_MODEL_PRICING = [
  * `z.array` as `[]` rather than `undefined`, so emptiness — not just absence —
  * selects the defaults. Explicit non-empty rows override the same model; a
  * supplied non-empty `models` list is authoritative.
+ *
+ * Rows sharing a model are that model's rate revisions, kept in ascending
+ * `effectiveFrom` order (an undated base revision first). Two rows declaring
+ * the same effective instant are one revision and the later row wins — the
+ * historical override rule — so re-declaring a model can neither duplicate a
+ * revision nor install a second undated base.
  * @param config - optional raw billing configuration.
- * @returns the resolved table and peak-hour windows.
+ * @returns the resolved table (per model: its revisions plus the newest rates) and peak-hour windows.
  */
 export function resolveBilling(config) {
     const peakHours = config?.peakHours !== undefined && config.peakHours.length > 0
@@ -76,11 +126,48 @@ export function resolveBilling(config) {
     const rows = config?.models !== undefined && config.models.length > 0
         ? config.models
         : DEFAULT_MODEL_PRICING;
+    const schedules = new Map();
+    for (const row of rows) {
+        // Spelled out per branch: `exactOptionalPropertyTypes` forbids handing an
+        // explicit `undefined` to an optional field.
+        const revision = row.effectiveFrom === undefined
+            ? { peak: row.peak, offPeak: row.offPeak }
+            : { effectiveFrom: row.effectiveFrom, peak: row.peak, offPeak: row.offPeak };
+        const revisions = schedules.get(row.model);
+        if (revisions === undefined) {
+            schedules.set(row.model, [revision]);
+            continue;
+        }
+        const duplicate = revisions.findIndex(candidate => candidate.effectiveFrom === revision.effectiveFrom);
+        if (duplicate >= 0)
+            revisions[duplicate] = revision;
+        else
+            revisions.push(revision);
+    }
     const models = new Map();
-    for (const row of rows)
-        models.set(row.model, { peak: row.peak, offPeak: row.offPeak });
+    for (const [model, revisions] of schedules) {
+        revisions.sort((left, right) => (left.effectiveFrom ?? Number.NEGATIVE_INFINITY) - (right.effectiveFrom ?? Number.NEGATIVE_INFINITY));
+        const newest = revisions[revisions.length - 1];
+        models.set(model, { peak: newest.peak, offPeak: newest.offPeak, revisions });
+    }
     return { peakHours, models };
 }
+/**
+ * The rate revision in effect at one instant: the newest revision that took
+ * effect at or before it. Revisions are ascending, so the scan stops at the
+ * first future one. An instant before the earliest dated revision bills at that
+ * earliest revision — a model with only dated rows is never left unpriced.
+ */
+function ratesAt(revisions, time) {
+    let chosen = revisions[0];
+    for (let index = 1; index < revisions.length; index += 1) {
+        const revision = revisions[index];
+        if (revision.effectiveFrom === undefined || revision.effectiveFrom > time)
+            break;
+        chosen = revision;
+    }
+    return chosen;
+}
 /** Beijing is a fixed UTC+8 offset with no DST. */
 const BEIJING_OFFSET_MS = 8 * 3_600_000;
 /** Milliseconds in one day. */
@@ -130,6 +217,7 @@ export function beijingPartsOf(time) {
     const msOfDay = shifted - epochDay * DAY_MS;
     const civil = civilDateOf(epochDay);
     return {
+        time,
         hour: Math.floor(msOfDay / 3_600_000),
         // 1970-01-01 was a Thursday (4).
         weekday: ((epochDay + 4) % 7 + 7) % 7,
@@ -189,7 +277,8 @@ export function isPeak(billing, now) {
 /**
  * Price one event at the official per-model rates, applying the peak/off-peak
  * table by its Beijing-time hour and weekday (peak windows apply Monday–Friday
- * only; weekends are off-peak). Each `assistant/message` event with usage
+ * only; weekends are off-peak) and the rate revision in effect at its own
+ * timestamp. Each `assistant/message` event with usage
  * contributes cache-hit input, cache-miss input (uncached input plus cache
  * writes), and output (reasoning included) tokens at the rate of its own
  * timestamp; a model with usage but no pricing row contributes nothing.
@@ -222,8 +311,10 @@ export function priceEventAt(parts, event, billing, names) {
 }
 /**
  * Price one provider-reported usage sample for one model at the rates of the
- * sample's own Beijing-time hour and weekday. `undefined` when the model has
- * no pricing row.
+ * sample's own Beijing-time hour and weekday — the peak or off-peak price of
+ * the rate revision in effect at the sample's own timestamp (a re-priced series
+ * bills its history at the rates that applied then). `undefined` when the model
+ * has no pricing row.
  * @param parts - the sample's Beijing-time view.
  * @param usage - the reported token buckets.
  * @param model - the wire model id the sample belongs to.
@@ -236,7 +327,8 @@ export function priceUsage(parts, usage, model, billing, names) {
     if (pricing === undefined)
         return undefined;
     const peak = isPeakParts(billing, parts.hour, parts.weekday);
-    const price = peak ? pricing.peak : pricing.offPeak;
+    const revision = ratesAt(pricing.revisions, parts.time);
+    const price = peak ? revision.peak : revision.offPeak;
     const hit = usage.cacheReadTokens ?? 0;
     const miss = usage.inputTokens + (usage.cacheWriteTokens ?? 0);
     const output = usage.outputTokens;

package/lib/types/index.d.ts

@@ -24,8 +24,8 @@ import type { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
 import type { BillingConfig } from './billing.ts';
 export { DeepSeekBalanceGateway, fetchDeepSeekBalance, parseDeepSeekBalance } from './balance.ts';
-export { addEventContribution, applyBillingEvent, beijingDayKey, BillingFolder, computeSessionSpend, computeSessionTurnSpends, computeTodaySpend, computeTurnSpend, DEFAULT_MODEL_PRICING, DEFAULT_PEAK_HOURS, emptyBillingFoldState, emptyTodaySpend, forkBoundaryOf, isPeak, isSeededSession, mergeTodaySpend, negateSpend, priceEvent, priceUsage, resolveBilling, SessionTurnSpendFolder, SpendAccumulator, subtractSpend, } from './billing.ts';
-export type { BillingConfig, BillingConfigModel, BillingEventContribution, BillingFoldSample, BillingFoldState, DeepSeekModelPricing, DeepSeekTokenPrice, PeakHourWindow, ResolvedBilling, } from './billing.ts';
+export { addEventContribution, applyBillingEvent, beijingDayKey, BillingFolder, computeSessionSpend, computeSessionTurnSpends, computeTodaySpend, computeTurnSpend, DEFAULT_MODEL_PRICING, DEFAULT_PEAK_HOURS, emptyBillingFoldState, emptyTodaySpend, FLASH_SERIES_RATE_CHANGE_AT, forkBoundaryOf, isPeak, isSeededSession, mergeTodaySpend, negateSpend, priceEvent, priceUsage, resolveBilling, SessionTurnSpendFolder, SpendAccumulator, subtractSpend, V4_PRO_ROUTE_SWITCH_AT, } from './billing.ts';
+export type { BillingConfig, BillingConfigModel, BillingEventContribution, BillingFoldSample, BillingFoldState, DeepSeekModelPricing, DeepSeekRateRevision, DeepSeekTokenPrice, PeakHourWindow, ResolvedBilling, } from './billing.ts';
 export type * from './types.ts';
 export { BILLING_UNIT_KEY, billingTodaySpendDefinition, foldBillingUnit, foldOwnBilling } from './projection.ts';
 export type { BillingUnitFold, BillingUnitState } from './projection.ts';
@@ -54,7 +54,12 @@ export interface Config {
     baseURL?: string;
     /** Advisory display rows, in presentation order; defaults to V4 Flash, V4.1 Flash, V4 Pro, and V4 Flash Vision Exp. */
     models?: BillingModel[];
-    /** Pricing table and peak-hour windows; omission uses the published defaults. Peak windows apply weekdays (Monday–Friday) only; weekends are always off-peak. */
+    /**
+     * Pricing table and peak-hour windows; omission uses the published defaults
+     * (including the V4 Flash series re-pricing effective 2026-09-10 12:00
+     * Beijing). Peak windows apply weekdays (Monday–Friday) only; weekends are
+     * always off-peak.
+     */
     billing?: BillingConfig;
 }
 export declare const Config: z<Config>;

package/lib/types/index.js

@@ -29,7 +29,7 @@ import { computeSessionSpend, computeTurnSpend, DEFAULT_MODEL_PRICING, DEFAULT_P
 import { billingTodaySpendDefinition } from "./projection.js";
 import { liveSessionEvents, persistenceInspect, TodaySpendCache, TodaySpendScanner } from "./today-spend.js";
 export { DeepSeekBalanceGateway, fetchDeepSeekBalance, parseDeepSeekBalance } from "./balance.js";
-export { addEventContribution, applyBillingEvent, beijingDayKey, BillingFolder, computeSessionSpend, computeSessionTurnSpends, computeTodaySpend, computeTurnSpend, DEFAULT_MODEL_PRICING, DEFAULT_PEAK_HOURS, emptyBillingFoldState, emptyTodaySpend, forkBoundaryOf, isPeak, isSeededSession, mergeTodaySpend, negateSpend, priceEvent, priceUsage, resolveBilling, SessionTurnSpendFolder, SpendAccumulator, subtractSpend, } from "./billing.js";
+export { addEventContribution, applyBillingEvent, beijingDayKey, BillingFolder, computeSessionSpend, computeSessionTurnSpends, computeTodaySpend, computeTurnSpend, DEFAULT_MODEL_PRICING, DEFAULT_PEAK_HOURS, emptyBillingFoldState, emptyTodaySpend, FLASH_SERIES_RATE_CHANGE_AT, forkBoundaryOf, isPeak, isSeededSession, mergeTodaySpend, negateSpend, priceEvent, priceUsage, resolveBilling, SessionTurnSpendFolder, SpendAccumulator, subtractSpend, V4_PRO_ROUTE_SWITCH_AT, } from "./billing.js";
 export { BILLING_UNIT_KEY, billingTodaySpendDefinition, foldBillingUnit, foldOwnBilling } from "./projection.js";
 export { foldSessionTitle, liveSessionEvents, persistenceInspect, persistenceListSnapshots, TodaySpendCache, TodaySpendScanner } from "./today-spend.js";
 export const name = 'llm-billing';
@@ -37,7 +37,15 @@ const DEFAULT_API_KEY_ENV = 'DEEPSEEK_API_KEY';
 const BASE_URL_ENV = 'DEEPSEEK_BASE_URL';
 /** Public API default; deployments may point elsewhere via $DEEPSEEK_BASE_URL. */
 export const PUBLIC_BASE_URL = 'https://api.deepseek.com';
+/**
+ * Advisory display rows mirroring the DSH `llm-deepseek` catalog (V4.1 Flash
+ * first, its current default route), plus the MiMo-V2.5 series. The retired
+ * preview id `deepseek-v4.1-flash-expires-on-0910` stays so the logs that used
+ * it keep a readable label; rows never restrict which models are priced — the
+ * pricing table does.
+ */
 const DEFAULT_MODELS = [
+    { id: 'deepseek-flash', name: 'DeepSeek-V41-Flash' },
     { id: 'deepseek-v4-flash', name: 'DeepSeek-V4-Flash' },
     { id: 'deepseek-v4.1-flash-expires-on-0910', name: 'DeepSeek-V4.1-Flash' },
     { id: 'deepseek-v4-pro', name: 'DeepSeek-V4-Pro' },
@@ -54,17 +62,22 @@ const tokenPrice = z.object({
     cacheMissInput: z.number().min(0),
     output: z.number().min(0),
 });
+const billingRateRow = z.object({
+    model: z.string().required(),
+    peak: tokenPrice,
+    offPeak: tokenPrice,
+    // Several rows may share one model: each is a rate revision, and samples are
+    // priced by the revision in effect at their own timestamp (epoch ms,
+    // inclusive).
+    effectiveFrom: z.number().min(0),
+});
 const billingConfig = z.object({
     // Copies of the readonly published tables, taken once at module load.
     peakHours: z.array(z.object({
         start: z.number().step(1).min(0).max(23),
         end: z.number().step(1).min(0).max(24),
     })).default([...DEFAULT_PEAK_HOURS]),
-    models: z.array(z.object({
-        model: z.string().required(),
-        peak: tokenPrice,
-        offPeak: tokenPrice,
-    })).default([...DEFAULT_MODEL_PRICING]),
+    models: z.array(billingRateRow).default([...DEFAULT_MODEL_PRICING]),
 });
 export const Config = z.object({
     apiKeyEnv: z.string().role('credential-ref').default(DEFAULT_API_KEY_ENV),

package/lib/types/projection.d.ts

@@ -48,13 +48,15 @@ export type BillingUnitDefinition = Omit<ProjectionDefinition<'billingTodaySpend
     wire: NonNullable<ProjectionDefinition<'billingTodaySpend', BillingUnitState>['wire']>;
 };
 /**
- * Build the `billingTodaySpend` unit for one resolved pricing table. The
- * pricing closure is fixed at registration; a pricing-table change therefore
- * prices only events folded after the change (historical spend keeps its
- * historical rates), unlike the events-scan paths which re-price the whole
- * log. Bump {@link ProjectionDefinition.stateVersion} whenever the state
- * shape or fold semantics change, so persisted checkpoint rows are discarded
- * instead of folded forward.
+ * Build the `billingTodaySpend` unit for one resolved pricing table. Published
+ * rate revisions travel inside the closure and are resolved per sample
+ * timestamp, so a re-priced series bills its own history correctly however late
+ * a log is folded; only a configuration change (editing `billing.models`) is
+ * fixed at registration, and it re-prices just the events folded afterwards
+ * (the events-scan paths re-price the whole log). Bump
+ * {@link ProjectionDefinition.stateVersion} whenever the state shape or fold
+ * semantics change, so persisted checkpoint rows are discarded instead of
+ * folded forward.
  * @param billing - resolved pricing with peak-hour windows.
  * @param catalog - model display rows, in presentation order.
  * @returns the unit definition to register on `ctx.sessionProjections`.

package/lib/types/projection.js

@@ -51,13 +51,15 @@ const billingUnitSchema = z.object({
     }).strict().nullable(),
 }).strict();
 /**
- * Build the `billingTodaySpend` unit for one resolved pricing table. The
- * pricing closure is fixed at registration; a pricing-table change therefore
- * prices only events folded after the change (historical spend keeps its
- * historical rates), unlike the events-scan paths which re-price the whole
- * log. Bump {@link ProjectionDefinition.stateVersion} whenever the state
- * shape or fold semantics change, so persisted checkpoint rows are discarded
- * instead of folded forward.
+ * Build the `billingTodaySpend` unit for one resolved pricing table. Published
+ * rate revisions travel inside the closure and are resolved per sample
+ * timestamp, so a re-priced series bills its own history correctly however late
+ * a log is folded; only a configuration change (editing `billing.models`) is
+ * fixed at registration, and it re-prices just the events folded afterwards
+ * (the events-scan paths re-price the whole log). Bump
+ * {@link ProjectionDefinition.stateVersion} whenever the state shape or fold
+ * semantics change, so persisted checkpoint rows are discarded instead of
+ * folded forward.
  * @param billing - resolved pricing with peak-hour windows.
  * @param catalog - model display rows, in presentation order.
  * @returns the unit definition to register on `ctx.sessionProjections`.
@@ -66,11 +68,13 @@ export function billingTodaySpendDefinition(billing, catalog) {
     const names = new Map(catalog.map(model => [model.id, model.name]));
     return {
         key: BILLING_UNIT_KEY,
-        // v3: DSH-aligned attempt pricing (assistant/attempt samples, same-step
-        // replacement, `llm/retry-started` closes the slot) on top of v2's
-        // boundary-aware fold and whole-session total; older checkpoint rows are
-        // discarded and refolded.
-        stateVersion: 3,
+        // v4: rate revisions resolved per sample timestamp (the V4 Flash series is
+        // re-priced from 2026-09-10 12:00 Beijing), on top of v3's DSH-aligned
+        // attempt pricing, v2's boundary-aware fold, and the whole-session total.
+        // A row checkpointed by the previous version priced every sample at one
+        // flat pair of rates, so rows folded after the re-pricing instant would
+        // keep the superseded rates: bumping discards them and refolds.
+        stateVersion: 4,
         stateSchema: billingUnitSchema,
         init: (_header, inheritedEventCount) => emptyBillingFoldState(Number(inheritedEventCount ?? 0)),
         apply: (state, event) => applyBillingEvent(state, event, billing, names),

package/lib/types/types.d.ts

@@ -7,8 +7,12 @@
  * and weekday, with peak windows Monday–Friday 09:00–12:00 / 14:00–18:00 and
  * weekends always off-peak; cache-hit input, cache-miss input (including
  * cache writes), and output (including reasoning) are billed separately at
- * per-1M-token rates. The published table prices the DeepSeek V4 rows and
- * the MiMo-V2.5 series (flat rate, no peak/off-peak distinction).
+ * per-1M-token rates, taking the rate revision in effect at that same instant
+ * (the flash series was re-priced from 2026-09-10 12:00 Beijing, its earlier
+ * samples keeping the superseded rates, and V4 Pro follows the V4.1 Flash
+ * rates from its announced route switch on 2026-09-14 12:00 Beijing). The
+ * published table prices the DeepSeek V4 rows and the MiMo-V2.5 series (flat
+ * rate, no peak/off-peak distinction).
  * @module @rayadesu/dsh-llm-billing/types
  */
 import type { SessionId } from '@deepseek-ai/dsh-session';

package/lib/types/types.js

@@ -7,8 +7,12 @@
  * and weekday, with peak windows Monday–Friday 09:00–12:00 / 14:00–18:00 and
  * weekends always off-peak; cache-hit input, cache-miss input (including
  * cache writes), and output (including reasoning) are billed separately at
- * per-1M-token rates. The published table prices the DeepSeek V4 rows and
- * the MiMo-V2.5 series (flat rate, no peak/off-peak distinction).
+ * per-1M-token rates, taking the rate revision in effect at that same instant
+ * (the flash series was re-priced from 2026-09-10 12:00 Beijing, its earlier
+ * samples keeping the superseded rates, and V4 Pro follows the V4.1 Flash
+ * rates from its announced route switch on 2026-09-14 12:00 Beijing). The
+ * published table prices the DeepSeek V4 rows and the MiMo-V2.5 series (flat
+ * rate, no peak/off-peak distinction).
  * @module @rayadesu/dsh-llm-billing/types
  */
 export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rayadesu/dsh-llm-billing",
   "description": "Standalone DeepSeek account-balance and session-spend provider exposed through the billing Remote",
-  "version": "0.3.9",
+  "version": "0.3.11",
   "publishConfig": {
     "access": "public"
   },