@uptimizr/db 2.0.1 → 2.1.0

package/dist/query/dsl/compare.d.ts

@@ -0,0 +1,167 @@
+/**
+ * **`compare`: what changed** (ADR 0051 §3/§4, design sketch §C.2).
+ *
+ * The first of the three things an agent cannot do today. A model asked "is the
+ * statue getting less attention than last week?" currently runs two queries,
+ * eyeballs two lists of different lengths in different orders, and reports a
+ * difference it computed in prose — which is where the arithmetic goes wrong,
+ * every time.
+ *
+ * `compare` runs the *same* validated spec twice — once with the query's own
+ * range and segment, once with the comparison's — and joins the two results
+ * **here, in TypeScript**, on the dimension key. Not in SQL: a self-join over
+ * two windows would have to be written per dialect, would double the parity
+ * surface, and would make the "one SQL path" property of the DSL false. The join
+ * is a `Map` over at most `limits.maxRows` rows on each side.
+ *
+ * Everything in this module is pure: rows in, rows out. It never runs a query —
+ * the collector does that twice and hands both results here.
+ *
+ * ## Which rows are joined
+ *
+ * On the **key columns**: the output columns of the grouping dimensions (the
+ * query's, or the metric's own grain). A `bucket`-grain metric's axis is
+ * deliberately *not* a key — two ranges have different buckets, so joining on
+ * them would produce two disjoint sets and zero matches. Its buckets are
+ * collapsed per key instead, and the per-bucket values feed
+ * {@link import("./significance.js").welchT} as two samples, which is the one
+ * place a t-test on this data is honest.
+ *
+ * A key present on one side only is still a row: `previous: null` is an arrival
+ * and `current: null` a disappearance, and both are usually the answer.
+ *
+ * ## Significance, only where it is earned
+ *
+ * For a count or session measure the row's share of its window is a proportion,
+ * so a pooled two-proportion z answers "is this share different" — and that is
+ * computed only when both windows clear the metric's `comparable.minSample`.
+ * For anything else (`fps`, a ratio, a duration average) the field is **absent**
+ * rather than guessed, and a caveat says why. An agent that is handed a p-value
+ * will quote it; handing it one that the data cannot support is worse than
+ * handing it none.
+ */
+import { type MetricDefinition, type MetricId } from "@uptimizr/metrics";
+import type { AppliedFilters, ResultRange, SampleSize, SummaryMeasure } from "../summary/types.js";
+import { type MeanSignificance, type Significance } from "./significance.js";
+/** A row as it leaves a store. */
+type Row = Readonly<Record<string, unknown>>;
+/** What the second run varied: the time window, or the slice. */
+export type ComparisonBasis = "range" | "segment";
+/** One side of a comparison, described well enough to be quoted on its own. */
+export interface ComparisonSide {
+    range: ResultRange;
+    /** The dimensions held fixed on this side, when the basis is `segment`. */
+    segment: AppliedFilters;
+    /** Rows the store returned before the join. */
+    rows: number;
+    /** Sum of the measure across those rows; `null` when it cannot be summed. */
+    total: number | null;
+    sampleSize: SampleSize;
+}
+/** One joined row: the same key, measured twice. */
+export interface ComparisonRow {
+    /** The dimension values that identify this row, keyed by output column. */
+    key: Readonly<Record<string, string>>;
+    /** The row's label — its key columns joined, so a reading can name it. */
+    label: string;
+    current: number | null;
+    previous: number | null;
+    /** `current - previous`; `null` when either side is missing. */
+    delta: number | null;
+    /** `delta / previous`; `null` when `previous` is missing, zero or negative. */
+    deltaPct: number | null;
+    /** Present only where the registry justifies a test — see the module doc. */
+    significance?: Significance;
+}
+/** The envelope a `compare` query answers with. */
+export interface ComparisonMeta {
+    metric: MetricId;
+    basis: ComparisonBasis;
+    /** The columns the two sides were joined on. */
+    keys: readonly string[];
+    measure: SummaryMeasure | null;
+    current: ComparisonSide;
+    previous: ComparisonSide;
+    /** Rows in the joined result. */
+    rows: number;
+    /** Whether either side hit its row cap, so a key may be missing from one. */
+    truncated: boolean;
+    /**
+     * Welch's t over the two windows' per-bucket values — present only for a
+     * `bucket`-grain metric whose measure is a mean, which is the only shape here
+     * that really is two samples.
+     */
+    overall?: MeanSignificance;
+    caveats: readonly string[];
+}
+/** `format=table` on a comparison: the envelope plus the joined rows. */
+export interface ComparisonResult {
+    meta: ComparisonMeta;
+    rows: readonly ComparisonRow[];
+}
+/** `format=summary` on a comparison: the biggest movers, with a reading. */
+export interface MoversSummary {
+    kind: "movers";
+    metric: MetricId;
+    basis: ComparisonBasis;
+    measure: SummaryMeasure | null;
+    current: ComparisonSide;
+    previous: ComparisonSide;
+    /** The rows that moved most, by absolute delta. Bounded by `maxSummaryRows`. */
+    top: readonly ComparisonRow[];
+    /** Rows the digest did not list individually. */
+    rest: {
+        rows: number;
+        delta: number | null;
+    };
+    overall?: MeanSignificance;
+    /** One sentence, templated from column semantics only — never model-written. */
+    reading: string;
+    caveats: readonly string[];
+}
+/** What the caller knows about the two runs that produced the rows. */
+export interface ComparisonContext {
+    basis: ComparisonBasis;
+    /** The output columns the two sides are joined on. */
+    keys: readonly string[];
+    currentRange: ResultRange;
+    previousRange: ResultRange;
+    currentSegment?: Readonly<Record<string, string>>;
+    previousSegment?: Readonly<Record<string, string>>;
+    /** The row cap in force, so `truncated` can be derived. */
+    limit?: number;
+    /** Extra caveats true of this comparison only. */
+    caveats?: readonly string[];
+    /** Cap on the movers digest; defaults to the registry's `maxSummaryRows`. */
+    maxRows?: number;
+}
+/**
+ * The dimension output columns two sides of a comparison are joined on.
+ *
+ * Deliberately the *dimensions*, not "every non-numeric column": a metric's row
+ * can carry descriptive text (a scene name next to a scene id) that is not part
+ * of its identity, and joining on it would split a key in two whenever the
+ * description changed between the two windows.
+ */
+export declare function comparisonKeys(metric: MetricDefinition, columns: readonly string[]): string[];
+/**
+ * Join two runs of the same spec into one comparison.
+ *
+ * `current` and `previous` are the rows each run produced, already coerced by
+ * the store edge. Neither array is mutated, and nothing here reads a clock or a
+ * store.
+ */
+export declare function compareRows(metric: MetricId | MetricDefinition, current: readonly Row[], previous: readonly Row[], ctx: ComparisonContext): ComparisonResult | null;
+/**
+ * Turn a comparison into the bounded `format=summary` digest: the rows that
+ * moved most, and one sentence that says what happened.
+ *
+ * The sentence is templated from the registry's column semantics — the measure's
+ * name and unit, the metric's `comparable.direction` — and never written by a
+ * model, so two identical results always read identically.
+ */
+export declare function summarizeComparison(metric: MetricId | MetricDefinition, comparison: ComparisonResult, ctx?: {
+    maxRows?: number;
+}): MoversSummary | null;
+export {};
+//# sourceMappingURL=compare.d.ts.map

