@vimoxshah/tokenflow 1.1.0

package/src/analytics/efficiency.js

@@ -0,0 +1,138 @@
+/**
+ * Efficiency + cost.
+ *
+ * "Efficiency" here means observable ratios, nothing more. A high
+ * output/input ratio is not automatically good and a low one is not
+ * automatically bad — the UI presents these as measurements with an
+ * explanation, not as a score.
+ */
+
+export function calculateEfficiency(totals, { sessions = 0, activeDays = 0, requests = null } = {}) {
+  const req = requests ?? totals.req;
+  const t = totals.total;
+  return {
+    outputPerInput: totals.in ? totals.out / totals.in : null,
+    outputPerPromptToken: (totals.in + totals.cr + totals.cw) ? totals.out / (totals.in + totals.cr + totals.cw) : null,
+    cacheRatio: t ? (totals.cr + totals.cw) / t : null,
+    cacheHitRate: totals.in + totals.cr ? totals.cr / (totals.in + totals.cr) : null,
+    // How many prompt tokens were re-sent fresh for every one served from
+    // cache. Above 1 means the cache is mostly missing.
+    freshPerCachedPrompt: totals.cr ? totals.in / totals.cr : null,
+    tokensPerSession: sessions ? t / sessions : null,
+    outputPerSession: sessions ? totals.out / sessions : null,
+    requestsPerSession: sessions ? req / sessions : null,
+    tokensPerActiveDay: activeDays ? t / activeDays : null,
+    tokensPerRequest: req ? t / req : null,
+    outputPerRequest: req ? totals.out / req : null,
+    reasoningShareOfOutput: totals.out ? totals.rs / totals.out : null,
+    refreshShareOfCacheWrite: totals.cw ? totals.cf / totals.cw : null,
+  };
+}
+
+/**
+ * Cost analysis with explicit coverage reporting.
+ *
+ * `coverage` is the fraction of requests in the slice whose model had a price.
+ * Presenting a total cost without it would imply a completeness that isn't
+ * there, so the UI always shows them together and lists the unpriced models
+ * by volume so the gap is actionable rather than mysterious.
+ */
+export function calculateCost(totals, { sessions = 0, activeDays = 0, unpriced = [], tiers = [], premiumTiers = [], overlayMeasured = null, overlayRequests = 0 } = {}) {
+  const covered = totals.costReq || 0;
+  const coverage = totals.req ? covered / totals.req : null;
+  const est = covered > 0 ? totals.cost : null;
+  // Measured cost comes from two places: a primary record that carried a
+  // billed amount, and an overlay source whose tokens are excluded from the
+  // totals but whose money is real. They are added together and kept strictly
+  // apart from the estimate — one is evidence, the other is arithmetic.
+  const measuredIn = totals.costMeasured > 0 ? totals.costMeasured : 0;
+  const measuredOverlay = overlayMeasured > 0 ? overlayMeasured : 0;
+  const measured = measuredIn + measuredOverlay > 0 ? measuredIn + measuredOverlay : null;
+  const premium = tiers.filter((t) => premiumTiers.includes(t.key));
+  const premiumTokens = premium.reduce((a, t) => a + t.total, 0);
+  return {
+    tiers,
+    premiumTierShare: totals.total ? premiumTokens / totals.total : null,
+    premiumTierTokens: premiumTokens,
+    premiumTierNames: premium.map((t) => t.key),
+    // Long-context premiums are a known, stated gap rather than a silent one.
+    underEstimateNote: 'Long-context premium tiers are not applied (they need a per-request prompt size plus a per-model threshold), so a long-context-heavy workload is under-estimated.',
+    estimated: est,
+    measured,
+    measuredInSlice: measuredIn || null,
+    measuredOverlay: measuredOverlay || null,
+    measuredNote: measuredOverlay
+      ? `Includes $${measuredOverlay.toFixed(2)} billed through a gateway across ${overlayRequests.toLocaleString()} request(s). Those tokens are excluded from the totals above so the client adapter's count is not doubled — the cost is not.`
+      : null,
+    basisNote: est === null && measured === null
+      ? 'No pricing configured for any model in this slice.'
+      : coverage !== null && coverage < 0.999
+        ? `Estimate covers ${(coverage * 100).toFixed(1)}% of requests; the rest have no configured price.`
+        : 'Estimate covers every request in this slice.',
+    coverage,
+    coveredRequests: covered,
+    totalRequests: totals.req,
+    perDay: est !== null && activeDays ? est / activeDays : null,
+    perSession: est !== null && sessions ? est / sessions : null,
+    perMillionTokens: est !== null && totals.total ? est / (totals.total / 1e6) : null,
+    perMillionOutput: est !== null && totals.out ? est / (totals.out / 1e6) : null,
+    unpriced,
+  };
+}
+
+/**
+ * Models with no configured price, ranked by the tokens they'd account for.
+ * This is the list the "Configure pricing" call-to-action shows.
+ */
+export function unpricedModels(rows, ix, priceLookup) {
+  const by = new Map();
+  for (const r of rows) {
+    if (r[ix.m.costReq] > 0) continue;
+    const model = r[ix.d.m];
+    const e = by.get(model) || { model, provider: r[ix.d.p], total: 0, requests: 0 };
+    e.total += r[ix.m.in] + r[ix.m.out] + r[ix.m.cr] + r[ix.m.cw];
+    e.requests += r[ix.m.req];
+    by.set(model, e);
+  }
+  const out = [...by.values()].filter((e) => e.requests > 0 && (!priceLookup || !priceLookup(e.model, e.provider)));
+  out.sort((a, b) => b.total - a.total);
+  return out;
+}
+
+/** Session shape distribution — the "long vs short session" analysis. */
+export function calculateSessionProfile(sessions) {
+  if (!sessions.length) {
+    return { count: 0, buckets: [], medianTokens: null, medianDurationMs: null, p90Tokens: null, longSessions: 0, shortSessions: 0, highOutput: 0 };
+  }
+  const tokens = sessions.map((s) => s.total || 0).sort((a, b) => a - b);
+  const durs = sessions.map((s) => s.durationMs || 0).filter((x) => x > 0).sort((a, b) => a - b);
+  const p = (arr, q) => (arr.length ? arr[Math.min(arr.length - 1, Math.floor(arr.length * q))] : null);
+  const medianTokens = p(tokens, 0.5);
+  const p90 = p(tokens, 0.9);
+  // Buckets are relative to this dataset's own distribution.
+  const edges = [p(tokens, 0.25), medianTokens, p(tokens, 0.75), p90];
+  const labels = ['Smallest 25%', '25–50%', '50–75%', '75–90%', 'Top 10%'];
+  const counts = new Array(5).fill(0);
+  const totals = new Array(5).fill(0);
+  for (const s of sessions) {
+    const t = s.total || 0;
+    let i = 0;
+    while (i < edges.length && t > edges[i]) i++;
+    counts[i]++;
+    totals[i] += t;
+  }
+  const grand = tokens.reduce((a, b) => a + b, 0);
+  return {
+    count: sessions.length,
+    medianTokens,
+    p90Tokens: p90,
+    medianDurationMs: durs.length ? durs[Math.floor(durs.length / 2)] : null,
+    buckets: labels.map((label, i) => ({
+      label, sessions: counts[i], tokens: totals[i], share: grand ? totals[i] / grand : null,
+      upperEdge: i < edges.length ? edges[i] : null,
+    })),
+    longSessions: sessions.filter((s) => (s.durationMs || 0) > 30 * 60000).length,
+    shortSessions: sessions.filter((s) => (s.durationMs || 0) > 0 && s.durationMs < 2 * 60000).length,
+    highOutput: sessions.filter((s) => medianTokens && (s.out || 0) > 2 * (medianTokens * 0.15)).length,
+  };
+}

