@rayadesu/dsh-llm-billing 0.2.2 → 0.2.4

package/lib/types/billing.js

@@ -4,11 +4,12 @@
  * Remote gateway stays transport-free and the whole spend is testable without
  * a key.
  *
- * The per-event pricing lives in {@link priceEvent}, the one shared fold
- * primitive: the events-scan paths ({@link computeSessionSpend},
- * {@link computeTodaySpend}) and the session-projection unit
- * (`billingTodaySpend` in projection.ts) all fold the same contribution, so a
- * pricing-table change cannot drift one path from the others.
+ * The per-event pricing lives in {@link priceEvent} and the fold in the
+ * {@link SpendAccumulator}: the events-scan paths ({@link computeSessionSpend},
+ * {@link computeTodaySpend}), the session-projection unit (`billingTodaySpend`
+ * in projection.ts), and the scanner's single-pass events path all price
+ * through the same primitives, so a pricing-table change cannot drift one path
+ * from the others.
  * @module @rayadesu/dsh-llm-billing/billing
  */
 /**
@@ -61,20 +62,29 @@ export function resolveBilling(config) {
         models.set(row.model, { peak: row.peak, offPeak: row.offPeak });
     return { peakHours, models };
 }
-/** The Beijing (Asia/Shanghai, UTC+8, no DST) hour of a timestamp. */
-function beijingHour(now) {
-    return new Date(now.getTime() + 8 * 3_600_000).getUTCHours();
-}
 /**
- * The Beijing (Asia/Shanghai, UTC+8, no DST) weekday of a timestamp, as
- * `getUTCDay()`: `0` is Sunday, `6` is Saturday.
+ * Derive the Beijing hour, weekday, and calendar-day key of one timestamp from
+ * a single shifted `Date` — every timezone-sensitive read shares this one
+ * implementation, so the pieces cannot drift apart.
+ * @param time - epoch milliseconds.
  */
