@rayadesu/dsh-llm-billing 0.3.16 → 0.3.18

package/lib/index.js

@@ -92,14 +92,35 @@ function parseDeepSeekBalance(body) {
 	};
 }
 /**
-* Fetch one account-balance snapshot from `{baseURL}/user/balance`.
-* @param baseURL - resolved endpoint base; `/user/balance` is appended.
-* @param apiKey - resolved bearer token for this endpoint.
-* @param signal - optional cancellation.
-* @returns the validated balance snapshot.
-* @throws {@link LlmError} for transport, HTTP, or malformed-response failures.
+* Whether another attempt can plausibly succeed. Only faults transient BY
+* NATURE qualify: a dropped socket (no status), a rate limit, or a server-side
+* error. A settled 4xx is final — retrying a bad key three times only reports
+* the truth three times later.
 */
-async function fetchDeepSeekBalance(baseURL, apiKey, signal) {
+function isRetryableStatus(status) {
+	if (status === void 0) return true;
+	return status === 429 || status >= 500;
+}
+/** Wait `ms` before the next attempt, abandoning the wait if the caller aborts. */
+function waitBalanceRetry(ms, signal) {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted === true) {
+			reject(signal.reason);
+			return;
+		}
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(signal?.reason);
+		};
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+/** One balance request attempt, REPORTED rather than thrown so the caller decides. */
+async function requestBalanceOnce(baseURL, apiKey, signal) {
 	let response;
 	try {
 		response = await fetch(`${baseURL}/user/balance`, {
@@ -111,17 +132,59 @@ async function fetchDeepSeekBalance(baseURL, apiKey, signal) {
 			...signal === void 0 ? {} : { signal }
 		});
 	} catch (error) {
-		if (signal?.aborted) throw new LlmError("DeepSeek balance request aborted by caller", "ABORTED", { cause: error });
-		throw new LlmError(`DeepSeek balance request to ${baseURL} failed`, "TRANSPORT", { cause: error });
+		return {
+			ok: false,
+			status: void 0,
+			error: signal?.aborted === true ? new LlmError("DeepSeek balance request aborted by caller", "ABORTED", { cause: error }) : new LlmError(`DeepSeek balance request to ${baseURL} failed`, "TRANSPORT", { cause: error })
+		};
 	}
-	if (!response.ok) throw new LlmError(`DeepSeek balance request failed (HTTP ${response.status})`, httpErrorCode(response.status), { status: response.status });
+	if (!response.ok) return {
+		ok: false,
+		status: response.status,
+		error: new LlmError(`DeepSeek balance request failed (HTTP ${response.status})`, httpErrorCode(response.status), { status: response.status })
+	};
 	let body;
 	try {
 		body = await response.json();
 	} catch (error) {
-		throw new LlmError("DeepSeek balance response was not valid JSON", "TRANSPORT", { cause: error });
+		return {
+			ok: false,
+			status: response.status,
+			error: new LlmError("DeepSeek balance response was not valid JSON", "TRANSPORT", { cause: error })
+		};
+	}
+	return {
+		ok: true,
+		value: parseDeepSeekBalance(body)
+	};
+}
+/**
+* Fetch one account-balance snapshot from `{baseURL}/user/balance`.
+*
+* Retries the faults that can plausibly clear — a dropped socket, a 429, a 5xx
+* — up to {@link BALANCE_FETCH_ATTEMPTS} attempts, because the badge polls
+* every few minutes and one lost packet would otherwise blank the balance
+* until the next interval. Permanent answers (including a rejected key) fail
+* on the first attempt.
+* @param baseURL - resolved endpoint base; `/user/balance` is appended.
+* @param apiKey - resolved bearer token for this endpoint.
+* @param signal - optional cancellation.
+* @returns the validated balance snapshot.
+* @throws {@link LlmError} for transport, HTTP, or malformed-response failures.
+*/
+async function fetchDeepSeekBalance(baseURL, apiKey, signal) {
+	for (let attempt = 1;; attempt += 1) {
+		const outcome = await requestBalanceOnce(baseURL, apiKey, signal);
+		if (outcome.ok) return outcome.value;
+		const exhausted = attempt >= 3;
+		const aborted = signal?.aborted === true;
+		if (!exhausted && !aborted && isRetryableStatus(outcome.status)) {
+			await waitBalanceRetry(150 * 2 ** (attempt - 1), signal);
+			continue;
+		}
+		if (outcome.status === 401 || outcome.status === 403) throw new LlmError(`DeepSeek balance request was rejected (HTTP ${outcome.status}) — the API key in effect for ${baseURL} is missing or unauthorized (check DEEPSEEK_API_KEY)`, httpErrorCode(outcome.status), { status: outcome.status });
+		throw outcome.error;
 	}
-	return parseDeepSeekBalance(body);
 }
 /**
 * Remote-only service exposing the DeepSeek account balance and session spend.
@@ -323,20 +386,307 @@ let DeepSeekBalanceGateway = (() => {
 	};
 })();
 //#endregion
-//#region lib/types/billing.js
+//#region lib/types/beijing-time.js
+/**
+* Beijing wall-clock arithmetic (Asia/Shanghai: a fixed UTC+8, no DST) — the
+* calendar fields a sample's rate depends on, and the day boundaries a scan is
+* clipped to. Split out of `billing.ts`: pricing asks this module questions, it
+* never asks about pricing.
+* @module @rayadesu/dsh-llm-billing/beijing-time
+*/
+/** 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
+	};
+}
 /**
-* DeepSeek billing: the peak/off-peak pricing table and the per-session spend
-* pricing. Pure functions over session events and the pricing table, so the
-* Remote gateway stays transport-free and the whole spend is testable without
-* a key.
+* 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 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 {
+		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 beijingPartsOf(now.getTime()).dayKey;
+}
+/**
+* The Beijing calendar day NAMED by `dayKey` as an epoch-millisecond range:
+* `start` inclusive, `end` exclusive. Derived from the key itself rather than
+* from a clock, because a scan prices whatever day it was asked for — today,
+* or a day a caller is replaying.
 *
-* 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
+* The conversion needs no calendar arithmetic: `Date.UTC` builds midnight UTC
+* of that civil date, and Beijing midnight is a fixed offset earlier (no DST).
+* @param dayKey - a `YYYY-MM-DD` Beijing day key.
+* @returns the day's bounds, or `undefined` when the key is not that shape.
+*/
+function beijingDayRangeOfKey(dayKey) {
+	const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(dayKey);
+	if (match === null) return void 0;
+	const utcMidnight = Date.UTC(Number(match[1]), Number(match[2]) - 1, Number(match[3]));
+	if (Number.isNaN(utcMidnight)) return void 0;
+	return {
+		start: utcMidnight - BEIJING_OFFSET_MS,
+		end: utcMidnight + DAY_MS - BEIJING_OFFSET_MS
+	};
+}
+//#endregion
+//#region lib/types/spend.js
+/**
+* Spend arithmetic: how two spends combine, how one is inverted, and how the
+* samples that could NOT be priced are tallied beside them. Pure, and knowing
+* nothing about rates, timezones or event shapes — the pricing engine
+* (`billing.ts`) owns all of that.
+* @module @rayadesu/dsh-llm-billing/spend
+*/
+/** A spend with no priced usage. */
+function emptyTodaySpend() {
+	return {
+		total: 0,
+		models: []
+	};
+}
+/** Sum two usage tallies (pure); an absent side stays absent. */
+function mergeUsageTally(left, right) {
+	if (left === void 0) return right;
+	if (right === void 0) return left;
+	return {
+		events: left.events + right.events,
+		tokens: left.tokens + right.tokens,
+		models: [.../* @__PURE__ */ new Set([...left.models, ...right.models])]
+	};
+}
+/** Add one affected sample to a tally (pure). */
+function addUsageTally(previous, model, tokens) {
+	const models = previous?.models ?? [];
+	return {
+		events: (previous?.events ?? 0) + 1,
+		tokens: (previous?.tokens ?? 0) + tokens,
+		models: models.includes(model) ? models : [...models, model]
+	};
+}
+/**
+* The advisory tallies carried BESIDE the priced rows, summed over `spends` as
+* a partial you can spread into any spend literal. Keys stay absent rather
+* than becoming `undefined` (`exactOptionalPropertyTypes`), so a fully priced
+* spend stays structurally identical to what every existing test asserts.
+*/
+function usageTalliesOf(spends) {
+	let unpriced;
+	for (const spend of spends) unpriced = mergeUsageTally(unpriced, spend.unpriced);
+	return { ...unpriced === void 0 ? {} : { unpriced } };
+}
+/** Note one sample that matched no pricing row and was therefore not billed. */
+function noteUnpriced(spend, model, tokens) {
+	return {
+		total: spend.total,
+		models: spend.models,
+		unpriced: addUsageTally(spend.unpriced, model, tokens)
+	};
+}
+/** The today-spend shape of a single priced contribution. */
+function contributionModel(priced) {
+	return {
+		model: priced.model,
+		displayName: priced.displayName,
+		cost: priced.cost,
+		peakCost: priced.peakCost,
+		offPeakCost: priced.offPeakCost,
+		cacheHitInputTokens: priced.cacheHitInputTokens,
+		cacheMissInputTokens: priced.cacheMissInputTokens,
+		outputTokens: priced.outputTokens,
+		cacheHitInputCost: priced.cacheHitInputCost,
+		cacheMissInputCost: priced.cacheMissInputCost,
+		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()]
+		};
+	}
+};
+/** 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),
+		...usageTalliesOf([spend]),
+		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()],
+		...usageTalliesOf([target])
+	};
+}
+/** The contribution as a one-row spend (the shape a sample keeps for replacement). */
+function contributionSpend(priced) {
+	return {
+		total: priced.cost,
+		models: [contributionModel(priced)]
+	};
+}
+/**
+* Merge one priced event's contribution into an accumulator spend (pure:
+* returns a new spend, never mutates its input).
+* @param spend - the accumulator (per session and day, or across sessions).
+* @param priced - the priced contribution to add.
+* @returns the merged spend.
+*/
+function addEventContribution(spend, 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,
+		...usageTalliesOf([spend])
+	};
+}
+/**
+* Sum two spends (per session and day, or across sessions) into one (pure:
+* returns a new spend, never mutates its inputs).
+* @param target - the accumulator spend.
+* @param source - the spend to add.
+* @returns the summed spend.
+*/
+function mergeTodaySpend(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);
+		rows.set(row.model, existing === void 0 ? row : mergeModelRows(existing, row));
+	}
+	return {
+		total: target.total + source.total,
+		models: [...rows.values()],
+		...usageTalliesOf([target, source])
+	};
+}
+//#endregion
+//#region lib/types/pricing-table.js
+/**
+* The published rate schedule: which models cost what, and since when.
+*
+* Data only — every policy decision about how a rate is chosen (revision
+* lookup, peak windows, day boundaries) lives in `billing.ts`. Keeping them
+* apart means adding a model never touches the pricing engine: the change is
+* one row here, plus a test.
+*
+* Rates are CNY per 1M tokens. Rows sharing a model are that model's rate
+* history (see {@link resolveBilling}).
+* @module @rayadesu/dsh-llm-billing/pricing-table
 */
 /**
 * Published peak-hour windows (Beijing time): 09:00–12:00 and 14:00–18:00,
@@ -516,6 +866,20 @@ const DEFAULT_MODEL_PRICING = [
 		}
 	}
 ];
+//#endregion
+//#region lib/types/pricing.js
+/**
+* DeepSeek pricing: the peak/off-peak pricing table, the per-event pricing, and
+* the resolved-billing shape. Pure functions over token usage and the pricing
+* table, so the Remote gateway stays transport-free and the whole spend is
+* testable without a key.
+*
+* The per-event pricing lives in {@link priceEvent} / {@link priceUsage}; the
+* fold state machine that consumes it (`BillingFolder` / {@link applyBillingEvent})
+* lives in `fold.ts`, and every scan path prices through these primitives so a
+* pricing-table change cannot drift one path from the others.
+* @module @rayadesu/dsh-llm-billing/pricing
+*/
 /**
 * Resolve optional configuration to a pricing table, defaulting omitted or
 * empty rows to the published rates. Schemastery materializes an absent
@@ -583,87 +947,6 @@ function ratesAt(revisions, time) {
 	}
 	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 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 {
-		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 beijingPartsOf(now.getTime()).dayKey;
-}
-/**
-* The durable inherited-prefix boundary of one session: the number of leading
-* events it inherited verbatim from its fork source, 0 for a session created
-* without a seed. A forked session (or any seeded replay) carries that count
-* in its session state; every event with `seq < seedLength` is a copy of an
-* event already billed in that source session, so pricing must skip them or
-* the same model output is counted once per copy. Accepts the durable field
-* of both DSH runtime families (see {@link ForkBoundarySource}).
-* @param source - the session, inspection result, header slice, or durable
-*   header carrying the boundary; `undefined` reads as 0.
-* @returns the inherited-prefix length; 0 for an unseeded session.
-*/
-function forkBoundaryOf(source) {
-	if (source === void 0) return 0;
-	const inherited = source.inheritedEventCount;
-	if (inherited !== void 0 && Number.isSafeInteger(inherited)) return inherited;
-	return source.header?.seedLength ?? source.meta?.seedLength ?? source.seedLength ?? 0;
-}
-/** Whether a durable header marks a fork-inherited (seeded) session across both runtime families. */
-function isSeededSession(header) {
-	if (header === void 0) return false;
-	if (header.isSeeded === true) return true;
-	return (header.seedLength ?? 0) > 0;
-}
 /** Whether a Beijing (hour, weekday) pair falls inside any peak-hour window. */
 function isPeakParts(billing, hour, weekday) {
 	if (weekday === 0 || weekday === 6) return false;
@@ -714,6 +997,31 @@ function priceEventAt(parts, event, billing, names) {
 	if (reported === void 0) return void 0;
 	return priceUsage(parts, reported, event.data.message.source.model, billing, names);
 }
+/** Every token one usage sample reports, whether or not it gets priced. */
+function usageTokens(usage) {
+	return usage.inputTokens + usage.outputTokens + (usage.cacheReadTokens ?? 0) + (usage.cacheWriteTokens ?? 0);
+}
+/** Max distinct model ids remembered for the once-only warning. */
+const UNPRICED_WARN_LIMIT = 64;
+/** Model ids already reported, so a long-running host logs each one once. */
+const reportedUnpricedModels = /* @__PURE__ */ new Set();
+/**
+* Report a model carrying no rate row, at most once per id (and at most
+* {@link UNPRICED_WARN_LIMIT} ids per process). Every figure reads as zero when
+* the upstream model is unknown, which looks exactly like "no usage" rather
+* than a missing row — the one thing this warning exists to separate.
+*
+* Deliberately NOT guessed: model ids are chosen by whoever ships the model, so
+* a similar-looking name says nothing about a similar price — and a wrong number
+* that LOOKS authoritative is worse than a visible gap. The fix is one row under
+* `billing.models`, which is exactly what the warning points at.
+* @param model - the unlisted wire model id.
+*/
+function reportUnpricedModel(model) {
+	if (reportedUnpricedModels.has(model) || reportedUnpricedModels.size >= UNPRICED_WARN_LIMIT) return;
+	reportedUnpricedModels.add(model);
+	console.warn(`[llm-billing] no pricing row for model "${model}" — its usage is NOT billed; add its row under billing.models to price it`);
+}
 /**
 * 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
@@ -755,115 +1063,17 @@ function priceUsage(parts, usage, model, billing, names) {
 		outputCost
 	};
 }
-/** A spend with no priced usage. */
-function emptyTodaySpend() {
-	return {
-		total: 0,
-		models: []
-	};
-}
-/** The today-spend shape of a single priced contribution. */
-function contributionModel(priced) {
-	return {
-		model: priced.model,
-		displayName: priced.displayName,
-		cost: priced.cost,
-		peakCost: priced.peakCost,
-		offPeakCost: priced.offPeakCost,
-		cacheHitInputTokens: priced.cacheHitInputTokens,
-		cacheMissInputTokens: priced.cacheMissInputTokens,
-		outputTokens: priced.outputTokens,
-		cacheHitInputCost: priced.cacheHitInputCost,
-		cacheMissInputCost: priced.cacheMissInputCost,
-		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()]
-		};
-	}
-};
-/** 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)
-		}))
-	};
-}
+//#endregion
+//#region lib/types/fold.js
 /**
-* 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.
+* The single-pass fold state machine that turns a committed event log into a
+* session's billed spend. Consumes the pricing primitives in `pricing.ts`
+* (`priceUsage` / `reportUnpricedModel`) and the spend algebra in `spend.ts`
+* (`addEventContribution` / `subtractSpend` / `noteUnpriced` / `emptyTodaySpend`);
+* every scan path prices through {@link applyBillingEvent} so a pricing-table
+* change cannot drift one path from the others.
+* @module @rayadesu/dsh-llm-billing/fold
 */
