@uptimizr/db 1.0.2 → 2.0.0

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

@@ -0,0 +1,19 @@
+/**
+ * `format=table | summary` result envelopes (ADR 0051 §2, design sketch §B.1).
+ *
+ * Pure, registry-driven and browser-safe — no store, no I/O, no `node:` import —
+ * so the same code shapes a collector response, a CLI result and (eventually) an
+ * in-browser demo store's output. Re-exported from both `@uptimizr/db` and the
+ * browser-safe `@uptimizr/db/query` subpath.
+ */
+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 { 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";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +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"}

package/dist/query/summary/index.js

@@ -0,0 +1,16 @@
+/**
+ * `format=table | summary` result envelopes (ADR 0051 §2, design sketch §B.1).
+ *
+ * Pure, registry-driven and browser-safe — no store, no I/O, no `node:` import —
+ * so the same code shapes a collector response, a CLI result and (eventually) an
+ * in-browser demo store's output. Re-exported from both `@uptimizr/db` and the
+ * browser-safe `@uptimizr/db/query` subpath.
+ */
+export { summarizeRows, tableResult } from "./summarize.js";
+export { clusterCells } from "./cluster.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";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,26 @@
+/**
+ * The `reading` sentence: one plain-English statement of what the result says,
+ * assembled **only** from the registry's column semantics (design sketch §B.1).
+ *
+ * No model is involved, and none may be: `reading` is part of a deterministic
+ * API response, so the same rows have to produce the same words on every engine
+ * and every process. Everything it can say is therefore a function of the
+ * metric's `title`, `grain`, and the `unit` / `label` / `measure` / `axis` / `rateOf`
+ * flags on its columns — which is exactly the information the registry exists to
+ * hold.
+ *
+ * The one hard rule enforced by `__tests__/summary.test.ts`: a `reading` never
+ * contains `undefined` or `NaN`. Every number goes through the total formatters
+ * in `format.ts`, which render a missing or non-finite value as `n/a`.
+ */
+import type { MetricDefinition } from "@uptimizr/metrics";
+import type { ResultSummary } from "./types.js";
+/**
+ * A summary that has everything but its sentence. Distributive, so the `kind`
+ * discriminant survives — a bare `Omit<ResultSummary, "reading">` would collapse
+ * the union to its common keys and lose the switch below.
+ */
+export type UnreadSummary<T = ResultSummary> = T extends unknown ? Omit<T, "reading"> : never;
+/** The templated `reading` for a summary that has everything but its sentence. */
+export declare function readingFor(metric: MetricDefinition, summary: UnreadSummary): string;
+//# sourceMappingURL=reading.d.ts.map

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

@@ -0,0 +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"}

package/dist/query/summary/reading.js

