@uptimizr/db 2.0.1 → 2.1.0

package/dist/insights/anomalies.js

@@ -0,0 +1,340 @@
+/**
+ * **`anomalies`** — "when did this go wrong, and what inside it went wrong?"
+ * (ADR 0051 §4, design sketch §D row `anomalies`).
+ *
+ * `baseline` says what normal looks like and `movers` says that something
+ * changed between two windows a caller had to choose. Neither names **a
+ * bucket**. This primitive walks one metric's bucket series and returns the
+ * buckets that do not belong in it, each labelled with what kind of departure it
+ * is and — where the metric declares a dimension it can be split by — which
+ * value inside the metric accounts for the excess.
+ *
+ * Pure, like the rest of `src/insights/`: it takes the rows `buildMetricBuckets`
+ * produced and returns rows. No store, no request, no dialect, so DuckDB,
+ * ClickHouse, Postgres and SQL Server cannot disagree about whether a Tuesday
+ * was abnormal.
+ *
+ * ## Three kinds, two detectors
+ *
+ * | `kind`  | Detector | The shape it catches |
+ * | ------- | -------- | -------------------- |
+ * | `spike` | robust z vs the trailing window | one bucket far above what came before |
+ * | `drop`  | the same, below | one bucket far below it |
+ * | `shift` | CUSUM over the whole series | a level that moved and *stayed* moved |
+ *
+ * The third is not a refinement of the first two, it is the case they
+ * structurally cannot see: a release that costs 6 FPS every day from Tuesday
+ * onward is never more than a MAD or two off on any single day, so no point
+ * detector will ever flag it, and yet it is the finding that matters most. Both
+ * detectors are driven by the *same* `sensitivity` dial and measured in the same
+ * unit (MADs of the series' own spread), so the two halves of a result are
+ * comparable rather than two unrelated alarms sharing an endpoint.
+ *
+ * ## The denominator: a scaled MAD, with a floor
+ *
+ * `sensitivity` is a **threshold**, not a ranking key, so the unit it counts has
+ * to be calibrated or the default is meaningless. The MAD of normally
+ * distributed data is about 0.674σ, so a raw `|z| > 3` on MADs is really "beyond
+ * 2σ" — a two-sided tail of roughly 4% *per bucket*, which over a 28-day window
+ * reports one or two perfectly ordinary days every time it is called. That is
+ * exactly the experience that makes people switch anomaly detection off.
+ *
+ * The spread is therefore `max(MAD × {@link MAD_TO_SIGMA}, 1% × |median|)`: the
+ * MAD rescaled into standard deviations, so `sensitivity: 3` means what a reader
+ * assumes it means, and then floored the way `movers` floors it. The floor is
+ * what stops a metric that sat at exactly 60 FPS for a fortnight — trailing MAD
+ * of 0 — from reporting a 59.9 FPS day as an infinite departure.
+ *
+ * `movers` reports the **unscaled** ratio, because there it ranks rather than
+ * thresholds and a constant factor changes no ordering. The two `z` columns
+ * therefore differ by that constant, which the registry entries both say.
+ *
+ * ## Cost is bounded, and declared
+ *
+ * The detection itself is one bucket read — the same grouped scan every insight
+ * makes. Attribution costs **at most {@link ANOMALY_MAX_CONTRIBUTOR_SCANS} extra
+ * grouped scans per request**, no matter how many buckets were anomalous:
+ * adjacent findings are merged into windows, the windows are ranked by how
+ * extreme they are, and only the top few are re-read. A metric with no declared
+ * split dimension pays for none.
+ */
+import { MIN_SPREAD_FRACTION } from "./movers.js";
+import { MAD_TO_SIGMA, median, medianAbsoluteDeviation, round } from "./stats.js";
+import { cusumChangePoints, rollingRobustStats } from "./changepoint.js";
+import { BUCKET_SECONDS, bucketMeasureFor, } from "./measures.js";
+/** Default `sensitivity`: a bucket must be more than three MADs out. */
+export const DEFAULT_ANOMALY_SENSITIVITY = 3;
+/** Smallest `sensitivity` a caller may ask for. */
+export const MIN_ANOMALY_SENSITIVITY = 1;
+/**
+ * Largest `sensitivity` a caller may ask for.
+ *
+ * Bounded at both ends on purpose. Below 1 every bucket is an anomaly and the
+ * answer is noise; above 10 nothing short of a total outage is, and a caller who
+ * wants that has asked the wrong question — they want a threshold alert, which
+ * is stage 3's `subscriptions`, not a detector.
+ */
+export const MAX_ANOMALY_SENSITIVITY = 10;
+/**
+ * How many buckets of history each bucket is judged against, per grain.
+ *
+ * A fortnight at day grain: long enough for the median to be stable, short
+ * enough that a month-old regime does not keep flagging today. A week at hour
+ * grain, which is 168 buckets — the shortest window that contains every hour of
+ * every weekday, so a quiet Sunday 03:00 is compared against a distribution that
+ * has seen quiet nights rather than against Tuesday lunchtime.
+ */
+export const ANOMALY_TRAILING_BUCKETS = {
+    day: 14,
+    hour: 168,
+};
+/**
+ * Trailing values a bucket needs before it can be judged at all.
+ *
+ * Under five, the median and the MAD are describing the accident of which four
+ * buckets happened to exist. Buckets with less history than this are reported as
+ * nothing rather than as findings — which is why a brand-new project reads
+ * "no anomalies" instead of "every day is an anomaly".
+ */
+export const ANOMALY_MIN_TRAILING = 5;
+/**
+ * The hard cap on extra grouped scans spent on attribution, per request.
+ *
+ * Contributor attribution re-reads the series grouped by one dimension over an
+ * anomalous window. Adjacent anomalous buckets are one window, and only the
+ * three most extreme windows are re-read, so the endpoint's cost is
+ * `1 + min(windows, 3)` grouped scans whatever the data looks like. A caller who
+ * wants attribution on a quieter finding narrows `since`/`until` around it; that
+ * is cheaper for the store than lifting the cap would be.
+ */
+export const ANOMALY_MAX_CONTRIBUTOR_SCANS = 3;
+/** Decimals an anomaly's numbers are rounded to before they leave the API. */
+export const ANOMALY_PRECISION = 6;
+/** Clamp a caller's `sensitivity` into the supported range. */
+export function clampSensitivity(value) {
+    if (value == null || !Number.isFinite(value))
+        return DEFAULT_ANOMALY_SENSITIVITY;
+    return Math.min(MAX_ANOMALY_SENSITIVITY, Math.max(MIN_ANOMALY_SENSITIVITY, value));
+}
+/**
+ * The dimension `anomalies` would attribute this metric's excess to, or `null`.
+ *
+ * `null` for a metric that declares none, and also for a `scene`-split metric on
+ * a request that is already scoped to one scene: the split would return a single
+ * value with a share of 1, which is not an explanation, and the scan that
+ * produced it would be wasted.
+ */
+export function contributorDimensionFor(metric, opts = {}) {
+    const splitBy = bucketMeasureFor(metric)?.splitBy;
+    if (splitBy == null)
+        return null;
+    if (splitBy === "scene" && opts.scene != null && opts.scene.length > 0)
+        return null;
+    return splitBy;
+}
+/**
+ * The spread a departure is measured in: the MAD rescaled to a standard
+ * deviation ({@link MAD_TO_SIGMA}), floored at {@link MIN_SPREAD_FRACTION} of the
+ * level. `null` when there is no spread to speak of.
+ *
+ * The rescaling is what makes `sensitivity` a calibrated dial (see the module
+ * doc); the floor is `movers`' own, so a flat window behaves identically in both
+ * primitives.
+ */
+function flooredSpread(centre, mad) {
+    if (centre == null || mad == null || !Number.isFinite(mad))
+        return null;
+    return Math.max(mad * MAD_TO_SIGMA, Math.abs(centre) * MIN_SPREAD_FRACTION);
+}
+/** A finite, bucket-ordered series from the store's rows. */
+function seriesOf(rows) {
+    return [...rows]
+        .filter((row) => row.value != null && Number.isFinite(row.value))
+        .sort((a, b) => a.bucket - b.bucket)
+        .map((row) => ({
+        bucket: row.bucket,
+        value: row.value,
+        sample: Number.isFinite(row.sample_size) ? row.sample_size : 0,
+    }));
+}
+/**
+ * Score one metric's bucket series and return its anomalous buckets, ordered by
+ * bucket, `contributor` still `null`.
+ *
+ * Point findings come first in time order, then the change-points, and a bucket
+ * that is both a spike and the start of a shift is reported twice — deliberately:
+ * "Tuesday was the worst day" and "Tuesday is when it stopped recovering" are two
+ * different facts, and collapsing them loses the second one.
+ */
+export function detectAnomalies(metric, scene, rows, opts) {
+    const series = seriesOf(rows);
+    const sensitivity = clampSensitivity(opts.sensitivity);
+    const out = [];
+    if (series.length === 0)
+        return out;
+    const values = series.map((point) => point.value);
+    // --- point detection: each bucket against the ones just before it ---------
+    const trailing = rollingRobustStats(values, ANOMALY_TRAILING_BUCKETS[opts.bucket], ANOMALY_MIN_TRAILING);
+    for (const [index, point] of series.entries()) {
+        const stats = trailing[index];
+        if (stats == null || stats.median == null)
+            continue;
+        // The same floored spread `movers` divides by, so a `z` of 4 means the same
+        // thing in both primitives — and taken from the trailing statistics already
+        // computed, so scoring a bucket stays O(1) on top of the rolling pass.
+        const spread = flooredSpread(stats.median, stats.mad);
+        if (spread == null || !(spread > 0))
+            continue;
+        const z = (point.value - stats.median) / spread;
+        if (Math.abs(z) <= sensitivity)
+            continue;
+        out.push({
+            metric,
+            scene: scene ?? "",
+            bucketStart: point.bucket,
+            value: round(point.value, ANOMALY_PRECISION),
+            expected: round(stats.median, ANOMALY_PRECISION),
+            z: round(z, ANOMALY_PRECISION),
+            kind: z > 0 ? "spike" : "drop",
+            contributor: null,
+            sampleSize: point.sample,
+        });
+    }
+    // --- change-points: a level that moved and stayed moved ------------------
+    // The spread is the whole series', so a shift's z is in the same MAD unit as a
+    // spike's; the *reference level* each segment is judged against is the level
+    // it started at, which the segmenting in `cusumChangePoints` re-estimates.
+    const spread = flooredSpread(median(values), medianAbsoluteDeviation(values));
+    for (const change of cusumChangePoints(values, spread, sensitivity, ANOMALY_TRAILING_BUCKETS[opts.bucket])) {
+        const point = series[change.index];
+        if (point == null)
+            continue;
+        out.push(shiftRow(metric, scene, point, change, spread));
+    }
+    return out.sort((a, b) => a.bucketStart - b.bucketStart || kindOrder(a.kind) - kindOrder(b.kind));
+}
+/** Point findings before the change-point that starts at the same bucket. */
+function kindOrder(kind) {
+    return kind === "shift" ? 1 : 0;
+}
+/** One `shift` row: the change-point bucket, carrying the pre and post levels. */
+function shiftRow(metric, scene, point, change, spread) {
+    const delta = change.after != null && change.before != null ? change.after - change.before : null;
+    return {
+        metric,
+        scene: scene ?? "",
+        bucketStart: point.bucket,
+        value: round(change.after, ANOMALY_PRECISION),
+        expected: round(change.before, ANOMALY_PRECISION),
+        // The size of the *level change*, in the same MAD unit as a spike's z — not
+        // the CUSUM statistic, which is an accumulation and would not be comparable.
+        z: delta == null || spread == null || !(spread > 0)
+            ? null
+            : round(delta / spread, ANOMALY_PRECISION),
+        kind: "shift",
+        contributor: null,
+        sampleSize: point.sample,
+    };
+}
+/**
+ * Merge anomalous buckets into the windows a contributor scan has to cover, most
+ * extreme first, capped at {@link ANOMALY_MAX_CONTRIBUTOR_SCANS}.
+ *
+ * Adjacent findings — a three-day outage is three rows — share one window and
+ * therefore one scan. Each window is widened backwards by the trailing length so
+ * the same scan also carries the history each split value's own "expected" is
+ * computed from; without that the attribution would compare a value against
+ * nothing and name whichever dimension happens to be biggest.
+ */
+export function contributorWindows(rows, opts) {
+    const width = BUCKET_SECONDS[opts.bucket] * 1000;
+    const trailing = ANOMALY_TRAILING_BUCKETS[opts.bucket] * width;
+    const ordered = [...rows].sort((a, b) => a.bucketStart - b.bucketStart);
+    const groups = [];
+    for (const row of ordered) {
+        const score = row.z == null ? 0 : Math.abs(row.z);
+        const last = groups[groups.length - 1];
+        // A `shift` is a statement about everything from its bucket onward, so its
+        // window runs to the end of the series; a point finding is one bucket.
+        const until = row.kind === "shift" ? opts.seriesUntil : row.bucketStart + width;
+        if (last != null && row.bucketStart <= last.until) {
+            last.until = Math.max(last.until, until);
+            last.score = Math.max(last.score, score);
+        }
+        else {
+            groups.push({ since: row.bucketStart, until, score });
+        }
+    }
+    return groups
+        .sort((a, b) => b.score - a.score || a.since - b.since)
+        .slice(0, ANOMALY_MAX_CONTRIBUTOR_SCANS)
+        .map((group) => ({ since: group.since - trailing, until: group.until }))
+        .sort((a, b) => a.since - b.since);
+}
+/** Whether an anomalous bucket falls inside a contributor window. */
+export function inContributorWindow(row, window) {
+    return row.bucketStart >= window.since && row.bucketStart < window.until;
+}
+/**
+ * Name the dimension value that accounts for one row's excess.
+ *
+ * `splitRows` are the same measure re-read grouped by `dimension` over the row's
+ * contributor window. For each value the excess is `observed − prior`, where
+ * `prior` is that value's median over the buckets *before* the finding and
+ * `observed` is its value in the anomalous bucket (or, for a `shift`, its median
+ * from the change-point onward — the same before/after comparison the row
+ * itself reports, done one dimension value at a time).
+ *
+ * The winner is the largest excess **with the same sign as the row's own**: a
+ * spike is explained by what went up, and a value that happened to fall during
+ * an error spike is not a contributor to it. `share` is that value's fraction of
+ * the summed same-signed excess, so the shares of all contributing values add to
+ * 1 and a reported share of 0.9 means what a reader thinks it means.
+ *
+ * Returns `null` when nothing can be named: no split rows, or an excess of zero,
+ * or every split value moving against the finding.
+ */
+export function attributeContributor(row, dimension, splitRows) {
+    if (row.value == null || row.expected == null)
+        return null;
+    const direction = Math.sign(row.value - row.expected);
+    if (direction === 0)
+        return null;
+    const byValue = new Map();
+    for (const split of splitRows) {
+        if (split.value == null || !Number.isFinite(split.value))
+            continue;
+        const key = split.dimension_value ?? "";
+        const list = byValue.get(key);
+        if (list == null)
+            byValue.set(key, [{ bucket: split.bucket, value: split.value }]);
+        else
+            list.push({ bucket: split.bucket, value: split.value });
+    }
+    if (byValue.size === 0)
+        return null;
+    const excesses = [];
+    for (const [key, points] of byValue) {
+        const prior = median(points.filter((p) => p.bucket < row.bucketStart).map((p) => p.value)) ?? 0;
+        const observed = row.kind === "shift"
+            ? median(points.filter((p) => p.bucket >= row.bucketStart).map((p) => p.value))
+            : (points.find((p) => p.bucket === row.bucketStart)?.value ?? null);
+        // A split value that vanished in the anomalous bucket contributes its own
+        // absence: for a drop that is the whole explanation.
+        const excess = (observed ?? 0) - prior;
+        if (Math.sign(excess) === direction)
+            excesses.push({ value: key, excess });
+    }
+    if (excesses.length === 0)
+        return null;
+    let total = 0;
+    for (const entry of excesses)
+        total += entry.excess;
+    const winner = excesses.reduce((best, entry) => Math.abs(entry.excess) > Math.abs(best.excess) ? entry : best);
+    return {
+        dimension,
+        value: winner.value,
+        share: total === 0 ? null : round(winner.excess / total, ANOMALY_PRECISION),
+    };
+}
+//# sourceMappingURL=anomalies.js.map

