@rayadesu/dsh-llm-billing 0.3.5 → 0.3.7

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # last confirmed-consistent state. Both languages carry equal authority; after
 # editing either side, bring the other along and re-record both hashes with:
 #   git hash-object README.md README.zh.md
-README.md: ed1a2bc7ef768d789ae4e6ba55c92254104b3a14
-README.zh.md: 3c84b79a1e1bc48fa43f8577bd81853f658a7087
+README.md: 3c0ae19286d6935190659ec1e1c93b7b63ab5c14
+README.zh.md: 08adb0d018b376fb5fa995b29cbb6790063f4814

package/README.md

@@ -31,7 +31,13 @@ Note: the projection path prices a session's history once, at the rates in effec
 
 ## Forked sessions
 
-A forked session (DSH's "fork" of a conversation) opens its log with a verbatim copy of its source session's events. Without special handling, the same model outputs would be billed once per copy: the child's session spend would include the inherited prefix, and today's spend would count it a second time alongside the parent's. The plugin prices only a session's OWN events — the durable `header.seedLength` is the fork boundary, and every event with `seq < seedLength` is treated as already billed in the source session. Fork children are therefore billed from their first new exchange onward (a freshly forked session prices to zero), today's spend counts each model output exactly once, and the same lineage-safe rule covers multi-generation forks and subagent forks (spawned with `context: 'fork'`). The boundary is the persisted header value, so a resumed fork child keeps its original boundary, while a session created without a seed — ordinary sessions and cold resumes included — carries no boundary and is billed in full.
+A forked session (DSH's "fork" of a conversation) opens its log with a verbatim copy of its source session's events. Without special handling, the same model outputs would be billed once per copy: the child's session spend would include the inherited prefix, and today's spend would count it a second time alongside the parent's. The plugin prices only a session's OWN events — the fork boundary is the session's persisted state (`header.seedLength` on the ≤ 0.1.1-rc.2 runtime, `Session.inheritedEventCount` / `inspect().inheritedEventCount` on 0.1.2-alpha.4+, both read structurally), and every event with `seq < boundary` is treated as already billed in the source session. Fork children are therefore billed from their first new exchange onward (a freshly forked session prices to zero), today's spend counts each model output exactly once, and the same lineage-safe rule covers multi-generation forks and subagent forks (spawned with `context: 'fork'`). The boundary is the persisted value, so a resumed fork child keeps its original boundary, while a session created without a seed — ordinary sessions and cold resumes included — carries no boundary and is billed in full.
+
+## Runtime compatibility
+
+Since 0.1.2-alpha.4, DSH replaced the live `Session` log surface `Session.events` with `Session.snapshotEvents()` (no args = the full current log) and `Session.ownEvents()`, and moved `SessionHeader.seedLength` to `Session.inheritedEventCount` (the persistence `inspect()` result carries the value beside `meta`; `listSnapshots()` headers keep only the boolean `isSeeded`). Every log read in the plugin goes through the structural adapters `liveSessionEvents` / `forkBoundaryOf` / `isSeededSession`, which accept both the ≤ 0.1.1-rc.2 and the 0.1.2-alpha.4+ shapes — the npm release baseline (`^0.1.2-alpha.5`) and the ahead-of-npm monorepo runtime both work without modification. On an unknown surface that has neither shape the plugin fails loudly rather than silently pricing an empty log.
+
+The persistence service itself changed surface too: 0.1.1-rc.2 exposes `inspect(id)` / `listSnapshots()`, while the 0.1.2-alpha.5 handle-based seam (in the monorepo after the released build) exposes `open(id, 'read')` + `SessionHandle.read()` / `list()`. The scanner reads both families through `persistenceInspect` / `persistenceListSnapshots` (the handle is always closed, including after a failed read), so the same plugin serves the published alpha line and the refactored checkout.
 
 ## Configuration
 

package/README.zh.md

@@ -31,7 +31,13 @@
 
 ## 分叉会话
 
-分叉会话（DSH 的「分叉会话」）的日志以来源会话事件的逐字节副本开头。若不特殊处理，同一批模型输出会按副本数重复计费：子会话的会话花费会包含继承前缀，今日花费也会在父会话之外再计一次。插件只对会话的**自有事件**计费——持久的 `header.seedLength` 即分叉边界，凡是 `seq < seedLength` 的事件都视为已在来源会话计费。因此分叉子会话从分叉后的第一次新交流开始计费（刚分叉的会话花费为零），今日花费对每个模型输出只计一次，同一血缘规则同样覆盖多代分叉与 subagent 分叉（`context: 'fork'` 生成）。边界取自已持久化的 header 值，所以恢复后的分叉子会话保持原边界；而创建时没有 seed 的会话——包括普通会话与冷恢复——不带边界，正常全额计费。
+分叉会话（DSH 的「分叉会话」）的日志以来源会话事件的逐字节副本开头。若不特殊处理，同一批模型输出会按副本数重复计费：子会话的会话花费会包含继承前缀，今日花费也会在父会话之外再计一次。插件只对会话的**自有事件**计费——分叉边界取自已持久化的会话状态（≤ 0.1.1-rc.2 运行时为 `header.seedLength`；0.1.2-alpha.4+ 运行时为 `Session.inheritedEventCount` / `inspect().inheritedEventCount`，两者都以结构方式读取），凡是 `seq < 边界` 的事件都视为已在来源会话计费。因此分叉子会话从分叉后的第一次新交流开始计费（刚分叉的会话花费为零），今日花费对每个模型输出只计一次，同一血缘规则同样覆盖多代分叉与 subagent 分叉（`context: 'fork'` 生成）。边界取自已持久化的值，所以恢复后的分叉子会话保持原边界；而创建时没有 seed 的会话——包括普通会话与冷恢复——不带边界，正常全额计费。
+
+## 运行时兼容性
+
+0.1.2-alpha.4 起，DSH 把 live `Session` 的日志读取表面从 `Session.events` 改为 `Session.snapshotEvents()`（无参 = 当前全量日志）与 `Session.ownEvents()`，并把 `SessionHeader.seedLength` 移至 `Session.inheritedEventCount`（持久化侧 `inspect()` 的结果在 `meta` 之外携带该值，`listSnapshots()` 的 header 只剩布尔 `isSeeded`）。插件的所有日志读取都走结构适配器 `liveSessionEvents` / `forkBoundaryOf` / `isSeededSession`，同时接受 ≤ 0.1.1-rc.2 与 0.1.2-alpha.4+ 两种形状——npm 发布基线（`^0.1.2-alpha.5`）与超前于它的 monorepo 运行时代码均无需改动即可工作。遇到两种形状都没有的未知运行时表面时，插件会显式失败而不是静默按零花费计价。
+
+持久化服务的表面同样换代：0.1.1-rc.2 提供 `inspect(id)` / `listSnapshots()`，而 handle 化的 0.1.2-alpha.5 seam（位于已发布构建之后的 monorepo 中）提供 `open(id, 'read')` + `SessionHandle.read()` / `list()`。扫描器通过 `persistenceInspect` / `persistenceListSnapshots` 同时读取两代表面（handle 总会关闭，读取失败时也一样），因此同一套插件既能服务已发布的 alpha 线，也能服务重构后的 checkout。
 
 ## 配置
 

package/lib/index.js

@@ -380,20 +380,28 @@ function beijingDayKey(now) {
 	return beijingParts(now.getTime()).dayKey;
 }
 /**
-* The durable inherited-prefix boundary of one session: its header's
-* `seedLength`, or 0 for a session created without a seed. A forked session
-* (or any seeded replay) carries the number of events it inherited verbatim
-* from its source session in its header; 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.
-* The value is the PERSISTED header field (not the in-memory constructor
-* seed length), so a resumed fork child keeps its original boundary and a
-* resume of an unseeded session stays at 0.
-* @param header - the session's durable header, when available.
+* 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(header) {
-	return header?.seedLength ?? 0;
+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) {
@@ -782,14 +790,22 @@ 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 (`header.seedLength` of them),
-* so the scanner prices only the child's OWN events (`seq >= seedLength`) 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 header, so 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
+* 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.
+*
+* 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
 */
 /**
@@ -810,6 +826,56 @@ function foldSessionTitle(events) {
 	return null;
 }
 /**
+* 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");
+}
+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.
+*/
+function persistenceListSnapshots(persistence) {
+	return isHandlePersistence(persistence) ? persistence.list() : persistence.listSnapshots();
+}
+/**
+* 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.
+*/
+async function persistenceInspect(persistence, id) {
+	if (isHandlePersistence(persistence)) {
+		const handle = await persistence.open(id, "read");
+		try {
+			return {
+				events: 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).
@@ -923,16 +989,19 @@ var TodaySpendScanner = class {
 	* until the session is inspected again. A SEEDED session (fork child)
 	* skips the ladder entirely: its cached row was folded over the inherited
 	* prefix too, so it always detaches through inspect with the durable
-	* boundary applied to the local fold.
+	* 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 seedLength - the durable inherited-prefix boundary (0 for unseeded).
+	* @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).
 	* @returns the resolved state and title, or `undefined` when unreadable.
 	*/
-	async resolveCold(id, seedLength) {
-		const { persistence, projectionCache, unit, logger } = this.deps;
+	async resolveCold(id, seeded) {
+		const { persistence, projectionCache, logger } = this.deps;
 		const persistenceService = persistence?.();
 		if (persistenceService === void 0) return void 0;
-		if (seedLength <= 0) {
+		if (!seeded) {
 			const cache = projectionCache?.();
 			if (cache !== void 0) try {
 				const value = (await cache.coldSnapshot(id)).values[BILLING_UNIT_KEY];
@@ -945,10 +1014,10 @@ var TodaySpendScanner = class {
 			}
 		}
 		try {
-			const inspection = await persistenceService.inspect(id);
+			const read = await persistenceInspect(persistenceService, id);
 			return {
-				value: foldOwnBilling(unit, inspection.events, seedLength),
-				title: foldSessionTitle(inspection.events)
+				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)}`);
@@ -992,18 +1061,18 @@ var TodaySpendScanner = class {
 			const store = sessions();
 			if (store !== void 0) for (const session of store.list()) {
 				liveIds.add(session.id);
-				const seedLength = forkBoundaryOf(session.header);
-				const state = seedLength > 0 ? this.ownBillingState(session.id, session.events, seedLength) : projectionsService?.stateOf(session, BILLING_UNIT_KEY);
+				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 persistenceService.listSnapshots();
+		const snapshots = await persistenceListSnapshots(persistenceService);
 		const pending = [];
 		for (const { header, revision } of snapshots) {
 			if (liveIds.has(header.id)) continue;
-			const seedLength = forkBoundaryOf(header);
+			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);
@@ -1012,11 +1081,11 @@ var TodaySpendScanner = class {
 			pending.push({
 				id: header.id,
 				revision,
-				seedLength
+				seeded
 			});
 		}
-		await withConcurrency(pending, 8, async ({ id, revision, seedLength }) => {
-			const resolved = await this.resolveCold(id, seedLength);
+		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
@@ -1058,19 +1127,19 @@ var TodaySpendScanner = class {
 			const store = sessions();
 			if (store !== void 0) for (const session of store.list()) {
 				liveIds.add(session.id);
-				collect(session.events, forkBoundaryOf(session.header));
+				collect(liveSessionEvents(session), forkBoundaryOf(session));
 				if (truncated) break;
 			}
 		}
 		const persistenceService = persistence?.();
 		if (!truncated && persistenceService !== void 0) {
-			const snapshots = await persistenceService.listSnapshots();
+			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 inspection = await persistenceService.inspect(header.id);
-					collect(inspection.events, forkBoundaryOf(inspection.meta));
+					const read = await persistenceInspect(persistenceService, header.id);
+					collect(read.events, read.seedLength);
 				} catch (error) {
 					logger.warn(`llm-billing: skipping unreadable session ${header.id}: ${String(error)}`);
 				}
@@ -1099,22 +1168,23 @@ var TodaySpendScanner = class {
 			const store = sessions();
 			if (store !== void 0) for (const session of store.list()) {
 				liveIds.add(session.id);
-				const seedLength = forkBoundaryOf(session.header);
-				const state = seedLength > 0 ? this.ownBillingState(session.id, session.events, seedLength) : projectionsService?.stateOf(session, BILLING_UNIT_KEY);
+				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, {
 					sessionId: session.id,
-					title: foldSessionTitle(session.events),
+					title: foldSessionTitle(events),
 					total: state.spend.total
 				});
 			}
 		}
 		const persistenceService = persistence?.();
 		if (persistenceService === void 0) return [...rows.values()];
-		const snapshots = await persistenceService.listSnapshots();
+		const snapshots = await persistenceListSnapshots(persistenceService);
 		const pending = [];
 		for (const { header, revision } of snapshots) {
 			if (liveIds.has(header.id)) continue;
-			const seedLength = forkBoundaryOf(header);
+			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, {
@@ -1127,11 +1197,11 @@ var TodaySpendScanner = class {
 			pending.push({
 				id: header.id,
 				revision,
-				seedLength
+				seeded
 			});
 		}
-		await withConcurrency(pending, 8, async ({ id, revision, seedLength }) => {
-			const resolved = await this.resolveCold(id, seedLength);
+		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
@@ -1190,19 +1260,19 @@ var TodaySpendScanner = class {
 			const store = sessions();
 			if (store !== void 0) for (const session of store.list()) {
 				liveIds.add(session.id);
-				collect(session.id, session.events, forkBoundaryOf(session.header));
+				collect(session.id, liveSessionEvents(session), forkBoundaryOf(session));
 				if (truncated) break;
 			}
 		}
 		const persistenceService = persistence?.();
 		if (!truncated && persistenceService !== void 0) {
-			const snapshots = await persistenceService.listSnapshots();
+			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 inspection = await persistenceService.inspect(header.id);
-					collect(header.id, inspection.events, forkBoundaryOf(inspection.meta));
+					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)}`);
 				}
@@ -1294,7 +1364,10 @@ const TODAY_SPEND_MAX_EVENTS = 2e5;
 /**
 * 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).
+* (inspected 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}.
 * @param ctx - plugin context carrying the SessionStore and optional persistence.
 * @param sessionId - the session to read.
 * @returns the session's complete event log plus its inherited-prefix boundary.
@@ -1303,16 +1376,12 @@ const TODAY_SPEND_MAX_EVENTS = 2e5;
 async function sessionEvents(ctx, sessionId) {
 	const live = ctx.get("sessions")?.get(sessionId);
 	if (live !== void 0) return {
-		events: live.events,
-		seedLength: forkBoundaryOf(live.header)
+		events: liveSessionEvents(live),
+		seedLength: forkBoundaryOf(live)
 	};
 	const persistence = ctx.get("sessionPersistence");
 	if (persistence !== void 0) try {
-		const inspection = await persistence.inspect(sessionId);
-		return {
-			events: inspection.events,
-			seedLength: forkBoundaryOf(inspection.meta)
-		};
+		return await persistenceInspect(persistence, sessionId);
 	} catch (error) {
 		throw new LlmError(`llm-billing: session ${sessionId} not found`, "NOT_FOUND", { cause: error });
 	}
@@ -1406,4 +1475,4 @@ function apply(ctx, config) {
 	});
 }
 //#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, mergeTodaySpend, name, parseDeepSeekBalance, priceEvent, resolveBilling };
+export { BILLING_UNIT_KEY, Config, DEFAULT_MODEL_PRICING, DEFAULT_PEAK_HOURS, DeepSeekBalanceGateway, PUBLIC_BASE_URL, SpendAccumulator, TODAY_SPEND_CACHE_MS, TODAY_SPEND_MAX_EVENTS, TodaySpendCache, TodaySpendScanner, addEventContribution, apply, beijingDayKey, billingTodaySpendDefinition, computeSessionSpend, computeTodaySpend, computeTurnSpend, emptyTodaySpend, fetchDeepSeekBalance, foldBillingUnit, foldOwnBilling, foldSessionTitle, forkBoundaryOf, isPeak, isSeededSession, liveSessionEvents, mergeTodaySpend, name, parseDeepSeekBalance, persistenceInspect, persistenceListSnapshots, priceEvent, resolveBilling };

package/lib/types/billing.d.ts

@@ -88,21 +88,54 @@ export declare function resolveBilling(config: BillingConfig | undefined): Resol
 /** The Beijing (Asia/Shanghai, UTC+8, no DST) calendar-day key of a timestamp. */
 export declare function beijingDayKey(now: Date): string;
 /**
- * The durable inherited-prefix boundary of one session: its header's
- * `seedLength`, or 0 for a session created without a seed. A forked session
- * (or any seeded replay) carries the number of events it inherited verbatim
- * from its source session in its header; 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.
- * The value is the PERSISTED header field (not the in-memory constructor
- * seed length), so a resumed fork child keeps its original boundary and a
- * resume of an unseeded session stays at 0.
- * @param header - the session's durable header, when available.
+ * Structural source of a session's durable inherited-prefix boundary. The
+ * field moved between DSH runtimes:
+ *
+ * - since 0.1.2-alpha.4, `SessionHeader.seedLength` was removed (the header
+ *   now carries only `isSeeded`: boolean) and the exact cut moved to
+ *   `Session.inheritedEventCount` / `SessionInspection.inheritedEventCount`;
+ * - at and before the 0.1.1-rc.2 npm baseline, the cut lived on the durable
+ *   header as `seedLength` (optional; absent for an unseeded session) and on
+ *   the persistence `inspect` result as `meta.seedLength`.
+ *
+ * The reader accepts any of the three shapes and prefers the newer,
+ * exact-count field, so the same plugin code prices correctly on both
+ * families of runtime.
+ */
+export interface ForkBoundarySource {
+    /** 0.1.2-alpha.4+: `Session.inheritedEventCount` / `SessionInspection.inheritedEventCount`. */
+    readonly inheritedEventCount?: number;
+    /** 0.1.1-rc.2 and earlier: `SessionHeader.seedLength`. */
+    readonly seedLength?: number;
+    /** ≤ 0.1.1-rc.2: the header slice of a `Session` (its `header.seedLength`). */
+    readonly header?: {
+        readonly seedLength?: number;
+        readonly isSeeded?: boolean;
+    };
+    /** ≤ 0.1.1-rc.2: the `meta` of a persistence `inspect` result (its `seedLength`). */
+    readonly meta?: {
+        readonly seedLength?: number;
+        readonly isSeeded?: boolean;
+    };
+}
+/**
+ * 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.
  */
-export declare function forkBoundaryOf(header: {
+export declare function forkBoundaryOf(source: ForkBoundarySource | undefined): number;
+/** Whether a durable header marks a fork-inherited (seeded) session across both runtime families. */
+export declare function isSeededSession(header: {
     readonly seedLength?: number;
-} | undefined): number;
+    readonly isSeeded?: boolean;
+} | undefined): boolean;
 /**
  * Whether a timestamp falls inside any peak-hour window (Beijing time,
  * weekdays Monday–Friday only). Weekends (Saturday and Sunday) are always

package/lib/types/billing.js

@@ -81,20 +81,32 @@ export function beijingDayKey(now) {
     return beijingParts(now.getTime()).dayKey;
 }
 /**
- * The durable inherited-prefix boundary of one session: its header's
- * `seedLength`, or 0 for a session created without a seed. A forked session
- * (or any seeded replay) carries the number of events it inherited verbatim
- * from its source session in its header; 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.
- * The value is the PERSISTED header field (not the in-memory constructor
- * seed length), so a resumed fork child keeps its original boundary and a
- * resume of an unseeded session stays at 0.
- * @param header - the session's durable header, when available.
+ * 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.
  */
-export function forkBoundaryOf(header) {
-    return header?.seedLength ?? 0;
+export function forkBoundaryOf(source) {
+    if (source === undefined)
+        return 0;
+    const inherited = source.inheritedEventCount;
+    if (inherited !== undefined && 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. */
+export function isSeededSession(header) {
+    if (header === undefined)
+        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) {

package/lib/types/index.d.ts

@@ -24,13 +24,13 @@ import type { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
 import type { BillingConfig } from './billing.ts';
 export { DeepSeekBalanceGateway, fetchDeepSeekBalance, parseDeepSeekBalance } from './balance.ts';
-export { addEventContribution, beijingDayKey, computeSessionSpend, computeTodaySpend, computeTurnSpend, DEFAULT_MODEL_PRICING, DEFAULT_PEAK_HOURS, emptyTodaySpend, forkBoundaryOf, isPeak, mergeTodaySpend, priceEvent, resolveBilling, SpendAccumulator, } from './billing.ts';
+export { addEventContribution, beijingDayKey, computeSessionSpend, computeTodaySpend, computeTurnSpend, DEFAULT_MODEL_PRICING, DEFAULT_PEAK_HOURS, emptyTodaySpend, forkBoundaryOf, isPeak, isSeededSession, mergeTodaySpend, priceEvent, resolveBilling, SpendAccumulator, } from './billing.ts';
 export type { BillingConfig, BillingConfigModel, BillingEventContribution, DeepSeekModelPricing, DeepSeekTokenPrice, PeakHourWindow, ResolvedBilling, } from './billing.ts';
 export type * from './types.ts';
 export { BILLING_UNIT_KEY, billingTodaySpendDefinition, foldBillingUnit, foldOwnBilling } from './projection.ts';
-export type { BillingUnitState } from './projection.ts';
-export { foldSessionTitle, TodaySpendCache, TodaySpendScanner } from './today-spend.ts';
-export type { ScannerPersistedHeader, ScannerSession, TodaySpendScannerDeps } from './today-spend.ts';
+export type { BillingUnitFold, BillingUnitState } from './projection.ts';
+export { foldSessionTitle, liveSessionEvents, persistenceInspect, persistenceListSnapshots, TodaySpendCache, TodaySpendScanner } from './today-spend.ts';
+export type { ScannerPersistedHeader, ScannerPersistence, ScannerPersistenceHandle, ScannerPersistenceLegacy, ScannerPersistedRead, ScannerSession, TodaySpendScannerDeps } from './today-spend.ts';
 export declare const name = "llm-billing";
 /** Public API default; deployments may point elsewhere via $DEEPSEEK_BASE_URL. */
 export declare const PUBLIC_BASE_URL = "https://api.deepseek.com";

package/lib/types/index.js

@@ -27,11 +27,11 @@ import { launchEnvironmentOf } from '@deepseek-ai/dsh-launch-environment';
 import { DeepSeekBalanceGateway, fetchDeepSeekBalance } from "./balance.js";
 import { computeSessionSpend, computeTurnSpend, DEFAULT_MODEL_PRICING, DEFAULT_PEAK_HOURS, forkBoundaryOf, mergeTodaySpend, resolveBilling, } from "./billing.js";
 import { billingTodaySpendDefinition } from "./projection.js";
-import { TodaySpendCache, TodaySpendScanner } from "./today-spend.js";
+import { liveSessionEvents, persistenceInspect, TodaySpendCache, TodaySpendScanner } from "./today-spend.js";
 export { DeepSeekBalanceGateway, fetchDeepSeekBalance, parseDeepSeekBalance } from "./balance.js";
-export { addEventContribution, beijingDayKey, computeSessionSpend, computeTodaySpend, computeTurnSpend, DEFAULT_MODEL_PRICING, DEFAULT_PEAK_HOURS, emptyTodaySpend, forkBoundaryOf, isPeak, mergeTodaySpend, priceEvent, resolveBilling, SpendAccumulator, } from "./billing.js";
+export { addEventContribution, beijingDayKey, computeSessionSpend, computeTodaySpend, computeTurnSpend, DEFAULT_MODEL_PRICING, DEFAULT_PEAK_HOURS, emptyTodaySpend, forkBoundaryOf, isPeak, isSeededSession, mergeTodaySpend, priceEvent, resolveBilling, SpendAccumulator, } from "./billing.js";
 export { BILLING_UNIT_KEY, billingTodaySpendDefinition, foldBillingUnit, foldOwnBilling } from "./projection.js";
-export { foldSessionTitle, TodaySpendCache, TodaySpendScanner } from "./today-spend.js";
+export { foldSessionTitle, liveSessionEvents, persistenceInspect, persistenceListSnapshots, TodaySpendCache, TodaySpendScanner } from "./today-spend.js";
 export const name = 'llm-billing';
 const DEFAULT_API_KEY_ENV = 'DEEPSEEK_API_KEY';
 const BASE_URL_ENV = 'DEEPSEEK_BASE_URL';
@@ -75,7 +75,10 @@ export const TODAY_SPEND_MAX_EVENTS = 200_000;
 /**
  * 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).
+ * (inspected 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}.
  * @param ctx - plugin context carrying the SessionStore and optional persistence.
  * @param sessionId - the session to read.
  * @returns the session's complete event log plus its inherited-prefix boundary.
@@ -84,13 +87,13 @@ export const TODAY_SPEND_MAX_EVENTS = 200_000;
 async function sessionEvents(ctx, sessionId) {
     const sessions = ctx.get('sessions');
     const live = sessions?.get(sessionId);
-    if (live !== undefined)
-        return { events: live.events, seedLength: forkBoundaryOf(live.header) };
+    if (live !== undefined) {
+        return { events: liveSessionEvents(live), seedLength: forkBoundaryOf(live) };
+    }
     const persistence = ctx.get('sessionPersistence');
     if (persistence !== undefined) {
         try {
-            const inspection = await persistence.inspect(sessionId);
-            return { events: inspection.events, seedLength: forkBoundaryOf(inspection.meta) };
+            return await persistenceInspect(persistence, sessionId);
         }
         catch (error) {
             throw new LlmError(`llm-billing: session ${sessionId} not found`, 'NOT_FOUND', { cause: error });

package/lib/types/projection.d.ts

@@ -64,8 +64,20 @@ export declare function billingTodaySpendDefinition(billing: ResolvedBilling, ca
     id: string;
     name: string;
 }[]): BillingUnitDefinition;
+/** The fold halves of a billing unit, as the detached cold recipes call them. */
+export interface BillingUnitFold {
+    /**
+     * Initial state for the empty log. DSH ≤ 0.1.1-rc.2 declared `init()` with
+     * no parameters; 0.1.2-alpha.5+ passes the Session header and inherited
+     * count. The unit ignores both, so the structural type accepts either call
+     * shape.
+     */
+    init(...metadata: never[]): BillingUnitState;
+    /** Pure transition: previous state + one committed event → next state. */
+    apply(state: BillingUnitState, event: SessionEvent): BillingUnitState;
+}
 /** Fold a unit from init over one session's event log (the detached cold recipe). */
-export declare function foldBillingUnit(unit: Pick<ProjectionDefinition<'billingTodaySpend', BillingUnitState>, 'init' | 'apply'>, events: readonly SessionEvent[]): BillingUnitState;
+export declare function foldBillingUnit(unit: BillingUnitFold, events: readonly SessionEvent[]): BillingUnitState;
 /**
  * Fold a unit from init over one session's OWN events only: the complete log
  * minus its inherited fork prefix (`seq < seedLength`). A forked child's
@@ -78,5 +90,5 @@ export declare function foldBillingUnit(unit: Pick<ProjectionDefinition<'billing
  *   ({@link forkBoundaryOf}); 0 for an unseeded session.
  * @returns the unit state folded over the session's own events.
  */
-export declare function foldOwnBilling(unit: Pick<ProjectionDefinition<'billingTodaySpend', BillingUnitState>, 'init' | 'apply'>, events: readonly SessionEvent[], seedLength?: number): BillingUnitState;
+export declare function foldOwnBilling(unit: BillingUnitFold, events: readonly SessionEvent[], seedLength?: number): BillingUnitState;
 //# sourceMappingURL=projection.d.ts.map

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

@@ -20,22 +20,29 @@
  * 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 (`header.seedLength` of them),
- * so the scanner prices only the child's OWN events (`seq >= seedLength`) 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 header, so 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
+ * 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.
+ *
+ * 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
  */
 import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session';
 import type { SessionPersistenceRevision } from '@deepseek-ai/dsh-session-persistence';
 import type { ResolvedBilling } from './billing.ts';
 import type { DeepSeekTodaySessionsSpend, DeepSeekTodaySpend } from './types.ts';
-import { BILLING_UNIT_KEY, type BillingUnitState } from './projection.ts';
-import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection';
+import { BILLING_UNIT_KEY, type BillingUnitFold, type BillingUnitState } from './projection.ts';
 /**
  * Fold one session's durable display title: the latest `session/title`
  * event's text (last-wins, matching the `title` projection), or `null` before
@@ -45,21 +52,102 @@ import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection';
  * @returns the session's current title, or `null` when untitled.
  */
 export declare function foldSessionTitle(events: readonly SessionEvent[]): string | null;
-/** Structural slice of a live session the scanner reads. */
+/**
+ * Structural slice of a live session the scanner reads, accepting both DSH
+ * runtime families: the ≤ 0.1.1-rc.2 baseline exposes the log as
+ * `events` (+ `header.seedLength`), while 0.1.2-alpha.4+ exposes
+ * `snapshotEvents()` and `inheritedEventCount` (and dropped the header field).
+ */
 export interface ScannerSession {
     readonly id: SessionId;
-    readonly events: readonly SessionEvent[];
-    /** Durable header slice; `seedLength` marks a fork child's inherited prefix. */
+    /** ≤ 0.1.1-rc.2: the full event log snapshot. */
+    readonly events?: readonly SessionEvent[];
+    /** 0.1.2-alpha.4+: materialize an immutable log snapshot; no args = the full current log. */
+    snapshotEvents?(fromSeq?: number, toSeqExclusive?: number): readonly SessionEvent[];
+    /** 0.1.2-alpha.4+: the durable inherited-prefix length (0 for an unseeded session). */
+    readonly inheritedEventCount?: number;
+    /** Durable header slice: `seedLength` (older runtime) or `isSeeded` (newer runtime). */
     readonly header?: {
         readonly seedLength?: number;
+        readonly isSeeded?: boolean;
     };
 }
+/**
+ * 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.
+ */
+export declare function liveSessionEvents(session: ScannerSession): readonly SessionEvent[];
 /** Structural slice of a listed persisted session (the snapshot header is a full SessionHeader). */
 export interface ScannerPersistedHeader {
     readonly id: SessionId;
-    /** Durable fork boundary carried by the snapshot header; absent for an unseeded session. */
+    /** ≤ 0.1.1-rc.2: the durable fork boundary carried by the snapshot header; absent for an unseeded session. */
     readonly seedLength?: number;
+    /** 0.1.2-alpha.4+: whether the session has a fork-inherited prefix (exact cut arrives with the inspect result). */
+    readonly isSeeded?: boolean;
+}
+/** One stored-session read: the full event log plus the durable inherited boundary. */
+export interface ScannerPersistedRead {
+    readonly events: readonly SessionEvent[];
+    /** Inherited-prefix length (fork seed length); 0 for an unseeded session. */
+    readonly seedLength: number;
 }
+/** ≤ 0.1.1-rc.2 persistence slice: service-level `inspect` / `listSnapshots`. */
+export interface ScannerPersistenceLegacy {
+    listSnapshots(): Promise<readonly {
+        header: ScannerPersistedHeader;
+        revision: SessionPersistenceRevision;
+    }[]>;
+    inspect(id: SessionId): Promise<{
+        meta?: {
+            readonly seedLength?: number;
+            readonly isSeeded?: boolean;
+        };
+        /** 0.1.2-alpha.4+: the exact inherited cut travels beside, not inside, the header. */
+        inheritedEventCount?: number;
+        events: readonly SessionEvent[];
+    }>;
+}
+/** 0.1.2-alpha.5+ handle-based persistence slice: service-level `list` / `open` + `SessionHandle`. */
+export interface ScannerPersistenceHandle {
+    list(): Promise<readonly {
+        header: ScannerPersistedHeader;
+        revision: SessionPersistenceRevision;
+    }[]>;
+    open(id: SessionId, access: 'read'): Promise<{
+        readonly header?: {
+            readonly seedLength?: number;
+            readonly isSeeded?: boolean;
+        };
+        /** 0.1.2-alpha.5+: the handle carries the exact inherited cut beside the header. */
+        readonly inheritedEventCount?: number;
+        read(): Promise<readonly SessionEvent[]>;
+        close(): Promise<void>;
+    }>;
+}
+/** Structural union the scanner reads through, accepting both persistence runtime families. */
+export type ScannerPersistence = ScannerPersistenceLegacy | ScannerPersistenceHandle;
+/**
+ * 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.
+ */
+export declare function persistenceListSnapshots(persistence: ScannerPersistence): Promise<readonly {
+    header: ScannerPersistedHeader;
+    revision: SessionPersistenceRevision;
+}[]>;
+/**
+ * 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.
+ */
+export declare function persistenceInspect(persistence: ScannerPersistence, id: SessionId): Promise<ScannerPersistedRead>;
 /** Structural slices of the optional services the scanner reads through. */
 export interface TodaySpendScannerDeps {
     /** Resolves the live SessionStore at scan time (absent in headless assemblies). */
@@ -67,18 +155,7 @@ export interface TodaySpendScannerDeps {
         list(): readonly ScannerSession[];
     } | undefined;
     /** Resolves the persistence backend at scan time (absent without persistence). */
-    persistence?: () => {
-        listSnapshots(): Promise<readonly {
-            header: ScannerPersistedHeader;
-            revision: SessionPersistenceRevision;
-        }[]>;
-        inspect(id: SessionId): Promise<{
-            meta: {
-                seedLength?: number;
-            };
-            events: readonly SessionEvent[];
-        }>;
-    } | undefined;
+    persistence?: () => ScannerPersistence | undefined;
     /** Resolves the session-projection registry at scan time (absent → events path). */
     projections?: () => {
         stateOf(session: ScannerSession, key: typeof BILLING_UNIT_KEY): BillingUnitState | undefined;
@@ -97,7 +174,7 @@ export interface TodaySpendScannerDeps {
      */
     ensureUnit?: () => void;
     /** The billing unit's fold (the projection path's detached cold recipe). */
-    unit: Pick<ProjectionDefinition<'billingTodaySpend', BillingUnitState>, 'init' | 'apply'>;
+    unit: BillingUnitFold;
     /** Hard cap on today's events collected by the events path. */
     maxEvents: number;
     /** Warn sink for truncation and unreadable sessions. */
@@ -179,9 +256,12 @@ export declare class TodaySpendScanner {
      * until the session is inspected again. A SEEDED session (fork child)
      * skips the ladder entirely: its cached row was folded over the inherited
      * prefix too, so it always detaches through inspect with the durable
-     * boundary applied to the local fold.
+     * 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 seedLength - the durable inherited-prefix boundary (0 for unseeded).
+     * @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).
      * @returns the resolved state and title, or `undefined` when unreadable.
      */
     private resolveCold;

package/lib/types/today-spend.js

@@ -20,17 +20,25 @@
  * 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 (`header.seedLength` of them),
- * so the scanner prices only the child's OWN events (`seq >= seedLength`) 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 header, so 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
+ * 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.
+ *
+ * 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
  */
-import { beijingDayKey, emptyTodaySpend, forkBoundaryOf, mergeTodaySpend, priceEvent, SpendAccumulator } from "./billing.js";
+import { beijingDayKey, emptyTodaySpend, forkBoundaryOf, isSeededSession, mergeTodaySpend, priceEvent, SpendAccumulator } from "./billing.js";
 import { BILLING_UNIT_KEY, foldOwnBilling } from "./projection.js";
 /**
  * Fold one session's durable display title: the latest `session/title`
@@ -53,6 +61,56 @@ export function foldSessionTitle(events) {
     }
     return null;
 }
+/**
+ * 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.
+ */
+export function liveSessionEvents(session) {
+    if (session.events !== undefined)
+        return session.events;
+    // Optional-call form keeps the receiver bound (snapshotEvents uses `this`).
+    if (session.snapshotEvents !== undefined)
+        return session.snapshotEvents();
+    throw new Error('llm-billing: session log surface is neither Session.events nor Session.snapshotEvents');
+}
+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.
+ */
+export function persistenceListSnapshots(persistence) {
+    return isHandlePersistence(persistence)
+        ? persistence.list()
+        : persistence.listSnapshots();
+}
+/**
+ * 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.
+ */
+export async function persistenceInspect(persistence, id) {
+    if (isHandlePersistence(persistence)) {
+        const handle = await persistence.open(id, 'read');
+        try {
+            return { events: 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
@@ -176,17 +234,20 @@ export class TodaySpendScanner {
      * until the session is inspected again. A SEEDED session (fork child)
      * skips the ladder entirely: its cached row was folded over the inherited
      * prefix too, so it always detaches through inspect with the durable
-     * boundary applied to the local fold.
+     * 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 seedLength - the durable inherited-prefix boundary (0 for unseeded).
+     * @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).
      * @returns the resolved state and title, or `undefined` when unreadable.
      */
-    async resolveCold(id, seedLength) {
-        const { persistence, projectionCache, unit, logger } = this.deps;
+    async resolveCold(id, seeded) {
+        const { persistence, projectionCache, logger } = this.deps;
         const persistenceService = persistence?.();
         if (persistenceService === undefined)
             return undefined;
-        if (seedLength <= 0) {
+        if (!seeded) {
             const cache = projectionCache?.();
             if (cache !== undefined) {
                 try {
@@ -200,8 +261,11 @@ export class TodaySpendScanner {
             }
         }
         try {
-            const inspection = await persistenceService.inspect(id);
-            return { value: foldOwnBilling(unit, inspection.events, seedLength), title: foldSessionTitle(inspection.events) };
+            const read = await persistenceInspect(persistenceService, id);
+            return {
+                value: foldOwnBilling(this.deps.unit, read.events, read.seedLength),
+                title: foldSessionTitle(read.events),
+            };
         }
         catch (error) {
             // One unreadable session must not blank the whole-day aggregate.
@@ -250,11 +314,11 @@ export class TodaySpendScanner {
             if (store !== undefined) {
                 for (const session of store.list()) {
                     liveIds.add(session.id);
-                    const seedLength = forkBoundaryOf(session.header);
+                    const seedLength = forkBoundaryOf(session);
                     // A fork child's eager cell covers its inherited prefix too; price
                     // its own events directly instead.
                     const state = seedLength > 0
-                        ? this.ownBillingState(session.id, session.events, seedLength)
+                        ? this.ownBillingState(session.id, liveSessionEvents(session), seedLength)
                         : projectionsService?.stateOf(session, BILLING_UNIT_KEY);
                     if (state !== undefined && state.dayKey === dayKey) {
                         total = mergeTodaySpend(total, state.spend);
@@ -265,22 +329,22 @@ export class TodaySpendScanner {
         const persistenceService = persistence?.();
         if (persistenceService === undefined)
             return total;
-        const snapshots = await persistenceService.listSnapshots();
+        const snapshots = await persistenceListSnapshots(persistenceService);
         const pending = [];
         for (const { header, revision } of snapshots) {
             if (liveIds.has(header.id))
                 continue;
-            const seedLength = forkBoundaryOf(header);
+            const seeded = isSeededSession(header);
             const resolved = this.coldResolved.get(header.id);
             if (resolved !== undefined && resolved.revision === revision) {
                 if (resolved.value.dayKey === dayKey)
                     total = mergeTodaySpend(total, resolved.value.spend);
                 continue;
             }
-            pending.push({ id: header.id, revision, seedLength });
+            pending.push({ id: header.id, revision, seeded });
         }
-        await withConcurrency(pending, 8, async ({ id, revision, seedLength }) => {
-            const resolved = await this.resolveCold(id, seedLength);
+        await withConcurrency(pending, 8, async ({ id, revision, seeded }) => {
+            const resolved = await this.resolveCold(id, seeded);
             if (resolved !== undefined)
                 this.coldResolved.set(id, { revision, ...resolved });
         });
@@ -326,7 +390,7 @@ export class TodaySpendScanner {
             if (store !== undefined) {
                 for (const session of store.list()) {
                     liveIds.add(session.id);
-                    collect(session.events, forkBoundaryOf(session.header));
+                    collect(liveSessionEvents(session), forkBoundaryOf(session));
                     if (truncated)
                         break;
                 }
@@ -334,15 +398,15 @@ export class TodaySpendScanner {
         }
         const persistenceService = persistence?.();
         if (!truncated && persistenceService !== undefined) {
-            const snapshots = await persistenceService.listSnapshots();
+            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 inspection = await persistenceService.inspect(header.id);
-                    collect(inspection.events, forkBoundaryOf(inspection.meta));
+                    const read = await persistenceInspect(persistenceService, header.id);
+                    collect(read.events, read.seedLength);
                 }
                 catch (error) {
                     // One unreadable session must not blank the whole-day aggregate.
@@ -381,14 +445,15 @@ export class TodaySpendScanner {
             if (store !== undefined) {
                 for (const session of store.list()) {
                     liveIds.add(session.id);
-                    const seedLength = forkBoundaryOf(session.header);
+                    const seedLength = forkBoundaryOf(session);
+                    const events = liveSessionEvents(session);
                     const state = seedLength > 0
-                        ? this.ownBillingState(session.id, session.events, seedLength)
+                        ? this.ownBillingState(session.id, events, seedLength)
                         : projectionsService?.stateOf(session, BILLING_UNIT_KEY);
                     if (state !== undefined && state.dayKey === dayKey) {
                         rows.set(session.id, {
                             sessionId: session.id,
-                            title: foldSessionTitle(session.events),
+                            title: foldSessionTitle(events),
                             total: state.spend.total,
                         });
                     }
@@ -398,12 +463,12 @@ export class TodaySpendScanner {
         const persistenceService = persistence?.();
         if (persistenceService === undefined)
             return [...rows.values()];
-        const snapshots = await persistenceService.listSnapshots();
+        const snapshots = await persistenceListSnapshots(persistenceService);
         const pending = [];
         for (const { header, revision } of snapshots) {
             if (liveIds.has(header.id))
                 continue;
-            const seedLength = forkBoundaryOf(header);
+            const seeded = isSeededSession(header);
             const resolved = this.coldResolved.get(header.id);
             if (resolved !== undefined && resolved.revision === revision) {
                 if (resolved.value.dayKey === dayKey) {
@@ -411,10 +476,10 @@ export class TodaySpendScanner {
                 }
                 continue;
             }
-            pending.push({ id: header.id, revision, seedLength });
+            pending.push({ id: header.id, revision, seeded });
         }
-        await withConcurrency(pending, 8, async ({ id, revision, seedLength }) => {
-            const resolved = await this.resolveCold(id, seedLength);
+        await withConcurrency(pending, 8, async ({ id, revision, seeded }) => {
+            const resolved = await this.resolveCold(id, seeded);
             if (resolved !== undefined)
                 this.coldResolved.set(id, { revision, ...resolved });
         });
@@ -470,7 +535,7 @@ export class TodaySpendScanner {
             if (store !== undefined) {
                 for (const session of store.list()) {
                     liveIds.add(session.id);
-                    collect(session.id, session.events, forkBoundaryOf(session.header));
+                    collect(session.id, liveSessionEvents(session), forkBoundaryOf(session));
                     if (truncated)
                         break;
                 }
@@ -478,15 +543,15 @@ export class TodaySpendScanner {
         }
         const persistenceService = persistence?.();
         if (!truncated && persistenceService !== undefined) {
-            const snapshots = await persistenceService.listSnapshots();
+            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 inspection = await persistenceService.inspect(header.id);
-                    collect(header.id, inspection.events, forkBoundaryOf(inspection.meta));
+                    const read = await persistenceInspect(persistenceService, header.id);
+                    collect(header.id, read.events, read.seedLength);
                 }
                 catch (error) {
                     // One unreadable session must not blank the whole-day aggregate.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rayadesu/dsh-llm-billing",
   "description": "Standalone DeepSeek account-balance and session-spend provider exposed through the billing Remote",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "publishConfig": {
     "access": "public"
   },
@@ -52,14 +52,14 @@
   },
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-credentials": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-launch-environment": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-session": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-session-persistence": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-session-projection": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-typert-protocol": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-credentials": "^0.1.2-alpha.5",
+    "@deepseek-ai/dsh-launch-environment": "^0.1.2-alpha.5",
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.5",
+    "@deepseek-ai/dsh-llm": "^0.1.2-alpha.5",
+    "@deepseek-ai/dsh-session": "^0.1.2-alpha.5",
+    "@deepseek-ai/dsh-session-persistence": "^0.1.2-alpha.5",
+    "@deepseek-ai/dsh-session-projection": "^0.1.2-alpha.5",
+    "@deepseek-ai/dsh-typert-protocol": "^0.1.2-alpha.5",
     "@deepseek-ai/cordis": "^4.0.1"
   },
   "dependencies": {
@@ -67,14 +67,14 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-credentials": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-launch-environment": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-session": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-session-persistence": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-session-projection": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-typert-protocol": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-credentials": "^0.1.2-alpha.5",
+    "@deepseek-ai/dsh-launch-environment": "^0.1.2-alpha.5",
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.5",
+    "@deepseek-ai/dsh-llm": "^0.1.2-alpha.5",
+    "@deepseek-ai/dsh-session": "^0.1.2-alpha.5",
+    "@deepseek-ai/dsh-session-persistence": "^0.1.2-alpha.5",
+    "@deepseek-ai/dsh-session-projection": "^0.1.2-alpha.5",
+    "@deepseek-ai/dsh-typert-protocol": "^0.1.2-alpha.5",
     "@deepseek-ai/cordis": "^4.0.1"
   }
 }