@uptimizr/db 2.0.1 → 2.1.0

package/dist/query/summary/labels.js

@@ -0,0 +1,261 @@
+/**
+ * **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 { gridColumns } from "./columns.js";
+/**
+ * Which **world** axis each grid axis indexes, for the registry's `unit: "index"`
+ * column names. `null` for a grid that is not world-space at all — the pointer
+ * and mesh-UV grids (`gx`/`gy`) are normalised viewport/UV cells and the
+ * view-direction grid is angular, so a world box would be a category error.
+ *
+ * Only the two world-space shapes are labelled: the voxel grids (`vx/vy/vz`) and
+ * the ground-plane bins (`gx/gz`), which index X and Z with no Y at all.
+ */
+const WORLD_AXES = {
+    vx: 0,
+    vy: 1,
+    vz: 2,
+    gx: 0,
+    gz: 2,
+};
+/**
+ * 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 function worldAxisMap(axes) {
+    if (axes.length === 0)
+        return null;
+    const mapped = [];
+    for (const axis of axes) {
+        const world = WORLD_AXES[axis];
+        if (world == null)
+            return null;
+        mapped.push(world);
+    }
+    // A repeated world axis would make containment meaningless.
+    return new Set(mapped).size === mapped.length ? mapped : 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 function isWorldSpatialMetric(metric) {
+    if (metric.grain !== "bin" && metric.grain !== "voxel")
+        return false;
+    const axes = gridColumns(metric, metric.grain === "voxel" ? 3 : 2);
+    return axes != null && worldAxisMap(axes.map(([name]) => name)) != null;
+}
+/** Volume of a box over the axes under test; `0` for a degenerate box. */
+function volumeOf(box, axes) {
+    let volume = 1;
+    for (const axis of axes) {
+        const min = box[axis] ?? 0;
+        const max = box[axis + 3] ?? 0;
+        volume *= Math.max(0, max - min);
+    }
+    return volume;
+}
+/** Whether `point` (indexed by the same axes) lies inside `box`, inclusive. */
+function contains(box, point, axes) {
+    for (let i = 0; i < axes.length; i++) {
+        const axis = axes[i];
+        const value = point[i];
+        if (value < (box[axis] ?? 0) || value > (box[axis + 3] ?? 0))
+            return false;
+    }
+    return true;
+}
+/** Squared distance from `point` to the centre of `box`, over the tested axes. */
+function centreDistanceSq(box, point, axes) {
+    let sum = 0;
+    for (let i = 0; i < axes.length; i++) {
+        const axis = axes[i];
+        const centre = ((box[axis] ?? 0) + (box[axis + 3] ?? 0)) / 2;
+        const delta = point[i] - centre;
+        sum += delta * delta;
+    }
+    return sum;
+}
+/**
+ * The early exit: a box grown by `slack` on every tested axis must still contain
+ * the point, or it can neither contain the point nor have its centre within
+ * `slack` of it (the centre is at least the overhang plus the half-extent away).
+ * Three comparisons, no square root, no allocation.
+ */
+function withinSlack(box, point, axes, slack) {
+    for (let i = 0; i < axes.length; i++) {
+        const axis = axes[i];
+        const value = point[i];
+        if (value < (box[axis] ?? 0) - slack || value > (box[axis + 3] ?? 0) + slack)
+            return false;
+    }
+    return true;
+}
+/** Nothing known: the shape a cluster gets when the scene registers neither. */
+const UNLABELLED = {
+    region: null,
+    regions: [],
+    nearestMesh: null,
+    distance: null,
+};
+/**
+ * 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 function labelPoint(point, scene, axes, meshThreshold) {
+    const regions = scene.regions ?? [];
+    const meshes = scene.meshes ?? [];
+    if (regions.length === 0 && meshes.length === 0)
+        return UNLABELLED;
+    // Regions: every containing box (ids ascending), smallest by volume reported.
+    const containing = [];
+    let smallestId = null;
+    let smallestVolume = Number.POSITIVE_INFINITY;
+    for (const region of regions) {
+        if (!contains(region.bounds, point, axes))
+            continue;
+        containing.push(region.id);
+        const volume = volumeOf(region.bounds, axes);
+        // `<` keeps the first of equal volumes; the id sort below makes that stable.
+        if (volume < smallestVolume || (volume === smallestVolume && region.id < (smallestId ?? ""))) {
+            smallestVolume = volume;
+            smallestId = region.id;
+        }
+    }
+    containing.sort();
+    // Meshes: a containing box wins outright (smallest, so a prop inside a room
+    // beats the room); otherwise the nearest centre inside the threshold.
+    let containedName = null;
+    let containedVolume = Number.POSITIVE_INFINITY;
+    let nearestName = null;
+    let nearestDistanceSq = Number.POSITIVE_INFINITY;
+    const thresholdSq = meshThreshold * meshThreshold;
+    for (const mesh of meshes) {
+        if (!withinSlack(mesh.aabb, point, axes, meshThreshold))
+            continue;
+        if (contains(mesh.aabb, point, axes)) {
+            const volume = volumeOf(mesh.aabb, axes);
+            if (volume < containedVolume ||
+                (volume === containedVolume && mesh.name < (containedName ?? ""))) {
+                containedVolume = volume;
+                containedName = mesh.name;
+            }
+            continue;
+        }
+        // Only worth measuring while nothing contains the point.
+        if (containedName != null)
+            continue;
+        const distanceSq = centreDistanceSq(mesh.aabb, point, axes);
+        if (distanceSq > thresholdSq)
+            continue;
+        if (distanceSq < nearestDistanceSq ||
+            (distanceSq === nearestDistanceSq && mesh.name < (nearestName ?? ""))) {
+            nearestDistanceSq = distanceSq;
+            nearestName = mesh.name;
+        }
+    }
+    const nearestMesh = containedName ?? nearestName;
+    return {
+        region: smallestId,
+        regions: containing,
+        nearestMesh,
+        distance: nearestMesh == null ? null : containedName != null ? 0 : Math.sqrt(nearestDistanceSq),
+    };
+}
+/**
+ * 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 function labelClusters(clusters, options) {
+    const { axes, cellSize, scene } = options;
+    const axisMap = worldAxisMap(axes);
+    const regions = scene.regions ?? [];
+    const meshes = scene.meshes ?? [];
+    if (axisMap == null || !(cellSize > 0) || !Number.isFinite(cellSize)) {
+        return { clusters: [...clusters], caveats: [], labelled: false };
+    }
+    const caveats = [];
+    if (meshes.length === 0) {
+        caveats.push(`No proxy registered for scene ${scene.id == null ? "(unnamed)" : `\`${scene.id}\``} — ` +
+            "`nearestMesh` and `distance` are unavailable. Register one with the SDK's " +
+            "`scanSceneProxy` so hotspots can name the geometry they sit on.");
+    }
+    if (regions.length === 0) {
+        caveats.push(`No regions defined for scene ${scene.id == null ? "(unnamed)" : `\`${scene.id}\``} — ` +
+            "`region` is null. Declare named boxes with `registerRegions` to give spatial answers a " +
+            "vocabulary.");
+    }
+    const threshold = cellSize * 2;
+    const labelledClusters = clusters.map((cluster) => {
+        // A cluster's centroid is a weighted mean of cell *indices*; the world point
+        // is the centre of that fractional cell (ADR 0040 §1).
+        const point = cluster.centroid.map((index) => (index + 0.5) * cellSize);
+        const label = labelPoint(point, scene, axisMap, threshold);
+        const drill = label.region != null ? { ...cluster.drill, region: label.region } : cluster.drill;
+        return {
+            ...cluster,
+            ...(drill != null ? { drill } : {}),
+            ...label,
+        };
+    });
+    return { clusters: labelledClusters, caveats, labelled: true };
+}
+//# sourceMappingURL=labels.js.map

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

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

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

@@ -1 +1 @@
-{"version":3,"file":"reading.d.ts","sourceRoot":"","sources":["../../../src/query/summary/reading.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAU1D,OAAO,KAAK,EAIV,aAAa,EAGd,MAAM,YAAY,CAAC;AA+JpB;;;;GAIG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,GAAG,aAAa,IAAI,CAAC,SAAS,OAAO,GAAG,IAAI,CAAC,CAAC,EAAE,SAAS,CAAC,GAAG,KAAK,CAAC;AAE9F,kFAAkF;AAClF,wBAAgB,UAAU,CAAC,MAAM,EAAE,gBAAgB,EAAE,OAAO,EAAE,aAAa,GAAG,MAAM,CAWnF"}
+{"version":3,"file":"reading.d.ts","sourceRoot":"","sources":["../../../src/query/summary/reading.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAU1D,OAAO,KAAK,EAIV,aAAa,EAId,MAAM,YAAY,CAAC;AAkLpB;;;;GAIG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,GAAG,aAAa,IAAI,CAAC,SAAS,OAAO,GAAG,IAAI,CAAC,CAAC,EAAE,SAAS,CAAC,GAAG,KAAK,CAAC;AAE9F,kFAAkF;AAClF,wBAAgB,UAAU,CAAC,MAAM,EAAE,gBAAgB,EAAE,OAAO,EAAE,aAAa,GAAG,MAAM,CAWnF"}

package/dist/query/summary/reading.js

@@ -93,6 +93,25 @@ function seriesReading(metric, summary) {
         `${formatQuantity(series.max, unit)} at ${formatLabel(series.maxLabel)}.` +
         sampleSentence(summary.sampleSize));
 }
+/**
+ * Where a hotspot is **in the scene's own words** (ADR 0051 §2, sketch §B.2):
+ * "near `checkout_button` in region `counter` ". Returns `""` when the scene
+ * registered nothing that could name it, so the sentence falls back to the grid
+ * coordinate it has always reported. The trailing space is deliberate — the
+ * caller concatenates it straight onto "centred at", and an unlabelled cluster
+ * must produce byte-identical text to before.
+ */
+function placeOf(cluster) {
+    const parts = [];
+    if (cluster.nearestMesh != null) {
+        // `distance === 0` means the mesh box contains the centroid — "on" rather
+        // than "near", because the hotspot is literally there.
+        parts.push(`${cluster.distance === 0 ? "on" : "near"} \`${cluster.nearestMesh}\``);
+    }
+    if (cluster.region != null)
+        parts.push(`in region \`${cluster.region}\``);
+    return parts.length === 0 ? "" : `${parts.join(" ")}, `;
+}
 function clusterReading(metric, summary) {
     const cellNoun = grainNoun(metric.grain, summary.occupiedCells);
     if (summary.occupiedCells === 0)
@@ -111,8 +130,8 @@ function clusterReading(metric, summary) {
     let text = `${metric.title}: ${formatNumber(summary.clusters.length)} ` +
         `hotspot${summary.clusters.length === 1 ? "" : "s"} over ` +
         `${formatNumber(summary.occupiedCells)} occupied ${cellNoun}. The densest spans ` +
-        `${extent} ${cellNoun} centred at (${centroid}) on ${summary.axes.join("/")}, holding ` +
-        `${formatQuantity(densest.weight, weightUnit)}`;
+        `${extent} ${cellNoun} ${placeOf(densest)}centred at (${centroid}) on ` +
+        `${summary.axes.join("/")}, holding ${formatQuantity(densest.weight, weightUnit)}`;
     text += densest.share == null ? "." : ` (${formatShare(densest.share)}).`;
     // Only name the part of `rest` that actually exists — "0 further clusters" is
     // noise in a sentence meant to be read at a glance.

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

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

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

@@ -1,30 +1,24 @@
 /**
- * Zod mirrors of the three result envelopes.
+ * Zod mirrors of the three result envelopes — **re-exported**, not redefined.
  *
  * The collector attaches each route's 200 response schema from the registry so
  * the Zod type provider **serialises through it** — which means the `table` and
  * `summary` envelopes need schemas too, or a formatted response would be
- * stripped down to nothing on its way out. `resultEnvelopeSchema(row)` builds
- * the union a formatted route responds with: the untouched `full` shape first,
- * so a default request is validated by exactly the schema it has always been
- * validated by, then the two envelopes.
+ * stripped down to nothing on its way out. `resultEnvelopeSchema(full, row)`
+ * builds the union a formatted route responds with: the untouched `full` shape
+ * first, so a default request is validated by exactly the schema it has always
+ * been validated by, then the two envelopes.
  *
- * These live next to the types rather than in the collector so the shapes have
- * one definition — the same reason the row schemas live in the registry.
+ * The definitions themselves now live in `@uptimizr/metrics`, next to the row
+ * schemas they wrap (#350): `@uptimizr/agent-core` and `@uptimizr/mcp` need the
+ * same shapes to describe a tool's result, and neither may depend on this
+ * package — it carries the DuckDB driver. This module keeps the names and the
+ * signatures `@uptimizr/db` has always exported, so nothing downstream changes.
  */
 import { z } from "zod";
+import { resultFormatSchema } from "@uptimizr/metrics";
 import type { ResultFormat } from "./types.js";
-/**
- * `format=full | table | summary`, the shared querystring value every
- * registry-served aggregate endpoint accepts. Spelled out literally rather than
- * built from `RESULT_FORMATS` so the inferred type is the `ResultFormat` union
- * and a route handler keeps its narrowing.
- */
-export declare const resultFormatSchema: z.ZodEnum<{
-    table: "table";
-    full: "full";
-    summary: "summary";
-}>;
+export { resultFormatSchema };
 /** Fails to compile if the schema and {@link ResultFormat} ever drift apart. */
 type AssertFormatsAgree = [
     z.infer<typeof resultFormatSchema> extends ResultFormat ? true : never,
@@ -43,6 +37,7 @@ export declare const resultSummarySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             high: z.ZodNumber;
         }, z.core.$strip>>;
         drill: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        drillQuery: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, z.core.$strip>>;
     rest: z.ZodObject<{
         rows: z.ZodNumber;
@@ -88,9 +83,9 @@ export declare const resultSummarySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         minLabel: z.ZodNullable<z.ZodString>;
         maxLabel: z.ZodNullable<z.ZodString>;
         trend: z.ZodEnum<{
-            flat: "flat";
             up: "up";
             down: "down";
+            flat: "flat";
         }>;
         slope: z.ZodNullable<z.ZodNumber>;
     }, z.core.$strip>;
@@ -134,6 +129,10 @@ export declare const resultSummarySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         weight: z.ZodNumber;
         share: z.ZodNullable<z.ZodNumber>;
         drill: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        region: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        regions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        nearestMesh: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        distance: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     }, z.core.$strip>>;
     rest: z.ZodObject<{
         clusters: z.ZodNumber;
@@ -211,7 +210,238 @@ export declare function tableResultSchema(row: z.ZodType): z.ZodObject;
  * The envelopes are unambiguous against it — `table` is an object with `meta`
  * and `rows`, `summary` an object with `kind` and `reading`, and neither can
  * satisfy a row array or a stats row's required numeric columns.
+ *
+ * A route's own `full` schema is passed explicitly because a single-record
+ * endpoint (the spatial `stats` routes) answers with a bare object rather than
+ * an array of rows.
  */
 export declare function resultEnvelopeSchema(full: z.ZodType, row: z.ZodType): z.ZodType;
-export {};
+/** `format=full | table` on a `compare` query: the envelope plus joined rows. */
+export declare const comparisonResultSchema: z.ZodObject<{
+    meta: z.ZodObject<{
+        metric: z.ZodEnum<{
+            [x: string]: string;
+        }>;
+        basis: z.ZodEnum<{
+            range: "range";
+            segment: "segment";
+        }>;
+        keys: z.ZodArray<z.ZodString>;
+        measure: z.ZodNullable<z.ZodObject<{
+            column: z.ZodString;
+            unit: z.ZodNullable<z.ZodString>;
+            additive: z.ZodBoolean;
+        }, z.core.$strip>>;
+        current: z.ZodObject<{
+            range: z.ZodObject<{
+                since: z.ZodNullable<z.ZodNumber>;
+                until: z.ZodNullable<z.ZodNumber>;
+            }, z.core.$strip>;
+            segment: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            rows: z.ZodNumber;
+            total: z.ZodNullable<z.ZodNumber>;
+            sampleSize: z.ZodObject<{
+                sessions: z.ZodNullable<z.ZodNumber>;
+                events: z.ZodNullable<z.ZodNumber>;
+            }, z.core.$strip>;
+        }, z.core.$strip>;
+        previous: z.ZodObject<{
+            range: z.ZodObject<{
+                since: z.ZodNullable<z.ZodNumber>;
+                until: z.ZodNullable<z.ZodNumber>;
+            }, z.core.$strip>;
+            segment: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            rows: z.ZodNumber;
+            total: z.ZodNullable<z.ZodNumber>;
+            sampleSize: z.ZodObject<{
+                sessions: z.ZodNullable<z.ZodNumber>;
+                events: z.ZodNullable<z.ZodNumber>;
+            }, z.core.$strip>;
+        }, z.core.$strip>;
+        rows: z.ZodNumber;
+        truncated: z.ZodBoolean;
+        overall: z.ZodOptional<z.ZodObject<{
+            test: z.ZodLiteral<"welch-t">;
+            current: z.ZodNumber;
+            previous: z.ZodNumber;
+            diff: z.ZodNumber;
+            t: z.ZodNumber;
+            df: z.ZodNumber;
+            pValue: z.ZodNumber;
+            significant: z.ZodBoolean;
+            currentSamples: z.ZodNumber;
+            previousSamples: z.ZodNumber;
+        }, z.core.$strip>>;
+        caveats: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+    rows: z.ZodArray<z.ZodObject<{
+        key: z.ZodRecord<z.ZodString, z.ZodString>;
+        label: z.ZodString;
+        current: z.ZodNullable<z.ZodNumber>;
+        previous: z.ZodNullable<z.ZodNumber>;
+        delta: z.ZodNullable<z.ZodNumber>;
+        deltaPct: z.ZodNullable<z.ZodNumber>;
+        significance: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            test: z.ZodLiteral<"two-proportion-z">;
+            current: z.ZodNumber;
+            previous: z.ZodNumber;
+            diff: z.ZodNumber;
+            z: z.ZodNumber;
+            pValue: z.ZodNumber;
+            significant: z.ZodBoolean;
+            currentInterval: z.ZodObject<{
+                low: z.ZodNumber;
+                high: z.ZodNumber;
+            }, z.core.$strip>;
+            previousInterval: z.ZodObject<{
+                low: z.ZodNumber;
+                high: z.ZodNumber;
+            }, z.core.$strip>;
+        }, z.core.$strip>, z.ZodObject<{
+            test: z.ZodLiteral<"welch-t">;
+            current: z.ZodNumber;
+            previous: z.ZodNumber;
+            diff: z.ZodNumber;
+            t: z.ZodNumber;
+            df: z.ZodNumber;
+            pValue: z.ZodNumber;
+            significant: z.ZodBoolean;
+            currentSamples: z.ZodNumber;
+            previousSamples: z.ZodNumber;
+        }, z.core.$strip>], "test">>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** `format=summary` on a `compare` query: the biggest movers, with a reading. */
+export declare const moversSummarySchema: z.ZodObject<{
+    kind: z.ZodLiteral<"movers">;
+    metric: z.ZodEnum<{
+        [x: string]: string;
+    }>;
+    basis: z.ZodEnum<{
+        range: "range";
+        segment: "segment";
+    }>;
+    measure: z.ZodNullable<z.ZodObject<{
+        column: z.ZodString;
+        unit: z.ZodNullable<z.ZodString>;
+        additive: z.ZodBoolean;
+    }, z.core.$strip>>;
+    current: z.ZodObject<{
+        range: z.ZodObject<{
+            since: z.ZodNullable<z.ZodNumber>;
+            until: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strip>;
+        segment: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        rows: z.ZodNumber;
+        total: z.ZodNullable<z.ZodNumber>;
+        sampleSize: z.ZodObject<{
+            sessions: z.ZodNullable<z.ZodNumber>;
+            events: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    previous: z.ZodObject<{
+        range: z.ZodObject<{
+            since: z.ZodNullable<z.ZodNumber>;
+            until: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strip>;
+        segment: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        rows: z.ZodNumber;
+        total: z.ZodNullable<z.ZodNumber>;
+        sampleSize: z.ZodObject<{
+            sessions: z.ZodNullable<z.ZodNumber>;
+            events: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    top: z.ZodArray<z.ZodObject<{
+        key: z.ZodRecord<z.ZodString, z.ZodString>;
+        label: z.ZodString;
+        current: z.ZodNullable<z.ZodNumber>;
+        previous: z.ZodNullable<z.ZodNumber>;
+        delta: z.ZodNullable<z.ZodNumber>;
+        deltaPct: z.ZodNullable<z.ZodNumber>;
+        significance: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            test: z.ZodLiteral<"two-proportion-z">;
+            current: z.ZodNumber;
+            previous: z.ZodNumber;
+            diff: z.ZodNumber;
+            z: z.ZodNumber;
+            pValue: z.ZodNumber;
+            significant: z.ZodBoolean;
+            currentInterval: z.ZodObject<{
+                low: z.ZodNumber;
+                high: z.ZodNumber;
+            }, z.core.$strip>;
+            previousInterval: z.ZodObject<{
+                low: z.ZodNumber;
+                high: z.ZodNumber;
+            }, z.core.$strip>;
+        }, z.core.$strip>, z.ZodObject<{
+            test: z.ZodLiteral<"welch-t">;
+            current: z.ZodNumber;
+            previous: z.ZodNumber;
+            diff: z.ZodNumber;
+            t: z.ZodNumber;
+            df: z.ZodNumber;
+            pValue: z.ZodNumber;
+            significant: z.ZodBoolean;
+            currentSamples: z.ZodNumber;
+            previousSamples: z.ZodNumber;
+        }, z.core.$strip>], "test">>;
+    }, z.core.$strip>>;
+    rest: z.ZodObject<{
+        rows: z.ZodNumber;
+        delta: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>;
+    overall: z.ZodOptional<z.ZodObject<{
+        test: z.ZodLiteral<"welch-t">;
+        current: z.ZodNumber;
+        previous: z.ZodNumber;
+        diff: z.ZodNumber;
+        t: z.ZodNumber;
+        df: z.ZodNumber;
+        pValue: z.ZodNumber;
+        significant: z.ZodBoolean;
+        currentSamples: z.ZodNumber;
+        previousSamples: z.ZodNumber;
+    }, z.core.$strip>>;
+    reading: z.ZodString;
+    caveats: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * `explain: true`: the plan instead of the rows.
+ *
+ * `params` carries names and logical types only — never values. That is not a
+ * redaction step applied afterwards; the DSL binds every caller-supplied value,
+ * so there is nothing in `sql` to redact and nothing in `params` worth echoing.
+ */
+export declare const queryPlanSchema: z.ZodObject<{
+    metric: z.ZodEnum<{
+        [x: string]: string;
+    }>;
+    tier: z.ZodEnum<{
+        delegated: "delegated";
+        generic: "generic";
+    }>;
+    dialect: z.ZodString;
+    sql: z.ZodString;
+    params: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodString;
+    }, z.core.$strip>>;
+    rowsScanned: z.ZodNullable<z.ZodNumber>;
+    sampleSize: z.ZodObject<{
+        sessions: z.ZodNullable<z.ZodNumber>;
+        events: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>;
+    warnings: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * The 200 response schema of the query DSL endpoint: everything
+ * {@link resultEnvelopeSchema} answers with, plus the three envelopes only the
+ * DSL can produce — a comparison, a movers digest and a plan.
+ *
+ * Order matters for the same reason it does there: the plain-rows shape is
+ * matched first so a `format=full` response cannot be reshaped on its way out.
+ */
+export declare function queryEnvelopeSchema(full: z.ZodType, row: z.ZodType): z.ZodType;
 //# sourceMappingURL=schema.d.ts.map