@rayadesu/dsh-llm-billing 0.3.15 → 0.3.17

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

@@ -7,7 +7,7 @@
  *   `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
+ *   a full `open` + handle read. 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.
@@ -38,208 +38,30 @@
  * 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
+ * durable cut instead. The boundary is the durable session state, read from the
+ * live-session and handle surfaces — a resumed fork child keeps its original
  * boundary and an unseeded session stays at 0.
  *
  * The live `Session` log surface changed in 0.1.2-alpha.4: `Session.events`
  * was removed and replaced by `Session.snapshotEvents()` / `ownEvents()`, and
  * `SessionHeader.seedLength` moved to `Session.inheritedEventCount` (the
- * persistence `inspect` result carries it alongside `meta`). Reads go through
- * {@link liveSessionEvents} / {@link forkBoundaryOf}, which accept both
- * families structurally, so the scanner runs on the ≤ 0.1.1-rc.2 npm baseline
- * and on the newer runtime.
+ * opened `SessionHandle` carries it alongside `header`). Reads go through
+ * {@link liveSessionEvents} / {@link forkBoundaryOf}, which accept the
+ * live-session and handle shapes structurally, so the scanner runs on the
+ * older `events` runtime and on the newer `snapshotEvents` runtime.
  * @module @rayadesu/dsh-llm-billing/today-spend
  */
-import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session';
+import type { SessionId } from '@deepseek-ai/dsh-session';
 import type { SessionPersistenceRevision } from '@deepseek-ai/dsh-session-persistence';
 import type { ResolvedBilling } from './billing.ts';
 import type { BillingFoldState } from './billing.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`
