@uptimizr/db 2.0.0 → 2.1.0

package/dist/insights/buckets.js

@@ -0,0 +1,220 @@
+/**
+ * **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 { ParamBag, rangeClause, sceneClause } from "../query/dialect.js";
+import { BUCKET_SECONDS, BUCKET_SPLIT_COLUMNS, resolveBucketMeasure, } from "./measures.js";
+/** The SQL expression for a promoted value column, per aggregate. */
+function valueColumnExpr(column, aggregate, d) {
+    switch (column) {
+        case "fps":
+            return "fps";
+        case "visible_ms":
+            return "visible_ms";
+        case "long_frames":
+            // Promoted, `NOT NULL DEFAULT 0`, and a 0 here is a real observation — a
+            // sampled window in which no frame ran long. Unlike `js_heap_bytes` it is
+            // never nulled out: excluding the good windows would report every project
+            // as permanently janky.
+            return "long_frames";
+        case "js_heap_bytes":
+            // A heap reading of 0 means "the browser did not report one" (the column
+            // is `NOT NULL DEFAULT 0`), so averages and percentiles must exclude it —
+            // exactly what `buildResourceSummary` / `buildResourcePercentiles` do. A
+            // `max` keeps the raw column: the largest of a set that includes 0 is
+            // unaffected by it, and nulling it out would only cost a branch.
+            return aggregate === "max" ? "js_heap_bytes" : "nullIf(js_heap_bytes, 0)";
+        case "ar_placement_scale":
+            // Not promoted; read from the payload exactly as `buildArPlacementSurfaces`
+            // reads it, so the bucket series and the metric agree.
+            return d.jsonFloat("payload", "scale");
+    }
+}
+/** The `SELECT` expression that produces a bucket's value. */
+function aggregateExpr(aggregate, d) {
+    switch (aggregate.kind) {
+        case "count":
+            return "count(*)";
+        case "sessions":
+            return "count(DISTINCT session_id)";
+        case "sum":
+            return `sum(${valueColumnExpr(aggregate.column, "sum", d)})`;
+        case "avg":
+            return `avg(${valueColumnExpr(aggregate.column, "avg", d)})`;
+        case "max":
+            return `max(${valueColumnExpr(aggregate.column, "max", d)})`;
+        case "quantile":
+            return d.quantile(valueColumnExpr(aggregate.column, "quantile", d), aggregate.q);
+    }
+}
+/**
+ * The `SELECT` expression for the bucket's denominator.
+ *
+ * For a session-valued measure the denominator *is* the distinct-session count
+ * (`minSample: 30` on `view_coverage_histogram` means thirty sessions, not
+ * thirty camera samples); for every other measure it is the number of events
+ * that contributed.
+ */
+function sampleSizeExpr(aggregate) {
+    return aggregate.kind === "sessions" ? "count(DISTINCT session_id)" : "count(*)";
+}
+/** `AND event_type IN (…)`, or `""` when the measure counts every channel. */
+function eventTypeClause(bag, measure) {
+    const types = measure.eventTypes;
+    if (types.length === 0)
+        return "";
+    if (types.length === 1) {
+        return ` AND event_type = ${bag.add("bmType0", "string", types[0])}`;
+    }
+    const placeholders = types.map((type, index) => bag.add(`bmType${index}`, "string", type));
+    return ` AND event_type IN (${placeholders.join(", ")})`;
+}
+/**
+ * One extra predicate, rendered from the closed vocabulary in `measures.ts`.
+ *
+ * Column names come from a compile-time union and values are always bound as
+ * parameters, so nothing a caller can influence reaches the SQL text.
+ */
+function predicateClause(bag, d, predicate, index) {
+    switch (predicate.kind) {
+        case "eq":
+            return ` AND ${predicate.column} = ${bag.add(`bmP${index}`, "string", predicate.value)}`;
+        case "ne":
+            return ` AND ${predicate.column} <> ${bag.add(`bmP${index}`, "string", predicate.value)}`;
+        case "in": {
+            const placeholders = predicate.values.map((value, i) => bag.add(`bmP${index}_${i}`, "string", value));
+            return ` AND ${predicate.column} IN (${placeholders.join(", ")})`;
+        }
+        case "geometry":
+            return ` AND ${d.arrayLength(predicate.column)} = ${predicate.arity}`;
+    }
+}
+/**
+ * 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 function buildMetricBuckets(projectId, opts, d) {
+    const measure = resolveBucketMeasure(opts.metric, opts.series);
+    if (measure == null) {
+        throw new Error(opts.series == null
+            ? `metric '${opts.metric}' has no portable bucket series`
+            : `metric '${opts.metric}' declares no '${opts.series}' series`);
+    }
+    const bag = new ParamBag(d);
+    const pid = bag.add("projectId", "string", projectId);
+    const seconds = BUCKET_SECONDS[opts.bucket ?? "day"];
+    const interval = bag.add("bmInterval", "u32", seconds);
+    const types = eventTypeClause(bag, measure);
+    const range = rangeClause(bag, opts);
+    const scene = sceneClause(bag, opts);
+    const predicates = (measure.where ?? [])
+        .map((predicate, index) => predicateClause(bag, d, predicate, index))
+        .join("");
+    // --- anomalies (#306): the optional grouped split ------------------------
+    // The column comes from the measure's own declaration via a compile-time
+    // union, so the only way a name reaches the SQL text is by being in
+    // `BUCKET_SPLIT_COLUMNS`. The grouping key is projected, grouped and ordered
+    // by so the rows arrive in a stable order on every engine.
+    const splitColumn = opts.groupBy == null ? null : BUCKET_SPLIT_COLUMNS[opts.groupBy];
+    const splitSelect = splitColumn == null ? "" : `,\n        ${splitColumn} AS dimension_value`;
+    const splitGroup = splitColumn == null ? "" : `, ${splitColumn}`;
+    const splitOrder = splitColumn == null ? "" : `, ${splitColumn} ASC`;
+    return {
+        query: `
+      SELECT
+        ${d.timeBucketMs("ts", interval)} AS bucket,
+        ${aggregateExpr(measure.aggregate, d)} AS value,
+        ${sampleSizeExpr(measure.aggregate)} AS sample_size${splitSelect}
+      FROM events
+      WHERE project_id = ${pid}${types}${range}${scene}${predicates}
+      GROUP BY bucket${splitGroup}
+      ORDER BY bucket ASC${splitOrder}
+    `,
+        query_params: bag.values,
+    };
+}
+/**
+ * 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 function byBucketThenDimension(a, b) {
+    if (a.bucket !== b.bucket)
+        return a.bucket - b.bucket;
+    const left = a.dimension_value ?? "";
+    const right = b.dimension_value ?? "";
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+/**
+ * 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 function toMetricBucketRows(rows) {
+    const out = [];
+    for (const row of rows) {
+        const bucket = toNumber(row.bucket);
+        if (bucket == null)
+            continue;
+        out.push({
+            bucket,
+            value: toNumber(row.value),
+            sample_size: toNumber(row.sample_size) ?? 0,
+            // Present only on a grouped read (#306); a null group key is the store's
+            // "unknown", which every other aggregation also renders as `''`.
+            ...(Object.prototype.hasOwnProperty.call(row, "dimension_value")
+                ? { dimension_value: row.dimension_value == null ? "" : String(row.dimension_value) }
+                : {}),
+        });
+    }
+    // Stable on both shapes: bucket first, then the split value, so a grouped
+    // series is grouped in TypeScript in the order the engines returned it.
+    return out.sort(byBucketThenDimension);
+}
+/** A finite number from a driver cell, or `null`. */
+function toNumber(value) {
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : null;
+    if (typeof value === "bigint")
+        return Number(value);
+    if (typeof value === "string") {
+        const parsed = Number(value.trim());
+        return value.trim() !== "" && Number.isFinite(parsed) ? parsed : null;
+    }
+    return null;
+}
+//# sourceMappingURL=buckets.js.map

