@ericsanchezok/synergy-workbench 0.0.0-stage → 3.1.1

package/src/stats/canonical.ts

@@ -0,0 +1,93 @@
+import { Usage } from "@ericsanchezok/synergy-harness/usage"
+import { RolloutAccounting } from "@ericsanchezok/synergy-harness/session/rollout/accounting"
+import type { StatsSnapshot, DailyBucket } from "./types"
+import { ExecutionPresentation } from "../execution/presentation"
+
+export namespace CanonicalStats {
+  function projection(accounting: RolloutAccounting.Summary) {
+    return {
+      ...RolloutAccounting.project(accounting),
+      cost: RolloutAccounting.knownExpense(accounting),
+      costPresentation: ExecutionPresentation.cost(accounting),
+      accounting,
+    }
+  }
+  export async function apply(snapshot: StatsSnapshot): Promise<StatsSnapshot> {
+    const usage = await Usage.summary()
+    const days = new Map<string, DailyBucket>(
+      snapshot.timeSeries.days.map((day) => [
+        day.day,
+        {
+          ...day,
+          ...projection(RolloutAccounting.empty()),
+          toolCalls: 0,
+        },
+      ]),
+    )
+    for (const day of usage.daily)
+      days.set(day.date, {
+        day: day.date,
+        sessions: 0,
+        turns: 0,
+        additions: 0,
+        deletions: 0,
+        files: 0,
+        errors: 0,
+        ...days.get(day.date),
+        ...projection(day.accounting),
+        toolCalls: day.toolCalls,
+      })
+    const total = projection(usage.accounting)
+    const turns = snapshot.overview.totalTurns
+    const activeDays = usage.daily.filter((day) => day.accounting.calls || day.accounting.legacy.messages).length || 1
+    return {
+      ...snapshot,
+      tokenCost: {
+        ...total,
+        cacheHitRate: usage.cache.ratio ?? usage.cache.observedRatio ?? 0,
+        avgCostPerTurn: turns ? total.cost / turns : 0,
+        avgTokensPerTurn: turns ? usage.accounting.tokens.total.known / turns : 0,
+        dailyCost: total.cost / activeDays,
+        dailyTokens: usage.accounting.tokens.total.known / activeDays,
+      },
+      models: {
+        models: usage.models.map((model) => {
+          const previous = snapshot.models.models.find(
+            (value) => value.providerID === model.providerID && value.modelID === model.modelID,
+          )
+          return {
+            providerID: model.providerID,
+            modelID: model.modelID,
+            messages: previous?.messages ?? 0,
+            turns: previous?.turns ?? 0,
+            avgResponseMs: previous?.avgResponseMs ?? 0,
+            ...projection(model.accounting),
+          }
+        }),
+      },
+      agents: {
+        ...snapshot.agents,
+        agents: Object.entries(usage.agents).map(([agent, accounting]) => {
+          const previous = snapshot.agents.agents.find((value) => value.agent === agent)
+          return {
+            agent,
+            messages: previous?.messages ?? 0,
+            sessions: previous?.sessions ?? 0,
+            subagentInvocations: previous?.subagentInvocations ?? 0,
+            ...projection(accounting),
+          }
+        }),
+      },
+      tools: {
+        tools: usage.tools.map((tool) => ({
+          tool: tool.tool,
+          calls: tool.calls,
+          successes: tool.completed,
+          errors: tool.failed,
+          avgDurationMs: tool.averageMs ?? 0,
+        })),
+      },
+      timeSeries: { ...snapshot.timeSeries, days: [...days.values()].sort((a, b) => a.day.localeCompare(b.day)) },
+    }
+  }
+}

package/src/stats/cli/stats.ts