-function beijingWeekday(now) {
-    return new Date(now.getTime() + 8 * 3_600_000).getUTCDay();
+function beijingParts(time) {
+    const shifted = new Date(time + 8 * 3_600_000);
+    return {
+        hour: shifted.getUTCHours(),
+        weekday: shifted.getUTCDay(),
+        dayKey: shifted.toISOString().slice(0, 10),
+    };
 }
 /** The Beijing (Asia/Shanghai, UTC+8, no DST) calendar-day key of a timestamp. */
 export function beijingDayKey(now) {
-    return new Date(now.getTime() + 8 * 3_600_000).toISOString().slice(0, 10);
+    return beijingParts(now.getTime()).dayKey;
+}
+/** Whether a Beijing (hour, weekday) pair falls inside any peak-hour window. */
+function isPeakParts(billing, hour, weekday) {
+    if (weekday === 0 || weekday === 6)
+        return false;
+    return billing.peakHours.some(({ start, end }) => hour >= start && hour < end);
 }
 /**
  * Whether a timestamp falls inside any peak-hour window (Beijing time,
@@ -85,11 +95,8 @@ export function beijingDayKey(now) {
  * @returns true during a weekday peak hour.
  */
 export function isPeak(billing, now) {
-    const weekday = beijingWeekday(now);
-    if (weekday === 0 || weekday === 6)
-        return false;
-    const hour = beijingHour(now);
-    return billing.peakHours.some(({ start, end }) => hour >= start && hour < end);
+    const { hour, weekday } = beijingParts(now.getTime());
+    return isPeakParts(billing, hour, weekday);
 }
 /**
  * Price one event at the official per-model rates, applying the peak/off-peak
@@ -114,8 +121,8 @@ export function priceEvent(event, billing, names) {
     const pricing = billing.models.get(model);
     if (pricing === undefined)
         return undefined;
-    const time = new Date(event.time);
-    const peak = isPeak(billing, time);
+    const { hour, weekday, dayKey } = beijingParts(event.time);
+    const peak = isPeakParts(billing, hour, weekday);
     const price = peak ? pricing.peak : pricing.offPeak;
     const hit = reported.cacheReadTokens ?? 0;
     const miss = reported.inputTokens + (reported.cacheWriteTokens ?? 0);
@@ -125,7 +132,7 @@ export function priceEvent(event, billing, names) {
     const outputCost = (output * price.output) / 1_000_000;
     const cost = hitCost + missCost + outputCost;
     return {
-        dayKey: beijingDayKey(time),
+        dayKey,
         model,
         displayName: names.get(model) ?? model,
         cost,
@@ -159,6 +166,45 @@ function contributionModel(priced) {
         outputCost: priced.outputCost,
     };
 }
+/** Sum two model rows of the same model (pure). */
+function mergeModelRows(left, right) {
+    return {
+        model: left.model,
+        displayName: left.displayName,
+        cost: left.cost + right.cost,
+        peakCost: left.peakCost + right.peakCost,
+        offPeakCost: left.offPeakCost + right.offPeakCost,
+        cacheHitInputTokens: left.cacheHitInputTokens + right.cacheHitInputTokens,
+        cacheMissInputTokens: left.cacheMissInputTokens + right.cacheMissInputTokens,
+        outputTokens: left.outputTokens + right.outputTokens,
+        cacheHitInputCost: left.cacheHitInputCost + right.cacheHitInputCost,
+        cacheMissInputCost: left.cacheMissInputCost + right.cacheMissInputCost,
+        outputCost: left.outputCost + right.outputCost,
+    };
+}
+/**
+ * Mutable model-row accumulator behind every spend fold. Rows keep first-seen
+ * model order — the same shape a pure `addEventContribution` chain produces —
+ * so the single-pass scan path and the pure public paths cannot diverge. One
+ * `Map` lookup per contribution instead of a per-event array copy: the huge
+ * event-log folds allocate one row object per model, not one intermediate
+ * array per event.
+ */
+export class SpendAccumulator {
+    rows = new Map();
+    total = 0;
+    /** Add one priced contribution. */
+    add(priced) {
+        const row = contributionModel(priced);
+        const existing = this.rows.get(priced.model);
+        this.rows.set(priced.model, existing === undefined ? row : mergeModelRows(existing, row));
+        this.total += priced.cost;
+    }
+    /** The folded spend; the accumulator stays usable afterwards. */
+    finish() {
+        return { total: this.total, models: [...this.rows.values()] };
+    }
+}
 /**
  * Merge one priced event's contribution into an accumulator spend (pure:
  * returns a new spend, never mutates its input).
@@ -167,22 +213,10 @@ function contributionModel(priced) {
  * @returns the merged spend.
  */
 export function addEventContribution(spend, priced) {
-    const rows = spend.models.map(row => row.model === priced.model
-        ? {
-            ...row,
-            cost: row.cost + priced.cost,
-            peakCost: row.peakCost + priced.peakCost,
-            offPeakCost: row.offPeakCost + priced.offPeakCost,
-            cacheHitInputTokens: row.cacheHitInputTokens + priced.cacheHitInputTokens,
-            cacheMissInputTokens: row.cacheMissInputTokens + priced.cacheMissInputTokens,
-            outputTokens: row.outputTokens + priced.outputTokens,
-            cacheHitInputCost: row.cacheHitInputCost + priced.cacheHitInputCost,
-            cacheMissInputCost: row.cacheMissInputCost + priced.cacheMissInputCost,
-            outputCost: row.outputCost + priced.outputCost,
-        }
-        : row);
-    if (!rows.some(row => row.model === priced.model))
-        rows.push(contributionModel(priced));
+    const row = contributionModel(priced);
+    const rows = spend.models.map(existing => existing.model === priced.model ? mergeModelRows(existing, row) : existing);
+    if (!rows.some(existing => existing.model === priced.model))
+        rows.push(row);
     return { total: spend.total + priced.cost, models: rows };
 }
 /**
@@ -193,24 +227,14 @@ export function addEventContribution(spend, priced) {
  * @returns the summed spend.
  */
 export function mergeTodaySpend(target, source) {
-    let merged = target;
+    const rows = new Map();
+    for (const row of target.models)
+        rows.set(row.model, row);
     for (const row of source.models) {
-        merged = addEventContribution(merged, {
-            dayKey: '',
-            model: row.model,
-            displayName: row.displayName,
-            cost: row.cost,
-            peakCost: row.peakCost,
-            offPeakCost: row.offPeakCost,
-            cacheHitInputTokens: row.cacheHitInputTokens,
-            cacheMissInputTokens: row.cacheMissInputTokens,
-            outputTokens: row.outputTokens,
-            cacheHitInputCost: row.cacheHitInputCost,
-            cacheMissInputCost: row.cacheMissInputCost,
-            outputCost: row.outputCost,
-        });
+        const existing = rows.get(row.model);
+        rows.set(row.model, existing === undefined ? row : mergeModelRows(existing, row));
     }
-    return merged;
+    return { total: target.total + source.total, models: [...rows.values()] };
 }
 /**
  * Price a set of billed events at the official per-model rates, applying the
@@ -223,19 +247,19 @@ export function mergeTodaySpend(target, source) {
  * published table prices only the two V4 rows).
  * @param events - the events to price.
  * @param billing - resolved pricing with peak-hour windows.
- * @param catalog - model display rows, in presentation order.
+ * @param names - model id → display label.
+ * @param dayKey - when provided, only events on this Beijing calendar day contribute.
  * @returns the total cost plus one row per priced model.
  */
-function priceEvents(events, billing, catalog) {
-    const names = new Map(catalog.map(model => [model.id, model.name]));
-    let spend = { total: 0, models: [] };
+function priceEvents(events, billing, names, dayKey) {
+    const accumulator = new SpendAccumulator();
     for (const event of events) {
         const priced = priceEvent(event, billing, names);
-        if (priced === undefined)
+        if (priced === undefined || (dayKey !== undefined && priced.dayKey !== dayKey))
             continue;
-        spend = addEventContribution(spend, priced);
+        accumulator.add(priced);
     }
-    return spend;
+    return accumulator.finish();
 }
 /**
  * Price one session's complete event log at the official per-model rates.
@@ -245,7 +269,52 @@ function priceEvents(events, billing, catalog) {
  * @returns the session's total cost plus one row per priced model.
  */
 export function computeSessionSpend(events, billing, catalog) {
-    return priceEvents(events, billing, catalog);
+    const names = new Map(catalog.map(model => [model.id, model.name]));
+    return priceEvents(events, billing, names);
+}
+/**
+ * Price one completed Turn's billed usage at the official per-model rates,
+ * identified by its closing assistant message id. The turn's events are those
+ * between its `turn/start` and `turn/end` (both matched by the message's own
+ * turn coordinate); each priced event applies the peak/off-peak table by its
+ * Beijing-time hour and weekday. A message that cannot be located, a turn
+ * without bracketing `turn/start` / `turn/end` events (for example after
+ * compaction), or a session with no priced usage prices to zero.
+ * @param events - one session's complete event log.
+ * @param billing - resolved pricing with peak-hour windows.
+ * @param catalog - model display rows, in presentation order.
+ * @param messageId - the closing assistant message's durable id.
+ * @returns the turn's total cost in CNY.
+ */
+export function computeTurnSpend(events, billing, catalog, messageId) {
+    const names = new Map(catalog.map(model => [model.id, model.name]));
+    let turn;
+    for (const event of events) {
+        if (event.type !== 'assistant/message')
+            continue;
+        if (event.data.message.id !== messageId)
+            continue;
+        turn = event.data.turn;
+        break;
+    }
+    if (turn === undefined)
+        return { total: 0 };
+    const accumulator = new SpendAccumulator();
+    let active = false;
+    for (const event of events) {
+        if (event.type === 'turn/start' && event.data.turn === turn) {
+            active = true;
+            continue;
+        }
+        if (event.type === 'turn/end' && event.data.turn === turn)
+            break;
+        if (!active)
+            continue;
+        const priced = priceEvent(event, billing, names);
+        if (priced !== undefined)
+            accumulator.add(priced);
+    }
+    return { total: accumulator.finish().total };
 }
 /**
  * Price every event whose Beijing-time calendar day is the day of `now`,
@@ -260,13 +329,6 @@ export function computeSessionSpend(events, billing, catalog) {
 export function computeTodaySpend(events, billing, catalog, now = new Date()) {
     const day = beijingDayKey(now);
     const names = new Map(catalog.map(model => [model.id, model.name]));
-    let spend = emptyTodaySpend();
-    for (const event of events) {
-        const priced = priceEvent(event, billing, names);
-        if (priced === undefined || priced.dayKey !== day)
-            continue;
-        spend = addEventContribution(spend, priced);
-    }
-    return spend;
+    return priceEvents(events, billing, names, day);
 }
 //# sourceMappingURL=billing.js.map

package/lib/types/index.d.ts

@@ -13,18 +13,23 @@
  * session-projection registry is composed, the plugin additionally registers
  * the `billingTodaySpend` projection unit, which folds each session's spend
  * eagerly and lets cold reads ride the projection-cache ladder.
+ *
+ * A per-session spend cache makes the badge's turn-settled recompute
+ * incremental: session logs are append-only and chronological (the same
+ * assumption the projection unit makes), so the spend is reused while the log
+ * length is unchanged, and only the appended tail is priced when it grows.
  * @module @rayadesu/dsh-llm-billing
  */
 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, beijingDayKey, computeSessionSpend, computeTodaySpend, DEFAULT_MODEL_PRICING, DEFAULT_PEAK_HOURS, emptyTodaySpend, isPeak, mergeTodaySpend, priceEvent, resolveBilling, } from './billing.ts';
+export { addEventContribution, beijingDayKey, computeSessionSpend, computeTodaySpend, computeTurnSpend, DEFAULT_MODEL_PRICING, DEFAULT_PEAK_HOURS, emptyTodaySpend, isPeak, mergeTodaySpend, priceEvent, resolveBilling, SpendAccumulator, } from './billing.ts';
 export type { BillingConfig, BillingConfigModel, BillingEventContribution, DeepSeekModelPricing, DeepSeekTokenPrice, PeakHourWindow, ResolvedBilling, } from './billing.ts';
 export type * from './types.ts';
 export { BILLING_UNIT_KEY, billingTodaySpendDefinition, foldBillingUnit } from './projection.ts';
 export type { BillingUnitState } from './projection.ts';
-export { TodaySpendCache, TodaySpendScanner } from './today-spend.ts';
+export { foldSessionTitle, TodaySpendCache, TodaySpendScanner } from './today-spend.ts';
 export type { ScannerPersistedHeader, ScannerSession, TodaySpendScannerDeps } from './today-spend.ts';
 export declare const name = "llm-billing";
 /** Public API default; deployments may point elsewhere via $DEEPSEEK_BASE_URL. */

package/lib/types/index.js

@@ -13,6 +13,11 @@
  * session-projection registry is composed, the plugin additionally registers
  * the `billingTodaySpend` projection unit, which folds each session's spend
  * eagerly and lets cold reads ride the projection-cache ladder.
+ *
+ * A per-session spend cache makes the badge's turn-settled recompute
+ * incremental: session logs are append-only and chronological (the same
+ * assumption the projection unit makes), so the spend is reused while the log
+ * length is unchanged, and only the appended tail is priced when it grows.
  * @module @rayadesu/dsh-llm-billing
  */
 import z from '@deepseek-ai/schemastery';
@@ -20,13 +25,13 @@ import { assertUsableApiKey, LlmError } from '@deepseek-ai/dsh-llm';
 import { credentialRef } from '@deepseek-ai/dsh-credentials';
 import { launchEnvironmentOf } from '@deepseek-ai/dsh-launch-environment';
 import { DeepSeekBalanceGateway, fetchDeepSeekBalance } from "./balance.js";
-import { computeSessionSpend, DEFAULT_MODEL_PRICING, DEFAULT_PEAK_HOURS, resolveBilling, } from "./billing.js";
+import { computeSessionSpend, computeTurnSpend, DEFAULT_MODEL_PRICING, DEFAULT_PEAK_HOURS, mergeTodaySpend, resolveBilling, } from "./billing.js";
 import { billingTodaySpendDefinition } from "./projection.js";
 import { TodaySpendCache, TodaySpendScanner } from "./today-spend.js";
 export { DeepSeekBalanceGateway, fetchDeepSeekBalance, parseDeepSeekBalance } from "./balance.js";
-export { addEventContribution, beijingDayKey, computeSessionSpend, computeTodaySpend, DEFAULT_MODEL_PRICING, DEFAULT_PEAK_HOURS, emptyTodaySpend, isPeak, mergeTodaySpend, priceEvent, resolveBilling, } from "./billing.js";
+export { addEventContribution, beijingDayKey, computeSessionSpend, computeTodaySpend, computeTurnSpend, DEFAULT_MODEL_PRICING, DEFAULT_PEAK_HOURS, emptyTodaySpend, isPeak, mergeTodaySpend, priceEvent, resolveBilling, SpendAccumulator, } from "./billing.js";
 export { BILLING_UNIT_KEY, billingTodaySpendDefinition, foldBillingUnit } from "./projection.js";
-export { TodaySpendCache, TodaySpendScanner } from "./today-spend.js";
+export { foldSessionTitle, TodaySpendCache, TodaySpendScanner } from "./today-spend.js";
 export const name = 'llm-billing';
 const DEFAULT_API_KEY_ENV = 'DEEPSEEK_API_KEY';
 const BASE_URL_ENV = 'DEEPSEEK_BASE_URL';
@@ -123,8 +128,29 @@ export function apply(ctx, config) {
     };
     const billing = resolveBilling(config.billing);
     const catalog = (config.models ?? DEFAULT_MODELS).map(model => ({ id: model.id, name: model.name ?? model.id }));
+    // Per-session incremental spend cache: a session log is append-only and
+    // chronological (the same assumption the projection unit makes), so a spend
+    // computed for `count` events stays valid while the log length is unchanged,
+    // and only the appended tail needs pricing when it grows. A pricing-table
+    // change does not retroactively reprice (same caveat as the projection
+    // path); the map is capped so an unbounded session-id space cannot grow it
+    // without bound.
+    const sessionSpendCache = new Map();
     const fetchSessionSpend = async (sessionId) => {
-        return computeSessionSpend(await sessionEvents(ctx, sessionId), billing, catalog);
+        const events = await sessionEvents(ctx, sessionId);
+        const cached = sessionSpendCache.get(sessionId);
+        if (cached !== undefined && cached.count === events.length)
+            return cached.spend;
+        if (cached !== undefined && cached.count < events.length) {
+            const spend = mergeTodaySpend(cached.spend, computeSessionSpend(events.slice(cached.count), billing, catalog));
+            sessionSpendCache.set(sessionId, { count: events.length, spend });
+            return spend;
+        }
+        const spend = computeSessionSpend(events, billing, catalog);
+        if (sessionSpendCache.size >= 1024)
+            sessionSpendCache.clear();
+        sessionSpendCache.set(sessionId, { count: events.length, spend });
+        return spend;
     };
     // Plan C: register the per-session spend projection unit on the projection
     // registry. Registration is lazy — it happens on the first projection-path
@@ -160,7 +186,13 @@ export function apply(ctx, config) {
         catalog,
     });
     const todayCache = new TodaySpendCache(dayKey => scanner.scan(dayKey), TODAY_SPEND_CACHE_MS);