-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 {
@@ -896,13 +1106,6 @@ function streamUsageOf(event) {
 		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.
 *
@@ -944,7 +1147,20 @@ function applyBillingEvent(state, event, billing, names) {
 	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);
+	const parts = beijingPartsOf(event.time);
+	if (billing.models.get(model) === void 0) {
+		reportUnpricedModel(model);
+		const tokens = usageTokens(usage);
+		const opens = state.dayKey === "" || parts.dayKey > state.dayKey;
+		const sameDay = parts.dayKey === state.dayKey;
+		return {
+			...state,
+			dayKey: opens ? parts.dayKey : state.dayKey,
+			spend: opens ? noteUnpriced(emptyTodaySpend(), model, tokens) : sameDay ? noteUnpriced(state.spend, model, tokens) : state.spend,
+			session: noteUnpriced(state.session, model, tokens)
+		};
+	}
+	const priced = priceUsage(parts, usage, model, billing, names);
 	if (priced === void 0) return state;
 	let session = state.session;
 	let spend = state.spend;
@@ -1006,40 +1222,43 @@ var BillingFolder = class {
 		return this.state;
 	}
 };
+//#endregion
+//#region lib/types/billing.js
 /**
-* Merge one priced event's contribution into an accumulator spend (pure:
-* returns a new spend, never mutates its input).
-* @param spend - the accumulator (per session and day, or across sessions).
-* @param priced - the priced contribution to add.
-* @returns the merged spend.
+* DeepSeek billing aggregation: the session/turn/today spend computations
+* over the pricing engine (`pricing.ts`) and the per-event fold state machine
+* (`fold.ts`). Pure functions over session events, so the whole spend is
+* testable without a key and the Remote gateway stays transport-free.
+*
+* The fold in {@link BillingFolder} / {@link applyBillingEvent} (see `fold.ts`)
+* and the per-event pricing in `pricing.ts` are the single source of truth the
+* events-scan paths, the session-projection unit, and the scanner all price
+* through, so a pricing-table change cannot drift one path from the others.
+* @module @rayadesu/dsh-llm-billing/billing
 */
-function addEventContribution(spend, 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
-	};
-}
 /**
-* Sum two spends (per session and day, or across sessions) into one (pure:
-* returns a new spend, never mutates its inputs).
-* @param target - the accumulator spend.
-* @param source - the spend to add.
-* @returns the summed spend.
+* The durable inherited-prefix boundary of one session: the number of leading
+* events it inherited verbatim from its fork source, 0 for a session created
+* without a seed. A forked session (or any seeded replay) carries that count
+* in its session state; every event with `seq < seedLength` is a copy of an
+* event already billed in that source session, so pricing must skip them or
+* the same model output is counted once per copy. Accepts the durable field
+* of the live-session and handle surfaces (see {@link ForkBoundarySource}).
+* @param source - the session, header slice, or opened handle carrying the
+*   boundary; `undefined` reads as 0.
+* @returns the inherited-prefix length; 0 for an unseeded session.
 */