package/dist/insights/anomalies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"anomalies.js","sourceRoot":"","sources":["../../src/insights/anomalies.ts"],"names":[],"mappings":"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"}

package/dist/insights/baseline.d.ts

@@ -0,0 +1,51 @@
+/**
+ * **`baseline`** — "what is normal for this scene?" (ADR 0051 §4, sketch §D).
+ *
+ * Reduces a metric's per-bucket series to the handful of numbers that let a
+ * reader (or an agent) judge a single later observation without re-deriving the
+ * distribution: where the series sits (`mean`, `median`), how much it normally
+ * moves (`mad`), what its ordinary range looks like (`p10`, `p90`), and whether
+ * it is drifting (`slope`).
+ *
+ * Pure: it takes the rows `buildMetricBuckets` produced and returns one row. It
+ * never sees a store, a request or a dialect, so the same series produces the
+ * same baseline on every engine — which is the point of computing statistics in
+ * TypeScript rather than in five dialects' SQL.
+ */
+import type { MetricBucketRow } from "./buckets.js";
+/**
+ * What `baseline` reports. One row per request.
+ *
+ * Every statistic is nullable and `null` means *"not defined for this series"* —
+ * an empty window, or fewer than two buckets for a slope. A brand-new project
+ * reads `null`, never `0`.
+ */
+export interface BaselineRow {
+    /** The registry metric the series is of. */
+    metric: string;
+    /** The scene it was scoped to; `''` when the baseline spans every scene. */
+    scene: string;
+    /** How many buckets carried a value. */
+    buckets: number;
+    mean: number | null;
+    median: number | null;
+    /** Median absolute deviation — the typical bucket-to-bucket swing. */
+    mad: number | null;
+    p10: number | null;
+    p90: number | null;
+    /** Least-squares slope against the bucket index: change per bucket. */
+    slope: number | null;
+    /** Events (or sessions, for a session-valued metric) behind the whole series. */
+    sampleSize: number;
+}
+/** How many decimals a baseline statistic is rounded to before it leaves the API. */
+export declare const BASELINE_PRECISION = 6;
+/**
+ * Reduce a bucket series to its baseline.
+ *
+ * Buckets whose `value` is `null` (an aggregate over no rows) are excluded from
+ * every statistic but still counted in `sampleSize`, because their events did
+ * happen — they simply did not produce a value for this measure.
+ */
+export declare function computeBaseline(metric: string, scene: string | undefined, rows: readonly MetricBucketRow[]): BaselineRow;
+//# sourceMappingURL=baseline.d.ts.map

