@uptimizr/db 2.0.1 → 2.1.0

package/dist/insights/evaluate.js

@@ -0,0 +1,158 @@
+/**
+ * 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 { resolveBucketMeasure, BUCKET_SECONDS, } from "./measures.js";
+import { byBucketThenDimension } from "./buckets.js";
+import { quantile } from "./stats.js";
+/** The vector columns a geometry predicate can guard. */
+const VECTORS = ["position", "direction", "hit_point", "screen"];
+/**
+ * The split dimension's value on one event — the in-memory mirror of
+ * `BUCKET_SPLIT_COLUMNS` (#306). `''` is "unknown", the same reading the stores'
+ * `NOT NULL DEFAULT ''` columns give.
+ */
+function splitValueOf(event, dimension) {
+    switch (dimension) {
+        case "scene":
+            return event.scene_id ?? "";
+        case "event_type":
+            return event.event_type ?? "";
+        case "mesh":
+            return event.mesh ?? "";
+        case "name":
+            return event.name ?? "";
+        case "source":
+            return event.source ?? "";
+    }
+}
+/** Whether an event satisfies one predicate from the closed vocabulary. */
+function matches(event, predicate) {
+    switch (predicate.kind) {
+        case "eq":
+            return (event[predicate.column] ?? "") === predicate.value;
+        case "ne":
+            return (event[predicate.column] ?? "") !== predicate.value;
+        case "in":
+            return predicate.values.includes(event[predicate.column] ?? "");
+        case "geometry": {
+            const column = VECTORS.find((name) => name === predicate.column);
+            const vector = column == null ? undefined : event[column];
+            return Array.isArray(vector) && vector.length === predicate.arity;
+        }
+    }
+}
+/** The numeric value a measure's aggregate reads off one event. */
+function valueOf(event, measure) {
+    if (measure.aggregate.kind === "count" || measure.aggregate.kind === "sessions")
+        return null;
+    const raw = event[measure.aggregate.column];
+    if (typeof raw !== "number" || !Number.isFinite(raw))
+        return null;
+    // `js_heap_bytes` of 0 means "not reported" — excluded from averages and
+    // percentiles, kept for a max. Mirrors `valueColumnExpr` in `buckets.ts`.
+    if (measure.aggregate.column === "js_heap_bytes" &&
+        raw === 0 &&
+        measure.aggregate.kind !== "max") {
+        return null;
+    }
+    return raw;
+}
+/**
+ * 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 function evaluateBucketMeasure(events, opts) {
+    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 width = BUCKET_SECONDS[opts.bucket ?? "day"] * 1000;
+    const types = measure.eventTypes.length > 0 ? new Set(measure.eventTypes) : null;
+    // Keyed by bucket, or by `bucket|dimension` on a grouped read (#306) — the
+    // in-memory counterpart of adding the column to the SQL `GROUP BY`.
+    const buckets = new Map();
+    for (const event of events) {
+        if (!Number.isFinite(event.ts))
+            continue;
+        if (opts.since != null && event.ts < opts.since)
+            continue;
+        if (opts.until != null && event.ts >= opts.until)
+            continue;
+        if (opts.scene != null && opts.scene.length > 0 && event.scene_id !== opts.scene)
+            continue;
+        if (types != null && !types.has(event.event_type))
+            continue;
+        if ((measure.where ?? []).some((predicate) => !matches(event, predicate)))
+            continue;
+        const start = Math.floor(event.ts / width) * width;
+        const dimension = opts.groupBy == null ? null : splitValueOf(event, opts.groupBy);
+        const key = dimension == null ? String(start) : `${start}|${dimension}`;
+        let entry = buckets.get(key);
+        if (entry == null) {
+            entry = { start, dimension, values: [], count: 0, sessions: new Set() };
+            buckets.set(key, entry);
+        }
+        entry.count += 1;
+        entry.sessions.add(event.session_id);
+        const value = valueOf(event, measure);
+        if (value != null)
+            entry.values.push(value);
+    }
+    const rows = [];
+    for (const entry of buckets.values()) {
+        rows.push({
+            bucket: entry.start,
+            value: aggregate(entry, measure),
+            sample_size: measure.aggregate.kind === "sessions" ? entry.sessions.size : entry.count,
+            ...(entry.dimension == null ? {} : { dimension_value: entry.dimension }),
+        });
+    }
+    return rows.sort(byBucketThenDimension);
+}
+/** Apply a measure's aggregate to one bucket's accumulated values. */
+function aggregate(entry, measure) {
+    switch (measure.aggregate.kind) {
+        case "count":
+            return entry.count;
+        case "sessions":
+            return entry.sessions.size;
+        case "sum": {
+            if (entry.values.length === 0)
+                return null;
+            let total = 0;
+            for (const value of entry.values)
+                total += value;
+            return total;
+        }
+        case "avg": {
+            if (entry.values.length === 0)
+                return null;
+            let total = 0;
+            for (const value of entry.values)
+                total += value;
+            return total / entry.values.length;
+        }
+        case "max":
+            return entry.values.length === 0 ? null : Math.max(...entry.values);
+        case "quantile":
+            return quantile(entry.values, measure.aggregate.q);
+    }
+}
+//# sourceMappingURL=evaluate.js.map

