cursedbelt-core 1.0.0

package/src/core/analytics/range.spec.ts

@@ -0,0 +1,280 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  addDays,
+  bucketize,
+  DAY_MS,
+  dayKey,
+  durationExcluding,
+  HOUR_MS,
+  median,
+  overlapMs,
+  percentile,
+  RANGE_PRESETS,
+  rangeLabel,
+  rangePreset,
+  resolveRange,
+  startOfDay,
+  startOfHour,
+  unitForSpan,
+} from './range';
+
+/** 2026-08-13 14:30 LOCAL — the tests are about local calendar behaviour. */
+const NOW = new Date(2026, 7, 13, 14, 30, 0).getTime();
+
+describe('the presets', () => {
+  test('every preset is reachable by key, and an unknown key does not throw', () => {
+    for (const p of RANGE_PRESETS) expect(rangePreset(p.key).key).toBe(p.key);
+    expect(rangePreset('nonsense' as never).key).toBe('week');
+  });
+
+  test('only the one-day range buckets by hour — 90 hourly buckets is unreadable', () => {
+    const hourly = RANGE_PRESETS.filter((p) => p.unit === 'hour');
+    expect(hourly.map((p) => p.key)).toEqual(['today']);
+  });
+
+  test('the owner\'s whole vocabulary is offered — including a year and a custom range', () => {
+    expect(RANGE_PRESETS.map((p) => p.key)).toEqual([
+      'today',
+      'week',
+      'month',
+      'quarter',
+      'year',
+      'all',
+      'custom',
+    ]);
+  });
+});
+
+describe('resolveRange — the custom range', () => {
+  const from = new Date(2026, 7, 1).getTime();
+  const to = new Date(2026, 7, 4).getTime(); // exclusive: through the end of Aug 3
+
+  test('takes the caller\'s bounds rather than deriving them from now', () => {
+    const r = resolveRange('custom', NOW, { custom: { from, to } });
+    expect(r.key).toBe('custom');
+    expect(r.from).toBe(from);
+    expect(r.to).toBe(to);
+    expect(r.buckets.map(dayKey)).toEqual(['2026-08-01', '2026-08-02', '2026-08-03', '2026-08-04']);
+  });
+
+  test('picks its bucket unit from the SPAN — hourly for a short window, daily beyond two days', () => {
+    const oneDay = resolveRange('custom', NOW, {
+      custom: { from, to: from + DAY_MS },
+    });
+    expect(oneDay.unit).toBe('hour');
+    expect(resolveRange('custom', NOW, { custom: { from, to } }).unit).toBe('day');
+    expect(unitForSpan(DAY_MS)).toBe('hour');
+    expect(unitForSpan(5 * DAY_MS)).toBe('day');
+  });
+
+  test('carries a comparable previous window of the SAME width', () => {
+    const r = resolveRange('custom', NOW, { custom: { from, to } });
+    expect(r.previous).not.toBeNull();
+    expect((r.previous as { to: number }).to).toBe(r.from);
+    expect((r.previous as { from: number; to: number }).to - (r.previous as { from: number }).from).toBe(
+      r.to - r.from,
+    );
+  });
+
+  // The failure path: a switcher can sit on Custom before two dates are picked.
+  // Throwing (or returning an empty axis) would make an ordinary interaction
+  // look like a broken dashboard.
+  test('degrades to a real window rather than throwing when the bounds are missing or backwards', () => {
+    for (const bad of [undefined, null, { from: to, to: from }, { from: Number.NaN, to }]) {
+      const r = resolveRange('custom', NOW, { custom: bad as never });
+      expect(r.key).toBe('month');
+      expect(r.buckets.length).toBeGreaterThan(0);
+    }
+  });
+
+  test('the legacy positional `earliest` argument still works', () => {
+    const earliest = NOW - 3 * DAY_MS;
+    expect(resolveRange('all', NOW, earliest).from).toBe(startOfDay(earliest));
+    expect(resolveRange('all', NOW, { earliest }).from).toBe(startOfDay(earliest));
+  });
+});
+
+describe('rangeLabel — a panel must be able to STATE its window', () => {
+  test('names the window in the reader\'s own calendar terms', () => {
+    expect(rangeLabel(resolveRange('today', NOW))).toBe('Today, since midnight');
+    expect(rangeLabel(resolveRange('week', NOW))).toBe('2026-08-07 → 2026-08-13');
+    expect(rangeLabel(resolveRange('all', NOW, NOW - 2 * DAY_MS))).toBe('All time — since 2026-08-11');
+    expect(
+      rangeLabel(
+        resolveRange('custom', NOW, {
+          custom: { from: new Date(2026, 7, 1).getTime(), to: new Date(2026, 7, 4).getTime() },
+        }),
+      ),
+    ).toBe('2026-08-01 → 2026-08-04');
+  });
+});
+
+describe('resolveRange — "today" means since midnight, not the last 24 hours', () => {
+  test('today starts at local midnight, not now-24h', () => {
+    const r = resolveRange('today', NOW);
+    expect(r.from).toBe(startOfDay(NOW));
+    expect(r.from).not.toBe(NOW - DAY_MS);
+  });
+
+  test('today has one bucket per elapsed hour, inclusive of the current partial hour', () => {
+    const r = resolveRange('today', NOW);
+    expect(r.unit).toBe('hour');
+    expect(r.buckets).toHaveLength(15); // 00:00 … 14:00
+    expect(r.buckets[0]).toBe(startOfDay(NOW));
+    expect(r.buckets.at(-1)).toBe(startOfHour(NOW));
+  });
+
+  test('a 7-day range covers 7 calendar days INCLUDING today', () => {
+    const r = resolveRange('week', NOW);
+    expect(r.buckets).toHaveLength(7);
+    expect(r.buckets.at(-1)).toBe(startOfDay(NOW));
+    expect(r.buckets[0]).toBe(addDays(startOfDay(NOW), -6));
+  });
+
+  test('the baseline window is the SAME LENGTH and sits immediately before', () => {
+    const r = resolveRange('week', NOW);
+    expect(r.previous).not.toBeNull();
+    expect(r.previous?.to).toBe(r.from);
+    expect((r.previous as { from: number }).from).toBe(r.from - (r.to - r.from));
+  });
+
+  test('"all" has NO baseline — nothing precedes everything, and zero would be a lie', () => {
+    expect(resolveRange('all', NOW, NOW - 3 * DAY_MS).previous).toBeNull();
+  });
+
+  test('"all" starts at the earliest datum', () => {
+    const earliest = new Date(2026, 6, 26, 9, 15).getTime();
+    expect(resolveRange('all', NOW, earliest).from).toBe(startOfDay(earliest));
+  });
+
+  test('"all" with no earliest datum falls back to 90 days, never to the epoch', () => {
+    const r = resolveRange('all', NOW);
+    expect(r.buckets.length).toBeLessThanOrEqual(91);
+    expect(r.from).toBeGreaterThan(NOW - 100 * DAY_MS);
+  });
+
+  test('a clock skewed into the future still yields an axis rather than an empty chart', () => {
+    const r = resolveRange('all', NOW, NOW + 5 * DAY_MS);
+    expect(r.buckets.length).toBeGreaterThan(0);
+  });
+});
+
+describe('addDays — DST, the bug nobody reproduces', () => {
+  test('crossing the US spring-forward boundary lands on the right calendar day', () => {
+    // 2026-03-08 is the US DST start. t + 86400000 lands at 01:00 on the 9th in
+    // a -06:00→-05:00 zone; addDays must still say "the 9th, same wall clock".
+    const before = new Date(2026, 2, 7, 12, 0).getTime();
+    const after = new Date(addDays(before, 2));
+    expect(after.getDate()).toBe(9);
+    expect(after.getHours()).toBe(12);
+  });
+});
+
+describe('bucketize', () => {
+  const range = resolveRange('week', NOW);
+  const at = (x: { t: number }) => x.t;
+
+  test('counts land in the right day and the output is axis-aligned', () => {
+    const today = { t: NOW - HOUR_MS };
+    const twoDaysAgo = { t: addDays(NOW, -2) };
+    const out = bucketize([today, today, twoDaysAgo], range, at);
+    expect(out).toHaveLength(range.buckets.length);
+    expect(out.at(-1)).toBe(2);
+    expect(out.at(-3)).toBe(1);
+  });
+
+  test('items outside the range are dropped, not clamped onto the edge buckets', () => {
+    const out = bucketize([{ t: addDays(NOW, -40) }, { t: NOW + DAY_MS }], range, at);
+    expect(out.reduce((a, b) => a + b, 0)).toBe(0);
+  });
+
+  test('a weight function sums magnitudes instead of counting', () => {
+    const out = bucketize([{ t: NOW }, { t: NOW }], range, at, () => 2.5);
+    expect(out.at(-1)).toBe(5);
+  });
+
+  test('a NaN timestamp is dropped rather than poisoning a bucket', () => {
+    const out = bucketize([{ t: Number.NaN }], range, at);
+    expect(out.every((v) => v === 0)).toBe(true);
+  });
+});
+
+describe('overlapMs / durationExcluding — the pause-adjusted duration', () => {
+  test('non-overlapping intervals contribute nothing', () => {
+    expect(overlapMs(0, 10, 20, 30)).toBe(0);
+  });
+
+  test('partial overlap is the intersection', () => {
+    expect(overlapMs(0, 20, 10, 30)).toBe(10);
+  });
+
+  test('a task that ran through a pause is charged only for the moving time', () => {
+    expect(durationExcluding(0, 100, [{ from: 20, to: 50 }])).toBe(70);
+  });
+
+  test('OVERLAPPING pause windows are not subtracted twice', () => {
+    // An engine pause nested inside a usage pause is the real case. A naive sum
+    // would subtract 60 from 100 and report 40.
+    expect(
+      durationExcluding(0, 100, [
+        { from: 10, to: 50 },
+        { from: 30, to: 40 },
+      ]),
+    ).toBe(60);
+  });
+
+  test('unsorted windows give the same answer as sorted ones', () => {
+    const windows = [
+      { from: 70, to: 80 },
+      { from: 10, to: 20 },
+    ];
+    expect(durationExcluding(0, 100, windows)).toBe(
+      durationExcluding(0, 100, [...windows].reverse()),
+    );
+  });
+
+  test('pauses reaching outside the interval are clipped to it', () => {
+    expect(durationExcluding(50, 100, [{ from: 0, to: 1000 }])).toBe(0);
+  });
+
+  test('a zero-length interval is zero, not negative', () => {
+    expect(durationExcluding(100, 100, [{ from: 0, to: 200 }])).toBe(0);
+    expect(durationExcluding(100, 50, [])).toBe(0);
+  });
+});
+
+describe('median / percentile', () => {
+  test('empty is null, NEVER zero — zero is a real measurement', () => {
+    expect(median([])).toBeNull();
+    expect(percentile([], 0.9)).toBeNull();
+  });
+
+  test('odd and even lengths', () => {
+    expect(median([3, 1, 2])).toBe(2);
+    expect(median([4, 1, 3, 2])).toBe(2.5);
+  });
+
+  test('p90 by nearest rank, and the extremes are addressable', () => {
+    const v = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+    expect(percentile(v, 0.9)).toBe(9);
+    expect(percentile(v, 1)).toBe(10);
+    expect(percentile(v, 0)).toBe(1);
+  });
+
+  test('the input is not mutated', () => {
+    const v = [3, 1, 2];
+    median(v);
+    expect(v).toEqual([3, 1, 2]);
+  });
+});
+
+describe('dayKey', () => {
+  test('is LOCAL, so an evening does not get filed under tomorrow', () => {
+    // 22:00 local on the 12th is the 13th in UTC for America/Chicago.
+    expect(dayKey(new Date(2026, 7, 12, 22, 0).getTime())).toBe('2026-08-12');
+  });
+
+  test('zero-pads', () => {
+    expect(dayKey(new Date(2026, 0, 5, 12, 0).getTime())).toBe('2026-01-05');
+  });
+});

