@uptimizr/db 2.0.1 → 2.1.0

package/dist/query/dsl/significance.js

@@ -0,0 +1,224 @@
+/**
+ * **Is this change real?** — the two significance tests `compare` can justify
+ * (ADR 0051 §4, design sketch §C.2).
+ *
+ * Pure functions over numbers: no registry, no store, no I/O. They exist here
+ * rather than inline in `compare.ts` so they can be unit-tested against
+ * textbook worked examples, which is the only way to be sure a statistic is
+ * right — a plausible-looking number is exactly the failure mode this file is
+ * meant to prevent, since a model will quote whatever it is handed.
+ *
+ * Two tests, because analytics produces two shapes of measure:
+ *
+ * - {@link twoProportionZ} — a **count or rate**. "Was 40/1000 this week
+ *   different from 25/900 last week?" Pooled two-proportion z, two-sided normal
+ *   p-value, plus a Wilson score interval on each proportion (which, unlike the
+ *   Wald interval, stays inside 0..1 at the small counts a long tail produces —
+ *   the same reason the summariser already uses it).
+ * - {@link welchT} — a **mean** over two samples of unequal size and variance.
+ *   Welch's unequal-variance t-test with the Welch–Satterthwaite degrees of
+ *   freedom. It applies where the two ranges really do give two *samples*: a
+ *   `bucket`-grain metric compared range-over-range hands us one value per
+ *   bucket on each side.
+ *
+ * Neither is applied speculatively. `compare.ts` computes a significance only
+ * when the registry says the measure supports it (`unit: count | sessions`, or a
+ * `rateOf` denominator) and the denominator clears the metric's
+ * `comparable.minSample`; otherwise the field is simply absent, because
+ * "no p-value" is a far better answer than a p-value computed from a
+ * denominator that cannot support one.
+ *
+ * ## Accuracy
+ *
+ * The normal CDF uses the Abramowitz & Stegun 7.1.26 rational approximation of
+ * `erf` (|error| < 1.5e-7). The Student-t CDF uses the regularised incomplete
+ * beta function via the Lentz continued fraction (Numerical Recipes §6.4),
+ * converged to 3e-16 or 300 iterations. Both are far tighter than the third
+ * significant figure anyone reads off a p-value.
+ */
+/** The default two-sided level. */
+export const DEFAULT_ALPHA = 0.05;
+/** z for a 95% two-sided interval. */
+const Z_95 = 1.959963984540054;
+/**
+ * `erf(x)` — Abramowitz & Stegun 7.1.26. |error| < 1.5e-7, which is three
+ * orders of magnitude finer than any p-value is read to.
+ */
+function erf(x) {
+    const sign = x < 0 ? -1 : 1;
+    const z = Math.abs(x);
+    const t = 1 / (1 + 0.3275911 * z);
+    const poly = t *
+        (0.254829592 + t * (-0.284496736 + t * (1.421413741 + t * (-1.453152027 + t * 1.061405429))));
+    return sign * (1 - poly * Math.exp(-z * z));
+}
+/** The standard normal CDF, Φ(x). */
+export function normalCdf(x) {
+    return 0.5 * (1 + erf(x / Math.SQRT2));
+}
+/** `ln Γ(x)` — Lanczos approximation (g = 7, n = 9); exact to ~15 digits for x > 0. */
+function logGamma(x) {
+    const coefficients = [
+        0.99999999999980993, 676.5203681218851, -1259.1392167224028, 771.32342877765313,
+        -176.61502916214059, 12.507343278686905, -0.13857109526572012, 9.9843695780195716e-6,
+        1.5056327351493116e-7,
+    ];
+    if (x < 0.5) {
+        // Reflection, so the series stays in its convergent range.
+        return Math.log(Math.PI / Math.sin(Math.PI * x)) - logGamma(1 - x);
+    }
+    const z = x - 1;
+    let series = coefficients[0];
+    for (let i = 1; i < coefficients.length; i++)
+        series += coefficients[i] / (z + i);
+    const t = z + 7.5;
+    return 0.5 * Math.log(2 * Math.PI) + (z + 0.5) * Math.log(t) - t + Math.log(series);
+}
+/** Continued fraction for the incomplete beta function (Numerical Recipes §6.4). */
+function betaContinuedFraction(x, a, b) {
+    const tiny = 1e-30;
+    const qab = a + b;
+    const qap = a + 1;
+    const qam = a - 1;
+    let c = 1;
+    let d = 1 - (qab * x) / qap;
+    if (Math.abs(d) < tiny)
+        d = tiny;
+    d = 1 / d;
+    let h = d;
+    for (let m = 1; m <= 300; m++) {
+        const m2 = 2 * m;
+        let numerator = (m * (b - m) * x) / ((qam + m2) * (a + m2));
+        d = 1 + numerator * d;
+        if (Math.abs(d) < tiny)
+            d = tiny;
+        c = 1 + numerator / c;
+        if (Math.abs(c) < tiny)
+            c = tiny;
+        d = 1 / d;
+        h *= d * c;
+        numerator = (-(a + m) * (qab + m) * x) / ((a + m2) * (qap + m2));
+        d = 1 + numerator * d;
+        if (Math.abs(d) < tiny)
+            d = tiny;
+        c = 1 + numerator / c;
+        if (Math.abs(c) < tiny)
+            c = tiny;
+        d = 1 / d;
+        const delta = d * c;
+        h *= delta;
+        if (Math.abs(delta - 1) < 3e-16)
+            break;
+    }
+    return h;
+}
+/** The regularised incomplete beta function `I_x(a, b)`. */
+function incompleteBeta(x, a, b) {
+    if (x <= 0)
+        return 0;
+    if (x >= 1)
+        return 1;
+    const front = Math.exp(logGamma(a + b) - logGamma(a) - logGamma(b) + a * Math.log(x) + b * Math.log(1 - x));
+    return x < (a + 1) / (a + b + 2)
+        ? (front * betaContinuedFraction(x, a, b)) / a
+        : 1 - (front * betaContinuedFraction(1 - x, b, a)) / b;
+}
+/** The two-sided p-value of a Student-t statistic with `df` degrees of freedom. */
+export function studentTTwoSided(t, df) {
+    if (!Number.isFinite(t) || !Number.isFinite(df) || df <= 0)
+        return 1;
+    const x = df / (df + t * t);
+    return incompleteBeta(x, df / 2, 0.5);
+}
+/**
+ * A Wilson score interval on `successes / trials`.
+ *
+ * The same interval the summary envelope reports, restated here so this module
+ * stays free of the summariser (and vice versa): both need it, neither should
+ * import the other.
+ */
+export function wilsonScoreInterval(successes, trials, z = Z_95) {
+    if (trials <= 0)
+        return { low: 0, high: 1 };
+    const p = successes / trials;
+    const denominator = 1 + (z * z) / trials;
+    const centre = p + (z * z) / (2 * trials);
+    const spread = z * Math.sqrt((p * (1 - p)) / trials + (z * z) / (4 * trials * trials));
+    return {
+        low: Math.max(0, (centre - spread) / denominator),
+        high: Math.min(1, (centre + spread) / denominator),
+    };
+}
+/**
+ * Pooled two-proportion z test: is `current.successes / current.trials`
+ * different from `previous.successes / previous.trials`?
+ *
+ * Returns `null` when either side has no trials — a proportion of nothing is not
+ * a proportion, and reporting `z = 0` for it would read as "no change" when the
+ * truth is "no data".
+ */
+export function twoProportionZ(current, previous, alpha = DEFAULT_ALPHA) {
+    if (current.trials <= 0 || previous.trials <= 0)
+        return null;
+    const p1 = current.successes / current.trials;
+    const p2 = previous.successes / previous.trials;
+    const pooled = (current.successes + previous.successes) / (current.trials + previous.trials);
+    const standardError = Math.sqrt(pooled * (1 - pooled) * (1 / current.trials + 1 / previous.trials));
+    // Two identical proportions at 0 or 1 give a zero standard error; the honest
+    // statistic there is z = 0 (no evidence of a difference), not a division by
+    // zero that would surface as NaN and be rendered as "null" downstream.
+    const z = standardError === 0 ? 0 : (p1 - p2) / standardError;
+    const pValue = 2 * (1 - normalCdf(Math.abs(z)));
+    return {
+        test: "two-proportion-z",
+        current: p1,
+        previous: p2,
+        diff: p1 - p2,
+        z,
+        pValue,
+        significant: pValue < alpha,
+        currentInterval: wilsonScoreInterval(current.successes, current.trials),
+        previousInterval: wilsonScoreInterval(previous.successes, previous.trials),
+    };
+}
+/** Mean and unbiased variance of a list of observations; `null` below two. */
+export function sampleOf(values) {
+    const finite = values.filter((value) => Number.isFinite(value));
+    if (finite.length < 2)
+        return null;
+    const mean = finite.reduce((sum, value) => sum + value, 0) / finite.length;
+    const variance = finite.reduce((sum, value) => sum + (value - mean) * (value - mean), 0) / (finite.length - 1);
+    return { mean, variance, n: finite.length };
+}
+/**
+ * Welch's unequal-variance t test with the Welch–Satterthwaite degrees of
+ * freedom.
+ *
+ * Returns `null` when either sample has fewer than two observations (there is no
+ * variance to test) or when both variances are zero and the means are equal.
+ */
+export function welchT(current, previous, alpha = DEFAULT_ALPHA) {
+    if (current.n < 2 || previous.n < 2)
+        return null;
+    const sc = current.variance / current.n;
+    const sp = previous.variance / previous.n;
+    const denominator = Math.sqrt(sc + sp);
+    if (denominator === 0)
+        return null;
+    const t = (current.mean - previous.mean) / denominator;
+    const df = ((sc + sp) * (sc + sp)) / ((sc * sc) / (current.n - 1) + (sp * sp) / (previous.n - 1));
+    const pValue = studentTTwoSided(t, df);
+    return {
+        test: "welch-t",
+        current: current.mean,
+        previous: previous.mean,
+        diff: current.mean - previous.mean,
+        t,
+        df,
+        pValue,
+        significant: pValue < alpha,
+        currentSamples: current.n,
+        previousSamples: previous.n,
+    };
+}
+//# sourceMappingURL=significance.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"significance.js","sourceRoot":"","sources":["../../../src/query/dsl/significance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAyDH,mCAAmC;AACnC,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,CAAC;AAElC,sCAAsC;AACtC,MAAM,IAAI,GAAG,iBAAiB,CAAC;AAE/B;;;GAGG;AACH,SAAS,GAAG,CAAC,CAAS;IACpB,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5B,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACtB,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,SAAS,GAAG,CAAC,CAAC,CAAC;IAClC,MAAM,IAAI,GACR,CAAC;QACD,CAAC,WAAW,GAAG,CAAC,GAAG,CAAC,CAAC,WAAW,GAAG,CAAC,GAAG,CAAC,WAAW,GAAG,CAAC,GAAG,CAAC,CAAC,WAAW,GAAG,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;IAChG,OAAO,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAC9C,CAAC;AAED,qCAAqC;AACrC,MAAM,UAAU,SAAS,CAAC,CAAS;IACjC,OAAO,GAAG,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;AACzC,CAAC;AAED,uFAAuF;AACvF,SAAS,QAAQ,CAAC,CAAS;IACzB,MAAM,YAAY,GAAG;QACnB,mBAAmB,EAAE,iBAAiB,EAAE,CAAC,kBAAkB,EAAE,kBAAkB;QAC/E,CAAC,kBAAkB,EAAE,kBAAkB,EAAE,CAAC,mBAAmB,EAAE,qBAAqB;QACpF,qBAAqB;KACtB,CAAC;IACF,IAAI,CAAC,GAAG,GAAG,EAAE,CAAC;QACZ,2DAA2D;QAC3D,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACrE,CAAC;IACD,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAChB,IAAI,MAAM,GAAG,YAAY,CAAC,CAAC,CAAW,CAAC;IACvC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,YAAY,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,MAAM,IAAK,YAAY,CAAC,CAAC,CAAY,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9F,MAAM,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;IAClB,OAAO,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AACtF,CAAC;AAED,oFAAoF;AACpF,SAAS,qBAAqB,CAAC,CAAS,EAAE,CAAS,EAAE,CAAS;IAC5D,MAAM,IAAI,GAAG,KAAK,CAAC;IACnB,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;IAClB,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;IAClB,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;IAClB,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC;IAC5B,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI;QAAE,CAAC,GAAG,IAAI,CAAC;IACjC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACV,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;QAC9B,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;QACjB,IAAI,SAAS,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QAC5D,CAAC,GAAG,CAAC,GAAG,SAAS,GAAG,CAAC,CAAC;QACtB,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI;YAAE,CAAC,GAAG,IAAI,CAAC;QACjC,CAAC,GAAG,CAAC,GAAG,SAAS,GAAG,CAAC,CAAC;QACtB,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI;YAAE,CAAC,GAAG,IAAI,CAAC;QACjC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACV,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACX,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC,CAAC;QACjE,CAAC,GAAG,CAAC,GAAG,SAAS,GAAG,CAAC,CAAC;QACtB,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI;YAAE,CAAC,GAAG,IAAI,CAAC;QACjC,CAAC,GAAG,CAAC,GAAG,SAAS,GAAG,CAAC,CAAC;QACtB,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI;YAAE,CAAC,GAAG,IAAI,CAAC;QACjC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACV,MAAM,KAAK,GAAG,CAAC,GAAG,CAAC,CAAC;QACpB,CAAC,IAAI,KAAK,CAAC;QACX,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,KAAK;YAAE,MAAM;IACzC,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,4DAA4D;AAC5D,SAAS,cAAc,CAAC,CAAS,EAAE,CAAS,EAAE,CAAS;IACrD,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IACrB,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IACrB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CACpB,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CACpF,CAAC;IACF,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC9B,CAAC,CAAC,CAAC,KAAK,GAAG,qBAAqB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;QAC9C,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,GAAG,qBAAqB,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;AAC3D,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,gBAAgB,CAAC,CAAS,EAAE,EAAU;IACpD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IACrE,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5B,OAAO,cAAc,CAAC,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC;AACxC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CACjC,SAAiB,EACjB,MAAc,EACd,IAAY,IAAI;IAEhB,IAAI,MAAM,IAAI,CAAC;QAAE,OAAO,EAAE,GAAG,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;IAC5C,MAAM,CAAC,GAAG,SAAS,GAAG,MAAM,CAAC;IAC7B,MAAM,WAAW,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC;IACzC,MAAM,MAAM,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC;IAC1C,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC;IACvF,OAAO;QACL,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,GAAG,WAAW,CAAC;QACjD,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,GAAG,WAAW,CAAC;KACnD,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAC5B,OAAmB,EACnB,QAAoB,EACpB,QAAgB,aAAa;IAE7B,IAAI,OAAO,CAAC,MAAM,IAAI,CAAC,IAAI,QAAQ,CAAC,MAAM,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAC7D,MAAM,EAAE,GAAG,OAAO,CAAC,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC;IAC9C,MAAM,EAAE,GAAG,QAAQ,CAAC,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC;IAChD,MAAM,MAAM,GAAG,CAAC,OAAO,CAAC,SAAS,GAAG,QAAQ,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC7F,MAAM,aAAa,GAAG,IAAI,CAAC,IAAI,CAC7B,MAAM,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,CACnE,CAAC;IACF,6EAA6E;IAC7E,4EAA4E;IAC5E,uEAAuE;IACvE,MAAM,CAAC,GAAG,aAAa,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,aAAa,CAAC;IAC9D,MAAM,MAAM,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAChD,OAAO;QACL,IAAI,EAAE,kBAAkB;QACxB,OAAO,EAAE,EAAE;QACX,QAAQ,EAAE,EAAE;QACZ,IAAI,EAAE,EAAE,GAAG,EAAE;QACb,CAAC;QACD,MAAM;QACN,WAAW,EAAE,MAAM,GAAG,KAAK;QAC3B,eAAe,EAAE,mBAAmB,CAAC,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC;QACvE,gBAAgB,EAAE,mBAAmB,CAAC,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC;KAC3E,CAAC;AACJ,CAAC;AAWD,8EAA8E;AAC9E,MAAM,UAAU,QAAQ,CAAC,MAAyB;IAChD,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;IAChE,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,GAAG,GAAG,KAAK,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC;IAC3E,MAAM,QAAQ,GACZ,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAChG,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;AAC9C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,MAAM,CACpB,OAAe,EACf,QAAgB,EAChB,QAAgB,aAAa;IAE7B,IAAI,OAAO,CAAC,CAAC,GAAG,CAAC,IAAI,QAAQ,CAAC,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACjD,MAAM,EAAE,GAAG,OAAO,CAAC,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC;IACxC,MAAM,EAAE,GAAG,QAAQ,CAAC,QAAQ,GAAG,QAAQ,CAAC,CAAC,CAAC;IAC1C,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC;IACvC,IAAI,WAAW,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,WAAW,CAAC;IACvD,MAAM,EAAE,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAClG,MAAM,MAAM,GAAG,gBAAgB,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACvC,OAAO;QACL,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,OAAO,CAAC,IAAI;QACrB,QAAQ,EAAE,QAAQ,CAAC,IAAI;QACvB,IAAI,EAAE,OAAO,CAAC,IAAI,GAAG,QAAQ,CAAC,IAAI;QAClC,CAAC;QACD,EAAE;QACF,MAAM;QACN,WAAW,EAAE,MAAM,GAAG,KAAK;QAC3B,cAAc,EAAE,OAAO,CAAC,CAAC;QACzB,eAAe,EAAE,QAAQ,CAAC,CAAC;KAC5B,CAAC;AACJ,CAAC"}

