@rayadesu/dsh-llm-billing 0.3.7 → 0.3.9

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

@@ -4,11 +4,13 @@
  * 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.
+ *   `billingTodaySpend` projection cell; cold sessions are answered from the
+ *   zero-I/O projection-cache row whenever that row's own day is not the
+ *   queried one, and otherwise resolved through 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 — and a
+ *   failed resolution is remembered by revision instead of being retried on
+ *   every scan.
  * - events path (plans A2/A3): collect and price only today's events in one
  *   pass (per-event Beijing-day filter during collection) with a hard cap,
  *   skipping sessions whose persisted revision is unchanged since the last
@@ -20,14 +22,15 @@
  * 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 (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.
+ * 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
+ * `billingTodaySpend` unit is boundary-aware (its state carries the inherited
+ * cut, and `apply` skips events below it), so the eager cell is correct for a
+ * fork child; the cold path skips the projection cache for a seeded session
+ * (its cached row may predate the boundary) and folds its own events with the
+ * durable cut instead. 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
@@ -41,7 +44,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 type { DeepSeekTodaySessionSpend, DeepSeekTodaySessionsSpend, DeepSeekTodaySpend } from './types.ts';
 import { BILLING_UNIT_KEY, type BillingUnitFold, type BillingUnitState } from './projection.ts';
 /**
  * Fold one session's durable display title: the latest `session/title`
@@ -86,6 +89,12 @@ export interface ScannerPersistedHeader {
     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;
+    /** Session format generation; part of the projection-cache record identity. */
+    readonly version?: number;
+    /** Session creation time; part of the projection-cache record identity. */
+    readonly createdAt?: number;
+    /** Working directory recorded on the header; part of the projection-cache record identity. */
+    readonly cwd?: string;
 }
 /** One stored-session read: the full event log plus the durable inherited boundary. */
 export interface ScannerPersistedRead {
@@ -109,6 +118,21 @@ export interface ScannerPersistenceLegacy {
         events: readonly SessionEvent[];
     }>;
 }
+/**
+ * One handle read result across DSH generations. The handle seam first
+ * returned the bare event array; since `9b78f99dec` (2026-09-06, in the
+ * 0.1.5-alpha.1 checkout) it returns `{ eventState, events }`. Both shapes are
+ * accepted so the same build serves the npm alpha line and the checkout.
+ */
+export type ScannerHandleRead = readonly SessionEvent[] | {
+    readonly events: readonly SessionEvent[];
+};
+/**
+ * Unwrap a handle read across both return shapes.
+ * @param read - the handle's read result.
+ * @returns the event array.
+ */
+export declare function handleReadEvents(read: ScannerHandleRead): readonly SessionEvent[];
 /** 0.1.2-alpha.5+ handle-based persistence slice: service-level `list` / `open` + `SessionHandle`. */
 export interface ScannerPersistenceHandle {
     list(): Promise<readonly {
@@ -122,7 +146,7 @@ export interface ScannerPersistenceHandle {
         };
         /** 0.1.2-alpha.5+: the handle carries the exact inherited cut beside the header. */
         readonly inheritedEventCount?: number;
-        read(): Promise<readonly SessionEvent[]>;
+        read(): Promise<ScannerHandleRead>;
         close(): Promise<void>;
     }>;
 }
@@ -160,11 +184,16 @@ export interface TodaySpendScannerDeps {
     projections?: () => {
         stateOf(session: ScannerSession, key: typeof BILLING_UNIT_KEY): BillingUnitState | undefined;
     } | undefined;
-    /** Resolves the projection cache at scan time (absent → detached fold for cold sessions). */
+    /**
+     * Resolves the projection cache at scan time (absent → detached fold for
+     * cold sessions). Only the zero-I/O `cachedSnapshot` reader is used: it
+     * serves already-checkpointed wire rows without touching a session log.
+     */
     projectionCache?: () => {
-        coldSnapshot(id: SessionId): Promise<{
-            values: Partial<Record<typeof BILLING_UNIT_KEY, BillingUnitState>>;
-        }>;
+        cachedSnapshot(header: ScannerPersistedHeader, inheritedEventCount: number, keys?: readonly string[]): {
+            readonly asOfSeq: number;
+            readonly values: Partial<Record<typeof BILLING_UNIT_KEY, BillingUnitState>>;
+        } | undefined;
     } | undefined;
     /**
      * Registers the billing unit on the projection registry, called once before
@@ -219,6 +248,23 @@ export declare class TodaySpendCache<T = DeepSeekTodaySpend> {
      */
     get(force?: boolean): Promise<T>;
 }
