@vimoxshah/tokenflow 1.1.0

package/src/analytics/capacity.js

@@ -0,0 +1,278 @@
+/**
+ * Capacity planning over user-declared limits.
+ *
+ * The engine never invents vendor quota data — no screen here claims to know
+ * what Anthropic or OpenAI think your remaining balance is. Instead this module
+ * answers the question with data TokenFlow actually has: a limit you declared
+ * in config, evaluated against the measured consumption in the store.
+ *
+ * ```yaml
+ * limits:
+ *   - id: anthropic-monthly
+ *     provider: anthropic        # optional cube filters: provider | model | project
+ *     scope: month               # day | week | month
+ *     metric: tokens             # tokens | input | output | requests | cost
+ *     cap: 120000000             # tokens (or dollars when metric: cost)
+ *     warnAt: 0.8                # optional warn threshold, default 0.8
+ * ```
+ *
+ * From that it derives, per limit: consumption in the current window, percent
+ * used, remaining capacity, burn rate (today's hourly pace and the trailing
+ * 7-day average), projected exhaustion, and exactly when the window resets.
+ *
+ * Pure module: all wall-clock facts enter through arguments (`nowMs`,
+ * `tzOffsetMinutes`, `today`) so results are testable and identical across
+ * CLI, server and browser.
+ */
+import { indexCube, filterCube, sumRows, finalize, weekStart } from './aggregate.js';
+
+export const LIMIT_SCOPES = /** @type {const} */ ({ DAY: 'day', WEEK: 'week', MONTH: 'month' });
+export const LIMIT_METRICS = /** @type {const} */ ({
+  TOKENS: 'tokens', INPUT: 'input', OUTPUT: 'output', REQUESTS: 'requests', COST: 'cost',
+});
+
+/** Validate one limit definition from config. @returns {{ok:boolean, errors:string[], value?:object}} */
+export function normalizeLimit(def) {
+  const errors = [];
+  if (!def || typeof def !== 'object') return { ok: false, errors: ['limit must be an object'] };
+  const id = typeof def.id === 'string' && def.id.trim() ? def.id.trim() : null;
+  if (!id) errors.push('id is required');
+  const scope = String(def.scope || '').toLowerCase();
+  const knownScopes = /** @type {string[]} */ (Object.values(LIMIT_SCOPES));
+  if (!knownScopes.includes(scope)) {
+    errors.push(`scope must be one of ${knownScopes.join(' | ')}`);
+  }
+  const metric = String(def.metric || LIMIT_METRICS.TOKENS).toLowerCase();
+  const knownMetrics = /** @type {string[]} */ (Object.values(LIMIT_METRICS));
+  if (!knownMetrics.includes(metric)) {
+    errors.push(`metric must be one of ${knownMetrics.join(' | ')}`);
+  }
+  const cap = Number(def.cap);
+  if (!Number.isFinite(cap) || cap <= 0) errors.push('cap must be a positive number');
+  let warnAt = def.warnAt === undefined || def.warnAt === null ? 0.8 : Number(def.warnAt);
+  if (!Number.isFinite(warnAt) || warnAt <= 0 || warnAt > 1) errors.push('warnAt must be a fraction between 0 and 1');
+  for (const k of ['provider', 'model', 'project']) {
+    if (def[k] !== undefined && def[k] !== null && typeof def[k] !== 'string') {
+      errors.push(`${k} must be a string`);
+    }
+  }
+  if (errors.length) return { ok: false, errors };
+  return {
+    ok: true,
+    errors: [],
+    value: {
+      id,
+      label: typeof def.label === 'string' && def.label.trim() ? def.label.trim() : id,
+      scope,
+      metric,
+      cap,
+      warnAt,
+      provider: def.provider ?? null,
+      model: def.model ?? null,
+      project: def.project ?? null,
+    },
+  };
+}
+
+/** Validate a whole limits array. Used by config import + the settings dialog. */
+export function normalizeLimits(list) {
+  const out = [];
+  const invalid = [];
+  if (!Array.isArray(list)) return { limits: out, invalid };
+  const seen = new Set();
+  list.forEach((def, i) => {
+    const v = normalizeLimit(def);
+    if (!v.ok) { invalid.push({ index: i, id: def?.id ?? null, errors: v.errors }); return; }
+    if (seen.has(v.value.id)) {
+      invalid.push({ index: i, id: v.value.id, errors: ['duplicate id'] });
+      return;
+    }
+    seen.add(v.value.id);
+    out.push(v.value);
+  });
+  return { limits: out, invalid };
+}
+
+/**
+ * Local midnight of `iso` expressed as a UTC epoch ms, given the timezone's
+ * offset in minutes east of UTC. This is the anchor for every reset countdown:
+ * a window ends when the *user's* calendar rolls over, not the machine's.
+ */
+export function localMidnightMs(iso, tzOffsetMinutes) {
+  const [y, m, d] = iso.split('-').map(Number);
+  return Date.UTC(y, m - 1, d, 0, 0, 0) - tzOffsetMinutes * 60000;
+}
+
+function addDaysISO(iso, n) {
+  const [y, m, d] = iso.split('-').map(Number);
+  const dt = new Date(Date.UTC(y, m - 1, d + n));
+  return `${dt.getUTCFullYear()}-${String(dt.getUTCMonth() + 1).padStart(2, '0')}-${String(dt.getUTCDate()).padStart(2, '0')}`;
+}
+
+/** @param {string} scope @param {string} todayIso */
+export function windowFor(scope, todayIso) {
+  switch (scope) {
+    case LIMIT_SCOPES.DAY: return { from: todayIso, to: todayIso };
+    case LIMIT_SCOPES.WEEK: return { from: weekStart(todayIso), to: todayIso };
+    case LIMIT_SCOPES.MONTH: return { from: `${todayIso.slice(0, 7)}-01`, to: todayIso };
+    default: throw new Error(`unknown scope ${scope}`);
+  }
+}
+
+/** When the current window ends, as UTC ms + a human interval. */
+export function resetFor(scope, todayIso, tzOffsetMinutes, nowMs) {  const midnight = localMidnightMs(todayIso, tzOffsetMinutes);
+  let end;
+  if (scope === LIMIT_SCOPES.DAY) {
+    end = localMidnightMs(addDaysISO(todayIso, 1), tzOffsetMinutes);
+  } else if (scope === LIMIT_SCOPES.WEEK) {
+    end = localMidnightMs(addDaysISO(weekStart(todayIso), 7), tzOffsetMinutes);
+  } else {
+    const nextMonth = addDaysISO(`${todayIso.slice(0, 7)}-01`, 32).slice(0, 7) + '-01';
+    end = localMidnightMs(nextMonth, tzOffsetMinutes);
+  }
+  return { atMs: end, inMs: Math.max(0, end - nowMs), midnightMs: midnight };
+}
+
+/** @param {object} m @param {string} metric */
+function usedFromMeasures(m, metric) {
+  switch (metric) {
+    case LIMIT_METRICS.INPUT: return { used: m.in, unit: 'tokens' };
+    case LIMIT_METRICS.OUTPUT: return { used: m.out, unit: 'tokens' };
+    case LIMIT_METRICS.REQUESTS: return { used: m.req, unit: 'requests' };
+    case LIMIT_METRICS.COST: return { used: m.cost, unit: 'usd' };
+    case LIMIT_METRICS.TOKENS:
+    default: return { used: m.total, unit: 'tokens' };
+  }
+}
+
+/**
+ * Evaluate every configured limit against the dataset.
+ *
+ * @param {object[]} rawLimits limit definitions straight from config
+ * @param {{
+ *   cube: object, today: string, nowMs?: number, tzOffsetMinutes?: number,
+ *   coverageFrom?: string | null,
+ * }} p
+ *   `coverageFrom` (optional, YYYY-MM-DD) trims the trailing-burn denominator
+ *    when the dataset is younger than the 7-day window, so a three-day-old
+ *    store does not understate its own pace.
+ */
+export function evaluateLimits(rawLimits, p) {
+  const { limits, invalid } = normalizeLimits(rawLimits);
+  const nowMs = p.nowMs ?? Date.now();
+  const tzOff = p.tzOffsetMinutes ?? 0;
+  const states = [];
+  if (!limits.length) return { states, invalid };
+
+  const ix = indexCube(p.cube);
+  const trailingTo = addDaysISO(p.today, -1);
+  const trailingFrom = addDaysISO(p.today, -7);
+  // Quota pacing does not pause on weekends, so zeros count — but a store with
+  // less history than the window must not dilute its own burn rate with days
+  // it could not possibly have measured.
+  const effectiveFrom = p.coverageFrom && p.coverageFrom > trailingFrom ? p.coverageFrom : trailingFrom;
+  const basisDays = Math.max(1, daysInclusive(effectiveFrom, trailingTo));
+
+  for (const lim of limits) {
+    const scopeFilters = {
+      provider: lim.provider ? [lim.provider] : null,
+      model: lim.model ? [lim.model] : null,
+      project: lim.project ? [lim.project] : null,
+    };
+    const win = windowFor(lim.scope, p.today);
+    const rows = filterCube(ix, {
+      from: win.from, to: win.to, includeOverlay: false, ...scopeFilters,
+    });
+    const m = finalize(sumRows(rows, ix));
+    const { used, unit } = usedFromMeasures(m, lim.metric);
+
+    const pctUsed = lim.cap > 0 ? used / lim.cap : null;
+    let status = 'unknown';
+    if (pctUsed !== null) status = pctUsed >= 1 ? 'exceeded' : pctUsed >= lim.warnAt ? 'warn' : 'ok';
+
+    // Today's slice for the hourly burn (same filters, single day).
+    const todayRows = filterCube(ix, {
+      from: p.today, to: p.today, includeOverlay: false, ...scopeFilters,
+    });
+    const tm = finalize(sumRows(todayRows, ix));
+    const todayUsed = usedFromMeasures(tm, lim.metric).used;
+
+    const localMinutes = ((nowMs / 60000 + tzOff) % 1440 + 1440) % 1440;
+    const hoursElapsed = Math.max(localMinutes / 60, 0.25); // floor avoids a midnight divide-by-zero
+    const burnPerHour = todayUsed > 0 ? todayUsed / hoursElapsed : 0;
+
+    const trailRows = filterCube(ix, {
+      from: effectiveFrom, to: trailingTo, includeOverlay: false, ...scopeFilters,
+    });
+    const trailM = finalize(sumRows(trailRows, ix));
+    const burnPerDay = usedFromMeasures(trailM, lim.metric).used / basisDays;
+
+    const remaining = Math.max(0, lim.cap - used);
+    const eta = exhaustionFor(remaining, burnPerHour, burnPerDay);
+    const reset = resetFor(lim.scope, p.today, tzOff, nowMs);
+
+    states.push({
+      ...lim,
+      unit,
+      window: win,
+      used,
+      remaining,
+      pctUsed,
+      status,
+      requests: m.req,
+      ...(lim.metric === LIMIT_METRICS.COST
+        ? { priceCoverage: m.req ? m.costReq / m.req : null }
+        : {}),
+      burn: {
+        perHourToday: burnPerHour || null,
+        perDayTrailing: burnPerDay || null,
+        basisDays,
+      },
+      etaHours: eta ? eta.hours : null,
+      etaVia: eta ? eta.via : null,
+      resetsAtMs: reset.atMs,
+      resetsInMs: reset.inMs,
+    });
+  }
+
+  states.sort((a, b) => urgency(b) - urgency(a));
+  return { states, invalid };
+}
+
+function daysInclusive(from, to) {
+  const [y1, m1, d1] = from.split('-').map(Number);
+  const [y2, m2, d2] = to.split('-').map(Number);
+  return Math.round((Date.UTC(y2, m2 - 1, d2) - Date.UTC(y1, m1 - 1, d1)) / 86400000) + 1;
+}
+
+function exhaustionFor(remaining, burnPerHour, burnPerDay) {
+  if (!(remaining > 0)) return null;
+  if (burnPerHour > 0 && Number.isFinite(burnPerHour)) return { hours: remaining / burnPerHour, via: 'hourly' };
+  if (burnPerDay !== null && burnPerDay > 0) return { hours: (remaining / burnPerDay) * 24, via: 'daily' };
+  return null;
+}
+
+function urgency(s) {
+  if (s.status === 'exceeded') return 1000;
+  const base = (s.pctUsed ?? 0) * 100;
+  // A limit that will be crossed before its reset outranks one that will not.
+  const beforeReset = s.etaHours !== null && s.resetsInMs > 0 && s.etaHours * 3600000 <= s.resetsInMs ? 200 : 0;
+  return base + beforeReset;
+}
+
+/** Cross-limit rollup for headers and menu bars. */
+export function summarizeCapacity(states) {
+  if (!states.length) return { anyExceeded: false, anyWarn: false, worst: null, firstToHit: null };
+  const exceeded = states.filter((s) => s.status === 'exceeded');
+  const warned = states.filter((s) => s.status === 'warn');
+  const firstToHit = states
+    .filter((s) => s.status !== 'exceeded' && s.etaHours !== null && s.resetsInMs > 0 && s.etaHours * 3600000 <= s.resetsInMs)
+    .sort((a, b) => a.etaHours - b.etaHours)[0] || null;
+  return {
+    anyExceeded: exceeded.length > 0,
+    anyWarn: warned.length > 0,
+    worst: states[0],
+    firstToHit,
+    counts: { total: states.length, exceeded: exceeded.length, warn: warned.length },
+  };
+}

