@rayadesu/dsh-llm-billing 0.3.8 → 0.3.10

package/lib/index.js

@@ -137,6 +137,7 @@ let DeepSeekBalanceGateway = (() => {
 	let _getTodaySpend_decorators;
 	let _getTodaySessionsSpend_decorators;
 	let _getTurnSpend_decorators;
+	let _getSessionTurnSpends_decorators;
 	return class DeepSeekBalanceGateway extends _classSuper {
 		static {
 			const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
@@ -145,6 +146,7 @@ let DeepSeekBalanceGateway = (() => {
 			_getTodaySpend_decorators = [Remote("getTodaySpend")];
 			_getTodaySessionsSpend_decorators = [Remote("getTodaySessionsSpend")];
 			_getTurnSpend_decorators = [Remote("getTurnSpend")];
+			_getSessionTurnSpends_decorators = [Remote("getSessionTurnSpends")];
 			__esDecorate(this, null, _getBalance_decorators, {
 				kind: "method",
 				name: "getBalance",
@@ -200,6 +202,17 @@ let DeepSeekBalanceGateway = (() => {
 				},
 				metadata: _metadata
 			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _getSessionTurnSpends_decorators, {
+				kind: "method",
+				name: "getSessionTurnSpends",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "getSessionTurnSpends" in obj,
+					get: (obj) => obj.getSessionTurnSpends
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
 			if (_metadata) Object.defineProperty(this, Symbol.metadata, {
 				enumerable: true,
 				configurable: true,
@@ -218,15 +231,18 @@ let DeepSeekBalanceGateway = (() => {
 			this.options = options;
 		}
 		/**
-		* Read the current DeepSeek account balance.
+		* Read the current DeepSeek account balance. A snapshot younger than the
+		* host-side TTL is reused, so several badge mounts share one provider call;
+		* `force` bypasses the TTL for the manual refresh.
+		* @param force - bypass the host-side TTL; omitted means a cached read.
 		* @returns the validated balance snapshot.
 		*/
-		getBalance() {
-			return this.options.fetchBalance();
+		getBalance(force) {
+			return this.options.fetchBalance(force ?? false);
 		}
 		/**
-		* Read one session's billed spend, priced per event by its Beijing-time
-		* peak/off-peak hour and weekday (weekends are always off-peak).
+		* Read one session's billed spend (same per-event pricing as
+		* {@link priceEvent}).
 		* @param sessionId - the session whose spend to compute.
 		* @returns the session's total cost plus one row per priced model.
 		*/
@@ -234,8 +250,8 @@ let DeepSeekBalanceGateway = (() => {
 			return this.options.fetchSessionSpend(sessionId);
 		}
 		/**
-		* Read today's billed spend across every session, priced per event by its
-		* Beijing-time calendar day, hour, and weekday (weekends are always off-peak).
+		* Read today's billed spend across every session: the same per-event
+		* pricing as {@link priceEvent}, restricted to the queried Beijing day.
 		* @param force - bypass the host-side 60s cache (manual refresh); omitted
 		*   means a cached read. Remote parameters cannot carry default values, so
 		*   the thunk receives `undefined` for an omitted argument.
@@ -245,10 +261,9 @@ let DeepSeekBalanceGateway = (() => {
 			return this.options.fetchTodaySpend(force ?? false);
 		}
 		/**
-		* Read today's billed spend per session, priced per event by its
-		* Beijing-time calendar day, hour, and weekday (weekends are always
-		* off-peak). Rows carry the session's durable title and sort by cost
-		* descending; sessions with no priced usage on the day are omitted.
+		* Read today's billed spend per session, restricted to the queried Beijing
+		* day. Rows carry the session's durable title and sort by cost descending;
+		* sessions with no priced usage on the day are omitted.
 		* @param force - bypass the host-side 60s cache (manual refresh); omitted
 		*   means a cached read.
 		* @returns today's per-session rows, highest first.
@@ -257,8 +272,8 @@ let DeepSeekBalanceGateway = (() => {
 			return this.options.fetchTodaySessionsSpend(force ?? false);
 		}
 		/**
-		* Read one completed Turn's billed spend, priced per event by its
-		* Beijing-time hour and weekday (weekends are always off-peak).
+		* Read one completed Turn's billed spend (same per-event pricing as
+		* {@link priceEvent}).
 		* @param sessionId - the session owning the Turn.
 		* @param messageId - the closing assistant message's durable id, which
 		*   locates the Turn in the session log.
@@ -267,6 +282,16 @@ let DeepSeekBalanceGateway = (() => {
 		getTurnSpend(sessionId, messageId) {
 			return this.options.fetchTurnSpend(sessionId, messageId);
 		}
+		/**
+		* Read every completed Turn's billed spend in one session (same per-event
+		* pricing as {@link priceEvent}). One call replaces the per-message
+		* `getTurnSpend` fan-out for a rendered transcript.
+		* @param sessionId - the session whose Turn costs to compute.
+		* @returns one row per assistant message inside a completed Turn, in log order.
+		*/
+		getSessionTurnSpends(sessionId) {
+			return this.options.fetchTurnSpends(sessionId);
+		}
 	};
 })();
 //#endregion
@@ -297,20 +322,93 @@ const DEFAULT_PEAK_HOURS = [{
 	start: 14,
 	end: 18
 }];
-/** Official peak/off-peak rates (CNY per 1M tokens), effective 2026-08-17. */
+/**
+* Inclusive epoch ms of the published V4 Flash series re-pricing:
+* 2026-09-10 12:00 Beijing time (UTC+8, no DST) = 04:00 UTC. Samples before
+* this instant keep the base rates; samples at or after it bill at the second
+* revision.
+*/
+const FLASH_SERIES_RATE_CHANGE_AT = Date.UTC(2026, 8, 10, 4, 0, 0);
+/**
+* Inclusive epoch ms of the announced V4 Pro route switch: 2026-09-14 12:00
+* Beijing time (UTC+8, no DST) = 04:00 UTC. From that instant the V4 Pro route
+* is served by V4.1 Flash and billed at the V4.1 Flash rates.
+*/
+const V4_PRO_ROUTE_SWITCH_AT = Date.UTC(2026, 8, 14, 4, 0, 0);
+/** The V4 Flash series' base rates (effective 2026-08-17), CNY per 1M tokens. */
+const FLASH_BASE_RATES = {
+	peak: {
+		cacheHitInput: .1,
+		cacheMissInput: 3,
+		output: 9
+	},
+	offPeak: {
+		cacheHitInput: .05,
+		cacheMissInput: 1.5,
+		output: 4.5
+	}
+};
+/**
+* The V4 Flash series' second revision (effective
+* {@link FLASH_SERIES_RATE_CHANGE_AT}): off-peak 0.02 / 1.0 / 4.0, peak at
+* twice those prices.
+*/
+const FLASH_REPRICED_RATES = {
+	effectiveFrom: FLASH_SERIES_RATE_CHANGE_AT,
+	peak: {
+		cacheHitInput: .04,
+		cacheMissInput: 2,
+		output: 8
+	},
+	offPeak: {
+		cacheHitInput: .02,
+		cacheMissInput: 1,
+		output: 4
+	}
+};
+/**
+* The V4.1 Flash rates as they reach the retired V4 Pro route from
+* {@link V4_PRO_ROUTE_SWITCH_AT}: the same price pair as the flash series'
+* second revision, carried at its own effective instant.
+*/
+const V4_PRO_SWITCHED_RATES = {
+	effectiveFrom: V4_PRO_ROUTE_SWITCH_AT,
+	peak: FLASH_REPRICED_RATES.peak,
+	offPeak: FLASH_REPRICED_RATES.offPeak
+};
+/**
+* Official peak/off-peak rates (CNY per 1M tokens) per model, as dated
+* revisions. Base rows are the schedule effective 2026-08-17; the V4 Flash
+* series (V4.1 Flash, V4 Flash, V4 Flash Vision Exp) carries the second
+* revision effective 2026-09-10 12:00 Beijing, and the V4 Pro row the V4.1
+* Flash rates from its announced route switch (2026-09-14 12:00 Beijing) —
+* the MiMo-V2.5 series is untouched by either adjustment. Rows sharing a model
+* are that model's rate history.
+*/
 const DEFAULT_MODEL_PRICING = [
+	{
+		model: "deepseek-flash",
+		...FLASH_BASE_RATES
+	},
+	{
+		model: "deepseek-flash",
+		...FLASH_REPRICED_RATES
+	},
 	{
 		model: "deepseek-v4-flash",
-		peak: {
-			cacheHitInput: .1,
-			cacheMissInput: 3,
-			output: 9
-		},
-		offPeak: {
-			cacheHitInput: .05,
-			cacheMissInput: 1.5,
-			output: 4.5
-		}
+		...FLASH_BASE_RATES
+	},
+	{
+		model: "deepseek-v4-flash",
+		...FLASH_REPRICED_RATES
+	},
+	{
+		model: "deepseek-v4.1-flash-expires-on-0910",
+		...FLASH_BASE_RATES
+	},
+	{
+		model: "deepseek-v4.1-flash-expires-on-0910",
+		...FLASH_REPRICED_RATES
 	},
 	{
 		model: "deepseek-v4-pro",
@@ -325,18 +423,17 @@ const DEFAULT_MODEL_PRICING = [
 			output: 13.5
 		}
 	},
+	{
+		model: "deepseek-v4-pro",
+		...V4_PRO_SWITCHED_RATES
+	},
 	{
 		model: "deepseek-v4-flash-vision-exp",
-		peak: {
-			cacheHitInput: .1,
-			cacheMissInput: 3,
-			output: 9
-		},
-		offPeak: {
-			cacheHitInput: .05,
-			cacheMissInput: 1.5,
-			output: 4.5
-		}
+		...FLASH_BASE_RATES
+	},
+	{
+		model: "deepseek-v4-flash-vision-exp",
+		...FLASH_REPRICED_RATES
 	},
 	{
 		model: "mimo-v2.5-pro",
@@ -371,39 +468,123 @@ const DEFAULT_MODEL_PRICING = [
 * `z.array` as `[]` rather than `undefined`, so emptiness — not just absence —
 * selects the defaults. Explicit non-empty rows override the same model; a
 * supplied non-empty `models` list is authoritative.
+*
+* Rows sharing a model are that model's rate revisions, kept in ascending
+* `effectiveFrom` order (an undated base revision first). Two rows declaring
+* the same effective instant are one revision and the later row wins — the
+* historical override rule — so re-declaring a model can neither duplicate a
+* revision nor install a second undated base.
 * @param config - optional raw billing configuration.
-* @returns the resolved table and peak-hour windows.
+* @returns the resolved table (per model: its revisions plus the newest rates) and peak-hour windows.
 */
 function resolveBilling(config) {
 	const peakHours = config?.peakHours !== void 0 && config.peakHours.length > 0 ? config.peakHours : DEFAULT_PEAK_HOURS;
 	const rows = config?.models !== void 0 && config.models.length > 0 ? config.models : DEFAULT_MODEL_PRICING;
+	const schedules = /* @__PURE__ */ new Map();
+	for (const row of rows) {
+		const revision = row.effectiveFrom === void 0 ? {
+			peak: row.peak,
+			offPeak: row.offPeak
+		} : {
+			effectiveFrom: row.effectiveFrom,
+			peak: row.peak,
+			offPeak: row.offPeak
+		};
+		const revisions = schedules.get(row.model);
+		if (revisions === void 0) {
+			schedules.set(row.model, [revision]);
+			continue;
+		}
+		const duplicate = revisions.findIndex((candidate) => candidate.effectiveFrom === revision.effectiveFrom);
+		if (duplicate >= 0) revisions[duplicate] = revision;
+		else revisions.push(revision);
+	}
 	const models = /* @__PURE__ */ new Map();
-	for (const row of rows) models.set(row.model, {
-		peak: row.peak,
-		offPeak: row.offPeak
-	});
+	for (const [model, revisions] of schedules) {
+		revisions.sort((left, right) => (left.effectiveFrom ?? Number.NEGATIVE_INFINITY) - (right.effectiveFrom ?? Number.NEGATIVE_INFINITY));
+		const newest = revisions[revisions.length - 1];
+		models.set(model, {
+			peak: newest.peak,
+			offPeak: newest.offPeak,
+			revisions
+		});
+	}
 	return {
 		peakHours,
 		models
 	};
 }
 /**
-* 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.
+* The rate revision in effect at one instant: the newest revision that took
+* effect at or before it. Revisions are ascending, so the scan stops at the
+* first future one. An instant before the earliest dated revision bills at that
+* earliest revision — a model with only dated rows is never left unpriced.
+*/
+function ratesAt(revisions, time) {
+	let chosen = revisions[0];
+	for (let index = 1; index < revisions.length; index += 1) {
+		const revision = revisions[index];
+		if (revision.effectiveFrom === void 0 || revision.effectiveFrom > time) break;
+		chosen = revision;
+	}
+	return chosen;
+}
+/** Beijing is a fixed UTC+8 offset with no DST. */
+const BEIJING_OFFSET_MS = 288e5;
+/** Milliseconds in one day. */
+const DAY_MS = 864e5;
+/** Epoch day of 1970-01-01 in the civil-date algorithm below. */
+const CIVIL_EPOCH_DAY = 719468;
+/** Two-digit zero pad for a calendar field. */
+function pad2(value) {
+	return value < 10 ? `0${value}` : String(value);
+}
+/**
+* Civil date of an epoch day (Howard Hinnant's days-from-civil inverse):
+* pure integer arithmetic, no `Date` allocation and no ISO-string slicing.
+*/
+function civilDateOf(epochDay) {
+	const shifted = epochDay + CIVIL_EPOCH_DAY;
+	const era = Math.floor(shifted / 146097);
+	const dayOfEra = shifted - era * 146097;
+	const yearOfEra = Math.floor((dayOfEra - Math.floor(dayOfEra / 1460) + Math.floor(dayOfEra / 36524) - Math.floor(dayOfEra / 146096)) / 365);
+	const year = yearOfEra + era * 400;
+	const dayOfYear = dayOfEra - (365 * yearOfEra + Math.floor(yearOfEra / 4) - Math.floor(yearOfEra / 100));
+	const monthPrime = Math.floor((5 * dayOfYear + 2) / 153);
+	const month = monthPrime + (monthPrime < 10 ? 3 : -9);
+	return {
+		year: month <= 2 ? year + 1 : year,
+		month,
+		day: dayOfYear - Math.floor((153 * monthPrime + 2) / 5) + 1
+	};
+}
+/**
+* Derive the Beijing hour, weekday, and calendar-day key of one timestamp with
+* pure integer arithmetic — every timezone-sensitive read shares this one
+* implementation, so the pieces cannot drift apart. Callers that filter by
+* day and then price the same event reuse the returned view, so each event is
+* parsed exactly once. (The hot fold path runs this per committed event; the
+* previous `Date` + `toISOString().slice()` version allocated a `Date` and a
+* 24-character string per call.)
 * @param time - epoch milliseconds.
+* @throws {RangeError} when `time` is not a finite number.
 */
-function beijingParts(time) {
-	const shifted = new Date(time + 288e5);
+function beijingPartsOf(time) {
+	if (!Number.isFinite(time)) throw new RangeError(`billing: event time is not finite (${String(time)})`);
+	const shifted = time + BEIJING_OFFSET_MS;
+	const epochDay = Math.floor(shifted / DAY_MS);
+	const msOfDay = shifted - epochDay * DAY_MS;
+	const civil = civilDateOf(epochDay);
 	return {
-		hour: shifted.getUTCHours(),
-		weekday: shifted.getUTCDay(),
-		dayKey: shifted.toISOString().slice(0, 10)
+		time,
+		hour: Math.floor(msOfDay / 36e5),
+		weekday: ((epochDay + 4) % 7 + 7) % 7,
+		dayKey: `${civil.year}-${pad2(civil.month)}-${pad2(civil.day)}`
 	};
 }
 /** The Beijing (Asia/Shanghai, UTC+8, no DST) calendar-day key of a timestamp. */
 function beijingDayKey(now) {
-	return beijingParts(now.getTime()).dayKey;
+	return beijingPartsOf(now.getTime()).dayKey;
 }
 /**
 * The durable inherited-prefix boundary of one session: the number of leading
@@ -443,41 +624,70 @@ function isPeakParts(billing, hour, weekday) {
 * @returns true during a weekday peak hour.
 */
 function isPeak(billing, now) {
-	const { hour, weekday } = beijingParts(now.getTime());
+	const { hour, weekday } = beijingPartsOf(now.getTime());
 	return isPeakParts(billing, hour, weekday);
 }
 /**
 * Price one event at the official per-model rates, applying the peak/off-peak
 * table by its Beijing-time hour and weekday (peak windows apply Monday–Friday
-* only; weekends are off-peak). Each `assistant/message` event with usage
+* only; weekends are off-peak) and the rate revision in effect at its own
+* timestamp. Each `assistant/message` event with usage
 * contributes cache-hit input, cache-miss input (uncached input plus cache
 * writes), and output (reasoning included) tokens at the rate of its own
-* timestamp; a model with usage but no pricing row contributes nothing (the
-* published table prices only the two V4 rows).
+* timestamp; a model with usage but no pricing row contributes nothing.
 * @param event - the event to price.
 * @param billing - resolved pricing with peak-hour windows.
 * @param names - model id → display label.
 * @returns the priced contribution, or `undefined` when the event has no priced usage.
 */
 function priceEvent(event, billing, names) {
+	return priceEventAt(beijingPartsOf(event.time), event, billing, names);
+}
+/**
+* Price one event at the official per-model rates using a precomputed
+* Beijing-time view — the day-filtering and pricing of one event share a
+* single timezone parse (see {@link beijingPartsOf}). Semantics are identical
+* to {@link priceEvent}.
+* @param parts - the event's Beijing-time view.
+* @param event - the event to price.
+* @param billing - resolved pricing with peak-hour windows.
+* @param names - model id → display label.
+* @returns the priced contribution, or `undefined` when the event has no priced usage.
+*/
+function priceEventAt(parts, event, billing, names) {
 	if (event.type !== "assistant/message") return void 0;
 	const reported = event.data.usage;
 	if (reported === void 0) return void 0;
-	const model = event.data.message.source.model;
+	return priceUsage(parts, reported, event.data.message.source.model, billing, names);
+}
+/**
+* Price one provider-reported usage sample for one model at the rates of the
+* sample's own Beijing-time hour and weekday — the peak or off-peak price of
+* the rate revision in effect at the sample's own timestamp (a re-priced series
+* bills its history at the rates that applied then). `undefined` when the model
+* has no pricing row.
+* @param parts - the sample's Beijing-time view.
+* @param usage - the reported token buckets.
+* @param model - the wire model id the sample belongs to.
+* @param billing - resolved pricing with peak-hour windows.
+* @param names - model id → display label.
+* @returns the priced contribution, or `undefined` when the model has no rate row.
+*/
+function priceUsage(parts, usage, model, billing, names) {
 	const pricing = billing.models.get(model);
 	if (pricing === void 0) return void 0;
-	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);
-	const output = reported.outputTokens;
+	const peak = isPeakParts(billing, parts.hour, parts.weekday);
+	const revision = ratesAt(pricing.revisions, parts.time);
+	const price = peak ? revision.peak : revision.offPeak;
+	const hit = usage.cacheReadTokens ?? 0;
+	const miss = usage.inputTokens + (usage.cacheWriteTokens ?? 0);
+	const output = usage.outputTokens;
 	const hitCost = hit * price.cacheHitInput / 1e6;
 	const missCost = miss * price.cacheMissInput / 1e6;
 	const outputCost = output * price.output / 1e6;
 	const cost = hitCost + missCost + outputCost;
 	return {
-		dayKey,
+		dayKey: parts.dayKey,
 		model,
 		displayName: names.get(model) ?? model,
 		cost,
@@ -556,6 +766,192 @@ var SpendAccumulator = class {
 		};
 	}
 };
+/** The additive inverse of one spend (pure): used to replace a priced sample. */
+function negateSpend(spend) {
+	const negate = (value) => -value;
+	return {
+		total: negate(spend.total),
+		models: spend.models.map((row) => ({
+			...row,
+			cost: negate(row.cost),
+			peakCost: negate(row.peakCost),
+			offPeakCost: negate(row.offPeakCost),
+			cacheHitInputTokens: negate(row.cacheHitInputTokens),
+			cacheMissInputTokens: negate(row.cacheMissInputTokens),
+			outputTokens: negate(row.outputTokens),
+			cacheHitInputCost: negate(row.cacheHitInputCost),
+			cacheMissInputCost: negate(row.cacheMissInputCost),
+			outputCost: negate(row.outputCost)
+		}))
+	};
+}
+/**
+* Subtract one spend from another (pure). Rows that cancel out completely are
+* dropped so a replaced sample leaves no zero row behind.
+* @param target - the spend to subtract from.
+* @param source - the spend to remove.
+* @returns the difference.
+*/
+function subtractSpend(target, source) {
+	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);
+		if (existing === void 0) continue;
+		const next = mergeModelRows(existing, negateSpend({
+			total: 0,
+			models: [row]
+		}).models[0]);
+		if (next.cost === 0 && next.cacheHitInputTokens === 0 && next.cacheMissInputTokens === 0 && next.outputTokens === 0) rows.delete(row.model);
+		else rows.set(row.model, next);
+	}
+	return {
+		total: target.total - source.total,
+		models: [...rows.values()]
+	};
+}
+/** The empty fold state for one fork boundary. */
+function emptyBillingFoldState(inheritedEventCount = 0) {
+	return {
+		dayKey: "",
+		spend: emptyTodaySpend(),
+		session: emptyTodaySpend(),
+		inheritedEventCount,
+		model: "",
+		last: null
+	};
+}
+/** Whether an unknown value looks like a provider usage report. */
+function isTokenUsage(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const candidate = value;
+	return typeof candidate.inputTokens === "number" && typeof candidate.outputTokens === "number";
+}
+/**
+* The last `usage` sample embedded in an event's stream, if any. `assistant/
+* attempt` and the embedded streams are newer than the plugin's npm baseline,
+* so the stream is read structurally (a failed/retried attempt reports its
+* usage only there).
+*/
+function streamUsageOf(event) {
+	const stream = event.data === void 0 ? void 0 : event.data.stream;
+	if (!Array.isArray(stream)) return void 0;
+	for (let index = stream.length - 1; index >= 0; index -= 1) {
+		const chunk = stream[index]?.chunk;
+		if (chunk === void 0 || chunk.type !== "usage") continue;
+		return isTokenUsage(chunk.usage) ? chunk.usage : void 0;
+	}
+}
+/** The contribution as a one-row spend (the shape a sample keeps for replacement). */
+function contributionSpend(priced) {
+	return {
+		total: priced.cost,
+		models: [contributionModel(priced)]
+	};
+}
+/**
+* Fold one committed event into a session's billed-spend state.
+*
+* Priced samples come from `assistant/message` (its own reported usage, or the
+* stream's last usage chunk) and `assistant/attempt` (the stream's last usage
+* chunk, priced with the model of the latest `request/header`, since an
+* attempt carries no route). A sample for the same `(turn, step)` replaces the
+* previous one; `llm/retry-started` closes the replacement slot so a retried
+* attempt adds. Every other event is inert and returns the same state
+* reference.
+* @param state - the previous fold state.
+* @param event - the committed event.
+* @param billing - resolved pricing with peak-hour windows.
+* @param names - model id → display label.
+* @returns the next state (the same reference when nothing was priced).
+*/
+function applyBillingEvent(state, event, billing, names) {
+	if (event.seq < state.inheritedEventCount) return state;
+	const type = event.type;
+	if (type === "request/header") {
+		const model = event.data?.header?.config?.model;
+		return typeof model === "string" && model.length > 0 && model !== state.model ? {
+			...state,
+			model
+		} : state;
+	}
+	const data = event.data;
+	if (type === "llm/retry-started") {
+		if (typeof data?.turn !== "number" || typeof data.step !== "number") return state;
+		const last = state.last;
+		if (last === null || last.turn !== data.turn || last.step !== data.step) return state;
+		return {
+			...state,
+			last: null
+		};
+	}
+	if (type !== "assistant/message" && type !== "assistant/attempt") return state;
+	const usage = (type === "assistant/message" ? data?.usage : void 0) ?? streamUsageOf(event);
+	if (!isTokenUsage(usage)) return state;
+	const model = type === "assistant/message" ? data?.message?.source?.model : state.model;
+	if (typeof model !== "string" || model.length === 0) return state;
+	const priced = priceUsage(beijingPartsOf(event.time), usage, model, billing, names);
+	if (priced === void 0) return state;
+	let session = state.session;
+	let spend = state.spend;
+	let dayKey = state.dayKey;
+	const last = state.last;
+	const turn = typeof data?.turn === "number" ? data.turn : 0;
+	const step = typeof data?.step === "number" ? data.step : 0;
+	if (last !== null && last.turn === turn && last.step === step) {
+		session = subtractSpend(session, last.spend);
+		if (last.dayKey === dayKey) spend = subtractSpend(spend, last.spend);
+	}
+	session = addEventContribution(session, priced);
+	if (dayKey === priced.dayKey) spend = addEventContribution(spend, priced);
+	else if (dayKey === "" || priced.dayKey > dayKey) {
+		dayKey = priced.dayKey;
+		spend = addEventContribution(emptyTodaySpend(), priced);
+	}
+	return {
+		...state,
+		dayKey,
+		spend,
+		session,
+		last: {
+			turn,
+			step,
+			dayKey: priced.dayKey,
+			spend: contributionSpend(priced)
+		}
+	};
+}
+/**
+* Mutable wrapper over {@link applyBillingEvent} for the pure pricing paths:
+* feed events in order, read the folded spend.
+*/
+var BillingFolder = class {
+	billing;
+	state;
+	/**
+	* @param billing - resolved pricing with peak-hour windows.
+	* @param catalog - model display rows, in presentation order.
+	* @param inheritedEventCount - fork boundary to skip (default 0).
+	*/
+	constructor(billing, catalog, inheritedEventCount = 0) {
+		this.billing = billing;
+		this.names = new Map(catalog.map((model) => [model.id, model.name]));
+		this.state = emptyBillingFoldState(inheritedEventCount);
+	}
+	names;
+	/** Fold one event. */
+	add(event) {
+		this.state = applyBillingEvent(this.state, event, this.billing, this.names);
+	}
+	/** Fold every event, in order. */
+	addAll(events) {
+		for (const event of events) this.add(event);
+	}
+	/** The folded state (live reference; do not mutate). */
+	get fold() {
+		return this.state;
+	}
+};
 /**
 * Merge one priced event's contribution into an accumulator spend (pure:
 * returns a new spend, never mutates its input).
@@ -592,34 +988,11 @@ function mergeTodaySpend(target, source) {
 	};
 }
 /**
-* Price a set of billed events at the official per-model rates, applying the
-* peak/off-peak table per event by its Beijing-time hour and weekday (peak
-* windows apply Monday–Friday only; weekends are off-peak). Each
-* `assistant/message` event with usage contributes cache-hit input, cache-miss
-* input (uncached input plus cache writes), and output (reasoning included)
-* tokens at the rate of its own timestamp, with the three component costs
-* carried separately; a model with usage but no pricing row is omitted (the
-* published table prices only the two V4 rows).
-* @param events - the events to price.
-* @param billing - resolved pricing with peak-hour windows.
-* @param names - model id → display label.
-* @param dayKey - when provided, only events on this Beijing calendar day contribute.
-* @param startSeq - when provided, only events with `seq >= startSeq` contribute
-*   (a forked session's inherited prefix, `seq < startSeq`, is skipped).
-* @returns the total cost plus one row per priced model.
-*/
-function priceEvents(events, billing, names, dayKey, startSeq = 0) {
-	const accumulator = new SpendAccumulator();
-	for (const event of events) {
-		if (event.seq < startSeq) continue;
-		const priced = priceEvent(event, billing, names);
-		if (priced === void 0 || dayKey !== void 0 && priced.dayKey !== dayKey) continue;
-		accumulator.add(priced);
-	}
-	return accumulator.finish();
-}
-/**
-* Price one session's complete event log at the official per-model rates.
+* Price one session's complete event log at the official per-model rates,
+* with DSH's attempt semantics: every provider-reported sample (an
+* `assistant/message`'s usage, or an `assistant/attempt`'s stream usage)
+* contributes, a later sample for the same `(turn, step)` replaces the earlier
+* one, and `llm/retry-started` makes the retried attempt add.
 * @param events - one session's complete event log.
 * @param billing - resolved pricing with peak-hour windows.
 * @param catalog - model display rows, in presentation order.
@@ -630,16 +1003,18 @@ function priceEvents(events, billing, names, dayKey, startSeq = 0) {
 * @returns the session's total cost plus one row per priced model.
 */
 function computeSessionSpend(events, billing, catalog, startSeq = 0) {
-	return priceEvents(events, billing, new Map(catalog.map((model) => [model.id, model.name])), void 0, startSeq);
+	const folder = new BillingFolder(billing, catalog, startSeq);
+	folder.addAll(events);
+	return folder.fold.session;
 }
 /**
-* 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.
+* Price one completed Turn's billed usage, 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), priced
+* with the same attempt semantics as {@link computeSessionSpend}. 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.
@@ -647,7 +1022,18 @@ function computeSessionSpend(events, billing, catalog, startSeq = 0) {
 * @returns the turn's total cost in CNY.
 */
 function computeTurnSpend(events, billing, catalog, messageId) {
-	const names = new Map(catalog.map((model) => [model.id, model.name]));
+	return { total: turnCostOf(events, billing, catalog, messageId) };
+}
+/**
+* The total cost of the Turn containing `messageId`, folded with the shared
+* attempt semantics (see {@link applyBillingEvent}).
+* @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 - one assistant message inside the Turn.
+* @returns the Turn's total cost in CNY, or 0 when the Turn cannot be located.
+*/
+function turnCostOf(events, billing, catalog, messageId) {
 	let turn;
 	for (const event of events) {
 		if (event.type !== "assistant/message") continue;
@@ -655,8 +1041,8 @@ function computeTurnSpend(events, billing, catalog, messageId) {
 		turn = event.data.turn;
 		break;
 	}
-	if (turn === void 0) return { total: 0 };
-	const accumulator = new SpendAccumulator();
+	if (turn === void 0) return 0;
+	const folder = new BillingFolder(billing, catalog);
 	let active = false;
 	for (const event of events) {
 		if (event.type === "turn/start" && event.data.turn === turn) {
@@ -665,16 +1051,116 @@ function computeTurnSpend(events, billing, catalog, messageId) {
 		}
 		if (event.type === "turn/end" && event.data.turn === turn) break;
 		if (!active) continue;
-		const priced = priceEvent(event, billing, names);
-		if (priced !== void 0) accumulator.add(priced);
+		folder.add(event);
 	}
-	return { total: accumulator.finish().total };
+	return folder.fold.session.total;
+}
+/**
+* Incremental single-pass fold of one session's completed-Turn costs, keyed by
+* the id of every assistant message inside each Turn. Feeding the fold only
+* the appended tail keeps a growing session's map current in O(new events)
+* instead of re-scanning the whole log per message.
+*
+* Semantics are exactly {@link computeTurnSpend}'s: a Turn is the
+* `turn/start`..`turn/end` range (matched by the event's own turn coordinate),
+* every priced event inside it contributes at its own timestamp's rate, and a
+* message outside any bracket contributes nothing.
+*/
+var SessionTurnSpendFolder = class {
+	billing;
+	catalog;
+	rows = [];
+	ids = [];
+	/** Events of the open Turn, folded with the shared attempt semantics on close. */
+	events = [];
+	open = false;
+	/** Events already fed; a shorter log resets the fold. */
+	cursor = 0;
+	/**
+	* @param billing - resolved pricing with peak-hour windows.
+	* @param catalog - model display rows, in presentation order.
+	*/
+	constructor(billing, catalog) {
+		this.billing = billing;
+		this.catalog = catalog;
+	}
+	/** How many events have been folded so far (the host's incremental cursor). */
+	get processed() {
+		return this.cursor;
+	}
+	/**
+	* Fold every event from the cursor to the end of the log. A log shorter than
+	* the cursor (rewritten session) restarts the fold from an empty state.
+	* @param events - the session's complete event log, in seq order.
+	*/
+	feed(events) {
+		if (events.length < this.cursor) this.reset();
+		for (let index = this.cursor; index < events.length; index += 1) {
+			const event = events[index];
+			if (event.type === "turn/start") {
+				this.open = true;
+				this.ids = [];
+				this.events = [];
+				continue;
+			}
+			if (event.type === "turn/end") {
+				if (this.open) {
+					const folder = new BillingFolder(this.billing, this.catalog);
+					folder.addAll(this.events);
+					const total = folder.fold.session.total;
+					for (const messageId of this.ids) this.rows.push({
+						messageId,
+						total
+					});
+				}
+				this.open = false;
+				this.ids = [];
+				this.events = [];
+				continue;
+			}
+			if (!this.open) continue;
+			if (event.type === "assistant/message") this.ids.push(event.data.message.id);
+			this.events.push(event);
+		}
+		this.cursor = events.length;
+	}
+	/** The folded map; the fold stays usable afterwards. */
+	finish() {
+		return { turns: [...this.rows] };
+	}
+	/** Drop the fold state so the next feed starts from the log's beginning. */
+	reset() {
+		this.rows.length = 0;
+		this.ids = [];
+		this.events = [];
+		this.open = false;
+		this.cursor = 0;
+	}
+};
+/**
+* Price every completed Turn of one session in a single pass (the pure
+* equivalent of {@link SessionTurnSpendFolder}).
+* @param events - one session's complete event log.
+* @param billing - resolved pricing with peak-hour windows.
+* @param catalog - model display rows, in presentation order.
+* @returns one row per assistant message inside a completed Turn, in log order.
+*/
+function computeSessionTurnSpends(events, billing, catalog) {
+	const folder = new SessionTurnSpendFolder(billing, catalog);
+	folder.feed(events);
+	return folder.finish();
 }
 /**
-* Price every event whose Beijing-time calendar day is the day of `now`,
-* aggregating across every session's event log. Events from other Beijing
-* days are ignored, so a caller passes the concatenated logs of all sessions.
-* @param events - every session's complete event log, concatenated.
+* Price one session's log for the Beijing-time calendar day of `now`. Events
+* after the reference day are ignored; the fold's latest-day state then
+* answers the query exactly (empty when the session's latest priced day is not
+* the reference day). Pricing follows {@link applyBillingEvent} (attempt
+* samples with same-step replacement).
+*
+* The fold's `(turn, step)` replacement slot is per session, so callers must
+* pass ONE session's log; aggregate across sessions with
+* {@link mergeTodaySpend}.
+* @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 now - the reference moment whose Beijing-time calendar day is "today".
@@ -682,24 +1168,31 @@ function computeTurnSpend(events, billing, catalog, messageId) {
 */
 function computeTodaySpend(events, billing, catalog, now = /* @__PURE__ */ new Date()) {
 	const day = beijingDayKey(now);
-	return priceEvents(events, billing, new Map(catalog.map((model) => [model.id, model.name])), day);
+	const folder = new BillingFolder(billing, catalog);
+	for (const event of events) {
+		if (beijingPartsOf(event.time).dayKey > day) continue;
+		folder.add(event);
+	}
+	return folder.fold.dayKey === day ? folder.fold.spend : emptyTodaySpend();
 }
 //#endregion
 //#region lib/types/projection.js
 /**
-* `billingTodaySpend` session-projection unit: per-session, per-Beijing-day
-* billed spend, folded eagerly by the DSH projection drive over committed
-* session events and checkpointed by the projection cache. The unit keeps only
-* the spend of the session's LATEST priced day (events are append-only and
-* chronological, so a day strictly older than the state's day never returns);
-* the aggregate "today" read sums the units whose `dayKey` matches the current
-* Beijing day — zero full-log scans once the fold is warm.
+* `billingTodaySpend` session-projection unit: per-session billed spend,
+* folded eagerly by the DSH projection drive over committed session events and
+* checkpointed by the projection cache. The state keeps the session's LATEST
+* priced Beijing day, its whole-session total, the fork boundary, the latest
+* request model, and the last priced attempt sample (DSH's same-step
+* replacement rule); the aggregate "today" read sums the units whose `dayKey`
+* matches the current Beijing day — zero full-log scans once the fold is warm.
 *
-* The unit's fold shares {@link priceEvent} with the events-scan paths
-* (`computeTodaySpend`), so both price with the same table. The unit is
+* The unit's fold IS the shared pricing fold ({@link applyBillingEvent}), so
+* the projection path and the events-scan paths cannot drift. The unit is
 * client-visible (`wire` = identity) because the persisted-cache read ladder
-* (`sessionProjectionCache.coldSnapshot` / registry `restore`) serves only
-* wired units; the wire value is the state itself.
+* (`sessionProjectionCache.cachedSnapshot` / registry `restore`) serves only
+* wired units, and because the browser half reads this value through
+* `useProjection` instead of polling a Remote; the wire value is the state
+* itself.
 * @module @rayadesu/dsh-llm-billing/projection
 */
 /** The projection key this unit owns. */
@@ -723,16 +1216,27 @@ const todaySpendSchema = z$1.object({
 }).strict();
 const billingUnitSchema = z$1.object({
 	dayKey: z$1.string(),
-	spend: todaySpendSchema
+	spend: todaySpendSchema,
+	session: todaySpendSchema,
+	inheritedEventCount: z$1.number().int().nonnegative(),
+	model: z$1.string(),
+	last: z$1.object({
+		turn: z$1.number().int().nonnegative(),
+		step: z$1.number().int().nonnegative(),
+		dayKey: z$1.string(),
+		spend: todaySpendSchema
+	}).strict().nullable()
 }).strict();
 /**
-* Build the `billingTodaySpend` unit for one resolved pricing table. The
-* pricing closure is fixed at registration; a pricing-table change therefore
-* prices only events folded after the change (historical spend keeps its
-* historical rates), unlike the events-scan paths which re-price the whole
-* log. Bump {@link ProjectionDefinition.stateVersion} whenever the state
-* shape or fold semantics change, so persisted checkpoint rows are discarded
-* instead of folded forward.
+* Build the `billingTodaySpend` unit for one resolved pricing table. Published
+* rate revisions travel inside the closure and are resolved per sample
+* timestamp, so a re-priced series bills its own history correctly however late
+* a log is folded; only a configuration change (editing `billing.models`) is
+* fixed at registration, and it re-prices just the events folded afterwards
+* (the events-scan paths re-price the whole log). Bump
+* {@link ProjectionDefinition.stateVersion} whenever the state shape or fold
+* semantics change, so persisted checkpoint rows are discarded instead of
+* folded forward.
 * @param billing - resolved pricing with peak-hour windows.
 * @param catalog - model display rows, in presentation order.
 * @returns the unit definition to register on `ctx.sessionProjections`.
@@ -741,25 +1245,10 @@ function billingTodaySpendDefinition(billing, catalog) {
 	const names = new Map(catalog.map((model) => [model.id, model.name]));
 	return {
 		key: BILLING_UNIT_KEY,
-		stateVersion: 1,
+		stateVersion: 4,
 		stateSchema: billingUnitSchema,
-		init: () => ({
-			dayKey: "",
-			spend: emptyTodaySpend()
-		}),
-		apply: (state, event) => {
-			const priced = priceEvent(event, billing, names);
-			if (priced === void 0) return state;
-			if (state.dayKey === priced.dayKey) return {
-				dayKey: state.dayKey,
-				spend: addEventContribution(state.spend, priced)
-			};
-			if (state.dayKey !== "" && priced.dayKey < state.dayKey) return state;
-			return {
-				dayKey: priced.dayKey,
-				spend: addEventContribution(emptyTodaySpend(), priced)
-			};
-		},
+		init: (_header, inheritedEventCount) => emptyBillingFoldState(Number(inheritedEventCount ?? 0)),
+		apply: (state, event) => applyBillingEvent(state, event, billing, names),
 		wire: {
 			viewSchema: billingUnitSchema,
 			view: (state) => state
@@ -800,11 +1289,13 @@ function foldOwnBilling(unit, events, seedLength = 0) {
 * compute the aggregate behind a cache miss:
 *
 * - projection path (plan C): live sessions read their eagerly folded
-*   `billingTodaySpend` projection cell; cold sessions resolve through the
-*   projection-cache ladder (cached row + tail replay + registry restore,
-*   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.
+*   `billingTodaySpend` projection cell; cold sessions are answered from the
+*   zero-I/O projection-cache row whenever that row's own day is not the
+*   queried one, and otherwise resolved through 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 — and a
+*   failed resolution is remembered by revision instead of being retried on
+*   every 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
@@ -816,14 +1307,15 @@ function foldOwnBilling(unit, events, seedLength = 0) {
 * unchanged log provably cannot change the aggregate.
 *
 * Forked sessions never double-count: a fork child's log opens with a
-* verbatim copy of its source session's events (its inherited boundary),
-* so the scanner prices only the child's OWN events on every path — the
-* projection path bypasses the eager cell for a seeded session and folds its
-* own events instead (the cell covers the inherited prefix too), and the cold
-* ladder skips the projection cache for a seeded session (its cached row
-* predates the boundary and covers inherited events). The boundary is the
-* durable session state, read across both DSH runtime families — a resumed
-* fork child keeps its original boundary and an unseeded session stays at 0.
+* verbatim copy of its source session's events (its inherited boundary), so
+* the scanner prices only the child's OWN events on every path. The
+* `billingTodaySpend` unit is boundary-aware (its state carries the inherited
+* cut, and `apply` skips events below it), so the eager cell is correct for a
+* fork child; the cold path skips the projection cache for a seeded session
+* (its cached row may predate the boundary) and folds its own events with the
+* durable cut instead. The boundary is the durable session state, read across
+* both DSH runtime families — a resumed fork child keeps its original
+* boundary and an unseeded session stays at 0.
 *
 * The live `Session` log surface changed in 0.1.2-alpha.4: `Session.events`
 * was removed and replaced by `Session.snapshotEvents()` / `ownEvents()`, and
@@ -862,6 +1354,15 @@ function liveSessionEvents(session) {
 	if (session.snapshotEvents !== void 0) return session.snapshotEvents();
 	throw new Error("llm-billing: session log surface is neither Session.events nor Session.snapshotEvents");
 }
+/**
+* Unwrap a handle read across both return shapes.
+* @param read - the handle's read result.
+* @returns the event array.
+*/
+function handleReadEvents(read) {
+	if (Array.isArray(read)) return read;
+	return read.events;
+}
 function isHandlePersistence(persistence) {
 	return typeof persistence.open === "function";
 }
@@ -888,7 +1389,7 @@ async function persistenceInspect(persistence, id) {
 		const handle = await persistence.open(id, "read");
 		try {
 			return {
-				events: await handle.read(),
+				events: handleReadEvents(await handle.read()),
 				seedLength: forkBoundaryOf(handle)
 			};
 		} finally {
@@ -952,7 +1453,7 @@ var TodaySpendCache = class {
 		const now = this.now();
 		const dayKey = beijingDayKey(now);
 		if (!force && this.cachedDayKey === dayKey && this.cachedValue !== void 0 && now.getTime() - this.cachedAt < this.ttlMs) return Promise.resolve(this.cachedValue);
-		if (!force && this.inFlight !== void 0) return this.inFlight;
+		if (this.inFlight !== void 0) return this.inFlight;
 		const run = (async () => {
 			try {
 				const value = await this.scan(dayKey);
@@ -964,10 +1465,24 @@ var TodaySpendCache = class {
 				this.inFlight = void 0;
 			}
 		})();
-		if (!force) this.inFlight = run;
+		this.inFlight = run;
 		return run;
 	}
 };
+/** Max session-ids kept in the scanner's cold-resolution cache before eviction. */
+const COLD_RESOLVE_CACHE_LIMIT = 1024;
+/** Max session-ids kept in the scanner's cold-failure cache before eviction. */
+const COLD_FAILED_CACHE_LIMIT = 1024;
+/**
+* Bounded-map eviction: drop the oldest inserted entry once `size` reached
+* `limit`. Evicting one entry (instead of clearing) keeps the other sessions'
+* resolved state warm across scans.
+*/
+function evictOldest$1(map, limit) {
+	if (map.size < limit) return;
+	const oldest = map.keys().next().value;
+	if (oldest !== void 0) map.delete(oldest);
+}
 /**
 * The aggregate computation behind a cache miss. Chooses the projection path
 * when the projection registry is composed, the events path otherwise; both
@@ -978,10 +1493,10 @@ var TodaySpendScanner = class {
 	deps;
 	/** Cold sessions resolved on the projection path: id → revision + unit state + title. */
 	coldResolved = /* @__PURE__ */ new Map();
+	/** Cold sessions whose resolution failed: id → revision (retried only when the log changes). */
+	coldFailed = /* @__PURE__ */ new Map();
 	/** Cold sessions resolved on the events path: id → revision (events were collected). */
 	lastEventsScan;
-	/** Live fork children priced on the projection path: id → own-events count + folded state. */
-	ownStates = /* @__PURE__ */ new Map();
 	constructor(deps) {
 		this.deps = deps;
 	}
@@ -991,9 +1506,7 @@ var TodaySpendScanner = class {
 	* @returns today's spend across every session.
 	*/
 	async scan(dayKey) {
-		if (this.deps.projections?.() === void 0) return this.scanEvents(dayKey);
-		this.deps.ensureUnit?.();
-		return this.scanProjections(dayKey);
+		return (await this.scanDetail(dayKey)).aggregate;
 	}
 	/**
 	* Compute today's per-session spend for one Beijing day, sorted by cost
@@ -1003,157 +1516,169 @@ var TodaySpendScanner = class {
 	* @returns today's per-session rows, highest first.
 	*/
 	async scanSessions(dayKey) {
-		const rows = this.deps.projections?.() === void 0 ? await this.scanSessionsEvents(dayKey) : await this.scanSessionsProjections(dayKey);
-		rows.sort((left, right) => right.total - left.total);
-		return { sessions: rows };
+		return { sessions: (await this.scanDetail(dayKey)).sessions };
 	}
 	/**
-	* 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. A SEEDED session (fork child)
-	* skips the ladder entirely: its cached row was folded over the inherited
+	* Compute the day's aggregate AND its per-session ranking in ONE pass: the
+	* aggregate is the sum of the rows, so the two reads share every session
+	* read, unit fold, and title fold instead of scanning twice. Chooses the
+	* projection path when the projection registry is composed, the events path
+	* otherwise.
+	* @param dayKey - the Beijing-time calendar-day key to aggregate.
+	* @returns the aggregate plus per-session rows sorted by cost descending.
+	*/
+	async scanDetail(dayKey) {
+		if (this.deps.projections?.() === void 0) return this.scanDetailEvents(dayKey);
+		this.deps.ensureUnit?.();
+		return this.scanDetailProjections(dayKey);
+	}
+	/**
+	* Resolve one cold session's billing unit state and display title.
+	*
+	* The zero-I/O projection-cache row answers the query directly whenever its
+	* own latest priced day is NOT the queried day: the row then proves the
+	* session contributed nothing to the queried day, so the log is never read.
+	* When the row IS the queried day (or no usable row exists) the session is
+	* inspected and folded locally, because the row may trail the log (a crash
+	* between the last checkpoint and the session's last event).
+	*
+	* A cache-served value carries no title (the ladder only stores projection
+	* values), so such rows report `title: null`. A SEEDED session (fork child)
+	* skips the cache entirely: its cached row was folded over the inherited
 	* prefix too, so it always detaches through inspect with the durable
 	* boundary (the inspect result's inherited count or `meta.seedLength`,
 	* depending on the runtime family) applied to the local fold.
-	* @param id - the cold session's id.
-	* @param seeded - whether the session carries a fork-inherited prefix
-	*   (from the snapshot header: `isSeeded` on 0.1.2-alpha.4+, `seedLength`
-	*   at and before the 0.1.1-rc.2 baseline).
+	* @param header - the listed session header (the cache identity witness).
+	* @param seeded - whether the session carries a fork-inherited prefix.
+	* @param dayKey - the Beijing-time day being aggregated.
 	* @returns the resolved state and title, or `undefined` when unreadable.
 	*/
-	async resolveCold(id, seeded) {
+	async resolveCold(header, seeded, dayKey) {
 		const { persistence, projectionCache, logger } = this.deps;
-		const persistenceService = persistence?.();
-		if (persistenceService === void 0) return void 0;
 		if (!seeded) {
 			const cache = projectionCache?.();
 			if (cache !== void 0) try {
-				const value = (await cache.coldSnapshot(id)).values[BILLING_UNIT_KEY];
-				if (value !== void 0) return {
+				const value = cache.cachedSnapshot(header, 0, [BILLING_UNIT_KEY])?.values[BILLING_UNIT_KEY];
+				if (value !== void 0 && value.dayKey !== dayKey) return {
 					value,
 					title: null
 				};
 			} catch (error) {
-				logger.warn(`llm-billing: projection cold read for session ${id} failed: ${String(error)}`);
+				logger.warn(`llm-billing: projection cache read for session ${header.id} failed: ${String(error)}`);
 			}
 		}
+		const persistenceService = persistence?.();
+		if (persistenceService === void 0) return void 0;
 		try {
-			const read = await persistenceInspect(persistenceService, id);
+			const read = await persistenceInspect(persistenceService, header.id);
 			return {
 				value: foldOwnBilling(this.deps.unit, read.events, read.seedLength),
 				title: foldSessionTitle(read.events)
 			};
 		} catch (error) {
-			logger.warn(`llm-billing: skipping unreadable session ${id}: ${String(error)}`);
+			logger.warn(`llm-billing: skipping unreadable session ${header.id}: ${String(error)}`);
 			return;
 		}
 	}
 	/**
-	* Fold one fork child's OWN events (its log minus the inherited prefix)
-	* with the billing unit, incrementally: the fold is reused while the log
-	* length is unchanged and only the new tail is applied when it grows.
-	* @param id - the session id (the own-state cache key).
-	* @param events - the session's complete log.
-	* @param seedLength - the inherited-prefix boundary.
-	* @returns the unit state over the session's own events.
+	* Live-session entries of one projection-path scan: each session with its
+	* eager `billingTodaySpend` cell. The cell is boundary-aware (the unit skips
+	* a fork child's inherited prefix), so a fork child reads the same own-event
+	* spend a non-fork session does.
 	*/
-	ownBillingState(id, events, seedLength) {
-		const cached = this.ownStates.get(id);
-		const ownCount = events.length - seedLength;
-		if (cached !== void 0 && cached.count === ownCount) return cached.state;
-		let state;
-		if (cached !== void 0 && cached.count < ownCount) {
-			state = cached.state;
-			for (const event of events) {
-				if (event.seq < seedLength + cached.count) continue;
-				state = this.deps.unit.apply(state, event);
-			}
-		} else state = foldOwnBilling(this.deps.unit, events, seedLength);
-		this.ownStates.set(id, {
-			count: ownCount,
-			state
-		});
-		return state;
+	*liveBillingEntries(store, projections) {
+		for (const session of store.list()) yield {
+			session,
+			state: projections?.stateOf(session, BILLING_UNIT_KEY)
+		};
 	}
-	/** Projection path: eager cells for live sessions, revision-gated cold ladder for the rest. */
-	async scanProjections(dayKey) {
-		const { sessions, persistence, projections } = this.deps;
-		const projectionsService = projections?.();
-		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 seedLength = forkBoundaryOf(session);
-				const state = seedLength > 0 ? this.ownBillingState(session.id, liveSessionEvents(session), seedLength) : projectionsService?.stateOf(session, BILLING_UNIT_KEY);
-				if (state !== void 0 && state.dayKey === dayKey) total = mergeTodaySpend(total, state.spend);
-			}
-		}
-		const persistenceService = persistence?.();
-		if (persistenceService === void 0) return total;
-		const snapshots = await persistenceListSnapshots(persistenceService);
+	/**
+	* Cold-ladder adopt: for every stored session not live, either the
+	* revision-gated resolution already in {@link coldResolved} is adopted
+	* (unchanged log costs nothing) or the session is queued behind a bounded
+	* parallel fan-out, resolved, remembered, and then adopted. A session whose
+	* resolution failed is remembered too (by revision), so an unreadable log
+	* is not re-read on every scan; a changed revision retries it. One
+	* unreadable session never blanks the whole-day aggregate.
+	* @param liveIds - ids of sessions already folded from the live store.
+	* @param snapshots - stored snapshot list (either runtime family).
+	* @param dayKey - the Beijing-time day being aggregated.
+	* @param adopt - fold one resolved cold session into the scan's result.
+	*/
+	async coldAdopt(liveIds, snapshots, dayKey, adopt) {
+		const persistenceAvailable = this.deps.persistence?.() !== void 0;
 		const pending = [];
 		for (const { header, revision } of snapshots) {
 			if (liveIds.has(header.id)) continue;
 			const seeded = isSeededSession(header);
 			const resolved = this.coldResolved.get(header.id);
 			if (resolved !== void 0 && resolved.revision === revision) {
-				if (resolved.value.dayKey === dayKey) total = mergeTodaySpend(total, resolved.value.spend);
+				adopt(header.id, resolved);
 				continue;
 			}
+			if (this.coldFailed.get(header.id) === revision) continue;
 			pending.push({
-				id: header.id,
+				header,
 				revision,
 				seeded
 			});
 		}
-		await withConcurrency(pending, 8, async ({ id, revision, seeded }) => {
-			const resolved = await this.resolveCold(id, seeded);
-			if (resolved !== void 0) this.coldResolved.set(id, {
-				revision,
-				...resolved
-			});
+		await withConcurrency(pending, 8, async ({ header, revision, seeded }) => {
+			const resolved = await this.resolveCold(header, seeded, dayKey);
+			if (resolved !== void 0) {
+				this.coldFailed.delete(header.id);
+				evictOldest$1(this.coldResolved, COLD_RESOLVE_CACHE_LIMIT);
+				this.coldResolved.set(header.id, {
+					revision,
+					...resolved
+				});
+			} else if (persistenceAvailable) {
+				evictOldest$1(this.coldFailed, COLD_FAILED_CACHE_LIMIT);
+				this.coldFailed.set(header.id, revision);
+			}
 		});
-		for (const { id } of pending) {
-			const resolved = this.coldResolved.get(id);
-			if (resolved !== void 0 && resolved.value.dayKey === dayKey) total = mergeTodaySpend(total, resolved.value.spend);
+		for (const { header } of pending) {
+			const resolved = this.coldResolved.get(header.id);
+			if (resolved !== void 0) adopt(header.id, resolved);
 		}
-		return total;
 	}
 	/**
-	* Events path: price today's events in a single pass (per-event Beijing-day
-	* filter during collection, hard cap), gated by revisions. A fork child's
-	* inherited prefix (`seq < seedLength`) is skipped, so each model output is
-	* priced only in its source session.
+	* Events-path collection shared by both aggregate and per-session scans:
+	* fold each session's log with the shared pricing fold (attempt samples with
+	* same-step replacement) and announce the session's latest-day spend, gated
+	* by revisions — a persisted session whose log did not change since the last
+	* scan is skipped. A fork child's inherited prefix (`seq < seedLength`) is
+	* skipped, so each model output is priced only in its source session. The
+	* hard cap counts the queried day's events; the revision watermark only
+	* advances on a complete pass.
+	* @param dayKey - the Beijing-time calendar-day key to aggregate.
+	* @param onSession - fold one session's state plus its complete log.
+	* @returns whether the hard cap truncated the scan.
 	*/
-	async scanEvents(dayKey) {
+	async collectTodayEvents(dayKey, onSession) {
 		const { sessions, persistence, maxEvents, logger, billing, catalog } = this.deps;
-		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, seedLength) => {
+		const collect = (id, events, seedLength) => {
+			const folder = new BillingFolder(billing, catalog, seedLength);
 			for (const event of events) {
-				if (event.seq < seedLength) continue;
-				if (beijingDayKey(new Date(event.time)) !== dayKey) continue;
-				collected += 1;
-				if (collected > maxEvents) {
-					truncated = true;
-					return;
+				if (beijingPartsOf(event.time).dayKey === dayKey) {
+					collected += 1;
+					if (collected > maxEvents) {
+						truncated = true;
+						break;
+					}
 				}
-				const priced = priceEvent(event, billing, names);
-				if (priced !== void 0) accumulator.add(priced);
+				folder.add(event);
 			}
+			onSession(id, folder.fold, events);
 		};
 		if (sessions !== void 0) {
 			const store = sessions();
 			if (store !== void 0) for (const session of store.list()) {
 				liveIds.add(session.id);
-				collect(liveSessionEvents(session), forkBoundaryOf(session));
+				collect(session.id, liveSessionEvents(session), forkBoundaryOf(session));
 				if (truncated) break;
 			}
 		}
@@ -1165,7 +1690,7 @@ var TodaySpendScanner = class {
 				if (this.lastEventsScan?.get(header.id) === revision) continue;
 				try {
 					const read = await persistenceInspect(persistenceService, header.id);
-					collect(read.events, read.seedLength);
+					collect(header.id, read.events, read.seedLength);
 				} catch (error) {
 					logger.warn(`llm-billing: skipping unreadable session ${header.id}: ${String(error)}`);
 				}
@@ -1174,146 +1699,87 @@ 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 accumulator.finish();
+		return truncated;
 	}
 	/**
-	* 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). A fork child's row prices
-	* its OWN events only (the cell covers the inherited prefix too).
+	* Projection path, one pass for both outputs: 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 answered from the projection cache). A fork child's cell covers its
+	* inherited prefix, so its own-events fold supplies both outputs.
 	* @param dayKey - the Beijing-time calendar-day key to aggregate.
-	* @returns unsorted per-session rows for the day.
+	* @returns the aggregate plus per-session rows, sorted by cost descending.
 	*/
-	async scanSessionsProjections(dayKey) {
+	async scanDetailProjections(dayKey) {
 		const { sessions, persistence, projections } = this.deps;
 		const projectionsService = projections?.();
+		let aggregate = emptyTodaySpend();
 		const rows = /* @__PURE__ */ new Map();
 		const liveIds = /* @__PURE__ */ new Set();
 		if (sessions !== void 0) {
 			const store = sessions();
-			if (store !== void 0) for (const session of store.list()) {
+			if (store !== void 0) for (const { session, state } of this.liveBillingEntries(store, projectionsService)) {
 				liveIds.add(session.id);
-				const seedLength = forkBoundaryOf(session);
-				const events = liveSessionEvents(session);
-				const state = seedLength > 0 ? this.ownBillingState(session.id, events, seedLength) : projectionsService?.stateOf(session, BILLING_UNIT_KEY);
-				if (state !== void 0 && state.dayKey === dayKey) rows.set(session.id, {
+				if (state === void 0 || state.dayKey !== dayKey) continue;
+				aggregate = mergeTodaySpend(aggregate, state.spend);
+				rows.set(session.id, {
 					sessionId: session.id,
-					title: foldSessionTitle(events),
+					title: foldSessionTitle(liveSessionEvents(session)),
 					total: state.spend.total
 				});
 			}
 		}
 		const persistenceService = persistence?.();
-		if (persistenceService === void 0) return [...rows.values()];
-		const snapshots = await persistenceListSnapshots(persistenceService);
-		const pending = [];
-		for (const { header, revision } of snapshots) {
-			if (liveIds.has(header.id)) continue;
-			const seeded = isSeededSession(header);
-			const resolved = this.coldResolved.get(header.id);
-			if (resolved !== void 0 && resolved.revision === revision) {
-				if (resolved.value.dayKey === dayKey) rows.set(header.id, {
-					sessionId: header.id,
+		if (persistenceService !== void 0) {
+			const snapshots = await persistenceListSnapshots(persistenceService);
+			await this.coldAdopt(liveIds, snapshots, dayKey, (id, resolved) => {
+				if (resolved.value.dayKey !== dayKey) return;
+				aggregate = mergeTodaySpend(aggregate, resolved.value.spend);
+				rows.set(id, {
+					sessionId: id,
 					title: resolved.title,
 					total: resolved.value.spend.total
 				});
-				continue;
-			}
-			pending.push({
-				id: header.id,
-				revision,
-				seeded
 			});
 		}
-		await withConcurrency(pending, 8, async ({ id, revision, seeded }) => {
-			const resolved = await this.resolveCold(id, seeded);
-			if (resolved !== void 0) this.coldResolved.set(id, {
-				revision,
-				...resolved
-			});
-		});
-		for (const { id } of pending) {
-			const resolved = this.coldResolved.get(id);
-			if (resolved !== void 0 && resolved.value.dayKey === dayKey) rows.set(id, {
-				sessionId: id,
-				title: resolved.title,
-				total: resolved.value.spend.total
-			});
-		}
-		return [...rows.values()];
+		return {
+			aggregate,
+			sessions: sortRows(rows)
+		};
 	}
 	/**
-	* 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. A fork child's inherited prefix
-	* (`seq < seedLength`) is skipped, so each row is the session's OWN spend.
-	* 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.
+	* Events path, one pass for both outputs: price today's events (per-event
+	* Beijing-day filter during collection, hard cap), gated by revisions. A
+	* fork child's inherited prefix (`seq < seedLength`) is skipped, so each
+	* model output is priced only in its source session. 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.
+	* @returns the aggregate plus per-session rows, sorted by cost descending.
 	*/
-	async scanSessionsEvents(dayKey) {
-		const { sessions, persistence, maxEvents, logger, billing, catalog } = this.deps;
-		const names = new Map(catalog.map((model) => [model.id, model.name]));
-		const rows = /* @__PURE__ */ new Map();
-		const liveIds = /* @__PURE__ */ new Set();
-		let collected = 0;
-		let truncated = false;
-		const collect = (id, events, seedLength) => {
-			let row = rows.get(id);
-			if (row === void 0) {
-				row = {
-					title: foldSessionTitle(events),
-					total: 0
-				};
-				rows.set(id, row);
-			}
-			for (const event of events) {
-				if (event.seq < seedLength) continue;
-				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) row.total += priced.cost;
-			}
+	async scanDetailEvents(dayKey) {
+		let aggregate = emptyTodaySpend();
+		const sessions = [];
+		await this.collectTodayEvents(dayKey, (id, fold, events) => {
+			if (fold.dayKey !== dayKey) return;
+			aggregate = mergeTodaySpend(aggregate, fold.spend);
+			sessions.push({
+				sessionId: id,
+				title: foldSessionTitle(events),
+				total: fold.spend.total
+			});
+		});
+		sessions.sort((left, right) => right.total - left.total);
+		return {
+			aggregate,
+			sessions
 		};
-		if (sessions !== void 0) {
-			const store = sessions();
-			if (store !== void 0) for (const session of store.list()) {
-				liveIds.add(session.id);
-				collect(session.id, liveSessionEvents(session), forkBoundaryOf(session));
-				if (truncated) break;
-			}
-		}
-		const persistenceService = persistence?.();
-		if (!truncated && persistenceService !== void 0) {
-			const snapshots = await persistenceListSnapshots(persistenceService);
-			for (const { header, revision } of snapshots) {
-				if (liveIds.has(header.id)) continue;
-				if (this.lastEventsScan?.get(header.id) === revision) continue;
-				try {
-					const read = await persistenceInspect(persistenceService, header.id);
-					collect(header.id, read.events, read.seedLength);
-				} catch (error) {
-					logger.warn(`llm-billing: skipping unreadable session ${header.id}: ${String(error)}`);
-				}
-				if (truncated) break;
-			}
-			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 [...rows.entries()].filter(([, row]) => row.total > 0).map(([sessionId, row]) => ({
-			sessionId,
-			title: row.title,
-			total: row.total
-		}));
 	}
 };
+/** Per-session rows from the map, highest total first. */
+function sortRows(rows) {
+	return [...rows.values()].sort((left, right) => right.total - left.total);
+}
 //#endregion
 //#region lib/types/index.js
 /**
@@ -1343,11 +1809,26 @@ const DEFAULT_API_KEY_ENV = "DEEPSEEK_API_KEY";
 const BASE_URL_ENV = "DEEPSEEK_BASE_URL";
 /** Public API default; deployments may point elsewhere via $DEEPSEEK_BASE_URL. */
 const PUBLIC_BASE_URL = "https://api.deepseek.com";
+/**
+* Advisory display rows mirroring the DSH `llm-deepseek` catalog (V4.1 Flash
+* first, its current default route), plus the MiMo-V2.5 series. The retired
+* preview id `deepseek-v4.1-flash-expires-on-0910` stays so the logs that used
+* it keep a readable label; rows never restrict which models are priced — the
+* pricing table does.
+*/
 const DEFAULT_MODELS = [
+	{
+		id: "deepseek-flash",
+		name: "DeepSeek-V41-Flash"
+	},
 	{
 		id: "deepseek-v4-flash",
 		name: "DeepSeek-V4-Flash"
 	},
+	{
+		id: "deepseek-v4.1-flash-expires-on-0910",
+		name: "DeepSeek-V4.1-Flash"
+	},
 	{
 		id: "deepseek-v4-pro",
 		name: "DeepSeek-V4-Pro"
@@ -1374,16 +1855,18 @@ const tokenPrice = z.object({
 	cacheMissInput: z.number().min(0),
 	output: z.number().min(0)
 });
+const billingRateRow = z.object({
+	model: z.string().required(),
+	peak: tokenPrice,
+	offPeak: tokenPrice,
+	effectiveFrom: z.number().min(0)
+});
 const billingConfig = z.object({
 	peakHours: z.array(z.object({
 		start: z.number().step(1).min(0).max(23),
 		end: z.number().step(1).min(0).max(24)
-	})).default(DEFAULT_PEAK_HOURS),
-	models: z.array(z.object({
-		model: z.string().required(),
-		peak: tokenPrice,
-		offPeak: tokenPrice
-	})).default(DEFAULT_MODEL_PRICING)
+	})).default([...DEFAULT_PEAK_HOURS]),
+	models: z.array(billingRateRow).default([...DEFAULT_MODEL_PRICING])
 });
 const Config = z.object({
 	apiKeyEnv: z.string().role("credential-ref").default(DEFAULT_API_KEY_ENV),
@@ -1395,6 +1878,25 @@ const Config = z.object({
 const TODAY_SPEND_CACHE_MS = 6e4;
 /** Hard cap on today's events collected by the events scan path. */
 const TODAY_SPEND_MAX_EVENTS = 2e5;
+/** Max session-spend rows kept for incremental recompute before eviction. */
+const SESSION_SPEND_CACHE_LIMIT = 1024;
+/** Max session-id entries kept in the per-turn-cost fold cache before eviction. */
+const SESSION_TURN_SPEND_CACHE_LIMIT = 64;
+/** How long one balance snapshot is reused before the host refetches it (15s). */
+const BALANCE_CACHE_MS = 15e3;
+/** Hard cap on one `/user/balance` request (5s); a hung endpoint never blocks the badge. */
+const BALANCE_TIMEOUT_MS = 5e3;
+/**
+* Bounded-map eviction: drop the oldest inserted entry once `size` reached
+* `limit`, so an unbounded session-id space grows the map no further. Evicting
+* one entry (instead of clearing) keeps the other sessions' incremental
+* spend warm.
+*/
+function evictOldest(map, limit) {
+	if (map.size < limit) return;
+	const oldest = map.keys().next().value;
+	if (oldest !== void 0) map.delete(oldest);
+}
 /**
 * Read one session's event log and durable seed boundary: the live
 * SessionStore first, then the persistence backend for a flushed session
@@ -1421,65 +1923,111 @@ async function sessionEvents(ctx, sessionId) {
 	}
 	throw new LlmError(`llm-billing: session ${sessionId} not found`, "NOT_FOUND");
 }
+/** Resolve the plugin's static facts once: endpoint, credential ref, pricing table. */
+function resolveFacts(ctx, config) {
+	return {
+		baseURL: () => config.baseURL ?? launchEnvironmentOf(ctx).get(BASE_URL_ENV)?.value ?? "https://api.deepseek.com",
+		apiKeyRef: credentialRef(config.apiKeyEnv ?? DEFAULT_API_KEY_ENV),
+		billing: resolveBilling(config.billing),
+		catalog: (config.models ?? DEFAULT_MODELS).map((model) => ({
+			id: model.id,
+			name: model.name ?? model.id
+		}))
+	};
+}
 /**
-* Register the `billing` Remote under the `billing` namespace.
-* @param ctx - owning plugin context.
-* @param config - validated plugin config.
+* Resolve the API key per call: the credentials service first, then the
+* launch environment fallback.
+* @throws {@link LlmError} with code `MISSING_CREDENTIAL` when neither yields a usable key.
 */
-function apply(ctx, config) {
-	const baseURL = () => config.baseURL ?? launchEnvironmentOf(ctx).get(BASE_URL_ENV)?.value ?? "https://api.deepseek.com";
-	const apiKeyRef = credentialRef(config.apiKeyEnv ?? DEFAULT_API_KEY_ENV);
-	const resolveApiKey = async () => {
-		const credentials = ctx.get("credentials");
-		if (credentials !== void 0) {
-			const hit = await credentials.resolve(apiKeyRef);
-			if (hit !== void 0) return assertUsableApiKey(hit.value, "llm-billing", apiKeyRef);
-		} else {
-			const ambient = launchEnvironmentOf(ctx).get(apiKeyRef);
-			if (ambient !== void 0 && ambient.value.length > 0) return assertUsableApiKey(ambient.value, "llm-billing", apiKeyRef);
-		}
-		throw new LlmError(`llm-billing: no API key; store ${apiKeyRef} through the credentials service or export it`, "MISSING_CREDENTIAL");
-	};
-	const fetchBalance = async () => {
-		const apiKey = await resolveApiKey();
-		return fetchDeepSeekBalance(baseURL(), apiKey);
-	};
-	const billing = resolveBilling(config.billing);
-	const catalog = (config.models ?? DEFAULT_MODELS).map((model) => ({
-		id: model.id,
-		name: model.name ?? model.id
-	}));
+async function resolveApiKey(ctx, apiKeyRef) {
+	const credentials = ctx.get("credentials");
+	if (credentials !== void 0) {
+		const hit = await credentials.resolve(apiKeyRef);
+		if (hit !== void 0) return assertUsableApiKey(hit.value, "llm-billing", apiKeyRef);
+	} else {
+		const ambient = launchEnvironmentOf(ctx).get(apiKeyRef);
+		if (ambient !== void 0 && ambient.value.length > 0) return assertUsableApiKey(ambient.value, "llm-billing", apiKeyRef);
+	}
+	throw new LlmError(`llm-billing: no API key; store ${apiKeyRef} through the credentials service or export it`, "MISSING_CREDENTIAL");
+}
+/**
+* Per-session incremental spend loader: a session log is append-only and
+* chronological (the same assumption the projection unit makes), so a spend
+* computed for `count` EVENTS OF THE SESSION'S OWN WORK (the log minus its
+* inherited fork prefix) stays valid while the log length is unchanged, and
+* only the appended tail needs pricing when it grows. A forked child's
+* inherited prefix (`seq < seedLength`) is priced only in its source
+* session; the cache is bounded (see {@link evictOldest}), so an unbounded
+* session-id space cannot grow it without bound.
+*/
+function createSessionSpendFetcher(ctx, facts) {
 	const sessionSpendCache = /* @__PURE__ */ new Map();
-	const fetchSessionSpend = async (sessionId) => {
+	return async (sessionId) => {
 		const { events, seedLength } = await sessionEvents(ctx, sessionId);
 		const ownCount = events.length - seedLength;
 		const cached = sessionSpendCache.get(sessionId);
-		if (cached !== void 0 && cached.count === ownCount) return cached.spend;
+		if (cached !== void 0 && cached.count === ownCount) {
+			sessionSpendCache.delete(sessionId);
+			sessionSpendCache.set(sessionId, cached);
+			return cached.spend;
+		}
 		if (cached !== void 0 && cached.count < ownCount) {
-			const spend = mergeTodaySpend(cached.spend, computeSessionSpend(events.slice(seedLength + cached.count), billing, catalog));
+			const spend = mergeTodaySpend(cached.spend, computeSessionSpend(events.slice(seedLength + cached.count), facts.billing, facts.catalog));
+			evictOldest(sessionSpendCache, SESSION_SPEND_CACHE_LIMIT);
 			sessionSpendCache.set(sessionId, {
 				count: ownCount,
 				spend
 			});
 			return spend;
 		}
-		const spend = computeSessionSpend(events, billing, catalog, seedLength);
-		if (sessionSpendCache.size >= 1024) sessionSpendCache.clear();
+		const spend = computeSessionSpend(events, facts.billing, facts.catalog, seedLength);
+		evictOldest(sessionSpendCache, SESSION_SPEND_CACHE_LIMIT);
 		sessionSpendCache.set(sessionId, {
 			count: ownCount,
 			spend
 		});
 		return spend;
 	};
-	const unit = billingTodaySpendDefinition(billing, catalog);
-	let unitRegistered = false;
-	const ensureUnit = () => {
-		if (unitRegistered) return;
+}
+/**
+* Once-registrar for the billing projection unit: the first call that finds
+* the registry composed registers the shared unit and every later call is a
+* no-op. Registering as early as the registry exists lets DSH's projection
+* write-behind (mandatory at `turn/end`) checkpoint a billing row for every
+* session that runs in this process, which is what makes the zero-I/O cold
+* path in {@link TodaySpendScanner} hit after the next restart.
+* @param ctx - plugin context.
+* @param unit - the unit definition built once per plugin config.
+* @returns an idempotent registrar.
+*/
+function createUnitRegistrar(ctx, unit) {
+	let registered = false;
+	return () => {
+		if (registered) return;
 		const registry = ctx.get("sessionProjections");
 		if (registry === void 0) return;
 		registry.register(unit);
-		unitRegistered = true;
+		registered = true;
 	};
+}
+/**
+* Today-spend loaders over one revision-gated scanner with two 60s
+* Beijing-day caches (in-flight coalescing and a `force` bypass):
+* - plan C uses the per-session spend projection unit registered by the
+*   caller's {@link createUnitRegistrar} as early as the registry exists (the
+*   registry builds cells lazily over the in-memory log, so events committed
+*   before registration are folded on first touch); without the registry the
+*   events path serves today's spend.
+* - plans A1–A3: the scanner chooses the projection path when the registry
+*   is composed, the events path otherwise.
+* @param ctx - plugin context.
+* @param facts - resolved endpoint, credential, pricing, and catalog facts.
+* @param unit - the shared projection unit definition.
+* @param ensureUnit - idempotent unit registrar (last-resort registration).
+* @returns the two today-spend loaders.
+*/
+function createTodaySpendLoaders(ctx, facts, unit, ensureUnit) {
 	const scanner = new TodaySpendScanner({
 		sessions: () => ctx.get("sessions"),
 		persistence: () => ctx.get("sessionPersistence"),
@@ -1489,24 +2037,108 @@ function apply(ctx, config) {
 		unit,
 		maxEvents: TODAY_SPEND_MAX_EVENTS,
 		logger: ctx.logger,
-		billing,
-		catalog
+		billing: facts.billing,
+		catalog: facts.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);
-	const fetchTodaySessionsSpend = async (force = false) => todaySessionsCache.get(force);
-	const fetchTurnSpend = async (sessionId, messageId) => {
+	const todayCache = new TodaySpendCache((dayKey) => scanner.scanDetail(dayKey), TODAY_SPEND_CACHE_MS);
+	return {
+		fetchTodaySpend: async (force = false) => (await todayCache.get(force)).aggregate,
+		fetchTodaySessionsSpend: async (force = false) => ({ sessions: (await todayCache.get(force)).sessions })
+	};
+}
+/** One completed Turn's spend loader, located by its closing message id. */
+function createTurnSpendFetcher(ctx, facts) {
+	return async (sessionId, messageId) => {
 		const { events } = await sessionEvents(ctx, sessionId);
-		return computeTurnSpend(events, billing, catalog, messageId);
+		return computeTurnSpend(events, facts.billing, facts.catalog, messageId);
 	};
+}
+/**
+* Every completed Turn's cost in one session, folded incrementally per session
+* (session logs are append-only, so only the appended tail is priced on a
+* growing log). One call serves a whole transcript's per-message cost rows,
+* replacing the per-message `getTurnSpend` fan-out.
+*/
+function createTurnSpendsFetcher(ctx, facts) {
+	const folders = /* @__PURE__ */ new Map();
+	return async (sessionId) => {
+		const { events } = await sessionEvents(ctx, sessionId);
+		let entry = folders.get(sessionId);
+		if (entry === void 0 || entry.count > events.length) {
+			entry = {
+				folder: new SessionTurnSpendFolder(facts.billing, facts.catalog),
+				count: 0
+			};
+			evictOldest(folders, 64);
+			folders.set(sessionId, entry);
+		}
+		if (entry.count !== events.length) {
+			entry.folder.feed(events);
+			entry.count = events.length;
+		}
+		return entry.folder.finish();
+	};
+}
+/**
+* Balance loader with a short host-side TTL and a hard request timeout: the
+* credential resolves per call, a fresh snapshot is reused for
+* {@link BALANCE_CACHE_MS} (so several badge mounts and several browsers share
+* one `/user/balance` call), concurrent misses coalesce, and `force` bypasses
+* the TTL for the manual refresh. A hung endpoint aborts after
+* {@link BALANCE_TIMEOUT_MS} instead of holding the badge's fetch forever.
+* @param ctx - plugin context carrying the credential seam.
+* @param facts - resolved endpoint and credential facts.
+* @returns the balance loader.
+*/
+function createBalanceFetcher(ctx, facts) {
+	let cached;
+	let inflight;
+	return async (force = false) => {
+		if (!force && cached !== void 0 && Date.now() - cached.at < 15e3) return cached.value;
+		if (inflight !== void 0) return inflight;
+		const run = (async () => {
+			try {
+				const apiKey = await resolveApiKey(ctx, facts.apiKeyRef);
+				const value = await fetchDeepSeekBalance(facts.baseURL(), apiKey, AbortSignal.timeout(BALANCE_TIMEOUT_MS));
+				cached = {
+					at: Date.now(),
+					value
+				};
+				return value;
+			} finally {
+				inflight = void 0;
+			}
+		})();
+		inflight = run;
+		return run;
+	};
+}
+/**
+* Register the `billing` Remote under the `billing` namespace. Assembly only:
+* facts resolve once, each loader owns its caches, and the gateway receives
+* the bound thunks.
+* @param ctx - owning plugin context.
+* @param config - validated plugin config.
+*/
+function apply(ctx, config) {
+	const facts = resolveFacts(ctx, config);
+	const unit = billingTodaySpendDefinition(facts.billing, facts.catalog);
+	const ensureUnit = createUnitRegistrar(ctx, unit);
+	ensureUnit();
+	ctx.on("session/created", ensureUnit);
+	const fetchBalance = createBalanceFetcher(ctx, facts);
+	const fetchSessionSpend = createSessionSpendFetcher(ctx, facts);
+	const { fetchTodaySpend, fetchTodaySessionsSpend } = createTodaySpendLoaders(ctx, facts, unit, ensureUnit);
+	const fetchTurnSpend = createTurnSpendFetcher(ctx, facts);
+	const fetchTurnSpends = createTurnSpendsFetcher(ctx, facts);
 	new DeepSeekBalanceGateway(ctx, {
 		fetchBalance,
 		fetchSessionSpend,
 		fetchTodaySpend,
 		fetchTodaySessionsSpend,
-		fetchTurnSpend
+		fetchTurnSpend,
+		fetchTurnSpends
 	});
 }
 //#endregion
-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, computeTurnSpend, emptyTodaySpend, fetchDeepSeekBalance, foldBillingUnit, foldOwnBilling, foldSessionTitle, forkBoundaryOf, isPeak, isSeededSession, liveSessionEvents, mergeTodaySpend, name, parseDeepSeekBalance, persistenceInspect, persistenceListSnapshots, priceEvent, resolveBilling };
+export { BALANCE_CACHE_MS, BALANCE_TIMEOUT_MS, BILLING_UNIT_KEY, BillingFolder, Config, DEFAULT_MODEL_PRICING, DEFAULT_PEAK_HOURS, DeepSeekBalanceGateway, FLASH_SERIES_RATE_CHANGE_AT, PUBLIC_BASE_URL, SESSION_SPEND_CACHE_LIMIT, SESSION_TURN_SPEND_CACHE_LIMIT, SessionTurnSpendFolder, SpendAccumulator, TODAY_SPEND_CACHE_MS, TODAY_SPEND_MAX_EVENTS, TodaySpendCache, TodaySpendScanner, V4_PRO_ROUTE_SWITCH_AT, addEventContribution, apply, applyBillingEvent, beijingDayKey, billingTodaySpendDefinition, computeSessionSpend, computeSessionTurnSpends, computeTodaySpend, computeTurnSpend, emptyBillingFoldState, emptyTodaySpend, fetchDeepSeekBalance, foldBillingUnit, foldOwnBilling, foldSessionTitle, forkBoundaryOf, isPeak, isSeededSession, liveSessionEvents, mergeTodaySpend, name, negateSpend, parseDeepSeekBalance, persistenceInspect, persistenceListSnapshots, priceEvent, priceUsage, resolveBilling, subtractSpend };