@chenmiao8563/dsh-token-ledger 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -8,6 +8,63 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 Nothing yet.
 
+## [0.2.0] - 2026-09-10
+
+### Added
+
+- **A settings page.** The browser half registers a `settings.section`, so the
+  ledger appears in the settings sidebar beside every other section. It shows:
+  - range totals for **this month**, **this year** and the **last 7 days**, each
+    with total tokens, cache hit rate and call count, plus the bucket breakdown;
+  - **today**, live, which moves as steps complete;
+  - a **usage calendar** switchable between year, month and week, where the week
+    view is a bar chart rather than a heatmap;
+  - the per-model breakdown with its own cache hit rates.
+- `lib/overview.js`, a pure function from a ledger snapshot to the payload the
+  page renders, and `lib/route.js`, the read-only
+  `GET /api/token-ledger/summary` route that serves it.
+- The browser half is hand-written against the client's module loader and
+  requires nothing but `react`, so the package still installs with no build step.
+
+### Changed
+
+- The overview is served over an HTTP route rather than a settings namespace.
+  A namespace would need a schema — a real dependency — and would rewrite
+  `settings.yaml` on every debounce with data that is derived and reproducible.
+  The ledger file remains the only store of record.
+
+## [0.1.1] - 2026-09-10
+
+Both fixes come from mounting the plugin in a real DSH host, which is the only
+place either defect was observable. Neither was reachable from the test suite,
+so both now have regression tests.
+
+### Fixed
+
+- **`/tokens` never registered.** The command definition passed `input` as a
+  bare string, and the command registry requires an object carrying a non-empty
+  `hint`. The resulting `TypeError` was thrown during mount, which also aborted
+  the rest of `apply()` — so the flush-on-dispose effect was never installed
+  either.
+- **Backfill under-counted forked sessions.** The inherited boundary was applied
+  as a raw index, but a stored session can arrive in the compact row form where
+  several logical events share one record and the declared count overshoots the
+  array length by an order of magnitude. Applying it skipped those sessions
+  entirely, which under-counted a real 139-session home by hundreds of millions
+  of tokens. The boundary is now located by the `session/end-seed` marker, which
+  is present and equivalent in both coordinate spaces, with the declared count
+  as a fallback that is refused when it cannot index the array it came with. A
+  fork with no usable boundary is folded whole and warned about, so the error
+  direction is over-counting rather than silent loss.
+
+### Changed
+
+- The on-disk ledger format is now version 2. A ledger written by 0.1.0 is
+  ignored on start rather than trusted, because its cursors would otherwise
+  mark every session as consumed and preserve the mis-counted totals forever.
+  The ledger rebuilds itself from the session logs, so the only effect is that
+  the first start after upgrading does the backfill again.
+
 ## [0.1.0] - 2026-09-10
 
 ### Added
@@ -31,5 +88,7 @@ Nothing yet.
 - Zero runtime dependencies, zero peer dependencies and no install scripts, so
   the package installs without a build step.
 
-[Unreleased]: https://github.com/chenmiao8563/dsh-token-ledger/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/chenmiao8563/dsh-token-ledger/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/chenmiao8563/dsh-token-ledger/compare/v0.1.1...v0.2.0
+[0.1.1]: https://github.com/chenmiao8563/dsh-token-ledger/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/chenmiao8563/dsh-token-ledger/releases/tag/v0.1.0

package/README.md

@@ -144,6 +144,33 @@ audit useless. The ledger's own `updatedAt` settles it:
          (1 calls, 5100 tokens not yet flushed)
 ```
 
+## Settings page
+
+The browser half adds a **Token ledger** section to the settings sidebar:
+
+- **Range totals** for this month, this year and the last 7 days — total tokens,
+  cache hit rate, call count, and the bucket breakdown behind them. The cache hit
+  rate is `cacheRead / (cacheRead + uncachedInput)`: the share of input the prompt
+  cache absorbed, so a route with no caching reads 0% rather than undefined.
+- **Today, live** — today's tokens, hit rate and calls, which move as steps
+  complete.
+- **A usage calendar** switchable between year, month and week. Year and month are
+  heatmaps; the week view is a bar chart. Heat levels are relative to the busiest
+  day in the window and square-rooted, so one huge day cannot flatten the rest.
+- **Per model** totals, each with its own hit rate.
+
+The page reads one read-only route, `GET /api/token-ledger/summary`, and polls it
+every 15 seconds. The route refuses a non-loopback peer, so it stays private even
+if the web server is bound to `0.0.0.0`.
+
+It needs a profile with a web server (the `web` or `desktop` profile). Without one,
+`/tokens` and the CLI still work, and the section says so instead of failing.
+
+The overview is deliberately **not** published through a settings namespace. That
+would need a schema — a real dependency, and this package has none — and would
+rewrite `settings.yaml` on every debounce with data that is derived and
+reproducible. The ledger file stays the only store of record.
+
 ## Configuration
 
 Override the composition entry by its `id`:
@@ -186,7 +213,8 @@ The ledger file is left alone on purpose — delete
 ## Development
 
 ```bash
