Token Accounting: Replay for Decisions, Projection for Display

Play first, then talk. Left gauge is replay measure()—compaction reads it. Right is UI projection projectedTokens—the status line shows it. A conversation advances: big tool output, compaction, model switch, new request. You'll see the gauges stay close most of the time, then openly diverge on the model switch—and look justified doing it.

Up front: the two numbers answer different questions. Compaction needs “how big would a request be right now”—accurate, may be expensive. The UI status line only needs occupancy for the user—cheap, durable, available immediately after reconnect; decimal precision doesn't matter. DSH simply builds separate roads and makes neither compromise.

The decision path is replay. Each ctx.tokenMeter.measure() call folds the durable log's current tail into an immutable snapshot: if the latest successful request's provider usage matches the current request envelope and isn't below its full heuristic anchor, use it as the anchor; surface (model-visible surface) changes after that are re-priced with signed deltas; with no reusable anchor, price the whole thing with a fixed heuristic.

The cost is plain: O(surface) per call—so only decision-makers like compaction call it at their own request boundary.

Source:docs/subsystems/token-meter.zh.md definitions of the two baseline kinds (usage anchor / estimated heuristic anchor).

The display path is projection. Ordinary durable session projection state with two last-writer-wins fields: pressureTokens—prompt-side size from the latest request report, input plus cache read/write, excluding output (usage-projection.ts lines 70–72); and contextWindow from the latest request/context log record. Numerator and denominator write separately—never one atomic observation.

pressureTokens alone is awkward: it only updates when a request reports usage, sits still during Turn streaming, and can't see compaction. Compaction replaces a big surface stretch but the status-line number doesn't move—users think compaction did nothing. So fold also carries a running surface total; what's published is the sample plus signed surface change after it. Source comments state the intent plainly: occupancy answers for the next request rather than the last one (usage-projection.ts lines 150–161 comments). Demo step 5 is that effect: compaction just hit disk, no new request yet, and the projection already dropped.

One timing detail: usage samples are stamped BEFORE the same event joins surface—so an assistant/message anchors the surface its own request saw, and the delta start doesn't skew.

The whole outward projection view is these 7 lines. The third spread is the lesson's punchline: pressureTokens + surfaceTokens - sampledSurfaceTokens—sample plus net surface change after sampling, floored with Math.max(0, …). If either source field is missing, that output simply doesn't appear.

  view: ({ contextWindow, pressureTokens, surfaceTokens, sampledSurfaceTokens }) => ({
    ...contextWindow === undefined ? {} : { contextWindow },
    ...pressureTokens === undefined ? {} : { pressureTokens },
    ...pressureTokens === undefined || sampledSurfaceTokens === undefined
      ? {}
      : { projectedTokens: Math.max(0, pressureTokens + surfaceTokens - sampledSurfaceTokens) },
  }),

Two edge cases fall out of this code. First, provider returns no usage: projection-side pressureTokens stays absent, spreads two and three never appear, UI shows no occupancy (Agent Note: show occupancy only when pressure and capacity are both known); decision side is unaffected—measure() falls back to an estimated heuristic anchor and still returns a number. Second, non-atomic occupancy divergence—the doc's defense already pops in demo step 6, from Agent Note lines 29–35, titled “Context occupancy is approximate, and that is the decision.”

Side by side, all three answer the same question: who uses the occupancy number, and who pays when it's wrong. Grok chose a forever-consistent coarse number; Claude Code patched display counting against double-count; DSH fully separates the two consumers and admits in docs that the display copy is approximate.