@@ -0,0 +1,169 @@
+/**
+ * The `reading` sentence: one plain-English statement of what the result says,
+ * assembled **only** from the registry's column semantics (design sketch §B.1).
+ *
+ * No model is involved, and none may be: `reading` is part of a deterministic
+ * API response, so the same rows have to produce the same words on every engine
+ * and every process. Everything it can say is therefore a function of the
+ * metric's `title`, `grain`, and the `unit` / `label` / `measure` / `axis` / `rateOf`
+ * flags on its columns — which is exactly the information the registry exists to
+ * hold.
+ *
+ * The one hard rule enforced by `__tests__/summary.test.ts`: a `reading` never
+ * contains `undefined` or `NaN`. Every number goes through the total formatters
+ * in `format.ts`, which render a missing or non-finite value as `n/a`.
+ */
+import { measureColumn } from "./columns.js";
+import { formatLabel, formatNumber, formatQuantity, formatShare, grainNoun, humanizeColumn, } from "./format.js";
+/** "Sample: 412 sessions over 9,130 events." — omitted when nothing is known. */
+function sampleSentence(sample) {
+    const parts = [];
+    if (sample.sessions != null)
+        parts.push(`${formatNumber(sample.sessions)} sessions`);
+    if (sample.events != null)
+        parts.push(`${formatNumber(sample.events)} events`);
+    if (parts.length === 0)
+        return "";
+    return ` Sample: ${parts.join(" over ")}.`;
+}
+/** The empty-result sentence, shared by every grain. */
+function nothingMatched(metric) {
+    return `${metric.title}: no rows matched the selected range and filters.`;
+}
+function rankedReading(metric, summary) {
+    if (summary.top.length === 0)
+        return nothingMatched(metric);
+    const measure = measureColumn(metric);
+    const unit = measure?.[1].unit;
+    const [first, second] = summary.top;
+    if (measure == null || first == null) {
+        const rows = summary.top.length + summary.rest.rows;
+        return (`${metric.title}: ${formatNumber(rows)} ${grainNoun(metric.grain, rows)} returned in store ` +
+            `order; the metric declares no measure column, so they cannot be ranked.` +
+            sampleSentence(summary.sampleSize));
+    }
+    const measureName = humanizeColumn(measure[0]);
+    let text = `${metric.title}: ${formatLabel(first.label)} leads on ${measureName} with ${formatQuantity(first.value, unit)}`;
+    if (first.share != null) {
+        text += ` (${formatShare(first.share)} of ${formatQuantity(summary.total, unit)})`;
+    }
+    if (second != null) {
+        text += `, followed by ${formatLabel(second.label)} with ${formatQuantity(second.value, unit)}`;
+        if (second.share != null)
+            text += ` (${formatShare(second.share)})`;
+    }
+    text += ".";
+    if (summary.rest.rows > 0) {
+        const held = summary.rest.share != null
+            ? formatShare(summary.rest.share)
+            : formatQuantity(summary.rest.value, unit);
+        text +=
+            ` The remaining ${formatNumber(summary.rest.rows)} ` +
+                `${grainNoun(metric.grain, summary.rest.rows)} hold ${held}.`;
+    }
+    if (summary.measure != null && !summary.measure.additive) {
+        const unitPhrase = summary.measure.unit == null
+            ? "not an additive quantity"
+            : `measured in ${summary.measure.unit}`;
+        text +=
+            ` Shares are not reported: ${measureName} is ${unitPhrase} and cannot be summed across ` +
+                `${grainNoun(metric.grain, 2)}.`;
+    }
+    return text + sampleSentence(summary.sampleSize);
+}
+function seriesReading(metric, summary) {
+    const { series } = summary;
+    if (series.points === 0)
+        return nothingMatched(metric);
+    const measure = measureColumn(metric);
+    const unit = measure?.[1].unit;
+    const measureName = measure == null ? "the measure" : humanizeColumn(measure[0]);
+    const axisName = humanizeColumn(series.axis);
+    if (series.points === 1) {
+        return (`${metric.title}: a single ${axisName} (${formatLabel(series.firstLabel)}) with ` +
+            `${measureName} ${formatQuantity(series.first, unit)} — too few points for a trend.` +
+            sampleSentence(summary.sampleSize));
+    }
+    const slope = series.slope == null ? "" : `, ${formatNumber(series.slope)} per ${axisName}`;
+    return (`${metric.title}: ${measureName} moved from ${formatQuantity(series.first, unit)} at ` +
+        `${formatLabel(series.firstLabel)} to ${formatQuantity(series.last, unit)} at ` +
+        `${formatLabel(series.lastLabel)} across ${formatNumber(series.points)} ` +
+        `${grainNoun("bucket", series.points)} — trend ${series.trend}${slope}. ` +
+        `Low ${formatQuantity(series.min, unit)} at ${formatLabel(series.minLabel)}, high ` +
+        `${formatQuantity(series.max, unit)} at ${formatLabel(series.maxLabel)}.` +
+        sampleSentence(summary.sampleSize));
+}
+function clusterReading(metric, summary) {
+    const cellNoun = grainNoun(metric.grain, summary.occupiedCells);
+    if (summary.occupiedCells === 0)
+        return nothingMatched(metric);
+    const densest = summary.clusters[0];
+    if (densest == null) {
+        return (`${metric.title}: ${formatNumber(summary.occupiedCells)} occupied ${cellNoun}, none of ` +
+            `which reached the density threshold of ${formatNumber(summary.densityThreshold)}.` +
+            sampleSentence(summary.sampleSize));
+    }
+    const centroid = densest.centroid.map((value) => formatNumber(value)).join(", ");
+    const extent = densest.extent.min
+        .map((min, axis) => formatNumber((densest.extent.max[axis] ?? min) - min + 1))
+        .join("x");
+    const weightUnit = summary.measure?.unit;
+    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)}`;
+    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.
+    const rest = [];
+    if (summary.rest.clusters > 0) {
+        rest.push(`${formatNumber(summary.rest.clusters)} further cluster${summary.rest.clusters === 1 ? "" : "s"}`);
+    }
+    if (summary.rest.cells > 0) {
+        rest.push(`${formatNumber(summary.rest.cells)} looser ${grainNoun(metric.grain, summary.rest.cells)}`);
+    }
+    if (rest.length > 0) {
+        text += ` ${rest.join(" and ")} hold ${formatShare(summary.rest.share)}.`;
+    }
+    return text + sampleSentence(summary.sampleSize);
+}
+function recordReading(metric, summary) {
+    const columns = Object.keys(summary.record);
+    if (columns.length === 0)
+        return nothingMatched(metric);
+    const measure = measureColumn(metric);
+    let text;
+    if (measure == null) {
+        const listed = columns
+            .slice(0, 3)
+            .map((column) => `${humanizeColumn(column)} ${formatLabel(summary.record[column])}`)
+            .join(", ");
+        text = `${metric.title}: ${listed}.`;
+    }
+    else {
+        text =
+            `${metric.title}: ${humanizeColumn(measure[0])} is ` +
+                `${formatQuantity(summary.total, measure[1].unit)}.`;
+    }
+    for (const [column, rate] of Object.entries(summary.rates)) {
+        text +=
+            ` ${humanizeColumn(column)} is ${formatShare(rate.value)} of ` +
+                `${humanizeColumn(rate.denominator)}.`;
+    }
+    return text + sampleSentence(summary.sampleSize);
+}
+/** The templated `reading` for a summary that has everything but its sentence. */
+export function readingFor(metric, summary) {
+    switch (summary.kind) {
+        case "ranked":
+            return rankedReading(metric, { ...summary, reading: "" });
+        case "series":
+            return seriesReading(metric, { ...summary, reading: "" });
+        case "clusters":
+            return clusterReading(metric, { ...summary, reading: "" });
+        case "record":
+            return recordReading(metric, { ...summary, reading: "" });
+    }
+}
+//# sourceMappingURL=reading.js.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,217 @@
+/**
+ * Zod mirrors of the three result envelopes.
+ *
+ * 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.
+ *
+ * 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.
+ */
+import { z } from "zod";
+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";
+}>;
+/** Fails to compile if the schema and {@link ResultFormat} ever drift apart. */
+type AssertFormatsAgree = [
+    z.infer<typeof resultFormatSchema> extends ResultFormat ? true : never,
+    ResultFormat extends z.infer<typeof resultFormatSchema> ? true : never
+];
+export type ResultFormatsAgree = AssertFormatsAgree;
+/** `format=summary`: one of the four grain-driven shapes. */
+export declare const resultSummarySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"ranked">;
+    top: z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        value: z.ZodNullable<z.ZodNumber>;
+        share: z.ZodNullable<z.ZodNumber>;
+        shareInterval: z.ZodOptional<z.ZodObject<{
+            low: z.ZodNumber;
+            high: z.ZodNumber;
+        }, z.core.$strip>>;
+        drill: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strip>>;
+    rest: z.ZodObject<{
+        rows: z.ZodNumber;
+        value: z.ZodNullable<z.ZodNumber>;
+        share: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>;
+    metric: z.ZodEnum<{
+        [x: string]: string;
+    }>;
+    range: z.ZodObject<{
+        since: z.ZodNullable<z.ZodNumber>;
+        until: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>;
+    filters: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    sampleSize: z.ZodObject<{
+        sessions: z.ZodNullable<z.ZodNumber>;
+        events: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>;
+    total: z.ZodNullable<z.ZodNumber>;
+    measure: z.ZodNullable<z.ZodObject<{
+        column: z.ZodString;
+        unit: z.ZodNullable<z.ZodString>;
+        additive: z.ZodBoolean;
+    }, z.core.$strip>>;
+    confidence: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodLiteral<"wilson">;
+        level: z.ZodNumber;
+        note: z.ZodString;
+    }, z.core.$strip>>;
+    reading: z.ZodString;
+    caveats: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"series">;
+    series: z.ZodObject<{
+        axis: z.ZodString;
+        points: z.ZodNumber;
+        first: z.ZodNullable<z.ZodNumber>;
+        last: z.ZodNullable<z.ZodNumber>;
+        min: z.ZodNullable<z.ZodNumber>;
+        max: z.ZodNullable<z.ZodNumber>;
+        firstLabel: z.ZodNullable<z.ZodString>;
+        lastLabel: z.ZodNullable<z.ZodString>;
+        minLabel: z.ZodNullable<z.ZodString>;
+        maxLabel: z.ZodNullable<z.ZodString>;
+        trend: z.ZodEnum<{
+            flat: "flat";
+            up: "up";
+            down: "down";
+        }>;
+        slope: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>;
+    metric: z.ZodEnum<{
+        [x: string]: string;
+    }>;
+    range: z.ZodObject<{
+        since: z.ZodNullable<z.ZodNumber>;
+        until: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>;
+    filters: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    sampleSize: z.ZodObject<{
+        sessions: z.ZodNullable<z.ZodNumber>;
+        events: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>;
+    total: z.ZodNullable<z.ZodNumber>;
+    measure: z.ZodNullable<z.ZodObject<{
+        column: z.ZodString;
+        unit: z.ZodNullable<z.ZodString>;
+        additive: z.ZodBoolean;
+    }, z.core.$strip>>;
+    confidence: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodLiteral<"wilson">;
+        level: z.ZodNumber;
+        note: z.ZodString;
+    }, z.core.$strip>>;
+    reading: z.ZodString;
+    caveats: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"clusters">;
+    axes: z.ZodArray<z.ZodString>;
+    occupiedCells: z.ZodNumber;
+    densityThreshold: z.ZodNumber;
+    clusters: z.ZodArray<z.ZodObject<{
+        centroid: z.ZodArray<z.ZodNumber>;
+        extent: z.ZodObject<{
+            min: z.ZodArray<z.ZodNumber>;
+            max: z.ZodArray<z.ZodNumber>;
+        }, z.core.$strip>;
+        cells: z.ZodNumber;
+        weight: z.ZodNumber;
+        share: z.ZodNullable<z.ZodNumber>;
+        drill: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strip>>;
+    rest: z.ZodObject<{
+        clusters: z.ZodNumber;
+        cells: z.ZodNumber;
+        weight: z.ZodNullable<z.ZodNumber>;
+        share: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>;
+    metric: z.ZodEnum<{
+        [x: string]: string;
+    }>;
+    range: z.ZodObject<{
+        since: z.ZodNullable<z.ZodNumber>;
+        until: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>;
+    filters: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    sampleSize: z.ZodObject<{
+        sessions: z.ZodNullable<z.ZodNumber>;
+        events: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>;
+    total: z.ZodNullable<z.ZodNumber>;
+    measure: z.ZodNullable<z.ZodObject<{
+        column: z.ZodString;
+        unit: z.ZodNullable<z.ZodString>;
+        additive: z.ZodBoolean;
+    }, z.core.$strip>>;
+    confidence: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodLiteral<"wilson">;
+        level: z.ZodNumber;
+        note: z.ZodString;
+    }, z.core.$strip>>;
+    reading: z.ZodString;
+    caveats: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"record">;
+    record: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+    rates: z.ZodRecord<z.ZodString, z.ZodObject<{
+        value: z.ZodNullable<z.ZodNumber>;
+        numerator: z.ZodString;
+        denominator: z.ZodString;
+    }, z.core.$strip>>;
+    metric: z.ZodEnum<{
+        [x: string]: string;
+    }>;
+    range: z.ZodObject<{
+        since: z.ZodNullable<z.ZodNumber>;
+        until: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>;
+    filters: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    sampleSize: z.ZodObject<{
+        sessions: z.ZodNullable<z.ZodNumber>;
+        events: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>;
+    total: z.ZodNullable<z.ZodNumber>;
+    measure: z.ZodNullable<z.ZodObject<{
+        column: z.ZodString;
+        unit: z.ZodNullable<z.ZodString>;
+        additive: z.ZodBoolean;
+    }, z.core.$strip>>;
+    confidence: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodLiteral<"wilson">;
+        level: z.ZodNumber;
+        note: z.ZodString;
+    }, z.core.$strip>>;
+    reading: z.ZodString;
+    caveats: z.ZodArray<z.ZodString>;
+}, z.core.$strip>], "kind">;
+/** `format=table`: the `meta` envelope around a metric's own row schema. */
+export declare function tableResultSchema(row: z.ZodType): z.ZodObject;
+/**
+ * The 200 response schema of a route that honours `format`: the union of the
+ * three envelopes.
+ *
+ * Order matters. `full` is first, so a default request is parsed by precisely
+ * the schema it was parsed by before this existed and its bytes cannot drift.
+ * 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.
+ */
+export declare function resultEnvelopeSchema(full: z.ZodType, row: z.ZodType): z.ZodType;
+export {};
+//# sourceMappingURL=schema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/query/summary/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB;;;;EAAuC,CAAC;AAEvE,gFAAgF;AAChF,KAAK,kBAAkB,GAAG;IACxB,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,SAAS,YAAY,GAAG,IAAI,GAAG,KAAK;IACtE,YAAY,SAAS,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,GAAG,IAAI,GAAG,KAAK;CACvE,CAAC;AACF,MAAM,MAAM,kBAAkB,GAAG,kBAAkB,CAAC;AAoIpD,6DAA6D;AAC7D,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2BAK9B,CAAC;AAEH,4EAA4E;AAC5E,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,SAAS,CAa7D;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,CAE/E"}

package/dist/query/summary/schema.js

@@ -0,0 +1,167 @@
+/**
+ * Zod mirrors of the three result envelopes.
+ *
+ * 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.
+ *
+ * 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.
+ */
+import { z } from "zod";
+import { METRIC_IDS } from "@uptimizr/metrics";
+/**
+ * `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 const resultFormatSchema = z.enum(["full", "table", "summary"]);
+/** Any registry metric id. */
+const metricIdSchema = z.enum(METRIC_IDS);
+const rangeSchema = z.object({
+    since: z.number().nullable(),
+    until: z.number().nullable(),
+});
+/** Applied filter values are whatever the route's own schema produced. */
+const filtersSchema = z.record(z.string(), z.unknown());
+const sampleSizeSchema = z.object({
+    sessions: z.number().nullable(),
+    events: z.number().nullable(),
+});
+const limitsSchema = z.object({
+    maxRows: z.number().int(),
+    maxSummaryRows: z.number().int(),
+});
+const measureSchema = z
+    .object({
+    column: z.string(),
+    unit: z.string().nullable(),
+    additive: z.boolean(),
+})
+    .nullable();
+const shareIntervalSchema = z.object({ low: z.number(), high: z.number() });
+const confidenceSchema = z.object({
+    kind: z.literal("wilson"),
+    level: z.number(),
+    note: z.string(),
+});
+const drillSchema = z.record(z.string(), z.string());
+const restSchema = z.object({
+    rows: z.number().int(),
+    value: z.number().nullable(),
+    share: z.number().nullable(),
+});
+/** Fields every summary carries, whatever its grain. */
+const summaryBase = {
+    metric: metricIdSchema,
+    range: rangeSchema,
+    filters: filtersSchema,
+    sampleSize: sampleSizeSchema,
+    total: z.number().nullable(),
+    measure: measureSchema,
+    confidence: confidenceSchema.optional(),
+    reading: z.string(),
+    caveats: z.array(z.string()),
+};
+const rankedSummarySchema = z.object({
+    ...summaryBase,
+    kind: z.literal("ranked"),
+    top: z.array(z.object({
+        label: z.string(),
+        value: z.number().nullable(),
+        share: z.number().nullable(),
+        shareInterval: shareIntervalSchema.optional(),
+        drill: drillSchema.optional(),
+    })),
+    rest: restSchema,
+});
+const seriesSummarySchema = z.object({
+    ...summaryBase,
+    kind: z.literal("series"),
+    series: z.object({
+        axis: z.string(),
+        points: z.number().int(),
+        first: z.number().nullable(),
+        last: z.number().nullable(),
+        min: z.number().nullable(),
+        max: z.number().nullable(),
+        firstLabel: z.string().nullable(),
+        lastLabel: z.string().nullable(),
+        minLabel: z.string().nullable(),
+        maxLabel: z.string().nullable(),
+        trend: z.enum(["up", "down", "flat"]),
+        slope: z.number().nullable(),
+    }),
+});
+const clusterSummarySchema = z.object({
+    ...summaryBase,
+    kind: z.literal("clusters"),
+    axes: z.array(z.string()),
+    occupiedCells: z.number().int(),
+    densityThreshold: z.number(),
+    clusters: z.array(z.object({
+        centroid: z.array(z.number()),
+        extent: z.object({ min: z.array(z.number()), max: z.array(z.number()) }),
+        cells: z.number().int(),
+        weight: z.number(),
+        share: z.number().nullable(),
+        drill: drillSchema.optional(),
+    })),
+    rest: z.object({
+        clusters: z.number().int(),
+        cells: z.number().int(),
+        weight: z.number().nullable(),
+        share: z.number().nullable(),
+    }),
+});
+const recordSummarySchema = z.object({
+    ...summaryBase,
+    kind: z.literal("record"),
+    record: z.record(z.string(), z.union([z.string(), z.number(), z.boolean(), z.null()])),
+    rates: z.record(z.string(), z.object({
+        value: z.number().nullable(),
+        numerator: z.string(),
+        denominator: z.string(),
+    })),
+});
+/** `format=summary`: one of the four grain-driven shapes. */
+export const resultSummarySchema = z.discriminatedUnion("kind", [
+    rankedSummarySchema,
+    seriesSummarySchema,
+    clusterSummarySchema,
+    recordSummarySchema,
+]);
+/** `format=table`: the `meta` envelope around a metric's own row schema. */
+export function tableResultSchema(row) {
+    return z.object({
+        meta: z.object({
+            metric: metricIdSchema,
+            range: rangeSchema,
+            filters: filtersSchema,
+            sampleSize: sampleSizeSchema,
+            rows: z.number().int(),
+            truncated: z.boolean(),
+            limits: limitsSchema,
+        }),
+        rows: z.array(row),
+    });
+}
+/**
+ * The 200 response schema of a route that honours `format`: the union of the
+ * three envelopes.
+ *
+ * Order matters. `full` is first, so a default request is parsed by precisely
+ * the schema it was parsed by before this existed and its bytes cannot drift.
+ * 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.
+ */
+export function resultEnvelopeSchema(full, row) {
+    return z.union([full, tableResultSchema(row), resultSummarySchema]);
+}
+//# sourceMappingURL=schema.js.map

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

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