-npm test            # 49 tests, no dependencies to install
+npm install         # devDependencies only: react, react-dom, and the slot registry DSH runs
+npm test            # 106 tests
 npm run verify      # packaging invariants (dependency-free, no install scripts, no bare imports)
 ```
 
@@ -194,6 +222,15 @@ npm run verify      # packaging invariants (dependency-free, no install scripts,
 spawning a child process per test file is blocked, use
 `npm run test:single-process`.
 
+The devDependencies are **test-only**. They are never installed for a consumer:
+the package ships with no dependencies, no peer dependencies and no install
+scripts, and `pnpm` does not install a dependency's devDependencies. They exist
+so the browser half can be checked against the real thing — React renders it, so
+a hook-order or DOM-prop mistake fails instead of passing silently, and
+`@deepseek-ai/dsh-client-ui-slots` validates the registration against the very
+registry that DSH runs. Without them installed the affected tests skip with a
+stated reason, so `npm test` still works from a fresh clone with no network.
+
 See [docs/VERIFICATION.md](docs/VERIFICATION.md) for what was actually verified
 and how, including the evidence behind the fork rule.
 

package/README.zh.md

@@ -136,6 +136,29 @@ dsh-token-ledger export  [选项]       导出 CSV 与 JSON
          (1 calls, 5100 tokens not yet flushed)
 ```
 
+## 设置页
+
+浏览器端会在设置侧边栏注册一个 **用量账本** 分区：
+
+- **区间总计**：本月 / 本年 / 近 7 天三档可切换，每档显示 Token 总计、缓存命中率、
+  调用次数，以及背后的四桶明细。缓存命中率定义为
+  `缓存读入 / (缓存读入 + 未命中输入)`——即输入中被缓存吸收的比例，因此完全不缓存的
+  路由读数是 0%，而不是空白。
+- **今日实时**：今天的 Token、命中率与调用次数，随每一步完成而变动。
+- **用量热力图**：年 / 月 / 一周三档可切换；年和月是热力图，切到一周改为柱状图。
+  热力档位相对窗口内最忙的一天取平方根，避免某一天特别大把其余全部压成最淡档。
+- **按模型**：各模型的用量与各自命中率。
+
+页面只读一个路由 `GET /api/token-ledger/summary`，每 15 秒轮询一次。
+该路由会拒绝非回环来源，因此即使 web 服务器绑定到 `0.0.0.0` 也不会外泄。
+
+它需要带 web 服务器的 profile（`web` 或 `desktop`）。没有的话 `/tokens` 与 CLI
+照常可用，分区会明确说明而不是直接失败。
+
+概览**刻意不**通过设置命名空间下发：那需要 schema（一个真实依赖，而本包零依赖），
+而且每次防抖都会用可推导、可重放的数据重写一遍 `settings.yaml`。
+账本文件始终是唯一的记录来源。
+
 ## 配置
 
 按 `id` 覆盖组合条目：
@@ -172,13 +195,20 @@ dsh plugin --profile web remove @chenmiao8563/dsh-token-ledger
 ## 开发
 
 ```bash
-npm test            # 49 个测试，无需安装任何依赖
+npm install         # 两个 devDependency：react 与 react-dom，供渲染测试使用
+npm test            # 96 个测试
 npm run verify      # 打包不变式（零依赖、无安装脚本、无裸模块说明符）
 ```
 
 `npm test` 使用 Node 内置测试运行器。在禁止逐文件 spawn 子进程的受限环境里，
 改用 `npm run test:single-process`。
 
