@rayadesu/dsh-llm-billing 0.3.8 → 0.3.10

package/lib/types/index.d.ts

@@ -24,8 +24,8 @@ 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, isSeededSession, mergeTodaySpend, priceEvent, resolveBilling, SpendAccumulator, } from './billing.ts';
-export type { BillingConfig, BillingConfigModel, BillingEventContribution, DeepSeekModelPricing, DeepSeekTokenPrice, PeakHourWindow, ResolvedBilling, } from './billing.ts';
+export { addEventContribution, applyBillingEvent, beijingDayKey, BillingFolder, computeSessionSpend, computeSessionTurnSpends, computeTodaySpend, computeTurnSpend, DEFAULT_MODEL_PRICING, DEFAULT_PEAK_HOURS, emptyBillingFoldState, emptyTodaySpend, FLASH_SERIES_RATE_CHANGE_AT, forkBoundaryOf, isPeak, isSeededSession, mergeTodaySpend, negateSpend, priceEvent, priceUsage, resolveBilling, SessionTurnSpendFolder, SpendAccumulator, subtractSpend, V4_PRO_ROUTE_SWITCH_AT, } from './billing.ts';
+export type { BillingConfig, BillingConfigModel, BillingEventContribution, BillingFoldSample, BillingFoldState, DeepSeekModelPricing, DeepSeekRateRevision, DeepSeekTokenPrice, PeakHourWindow, ResolvedBilling, } from './billing.ts';
 export type * from './types.ts';
 export { BILLING_UNIT_KEY, billingTodaySpendDefinition, foldBillingUnit, foldOwnBilling } from './projection.ts';
 export type { BillingUnitFold, BillingUnitState } from './projection.ts';
@@ -52,9 +52,14 @@ export interface Config {
     apiKeyEnv?: string;
     /** Endpoint base; defaults to `$DEEPSEEK_BASE_URL`, then `https://api.deepseek.com`. */
     baseURL?: string;
-    /** Advisory display rows, in presentation order; defaults to V4 Flash, V4 Pro, and V4 Flash Vision Exp. */
+    /** Advisory display rows, in presentation order; defaults to V4 Flash, V4.1 Flash, V4 Pro, and V4 Flash Vision Exp. */
     models?: BillingModel[];
-    /** Pricing table and peak-hour windows; omission uses the published defaults. Peak windows apply weekdays (Monday–Friday) only; weekends are always off-peak. */
+    /**
+     * Pricing table and peak-hour windows; omission uses the published defaults
+     * (including the V4 Flash series re-pricing effective 2026-09-10 12:00
+     * Beijing). Peak windows apply weekdays (Monday–Friday) only; weekends are
+     * always off-peak.
+     */
     billing?: BillingConfig;
 }
 export declare const Config: z<Config>;
@@ -62,8 +67,18 @@ export declare const Config: z<Config>;
 export declare const TODAY_SPEND_CACHE_MS = 60000;
 /** Hard cap on today's events collected by the events scan path. */
 export declare const TODAY_SPEND_MAX_EVENTS = 200000;
+/** Max session-spend rows kept for incremental recompute before eviction. */
+export declare const SESSION_SPEND_CACHE_LIMIT = 1024;
+/** Max session-id entries kept in the per-turn-cost fold cache before eviction. */
+export declare const SESSION_TURN_SPEND_CACHE_LIMIT = 64;
+/** How long one balance snapshot is reused before the host refetches it (15s). */
+export declare const BALANCE_CACHE_MS = 15000;
+/** Hard cap on one `/user/balance` request (5s); a hung endpoint never blocks the badge. */
+export declare const BALANCE_TIMEOUT_MS = 5000;
 /**
- * Register the `billing` Remote under the `billing` namespace.
+ * Register the `billing` Remote under the `billing` namespace. Assembly only:
+ * facts resolve once, each loader owns its caches, and the gateway receives
+ * the bound thunks.
  * @param ctx - owning plugin context.
  * @param config - validated plugin config.
  */

package/lib/types/index.js

