@rayadesu/dsh-llm-billing 0.3.4 → 0.3.6

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: 85c6cc052cd3332f23351db8123259565a669602
+README.zh.md: 96d0d9d70fe94bfb0afa2e2af3f97231103d3590

package/README.md

@@ -31,7 +31,11 @@ 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.1-rc.2`) 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.
 
 ## Configuration
 

package/README.zh.md

@@ -31,7 +31,11 @@
 
 ## 分叉会话
 
-分叉会话（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.1-rc.2`）与超前于它的 monorepo 运行时代码均无需改动即可工作。遇到两种形状都没有的未知运行时表面时，插件会显式失败而不是静默按零花费计价。
 
 ## 配置
 

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,17 @@ 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");
+}
+/**
 * 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 +950,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];
@@ -947,7 +977,7 @@ var TodaySpendScanner = class {
 		try {
 			const inspection = await persistenceService.inspect(id);
 			return {
-				value: foldOwnBilling(unit, inspection.events, seedLength),
+				value: foldOwnBilling(this.deps.unit, inspection.events, forkBoundaryOf(inspection)),
 				title: foldSessionTitle(inspection.events)
 			};
 		} catch (error) {
@@ -992,8 +1022,8 @@ 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);
 			}
 		}
@@ -1003,7 +1033,7 @@ var TodaySpendScanner = class {
 		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 +1042,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,7 +1088,7 @@ 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;
 			}
 		}
@@ -1070,7 +1100,7 @@ var TodaySpendScanner = class {
 				if (this.lastEventsScan?.get(header.id) === revision) continue;
 				try {
 					const inspection = await persistenceService.inspect(header.id);
-					collect(inspection.events, forkBoundaryOf(inspection.meta));
+					collect(inspection.events, forkBoundaryOf(inspection));
 				} catch (error) {
 					logger.warn(`llm-billing: skipping unreadable session ${header.id}: ${String(error)}`);
 				}
@@ -1099,11 +1129,12 @@ 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
 				});
 			}
@@ -1114,7 +1145,7 @@ var TodaySpendScanner = class {
 		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 +1158,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,7 +1221,7 @@ 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;
 			}
 		}
@@ -1202,7 +1233,7 @@ var TodaySpendScanner = class {
 				if (this.lastEventsScan?.get(header.id) === revision) continue;
 				try {
 					const inspection = await persistenceService.inspect(header.id);
-					collect(header.id, inspection.events, forkBoundaryOf(inspection.meta));
+					collect(header.id, inspection.events, forkBoundaryOf(inspection));
 				} catch (error) {
 					logger.warn(`llm-billing: skipping unreadable session ${header.id}: ${String(error)}`);
 				}
@@ -1294,7 +1325,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,15 +1337,15 @@ 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)
+			seedLength: forkBoundaryOf(inspection)
 		};
 	} catch (error) {
 		throw new LlmError(`llm-billing: session ${sessionId} not found`, "NOT_FOUND", { cause: error });
@@ -1406,4 +1440,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, priceEvent, resolveBilling };

package/lib/types/billing.d.ts

@@ -88,21 +88,52 @@ 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;
+    };
+    /** ≤ 0.1.1-rc.2: the `meta` of a persistence `inspect` result (its `seedLength`). */
+    readonly meta?: {
+        readonly seedLength?: number;
+    };
+}
+/**
+ * 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,12 +24,12 @@ 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 { foldSessionTitle, liveSessionEvents, TodaySpendCache, TodaySpendScanner } from './today-spend.ts';
 export type { ScannerPersistedHeader, ScannerSession, TodaySpendScannerDeps } from './today-spend.ts';
 export declare const name = "llm-billing";
 /** Public API default; deployments may point elsewhere via $DEEPSEEK_BASE_URL. */

package/lib/types/index.js

@@ -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, 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, 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,14 @@ 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 { events: inspection.events, seedLength: forkBoundaryOf(inspection) };
         }
         catch (error) {
             throw new LlmError(`llm-billing: session ${sessionId} not found`, 'NOT_FOUND', { cause: error });

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

@@ -20,14 +20,22 @@
  * 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';
@@ -45,20 +53,40 @@ 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. */
+    readonly 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;
 }
 /** Structural slices of the optional services the scanner reads through. */
 export interface TodaySpendScannerDeps {
@@ -73,9 +101,12 @@ export interface TodaySpendScannerDeps {
             revision: SessionPersistenceRevision;
         }[]>;
         inspect(id: SessionId): Promise<{
-            meta: {
-                seedLength?: number;
+            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[];
         }>;
     } | undefined;
@@ -179,9 +210,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,20 @@ 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');
+}
 /**
  * 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 +198,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 {
@@ -201,7 +226,10 @@ export class TodaySpendScanner {
         }
         try {
             const inspection = await persistenceService.inspect(id);
-            return { value: foldOwnBilling(unit, inspection.events, seedLength), title: foldSessionTitle(inspection.events) };
+            return {
+                value: foldOwnBilling(this.deps.unit, inspection.events, forkBoundaryOf(inspection)),
+                title: foldSessionTitle(inspection.events),
+            };
         }
         catch (error) {
             // One unreadable session must not blank the whole-day aggregate.
@@ -250,11 +278,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);
@@ -270,17 +298,17 @@ export class TodaySpendScanner {
         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 +354,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;
                 }
@@ -342,7 +370,7 @@ export class TodaySpendScanner {
                     continue;
                 try {
                     const inspection = await persistenceService.inspect(header.id);
-                    collect(inspection.events, forkBoundaryOf(inspection.meta));
+                    collect(inspection.events, forkBoundaryOf(inspection));
                 }
                 catch (error) {
                     // One unreadable session must not blank the whole-day aggregate.
@@ -381,14 +409,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,
                         });
                     }
@@ -403,7 +432,7 @@ export class TodaySpendScanner {
         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 +440,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 +499,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;
                 }
@@ -486,7 +515,7 @@ export class TodaySpendScanner {
                     continue;
                 try {
                     const inspection = await persistenceService.inspect(header.id);
-                    collect(header.id, inspection.events, forkBoundaryOf(inspection.meta));
+                    collect(header.id, inspection.events, forkBoundaryOf(inspection));
                 }
                 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.4",
+  "version": "0.3.6",
   "publishConfig": {
     "access": "public"
   },