@rayadesu/dsh-llm-billing 0.3.6 → 0.3.8

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

package/README.md

@@ -35,7 +35,9 @@ A forked session (DSH's "fork" of a conversation) opens its log with a verbatim
 
 ## 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.
+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

@@ -35,7 +35,9 @@
 
 ## 运行时兼容性
 
-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 运行时代码均无需改动即可工作。遇到两种形状都没有的未知运行时表面时，插件会显式失败而不是静默按零花费计价。
+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

@@ -337,6 +337,32 @@ const DEFAULT_MODEL_PRICING = [
 			cacheMissInput: 1.5,
 			output: 4.5
 		}
+	},
+	{
+		model: "mimo-v2.5-pro",
+		peak: {
+			cacheHitInput: .025,
+			cacheMissInput: 3,
+			output: 6
+		},
+		offPeak: {
+			cacheHitInput: .025,
+			cacheMissInput: 3,
+			output: 6
+		}
+	},
+	{
+		model: "mimo-v2.5",
+		peak: {
+			cacheHitInput: .02,
+			cacheMissInput: 1,
+			output: 2
+		},
+		offPeak: {
+			cacheHitInput: .02,
+			cacheMissInput: 1,
+			output: 2
+		}
 	}
 ];
 /**
@@ -836,6 +862,45 @@ function liveSessionEvents(session) {
 	if (session.snapshotEvents !== void 0) return session.snapshotEvents();
 	throw new Error("llm-billing: session log surface is neither Session.events nor Session.snapshotEvents");
 }
+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
@@ -975,10 +1040,10 @@ var TodaySpendScanner = class {
 			}
 		}
 		try {
-			const inspection = await persistenceService.inspect(id);
+			const read = await persistenceInspect(persistenceService, id);
 			return {
-				value: foldOwnBilling(this.deps.unit, inspection.events, forkBoundaryOf(inspection)),
-				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)}`);
@@ -1029,7 +1094,7 @@ var TodaySpendScanner = class {
 		}
 		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;
@@ -1094,13 +1159,13 @@ var TodaySpendScanner = class {
 		}
 		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));
+					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)}`);
 				}
@@ -1141,7 +1206,7 @@ var TodaySpendScanner = class {
 		}
 		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;
@@ -1227,13 +1292,13 @@ var TodaySpendScanner = class {
 		}
 		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));
+					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)}`);
 				}
@@ -1290,6 +1355,14 @@ const DEFAULT_MODELS = [
 	{
 		id: "deepseek-v4-flash-vision-exp",
 		name: "DeepSeek-V4-Flash-Vision-Exp"
+	},
+	{
+		id: "mimo-v2.5-pro",
+		name: "MiMo-V2.5-Pro"
+	},
+	{
+		id: "mimo-v2.5",
+		name: "MiMo-V2.5"
 	}
 ];
 const billingModel = z.object({
@@ -1342,11 +1415,7 @@ async function sessionEvents(ctx, sessionId) {
 	};
 	const persistence = ctx.get("sessionPersistence");
 	if (persistence !== void 0) try {
-		const inspection = await persistence.inspect(sessionId);
-		return {
-			events: inspection.events,
-			seedLength: forkBoundaryOf(inspection)
-		};
+		return await persistenceInspect(persistence, sessionId);
 	} catch (error) {
 		throw new LlmError(`llm-billing: session ${sessionId} not found`, "NOT_FOUND", { cause: error });
 	}
@@ -1440,4 +1509,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, isSeededSession, liveSessionEvents, 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

@@ -110,10 +110,12 @@ export interface ForkBoundarySource {
     /** ≤ 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;
     };
 }
 /**

package/lib/types/billing.js

@@ -40,6 +40,17 @@ export const DEFAULT_MODEL_PRICING = [
         peak: { cacheHitInput: 0.10, cacheMissInput: 3.0, output: 9.0 },
         offPeak: { cacheHitInput: 0.05, cacheMissInput: 1.5, output: 4.5 },
     },
+    // MiMo-V2.5 series (Xiaomi): flat rate, no peak/off-peak distinction.
+    {
+        model: 'mimo-v2.5-pro',
+        peak: { cacheHitInput: 0.025, cacheMissInput: 3.0, output: 6.0 },
+        offPeak: { cacheHitInput: 0.025, cacheMissInput: 3.0, output: 6.0 },
+    },
+    {
+        model: 'mimo-v2.5',
+        peak: { cacheHitInput: 0.02, cacheMissInput: 1.0, output: 2.0 },
+        offPeak: { cacheHitInput: 0.02, cacheMissInput: 1.0, output: 2.0 },
+    },
 ];
 /**
  * Resolve optional configuration to a pricing table, defaulting omitted or

package/lib/types/index.d.ts

@@ -28,9 +28,9 @@ export { addEventContribution, beijingDayKey, computeSessionSpend, computeTodayS
 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, liveSessionEvents, 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 { liveSessionEvents, 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, isSeededSession, mergeTodaySpend, priceEvent, resolveBilling, SpendAccumulator, } from "./billing.js";
 export { BILLING_UNIT_KEY, billingTodaySpendDefinition, foldBillingUnit, foldOwnBilling } from "./projection.js";
-export { foldSessionTitle, liveSessionEvents, 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';
@@ -41,6 +41,8 @@ const DEFAULT_MODELS = [
     { id: 'deepseek-v4-flash', name: 'DeepSeek-V4-Flash' },
     { id: 'deepseek-v4-pro', name: 'DeepSeek-V4-Pro' },
     { id: 'deepseek-v4-flash-vision-exp', name: 'DeepSeek-V4-Flash-Vision-Exp' },
+    { id: 'mimo-v2.5-pro', name: 'MiMo-V2.5-Pro' },
+    { id: 'mimo-v2.5', name: 'MiMo-V2.5' },
 ];
 const billingModel = z.object({
     id: z.string().required(),
@@ -93,8 +95,7 @@ async function sessionEvents(ctx, sessionId) {
     const persistence = ctx.get('sessionPersistence');
     if (persistence !== undefined) {
         try {
-            const inspection = await persistence.inspect(sessionId);
-            return { events: inspection.events, seedLength: forkBoundaryOf(inspection) };
+            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

@@ -42,8 +42,7 @@ 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
@@ -64,7 +63,7 @@ export interface ScannerSession {
     /** ≤ 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[];
+    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). */
@@ -88,6 +87,67 @@ export interface ScannerPersistedHeader {
     /** 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). */
@@ -95,21 +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?: {
-                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;
+    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;
@@ -128,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. */

package/lib/types/today-spend.js

@@ -75,6 +75,42 @@ export function liveSessionEvents(session) {
         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
@@ -225,10 +261,10 @@ export class TodaySpendScanner {
             }
         }
         try {
-            const inspection = await persistenceService.inspect(id);
+            const read = await persistenceInspect(persistenceService, id);
             return {
-                value: foldOwnBilling(this.deps.unit, inspection.events, forkBoundaryOf(inspection)),
-                title: foldSessionTitle(inspection.events),
+                value: foldOwnBilling(this.deps.unit, read.events, read.seedLength),
+                title: foldSessionTitle(read.events),
             };
         }
         catch (error) {
@@ -293,7 +329,7 @@ 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))
@@ -362,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));
+                    const read = await persistenceInspect(persistenceService, header.id);
+                    collect(read.events, read.seedLength);
                 }
                 catch (error) {
                     // One unreadable session must not blank the whole-day aggregate.
@@ -427,7 +463,7 @@ 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))
@@ -507,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));
+                    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.6",
+  "version": "0.3.8",
   "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"
   }
 }