@jeffjassky/telemetry 0.3.0 → 0.4.0

package/dist/mcp.cjs

@@ -5,8 +5,36 @@ require('uuidv7');
 var mongoose = require('mongoose');
 
 // src/server/mcp.ts
+var TelemetryKind = {
+  Event: "event",
+  Error: "error",
+  Span: "span",
+  State: "state",
+  Usage: "usage"
+};
+var TELEMETRY_KINDS = Object.values(TelemetryKind);
+var LogLevel = {
+  Debug: "debug",
+  Info: "info",
+  Warn: "warn",
+  Error: "error",
+  Fatal: "fatal"
+};
+var Env = { Prod: "prod", Staging: "staging", Dev: "dev" };
+var Origin = { Server: "server", Client: "client" };
 var PLATFORM_SCOPE = "*";
 var isPlatformScope = (tenantId) => tenantId === PLATFORM_SCOPE;
+var RETENTION_DAYS = {
+  // keep-all + 90d is cheap at this scale, and it makes p95-by-route a raw
+  // query instead of a rollup design (schema §2.1)
+  [TelemetryKind.Span]: 90,
+  [TelemetryKind.Error]: 90,
+  [TelemetryKind.Event]: 730,
+  [TelemetryKind.State]: 730,
+  [TelemetryKind.Usage]: null
+  // money is immortal
+};
+var COUNTER_OVERFLOW_KEY = "(other)|(other)";
 var truncate = (d, b) => {
   if (!b) return void 0;
   if (b === "hour") return new Date(Math.floor(d.getTime() / 36e5) * 36e5);
@@ -225,6 +253,10 @@ var DEFAULT_LIMITS = {
   rollups: 500,
   trace: 500,
   journey: 500,
+  breakdown: 50,
+  // top groups — a starting point, to be measured on real hosts
+  values: 200,
+  // top values of one dimension — a picker, not a table
   distribution: 1e5,
   distinct: 1e5,
   funnel: 5e3
@@ -238,7 +270,10 @@ function buildMatch(scope, range, f) {
     occurredAt: { $gte: range.from, $lt: range.to }
   };
   for (const k of ["kind", "name", "severity", "env", "service", "release", "traceId"]) {
-    if (f[k]) match[k] = f[k];
+    const v = f[k];
+    if (Array.isArray(v)) {
+      if (v.length) match[k] = { $in: v };
+    } else if (v) match[k] = v;
   }
   if (f.subject) match.subjectKeys = f.subject;
   for (const [k, v] of Object.entries(f.attrs ?? {})) match[`attrs.${k}`] = v;
@@ -261,6 +296,68 @@ function buildMatch(scope, range, f) {
   }
   return match;
 }
+var INTERVALS = ["hour", "day", "week", "month"];
+var truncTo = (path, unit) => ({
+  $dateTrunc: { date: path, unit, ...unit === "week" ? { startOfWeek: "monday" } : {} }
+});
+function measureAccumulator(measure) {
+  const m = /^(sum|avg):(.+)$/.exec(measure);
+  if (!m) return { $sum: { $divide: [1, { $ifNull: ["$sampleRate", 1] }] } };
+  const path = m[2] === "durationMs" ? "$durationMs" : `$metrics.${m[2]}`;
+  return m[1] === "sum" ? { $sum: path } : { $avg: path };
+}
+var badRequest = (message) => Object.assign(new Error(`telemetry: breakdown() \u2014 ${message}`), { status: 400 });
+var BREAKDOWN_FIELDS = [
+  "kind",
+  "name",
+  "severity",
+  "env",
+  "service",
+  "release",
+  "origin",
+  "client.platform",
+  "client.appVersion",
+  "usage.meter",
+  "usage.billedTo",
+  "usage.unit",
+  "state.key",
+  "state.to",
+  "error.type",
+  "error.handled"
+];
+var typePrefix = (ref) => ({
+  $let: {
+    vars: { ref },
+    in: {
+      $cond: [
+        { $eq: [{ $type: "$$ref" }, "string"] },
+        { $arrayElemAt: [{ $split: ["$$ref", ":"] }, 0] },
+        null
+      ]
+    }
+  }
+});
+function dimExpression(dim2) {
+  if (dim2.startsWith("attr:")) {
+    const key = dim2.slice(5);
+    if (!key) throw badRequest('`attr:` needs a key, e.g. "attr:plan"');
+    return { $ifNull: [`$attrs.${key}`, null] };
+  }
+  if (dim2.startsWith("field:")) {
+    const path = dim2.slice(6);
+    if (!BREAKDOWN_FIELDS.includes(path)) {
+      throw badRequest(
+        `"field:${path}" is not groupable. Allowed paths: ${BREAKDOWN_FIELDS.join(", ")}. Grouping by \`data.*\`, \`body\`, or an arbitrary path is refused \u2014 those are unindexed free-form content, and a $group over them scans it all. Use \`attr:<key>\` for a declared attr.`
+      );
+    }
+    return { $ifNull: [`$${path}`, null] };
+  }
+  if (dim2 === "subjectType") return typePrefix({ $arrayElemAt: ["$subjectKeys", 0] });
+  if (dim2 === "actorType") return typePrefix("$actor");
+  throw badRequest(
+    `"${dim2}" is not a dimension. Use "attr:<key>", "field:<path>", "subjectType" or "actorType".`
+  );
+}
 var QueryCache = class {
   constructor(ttlMs, cap) {
     this.ttlMs = ttlMs;
@@ -334,16 +431,9 @@ function createQueries(ctx) {
       return cache.get(
         key,
         () => timed("series", { scope, filter, measure, interval }, async () => {
-          const m = /^(sum|avg):(.+)$/.exec(measure);
-          const value = !m ? { $sum: { $divide: [1, { $ifNull: ["$sampleRate", 1] }] } } : m[1] === "sum" ? { $sum: `$metrics.${m[2]}` } : { $avg: `$metrics.${m[2]}` };
           const buckets = await ctx.TelemetryModel.aggregate([
             { $match: buildMatch(scope, range, filter) },
-            {
-              $group: {
-                _id: { $dateTrunc: { date: "$occurredAt", unit: interval, ...interval === "week" ? { startOfWeek: "monday" } : {} } },
-                value
-              }
-            },
+            { $group: { _id: truncTo("$occurredAt", interval), value: measureAccumulator(measure) } },
             { $sort: { _id: 1 } },
             { $limit: limits.series }
           ]);
@@ -351,6 +441,114 @@ function createQueries(ctx) {
         })
       );
     },
+    /**
+     * Top groups of a measure by one or two dimensions — "which models cost the
+     * most", "errors by release", "events by platform per week". The primitive
+     * that replaces a page's client-side grouping of whatever rows it happened
+     * to have fetched, which answered "this page" while reading like it
+     * answered the range (reports §6).
+     *
+     * THE CAP IS ON GROUPS RETURNED, NEVER ON ROWS SCANNED. Every `$limit`
+     * below sits AFTER a `$group`, exactly as series() does: the scan is bounded
+     * by buildMatch — tenant, range, filters, indexes — and nothing else, so a
+     * quarter of a million records is one pass and 50 rows. Truncation
+     * therefore keeps the TOP groups by measure, which is what a breakdown
+     * table means; a cap on documents scanned would return an arbitrary prefix
+     * and call it the top.
+     *
+     * With an `interval` this runs a SECOND aggregate restricted to the top
+     * groups, rather than one pipeline that groups by (dims, bucket) and folds.
+     * Two reasons: the ranking must be the measure over the WHOLE range (the
+     * same number the no-interval call reports), and folding in one pass means
+     * `$push`-ing every bucket of every group before the cap can apply — the
+     * unbounded intermediate this primitive exists to avoid. The restriction is
+     * an `$expr`/`$or` over the ≤ cap tuples because a dim can be a computed
+     * expression (subjectType), which a plain `$in` on a path cannot address.
+     *
+     * Under PLATFORM_SCOPE it aggregates ACROSS tenants, like series() — one
+     * set of groups with every tenant summed into it, which is the platform-wide
+     * table a platform operator came for. Ask for a per-tenant split by scoping
+     * to a tenant, or with rollups().
+     */
+    breakdown(scope, range, filter, opts) {
+      const groupBy = opts.groupBy ?? [];
+      if (groupBy.length < 1 || groupBy.length > 2) {
+        throw badRequest(`groupBy takes 1 or 2 dimensions, got ${groupBy.length}`);
+      }
+      const measure = opts.measure ?? "count";
+      const interval = opts.interval;
+      if (interval && !INTERVALS.includes(interval)) {
+        throw badRequest(`interval must be one of ${INTERVALS.join(", ")}`);
+      }
+      const dims = groupBy.map(dimExpression);
+      const cap = Math.min(Math.max(1, opts.limit ?? limits.breakdown), limits.breakdown);
+      const key = JSON.stringify([
+        "breakdown",
+        scope,
+        range.from,
+        range.to,
+        filter,
+        groupBy,
+        measure,
+        interval ?? null,
+        cap
+      ]);
+      return cache.get(
+        key,
+        () => timed("breakdown", { scope, filter, groupBy, measure, interval }, async () => {
+          const match = buildMatch(scope, range, filter);
+          const dimId = Object.fromEntries(dims.map((expr, i) => [`d${i}`, expr]));
+          const top = await ctx.TelemetryModel.aggregate([
+            { $match: match },
+            { $group: { _id: dimId, value: measureAccumulator(measure) } },
+            { $sort: { value: -1, _id: 1 } },
+            { $limit: cap + 1 }
+          ]);
+          const truncated = top.length > cap;
+          if (truncated) top.pop();
+          const tuples = top.map(
+            (g) => groupBy.map((_, i) => g._id?.[`d${i}`] ?? null)
+          );
+          if (!interval) {
+            return {
+              rows: top.map((g, i) => ({ dims: tuples[i], value: g.value })),
+              groups: top.length,
+              truncated,
+              bucketsTruncated: false,
+              dataSource: "raw"
+            };
+          }
+          if (!tuples.length) {
+            return { rows: [], groups: 0, truncated, bucketsTruncated: false, dataSource: "raw" };
+          }
+          const inTop = {
+            $or: tuples.map((t) => ({ $and: dims.map((expr, i) => ({ $eq: [expr, t[i] ?? null] })) }))
+          };
+          const bucketCap = limits.series * top.length;
+          const perBucket = await ctx.TelemetryModel.aggregate([
+            { $match: { ...match, $expr: inTop } },
+            { $group: { _id: { at: truncTo("$occurredAt", interval), ...dimId }, value: measureAccumulator(measure) } },
+            // `at` is the first key of `_id`, so one BSON sort orders by bucket
+            // then by dims — deterministic without a second sort key
+            { $sort: { _id: 1 } },
+            { $limit: bucketCap + 1 }
+          ]);
+          const bucketsTruncated = perBucket.length > bucketCap;
+          if (bucketsTruncated) perBucket.pop();
+          return {
+            rows: perBucket.map((b) => ({
+              dims: groupBy.map((_, i) => b._id?.[`d${i}`] ?? null),
+              at: b._id.at,
+              value: b.value
+            })),
+            groups: top.length,
+            truncated,
+            bucketsTruncated,
+            dataSource: "raw"
+          };
+        })
+      );
+    },
     /**
      * Percentiles + histogram off raw. Keep-all makes the SAMPLE complete —
      * no sampling stands between the match and the math (§5.3) — but the
@@ -592,6 +790,771 @@ function requireDistinctFamily(registry, as) {
   }
   return spec;
 }
+new mongoose.Schema(
+  {
+    type: { type: String, required: true },
+    // user | org | team | session
+    id: { type: String, required: true },
+    /** disambiguates same-type parties: sender | recipient | impersonated */
+    role: { type: String }
+  },
+  { _id: false }
+);
+var BUILTIN_PLATFORMS = ["web", "electron", "ios", "android", "server", "cli"];
+var StackFrameSchema = new mongoose.Schema(
+  {
+    filename: String,
+    fn: String,
+    lineno: Number,
+    colno: Number,
+    inApp: Boolean,
+    context: [String]
+  },
+  { _id: false }
+);
+new mongoose.Schema(
+  {
+    type: { type: String, required: true },
+    message: { type: String, required: true },
+    handled: { type: Boolean, required: true, default: false },
+    /** grouping key */
+    fingerprint: { type: String, required: true },
+    frames: [StackFrameSchema]
+  },
+  { _id: false }
+);
+new mongoose.Schema(
+  {
+    key: { type: String, required: true },
+    // 'lifecycle' | 'onboarding_step'
+    from: String,
+    to: { type: String, required: true },
+    /** how long the subject sat in `from` — answers "where do they stall" */
+    previousSinceMs: Number
+  },
+  { _id: false }
+);
+new mongoose.Schema(
+  {
+    meter: { type: String, required: true },
+    quantity: { type: Number, required: true },
+    unit: { type: String, required: true },
+    /**
+     * Authoritative money. `metrics.cost_usd` is a BSON double — fine as a
+     * measure, wrong as the thing that becomes an invoice. Money is
+     * authoritative only on kind=usage; the metric is a lossy copy.
+     */
+    amount: mongoose.Schema.Types.Decimal128,
+    currency: String,
+    /** at-least-once dedupe. Deterministic, e.g. `${traceId}:${spanId}` */
+    idempotencyKey: { type: String, required: true },
+    /** who pays — 'org:o_9'. Distinct from subject and from actor. */
+    billedTo: { type: String, required: true },
+    billable: { type: Boolean, required: true, default: true },
+    priceVersion: String,
+    /** corrections are new reversing rows; never UPDATE a billed row */
+    reverses: String
+  },
+  { _id: false }
+);
+
+// src/server/catalog.ts
+var label = (src) => src.slice(src.indexOf(":") + 1);
+var LEAF_TYPES = {
+  string: "string",
+  number: "number",
+  int: "number",
+  bigint: "number",
+  boolean: "boolean",
+  date: "date"
+};
+function walkAttr(schema) {
+  let node = schema;
+  let optional = false;
+  for (let depth = 0; node && depth < 20; depth++) {
+    const def = node._zod?.def ?? node.def;
+    if (!def?.type) break;
+    switch (def.type) {
+      // these three all mean "the value may be absent from a stored record",
+      // which is the only thing `optional` claims
+      case "optional":
+      case "nullable":
+      case "default":
+        optional = true;
+        node = def.innerType;
+        continue;
+      case "catch":
+      case "readonly":
+        node = def.innerType;
+        continue;
+      // a pipe is `in -> out`; the INPUT side is what a caller may send and so
+      // what a stored value was validated as. The output of a transform is
+      // frequently a shape no filter could ever be written against.
+      case "pipe":
+        node = def.in;
+        continue;
+      case "enum": {
+        const options = Array.isArray(node.options) ? node.options : Object.values(def.entries ?? {});
+        return { type: "enum", values: options.map(String), optional };
+      }
+      case "literal":
+        return { type: "enum", values: [...def.values ?? []].map(String), optional };
+      default:
+        return { type: LEAF_TYPES[def.type] ?? "string", optional };
+    }
+  }
+  return { type: "string", optional };
+}
+var dim = (key, type, o = {}) => ({
+  key,
+  // the two pseudo-dims are derived at query time from subjectKeys / actor, so
+  // they carry no `field:` prefix and label to themselves
+  label: key.startsWith("field:") ? key.slice(6) : key,
+  type,
+  ...o.values ? { values: [...o.values] } : {},
+  optional: o.optional ?? false,
+  indexed: o.indexed ?? false
+});
+var envelopeDims = (platforms) => [
+  dim("field:kind", "enum", { values: TELEMETRY_KINDS, indexed: true }),
+  dim("field:name", "string", { indexed: true }),
+  dim("field:severity", "enum", { values: Object.values(LogLevel) }),
+  dim("field:env", "enum", { values: Object.values(Env) }),
+  dim("field:service", "string"),
+  dim("field:release", "string"),
+  dim("field:origin", "enum", { values: Object.values(Origin) }),
+  // client context is absent on server-origin records, so both of its dims are optional
+  dim("field:client.platform", "enum", { values: platforms, optional: true }),
+  dim("field:client.appVersion", "string", { optional: true }),
+  dim("subjectType", "string", { optional: true, indexed: true }),
+  dim("actorType", "string", { optional: true })
+];
+var kindDims = (kind) => {
+  switch (kind) {
+    case TelemetryKind.Usage:
+      return [
+        dim("field:usage.meter", "string", { indexed: true }),
+        dim("field:usage.billedTo", "string"),
+        dim("field:usage.unit", "string")
+      ];
+    case TelemetryKind.State:
+      return [
+        dim("field:state.key", "string", { indexed: true }),
+        dim("field:state.to", "string", { indexed: true })
+      ];
+    case TelemetryKind.Error:
+      return [dim("field:error.type", "string"), dim("field:error.handled", "boolean")];
+    default:
+      return [];
+  }
+};
+var RAW_OPS = ["avg", "p50", "p95", "p99"];
+function deriveCatalog(registry, opts = {}) {
+  const platforms = [.../* @__PURE__ */ new Set([...BUILTIN_PLATFORMS, ...opts.platforms ?? []])];
+  const families = {};
+  for (const [name, spec] of Object.entries(registry)) {
+    for (const r of spec.rollups ?? []) {
+      const as = r.as ?? name;
+      const seen = families[as];
+      if (!seen) {
+        families[as] = {
+          as,
+          by: [...r.by],
+          labels: r.by.map(label),
+          bucket: r.bucket ?? null,
+          lifetime: !r.bucket,
+          // `subjects` only means anything when there is a subject dim to
+          // restrict; without one it selects nothing and claiming it would
+          // offer a subject filter the family cannot answer
+          subjectTypes: r.by.includes("subject") ? [...r.subjects ?? []] : [],
+          sums: [...r.sum ?? []],
+          capture: (r.capture ?? []).map(label),
+          feeders: [name],
+          retentionDays: r.retentionDays ?? null
+        };
+        continue;
+      }
+      for (const k of r.sum ?? []) if (!seen.sums.includes(k)) seen.sums.push(k);
+      for (const c of r.capture ?? []) {
+        const l = label(c);
+        if (!seen.capture.includes(l)) seen.capture.push(l);
+      }
+      if (!seen.feeders.includes(name)) seen.feeders.push(name);
+    }
+  }
+  const events = {};
+  const namespaces = {};
+  const subjectTypes = [];
+  const noteSubject = (t) => {
+    if (!subjectTypes.includes(t)) subjectTypes.push(t);
+  };
+  for (const [name, spec] of Object.entries(registry)) {
+    const dot = name.indexOf(".");
+    const namespace = dot === -1 ? name : name.slice(0, dot);
+    (namespaces[namespace] ??= []).push(name);
+    for (const s of spec.subjects) noteSubject(s);
+    const indexedAttrs = [...spec.indexedAttrs ?? []];
+    const dims = Object.entries(spec.attrs?.shape ?? {}).map(
+      ([key, schema]) => {
+        const walked = walkAttr(schema);
+        return {
+          key: `attr:${key}`,
+          label: key,
+          type: walked.type,
+          ...walked.values ? { values: walked.values } : {},
+          optional: walked.optional,
+          indexed: indexedAttrs.includes(key)
+        };
+      }
+    );
+    dims.push(...kindDims(spec.kind));
+    const eventFamilies = [];
+    const ownSums = /* @__PURE__ */ new Map();
+    for (const r of spec.rollups ?? []) {
+      const as = r.as ?? name;
+      if (!eventFamilies.includes(as)) eventFamilies.push(as);
+      const set = ownSums.get(as) ?? /* @__PURE__ */ new Set();
+      for (const k of r.sum ?? []) set.add(k);
+      ownSums.set(as, set);
+      for (const s of r.subjects ?? []) noteSubject(s);
+    }
+    const measures = [{ key: "count", exactVia: [] }];
+    for (const k of Object.keys(spec.metrics?.shape ?? {})) {
+      measures.push({
+        key: `sum:${k}`,
+        metric: k,
+        exactVia: eventFamilies.filter((as) => ownSums.get(as)?.has(k))
+      });
+      for (const op of RAW_OPS) measures.push({ key: `${op}:${k}`, metric: k, exactVia: [] });
+    }
+    if (spec.kind === TelemetryKind.Span) {
+      for (const op of RAW_OPS) {
+        measures.push({ key: `${op}:durationMs`, metric: "durationMs", exactVia: [] });
+      }
+    }
+    events[name] = {
+      kind: spec.kind,
+      origin: spec.origin,
+      subjects: [...spec.subjects],
+      description: spec.description,
+      namespace,
+      dims,
+      measures,
+      families: eventFamilies,
+      indexedAttrs,
+      indexedMetrics: [...spec.indexedMetrics ?? []],
+      // `hasOwnProperty` rather than `??`, exactly as model.ts stamps expiresAt:
+      // an explicit `retentionDays: null` means immortal and must not fall
+      // through to the per-kind default
+      retentionDays: Object.prototype.hasOwnProperty.call(spec, "retentionDays") ? spec.retentionDays ?? null : RETENTION_DAYS[spec.kind]
+    };
+  }
+  return { events, families, namespaces, envelope: envelopeDims(platforms), subjectTypes };
+}
+function projectRegistry(catalog) {
+  return Object.fromEntries(
+    Object.entries(catalog.events).map(([name, e]) => [
+      name,
+      {
+        kind: e.kind,
+        origin: e.origin,
+        subjects: e.subjects,
+        description: e.description,
+        attrKeys: e.dims.filter((d) => d.key.startsWith("attr:")).map((d) => d.label),
+        // every metric key gets exactly one `sum:` measure and nothing else does
+        metricKeys: e.measures.filter((m) => m.key.startsWith("sum:")).map((m) => m.metric),
+        indexedAttrs: e.indexedAttrs,
+        indexedMetrics: e.indexedMetrics,
+        rollups: e.families.map((as) => {
+          const f = catalog.families[as];
+          return { as: f.as, by: f.by, bucket: f.bucket, sum: f.sums, subjects: f.subjectTypes };
+        })
+      }
+    ])
+  );
+}
+
+// src/server/report.ts
+var RANGE_MS = {
+  "1h": 36e5,
+  "24h": 864e5,
+  "7d": 7 * 864e5,
+  "30d": 30 * 864e5,
+  "90d": 90 * 864e5
+};
+var badRequest2 = (message) => Object.assign(new Error(`telemetry: ${message}`), { status: 400 });
+function rangeOf(range, now = /* @__PURE__ */ new Date()) {
+  if (typeof range === "string") {
+    const ms = RANGE_MS[range] ?? spanOf(range);
+    if (ms == null) {
+      throw badRequest2(
+        `range "${range}" is not a known shorthand \u2014 use one of ${Object.keys(RANGE_MS).join(", ")}, an \`<n>h\`/\`<n>d\` form, or an explicit { from, to } ISO pair`
+      );
+    }
+    return { from: new Date(now.getTime() - ms), to: now };
+  }
+  const from = new Date(range.from);
+  const to = new Date(range.to);
+  if (Number.isNaN(from.getTime()) || Number.isNaN(to.getTime()) || from >= to) {
+    throw badRequest2(
+      `range { from: "${range.from}", to: "${range.to}" } is not valid \u2014 \`from\` must be a valid ISO time strictly before \`to\` (the package is half-open everywhere)`
+    );
+  }
+  return { from, to };
+}
+function spanOf(range) {
+  const m = /^(\d+)([hd])$/.exec(range);
+  if (!m) return null;
+  return Number(m[1]) * (m[2] === "h" ? 36e5 : 864e5);
+}
+function intervalForRange(range, now = /* @__PURE__ */ new Date()) {
+  if (typeof range === "string" && RANGE_MS[range] != null) {
+    return range === "1h" || range === "24h" ? "hour" : range === "90d" ? "week" : "day";
+  }
+  const { from, to } = rangeOf(range, now);
+  const ms = to.getTime() - from.getTime();
+  if (ms <= 864e5) return "hour";
+  if (ms < 90 * 864e5) return "day";
+  return "week";
+}
+var INTERVAL_RANK = { hour: 0, day: 1, week: 2, month: 3 };
+var shift = (range) => ({
+  from: new Date(range.from.getTime() - (range.to.getTime() - range.from.getTime())),
+  to: range.from
+});
+function expandSource(source, catalog) {
+  if ("event" in source) {
+    if (!catalog.events[source.event]) {
+      return unavailable(
+        `no event named "${source.event}" is registered \u2014 the catalog knows ${count(Object.keys(catalog.events).length, "event")}, so either the name is a typo or the registry never declared it`
+      );
+    }
+    return { form: "event", events: [source.event] };
+  }
+  if ("namespace" in source) {
+    const events = catalog.namespaces[source.namespace];
+    if (!events?.length) {
+      return unavailable(
+        `no event name starts with "${source.namespace}." \u2014 the registered namespaces are ${Object.keys(catalog.namespaces).join(", ")}`
+      );
+    }
+    return { form: "namespace", events: [...events] };
+  }
+  if ("kind" in source) {
+    const events = Object.keys(catalog.events).filter((n) => catalog.events[n].kind === source.kind);
+    if (!events.length) {
+      return unavailable(
+        `no event is registered with kind "${source.kind}" \u2014 declare one, or pick a kind the registry uses`
+      );
+    }
+    return { form: "kind", events, kind: source.kind };
+  }
+  const family = catalog.families[source.family];
+  if (!family) {
+    return unavailable(
+      `no rollup family "${source.family}" is declared \u2014 add a \`rollups: [{ as: '${source.family}', by: [...] }]\` block to the event that should feed it`
+    );
+  }
+  return { form: "family", events: [...family.feeders], family };
+}
+var FILTER_ONLY = {
+  "field:subject": "subject",
+  "field:traceId": "traceId"
+};
+function dimsFor(catalog, events) {
+  const out = /* @__PURE__ */ new Map();
+  for (const d of catalog.envelope) out.set(d.key, d);
+  for (const name of events) {
+    for (const d of catalog.events[name]?.dims ?? []) {
+      const seen = out.get(d.key);
+      out.set(d.key, seen ? { ...seen, indexed: seen.indexed && d.indexed } : d);
+    }
+  }
+  return out;
+}
+var measureDeclared = (catalog, events, key) => key === "count" || events.some((n) => catalog.events[n]?.measures.some((m) => m.key === key));
+var MEASURE_OP = /^(sum|avg|p50|p90|p95|p99):(.+)$/;
+var unavailable = (why) => ({ unavailable: true, why });
+var count = (n, noun) => `${n} ${noun}${n === 1 ? "" : "s"}`;
+function resolveReport(report, catalog, opts = {}) {
+  const now = opts.now ?? /* @__PURE__ */ new Date();
+  const limits = opts.limits ?? {};
+  const src = expandSource(report.source, catalog);
+  if ("unavailable" in src) return src;
+  const measure = report.measure ?? "count";
+  const groupBy = report.groupBy ?? [];
+  if (groupBy.length > 2) {
+    return unavailable(
+      `groupBy takes at most 2 dimensions, got ${groupBy.length} (${groupBy.join(", ")}) \u2014 three dims is a pivot table nobody can read and a group count that multiplies`
+    );
+  }
+  if (report.interval && INTERVAL_RANK[report.interval] == null) {
+    return unavailable(`interval "${report.interval}" is not one of hour, day, week, month`);
+  }
+  if (measure === "funnel") return planFunnel(report, catalog, now, limits);
+  if (measure.startsWith("distinct:")) return planDistinct(report, catalog, src, measure, now);
+  const opMatch = MEASURE_OP.exec(measure);
+  if (measure !== "count" && !opMatch) {
+    return unavailable(
+      `measure "${measure}" is not a measure \u2014 use 'count', 'sum:<metric>', 'avg:<metric>', 'p50|p95|p99:<metric>', 'distinct:<subjectType>' or 'funnel'`
+    );
+  }
+  if (opMatch && !measureDeclared(catalog, src.events, measure)) {
+    return unavailable(
+      `"${measure}" names a metric no source event declares \u2014 add \`${opMatch[2]}\` to the \`metrics\` object of ${src.events.join(", ")}, or pick one of ${metricList(catalog, src.events)}`
+    );
+  }
+  const exact = planRollups(report, catalog, src, measure, groupBy, now, limits);
+  if (exact) return exact;
+  const filter = toRecordFilter(report, catalog, src);
+  if ("unavailable" in filter) return filter;
+  const range = rangeOf(report.range, now);
+  const dims = dimsFor(catalog, src.events);
+  const touched = [...groupBy, ...(report.filters ?? []).map((f) => f.dim)];
+  const unindexed = touched.find((k) => !(dims.get(k)?.indexed ?? FILTER_ONLY[k] != null));
+  const scanWhy = unindexed ? ` \u2014 "${unindexed}" has no index behind it, so this is a collection scan bounded only by the range` + (unindexed.startsWith("attr:") ? `; add "${unindexed.slice(5)}" to \`indexedAttrs\` to make it a lookup` : "") : "";
+  const exactness = unindexed != null ? "scan" : "raw";
+  if (opMatch && opMatch[1] !== "sum" && opMatch[1] !== "avg") {
+    if (groupBy.length) {
+      return unavailable(
+        `percentiles per group are not offered yet (reports \xA713) \u2014 "${measure}" with groupBy ${groupBy.join(", ")} would be one distribution() read per group. Drop the groupBy, or filter to one group and ask again`
+      );
+    }
+    return withCompare(report, {
+      primitive: "distribution",
+      args: [range, filter, { measure: opMatch[2] }],
+      exactness,
+      why: `${measure} is approximate by construction ($percentile t-digest over the matched records)${scanWhy}`
+    });
+  }
+  if (groupBy.length) {
+    const bad = groupBy.find((k) => !dims.has(k));
+    if (bad) {
+      return unavailable(
+        `"${bad}" is not a dimension of ${describe(src)} \u2014 group by one of ${[...dims.keys()].join(", ")}`
+      );
+    }
+    return withCompare(report, {
+      primitive: "breakdown",
+      args: [
+        range,
+        filter,
+        {
+          groupBy,
+          measure,
+          ...report.interval ? { interval: report.interval } : {},
+          ...report.limit ? { limit: capped(report.limit, limits.breakdown) } : {}
+        }
+      ],
+      exactness,
+      why: `raw ${measure} by ${groupBy.join(" \xD7 ")} over the range${scanWhy}`
+    });
+  }
+  if (!report.measure && !report.interval) {
+    return withCompare(report, {
+      primitive: "records",
+      args: [range, filter, report.limit ? { limit: capped(report.limit, limits.records) } : {}],
+      exactness,
+      why: `the matching records themselves, newest first${scanWhy}`
+    });
+  }
+  const interval = report.interval ?? intervalForRange(report.range, now);
+  return withCompare(report, {
+    primitive: "series",
+    args: [range, filter, { measure, interval }],
+    exactness,
+    why: `raw ${measure} per ${interval} over the range${scanWhy}`
+  });
+}
+var capped = (limit, cap) => cap == null ? limit : Math.max(1, Math.min(limit, cap));
+var describe = (src) => src.form === "family" ? `family "${src.family.as}"` : src.events.join(", ");
+var metricList = (catalog, events) => {
+  const keys = /* @__PURE__ */ new Set();
+  for (const n of events) for (const m of catalog.events[n]?.measures ?? []) keys.add(m.key);
+  return keys.size ? [...keys].join(", ") : "nothing but count";
+};
+function planFunnel(report, catalog, now, limits) {
+  const stages = report.stages ?? [];
+  if (!stages.length) {
+    return unavailable(
+      "`measure: 'funnel'` needs `stages` \u2014 one or more lifetime `by: ['subject']` rollup family names, in the order a subject reaches them"
+    );
+  }
+  const anchor = report.anchor ?? stages[0];
+  const exits = report.exits ?? [];
+  for (const as of [...stages, anchor, ...exits]) {
+    const refusal = milestoneRefusal(catalog, as);
+    if (refusal) return unavailable(refusal);
+  }
+  const first = catalog.families[stages[0]];
+  for (const as of [...stages.slice(1), anchor]) {
+    const f = catalog.families[as];
+    if (!sameSet(f.subjectTypes, first.subjectTypes)) {
+      return unavailable(
+        `funnel stages must share one subject type: "${stages[0]}" is declared \`subjects: [${first.subjectTypes.join(", ")}]\` and "${as}" is \`subjects: [${f.subjectTypes.join(", ")}]\` \u2014 two populations cannot convert into each other`
+      );
+    }
+  }
+  if (report.subjectType && !first.subjectTypes.includes(report.subjectType)) {
+    return unavailable(
+      `subjectType "${report.subjectType}" is not one of the stages' subjects (${first.subjectTypes.join(", ")}) \u2014 the cohort would be empty`
+    );
+  }
+  if (report.interval === "hour") {
+    return unavailable(
+      "funnel slices are day, week or month \u2014 an hourly cohort slice is not offered, because a cohort is assembled from lifetime milestones with no hourly grain to slice on"
+    );
+  }
+  const params = {
+    stages: stages.map((as) => ({ as })),
+    anchor,
+    ...exits.length ? { exits: exits.map((as) => ({ as })) } : {},
+    cohort: rangeOf(report.range, now),
+    ...report.subjectType ? { subjectType: report.subjectType } : {},
+    ...report.interval ? { interval: report.interval } : {},
+    ...report.limit ? { limit: capped(report.limit, limits.funnel) } : {}
+  };
+  return withCompare(report, {
+    primitive: "funnel",
+    args: [params],
+    exactness: "exact",
+    via: anchor,
+    why: `cohort funnel over ${count(stages.length, "lifetime milestone family")}, anchored on "${anchor}" \u2014 rollups only, no raw scan`
+  });
+}
+function milestoneRefusal(catalog, as) {
+  const f = catalog.families[as];
+  if (!f) {
+    return `no rollup family "${as}" is declared. Add a \`rollups: [{ as: '${as}', by: ['subject'], subjects: [...] }]\` block to the event that marks it`;
+  }
+  const shape = `by: [${f.by.map((d) => `'${d}'`).join(", ")}]${f.bucket ? `, bucket: '${f.bucket}'` : ""}`;
+  if (!f.lifetime) {
+    return `rollup family "${as}" (declared on "${f.feeders[0]}") is BUCKETED (${shape}). A milestone needs a lifetime family so \`firstAt\` is the one moment the subject reached it; a bucketed family has one doc per period and would count the same subject repeatedly`;
+  }
+  if (f.by.length !== 1 || f.by[0] !== "subject") {
+    return `rollup family "${as}" (declared on "${f.feeders[0]}") is keyed ${shape}, but a milestone must be keyed by exactly one subject dim (\`by: ['subject']\`). Extra dims split one subject across several docs, which would over-count every stage`;
+  }
+  return null;
+}
+function planDistinct(report, catalog, src, measure, now) {
+  const subjectType = measure.slice("distinct:".length);
+  if (!subjectType) {
+    return unavailable(
+      `"${measure}" needs a subject type \u2014 'distinct:account', one of ${catalog.subjectTypes.join(", ")}`
+    );
+  }
+  if (!catalog.subjectTypes.includes(subjectType)) {
+    return unavailable(
+      `no event or rollup declares the subject type "${subjectType}" \u2014 the registry knows ${catalog.subjectTypes.join(", ") || "no subject types at all"}`
+    );
+  }
+  if (report.groupBy?.length) {
+    return unavailable(
+      `distinct counts take no groupBy: distinctCount() answers one series per family, and "${report.groupBy.join(", ")}" would need a family keyed by those dims AND \`by: ['subject']\`, which cannot count subjects exactly`
+    );
+  }
+  const wanted = new Set(src.events);
+  const fits = Object.values(catalog.families).filter(
+    (f) => f.bucket != null && f.by.length === 1 && f.by[0] === "subject" && f.subjectTypes.includes(subjectType) && src.events.every((e) => f.feeders.includes(e))
+  );
+  const family = fits.find((f) => sameSet(f.feeders, [...wanted])) ?? fits[0];
+  if (!family) {
+    return unavailable(
+      `no bucketed \`by: ['subject']\` family covers ${src.events.join(", ")} for subject type "${subjectType}" \u2014 declare \`rollups: [{ as: 'activity', by: ['subject'], subjects: ['${subjectType}'], bucket: 'day' }]\` on the events that count as activity`
+    );
+  }
+  const superset = !sameSet(family.feeders, [...wanted]);
+  return withCompare(report, {
+    primitive: "distinctCount",
+    args: [
+      {
+        as: family.as,
+        subjectType,
+        range: rangeOf(report.range, now),
+        ...report.interval ? { interval: report.interval } : {}
+      }
+    ],
+    exactness: "exact",
+    via: family.as,
+    why: `"${family.as}" writes exactly one doc per (subject, ${family.bucket}), so distinct subjects IS the doc count \u2014 exact, no sketch` + (superset ? `. Its feeders (${family.feeders.join(", ")}) are a SUPERSET of the source (${src.events.join(", ")}), so the count includes subjects who only did the others` : "")
+  });
+}
+var famDims = (f) => f.by.map((b) => b === "subject" ? "subjectType" : b);
+function planRollups(report, catalog, src, measure, groupBy, now, limits) {
+  if (report.excludeActorTypes?.length) return null;
+  const candidates = src.family ? [src.family] : Object.values(catalog.families).filter((f) => sameSet(f.feeders, src.events));
+  const op = MEASURE_OP.exec(measure);
+  const filters = report.filters ?? [];
+  const fits = candidates.filter((f) => {
+    const dims2 = famDims(f);
+    if (!groupBy.every((k) => dims2.includes(k))) return false;
+    if (report.interval && (!f.bucket || INTERVAL_RANK[f.bucket] > INTERVAL_RANK[report.interval])) return false;
+    if (op) {
+      if (op[1] !== "sum" && op[1] !== "avg" || !f.sums.includes(op[2])) return false;
+    }
+    return filters.every(
+      (t) => dims2.includes(t.dim) && (t.op === "eq" || t.op === "in") || nameFilterCovers(t, f)
+    );
+  });
+  const family = fits.sort((a, b) => a.by.length - b.by.length)[0];
+  if (!family) return null;
+  const dims = famDims(family);
+  const range = rangeOf(report.range, now);
+  const on = family.lifetime ? "firstAt" : "bucketAt";
+  const fold = filters.filter((t) => dims.includes(t.dim));
+  return withCompare(report, {
+    primitive: "rollups",
+    args: [
+      {
+        as: family.as,
+        on,
+        range,
+        sort: family.lifetime ? "count" : "bucketAt",
+        ...report.limit ? { limit: capped(report.limit, limits.rollups) } : {}
+      }
+    ],
+    exactness: "exact",
+    via: family.as,
+    shape: {
+      groupBy,
+      labels: groupBy.map((k) => family.labels[dims.indexOf(k)]),
+      measure,
+      ...report.interval ? { interval: report.interval } : {},
+      ...fold.length ? { filters: fold.map((t) => ({ ...t, label: family.labels[dims.indexOf(t.dim)] })) } : {}
+    },
+    why: `family "${family.as}" is keyed by ${dims.join(", ") || "nothing but its feeders"} and maintained on write, so this is one indexed rollup read over \`${on}\` instead of a raw scan` + (op?.[1] === "avg" ? `. avg:${op[2]} is exact off a rollup: the executor divides sums.${op[2]} by count` : "") + (report.interval && family.bucket !== report.interval ? `. Its ${family.bucket} buckets roll up into ${report.interval} without splitting one` : "")
+  });
+}
+function nameFilterCovers(t, f) {
+  if (t.dim !== "field:name") return false;
+  const admitted = t.op === "eq" ? [String(t.value)] : t.op === "in" ? [...t.value].map(String) : null;
+  return admitted != null && f.feeders.every((n) => admitted.includes(n));
+}
+var FIELD_TERMS = {
+  "field:kind": "kind",
+  "field:name": "name",
+  "field:severity": "severity",
+  "field:env": "env",
+  "field:service": "service",
+  "field:release": "release",
+  ...FILTER_ONLY
+};
+function toRecordFilter(report, catalog, src) {
+  const filter = {};
+  if (src.events.length === 1) {
+    filter.name = src.events[0];
+  } else if (src.kind) {
+    filter.kind = src.kind;
+  } else {
+    filter.name = [...src.events];
+  }
+  for (const t of report.filters ?? []) {
+    const term = FIELD_TERMS[t.dim];
+    if (term) {
+      if (t.op !== "eq") {
+        return unavailable(
+          `"${t.dim}" supports equality only on the raw path \u2014 RecordFilter.${String(term)} is one string, and "${t.op}" would need a term query.ts does not build`
+        );
+      }
+      filter[term] = String(t.value);
+      continue;
+    }
+    if (t.dim.startsWith("attr:")) {
+      const key = t.dim.slice(5);
+      if (t.op === "eq") {
+        (filter.attrs ??= {})[key] = String(t.value);
+        continue;
+      }
+      if (t.op === "gte" || t.op === "lte") {
+        if (!measureDeclared(catalog, src.events, `sum:${key}`)) {
+          return unavailable(
+            `"${t.dim} ${t.op}" is a numeric bound, which only a declared metric can carry \u2014 add \`${key}\` to the \`metrics\` object of ${src.events.join(", ")}, or filter it as an equality`
+          );
+        }
+        const range = (filter.metrics ??= {})[key] ??= {};
+        range[t.op] = Number(t.value);
+        continue;
+      }
+      return unavailable(
+        `"${t.dim}" supports equality (or a gte/lte bound on a metric) \u2014 an \`in\` over attrs would need a \`$in\` term buildMatch does not write`
+      );
+    }
+    if (t.dim === "subjectType" || t.dim === "actorType") {
+      return unavailable(
+        `"${t.dim}" is derived at query time from ${t.dim === "subjectType" ? "`subjectKeys`" : "`actor`"} and RecordFilter has no term for it \u2014 group by it instead, pin one subject with \`field:subject\`` + (t.dim === "actorType" ? ", or use `excludeActorTypes`" : "")
+      );
+    }
+    return unavailable(
+      `"${t.dim}" is not filterable on the raw path \u2014 RecordFilter carries ${Object.keys(FIELD_TERMS).join(", ")}, \`attr:<key>\` and metric bounds`
+    );
+  }
+  if (report.excludeActorTypes?.length) filter.excludeActorTypes = [...report.excludeActorTypes];
+  return filter;
+}
+function withCompare(report, plan) {
+  if (report.compare !== "previous") return plan;
+  const [first, ...rest] = plan.args;
+  if (plan.primitive === "rollups" || plan.primitive === "distinctCount" || plan.primitive === "funnel") {
+    const params = first;
+    const key = plan.primitive === "funnel" ? "cohort" : "range";
+    const window = params[key];
+    if (!window) return plan;
+    return { ...plan, previous: { args: [{ ...params, [key]: { ...window, ...shift(window) } }, ...rest] } };
+  }
+  return { ...plan, previous: { args: [shift(first), ...rest] } };
+}
+var sameSet = (a, b) => a.length === b.length && a.every((x) => b.includes(x));
+var LEGACY_DIMS = {
+  kind: "field:kind",
+  name: "field:name",
+  severity: "field:severity",
+  env: "field:env",
+  service: "field:service",
+  release: "field:release",
+  subject: "field:subject",
+  traceId: "field:traceId"
+};
+function normalizeQuery(query) {
+  if (!query || typeof query !== "object") return null;
+  if ("source" in query && query.source) return query;
+  const q = query;
+  const filters = q.filters ?? {};
+  const str = (v) => typeof v === "string" && v ? v : null;
+  const name = str(filters.name);
+  const family = str(filters.rollup);
+  const kind = str(filters.kind);
+  const source = name ? { event: name } : family ? { family } : kind ? { kind } : null;
+  if (!source) return null;
+  const consumed = name ? "name" : family ? "rollup" : "kind";
+  const terms = [];
+  for (const [k, v] of Object.entries(filters)) {
+    if (k === consumed || k === "rollup") continue;
+    if (k === "excludeActorTypes") continue;
+    if (k === "attrs") {
+      const entries = typeof v === "string" ? v.split(",").map((pair) => pair.split(":").map((s) => s.trim())) : Object.entries(v ?? {}).map(([a, b]) => [a, String(b)]);
+      for (const [key, value2] of entries) {
+        if (key && value2 != null) terms.push({ dim: `attr:${key}`, op: "eq", value: String(value2) });
+      }
+      continue;
+    }
+    const dim2 = LEGACY_DIMS[k];
+    const value = str(v);
+    if (dim2 && value) terms.push({ dim: dim2, op: "eq", value });
+  }
+  const groupBy = (q.groupBy ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+  const sort = q.sort === "value" || q.sort === "label" || q.sort === "time" ? q.sort : void 0;
+  const actors = filters.excludeActorTypes;
+  return {
+    source,
+    range: q.range ?? "7d",
+    ...terms.length ? { filters: terms } : {},
+    ...groupBy.length ? { groupBy } : {},
+    ...sort ? { sort } : {},
+    ...Array.isArray(actors) && actors.length ? { excludeActorTypes: actors.map(String) } : {}
+  };
+}
+
+// src/server/views.ts
 function buildViewModel(connection, modelName, collection) {
   const existing = connection.models?.[modelName];
   if (existing) return existing;
@@ -618,31 +1581,58 @@ var KIND_PAGE = {
   state: "journeys",
   usage: "usage"
 };
-function deriveViews(registry) {
+function deriveViews(registry, catalog = deriveCatalog(registry)) {
   const views = [];
-  const families = /* @__PURE__ */ new Set();
-  for (const [name, spec] of Object.entries(registry)) {
-    views.push({
-      origin: "derived",
-      name,
-      page: KIND_PAGE[spec.kind] ?? "events",
-      query: { range: "7d", filters: { name }, display: spec.kind === "event" ? "series" : "table" }
+  const derived = (name, page, query) => views.push({ origin: "derived", name, page, query });
+  for (const [name, e] of Object.entries(catalog.events)) {
+    derived(name, KIND_PAGE[e.kind] ?? "events", {
+      source: { event: name },
+      range: "7d",
+      interval: intervalForRange("7d")
     });
-    for (const r of spec.rollups ?? []) families.add(r.as ?? name);
-  }
-  for (const as of families) {
-    views.push({
-      origin: "derived",
-      name: `rollup: ${as}`,
-      page: "journeys",
-      query: { range: "30d", filters: { rollup: as }, display: "breakdown" }
+  }
+  for (const as of Object.keys(catalog.families)) {
+    derived(`rollup: ${as}`, "journeys", { source: { family: as }, range: "30d" });
+  }
+  for (const [ns, names] of Object.entries(catalog.namespaces)) {
+    if (names.length < 2) continue;
+    derived(`namespace: ${ns}`, "explore", {
+      source: { namespace: ns },
+      range: "30d",
+      interval: "day",
+      groupBy: ["field:name"]
+    });
+  }
+  for (const [name, e] of Object.entries(catalog.events)) {
+    if (e.kind !== "usage") continue;
+    const money = e.measures.find((m) => m.key.startsWith("sum:") && m.key.endsWith("_usd"));
+    if (!money) continue;
+    derived(`spend: ${name}`, "usage", {
+      source: { event: name },
+      range: "30d",
+      interval: "day",
+      measure: money.key
+    });
+  }
+  for (const subjectType of catalog.subjectTypes) {
+    const stages = Object.values(catalog.families).filter((f) => f.lifetime && f.by.length === 1 && f.by[0] === "subject" && f.subjectTypes.includes(subjectType)).map((f) => f.as);
+    if (stages.length < 2) continue;
+    derived(`funnel: ${subjectType}`, "journeys", {
+      // any source expands; the family the funnel is anchored on is the honest one
+      source: { family: stages[0] },
+      range: "30d",
+      interval: "week",
+      measure: "funnel",
+      stages,
+      anchor: stages[0],
+      subjectType
     });
   }
   return views;
 }
 async function resolveViews(opts) {
   const byName = /* @__PURE__ */ new Map();
-  for (const v of deriveViews(opts.registry)) byName.set(v.name, v);
+  for (const v of deriveViews(opts.registry, opts.catalog)) byName.set(v.name, v);
   for (const v of opts.configured) byName.set(v.name, { ...v, origin: "configured" });
   const saved = await opts.ViewModel.find({
     tenantId: opts.tenantId,
@@ -660,6 +1650,286 @@ async function resolveViews(opts) {
   return [...byName.values()];
 }
 
+// src/server/suggest.ts
+var UNREGISTERED_REASON = "unregistered event";
+var MAX_SUGGESTIONS = 50;
+var NAME_MAX = 120;
+var quote = (s) => /^[A-Za-z0-9_.:$-]+$/.test(s) ? `'${s}'` : JSON.stringify(s);
+var prop = (s) => /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(s) ? s : quote(s);
+var times = (n) => `${n} time${n === 1 ? "" : "s"}`;
+var split = (k) => {
+  const i = k.indexOf("|");
+  return i === -1 ? [k, ""] : [k.slice(0, i), k.slice(i + 1)];
+};
+function deriveSuggestions(input) {
+  const { counters, catalog, quarantine = [] } = input;
+  const out = [];
+  for (const [k, count2] of Object.entries(counters.undeclaredAttrs ?? {})) {
+    if (k === COUNTER_OVERFLOW_KEY || !count2) continue;
+    const [name, key] = split(k);
+    if (!name || !key) continue;
+    const facet = catalog.events[name];
+    const line = `${prop(key)}: z.string().max(64),`;
+    const hasAttrs = !!facet?.dims.some((d) => d.key.startsWith("attr:"));
+    out.push({
+      kind: "undeclared_attr",
+      target: name,
+      key,
+      count: count2,
+      message: `\`${name}\` has been sent with attr \`${key}\` ${times(count2)} \u2014 not declared`,
+      fix: hasAttrs ? line : `attrs: z.object({ ${prop(key)}: z.string().max(64) }),`
+    });
+  }
+  for (const [k, count2] of Object.entries(counters.rollupSkippedBy ?? {})) {
+    if (k === COUNTER_OVERFLOW_KEY || !count2) continue;
+    const [as, dim2] = split(k);
+    if (!as || !dim2) continue;
+    const feeders = catalog.families[as]?.feeders ?? [];
+    const where = feeders.length ? `// on the \`${as}\` rollup of ${feeders.map((f) => `\`${f}\``).join(", ")}
+` : "";
+    out.push({
+      kind: "missing_dim_default",
+      target: as,
+      key: dim2,
+      count: count2,
+      message: `\`${as}\` skipped ${count2} record${count2 === 1 ? "" : "s"} with no \`${dim2}\` \u2014 declare \`dimDefault\``,
+      fix: `${where}dimDefault: 'unknown',`
+    });
+  }
+  const unregistered = /* @__PURE__ */ new Map();
+  for (const row of quarantine) {
+    if (typeof row?.reason !== "string" || !row.reason.includes(UNREGISTERED_REASON)) continue;
+    const name = typeof row.name === "string" ? row.name.slice(0, NAME_MAX) : "";
+    if (!name || name === "(unnamed)") continue;
+    unregistered.set(name, (unregistered.get(name) ?? 0) + 1);
+  }
+  for (const [name, count2] of unregistered) {
+    out.push({
+      kind: "unregistered_event",
+      target: name,
+      count: count2,
+      message: `\`${name}\` was rejected ${times(count2)} \u2014 not in the registry`,
+      // the minimum that boots: validateRegistry wants a kind, an origin, and
+      // a subjects array, and nothing here can guess the rest
+      fix: `${quote(name)}: { kind: 'event', origin: 'client', subjects: [], description: '' },`
+    });
+  }
+  out.sort(
+    (a, b) => b.count - a.count || a.target.localeCompare(b.target) || (a.key ?? "").localeCompare(b.key ?? "")
+  );
+  return out.slice(0, MAX_SUGGESTIONS);
+}
+
+// src/server/values.ts
+var empty = (source) => ({
+  values: [],
+  source,
+  truncated: false,
+  dataSource: source
+});
+var SAMPLED_COUNT = { $sum: { $divide: [1, { $ifNull: ["$sampleRate", 1] }] } };
+function createValues(ctx) {
+  const limits = { ...DEFAULT_LIMITS, ...ctx.limits };
+  const slowMs = ctx.slowMs ?? 500;
+  const cache = new QueryCache(ctx.cacheTtlMs ?? 10 * 6e4, ctx.cacheSize ?? 60);
+  const { catalog } = ctx;
+  const timed = async (op, params, run) => {
+    const t0 = Date.now();
+    try {
+      return await run();
+    } finally {
+      const ms = Date.now() - t0;
+      if (ms > slowMs) ctx.onSlowQuery?.({ op, ms, params });
+    }
+  };
+  const eventNames = (names) => names?.length ? names.filter((n) => catalog.events[n]) : Object.keys(catalog.events);
+  function fromCatalog(dim2, names) {
+    const facets = [];
+    for (const d of catalog.envelope) if (d.key === dim2) facets.push(d);
+    for (const name of eventNames(names)) {
+      for (const d of catalog.events[name].dims) if (d.key === dim2) facets.push(d);
+    }
+    const out = [];
+    for (const f of facets) for (const v of f.values ?? []) if (!out.includes(v)) out.push(v);
+    return out;
+  }
+  function pickFamily(dim2, names) {
+    if (dim2 === "subjectType" || dim2 === "actorType") return null;
+    const matches = Object.values(catalog.families).map((f) => ({ f, index: f.by.indexOf(dim2) })).filter(({ f, index }) => index !== -1 && (!names?.length || f.feeders.some((n) => names.includes(n)))).sort((a, b) => a.f.by.length - b.f.by.length || a.f.as.localeCompare(b.f.as));
+    const best = matches[0];
+    return best ? { as: best.f.as, index: best.index, label: best.f.labels[best.index] } : null;
+  }
+  function rawReadable(dim2, names) {
+    try {
+      dimExpression(dim2);
+    } catch {
+      return false;
+    }
+    if (!dim2.startsWith("attr:")) return true;
+    const key = dim2.slice(5);
+    return eventNames(names).some((n) => catalog.events[n].indexedAttrs.includes(key));
+  }
+  return async function values(scope, params) {
+    const { dim: dim2, names, range } = params;
+    if (!dim2) return empty("none");
+    const cap = Math.min(Math.max(1, params.limit ?? limits.values), limits.values);
+    const key = JSON.stringify([
+      "values",
+      scope,
+      dim2,
+      names ?? null,
+      range?.from ?? null,
+      range?.to ?? null,
+      cap
+    ]);
+    return cache.get(
+      key,
+      () => timed("values", { scope, dim: dim2, names }, async () => {
+        const declared = fromCatalog(dim2, names);
+        if (declared.length) {
+          return { values: declared, source: "catalog", truncated: false, dataSource: "catalog" };
+        }
+        const family = pickFamily(dim2, names);
+        if (family) {
+          const rows2 = await ctx.RollupModel.aggregate([
+            {
+              $match: {
+                ...isPlatformScope(scope) ? {} : { tenantId: scope },
+                as: family.as
+              }
+            },
+            { $project: { v: { $arrayElemAt: ["$dims", family.index] }, count: 1 } },
+            { $match: { v: { $type: "string" } } },
+            { $group: { _id: "$v", count: { $sum: "$count" } } },
+            { $sort: { count: -1, _id: 1 } },
+            { $limit: cap + 1 }
+          ]);
+          const truncated2 = rows2.length > cap;
+          if (truncated2) rows2.pop();
+          const prefix = `${family.label}=`;
+          return {
+            values: rows2.map(
+              (r) => String(r._id).startsWith(prefix) ? String(r._id).slice(prefix.length) : String(r._id)
+            ),
+            counts: rows2.map((r) => r.count),
+            source: "rollups",
+            via: family.as,
+            truncated: truncated2,
+            dataSource: "rollups"
+          };
+        }
+        if (!rawReadable(dim2, names)) return empty("none");
+        if (!range) return empty("none");
+        const rows = await ctx.TelemetryModel.aggregate([
+          { $match: buildMatch(scope, range, names?.length ? { name: names } : {}) },
+          { $group: { _id: dimExpression(dim2), count: SAMPLED_COUNT } },
+          // a "no value" is not a value to pick — the null group is real
+          // (breakdown reports it) but it is not something a filter can name
+          { $match: { _id: { $ne: null } } },
+          { $sort: { count: -1, _id: 1 } },
+          { $limit: cap + 1 }
+        ]);
+        const truncated = rows.length > cap;
+        if (truncated) rows.pop();
+        return {
+          values: rows.map((r) => String(r._id)),
+          counts: rows.map((r) => r.count),
+          source: "raw",
+          truncated,
+          dataSource: "raw"
+        };
+      })
+    );
+  };
+}
+
+// src/server/execute.ts
+async function executeReport(q, scope, report, catalog, opts = {}) {
+  const plan = resolveReport(report, catalog, { now: opts.now, limits: opts.limits });
+  if ("unavailable" in plan) throw Object.assign(new Error(plan.why), { status: 400 });
+  const run = async (args) => {
+    const raw = await q[plan.primitive](scope, ...args);
+    if (plan.primitive === "rollups" && plan.shape) {
+      return foldRollups(raw?.rows ?? [], plan.shape, !!raw?.truncated);
+    }
+    if (plan.primitive === "records" && opts.redact) {
+      return { ...raw, items: opts.redact(raw?.items ?? []) };
+    }
+    return raw;
+  };
+  const [result, previous] = await Promise.all([
+    run(plan.args),
+    plan.previous ? run(plan.previous.args) : Promise.resolve(void 0)
+  ]);
+  return {
+    report,
+    plan,
+    result,
+    ...plan.previous ? { previous } : {},
+    dataSource: result?.dataSource ?? "raw"
+  };
+}
+var MEASURE_OP2 = /^(sum|avg):(.+)$/;
+function foldRollups(rows, shape, truncated = false) {
+  const op = MEASURE_OP2.exec(shape.measure);
+  const groups = /* @__PURE__ */ new Map();
+  for (const doc of rows) {
+    const dims = doc?.dims ?? [];
+    if (!(shape.filters ?? []).every((f) => admits(f, dimValue(dims, f.label)))) continue;
+    const tuple = shape.labels.map((label2) => dimValue(dims, label2));
+    const at = shape.interval && doc.bucketAt ? truncate(new Date(doc.bucketAt), shape.interval) : void 0;
+    const key = `${JSON.stringify(tuple)}|${at ? at.getTime() : ""}`;
+    let g = groups.get(key);
+    if (!g) groups.set(key, g = { dims: tuple, ...at ? { at } : {}, sum: 0, count: 0 });
+    g.count += typeof doc.count === "number" ? doc.count : 0;
+    if (op) g.sum += sumOf(doc.sums, op[2]);
+  }
+  const rowsOut = [...groups.values()].map((g) => ({
+    dims: g.dims,
+    ...g.at ? { at: g.at } : {},
+    // avg is sums[k]/count off the SAME doc, which is exact — not an average of
+    // averages, which is what folding a per-bucket mean would have produced
+    value: !op ? g.count : op[1] === "sum" ? g.sum : g.count ? g.sum / g.count : 0
+  }));
+  rowsOut.sort(
+    shape.interval ? (a, b) => (a.at?.getTime() ?? 0) - (b.at?.getTime() ?? 0) || byDims(a, b) : (a, b) => b.value - a.value || byDims(a, b)
+  );
+  return {
+    rows: rowsOut,
+    groups: new Set([...groups.values()].map((g) => JSON.stringify(g.dims))).size,
+    truncated,
+    dataSource: "rollups"
+  };
+}
+function dimValue(dims, label2) {
+  const prefix = `${label2}=`;
+  for (const d of dims) if (d.startsWith(prefix)) return d.slice(prefix.length);
+  for (const d of dims) if (!d.includes("=")) return d;
+  return null;
+}
+function admits(f, value) {
+  if (f.op === "in") return f.value.map(String).includes(String(value));
+  if (f.op === "gte" || f.op === "lte") {
+    const n = Number(value);
+    if (Number.isNaN(n)) return false;
+    return f.op === "gte" ? n >= Number(f.value) : n <= Number(f.value);
+  }
+  return String(value) === String(f.value);
+}
+function sumOf(sums, key) {
+  if (!sums) return 0;
+  const v = sums instanceof Map ? sums.get(key) : sums[key];
+  return typeof v === "number" ? v : 0;
+}
+function byDims(a, b) {
+  for (let i = 0; i < a.dims.length; i++) {
+    const x = a.dims[i] ?? "";
+    const y = b.dims[i] ?? "";
+    if (x !== y) return x < y ? -1 : 1;
+  }
+  return 0;
+}
+
 // src/server/mcp.ts
 var tenantArg = {
   tenant: zod.z.string().optional().describe(
@@ -672,7 +1942,9 @@ var rangeArg = {
 };
 var filterArg = {
   kind: zod.z.enum(["event", "error", "span", "state", "usage"]).optional(),
-  name: zod.z.string().optional().describe('exact event name, e.g. "user.signed_up" \u2014 see describe_telemetry'),
+  name: zod.z.union([zod.z.string(), zod.z.array(zod.z.string())]).optional().describe(
+    'exact event name, e.g. "user.signed_up" \u2014 or several as an array, read as one $in. See describe_telemetry'
+  ),
   severity: zod.z.string().optional(),
   env: zod.z.string().optional().describe("prod | staging | dev"),
   service: zod.z.string().optional(),
@@ -700,6 +1972,38 @@ function parseRange(from, to) {
   return { from: fromD, to: toD };
 }
 var INTERVAL = zod.z.enum(["hour", "day", "week", "month"]);
+var REPORT_ARG = zod.z.object({
+  source: zod.z.union([
+    zod.z.object({ event: zod.z.string() }),
+    zod.z.object({ namespace: zod.z.string() }),
+    zod.z.object({ kind: zod.z.enum(["event", "error", "span", "state", "usage"]) }),
+    zod.z.object({ family: zod.z.string() })
+  ]).describe(
+    'what is being counted: { event: "llm.completion" } one registered name, { namespace: "billing" } every name under it, { kind: "error" }, or { family: "llm_cost" } to read a rollup family directly'
+  ),
+  range: zod.z.union([zod.z.string(), zod.z.object({ from: zod.z.string(), to: zod.z.string() })]).describe('"7d" / "24h" / "90d", or an explicit half-open { from, to } ISO pair'),
+  interval: INTERVAL.optional().describe("bucket the answer over time"),
+  measure: zod.z.string().optional().describe(
+    'a measure key from the catalog: "count" (default), "sum:<metric>", "avg:<metric>", "p50|p90|p95|p99:<metric>", "distinct:<subjectType>" for exact actives, or "funnel"'
+  ),
+  groupBy: zod.z.array(zod.z.string()).max(2).optional().describe('at most two dims \u2014 "attr:<key>", "field:<path>", "subjectType", "actorType"'),
+  filters: zod.z.array(
+    zod.z.object({
+      dim: zod.z.string().describe('a dim key, e.g. "attr:gen_ai_request_model" or "field:env"'),
+      op: zod.z.enum(["eq", "in", "gte", "lte"]).describe("gte/lte bound a declared metric only"),
+      value: zod.z.union([zod.z.string(), zod.z.array(zod.z.string()), zod.z.number()])
+    })
+  ).optional(),
+  excludeActorTypes: zod.z.array(zod.z.string()).optional().describe('the customer toggle, e.g. ["admin","system"] \u2014 a record with no actor always survives'),
+  sort: zod.z.enum(["value", "label", "time"]).optional(),
+  limit: zod.z.number().int().positive().optional(),
+  compare: zod.z.literal("previous").optional().describe("also run the window immediately before, same length"),
+  // ── funnel only (`measure: "funnel"`) ──
+  stages: zod.z.array(zod.z.string()).optional().describe("lifetime by:['subject'] rollup families, in order"),
+  anchor: zod.z.string().optional().describe("the milestone that assigns cohort membership. Default: stages[0]"),
+  exits: zod.z.array(zod.z.string()).optional().describe("families counted but never staged"),
+  subjectType: zod.z.string().optional()
+});
 function createTelemetryMcp(opts) {
   const { telemetry: t, viewerAdapter, subjectAdapter, configured = [] } = opts;
   if (!viewerAdapter?.resolveViewer) {
@@ -719,6 +2023,16 @@ function createTelemetryMcp(opts) {
     registry: t.registry,
     limits: opts.limits
   });
+  const catalog = deriveCatalog(t.registry, {
+    platforms: t.models.telemetry.schema.path("client")?.schema?.path("platform")?.enumValues
+  });
+  const registry = projectRegistry(catalog);
+  const values = createValues({
+    catalog,
+    TelemetryModel: t.models.telemetry,
+    RollupModel: t.models.rollups,
+    limits: opts.limits
+  });
   const ViewModel = buildViewModel(
     t.models.telemetry.db,
     `${t.models.telemetry.modelName}View`,
@@ -743,17 +2057,45 @@ function createTelemetryMcp(opts) {
     if (!refs.size) return {};
     return subjectAdapter.describe([...refs].slice(0, 100));
   }
+  async function pickReport(scope, viewer, a) {
+    const override = a.from || a.to ? parseRange(a.from, a.to) : null;
+    const withRange = (r) => override ? { ...r, range: { from: override.from.toISOString(), to: override.to.toISOString() } } : r;
+    if (a.report) return { report: withRange(a.report) };
+    if (!a.name) {
+      throw new Error("needs either `name` (a report from list_reports) or an inline `report` object");
+    }
+    const views = await resolveViews({
+      ViewModel,
+      registry: t.registry,
+      catalog,
+      configured,
+      tenantId: scope,
+      viewerRef: viewer.viewerRef
+    });
+    const view = views.find((v) => v.name === a.name);
+    if (!view) throw new Error(`no report named "${a.name}" \u2014 call list_reports for the menu`);
+    const report = normalizeQuery(view.query);
+    if (report) return { name: view.name, report: withRange(report) };
+    const query = view.query ?? {};
+    return {
+      legacy: true,
+      name: view.name,
+      range: override ?? rangeFromView(query.range),
+      filters: query.filters ?? {}
+    };
+  }
+  const planShaped = (report) => resolveReport(report, catalog);
   const tool = (d) => d;
   const tools = [
     // ── vocabulary ──────────────────────────────────────────────────────────
     tool({
       name: "describe_telemetry",
       title: "Describe telemetry schema",
-      description: "The vocabulary of this telemetry instance: every event name with its kind, declared attributes, metrics, indexed filters, and rollup families. CALL THIS FIRST \u2014 every other tool speaks the names it returns.",
+      description: "The vocabulary of this telemetry instance: every event name with its kind, declared attributes, metrics, indexed filters, and rollup families. CALL THIS FIRST \u2014 every other tool speaks the names it returns. Prefer the `catalog` half of the answer over `registry`: it types every dimension, gives the closed value domain of the ones that have one, marks which are indexed (cheap) rather than a scan, lists the measures each event can be aggregated by, and says which rollup family answers a sum exactly.",
       inputSchema: zod.z.object({}),
       async handler(_args, ctx) {
         await resolve(ctx);
-        return { registry: registryProjection(t), kinds: ["event", "error", "span", "state", "usage"] };
+        return { registry, catalog, kinds: ["event", "error", "span", "state", "usage"] };
       }
     }),
     // ── events ──────────────────────────────────────────────────────────────
@@ -825,6 +2167,30 @@ function createTelemetryMcp(opts) {
         });
       }
     }),
+    tool({
+      name: "event_breakdown",
+      title: "Breakdown by dimension",
+      description: "Top groups of a measure by one or two dimensions \u2014 'which models cost the most', 'errors by release', 'events by platform per week'. groupBy takes attr:<key>, field:<path>, subjectType, actorType; see describe_telemetry for the keys. Reports `truncated` when more groups existed than were returned.",
+      inputSchema: zod.z.object({
+        ...filterArg,
+        ...rangeArg,
+        ...tenantArg,
+        groupBy: zod.z.array(zod.z.string()).min(1).max(2).describe('one or two dimensions, e.g. ["attr:gen_ai_request_model"] or ["attr:feature","field:env"]'),
+        measure: zod.z.string().optional().describe('"count" (default), or "sum:<metric>" / "avg:<metric>", e.g. "sum:cost_usd"'),
+        interval: INTERVAL.optional().describe("also split each group by time bucket; rows then carry `at`"),
+        limit: zod.z.number().int().positive().optional().describe("groups returned, not rows scanned")
+      }),
+      async handler(a, ctx) {
+        const viewer = await resolve(ctx);
+        const scope = pickScope(viewer, a.tenant);
+        return q.breakdown(scope, parseRange(a.from, a.to), toFilter(a), {
+          groupBy: a.groupBy,
+          measure: a.measure,
+          interval: a.interval,
+          limit: a.limit
+        });
+      }
+    }),
     tool({
       name: "metric_distribution",
       title: "Metric distribution (percentiles)",
@@ -870,6 +2236,30 @@ function createTelemetryMcp(opts) {
         });
       }
     }),
+    tool({
+      name: "dimension_values",
+      title: "Dimension values",
+      description: "The values a dimension actually takes \u2014 from the registry's enum when it has one, else from what the rollups have seen, else from a raw scan over a range. Use before filtering or grouping so you name a value that exists. `source` says where the answer came from.",
+      inputSchema: zod.z.object({
+        dim: zod.z.string().describe('a dimension key from describe_telemetry: "attr:<key>", "field:<path>", "subjectType" or "actorType"'),
+        names: zod.z.array(zod.z.string()).optional().describe("restrict to these event names \u2014 required for the raw scan, a narrowing hint otherwise"),
+        ...rangeArg,
+        ...tenantArg,
+        limit: zod.z.number().int().positive().optional()
+      }),
+      async handler(a, ctx) {
+        const viewer = await resolve(ctx);
+        const scope = pickScope(viewer, a.tenant);
+        return values(scope, {
+          dim: a.dim,
+          names: a.names,
+          // no range is not an error here: it just means the raw step is off
+          // the table, and `source: 'none'` says so
+          range: a.from || a.to ? parseRange(a.from, a.to) : void 0,
+          limit: a.limit
+        });
+      }
+    }),
     tool({
       name: "active_users",
       title: "Active users (DAU/WAU/MAU)",
@@ -968,6 +2358,7 @@ function createTelemetryMcp(opts) {
         const views = await resolveViews({
           ViewModel,
           registry: t.registry,
+          catalog,
           configured,
           tenantId: scope,
           viewerRef: viewer.viewerRef
@@ -977,26 +2368,52 @@ function createTelemetryMcp(opts) {
     }),
     tool({
       name: "run_report",
-      title: "Run a saved report",
-      description: "Execute one named report from list_reports and return its result. Read-only: the report is a stored filter/range that dispatches to the same query the dashboard would run.",
+      title: "Run a report",
+      description: 'Execute a report and return its answer. Two ways in: `name`, one of the reports list_reports offers, or `report`, an inline Report you compose yourself \u2014 the general "ask telemetry a question" tool. A Report says WHAT is counted (`source`), over what range, sliced by which dimensions (`groupBy`) and by what measure; the planner then picks the primitive that answers it, preferring a pre-aggregated rollup family (exact, one indexed read) over a raw scan. The answer carries the `plan` it ran, including `exactness` (exact / raw / scan) and a `why` sentence \u2014 read them, and prefer an `exact` plan when one exists. If you are unsure a report is answerable or affordable, call plan_report first: it returns the same plan without doing the read. Names and dimensions come from describe_telemetry; `from`/`to` override the report\'s own range. Raw records are redacted like search_events.',
       inputSchema: zod.z.object({
-        name: zod.z.string().describe("the report name from list_reports"),
+        name: zod.z.string().optional().describe("a report name from list_reports \u2014 or pass `report` instead"),
+        report: REPORT_ARG.optional().describe("an inline Report, composed from describe_telemetry's catalog"),
         ...rangeArg,
         ...tenantArg
       }),
       async handler(a, ctx) {
         const viewer = await resolve(ctx);
         const scope = pickScope(viewer, a.tenant);
-        const views = await resolveViews({
-          ViewModel,
-          registry: t.registry,
-          configured,
-          tenantId: scope,
-          viewerRef: viewer.viewerRef
-        });
-        const view = views.find((v) => v.name === a.name);
-        if (!view) throw new Error(`no report named "${a.name}" \u2014 call list_reports for the menu`);
-        return runReport(q, scope, view, a.from, a.to, redactAll);
+        const picked = await pickReport(scope, viewer, a);
+        if ("legacy" in picked) {
+          const res = await q.records(scope, picked.range, toFilter(picked.filters), { limit: 200 });
+          return {
+            name: picked.name,
+            legacy: true,
+            result: { ...res, items: redactAll(res.items) },
+            dataSource: "raw"
+          };
+        }
+        const out = await executeReport(q, scope, picked.report, catalog, { redact: redactAll });
+        return picked.name ? { name: picked.name, ...out } : out;
+      }
+    }),
+    tool({
+      name: "plan_report",
+      title: "Plan a report (dry run)",
+      description: "Ask what a report WOULD cost before you spend the read. Same input as run_report, no query: it returns the plan \u2014 which primitive answers it, with what arguments, and `exactness` (`exact` = maintained rollup docs, `raw` = an indexed scan of records, `scan` = a dimension with no index behind it) \u2014 or `{ unavailable: true, why }` when nothing can answer it. A refusal is an answer, not an error: the `why` names the offending key and the registry change that would make the question answerable, so use it to pick a different measure or dimension rather than retrying the same one.",
+      inputSchema: zod.z.object({
+        name: zod.z.string().optional().describe("a report name from list_reports \u2014 or pass `report` instead"),
+        report: REPORT_ARG.optional().describe("an inline Report, composed from describe_telemetry's catalog"),
+        ...rangeArg,
+        ...tenantArg
+      }),
+      async handler(a, ctx) {
+        const viewer = await resolve(ctx);
+        const scope = pickScope(viewer, a.tenant);
+        const picked = await pickReport(scope, viewer, a);
+        if ("legacy" in picked) {
+          return {
+            unavailable: true,
+            why: `the stored report "${picked.name}" is a pre-Report view whose query names no source, so there is nothing to plan \u2014 run_report reads its records directly. Compose an inline \`report\` to plan one`
+          };
+        }
+        return picked.name ? { name: picked.name, ...planShaped(picked.report) } : planShaped(picked.report);
       }
     }),
     // ── platform ────────────────────────────────────────────────────────────
@@ -1044,62 +2461,35 @@ function createTelemetryMcp(opts) {
     tool({
       name: "telemetry_health",
       title: "Telemetry health",
-      description: 'The health of the telemetry pipeline itself: drop/default/cap counters, quarantined failed writes, and the index budget. Answers "are we silently dropping events?".',
+      description: 'The health of the telemetry pipeline itself: drop/default/cap counters, quarantined failed writes, and the index budget. Answers "are we silently dropping events?" \u2014 and what the data says the registry is missing.',
       inputSchema: zod.z.object({ ...tenantArg }),
       async handler(a, ctx) {
         const viewer = await resolve(ctx);
         const scope = pickScope(viewer, a.tenant);
         const quarantine = await t.collections.rejects().find(isPlatformScope(scope) ? {} : { "raw.tenantId": scope }, { sort: { at: -1 }, limit: 50 }).toArray().catch(() => []);
         const indexes = await t.models.telemetry.collection.indexes().catch(() => []);
-        return { counters: t.counters, quarantine, indexCount: indexes.length };
+        return {
+          counters: t.counters,
+          quarantine,
+          indexCount: indexes.length,
+          suggestions: deriveSuggestions({ counters: t.counters, catalog, quarantine })
+        };
       }
     })
   ];
   return tools;
 }
 var toJsonSchema = (tool) => zod.z.toJSONSchema(tool.inputSchema);
-function registryProjection(t) {
-  return Object.fromEntries(
-    Object.entries(t.registry).map(([name, spec]) => [
-      name,
-      {
-        kind: spec.kind,
-        description: spec.description,
-        attrKeys: spec.attrs ? Object.keys(spec.attrs.shape) : [],
-        metricKeys: spec.metrics ? Object.keys(spec.metrics.shape) : [],
-        indexedAttrs: spec.indexedAttrs ?? [],
-        indexedMetrics: spec.indexedMetrics ?? [],
-        rollups: (spec.rollups ?? []).map((r) => ({
-          as: r.as ?? name,
-          by: r.by,
-          bucket: r.bucket ?? null
-        }))
-      }
-    ])
-  );
-}
 function reportSummary(v) {
+  const report = normalizeQuery(v.query);
   return {
     name: v.name,
     origin: v.origin,
     page: v.page,
     shared: v.shared,
-    display: v.query?.display
+    ...report ? { source: report.source } : {}
   };
 }
-async function runReport(q, scope, view, from, to, redactAll) {
-  const query = view.query ?? {};
-  const filters = query.filters ?? {};
-  const range = from || to ? parseRange(from, to) : rangeFromView(query.range);
-  if (filters.rollup) {
-    return { report: view.name, result: await q.rollups(scope, { as: filters.rollup, range }) };
-  }
-  if (query.display === "series") {
-    return { report: view.name, result: await q.series(scope, range, toFilter(filters)) };
-  }
-  const res = await q.records(scope, range, toFilter(filters), { limit: 200 });
-  return { report: view.name, result: { ...res, items: redactAll(res.items) } };
-}
 function rangeFromView(range) {
   const to = /* @__PURE__ */ new Date();
   const m = /^(\d+)([dh])$/.exec(String(range ?? "7d"));