mixdog 0.9.174 → 1.0.0

package/src/standalone/usage-stats-model.mjs

@@ -1,653 +1 @@
-/**
- * Token/cost aggregation by provider, with a per-model drill-down.
- *
- * Two stores answer the same question over different horizons: the raw gateway
- * event list is complete but bounded to a recent window, while the daily rollup
- * survives indefinitely. A day that exists in the rollup is owned by the rollup
- * and the events it already contains are skipped by timestamp, so the events on
- * either side of that span still count and no turn counts twice. Days that
- * predate the rollup are recovered from the events alone.
- *
- * Both stores start at the day they were introduced, and the event list is
- * additionally capped by row count, so neither reaches the months already on
- * disk as session transcripts. A third source rebuilds those days from the
- * transcripts; it is consulted only where the other two have nothing, which is
- * what keeps a recovered day from landing on top of a recorded one.
- *
- * By default only the user's own turns are reported. Background runners spend
- * several times more tokens than the conversation does on this machine, so
- * folding them into the same number answers a question nobody asked.
- *
- * Pure module: callers pass both stores in, which keeps the arithmetic testable
- * and keeps disk access at the runtime boundary.
- */
-import { billableInputTokensForProvider } from '../runtime/shared/llm/cost.mjs';
-import { hourlySeries } from './usage-stats-hours.mjs';
-import { isConversationUsageSource, knownCostTurns, usageRollupDayKey } from '../runtime/shared/llm/usage-rollup.mjs';
-
-function num(value) {
-  const n = Number(value);
-  return Number.isFinite(n) && n > 0 ? n : 0;
-}
-
-function text(value) {
-  return typeof value === 'string' ? value.trim() : '';
-}
-
-/** `numerator / denominator` rounded; null while any turn is unmeasured, 0 without a denominator. */
-function measuredRatio(unmeasuredTurns, numerator, denominator, digits) {
-  if (unmeasuredTurns > 0) return null;
-  return denominator > 0 ? round(numerator / denominator, digits) : 0;
-}
-
-function round(value, digits) {
-  const factor = 10 ** digits;
-  return Math.round(value * factor) / factor;
-}
-
-/**
- * `days === null` is all time, `0` is today, and N is N calendar dates including
- * today. Day buckets cannot truthfully answer partial historical-day windows.
- */
-function resolveWindow(days, now) {
-  if (days === 0) {
-    const midnight = new Date(now);
-    midnight.setHours(0, 0, 0, 0);
-    return { days: 0, fromMs: midnight.getTime(), toMs: now };
-  }
-  const span = Number(days);
-  if (!Number.isFinite(span) || span <= 0) return { days: null, fromMs: 0, toMs: now };
-  const first = new Date(now);
-  first.setHours(0, 0, 0, 0);
-  first.setDate(first.getDate() - Math.floor(span) + 1);
-  return { days: Math.floor(span), fromMs: first.getTime(), toMs: now };
-}
-
-/** The same-length window immediately before this one, for a change figure. */
-function previousWindow(window) {
-  if (window.days === null) return null;
-  // No misleading full-yesterday comparison against an unfinished today.
-  if (window.days === 0) return null;
-  const first = new Date(window.fromMs);
-  first.setDate(first.getDate() - window.days);
-  return { days: window.days, fromMs: first.getTime(), toMs: window.fromMs - 1 };
-}
-
-function createState() {
-  return {
-    turns: 0,
-    input: 0,
-    output: 0,
-    cacheRead: 0,
-    cacheWrite: 0,
-    costUsd: 0,
-    costBilled: 0,
-    costEstimated: 0,
-    costKnownTurns: 0,
-    unmeasuredTurns: 0,
-    durationMs: 0,
-    durationTurns: 0,
-    providers: new Map(),
-    sessions: new Map(),
-    sessionsComplete: true,
-    anonymousSessions: [],
-    sessionsDropped: 0,
-    dayKeys: new Set(),
-    daily: new Map(),
-    rollupDays: 0,
-    eventDays: 0,
-    // Days rebuilt from the session transcripts because neither store holds
-    // them any more.
-    historyDays: 0,
-    // Days written before turns carried a source cannot answer "mine only".
-    unclassifiedDays: 0,
-    unclassifiedTurns: 0,
-    partialDays: 0,
-  };
-}
-
-function providerBucket(state, provider, kind) {
-  let bucket = state.providers.get(provider);
-  if (!bucket) {
-    bucket = {
-      provider,
-      providerKind: '',
-      turns: 0,
-      input: 0,
-      output: 0,
-      cacheRead: 0,
-      cacheWrite: 0,
-      costUsd: 0,
-      models: new Map(),
-      sessions: new Set(),
-      sessionsComplete: true,
-    };
-    state.providers.set(provider, bucket);
-  }
-  if (kind && !bucket.providerKind) bucket.providerKind = kind;
-  return bucket;
-}
-
-function modelBucket(provider, model) {
-  let bucket = provider.models.get(model);
-  if (!bucket) {
-    bucket = {
-      model,
-      turns: 0,
-      input: 0,
-      output: 0,
-      cacheRead: 0,
-      cacheWrite: 0,
-      costUsd: 0,
-      sessions: new Set(),
-      sessionsComplete: true,
-    };
-    provider.models.set(model, bucket);
-  }
-  return bucket;
-}
-
-function addUsage(target, usage) {
-  target.turns += usage.turns;
-  target.input += usage.input;
-  target.output += usage.output;
-  target.cacheRead += usage.cacheRead;
-  target.cacheWrite += usage.cacheWrite;
-  target.costUsd += usage.costUsd;
-  target.costKnownTurns = (target.costKnownTurns || 0) + (usage.costKnownTurns || 0);
-  target.costBilled = (target.costBilled || 0) + (usage.costBilled || 0);
-  target.costEstimated = (target.costEstimated || 0) + (usage.costEstimated || 0);
-  target.unmeasuredTurns = (target.unmeasuredTurns || 0) + (usage.unmeasuredTurns || 0);
-}
-
-function foldRoute(state, providerId, modelId, kind, usage) {
-  const provider = providerBucket(state, providerId, kind);
-  const model = modelBucket(provider, modelId);
-  for (const bucket of [provider, model]) {
-    addUsage(bucket, usage);
-    if (usage.turns > 0 && (!usage.sessions || usage.sessionsComplete === false)) {
-      bucket.sessionsComplete = false;
-    }
-    for (const id of Object.keys(usage.sessions || {})) bucket.sessions.add(id);
-  }
-  addUsage(state, usage);
-}
-
-function addDaily(state, key, usage, providerId) {
-  let bucket = state.daily.get(key);
-  if (!bucket) {
-    bucket = {
-      day: key,
-      turns: 0,
-      input: 0,
-      output: 0,
-      cacheRead: 0,
-      cacheWrite: 0,
-      costUsd: 0,
-      // Per-provider split of this day, so a chart can show WHICH provider a
-      // day's spend went to instead of one anonymous total.
-      providers: new Map(),
-    };
-    state.daily.set(key, bucket);
-  }
-  addUsage(bucket, usage);
-  const id = text(providerId);
-  if (!id) return;
-  let slice = bucket.providers.get(id);
-  if (!slice) {
-    slice = { provider: id, turns: 0, input: 0, output: 0, cacheRead: 0, cacheWrite: 0, costUsd: 0 };
-    bucket.providers.set(id, slice);
-  }
-  addUsage(slice, usage);
-}
-
-function foldRollupDay(state, key, day, conversationOnly) {
-  const totals = conversationOnly ? day?.conversation : day;
-  if (!totals) {
-    // The whole day predates source attribution. Leaving it out is the only
-    // honest answer for a conversation-only view; the count reports the gap.
-    state.unclassifiedDays += 1;
-    state.unclassifiedTurns += num(day?.turns);
-    return;
-  }
-  state.dayKeys.add(key);
-  // A rebuilt day keeps saying so after it is frozen into the rollup, which is
-  // the only thing left distinguishing it from a recorded one.
-  if (day?.restored === true) state.historyDays += 1;
-  if (day?.importedPartial === true) state.partialDays += 1;
-  if (conversationOnly && day?.conversationPartial === true) state.partialDays += 1;
-  state.durationMs += num(totals.durationMs);
-  state.durationTurns += num(totals.durationTurns);
-  state.sessionsDropped += num(day?.sessionsDropped);
-  if (totals.sessionsComplete === false || num(day?.sessionsDropped) > 0) state.sessionsComplete = false;
-
-  const models = day?.models && typeof day.models === 'object' ? day.models : {};
-  for (const [routeKey, raw] of Object.entries(models)) {
-    const route = conversationOnly ? raw?.conversation : raw;
-    if (!route) continue;
-    const slash = routeKey.indexOf('/');
-    const providerId = text(raw?.provider) || (slash > 0 ? routeKey.slice(0, slash) : '');
-    const modelId = text(raw?.model) || (slash > 0 ? routeKey.slice(slash + 1) : '');
-    if (!providerId || !modelId) continue;
-    const usage = {
-      turns: num(route.turns),
-      input: num(route.input),
-      output: num(route.output),
-      cacheRead: num(route.cacheRead),
-      cacheWrite: num(route.cacheWrite),
-      costUsd: num(route.costUsd),
-      costKnownTurns: knownCostTurns(route, num),
-      costBilled: num(route.costBilled),
-      costEstimated:
-        route.costEstimated == null
-          ? Math.max(0, num(route.costUsd) - num(route.costBilled))
-          : num(route.costEstimated),
-      sessions: route.sessions,
-      sessionsComplete: route.sessionsComplete,
-      unmeasuredTurns: num(route.unmeasuredTurns),
-    };
-    foldRoute(state, providerId, modelId, text(raw?.kind), usage);
-    addDaily(state, key, usage, providerId);
-  }
-
-  // Session ids are recorded for conversation turns only, so both views read
-  // the same map: a background cycle has no session worth counting. The one
-  // exception is a day whose ids were collected while cycles still counted and
-  // never cleared — keeping those would inflate the count by an order of
-  // magnitude. The raw events still cover such a recent day.
-  const partial = conversationOnly && day?.conversationPartial === true && day?.sessionsPurged !== true;
-  const sessions = !partial && day?.sessions && typeof day.sessions === 'object' ? day.sessions : {};
-  for (const [id, tokens] of Object.entries(sessions)) {
-    // One session can span midnight; its totals are summed across days.
-    state.sessions.set(id, (state.sessions.get(id) || 0) + num(tokens));
-  }
-  if (!partial && Array.isArray(day?.sessionTokens)) {
-    for (const tokens of day.sessionTokens) state.anonymousSessions.push(num(tokens));
-    if (day.sessionTokens.length) state.sessionsComplete = false;
-  }
-}
-
-function foldEvent(state, key, event, conversationOnly) {
-  const conversation = isConversationUsageSource(event?.sourceType);
-  if (conversationOnly && !conversation) return;
-  const providerId = text(event?.provider);
-  const modelId = text(event?.model);
-  if (!providerId || !modelId) return;
-  state.dayKeys.add(key);
-
-  const cacheRead = num(event?.cacheReadTokens);
-  const cacheWrite = num(event?.cacheWriteTokens);
-  const sessionId = conversation ? text(event?.sessionId) : '';
-  const costSource = text(event?.costSource);
-  const priced =
-    event?.costUsd != null && Number.isFinite(Number(event.costUsd)) && !['', 'none', 'unpriced'].includes(costSource);
-  const usage = {
-    turns: 1,
-    // Same normalization the rollup applies: a provider that reports the whole
-    // prompt as input would otherwise have its cache counted twice.
-    input: billableInputTokensForProvider(providerId, num(event?.inputTokens), cacheRead, cacheWrite),
-    output: num(event?.outputTokens),
-    cacheRead,
-    cacheWrite,
-    costUsd: num(event?.costUsd),
-    costKnownTurns: priced ? 1 : 0,
-    costBilled: priced && costSource === 'provider' ? num(event.costUsd) : 0,
-    costEstimated: priced && costSource !== 'provider' ? num(event.costUsd) : 0,
-    sessions: sessionId ? { [sessionId]: 1 } : {},
-    sessionsComplete: !conversation || Boolean(sessionId),
-  };
-  foldRoute(state, providerId, modelId, text(event?.providerKind), usage);
-  addDaily(state, key, usage, providerId);
-
-  const durationMs = num(event?.durationMs);
-  if (durationMs > 0) {
-    state.durationMs += durationMs;
-    state.durationTurns += 1;
-  }
-  if (sessionId) {
-    const tokens = usage.input + usage.output + usage.cacheRead + usage.cacheWrite;
-    state.sessions.set(sessionId, (state.sessions.get(sessionId) || 0) + tokens);
-  } else if (conversation) state.sessionsComplete = false;
-}
-
-function collect({ events, rollupDays, historyDays, window, conversationOnly }) {
-  const fromKey = window.fromMs > 0 ? usageRollupDayKey(window.fromMs) : '';
-  const toKey = usageRollupDayKey(window.toMs);
-  const state = createState();
-
-  const eventsByDay = new Map();
-  for (const event of events) {
-    const ts = Number(event?.ts);
-    if (!Number.isFinite(ts) || ts < window.fromMs || ts > window.toMs) continue;
-    const key = usageRollupDayKey(ts);
-    const group = eventsByDay.get(key);
-    if (group) group.push(event);
-    else eventsByDay.set(key, [event]);
-  }
-  // The event list is bounded by row count, and the cap evicts the oldest rows
-  // first, so its earliest day is the one arriving half-eaten. Every later day
-  // is whole. Naming it here lets the rebuild step below take that one day back
-  // without second-guessing the days the store really does cover.
-  const truncatedEventDay = eventsByDay.size ? [...eventsByDay.keys()].sort()[0] : '';
-
-  // The rollup owns every day it holds, because it outlives the event cap.
-  // firstTs/lastTs say which turns it already contains, so only the events
-  // outside that span are added on top — the turns of the day before rolling
-  // up began, and anything written after the last fold. A bucket from before
-  // those bounds existed carries no span: there the fuller store is taken
-  // whole, since nothing distinguishes an overlapping turn from a new one.
-  for (const [key, day] of Object.entries(rollupDays)) {
-    if (key < fromKey || key > toKey) continue;
-    const group = eventsByDay.get(key);
-    // A bucket written before turns carried a source cannot answer "mine
-    // only". Where the raw events still cover that day they can, so they are
-    // used instead of dropping the day entirely.
-    if (conversationOnly && !day?.conversation && group?.length) continue;
-    const firstTs = num(day?.firstTs);
-    const lastTs = num(day?.lastTs);
-    if (firstTs > 0 && lastTs > 0) {
-      const extra = group
-        ? group.filter((event) => {
-            const ts = Number(event?.ts);
-            return Number.isFinite(ts) && (ts < firstTs || ts > lastTs);
-          })
-        : [];
-      if (extra.length) eventsByDay.set(key, extra);
-      else eventsByDay.delete(key);
-    } else {
-      if (group && group.length > num(day?.turns)) continue;
-      eventsByDay.delete(key);
-    }
-    state.rollupDays += 1;
-    foldRollupDay(state, key, day, conversationOnly);
-  }
-
-  // Transcript-derived days are the last resort: a recorded day always wins,
-  // whether it came from the rollup or from the events still on disk. Only the
-  // days neither store reaches — everything before recording began, and
-  // everything the event cap evicted — are taken from here.
-  for (const [key, day] of Object.entries(historyDays || {})) {
-    if (key < fromKey || key > toKey) continue;
-    if (rollupDays[key]) continue;
-    const group = eventsByDay.get(key);
-    if (group?.length) {
-      // A whole day of events outranks a rebuild of it.
-      if (key !== truncatedEventDay) continue;
-      // On the truncated day the two sources are compared as wholes and the
-      // fuller one takes the day: the surviving rows would otherwise report a
-      // full day of work as the handful of turns the cap happened to spare.
-      if (num(day?.turns) <= group.length) continue;
-      eventsByDay.delete(key);
-    }
-    foldRollupDay(state, key, day, conversationOnly);
-  }
-
-  state.eventDays = eventsByDay.size;
-  for (const [key, group] of eventsByDay) {
-    for (const event of group) foldEvent(state, key, event, conversationOnly);
-  }
-  return state;
-}
-
-/** Every calendar day from `first` to `last`, inclusive. */
-function calendarDays(first, last) {
-  if (!first || !last) return [];
-  const out = [];
-  const cursor = new Date(`${first}T00:00:00`);
-  const end = Date.parse(`${last}T00:00:00`);
-  if (Number.isNaN(cursor.getTime()) || Number.isNaN(end)) return [];
-  // Walking the Date itself (rather than adding 24h) keeps a daylight-saving
-  // boundary from shifting the key by a day.
-  while (cursor.getTime() <= end) {
-    out.push(usageRollupDayKey(cursor.getTime()));
-    cursor.setDate(cursor.getDate() + 1);
-    if (out.length > 4000) break;
-  }
-  return out;
-}
-
-function median(values) {
-  if (!values.length) return 0;
-  const sorted = [...values].sort((a, b) => a - b);
-  const middle = Math.floor(sorted.length / 2);
-  return sorted.length % 2 === 0 ? (sorted[middle - 1] + sorted[middle]) / 2 : sorted[middle];
-}
-
-// "tokens" is everything a turn moved: fresh input, output, and the cached
-// prompt it read or wrote. Cached providers re-read the whole context every
-// turn, so counting only the fresh part made a cached route look idle beside
-// an uncached one doing the same work. The split stays in input/output/cache.
-function tokensOf(bucket) {
-  return bucket.input + bucket.output + bucket.cacheRead + bucket.cacheWrite;
-}
-
-function exportRoute(bucket, totalTokens) {
-  const tokens = tokensOf(bucket);
-  const fresh = bucket.input + bucket.output;
-  const prompt = bucket.input + bucket.cacheRead + bucket.cacheWrite;
-  const unmeasuredTurns = num(bucket.unmeasuredTurns);
-  const unknown = unmeasuredTurns > 0 && unmeasuredTurns === bucket.turns;
-  return {
-    turns: bucket.turns,
-    // Ids that were seen are counted even when some turns carried none: the
-    // figure is then a floor, and the flag says so, rather than an unknown.
-    sessions: bucket.sessions.size,
-    sessionsComplete: bucket.sessionsComplete,
-    input: unknown ? null : bucket.input,
-    output: bucket.output,
-    cacheRead: unknown ? null : bucket.cacheRead,
-    cacheWrite: unknown ? null : bucket.cacheWrite,
-    cacheTokens: bucket.cacheRead + bucket.cacheWrite,
-    tokens,
-    unmeasuredTurns,
-    costUsd: round(bucket.costUsd, 6),
-    costBilled: round(num(bucket.costBilled), 6),
-    costEstimated: round(num(bucket.costEstimated), 6),
-    costKnownTurns: num(bucket.costKnownTurns),
-    costUnpricedTurns: Math.max(0, bucket.turns - num(bucket.costKnownTurns)),
-    costCoverage: bucket.turns > 0 ? num(bucket.costKnownTurns) / bucket.turns : 0,
-    share: measuredRatio(unmeasuredTurns, tokens, totalTokens, 6),
-    // How much of this route's prompt arrived from cache instead of being read
-    // again. Cache writes are misses, so belong in the denominator, not the
-    // numerator.
-    cacheHitRate: measuredRatio(unmeasuredTurns, bucket.cacheRead, prompt, 4),
-    // What a million fresh tokens actually cost on this route. Cache is excluded
-    // from the divisor: including it would divide real spend by a number two
-    // orders of magnitude larger and rank every route as free.
-    costPerMTokens: fresh > 0 ? round(bucket.costUsd / (fresh / 1_000_000), 4) : 0,
-    // Answer length, which is what separates a terse route from a verbose one
-    // at the same price.
-    outputPerTurn: bucket.turns > 0 ? Math.round(bucket.output / bucket.turns) : 0,
-  };
-}
-
-/** Provider rows for the window: each provider's route totals plus its
- *  per-model split, both ordered by tokens then cost. `modelLimit` truncates
- *  only the model list, never the provider list. */
-function exportProviders(state, { totalTokens, modelLimit }) {
-  return [...state.providers.values()]
-    .map((bucket) => {
-      const models = [...bucket.models.values()]
-        .map((model) => ({ model: model.model, ...exportRoute(model, totalTokens) }))
-        .sort((a, b) => b.tokens - a.tokens || b.costUsd - a.costUsd);
-      return {
-        provider: bucket.provider,
-        providerKind: bucket.providerKind,
-        ...exportRoute(bucket, totalTokens),
-        modelCount: models.length,
-        models: modelLimit > 0 ? models.slice(0, modelLimit) : models,
-      };
-    })
-    .sort((a, b) => b.tokens - a.tokens || b.costUsd - a.costUsd);
-}
-
-/** One row per calendar day in the window, with its per-provider split.
- *  A day with no traffic is still a day. Only the days that HAD usage are
- *  collected upstream, so an idle stretch would otherwise vanish and pull the
- *  surrounding days together — a fortnight off would read as continuous work.
- *  Filling the calendar keeps a quiet day visible as a quiet day. */
-function exportDailySeries(state, { window, period, firstDay, endDay }) {
-  return calendarDays(window.days === null ? firstDay : usageRollupDayKey(window.fromMs), period?.endDay || endDay).map(
-    (day) => {
-      const bucket = state.daily.get(day);
-      const future = period ? { future: day > endDay } : {};
-      if (!bucket) {
-        return { day, turns: 0, tokens: 0, cacheTokens: 0, costUsd: 0, costKnownTurns: 0, providers: [], ...future };
-      }
-      return {
-        day: bucket.day,
-        turns: bucket.turns,
-        tokens: tokensOf(bucket),
-        cacheTokens: bucket.cacheRead + bucket.cacheWrite,
-        costUsd: round(bucket.costUsd, 6),
-        costKnownTurns: num(bucket.costKnownTurns),
-        unmeasuredTurns: num(bucket.unmeasuredTurns),
-        ...future,
-        providers: [...bucket.providers.values()]
-          .map((slice) => ({
-            provider: slice.provider,
-            turns: slice.turns,
-            tokens: tokensOf(slice),
-            costUsd: round(slice.costUsd, 6),
-            costKnownTurns: num(slice.costKnownTurns),
-            unmeasuredTurns: num(slice.unmeasuredTurns),
-          }))
-          .sort((a, b) => b.tokens - a.tokens),
-      };
-    }
-  );
-}
-
-/** Window totals: volume, spend and the derived per-day/per-session rates. */
-function exportTotals(state, { sessionTotals, totalTokens, cacheTokens, effectiveDays }) {
-  return {
-    sessions: sessionTotals.length,
-    sessionsComplete: state.sessionsComplete,
-    turns: state.turns,
-    days: effectiveDays,
-    input: state.input,
-    output: state.output,
-    tokens: totalTokens,
-    unmeasuredTurns: state.unmeasuredTurns,
-    cacheRead: state.cacheRead,
-    cacheWrite: state.cacheWrite,
-    cacheTokens,
-    totalTokens,
-    // How much of the prompt arrived from cache instead of being read again.
-    cacheHitRate: measuredRatio(
-      state.unmeasuredTurns,
-      state.cacheRead,
-      state.input + state.cacheRead + state.cacheWrite,
-      4
-    ),
-    costUsd: round(state.costUsd, 6),
-    costKnownTurns: state.costKnownTurns,
-    costUnpricedTurns: Math.max(0, state.turns - state.costKnownTurns),
-    // Priced by the provider vs derived from the catalog. A subscription turn
-    // lands in the second: real spend, but never an invoice line.
-    costBilled: round(state.costBilled, 6),
-    costEstimated: round(state.costEstimated, 6),
-    costPerDay: effectiveDays > 0 ? round(state.costUsd / effectiveDays, 6) : 0,
-    tokensPerSession: sessionTotals.length ? Math.round(totalTokens / sessionTotals.length) : 0,
-    medianTokensPerSession: Math.round(median(sessionTotals)),
-    avgDurationMs: state.durationTurns > 0 ? Math.round(state.durationMs / state.durationTurns) : 0,
-    // 1 = every turn carries a real price; below that some rows are unpriced.
-    costCoverage: state.turns > 0 ? round(state.costKnownTurns / state.turns, 4) : 0,
-  };
-}
-
-/** How much of the window the figures actually saw, and what they had to skip. */
-function exportCoverage(state, historyPending) {
-  return {
-    rollupDays: state.rollupDays,
-    eventDays: state.eventDays,
-    // Days rebuilt from transcripts, and whether that rebuild is still
-    // running — a surface can then say the older figures may still grow.
-    historyDays: state.historyDays,
-    historyPending: historyPending === true,
-    sessionsDropped: state.sessionsDropped,
-    // Days the rollup holds without a source split; excluded from a
-    // conversation-only view rather than guessed at.
-    unclassifiedDays: state.unclassifiedDays,
-    unclassifiedTurns: state.unclassifiedTurns,
-    partialDays: state.partialDays,
-  };
-}
-
-/**
- * @param {object} options
- * @param {Array}  [options.events] raw gateway usage events
- * @param {object} [options.rollup] normalized daily rollup document
- * @param {number} [options.now]
- * @param {number|null} [options.days] null = all time, 0 = today, N = last N days
- * @param {number} [options.modelLimit] 0 = every model
- * @param {'conversation'|'all'} [options.source] default: the user's own turns
- * @param {object|null} [options.period] calendar selection from resolveUsageStatsPeriod
- */
-export function usageStatsSnapshot({
-  events = [],
-  rollup = null,
-  history = null,
-  historyPending = false,
-  now = Date.now(),
-  days = null,
-  period = null,
-  modelLimit = 0,
-  source = 'conversation',
-} = {}) {
-  const conversationOnly = source !== 'all';
-  const window = period ? { days: period.days, fromMs: period.fromMs, toMs: period.toMs } : resolveWindow(days, now);
-  const rollupDays = rollup?.days && typeof rollup.days === 'object' ? rollup.days : {};
-  let historyDays = {};
-  if (history?.days && typeof history.days === 'object') historyDays = history.days;
-  else if (history && typeof history === 'object') historyDays = history;
-  const eventList = Array.isArray(events) ? events : [];
-  const state = collect({ events: eventList, rollupDays, historyDays, window, conversationOnly });
-
-  const cacheTokens = state.cacheRead + state.cacheWrite;
-  const totalTokens = state.input + state.output + cacheTokens;
-  const sessionTotals = [...state.sessions.values(), ...state.anonymousSessions];
-  const dayKeys = [...state.dayKeys].sort();
-  const firstDay = dayKeys[0] || '';
-  const lastDay = dayKeys[dayKeys.length - 1] || '';
-  // Cost per day is read against the calendar span, not the days that happened
-  // to have traffic — an idle day still spends nothing and must dilute it.
-  const endDay = usageRollupDayKey(window.toMs);
-  const spanDays = firstDay ? calendarDays(firstDay, endDay).length : 0;
-  const effectiveDays = window.days === null ? spanDays : Math.max(1, window.days || 1);
-
-  const providers = exportProviders(state, { totalTokens, modelLimit });
-  const daily = exportDailySeries(state, { window, period, firstDay, endDay });
-
-  // "All time" has nothing before it to compare against.
-  const earlier = period ? null : previousWindow(window);
-  const prior = earlier
-    ? collect({ events: eventList, rollupDays, historyDays, window: earlier, conversationOnly })
-    : null;
-
-  return {
-    generatedAt: now,
-    ...(period ? { period } : {}),
-    ...(period?.view === 'hour' ? { hourly: hourlySeries(rollup?.hourly, period, conversationOnly) } : {}),
-    source: conversationOnly ? 'conversation' : 'all',
-    range: {
-      days: window.days,
-      fromMs: window.fromMs,
-      toMs: window.toMs,
-      firstDay,
-      lastDay,
-      activeDays: dayKeys.length,
-    },
-    totals: exportTotals(state, { sessionTotals, totalTokens, cacheTokens, effectiveDays }),
-    previous: prior
-      ? {
-          turns: prior.turns,
-          tokens: tokensOf(prior),
-          costUsd: round(prior.costUsd, 6),
-        }
-      : null,
-    daily,
-    providers,
-    coverage: exportCoverage(state, historyPending),
-  };
-}
+export * from '../session-runtime/services/usage-stats-model.mjs';