package/dist/insights/baseline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseline.d.ts","sourceRoot":"","sources":["../../src/insights/baseline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAUH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,sEAAsE;IACtE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,uEAAuE;IACvE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,iFAAiF;IACjF,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,qFAAqF;AACrF,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,IAAI,EAAE,SAAS,eAAe,EAAE,GAC/B,WAAW,CAsBb"}

package/dist/insights/baseline.js

@@ -0,0 +1,48 @@
+/**
+ * **`baseline`** — "what is normal for this scene?" (ADR 0051 §4, sketch §D).
+ *
+ * Reduces a metric's per-bucket series to the handful of numbers that let a
+ * reader (or an agent) judge a single later observation without re-deriving the
+ * distribution: where the series sits (`mean`, `median`), how much it normally
+ * moves (`mad`), what its ordinary range looks like (`p10`, `p90`), and whether
+ * it is drifting (`slope`).
+ *
+ * Pure: it takes the rows `buildMetricBuckets` produced and returns one row. It
+ * never sees a store, a request or a dialect, so the same series produces the
+ * same baseline on every engine — which is the point of computing statistics in
+ * TypeScript rather than in five dialects' SQL.
+ */
+import { leastSquaresSlope, mean, median, medianAbsoluteDeviation, quantile, round, } from "./stats.js";
+/** How many decimals a baseline statistic is rounded to before it leaves the API. */
+export const BASELINE_PRECISION = 6;
+/**
+ * Reduce a bucket series to its baseline.
+ *
+ * Buckets whose `value` is `null` (an aggregate over no rows) are excluded from
+ * every statistic but still counted in `sampleSize`, because their events did
+ * happen — they simply did not produce a value for this measure.
+ */
+export function computeBaseline(metric, scene, rows) {
+    const values = [];
+    let sampleSize = 0;
+    // Ordered by bucket, so the slope is a slope against *time* rather than
+    // against whatever order the driver happened to return rows in.
+    for (const row of [...rows].sort((a, b) => a.bucket - b.bucket)) {
+        sampleSize += Number.isFinite(row.sample_size) ? row.sample_size : 0;
+        if (row.value != null && Number.isFinite(row.value))
+            values.push(row.value);
+    }
+    return {
+        metric,
+        scene: scene ?? "",
+        buckets: values.length,
+        mean: round(mean(values), BASELINE_PRECISION),
+        median: round(median(values), BASELINE_PRECISION),
+        mad: round(medianAbsoluteDeviation(values), BASELINE_PRECISION),
+        p10: round(quantile(values, 0.1), BASELINE_PRECISION),
+        p90: round(quantile(values, 0.9), BASELINE_PRECISION),
+        slope: round(leastSquaresSlope(values), BASELINE_PRECISION),
+        sampleSize,
+    };
+}
+//# sourceMappingURL=baseline.js.map

