@vimoxshah/tokenflow 1.1.0

package/src/analytics/insights.js

@@ -0,0 +1,283 @@
+/**
+ * Insight generation.
+ *
+ * Every insight is derived from the slice at render time. Nothing here is a
+ * template with a number dropped in — each generator computes its own
+ * condition and simply produces no insight when the condition isn't met or
+ * when the supporting sample is too small. That is why the panel can be empty:
+ * an empty insight panel is the honest output for a thin slice.
+ */
+import { compact, pct, signedPct, shortDate, hourWindow } from '../core/units.js';
+import { previousPeriod } from './comparison.js';
+import { filterCube, groupRows, sumRows, daysBetween } from './aggregate.js';
+import { interfaceClass } from '../core/schema.js';
+
+const MIN_DAYS_FOR_TREND = 14;
+const MIN_REQUESTS = 20;
+
+/**
+ * @param {object} c context
+ * @param {object} c.ix cube index
+ * @param {any[]} c.rows filtered rows
+ * @param {object} c.totals
+ * @param {any[]} c.series daily series
+ * @param {any[]} c.sessions
+ * @param {object} c.filters
+ * @param {{from:string,to:string}} c.range
+ * @param {object} c.hourly
+ * @param {object} c.peaks
+ * @param {object} c.composition
+ * @param {object} c.trend
+ * @param {object} [c.correlations]
+ * @param {object} [c.cost]
+ * @returns {{icon:string,text:string,kind:string,weight:number}[]}
+ */
+export function generateInsights(c) {
+  const out = [];
+  const add = (icon, text, kind, weight) => out.push({ icon, text, kind, weight });
+  const { ix, rows, totals, series, sessions, range, hourly, peaks, composition, trend } = c;
+  const activeDays = series.filter((d) => d.tokenActive).length;
+
+  if (!rows.length || totals.req < 1) {
+    return [{ icon: 'ℹ', text: 'No usage records match the current filters.', kind: 'empty', weight: 0 }];
+  }
+
+  // ---- trend -------------------------------------------------------------
+  if (trend && trend.change !== null && activeDays >= MIN_DAYS_FOR_TREND) {
+    const up = trend.change > 0;
+    add(
+      up ? '📈' : '📉',
+      `Token usage ${up ? 'increased' : 'decreased'} ${signedPct(trend.change)} over the last ${trend.window} days versus the ${trend.window} before.`,
+      'trend',
+      Math.abs(trend.change) * 100,
+    );
+  }
+
+  // ---- peak --------------------------------------------------------------
+  if (peaks?.peakDay) {
+    const median = series.filter((d) => d.tokenActive).map((d) => d.total).sort((a, b) => a - b)[Math.floor(activeDays / 2)] || 0;
+    const times = median ? peaks.peakDay.total / median : null;
+    add(
+      '🔥',
+      `Highest usage day was ${shortDate(peaks.peakDay.date)} at ${compact(peaks.peakDay.total)} tokens` +
+        (times && times > 1.5 ? ` — ${times.toFixed(1)}× a typical active day.` : '.'),
+      'peak',
+      60,
+    );
+  }
+
+  // ---- provider concentration -------------------------------------------
+  const byProvider = [...groupRows(rows, ix, (r) => r[ix.d.p]).values()].sort((a, b) => b.m.total - a.m.total);
+  if (byProvider.length && totals.total > 0) {
+    const top = byProvider[0];
+    add(
+      '🤖',
+      byProvider.length === 1
+        ? `All measured usage in this slice went to one provider: ${label(top.key)}.`
+        : `${label(top.key)} accounts for ${pct(top.m.total / totals.total)} of tokens across ${byProvider.length} providers.`,
+      'provider',
+      50,
+    );
+  }
+
+  // ---- interface shift ---------------------------------------------------
+  const shift = interfaceShift(c);
+  if (shift) {
+    add('💻', shift, 'interface', 55);
+  }
+
+  // ---- cache -------------------------------------------------------------
+  if (composition?.cacheRatio !== null && composition?.cacheRatio !== undefined) {
+    const hit = composition.cacheHitRate;
+    add(
+      '⚡',
+      `Cache was ${pct(composition.cacheRatio)} of all token activity` +
+        (hit !== null ? `, and ${pct(hit)} of prompt tokens were served from cache rather than re-sent.` : '.'),
+      'cache',
+      45,
+    );
+  }
+
+  // ---- output vs prompt --------------------------------------------------
+  if (composition?.outputPerPromptToken) {
+    const r = composition.outputPerPromptToken;
+    const per = 1 / r;
+    add(
+      '🧮',
+      `Every generated token costs about ${per >= 10 ? Math.round(per) : per.toFixed(1)} prompt tokens sent (output is ${pct(r)} of all token activity` +
+        (composition.outputPerInput !== null ? `; output/fresh-input ratio ${composition.outputPerInput.toFixed(2)}` : '') +
+        `) — this usage is ${r < 0.1 ? 'strongly prompt-heavy' : r < 0.25 ? 'prompt-heavy' : 'output-heavy'}.`,
+      'composition',
+      35,
+    );
+  }
+  if (composition?.reasoningShareOfOutput > 0.05) {
+    add('🧠', `Reasoning accounted for ${pct(composition.reasoningShareOfOutput)} of generated tokens.`, 'composition', 30);
+  }
+
+  // ---- time of day -------------------------------------------------------
+  if (hourly?.peakWindow && hourly.peakWindow.share > 0.15) {
+    const w = hourly.peakWindow;
+    let text = `Your busiest window is ${hourWindow(w.from, w.to)} (${pct(w.share)} of tokens).`;
+    if (hourly.secondaryWindow && hourly.secondaryWindow.share > 0.1) {
+      text += ` A second peak sits at ${hourWindow(hourly.secondaryWindow.from, hourly.secondaryWindow.to)}.`;
+    }
+    add(hourly.peakWindow.from >= 18 || hourly.peakWindow.from < 6 ? '🌙' : '☀️', text, 'hour', 40);
+  }
+
+  // ---- weekend behaviour -------------------------------------------------
+  const weekend = series.filter((d) => d.tokenActive && [5, 6].includes(dow(d.date)));
+  if (activeDays >= 14) {
+    if (weekend.length === 0) {
+      add('📅', 'No weekend usage at all in this period — your AI use is entirely on weekdays.', 'rhythm', 25);
+    } else if (weekend.length / activeDays > 0.25) {
+      add('📅', `${pct(weekend.length / activeDays)} of your active days were weekends.`, 'rhythm', 25);
+    }
+  }
+
+  // ---- model migration ---------------------------------------------------
+  for (const m of modelMigrations(c)) add('🔄', m.text, 'migration', m.weight);
+
+  // ---- new / dropped providers ------------------------------------------
+  for (const t of newOrStopped(c)) add(t.icon, t.text, 'change', t.weight);
+
+  // ---- sessions ----------------------------------------------------------
+  if (sessions.length >= 10 && activeDays > 0) {
+    const perDay = sessions.length / activeDays;
+    add('🧵', `${sessions.length.toLocaleString('en-US')} sessions over ${activeDays} active days — ${perDay.toFixed(1)} per day, ${compact(totals.total / sessions.length)} tokens each.`, 'sessions', 20);
+  }
+
+  // ---- data-honesty notes -----------------------------------------------
+  const naRate = totals.req ? totals.naAny / (totals.req * 4) : 0;
+  if (naRate > 0.05) {
+    add('⚠', `${pct(naRate)} of token fields in this slice were not reported by their source; those gaps are excluded from totals rather than counted as zero.`, 'quality', 15);
+  }
+
+  // ---- cost --------------------------------------------------------------
+  if (c.cost) {
+    if (c.cost.estimated !== null && c.cost.coverage !== null && c.cost.coverage > 0.5) {
+      add('💵', `Estimated spend ${money(c.cost.estimated)} (${pct(c.cost.coverage)} of requests priced) — about ${money(c.cost.perMillionTokens)} per million tokens.`, 'cost', 33);
+    } else if (c.cost.unpriced?.length) {
+      const top = c.cost.unpriced[0];
+      add('💵', `Cost is not shown because ${c.cost.unpriced.length} model(s) have no configured price — the largest is ${top.model} at ${compact(top.total)} tokens. Add pricing to enable cost analysis.`, 'cost', 33);
+    }
+    if (c.cost.measured !== null && c.cost.estimated !== null) {
+      const d = c.cost.estimated ? (c.cost.measured - c.cost.estimated) / c.cost.estimated : null;
+      if (d !== null && Math.abs(d) > 0.1) {
+        add('🔍', `Gateway-measured cost differs from the price-table estimate by ${signedPct(d)} — the measured figure covers only proxy-routed traffic.`, 'cost', 28);
+      }
+    }
+  }
+
+  // ---- correlation ------------------------------------------------------
+  if (c.correlations?.available) {
+    const top = c.correlations.metrics[0];
+    add(
+      '🔗',
+      `Daily AI usage and ${metricLabel(top.metric)} show a ${top.strength} ${top.direction} correlation (r = ${top.r.toFixed(2)}, n = ${top.n} days). Correlation only — not evidence that one caused the other.`,
+      'correlation',
+      48,
+    );
+  }
+
+  out.sort((a, b) => b.weight - a.weight);
+  return out;
+}
+
+// ---------------------------------------------------------------- helpers ---
+
+function interfaceShift(c) {
+  const { ix, filters, range, totals } = c;
+  if (!range?.from || !range?.to) return null;
+  const len = daysBetween(range.from, range.to) + 1;
+  if (len < MIN_DAYS_FOR_TREND * 2) return null;
+  const prev = previousPeriod(range.from, range.to);
+  const share = (from, to) => {
+    const rows = filterCube(ix, { ...filters, from, to });
+    let cli = 0, all = 0;
+    for (const r of rows) {
+      const t = r[ix.m.in] + r[ix.m.out] + r[ix.m.cr] + r[ix.m.cw];
+      all += t;
+      if (interfaceClass(r[ix.d.i]) === 'CLI / headless') cli += t;
+    }
+    return { share: all ? cli / all : null, total: all };
+  };
+  const now = share(range.from, range.to);
+  const before = share(prev.from, prev.to);
+  if (now.share === null || before.share === null || before.total < 1000) return null;
+  const diff = now.share - before.share;
+  if (Math.abs(diff) < 0.05) return null;
+  return `CLI / headless usage moved from ${pct(before.share)} to ${pct(now.share)} of tokens versus the previous ${len} days.`;
+}
+
+function modelMigrations(c) {
+  const { ix, filters, range } = c;
+  const out = [];
+  if (!range?.from || !range?.to) return out;
+  const len = daysBetween(range.from, range.to) + 1;
+  if (len < MIN_DAYS_FOR_TREND * 2) return out;
+  const prev = previousPeriod(range.from, range.to);
+  const totalsOf = (from, to) => {
+    const rows = filterCube(ix, { ...filters, from, to });
+    const g = groupRows(rows, ix, (r) => r[ix.d.m]);
+    const all = [...g.values()].reduce((a, x) => a + x.m.total, 0);
+    return { g, all };
+  };
+  const a = totalsOf(prev.from, prev.to);
+  const b = totalsOf(range.from, range.to);
+  if (!a.all || !b.all) return out;
+  const keys = new Set([...a.g.keys(), ...b.g.keys()]);
+  const moves = [];
+  for (const k of keys) {
+    const sa = (a.g.get(k)?.m.total ?? 0) / a.all;
+    const sb = (b.g.get(k)?.m.total ?? 0) / b.all;
+    if (Math.abs(sb - sa) < 0.08) continue;
+    moves.push({ model: k, from: sa, to: sb, diff: sb - sa });
+  }
+  moves.sort((x, y) => Math.abs(y.diff) - Math.abs(x.diff));
+  const risers = moves.filter((m) => m.diff > 0).slice(0, 1);
+  const fallers = moves.filter((m) => m.diff < 0).slice(0, 1);
+  if (risers.length && fallers.length) {
+    out.push({
+      text: `Model mix is shifting: ${fallers[0].model} fell from ${pct(fallers[0].from)} to ${pct(fallers[0].to)} of tokens while ${risers[0].model} rose from ${pct(risers[0].from)} to ${pct(risers[0].to)}.`,
+      weight: 52,
+    });
+  } else if (risers.length) {
+    out.push({ text: `${risers[0].model} grew from ${pct(risers[0].from)} to ${pct(risers[0].to)} of tokens versus the previous period.`, weight: 44 });
+  }
+  return out;
+}
+
+function newOrStopped(c) {
+  const { ix, filters, range } = c;
+  const out = [];
+  if (!range?.from || !range?.to) return out;
+  const len = daysBetween(range.from, range.to) + 1;
+  if (len < 7) return out;
+  const prev = previousPeriod(range.from, range.to);
+  const keysOf = (from, to, dim) => new Set(filterCube(ix, { ...filters, from, to }).map((r) => r[ix.d[dim]]));
+  for (const [dim, noun] of [['p', 'provider'], ['c', 'client']]) {
+    const before = keysOf(prev.from, prev.to, dim);
+    const now = keysOf(range.from, range.to, dim);
+    const added = [...now].filter((k) => !before.has(k));
+    const gone = [...before].filter((k) => !now.has(k));
+    if (before.size && added.length) out.push({ icon: '✨', text: `New ${noun}${added.length > 1 ? 's' : ''} this period: ${added.map(label).join(', ')}.`, weight: 42 });
+    if (before.size && gone.length) out.push({ icon: '🚪', text: `No usage this period from ${noun}${gone.length > 1 ? 's' : ''} you used before: ${gone.map(label).join(', ')}.`, weight: 38 });
+  }
+  return out;
+}
+
+function metricLabel(k) {
+  return { commits: 'git commits', insertions: 'lines added', files: 'files changed', aiLines: 'AI-authored lines', edits: 'AI edit events' }[k] || k;
+}
+function label(s) {
+  return String(s).replace(/^\w/, (m) => m.toUpperCase());
+}
+function money(n) {
+  if (n === null || n === undefined) return '—';
+  return n < 1 ? `$${n.toFixed(3)}` : n < 1000 ? `$${n.toFixed(2)}` : `$${(n / 1000).toFixed(1)}K`;
+}
+function dow(iso) {
+  const [y, m, d] = iso.split('-').map(Number);
+  return (new Date(Date.UTC(y, m - 1, d)).getUTCDay() + 6) % 7;
+}