package/dist/query/index.d.ts

@@ -19,7 +19,9 @@ export * from "./relational.js";
 export * from "./postgresDialect.js";
 export * from "./mssqlDialect.js";
 export * from "./aggregations.js";
+export * from "./customEventVocabulary.js";
 export { toEventRow, formatUtcTimestamp, toNodeSampleRow, nodeSampleRowToEvent, } from "../events.js";
 export type { EventRow, NodeSampleRow, SessionMeta } from "../events.js";
 export { DUCKDB_MIGRATIONS } from "../duckdb/migrations.js";
+export * from "./dsl/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/query/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/query/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,cAAc,YAAY,CAAC;AAG3B,cAAc,cAAc,CAAC;AAG7B,cAAc,oBAAoB,CAAC;AAKnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAGlC,cAAc,mBAAmB,CAAC;AAGlC,OAAO,EACL,UAAU,EACV,kBAAkB,EAClB,eAAe,EACf,oBAAoB,GACrB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,QAAQ,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAMzE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/query/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,cAAc,YAAY,CAAC;AAG3B,cAAc,cAAc,CAAC;AAG7B,cAAc,oBAAoB,CAAC;AAKnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAGlC,cAAc,mBAAmB,CAAC;AAKlC,cAAc,4BAA4B,CAAC;AAG3C,OAAO,EACL,UAAU,EACV,kBAAkB,EAClB,eAAe,EACf,oBAAoB,GACrB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,QAAQ,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAMzE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAK5D,cAAc,gBAAgB,CAAC"}

