@chenmiao8563/dsh-token-ledger 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -8,6 +8,38 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 Nothing yet.
 
+## [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 +63,6 @@ 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.1.1...HEAD
+[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/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,43 @@ $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.
+
 ## 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

package/lib/index.js

@@ -22,7 +22,7 @@
  * @module dsh-token-ledger
  */
 
-import { UsageLedger, inheritedCut } from './ledger.js'
+import { UsageLedger, inheritedCut, isForkSession } from './ledger.js'
 import { ledgerPaths, loadLedger, saveLedger, writeFileAtomic } from './store.js'
 import { join } from 'node:path'
 
@@ -131,12 +131,22 @@ export function apply(ctx, config = {}) {
         const events = stored?.events
         if (!Array.isArray(events)) continue
         const meta = stored?.meta ?? header
-        ledger.adoptHistory({
-          sessionId: id,
+        // A fork's prefix belongs to its parent, which is counted separately.
+        // The boundary is located by the `session/end-seed` marker rather than
+        // by a raw count, because a count can be expressed in a different
+        // coordinate space than the array we were handed. See inheritedCut.
+        const inheritedEventCount = inheritedCut({
+          header: meta,
           events,
-          // Only a fork's prefix belongs to another session; see inheritedCut.
-          inheritedEventCount: inheritedCut(meta, stored?.inheritedEventCount ?? meta?.seedLength),
+          inheritedEventCount: stored?.inheritedEventCount ?? meta?.seedLength,
         })
+        if (isForkSession(meta) && inheritedEventCount === 0) {
+          log.warn(
+            '[token-ledger] forked session %s has no usable inheritance boundary; folding it whole, so its totals may include the parent prefix',
+            id,
+          )
+        }
+        ledger.adoptHistory({ sessionId: id, events, inheritedEventCount })
         sessions += 1
       } catch (error) {
         errors += 1
@@ -230,7 +240,9 @@ export function apply(ctx, config = {}) {
       commandCtx.commands.register({
         name: 'tokens',
         description: 'Show the cumulative token ledger (per day and per model)',
-        input: 'summary | export | json | path',
+        // `input` must be an object carrying a non-empty `hint` string; a bare
+        // string is rejected by the command registry with a TypeError.
+        input: { hint: 'summary | export | json | path' },
         handler: runCommand,
       })
     })

package/lib/ledger.js

@@ -36,8 +36,17 @@
  * @module dsh-token-ledger/ledger
  */
 
-/** Bumped whenever the folded state shape changes, so stale files are ignored. */
-export const LEDGER_VERSION = 1
+/**
+ * Bumped whenever the folded state shape **or the counting semantics** change.
+ *
+ * A stored ledger is a cache of a fold, and its per-session cursors claim those
+ * sessions are fully consumed. State written by a version that counted
+ * differently would therefore keep its wrong totals forever: the fixed version
+ * would skip every session as already consumed. Version 2 exists precisely
+ * because 0.1.0's boundary rule mis-counted forks, so its files must be
+ * discarded and rebuilt rather than trusted.
+ */
+export const LEDGER_VERSION = 2
 
 /** The four disjoint provider usage buckets, all defaulting to zero. */
 const BUCKET_KEYS = ['inputTokens', 'outputTokens', 'cacheReadTokens', 'cacheWriteTokens']
@@ -156,15 +165,24 @@ export function dateKeyOf(timeMs, now = new Date()) {
 }
 
 /**
- * Decide how much of a session's stored history is somebody else's.
+ * Whether a stored session header describes a fork.
+ *
+ * @param {object} [header] - a `SessionHeader`-shaped object.
+ * @returns {boolean} true when the session has a parent.
+ */
+export function isForkSession(header) {
+  return header?.parentSession !== undefined && header?.parentSession !== null
+}
+
+/**
+ * Decide how much of a session's event list belongs to another session.
  *
  * A session log can carry a prefix of already-recorded history. Two very
  * different situations produce one, and only one of them must be cut:
  *
  * - **Fork** (`header.parentSession` is set): the prefix is the *parent
  *   session's* history, and the parent is counted separately. Folding the
- *   prefix here would count those tokens twice, so it is cut at
- *   `inheritedEventCount`.
+ *   prefix here would count those tokens twice, so it is cut.
  * - **Resume** (no parent): the prefix is *this session's own* earlier history,
  *   stored once, with no other session to double count it against. Cutting it
  *   would lose tokens, so nothing is cut.
@@ -175,14 +193,42 @@ export function dateKeyOf(timeMs, now = new Date()) {
  * while for the non-forked logs carrying the same marker the prefix did not
  * reappear later in the file.
  *
- * @param {object} [header] - a `SessionHeader`-shaped object.
- * @param {number} [inheritedEventCount] - the cut storage reports for this session.
+ * ## Why the boundary is located by the marker
+ *
+ * The obvious implementation — skip `inheritedEventCount` leading entries — is
+ * wrong, and shipping it under-counted a real 139-session home by hundreds of
+ * millions of tokens. A stored session reaches this fold in one of two
+ * coordinate spaces:
+ *
+ * - the **logical** event list, where positions match `seq` and
+ *   `inheritedEventCount` is directly meaningful;
+ * - the **compact row** form the log is stored in, where several logical events
+ *   share one record, so the declared count overshoots the array length and
+ *   applying it skipped the entire session.
+ *
+ * `session/end-seed` is present in both forms and marks the same boundary, so
+ * it is authoritative. The declared count is only a fallback, and only when it
+ * is a plausible index into the list we were actually handed: a count that
+ * reaches past the end proves it is not in this list's space and is refused
+ * rather than trusted. Callers are expected to warn when a fork yields a cut of
+ * zero, because that over-counts rather than silently losing data.
+ *
+ * @param {object} input - what is known about the session's stored content.
+ * @param {object} [input.header] - stored header/meta carrying `parentSession`.
+ * @param {object[]} [input.events] - the stored event list about to be folded.
+ * @param {number} [input.inheritedEventCount] - the cut storage declares.
  * @returns {number} the number of leading events to skip.
  */
-export function inheritedCut(header, inheritedEventCount) {
-  const isFork = header?.parentSession !== undefined && header?.parentSession !== null
-  if (!isFork) return 0
-  return typeof inheritedEventCount === 'number' && inheritedEventCount > 0 ? inheritedEventCount : 0
+export function inheritedCut({ header, events, inheritedEventCount } = {}) {
+  if (!isForkSession(header)) return 0
+  const list = Array.isArray(events) ? events : []
+  const marker = list.findIndex((event) => event?.type === 'session/end-seed')
+  if (marker >= 0) return marker + 1
+  const declared =
+    typeof inheritedEventCount === 'number' && Number.isFinite(inheritedEventCount) && inheritedEventCount > 0
+      ? Math.floor(inheritedEventCount)
+      : 0
+  return declared > 0 && declared < list.length ? declared : 0
 }
 
 /**
@@ -514,13 +560,18 @@ export class UsageLedger {
    * Merge a snapshot back in. Returns false for missing or incompatible state,
    * which callers treat as "start fresh" rather than as an error.
    *
+   * The postcondition of a `false` return is an empty ledger, never a partially
+   * loaded one: the state is cleared before the snapshot is judged, so a
+   * rejected file cannot leave stale totals or cursors behind for the next
+   * caller to mistake for real data.
+   *
    * @param {unknown} snapshot - a previously produced snapshot.
    * @returns {boolean} whether the snapshot was usable.
    */
   restore(snapshot) {
+    this.reset()
     if (snapshot === null || typeof snapshot !== 'object') return false
     if (snapshot.version !== LEDGER_VERSION) return false
-    this.reset()
 
     const absorb = (raw) => countersFromUsage(raw)
     const totals = absorb(snapshot.totals)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chenmiao8563/dsh-token-ledger",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Transparent, auditable token accounting for DeepSeek Harness: a restart-safe ledger over the durable session log, plus a CLI that recomputes it from raw logs and diffs the result.",
   "keywords": [
     "dsh",