package/src/analytics/forecast.js

@@ -0,0 +1,202 @@
+/**
+ * Forecasting.
+ *
+ * A deliberately conservative model: an ordinary least-squares trend over the
+ * most recent N calendar days, a robust (median/MAD) residual spread, and hard
+ * minimum-data gates. When there is not enough history the answer is `null`
+ * with the reason attached — never a confident-looking number built on three
+ * data points.
+ *
+ * Everything here is pure and deterministic: same series in, same forecast
+ * out. The browser, the CLI and the watch daemon all call these functions, so
+ * no surface can disagree about the future.
+ */
+import { daysBetween } from './aggregate.js';
+
+export const MIN_POINTS = 5;
+const MAD_SCALE = 1.4826; // consistency constant for normally distributed errors
+
+/** Ordinary least squares fit of y = intercept + slope * x over index pairs. */
+function ols(ys) {
+  const n = ys.length;
+  let sx = 0;
+  let sy = 0;
+  let sxx = 0;
+  let sxy = 0;
+  for (let i = 0; i < n; i++) {
+    sx += i;
+    sy += ys[i];
+    sxx += i * i;
+    sxy += i * ys[i];
+  }
+  const denom = n * sxx - sx * sx;
+  if (denom === 0) return { slope: 0, intercept: sy / n };
+  const slope = (n * sxy - sx * sy) / denom;
+  return { slope, intercept: (sy - slope * sx) / n };
+}
+
+function median(sortedAsc) {
+  if (!sortedAsc.length) return null;
+  const mid = Math.floor(sortedAsc.length / 2);
+  return sortedAsc.length % 2 ? sortedAsc[mid] : (sortedAsc[mid - 1] + sortedAsc[mid]) / 2;
+}
+
+/** Median absolute deviation scaled to a standard-deviation estimate. */
+export function robustSigma(values) {
+  if (values.length < 2) return null;
+  const med = median([...values].sort((a, b) => a - b));
+  const devs = values.map((v) => Math.abs(v - med));
+  const mad = median(devs.sort((a, b) => a - b));
+  return mad * MAD_SCALE;
+}
+
+/**
+ * Forecast the next value(s) of a daily series with a linear trend.
+ *
+ * @param {{key:string, [k:string]:any}[]} series calendar-complete daily rows
+ *   as produced by calculateDailyUsage (must be sorted by key ascending)
+ * @param {{window?:number, metric?:string, horizonDays?:number}} opt
+ * @returns {{
+ *   next: number|null, interval:[number,number]|null,
+ *   horizon: {days:number, total:number}|null,
+ *   slope:number|null, confidence:'high'|'medium'|'low'|null,
+ *   n:number, reason?:string,
+ * }} nulls when the sample is too thin; `reason` says why
+ */
+export function linearForecast(series, opt = {}) {
+  const metric = opt.metric || 'total';
+  const window = Math.max(MIN_POINTS, opt.window || 14);
+  const tail = series.slice(-window);
+  const ys = tail.map((d) => Number(d[metric])).filter((v) => Number.isFinite(v));
+
+  if (ys.length < MIN_POINTS) {
+    return {
+      next: null, interval: null, horizon: null, slope: null, confidence: null,
+      n: ys.length, reason: `${ys.length} usable day(s); need at least ${MIN_POINTS}`,
+    };
+  }
+
+  const { slope, intercept } = ols(ys);
+  const residuals = ys.map((y, i) => y - (intercept + slope * i));
+  const sigma = robustSigma(residuals) ?? 0;
+  const nextX = ys.length;
+  const predict = (x) => Math.max(0, intercept + slope * x);
+
+  // A robust sigma near zero means the model fits well but may still miss
+  // regime changes; widen slightly so "high confidence" stays honest.
+  const sigmaEff = Math.max(sigma, 1e-9);
+  const meanY = ys.reduce((a, b) => a + b, 0) / ys.length;
+  const cv = meanY > 0 ? sigma / meanY : Infinity;
+
+  const confidence = ys.length >= 10 && cv <= 0.35 && sigmaEff > 0
+    ? 'high'
+    : ys.length >= 7 && cv <= 0.8 ? 'medium' : 'low';
+
+  const horizonDays = opt.horizonDays || 7;
+  let horizonSum = 0;
+  for (let i = 1; i <= horizonDays; i++) horizonSum += predict(nextX + i - 1);
+
+  return {
+    next: predict(nextX),
+    interval: [Math.max(0, predict(nextX) - 1.96 * sigma), predict(nextX) + 1.96 * sigma],
+    horizon: { days: horizonDays, total: horizonSum },
+    slope,
+    confidence,
+    n: ys.length,
+  };
+}
+
+/**
+ * Project how the current calendar month ends.
+ *
+ * Month-to-date is measured fact; the remainder is forecast. The two are never
+ * added silently without saying which part is which.
+ *
+ * @param {{key:string, [k:string]:any}[]} daily calendar-complete series
+ * @param {string} todayIso YYYY-MM-DD
+ * @param {{metric?:string}} opt
+ */
+export function monthEndProjection(daily, todayIso, opt = {}) {
+  const metric = opt.metric || 'total';
+  const monthStart = `${todayIso.slice(0, 7)}-01`;
+  const mtd = daily.filter((d) => d.key >= monthStart && d.key <= todayIso);
+  const actualToDate = mtd.reduce((a, d) => a + (Number(d[metric]) || 0), 0);
+  const remainingDays = Math.max(
+    0,
+    daysBetween(todayIso, lastDayOfMonth(todayIso)),
+  );
+  if (mtd.length < MIN_POINTS && remainingDays > 0) {
+    return {
+      projected: null, actualToDate, remainingDays,
+      forecastRemainder: null, confidence: null,
+      reason: `${mtd.length} day(s) this month; need at least ${MIN_POINTS} to project`,
+    };
+  }
+  // The remainder comes from one call so measured and forecast can never be
+  // mixed twice, and the projection uses exactly the model whose confidence we
+  // report.
+  const fc = linearForecast(daily.filter((d) => d.key <= todayIso), { ...opt, horizonDays: remainingDays });
+  const remainder = remainingDays === 0 ? 0 : fc.horizon ? fc.horizon.total : null;
+  return {
+    projected: remainder === null ? null : actualToDate + remainder,
+    actualToDate,
+    remainingDays,
+    forecastRemainder: remainder,
+    confidence: fc.confidence,
+    perDay: fc.next,
+    reason: fc.reason,
+  };
+}
+
+/** Last calendar day of the month containing `iso`. */
+export function lastDayOfMonth(iso) {
+  const [y, m] = iso.split('-').map(Number);
+  return `${y}-${String(m).padStart(2, '0')}-${String(new Date(Date.UTC(y, m, 0)).getUTCDate()).padStart(2, '0')}`;
+}
+
+/**
+ * Hours until `remaining` is exhausted at a given burn rate.
+ *
+ * @param {{remaining:number, burnPerHour:number|null, burnPerDay?:number|null, nowMs:number}} p
+ * @returns {{hours:number|null, via:'hourly'|'daily'} | null}
+ *   null when there is nothing to exhaust or no measurable burn.
+ */
+export function exhaustionEta({ remaining, burnPerHour, burnPerDay = null, nowMs }) {
+  if (!Number.isFinite(remaining) || remaining <= 0) return null;
+  if (burnPerHour !== null && Number.isFinite(burnPerHour) && burnPerHour > 0) {
+    return { hours: remaining / burnPerHour, via: 'hourly' };
+  }
+  if (burnPerDay !== null && Number.isFinite(burnPerDay) && burnPerDay > 0) {
+    return { hours: (remaining / burnPerDay) * 24, via: 'daily' };
+  }
+  return null;
+}
+
+/**
+ * Convenience wrapper used by live status + CLI: one object describing where
+ * usage is heading.
+ *
+ * @param {{key:string, cost?:number|null, [k:string]:any}[]} daily
+ * @param {string} todayIso
+ */
+export function buildForecast(daily, todayIso) {
+  const tokens = linearForecast(daily, { metric: 'total' });
+  const costSeries = daily.some((d) => Number.isFinite(Number(d.cost)) && Number(d.cost) > 0);
+  const cost = costSeries ? linearForecast(daily, { metric: 'cost' }) : null;
+  const monthTokens = monthEndProjection(daily, todayIso, { metric: 'total' });
+  const monthCost = costSeries ? monthEndProjection(daily, todayIso, { metric: 'cost' }) : null;
+  return {
+    generatedFor: todayIso,
+    tomorrow: tokens.next,
+    tomorrowInterval: tokens.interval,
+    next7days: tokens.horizon ? tokens.horizon.total : null,
+    next7daysCost: cost?.horizon ? cost.horizon.total : null,
+    monthEnd: monthTokens.projected,
+    monthEndActualToDate: monthTokens.actualToDate,
+    monthEndCost: monthCost?.projected ?? null,
+    monthEndCostActualToDate: monthCost?.actualToDate ?? null,
+    confidence: tokens.confidence,
+    n: tokens.n,
+    reason: tokens.reason || null,
+  };
+}