package/dist/query/dsl/compare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare.d.ts","sourceRoot":"","sources":["../../../src/query/dsl/compare.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,EAAa,KAAK,gBAAgB,EAAE,KAAK,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAWpF,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACnG,OAAO,EAIL,KAAK,gBAAgB,EACrB,KAAK,YAAY,EAClB,MAAM,mBAAmB,CAAC;AAE3B,kCAAkC;AAClC,KAAK,GAAG,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAE7C,iEAAiE;AACjE,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,SAAS,CAAC;AAElD,+EAA+E;AAC/E,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,WAAW,CAAC;IACnB,2EAA2E;IAC3E,OAAO,EAAE,cAAc,CAAC;IACxB,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,UAAU,EAAE,UAAU,CAAC;CACxB;AAED,oDAAoD;AACpD,MAAM,WAAW,aAAa;IAC5B,2EAA2E;IAC3E,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACtC,0EAA0E;IAC1E,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,gEAAgE;IAChE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,6EAA6E;IAC7E,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B;AAED,mDAAmD;AACnD,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,QAAQ,CAAC;IACjB,KAAK,EAAE,eAAe,CAAC;IACvB,gDAAgD;IAChD,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,OAAO,EAAE,cAAc,GAAG,IAAI,CAAC;IAC/B,OAAO,EAAE,cAAc,CAAC;IACxB,QAAQ,EAAE,cAAc,CAAC;IACzB,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,SAAS,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B;AAED,yEAAyE;AACzE,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,cAAc,CAAC;IACrB,IAAI,EAAE,SAAS,aAAa,EAAE,CAAC;CAChC;AAED,4EAA4E;AAC5E,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,QAAQ,CAAC;IACjB,KAAK,EAAE,eAAe,CAAC;IACvB,OAAO,EAAE,cAAc,GAAG,IAAI,CAAC;IAC/B,OAAO,EAAE,cAAc,CAAC;IACxB,QAAQ,EAAE,cAAc,CAAC;IACzB,gFAAgF;IAChF,GAAG,EAAE,SAAS,aAAa,EAAE,CAAC;IAC9B,iDAAiD;IACjD,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAC7C,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,gFAAgF;IAChF,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B;AAED,uEAAuE;AACvE,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,eAAe,CAAC;IACvB,sDAAsD;IACtD,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,YAAY,EAAE,WAAW,CAAC;IAC1B,aAAa,EAAE,WAAW,CAAC;IAC3B,cAAc,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAClD,eAAe,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AA0FD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,gBAAgB,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAO7F;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,QAAQ,GAAG,gBAAgB,EACnC,OAAO,EAAE,SAAS,GAAG,EAAE,EACvB,QAAQ,EAAE,SAAS,GAAG,EAAE,EACxB,GAAG,EAAE,iBAAiB,GACrB,gBAAgB,GAAG,IAAI,CA0HzB;AAiDD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,QAAQ,GAAG,gBAAgB,EACnC,UAAU,EAAE,gBAAgB,EAC5B,GAAG,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GAC7B,aAAa,GAAG,IAAI,CAmEtB"}

