@rayadesu/dsh-llm-billing 0.2.2 → 0.2.3

package/lib/index.js

@@ -228,11 +228,12 @@ let DeepSeekBalanceGateway = (() => {
 * 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
 */
 /**
@@ -311,20 +312,28 @@ function resolveBilling(config) {
 		models
 	};
 }
-/** The Beijing (Asia/Shanghai, UTC+8, no DST) hour of a timestamp. */
-function beijingHour(now) {
-	return new Date(now.getTime() + 288e5).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() + 288e5).getUTCDay();
+function beijingParts(time) {
+	const shifted = new Date(time + 288e5);
+	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. */
 function beijingDayKey(now) {
-	return new Date(now.getTime() + 288e5).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,
@@ -335,10 +344,8 @@ function beijingDayKey(now) {
 * @returns true during a weekday peak hour.
 */
 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
@@ -360,8 +367,8 @@ function priceEvent(event, billing, names) {
 	const model = event.data.message.source.model;
 	const pricing = billing.models.get(model);
 	if (pricing === void 0) return void 0;
-	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);
@@ -371,7 +378,7 @@ function priceEvent(event, billing, names) {
 	const outputCost = output * price.output / 1e6;
 	const cost = hitCost + missCost + outputCost;
 	return {
-		dayKey: beijingDayKey(time),
+		dayKey,
 		model,
 		displayName: names.get(model) ?? model,
 		cost,
@@ -408,6 +415,48 @@ 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.
+*/
+var SpendAccumulator = class {
+	rows = /* @__PURE__ */ 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 === void 0 ? 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).
@@ -416,19 +465,9 @@ function contributionModel(priced) {
 * @returns the merged spend.
 */
 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
@@ -442,22 +481,16 @@ function addEventContribution(spend, priced) {
 * @returns the summed spend.
 */
 function mergeTodaySpend(target, source) {
-	let merged = target;
-	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
-	});
-	return merged;
+	const rows = /* @__PURE__ */ new Map();
+	for (const row of target.models) rows.set(row.model, row);
+	for (const row of source.models) {
+		const existing = rows.get(row.model);
+		rows.set(row.model, existing === void 0 ? row : mergeModelRows(existing, row));
+	}
+	return {
+		total: target.total + source.total,
+		models: [...rows.values()]
+	};
 }
 /**
 * Price a set of billed events at the official per-model rates, applying the
@@ -470,21 +503,18 @@ 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 === void 0) continue;
-		spend = addEventContribution(spend, priced);
+		if (priced === void 0 || dayKey !== void 0 && priced.dayKey !== dayKey) continue;
+		accumulator.add(priced);
 	}
-	return spend;
+	return accumulator.finish();
 }
 /**
 * Price one session's complete event log at the official per-model rates.
@@ -494,7 +524,7 @@ function priceEvents(events, billing, catalog) {
 * @returns the session's total cost plus one row per priced model.
 */
 function computeSessionSpend(events, billing, catalog) {
-	return priceEvents(events, billing, catalog);
+	return priceEvents(events, billing, new Map(catalog.map((model) => [model.id, model.name])));
 }
 /**
 * Price every event whose Beijing-time calendar day is the day of `now`,
@@ -508,14 +538,7 @@ function computeSessionSpend(events, billing, catalog) {
 */
 function computeTodaySpend(events, billing, catalog, now = /* @__PURE__ */ 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 === void 0 || priced.dayKey !== day) continue;
-		spend = addEventContribution(spend, priced);
-	}
-	return spend;
+	return priceEvents(events, billing, new Map(catalog.map((model) => [model.id, model.name])), day);
 }
 //#endregion
 //#region lib/types/projection.js
@@ -618,9 +641,10 @@ function foldBillingUnit(unit, events) {
 *   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
@@ -628,11 +652,19 @@ function foldBillingUnit(unit, events) {
 * unchanged log provably cannot change the aggregate.
 * @module @rayadesu/dsh-llm-billing/today-spend
 */
-/** Bounded parallel fan-out: run `run` over `items` with at most `limit` in flight. */
+/**
+* Bounded parallel fan-out: run `run` over `items` with at most `limit` in
+* flight. A shared index counter hands each worker its next job, so the
+* dispatch is O(n) overall (array `shift()` would be O(n) per pop).
+*/
 async function withConcurrency(items, limit, run) {
-	const queue = [...items];
-	await Promise.all(Array.from({ length: Math.min(limit, queue.length) }, async () => {
-		for (let job = queue.shift(); job !== void 0; job = queue.shift()) await run(job);
+	const total = items.length;
+	let next = 0;
+	await Promise.all(Array.from({ length: Math.min(limit, total) }, async () => {
+		for (let job = next; job < total; job = next) {
+			next += 1;
+			await run(items[job]);
+		}
 	}));
 }
 /**
@@ -713,13 +745,15 @@ var TodaySpendScanner = class {
 	/** Projection path: eager cells for live sessions, revision-gated cold ladder for the rest. */
 	async scanProjections(dayKey) {
 		const { sessions, persistence, projections, projectionCache, unit, logger } = this.deps;
+		const projectionsService = projections?.();
+		const cache = projectionCache?.();
 		let total = emptyTodaySpend();
 		const liveIds = /* @__PURE__ */ new Set();
 		if (sessions !== void 0) {
 			const store = sessions();
 			if (store !== void 0) for (const session of store.list()) {
 				liveIds.add(session.id);
-				const state = projections?.()?.stateOf(session, BILLING_UNIT_KEY);
+				const state = projectionsService?.stateOf(session, BILLING_UNIT_KEY);
 				if (state !== void 0 && state.dayKey === dayKey) total = mergeTodaySpend(total, state.spend);
 			}
 		}
@@ -741,7 +775,6 @@ var TodaySpendScanner = class {
 		}
 		await withConcurrency(pending, 8, async ({ id, revision }) => {
 			let value;
-			const cache = projectionCache?.();
 			if (cache !== void 0) try {
 				value = (await cache.coldSnapshot(id)).values[BILLING_UNIT_KEY];
 			} catch (error) {
@@ -764,24 +797,34 @@ var TodaySpendScanner = class {
 		}
 		return total;
 	}
-	/** 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.
+	*/
 	async scanEvents(dayKey) {
 		const { sessions, persistence, maxEvents, logger, billing, catalog } = this.deps;
-		const events = [];
+		const names = new Map(catalog.map((model) => [model.id, model.name]));
+		const accumulator = new SpendAccumulator();
 		const liveIds = /* @__PURE__ */ new Set();
+		let collected = 0;
 		let truncated = false;
+		const collect = (events) => {
+			for (const event of events) {
+				if (beijingDayKey(new Date(event.time)) !== dayKey) continue;
+				collected += 1;
+				if (collected > maxEvents) {
+					truncated = true;
+					return;
+				}
+				const priced = priceEvent(event, billing, names);
+				if (priced !== void 0) accumulator.add(priced);
+			}
+		};
 		if (sessions !== void 0) {
 			const store = sessions();
 			if (store !== void 0) for (const session of store.list()) {
 				liveIds.add(session.id);
-				for (const event of session.events) {
-					if (beijingDayKey(new Date(event.time)) !== dayKey) continue;
-					events.push(event);
-					if (events.length >= maxEvents) {
-						truncated = true;
-						break;
-					}
-				}
+				collect(session.events);
 				if (truncated) break;
 			}
 		}
@@ -792,15 +835,7 @@ var TodaySpendScanner = class {
 				if (liveIds.has(header.id)) continue;
 				if (this.lastEventsScan?.get(header.id) === revision) continue;
 				try {
-					const inspection = await persistenceService.inspect(header.id);
-					for (const event of inspection.events) {
-						if (beijingDayKey(new Date(event.time)) !== dayKey) continue;
-						events.push(event);
-						if (events.length >= maxEvents) {
-							truncated = true;
-							break;
-						}
-					}
+					collect((await persistenceService.inspect(header.id)).events);
 				} catch (error) {
 					logger.warn(`llm-billing: skipping unreadable session ${header.id}: ${String(error)}`);
 				}
@@ -809,7 +844,7 @@ var TodaySpendScanner = class {
 			if (!truncated) this.lastEventsScan = new Map(snapshots.map((snapshot) => [snapshot.header.id, snapshot.revision]));
 		}
 		if (truncated) logger.warn(`llm-billing: today's events exceeded ${maxEvents}; result truncated`);
-		return computeTodaySpend(events, billing, catalog, /* @__PURE__ */ new Date(`${dayKey}T00:00:00Z`));
+		return accumulator.finish();
 	}
 };
 //#endregion
@@ -829,6 +864,11 @@ var TodaySpendScanner = class {
 * 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
 */
 const name = "llm-billing";
@@ -928,8 +968,26 @@ function apply(ctx, config) {
 		id: model.id,
 		name: model.name ?? model.id
 	}));
+	const sessionSpendCache = /* @__PURE__ */ 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 !== void 0 && cached.count === events.length) return cached.spend;
+		if (cached !== void 0 && 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;
 	};
 	const unit = billingTodaySpendDefinition(billing, catalog);
 	let unitRegistered = false;
@@ -961,4 +1019,4 @@ function apply(ctx, config) {
 	});
 }
 //#endregion
-export { BILLING_UNIT_KEY, Config, DEFAULT_MODEL_PRICING, DEFAULT_PEAK_HOURS, DeepSeekBalanceGateway, PUBLIC_BASE_URL, TODAY_SPEND_CACHE_MS, TODAY_SPEND_MAX_EVENTS, TodaySpendCache, TodaySpendScanner, addEventContribution, apply, beijingDayKey, billingTodaySpendDefinition, computeSessionSpend, computeTodaySpend, emptyTodaySpend, fetchDeepSeekBalance, foldBillingUnit, isPeak, mergeTodaySpend, name, parseDeepSeekBalance, priceEvent, resolveBilling };
+export { BILLING_UNIT_KEY, Config, DEFAULT_MODEL_PRICING, DEFAULT_PEAK_HOURS, DeepSeekBalanceGateway, PUBLIC_BASE_URL, SpendAccumulator, TODAY_SPEND_CACHE_MS, TODAY_SPEND_MAX_EVENTS, TodaySpendCache, TodaySpendScanner, addEventContribution, apply, beijingDayKey, billingTodaySpendDefinition, computeSessionSpend, computeTodaySpend, emptyTodaySpend, fetchDeepSeekBalance, foldBillingUnit, isPeak, mergeTodaySpend, name, parseDeepSeekBalance, priceEvent, resolveBilling };

package/lib/types/billing.d.ts

@@ -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
  */
 import type { SessionEvent } from '@deepseek-ai/dsh-session';
@@ -143,6 +144,22 @@ export interface BillingEventContribution {
 export declare function priceEvent(event: SessionEvent, billing: ResolvedBilling, names: ReadonlyMap<string, string>): BillingEventContribution | undefined;
 /** A spend with no priced usage. */
 export declare function emptyTodaySpend(): DeepSeekTodaySpend;
+/**
+ * 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 declare class SpendAccumulator {
+    private readonly rows;
+    private total;
+    /** Add one priced contribution. */
+    add(priced: BillingEventContribution): void;
+    /** The folded spend; the accumulator stays usable afterwards. */
+    finish(): DeepSeekTodaySpend;
+}
 /**
  * Merge one priced event's contribution into an accumulator spend (pure:
  * returns a new spend, never mutates its input).

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,8 @@ 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 every event whose Beijing-time calendar day is the day of `now`,
@@ -260,13 +285,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,13 +13,18 @@
  * 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, 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';

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,11 +25,11 @@ 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, 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, 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 const name = 'llm-billing';
@@ -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

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
@@ -132,7 +133,10 @@ export declare class TodaySpendScanner {
     scan(dayKey: string): Promise<DeepSeekTodaySpend>;
     /** 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;
 }
 //# sourceMappingURL=today-spend.d.ts.map

package/lib/types/today-spend.js

@@ -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
@@ -19,14 +20,21 @@
  * unchanged log provably cannot change the aggregate.
  * @module @rayadesu/dsh-llm-billing/today-spend
  */
-import { beijingDayKey, computeTodaySpend, emptyTodaySpend, mergeTodaySpend } from "./billing.js";
+import { beijingDayKey, emptyTodaySpend, mergeTodaySpend, priceEvent, SpendAccumulator } from "./billing.js";
 import { BILLING_UNIT_KEY, foldBillingUnit } from "./projection.js";
-/** Bounded parallel fan-out: run `run` over `items` with at most `limit` in flight. */
+/**
+ * Bounded parallel fan-out: run `run` over `items` with at most `limit` in
+ * flight. A shared index counter hands each worker its next job, so the
+ * dispatch is O(n) overall (array `shift()` would be O(n) per pop).
+ */
 async function withConcurrency(items, limit, run) {
-    const queue = [...items];
-    await Promise.all(Array.from({ length: Math.min(limit, queue.length) }, async () => {
-        for (let job = queue.shift(); job !== undefined; job = queue.shift())
-            await run(job);
+    const total = items.length;
+    let next = 0;
+    await Promise.all(Array.from({ length: Math.min(limit, total) }, async () => {
+        for (let job = next; job < total; job = next) {
+            next += 1;
+            await run(items[job]);
+        }
     }));
 }
 /**
@@ -114,6 +122,9 @@ export class TodaySpendScanner {
     /** Projection path: eager cells for live sessions, revision-gated cold ladder for the rest. */
     async scanProjections(dayKey) {
         const { sessions, persistence, projections, projectionCache, unit, logger } = this.deps;
+        // Services resolve once per scan, not per session / per cold task.
+        const projectionsService = projections?.();
+        const cache = projectionCache?.();
         let total = emptyTodaySpend();
         const liveIds = new Set();
         if (sessions !== undefined) {
@@ -121,7 +132,7 @@ export class TodaySpendScanner {
             if (store !== undefined) {
                 for (const session of store.list()) {
                     liveIds.add(session.id);
-                    const state = projections?.()?.stateOf(session, BILLING_UNIT_KEY);
+                    const state = projectionsService?.stateOf(session, BILLING_UNIT_KEY);
                     if (state !== undefined && state.dayKey === dayKey) {
                         total = mergeTodaySpend(total, state.spend);
                     }
@@ -146,7 +157,6 @@ export class TodaySpendScanner {
         }
         await withConcurrency(pending, 8, async ({ id, revision }) => {
             let value;
-            const cache = projectionCache?.();
             if (cache !== undefined) {
                 try {
                     value = (await cache.coldSnapshot(id)).values[BILLING_UNIT_KEY];
@@ -176,26 +186,37 @@ export class TodaySpendScanner {
         }
         return total;
     }
-    /** 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.
+     */
     async scanEvents(dayKey) {
         const { sessions, persistence, maxEvents, logger, billing, catalog } = this.deps;
-        const events = [];
+        const names = new Map(catalog.map(model => [model.id, model.name]));
+        const accumulator = new SpendAccumulator();
         const liveIds = new Set();
+        let collected = 0;
         let truncated = false;
+        const collect = (events) => {
+            for (const event of events) {
+                if (beijingDayKey(new Date(event.time)) !== dayKey)
+                    continue;
+                collected += 1;
+                if (collected > maxEvents) {
+                    truncated = true;
+                    return;
+                }
+                const priced = priceEvent(event, billing, names);
+                if (priced !== undefined)
+                    accumulator.add(priced);
+            }
+        };
         if (sessions !== undefined) {
             const store = sessions();
             if (store !== undefined) {
                 for (const session of store.list()) {
                     liveIds.add(session.id);
-                    for (const event of session.events) {
-                        if (beijingDayKey(new Date(event.time)) !== dayKey)
-                            continue;
-                        events.push(event);
-                        if (events.length >= maxEvents) {
-                            truncated = true;
-                            break;
-                        }
-                    }
+                    collect(session.events);
                     if (truncated)
                         break;
                 }
@@ -210,16 +231,7 @@ export class TodaySpendScanner {
                 if (this.lastEventsScan?.get(header.id) === revision)
                     continue;
                 try {
-                    const inspection = await persistenceService.inspect(header.id);
-                    for (const event of inspection.events) {
-                        if (beijingDayKey(new Date(event.time)) !== dayKey)
-                            continue;
-                        events.push(event);
-                        if (events.length >= maxEvents) {
-                            truncated = true;
-                            break;
-                        }
-                    }
+                    collect((await persistenceService.inspect(header.id)).events);
                 }
                 catch (error) {
                     // One unreadable session must not blank the whole-day aggregate.
@@ -237,10 +249,7 @@ export class TodaySpendScanner {
         }
         if (truncated)
             logger.warn(`llm-billing: today's events exceeded ${maxEvents}; result truncated`);
-        // The reference moment is derived from the day key (UTC midnight on that
-        // date is 08:00 Beijing the same day), so the pricing re-check cannot
-        // drift from the collection filter across a Beijing-day boundary.
-        return computeTodaySpend(events, billing, catalog, new Date(`${dayKey}T00:00:00Z`));
+        return accumulator.finish();
     }
 }
 //# sourceMappingURL=today-spend.js.map

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.2.2",
+  "version": "0.2.3",
   "publishConfig": {
     "access": "public"
   },