package/src/analytics/milestones.js

@@ -0,0 +1,91 @@
+/**
+ * Milestones — moments worth celebrating, computed from the daily series.
+ *
+ * Rules of the road:
+ *   - every milestone is a MEASURED fact about the dataset (a record broken,
+ *     a round spend threshold reached for the first time, a streak hitting a
+ *     multiple of seven), never flattery;
+ *   - ids are stable (`type:date`), so the watcher can announce exactly the
+ *     ones it has never announced before;
+ *   - quiet data produces an empty list. No participation trophies.
+ */
+import { compact } from '../core/units.js';
+
+export const COST_STEPS = [10, 25, 50, 100, 250, 500, 1000];
+export const STREAK_STEP = 7;
+
+/** @typedef {{id:string, type:'biggest_day'|'cost_threshold'|'streak', icon:string, title:string, detail:string, date:string}} Milestone */
+
+function money(n) {
+  if (n >= 1000) return `$${(n / 1000).toFixed(1)}K`;
+  return `$${n.toFixed(2)}`;
+}
+
+const isActiveDay = (d) => Boolean(d.tokenActive) || Boolean(d.active);
+
+/**
+ * @param {{key:string,total:number,cost?:number|null,tokenActive?:boolean,
+ *          active?:boolean}[]} daily calendar-complete series whose LAST entry
+ *        is today (today may still be partial)
+ * @returns {Milestone[]}
+ */
+export function detectMilestones(daily) {
+  /** @type {Milestone[]} */
+  const out = [];
+  if (!Array.isArray(daily) || daily.length < 2) return out;
+
+  const today = daily[daily.length - 1];
+  const past = daily.slice(0, -1);
+  const todayTotal = today.total || 0;
+
+  // ---- biggest measured day -------------------------------------------------
+  // Requires real history above zero so day one is not a hollow record.
+  const prevMax = past.reduce((m, d) => Math.max(m, d.total || 0), 0);
+  if (prevMax > 0 && todayTotal > prevMax) {
+    out.push({
+      id: `biggest_day:${today.key}`,
+      type: 'biggest_day',
+      icon: '🏆',
+      title: 'Biggest day yet',
+      date: today.key,
+      detail: `${compact(todayTotal)} tokens — above your previous best of ${compact(prevMax)}.`,
+    });
+  }
+
+  // ---- first-ever spend threshold ---------------------------------------------
+  const todayCost = Number(today.cost) || 0;
+  if (todayCost > 0) {
+    // Highest newly-reached step wins: a single $120 day after a $8 peak is
+    // "First $100 day", not two celebrations.
+    for (const step of [...COST_STEPS].reverse()) {
+      const crossedBefore = past.some((d) => (Number(d.cost) || 0) >= step);
+      if (!crossedBefore && todayCost >= step) {
+        out.push({
+          id: `cost_${step}:${today.key}`,
+          type: 'cost_threshold',
+          icon: '💰',
+          title: `First $${step} day`,
+          date: today.key,
+          detail: `Estimated spend reached ${money(todayCost)} today — past $${step} for the first time.`,
+        });
+        break;
+      }
+    }
+  }
+
+  // ---- consecutive active days -------------------------------------------------
+  let streak = 0;
+  for (let i = daily.length - 1; i >= 0 && isActiveDay(daily[i]); i--) streak++;
+  if (streak >= STREAK_STEP && streak % STREAK_STEP === 0) {
+    out.push({
+      id: `streak_${streak}:${today.key}`,
+      type: 'streak',
+      icon: '🔥',
+      title: `${streak}-day streak`,
+      date: today.key,
+      detail: `${streak} consecutive active days.`,
+    });
+  }
+
+  return out;
+}