+/** Max session-ids kept in the scanner's cold-resolution cache before eviction. */
+export declare const COLD_RESOLVE_CACHE_LIMIT = 1024;
+/** Max session-ids kept in the scanner's cold-failure cache before eviction. */
+export declare const COLD_FAILED_CACHE_LIMIT = 1024;
+/** Bounded parallel fan-out for cold-session resolution. */
+export declare const COLD_RESOLVE_CONCURRENCY = 8;
+/**
+ * One day's aggregate plus its per-session ranking, computed in a single pass:
+ * the aggregate is the sum of the rows, so both reads share every session
+ * read, unit fold, and title fold.
+ */
+export interface TodaySpendDetail {
+    /** Today's spend across every session. */
+    aggregate: DeepSeekTodaySpend;
+    /** Today's per-session rows, sorted by cost descending. */
+    sessions: DeepSeekTodaySessionSpend[];
+}
 /**
  * The aggregate computation behind a cache miss. Chooses the projection path
  * when the projection registry is composed, the events path otherwise; both
@@ -229,10 +275,10 @@ export declare class TodaySpendScanner {
     private readonly deps;
     /** Cold sessions resolved on the projection path: id → revision + unit state + title. */
     private readonly coldResolved;
+    /** Cold sessions whose resolution failed: id → revision (retried only when the log changes). */
+    private readonly coldFailed;
     /** Cold sessions resolved on the events path: id → revision (events were collected). */
     private lastEventsScan;
-    /** Live fork children priced on the projection path: id → own-events count + folded state. */
-    private readonly ownStates;
     constructor(deps: TodaySpendScannerDeps);
     /**
      * Compute today's aggregate for one Beijing day.
@@ -249,62 +295,92 @@ export declare class TodaySpendScanner {
      */
     scanSessions(dayKey: string): Promise<DeepSeekTodaySessionsSpend>;
     /**
-     * Resolve one cold session's billing unit state and display title through
-     * the projection-cache ladder (cached row first, then a detached local
-     * fold over a full inspect). A cache-served value carries no title (the
-     * ladder only stores projection values), so such rows report `title: null`
-     * until the session is inspected again. A SEEDED session (fork child)
-     * skips the ladder entirely: its cached row was folded over the inherited
+     * Compute the day's aggregate AND its per-session ranking in ONE pass: the
+     * aggregate is the sum of the rows, so the two reads share every session
+     * read, unit fold, and title fold instead of scanning twice. Chooses the
+     * projection path when the projection registry is composed, the events path
+     * otherwise.
+     * @param dayKey - the Beijing-time calendar-day key to aggregate.
+     * @returns the aggregate plus per-session rows sorted by cost descending.
+     */
+    scanDetail(dayKey: string): Promise<TodaySpendDetail>;
+    /**
+     * Resolve one cold session's billing unit state and display title.
+     *
+     * The zero-I/O projection-cache row answers the query directly whenever its
+     * own latest priced day is NOT the queried day: the row then proves the
+     * session contributed nothing to the queried day, so the log is never read.
+     * When the row IS the queried day (or no usable row exists) the session is
+     * inspected and folded locally, because the row may trail the log (a crash
+     * between the last checkpoint and the session's last event).
+     *
+     * A cache-served value carries no title (the ladder only stores projection
+     * values), so such rows report `title: null`. A SEEDED session (fork child)
+     * skips the cache entirely: its cached row was folded over the inherited
      * prefix too, so it always detaches through inspect with the durable
      * 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 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).
+     * @param header - the listed session header (the cache identity witness).
+     * @param seeded - whether the session carries a fork-inherited prefix.
+     * @param dayKey - the Beijing-time day being aggregated.
      * @returns the resolved state and title, or `undefined` when unreadable.
      */
     private resolveCold;
     /**
-     * Fold one fork child's OWN events (its log minus the inherited prefix)
-     * with the billing unit, incrementally: the fold is reused while the log
-     * length is unchanged and only the new tail is applied when it grows.
-     * @param id - the session id (the own-state cache key).
-     * @param events - the session's complete log.
-     * @param seedLength - the inherited-prefix boundary.
-     * @returns the unit state over the session's own events.
+     * Live-session entries of one projection-path scan: each session with its
+     * eager `billingTodaySpend` cell. The cell is boundary-aware (the unit skips
+     * a fork child's inherited prefix), so a fork child reads the same own-event
+     * spend a non-fork session does.
+     */
+    private liveBillingEntries;
+    /**
+     * Cold-ladder adopt: for every stored session not live, either the
+     * revision-gated resolution already in {@link coldResolved} is adopted
+     * (unchanged log costs nothing) or the session is queued behind a bounded
+     * parallel fan-out, resolved, remembered, and then adopted. A session whose
+     * resolution failed is remembered too (by revision), so an unreadable log
+     * is not re-read on every scan; a changed revision retries it. One
+     * unreadable session never blanks the whole-day aggregate.
+     * @param liveIds - ids of sessions already folded from the live store.
+     * @param snapshots - stored snapshot list (either runtime family).
+     * @param dayKey - the Beijing-time day being aggregated.
+     * @param adopt - fold one resolved cold session into the scan's result.
      */