@@ -0,0 +1,348 @@
+import type { Argv } from "yargs"
+import { cmd } from "@ericsanchezok/synergy-util/cli-command"
+import { UI } from "@ericsanchezok/synergy-util/terminal"
+import { Engine } from ".."
+import type { StatsSnapshot, ProgressCallback } from ".."
+import { RolloutQuery } from "@ericsanchezok/synergy-harness/session/rollout/query"
+
+export const StatsCommand = cmd({
+  command: "stats",
+  describe: "show token usage and cost statistics",
+  builder: (yargs: Argv) => {
+    return yargs
+      .option("run", { type: "string", describe: "Show one run and its descendant accounting" })
+      .option("compare", {
+        type: "string",
+        array: true,
+        nargs: 2,
+        describe: "Compare two runs without inferring task quality",
+      })
+      .option("days", {
+        describe: "show stats for the last N days (default: all time)",
+        type: "number",
+      })
+      .option("tools", {
+        describe: "number of tools to show (default: all)",
+        type: "number",
+      })
+      .option("models", {
+        describe: "show model statistics (default: hidden). Pass a number to show top N, otherwise shows all",
+      })
+      .option("project", {
+        describe: "filter by project (default: all projects, empty string: current project)",
+        type: "string",
+      })
+      .option("recompute", {
+        describe: "force full recompute from scratch",
+        type: "boolean",
+        default: false,
+      })
+      .option("json", {
+        describe: "output raw JSON instead of formatted display",
+        type: "boolean",
+        default: false,
+      })
+  },
+  handler: async (args) => {
+    if (args.run || args.compare) {
+      if (args.run && args.compare) throw new Error("Use either --run or --compare")
+      const result = args.run
+        ? await RolloutQuery.find(args.run)
+        : await Promise.all(args.compare!.map((id) => RolloutQuery.find(id)))
+      console.log(JSON.stringify(Array.isArray(result) ? RolloutQuery.compare(result[0], result[1]) : result, null, 2))
+      return
+    }
+    const onProgress: ProgressCallback = (event) => {
+      if (args.json) return
+      const pct = event.total > 0 ? Math.round((event.current / event.total) * 100) : 0
+      const bar = UI.progressBar({ ratio: event.current / Math.max(1, event.total), width: 30, brackets: true })
+      const msg = event.message ?? event.phase
+      process.stdout.write(`\r  ${bar} ${pct}% ${msg}`)
+      if (event.current === event.total && event.phase === "snapshot") {
+        process.stdout.write("\r\x1B[K")
+      }
+    }
+
+    let snapshot: StatsSnapshot
+
+    if (args.project !== undefined) {
+      console.log("Note: project-scoped filtering requires full recomputation.")
+      snapshot = await Engine.recompute(onProgress)
+    } else if (args.recompute) {
+      snapshot = await Engine.recompute(onProgress)
+    } else {
+      snapshot = await Engine.update(onProgress)
+    }
+
+    // Apply --days filter client-side on time series
+    if (args.days !== undefined) {
+      snapshot = filterByDays(snapshot, args.days)
+    }
+
+    if (args.json) {
+      console.log(JSON.stringify(snapshot, null, 2))
+      return
+    }
+
+    let modelLimit: number | undefined
+    if (args.models === true) {
+      modelLimit = Infinity
+    } else if (typeof args.models === "number") {
+      modelLimit = args.models
+    }
+
+    displayStats(snapshot, args.tools, modelLimit)
+  },
+})
+
+function filterByDays(snapshot: StatsSnapshot, days: number): StatsSnapshot {
+  const MS_IN_DAY = 24 * 60 * 60 * 1000
+  const cutoff =
+    days === 0
+      ? (() => {
+          const d = new Date()
+          d.setHours(0, 0, 0, 0)
+          return d.getTime()
+        })()
+      : Date.now() - days * MS_IN_DAY
+
+  const filteredDays = snapshot.timeSeries.days.filter((d) => new Date(d.day).getTime() >= cutoff)
+
+  return {
+    ...snapshot,
+    timeSeries: {
+      ...snapshot.timeSeries,
+      days: filteredDays,
+    },
+  }
+}
+
+export function displayStats(snapshot: StatsSnapshot, toolLimit?: number, modelLimit?: number) {
+  const width = 72
+
+  function renderRow(label: string, value: string): string {
+    const availableWidth = width - 1
+    const paddingNeeded = availableWidth - label.length - value.length
+    const padding = Math.max(0, paddingNeeded)
+    return `│${label}${" ".repeat(padding)}${value} │`
+  }
+
+  function renderHeader(title: string): void {
+    const innerWidth = width - 2
+    const padTotal = innerWidth - title.length
+    const padLeft = Math.floor(padTotal / 2)
+    const padRight = padTotal - padLeft
+    console.log(`│${" ".repeat(padLeft)}${title}${" ".repeat(padRight)}│`)
+  }
+
+  function topBorder(): void {
+    console.log(`┌${"─".repeat(width - 2)}┐`)
+  }
+
+  function divider(): void {
+    console.log(`├${"─".repeat(width - 2)}┤`)
+  }
+
+  function bottomBorder(): void {
+    console.log(`└${"─".repeat(width - 2)}┘`)
+  }
+
+  const { overview, tokenCost, models, agents, tools, codeChanges, lifecycle, channels } = snapshot
+
+  // ── Overview ──────────────────────────────────────────────
+  topBorder()
+  renderHeader("OVERVIEW")
+  divider()
+  console.log(
+    renderRow(
+      "Sessions",
+      `${overview.totalSessions.toLocaleString()} (active: ${overview.activeSessions}, archived: ${overview.archivedSessions})`,
+    ),
+  )
+  console.log(renderRow("Messages", overview.totalMessages.toLocaleString()))
+  console.log(renderRow("Turns", overview.totalTurns.toLocaleString()))
+  console.log(renderRow("Days Active", overview.totalDays.toString()))
+  console.log(renderRow("Longest Streak", overview.longestStreak.toString()))
+  console.log(renderRow("Current Streak", overview.currentStreak.toString()))
+  console.log(renderRow("Projects", overview.projectCount.toString()))
+  bottomBorder()
+  console.log()
+
+  // ── Tokens & Cost ─────────────────────────────────────────
+  topBorder()
+  renderHeader("TOKENS & COST")
+  divider()
+  console.log(renderRow("Known API Estimate", `$${tokenCost.cost.toFixed(2)}`))
+  if (tokenCost.accounting) {
+    const accounting = tokenCost.accounting
+    console.log(renderRow("Unpriced API Attempts", accounting.apiEstimate.unknown.toString()))
+    console.log(renderRow("Unobserved Calls", accounting.unobservedCalls.toString()))
+    console.log(renderRow("Subscription API Equivalent", `$${accounting.subscriptionEquivalent.known.toFixed(4)}`))
+    console.log(renderRow("Unknown Subscription Estimates", accounting.subscriptionEquivalent.unknown.toString()))
+    console.log(renderRow("Historical Calculation", `$${accounting.legacy.cost.toFixed(4)}`))
+    for (const [currency, amount] of Object.entries(accounting.reported.currencies))
+      console.log(renderRow(`Provider Reported (${currency})`, amount.toFixed(4)))
+  }
+  console.log(renderRow("Avg Cost/Turn", `$${tokenCost.avgCostPerTurn.toFixed(4)}`))
+  console.log(renderRow("Daily Cost", `$${tokenCost.dailyCost.toFixed(2)}`))
+  console.log(renderRow("Input Tokens", formatNumber(tokenCost.tokens.input)))
+  console.log(renderRow("Output Tokens", formatNumber(tokenCost.tokens.output)))
+  console.log(renderRow("Reasoning (included in output)", formatNumber(tokenCost.tokens.reasoning)))
+  console.log(renderRow("Cache Read", formatNumber(tokenCost.tokens.cache.read)))
+  console.log(renderRow("Cache Write", formatNumber(tokenCost.tokens.cache.write)))
+  console.log(renderRow("Cache Hit Rate", `${(tokenCost.cacheHitRate * 100).toFixed(1)}%`))
+  console.log(renderRow("Avg Tokens/Turn", formatNumber(Math.round(tokenCost.avgTokensPerTurn))))
+  console.log(renderRow("Daily Tokens", formatNumber(Math.round(tokenCost.dailyTokens))))
+  bottomBorder()
+  console.log()
+
+  // ── Models ────────────────────────────────────────────────
+  if (modelLimit !== undefined && models.models.length > 0) {
+    const sorted = [...models.models].sort((a, b) => b.messages - a.messages)
+    const toDisplay = modelLimit === Infinity ? sorted : sorted.slice(0, modelLimit)
+
+    topBorder()
+    renderHeader("MODEL USAGE")
+    divider()
+
+    for (const m of toDisplay) {
+      const modelKey = `${m.providerID}/${m.modelID}`
+      console.log(renderRow(modelKey, ""))
+      console.log(renderRow("  Messages", m.messages.toLocaleString()))
+      console.log(renderRow("  Input Tokens", formatNumber(m.tokens.input)))
+      console.log(renderRow("  Output Tokens", formatNumber(m.tokens.output)))
+      console.log(renderRow("  Known API Estimate", `$${m.cost.toFixed(4)}`))
+      console.log(renderRow("  Avg Response", `${m.avgResponseMs.toFixed(0)}ms`))
+      divider()
+    }
+    // Replace last divider with bottom border
+    process.stdout.write("\x1B[1A")
+    bottomBorder()
+    console.log()
+  }
+
+  // ── Agents ────────────────────────────────────────────────
+  if (agents.agents.length > 0) {
+    const sorted = [...agents.agents].sort((a, b) => b.messages - a.messages)
+
+    topBorder()
+    renderHeader("AGENT USAGE")
+    divider()
+
+    for (const a of sorted) {
+      console.log(renderRow(a.agent, ""))
+      console.log(renderRow("  Messages", a.messages.toLocaleString()))
+      console.log(renderRow("  Sessions", a.sessions.toLocaleString()))
+      console.log(renderRow("  Known API Estimate", `$${a.cost.toFixed(4)}`))
+      console.log(renderRow("  Subagent Calls", a.subagentInvocations.toLocaleString()))
+      divider()
+    }
+    process.stdout.write("\x1B[1A")
+    bottomBorder()
+    console.log()
+
+    if (agents.totalSubagentCalls > 0) {
+      console.log(`  Total subagent calls: ${agents.totalSubagentCalls.toLocaleString()}`)
+      console.log()
+    }
+  }
+
+  // ── Tools ─────────────────────────────────────────────────
+  if (tools.tools.length > 0) {
+    const sorted = [...tools.tools].sort((a, b) => b.calls - a.calls)
+    const toDisplay = toolLimit ? sorted.slice(0, toolLimit) : sorted
+    const maxCalls = Math.max(...toDisplay.map((t) => t.calls))
+    const totalCalls = tools.tools.reduce((sum, t) => sum + t.calls, 0)
+
+    topBorder()
+    renderHeader("TOOL USAGE")
+    divider()
+
+    for (const t of toDisplay) {
+      const ratio = t.calls / maxCalls
+      const bar = UI.progressBar({ ratio, width: 20, brackets: false })
+      const percentage = totalCalls > 0 ? ((t.calls / totalCalls) * 100).toFixed(1) : "0.0"
+      const successRate = t.calls > 0 ? ((t.successes / t.calls) * 100).toFixed(0) : "—"
+
+      const maxToolLength = 18
+      const truncatedTool = t.tool.length > maxToolLength ? t.tool.substring(0, maxToolLength - 2) + ".." : t.tool
+      const toolName = truncatedTool.padEnd(maxToolLength)
+
+      const content = ` ${toolName} ${bar.padEnd(20)} ${t.calls.toString().padStart(4)} (${percentage.padStart(4)}%) ${successRate.padStart(3)}%ok`
+      const padding = Math.max(0, width - content.length - 1)
+      console.log(`│${content}${" ".repeat(padding)} │`)
+    }
+
+    divider()
+    const avgDurLine = ` Avg duration per tool (ms):`
+    console.log(`│${avgDurLine}${" ".repeat(width - avgDurLine.length - 2)} │`)
+    for (const t of toDisplay) {
+      const durText = `   ${t.tool}: ${t.avgDurationMs.toFixed(0)}ms`
+      const padding = Math.max(0, width - durText.length - 2)
+      console.log(`│${durText}${" ".repeat(padding)} │`)
+    }
+
+    bottomBorder()
+    console.log()
+  }
+
+  // ── Code Changes ──────────────────────────────────────────
+  if (codeChanges.totalAdditions > 0 || codeChanges.totalDeletions > 0) {
+    topBorder()
+    renderHeader("CODE CHANGES")
+    divider()
+    console.log(renderRow("Additions", formatNumber(codeChanges.totalAdditions)))
+    console.log(renderRow("Deletions", formatNumber(codeChanges.totalDeletions)))
+    console.log(renderRow("Net Lines", formatNumber(codeChanges.netLines)))
+    console.log(renderRow("Files Touched", formatNumber(codeChanges.totalFiles)))
+    console.log(renderRow("Daily Additions", formatNumber(Math.round(codeChanges.dailyAdditions))))
+    console.log(renderRow("Daily Deletions", formatNumber(Math.round(codeChanges.dailyDeletions))))
+    bottomBorder()
+    console.log()
+  }
+
+  // ── Lifecycle ─────────────────────────────────────────────
+  topBorder()
+  renderHeader("LIFECYCLE")
+  divider()
+  console.log(renderRow("Pinned Sessions", lifecycle.pinnedCount.toLocaleString()))
+  console.log(renderRow("Avg Turns/Session", lifecycle.avgTurnsPerSession.toFixed(1)))
+  console.log(renderRow("Median Turns/Session", lifecycle.medianTurnsPerSession.toFixed(1)))
+  console.log(renderRow("Compactions", lifecycle.compactionCount.toLocaleString()))
+  console.log(renderRow("Retries", lifecycle.retryCount.toLocaleString()))
+  console.log(renderRow("Error Rate", `${(lifecycle.errorRate * 100).toFixed(1)}%`))
+  console.log(
+    renderRow(
+      "Duration (short/med/long)",
+      `${lifecycle.durationBuckets.short}/${lifecycle.durationBuckets.medium}/${lifecycle.durationBuckets.long}`,
+    ),
+  )
+  bottomBorder()
+  console.log()
+
+  // ── Channels ──────────────────────────────────────────────
+  if (channels.channels.length > 0) {
+    topBorder()
+    renderHeader("CHANNELS")
+    divider()
+
+    for (const c of channels.channels) {
+      console.log(renderRow(c.channel, `sessions: ${c.sessions}, messages: ${c.messages}`))
+    }
+
+    divider()
+    console.log(renderRow("Interactive", channels.interactiveSessions.toLocaleString()))
+    console.log(renderRow("Unattended", channels.unattendedSessions.toLocaleString()))
+    bottomBorder()
+    console.log()
+  }
+}
+
+function formatNumber(num: number): string {
+  if (num >= 1000000) {
+    return (num / 1000000).toFixed(1) + "M"
+  } else if (num >= 1000) {
+    return (num / 1000).toFixed(1) + "K"
+  }
+  return num.toString()
+}