package/dist/insights/evaluate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluate.js","sourceRoot":"","sources":["../../src/insights/evaluate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EACL,oBAAoB,EACpB,cAAc,GAMf,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,qBAAqB,EAAwB,MAAM,cAAc,CAAC;AAC3E,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AA0CtC,yDAAyD;AACzD,MAAM,OAAO,GAAG,CAAC,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,QAAQ,CAAU,CAAC;AAE1E;;;;GAIG;AACH,SAAS,YAAY,CAAC,KAAsB,EAAE,SAA+B;IAC3E,QAAQ,SAAS,EAAE,CAAC;QAClB,KAAK,OAAO;YACV,OAAO,KAAK,CAAC,QAAQ,IAAI,EAAE,CAAC;QAC9B,KAAK,YAAY;YACf,OAAO,KAAK,CAAC,UAAU,IAAI,EAAE,CAAC;QAChC,KAAK,MAAM;YACT,OAAO,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC;QAC1B,KAAK,MAAM;YACT,OAAO,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC;QAC1B,KAAK,QAAQ;YACX,OAAO,KAAK,CAAC,MAAM,IAAI,EAAE,CAAC;IAC9B,CAAC;AACH,CAAC;AAED,2EAA2E;AAC3E,SAAS,OAAO,CAAC,KAAsB,EAAE,SAA0B;IACjE,QAAQ,SAAS,CAAC,IAAI,EAAE,CAAC;QACvB,KAAK,IAAI;YACP,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,KAAK,SAAS,CAAC,KAAK,CAAC;QAC7D,KAAK,IAAI;YACP,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,KAAK,SAAS,CAAC,KAAK,CAAC;QAC7D,KAAK,IAAI;YACP,OAAO,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;QAClE,KAAK,UAAU,CAAC,CAAC,CAAC;YAChB,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,SAAS,CAAC,MAAM,CAAC,CAAC;YACjE,MAAM,MAAM,GAAG,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YAC1D,OAAO,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS,CAAC,KAAK,CAAC;QACpE,CAAC;IACH,CAAC;AACH,CAAC;AAED,mEAAmE;AACnE,SAAS,OAAO,CAAC,KAAsB,EAAE,OAAsB;IAC7D,IAAI,OAAO,CAAC,SAAS,CAAC,IAAI,KAAK,OAAO,IAAI,OAAO,CAAC,SAAS,CAAC,IAAI,KAAK,UAAU;QAAE,OAAO,IAAI,CAAC;IAC7F,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAC5C,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAClE,yEAAyE;IACzE,0EAA0E;IAC1E,IACE,OAAO,CAAC,SAAS,CAAC,MAAM,KAAK,eAAe;QAC5C,GAAG,KAAK,CAAC;QACT,OAAO,CAAC,SAAS,CAAC,IAAI,KAAK,KAAK,EAChC,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CACnC,MAAiC,EACjC,IAA2B;IAE3B,MAAM,OAAO,GAAG,oBAAoB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IAC/D,IAAI,OAAO,IAAI,IAAI,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CACb,IAAI,CAAC,MAAM,IAAI,IAAI;YACjB,CAAC,CAAC,WAAW,IAAI,CAAC,MAAM,iCAAiC;YACzD,CAAC,CAAC,WAAW,IAAI,CAAC,MAAM,kBAAkB,IAAI,CAAC,MAAM,UAAU,CAClE,CAAC;IACJ,CAAC;IACD,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,CAAC;IAC1D,MAAM,KAAK,GAAG,OAAO,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACjF,2EAA2E;IAC3E,oEAAoE;IACpE,MAAM,OAAO,GAAG,IAAI,GAAG,EASpB,CAAC;IAEJ,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YAAE,SAAS;QACzC,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,IAAI,KAAK,CAAC,EAAE,GAAG,IAAI,CAAC,KAAK;YAAE,SAAS;QAC1D,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,IAAI,KAAK,CAAC,EAAE,IAAI,IAAI,CAAC,KAAK;YAAE,SAAS;QAC3D,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,KAAK,IAAI,CAAC,KAAK;YAAE,SAAS;QAC3F,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC;YAAE,SAAS;QAC5D,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;YAAE,SAAS;QAEpF,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,GAAG,KAAK,CAAC,GAAG,KAAK,CAAC;QACnD,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAClF,MAAM,GAAG,GAAG,SAAS,IAAI,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,IAAI,SAAS,EAAE,CAAC;QACxE,IAAI,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,KAAK,IAAI,IAAI,EAAE,CAAC;YAClB,KAAK,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,IAAI,GAAG,EAAE,EAAE,CAAC;YACxE,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC1B,CAAC;QACD,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC;QACjB,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QACrC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QACtC,IAAI,KAAK,IAAI,IAAI;YAAE,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC9C,CAAC;IAED,MAAM,IAAI,GAAsB,EAAE,CAAC;IACnC,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;QACrC,IAAI,CAAC,IAAI,CAAC;YACR,MAAM,EAAE,KAAK,CAAC,KAAK;YACnB,KAAK,EAAE,SAAS,CAAC,KAAK,EAAE,OAAO,CAAC;YAChC,WAAW,EAAE,OAAO,CAAC,SAAS,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK;YACtF,GAAG,CAAC,KAAK,CAAC,SAAS,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC;SACzE,CAAC,CAAC;IACL,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;AAC1C,CAAC;AAED,sEAAsE;AACtE,SAAS,SAAS,CAChB,KAAiE,EACjE,OAAsB;IAEtB,QAAQ,OAAO,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;QAC/B,KAAK,OAAO;YACV,OAAO,KAAK,CAAC,KAAK,CAAC;QACrB,KAAK,UAAU;YACb,OAAO,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;QAC7B,KAAK,KAAK,CAAC,CAAC,CAAC;YACX,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,IAAI,CAAC;YAC3C,IAAI,KAAK,GAAG,CAAC,CAAC;YACd,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,MAAM;gBAAE,KAAK,IAAI,KAAK,CAAC;YACjD,OAAO,KAAK,CAAC;QACf,CAAC;QACD,KAAK,KAAK,CAAC,CAAC,CAAC;YACX,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,IAAI,CAAC;YAC3C,IAAI,KAAK,GAAG,CAAC,CAAC;YACd,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,MAAM;gBAAE,KAAK,IAAI,KAAK,CAAC;YACjD,OAAO,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC;QACrC,CAAC;QACD,KAAK,KAAK;YACR,OAAO,KAAK,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;QACtE,KAAK,UAAU;YACb,OAAO,QAAQ,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IACvD,CAAC;AACH,CAAC"}