package/dist/insights/baseline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseline.js","sourceRoot":"","sources":["../../src/insights/baseline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,iBAAiB,EACjB,IAAI,EACJ,MAAM,EACN,uBAAuB,EACvB,QAAQ,EACR,KAAK,GACN,MAAM,YAAY,CAAC;AA6BpB,qFAAqF;AACrF,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC;AAEpC;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAC7B,MAAc,EACd,KAAyB,EACzB,IAAgC;IAEhC,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,wEAAwE;IACxE,gEAAgE;IAChE,KAAK,MAAM,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;QAChE,UAAU,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;QACrE,IAAI,GAAG,CAAC,KAAK,IAAI,IAAI,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC;YAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAC9E,CAAC;IAED,OAAO;QACL,MAAM;QACN,KAAK,EAAE,KAAK,IAAI,EAAE;QAClB,OAAO,EAAE,MAAM,CAAC,MAAM;QACtB,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,kBAAkB,CAAC;QAC7C,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,kBAAkB,CAAC;QACjD,GAAG,EAAE,KAAK,CAAC,uBAAuB,CAAC,MAAM,CAAC,EAAE,kBAAkB,CAAC;QAC/D,GAAG,EAAE,KAAK,CAAC,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,kBAAkB,CAAC;QACrD,GAAG,EAAE,KAAK,CAAC,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,kBAAkB,CAAC;QACrD,KAAK,EAAE,KAAK,CAAC,iBAAiB,CAAC,MAAM,CAAC,EAAE,kBAAkB,CAAC;QAC3D,UAAU;KACX,CAAC;AACJ,CAAC"}