package/dist/insights/buckets.js.map

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

package/dist/insights/changepoint.d.ts

@@ -0,0 +1,130 @@
+/**
+ * **Rolling robust statistics and change-point detection** (ADR 0051 §4,
+ * design sketch §D row `anomalies`).
+ *
+ * Two generic, series-shaped algorithms that `anomalies.ts` composes, kept in
+ * their own module for the same reason `stats.ts` exists: they are pure
+ * functions of `readonly number[]` with no notion of a metric, a bucket, a store
+ * or a dialect, and they are unit-tested against hand-built series rather than
+ * against a query result.
+ *
+ * ## Why these two, and not a model
+ *
+ * A self-hosted collector has one project's history and no training budget, so
+ * an anomaly detector here has to work on a few dozen buckets, explain itself in
+ * one number, and never need tuning per metric. Two classical methods do exactly
+ * that, and they answer *different* questions — which is why both are here:
+ *
+ * - {@link rollingRobustStats} answers **"is this bucket unlike the ones just
+ *   before it?"** — a single surprising day. It is a *point* detector.
+ * - {@link cusumChangePoints} answers **"did the level move and stay moved?"** —
+ *   a regression that is only 1.5 MADs deep and so never trips a point detector,
+ *   but that persists for a fortnight. It is a *sequential* detector, and it is
+ *   the one that catches the shape a release regression actually has.
+ *
+ * Both are robust by construction: the centre is a median and the scale is a
+ * median absolute deviation, so one catastrophic bucket in the trailing window
+ * cannot widen the tolerance until nothing is ever abnormal again.
+ */
+/**
+ * The trailing centre and spread for one index of a series.
+ *
+ * `null` in both fields means the index had too little history to be judged —
+ * never `0`, which would claim a perfectly flat past.
+ */
+export interface RollingRobustPoint {
+    /** Median of the trailing window; `null` when it held too few values. */
+    median: number | null;
+    /** Median absolute deviation of the same window; `null` alongside a null median. */
+    mad: number | null;
+    /** How many values the trailing window actually carried. */
+    count: number;
+}
+/**
+ * The trailing median and MAD for every index of `values`.
+ *
+ * The window for index `i` is `values[i - window .. i - 1]` — **the point itself
+ * is excluded**, which is the whole point. Including it drags the median toward
+ * the very value being judged and inflates the MAD by the deviation being
+ * measured, so a big enough spike partly hides itself. Excluding it makes the
+ * comparison "against what came before", which is what a reader means by
+ * "unusual".
+ *
+ * Indices with fewer than `minCount` trailing values report `null`: the first
+ * days of a project are not evidence about the first days of a project, and a
+ * detector that flags them produces a page of findings on every new install.
+ *
+ * Non-finite entries are skipped (they never enter a window and are never
+ * scored), so a sparse series behaves like the shorter series it really is.
+ */
+export declare function rollingRobustStats(values: readonly number[], window: number, minCount: number): RollingRobustPoint[];
+/**
+ * Slack ("allowance") of the tabular CUSUM, in MAD units.
+ *
+ * The accumulator only grows once a deviation exceeds this, so ordinary
+ * bucket-to-bucket noise cancels instead of drifting upward forever. Half a MAD
+ * is the textbook choice — it is the shift size the chart is tuned to detect
+ * fastest — and keeping it a constant rather than a parameter is deliberate:
+ * `sensitivity` already moves the decision threshold, and two dials that both
+ * mean "how eager" would be impossible for a caller to reason about.
+ */
+export declare const CUSUM_SLACK = 0.5;
+/**
+ * The decision threshold, as a multiple of `sensitivity`.
+ *
+ * The alarm fires when the accumulated excess passes
+ * `sensitivity × CUSUM_DECISION_FACTOR` MADs. At the default `sensitivity` of 3
+ * that is 6 MADs of *accumulated* excess — reachable by four consecutive buckets
+ * two MADs off, or by a dozen buckets barely off, but not by noise. It keeps the
+ * one dial monotone: a higher `sensitivity` means fewer findings for the point
+ * detector and for the change-point detector alike.
+ */
+export declare const CUSUM_DECISION_FACTOR = 2;
+/** A detected level shift in a series. */
+export interface ChangePoint {
+    /** Index at which the shift began — the last point before the drift started. */
+    index: number;
+    /** Direction of the shift. */
+    direction: "up" | "down";
+    /** Median of the segment before the change-point. */
+    before: number | null;
+    /** Median of the segment from the change-point to the next one (or the end). */
+    after: number | null;
+    /** Accumulated excess, in MADs, at the bucket that raised the alarm. */
+    score: number;
+}
+/**
+ * Two-sided tabular CUSUM over `values`, segmented so several level changes in
+ * one series are found rather than one.
+ *
+ * ```
+ * eᵢ  = clip((xᵢ − reference) / spread, ±sensitivity)
+ * S⁺ᵢ = max(0, S⁺ᵢ₋₁ + eᵢ − k)      S⁻ᵢ = max(0, S⁻ᵢ₋₁ − eᵢ − k)
+ * ```
+ *
+ * Three decisions make this a *change-point* detector rather than a chart:
+ *
+ * 1. **The reference is the level the segment started at** — the median of its
+ *    first `referenceLength` values — not the median of the whole series. With a
+ *    whole-series centre, a series that steps up halfway sits *above* its own
+ *    median for the entire second half and *below* it for the entire first, so
+ *    the accumulator starts drifting at index 0 and the alarm names the wrong
+ *    bucket. Measuring against where the series began is what makes "it moved"
+ *    a statement about a moment.
+ * 2. **An alarm is reported where the accumulator last left zero**, not where it
+ *    crossed the threshold. A CUSUM crosses several buckets after the level
+ *    actually moved — that lag is how it earns its sensitivity — and reporting
+ *    the crossing would put the finding on the wrong day.
+ * 3. **After an alarm the series is re-segmented from the change-point**, with
+ *    the reference re-estimated over the new regime. Without that, a shifted
+ *    series keeps deviating from the old reference forever and alarms again
+ *    every few buckets; with it, a level that moves and moves back reports
+ *    exactly two change-points.
+ *
+ * `spread` is supplied by the caller (`anomalies.ts` passes the same floored MAD
+ * the point detector uses, so both halves of the primitive are measured in one
+ * unit). A non-positive or missing `spread` means there is nothing to detect and
+ * the result is empty.
+ */
+export declare function cusumChangePoints(values: readonly number[], spread: number | null, sensitivity: number, referenceLength: number): ChangePoint[];
+//# sourceMappingURL=changepoint.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"changepoint.d.ts","sourceRoot":"","sources":["../../src/insights/changepoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,yEAAyE;IACzE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,oFAAoF;IACpF,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,kBAAkB,EAAE,CAyBtB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,MAAM,CAAC;AAE/B;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAoBvC,0CAA0C;AAC1C,MAAM,WAAW,WAAW;IAC1B,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,SAAS,EAAE,IAAI,GAAG,MAAM,CAAC;IACzB,qDAAqD;IACrD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,gFAAgF;IAChF,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,wEAAwE;IACxE,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,WAAW,EAAE,MAAM,EACnB,eAAe,EAAE,MAAM,GACtB,WAAW,EAAE,CAyCf"}