package/dist/insights/health.d.ts

@@ -0,0 +1,219 @@
+/**
+ * **`scene_health`** — "which scene is in trouble, and why?" (ADR 0051 §4, sketch §D).
+ *
+ * One number per scene, and — more importantly — the six numbers it was built
+ * from. A single score is only useful if it can be taken apart: every factor
+ * reports the **metric id** behind it, the **raw** value that metric produced,
+ * the **normalised** 0–100 it contributed and the **weight** it carried, so
+ * "the lobby is at 38" is always one step away from "because its 5th-percentile
+ * FPS is 19 against a project norm of 47".
+ *
+ * Pure TypeScript over the same bucket series as every other primitive.
+ *
+ * ## The score is relative, and says so
+ *
+ * There is no absolute scale on which 60 FPS is "healthy" — a marketing
+ * configurator and a six-player VR game do not share one — so every factor is
+ * normalised against **the project's own baseline over the previous equal
+ * window**, using the same robust centre-and-spread `movers` ranks with
+ * (median, and a MAD floored at 1% of the level). A factor exactly at the
+ * project norm scores **50**; {@link HEALTH_Z_SPAN} robust deviations better
+ * scores 100, the same distance worse scores 0.
+ *
+ * That makes the score a comparison, not a grade: a project where every scene
+ * is equally bad reads 50 across the board. It is the right shape for the
+ * question actually asked ("*which* scene should I look at this week"), and the
+ * registry entry's caveats say plainly that it is not a quality bar.
+ *
+ * ## Factors are declared, not inferred
+ *
+ * {@link HEALTH_FACTORS} is a fixed, ordered catalog. Each entry names the
+ * metric it reads, whether it is a level or a rate (and which catalog series
+ * supply the numerator and denominator), which direction is good, and its
+ * default weight. Nothing here is derived from a request, so the fan-out is a
+ * compile-time constant and a caller can only change the **weights** — never
+ * which series are read.
+ */
+import type { MetricId } from "@uptimizr/metrics";
+import type { MetricBucketRow } from "./buckets.js";
+import { type BucketGrain, type BucketVariant } from "./measures.js";
+import { type ResolvedWindow } from "./windows.js";
+/** How one health factor is measured. */
+export interface HealthFactorSpec {
+    /** Stable factor id — the key a `weights` override addresses it by. */
+    readonly id: string;
+    /** The registry metric this factor is a reading of. */
+    readonly metric: MetricId;
+    /**
+     * The series that supplies the factor's numerator: a named catalog variant,
+     * or `undefined` for the metric's own headline series.
+     */
+    readonly numerator?: BucketVariant;
+    /**
+     * The series that supplies the denominator, making this factor a **rate**.
+     * `undefined` for a level factor (an FPS percentile), which is read directly.
+     */
+    readonly denominator?: BucketVariant;
+    /** Whether a *higher* raw value is healthier. */
+    readonly direction: "up" | "down";
+    /** Default weight in the score. Overridable per request. */
+    readonly weight: number;
+    /** What one unit of the raw value is. */
+    readonly unit: string;
+    /** What the raw number actually measures — copied into the row. */
+    readonly note: string;
+}
+/**
+ * The six factors, in the order they are reported.
+ *
+ * The weights are a judgement, and they are declared here (and surfaced in the
+ * registry entry, so they appear in `capabilities` and in the generated tool
+ * catalog) precisely so that judgement is arguable rather than hidden: errors
+ * and raw smoothness dominate, frustration signals matter, and exploration is a
+ * tiebreak. A project that disagrees passes `weights`.
+ */
+export declare const HEALTH_FACTORS: readonly HealthFactorSpec[];
+/** Every factor id, for validating a `weights` override. */
+export declare const HEALTH_FACTOR_IDS: readonly string[];
+/** The declared default weights, as the registry entry publishes them. */
+export declare const HEALTH_DEFAULT_WEIGHTS: Readonly<Record<string, number>>;
+/**
+ * How many robust deviations from the project norm span half the scale.
+ *
+ * At the norm a factor scores 50; `HEALTH_Z_SPAN` deviations better scores 100
+ * and the same distance worse scores 0. Four is chosen so that the everyday
+ * range of a metric occupies the middle of the scale rather than saturating it
+ * — a scene one MAD off the norm reads 62 or 38, which is a nudge, and it takes
+ * a genuinely unusual reading to bottom out.
+ */
+export declare const HEALTH_Z_SPAN = 4;
+/** Decimals a health number is rounded to before it leaves the API. */
+export declare const HEALTH_PRECISION = 6;
+/**
+ * Sessions below which a scene's score is not worth reading.
+ *
+ * Not a filter: the row is returned with its `sampleSize` so a caller can see
+ * why, exactly as `movers` keeps its sub-`minSample` rows.
+ */
+export declare const HEALTH_MIN_SESSIONS = 20;
+/** How many scenes one request may score when the caller names none. */
+export declare const HEALTH_DEFAULT_SCENES = 5;
+/** The hard cap on scenes per request — the fan-out is linear in this. */
+export declare const HEALTH_MAX_SCENES = 10;
+/** Default window, in days. */
+export declare const HEALTH_DEFAULT_WINDOW_DAYS = 7;
+/**
+ * Resolve the window a health score is computed over, and the project baseline
+ * window immediately before it.
+ *
+ * **This is the one insight primitive whose window includes the bucket in
+ * progress**, and the difference is deliberate. `baseline` and `movers` floor
+ * `until` down to the last complete bucket because they report *counts*, and a
+ * third of a day of traffic compared against whole days reads as a collapse
+ * every morning. Every health factor is a **rate or a percentile** — errors per
+ * session, long frames per sampled window, the 5th-percentile FPS — and none of
+ * those is distorted by a partial bucket: half a day of data gives half the
+ * numerator *and* half the denominator.
+ *
+ * Flooring here would instead make the score answer about **yesterday**, which
+ * is the wrong answer to 'which scene is in trouble' and, on a dashboard whose
+ * range is the last hour, would show an empty tile all day.
+ *
+ * The baseline is the equal window immediately before — the same 'previous
+ * equal window' reference `movers` uses, so a health score and a movers list
+ * are read against the same past.
+ */
+export declare function resolveHealthWindows(opts: {
+    since?: number;
+    until?: number;
+    windowDays?: number;
+    bucket: BucketGrain;
+    now: number;
+}): {
+    range: ResolvedWindow;
+    baseline: ResolvedWindow;
+};
+/** One factor's contribution to a scene's score. */
+export interface HealthFactorRow {
+    /** The factor id — the key a `weights` override addresses. */
+    id: string;
+    /** The registry metric behind the raw value. */
+    metric: string;
+    /** The value that metric produced over the window, in `unit`. */
+    raw: number | null;
+    /** The project baseline this was normalised against — the previous window's median. */
+    baseline: number | null;
+    /** 0–100 against that baseline; 50 is exactly the project norm. `null` when unavailable. */
+    score: number | null;
+    /** The weight this factor carried. */
+    weight: number;
+    unit: string;
+    /** What the raw number is, and why it is normalised the way it is. */
+    note: string;
+}
+/** What `scene_health` reports. One row per scene. */
+export interface SceneHealthRow {
+    /** The scene scored; `''` when the request spanned every scene. */
+    scene: string;
+    /** Weighted mean of the available factors' scores, 0–100; `null` when none were. */
+    score: number | null;
+    factors: HealthFactorRow[];
+    /** Sessions behind the window — what decides whether the score means anything. */
+    sampleSize: number;
+    since: number;
+    until: number;
+}
+/** The two bucket series one factor reads, over one window. */
+export interface HealthSeries {
+    numerator: readonly MetricBucketRow[];
+    /** Absent for a level factor. */
+    denominator?: readonly MetricBucketRow[];
+}
+/** Everything `computeSceneHealth` needs about one factor. */
+export interface HealthFactorInput {
+    /** The scene's series over the scored window. */
+    current: HealthSeries;
+    /** The project's series over the preceding equal window — the baseline. */
+    baseline: HealthSeries;
+}
+/**
+ * Map a raw value onto 0–100 against a baseline centre and spread.
+ *
+ * Linear in the robust z and clamped, rather than a logistic or a percentile
+ * rank: a reader has to be able to do the arithmetic backwards from the row.
+ * `null` when the baseline carried nothing to compare against — an unscored
+ * factor, never a default of 50, because "we have no history for this" and
+ * "this is exactly normal" are different statements.
+ */
+export declare function normaliseFactor(raw: number | null, baseline: readonly number[], direction: "up" | "down"): {
+    score: number | null;
+    centre: number | null;
+};
+/**
+ * Resolve the weights a request scores with.
+ *
+ * An override replaces a factor's weight; factors the override does not mention
+ * keep their declared weight, so `weights={"error_rate":0.6}` means "I care
+ * much more about errors" rather than "score errors only". Unknown ids are
+ * rejected at the route, not silently ignored.
+ */
+export declare function resolveWeights(override?: Readonly<Record<string, number>> | null): Record<string, number>;
+/**
+ * Score one scene.
+ *
+ * `inputs` is keyed by factor id; a factor with no entry (a project with no XR
+ * traffic, a scene with no perf samples) is reported with `score: null` and
+ * excluded from the weighted mean rather than dropped from the row — the reason
+ * a score is missing a factor has to be visible in the answer.
+ */
+export declare function computeSceneHealth(opts: {
+    scene: string;
+    since: number;
+    until: number;
+    sampleSize: number;
+    inputs: Readonly<Record<string, HealthFactorInput | undefined>>;
+    weights?: Readonly<Record<string, number>> | null;
+}): SceneHealthRow;
+/** Least healthy first, then by scene id so the order is a function of the rows. */
+export declare function rankSceneHealth(rows: readonly SceneHealthRow[]): SceneHealthRow[];
+//# sourceMappingURL=health.d.ts.map

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

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