@jeffjassky/telemetry 0.1.0 → 0.2.0

package/dist/mcp.cjs

@@ -0,0 +1,1114 @@
+'use strict';
+
+var zod = require('zod');
+require('uuidv7');
+var mongoose = require('mongoose');
+
+// src/server/mcp.ts
+var PLATFORM_SCOPE = "*";
+var isPlatformScope = (tenantId) => tenantId === PLATFORM_SCOPE;
+var truncate = (d, b) => {
+  if (!b) return void 0;
+  if (b === "hour") return new Date(Math.floor(d.getTime() / 36e5) * 36e5);
+  const y = d.getUTCFullYear();
+  const m = d.getUTCMonth();
+  if (b === "month") return new Date(Date.UTC(y, m, 1));
+  const day = new Date(Date.UTC(y, m, d.getUTCDate()));
+  if (b === "day") return day;
+  return new Date(day.getTime() - (day.getUTCDay() + 6) % 7 * 864e5);
+};
+
+// src/server/funnel.ts
+var DAY_MS = 864e5;
+function median(values) {
+  if (values.length === 0) return null;
+  const s = [...values].sort((a, b) => a - b);
+  const mid = s.length >> 1;
+  return s.length % 2 === 1 ? s[mid] : (s[mid - 1] + s[mid]) / 2;
+}
+function summarizeStages(subjects, stages) {
+  const firstKey = stages[0]?.key;
+  const first = firstKey ? subjects.filter((s) => s.stages[firstKey]).length : 0;
+  return stages.map((st, i) => {
+    const prev = i > 0 ? stages[i - 1] : null;
+    const next = i < stages.length - 1 ? stages[i + 1] : null;
+    const reached = [];
+    const fromAnchor = [];
+    for (const s of subjects) {
+      const at = s.stages[st.key];
+      if (!at) continue;
+      reached.push(s);
+      if (s.anchorAt) fromAnchor.push((at.getTime() - s.anchorAt.getTime()) / DAY_MS);
+    }
+    let prevReached = 0;
+    let notReached = 0;
+    const fromPrevious = [];
+    if (prev) {
+      for (const s of subjects) {
+        const p = s.stages[prev.key];
+        if (!p) continue;
+        prevReached += 1;
+        const cur = s.stages[st.key];
+        if (cur) fromPrevious.push((cur.getTime() - p.getTime()) / DAY_MS);
+        else notReached += 1;
+      }
+    }
+    return {
+      order: st.order,
+      key: st.key,
+      as: st.as,
+      label: st.label,
+      ...st.description ? { description: st.description } : {},
+      subjects: reached.length,
+      pctOfFirst: first > 0 ? reached.length / first * 100 : null,
+      pctOfPrevious: prev ? prevReached > 0 ? reached.length / prevReached * 100 : null : null,
+      medianDaysFromAnchor: median(fromAnchor),
+      medianDaysFromPrevious: prev ? median(fromPrevious) : null,
+      notReached,
+      // the divergence: maxed's `!next` clause makes every subject that reached
+      // the terminal stage "stuck" there. null says "undefined", which is true.
+      stalledAt: next ? subjects.filter((s) => s.stages[st.key] && !s.stages[next.key]).length : null
+    };
+  });
+}
+function findFamily(registry, as) {
+  for (const [name, s] of Object.entries(registry)) {
+    for (const r of s.rollups ?? []) {
+      if ((r.as ?? name) === as) return { name, spec: r };
+    }
+  }
+  return null;
+}
+function requireMilestoneFamily(registry, as, primitive) {
+  const found = findFamily(registry, as);
+  if (!found) {
+    throw new Error(
+      `telemetry: ${primitive} \u2014 no rollup family "${as}" is declared. Add a \`rollups: [{ as: '${as}', by: ['subject'], subjects: [...] }]\` block to the event that marks it.`
+    );
+  }
+  const { name, spec } = found;
+  const shape = `by: [${spec.by.map((d) => `'${d}'`).join(", ")}]${spec.bucket ? `, bucket: '${spec.bucket}'` : ""}`;
+  if (spec.bucket) {
+    throw new Error(
+      `telemetry: ${primitive} \u2014 rollup family "${as}" (declared on "${name}") 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 (spec.by.length !== 1 || spec.by[0] !== "subject") {
+    throw new Error(
+      `telemetry: ${primitive} \u2014 rollup family "${as}" (declared on "${name}") 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 spec;
+}
+function cohortWindow(c) {
+  const endInclusive = c.endInclusive === true;
+  return { from: c.from, to: endInclusive ? new Date(c.to.getTime() + 1) : c.to, endInclusive };
+}
+async function runFunnel(ctx, scope, params) {
+  if (!params.stages?.length) throw new Error("telemetry: funnel() needs at least one stage");
+  const stages = params.stages.map((s, i) => ({
+    order: i + 1,
+    key: s.key ?? s.as,
+    as: s.as,
+    label: s.label ?? s.key ?? s.as,
+    ...s.description ? { description: s.description } : {}
+  }));
+  const exits = (params.exits ?? []).map((s, i) => ({
+    order: i + 1,
+    key: s.key ?? s.as,
+    as: s.as,
+    label: s.label ?? s.key ?? s.as
+  }));
+  const anchor = params.anchor ?? stages[0].as;
+  requireMilestoneFamily(ctx.registry, anchor, "funnel()");
+  for (const s of [...stages, ...exits]) requireMilestoneFamily(ctx.registry, s.as, "funnel()");
+  const { from, to, endInclusive } = cohortWindow(params.cohort);
+  const cap = Math.min(Math.max(1, params.limit ?? ctx.cohortCap), ctx.cohortCap);
+  const cohortMatch = {
+    ...ctx.scopeMatch(scope),
+    as: anchor,
+    // AMBIGUOUS-2 (cohort-math): maxed's cohort read overwrites per row with no
+    // ordering, so its `signupAt` is whichever row Mongo returned last —
+    // nondeterministic. Unreachable here by construction: the rollup's `firstAt`
+    // is a `$min` maintained on write, so the anchor timestamp is the EARLIEST
+    // occurrence, always, matching the tie-break rule maxed uses everywhere else
+    // (R12). We take min(at) and the storage enforces it.
+    firstAt: { $gte: from, $lt: to }
+  };
+  if (params.subjectType) cohortMatch.subjectType = params.subjectType;
+  const cohortRows = await ctx.RollupModel.find(cohortMatch).sort({ firstAt: 1 }).limit(cap + 1).lean();
+  const truncated = cohortRows.length > cap;
+  if (truncated) cohortRows.pop();
+  const keyOf = (r) => `${r.tenantId ?? ""}|${r.dims?.[0]}`;
+  const index = /* @__PURE__ */ new Map();
+  const refs = /* @__PURE__ */ new Set();
+  const tenants = /* @__PURE__ */ new Set();
+  for (const r of cohortRows) {
+    const ref = r.dims?.[0];
+    if (!ref) continue;
+    refs.add(ref);
+    tenants.add(String(r.tenantId ?? ""));
+    index.set(keyOf(r), { ref, anchorAt: r.firstAt, stages: {}, exits: {} });
+  }
+  if (refs.size) {
+    const byAs = /* @__PURE__ */ new Map();
+    for (const s of [...stages, ...exits]) {
+      const list = byAs.get(s.as) ?? [];
+      list.push(s);
+      byAs.set(s.as, list);
+    }
+    const stageRows = await ctx.RollupModel.find({
+      ...ctx.scopeMatch(scope),
+      as: { $in: [...byAs.keys()] },
+      dims: { $in: [...refs] },
+      // AMBIGUOUS-1 (cohort-math): maxed collects stages with `at >= cohortStart`
+      // and no upper bound. We keep the lower bound — reading (a), as-written.
+      // Reasons: (1) it is what maxed does, and an equivalence test against a
+      // table computed under the other reading would prove nothing; (2) over
+      // rollup storage the predicate reads "first reached no earlier than the
+      // cohort opened", which is the only reading under which a cohort's funnel
+      // is a function of its own window — drop the bound and a backfill dated
+      // before the window silently adds stages to a report already published.
+      // No UPPER bound, deliberately: a conversion landing months after the
+      // window still belongs to its cohort (R7).
+      firstAt: { $gte: from }
+    }).limit(refs.size * tenants.size * byAs.size + 1).lean();
+    for (const r of stageRows) {
+      const subject = index.get(keyOf(r));
+      if (!subject) continue;
+      for (const s of byAs.get(r.as) ?? []) {
+        const bag = exits.includes(s) ? subject.exits : subject.stages;
+        const prevAt = bag[s.key];
+        if (!prevAt || r.firstAt < prevAt) bag[s.key] = r.firstAt;
+      }
+    }
+  }
+  const subjects = [...index.values()];
+  const summary = summarizeStages(subjects, stages);
+  let slices = null;
+  if (params.interval) {
+    const groups = /* @__PURE__ */ new Map();
+    for (const s of subjects) {
+      if (!s.anchorAt) continue;
+      const at = truncate(s.anchorAt, params.interval);
+      const k = at.getTime();
+      groups.set(k, [...groups.get(k) ?? [], s]);
+    }
+    slices = [...groups.entries()].sort((a, b) => a[0] - b[0]).map(([k, members]) => ({
+      at: new Date(k),
+      subjects: members.length,
+      stages: summarizeStages(members, stages)
+    }));
+  }
+  return {
+    cohortSubjects: subjects.length,
+    first: stages[0] ? subjects.filter((s) => s.stages[stages[0].key]).length : 0,
+    stages: summary,
+    exits: exits.map((e) => ({
+      key: e.key,
+      as: e.as,
+      label: e.label,
+      subjects: subjects.filter((s) => s.exits[e.key]).length
+    })),
+    slices,
+    truncated,
+    cohort: { from: params.cohort.from, to: params.cohort.to, endInclusive, anchor },
+    dataSource: "rollups"
+  };
+}
+
+// src/server/query.ts
+var DEFAULT_LIMITS = {
+  records: 200,
+  series: 744,
+  // a month of hourly buckets
+  rollups: 500,
+  trace: 500,
+  journey: 500,
+  distribution: 1e5,
+  distinct: 1e5,
+  funnel: 5e3
+};
+var esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+function buildMatch(scope, range, f) {
+  const match = {
+    // the ONLY place the tenant term is optional. Omitted under '*' — every
+    // other term still applies, and the time range is still mandatory (§18).
+    ...isPlatformScope(scope) ? {} : { tenantId: scope },
+    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];
+  }
+  if (f.subject) match.subjectKeys = f.subject;
+  for (const [k, v] of Object.entries(f.attrs ?? {})) match[`attrs.${k}`] = v;
+  for (const [k, r] of Object.entries(f.metrics ?? {})) {
+    const term = {};
+    if (r.gte != null) term.$gte = r.gte;
+    if (r.lte != null) term.$lte = r.lte;
+    if (Object.keys(term).length) match[`metrics.${k}`] = term;
+  }
+  if (f.excludeActorTypes?.length) {
+    match.$and = [
+      ...match.$and ?? [],
+      {
+        $or: [
+          { actor: { $exists: false } },
+          { actor: { $not: new RegExp(`^(${f.excludeActorTypes.map(esc).join("|")}):`) } }
+        ]
+      }
+    ];
+  }
+  return match;
+}
+var QueryCache = class {
+  constructor(ttlMs, cap) {
+    this.ttlMs = ttlMs;
+    this.cap = cap;
+  }
+  ttlMs;
+  cap;
+  store = /* @__PURE__ */ new Map();
+  get(key, produce) {
+    const hit = this.store.get(key);
+    if (hit && Date.now() - hit.at < this.ttlMs) return hit.value;
+    const value = produce();
+    value.catch(() => this.store.delete(key));
+    if (this.store.size >= this.cap) {
+      const oldest = [...this.store.entries()].sort((a, b) => a[1].at - b[1].at)[0];
+      if (oldest) this.store.delete(oldest[0]);
+    }
+    this.store.set(key, { at: Date.now(), value });
+    return value;
+  }
+};
+function createQueries(ctx) {
+  const limits = { ...DEFAULT_LIMITS, ...ctx.limits };
+  const slowMs = ctx.slowMs ?? 500;
+  const cache = new QueryCache(ctx.cacheTtlMs ?? 10 * 6e4, ctx.cacheSize ?? 60);
+  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 });
+    }
+  };
+  return {
+    /** cursor-paged raw envelope reads — tables, lists, detail drawers */
+    async records(scope, range, filter = {}, opts = {}) {
+      const limit = Math.min(Math.max(1, opts.limit ?? limits.records), limits.records);
+      const match = buildMatch(scope, range, filter);
+      if (opts.cursor) {
+        const [atIso, id] = JSON.parse(Buffer.from(opts.cursor, "base64url").toString());
+        const at = new Date(atIso);
+        match.$and = [
+          ...match.$and ?? [],
+          { $or: [{ occurredAt: { $lt: at } }, { occurredAt: at, _id: { $lt: id } }] }
+        ];
+      }
+      return timed("records", { scope, filter }, async () => {
+        const items = await ctx.TelemetryModel.find(match).sort({ occurredAt: -1, _id: -1 }).limit(limit + 1).lean();
+        const more = items.length > limit;
+        if (more) items.pop();
+        const last = items[items.length - 1];
+        return {
+          items,
+          nextCursor: more ? Buffer.from(JSON.stringify([new Date(last.occurredAt).toISOString(), last._id])).toString("base64url") : null,
+          dataSource: "raw"
+        };
+      });
+    },
+    /** time-series at query time. count extrapolates by 1/sampleRate (§5.3) —
+     *  exact while rates sit at 1, still honest the day one drops.
+     *
+     *  Under PLATFORM_SCOPE this aggregates ACROSS tenants into one bucket per
+     *  interval. That is the platform-wide chart, not a bug — the sum of every
+     *  tenant is the number a platform operator came for. A per-tenant
+     *  breakdown is a different question; ask it with rollups() or by scoping
+     *  to a tenant. Same for distribution() below. */
+    series(scope, range, filter, opts = {}) {
+      const { measure = "count", interval = "day" } = opts;
+      const key = JSON.stringify(["series", scope, range.from, range.to, filter, measure, interval]);
+      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
+              }
+            },
+            { $sort: { _id: 1 } },
+            { $limit: limits.series }
+          ]);
+          return { buckets: buckets.map((b) => ({ at: b._id, value: b.value })), 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
+     * computation is not exact and this comment used to claim it was:
+     * `$percentile` runs `method: 'approximate'` (t-digest), and the scan stops
+     * at `limits.distribution`.
+     *
+     * So the ceiling is read as cap+1 and `truncated` reports whether it was
+     * actually reached, the same way rollups/distinctCount/funnel do. A match
+     * wider than the ceiling is an undercount, and an undercount the response
+     * does not mention is the silent cap this package refuses everywhere else.
+     * Mongo 7+.
+     */
+    distribution(scope, range, filter, opts = {}) {
+      const measure = opts.measure ?? "durationMs";
+      const path = measure === "durationMs" ? "$durationMs" : `$metrics.${measure.replace(/^metric:/, "")}`;
+      const key = JSON.stringify(["distribution", scope, range.from, range.to, filter, measure]);
+      return cache.get(
+        key,
+        () => timed("distribution", { scope, filter, measure }, async () => {
+          const match = {
+            ...buildMatch(scope, range, filter),
+            [path.slice(1)]: { $exists: true }
+          };
+          const cap = limits.distribution;
+          const [summary] = await ctx.TelemetryModel.aggregate([
+            { $match: match },
+            { $limit: cap + 1 },
+            {
+              $group: {
+                _id: null,
+                p: { $percentile: { input: path, p: [0.5, 0.9, 0.95, 0.99], method: "approximate" } },
+                min: { $min: path },
+                max: { $max: path },
+                avg: { $avg: path },
+                n: { $sum: 1 }
+              }
+            }
+          ]);
+          if (!summary) return { n: 0, truncated: false, dataSource: "raw" };
+          const [p50, p90, p95, p99] = summary.p;
+          const histogram = await ctx.TelemetryModel.aggregate([
+            { $match: match },
+            { $limit: cap + 1 },
+            { $bucketAuto: { groupBy: path, buckets: 20 } }
+          ]);
+          return {
+            p50,
+            p90,
+            p95,
+            p99,
+            min: summary.min,
+            max: summary.max,
+            avg: summary.avg,
+            n: summary.n,
+            histogram: histogram.map((h) => ({ min: h._id.min, max: h._id.max, n: h.count })),
+            truncated: summary.n > cap,
+            dataSource: "raw"
+          };
+        })
+      );
+    },
+    /** rollup family reads — issues, spend, activity, milestones, funnels */
+    rollups(scope, params) {
+      const key = JSON.stringify(["rollups", scope, params]);
+      return cache.get(
+        key,
+        () => timed("rollups", { scope, params }, async () => {
+          let bucketed = false;
+          outer: for (const [name, s] of Object.entries(ctx.registry)) {
+            for (const r of s.rollups ?? []) {
+              if ((r.as ?? name) === params.as) {
+                bucketed = !!r.bucket;
+                break outer;
+              }
+            }
+          }
+          const match = {
+            ...isPlatformScope(scope) ? {} : { tenantId: scope },
+            as: params.as
+          };
+          if (params.dims) {
+            match.dims = Array.isArray(params.dims) ? { $in: params.dims } : params.dims;
+          }
+          if (params.subjectType) match.subjectType = params.subjectType;
+          if (params.range) {
+            const on = params.on ?? (bucketed ? "bucketAt" : "lastAt");
+            match[on] = { $gte: params.range.from, $lt: params.range.to };
+          }
+          const sortKey = params.sort ?? (bucketed ? "bucketAt" : "count");
+          const limit = Math.min(Math.max(1, params.limit ?? limits.rollups), limits.rollups);
+          const rows = await ctx.RollupModel.find(match).sort({ [sortKey]: sortKey === "firstAt" || sortKey === "bucketAt" ? 1 : -1 }).limit(limit + 1).lean();
+          const truncated = rows.length > limit;
+          if (truncated) rows.pop();
+          return { rows, bucketed, truncated, dataSource: "rollups" };
+        })
+      );
+    },
+    /** one trace, every kind, one time axis — the first join view */
+    trace(scope, traceId) {
+      return timed("trace", { scope, traceId }, async () => {
+        const items = await ctx.TelemetryModel.find({
+          ...isPlatformScope(scope) ? {} : { tenantId: scope },
+          traceId
+        }).sort({ occurredAt: 1 }).limit(limits.trace).lean();
+        return { items, dataSource: "raw" };
+      });
+    },
+    /** one subject's whole story — records interleaved, milestones as markers */
+    journey(scope, subjectRef, range, opts = {}) {
+      return timed("journey", { scope, subjectRef }, async () => {
+        const limit = Math.min(Math.max(1, opts.limit ?? limits.journey), limits.journey);
+        const pin = isPlatformScope(scope) ? {} : { tenantId: scope };
+        const [records, milestones] = await Promise.all([
+          ctx.TelemetryModel.find({
+            ...pin,
+            subjectKeys: subjectRef,
+            occurredAt: { $gte: range.from, $lt: range.to }
+          }).sort({ occurredAt: -1 }).limit(limit).lean(),
+          // lifetime families only — bucketed activity rows would drown the markers
+          ctx.RollupModel.find({ ...pin, dims: subjectRef, bucketAt: { $exists: false } }).sort({ firstAt: 1 }).limit(100).lean()
+        ]);
+        return { records, milestones, dataSource: "raw+rollups" };
+      });
+    },
+    /**
+     * Distinct subjects per bucket, and over the whole range — DAU/MAU/WAU,
+     * EXACTLY, with no sketch and no write-path change.
+     *
+     * The trick is that there is no trick. A family declared `by: ['subject']`
+     * with a bucket already writes exactly ONE doc per (subject, bucket), which
+     * is what the deterministic `_id` guarantees. So distinct-subjects-in-bucket
+     * IS the doc count, and distinct-over-a-range is one `$group` on `dims`. An
+     * HLL sketch would buy approximation we do not need and storage we would
+     * have to maintain.
+     *
+     * `interval` may be COARSER than the family's own bucket (daily rows →
+     * monthly MAU) — re-truncating bucket starts cannot split a bucket across
+     * two periods, so the roll-up stays exact. Asking for finer than the family
+     * writes cannot invent detail: it returns the family's own grain.
+     */
+    distinctCount(scope, params) {
+      const spec = requireDistinctFamily(ctx.registry, params.as);
+      const interval = params.interval ?? spec.bucket;
+      const key = JSON.stringify(["distinctCount", scope, params]);
+      return cache.get(
+        key,
+        () => timed("distinctCount", { scope, params }, async () => {
+          const match = {
+            ...isPlatformScope(scope) ? {} : { tenantId: scope },
+            as: params.as,
+            bucketAt: { $gte: params.range.from, $lt: params.range.to }
+          };
+          if (params.subjectType) match.subjectType = params.subjectType;
+          const cap = limits.distinct;
+          const [out] = await ctx.RollupModel.aggregate([
+            { $match: match },
+            // one scan ceiling, shared by both branches — and cap+1 so the
+            // response can SAY it was truncated instead of quietly undercounting
+            { $limit: cap + 1 },
+            {
+              $facet: {
+                buckets: [
+                  {
+                    $group: {
+                      _id: {
+                        at: { $dateTrunc: { date: "$bucketAt", unit: interval, ...interval === "week" ? { startOfWeek: "monday" } : {} } },
+                        dims: "$dims"
+                      }
+                    }
+                  },
+                  { $group: { _id: "$_id.at", value: { $sum: 1 } } },
+                  { $sort: { _id: 1 } },
+                  { $limit: limits.series }
+                ],
+                distinct: [{ $group: { _id: "$dims" } }, { $count: "n" }],
+                scanned: [{ $count: "n" }]
+              }
+            }
+          ]);
+          const scanned = out?.scanned?.[0]?.n ?? 0;
+          return {
+            buckets: (out?.buckets ?? []).map((b) => ({ at: b._id, value: b.value })),
+            /** distinct subjects across the WHOLE range — never the sum of the buckets */
+            distinct: out?.distinct?.[0]?.n ?? 0,
+            interval,
+            truncated: scanned > cap,
+            dataSource: "rollups"
+          };
+        })
+      );
+    },
+    /**
+     * Cohort funnel over lifetime milestone families — stage counts, conversion,
+     * and median time-to-step. See funnel.ts; the math lives there so it can be
+     * unit-pinned without a database.
+     */
+    funnel(scope, params) {
+      return timed(
+        "funnel",
+        { scope, params },
+        () => runFunnel(
+          {
+            RollupModel: ctx.RollupModel,
+            registry: ctx.registry,
+            cohortCap: limits.funnel,
+            scopeMatch: (s) => isPlatformScope(s) ? {} : { tenantId: s }
+          },
+          scope,
+          params
+        )
+      );
+    }
+  };
+}
+function requireDistinctFamily(registry, as) {
+  const found = findFamily(registry, as);
+  if (!found) {
+    throw new Error(
+      `telemetry: distinctCount() \u2014 no rollup family "${as}" is declared. Add \`rollups: [{ as: '${as}', by: ['subject'], subjects: [...], bucket: 'day' }]\` to the events that count as activity.`
+    );
+  }
+  const { name, spec } = found;
+  const by = `by: [${spec.by.map((d) => `'${d}'`).join(", ")}]`;
+  if (!spec.bucket) {
+    throw new Error(
+      `telemetry: distinctCount() \u2014 rollup family "${as}" (declared on "${name}") has no \`bucket\`. Distinct-per-period needs one doc per (subject, period); a lifetime family has one doc per subject forever, so every period would report the same number. Add \`bucket: 'day'\`, or ask this with rollups().`
+    );
+  }
+  if (!spec.by.includes("subject")) {
+    throw new Error(
+      `telemetry: distinctCount() \u2014 rollup family "${as}" (declared on "${name}") is keyed ${by} with no \`subject\` dim, so its docs count OCCURRENCES, not subjects. Add 'subject' to \`by\` (with \`subjects: [...]\`).`
+    );
+  }
+  if (spec.by.length !== 1) {
+    throw new Error(
+      `telemetry: distinctCount() \u2014 rollup family "${as}" (declared on "${name}") is keyed ${by}. Extra dims split one subject across several docs per period, so the count would exceed the true distinct total. Declare a second family with \`by: ['subject']\` for the distinct question.`
+    );
+  }
+  return spec;
+}
+function buildViewModel(connection, modelName, collection) {
+  const existing = connection.models?.[modelName];
+  if (existing) return existing;
+  const schema = new mongoose.Schema(
+    {
+      _id: { type: String, required: true },
+      tenantId: { type: String, required: true },
+      /** a person — forget() deletes private views, redacts this on shared ones */
+      ownerRef: String,
+      shared: { type: Boolean, default: false },
+      spec: { type: mongoose.Schema.Types.Mixed, required: true },
+      createdAt: { type: Date, required: true }
+    },
+    { collection, versionKey: false }
+  );
+  schema.index({ tenantId: 1, shared: 1 });
+  schema.index({ tenantId: 1, ownerRef: 1 });
+  return connection.model(modelName, schema);
+}
+var KIND_PAGE = {
+  error: "errors",
+  span: "traces",
+  event: "events",
+  state: "journeys",
+  usage: "usage"
+};
+function deriveViews(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" }
+    });
+    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" }
+    });
+  }
+  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 opts.configured) byName.set(v.name, { ...v, origin: "configured" });
+  const saved = await opts.ViewModel.find({
+    tenantId: opts.tenantId,
+    $or: [{ shared: true }, ...opts.viewerRef ? [{ ownerRef: opts.viewerRef }] : []]
+  }).sort({ createdAt: 1 }).limit(200).lean();
+  for (const doc of saved) {
+    byName.set(doc.spec.name, {
+      ...doc.spec,
+      origin: "saved",
+      id: doc._id,
+      ownerRef: doc.ownerRef,
+      shared: doc.shared
+    });
+  }
+  return [...byName.values()];
+}
+
+// src/server/mcp.ts
+var tenantArg = {
+  tenant: zod.z.string().optional().describe(
+    "platform operators only: restrict the read to one tenant id. Permitted ONLY when your viewer is scoped to '*'; a hard error otherwise."
+  )
+};
+var rangeArg = {
+  from: zod.z.string().optional().describe("ISO 8601 start, inclusive. Default: 7 days before `to`."),
+  to: zod.z.string().optional().describe("ISO 8601 end, exclusive. Default: now.")
+};
+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'),
+  severity: zod.z.string().optional(),
+  env: zod.z.string().optional().describe("prod | staging | dev"),
+  service: zod.z.string().optional(),
+  release: zod.z.string().optional(),
+  subject: zod.z.string().optional().describe('pin to one subject, e.g. "user:u_1"'),
+  traceId: zod.z.string().optional(),
+  attrs: zod.z.record(zod.z.string(), zod.z.string()).optional().describe("equality on declared indexed attrs"),
+  excludeActorTypes: zod.z.array(zod.z.string()).optional().describe('drop typed actors, e.g. ["admin","system"] for a customer-only view')
+};
+function toFilter(a) {
+  const f = {};
+  for (const k of ["kind", "name", "severity", "env", "service", "release", "subject", "traceId"]) {
+    if (a[k] != null) f[k] = a[k];
+  }
+  if (a.attrs) f.attrs = a.attrs;
+  if (a.excludeActorTypes?.length) f.excludeActorTypes = a.excludeActorTypes;
+  return f;
+}
+function parseRange(from, to) {
+  const toD = to ? new Date(to) : /* @__PURE__ */ new Date();
+  const fromD = from ? new Date(from) : new Date(toD.getTime() - 7 * 864e5);
+  if (Number.isNaN(fromD.getTime()) || Number.isNaN(toD.getTime()) || fromD >= toD) {
+    throw new Error("invalid time range: `from` must be a valid ISO time strictly before `to`");
+  }
+  return { from: fromD, to: toD };
+}
+var INTERVAL = zod.z.enum(["hour", "day", "week", "month"]);
+function createTelemetryMcp(opts) {
+  const { telemetry: t, viewerAdapter, subjectAdapter, configured = [] } = opts;
+  if (!viewerAdapter?.resolveViewer) {
+    throw new Error(
+      "telemetry: createTelemetryMcp requires a viewerAdapter \u2014 an unauthenticated telemetry tool is a data leak an agent will find"
+    );
+  }
+  const redact = opts.redact === false ? (r) => r : opts.redact ?? ((r) => {
+    if (!r || typeof r !== "object" || r.data === void 0) return r;
+    const { data, ...rest } = r;
+    return { ...rest, data: "[redacted]" };
+  });
+  const redactAll = (items) => items.map(redact);
+  const q = createQueries({
+    TelemetryModel: t.models.telemetry,
+    RollupModel: t.models.rollups,
+    registry: t.registry,
+    limits: opts.limits
+  });
+  const ViewModel = buildViewModel(
+    t.models.telemetry.db,
+    `${t.models.telemetry.modelName}View`,
+    `${t.models.telemetry.collection.collectionName}_views`
+  );
+  async function resolve(ctx) {
+    const viewer = await viewerAdapter.resolveViewer(ctx);
+    if (!viewer?.tenantId) throw new Error("unauthorized: viewerAdapter returned no viewer");
+    return viewer;
+  }
+  function pickScope(viewer, tenant) {
+    if (tenant == null || tenant === "") return viewer.tenantId;
+    if (!isPlatformScope(viewer.tenantId)) {
+      throw new Error("the `tenant` argument is permitted only for platform-scope ('*') viewers");
+    }
+    return tenant;
+  }
+  async function labelSubjects(items) {
+    if (!subjectAdapter) return void 0;
+    const refs = /* @__PURE__ */ new Set();
+    for (const it of items) for (const r of it?.subjectKeys ?? []) refs.add(r);
+    if (!refs.size) return {};
+    return subjectAdapter.describe([...refs].slice(0, 100));
+  }
+  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.",
+      inputSchema: zod.z.object({}),
+      async handler(_args, ctx) {
+        await resolve(ctx);
+        return { registry: registryProjection(t), kinds: ["event", "error", "span", "state", "usage"] };
+      }
+    }),
+    // ── events ──────────────────────────────────────────────────────────────
+    tool({
+      name: "search_events",
+      title: "Search events",
+      description: "Raw telemetry records matching a filter, newest first, cursor-paged. The general list/table/tail tool across every kind. `data` payloads are redacted by default.",
+      inputSchema: zod.z.object({
+        ...filterArg,
+        ...rangeArg,
+        ...tenantArg,
+        limit: zod.z.number().int().positive().optional(),
+        cursor: zod.z.string().optional().describe("opaque nextCursor from a previous call")
+      }),
+      async handler(a, ctx) {
+        const viewer = await resolve(ctx);
+        const scope = pickScope(viewer, a.tenant);
+        const res = await q.records(scope, parseRange(a.from, a.to), toFilter(a), {
+          limit: a.limit,
+          cursor: a.cursor
+        });
+        return { ...res, items: redactAll(res.items), subjects: await labelSubjects(res.items) };
+      }
+    }),
+    tool({
+      name: "list_errors",
+      title: "List errors",
+      description: 'Recent error records, newest first \u2014 the focused feed for "what is breaking?". A convenience over search_events with kind pinned to "error"; still accepts name/service/env/severity filters.',
+      inputSchema: zod.z.object({
+        name: zod.z.string().optional(),
+        severity: zod.z.string().optional(),
+        service: zod.z.string().optional(),
+        env: zod.z.string().optional(),
+        release: zod.z.string().optional(),
+        subject: zod.z.string().optional(),
+        excludeActorTypes: filterArg.excludeActorTypes,
+        ...rangeArg,
+        ...tenantArg,
+        limit: zod.z.number().int().positive().optional(),
+        cursor: zod.z.string().optional()
+      }),
+      async handler(a, ctx) {
+        const viewer = await resolve(ctx);
+        const scope = pickScope(viewer, a.tenant);
+        const res = await q.records(scope, parseRange(a.from, a.to), { ...toFilter(a), kind: "error" }, {
+          limit: a.limit,
+          cursor: a.cursor
+        });
+        return { ...res, items: redactAll(res.items), subjects: await labelSubjects(res.items) };
+      }
+    }),
+    tool({
+      name: "event_trends",
+      title: "Event trends over time",
+      description: 'A time series of a measure, bucketed by interval \u2014 counts by default, or sum:/avg: of a declared metric (e.g. "avg:durationMs"). Use for "is this rising?" questions.',
+      inputSchema: zod.z.object({
+        ...filterArg,
+        ...rangeArg,
+        ...tenantArg,
+        measure: zod.z.string().optional().describe('"count" (default), or "sum:<metric>" / "avg:<metric>", e.g. "sum:tokens"'),
+        interval: INTERVAL.optional()
+      }),
+      async handler(a, ctx) {
+        const viewer = await resolve(ctx);
+        const scope = pickScope(viewer, a.tenant);
+        return q.series(scope, parseRange(a.from, a.to), toFilter(a), {
+          measure: a.measure,
+          interval: a.interval
+        });
+      }
+    }),
+    tool({
+      name: "metric_distribution",
+      title: "Metric distribution (percentiles)",
+      description: 'Percentiles (p50/p90/p95/p99), min/max/avg, and a 20-bucket histogram of a numeric metric over the matched records \u2014 e.g. "what is p95 latency for the checkout span?". Defaults to durationMs.',
+      inputSchema: zod.z.object({
+        ...filterArg,
+        ...rangeArg,
+        ...tenantArg,
+        measure: zod.z.string().optional().describe('"durationMs" (default) or a declared metric key, e.g. "metric:tokens"')
+      }),
+      async handler(a, ctx) {
+        const viewer = await resolve(ctx);
+        const scope = pickScope(viewer, a.tenant);
+        return q.distribution(scope, parseRange(a.from, a.to), toFilter(a), { measure: a.measure });
+      }
+    }),
+    // ── aggregates ────────────────────────────────────────────────────────────
+    tool({
+      name: "rollup_breakdown",
+      title: "Rollup breakdown",
+      description: "Top rows of a pre-aggregated rollup family \u2014 top issues, top spenders, most-active accounts, whatever the registry declares. Name the family (`as`) from describe_telemetry; optionally slice by dimension values.",
+      inputSchema: zod.z.object({
+        as: zod.z.string().describe('the rollup family, e.g. "spend_by_account" \u2014 see describe_telemetry'),
+        dims: zod.z.array(zod.z.string()).optional().describe("restrict to these dimension values"),
+        subjectType: zod.z.string().optional(),
+        on: zod.z.enum(["firstAt", "lastAt", "bucketAt"]).optional(),
+        sort: zod.z.enum(["count", "lastAt", "firstAt", "bucketAt"]).optional(),
+        ...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 q.rollups(scope, {
+          as: a.as,
+          dims: a.dims,
+          subjectType: a.subjectType,
+          on: a.on,
+          sort: a.sort,
+          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)",
+      description: "Exact distinct-subject counts per interval and across the whole range \u2014 daily/weekly/monthly actives \u2014 from a bucketed subject rollup family. Errors if the named family has no subject dimension or bucket.",
+      inputSchema: zod.z.object({
+        as: zod.z.string().describe('a bucketed subject family, e.g. "active_accounts"'),
+        subjectType: zod.z.string().optional(),
+        interval: INTERVAL.optional(),
+        ...rangeArg,
+        ...tenantArg
+      }),
+      async handler(a, ctx) {
+        const viewer = await resolve(ctx);
+        const scope = pickScope(viewer, a.tenant);
+        return q.distinctCount(scope, {
+          as: a.as,
+          subjectType: a.subjectType,
+          interval: a.interval,
+          range: parseRange(a.from, a.to)
+        });
+      }
+    }),
+    tool({
+      name: "funnel_analysis",
+      title: "Cohort funnel",
+      description: "A cohort funnel over lifetime milestone families: stage counts, conversion %, drop-off, and median time-to-step. Pass ordered stage families; the cohort window is the time range.",
+      inputSchema: zod.z.object({
+        stages: zod.z.array(zod.z.string()).min(1).describe('ordered rollup families, e.g. ["signed_up","activated","converted"]'),
+        anchor: zod.z.string().optional().describe("family assigning cohort membership. Default: stages[0]."),
+        exits: zod.z.array(zod.z.string()).optional().describe("families counted but not staged"),
+        subjectType: zod.z.string().optional(),
+        interval: zod.z.enum(["day", "week", "month"]).optional().describe("also slice the cohort by anchor date"),
+        endInclusive: zod.z.boolean().optional(),
+        ...rangeArg,
+        ...tenantArg,
+        limit: zod.z.number().int().positive().optional()
+      }),
+      async handler(a, ctx) {
+        const viewer = await resolve(ctx);
+        const scope = pickScope(viewer, a.tenant);
+        const range = parseRange(a.from, a.to);
+        return q.funnel(scope, {
+          stages: a.stages.map((as) => ({ as })),
+          anchor: a.anchor,
+          exits: a.exits?.map((as) => ({ as })),
+          subjectType: a.subjectType,
+          interval: a.interval,
+          cohort: { ...range, endInclusive: a.endInclusive === true },
+          limit: a.limit
+        });
+      }
+    }),
+    // ── deep-dive ─────────────────────────────────────────────────────────────
+    tool({
+      name: "inspect_trace",
+      title: "Inspect a trace",
+      description: "Every record sharing one traceId, on a single time axis \u2014 the correlated view of one request across services. Get a traceId from search_events or list_errors.",
+      inputSchema: zod.z.object({ traceId: zod.z.string(), ...tenantArg }),
+      async handler(a, ctx) {
+        const viewer = await resolve(ctx);
+        const scope = pickScope(viewer, a.tenant);
+        const res = await q.trace(scope, a.traceId);
+        return { ...res, items: redactAll(res.items) };
+      }
+    }),
+    tool({
+      name: "user_journey",
+      title: "User journey",
+      description: `One subject's whole story over a range \u2014 records interleaved with lifetime milestones. Pass a subject ref like "user:u_1".`,
+      inputSchema: zod.z.object({
+        subject: zod.z.string().describe('subject ref, e.g. "user:u_1"'),
+        ...rangeArg,
+        ...tenantArg,
+        limit: zod.z.number().int().positive().optional()
+      }),
+      async handler(a, ctx) {
+        const viewer = await resolve(ctx);
+        const scope = pickScope(viewer, a.tenant);
+        const res = await q.journey(scope, a.subject, parseRange(a.from, a.to), { limit: a.limit });
+        return {
+          ...res,
+          records: redactAll(res.records),
+          subjects: await labelSubjects(res.records)
+        };
+      }
+    }),
+    // ── reports ───────────────────────────────────────────────────────────────
+    tool({
+      name: "list_reports",
+      title: "List saved reports",
+      description: "The menu of reports available in this instance: saved (built by people), configured (wired by the host), and registry-derived. Each has a name and a stored query you can run with run_report.",
+      inputSchema: zod.z.object({ ...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
+        });
+        return { reports: views.map(reportSummary) };
+      }
+    }),
+    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.",
+      inputSchema: zod.z.object({
+        name: zod.z.string().describe("the report name from list_reports"),
+        ...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);
+      }
+    }),
+    // ── platform ────────────────────────────────────────────────────────────
+    tool({
+      name: "list_tenants",
+      title: "List tenants",
+      description: 'The tenant roster with recent activity \u2014 tenants that emitted anything in the range, each with a rollup-doc count, family count, event total, and last-activity time. Cross-tenant under a platform ("*") viewer; a single row otherwise.',
+      inputSchema: zod.z.object({ ...rangeArg, limit: zod.z.number().int().positive().optional() }),
+      async handler(a, ctx) {
+        const viewer = await resolve(ctx);
+        const { from, to } = parseRange(a.from, a.to);
+        const limit = Math.min(Math.max(1, a.limit ?? 200), 1e3);
+        const match = { lastAt: { $gte: from, $lt: to } };
+        if (!isPlatformScope(viewer.tenantId)) match.tenantId = viewer.tenantId;
+        const rows = await t.models.rollups.aggregate([
+          { $match: match },
+          {
+            $group: {
+              _id: "$tenantId",
+              rollupDocs: { $sum: 1 },
+              families: { $addToSet: "$as" },
+              events: { $sum: "$count" },
+              lastActivity: { $max: "$lastAt" }
+            }
+          },
+          { $sort: { lastActivity: -1 } },
+          { $limit: limit + 1 }
+        ]);
+        const truncated = rows.length > limit;
+        if (truncated) rows.pop();
+        return {
+          tenants: rows.map((r) => ({
+            tenantId: r._id,
+            rollupDocs: r.rollupDocs,
+            families: r.families.length,
+            events: r.events,
+            lastActivity: r.lastActivity
+          })),
+          truncated,
+          dataSource: "rollups"
+        };
+      }
+    }),
+    // ── ops ─────────────────────────────────────────────────────────────────
+    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?".',
+      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 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) {
+  return {
+    name: v.name,
+    origin: v.origin,
+    page: v.page,
+    shared: v.shared,
+    display: v.query?.display
+  };
+}
+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"));
+  const n = m ? Number(m[1]) : 7;
+  const unit = m?.[2] === "h" ? 36e5 : 864e5;
+  return { from: new Date(to.getTime() - n * unit), to };
+}
+
+exports.createTelemetryMcp = createTelemetryMcp;
+exports.toJsonSchema = toJsonSchema;
+//# sourceMappingURL=mcp.cjs.map
+//# sourceMappingURL=mcp.cjs.map