+React **只是 devDependency**，消费者永远不会安装它：本包不带任何依赖、任何 peer
+依赖、任何安装脚本，而 pnpm 不会为依赖安装其 devDependencies。它在这里的作用是让
+浏览器端能用**真库**渲染并断言——这能抓到替身抓不到的东西：hook 顺序违规与非法
+DOM 属性，React 会报出来，而手写的 `createElement` 会默默接受。没装它时这些渲染
+测试会带明确原因**跳过而不是失败**，所以全新克隆、无网络也能跑 `npm test`。
+
 实际验证了什么、怎么验证的（包括 fork 规则背后的证据）见
 [docs/VERIFICATION.md](docs/VERIFICATION.md)。
 

package/docs/VERIFICATION.md

@@ -139,6 +139,49 @@ this similarity gate, which runs at publish time. The scoped name was
 re-verified end to end as shown above; the CLI command and Cordis entry id are
 unchanged.
 
+### Install from the npm registry, isolated
+
+The published artifact was installed the way a stranger would install it, into a
+disposable `DSH_HOME`:
+
+```
+$ DSH_HOME=<tmp>/home <dsh-desktop-cli> plugin --profile web add @chenmiao8563/dsh-token-ledger
+dsh: initialized profile web at <tmp>/home/profiles/web
+Progress: resolved 1, reused 0, downloaded 0, added 0
+dependencies:
++ @chenmiao8563/dsh-token-ledger ^0.1.0
+Packages: +1
+Progress: resolved 1, reused 0, downloaded 1, added 1, done
+Done in 2.7s using pnpm v11.8.0
+```
+
+The lockfile records a real registry resolution with its integrity hash and the
+declared engine range:
+
+```
+'@chenmiao8563/dsh-token-ledger@0.1.0':
+  resolution: {integrity: sha512-yApGruS1Hcyq0oIOq8t6Y8gAJFefAoiHLzDsvPsecND6+DIj878x8YtQ5Ggz+PVYL9yTvaPAgIVcOhyBNvPGnw==}
+  engines: {node: '>=22.15.0'}
+  hasBin: true
+```
+
+The reconciler added it to the bundle stack, and `pnpm-workspace.yaml` was left
+untouched — **no `allowBuilds` entry was needed**, which is the installability
+claim this document exists to check:
+
+```json
+"dsh": { "profile": { "bundles": [
+  "@deepseek-ai/dsh-base",
+  "@deepseek-ai/dsh-web-app",
+  "@chenmiao8563/dsh-token-ledger"
+] } }
+```
+
+The packument itself took roughly two minutes to become readable after the first
+publish in the new scope — during that window `dist-tags` and the tarball were
+already live while `GET /@chenmiao8563%2Fdsh-token-ledger` still returned 404.
+That is registry propagation, not a failed publish.
+
 ### Note for whoever verifies this next
 
 On this machine the `dsh` shell shim hardcodes `DSH_HOME`, so exporting