package/src/analytics/peak.js

@@ -0,0 +1,106 @@
+/**
+ * Peak analysis. Every value here is an argmax over the filtered slice — there
+ * are no thresholds and nothing is hardcoded.
+ */
+import { groupRows, rank, weekStart, monthKey, finalize, zeroMeasures, addInto } from './aggregate.js';
+
+/**
+ * @param {any[][]} rows filtered cube rows
+ * @param {object} ix
+ * @param {{series?:any[], topN?:number, sessions?:any[]}} opt
+ */
+export function calculatePeakUsage(rows, ix, opt = {}) {
+  const topN = opt.topN ?? 10;
+  const byDay = rank(rows, ix, (r) => r[ix.d.d]);
+  const byWeek = rank(rows, ix, (r) => weekStart(r[ix.d.d]));
+  const byMonth = rank(rows, ix, (r) => monthKey(r[ix.d.d]));
+  const byHour = rank(rows, ix, (r) => r[ix.d.h]);
+  const byProvider = rank(rows, ix, (r) => r[ix.d.p]);
+  const byModel = rank(rows, ix, (r) => r[ix.d.m]);
+  const byInterface = rank(rows, ix, (r) => r[ix.d.i]);
+  const byProject = rank(rows, ix, (r) => r[ix.d.pj]);
+
+  const maxBy = (groups, field) => {
+    let best = null;
+    for (const g of groups) if (!best || g.m[field] > best.m[field]) best = g;
+    return best ? { key: best.key, value: best.m[field], total: best.m.total } : null;
+  };
+
+  // Lowest *active* day: a zero-token calendar gap is not a "low day".
+  const activeDays = byDay.filter((g) => g.m.req > 0 && g.m.total > 0);
+  const lowest = activeDays.length
+    ? activeDays.reduce((a, b) => (b.m.total < a.m.total ? b : a))
+    : null;
+
+  const peakSession = opt.sessions && opt.sessions.length
+    ? opt.sessions.reduce((a, b) => ((b.total || 0) > (a.total || 0) ? b : a))
+    : null;
+
+  return {
+    topDays: byDay.slice(0, topN).map((g) => ({
+      date: g.key, total: g.m.total, input: g.m.in, output: g.m.out,
+      cache: g.m.cr + g.m.cw, requests: g.m.req,
+    })),
+    peakDay: byDay[0] ? { date: byDay[0].key, total: byDay[0].m.total } : null,
+    lowestActiveDay: lowest ? { date: lowest.key, total: lowest.m.total } : null,
+    peakWeek: byWeek[0] ? { weekStart: byWeek[0].key, total: byWeek[0].m.total } : null,
+    peakMonth: byMonth[0] ? { month: byMonth[0].key, total: byMonth[0].m.total } : null,
+    peakHour: byHour[0] ? { hour: Number(byHour[0].key), total: byHour[0].m.total } : null,
+    peakProvider: byProvider[0] ? { provider: byProvider[0].key, total: byProvider[0].m.total } : null,
+    peakModel: byModel[0] ? { model: byModel[0].key, total: byModel[0].m.total } : null,
+    peakInterface: byInterface[0] ? { interface: byInterface[0].key, total: byInterface[0].m.total } : null,
+    peakProject: byProject[0] ? { project: byProject[0].key, total: byProject[0].m.total } : null,
+    highestOutputDay: maxBy(byDay, 'out'),
+    highestInputDay: maxBy(byDay, 'in'),
+    highestCacheDay: (() => {
+      let best = null;
+      for (const g of byDay) {
+        const c = g.m.cr + g.m.cw;
+        if (!best || c > best.value) best = { key: g.key, value: c, total: g.m.total };
+      }
+      return best;
+    })(),
+    busiestDayByRequests: maxBy(byDay, 'req'),
+    peakSession: peakSession
+      ? {
+        id: peakSession.id, total: peakSession.total, model: peakSession.m,
+        project: peakSession.pj, date: peakSession.d, requests: peakSession.req,
+        durationMs: peakSession.durationMs,
+      }
+      : null,
+  };
+}
+
+/** Per-day detail for the heatmap drill-down. */
+export function dayDetail(rows, ix, date, sessions = []) {
+  const dayRows = rows.filter((r) => r[ix.d.d] === date);
+  if (!dayRows.length) return null;
+  const m = finalize(dayRows.reduce((acc, r) => addInto(acc, r, ix), zeroMeasures()));
+  const top = (dim) => {
+    const g = rank(dayRows, ix, (r) => r[ix.d[dim]], { limit: 3 });
+    return g.map((x) => ({ key: x.key, total: x.m.total, share: m.total ? x.m.total / m.total : null }));
+  };
+  const daySessions = sessions.filter((s) => s.d === date);
+  return {
+    date,
+    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,
+    cost: m.costReq > 0 ? m.cost : null,
+    sessions: daySessions.length,
+    providers: top('p'),
+    models: top('m'),
+    interfaces: top('i'),
+    projects: top('pj'),
+    hours: (() => {
+      const h = Array.from({ length: 24 }, () => 0);
+      for (const r of dayRows) h[r[ix.d.h]] += r[ix.m.in] + r[ix.m.out] + r[ix.m.cr] + r[ix.m.cw];
+      return h;
+    })(),
+  };
+}