-function mergeTodaySpend(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);
-		rows.set(row.model, existing === void 0 ? row : mergeModelRows(existing, row));
-	}
-	return {
-		total: target.total + source.total,
-		models: [...rows.values()]
-	};
+function forkBoundaryOf(source) {
+	if (source === void 0) return 0;
+	const inherited = source.inheritedEventCount;
+	if (inherited !== void 0 && Number.isSafeInteger(inherited)) return inherited;
+	return source.header?.seedLength ?? source.seedLength ?? 0;
+}
+/** Whether a durable header marks a fork-inherited (seeded) session across the live-session and handle surfaces. */
+function isSeededSession(header) {
+	if (header === void 0) return false;
+	if (header.isSeeded === true) return true;
+	return (header.seedLength ?? 0) > 0;
 }
 /**
 * Price one session's complete event log at the official per-model rates,
@@ -1222,9 +1441,10 @@ function computeSessionTurnSpends(events, billing, catalog) {
 */
 function computeTodaySpend(events, billing, catalog, now = /* @__PURE__ */ new Date()) {
 	const day = beijingDayKey(now);
+	const dayEnd = beijingDayRangeOfKey(day)?.end ?? Number.POSITIVE_INFINITY;
 	const folder = new BillingFolder(billing, catalog);
 	for (const event of events) {
-		if (beijingPartsOf(event.time).dayKey > day) continue;
+		if (event.time >= dayEnd) continue;
 		folder.add(event);
 	}
 	return folder.fold.dayKey === day ? folder.fold.spend : emptyTodaySpend();
@@ -1264,9 +1484,23 @@ const modelRowSchema = z$1.object({
 	cacheMissInputCost: z$1.number().nonnegative(),
 	outputCost: z$1.number().nonnegative()
 }).strict();
+/**
+* The advisory tally of usage that could not be billed at its own rate (see
+* `DeepSeekTodaySpend.unpriced`). Declared here because the
+* unit's schemas are `.strict()`: an undeclared key REJECTS the whole unit
+* rather than being stripped, so adding these fields to the fold without
+* declaring them here would fail every projection fold the moment a sample
+* went unpriced.
+*/
+const usageTallySchema = z$1.object({
+	events: z$1.number().int().nonnegative(),
+	tokens: z$1.number().int().nonnegative(),
+	models: z$1.array(z$1.string())
+}).strict();
 const todaySpendSchema = z$1.object({
 	total: z$1.number().nonnegative(),
-	models: z$1.array(modelRowSchema)
+	models: z$1.array(modelRowSchema),
+	unpriced: usageTallySchema.optional()
 }).strict();
 const billingUnitSchema = z$1.object({
 	dayKey: z$1.string(),
@@ -1336,67 +1570,13 @@ function foldOwnBilling(unit, events, seedLength = 0) {
 	return state;
 }
 //#endregion
-//#region lib/types/today-spend.js
-/**
-* Today-spend read path: the 60-second Beijing-day cache with in-flight
-* coalescing and a force bypass (plan A1), plus the two scan strategies that
-* compute the aggregate behind a cache miss:
-*
-* - projection path (plan C): live sessions read their eagerly folded
-*   `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,
-*   adopting the fold it already priced for a session whose persisted revision
-*   is unchanged since the last pass.
-*
-* Both strategies run behind the same {@link TodaySpendCache}, so a miss
-* happens at most once per 60 seconds per process, and a manual refresh
-* (`force`) bypasses the time window but keeps the revision caches — an
-* unchanged log provably cannot change the aggregate. That proof is what makes
-* a revision gate a CACHE: both strategies therefore adopt the resolution they
-* remember for an unchanged revision instead of skipping the session, so an
-* unchanged log costs no I/O and still contributes its full spend (and title)
-* to the aggregate and the ranking on every scan.
-*
-* The per-session ranking is a per-CONVERSATION ranking: a subagent child is
-* work the delegating conversation paid for, not a session the user opened, so
-* every subagent row is folded into the row of the top-level session at the
-* root of its `parentSession` chain (see {@link rollUpSubagentSpend}). The
-* aggregate is unaffected — it sums the same sessions either way.
-*
-* 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
-* `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
-* `SessionHeader.seedLength` moved to `Session.inheritedEventCount` (the
-* persistence `inspect` result carries it alongside `meta`). Reads go through
-* {@link liveSessionEvents} / {@link forkBoundaryOf}, which accept both
-* families structurally, so the scanner runs on the ≤ 0.1.1-rc.2 npm baseline
-* and on the newer runtime.
-* @module @rayadesu/dsh-llm-billing/today-spend
-*/
+//#region lib/types/session-lineage.js
 /**
-* Fold one session's durable display title: the latest `session/title`
-* event's text (last-wins, matching the `title` projection), or `null` before
-* the first title lands. The fold runs over the complete log, so an explicit
-* user rename is picked up as soon as its event commits.
-* @param events - one session's complete event log.
-* @returns the session's current title, or `null` when untitled.
+* Session lineage and titles: which session delegated which, where a subtree's
+* spend belongs, and the title a ranking row is labelled with. Split out of
+* `today-spend.ts` because neither the cache nor the scan strategies care
+* about lineage for their own sake — they only ask for it.
+* @module @rayadesu/dsh-llm-billing/session-lineage
 */
 function foldSessionTitle(events) {
 	for (let index = events.length - 1; index >= 0; index--) {
@@ -1481,68 +1661,23 @@ function rollUpSubagentSpend(rows, lineage, titles = /* @__PURE__ */ new Map())
 	return [...merged.values()].sort((left, right) => right.total - left.total);
 }
 /**
-* Read one live session's complete event log across both runtime families.
-* @throws when the session exposes neither the legacy `events` snapshot nor
-*   the newer `snapshotEvents()` reader — an unknown runtime surface must
-*   fail loudly rather than silently price an empty log.
-*/
-function liveSessionEvents(session) {
-	if (session.events !== void 0) return session.events;
-	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";
-}
-/**
-* List every stored session snapshot across both persistence runtime families:
-* `listSnapshots` (≤ 0.1.1-rc.2) or `list` (0.1.2-alpha.5+).
-* @param persistence - the persistence service slice.
-* @returns one snapshot per stored session.
+* Structural slice of a live session's header: the fork boundary of both DSH
+* runtime families plus the delegation lineage the ranking roll-up reads.
 */
-function persistenceListSnapshots(persistence) {
-	return isHandlePersistence(persistence) ? persistence.list() : persistence.listSnapshots();
-}
+//#endregion
+//#region lib/types/cache.js
 /**
-* Read one stored session's complete event log and durable inherited boundary
-* across both persistence runtime families: legacy `inspect` (≤ 0.1.1-rc.2)
-* or `open` + handle `read` (0.1.2-alpha.5+; the handle is closed after the
-* read). Both throw when the session does not exist.
-* @param persistence - the persistence service slice.
-* @param id - the stored session to read.
-* @returns the session's complete event log plus its inherited-prefix boundary.
+* The read-path cache: one 60-second Beijing-day window per process with
+* in-flight coalescing and stale-while-revalidate, plus the bounded fan-out
+* helper the cold scan parallelises with. Split out of `today-spend.ts` — it is
+* the one piece that knows nothing about sessions at all.
+* @module @rayadesu/dsh-llm-billing/cache
 */
-async function persistenceInspect(persistence, id) {
-	if (isHandlePersistence(persistence)) {
-		const handle = await persistence.open(id, "read");
-		try {
-			return {
-				events: handleReadEvents(await handle.read()),
-				seedLength: forkBoundaryOf(handle)
-			};
-		} finally {
-			await handle.close();
-		}
-	}
-	const inspection = await persistence.inspect(id);
-	return {
-		events: inspection.events,
-		seedLength: forkBoundaryOf(inspection)
-	};
-}
 /**
 * 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).
+* dispatch is O(n) overall (array `shift()` would be O(n) per pop). The cold
+* scan parallelises its session reads through this.
 */
 async function withConcurrency(items, limit, run) {
 	const total = items.length;
@@ -1555,10 +1690,29 @@ async function withConcurrency(items, limit, run) {
 	}));
 }
 /**
+* Hand the host's event loop back between session folds.
+*
+* The folds are synchronous CPU work — the pricing fold and `foldSessionTitle`
+* walk a whole log without an `await` — and they run on the same main loop that
+* serves the GUI's own round trips (switching model, creating a session). A
+* scan that never yields blocks those requests for its entire duration, which
+* is exactly what a cold scan did. `setImmediate` schedules the continuation
+* for the check phase, so the poll phase is served first: pending I/O — the
+* GUI's requests among it — completes before the next slice of folding.
+*/
+function yieldToEventLoop() {
+	return new Promise((resolve) => {
+		setImmediate(resolve);
+	});
+}
+/**
 * The A1 cache: one Beijing-day key + a 60s window, an in-flight promise that
-* coalesces concurrent misses, and a `force` bypass for the manual refresh
-* path. Cross-day invalidation is automatic (the day key changes); a failed
-* scan leaves the previous value in place and retries on the next call.
+* coalesces concurrent misses, a stale-while-revalidate path so a lapsed window
+* never makes a plain reader wait on the day's scan, and a `force` bypass that
+* makes a reader wait for a fresh scan instead. Cross-day invalidation is
+* automatic (the day key changes, and the previous day's value is never
+* served); a failed scan leaves the previous value in place and retries on the
+* next call.
 * @typeParam T - the cached aggregate's value shape (the spend or its
 *   per-session breakdown).
 */
@@ -1582,26 +1736,60 @@ var TodaySpendCache = class {
 	}
 	/**
 	* Read today's spend, cached per Beijing day within the TTL window.
-	* @param force - bypass the time window (manual refresh); the day-key gate
-	*   and the in-flight coalescing still apply to non-force callers.
+	*
+	* Two reads share this entry point, and `force` is the switch between them —
+	* its two values are exactly the two policies a caller can want, so there is
+	* no third mode:
+	*
+	* - **plain (`force: false`)** — stale-while-revalidate. A value for the
+	*   queried day is returned AT ONCE; once its window has lapsed the scan that
+	*   refreshes it runs behind the answer. This is the read for everything the
+	*   user did not just cause: a mount, a panel open, a poll, a session switch.
+	* - **forced (`force: true`)** — recompute now and WAIT: both the window and
+	*   the stale shortcut are bypassed. This is the read for a manual refresh and
+	*   for a settled turn, which have just changed the answer and must not be
+	*   handed the value from before they ran. A plain read there would report the
+	*   day's pre-turn figure one turn late.
+	*
+	* A day with no value yet (the first read of the day, or a Beijing-day
+	* rollover — yesterday's total is never served as today's) waits either way,
+	* because there is nothing honest to show. A failed revalidation leaves the
+	* previous value in place, and a pass already in flight is joined rather than
+	* duplicated.
+	* @param force - `true` recomputes now and waits; `false` serves the value on
+	*   hand and refreshes behind it.
 	* @returns today's spend.
 	*/
 	get(force = false) {
 		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);
+		const cached = this.cachedDayKey === dayKey ? this.cachedValue : void 0;
+		if (!force && cached !== void 0) {
+			if (now.getTime() - this.cachedAt < this.ttlMs) return Promise.resolve(cached);
+			if (this.inFlight === void 0) this.run(dayKey).catch(() => void 0);
+			return Promise.resolve(cached);
+		}
 		if (this.inFlight !== void 0) return this.inFlight;
-		const run = (async () => {
-			try {
-				const value = await this.scan(dayKey);
-				this.cachedDayKey = dayKey;
-				this.cachedValue = value;
-				this.cachedAt = now.getTime();
-				return value;
-			} finally {
-				this.inFlight = void 0;
-			}
-		})();
+		return this.run(dayKey);
+	}
+	/**
+	* Run one scan and publish its result.
+	*
+	* `cachedAt` is stamped when the scan COMPLETES, not when it starts: a pass
+	* slower than the TTL would otherwise be born expired, and every read after
+	* it would start another pass back-to-back.
+	* @param dayKey - the Beijing day the pass aggregates.
+	* @returns the freshly scanned value.
+	*/
+	run(dayKey) {
+		const run = this.scan(dayKey).then((value) => {
+			this.cachedDayKey = dayKey;
+			this.cachedValue = value;
+			this.cachedAt = this.now().getTime();
+			return value;
+		}).finally(() => {
+			this.inFlight = void 0;
+		});
 		this.inFlight = run;
 		return run;
 	}
@@ -1610,6 +1798,121 @@ var TodaySpendCache = class {
 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;
+/** The live SessionStore slice a scan reads (resolved once per scan). */
+//#endregion
+//#region lib/types/persistence.js
+/**
+* The persistence seams a cold scan reads through. DSH ships a single
+* persistence runtime family — the handle-based `list` / `open` +
+* `SessionHandle` surface (0.1.2-alpha.5+, the only one the plugin's
+* `^0.2.0-rc.1` peer targets). This module is the only place that knows
+* the handle shape. Split out of `today-spend.ts` so the scan strategies read
+* one shape.
+* @module @rayadesu/dsh-llm-billing/persistence
+*/
+/**
+* Read one live session's complete event log across both runtime families.
+* @throws when the session exposes neither the legacy `events` snapshot nor
+*   the newer `snapshotEvents()` reader — an unknown runtime surface must
+*   fail loudly rather than silently price an empty log.
+*/
+function liveSessionEvents(session) {
+	if (session.events !== void 0) return session.events;
+	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;
+}
+/**
+* List every stored session snapshot through the handle-based persistence
+* service (`list`).
+* @param persistence - the persistence service slice.
+* @returns one snapshot per stored session.
+*/
+function persistenceListSnapshots(persistence) {
+	return persistence.list();
+}
+/**
+* Read one stored session's complete event log and durable inherited boundary
+* through the handle-based persistence service (`open` + handle `read`; the
+* handle is closed after the read). Throws when the session does not exist.
+* @param persistence - the persistence service slice.
+* @param id - the stored session to read.
+* @returns the session's complete event log plus its inherited-prefix boundary.
+*/
+async function persistenceInspect(persistence, id) {
+	const handle = await persistence.open(id, "read");
+	try {
+		return {
+			events: handleReadEvents(await handle.read()),
+			seedLength: forkBoundaryOf(handle)
+		};
+	} finally {
+		await handle.close();
+	}
+}
+//#endregion
+//#region lib/types/today-spend.js
+/**
+* Today-spend read path: the 60-second Beijing-day cache with in-flight
+* coalescing and a force bypass (plan A1), plus the two scan strategies that
+* compute the aggregate behind a cache miss:
+*
+* - projection path (plan C): live sessions read their eagerly folded
+*   `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 `open` + handle read. 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,
+*   adopting the fold it already priced for a session whose persisted revision
+*   is unchanged since the last pass.
+*
+* Both strategies run behind the same {@link TodaySpendCache}, so a miss
+* happens at most once per 60 seconds per process, and a manual refresh
+* (`force`) bypasses the time window but keeps the revision caches — an
+* unchanged log provably cannot change the aggregate. That proof is what makes
+* a revision gate a CACHE: both strategies therefore adopt the resolution they
+* remember for an unchanged revision instead of skipping the session, so an
+* unchanged log costs no I/O and still contributes its full spend (and title)
+* to the aggregate and the ranking on every scan.
+*
+* The per-session ranking is a per-CONVERSATION ranking: a subagent child is
+* work the delegating conversation paid for, not a session the user opened, so
+* every subagent row is folded into the row of the top-level session at the
+* root of its `parentSession` chain (see {@link rollUpSubagentSpend}). The
+* aggregate is unaffected — it sums the same sessions either way.
+*
+* 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
+* `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 from the
+* live-session and handle surfaces — 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
+* `SessionHeader.seedLength` moved to `Session.inheritedEventCount` (the
+* opened `SessionHandle` carries it alongside `header`). Reads go through
+* {@link liveSessionEvents} / {@link forkBoundaryOf}, which accept the
+* live-session and handle shapes structurally, so the scanner runs on the
+* older `events` runtime and on the newer `snapshotEvents` runtime.
+* @module @rayadesu/dsh-llm-billing/today-spend
+*/
 /**
 * Bounded-map eviction: drop the oldest inserted entry once `size` reached
 * `limit`. Evicting one entry (instead of clearing) keeps the other sessions'
@@ -1678,7 +1981,12 @@ var TodaySpendScanner = class {
 	* from the aggregate and the ranking on every scan after the first.
 	*/
 	coldResolved = /* @__PURE__ */ new Map();
-	/** Cold sessions whose resolution failed: id → revision (retried only when the log changes). */
+	/**
+	* Cold sessions whose resolution failed, id → the revision it failed at plus
+	* when. Keyed by revision too, so an unchanged log is not re-read every scan,
+	* but the retry is TIME-boxed: a purely revision-keyed failure would hide a
+	* session permanently when its log never changes again.
+	*/
 	coldFailed = /* @__PURE__ */ new Map();
 	constructor(deps) {
 		this.deps = deps;
@@ -1721,7 +2029,10 @@ var TodaySpendScanner = class {
 	* otherwise.
 	*
 	* The aggregate sums every priced session, subagents included — the ranking's
-	* subagent roll-up only regroups rows, so neither total moves.
+	* subagent roll-up only regroups rows, so neither total moves. Both paths
+	* fold in slices and hand the host's event loop back every
+	* {@link SCAN_YIELD_SESSIONS} sessions, so a long scan never starves the
+	* GUI's own round trips.
 	* @param dayKey - the Beijing-time calendar-day key to aggregate.
 	* @returns the aggregate plus per-session rows sorted by cost descending.
 	*/
@@ -1737,14 +2048,14 @@ var TodaySpendScanner = class {
 	* 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
+	* opened 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`,
+	* prefix too, so it always detaches through a handle read with the durable
+	* boundary (the handle's `inheritedEventCount` or `header.seedLength`,
 	* depending on the runtime family) applied to the local fold.
 	* @param header - the listed session header (the cache identity witness).
 	* @param seeded - whether the session carries a fork-inherited prefix.
@@ -1814,14 +2125,18 @@ var TodaySpendScanner = class {
 				adopt(header.id, resolved);
 				continue;
 			}
-			if (this.coldFailed.get(header.id) === revision) continue;
+			const failed = this.coldFailed.get(header.id);
+			if (failed !== void 0 && failed.revision === revision && Date.now() - failed.at < 3e5) continue;
 			pending.push({
 				header,
 				revision,
 				seeded
 			});
 		}
+		let resolvedCount = 0;
 		await withConcurrency(pending, 8, async ({ header, revision, seeded }) => {
+			resolvedCount += 1;
+			if (resolvedCount % 8 === 0) await yieldToEventLoop();
 			const resolved = await this.resolveCold(header, seeded, dayKey);
 			if (resolved !== void 0) {
 				this.coldFailed.delete(header.id);
@@ -1831,10 +2146,16 @@ var TodaySpendScanner = class {
 				});
 			} else if (persistenceAvailable) {
 				evictOldest$1(this.coldFailed, COLD_FAILED_CACHE_LIMIT);
-				this.coldFailed.set(header.id, revision);
+				this.coldFailed.set(header.id, {
+					revision,
+					at: Date.now()
+				});
 			}
 		});
+		let adopted = 0;
 		for (const { header } of pending) {
+			adopted += 1;
+			if (adopted % 8 === 0) await yieldToEventLoop();
 			const resolved = this.coldResolved.get(header.id);
 			if (resolved !== void 0) adopt(header.id, resolved);
 		}
@@ -1860,11 +2181,13 @@ var TodaySpendScanner = class {
 		const liveIds = /* @__PURE__ */ new Set();
 		let collected = 0;
 		let truncated = false;
+		const dayRange = beijingDayRangeOfKey(dayKey);
+		const onDay = dayRange === void 0 ? (event) => beijingPartsOf(event.time).dayKey === dayKey : (event) => event.time >= dayRange.start && event.time < dayRange.end;
 		/** Price one complete log, announce it, and return what to remember. */
 		const collect = (id, events, seedLength, lineage) => {
 			const folder = new BillingFolder(billing, catalog, seedLength);
 			for (const event of events) {
-				if (beijingPartsOf(event.time).dayKey === dayKey) {
+				if (onDay(event)) {
 					collected += 1;
 					if (collected > maxEvents) {
 						truncated = true;
@@ -1883,10 +2206,15 @@ var TodaySpendScanner = class {
 		};
 		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), session.header ?? {});
-				if (truncated) break;
+			if (store !== void 0) {
+				let folded = 0;
+				for (const session of store.list()) {
+					folded += 1;
+					if (folded % 8 === 0) await yieldToEventLoop();
+					liveIds.add(session.id);
+					collect(session.id, liveSessionEvents(session), forkBoundaryOf(session), session.header ?? {});
+					if (truncated) break;
+				}
 			}
 		}
 		const persistenceService = persistence?.();
@@ -1918,7 +2246,7 @@ var TodaySpendScanner = class {
 	/**
 	* 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`
+	* revision-gated cold ladder for the rest (title resolved on the handle read, `null`
 	* when answered from the projection cache). A fork child's cell covers its
 	* inherited prefix, so its own-events fold supplies both outputs. Lineage
 	* (which session delegated which) comes from the same headers the boundary
@@ -1938,23 +2266,28 @@ var TodaySpendScanner = class {
 		const liveIds = /* @__PURE__ */ new Set();
 		if (sessions !== void 0) {
 			const store = sessions();
-			if (store !== void 0) for (const { session, state } of this.liveBillingEntries(store, projectionsService)) {
-				liveIds.add(session.id);
-				lineage.set(session.id, session.header ?? {});
-				const born = session.header?.createdAt;
-				if (born !== void 0) createdAt.set(session.id, born);
-				const title = foldSessionTitle(liveSessionEvents(session));
-				titles.set(session.id, title);
-				if (state === void 0) continue;
-				ownSpend.set(session.id, state.session);
-				if (state.dayKey !== dayKey) continue;
-				aggregate = mergeTodaySpend(aggregate, state.spend);
-				rows.set(session.id, {
-					sessionId: session.id,
-					title,
-					total: state.spend.total,
-					ownTotal: state.spend.total
-				});
+			if (store !== void 0) {
+				let folded = 0;
+				for (const { session, state } of this.liveBillingEntries(store, projectionsService)) {
+					folded += 1;
+					if (folded % 8 === 0) await yieldToEventLoop();
+					liveIds.add(session.id);
+					lineage.set(session.id, session.header ?? {});
+					const born = session.header?.createdAt;
+					if (born !== void 0) createdAt.set(session.id, born);
+					const title = foldSessionTitle(liveSessionEvents(session));
+					titles.set(session.id, title);
+					if (state === void 0) continue;
+					ownSpend.set(session.id, state.session);
+					if (state.dayKey !== dayKey) continue;
+					aggregate = mergeTodaySpend(aggregate, state.spend);
+					rows.set(session.id, {
+						sessionId: session.id,
+						title,
+						total: state.spend.total,
+						ownTotal: state.spend.total
+					});
+				}
 			}
 		}
 		const persistenceService = persistence?.();
@@ -2161,7 +2494,7 @@ function evictOldest(map, limit) {
 /**
 * Read one session's event log and durable seed boundary: the live
 * SessionStore first, then the persistence backend for a flushed session
-* (inspected directly by id — no header listing). The live-session surface
+* (opened directly by id — no header listing). The live-session surface
 * is read structurally across both DSH runtime families — `Session.events`
 * (≤ 0.1.1-rc.2) or `Session.snapshotEvents()` + `Session.inheritedEventCount`
 * (0.1.2-alpha.4+) — via {@link liveSessionEvents} / {@link forkBoundaryOf}.