@@ -25,11 +25,11 @@ import { assertUsableApiKey, LlmError } from '@deepseek-ai/dsh-llm';
 import { credentialRef } from '@deepseek-ai/dsh-credentials';
 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 { computeSessionSpend, computeTurnSpend, DEFAULT_MODEL_PRICING, DEFAULT_PEAK_HOURS, forkBoundaryOf, mergeTodaySpend, resolveBilling, SessionTurnSpendFolder, } from "./billing.js";
 import { billingTodaySpendDefinition } from "./projection.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 { addEventContribution, applyBillingEvent, beijingDayKey, BillingFolder, computeSessionSpend, computeSessionTurnSpends, computeTodaySpend, computeTurnSpend, DEFAULT_MODEL_PRICING, DEFAULT_PEAK_HOURS, emptyBillingFoldState, emptyTodaySpend, FLASH_SERIES_RATE_CHANGE_AT, forkBoundaryOf, isPeak, isSeededSession, mergeTodaySpend, negateSpend, priceEvent, priceUsage, resolveBilling, SessionTurnSpendFolder, SpendAccumulator, subtractSpend, V4_PRO_ROUTE_SWITCH_AT, } from "./billing.js";
 export { BILLING_UNIT_KEY, billingTodaySpendDefinition, foldBillingUnit, foldOwnBilling } from "./projection.js";
 export { foldSessionTitle, liveSessionEvents, persistenceInspect, persistenceListSnapshots, TodaySpendCache, TodaySpendScanner } from "./today-spend.js";
 export const name = 'llm-billing';
@@ -37,8 +37,17 @@ const DEFAULT_API_KEY_ENV = 'DEEPSEEK_API_KEY';
 const BASE_URL_ENV = 'DEEPSEEK_BASE_URL';
 /** Public API default; deployments may point elsewhere via $DEEPSEEK_BASE_URL. */
 export const PUBLIC_BASE_URL = 'https://api.deepseek.com';
