@uptimizr/metrics 0.1.0 → 0.2.0

package/AGENTS.md

@@ -8,6 +8,8 @@
 The **semantic metric registry**: one machine-readable `MetricDefinition` per Uptimizr analytics
 metric. It is the single source of truth for _what can be asked_ of a collector — the endpoint, the
 filters, the shape and units of a row, the row caps, how to read the answer and what not to trust.
+It also owns the Zod mirrors of the three **result envelopes** (`format=full | table | summary`,
+ADR 0051 §2), so the collector, the tool catalog and the MCP server describe one set of shapes.
 
 It is **pure data**: `zod` and a type-only `@uptimizr/schema` import, nothing else. No `node:`
 built-in, no DOM, no database driver. Import it from a browser bundle, a worker or an `npx` CLI.
@@ -35,6 +37,34 @@ for (const metric of allMetrics()) {
 const metric: MetricDefinition | undefined = getMetric("perf_summary");
 ```
 
+```ts
+import { resultEnvelopeSchema, structuredEnvelopeSchema, getMetric } from "@uptimizr/metrics";
+
+const row = getMetric("top_meshes")!.row;
+// Union of the three envelopes, for a caller that can express one (a route's
+// 200 schema, a parser): rows[] | { meta, rows } | a summary digest.
+resultEnvelopeSchema(row).parse(await response.json());
+// The merged OBJECT form of the same union, for an MCP `outputSchema` — the
+// SDK drops an output schema that is not an object, unions included.
+structuredEnvelopeSchema(row);
+```
+
+This package also owns the **vocabulary half** of validating a query-DSL document
+(ADR 0051 §3). `@uptimizr/schema`'s `queryV1Schema` checks the shape; `validateQuery` answers
+the registry's questions and returns them as data:
+
+```ts
+import { validateQuery, nativeDimensions, genericDimensions } from "@uptimizr/metrics";
+
+const { issues, metric, tier } = validateQuery(query); // [] issues means it can be run
+issues[0]?.code; // "unsupported_filter" | "dimension_not_native" | "limit_too_large" | …
+issues[0]?.accepted; // what *would* have worked, when that is a closed list
+tier; // "delegated" (the metric's own builder) | "generic" (the shared group-by)
+
+nativeDimensions(metric!); // the grain its rows carry — `metric.grainDimensions`
+genericDimensions(metric!); // what it can *also* be grouped by, or [] if it cannot
+```
+
 ## Rules for agents
 
 - **Derive, never restate.** Tool catalogs, OpenAPI paths, capability lists and docs tables are
@@ -51,10 +81,109 @@ const metric: MetricDefinition | undefined = getMetric("perf_summary");
   calls. Rename nothing; add instead.
 - **Respect `limits`.** `maxRows` is the registry's promise that no answer is unbounded;
   `maxSummaryRows` is what a model should be shown.
+- **Describe a result with the envelope schemas, never a hand-written copy.** `tableEnvelopeSchema`,
+  `summaryEnvelopeSchema`, `resultEnvelopeSchema` and `structuredEnvelopeSchema` are the one
+  definition; `@uptimizr/db/summary` re-exports them under its established names, and the summariser
+  that _builds_ an envelope still lives there.
 - **Read `caveats` before you conclude anything.** They record small-sample, sampling-rate and
   capture-gating conditions — a metric with no enabled source channel returns an honest empty
   result, not a zero.
 - **`null` is not `0`.** An aggregate over no samples is SQL `NULL` and means "no data".
+- **`dimensions` is not the grain.** `MetricDefinition.dimensions` lists what a metric can be
+  _filtered, keyed or regrouped_ by; `grainDimensions` (read it through `nativeDimensions`) is what
+  its rows are actually keyed by. `top_meshes` declares `session` and returns one row per mesh.
+- **`grainDimensions` is declared, not derived.** It used to be read back out of `row.shape`; since
+  #304 it is registry data, and `src/__tests__/registry.test.ts` keeps the old derivation as the
+  gate on the declaration. Add it to every new entry.
+- **`genericGroupBy` is a claim about portability.** Declare it only where the measure is a
+  `count(*)`, a `count(DISTINCT session_id)`, or a `sum`/`avg`/`max` over a **promoted** column —
+  the shapes that render identically on all four engines at any grain. A spatial binning and a
+  percentile do not, and must not have one. Every measure column it names must also be a column of
+  the metric's `row`.
+- **`sourceChannels` is load-bearing.** The collector's project context document
+  (`GET /api/v1/context`, ADR 0051 §5) reports a metric under `metrics.disabledByCapture` when
+  **every** channel it declares produced no events over the window, which is how an agent learns to
+  say "that channel is off" instead of reporting the zero as a finding. An empty `sourceChannels`
+  means a derived rollup and is never reported as disabled — so declare the channels a metric
+  really reads, no more and no fewer.
+
+## Derived metrics (ADR 0051 §4)
+
+Most entries name a `build*` aggregation. Five do not, and are not store resources either: the
+insight primitives `insight_baseline`, `insight_movers`, `insight_anomalies`,
+`insight_significance` and `insight_scene_health` are computed in pure TypeScript _over other
+metrics' data_ (`@uptimizr/db`'s `src/insights/`). They carry `derived: "insight"`, and there are
+three kinds of entry rather than two:
+
+| Predicate           | Entry                                                          |
+| ------------------- | -------------------------------------------------------------- |
+| `isResourceMetric`  | A store read — no builder, no querystring, no `format`.        |
+| `isDerivedMetric`   | Computed in TypeScript; a real aggregate with an endpoint.     |
+| `isAggregateMetric` | Either a builder or a derivation — i.e. "takes a querystring". |
+
+Prefer `isAggregateMetric` over `metric.builder != null` anywhere the question is "is this served as
+an aggregate?", or a derived metric silently drops out of the envelope and OpenAPI surfaces.
+
+Two things a derived entry carries that are worth reading before you use one. `insight_significance`
+picks its statistical test from the **compared** metric's own entry — a headline column whose
+`rateOf` names a denominator gets a two-proportion test, a bare count gets a Poisson rate test, and
+everything else gets Welch's t — so `columns[...].rateOf` is load-bearing, not decoration.
+`insight_scene_health` declares its per-factor **weights in its `caveats`** so they are visible in
+`capabilities` and in the generated tool catalog; they are a judgement, published so it can be
+argued with and overridden per request.
+
+## Panel specs (ADR 0051 §7)
+
+The same split, one level up. `@uptimizr/schema`'s `panelSpecV1Schema` says a spec is well formed;
+`validatePanelSpec(spec)` says whether it will draw anything. It runs `validateQuery` over the
+spec's query (prefixing each issue's `path` with `query.`) and adds the two checks only the registry
+can make — does the chart suit the metric's grain, and does the `encoding` name columns the metric
+actually returns:
+
+```ts
+import {
+  validatePanelSpec,
+  suggestChart,
+  defaultEncoding,
+  chartsForMetric,
+} from "@uptimizr/metrics";
+
+const { issues, metric, tier } = validatePanelSpec(spec); // [] issues means it can be pinned
+issues[0]?.code; // the DSL's codes, plus "chart_grain_mismatch" | "unknown_encoding_column"
+issues[0]?.accepted; // the charts that would have worked, or the metric's real result columns
+
+suggestChart(metric, query); // what to pre-fill; always satisfies `chartSuitsMetric`
+defaultEncoding(metric, chart); // the metric's axis/label on `x`, its measure on `y`
+```
+
+`PANEL_CHART_RULES` is the compatibility table as data — the validator, `suggestChart` and the
+published table all read it, so they cannot drift:
+
+| Chart           | Requires                                                                                                       |
+| --------------- | -------------------------------------------------------------------------------------------------------------- |
+| `table`         | nothing — any metric's rows can be listed                                                                      |
+| `stat`          | a single-record result (a `project`-grain metric with no grain dimensions)                                     |
+| `bar`           | a label column, a measure column, and a ranked or bucketed grain (`mesh`, `scene`, `session`, `row`, `bucket`) |
+| `line` / `area` | an ordered axis column — in practice a `bucket`-grain metric                                                   |
+| `heatmap2d`     | a `bin` grain (the metric already bins its input into a grid)                                                  |
+| `world3d`       | a `voxel` grain (the metric already bins its input into world-space cells)                                     |
+
+`chartSuitsMetric(chart, metric)` is the predicate behind one row; `chartsForMetric(metric)` lists
+every chart that fits. `axisColumn` / `labelColumn` / `measureColumn` read the column semantics the
+rules depend on, and `resultColumns(metric, query)` is what an encoding is checked against — the
+metric's declared `row` on the delegated tier, but the grouped dimensions plus the declared measures
+on the generic tier, because a regrouped `top_meshes` has no `mesh` column.
+
+**Rules for agents:**
+
+- **A pinned panel is read much later than it is written**, which is why the chart is checked at all.
+  A `line` over `top_meshes` does not fail — it draws something a reader takes for a trend. Pin time
+  is the moment somebody is paying attention, so that is where the refusal belongs.
+- **Widen the table with a `PanelChartRule`, never a special case.** A rule's `requires` string is
+  what the collector's `400` quotes; `src/__tests__/panelSpec.test.ts` pins the whole chart × metric
+  matrix and the rendered table.
+- A rule may read only the **grain and the column semantics**, like everything else here. If a metric
+  charts badly, fix its `label` / `axis` / `measure` declarations.
 
 ## Where the SQL lives
 

package/README.md

@@ -7,7 +7,9 @@
 
 Everything that used to restate the query surface by hand is **derived** from this package: the
 agent tool catalog in [`@uptimizr/agent-core`](../agent-core), the `uptimizr://capabilities`
-resource and tool output schemas in [`@uptimizr/mcp`](../mcp), the collector's
+resource and tool output schemas in [`@uptimizr/mcp`](../mcp) — which describe a row **and** the
+`format=full | table | summary` result envelopes this package also defines (ADR 0051 §2) — the
+collector's
 `GET /api/v1/openapi.json` document, and the endpoint/tool tables in the docs. Coverage therefore
 cannot drift: CI fails when an aggregation has no registry entry, when a row schema does not match
 real query output, or when an endpoint's querystring keys diverge from its declared filters.
@@ -28,12 +30,12 @@ pnpm add @uptimizr/metrics
 ```ts
 import { allMetrics, getMetric, METRIC_IDS } from "@uptimizr/metrics";
 
-METRIC_IDS.length; // 71 metrics (69 aggregations + 2 store resources)
+METRIC_IDS.length; // 78 metrics (70 aggregations + 5 insight derivations + 3 store resources)
 
 const metric = getMetric("top_meshes");
 metric?.title; // "Most-interacted meshes"
 metric?.endpoint?.path; // "/api/v1/meshes/top"
-metric?.filters; // ["since", "until", "bins", "limit", "session"]
+metric?.filters; // ["since", "until", "bins", "limit", "session", "format"]
 metric?.row; // z.ZodObject — the shape of one row
 metric?.columns.count?.unit; // "count"
 metric?.limits.maxRows; // the hard cap no consumer may exceed
@@ -44,23 +46,23 @@ const byCategory = Object.groupBy(allMetrics(), (m) => m.category);
 
 ## What a `MetricDefinition` carries
 
-| Field                   | Meaning                                                                                                                                                               |
-| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `id`                    | Stable snake_case id. Also the DSL metric name and the **agent tool name**.                                                                                           |
-| `title`, `description`  | Agent-facing prose: what it measures and what one row is.                                                                                                             |
-| `builder`               | The `build*` aggregation in `@uptimizr/db` that computes it. Absent for the two **resource** entries (`session_meta`, `scene_representation`), which are store reads. |
-| `endpoint`              | `{ method, path, pathParams }` — the canned collector route, when one exists.                                                                                         |
-| `grain`                 | What one row represents (`project`, `scene`, `session`, `mesh`, `bin`, `voxel`, `bucket`, `row`).                                                                     |
-| `dimensions`            | The `DimensionId`s the rows are keyed by. Closed vocabulary.                                                                                                          |
-| `filters`               | The `FilterId`s the endpoint accepts — exactly its Zod querystring keys.                                                                                              |
-| `row`                   | `z.ZodObject` for one row: the source for OpenAPI, tool output schemas and numeric coercion.                                                                          |
-| `columns`               | Per-column `{ description, unit, measure, label, rateOf }`.                                                                                                           |
-| `limits`                | `{ maxRows, maxSummaryRows }` — no consumer can ask for an unbounded payload.                                                                                         |
-| `interpretation`        | How to read the result.                                                                                                                                               |
-| `caveats`               | Small-sample, capture-gating and sampling-rate warnings.                                                                                                              |
-| `sourceChannels`        | The `EventType` capture channels that feed it (ADR 0012).                                                                                                             |
-| `related`, `comparable` | Metrics worth reading alongside; comparison semantics for deltas.                                                                                                     |
-| `category`              | Grouping used by the docs, the capabilities resource and the health score.                                                                                            |
+| Field                   | Meaning                                                                                                                                                                                                                                                                       |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`                    | Stable snake_case id. Also the DSL metric name and the **agent tool name**.                                                                                                                                                                                                   |
+| `title`, `description`  | Agent-facing prose: what it measures and what one row is.                                                                                                                                                                                                                     |
+| `builder`               | The `build*` aggregation in `@uptimizr/db` that computes it. Absent for the three **resource** entries (`session_meta`, `session_narrative`, `scene_representation`), which are store reads, and for the five `derived: "insight"` entries, which are computed in TypeScript. |
+| `endpoint`              | `{ method, path, pathParams }` — the canned collector route, when one exists.                                                                                                                                                                                                 |
+| `grain`                 | What one row represents (`project`, `scene`, `session`, `mesh`, `bin`, `voxel`, `bucket`, `row`).                                                                                                                                                                             |
+| `dimensions`            | The `DimensionId`s it can be filtered, keyed or regrouped by — `grainDimensions` is what its rows are actually keyed by. Closed vocabulary.                                                                                                                                   |
+| `filters`               | The `FilterId`s the endpoint accepts — exactly its Zod querystring keys.                                                                                                                                                                                                      |
+| `row`                   | `z.ZodObject` for one row: the source for OpenAPI, tool output schemas (wrapped in the result envelopes below) and numeric coercion.                                                                                                                                          |
+| `columns`               | Per-column `{ description, unit, measure, label, rateOf }`.                                                                                                                                                                                                                   |
+| `limits`                | `{ maxRows, maxSummaryRows }` — no consumer can ask for an unbounded payload.                                                                                                                                                                                                 |
+| `interpretation`        | How to read the result.                                                                                                                                                                                                                                                       |
+| `caveats`               | Small-sample, capture-gating and sampling-rate warnings.                                                                                                                                                                                                                      |
+| `sourceChannels`        | The `EventType` capture channels that feed it (ADR 0012).                                                                                                                                                                                                                     |
+| `related`, `comparable` | Metrics worth reading alongside; comparison semantics for deltas.                                                                                                                                                                                                             |
+| `category`              | Grouping used by the docs, the capabilities resource and the health score.                                                                                                                                                                                                    |
 
 ## Exports
 
@@ -75,7 +77,27 @@ const byCategory = Object.groupBy(allMetrics(), (m) => m.category);
 **Helpers**
 
 - `allMetrics()`, `getMetric(id)`, `isMetricId(value)`
-- `metricForBuilder(builder)`, `isResourceMetric(metric)`
+- `metricForBuilder(builder)`, and the entry-kind predicates `isResourceMetric(metric)`,
+  `isDerivedMetric(metric)`, `isAggregateMetric(metric)`
+- `validateQuery(query)`, `nativeDimensions(metric)`, `genericDimensions(metric)`,
+  `queryTier(metric, query)` — the query-DSL vocabulary checks (ADR 0051 §3)
+
+**Result envelopes** (ADR 0051 §2)
+
+The Zod mirrors of `format=full | table | summary`. They live here, next to the row schemas they
+wrap, because the collector (`@uptimizr/db`, which re-exports them from `@uptimizr/db/summary`
+under its own names), the generated tool catalog and the MCP server all need them and none of
+those may depend on the others. The summariser that _builds_ an envelope stays in
+`@uptimizr/db/summary`.
+
+- `resultFormatSchema` — the `full | table | summary` enum.
+- `tableEnvelopeSchema(row)` — `{ meta, rows }`; `tableMetaSchema` — the `meta` block alone.
+- `summaryEnvelopeSchema` — the four grain-driven digests, discriminated on `kind`.
+- `resultEnvelopeSchema(row, full?)` — the union of the three, for a caller that can express one
+  (a route's 200 response schema, a parser). `full` defaults to an array of `row`.
+- `structuredEnvelopeSchema(row)` — the same union merged into **one loose object**, every key
+  optional. An MCP `outputSchema` must be an object schema: the SDK drops anything else, a
+  top-level union included, and then advertises no schema at all.
 
 **Types**
 

package/dist/envelopes.d.ts

@@ -0,0 +1,280 @@
+/**
+ * Zod mirrors of the three result envelopes (ADR 0051 §2, design sketch §B.1).
+ *
+ * `format=full | table | summary` is the shared querystring of every
+ * registry-served aggregate endpoint, and the same three shapes are what an
+ * agent gets back through MCP. They are described **here**, next to the row
+ * schemas they wrap, because three different packages need them and none of
+ * them may depend on the others:
+ *
+ * - `@uptimizr/db` attaches each route's 200 response schema from the registry,
+ *   so the collector's Zod type provider serialises a formatted response
+ *   *through* one of these — without them a `table` or `summary` response would
+ *   be stripped to nothing on its way out. `@uptimizr/db/summary` re-exports
+ *   every schema below under its established names, so that package's public
+ *   API is unchanged.
+ * - `@uptimizr/agent-core` derives each generated tool's `outputSchema` from
+ *   them, and `@uptimizr/mcp` validates `structuredContent` with them. Neither
+ *   package may depend on `@uptimizr/db` (it carries a ~37 MB DuckDB binding;
+ *   `dependencies.test.ts` in both packages fails if it reappears) — which is
+ *   exactly why the *pure* schemas live in this dependency-free package.
+ *
+ * Only the schemas moved. The summariser that *builds* an envelope
+ * (`summarizeRows`, `tableResult`, `clusterCells`, …) is still
+ * `@uptimizr/db/summary`'s; relocating it is #337.
+ */
+import { z } from "zod";
+/**
+ * `format=full | table | summary`, the shared querystring value every
+ * registry-served aggregate endpoint accepts. Spelled out literally rather than
+ * built from a `RESULT_FORMATS` array so the inferred type is the string union
+ * itself and a route handler keeps its narrowing.
+ */
+export declare const resultFormatSchema: z.ZodEnum<{
+    summary: "summary";
+    full: "full";
+    table: "table";
+}>;
+/** `format=summary`: one of the four grain-driven shapes. */
+export declare const summaryEnvelopeSchema: 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>>;
+        drillQuery: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, 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<{
+            up: "up";
+            down: "down";
+            flat: "flat";
+        }>;
+        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>>;
+        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;
+        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">;
+/** The `meta` block `format=table` wraps a metric's rows in. */
+export declare const tableMetaSchema: z.ZodObject<{
+    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>;
+    rows: z.ZodNumber;
+    truncated: z.ZodBoolean;
+    limits: z.ZodObject<{
+        maxRows: z.ZodNumber;
+        maxSummaryRows: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/** `format=table`: the `meta` envelope around a metric's own row schema. */
+export declare function tableEnvelopeSchema(row: z.ZodType): z.ZodObject;
+/**
+ * The result a caller gets from a surface that honours `format`: the union of
+ * the three envelopes.
+ *
+ * Order matters. The `full` shape 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.
+ *
+ * `full` defaults to a plain array of `row`, which is what an agent-facing
+ * caller wants; the collector passes its own route-level 200 schema instead,
+ * because a single-record route (the spatial `stats` endpoints) answers with a
+ * bare object rather than an array.
+ */
+export declare function resultEnvelopeSchema(row: z.ZodType, full?: z.ZodType): z.ZodType;
+/**
+ * The **object** form of {@link resultEnvelopeSchema}, for a tool that must
+ * advertise its result as a single JSON Schema object — which is what MCP's
+ * `outputSchema` is: a `type: "object"` schema the SDK validates
+ * `structuredContent` against, on the server with Zod and again on the client
+ * with Ajv.
+ *
+ * A top-level `z.union` cannot be used there. The MCP TypeScript SDK normalises
+ * an output schema to an object schema and **silently drops** anything that is
+ * not one (`normalizeObjectSchema` returns `undefined` for a union), so
+ * `tools/list` would advertise no output schema at all and every call would then
+ * fail validation — worse than the bug this replaces. So the three envelopes are
+ * merged into one loose object whose every key is optional:
+ *
+ * - `rows` — `format=full` (wrapped as `{ rows }` by the MCP server, so a
+ *   single-record read looks like every other) and the rows of `format=table`.
+ *   Its element schema stays the metric's own, so a column that is out of
+ *   contract is still reported by name.
+ * - `meta` — only `format=table` carries it.
+ * - `kind` and the summary fields — only `format=summary` carries them, and
+ *   `kind` says which grain-specific fields (`top`, `series`, `clusters`,
+ *   `record`) came with it.
+ *
+ * The object is deliberately *loose*: an envelope key a newer collector adds is
+ * passed through rather than dropped. Callers that can express a union — a
+ * collector route's response schema, a test — should use
+ * {@link resultEnvelopeSchema}, which discriminates strictly.
+ */
+export declare function structuredEnvelopeSchema(row: z.ZodType, metric?: string): z.ZodObject;
+//# sourceMappingURL=envelopes.d.ts.map

package/dist/envelopes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelopes.d.ts","sourceRoot":"","sources":["../src/envelopes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB;;;;EAAuC,CAAC;AAgKvE,6DAA6D;AAC7D,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2BAKhC,CAAC;AAEH,gEAAgE;AAChE,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;iBAQ1B,CAAC;AAEH,4EAA4E;AAC5E,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,SAAS,CAK/D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,CAAC,CAAC,OAAO,EAAE,IAAI,GAAE,CAAC,CAAC,OAAsB,GAAG,CAAC,CAAC,OAAO,CAE9F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,SAAS,CAuDrF"}