package/dist/insights/buckets.d.ts

@@ -0,0 +1,114 @@
+/**
+ * **The one generic bucket query** behind both insight primitives
+ * (ADR 0051 §4, design sketch §D).
+ *
+ * `buildMetricBuckets` renders a {@link BucketMeasure} — the declarative
+ * description of how a comparable metric's primary column is reproduced per
+ * time bucket, from `measures.ts` — into a single grouped scan of `events`:
+ *
+ * ```sql
+ * SELECT <time bucket> AS bucket, <aggregate> AS value, <denominator> AS sample_size
+ * FROM events
+ * WHERE project_id = ? AND event_type IN (…) AND …
+ * GROUP BY bucket ORDER BY bucket ASC
+ * ```
+ *
+ * It is authored against the {@link Dialect} interface like every aggregation in
+ * `query/aggregations.ts`, and parity-tested on all four engines through
+ * `src/parity/cases.ts`. It deliberately does **not** live in
+ * `query/aggregations.ts`: the `build*` exports of that module are the registry's
+ * closed list of *metrics*, each of which must have its own registry entry and
+ * endpoint. This is not a metric — it is the shared input of two, and has no
+ * endpoint, no row schema and no tool of its own. Keeping it here keeps the
+ * registry's coverage invariant meaningful.
+ *
+ * No statistic is computed in SQL. The query returns raw per-bucket values and
+ * everything else — mean, median, MAD, quantiles, slope, robust z — is pure
+ * TypeScript in `stats.ts`, so no two engines can disagree about an insight.
+ */
+import type { Dialect } from "../query/dialect.js";
+import type { QuerySpec, RangeOptions, SceneOptions } from "../query/types.js";
+import { type BucketGrain, type BucketSplitDimension, type BucketVariant } from "./measures.js";
+/** What to bucket, over what window, for whom. */
+export interface MetricBucketOptions extends RangeOptions, SceneOptions {
+    /** The registry metric whose primary column the series reproduces. */
+    metric: string;
+    /** Time grain; defaults to `day`. */
+    bucket?: BucketGrain;
+    /**
+     * Split the series by one promoted dimension — the measure's own
+     * {@link BucketMeasure.splitBy}, never a caller-supplied column.
+     *
+     * With it, each row additionally carries `dimension_value` and the grouped
+     * scan answers "which mesh / channel / source accounts for this bucket?" in
+     * one extra read rather than one read per candidate value. Without it the
+     * query, its rows and its cost are exactly what they were before (#305).
+     */
+    groupBy?: BucketSplitDimension;
+    /**
+     * Read one of the metric’s **named auxiliary series** instead of its headline
+     * one (the rate denominator, an FPS tail, … — see `measures.ts`, #307).
+     *
+     * Never caller input: `significance` and `scene_health` set it from the
+     * registry and from their own fixed factor catalog respectively, so the value
+     * is always one of a compile-time union.
+     *
+     * Named `series` rather than `variant` because `variant` is already an
+     * aggregation option elsewhere (the variant-leaderboard's custom-event
+     * predicate), and the store-parity harness builds every aggregation from one
+     * shared option bag: two unrelated meanings under one key would silently
+     * cross over.
+     */
+    series?: BucketVariant;
+}
+/**
+ * One bucket of a metric's series, as the store returns it.
+ *
+ * `value` is nullable because an aggregate over no matching rows is SQL-`NULL`
+ * (a bucket in which a `quantile` had nothing to rank), and `null` must reach
+ * the statistics as "no observation" rather than as `0`. Buckets with no
+ * matching events at all are simply absent — the series is sparse, and
+ * `baseline`/`movers` treat absence as absence.
+ */
+export interface MetricBucketRow {
+    /** Bucket start, epoch milliseconds (UTC, aligned to the grain). */
+    bucket: number;
+    /** The metric's primary column for this bucket, or `null` when undefined. */
+    value: number | null;
+    /** The denominator behind `value` — what `minSample` is compared against. */
+    sample_size: number;
+    /**
+     * The split dimension's value for this row, present only on a grouped read
+     * (`groupBy`). `''` is the store's "unknown"/unattributed, exactly as it is
+     * in every other aggregation.
+     */
+    dimension_value?: string;
+}
+/**
+ * Build the per-bucket series of a metric's comparable primary column.
+ *
+ * Throws when the metric has no portable bucket form — the route validates
+ * against `BUCKETABLE_METRIC_IDS` at the edge and answers `400`, so reaching
+ * this is a programming error rather than bad input.
+ */
+export declare function buildMetricBuckets(projectId: string, opts: MetricBucketOptions, d: Dialect): QuerySpec;
+/**
+ * Total order over bucket rows: by bucket, then by the split value on a grouped
+ * read (#306).
+ *
+ * Compared by code point rather than `localeCompare`, so the order is a property
+ * of the data instead of the ICU build the collector happens to run on — the same
+ * reason every statistic in this directory is computed in TypeScript.
+ */
+export declare function byBucketThenDimension(a: MetricBucketRow, b: MetricBucketRow): number;
+/**
+ * Normalise driver output into a {@link MetricBucketRow}.
+ *
+ * `buildMetricBuckets` produces no registry metric, so it carries no
+ * `QuerySpec.metric` tag and the store-edge coercion (ADR 0051 §2) has no row
+ * schema to coerce it against. ClickHouse string-encodes 64-bit counts over
+ * HTTP, so the numbers are parsed here instead — the one place every store's
+ * bucket read passes through.
+ */
+export declare function toMetricBucketRows(rows: readonly Record<string, unknown>[]): MetricBucketRow[];
+//# sourceMappingURL=buckets.d.ts.map

package/dist/insights/buckets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buckets.d.ts","sourceRoot":"","sources":["../../src/insights/buckets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAEnD,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC/E,OAAO,EAKL,KAAK,WAAW,EAGhB,KAAK,oBAAoB,EAEzB,KAAK,aAAa,EACnB,MAAM,eAAe,CAAC;AAEvB,kDAAkD;AAClD,MAAM,WAAW,mBAAoB,SAAQ,YAAY,EAAE,YAAY;IACrE,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,MAAM,CAAC,EAAE,WAAW,CAAC;IAErB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,oBAAoB,CAAC;IAE/B;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,6EAA6E;IAC7E,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAkGD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,mBAAmB,EACzB,CAAC,EAAE,OAAO,GACT,SAAS,CA0CX;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,eAAe,EAAE,CAAC,EAAE,eAAe,GAAG,MAAM,CAKpF;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,eAAe,EAAE,CAmB9F"}