@jeffjassky/telemetry 0.3.0 → 0.5.0

package/dist/index.js

@@ -59,8 +59,30 @@ var newCounters = () => ({
   capped: 0,
   rollupSkipped: 0,
   deduped: 0,
-  truncated: 0
+  truncated: 0,
+  rollupSkippedBy: {},
+  undeclaredAttrs: {},
+  subjectsLinked: 0,
+  subjectLinkMisses: 0,
+  subjectLinkErrors: 0,
+  subjectLinkTimeouts: 0,
+  subjectLinkUndeclared: 0,
+  subjectLinkCapped: 0
 });
+var COUNTER_MAP_MAX = 1e3;
+var COUNTER_OVERFLOW_KEY = "(other)|(other)";
+var bumpCounterMap = (map, key) => {
+  const seen = map[key];
+  if (seen !== void 0) {
+    map[key] = seen + 1;
+    return;
+  }
+  if (map[COUNTER_OVERFLOW_KEY] !== void 0 || Object.keys(map).length >= COUNTER_MAP_MAX) {
+    map[COUNTER_OVERFLOW_KEY] = (map[COUNTER_OVERFLOW_KEY] ?? 0) + 1;
+    return;
+  }
+  map[key] = 1;
+};
 var traceKeep = (traceId, rate) => {
   if (rate >= 1) return true;
   if (!traceId) return Math.random() < rate;
@@ -388,15 +410,15 @@ function buildBaseSchema(collection, registry, counters, opts) {
     if (this.kind === TelemetryKind.State && !this.state?.to) {
       throw new Error("telemetry: state requires state.to");
     }
-    const check = (label2, m, zschema) => {
+    const check = (label3, m, zschema) => {
       const obj = Object.fromEntries(m ?? []);
       if (!zschema) {
-        if (Object.keys(obj).length) throw new Error(`telemetry: "${this.name}" declares no ${label2}`);
+        if (Object.keys(obj).length) throw new Error(`telemetry: "${this.name}" declares no ${label3}`);
         return;
       }
       const s = zschema.strict?.() ?? zschema;
       const r = s.safeParse(obj);
-      if (!r.success) throw new Error(`telemetry: ${label2} invalid for "${this.name}": ${r.error.message}`);
+      if (!r.success) throw new Error(`telemetry: ${label3} invalid for "${this.name}": ${r.error.message}`);
     };
     check("attrs", this.attrs, spec.attrs);
     check("metrics", this.metrics, spec.metrics);
@@ -545,6 +567,7 @@ async function recordRollup(RollupModel, doc, name, spec, counters) {
     if (v == null || v === "") {
       if (spec.dimDefault === void 0) {
         counters.rollupSkipped++;
+        bumpCounterMap(counters.rollupSkippedBy, `${as}|${label(src)}`);
         return;
       }
       v = spec.dimDefault;
@@ -636,6 +659,120 @@ function createCheckpointFactory(CheckpointModel, logger) {
 }
 
 // src/server/emit.ts
+function noteUndeclaredAttrs(counters, name, spec, attrs) {
+  if (!attrs || typeof attrs !== "object") return;
+  const keys = attrs instanceof Map ? [...attrs.keys()] : Object.keys(attrs);
+  const shape = spec.attrs?.shape;
+  for (const raw of keys) {
+    const key = String(raw).replace(/\./g, "_");
+    if (shape && Object.prototype.hasOwnProperty.call(shape, key)) continue;
+    bumpCounterMap(counters.undeclaredAttrs, `${name}|${key}`);
+  }
+}
+var SUBJECT_MAX = 8;
+var SUBJECT_LINK_TIMEOUT_MS = 50;
+var LINK_TIMEOUT = /* @__PURE__ */ Symbol("telemetry.subjectLink.timeout");
+function createSubjectLinking(opts) {
+  const { linker, counters, logger } = opts;
+  if (!linker) return null;
+  const timeoutMs = opts.timeoutMs ?? SUBJECT_LINK_TIMEOUT_MS;
+  const warned = /* @__PURE__ */ new Set();
+  const warnOnce = (key, msg) => {
+    if (warned.has(key) || warned.size >= COUNTER_MAP_MAX) return;
+    warned.add(key);
+    logger.warn(msg);
+  };
+  return async function linkSubjects(name, spec, tenantId, declared) {
+    const have = Array.isArray(declared) ? declared : [];
+    const seen = /* @__PURE__ */ new Set();
+    const view = [];
+    for (const s of have) {
+      const ref = wellFormed(s);
+      if (!ref) continue;
+      seen.add(`${ref.type}:${ref.id}`);
+      view.push(ref);
+    }
+    let out;
+    let timer;
+    try {
+      out = await Promise.race([
+        // the async wrapper turns a SYNCHRONOUS throw into a rejection, so a
+        // linker that dies on its first line lands in the same catch as one
+        // whose promise rejects
+        (async () => linker.link(view, { name, tenantId }))(),
+        new Promise((_, reject) => {
+          timer = setTimeout(() => reject(LINK_TIMEOUT), timeoutMs);
+        })
+      ]);
+    } catch (e) {
+      if (e === LINK_TIMEOUT) {
+        counters.subjectLinkTimeouts++;
+        warnOnce(
+          "timeout",
+          `[telemetry] subjectLinker.link() exceeded ${timeoutMs}ms \u2014 records are being written UNLINKED rather than waiting. The hook is expected to answer from a cache; a resolver that queries per record cannot keep up with ingest. Warned once \u2014 the count is counters.subjectLinkTimeouts.`
+        );
+      } else {
+        counters.subjectLinkErrors++;
+        warnOnce(
+          "threw",
+          `[telemetry] subjectLinker.link() threw \u2014 records are being written unlinked: ${e}. Warned once \u2014 the count is counters.subjectLinkErrors.`
+        );
+      }
+      return null;
+    } finally {
+      clearTimeout(timer);
+    }
+    if (!Array.isArray(out)) {
+      counters.subjectLinkErrors++;
+      warnOnce(
+        "shape",
+        `[telemetry] subjectLinker.link() resolved to ${typeof out}, not an array \u2014 records are being written unlinked. Return [] when nothing links. Warned once \u2014 the count is counters.subjectLinkErrors.`
+      );
+      return null;
+    }
+    if (!out.length) {
+      counters.subjectLinkMisses++;
+      return null;
+    }
+    let room = Math.max(0, SUBJECT_MAX - have.length);
+    let capped2 = 0;
+    const add = [];
+    for (const s of out) {
+      const ref = wellFormed(s);
+      if (!ref) {
+        counters.subjectLinkErrors++;
+        warnOnce(
+          "entry",
+          "[telemetry] subjectLinker returned an entry that is not { type, id } \u2014 dropped. Warned once \u2014 the count is counters.subjectLinkErrors."
+        );
+        continue;
+      }
+      const key = `${ref.type}:${ref.id}`;
+      if (seen.has(key)) continue;
+      if (!spec.subjects.includes(ref.type)) {
+        counters.subjectLinkUndeclared++;
+      }
+      if (room <= 0) {
+        capped2++;
+        continue;
+      }
+      seen.add(key);
+      room--;
+      add.push(ref);
+    }
+    counters.subjectLinkCapped += capped2;
+    if (!add.length) return null;
+    counters.subjectsLinked += add.length;
+    return [...have, ...add];
+  };
+}
+function wellFormed(s) {
+  if (!s || typeof s !== "object") return null;
+  const { type, id, role } = s;
+  if (typeof type !== "string" || !type) return null;
+  if (typeof id !== "string" || !id) return null;
+  return typeof role === "string" && role ? { type, id, role } : { type, id };
+}
 function createEmitter(ctx) {
   const { registry, byKind, RollupModel, rejects, counters } = ctx;
   const burstBuckets = /* @__PURE__ */ new Map();
@@ -672,16 +809,21 @@ function createEmitter(ctx) {
     const durable = kind === TelemetryKind.Usage || (doc.durable ?? spec.durable ?? false);
     const Model = byKind[kind];
     const { forceKeep: _drop, durable: _durable, ...rest } = doc;
+    const linked = ctx.linkSubjects ? await ctx.linkSubjects(name, spec, doc.tenantId, doc.subjects) : null;
     const safe = (o) => new Map(Object.entries(o ?? {}).map(([k, v]) => [k.replace(/\./g, "_"), v]));
     const payload = {
       ...rest,
       _id: id,
       name,
+      // computed like everything below it, and absent when nothing linked, so a
+      // host with no linker hands the model the exact object 0.4.0 did
+      ...linked ? { subjects: linked } : {},
       sampleRate: forced ? 1 : baseRate,
       forced,
       attrs: safe(doc.attrs),
       metrics: safe(doc.metrics)
     };
+    noteUndeclaredAttrs(counters, name, spec, doc.attrs);
     const onFail = async (e) => {
       counters.rejected++;
       await rejects().insertOne({ at: /* @__PURE__ */ new Date(), name, reason: String(e), raw: plain(doc) }).catch(() => {
@@ -887,10 +1029,10 @@ function parseKeyString(raw) {
   if (!raw) return null;
   const m = KEY_RE.exec(raw.trim());
   if (!m) return null;
-  const [, prefix, label2, id, secret] = m;
+  const [, prefix, label3, id, secret] = m;
   if (prefix === "sk" && !secret) return null;
   if (prefix === "pk" && secret) return null;
-  return { kind: prefix === "pk" ? KeyKind.Publishable : KeyKind.Secret, label: label2, id, secret };
+  return { kind: prefix === "pk" ? KeyKind.Publishable : KeyKind.Secret, label: label3, id, secret };
 }
 var SCRYPT_VERSION = "scrypt1";
 var SCRYPT = { N: 16384, r: 8, p: 1, keylen: 32 };
@@ -948,7 +1090,7 @@ async function createKey(KeyModel, input) {
     tenantId,
     service,
     env,
-    label: label2 = "live",
+    label: label3 = "live",
     origins = [],
     allowedNames,
     maxPerMinute = 600
@@ -981,7 +1123,7 @@ async function createKey(KeyModel, input) {
     createdAt: /* @__PURE__ */ new Date()
   });
   const prefix = kind === KeyKind.Publishable ? "pk" : "sk";
-  return { key: secret ? `${prefix}_${label2}_${id}_${secret}` : `${prefix}_${label2}_${id}`, id };
+  return { key: secret ? `${prefix}_${label3}_${id}_${secret}` : `${prefix}_${label3}_${id}`, id };
 }
 var BATCH_MAX = 100;
 function createIngest(opts) {
@@ -1183,6 +1325,9 @@ function createIngest(opts) {
         const occurredRaw = rec.occurredAt ? Date.parse(rec.occurredAt) : NaN;
         const occurredAt = Number.isFinite(occurredRaw) ? new Date(occurredRaw - clockSkewMs) : receivedAt;
         const safeMap = (o) => o && typeof o === "object" ? new Map(Object.entries(o).map(([k, v]) => [k.replace(/\./g, "_"), v])) : /* @__PURE__ */ new Map();
+        noteUndeclaredAttrs(t.counters, name, spec, rec.attrs);
+        const subjects = mergeSubjects(rec.subjects);
+        const linked = t.linkSubjects ? await t.linkSubjects(name, spec, tenantId, subjects) : null;
         const Model = t.models.byKind[spec.kind];
         const d = new Model({
           // facts the wire may not assert: tenant, service, env, origin, plane
@@ -1193,7 +1338,7 @@ function createIngest(opts) {
           tenantId,
           occurredAt,
           severity: typeof rec.severity === "string" ? rec.severity : void 0,
-          subjects: mergeSubjects(rec.subjects),
+          subjects: linked ?? subjects,
           actor: ctx.actor ?? (typeof rec.actor === "string" ? rec.actor : batchActor),
           onBehalfOf: typeof rec.onBehalfOf === "string" ? rec.onBehalfOf : void 0,
           service: key.service,
@@ -1253,6 +1398,292 @@ function createIngest(opts) {
   return router;
 }
 
+// src/server/catalog.ts
+var label2 = (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(label2),
+          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(label2),
+          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 = label2(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/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/funnel.ts
 var DAY_MS = 864e5;
 function median(values) {
@@ -1460,6 +1891,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
@@ -1473,7 +1908,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;
@@ -1496,6 +1934,68 @@ function buildMatch(scope, range, f) {
   }
   return match;
 }
+var INTERVALS = ["hour", "day", "week", "month"];
+var truncTo = (path3, unit) => ({
+  $dateTrunc: { date: path3, unit, ...unit === "week" ? { startOfWeek: "monday" } : {} }
+});
+function measureAccumulator(measure) {
+  const m = /^(sum|avg):(.+)$/.exec(measure);
+  if (!m) return { $sum: { $divide: [1, { $ifNull: ["$sampleRate", 1] }] } };
+  const path3 = m[2] === "durationMs" ? "$durationMs" : `$metrics.${m[2]}`;
+  return m[1] === "sum" ? { $sum: path3 } : { $avg: path3 };
+}
+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 path3 = dim2.slice(6);
+    if (!BREAKDOWN_FIELDS.includes(path3)) {
+      throw badRequest(
+        `"field:${path3}" 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: [`$${path3}`, 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;
@@ -1569,16 +2069,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 }
           ]);
@@ -1586,6 +2079,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
@@ -1827,6 +2428,820 @@ function requireDistinctFamily(registry, as) {
   }
   return spec;
 }
+
+// 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/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 FILTER_OPS = /* @__PURE__ */ new Set(["eq", "in", "gte", "lte"]);
+var SORTS = /* @__PURE__ */ new Set(["value", "label", "time"]);
+function parseReportQuery(q) {
+  const str = (k) => {
+    const v = Array.isArray(q[k]) ? q[k][0] : q[k];
+    return typeof v === "string" && v ? v : void 0;
+  };
+  const list = (k) => (str(k) ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+  const raw = str("source");
+  if (!raw) {
+    throw badRequest2(
+      "`source` is required \u2014 one of source=event:<name>, namespace:<ns>, kind:<kind>, family:<as>"
+    );
+  }
+  const cut = raw.indexOf(":");
+  const form = cut > 0 ? raw.slice(0, cut) : "";
+  const named = cut > 0 ? raw.slice(cut + 1) : "";
+  if (!named || !["event", "namespace", "kind", "family"].includes(form)) {
+    throw badRequest2(
+      `\`source\` must be "event:<name>", "namespace:<ns>", "kind:<kind>" or "family:<as>" \u2014 got "${raw}"`
+    );
+  }
+  const source = form === "event" ? { event: named } : form === "namespace" ? { namespace: named } : form === "kind" ? { kind: named } : { family: named };
+  const shorthand = str("range");
+  const from = str("from");
+  const to = str("to");
+  if (!shorthand && !(from && to)) {
+    throw badRequest2("a range is required \u2014 either `range=7d` or both `from` and `to` as ISO times");
+  }
+  const range = shorthand ?? { from, to };
+  const interval = str("interval");
+  if (interval && INTERVAL_RANK[interval] == null) {
+    throw badRequest2(`\`interval\` must be one of hour, day, week, month \u2014 got "${interval}"`);
+  }
+  const sort = str("sort");
+  if (sort && !SORTS.has(sort)) {
+    throw badRequest2(`\`sort\` must be one of value, label, time \u2014 got "${sort}"`);
+  }
+  const compare = str("compare");
+  if (compare && compare !== "previous") {
+    throw badRequest2(`\`compare\` takes only "previous" \u2014 got "${compare}"`);
+  }
+  const limitRaw = str("limit");
+  const limit = limitRaw == null ? void 0 : Number(limitRaw);
+  if (limit != null && (!Number.isInteger(limit) || limit < 1)) {
+    throw badRequest2(`\`limit\` must be a positive integer \u2014 got "${limitRaw}"`);
+  }
+  const measure = str("measure");
+  const groupBy = list("groupBy");
+  const excludeActorTypes = list("excludeActors");
+  const stages = list("stages");
+  const exits = list("exits");
+  const anchor = str("anchor");
+  const subjectType = str("subjectType");
+  const filters = (q.filter == null ? [] : Array.isArray(q.filter) ? q.filter.map(String) : [String(q.filter)]).map(parseFilterTerm);
+  return {
+    source,
+    range,
+    ...interval ? { interval } : {},
+    ...measure ? { measure } : {},
+    ...groupBy.length ? { groupBy } : {},
+    ...filters.length ? { filters } : {},
+    ...excludeActorTypes.length ? { excludeActorTypes } : {},
+    ...sort ? { sort } : {},
+    ...limit != null ? { limit } : {},
+    ...compare ? { compare: "previous" } : {},
+    ...stages.length ? { stages } : {},
+    ...anchor ? { anchor } : {},
+    ...exits.length ? { exits } : {},
+    ...subjectType ? { subjectType } : {}
+  };
+}
+function parseFilterTerm(term) {
+  const parts = term.split(":");
+  const i = parts.findIndex((p) => FILTER_OPS.has(p));
+  const rest = i < 0 ? "" : parts.slice(i + 1).join(":");
+  if (i < 1 || !rest) {
+    throw badRequest2(
+      `\`filter\` must be "<dim>:<op>:<value>" with op one of eq, in, gte, lte \u2014 got "${term}"`
+    );
+  }
+  const dim2 = parts.slice(0, i).join(":");
+  const op = parts[i];
+  if (op === "in") {
+    const values = rest.split(",").map((s) => s.trim()).filter(Boolean);
+    if (!values.length) throw badRequest2(`\`filter\` "${term}" has an empty \`in\` list`);
+    return { dim: dim2, op, value: values };
+  }
+  if (op === "gte" || op === "lte") {
+    const n = Number(rest);
+    if (Number.isNaN(n)) throw badRequest2(`\`filter\` bound "${term}" is not a number`);
+    return { dim: dim2, op, value: n };
+  }
+  return { dim: dim2, op, value: rest };
+}
+function reportToQuery(report) {
+  const s = report.source;
+  const q = {
+    source: "event" in s ? `event:${s.event}` : "namespace" in s ? `namespace:${s.namespace}` : "kind" in s ? `kind:${s.kind}` : `family:${s.family}`
+  };
+  if (typeof report.range === "string") q.range = report.range;
+  else {
+    q.from = report.range.from;
+    q.to = report.range.to;
+  }
+  if (report.interval) q.interval = report.interval;
+  if (report.measure) q.measure = report.measure;
+  if (report.groupBy?.length) q.groupBy = report.groupBy.join(",");
+  if (report.filters?.length) {
+    const terms = report.filters.map(
+      (f) => `${f.dim}:${f.op}:${Array.isArray(f.value) ? f.value.join(",") : String(f.value)}`
+    );
+    q.filter = terms.length === 1 ? terms[0] : terms;
+  }
+  if (report.excludeActorTypes?.length) q.excludeActors = report.excludeActorTypes.join(",");
+  if (report.sort) q.sort = report.sort;
+  if (report.limit != null) q.limit = String(report.limit);
+  if (report.compare) q.compare = report.compare;
+  if (report.stages?.length) q.stages = report.stages.join(",");
+  if (report.anchor) q.anchor = report.anchor;
+  if (report.exits?.length) q.exits = report.exits.join(",");
+  if (report.subjectType) q.subjectType = report.subjectType;
+  return q;
+}
+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/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((label3) => dimValue(dims, label3));
+    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, label3) {
+  const prefix = `${label3}=`;
+  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;
+}
 function buildViewModel(connection, modelName, collection) {
   const existing = connection.models?.[modelName];
   if (existing) return existing;
@@ -1853,31 +3268,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,
@@ -1936,6 +3378,10 @@ var parseFilter = (q) => {
   for (const k of ["kind", "name", "severity", "env", "service", "release", "subject", "traceId"]) {
     if (typeof q[k] === "string" && q[k]) f[k] = q[k];
   }
+  if (typeof q.name === "string" && q.name.includes(",")) {
+    const names = q.name.split(",").map((s) => s.trim()).filter(Boolean);
+    if (names.length) f.name = names.length === 1 ? names[0] : names;
+  }
   if (typeof q.attrs === "string" && q.attrs) {
     f.attrs = Object.fromEntries(
       String(q.attrs).split(",").map((p) => p.split(":")).filter((p) => p.length >= 2).map(([k, ...v]) => [k, v.join(":")])
@@ -1967,30 +3413,6 @@ var parseDims = (v) => {
   }
   return v.length ? v : void 0;
 };
-function registryProjection(t) {
-  return Object.fromEntries(
-    Object.entries(t.registry).map(([name, spec]) => [
-      name,
-      {
-        kind: spec.kind,
-        origin: spec.origin,
-        subjects: spec.subjects,
-        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,
-          sum: r.sum ?? [],
-          subjects: r.subjects ?? []
-        }))
-      }
-    ])
-  );
-}
 function createDashboard(opts) {
   const { telemetry: t, viewerAdapter, subjectAdapter, views: configured = [] } = opts;
   if (!viewerAdapter?.resolveViewer) {
@@ -2020,6 +3442,20 @@ function createDashboard(opts) {
     cacheTtlMs: opts.cacheTtlMs,
     cacheSize: opts.cacheSize
   });
+  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.queryLimits,
+    onSlowQuery: opts.onSlowQuery,
+    slowMs: opts.slowMs,
+    cacheTtlMs: opts.cacheTtlMs,
+    cacheSize: opts.cacheSize
+  });
   const api = express2.Router();
   api.use(express2.json({ limit: "64kb" }));
   api.use(async (req, res, next) => {
@@ -2038,7 +3474,8 @@ function createDashboard(opts) {
     }, next);
   };
   api.get("/registry", h(async (req) => ({
-    registry: registryProjection(t),
+    registry,
+    catalog,
     kinds: ["event", "error", "span", "state", "usage"],
     role: req.viewer.role,
     scope: req.viewer.tenantId,
@@ -2061,6 +3498,14 @@ function createDashboard(opts) {
       measure: typeof req.query.measure === "string" ? req.query.measure : void 0
     })
   ));
+  api.get("/breakdown", h(
+    async (req) => q.breakdown(req.viewer.tenantId, parseRange(req.query), parseFilter(req.query), {
+      groupBy: String(req.query.groupBy ?? "").split(",").map((s) => s.trim()).filter(Boolean),
+      measure: typeof req.query.measure === "string" ? req.query.measure : void 0,
+      interval: req.query.interval || void 0,
+      limit: req.query.limit ? Number(req.query.limit) : void 0
+    })
+  ));
   api.get("/rollups", h(async (req) => {
     if (typeof req.query.as !== "string" || !req.query.as) {
       throw Object.assign(new Error("rollup family required"), { status: 400 });
@@ -2091,7 +3536,7 @@ function createDashboard(opts) {
       limit: req.query.limit ? Number(req.query.limit) : void 0
     })
   ));
-  const badRequest = async (run) => {
+  const badRequest3 = async (run) => {
     try {
       return await run();
     } catch (e) {
@@ -2104,7 +3549,7 @@ function createDashboard(opts) {
     if (!stages.length) {
       throw Object.assign(new Error("funnel needs `stages` \u2014 a comma-separated list of rollup families"), { status: 400 });
     }
-    return badRequest(() => q.funnel(req.viewer.tenantId, {
+    return badRequest3(() => q.funnel(req.viewer.tenantId, {
       stages,
       exits: parseStages(req.query.exits),
       anchor: typeof req.query.anchor === "string" ? req.query.anchor : void 0,
@@ -2119,22 +3564,46 @@ function createDashboard(opts) {
     if (typeof req.query.as !== "string" || !req.query.as) {
       throw Object.assign(new Error("rollup family required"), { status: 400 });
     }
-    return badRequest(() => q.distinctCount(req.viewer.tenantId, {
+    return badRequest3(() => q.distinctCount(req.viewer.tenantId, {
       as: req.query.as,
       subjectType: typeof req.query.subjectType === "string" ? req.query.subjectType : void 0,
       range: parseRange(req.query),
       interval: req.query.interval || void 0
     }));
   }));
+  api.get("/values", h(async (req) => {
+    const dim2 = typeof req.query.dim === "string" ? req.query.dim.trim() : "";
+    if (!dim2) {
+      throw Object.assign(new Error("dim required"), { status: 400 });
+    }
+    const names = String(req.query.names ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+    return values(req.viewer.tenantId, {
+      dim: dim2,
+      names: names.length ? names : void 0,
+      range: req.query.from || req.query.to ? parseRange(req.query) : void 0,
+      limit: req.query.limit ? Number(req.query.limit) : void 0
+    });
+  }));
   api.get("/subjects/describe", h(async (req) => {
     const refs = String(req.query.refs ?? "").split(",").filter(Boolean).slice(0, 100);
     if (!subjectAdapter) return { refs: {} };
     return { refs: await subjectAdapter.describe(refs) };
   }));
+  api.get("/report", h(
+    async (req) => badRequest3(
+      () => executeReport(q, req.viewer.tenantId, parseReportQuery(req.query), catalog)
+    )
+  ));
+  api.get("/report/plan", h(
+    async (req) => badRequest3(
+      async () => resolveReport(parseReportQuery(req.query), catalog)
+    )
+  ));
   api.get("/views", h(async (req) => ({
     views: await resolveViews({
       ViewModel,
       registry: t.registry,
+      catalog,
       configured,
       tenantId: req.viewer.tenantId,
       viewerRef: req.viewer.viewerRef
@@ -2177,7 +3646,13 @@ function createDashboard(opts) {
       indexCount: indexes.length,
       indexBudget: INDEX_BUDGET,
       keys,
-      role: req.viewer.role
+      role: req.viewer.role,
+      // The same three sources, read the other way round: what the data says
+      // the registry is missing, each with the line that would fix it. Derived
+      // from the counters and the quarantine ALREADY fetched above, so the
+      // page costs no extra read. Nothing is written — the host still edits
+      // the registry by hand (reports §9).
+      suggestions: deriveSuggestions({ counters: t.counters, catalog, quarantine })
     };
   }));
   api.post("/system/keys/:id/revoke", h(async (req, res) => {
@@ -2266,7 +3741,22 @@ function createTelemetry(config) {
     inFlight.add(p);
     void p.finally(() => inFlight.delete(p));
   };
-  const emit = createEmitter({ registry, byKind, RollupModel, rejects, counters, logger, track });
+  const linkSubjects = createSubjectLinking({
+    linker: config.subjectLinker,
+    timeoutMs: config.subjectLinkTimeoutMs,
+    counters,
+    logger
+  });
+  const emit = createEmitter({
+    registry,
+    byKind,
+    RollupModel,
+    rejects,
+    counters,
+    logger,
+    track,
+    linkSubjects
+  });
   const forget = createForget({
     TelemetryModel,
     RollupModel,
@@ -2329,6 +3819,17 @@ function createTelemetry(config) {
     counters,
     /** the registry, exposed for the router factories — hosts should import their own */
     registry,
+    /**
+     * Write-time subject linking, exposed for the router factories. `null` when
+     * no `subjectLinker` is configured.
+     *
+     * The wire path does not go through emit() — createIngest() builds its
+     * record itself, because at-least-once delivery inverts the plane order
+     * (insert first, THEN aggregate). So it reaches the linker the same way it
+     * reaches the registry and the models: off the instance, running the one
+     * implementation, rather than growing a second copy of the rules.
+     */
+    linkSubjects,
     logger,
     /** mint an ingest key; the full key string is returned once, never again */
     createKey: (input) => createKey(KeyModel, input),
@@ -2345,6 +3846,6 @@ function createTelemetry(config) {
   };
 }
 
-export { BODY_MAX_CHARS, DEFAULT_LIMITS, Env, INDEX_BUDGET, KeyKind, LogLevel, Origin, PLATFORM_SCOPE, RETENTION_DAYS, SAMPLE_RATE, SCHEMA_VERSION, TelemetryKind, TenantMode, boundedMeta, createDashboard, createIngest, createKey, createQueries, createTelemetry, defaultSpaDir, defineRegistry, deriveViews, findFamily, hashSecret, isPlatformScope, median, newId, parseKeyString, plain, requireMilestoneFamily, resolveDim, summarizeStages, traceKeep, truncate, validateRegistry, verifySecret };
+export { BODY_MAX_CHARS, COUNTER_MAP_MAX, COUNTER_OVERFLOW_KEY, DEFAULT_LIMITS, Env, INDEX_BUDGET, KeyKind, LogLevel, MAX_SUGGESTIONS, Origin, PLATFORM_SCOPE, RETENTION_DAYS, SAMPLE_RATE, SCHEMA_VERSION, SUBJECT_LINK_TIMEOUT_MS, SUBJECT_MAX, TelemetryKind, TenantMode, boundedMeta, createDashboard, createIngest, createKey, createQueries, createTelemetry, createValues, defaultSpaDir, defineRegistry, deriveCatalog, deriveSuggestions, deriveViews, executeReport, findFamily, foldRollups, hashSecret, intervalForRange, isPlatformScope, median, newId, normalizeQuery, parseKeyString, parseReportQuery, plain, projectRegistry, rangeOf, reportToQuery, requireMilestoneFamily, resolveDim, resolveReport, summarizeStages, traceKeep, truncate, validateRegistry, verifySecret };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map