package/dist/query/dsl/compare.js

@@ -0,0 +1,358 @@
+/**
+ * **`compare`: what changed** (ADR 0051 §3/§4, design sketch §C.2).
+ *
+ * The first of the three things an agent cannot do today. A model asked "is the
+ * statue getting less attention than last week?" currently runs two queries,
+ * eyeballs two lists of different lengths in different orders, and reports a
+ * difference it computed in prose — which is where the arithmetic goes wrong,
+ * every time.
+ *
+ * `compare` runs the *same* validated spec twice — once with the query's own
+ * range and segment, once with the comparison's — and joins the two results
+ * **here, in TypeScript**, on the dimension key. Not in SQL: a self-join over
+ * two windows would have to be written per dialect, would double the parity
+ * surface, and would make the "one SQL path" property of the DSL false. The join
+ * is a `Map` over at most `limits.maxRows` rows on each side.
+ *
+ * Everything in this module is pure: rows in, rows out. It never runs a query —
+ * the collector does that twice and hands both results here.
+ *
+ * ## Which rows are joined
+ *
+ * On the **key columns**: the output columns of the grouping dimensions (the
+ * query's, or the metric's own grain). A `bucket`-grain metric's axis is
+ * deliberately *not* a key — two ranges have different buckets, so joining on
+ * them would produce two disjoint sets and zero matches. Its buckets are
+ * collapsed per key instead, and the per-bucket values feed
+ * {@link import("./significance.js").welchT} as two samples, which is the one
+ * place a t-test on this data is honest.
+ *
+ * A key present on one side only is still a row: `previous: null` is an arrival
+ * and `current: null` a disappearance, and both are usually the answer.
+ *
+ * ## Significance, only where it is earned
+ *
+ * For a count or session measure the row's share of its window is a proportion,
+ * so a pooled two-proportion z answers "is this share different" — and that is
+ * computed only when both windows clear the metric's `comparable.minSample`.
+ * For anything else (`fps`, a ratio, a duration average) the field is **absent**
+ * rather than guessed, and a caveat says why. An agent that is handed a p-value
+ * will quote it; handing it one that the data cannot support is worse than
+ * handing it none.
+ */
+import { getMetric } from "@uptimizr/metrics";
+import { axisColumn, columnsOf, labelColumn, measureColumn, numberAt, sampleSizeOf, } from "../summary/columns.js";
+import { formatNumber, formatShare } from "../summary/format.js";
+import { isAdditiveUnit } from "../summary/format.js";
+import { sampleOf, twoProportionZ, welchT, } from "./significance.js";
+/** A key's identity as one string, so it can index a `Map`. */
+function keyOf(row, keys) {
+    return keys.map((column) => `${column}=${String(row[column] ?? "")}`).join("\u0000");
+}
+/** The key columns' values, as the row reports them. */
+function keyValues(row, keys) {
+    const out = {};
+    for (const column of keys)
+        out[column] = String(row[column] ?? "");
+    return out;
+}
+/** What `total` counts, and whether it may be summed at all. */
+function measureOf(metric) {
+    const column = measureColumn(metric);
+    if (column == null)
+        return null;
+    const [name, semantics] = column;
+    return { column: name, unit: semantics.unit ?? null, additive: isAdditiveUnit(semantics.unit) };
+}
+/** One side's rows, collapsed to one value per key. */
+function collapse(rows, keys, column, additive) {
+    const out = new Map();
+    for (const row of rows) {
+        const id = keyOf(row, keys);
+        const value = column == null ? null : numberAt(row, column);
+        const bucket = out.get(id) ?? { key: keyValues(row, keys), sum: 0, count: 0 };
+        if (value != null) {
+            bucket.sum += value;
+            bucket.count += 1;
+        }
+        out.set(id, bucket);
+    }
+    return new Map([...out].map(([id, bucket]) => [
+        id,
+        {
+            key: bucket.key,
+            // Several rows collapse into one key only for a `bucket`-grain metric,
+            // whose axis is not a join key. Counts add; means average, for the same
+            // reason the series summary averages them.
+            value: bucket.count === 0 ? null : additive ? bucket.sum : bucket.sum / bucket.count,
+        },
+    ]));
+}
+/** Per-bucket values of one side, for the Welch sample. */
+function bucketValues(metric, rows, column, additive) {
+    const axis = axisColumn(metric)?.[0];
+    if (axis == null || column == null)
+        return [];
+    const buckets = new Map();
+    for (const row of rows) {
+        const value = numberAt(row, column);
+        if (value == null)
+            continue;
+        const id = String(row[axis] ?? "");
+        const bucket = buckets.get(id) ?? { sum: 0, count: 0 };
+        bucket.sum += value;
+        bucket.count += 1;
+        buckets.set(id, bucket);
+    }
+    return [...buckets.values()].map((bucket) => (additive ? bucket.sum : bucket.sum / bucket.count));
+}
+/** Sum a column over rows, or `null` when nothing was measurable. */
+function totalOf(rows, column) {
+    if (column == null)
+        return null;
+    let total = 0;
+    let seen = false;
+    for (const row of rows) {
+        const value = numberAt(row, column);
+        if (value == null)
+            continue;
+        seen = true;
+        total += value;
+    }
+    return seen ? total : null;
+}
+/**
+ * The dimension output columns two sides of a comparison are joined on.
+ *
+ * Deliberately the *dimensions*, not "every non-numeric column": a metric's row
+ * can carry descriptive text (a scene name next to a scene id) that is not part
+ * of its identity, and joining on it would split a key in two whenever the
+ * description changed between the two windows.
+ */
+export function comparisonKeys(metric, columns) {
+    // Only a real `axis: true` column is excluded. `axisColumn` falls back to the
+    // label for metrics that declare none, and the label is exactly what a
+    // leaderboard comparison must join on — dropping it would collapse every mesh
+    // into one unkeyed row.
+    const axis = columnsOf(metric).find(([, semantics]) => semantics.axis === true)?.[0];
+    return columns.filter((column) => column !== axis);
+}
+/**
+ * Join two runs of the same spec into one comparison.
+ *
+ * `current` and `previous` are the rows each run produced, already coerced by
+ * the store edge. Neither array is mutated, and nothing here reads a clock or a
+ * store.
+ */
+export function compareRows(metric, current, previous, ctx) {
+    const definition = typeof metric === "string" ? getMetric(metric) : metric;
+    if (definition == null)
+        return null;
+    const measure = measureOf(definition);
+    const column = measure?.column;
+    const additive = measure?.additive === true;
+    const keys = [...ctx.keys];
+    const currentTotal = totalOf(current, column);
+    const previousTotal = totalOf(previous, column);
+    const currentByKey = collapse(current, keys, column, additive);
+    const previousByKey = collapse(previous, keys, column, additive);
+    // A proportion test needs a denominator that means something: a count or a
+    // session count, present on both sides, and past the metric's own minimum.
+    const minSample = definition.comparable?.minSample ?? 0;
+    const proportional = (measure?.unit === "count" || measure?.unit === "sessions") &&
+        currentTotal != null &&
+        previousTotal != null &&
+        currentTotal >= minSample &&
+        previousTotal >= minSample &&
+        currentTotal > 0 &&
+        previousTotal > 0;
+    const ids = new Set([...currentByKey.keys(), ...previousByKey.keys()]);
+    const rows = [];
+    for (const id of ids) {
+        const left = currentByKey.get(id);
+        const right = previousByKey.get(id);
+        const key = left?.key ?? right?.key ?? {};
+        const currentValue = left?.value ?? null;
+        const previousValue = right?.value ?? null;
+        const delta = currentValue != null && previousValue != null ? currentValue - previousValue : null;
+        const significance = proportional && currentValue != null && previousValue != null
+            ? twoProportionZ({ successes: currentValue, trials: currentTotal }, { successes: previousValue, trials: previousTotal })
+            : null;
+        rows.push({
+            key,
+            label: keys.map((name) => String(key[name] ?? "")).join(" · "),
+            current: currentValue,
+            previous: previousValue,
+            delta,
+            deltaPct: delta != null && previousValue != null && previousValue > 0 ? delta / previousValue : null,
+            ...(significance != null ? { significance } : {}),
+        });
+    }
+    // Biggest absolute movement first, then alphabetically, so the order is a
+    // function of the data rather than of iteration order.
+    rows.sort((a, b) => {
+        const left = Math.abs(a.delta ?? 0);
+        const right = Math.abs(b.delta ?? 0);
+        if (left !== right)
+            return right - left;
+        return a.label < b.label ? -1 : a.label > b.label ? 1 : 0;
+    });
+    const overall = definition.grain === "bucket" && measure != null && !measure.additive
+        ? welchOf(definition, current, previous, column, additive)
+        : null;
+    const cap = ctx.limit ?? definition.limits.maxRows;
+    const truncated = Number.isFinite(cap) && (current.length >= cap || previous.length >= cap);
+    const caveats = [...definition.caveats, ...(ctx.caveats ?? [])];
+    if (!proportional) {
+        caveats.push(measure?.unit === "count" || measure?.unit === "sessions"
+            ? `Neither window reaches the ${minSample}-${measure.unit === "sessions" ? "session" : "event"} ` +
+                "minimum this metric declares, so no significance is reported — read the deltas as " +
+                "direction only."
+            : "This metric's measure is not a count, so a row's share of the window is not a " +
+                "proportion and no significance test applies. The deltas are still exact.");
+    }
+    if (truncated) {
+        caveats.push(`One or both windows hit the ${cap}-row cap, so a key missing from a side may be truncated ` +
+            "rather than absent.");
+    }
+    if (keys.length === 0) {
+        caveats.push("This metric has no dimension key, so the comparison is a single total per window.");
+    }
+    return {
+        meta: {
+            metric: definition.id,
+            basis: ctx.basis,
+            keys,
+            measure,
+            current: {
+                range: ctx.currentRange,
+                segment: { ...(ctx.currentSegment ?? {}) },
+                rows: current.length,
+                total: currentTotal,
+                sampleSize: sampleSizeOf(definition, current),
+            },
+            previous: {
+                range: ctx.previousRange,
+                segment: { ...(ctx.previousSegment ?? {}) },
+                rows: previous.length,
+                total: previousTotal,
+                sampleSize: sampleSizeOf(definition, previous),
+            },
+            rows: rows.length,
+            truncated,
+            ...(overall != null ? { overall } : {}),
+            caveats,
+        },
+        rows,
+    };
+}
+/** Welch's t over the two windows' per-bucket values. */
+function welchOf(metric, current, previous, column, additive) {
+    const left = sampleOf(bucketValues(metric, current, column, additive));
+    const right = sampleOf(bucketValues(metric, previous, column, additive));
+    if (left == null || right == null)
+        return null;
+    return welchT(left, right);
+}
+/**
+ * The headline when one side has no rows at all.
+ *
+ * "The two windows cannot be totalled" would be true and useless: what actually
+ * happened is that one of them is empty, and saying which is the whole answer —
+ * a metric that appeared or disappeared between two windows is the single most
+ * interesting thing a comparison can report.
+ */
+function emptySideHeadline(title, measure, meta) {
+    const side = meta.basis === "range" ? "window" : "segment";
+    if (meta.current.total != null) {
+        return (`${title}: \`${measure}\` totalled ${formatNumber(meta.current.total)} in this ${side}, ` +
+            `and the comparison ${side} has no rows at all — everything here is new.`);
+    }
+    if (meta.previous.total != null) {
+        return (`${title}: this ${side} has no rows at all, against ${formatNumber(meta.previous.total)} ` +
+            `in the comparison ${side} — everything there has gone.`);
+    }
+    return `${title}: neither ${side} has any \`${measure}\` to compare.`;
+}
+/** How a delta reads in prose. */
+function movement(delta) {
+    if (delta == null)
+        return "changed";
+    if (delta > 0)
+        return "rose";
+    if (delta < 0)
+        return "fell";
+    return "held";
+}
+/**
+ * Turn a comparison into the bounded `format=summary` digest: the rows that
+ * moved most, and one sentence that says what happened.
+ *
+ * The sentence is templated from the registry's column semantics — the measure's
+ * name and unit, the metric's `comparable.direction` — and never written by a
+ * model, so two identical results always read identically.
+ */
+export function summarizeComparison(metric, comparison, ctx = {}) {
+    const definition = typeof metric === "string" ? getMetric(metric) : metric;
+    if (definition == null)
+        return null;
+    const cap = Math.max(0, ctx.maxRows ?? definition.limits.maxSummaryRows);
+    const top = comparison.rows.slice(0, cap);
+    const restRows = comparison.rows.slice(cap);
+    const restDelta = restRows.reduce((sum, row) => (row.delta == null ? sum : (sum ?? 0) + row.delta), null);
+    const { meta } = comparison;
+    const measureName = meta.measure?.column ?? "the measure";
+    const totalDelta = meta.current.total != null && meta.previous.total != null
+        ? meta.current.total - meta.previous.total
+        : null;
+    const totalPct = totalDelta != null && meta.previous.total != null && meta.previous.total > 0
+        ? totalDelta / meta.previous.total
+        : null;
+    const window = meta.basis === "range" ? "against the comparison window" : "against the comparison segment";
+    const headline = totalDelta == null
+        ? emptySideHeadline(definition.title, measureName, meta)
+        : `${definition.title}: \`${measureName}\` ${movement(totalDelta)} from ` +
+            `${formatNumber(meta.previous.total)} to ${formatNumber(meta.current.total)} ` +
+            `(${totalDelta >= 0 ? "+" : ""}${formatNumber(totalDelta)}` +
+            `${totalPct == null ? "" : `, ${totalPct >= 0 ? "+" : ""}${formatShare(totalPct)}`}) ${window}.`;
+    const biggest = top[0];
+    const mover = biggest == null || biggest.delta == null || biggest.label.length === 0
+        ? ""
+        : ` Biggest mover: ${labelNoun(definition)} \`${biggest.label}\`, ` +
+            `${formatNumber(biggest.previous)} → ${formatNumber(biggest.current)} ` +
+            `(${biggest.delta >= 0 ? "+" : ""}${formatNumber(biggest.delta)})` +
+            `${biggest.significance?.test === "two-proportion-z"
+                ? biggest.significance.significant
+                    ? `, significant at p = ${formatPValue(biggest.significance.pValue)}`
+                    : `, not significant (p = ${formatPValue(biggest.significance.pValue)})`
+                : ""}.`;
+    const trend = meta.overall == null
+        ? ""
+        : ` Across buckets, the mean moved ${formatNumber(meta.overall.previous)} → ` +
+            `${formatNumber(meta.overall.current)} (Welch t = ${formatNumber(meta.overall.t)}, ` +
+            `p = ${formatPValue(meta.overall.pValue)}).`;
+    return {
+        kind: "movers",
+        metric: definition.id,
+        basis: meta.basis,
+        measure: meta.measure,
+        current: meta.current,
+        previous: meta.previous,
+        top,
+        rest: { rows: restRows.length, delta: restDelta },
+        ...(meta.overall != null ? { overall: meta.overall } : {}),
+        reading: `${headline}${mover}${trend}`,
+        caveats: meta.caveats,
+    };
+}
+/** What one row of this metric is called, for the reading sentence. */
+function labelNoun(metric) {
+    return labelColumn(metric)?.[0] ?? metric.grain;
+}
+/** A p-value at three decimals, or `< 0.001` when it is smaller than that. */
+function formatPValue(p) {
+    if (!Number.isFinite(p))
+        return "n/a";
+    return p < 0.001 ? "< 0.001" : p.toFixed(3);
+}
+//# sourceMappingURL=compare.js.map