package/dist/query/index.js

@@ -26,6 +26,10 @@ export * from "./postgresDialect.js";
 export * from "./mssqlDialect.js";
 // Every `build*` aggregation (renders a QuerySpec for a given Dialect).
 export * from "./aggregations.js";
+// The custom-event vocabulary fold (ADR 0051 §5): the pure half of
+// `buildCustomEventVocabulary`, which turns the sampled payloads into prop keys
+// and coarse types. No I/O, no dialect — browser-safe like the builders.
+export * from "./customEventVocabulary.js";
 // Engine-neutral event → row mapping (isomorphic; imports only @uptimizr/schema).
 export { toEventRow, formatUtcTimestamp, toNodeSampleRow, nodeSampleRowToEvent, } from "../events.js";
 // The DuckDB schema DDL. `migrations.ts` only imports the `DuckdbClient` *type*
@@ -33,4 +37,8 @@ export { toEventRow, formatUtcTimestamp, toNodeSampleRow, nodeSampleRowToEvent,
 // DuckDB-Wasm database. Re-exported here so the in-browser store stays a single
 // source of truth with the Node store (no duplicated/drifting schema).
 export { DUCKDB_MIGRATIONS } from "../duckdb/migrations.js";
+// The delegated query-DSL compiler (ADR 0051 §3). Pure: it reads the metric
+// registry and renders a `QuerySpec` through the same builders above, so it is
+// browser-safe for the same reason they are.
+export * from "./dsl/index.js";
 //# sourceMappingURL=index.js.map

package/dist/query/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/query/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,8DAA8D;AAC9D,cAAc,YAAY,CAAC;AAE3B,mDAAmD;AACnD,cAAc,cAAc,CAAC;AAE7B,+CAA+C;AAC/C,cAAc,oBAAoB,CAAC;AAEnC,+EAA+E;AAC/E,8EAA8E;AAC9E,kBAAkB;AAClB,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAElC,wEAAwE;AACxE,cAAc,mBAAmB,CAAC;AAElC,kFAAkF;AAClF,OAAO,EACL,UAAU,EACV,kBAAkB,EAClB,eAAe,EACf,oBAAoB,GACrB,MAAM,cAAc,CAAC;AAGtB,gFAAgF;AAChF,+EAA+E;AAC/E,gFAAgF;AAChF,uEAAuE;AACvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/query/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,8DAA8D;AAC9D,cAAc,YAAY,CAAC;AAE3B,mDAAmD;AACnD,cAAc,cAAc,CAAC;AAE7B,+CAA+C;AAC/C,cAAc,oBAAoB,CAAC;AAEnC,+EAA+E;AAC/E,8EAA8E;AAC9E,kBAAkB;AAClB,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAElC,wEAAwE;AACxE,cAAc,mBAAmB,CAAC;AAElC,mEAAmE;AACnE,gFAAgF;AAChF,yEAAyE;AACzE,cAAc,4BAA4B,CAAC;AAE3C,kFAAkF;AAClF,OAAO,EACL,UAAU,EACV,kBAAkB,EAClB,eAAe,EACf,oBAAoB,GACrB,MAAM,cAAc,CAAC;AAGtB,gFAAgF;AAChF,+EAA+E;AAC/E,gFAAgF;AAChF,uEAAuE;AACvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE5D,4EAA4E;AAC5E,+EAA+E;AAC/E,6CAA6C;AAC7C,cAAc,gBAAgB,CAAC"}

package/dist/query/summary/index.d.ts

@@ -10,10 +10,12 @@ export { summarizeRows, tableResult } from "./summarize.js";
 export type { ResultRow } from "./summarize.js";
 export { clusterCells } from "./cluster.js";
 export type { ClusterOptions, ClusterResult, GridCell } from "./cluster.js";
+export { isWorldSpatialMetric, labelClusters, labelPoint, worldAxisMap } from "./labels.js";
+export type { LabelOptions, LabelledClusters } from "./labels.js";
 export { wilsonInterval, leastSquaresSlope, trendOf, Z_95 } from "./stats.js";
 export { sampleSizeOf } from "./columns.js";
 export { isAdditiveUnit } from "./format.js";
 export { RESULT_FORMATS } from "./types.js";
-export type { AppliedFilters, ClusterRest, ClusterSummary, DrillHints, RankedRow, RankedSummary, RecordSummary, ResolvedRate, RestBucket, ResultFormat, ResultLimits, ResultRange, ResultSummary, SampleSize, SeriesDigest, SeriesSummary, ShareInterval, SpatialCluster, SummaryBase, SummaryConfidence, SummaryContext, SummaryMeasure, TableMeta, TableResult, TrendDirection, } from "./types.js";
-export { resultEnvelopeSchema, resultFormatSchema, resultSummarySchema, tableResultSchema, } from "./schema.js";
+export type { AppliedFilters, ClusterRest, ClusterSummary, DrillHints, DrillQuery, RankedRow, RankedSummary, RecordSummary, ResolvedRate, RestBucket, ResultFormat, ResultLimits, ResultRange, ResultSummary, SampleSize, SeriesDigest, SeriesSummary, ShareInterval, SpatialCluster, SpatialLabel, SpatialScene, SummaryBase, SummaryConfidence, SummaryContext, SummaryMeasure, TableMeta, TableResult, TrendDirection, } from "./types.js";
+export { comparisonResultSchema, moversSummarySchema, queryEnvelopeSchema, queryPlanSchema, resultEnvelopeSchema, resultFormatSchema, resultSummarySchema, tableResultSchema, } from "./schema.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/query/summary/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/query/summary/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC5D,YAAY,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC5E,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAC9E,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,YAAY,EACV,cAAc,EACd,WAAW,EACX,cAAc,EACd,UAAU,EACV,SAAS,EACT,aAAa,EACb,aAAa,EACb,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,aAAa,EACb,UAAU,EACV,YAAY,EACZ,aAAa,EACb,aAAa,EACb,cAAc,EACd,WAAW,EACX,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,SAAS,EACT,WAAW,EACX,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/query/summary/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC5D,YAAY,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC5E,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC5F,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAC9E,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,YAAY,EACV,cAAc,EACd,WAAW,EACX,cAAc,EACd,UAAU,EACV,UAAU,EACV,SAAS,EACT,aAAa,EACb,aAAa,EACb,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,aAAa,EACb,UAAU,EACV,YAAY,EACZ,aAAa,EACb,aAAa,EACb,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,SAAS,EACT,WAAW,EACX,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,sBAAsB,EACtB,mBAAmB,EACnB,mBAAmB,EACnB,eAAe,EACf,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,aAAa,CAAC"}