package/src/core/analytics/range.ts

@@ -0,0 +1,383 @@
+/**
+ * The time-range vocabulary every analytics surface shares — the presets, the
+ * bucket size each one implies, and the bucketing itself.
+ *
+ * ── Why this is a shared primitive and not per-dashboard code ────────────────
+ * Every dashboard needs "today / this week / this month", and every one that
+ * hand-rolls it gets the same three things subtly wrong:
+ *
+ * 1. **"Today" is not "the last 24 hours."** The owner asking *"has the
+ *    orchestrator done well today?"* means since midnight in THEIR timezone,
+ *    against comparable earlier days. A rolling 24h window silently mixes last
+ *    night into this morning and makes every day look average.
+ * 2. **The bucket must follow the range.** Hourly buckets over 90 days is 2,160
+ *    points nobody can read; daily buckets over one day is a single bar. The
+ *    preset owns both, so a range change cannot leave a mismatched bucket
+ *    behind.
+ * 3. **A comparison needs a baseline of the same shape.** "42 tasks" answers
+ *    nothing. "42, against a 7-day median of 26" answers the question that was
+ *    actually asked — and the baseline has to be the same length as the range
+ *    or the comparison is meaningless.
+ *
+ * Framework-free and DOM-free on purpose: the ENGINE computes with it and the
+ * BROWSER renders with it, and they must bucket identically or a chart's x-axis
+ * disagrees with its own tooltip.
+ *
+ * ── Local days, not UTC days ────────────────────────────────────────────────
+ * Day boundaries come from the host's own calendar (`new Date(y, m, d)`), so a
+ * day is the day the reader lived through. UTC bucketing would move "today" by
+ * 5–6 hours in America/Chicago and put a normal evening's work on tomorrow.
+ * 🔴 It follows that the ENGINE must be the one to bucket (it shares the
+ * owner's timezone) — a prod box on UTC bucketing for a Chicago reader
+ * reintroduces exactly this bug.
+ */
+
+/**
+ * The preset keys. `all` is unbounded-below — it starts at the first datum.
+ *
+ * `custom` is the one key with no fixed width: it takes explicit bounds from the
+ * caller (`resolveRange(key, now, { custom })`) and picks its own bucket unit
+ * from how wide those bounds are. It exists because the owner asked for it by
+ * name — *"I want to be able to view all types of times (all time, this year,
+ * this month, weeks days, custom times, etc)"* (2026-08-13) — and because a
+ * dashboard whose narrowest question is "the last 7 days" cannot answer "what
+ * happened during that incident on the 14th".
+ */
+export type RangeKey = 'today' | 'week' | 'month' | 'quarter' | 'year' | 'all' | 'custom';
+
+/** How wide one bucket is. `day` is calendar-aligned; `hour` is clock-aligned. */
+export type BucketUnit = 'hour' | 'day';
+
+export interface RangePreset {
+  key: RangeKey;
+  /** Control label — short, because it sits in a segmented control. */
+  label: string;
+  /** What the range covers, for a tooltip or a subtitle. */
+  description: string;
+  unit: BucketUnit;
+  /**
+   * Whole days back from today, inclusive of today. `null` for `all`.
+   * `today` is 1 — itself.
+   */
+  days: number | null;
+}
+
+export const RANGE_PRESETS: readonly RangePreset[] = [
+  {
+    key: 'today',
+    label: 'Today',
+    description: 'Since midnight, by hour',
+    unit: 'hour',
+    days: 1,
+  },
+  { key: 'week', label: '7 days', description: 'The last 7 days, by day', unit: 'day', days: 7 },
+  {
+    key: 'month',
+    label: '30 days',
+    description: 'The last 30 days, by day',
+    unit: 'day',
+    days: 30,
+  },
+  {
+    key: 'quarter',
+    label: '90 days',
+    description: 'The last 90 days, by day',
+    unit: 'day',
+    days: 90,
+  },
+  {
+    key: 'year',
+    label: '1 year',
+    description: 'The last 365 days, by day',
+    unit: 'day',
+    days: 365,
+  },
+  { key: 'all', label: 'All', description: 'Everything on record, by day', unit: 'day', days: null },
+  {
+    key: 'custom',
+    label: 'Custom',
+    description: 'A range you pick',
+    unit: 'day',
+    // Not a width. `custom` is resolved from the caller's own bounds; `days` is
+    // null for the same reason `all`'s is — neither has one until it is asked.
+    days: null,
+  },
+] as const;
+
+/** The presets with a fixed width, in order — the ordinary switcher's options. */
+export const FIXED_RANGE_KEYS: readonly RangeKey[] = RANGE_PRESETS.filter(
+  (p) => p.key !== 'custom',
+).map((p) => p.key);
+
+/** Explicit bounds for the `custom` preset. `to` is exclusive, like `ResolvedRange.to`. */
+export interface CustomRangeBounds {
+  from: number;
+  to: number;
+}
+
+export interface ResolveRangeOptions {
+  /** The first datum's timestamp — bounds the `all` preset. */
+  earliest?: number;
+  /** Required by `custom`; ignored by every other key. */
+  custom?: CustomRangeBounds | null;
+}
+
+/**
+ * Pick the bucket unit for an arbitrary span. Hourly up to two days (a bucket
+ * per hour over 48h is 48 points — readable); daily past that, because 90 days
+ * of hourly buckets is 2,160 points nobody can read, which is the same argument
+ * the fixed presets make.
+ */
+export const unitForSpan = (spanMs: number): BucketUnit => (spanMs <= 2 * DAY_MS ? 'hour' : 'day');
+
+export const rangePreset = (key: RangeKey): RangePreset =>
+  RANGE_PRESETS.find((p) => p.key === key) ?? RANGE_PRESETS[1];
+
+export const HOUR_MS = 3_600_000;
+export const DAY_MS = 86_400_000;
+
+/** Local midnight at the start of `t`'s day. */
+export const startOfDay = (t: number): number => {
+  const d = new Date(t);
+  return new Date(d.getFullYear(), d.getMonth(), d.getDate()).getTime();
+};
+
+/** Local start of `t`'s hour. */
+export const startOfHour = (t: number): number => {
+  const d = new Date(t);
+  return new Date(d.getFullYear(), d.getMonth(), d.getDate(), d.getHours()).getTime();
+};
+
+/** Start of the bucket `t` falls in, for either unit. */
+export const startOfBucket = (t: number, unit: BucketUnit): number =>
+  unit === 'hour' ? startOfHour(t) : startOfDay(t);
+
+/**
+ * Add `n` calendar days, keeping the wall clock. `t + n * DAY_MS` drifts by an
+ * hour twice a year and lands on the wrong calendar day, which shows up as a
+ * duplicated or missing bar exactly once every spring and autumn — the kind of
+ * bug nobody reproduces.
+ *
+ * The time-of-day is carried through rather than normalised to midnight: every
+ * caller here passes an already-aligned value, so normalising would be
+ * invisible in this file and a trap for the first caller that does not.
+ */
+export const addDays = (t: number, n: number): number => {
+  const d = new Date(t);
+  return new Date(
+    d.getFullYear(),
+    d.getMonth(),
+    d.getDate() + n,
+    d.getHours(),
+    d.getMinutes(),
+    d.getSeconds(),
+    d.getMilliseconds(),
+  ).getTime();
+};
+
+export interface ResolvedRange {
+  key: RangeKey;
+  /** Inclusive start (epoch ms), bucket-aligned. */
+  from: number;
+  /** Exclusive end (epoch ms) — `now`, so the newest bucket is partial. */
+  to: number;
+  unit: BucketUnit;
+  /** Every bucket start in the range, oldest → newest. */
+  buckets: number[];
+  /**
+   * The comparable previous window, for a baseline. `null` for `all` (nothing
+   * precedes everything) — a caller must then say "no baseline", never zero.
+   */
+  previous: { from: number; to: number } | null;
+}
+
+/**
+ * Turn a preset into concrete bounds and bucket starts.
+ *
+ * The third argument is either the `earliest` timestamp (the original,
+ * still-supported form — `all` is bounded by the first datum, and absent one it
+ * falls back to 90 days so a caller can never ask for a bucket array reaching
+ * back to the epoch) or an options object, which is how `custom` receives its
+ * bounds.
+ *
+ * 🔴 `custom` with no bounds is NOT an error and must not throw — a switcher can
+ * legitimately be on Custom before the reader has picked two dates. It degrades
+ * to the `month` preset, which is a visible, ordinary window rather than an
+ * empty chart the reader has to diagnose.
+ */
+export function resolveRange(
+  key: RangeKey,
+  now: number,
+  options?: number | ResolveRangeOptions,
+): ResolvedRange {
+  const opts: ResolveRangeOptions =
+    typeof options === 'number' ? { earliest: options } : (options ?? {});
+
+  if (key === 'custom') {
+    const bounds = opts.custom;
+    if (!bounds || !Number.isFinite(bounds.from) || !Number.isFinite(bounds.to) || bounds.to <= bounds.from) {
+      return resolveRange('month', now, { earliest: opts.earliest });
+    }
+    const unit = unitForSpan(bounds.to - bounds.from);
+    const from = startOfBucket(bounds.from, unit);
+    const to = bounds.to;
+    const buckets = bucketStarts(from, to, unit);
+    const span = to - from;
+    return { key, from, to, unit, buckets, previous: { from: from - span, to: from } };
+  }
+
+  const preset = rangePreset(key);
+  const from =
+    preset.days === null
+      ? startOfDay(opts.earliest ?? addDays(now, -90))
+      : preset.unit === 'hour'
+        ? startOfDay(now)
+        : addDays(startOfDay(now), -(preset.days - 1));
+
+  const buckets = bucketStarts(from, now, preset.unit);
+
+  const span = now - from;
+  return {
+    key,
+    from,
+    to: now,
+    unit: preset.unit,
+    buckets,
+    previous: preset.days === null ? null : { from: from - span, to: from },
+  };
+}
+
+/** Every bucket start in `[from, to]`, oldest → newest. Never empty. */
+function bucketStarts(from: number, to: number, unit: BucketUnit): number[] {
+  const buckets: number[] = [];
+  if (unit === 'hour') {
+    for (let t = from; t <= to; t += HOUR_MS) buckets.push(t);
+  } else {
+    for (let t = from; t <= to; t = addDays(t, 1)) buckets.push(t);
+  }
+  // A guard, not a formality: a corrupt clock (or an `earliest` in the future)
+  // could otherwise produce an empty axis with no explanation.
+  if (buckets.length === 0) buckets.push(from);
+  return buckets;
+}
+
+/**
+ * The three fields it takes to STATE a window — deliberately less than a
+ * `ResolvedRange`, so a server can put the window on the wire beside an
+ * aggregate without also shipping its bucket array. Every `ResolvedRange`
+ * satisfies it.
+ */
+export type RangeWindow = Pick<ResolvedRange, 'key' | 'from' | 'to'>;
+
+/**
+ * The active window, stated in words — what a panel prints so a reader never has
+ * to infer which period a number covers.
+ *
+ * This exists because of one owner report, 2026-08-13: *"what time period are we
+ * showing. For instance 'Spend & tokens by model' doesn't say if its per this
+ * month or week"*. A figure whose window is unstated is not a smaller version of
+ * the same figure — it is unreadable, because every reasonable guess gives a
+ * different answer.
+ */
+export function rangeLabel(range: RangeWindow): string {
+  if (range.key === 'today') return 'Today, since midnight';
+  if (range.key === 'all') return `All time — since ${dayKey(range.from)}`;
+  const first = dayKey(range.from);
+  const last = dayKey(range.to);
+  return first === last ? first : `${first} → ${last}`;
+}
+
+/**
+ * Sum `weight(item)` into buckets by `at(item)`. Items outside the range are
+ * dropped — silently, because a caller passing "all events" and asking for
+ * today is the normal case, not an error.
+ *
+ * Returns one number per bucket, index-aligned with `range.buckets`, so a
+ * caller can zip it against any other series from the same range without
+ * re-deriving the axis.
+ */
+export function bucketize<T>(
+  items: readonly T[],
+  range: ResolvedRange,
+  at: (item: T) => number,
+  weight: (item: T) => number = () => 1,
+): number[] {
+  const out = new Array<number>(range.buckets.length).fill(0);
+  const index = new Map(range.buckets.map((t, i) => [t, i]));
+  for (const item of items) {
+    const t = at(item);
+    if (!Number.isFinite(t) || t < range.from || t > range.to) continue;
+    const i = index.get(startOfBucket(t, range.unit));
+    if (i !== undefined) out[i] += weight(item);
+  }
+  return out;
+}
+
+/**
+ * How much of `[from, to)` overlaps `[windowFrom, windowTo)`. The primitive
+ * behind every "…excluding the time it was paused" number: a duration is only
+ * honest once the intervals it should not be charged for are subtracted.
+ */
+export const overlapMs = (
+  from: number,
+  to: number,
+  windowFrom: number,
+  windowTo: number,
+): number => Math.max(0, Math.min(to, windowTo) - Math.max(from, windowFrom));
+
+/**
+ * `[from, to)` minus every interval in `exclude`. Used for pause-adjusted
+ * durations and for the denominator of a rate that must not count downtime.
+ *
+ * `exclude` may overlap itself and need not be sorted — overlapping pause
+ * windows (an engine pause inside a usage pause) must not subtract twice, which
+ * is the bug a naive sum produces.
+ */
+export function durationExcluding(
+  from: number,
+  to: number,
+  exclude: readonly { from: number; to: number }[],
+): number {
+  const total = Math.max(0, to - from);
+  if (total === 0 || exclude.length === 0) return total;
+
+  const clipped = exclude
+    .map((w) => ({ from: Math.max(w.from, from), to: Math.min(w.to, to) }))
+    .filter((w) => w.to > w.from)
+    .sort((a, b) => a.from - b.from);
+
+  let excluded = 0;
+  let cursor = -Infinity;
+  for (const w of clipped) {
+    const start = Math.max(w.from, cursor);
+    if (w.to > start) {
+      excluded += w.to - start;
+      cursor = w.to;
+    }
+  }
+  return Math.max(0, total - excluded);
+}
+
+/** Median of a numeric list. `null` for empty — never 0, which is a real value. */
+export function median(values: readonly number[]): number | null {
+  if (values.length === 0) return null;
+  const s = [...values].sort((a, b) => a - b);
+  const mid = s.length >> 1;
+  return s.length % 2 === 0 ? (s[mid - 1] + s[mid]) / 2 : s[mid];
+}
+
+/** The `p`-th percentile (0–1), nearest-rank. `null` for empty. */
+export function percentile(values: readonly number[], p: number): number | null {
+  if (values.length === 0) return null;
+  const s = [...values].sort((a, b) => a - b);
+  const rank = Math.ceil(Math.min(1, Math.max(0, p)) * s.length);
+  return s[Math.max(0, rank - 1)];
+}
+
+/** A day key (`2026-08-13`) in LOCAL time — never `toISOString`, which is UTC. */
+export function dayKey(t: number): string {
+  const d = new Date(t);
+  const mm = String(d.getMonth() + 1).padStart(2, '0');
+  const dd = String(d.getDate()).padStart(2, '0');
+  return `${d.getFullYear()}-${mm}-${dd}`;
+}