+    const todaySessionsCache = new TodaySpendCache(dayKey => scanner.scanSessions(dayKey), TODAY_SPEND_CACHE_MS);
     const fetchTodaySpend = async (force = false) => todayCache.get(force);
-    new DeepSeekBalanceGateway(ctx, { fetchBalance, fetchSessionSpend, fetchTodaySpend });
+    const fetchTodaySessionsSpend = async (force = false) => todaySessionsCache.get(force);
+    const fetchTurnSpend = async (sessionId, messageId) => {
+        const events = await sessionEvents(ctx, sessionId);
+        return computeTurnSpend(events, billing, catalog, messageId);
+    };
+    new DeepSeekBalanceGateway(ctx, { fetchBalance, fetchSessionSpend, fetchTodaySpend, fetchTodaySessionsSpend, fetchTurnSpend });
 }
 //# sourceMappingURL=index.js.map

package/lib/types/today-spend.d.ts

@@ -9,9 +9,10 @@
  *   with write-back) or, without the cache service, one detached local fold
  *   over a full `inspect`. Persisted revisions gate every cold read, so a
  *   session whose log did not change since the last resolution costs nothing.
- * - events path (plans A2/A3): collect only today's events (per-event
- *   Beijing-day filter during collection) with a hard cap, skipping sessions
- *   whose persisted revision is unchanged since the last scan.
+ * - events path (plans A2/A3): collect and price only today's events in one
+ *   pass (per-event Beijing-day filter during collection) with a hard cap,
+ *   skipping sessions whose persisted revision is unchanged since the last
+ *   scan.
  *
  * Both strategies run behind the same {@link TodaySpendCache}, so a miss
  * happens at most once per 60 seconds per process, and a manual refresh