+/**
+ * Advisory display rows mirroring the DSH `llm-deepseek` catalog (V4.1 Flash
+ * first, its current default route), plus the MiMo-V2.5 series. The retired
+ * preview id `deepseek-v4.1-flash-expires-on-0910` stays so the logs that used
+ * it keep a readable label; rows never restrict which models are priced — the
+ * pricing table does.
+ */
 const DEFAULT_MODELS = [
+    { id: 'deepseek-flash', name: 'DeepSeek-V41-Flash' },
     { id: 'deepseek-v4-flash', name: 'DeepSeek-V4-Flash' },
+    { id: 'deepseek-v4.1-flash-expires-on-0910', name: 'DeepSeek-V4.1-Flash' },
     { id: 'deepseek-v4-pro', name: 'DeepSeek-V4-Pro' },
     { id: 'deepseek-v4-flash-vision-exp', name: 'DeepSeek-V4-Flash-Vision-Exp' },
     { id: 'mimo-v2.5-pro', name: 'MiMo-V2.5-Pro' },
@@ -53,16 +62,22 @@ const tokenPrice = z.object({
     cacheMissInput: z.number().min(0),
     output: z.number().min(0),
 });
+const billingRateRow = z.object({
+    model: z.string().required(),
+    peak: tokenPrice,
+    offPeak: tokenPrice,
+    // Several rows may share one model: each is a rate revision, and samples are
+    // priced by the revision in effect at their own timestamp (epoch ms,
+    // inclusive).
+    effectiveFrom: z.number().min(0),
+});
 const billingConfig = z.object({
+    // Copies of the readonly published tables, taken once at module load.
     peakHours: z.array(z.object({
         start: z.number().step(1).min(0).max(23),
         end: z.number().step(1).min(0).max(24),
-    })).default(DEFAULT_PEAK_HOURS),
-    models: z.array(z.object({
-        model: z.string().required(),
-        peak: tokenPrice,
-        offPeak: tokenPrice,
-    })).default(DEFAULT_MODEL_PRICING),
+    })).default([...DEFAULT_PEAK_HOURS]),
+    models: z.array(billingRateRow).default([...DEFAULT_MODEL_PRICING]),
 });
 export const Config = z.object({
     apiKeyEnv: z.string().role('credential-ref').default(DEFAULT_API_KEY_ENV),
@@ -74,6 +89,27 @@ export const Config = z.object({
 export const TODAY_SPEND_CACHE_MS = 60_000;
 /** Hard cap on today's events collected by the events scan path. */
 export const TODAY_SPEND_MAX_EVENTS = 200_000;
+/** Max session-spend rows kept for incremental recompute before eviction. */
+export const SESSION_SPEND_CACHE_LIMIT = 1024;
+/** Max session-id entries kept in the per-turn-cost fold cache before eviction. */
+export const SESSION_TURN_SPEND_CACHE_LIMIT = 64;
+/** How long one balance snapshot is reused before the host refetches it (15s). */
+export const BALANCE_CACHE_MS = 15_000;
+/** Hard cap on one `/user/balance` request (5s); a hung endpoint never blocks the badge. */
+export const BALANCE_TIMEOUT_MS = 5_000;
+/**
+ * Bounded-map eviction: drop the oldest inserted entry once `size` reached
+ * `limit`, so an unbounded session-id space grows the map no further. Evicting
+ * one entry (instead of clearing) keeps the other sessions' incremental
+ * spend warm.
+ */
+function evictOldest(map, limit) {
+    if (map.size < limit)
+        return;
+    const oldest = map.keys().next().value;
+    if (oldest !== undefined)
+        map.delete(oldest);
+}
 /**
  * Read one session's event log and durable seed boundary: the live
  * SessionStore first, then the persistence backend for a flushed session
@@ -103,84 +139,111 @@ async function sessionEvents(ctx, sessionId) {
     }
     throw new LlmError(`llm-billing: session ${sessionId} not found`, 'NOT_FOUND');
 }
+/** Resolve the plugin's static facts once: endpoint, credential ref, pricing table. */
+function resolveFacts(ctx, config) {
+    return {
+        baseURL: () => config.baseURL
+            ?? launchEnvironmentOf(ctx).get(BASE_URL_ENV)?.value
+            ?? PUBLIC_BASE_URL,
+        apiKeyRef: credentialRef(config.apiKeyEnv ?? DEFAULT_API_KEY_ENV),
+        billing: resolveBilling(config.billing),
+        catalog: (config.models ?? DEFAULT_MODELS).map(model => ({ id: model.id, name: model.name ?? model.id })),
+    };
+}
 /**
- * Register the `billing` Remote under the `billing` namespace.
- * @param ctx - owning plugin context.
- * @param config - validated plugin config.
+ * Resolve the API key per call: the credentials service first, then the
+ * launch environment fallback.
+ * @throws {@link LlmError} with code `MISSING_CREDENTIAL` when neither yields a usable key.
  */
-export function apply(ctx, config) {
-    const baseURL = () => config.baseURL
-        ?? launchEnvironmentOf(ctx).get(BASE_URL_ENV)?.value
-        ?? PUBLIC_BASE_URL;
-    const apiKeyRef = credentialRef(config.apiKeyEnv ?? DEFAULT_API_KEY_ENV);
-    const resolveApiKey = async () => {
-        const credentials = ctx.get('credentials');
-        if (credentials !== undefined) {
-            const hit = await credentials.resolve(apiKeyRef);
-            if (hit !== undefined)
-                return assertUsableApiKey(hit.value, 'llm-billing', apiKeyRef);
-        }
-        else {
-            const ambient = launchEnvironmentOf(ctx).get(apiKeyRef);
-            if (ambient !== undefined && ambient.value.length > 0) {
-                return assertUsableApiKey(ambient.value, 'llm-billing', apiKeyRef);
-            }
+async function resolveApiKey(ctx, apiKeyRef) {
+    const credentials = ctx.get('credentials');
+    if (credentials !== undefined) {
+        const hit = await credentials.resolve(apiKeyRef);
+        if (hit !== undefined)
+            return assertUsableApiKey(hit.value, 'llm-billing', apiKeyRef);
+    }
+    else {
+        const ambient = launchEnvironmentOf(ctx).get(apiKeyRef);
+        if (ambient !== undefined && ambient.value.length > 0) {
+            return assertUsableApiKey(ambient.value, 'llm-billing', apiKeyRef);
         }
-        throw new LlmError(`llm-billing: no API key; store ${apiKeyRef} through the credentials service or export it`, 'MISSING_CREDENTIAL');
-    };
-    const fetchBalance = async () => {
-        const apiKey = await resolveApiKey();
-        return fetchDeepSeekBalance(baseURL(), apiKey);
-    };
-    const billing = resolveBilling(config.billing);
-    const catalog = (config.models ?? DEFAULT_MODELS).map(model => ({ id: model.id, name: model.name ?? model.id }));
-    // Per-session incremental spend cache: a session log is append-only and
-    // chronological (the same assumption the projection unit makes), so a spend
-    // computed for `count` EVENTS OF THE SESSION'S OWN WORK (the log minus its
-    // inherited fork prefix) stays valid while the log length is unchanged, and
-    // only the appended tail needs pricing when it grows. A forked child's
-    // inherited prefix (`seq < seedLength`) is priced only in its source
-    // session; the map is capped so an unbounded session-id space cannot grow
-    // it without bound.
+    }
+    throw new LlmError(`llm-billing: no API key; store ${apiKeyRef} through the credentials service or export it`, 'MISSING_CREDENTIAL');
+}
+/**
+ * Per-session incremental spend loader: a session log is append-only and
+ * chronological (the same assumption the projection unit makes), so a spend
+ * computed for `count` EVENTS OF THE SESSION'S OWN WORK (the log minus its
+ * inherited fork prefix) stays valid while the log length is unchanged, and
+ * only the appended tail needs pricing when it grows. A forked child's
+ * inherited prefix (`seq < seedLength`) is priced only in its source
+ * session; the cache is bounded (see {@link evictOldest}), so an unbounded
+ * session-id space cannot grow it without bound.
+ */
+function createSessionSpendFetcher(ctx, facts) {
     const sessionSpendCache = new Map();
-    const fetchSessionSpend = async (sessionId) => {
+    return async (sessionId) => {
         const { events, seedLength } = await sessionEvents(ctx, sessionId);
         const ownCount = events.length - seedLength;
         const cached = sessionSpendCache.get(sessionId);
-        if (cached !== undefined && cached.count === ownCount)
+        if (cached !== undefined && cached.count === ownCount) {
+            // LRU touch: re-insert so the entry is evicted only after fresher ones.
+            sessionSpendCache.delete(sessionId);
+            sessionSpendCache.set(sessionId, cached);
             return cached.spend;
+        }
         if (cached !== undefined && cached.count < ownCount) {
-            const spend = mergeTodaySpend(cached.spend, computeSessionSpend(events.slice(seedLength + cached.count), billing, catalog));
+            const spend = mergeTodaySpend(cached.spend, computeSessionSpend(events.slice(seedLength + cached.count), facts.billing, facts.catalog));
+            evictOldest(sessionSpendCache, SESSION_SPEND_CACHE_LIMIT);
             sessionSpendCache.set(sessionId, { count: ownCount, spend });
             return spend;
         }
-        const spend = computeSessionSpend(events, billing, catalog, seedLength);
-        if (sessionSpendCache.size >= 1024)
-            sessionSpendCache.clear();
+        const spend = computeSessionSpend(events, facts.billing, facts.catalog, seedLength);
+        evictOldest(sessionSpendCache, SESSION_SPEND_CACHE_LIMIT);
         sessionSpendCache.set(sessionId, { count: ownCount, spend });
         return spend;
     };
-    // Plan C: register the per-session spend projection unit on the projection
-    // registry. Registration is lazy — it happens on the first projection-path
-    // scan, not through `ctx.inject` (whose plugin-mount wait would also engage
-    // the test-invariant host in suites that never provide the registry). The
-    // registry builds cells lazily over the in-memory log, so events committed
-    // before registration are folded on first touch; without the registry the
-    // events path serves today's spend.
-    const unit = billingTodaySpendDefinition(billing, catalog);
-    let unitRegistered = false;
-    const ensureUnit = () => {
-        if (unitRegistered)
+}
+/**
+ * Once-registrar for the billing projection unit: the first call that finds
+ * the registry composed registers the shared unit and every later call is a
+ * no-op. Registering as early as the registry exists lets DSH's projection
+ * write-behind (mandatory at `turn/end`) checkpoint a billing row for every
+ * session that runs in this process, which is what makes the zero-I/O cold
+ * path in {@link TodaySpendScanner} hit after the next restart.
+ * @param ctx - plugin context.
+ * @param unit - the unit definition built once per plugin config.
+ * @returns an idempotent registrar.
+ */
+function createUnitRegistrar(ctx, unit) {
+    let registered = false;
+    return () => {
+        if (registered)
             return;
         const registry = ctx.get('sessionProjections');
         if (registry === undefined)
             return;
         registry.register(unit);
-        unitRegistered = true;
+        registered = true;
     };
-    // Plans A1–A3: 60s Beijing-day cache with in-flight coalescing and a force
-    // bypass, over a revision-gated scanner (projection path when the registry
-    // is composed, events path otherwise).
+}
+/**
+ * Today-spend loaders over one revision-gated scanner with two 60s
+ * Beijing-day caches (in-flight coalescing and a `force` bypass):
+ * - plan C uses the per-session spend projection unit registered by the
+ *   caller's {@link createUnitRegistrar} as early as the registry exists (the
+ *   registry builds cells lazily over the in-memory log, so events committed
+ *   before registration are folded on first touch); without the registry the
+ *   events path serves today's spend.
+ * - plans A1–A3: the scanner chooses the projection path when the registry
+ *   is composed, the events path otherwise.
+ * @param ctx - plugin context.
+ * @param facts - resolved endpoint, credential, pricing, and catalog facts.
+ * @param unit - the shared projection unit definition.
+ * @param ensureUnit - idempotent unit registrar (last-resort registration).
+ * @returns the two today-spend loaders.
+ */
+function createTodaySpendLoaders(ctx, facts, unit, ensureUnit) {
     const scanner = new TodaySpendScanner({
         sessions: () => ctx.get('sessions'),
         persistence: () => ctx.get('sessionPersistence'),
@@ -190,17 +253,108 @@ export function apply(ctx, config) {
         unit,
         maxEvents: TODAY_SPEND_MAX_EVENTS,
         logger: ctx.logger,
-        billing,
-        catalog,
+        billing: facts.billing,
+        catalog: facts.catalog,
     });
-    const todayCache = new TodaySpendCache(dayKey => scanner.scan(dayKey), TODAY_SPEND_CACHE_MS);
-    const todaySessionsCache = new TodaySpendCache(dayKey => scanner.scanSessions(dayKey), TODAY_SPEND_CACHE_MS);
-    const fetchTodaySpend = async (force = false) => todayCache.get(force);
-    const fetchTodaySessionsSpend = async (force = false) => todaySessionsCache.get(force);
-    const fetchTurnSpend = async (sessionId, messageId) => {
+    const todayCache = new TodaySpendCache(dayKey => scanner.scanDetail(dayKey), TODAY_SPEND_CACHE_MS);
+    return {
+        fetchTodaySpend: async (force = false) => (await todayCache.get(force)).aggregate,
+        fetchTodaySessionsSpend: async (force = false) => ({ sessions: (await todayCache.get(force)).sessions }),
+    };
+}
+/** One completed Turn's spend loader, located by its closing message id. */
+function createTurnSpendFetcher(ctx, facts) {
+    return async (sessionId, messageId) => {
+        const { events } = await sessionEvents(ctx, sessionId);
+        return computeTurnSpend(events, facts.billing, facts.catalog, messageId);
+    };
+}
+/**
+ * Every completed Turn's cost in one session, folded incrementally per session
+ * (session logs are append-only, so only the appended tail is priced on a
+ * growing log). One call serves a whole transcript's per-message cost rows,
+ * replacing the per-message `getTurnSpend` fan-out.
+ */
+function createTurnSpendsFetcher(ctx, facts) {
+    const folders = new Map();
+    return async (sessionId) => {
         const { events } = await sessionEvents(ctx, sessionId);
-        return computeTurnSpend(events, billing, catalog, messageId);
+        let entry = folders.get(sessionId);
+        if (entry === undefined || entry.count > events.length) {
+            entry = { folder: new SessionTurnSpendFolder(facts.billing, facts.catalog), count: 0 };
+            evictOldest(folders, SESSION_TURN_SPEND_CACHE_LIMIT);
+            folders.set(sessionId, entry);
+        }
+        if (entry.count !== events.length) {
+            entry.folder.feed(events);
+            entry.count = events.length;
+        }
+        return entry.folder.finish();
+    };
+}
+/**
+ * Balance loader with a short host-side TTL and a hard request timeout: the
+ * credential resolves per call, a fresh snapshot is reused for
+ * {@link BALANCE_CACHE_MS} (so several badge mounts and several browsers share
+ * one `/user/balance` call), concurrent misses coalesce, and `force` bypasses
+ * the TTL for the manual refresh. A hung endpoint aborts after
+ * {@link BALANCE_TIMEOUT_MS} instead of holding the badge's fetch forever.
+ * @param ctx - plugin context carrying the credential seam.
+ * @param facts - resolved endpoint and credential facts.
+ * @returns the balance loader.
+ */
+function createBalanceFetcher(ctx, facts) {
+    let cached;
+    let inflight;
+    return async (force = false) => {
+        if (!force && cached !== undefined && Date.now() - cached.at < BALANCE_CACHE_MS)
+            return cached.value;
+        if (inflight !== undefined)
+            return inflight;
+        const run = (async () => {
+            try {
+                const apiKey = await resolveApiKey(ctx, facts.apiKeyRef);
+                const value = await fetchDeepSeekBalance(facts.baseURL(), apiKey, AbortSignal.timeout(BALANCE_TIMEOUT_MS));
+                cached = { at: Date.now(), value };
+                return value;
+            }
+            finally {
+                inflight = undefined;
+            }
+        })();
+        inflight = run;
+        return run;
     };
-    new DeepSeekBalanceGateway(ctx, { fetchBalance, fetchSessionSpend, fetchTodaySpend, fetchTodaySessionsSpend, fetchTurnSpend });
+}
+/**
+ * Register the `billing` Remote under the `billing` namespace. Assembly only:
+ * facts resolve once, each loader owns its caches, and the gateway receives
+ * the bound thunks.
+ * @param ctx - owning plugin context.
+ * @param config - validated plugin config.
+ */
+export function apply(ctx, config) {
+    const facts = resolveFacts(ctx, config);
+    // One unit instance per plugin config, registered as early as the registry
+    // exists (and again on the first session created, in case the registry is
+    // composed after this plugin): DSH's write-behind then checkpoints a
+    // billing row for every session that runs in this process.
+    const unit = billingTodaySpendDefinition(facts.billing, facts.catalog);
+    const ensureUnit = createUnitRegistrar(ctx, unit);
+    ensureUnit();
+    ctx.on('session/created', ensureUnit);
+    const fetchBalance = createBalanceFetcher(ctx, facts);
+    const fetchSessionSpend = createSessionSpendFetcher(ctx, facts);
+    const { fetchTodaySpend, fetchTodaySessionsSpend } = createTodaySpendLoaders(ctx, facts, unit, ensureUnit);
+    const fetchTurnSpend = createTurnSpendFetcher(ctx, facts);
+    const fetchTurnSpends = createTurnSpendsFetcher(ctx, facts);
+    new DeepSeekBalanceGateway(ctx, {
+        fetchBalance,
+        fetchSessionSpend,
+        fetchTodaySpend,
+        fetchTodaySessionsSpend,
+        fetchTurnSpend,
+        fetchTurnSpends,
+    });
 }
 //# sourceMappingURL=index.js.map

package/lib/types/projection.d.ts

@@ -1,37 +1,36 @@
 /**
- * `billingTodaySpend` session-projection unit: per-session, per-Beijing-day
- * billed spend, folded eagerly by the DSH projection drive over committed
- * session events and checkpointed by the projection cache. The unit keeps only
- * the spend of the session's LATEST priced day (events are append-only and
- * chronological, so a day strictly older than the state's day never returns);
- * the aggregate "today" read sums the units whose `dayKey` matches the current
- * Beijing day — zero full-log scans once the fold is warm.
+ * `billingTodaySpend` session-projection unit: per-session billed spend,
+ * folded eagerly by the DSH projection drive over committed session events and
+ * checkpointed by the projection cache. The state keeps the session's LATEST
+ * priced Beijing day, its whole-session total, the fork boundary, the latest
+ * request model, and the last priced attempt sample (DSH's same-step
+ * replacement rule); the aggregate "today" read sums the units whose `dayKey`
+ * matches the current Beijing day — zero full-log scans once the fold is warm.
  *
- * The unit's fold shares {@link priceEvent} with the events-scan paths
- * (`computeTodaySpend`), so both price with the same table. The unit is
+ * The unit's fold IS the shared pricing fold ({@link applyBillingEvent}), so
+ * the projection path and the events-scan paths cannot drift. The unit is
  * client-visible (`wire` = identity) because the persisted-cache read ladder
- * (`sessionProjectionCache.coldSnapshot` / registry `restore`) serves only
- * wired units; the wire value is the state itself.
+ * (`sessionProjectionCache.cachedSnapshot` / registry `restore`) serves only
+ * wired units, and because the browser half reads this value through
+ * `useProjection` instead of polling a Remote; the wire value is the state
+ * itself.
  * @module @rayadesu/dsh-llm-billing/projection
  */
 import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection';
 import type { SessionEvent } from '@deepseek-ai/dsh-session';
-import type { ResolvedBilling } from './billing.ts';
-import type { DeepSeekTodaySpend } from './types.ts';
+import type { BillingFoldState, ResolvedBilling } from './billing.ts';
 /** The projection key this unit owns. */
 export declare const BILLING_UNIT_KEY = "billingTodaySpend";
 /**
- * Per-session unit state: the Beijing day of the session's latest priced
- * event and that day's billed spend. `dayKey` is `''` while the session has no
- * priced usage, and the state only ever describes ONE day (the latest) —
- * plain JSON, as the persisted-cache contract requires.
+ * The unit's state is the shared billing fold state: the latest priced
+ * Beijing day, the whole-session total, the fork boundary, the latest request
+ * model, and the last priced attempt sample. Plain JSON, as the
+ * persisted-cache contract requires. The fold is boundary-aware: it prices
+ * only the session's OWN events (a fork child's inherited prefix is skipped),
+ * so both totals match the Remote paths and the client can read them without
+ * a Remote call.
  */
-export interface BillingUnitState {
-    /** Beijing-time calendar-day key of the state's spend; `''` for no priced usage. */
-    dayKey: string;
-    /** The spend of the session's latest priced Beijing day. */
-    spend: DeepSeekTodaySpend;
-}
+export type BillingUnitState = BillingFoldState;
 declare module '@deepseek-ai/dsh-session-projection/types' {
     interface SessionProjectionStateMap {
         billingTodaySpend: BillingUnitState;
@@ -49,13 +48,15 @@ export type BillingUnitDefinition = Omit<ProjectionDefinition<'billingTodaySpend
     wire: NonNullable<ProjectionDefinition<'billingTodaySpend', BillingUnitState>['wire']>;
 };
 /**
- * Build the `billingTodaySpend` unit for one resolved pricing table. The
- * pricing closure is fixed at registration; a pricing-table change therefore
- * prices only events folded after the change (historical spend keeps its
- * historical rates), unlike the events-scan paths which re-price the whole
- * log. Bump {@link ProjectionDefinition.stateVersion} whenever the state
- * shape or fold semantics change, so persisted checkpoint rows are discarded
- * instead of folded forward.
+ * Build the `billingTodaySpend` unit for one resolved pricing table. Published
+ * rate revisions travel inside the closure and are resolved per sample
+ * timestamp, so a re-priced series bills its own history correctly however late
+ * a log is folded; only a configuration change (editing `billing.models`) is
+ * fixed at registration, and it re-prices just the events folded afterwards
+ * (the events-scan paths re-price the whole log). Bump
+ * {@link ProjectionDefinition.stateVersion} whenever the state shape or fold
+ * semantics change, so persisted checkpoint rows are discarded instead of
+ * folded forward.
  * @param billing - resolved pricing with peak-hour windows.
  * @param catalog - model display rows, in presentation order.
  * @returns the unit definition to register on `ctx.sessionProjections`.
@@ -69,8 +70,8 @@ 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.
+     * count. Detached folds call it with no arguments and apply the boundary
+     * themselves (see {@link foldOwnBilling}), so both call shapes stay valid.
      */
     init(...metadata: never[]): BillingUnitState;
     /** Pure transition: previous state + one committed event → next state. */

package/lib/types/projection.js

@@ -1,21 +1,23 @@
 /**
- * `billingTodaySpend` session-projection unit: per-session, per-Beijing-day
- * billed spend, folded eagerly by the DSH projection drive over committed
- * session events and checkpointed by the projection cache. The unit keeps only
- * the spend of the session's LATEST priced day (events are append-only and
- * chronological, so a day strictly older than the state's day never returns);
- * the aggregate "today" read sums the units whose `dayKey` matches the current
- * Beijing day — zero full-log scans once the fold is warm.
+ * `billingTodaySpend` session-projection unit: per-session billed spend,
+ * folded eagerly by the DSH projection drive over committed session events and
+ * checkpointed by the projection cache. The state keeps the session's LATEST
+ * priced Beijing day, its whole-session total, the fork boundary, the latest
+ * request model, and the last priced attempt sample (DSH's same-step
+ * replacement rule); the aggregate "today" read sums the units whose `dayKey`
+ * matches the current Beijing day — zero full-log scans once the fold is warm.
  *
- * The unit's fold shares {@link priceEvent} with the events-scan paths
- * (`computeTodaySpend`), so both price with the same table. The unit is
+ * The unit's fold IS the shared pricing fold ({@link applyBillingEvent}), so
+ * the projection path and the events-scan paths cannot drift. The unit is
  * client-visible (`wire` = identity) because the persisted-cache read ladder
- * (`sessionProjectionCache.coldSnapshot` / registry `restore`) serves only
- * wired units; the wire value is the state itself.
+ * (`sessionProjectionCache.cachedSnapshot` / registry `restore`) serves only
+ * wired units, and because the browser half reads this value through
+ * `useProjection` instead of polling a Remote; the wire value is the state
+ * itself.
  * @module @rayadesu/dsh-llm-billing/projection
  */
 import { z } from 'zod';
-import { addEventContribution, emptyTodaySpend, priceEvent } from "./billing.js";
+import { applyBillingEvent, emptyBillingFoldState } from "./billing.js";
 /** The projection key this unit owns. */
 export const BILLING_UNIT_KEY = 'billingTodaySpend';
 const modelRowSchema = z.object({
@@ -38,15 +40,26 @@ const todaySpendSchema = z.object({
 const billingUnitSchema = z.object({
     dayKey: z.string(),
     spend: todaySpendSchema,
+    session: todaySpendSchema,
+    inheritedEventCount: z.number().int().nonnegative(),
+    model: z.string(),
+    last: z.object({
+        turn: z.number().int().nonnegative(),
+        step: z.number().int().nonnegative(),
+        dayKey: z.string(),
+        spend: todaySpendSchema,
+    }).strict().nullable(),
 }).strict();
 /**
- * Build the `billingTodaySpend` unit for one resolved pricing table. The
- * pricing closure is fixed at registration; a pricing-table change therefore
- * prices only events folded after the change (historical spend keeps its
- * historical rates), unlike the events-scan paths which re-price the whole
- * log. Bump {@link ProjectionDefinition.stateVersion} whenever the state
- * shape or fold semantics change, so persisted checkpoint rows are discarded
- * instead of folded forward.
+ * Build the `billingTodaySpend` unit for one resolved pricing table. Published
+ * rate revisions travel inside the closure and are resolved per sample
+ * timestamp, so a re-priced series bills its own history correctly however late
+ * a log is folded; only a configuration change (editing `billing.models`) is
+ * fixed at registration, and it re-prices just the events folded afterwards
+ * (the events-scan paths re-price the whole log). Bump
+ * {@link ProjectionDefinition.stateVersion} whenever the state shape or fold
+ * semantics change, so persisted checkpoint rows are discarded instead of
+ * folded forward.
  * @param billing - resolved pricing with peak-hour windows.
  * @param catalog - model display rows, in presentation order.
  * @returns the unit definition to register on `ctx.sessionProjections`.
@@ -55,26 +68,16 @@ export function billingTodaySpendDefinition(billing, catalog) {
     const names = new Map(catalog.map(model => [model.id, model.name]));
     return {
         key: BILLING_UNIT_KEY,
-        stateVersion: 1,
+        // v4: rate revisions resolved per sample timestamp (the V4 Flash series is
+        // re-priced from 2026-09-10 12:00 Beijing), on top of v3's DSH-aligned
+        // attempt pricing, v2's boundary-aware fold, and the whole-session total.
+        // A row checkpointed by the previous version priced every sample at one
+        // flat pair of rates, so rows folded after the re-pricing instant would
+        // keep the superseded rates: bumping discards them and refolds.
+        stateVersion: 4,
         stateSchema: billingUnitSchema,
-        init: () => ({ dayKey: '', spend: emptyTodaySpend() }),
-        apply: (state, event) => {
-            const priced = priceEvent(event, billing, names);
-            if (priced === undefined)
-                return state;
-            if (state.dayKey === priced.dayKey) {
-                return { dayKey: state.dayKey, spend: addEventContribution(state.spend, priced) };
-            }
-            // The session log is append-only and chronological, so an event whose
-            // Beijing day is strictly older than the state's day cannot legally
-            // follow it; ignore defensively to keep the persisted fold
-            // deterministic under reordered or clock-skewed timestamps.
-            if (state.dayKey !== '' && priced.dayKey < state.dayKey)
-                return state;
-            // First priced event, or the session's first priced event of a new day:
-            // the state resets to that day's spend.
-            return { dayKey: priced.dayKey, spend: addEventContribution(emptyTodaySpend(), priced) };
-        },
+        init: (_header, inheritedEventCount) => emptyBillingFoldState(Number(inheritedEventCount ?? 0)),
+        apply: (state, event) => applyBillingEvent(state, event, billing, names),
         wire: { viewSchema: billingUnitSchema, view: state => state },
     };
 }