package/src/analytics/index.js

@@ -0,0 +1,327 @@
+/**
+ * The analytics facade + plugin registry.
+ *
+ * `computeView(bundle, filters)` is the single entry point that turns a data
+ * bundle plus a filter state into everything a dashboard needs. The browser
+ * calls it on every filter change; the CLI calls it for `status`; the snapshot
+ * exporter calls it once. One implementation, so the numbers can never disagree
+ * between surfaces.
+ *
+ * ## Plugin model
+ *
+ * Analytics modules register themselves with `registerAnalytics({id, section,
+ * compute})`. `compute` receives the fully prepared slice and returns whatever
+ * shape it likes, exposed at `view.plugins[id]`. That is how cost, git,
+ * carbon, team, or prompt-efficiency analytics get added later without
+ * touching this file.
+ */
+import {
+  indexCube, filterCube, filterSessions, sumRows, facet, EMPTY_FILTERS,
+  weekStart, monthKey, dateRange, daysBetween, addDays,
+} from './aggregate.js';
+import {
+  calculateDailyUsage, movingAverage, calculateAverageUsage, calculateComposition,
+  calculateUsageTrend, calculateHourlyUsage, calculateDowUsage, calculateHourDow,
+  calendarLevels, calculateStreaks,
+} from './token-usage.js';
+import {
+  calculateDimensionUsage, calculateDimensionSeries, calculateDimensionGrowth,
+  calculateModelEfficiency, calculateInterfaceTrend,
+} from './dimensions.js';
+import { calculatePeakUsage, dayDetail } from './peak.js';
+import { calculateEfficiency, calculateCost, unpricedModels, calculateSessionProfile } from './efficiency.js';
+import { calculatePeriodComparison, previousPeriod } from './comparison.js';
+import { calculateActivityProxies, calculateWorkSeries, calculateCorrelations, calculateActivityContrast } from './productivity.js';
+import { generateInsights } from './insights.js';
+import { buildForecast, linearForecast, monthEndProjection, exhaustionEta } from './forecast.js';
+import { detectAnomalies, firstSeenEntities } from './anomalies.js';
+import { evaluateLimits, summarizeCapacity, normalizeLimits } from './capacity.js';
+import { buildPriceBook } from '../core/pricing.js';
+
+const plugins = new Map();
+
+/** @param {{id:string, section?:string, title?:string, compute:(slice:object)=>any}} def */
+export function registerAnalytics(def) {
+  if (!def || !def.id || typeof def.compute !== 'function') {
+    throw new Error('registerAnalytics requires { id, compute }');
+  }
+  plugins.set(def.id, { section: 'custom', title: def.id, ...def });
+  return def;
+}
+export function listAnalytics() {
+  return [...plugins.values()].map((p) => ({ id: p.id, section: p.section, title: p.title }));
+}
+export function clearAnalytics() {
+  plugins.clear();
+}
+
+export const QUICK_RANGES = [
+  { id: 'today', label: 'Today' },
+  { id: 'yesterday', label: 'Yesterday' },
+  { id: '7d', label: 'Last 7 days' },
+  { id: '30d', label: 'Last 30 days' },
+  { id: '90d', label: 'Last 90 days' },
+  { id: 'mtd', label: 'This month' },
+  { id: 'lastmonth', label: 'Last month' },
+  { id: 'all', label: 'All data' },
+  { id: 'custom', label: 'Custom' },
+];
+
+/**
+ * Resolve a quick range against the dataset's own coverage, so "last 30 days"
+ * means the last 30 days of the calendar, and "all data" means exactly what is
+ * in the store.
+ */
+export function resolveRange(id, coverage, today) {
+  const to = today || coverage.to;
+  const from = coverage.from;
+  switch (id) {
+    case 'today': return { from: to, to };
+    case 'yesterday': return { from: addDays(to, -1), to: addDays(to, -1) };
+    case '7d': return { from: addDays(to, -6), to };
+    case '30d': return { from: addDays(to, -29), to };
+    case '90d': return { from: addDays(to, -89), to };
+    case 'mtd': return { from: `${to.slice(0, 7)}-01`, to };
+    case 'lastmonth': {
+      const first = `${to.slice(0, 7)}-01`;
+      const lastMonthEnd = addDays(first, -1);
+      return { from: `${lastMonthEnd.slice(0, 7)}-01`, to: lastMonthEnd };
+    }
+    case 'all':
+    default:
+      return { from, to };
+  }
+}
+
+/**
+ * @param {{cube:object, sessions:any[], activity:object, meta?:object,
+ *          pricing?:object, limits?:object[]}} bundle
+ * @param {Partial<typeof EMPTY_FILTERS> & {granularity?:'day'|'week'|'month', compare?:{a:object,b:object}, drillDate?:string}} [filters]
+ */
+export function computeView(bundle, filters = {}) {
+  const ix = indexCube(bundle.cube);
+  const f = { ...EMPTY_FILTERS, ...filters };
+  const coverage = bundle.meta?.coverage || datasetCoverage(ix);
+  const range = {
+    from: f.from || coverage.from,
+    to: f.to || coverage.to,
+  };
+  const eff = { ...f, from: range.from, to: range.to };
+
+  const rows = filterCube(ix, eff);
+  const sessions = filterSessions(bundle.sessions || [], eff);
+  const totals = sumRows(rows, ix);
+  const granularity = filters.granularity || 'day';
+
+  const daily = calculateDailyUsage(rows, ix, { granularity: 'day', from: range.from, to: range.to });
+  const series = granularity === 'day'
+    ? daily
+    : calculateDailyUsage(rows, ix, { granularity, from: range.from, to: range.to, fill: false });
+  const bucketOf = granularity === 'week' ? weekStart : granularity === 'month' ? monthKey : (d) => d;
+  const buckets = series.map((s) => s.key);
+
+  const averages = calculateAverageUsage(daily);
+  const composition = calculateComposition(totals);
+  const trend = calculateUsageTrend(daily, 30);
+  const hourly = calculateHourlyUsage(rows, ix);
+  const dowUsage = calculateDowUsage(rows, ix, daily);
+  const hourDow = calculateHourDow(rows, ix);
+  const levels = calendarLevels(daily);
+  const streaks = calculateStreaks(daily);
+  const peaks = calculatePeakUsage(rows, ix, { series: daily, sessions, topN: 10 });
+
+  const providers = calculateDimensionUsage(rows, ix, 'p', { sessions, grandTotal: totals.total });
+  const models = calculateDimensionUsage(rows, ix, 'm', { sessions, grandTotal: totals.total });
+  const families = calculateDimensionUsage(rows, ix, 'mf', { sessions, grandTotal: totals.total });
+  const clients = calculateDimensionUsage(rows, ix, 'c', { sessions, grandTotal: totals.total });
+  const interfaces = calculateDimensionUsage(rows, ix, 'i', { sessions, grandTotal: totals.total });
+  const projects = calculateDimensionUsage(rows, ix, 'pj', { sessions, grandTotal: totals.total, limit: 25 });
+  const gateways = calculateDimensionUsage(rows, ix, 'g', { sessions, grandTotal: totals.total });
+  const tiers = calculateDimensionUsage(rows, ix, 'st', { sessions, grandTotal: totals.total });
+
+  const providerSeries = calculateDimensionSeries(rows, ix, 'p', buckets, { topN: 6, bucketOf });
+  const modelSeries = calculateDimensionSeries(rows, ix, 'm', buckets, { topN: 6, bucketOf });
+  const interfaceTrend = calculateInterfaceTrend(rows, ix, buckets, bucketOf);
+  const efficiency = calculateEfficiency(totals, { sessions: sessions.length, activeDays: averages.activeDays });
+  const sessionProfile = calculateSessionProfile(sessions);
+  const modelEfficiency = calculateModelEfficiency(rows, ix, sessions, { limit: 24 });
+
+  const book = buildPriceBook(bundle.pricing || {});
+  const unpriced = unpricedModels(rows, ix, (m, p) => book.lookup(m, p));
+  // Attach the rate provenance to each model row so the Cost page can show
+  // where every number came from rather than asserting it.
+  // Rows are decorated in place with rate provenance the dimension helper
+  // does not know about.
+  for (const m of /** @type {Record<string, any>[]} */ (models)) {
+    const entry = book.lookup(m.key, m.provider) || book.lookup(m.key, 'unknown');
+    m.priceSource = entry ? (entry.origin === 'user' ? 'your override' : entry.src) : null;
+    m.rates = entry ? { in: entry.in, out: entry.out, cacheRead: entry.cacheRead, cacheWrite: entry.cacheWrite, cacheRefresh: entry.cacheRefresh } : null;
+  }
+  // An overlay source is a gateway's own billing log: its tokens describe
+  // traffic a client adapter already counted, so they stay out of the totals —
+  // but its cost is *measured*, not estimated, and dropping it would throw away
+  // the only hard money number in the dataset. Sum it from an overlay-only
+  // slice and report it beside the estimate, never inside it.
+  const overlayRows = f.includeOverlay ? [] : filterCube(ix, { ...eff, includeOverlay: true }).filter((r) => r[ix.d.ms] === 'overlay');
+  const overlay = overlayRows.length ? sumRows(overlayRows, ix) : null;
+  const cost = calculateCost(totals, {
+    sessions: sessions.length, activeDays: averages.activeDays, unpriced, tiers,
+    // Tiers billed above the standard rate, so the UI can call them out.
+    premiumTiers: ['priority', 'fast'],
+    overlayMeasured: overlay ? (overlay.costMeasured || 0) + (overlay.cost || 0) : null,
+    overlayRequests: overlay ? overlay.req : 0,
+  });
+
+  const providerGrowth = calculateDimensionGrowth(ix, 'p', eff, range);
+  const modelGrowth = calculateDimensionGrowth(ix, 'm', eff, range);
+
+  const work = calculateWorkSeries(bundle.activity || { rows: {} }, { from: range.from, to: range.to, projects: f.project });
+  const correlations = calculateCorrelations(daily, work);
+  const contrast = calculateActivityContrast(daily, work, 'insertions');
+  const proxies = calculateActivityProxies(daily, sessions, totals);
+
+  const comparison = filters.compare
+    ? calculatePeriodComparison(ix, bundle.sessions || [], eff, filters.compare.a, filters.compare.b)
+    : null;
+
+  const drill = filters.drillDate ? dayDetail(rows, ix, filters.drillDate, sessions) : null;
+
+  // ---- forward-looking + structural intelligence --------------------------
+  // `today` is the dataset timezone's calendar today (meta), so "this month"
+  // and reset windows mean the user's local calendar, never the host's.
+  const todayIso = bundle.meta?.today || range.to;
+  const forecast = buildForecast(daily, todayIso);
+  const anomalies = detectAnomalies(daily);
+  const firstSeen = {
+    models: firstSeenEntities(ix, { today: todayIso, dim: 'm', withinDays: 7 }).slice(0, 3),
+    providers: firstSeenEntities(ix, { today: todayIso, dim: 'p', withinDays: 7 }).slice(0, 3),
+  };
+  // Capacity is evaluated against the WHOLE primary dataset on purpose: a
+  // quota window is a fact about your accounts, not about the dashboard's
+  // current filter state. Per-limit provider/model/project scoping happens
+  // inside evaluateLimits.
+  const capEval = evaluateLimits(bundle.limits || [], {
+    cube: bundle.cube,
+    today: todayIso,
+    nowMs: Date.now(),
+    tzOffsetMinutes: bundle.meta?.tzOffsetMinutes ?? 0,
+    coverageFrom: coverage.from,
+  });
+  const capacity = { ...capEval, summary: summarizeCapacity(capEval.states) };
+
+  const view = {
+    range,
+    coverage,
+    filters: eff,
+    granularity,
+    kpis: buildKpis(totals, averages, peaks, sessions, providers, models, daily),
+    totals,
+    series,
+    daily,
+    movingAverages: {
+      ma7: movingAverage(daily, 7),
+      ma30: movingAverage(daily, 30),
+    },
+    averages,
+    composition,
+    trend,
+    hourly,
+    dowUsage,
+    hourDow,
+    calendar: { days: daily, levels },
+    streaks,
+    peaks,
+    dimensions: { providers, models, families, clients, interfaces, projects, gateways, tiers },
+    stacks: { providerSeries, modelSeries, interfaceTrend },
+    growth: { providers: providerGrowth, models: modelGrowth },
+    efficiency,
+    sessionProfile,
+    modelEfficiency,
+    cost,
+    productivity: { proxies, work, correlations, contrast },
+    comparison,
+    drill,
+    forecast,
+    anomalies,
+    firstSeen,
+    capacity,
+    facets: {
+      provider: facet(ix, 'p'),
+      model: facet(ix, 'm'),
+      model_family: facet(ix, 'mf'),
+      client: facet(ix, 'c'),
+      interface: facet(ix, 'i'),
+      gateway: facet(ix, 'g'),
+      project: facet(ix, 'pj'),
+      repository: facet(ix, 'rp'),
+      service_tier: facet(ix, 'st'),
+    },
+    plugins: {},
+  };
+
+  view.insights = generateInsights({
+    ix, rows, totals, series: daily, sessions, filters: eff, range,
+    hourly, peaks, composition, trend, cost, correlations,
+  });
+
+  const slice = { ix, rows, sessions, totals, view, bundle, filters: eff, range };
+  for (const p of plugins.values()) {
+    try {
+      view.plugins[p.id] = p.compute(slice);
+    } catch (err) {
+      view.plugins[p.id] = { error: err.message };
+    }
+  }
+  return view;
+}
+
+function buildKpis(totals, averages, peaks, sessions, providers, models, daily) {
+  const activeDays = averages.activeDays;
+  return {
+    total: { value: totals.total, label: 'Total usage', unit: 'tokens', measured: true },
+    input: { value: totals.in, label: 'Input', unit: 'tokens', na: totals.naIn },
+    output: { value: totals.out, label: 'Output', unit: 'tokens', na: totals.naOut },
+    cache: { value: totals.cr + totals.cw, label: 'Cache', unit: 'tokens', na: totals.naCr + totals.naCw },
+    avgPerDay: { value: averages.perActiveDay, label: 'Avg / active day', unit: 'tokens' },
+    peak: {
+      value: peaks.peakDay?.total ?? null,
+      label: 'Peak day',
+      unit: 'tokens',
+      detail: peaks.peakDay?.date ?? null,
+    },
+    activeDays: { value: activeDays, label: 'Active days', unit: 'days', detail: `${daily.length} in range` },
+    sessions: { value: sessions.length, label: 'Sessions', unit: 'sessions' },
+    sessionsPerDay: { value: activeDays ? sessions.length / activeDays : null, label: 'Avg sessions / day', unit: '' },
+    providers: { value: providers.length, label: 'Providers', unit: '' },
+    models: { value: models.length, label: 'Models', unit: '' },
+    requests: { value: totals.req, label: 'Requests', unit: '' },
+  };
+}
+
+export function datasetCoverage(ix) {
+  let from = null;
+  let to = null;
+  for (const r of ix.rows) {
+    const d = r[ix.d.d];
+    if (from === null || d < from) from = d;
+    if (to === null || d > to) to = d;
+  }
+  return { from, to };
+}
+
+export {
+  indexCube, filterCube, filterSessions, sumRows, facet, EMPTY_FILTERS,
+  calculateDailyUsage, movingAverage, calculateAverageUsage, calculateComposition,
+  calculateUsageTrend, calculateHourlyUsage, calculateDowUsage, calculateHourDow,
+  calendarLevels, calculateStreaks,
+  calculateDimensionUsage, calculateDimensionSeries, calculateDimensionGrowth,
+  calculateModelEfficiency, calculateInterfaceTrend,
+  calculatePeakUsage, dayDetail,
+  calculateEfficiency, calculateCost, unpricedModels, calculateSessionProfile,
+  calculatePeriodComparison, previousPeriod,
+  calculateActivityProxies, calculateWorkSeries, calculateCorrelations, calculateActivityContrast,
+  generateInsights, daysBetween, addDays, dateRange, weekStart, monthKey,
+  buildForecast, linearForecast, monthEndProjection, exhaustionEta,
+  detectAnomalies, firstSeenEntities,
+  evaluateLimits, summarizeCapacity, normalizeLimits,
+};