@@ -22,9 +23,18 @@
 import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session';
 import type { SessionPersistenceRevision } from '@deepseek-ai/dsh-session-persistence';
 import type { ResolvedBilling } from './billing.ts';
-import type { DeepSeekTodaySpend } from './types.ts';
+import type { DeepSeekTodaySessionsSpend, DeepSeekTodaySpend } from './types.ts';
 import { BILLING_UNIT_KEY, type BillingUnitState } from './projection.ts';
 import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection';
+/**
+ * Fold one session's durable display title: the latest `session/title`
+ * event's text (last-wins, matching the `title` projection), or `null` before
+ * the first title lands. The fold runs over the complete log, so an explicit
+ * user rename is picked up as soon as its event commits.
+ * @param events - one session's complete event log.
+ * @returns the session's current title, or `null` when untitled.
+ */
+export declare function foldSessionTitle(events: readonly SessionEvent[]): string | null;
 /** Structural slice of a live session the scanner reads. */
 export interface ScannerSession {
     readonly id: SessionId;
@@ -88,8 +98,10 @@ export interface TodaySpendScannerDeps {
  * coalesces concurrent misses, and a `force` bypass for the manual refresh
  * path. Cross-day invalidation is automatic (the day key changes); a failed
  * scan leaves the previous value in place and retries on the next call.
+ * @typeParam T - the cached aggregate's value shape (the spend or its
+ *   per-session breakdown).
  */
-export declare class TodaySpendCache {
+export declare class TodaySpendCache<T = DeepSeekTodaySpend> {
     private readonly scan;
     private readonly ttlMs;
     private readonly now;
@@ -98,18 +110,18 @@ export declare class TodaySpendCache {
     private cachedAt;
     private inFlight;
     /**
+     * @param scan - the aggregate computation behind a miss.
      * @param ttlMs - time window in milliseconds (default 60 000).
      * @param now - clock source (injectable for tests).
-     * @param scan - the aggregate computation behind a miss.
      */
-    constructor(scan: (dayKey: string) => Promise<DeepSeekTodaySpend>, ttlMs?: number, now?: () => Date);
+    constructor(scan: (dayKey: string) => Promise<T>, ttlMs?: number, now?: () => Date);
     /**
      * Read today's spend, cached per Beijing day within the TTL window.
      * @param force - bypass the time window (manual refresh); the day-key gate
      *   and the in-flight coalescing still apply to non-force callers.
      * @returns today's spend.
      */
-    get(force?: boolean): Promise<DeepSeekTodaySpend>;
+    get(force?: boolean): Promise<T>;
 }
 /**
  * The aggregate computation behind a cache miss. Chooses the projection path
@@ -119,7 +131,7 @@ export declare class TodaySpendCache {
  */
 export declare class TodaySpendScanner {
     private readonly deps;
-    /** Cold sessions resolved on the projection path: id → revision + unit state. */
+    /** Cold sessions resolved on the projection path: id → revision + unit state + title. */
     private readonly coldResolved;
     /** Cold sessions resolved on the events path: id → revision (events were collected). */
     private lastEventsScan;
@@ -130,9 +142,49 @@ export declare class TodaySpendScanner {
      * @returns today's spend across every session.
      */
     scan(dayKey: string): Promise<DeepSeekTodaySpend>;
+    /**
+     * Compute today's per-session spend for one Beijing day, sorted by cost
+     * descending. Sessions with no priced usage on the day are omitted; each
+     * row carries the session's durable title folded from its log.
+     * @param dayKey - the Beijing-time calendar-day key to aggregate.
+     * @returns today's per-session rows, highest first.
+     */
+    scanSessions(dayKey: string): Promise<DeepSeekTodaySessionsSpend>;
+    /**
+     * Resolve one cold session's billing unit state and display title through
+     * the projection-cache ladder (cached row first, then a detached local
+     * fold over a full inspect). A cache-served value carries no title (the
+     * ladder only stores projection values), so such rows report `title: null`
+     * until the session is inspected again.
+     * @param id - the cold session's id.
+     * @returns the resolved state and title, or `undefined` when unreadable.
+     */
+    private resolveCold;
     /** Projection path: eager cells for live sessions, revision-gated cold ladder for the rest. */
     private scanProjections;
-    /** Events path: collect only today's events (capped), gated by revisions. */
+    /**
+     * Events path: price today's events in a single pass (per-event Beijing-day
+     * filter during collection, hard cap), gated by revisions.
+     */
     private scanEvents;
+    /**
+     * Projection-path per-session scan: eager cells for live sessions (title
+     * folded from the live log, so a rename is reflected immediately),
+     * revision-gated cold ladder for the rest (title resolved on inspect,
+     * `null` when served from the projection cache).
+     * @param dayKey - the Beijing-time calendar-day key to aggregate.
+     * @returns unsorted per-session rows for the day.
+     */
+    private scanSessionsProjections;
+    /**
+     * Events-path per-session scan: price today's events in a single pass,
+     * accumulating per session (per-event Beijing-day filter during collection,
+     * hard cap), gated by revisions. Titles fold from each session's complete
+     * log — a `session/title` event can predate today — so a rename is reflected
+     * as soon as the session's log is re-read.
+     * @param dayKey - the Beijing-time calendar-day key to aggregate.
+     * @returns unsorted per-session rows for the day.
+     */
+    private scanSessionsEvents;
 }
 //# sourceMappingURL=today-spend.d.ts.map