package/dist/query/dsl/compare.js.map

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

package/dist/query/dsl/compile.d.ts

@@ -0,0 +1,89 @@
+/**
+ * **The delegated query compiler** (ADR 0051 §3, design sketch §C.2, tier 1).
+ *
+ * A validated `queryV1` document becomes a `QuerySpec` by way of the metric's
+ * *existing* aggregation builder: the registry says which `build*` computes the
+ * metric, `FILTER_TARGETS` says which option field each filter drives, and the
+ * builder renders the SQL it has always rendered, through the same `Dialect`.
+ *
+ * That is the point of the delegated tier. Every registry metric is reachable
+ * through the DSL on day one at exactly the power its canned endpoint has — no
+ * second SQL path, no "DSL-only" subset of metrics, and nothing new for the
+ * cross-engine parity harness to cover, because the specs it compiles *are* the
+ * specs the parity cases already pin (`src/__tests__/queryDsl.test.ts` asserts
+ * that equality builder by builder, on all four dialects).
+ *
+ * It also means the DSL inherits the two properties that matter most and cannot
+ * be bolted on afterwards: every value reaches SQL as a bound parameter (the
+ * builders' `ParamBag`), and the returned spec carries its `metric`, so the
+ * store edge coerces the rows (`coerceRows`, ADR 0051 §2) without knowing a DSL
+ * exists.
+ *
+ * What this module does **not** do: validate. A query must already have passed
+ * `queryV1Schema` (shape) and `validateQuery` (vocabulary) — by the time it gets
+ * here, the metric exists, has a builder, accepts every filter named, and asks
+ * for a grain it can produce. The two `throw`s below are guards against a caller
+ * skipping that, not a client-facing error path.
+ */
+import { type MetricId, type QueryTier } from "@uptimizr/metrics";
+import type { QueryV1 } from "@uptimizr/schema";
+import type { Dialect } from "../dialect.js";
+import type { QuerySpec, WorldAabb } from "../types.js";
+/**
+ * The option bag an aggregation builder takes, assembled from a query. Loosely
+ * typed for the reason given on {@link import("./builders.js").AggregationBuilder}:
+ * each builder's own options are a different intersection, and what makes the
+ * bag correct is registry validation upstream, not a type here.
+ */
+export type MetricQueryOptions = Readonly<Record<string, unknown>>;
+/**
+ * The dashboard's camera-mode toggle → the `scene.cameraType` the events carry
+ * (ADR 0026). The same mapping the canned routes apply; it lives here too so a
+ * DSL query and a `?cameraMode=` request produce the identical spec.
+ */
+export declare function cameraTypeForMode(mode: "viewer" | "first-person" | undefined): string | undefined;
+/**
+ * Values a query cannot carry on its own and the caller resolves first.
+ *
+ * `region` may be the **id** of a registered scene region (ADR 0051 §2), which
+ * only a store can turn into bounds, and `cellSize` may be derived from the
+ * scene's registered extent when the caller did not pin one (ADR 0040 §1). Both
+ * are looked up by the collector before compilation, exactly as the canned
+ * spatial routes do, and passed in here.
+ */
+export interface QueryResolution {
+    /** Bounds for a `filters.region` given as a region id. */
+    region?: WorldAabb;
+    /** The effective voxel edge, when the caller left `cellSize` to the collector. */
+    cellSize?: number;
+}
+/**
+ * Turn a validated query into the option bag its builder takes.
+ *
+ * The mapping is the registry's, not this file's: for each filter the query
+ * carries, `FILTER_TARGETS[filter].field` names the option field it drives. Only
+ * two values are transformed on the way — the camera-mode toggle becomes the
+ * stored `cameraType`, and a region id becomes the bounds the caller resolved.
+ */
+export declare function toBuilderOptions(query: QueryV1, resolved?: QueryResolution, tier?: QueryTier): MetricQueryOptions;
+/**
+ * Render the `QuerySpec` for one metric and an already-assembled option bag.
+ *
+ * This is the seam the stores use: a store's `runMetric` is exactly
+ * `run<Engine>Query(compileMetric(metric, projectId, options, <engine>Dialect))`,
+ * so the DSL reaches every engine through the one code path aggregations already
+ * take — and therefore through the same parity harness and the same numeric
+ * coercion.
+ */
+export declare function compileMetric(metric: MetricId, projectId: string, options: MetricQueryOptions, dialect: Dialect): QuerySpec;
+/**
+ * Compile a validated query end to end: filters → option bag → the metric's
+ * builder (or the generic one) → a `QuerySpec`.
+ *
+ * The tier is derived here rather than passed in, so a caller that has a
+ * validated query cannot compile it onto the wrong compiler; the collector,
+ * which already has the tier from `validateQuery`, may pass it to save the
+ * lookup.
+ */
+export declare function compileQuery(projectId: string, query: QueryV1, dialect: Dialect, resolved?: QueryResolution, tier?: QueryTier): QuerySpec;
+//# sourceMappingURL=compile.d.ts.map

package/dist/query/dsl/compile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../../src/query/dsl/compile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAML,KAAK,QAAQ,EACb,KAAK,SAAS,EACf,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAIxD;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAEnE;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,GAAG,cAAc,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAIjG;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,0DAA0D;IAC1D,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAoBD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,OAAO,EACd,QAAQ,GAAE,eAAoB,EAC9B,IAAI,GAAE,SAAuB,GAC5B,kBAAkB,CAoEpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,QAAQ,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,kBAAkB,EAC3B,OAAO,EAAE,OAAO,GACf,SAAS,CAmBX;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,OAAO,EAChB,QAAQ,GAAE,eAAoB,EAC9B,IAAI,CAAC,EAAE,SAAS,GACf,SAAS,CASX"}