package/dist/insights/changepoint.js

@@ -0,0 +1,209 @@
+/**
+ * **Rolling robust statistics and change-point detection** (ADR 0051 §4,
+ * design sketch §D row `anomalies`).
+ *
+ * Two generic, series-shaped algorithms that `anomalies.ts` composes, kept in
+ * their own module for the same reason `stats.ts` exists: they are pure
+ * functions of `readonly number[]` with no notion of a metric, a bucket, a store
+ * or a dialect, and they are unit-tested against hand-built series rather than
+ * against a query result.
+ *
+ * ## Why these two, and not a model
+ *
+ * A self-hosted collector has one project's history and no training budget, so
+ * an anomaly detector here has to work on a few dozen buckets, explain itself in
+ * one number, and never need tuning per metric. Two classical methods do exactly
+ * that, and they answer *different* questions — which is why both are here:
+ *
+ * - {@link rollingRobustStats} answers **"is this bucket unlike the ones just
+ *   before it?"** — a single surprising day. It is a *point* detector.
+ * - {@link cusumChangePoints} answers **"did the level move and stay moved?"** —
+ *   a regression that is only 1.5 MADs deep and so never trips a point detector,
+ *   but that persists for a fortnight. It is a *sequential* detector, and it is
+ *   the one that catches the shape a release regression actually has.
+ *
+ * Both are robust by construction: the centre is a median and the scale is a
+ * median absolute deviation, so one catastrophic bucket in the trailing window
+ * cannot widen the tolerance until nothing is ever abnormal again.
+ */
+import { median, medianAbsoluteDeviation } from "./stats.js";
+/**
+ * The trailing median and MAD for every index of `values`.
+ *
+ * The window for index `i` is `values[i - window .. i - 1]` — **the point itself
+ * is excluded**, which is the whole point. Including it drags the median toward
+ * the very value being judged and inflates the MAD by the deviation being
+ * measured, so a big enough spike partly hides itself. Excluding it makes the
+ * comparison "against what came before", which is what a reader means by
+ * "unusual".
+ *
+ * Indices with fewer than `minCount` trailing values report `null`: the first
+ * days of a project are not evidence about the first days of a project, and a
+ * detector that flags them produces a page of findings on every new install.
+ *
+ * Non-finite entries are skipped (they never enter a window and are never
+ * scored), so a sparse series behaves like the shorter series it really is.
+ */
+export function rollingRobustStats(values, window, minCount) {
+    const out = [];
+    const width = Math.max(1, Math.floor(window));
+    const floor = Math.max(1, Math.floor(minCount));
+    // The trailing values in a plain array: the windows are tens to a few hundred
+    // entries and a median needs them sorted anyway, so an incremental structure
+    // would add ordering bugs to buy nothing measurable.
+    const trailing = [];
+    for (const value of values) {
+        if (trailing.length < floor) {
+            out.push({ median: null, mad: null, count: trailing.length });
+        }
+        else {
+            const centre = median(trailing);
+            out.push({
+                median: centre,
+                mad: medianAbsoluteDeviation(trailing),
+                count: trailing.length,
+            });
+        }
+        if (Number.isFinite(value)) {
+            trailing.push(value);
+            if (trailing.length > width)
+                trailing.shift();
+        }
+    }
+    return out;
+}
+/**
+ * Slack ("allowance") of the tabular CUSUM, in MAD units.
+ *
+ * The accumulator only grows once a deviation exceeds this, so ordinary
+ * bucket-to-bucket noise cancels instead of drifting upward forever. Half a MAD
+ * is the textbook choice — it is the shift size the chart is tuned to detect
+ * fastest — and keeping it a constant rather than a parameter is deliberate:
+ * `sensitivity` already moves the decision threshold, and two dials that both
+ * mean "how eager" would be impossible for a caller to reason about.
+ */
+export const CUSUM_SLACK = 0.5;
+/**
+ * The decision threshold, as a multiple of `sensitivity`.
+ *
+ * The alarm fires when the accumulated excess passes
+ * `sensitivity × CUSUM_DECISION_FACTOR` MADs. At the default `sensitivity` of 3
+ * that is 6 MADs of *accumulated* excess — reachable by four consecutive buckets
+ * two MADs off, or by a dozen buckets barely off, but not by noise. It keeps the
+ * one dial monotone: a higher `sensitivity` means fewer findings for the point
+ * detector and for the change-point detector alike.
+ */
+export const CUSUM_DECISION_FACTOR = 2;
+/**
+ * Why each deviation is clamped to ±`sensitivity` before it is accumulated.
+ *
+ * A textbook CUSUM alarms on a single large outlier: one bucket ten MADs out
+ * contributes 9.5 on its own and trips any reasonable threshold, so every spike
+ * would also be reported as a level shift and `kind` would stop meaning
+ * anything. Winsorising at exactly the point detector's own threshold fixes
+ * that by construction: a bucket the point detector already calls a `spike`
+ * contributes at most `sensitivity − k`, so **no single bucket can raise a
+ * change-point alarm** at the default settings — it takes three saturated
+ * buckets in a row, or a longer run of smaller ones. That is precisely the
+ * difference between "a bad Tuesday" and "it has been worse since Tuesday",
+ * which is the distinction `kind` exists to make.
+ */
+function winsorise(deviation, limit) {
+    return Math.max(-limit, Math.min(limit, deviation));
+}
+/**
+ * Two-sided tabular CUSUM over `values`, segmented so several level changes in
+ * one series are found rather than one.
+ *
+ * ```
+ * eᵢ  = clip((xᵢ − reference) / spread, ±sensitivity)
+ * S⁺ᵢ = max(0, S⁺ᵢ₋₁ + eᵢ − k)      S⁻ᵢ = max(0, S⁻ᵢ₋₁ − eᵢ − k)
+ * ```
+ *
+ * Three decisions make this a *change-point* detector rather than a chart:
+ *
+ * 1. **The reference is the level the segment started at** — the median of its
+ *    first `referenceLength` values — not the median of the whole series. With a
+ *    whole-series centre, a series that steps up halfway sits *above* its own
+ *    median for the entire second half and *below* it for the entire first, so
+ *    the accumulator starts drifting at index 0 and the alarm names the wrong
+ *    bucket. Measuring against where the series began is what makes "it moved"
+ *    a statement about a moment.
+ * 2. **An alarm is reported where the accumulator last left zero**, not where it
+ *    crossed the threshold. A CUSUM crosses several buckets after the level
+ *    actually moved — that lag is how it earns its sensitivity — and reporting
+ *    the crossing would put the finding on the wrong day.
+ * 3. **After an alarm the series is re-segmented from the change-point**, with
+ *    the reference re-estimated over the new regime. Without that, a shifted
+ *    series keeps deviating from the old reference forever and alarms again
+ *    every few buckets; with it, a level that moves and moves back reports
+ *    exactly two change-points.
+ *
+ * `spread` is supplied by the caller (`anomalies.ts` passes the same floored MAD
+ * the point detector uses, so both halves of the primitive are measured in one
+ * unit). A non-positive or missing `spread` means there is nothing to detect and
+ * the result is empty.
+ */
+export function cusumChangePoints(values, spread, sensitivity, referenceLength) {
+    const out = [];
+    if (spread == null || !(spread > 0) || values.length < 2)
+        return out;
+    const threshold = Math.max(0, sensitivity) * CUSUM_DECISION_FACTOR;
+    if (!(threshold > 0))
+        return out;
+    const reference = Math.max(2, Math.floor(referenceLength));
+    let from = 0;
+    while (from < values.length) {
+        const segment = values.slice(from);
+        const alarm = firstAlarm(segment, median(segment.slice(0, Math.min(reference, segment.length))), spread, threshold, sensitivity);
+        if (alarm == null)
+            break;
+        const at = from + alarm.index;
+        out.push({
+            index: at,
+            direction: alarm.direction,
+            before: null,
+            after: null,
+            score: alarm.score,
+        });
+        // Strictly forward, so a pathological series cannot loop here.
+        from = at + 1;
+    }
+    // Levels are filled in once the segment boundaries are known: `before` is the
+    // regime that ended at the change-point and `after` the one that began there,
+    // each closed by its neighbour rather than running to the end of the series.
+    for (const [position, change] of out.entries()) {
+        const previous = position === 0 ? 0 : out[position - 1].index;
+        const next = position === out.length - 1 ? values.length : out[position + 1].index;
+        change.before = median(values.slice(previous, change.index));
+        change.after = median(values.slice(change.index, next));
+    }
+    return out;
+}
+/** Where one segment first departs from its own opening level, if it does. */
+function firstAlarm(values, reference, spread, threshold, sensitivity) {
+    if (reference == null)
+        return null;
+    let up = 0;
+    let down = 0;
+    let upStart = 0;
+    let downStart = 0;
+    for (let index = 0; index < values.length; index += 1) {
+        const value = values[index];
+        if (!Number.isFinite(value))
+            continue;
+        const deviation = winsorise((value - reference) / spread, sensitivity);
+        if (up === 0)
+            upStart = index;
+        if (down === 0)
+            downStart = index;
+        up = Math.max(0, up + deviation - CUSUM_SLACK);
+        down = Math.max(0, down - deviation - CUSUM_SLACK);
+        if (up > threshold)
+            return { index: upStart, direction: "up", score: up };
+        if (down > threshold)
+            return { index: downStart, direction: "down", score: down };
+    }
+    return null;
+}
+//# sourceMappingURL=changepoint.js.map