package/src/analytics/comparison.js

@@ -0,0 +1,96 @@
+/**
+ * Comparison mode — two arbitrary periods, side by side.
+ */
+import { filterCube, filterSessions, sumRows, groupRows, daysBetween, addDays, rank } from './aggregate.js';
+import { interfaceClass } from '../core/schema.js';
+
+/**
+ * @param {object} ix
+ * @param {any[]} sessions
+ * @param {object} filters base filters (date fields are overridden)
+ * @param {{from:string,to:string}} a
+ * @param {{from:string,to:string}} b
+ */
+export function calculatePeriodComparison(ix, sessions, filters, a, b) {
+  const side = (p) => {
+    const rows = filterCube(ix, { ...filters, from: p.from, to: p.to });
+    const m = sumRows(rows, ix);
+    const sess = filterSessions(sessions, { ...filters, from: p.from, to: p.to });
+    const days = new Set(rows.map((r) => r[ix.d.d]));
+    const cli = rows.reduce((acc, r) => {
+      const c = interfaceClass(r[ix.d.i]);
+      const t = r[ix.m.in] + r[ix.m.out] + r[ix.m.cr] + r[ix.m.cw];
+      acc.total += t;
+      if (c === 'CLI / headless') acc.cli += t;
+      return acc;
+    }, { cli: 0, total: 0 });
+    const byDay = rank(rows, ix, (r) => r[ix.d.d], { limit: 1 });
+    return {
+      period: p,
+      calendarDays: daysBetween(p.from, p.to) + 1,
+      activeDays: days.size,
+      total: m.total,
+      input: m.in,
+      output: m.out,
+      cacheRead: m.cr,
+      cacheWrite: m.cw,
+      cache: m.cr + m.cw,
+      reasoning: m.rs,
+      requests: m.req,
+      sessions: sess.length,
+      cost: m.costReq > 0 ? m.cost : null,
+      avgPerActiveDay: days.size ? m.total / days.size : null,
+      avgPerSession: sess.length ? m.total / sess.length : null,
+      providers: new Set(rows.map((r) => r[ix.d.p])).size,
+      models: new Set(rows.map((r) => r[ix.d.m])).size,
+      cliShare: cli.total ? cli.cli / cli.total : null,
+      peak: byDay[0] ? { date: byDay[0].key, total: byDay[0].m.total } : null,
+      _rows: rows,
+    };
+  };
+
+  const A = side(a);
+  const B = side(b);
+  const METRICS = [
+    ['total', 'Total usage'], ['input', 'Input'], ['output', 'Output'],
+    ['cache', 'Cache'], ['requests', 'Requests'], ['sessions', 'Sessions'],
+    ['avgPerActiveDay', 'Avg / active day'], ['avgPerSession', 'Avg / session'],
+    ['activeDays', 'Active days'], ['providers', 'Providers'], ['models', 'Models'],
+    ['cliShare', 'CLI share'], ['cost', 'Estimated cost'],
+  ];
+  const deltas = METRICS.map(([k, label]) => {
+    const av = A[k];
+    const bv = B[k];
+    const change = av === null || bv === null || av === 0 ? null : (bv - av) / av;
+    return { key: k, label, a: av, b: bv, change, kind: k === 'cliShare' ? 'share' : k === 'cost' ? 'cost' : 'count' };
+  });
+
+  // Which providers/models moved — the "what changed" part of a comparison.
+  const shift = (dim) => {
+    const ga = groupRows(A._rows, ix, (r) => r[ix.d[dim]]);
+    const gb = groupRows(B._rows, ix, (r) => r[ix.d[dim]]);
+    const keys = new Set([...ga.keys(), ...gb.keys()]);
+    const rows = [...keys].map((k) => {
+      const x = ga.get(k)?.m.total ?? 0;
+      const y = gb.get(k)?.m.total ?? 0;
+      return { key: k, a: x, b: y, change: x ? (y - x) / x : null, absolute: y - x };
+    });
+    rows.sort((p, q) => Math.abs(q.absolute) - Math.abs(p.absolute));
+    return rows;
+  };
+
+  // Compute the shifts BEFORE dropping the row references they read.
+  const providerShift = shift('p');
+  const modelShift = shift('m');
+  const interfaceShift = shift('i');
+  delete A._rows;
+  delete B._rows;
+  return { a: A, b: B, deltas, providerShift, modelShift, interfaceShift };
+}
+
+/** The previous equally-long window immediately before `from`. */
+export function previousPeriod(from, to) {
+  const len = daysBetween(from, to) + 1;
+  const prevTo = addDays(from, -1);
+  return { from: addDays(prevTo, -(len - 1)), to: prevTo };
+}