-    private ownBillingState;
-    /** Projection path: eager cells for live sessions, revision-gated cold ladder for the rest. */
-    private scanProjections;
+    private coldAdopt;
     /**
-     * Events path: price today's events in a single pass (per-event Beijing-day
-     * filter during collection, hard cap), gated by revisions. A fork child's
-     * inherited prefix (`seq < seedLength`) is skipped, so each model output is
-     * priced only in its source session.
+     * Events-path collection shared by both aggregate and per-session scans:
+     * fold each session's log with the shared pricing fold (attempt samples with
+     * same-step replacement) and announce the session's latest-day spend, gated
+     * by revisions — a persisted session whose log did not change since the last
+     * scan is skipped. A fork child's inherited prefix (`seq < seedLength`) is
+     * skipped, so each model output is priced only in its source session. The
+     * hard cap counts the queried day's events; the revision watermark only
+     * advances on a complete pass.
+     * @param dayKey - the Beijing-time calendar-day key to aggregate.
+     * @param onSession - fold one session's state plus its complete log.
+     * @returns whether the hard cap truncated the scan.
      */
-    private scanEvents;
+    private collectTodayEvents;
     /**
-     * Projection-path per-session scan: eager cells for live sessions (title
-     * folded from the live log, so a rename is reflected immediately),
-     * revision-gated cold ladder for the rest (title resolved on inspect,
-     * `null` when served from the projection cache). A fork child's row prices
-     * its OWN events only (the cell covers the inherited prefix too).
+     * Projection path, one pass for both outputs: eager cells for live sessions
+     * (title folded from the live log, so a rename is reflected immediately),
+     * revision-gated cold ladder for the rest (title resolved on inspect, `null`
+     * when answered from the projection cache). A fork child's cell covers its
+     * inherited prefix, so its own-events fold supplies both outputs.
      * @param dayKey - the Beijing-time calendar-day key to aggregate.
-     * @returns unsorted per-session rows for the day.
+     * @returns the aggregate plus per-session rows, sorted by cost descending.
      */
-    private scanSessionsProjections;
+    private scanDetailProjections;
     /**
-     * Events-path per-session scan: price today's events in a single pass,
-     * accumulating per session (per-event Beijing-day filter during collection,
-     * hard cap), gated by revisions. A fork child's inherited prefix
-     * (`seq < seedLength`) is skipped, so each row is the session's OWN spend.
-     * Titles fold from each session's complete log — a `session/title` event
-     * can predate today — so a rename is reflected as soon as the session's log
-     * is re-read.
+     * Events path, one pass for both outputs: price today's events (per-event
+     * Beijing-day filter during collection, hard cap), gated by revisions. A
+     * fork child's inherited prefix (`seq < seedLength`) is skipped, so each
+     * model output is priced only in its source session. Titles fold from each
+     * session's complete log — a `session/title` event can predate today — so a
+     * rename is reflected as soon as the session's log is re-read.
      * @param dayKey - the Beijing-time calendar-day key to aggregate.
-     * @returns unsorted per-session rows for the day.
+     * @returns the aggregate plus per-session rows, sorted by cost descending.
      */
-    private scanSessionsEvents;
+    private scanDetailEvents;
 }
 //# sourceMappingURL=today-spend.d.ts.map