package/src/analytics/productivity.js

@@ -0,0 +1,166 @@
+/**
+ * AI activity / productivity **proxies** — and correlations, never causation.
+ *
+ * Token counts do not measure productivity. What they measure is how much
+ * model capacity a day consumed. This module therefore does two separate
+ * things and labels them differently:
+ *
+ *   1. Activity proxies — sessions, sessions/day, tokens/session, active
+ *      workdays, session length distribution. These are descriptions of
+ *      behaviour, presented as such.
+ *
+ *   2. Correlation — when an independent work signal exists (git commits,
+ *      AI-authored lines, files changed), the Pearson coefficient between it
+ *      and daily AI usage, over the OVERLAPPING days only, with n reported.
+ *      Below `minOverlap` days it returns `null` and an explanation rather
+ *      than a number, because a correlation computed on four days is not a
+ *      finding, it is decoration.
+ */
+import { dowOf } from './token-usage.js';
+
+export function calculateActivityProxies(series, sessions, totals) {
+  const active = series.filter((d) => d.tokenActive);
+  const byDay = new Map();
+  for (const s of sessions) byDay.set(s.d, (byDay.get(s.d) || 0) + 1);
+  const sessionDays = byDay.size;
+  const weekdayActive = active.filter((d) => dowOf(d.date) < 5).length;
+  const weekendActive = active.length - weekdayActive;
+  return {
+    sessions: sessions.length,
+    activeDays: active.length,
+    sessionDays,
+    sessionsPerActiveDay: sessionDays ? sessions.length / sessionDays : null,
+    tokensPerSession: sessions.length ? totals.total / sessions.length : null,
+    requestsPerSession: sessions.length ? totals.req / sessions.length : null,
+    outputPerSession: sessions.length ? totals.out / sessions.length : null,
+    weekdayActiveDays: weekdayActive,
+    weekendActiveDays: weekendActive,
+    weekendShare: active.length ? weekendActive / active.length : null,
+    projects: new Set(sessions.map((s) => s.pj)).size,
+    repositories: new Set(sessions.map((s) => s.rp)).size,
+    medianSessionsPerDay: sessionDays
+      ? [...byDay.values()].sort((a, b) => a - b)[Math.floor(sessionDays / 2)]
+      : null,
+  };
+}
+
+/**
+ * Daily work signals from the activity rollup.
+ * @param {{rows:Record<string,object>}} activity
+ * @param {{from?:string,to?:string,projects?:string[]}} [f]
+ */
+export function calculateWorkSeries(activity, f = {}) {
+  const byDay = new Map();
+  const pj = f.projects && f.projects.length ? new Set(f.projects) : null;
+  for (const a of Object.values(activity.rows || {})) {
+    if (f.from && a.d < f.from) continue;
+    if (f.to && a.d > f.to) continue;
+    if (pj && !pj.has(a.pj)) continue;
+    const e = byDay.get(a.d) || { date: a.d, commits: 0, files: 0, insertions: 0, deletions: 0, aiLines: 0, humanLines: 0, edits: 0 };
+    e.commits += a.commits || 0;
+    e.files += a.files || 0;
+    e.insertions += a.ins || 0;
+    e.deletions += a.del || 0;
+    e.aiLines += a.aiLines || 0;
+    e.humanLines += a.humanLines || 0;
+    e.edits += a.edits || 0;
+    byDay.set(a.d, e);
+  }
+  return [...byDay.values()].sort((a, b) => (a.date < b.date ? -1 : 1));
+}
+
+/** Pearson r. Returns null for degenerate input rather than 0. */
+export function pearson(xs, ys) {
+  const n = Math.min(xs.length, ys.length);
+  if (n < 3) return null;
+  let sx = 0, sy = 0;
+  for (let i = 0; i < n; i++) { sx += xs[i]; sy += ys[i]; }
+  const mx = sx / n, my = sy / n;
+  let num = 0, dx = 0, dy = 0;
+  for (let i = 0; i < n; i++) {
+    const a = xs[i] - mx, b = ys[i] - my;
+    num += a * b; dx += a * a; dy += b * b;
+    }
+  if (dx === 0 || dy === 0) return null;
+  return num / Math.sqrt(dx * dy);
+}
+
+/**
+ * @param {any[]} usageSeries output of calculateDailyUsage
+ * @param {any[]} workSeries output of calculateWorkSeries
+ * @param {{minOverlap?:number, metrics?:string[]}} [opt]
+ */
+export function calculateCorrelations(usageSeries, workSeries, opt = {}) {
+  const minOverlap = opt.minOverlap ?? 10;
+  const metrics = opt.metrics ?? ['commits', 'insertions', 'files', 'aiLines', 'edits'];
+  const usageBy = new Map(usageSeries.map((d) => [d.date, d]));
+  const workBy = new Map(workSeries.map((d) => [d.date, d]));
+  const overlap = [...workBy.keys()].filter((d) => usageBy.has(d)).sort();
+
+  const base = {
+    available: false,
+    overlapDays: overlap.length,
+    minOverlap,
+    window: overlap.length ? { from: overlap[0], to: overlap[overlap.length - 1] } : null,
+    reason: null,
+    metrics: [],
+    note: 'Correlation only. AI token usage is not a measure of productivity, and a relationship here does not imply that one caused the other.',
+  };
+
+  if (!workSeries.length) {
+    return { ...base, reason: 'No independent work signal is available. Enable the git or cursor adapter to correlate usage with shipped work.' };
+  }
+  if (overlap.length < minOverlap) {
+    return {
+      ...base,
+      reason: `Only ${overlap.length} day(s) where both AI usage and work activity were recorded — at least ${minOverlap} are needed before a correlation means anything.`,
+    };
+  }
+
+  const usage = overlap.map((d) => usageBy.get(d).total);
+  const out = [];
+  for (const key of metrics) {
+    const work = overlap.map((d) => workBy.get(d)[key] || 0);
+    if (work.every((v) => v === 0)) continue;
+    const r = pearson(usage, work);
+    if (r === null) continue;
+    out.push({
+      metric: key,
+      r,
+      strength: Math.abs(r) >= 0.7 ? 'strong' : Math.abs(r) >= 0.4 ? 'moderate' : Math.abs(r) >= 0.2 ? 'weak' : 'negligible',
+      direction: r > 0 ? 'positive' : 'negative',
+      n: overlap.length,
+      series: overlap.map((d, i) => ({ date: d, usage: usage[i], work: work[i] })),
+    });
+  }
+  out.sort((a, b) => Math.abs(b.r) - Math.abs(a.r));
+  return { ...base, available: out.length > 0, metrics: out, reason: out.length ? null : 'No work metric had enough variation to correlate.' };
+}
+
+/**
+ * Split a day set into higher- and lower-usage halves and compare the work
+ * signal between them. Reported as a difference between groups — explicitly not
+ * as "AI made you N% faster".
+ */
+export function calculateActivityContrast(usageSeries, workSeries, metric = 'insertions') {
+  const usageBy = new Map(usageSeries.map((d) => [d.date, d.total]));
+  const pairs = workSeries
+    .filter((w) => usageBy.has(w.date) && usageBy.get(w.date) > 0)
+    .map((w) => ({ date: w.date, usage: usageBy.get(w.date), work: w[metric] || 0 }));
+  if (pairs.length < 8) return null;
+  const sorted = [...pairs].sort((a, b) => a.usage - b.usage);
+  const half = Math.floor(sorted.length / 2);
+  const low = sorted.slice(0, half);
+  const high = sorted.slice(-half);
+  const avg = (a) => a.reduce((x, y) => x + y.work, 0) / a.length;
+  const lo = avg(low);
+  const hi = avg(high);
+  return {
+    metric,
+    n: pairs.length,
+    lowUsageMean: lo,
+    highUsageMean: hi,
+    difference: lo > 0 ? (hi - lo) / lo : null,
+    note: 'Days grouped by AI usage; the difference is an observed association between the two groups, not an effect of AI usage.',
+  };
+}