@@ -151,18 +194,120 @@ $env:DSH_HOME = '<tmp>\home'
 & '<install>\DSH Desktop.exe' --expose-internals '<install>\resources\app.asar\lib\desktop-cli.js' plugin --profile web add <path>
 ```
 
+## Live host mount
+
+Version 0.1.0 was installed into a real desktop profile, the host was restarted,
+and the host log recorded the mount:
+
+```
+20:24:52 [I] [token-ledger] started a new ledger at <DSH_HOME>\token-ledger\ledger.json
+20:24:52 [E] [token-ledger] TypeError: command "tokens" input hint must be a string
+20:25:00 [I] [token-ledger] backfilled 139 stored session(s), 0 unreadable; total 790455336 tokens over 4518 calls
+```
+
+This step was worth doing precisely because it failed. Both defects it exposed
+were unreachable from the 49-test suite, and both are fixed in 0.1.1 with
+regression tests:
+
+| Defect | Evidence | Cause |
+| --- | --- | --- |
+| `/tokens` never registered | the `TypeError` above, and no `command/*` event when `/tokens` was typed | `input` was passed as a bare string; the registry requires `{ hint: string }`. The throw also aborted the rest of `apply()`, so the flush-on-dispose effect was never installed |
+| backfill under-counted forks | 4,518 calls / 790,455,336 tokens against the CLI's 6,901 / 1,205,685,663 on the same logs | the inherited boundary was applied as a raw index, but the row-form log packs several logical events per record, so the declared count overshot the array and skipped those sessions entirely |
+
+The diagnosis came from the ledger's own artifacts rather than from guesswork:
+the host log line above, and a cross-tabulation of the ledger's 65 recorded
+sessions against the 72 logs carrying a `session/end-seed` marker and the 29
+declaring a parent. The 61 sessions outside both sets turned out to be
+four-record logs with no usage at all, which is why they correctly have no entry.
+
+## Browser half (0.2.0)
+
+What is checked here and what is not, because the difference is large.
+
+**Checked by test.** `lib/overview.js` and `lib/route.js` are pure or near-pure
+and are tested directly: range boundaries, cache-hit-rate arithmetic, gap-filled
+series, the loopback and origin guard, method handling, and the 500-on-fault
+path. The browser half is loaded through a stand-in module loader with a
+stand-in React, which exercises the module wrapper, the registration contract,
+and the whole render tree — formatting, heat levels, week-bar slicing, view
+switching, and the empty, malformed and stale-data paths.
+`scripts/verify-package.mjs` additionally fails the build if the browser half
+requires anything the loader does not provide, if its module id stops matching
+the package name, if it stops compiling as a classic script, or if a declared
+client dependency is outside the client-half namespace.
+
+**Checked by reading DSH's own source, not by inference.** The contracts the
+browser half depends on were read out of the shipped bundles rather than copied
+from a third-party plugin:
+
+| Contract | Where it was read | Result |
+| --- | --- | --- |
+| The `settings.section` registration shape | the sections DSH ships — `dsh-client-ui-settings-models` (order 10), `-settings-plugins` (15) and `-ui-agent-preset` (20) — plus the shell in `-settings-general` that renders them via `renderSlot("settings.section", …, { only: active })` | identical field set; `locale` is optional, proven by `-settings-models` omitting it; the sidebar rows come from `id`, `order` and `label`, all of which this plugin supplies |
+| The client module format | every `@deepseek-ai/dsh-client-*/lib/client.js` | byte-identical wrapper: `window.__ModuleLoader__.load({ id, factory })` with `var module = { exports: {} }` and `exports.apply`/`exports.inject` |
+| When the factory runs | `dsh-client-modules` module docs | only registration happens at script execution; body side effects, styles included, run at materialization — which is why the stylesheet is installed inside `apply()` |
+| The `dsh.client` declaration | `parseDshClient` in `dsh-client-modules/lib/index.js` | `platform` must be a string and only `web` is loaded; `inject` and `external` are optional string arrays; `external` — not `inject` — is what orders the module graph |
+| What `dsh.client.inject` **contains** | the five `dsh.client` declarations DSH ships, two of them non-empty: `dsh-client-locale` and `dsh-client-ui-settings-general` | **package/entry ids, not service names.** A module's own exported `inject` is the separate service list. This plugin lists the two packages whose services it uses, which is the same convention, and an empty list is also legal (`dsh-client-connection` uses one) |
+| What `external` contains | the module-graph walk in `dsh-client-modules/lib/client.js`, which runs every entry through `stripClientSuffix` before resolving it | module specifiers for *other rows*. This plugin requires only `react`, which the loader provides and no row owns, so it declares none |
+| How `exports["./client"]` is located | `clientExportOf` in `dsh-client-modules/lib/index.js` | a plain string or an object with a string `default`; anything else throws. A plain string is used here, and `verify-package.mjs` pins it |
+| Whether a **scoped** package id survives | `stripClientSuffix` in `dsh-client-modules/lib/client.js` | it removes only a trailing `/client`, so `@chenmiao8563/dsh-token-ledger` passes through intact. DSH's own client packages are scoped too, so the transport already carries ids containing `/` |
+
+That reading corrected two real mistakes in the first draft of this half, both of
+which would have been a silent failure rather than an error:
+
+- `@deepseek-ai/dsh-client-ui-slots` was listed as a client dependency. It is a
+  pure core library (its manifest exports only `.`, and it declares no
+  `dsh.client`), so it is never a client module row.
+- The settings shell package was listed as `-ui-settings`, which holds the
+  namespace-scope service; the section slot is declared and rendered by
+  `-ui-settings-general`.
+
+**Checked under the real React.** `test/client-render.test.mjs` renders the
+presentation component with React 18.3.1 — the same major version DSH bundles —
+through `react-dom/server`, and asserts the actual markup: the range tabs and
+their active state, the totals, hit rate and call count for each range, today's
+block surviving a year-range selection, the year heat grid (one cell per day plus
+five legend swatches), the month grid (every day of March), the week bars (seven,
+with inline heights), bounded heat levels drawn from a five-entry palette,
+proportional model bars, and the loading, error, stale and empty states. It also
+captures `console.error` and `console.warn` and **fails if React complained at
+all**, which is what catches an invalid DOM prop or a hook-order violation — the
+class of defect a hand-rolled `createElement` accepts silently.
+
+React is a devDependency, so this runs in CI and under `prepublishOnly`. Without
+it installed the file skips with a stated reason rather than failing, which keeps
+`npm test` working from a fresh clone with no network.
+
+**Checked against the real slot registry.** `test/slot-registration.test.mjs`
+feeds the registration `apply` actually builds into
+`@deepseek-ai/dsh-client-ui-slots` — the registry DSH itself runs, pinned as a
+devDependency to `0.1.2-rc.1`, the exact version this DSH bundles (`latest` on
+npm is an older `0.0.1-rc.1`, so the version is pinned rather than ranged). It
+asserts that the registry accepts the entry, that `resolveSlotLabel` resolves the
+label thunk to a non-empty string — a label it could not resolve would render as
+a blank sidebar row — that the entry id does not collide with the three sections
+DSH ships, that a duplicate id is refused, that disposing retires the entry, and
+that registering into an undeclared slot is refused, which is why the plugin uses
+`slots.inject` rather than registering blind.
+
+**Not checked.** Whether the client module loader accepts the file, whether the
+shell renders the section, and how any of it looks. Nothing here executes
+`window.__ModuleLoader__` or mounts the component into a DOM: the module's shape
+is asserted to match every bundle DSH ships, and the registration is validated by
+the real registry, but no single process loads the plugin the way the browser
+does. The remaining risk is integration and visual — a first-run surprise, not a
+contractual one.
+
 ## Not verified
 
 Stated plainly, because a verification file that only lists successes is not
 useful:
 
-- **Live in-process mount inside a running DSH host.** The composition is proven
-  (`--dump-config`), and the plugin's behaviour against a Cordis stand-in is
-  covered by tests, but the packaged desktop CLI exposes no way to boot the
-  plugin tree without serving the GUI, so the plugin was not observed mounting
-  inside a real host process, and `/tokens` was not exercised in a live
-  conversation. The remaining risk is confined to the host's exact service
-  contract at mount time, not to the counting logic.
+- **`/tokens` end to end through the GUI.** The command now satisfies the
+  registry contract and is covered by a regression test, but the corrected build
+  has not yet been observed answering `/tokens` in a live conversation.
+- **Backfill parity with the CLI on a real host.** Both paths now share one
+  boundary function, and each is tested, but the backfill's numbers have not
+  been compared against a CLI rebuild on the same host after the 0.1.1 fix.
 - **Any DSH release other than `0.1.2-rc.1`.** The API surface used is stable
   across the `0.1.2` line by inspection, not by test.
 - **Non-Windows platforms.** The logic is platform-independent and CI runs

package/lib/cli.js

@@ -13,7 +13,7 @@ import { readdirSync, readFileSync, statSync } from 'node:fs'
 import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
-import { UsageLedger, inheritedCut } from './ledger.js'
+import { UsageLedger, inheritedCut, isForkSession } from './ledger.js'
 import { readSessionLog } from './session-log.js'
 import { ledgerPaths, loadLedger, saveLedger, writeFileAtomic } from './store.js'
 
@@ -195,14 +195,17 @@ export function rebuildFromLogs(sessionsDir, { onWarning = () => {} } = {}) {
     const header = records[0]?.type === 'session' ? records[0] : undefined
     const fallbackId = file.replace(/\\/g, '/').split('/').slice(-2)[0]
     const sessionId = String(header?.id ?? fallbackId)
-    const markerIndex = records.findIndex((record) => record.type === 'session/end-seed')
-    const isFork = header?.parentSession !== undefined && header?.parentSession !== null
-
-    let cut = 0
-    if (isFork) {
-      forks += 1
-      if (markerIndex >= 0) cut = markerIndex
-      else onWarning(`forked session ${sessionId} has no session/end-seed marker; folding it whole`)
+    const isFork = isForkSession(header)
+    if (isFork) forks += 1
+
+    // This file is the compact row form, so a stored `seq` is not an array
+    // index; the boundary is located structurally, by the marker. See
+    // inheritedCut for why the declared count cannot be trusted here.
+    const cut = inheritedCut({ header, events: records, inheritedEventCount: header?.seedLength })
+    if (isFork && cut === 0) {
+      onWarning(
+        `forked session ${sessionId} has no usable inheritance boundary; folding it whole, so its totals may include the parent prefix`,
+      )
     }
 
     // The newest event time lets the audit tell "the ledger is merely behind a