@rayadesu/dsh-llm-billing 0.1.0 → 0.2.0

package/lib/types/today-spend.js

@@ -0,0 +1,246 @@
+/**
+ * Today-spend read path: the 60-second Beijing-day cache with in-flight
+ * coalescing and a force bypass (plan A1), plus the two scan strategies that
+ * compute the aggregate behind a cache miss:
+ *
+ * - projection path (plan C): live sessions read their eagerly folded
+ *   `billingTodaySpend` projection cell; cold sessions resolve through the
+ *   projection-cache ladder (cached row + tail replay + registry restore,
+ *   with write-back) or, without the cache service, one detached local fold
+ *   over a full `inspect`. Persisted revisions gate every cold read, so a
+ *   session whose log did not change since the last resolution costs nothing.
+ * - events path (plans A2/A3): collect only today's events (per-event
+ *   Beijing-day filter during collection) with a hard cap, skipping sessions
+ *   whose persisted revision is unchanged since the last scan.
+ *
+ * Both strategies run behind the same {@link TodaySpendCache}, so a miss
+ * happens at most once per 60 seconds per process, and a manual refresh
+ * (`force`) bypasses the time window but keeps the revision caches — an
+ * unchanged log provably cannot change the aggregate.
+ * @module @rayadesu/dsh-llm-billing/today-spend
+ */
+import { beijingDayKey, computeTodaySpend, emptyTodaySpend, mergeTodaySpend } from "./billing.js";
+import { BILLING_UNIT_KEY, foldBillingUnit } from "./projection.js";
+/** Bounded parallel fan-out: run `run` over `items` with at most `limit` in flight. */
+async function withConcurrency(items, limit, run) {
+    const queue = [...items];
+    await Promise.all(Array.from({ length: Math.min(limit, queue.length) }, async () => {
+        for (let job = queue.shift(); job !== undefined; job = queue.shift())
+            await run(job);
+    }));
+}
+/**
+ * The A1 cache: one Beijing-day key + a 60s window, an in-flight promise that
+ * coalesces concurrent misses, and a `force` bypass for the manual refresh
+ * path. Cross-day invalidation is automatic (the day key changes); a failed
+ * scan leaves the previous value in place and retries on the next call.
+ */
+export class TodaySpendCache {
+    scan;
+    ttlMs;
+    now;
+    cachedDayKey;
+    cachedValue;
+    cachedAt = 0;
+    inFlight;
+    /**
+     * @param ttlMs - time window in milliseconds (default 60 000).
+     * @param now - clock source (injectable for tests).
+     * @param scan - the aggregate computation behind a miss.
+     */
+    constructor(scan, ttlMs = 60_000, now = () => new Date()) {
+        this.scan = scan;
+        this.ttlMs = ttlMs;
+        this.now = now;
+    }
+    /**
+     * Read today's spend, cached per Beijing day within the TTL window.
+     * @param force - bypass the time window (manual refresh); the day-key gate
+     *   and the in-flight coalescing still apply to non-force callers.
+     * @returns today's spend.
+     */
+    get(force = false) {
+        const now = this.now();
+        const dayKey = beijingDayKey(now);
+        if (!force && this.cachedDayKey === dayKey && this.cachedValue !== undefined
+            && now.getTime() - this.cachedAt < this.ttlMs) {
+            return Promise.resolve(this.cachedValue);
+        }
+        if (!force && this.inFlight !== undefined)
+            return this.inFlight;
+        const run = (async () => {
+            try {
+                const value = await this.scan(dayKey);
+                this.cachedDayKey = dayKey;
+                this.cachedValue = value;
+                this.cachedAt = now.getTime();
+                return value;
+            }
+            finally {
+                this.inFlight = undefined;
+            }
+        })();
+        if (!force)
+            this.inFlight = run;
+        return run;
+    }
+}
+/**
+ * The aggregate computation behind a cache miss. Chooses the projection path
+ * when the projection registry is composed, the events path otherwise; both
+ * gate cold reads on persisted revisions so steady-state scans touch only
+ * sessions whose logs actually changed.
+ */
+export class TodaySpendScanner {
+    deps;
+    /** Cold sessions resolved on the projection path: id → revision + unit state. */
+    coldResolved = new Map();
+    /** Cold sessions resolved on the events path: id → revision (events were collected). */
+    lastEventsScan;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * Compute today's aggregate for one Beijing day.
+     * @param dayKey - the Beijing-time calendar-day key to aggregate.
+     * @returns today's spend across every session.
+     */
+    async scan(dayKey) {
+        if (this.deps.projections?.() === undefined)
+            return this.scanEvents(dayKey);
+        this.deps.ensureUnit?.();
+        return this.scanProjections(dayKey);
+    }
+    /** Projection path: eager cells for live sessions, revision-gated cold ladder for the rest. */
+    async scanProjections(dayKey) {
+        const { sessions, persistence, projections, projectionCache, unit, logger } = this.deps;
+        let total = emptyTodaySpend();
+        const liveIds = new Set();
+        if (sessions !== undefined) {
+            const store = sessions();
+            if (store !== undefined) {
+                for (const session of store.list()) {
+                    liveIds.add(session.id);
+                    const state = projections?.()?.stateOf(session, BILLING_UNIT_KEY);
+                    if (state !== undefined && state.dayKey === dayKey) {
+                        total = mergeTodaySpend(total, state.spend);
+                    }
+                }
+            }
+        }
+        const persistenceService = persistence?.();
+        if (persistenceService === undefined)
+            return total;
+        const snapshots = await persistenceService.listSnapshots();
+        const pending = [];
+        for (const { header, revision } of snapshots) {
+            if (liveIds.has(header.id))
+                continue;
+            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 });
+        }
+        await withConcurrency(pending, 8, async ({ id, revision }) => {
+            let value;
+            const cache = projectionCache?.();
+            if (cache !== undefined) {
+                try {
+                    value = (await cache.coldSnapshot(id)).values[BILLING_UNIT_KEY];
+                }
+                catch (error) {
+                    logger.warn(`llm-billing: projection cold read for session ${id} failed: ${String(error)}`);
+                }
+            }
+            if (value === undefined) {
+                try {
+                    const inspection = await persistenceService.inspect(id);
+                    value = foldBillingUnit(unit, inspection.events);
+                }
+                catch (error) {
+                    // One unreadable session must not blank the whole-day aggregate.
+                    logger.warn(`llm-billing: skipping unreadable session ${id}: ${String(error)}`);
+                }
+            }
+            if (value !== undefined)
+                this.coldResolved.set(id, { revision, value });
+        });
+        for (const { id } of pending) {
+            const resolved = this.coldResolved.get(id);
+            if (resolved !== undefined && resolved.value.dayKey === dayKey) {
+                total = mergeTodaySpend(total, resolved.value.spend);
+            }
+        }
+        return total;
+    }
+    /** Events path: collect only today's events (capped), gated by revisions. */
+    async scanEvents(dayKey) {
+        const { sessions, persistence, maxEvents, logger, billing, catalog } = this.deps;
+        const events = [];
+        const liveIds = new Set();
+        let truncated = false;
+        if (sessions !== undefined) {
+            const store = sessions();
+            if (store !== undefined) {
+                for (const session of store.list()) {
+                    liveIds.add(session.id);
+                    for (const event of session.events) {
+                        if (beijingDayKey(new Date(event.time)) !== dayKey)
+                            continue;
+                        events.push(event);
+                        if (events.length >= maxEvents) {
+                            truncated = true;
+                            break;
+                        }
+                    }
+                    if (truncated)
+                        break;
+                }
+            }
+        }
+        const persistenceService = persistence?.();
+        if (!truncated && persistenceService !== undefined) {
+            const snapshots = await persistenceService.listSnapshots();
+            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);
+                    for (const event of inspection.events) {
+                        if (beijingDayKey(new Date(event.time)) !== dayKey)
+                            continue;
+                        events.push(event);
+                        if (events.length >= maxEvents) {
+                            truncated = true;
+                            break;
+                        }
+                    }
+                }
+                catch (error) {
+                    // One unreadable session must not blank the whole-day aggregate.
+                    logger.warn(`llm-billing: skipping unreadable session ${header.id}: ${String(error)}`);
+                }
+                if (truncated)
+                    break;
+            }
+            // Only a complete pass may advance the revision watermark: a truncated
+            // pass left sessions unread, and recording them would skip their events
+            // on the next scan.
+            if (!truncated) {
+                this.lastEventsScan = new Map(snapshots.map(snapshot => [snapshot.header.id, snapshot.revision]));
+            }
+        }
+        if (truncated)
+            logger.warn(`llm-billing: today's events exceeded ${maxEvents}; result truncated`);
+        // The reference moment is derived from the day key (UTC midnight on that
+        // date is 08:00 Beijing the same day), so the pricing re-check cannot
+        // drift from the collection filter across a Beijing-day boundary.
+        return computeTodaySpend(events, billing, catalog, new Date(`${dayKey}T00:00:00Z`));
+    }
+}
+//# sourceMappingURL=today-spend.js.map

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.1.0",
+  "version": "0.2.0",
   "publishConfig": {
     "access": "public"
   },
@@ -55,6 +55,7 @@
     "@deepseek-ai/dsh-llm": "^0.1.0-rc.8",
     "@deepseek-ai/dsh-session": "^0.1.0-rc.8",
     "@deepseek-ai/dsh-session-persistence": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-session-projection": "^0.1.0-rc.8",
     "@deepseek-ai/dsh-typert-protocol": "^0.1.0-rc.8",
     "@deepseek-ai/cordis": "^4.0.1"
   },
@@ -69,6 +70,7 @@
     "@deepseek-ai/dsh-llm": "^0.1.0-rc.8",
     "@deepseek-ai/dsh-session": "^0.1.0-rc.8",
     "@deepseek-ai/dsh-session-persistence": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-session-projection": "^0.1.0-rc.8",
     "@deepseek-ai/dsh-typert-protocol": "^0.1.0-rc.8",
     "@deepseek-ai/cordis": "^4.0.1"
   }