package/dist/insights/changepoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"changepoint.js","sourceRoot":"","sources":["../../src/insights/changepoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,MAAM,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAiB7D;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAAyB,EACzB,MAAc,EACd,QAAgB;IAEhB,MAAM,GAAG,GAAyB,EAAE,CAAC;IACrC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;IAC9C,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC;IAChD,8EAA8E;IAC9E,6EAA6E;IAC7E,qDAAqD;IACrD,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,QAAQ,CAAC,MAAM,GAAG,KAAK,EAAE,CAAC;YAC5B,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;QAChE,CAAC;aAAM,CAAC;YACN,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC;YAChC,GAAG,CAAC,IAAI,CAAC;gBACP,MAAM,EAAE,MAAM;gBACd,GAAG,EAAE,uBAAuB,CAAC,QAAQ,CAAC;gBACtC,KAAK,EAAE,QAAQ,CAAC,MAAM;aACvB,CAAC,CAAC;QACL,CAAC;QACD,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YAC3B,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACrB,IAAI,QAAQ,CAAC,MAAM,GAAG,KAAK;gBAAE,QAAQ,CAAC,KAAK,EAAE,CAAC;QAChD,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,GAAG,CAAC;AAE/B;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC;AAEvC;;;;;;;;;;;;;GAaG;AACH,SAAS,SAAS,CAAC,SAAiB,EAAE,KAAa;IACjD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC;AACtD,CAAC;AAgBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAAyB,EACzB,MAAqB,EACrB,WAAmB,EACnB,eAAuB;IAEvB,MAAM,GAAG,GAAkB,EAAE,CAAC;IAC9B,IAAI,MAAM,IAAI,IAAI,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,GAAG,CAAC;IACrE,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,WAAW,CAAC,GAAG,qBAAqB,CAAC;IACnE,IAAI,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC;QAAE,OAAO,GAAG,CAAC;IACjC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC,CAAC;IAE3D,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,OAAO,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC;QAC5B,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACnC,MAAM,KAAK,GAAG,UAAU,CACtB,OAAO,EACP,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAC7D,MAAM,EACN,SAAS,EACT,WAAW,CACZ,CAAC;QACF,IAAI,KAAK,IAAI,IAAI;YAAE,MAAM;QACzB,MAAM,EAAE,GAAG,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC;QAC9B,GAAG,CAAC,IAAI,CAAC;YACP,KAAK,EAAE,EAAE;YACT,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,MAAM,EAAE,IAAI;YACZ,KAAK,EAAE,IAAI;YACX,KAAK,EAAE,KAAK,CAAC,KAAK;SACnB,CAAC,CAAC;QACH,+DAA+D;QAC/D,IAAI,GAAG,EAAE,GAAG,CAAC,CAAC;IAChB,CAAC;IAED,8EAA8E;IAC9E,8EAA8E;IAC9E,6EAA6E;IAC7E,KAAK,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC;QAC/C,MAAM,QAAQ,GAAG,QAAQ,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAE,GAAG,CAAC,QAAQ,GAAG,CAAC,CAAiB,CAAC,KAAK,CAAC;QAC/E,MAAM,IAAI,GACR,QAAQ,KAAK,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAE,GAAG,CAAC,QAAQ,GAAG,CAAC,CAAiB,CAAC,KAAK,CAAC;QACzF,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QAC7D,MAAM,CAAC,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;IAC1D,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,8EAA8E;AAC9E,SAAS,UAAU,CACjB,MAAyB,EACzB,SAAwB,EACxB,MAAc,EACd,SAAiB,EACjB,WAAmB;IAEnB,IAAI,SAAS,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC;IACnC,IAAI,EAAE,GAAG,CAAC,CAAC;IACX,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACtD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAW,CAAC;QACtC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;YAAE,SAAS;QACtC,MAAM,SAAS,GAAG,SAAS,CAAC,CAAC,KAAK,GAAG,SAAS,CAAC,GAAG,MAAM,EAAE,WAAW,CAAC,CAAC;QACvE,IAAI,EAAE,KAAK,CAAC;YAAE,OAAO,GAAG,KAAK,CAAC;QAC9B,IAAI,IAAI,KAAK,CAAC;YAAE,SAAS,GAAG,KAAK,CAAC;QAClC,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,GAAG,SAAS,GAAG,WAAW,CAAC,CAAC;QAC/C,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,GAAG,SAAS,GAAG,WAAW,CAAC,CAAC;QACnD,IAAI,EAAE,GAAG,SAAS;YAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;QAC1E,IAAI,IAAI,GAAG,SAAS;YAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACpF,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/insights/evaluate.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The in-memory evaluator for a {@link BucketMeasure} (ADR 0051 §4).
+ *
+ * `buildMetricBuckets` renders a measure to SQL for the four persistent stores.
+ * The collector also ships an in-memory store — the one the playground and the
+ * end-to-end harness boot without a database — which has no SQL to run. Rather
+ * than let the insight endpoints go dark there (an empty series reads as "no
+ * data", which is a different and misleading claim), the same declarative
+ * measure is evaluated directly over events here.
+ *
+ * Pure, and deliberately the *same shape* as the SQL: one pass that groups by
+ * bucket, then one aggregate per bucket, using the same closed predicate
+ * vocabulary. `src/__tests__/insights.test.ts` runs both paths over the same
+ * rows so the two cannot drift.
+ */
+import { type BucketGrain, type BucketSplitDimension, type BucketVariant } from "./measures.js";
+import { type MetricBucketRow } from "./buckets.js";
+/**
+ * The promoted event columns a measure can read — the in-memory mirror of the
+ * `events` table's column set. A store maps its own event representation into
+ * this once, and the evaluator never sees the store's shape.
+ */
+export interface BucketEventLike {
+    /** Event time, epoch milliseconds. */
+    ts: number;
+    event_type: string;
+    scene_id: string;
+    session_id: string;
+    mesh?: string;
+    name?: string;
+    source?: string;
+    fps?: number;
+    visible_ms?: number;
+    js_heap_bytes?: number;
+    long_frames?: number;
+    position?: readonly number[];
+    direction?: readonly number[];
+    hit_point?: readonly number[];
+    screen?: readonly number[];
+    /** `ar_placement.scale`, the one measure value that lives in the payload. */
+    ar_placement_scale?: number;
+}
+/** Scope an evaluation the way the SQL's `WHERE` clause does. */
+export interface EvaluateBucketOptions {
+    metric: string;
+    /** A named auxiliary series of the metric rather than its headline one (#307). */
+    series?: BucketVariant;
+    bucket?: BucketGrain;
+    since?: number;
+    until?: number;
+    scene?: string;
+    /** Split the series by one promoted dimension, as `buildMetricBuckets` does. */
+    groupBy?: BucketSplitDimension;
+}
+/**
+ * Evaluate a metric's bucket series over events held in memory.
+ *
+ * Returns the same rows `buildMetricBuckets` would: ascending by bucket, with
+ * buckets that matched nothing simply absent. Throws for a metric with no
+ * portable bucket form, exactly as the builder does.
+ */
+export declare function evaluateBucketMeasure(events: Iterable<BucketEventLike>, opts: EvaluateBucketOptions): MetricBucketRow[];
+//# sourceMappingURL=evaluate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"evaluate.d.ts","sourceRoot":"","sources":["../../src/insights/evaluate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAGL,KAAK,WAAW,EAGhB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EACnB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAG3E;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,sCAAsC;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,6EAA6E;IAC7E,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,iEAAiE;AACjE,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,gFAAgF;IAChF,OAAO,CAAC,EAAE,oBAAoB,CAAC;CAChC;AA2DD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,QAAQ,CAAC,eAAe,CAAC,EACjC,IAAI,EAAE,qBAAqB,GAC1B,eAAe,EAAE,CAwDnB"}