cursedbelt-core 1.0.0

package/dist/core/analytics/range.d.ts

@@ -0,0 +1,186 @@
+/**
+ * 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 declare const RANGE_PRESETS: readonly RangePreset[];
+/** The presets with a fixed width, in order — the ordinary switcher's options. */
+export declare const FIXED_RANGE_KEYS: readonly RangeKey[];
+/** 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 declare const unitForSpan: (spanMs: number) => BucketUnit;
+export declare const rangePreset: (key: RangeKey) => RangePreset;
+export declare const HOUR_MS = 3600000;
+export declare const DAY_MS = 86400000;
+/** Local midnight at the start of `t`'s day. */
+export declare const startOfDay: (t: number) => number;
+/** Local start of `t`'s hour. */
+export declare const startOfHour: (t: number) => number;
+/** Start of the bucket `t` falls in, for either unit. */
+export declare const startOfBucket: (t: number, unit: BucketUnit) => number;
+/**
+ * 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 declare const addDays: (t: number, n: number) => number;
+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 declare function resolveRange(key: RangeKey, now: number, options?: number | ResolveRangeOptions): ResolvedRange;
+/**
+ * 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 declare function rangeLabel(range: RangeWindow): string;
+/**
+ * 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 declare function bucketize<T>(items: readonly T[], range: ResolvedRange, at: (item: T) => number, weight?: (item: T) => number): number[];
+/**
+ * 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 declare const overlapMs: (from: number, to: number, windowFrom: number, windowTo: number) => number;
+/**
+ * `[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 declare function durationExcluding(from: number, to: number, exclude: readonly {
+    from: number;
+    to: number;
+}[]): number;
+/** Median of a numeric list. `null` for empty — never 0, which is a real value. */
+export declare function median(values: readonly number[]): number | null;
+/** The `p`-th percentile (0–1), nearest-rank. `null` for empty. */
+export declare function percentile(values: readonly number[], p: number): number | null;
+/** A day key (`2026-08-13`) in LOCAL time — never `toISOString`, which is UTC. */
+export declare function dayKey(t: number): string;

package/dist/core/analytics/range.js

@@ -0,0 +1,271 @@
+/**
+ * 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.
+ */
+export const RANGE_PRESETS = [
+    {
+        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,
+    },
+];
+/** The presets with a fixed width, in order — the ordinary switcher's options. */
+export const FIXED_RANGE_KEYS = RANGE_PRESETS.filter((p) => p.key !== 'custom').map((p) => p.key);
+/**
+ * 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) => (spanMs <= 2 * DAY_MS ? 'hour' : 'day');
+export const rangePreset = (key) => 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) => {
+    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) => {
+    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, unit) => 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, n) => {
+    const d = new Date(t);
+    return new Date(d.getFullYear(), d.getMonth(), d.getDate() + n, d.getHours(), d.getMinutes(), d.getSeconds(), d.getMilliseconds()).getTime();
+};
+/**
+ * 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, now, options) {
+    const opts = 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, to, unit) {
+    const buckets = [];
+    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 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) {
+    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(items, range, at, weight = () => 1) {
+    const out = new Array(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, to, windowFrom, windowTo) => 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, to, exclude) {
+    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) {
+    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, p) {
+    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) {
+    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}`;
+}