- * event's text (last-wins, matching the `title` projection), or `null` before
- * the first title lands. The fold runs over the complete log, so an explicit
- * user rename is picked up as soon as its event commits.
- * @param events - one session's complete event log.
- * @returns the session's current title, or `null` when untitled.
- */
-export declare function foldSessionTitle(events: readonly SessionEvent[]): string | null;
-/**
- * Structural slice of a session's durable lineage: the header fields DSH
- * stamps on a delegation child (`origin: 'subagent'`, the delegating session's
- * id, and the depth that survives persistence). All three are read
- * structurally, so the scanner works on every runtime family — a log written
- * before the fields existed simply carries none of them and reads as a
- * top-level session.
- */
-export interface SessionLineage {
-    /** The session this one was forked from or delegated by; absent for a top-level session. */
-    readonly parentSession?: SessionId;
-    /** DSH's subagent-child classification (`childSessionMeta` stamps it). */
-    readonly origin?: 'subagent';
-    /** Delegation depth: absent (zero) at the top level, parent depth + 1 for a subagent child. */
-    readonly delegationDepth?: number;
-}
-/**
- * Whether one session's durable header marks it as a subagent child. Either
- * marker is enough: `origin` is DSH's navigation classification and
- * `delegationDepth` is its persisted recursion budget, so a header carrying
- * only the depth (or only the origin) is still a delegation child. A session
- * created without either — an ordinary session, a user fork, or a cold resume
- * — is top-level.
- * @param header - the session's lineage slice; `undefined` reads as top-level.
- * @returns true when the session was created as a subagent child.
- */
-export declare function isSubagentSession(header: SessionLineage | undefined): boolean;
-/**
- * The top-level session one session's ranking row belongs to: the session
- * itself for a top-level session, and for a subagent child the first ancestor
- * up the `parentSession` chain that is not itself a subagent child. A
- * multi-generation delegation (a subagent that spawned subagents) therefore
- * lands on the same root row as its parent, and a child whose parent header is
- * unknown is attributed to the parent id its own header names — the parent is
- * authoritative even when its log is not part of this scan.
- * @param id - the session whose row is being attributed.
- * @param lineage - lineage of every session this scan saw, by id.
- * @returns the session id whose ranking row the input belongs to.
- */
-export declare function topLevelSessionOf(id: SessionId, lineage: ReadonlyMap<SessionId, SessionLineage>): SessionId;
-/**
- * Fold every subagent child's row into the top-level row it belongs to
- * ({@link topLevelSessionOf}), so the ranking lists conversations rather than
- * every delegation a conversation started. A child's spend is added to its
- * ancestor's `total`; the ancestor's `ownTotal` keeps its own spend only. A
- * top-level session whose own day was empty but whose subagents priced
- * something still gets a row (with `ownTotal` 0), carrying the title the scan
- * resolved for it in `titles`.
- * @param rows - one row per session that priced something today (own spends).
- * @param lineage - lineage of every session this scan saw, by id.
- * @param titles - resolved display titles by session id; a session absent from
- *   the map has no resolved title and its created row reports `null`.
- * @returns the merged rows, sorted by `total` descending.
- */
-export declare function rollUpSubagentSpend(rows: readonly DeepSeekTodaySessionSpend[], lineage: ReadonlyMap<SessionId, SessionLineage>, titles?: ReadonlyMap<SessionId, string | null>): DeepSeekTodaySessionSpend[];
-/**
- * Structural slice of a live session's header: the fork boundary of both DSH
- * runtime families plus the delegation lineage the ranking roll-up reads.
- */
-export interface SessionHeaderSlice extends SessionLineage {
-    /** ≤ 0.1.1-rc.2: the durable fork boundary carried by the header; absent for an unseeded session. */
-    readonly seedLength?: number;
-    /** 0.1.2-alpha.4+: whether the session has a fork-inherited prefix. */
-    readonly isSeeded?: boolean;
-    /**
-     * Durable creation instant (epoch ms). The conversation read uses it to tell
-     * whether a session's spend can span more than the queried day; it is also
-     * part of the projection-cache record identity.
-     */
-    readonly createdAt?: number;
-}
-/**
- * Structural slice of a live session the scanner reads, accepting both DSH
- * runtime families: the ≤ 0.1.1-rc.2 baseline exposes the log as
- * `events` (+ `header.seedLength`), while 0.1.2-alpha.4+ exposes
- * `snapshotEvents()` and `inheritedEventCount` (and dropped the header field).
- */
-export interface ScannerSession {
-    readonly id: SessionId;
-    /** ≤ 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. */
-    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), plus lineage. */
-    readonly header?: SessionHeaderSlice;
-}
-/**
- * Read one live session's complete event log across both runtime families.
- * @throws when the session exposes neither the legacy `events` snapshot nor
- *   the newer `snapshotEvents()` reader — an unknown runtime surface must
- *   fail loudly rather than silently price an empty log.
- */
-export declare function liveSessionEvents(session: ScannerSession): readonly SessionEvent[];
-/** Structural slice of a listed persisted session (the snapshot header is a full SessionHeader). */
-export interface ScannerPersistedHeader extends SessionHeaderSlice {
-    readonly id: SessionId;
-    /** Session format generation; part of the projection-cache record identity. */
-    readonly version?: 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 {
-    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?: SessionHeaderSlice;
-        /** 0.1.2-alpha.4+: the exact inherited cut travels beside, not inside, the header. */
-        inheritedEventCount?: number;
-        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 {
-        header: ScannerPersistedHeader;
-        revision: SessionPersistenceRevision;
-    }[]>;
-    open(id: SessionId, access: 'read'): Promise<{
-        readonly header?: SessionHeaderSlice;
-        /** 0.1.2-alpha.5+: the handle carries the exact inherited cut beside the header. */
-        readonly inheritedEventCount?: number;
-        read(): Promise<ScannerHandleRead>;
-        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. */
+import { type SessionLineage } from './session-lineage.ts';
+import type { ScannerPersistedHeader, ScannerPersistence, ScannerSession } from './persistence.ts';
+export * from './session-lineage.ts';
+export * from './persistence.ts';
+export * from './cache.ts';
 export interface TodaySpendScannerDeps {
     /** Resolves the live SessionStore at scan time (absent in headless assemblies). */
     sessions?: () => {
@@ -285,42 +107,6 @@ export interface TodaySpendScannerDeps {
         name: string;
     }[];
 }
-/**
- * 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.
- * @typeParam T - the cached aggregate's value shape (the spend or its
- *   per-session breakdown).
- */
-export declare class TodaySpendCache<T = DeepSeekTodaySpend> {
-    private readonly scan;
-    private readonly ttlMs;
-    private readonly now;
-    private cachedDayKey;
-    private cachedValue;
-    private cachedAt;
-    private inFlight;
-    /**
-     * @param scan - the aggregate computation behind a miss.
-     * @param ttlMs - time window in milliseconds (default 60 000).
-     * @param now - clock source (injectable for tests).
-     */
-    constructor(scan: (dayKey: string) => Promise<T>, ttlMs?: number, now?: () => Date);
-    /**
-     * 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?: 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
@@ -402,7 +188,12 @@ export declare class TodaySpendScanner {
      * from the aggregate and the ranking on every scan after the first.
      */
     private readonly coldResolved;
-    /** Cold sessions whose resolution failed: id → revision (retried only when the log changes). */
+    /**
+     * Cold sessions whose resolution failed, id → the revision it failed at plus
+     * when. Keyed by revision too, so an unchanged log is not re-read every scan,
+     * but the retry is TIME-boxed: a purely revision-keyed failure would hide a
+     * session permanently when its log never changes again.
+     */
     private readonly coldFailed;
     constructor(deps: TodaySpendScannerDeps);
     /**
@@ -436,7 +227,10 @@ export declare class TodaySpendScanner {
      * otherwise.
      *
      * The aggregate sums every priced session, subagents included — the ranking's
-     * subagent roll-up only regroups rows, so neither total moves.
+     * subagent roll-up only regroups rows, so neither total moves. Both paths
+     * fold in slices and hand the host's event loop back every
+     * {@link SCAN_YIELD_SESSIONS} sessions, so a long scan never starves the
+     * GUI's own round trips.
      * @param dayKey - the Beijing-time calendar-day key to aggregate.
      * @returns the aggregate plus per-session rows sorted by cost descending.
      */
@@ -448,14 +242,14 @@ export declare class TodaySpendScanner {
      * 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
+     * opened 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`,
+     * prefix too, so it always detaches through a handle read with the durable
+     * boundary (the handle's `inheritedEventCount` or `header.seedLength`,
      * depending on the runtime family) applied to the local fold.
      * @param header - the listed session header (the cache identity witness).
      * @param seeded - whether the session carries a fork-inherited prefix.
@@ -504,7 +298,7 @@ export declare class TodaySpendScanner {
     /**
      * 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`
+     * revision-gated cold ladder for the rest (title resolved on the handle read, `null`
      * when answered from the projection cache). A fork child's cell covers its
      * inherited prefix, so its own-events fold supplies both outputs. Lineage
      * (which session delegated which) comes from the same headers the boundary