package/dist/query/summary/index.js

@@ -8,9 +8,10 @@
  */
 export { summarizeRows, tableResult } from "./summarize.js";
 export { clusterCells } from "./cluster.js";
+export { isWorldSpatialMetric, labelClusters, labelPoint, worldAxisMap } from "./labels.js";
 export { wilsonInterval, leastSquaresSlope, trendOf, Z_95 } from "./stats.js";
 export { sampleSizeOf } from "./columns.js";
 export { isAdditiveUnit } from "./format.js";
 export { RESULT_FORMATS } from "./types.js";
-export { resultEnvelopeSchema, resultFormatSchema, resultSummarySchema, tableResultSchema, } from "./schema.js";
+export { comparisonResultSchema, moversSummarySchema, queryEnvelopeSchema, queryPlanSchema, resultEnvelopeSchema, resultFormatSchema, resultSummarySchema, tableResultSchema, } from "./schema.js";
 //# sourceMappingURL=index.js.map

package/dist/query/summary/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/query/summary/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE5D,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAC9E,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AA4B5C,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/query/summary/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE5D,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE5F,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAC9E,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AA+B5C,OAAO,EACL,sBAAsB,EACtB,mBAAmB,EACnB,mBAAmB,EACnB,eAAe,EACf,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,aAAa,CAAC"}