package/src/stats/engine.ts

@@ -0,0 +1,197 @@
+import { RolloutSnapshot } from "@ericsanchezok/synergy-harness/session/rollout/snapshot"
+import { OperationDigest } from "./types"
+import { Lock } from "@ericsanchezok/synergy-harness/util/lock"
+import { readRolloutRevision } from "@ericsanchezok/synergy-harness/rollout"
+import type { Info as SessionInfo } from "@ericsanchezok/synergy-harness/session/types"
+import { Storage } from "@ericsanchezok/synergy-harness/storage/storage"
+import { StoragePath } from "@ericsanchezok/synergy-harness/storage/path"
+import { Aggregator } from "./aggregator"
+import { StatsStorage } from "./storage"
+import { Rollup } from "./rollup"
+import { CanonicalStats } from "./canonical"
+import { Usage } from "@ericsanchezok/synergy-harness/usage"
+import type { StatsWatermark, StatsSnapshot, ProgressCallback } from "./types"
+
+export namespace Engine {
+  // -----------------------------------------------------------------------
+  // Public API
+  // -----------------------------------------------------------------------
+
+  /**
+   * Run incremental stats update: scan sessions changed since watermark,
+   * update digests + daily buckets, recompute snapshot.
+   */
+  export async function update(onProgress?: ProgressCallback): Promise<StatsSnapshot> {
+    return requestRefresh(false, onProgress)
+  }
+
+  const jobs = Storage.state(
+    () =>
+      new Map<
+        boolean,
+        {
+          promise: Promise<StatsSnapshot>
+          listeners: Set<ProgressCallback>
+        }
+      >(),
+  )
+
+  function requestRefresh(full: boolean, onProgress?: ProgressCallback): Promise<StatsSnapshot> {
+    const running = jobs()
+    const existing = running.get(full) ?? (!full ? running.get(true) : undefined)
+    if (existing) {
+      if (onProgress) existing.listeners.add(onProgress)
+      return existing.promise.finally(() => {
+        if (onProgress) existing.listeners.delete(onProgress)
+      })
+    }
+    const listeners = new Set<ProgressCallback>(onProgress ? [onProgress] : [])
+    const promise = refresh(full, (event) => {
+      for (const listener of listeners)
+        void Promise.resolve()
+          .then(() => listener(event))
+          .catch(() => listeners.delete(listener))
+    }).finally(() => running.delete(full))
+    running.set(full, { promise, listeners })
+    return promise
+  }
+
+  async function operationDigests() {
+    const result: OperationDigest[] = []
+    const retained = new Set<string>()
+    for (const scopeID of await Storage.scan(["operations"])) {
+      for (const operationID of await Storage.scan(["operations", scopeID])) {
+        const owner = { kind: "operation" as const, scopeID, operationID }
+        const revision = await readRolloutRevision(owner)
+        if (!revision) continue
+        const key = StoragePath.statsOperation(scopeID, operationID)
+        retained.add(key.join("/"))
+        const cached = await Storage.read(key).catch((error) => {
+          if (error instanceof Storage.NotFoundError) return undefined
+          throw error
+        })
+        const parsed = OperationDigest.safeParse(cached)
+        if (parsed.success && parsed.data.rolloutRevision === revision) {
+          result.push(parsed.data)
+          continue
+        }
+        const digest = Aggregator.operation(await RolloutSnapshot.read(owner, { revision }))
+        await Storage.write(key, digest)
+        result.push(digest)
+      }
+    }
+    for (const scopeID of await Storage.scan(StoragePath.statsOperations()))
+      for (const id of await Storage.scan([...StoragePath.statsOperations(), scopeID])) {
+        const key = StoragePath.statsOperation(scopeID, id)
+        if (!retained.has(key.join("/"))) await Storage.remove(key)
+      }
+    return result
+  }
+
+  async function refresh(full: boolean, onProgress?: ProgressCallback): Promise<StatsSnapshot> {
+    using lock = await Lock.write("stats-update")
+    const watermark = full ? undefined : await StatsStorage.getWatermark()
+
+    onProgress?.({ phase: "scan", current: 0, total: 1, message: "Scanning sessions..." })
+    const allSessions = await getAllSessions()
+
+    let newOrUpdated: SessionInfo[]
+    let deletedIDs: string[]
+
+    if (watermark) {
+      const knownSet = new Set(watermark.sessionIDs)
+      const currentMap = new Map(allSessions.map((s) => [s.id, s]))
+
+      // Sessions that are new or updated since watermark
+      newOrUpdated = []
+      for (let offset = 0; offset < allSessions.length; offset += 20) {
+        const batch = allSessions.slice(offset, offset + 20)
+        const changed = await Promise.all(
+          batch.map(async (session) => {
+            if (!knownSet.has(session.id) || session.time.updated > watermark.lastUpdated) return true
+            const [digest, revision] = await Promise.all([
+              StatsStorage.getDigest(session.id),
+              readRolloutRevision({ kind: "session", scopeID: session.scope.id, sessionID: session.id }),
+            ])
+            return digest?.rolloutRevision !== revision
+          }),
+        )
+        newOrUpdated.push(...batch.filter((_, index) => changed[index]))
+      }
+
+      // Sessions that were known but no longer exist
+      deletedIDs = watermark.sessionIDs.filter((id) => !currentMap.has(id))
+    } else {
+      newOrUpdated = allSessions
+      deletedIDs = []
+    }
+
+    // Digest new/updated sessions with progress
+    const freshDigests = await Aggregator.digestAll(newOrUpdated, (current, total) => {
+      onProgress?.({ phase: "digest", current, total, message: `Digesting sessions ${current}/${total}...` })
+    })
+
+    // Write new/updated digests
+    for (const d of freshDigests) {
+      await Usage.preserveOwner({ kind: "session", scopeID: d.scopeID, sessionID: d.sessionID })
+      await StatsStorage.setDigest(d)
+    }
+
+    // Remove digests for deleted sessions
+    for (const id of deletedIDs) {
+      await StatsStorage.removeDigest(id)
+    }
+
+    // Load all digests for full snapshot
+    onProgress?.({ phase: "snapshot", current: 0, total: 1, message: "Computing snapshot..." })
+    const allDigests = await StatsStorage.getAllDigests()
+
+    // Compute new watermark
+    const maxUpdated = allSessions.length > 0 ? Math.max(...allSessions.map((s) => s.time.updated)) : 0
+    const newWatermark: StatsWatermark = {
+      lastUpdated: maxUpdated,
+      sessionIDs: allSessions.map((s) => s.id),
+      lastFullScanAt: Date.now(),
+    }
+
+    // Compute and store snapshot
+    const snapshot = await CanonicalStats.apply(Rollup.snapshot(allDigests, maxUpdated, await operationDigests()))
+    onProgress?.({
+      phase: "bucket",
+      current: 0,
+      total: snapshot.timeSeries.days.length,
+      message: "Updating daily buckets...",
+    })
+    const days = new Set(snapshot.timeSeries.days.map((day) => day.day))
+    for (const day of snapshot.timeSeries.days) await StatsStorage.setDailyBucket(day.day, day)
+    for (const day of await StatsStorage.listDailyKeys()) {
+      if (!days.has(day)) await Storage.remove(StoragePath.statsDaily(day))
+    }
+    await StatsStorage.setSnapshot(snapshot)
+    await StatsStorage.setWatermark(newWatermark)
+
+    onProgress?.({ phase: "snapshot", current: 1, total: 1, message: "Done" })
+    return snapshot
+  }
+
+  export async function get(): Promise<StatsSnapshot | null> {
+    return (await StatsStorage.getSnapshot()) ?? null
+  }
+
+  /**
+   * Force full recompute from scratch (clears all cached stats).
+   */
+  export async function recompute(onProgress?: ProgressCallback): Promise<StatsSnapshot> {
+    return requestRefresh(true, onProgress)
+  }
+
+  // -----------------------------------------------------------------------
+  // Internal helpers
+  // -----------------------------------------------------------------------
+
+  async function getAllSessions(): Promise<SessionInfo[]> {
+    const sessions: SessionInfo[] = []
+    for await (const record of Storage.records<SessionInfo>({ kind: "session" })) sessions.push(record.value)
+    return sessions
+  }
+}

package/src/stats/index.ts

@@ -0,0 +1,5 @@
+export { Engine } from "./engine"
+export { Aggregator } from "./aggregator"
+export { Rollup } from "./rollup"
+export { StatsStorage } from "./storage"
+export * from "./types"