package/src/analytics/dimensions.js

@@ -0,0 +1,230 @@
+/**
+ * Per-dimension analytics: provider, model, interface, project.
+ *
+ * All four share one shape so the UI can render any of them with the same
+ * table and chart components, and so a dimension added by a future adapter
+ * needs no new analytics code.
+ */
+import { rank, groupRows, filterCube, sumRows, dateRange, daysBetween, addDays, finalize, zeroMeasures, addInto } from './aggregate.js';
+import { interfaceClass } from '../core/schema.js';
+
+/**
+ * @param {any[][]} rows
+ * @param {object} ix
+ * @param {string} dim cube dimension key: p | m | mf | c | i | g | pj | rp
+ * @param {{limit?:number, activeDays?:boolean, sessions?:any[], grandTotal?:number}} opt
+ */
+export function calculateDimensionUsage(rows, ix, dim, opt = {}) {
+  const col = ix.d[dim];
+  const groups = rank(rows, ix, (r) => r[col], { keepRows: true });
+  const grand = opt.grandTotal ?? groups.reduce((a, g) => a + g.m.total, 0);
+  const sessionsBy = new Map();
+  if (opt.sessions) {
+    // Sessions carry the same short dimension keys as the cube.
+    const KNOWN = new Set(['p', 'm', 'mf', 'c', 'i', 'g', 'pj', 'rp', 'st']);
+    const sdim = KNOWN.has(dim) ? dim : 'rp';
+    for (const s of opt.sessions) {
+      const k = s[sdim];
+      const e = sessionsBy.get(k) || { n: 0, tokens: 0, longMs: 0 };
+      e.n++;
+      e.tokens += s.total || 0;
+      e.longMs += s.durationMs || 0;
+      sessionsBy.set(k, e);
+    }
+  }
+
+  const out = groups.map((g) => {
+    const days = new Set();
+    let peakDay = null;
+    let peakTotal = -1;
+    const byDay = new Map();
+    for (const r of g.rows) {
+      const d = r[ix.d.d];
+      days.add(d);
+      const t = r[ix.m.in] + r[ix.m.out] + r[ix.m.cr] + r[ix.m.cw];
+      byDay.set(d, (byDay.get(d) || 0) + t);
+    }
+    for (const [d, t] of byDay) if (t > peakTotal) { peakTotal = t; peakDay = d; }
+    const sess = sessionsBy.get(g.key) || null;
+    return {
+      key: g.key,
+      // The dominant provider for this dimension value — needed to resolve a
+      // vendor-specific cache multiplier when pricing a model.
+      provider: g.rows.length ? g.rows[0][ix.d.p] : null,
+      total: g.m.total,
+      input: g.m.in,
+      output: g.m.out,
+      cacheRead: g.m.cr,
+      cacheWrite: g.m.cw,
+      cache: g.m.cr + g.m.cw,
+      cacheRefresh: g.m.cf,
+      reasoning: g.m.rs,
+      requests: g.m.req,
+      cost: g.m.costReq > 0 ? g.m.cost : null,
+      costMeasured: g.m.costMeasured || null,
+      costCoveredRequests: g.m.costReq,
+      activeDays: days.size,
+      avgPerActiveDay: days.size ? g.m.total / days.size : null,
+      avgPerRequest: g.m.req ? g.m.total / g.m.req : null,
+      peakDay,
+      peakDayTotal: peakTotal < 0 ? null : peakTotal,
+      sessions: sess ? sess.n : null,
+      avgPerSession: sess && sess.n ? g.m.total / sess.n : null,
+      share: grand ? g.m.total / grand : null,
+      missing: { input: g.m.naIn, output: g.m.naOut, cacheRead: g.m.naCr, cacheWrite: g.m.naCw },
+    };
+  });
+  return opt.limit ? out.slice(0, opt.limit) : out;
+}
+
+export const calculateProviderUsage = (rows, ix, opt) => calculateDimensionUsage(rows, ix, 'p', opt);
+export const calculateModelUsage = (rows, ix, opt) => calculateDimensionUsage(rows, ix, 'm', opt);
+export const calculateInterfaceUsage = (rows, ix, opt) => calculateDimensionUsage(rows, ix, 'i', opt);
+export const calculateProjectUsage = (rows, ix, opt) => calculateDimensionUsage(rows, ix, 'pj', opt);
+
+/**
+ * Stacked series per dimension value: one row per bucket, one column per
+ * top-N key, with everything else folded into "Other" — never a 9th generated
+ * colour.
+ */
+export function calculateDimensionSeries(rows, ix, dim, buckets, opt = {}) {
+  const topN = opt.topN ?? 6;
+  const keyFn = opt.bucketOf || ((d) => d);
+  const metric = opt.metric || 'tokens'; // tokens | requests | cost
+  const top = rank(rows, ix, (r) => r[ix.d[dim]], { limit: topN }).map((g) => g.key);
+  const topSet = new Set(top);
+  const byBucket = new Map();
+  const measureOf = (r) => {
+    if (metric === 'requests') return r[ix.m.req];
+    if (metric === 'cost') return r[ix.m.costReq] > 0 ? (r[ix.m.cost] || 0) : 0;
+    return r[ix.m.in] + r[ix.m.out] + r[ix.m.cr] + r[ix.m.cw];
+  };
+  for (const r of rows) {
+    const b = keyFn(r[ix.d.d]);
+    let row = byBucket.get(b);
+    if (!row) {
+      row = { key: b };
+      for (const k of top) row[k] = 0;
+      row.Other = 0;
+      byBucket.set(b, row);
+    }
+    const k = r[ix.d[dim]];
+    // Cost is only counted where it was actually computed from a rate; a
+    // request with no price contributes to the unpriced remainder, not zero.
+    if (topSet.has(k)) row[k] += measureOf(r);
+    else row.Other += measureOf(r);
+  }
+  const hasOther = [...byBucket.values()].some((r) => r.Other > 0);
+  const keys = hasOther ? [...top, 'Other'] : top;
+  const series = (buckets || [...byBucket.keys()].sort()).map((b) => {
+    const row = byBucket.get(b);
+    if (row) return row;
+    const empty = { key: b };
+    for (const k of keys) empty[k] = 0;
+    return empty;
+  });
+  return { keys, series };
+}
+
+/**
+ * Period-over-period growth per dimension value. The comparison window is the
+ * same length as the current one, immediately preceding it.
+ */
+export function calculateDimensionGrowth(ix, dim, filters, { from, to }) {
+  // An empty store has no coverage; growth against nothing is nothing.
+  if (!from || !to) {
+    return { window: { from: null, to: null }, previousWindow: { from: null, to: null }, rows: [] };
+  }
+  const days = daysBetween(from, to) + 1;
+  const prevTo = addDays(from, -1);
+  const prevFrom = addDays(prevTo, -(days - 1));
+  const cur = filterCube(ix, { ...filters, from, to });
+  const prev = filterCube(ix, { ...filters, from: prevFrom, to: prevTo });
+  const curBy = groupRows(cur, ix, (r) => r[ix.d[dim]]);
+  const prevBy = groupRows(prev, ix, (r) => r[ix.d[dim]]);
+  const keys = new Set([...curBy.keys(), ...prevBy.keys()]);
+  const out = [];
+  for (const k of keys) {
+    const c = curBy.get(k)?.m.total ?? 0;
+    const p = prevBy.get(k)?.m.total ?? 0;
+    out.push({
+      key: k,
+      current: c,
+      previous: p,
+      change: p > 0 ? (c - p) / p : null,
+      absolute: c - p,
+      status: p === 0 ? (c > 0 ? 'new' : 'none') : c === 0 ? 'stopped' : c > p ? 'up' : c < p ? 'down' : 'flat',
+    });
+  }
+  out.sort((a, b) => b.current - a.current);
+  return { window: { from, to }, previousWindow: { from: prevFrom, to: prevTo }, rows: out };
+}
+
+/**
+ * Model efficiency scatter: tokens per session (x) against sessions per active
+ * day (y), bubble = total tokens. Grouped by provider, which is why the caller
+ * caps the colour count — a scatter needs all-pairs colour separation.
+ */
+export function calculateModelEfficiency(rows, ix, sessions, { limit = 24 } = {}) {
+  const byModel = rank(rows, ix, (r) => r[ix.d.m], { keepRows: true, limit });
+  const sessByModel = new Map();
+  for (const s of sessions) {
+    const e = sessByModel.get(s.m) || { n: 0, days: new Set(), tokens: 0, durations: [] };
+    e.n++;
+    e.days.add(s.d);
+    e.tokens += s.total || 0;
+    if (s.durationMs) e.durations.push(s.durationMs);
+    sessByModel.set(s.m, e);
+  }
+  return byModel.map((g) => {
+    const s = sessByModel.get(g.key);
+    const days = new Set(g.rows.map((r) => r[ix.d.d]));
+    const provider = g.rows.length ? g.rows[0][ix.d.p] : 'unknown';
+    return {
+      model: g.key,
+      provider,
+      family: g.rows.length ? g.rows[0][ix.d.mf] : 'Unknown',
+      total: g.m.total,
+      requests: g.m.req,
+      sessions: s ? s.n : null,
+      activeDays: days.size,
+      tokensPerSession: s && s.n ? g.m.total / s.n : null,
+      sessionsPerDay: s && s.days.size ? s.n / s.days.size : null,
+      tokensPerRequest: g.m.req ? g.m.total / g.m.req : null,
+      outputPerRequest: g.m.req ? g.m.out / g.m.req : null,
+      medianSessionMs: s && s.durations.length ? median(s.durations) : null,
+    };
+  });
+}
+
+/** CLI vs GUI over time — the "how is my tooling shifting" series. */
+export function calculateInterfaceTrend(rows, ix, buckets, bucketOf = (d) => d) {
+  const classes = new Map();
+  for (const r of rows) {
+    const b = bucketOf(r[ix.d.d]);
+    const cls = interfaceClass(r[ix.d.i]);
+    let row = classes.get(b);
+    if (!row) { row = { key: b }; classes.set(b, row); }
+    row[cls] = (row[cls] || 0) + r[ix.m.in] + r[ix.m.out] + r[ix.m.cr] + r[ix.m.cw];
+  }
+  const keys = [...new Set([...classes.values()].flatMap((r) => Object.keys(r).filter((k) => k !== 'key')))];
+  const series = (buckets || [...classes.keys()].sort()).map((b) => {
+    const row = classes.get(b) || { key: b };
+    for (const k of keys) if (row[k] === undefined) row[k] = 0;
+    return row;
+  });
+  // Share-of-total per bucket, which is what makes a shift legible.
+  const shares = series.map((row) => {
+    const t = keys.reduce((a, k) => a + row[k], 0);
+    const o = { key: row.key };
+    for (const k of keys) o[k] = t ? row[k] / t : 0;
+    return o;
+  });
+  return { keys, series, shares };
+}
+
+function median(xs) {
+  const a = [...xs].sort((x, y) => x - y);
+  const m = Math.floor(a.length / 2);
+  return a.length % 2 ? a[m] : (a[m - 1] + a[m]) / 2;
+}