package/dist/query/summary/labels.d.ts

@@ -0,0 +1,101 @@
+/**
+ * **Spatial labelling** of summary clusters (ADR 0051 §2, design sketch §B.2).
+ *
+ * A hotspot reported as "centred at (-6.2, 0, 8.4)" tells a language model
+ * nothing it can act on. The scene registry already knows the vocabulary that
+ * would: the proxy's per-mesh AABBs (ADR 0010/0014) name the geometry, and the
+ * scene's **regions** (`sceneRegionSchema`) name the places a developer cares
+ * about. This module joins the two onto a cluster so the same hotspot reads
+ * "near `checkout_button`, in region `counter`".
+ *
+ * Four fields are attached, and each is defensible on its own:
+ *
+ * | field         | rule                                                              |
+ * | ------------- | ----------------------------------------------------------------- |
+ * | `region`      | the **smallest** region (by volume) whose box contains the centroid |
+ * | `regions`     | *every* containing region id, ascending — regions may overlap       |
+ * | `nearestMesh` | a proxy box containing the centroid, else the nearest box centre    |
+ * | `distance`    | world units to that mesh's centre; `0` when the box contains it     |
+ *
+ * A mesh match is only reported when it is close enough to mean something: a
+ * non-containing box must have its centre within `cellSize × 2` of the centroid,
+ * the width of the cell the hotspot was binned into either side. Beyond that the
+ * answer is `null` — "there is nothing here" is information, and a confidently
+ * wrong landmark is worse than none.
+ *
+ * ## Determinism
+ *
+ * Everything here is a pure function of the *sets* it is given. Ties are broken
+ * by id / name ascending (never by array order), volumes and distances are
+ * compared as plain numbers, and no accumulation happens across boxes — so the
+ * same scene and the same clusters always produce the same labels, whatever
+ * order the store, the registry table or the proxy listed their rows in.
+ *
+ * ## Cost
+ *
+ * `O(clusters × boxes)`, with an early exit: a box whose expanded bounds (its
+ * own box grown by the mesh threshold) do not contain the centroid can neither
+ * contain it nor have its centre within the threshold, so it is rejected after
+ * at most three comparisons without any distance math. With a summary capped at
+ * `maxSummaryRows` clusters and a proxy capped at `LIMITS.maxSceneProxyMeshes`
+ * boxes, the whole labelling pass is bounded — `__tests__/spatialLabels.test.ts`
+ * holds the largest shape to under 50 ms.
+ *
+ * Pure and browser-safe: no I/O, no `node:` import, no store reference. The
+ * collector loads the regions and the proxy once per request and hands them in.
+ */
+import type { MetricDefinition } from "@uptimizr/metrics";
+import type { SpatialCluster, SpatialLabel, SpatialScene } from "./types.js";
+/**
+ * Map a cluster summary's grid axes onto world axes, or `null` when the grid is
+ * not world-space. A 2-axis `gx`/`gz` grid maps to X and Z: the labelling then
+ * tests containment and distance **in the ground plane only**, which is what a
+ * ground-binned metric actually measured.
+ */
+export declare function worldAxisMap(axes: readonly string[]): (0 | 1 | 2)[] | null;
+/**
+ * Whether a metric summarises as clusters on a **world-space** grid, and so is
+ * worth loading a scene's regions and proxy for. Lets the collector skip the two
+ * registry reads for the grids that could never be labelled — the viewport
+ * pointer/UV bins and the angular view-direction grid — without teaching the
+ * Fastify layer which grids those are.
+ */
+export declare function isWorldSpatialMetric(metric: MetricDefinition): boolean;
+/**
+ * Label one world-space point against a scene's regions and proxy meshes.
+ *
+ * `point` carries one coordinate per entry of `axes`, already in world units.
+ * `meshThreshold` is how far a *non-containing* mesh box's centre may be and
+ * still be reported (the collector passes `cellSize × 2`); pass `0` to accept
+ * containment only.
+ */
+export declare function labelPoint(point: readonly number[], scene: SpatialScene, axes: readonly (0 | 1 | 2)[], meshThreshold: number): SpatialLabel;
+/** What {@link labelClusters} produced: the labelled clusters and what it could not do. */
+export interface LabelledClusters {
+    clusters: SpatialCluster[];
+    /** Caveats naming what the scene did not register; empty when both are present. */
+    caveats: string[];
+    /** Whether anything was actually labelled (false when the grid is not world-space). */
+    labelled: boolean;
+}
+/** Everything {@link labelClusters} needs about the request that produced them. */
+export interface LabelOptions {
+    /** The metric's grid axis column names, in order (`["vx","vy","vz"]`). */
+    axes: readonly string[];
+    /** The effective world size of one cell (ADR 0040 §1). */
+    cellSize: number;
+    /** The scene's registered regions and proxy meshes. */
+    scene: SpatialScene;
+}
+/**
+ * Attach `region` / `regions` / `nearestMesh` / `distance` to each cluster, and
+ * upgrade the `drill.region` hint from an ad-hoc world box to the **region id**
+ * when a registered region contains the hotspot — the id is the shared name both
+ * a human and `?region=<id>` understand, so it is strictly the better hint.
+ *
+ * Returns the clusters untouched (and `labelled: false`) when the grid is not
+ * world-space or no cell size is known: a viewport-bin or angular grid has no
+ * world point to label, and saying so is the honest answer.
+ */
+export declare function labelClusters(clusters: readonly SpatialCluster[], options: LabelOptions): LabelledClusters;
+//# sourceMappingURL=labels.d.ts.map

package/dist/query/summary/labels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"labels.d.ts","sourceRoot":"","sources":["../../../src/query/summary/labels.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAsB7E;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,IAAI,CAU1E;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAItE;AAmED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE,SAAS,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,EAC5B,aAAa,EAAE,MAAM,GACpB,YAAY,CA6Dd;AAED,2FAA2F;AAC3F,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B,mFAAmF;IACnF,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,uFAAuF;IACvF,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,mFAAmF;AACnF,MAAM,WAAW,YAAY;IAC3B,0EAA0E;IAC1E,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,KAAK,EAAE,YAAY,CAAC;CACrB;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,SAAS,cAAc,EAAE,EACnC,OAAO,EAAE,YAAY,GACpB,gBAAgB,CAwClB"}