@open-everywhere/core 0.1.0

package/agent/spend/reporting.ts

@@ -0,0 +1,900 @@
+// Shared plumbing for the reporting tools (session_cost / spend_report / usage_report,
+// agent/tools/) and their control-plane sibling (usage_summary in control/views.ts) —
+// Batch B1 of build-2026-07-04-rbac-skills-cost.md's D6. Nothing here is a tool itself;
+// this is the "how do we scope + price + predict from usage_events rows" logic the three
+// tools and the control view all need, kept in one place so it's tested once.
+//
+// SCOPE GATING (D2): domain scope = "anyone in the domain" — the caller's channel
+// resolving to a domain at all IS the gate, no further role check. Reuses
+// skills/domain-skills.ts's resolveSkillDomainDetailed for that resolution (same
+// dm/mpim/external/unassigned exclusions a runtime skill author is held to — see that
+// module's header for why), but supplies its own refusal wording: "can't author a
+// skill" would be a misleading error from a read-only report. Org scope = org-admin
+// (access/roles.ts's requireOrgAdmin, unchanged).
+//
+// DOMAIN BUCKETING OF USAGE ROWS: a usage_events row only carries a surfaceKey + a
+// best-effort `kind` (agent/hooks/spend.ts's turnKind), not a full SurfaceBinding, so
+// it can't be run through skillDomainFor directly. domainOfUsageRow mirrors that
+// policy's SHAPE (explicit domain wins; an internal/unassigned surface falls to the
+// `org` pseudo-domain) using `kind` as the mode signal: kind==="dm" is excluded (no
+// memory domain, matching skillDomainFor's dm exclusion) and everything else resolves
+// like an ordinary channel. This is an approximation for mpim/external surfaces (usage
+// rows can't distinguish them from an unassigned internal channel, so they fall into
+// the org bucket) — acceptable because nothing here is an access decision, only a
+// read-only report's grouping.
+//
+// HONEST ESTIMATES: every number this module derives beyond a straight token/event SUM
+// is labelled as an estimate in its own shape (a `note`/`skippedReason` string, or a
+// `projected`/`approx` field name) — no dollar figure or count is fabricated; an
+// unresolvable one is omitted or explained, never guessed (same evidence discipline as
+// spend/pricing.ts's D5).
+
+import { resolvePartition } from "../memory/partition.js";
+import { requireOrgAdmin } from "../access/roles.js";
+import { domainForChannel, criteriaDomain, type Domain } from "../memory/domain.js";
+import { resolveSkillDomainDetailed, skillDomainFor, type SkillDomainRefusal, type SkillDomainResult } from "../skills/domain-skills.js";
+import { getOperationalStore } from "../operational/provider.js";
+import { getConfig } from "../access/config.js";
+import type { UsageSummaryRow } from "../operational/store.js";
+import { parseCron, cronMatches, DISPATCH_TICK_MINUTES } from "../routines/schedule.js";
+import type { RoutineTrigger } from "../routines/routine.js";
+import { modelPricing, estimateCostUsd, soleConfiguredModel, type ModelPricing, type UsageTokens, type UsageShape } from "./pricing.js";
+import { UNKNOWN_MODEL, periodOf } from "./spend.js";
+import { foldDisclosure, type SurfaceDisclosure } from "./dm-mask.js";
+import { spendRollup, type SurfacePeriodSpend } from "./store.js";
+import type { BindableContext, SurfaceBinding } from "../identity/binding.js";
+
+// --- scope gating -------------------------------------------------------------------
+
+export type ReportScope = "domain" | "org";
+
+export interface ResolvedReportScope {
+  readonly org: string;
+  /** Present only for scope "domain" — the caller's resolved domain name. */
+  readonly domain?: string;
+}
+
+/** A tool-facing refusal for a report request that can't resolve a domain — parallel
+ *  to domain-skills.ts's domainSkillRefusalMessage, reworded for a read-only report
+ *  (that function's wording is about AUTHORING a skill, which would be misleading
+ *  here). */
+export function reportDomainRefusalMessage(reason: SkillDomainRefusal): string {
+  switch (reason) {
+    case "dm":
+      return 'Domain-scoped reporting isn\'t available from a DM (a DM has no memory domain) — ask from a channel in the domain, or pass scope:"org" if you\'re an org admin.';
+    case "mpim":
+      return "Domain-scoped reporting isn't available from a group chat (execution-only, no memory domain) — ask from a channel in the domain instead.";
+    case "external":
+      return "Domain-scoped reporting isn't available from an externally-shared or unconfirmed channel.";
+    case "unassigned":
+      return 'This channel isn\'t in any memory domain and no org-wide default domain is configured — there\'s no domain to report on. Try scope:"org" if you\'re an org admin.';
+  }
+}
+
+/**
+ * Gate + resolve a report call's scope. scope="org" requires org-admin
+ * (requireOrgAdmin throws a named, model-friendly error otherwise); scope="domain"
+ * requires the caller's channel to resolve to a memory domain at all — succeeding IS
+ * the gate ("anyone in the domain" per D2), so a plain member gets their own domain's
+ * numbers but never another domain's or the org-wide view.
+ */
+export function resolveReportScope(ctx: BindableContext, scope: ReportScope): ResolvedReportScope {
+  const org = resolvePartition(ctx).org;
+  if (scope === "org") {
+    requireOrgAdmin(ctx);
+    return { org };
+  }
+  const resolved = resolveSkillDomainDetailed(ctx);
+  if (resolved.domain === null) throw new Error(reportDomainRefusalMessage(resolved.reason));
+  return { org, domain: resolved.domain };
+}
+
+// --- domain bucketing of usage rows --------------------------------------------------
+
+/**
+ * Which domain a usage_events row belongs to, for report filtering (see file header
+ * for the mirrored-not-identical relationship to skillDomainFor). Undefined when the
+ * row can't be attributed to any domain (a dm-kind row, or an internal/unassigned
+ * surface with no `org` pseudo-domain configured).
+ *
+ * GRAIN NOTE (item 22): rows are stamped at SPEND grain — a Discord thread turn's
+ * surfaceKey is its PARENT channel (hooks/spend.ts) — so this hop just works. Rows
+ * written BEFORE that landed carry the thread's own channel id and attribute to the
+ * org fallback here; they age out with usage_events retention (90d default) and the
+ * gate's calendar-month window, so no backfill/re-mapping is done.
+ */
+export function domainOfUsageRow(surfaceKey: string, kind: string | undefined, domains: readonly Domain[]): string | undefined {
+  if (kind === "dm") return undefined;
+  return domainForChannel(surfaceKey, domains)?.name ?? criteriaDomain("org", domains)?.name;
+}
+
+/** Filter usage rows to the ones belonging to `domainName` (per domainOfUsageRow). */
+export function filterToDomain<T extends { readonly surfaceKey: string; readonly kind?: string }>(
+  rows: readonly T[],
+  domainName: string,
+  domains: readonly Domain[],
+): T[] {
+  return rows.filter((r) => domainOfUsageRow(r.surfaceKey, r.kind, domains) === domainName);
+}
+
+// --- the unprivileged domain spend scan (OPE-1631) ----------------------------------
+//
+// WHAT IT IS. One read that answers "what has my domain spent lately" for a caller who holds no
+// admin role at all — the read `/oe budget raise` runs so the requester proposes a cap against a
+// number instead of against a guess. It is UNPRIVILEGED in exactly the sense `resolveReportScope`'s
+// domain arm already is (D2, "anyone in the domain"): resolving to a domain IS the gate, and the
+// caller gets that domain and no other.
+//
+// 🔴 "THEIR DOMAIN" CAN BE THE `org` PSEUDO-DOMAIN, AND THAT BUCKET IS WIDE. Say it plainly rather
+// than claiming a narrowness the resolver does not give. `skillDomainFor` falls an INTERNAL,
+// UNASSIGNED channel through to the `org` criteria domain, and this repo ships exactly that domain
+// (`agent/memory/config/domains/org.ts`). A caller in a channel no explicit domain claims therefore
+// resolves to `org`, and the sum below covers every ledger row no explicit domain claims — every
+// other unassigned surface, and DM rows too, because a `spend_ledger` row carries no `kind` and so
+// cannot take the `dm` exclusion `filterToDomain` applies to usage rows (tools/set_spend_limit.ts
+// states that asymmetry).
+//
+// THE FIGURE IS THEN ORG-SCALE, NOT WORKSPACE-SCALE. `criteriaDomain` is
+// `domains.find((d) => d.match === "org")` (memory/domain.ts) — it never looks at a surface key —
+// so the `org` bucket claims every unmatched key on EVERY workspace and EVERY platform this
+// deployment serves, and the rollup read narrows by org and by PERIOD alone — the period range
+// bounds how much history the read costs, and bounds the DISCLOSURE not at all. `/oe budget` is a
+// STRICTLY NARROWER disclosure and is not the precedent for this one: its workspace line sums the
+// `${workspaceKey}/` prefix (spend/store.ts), which is one platform and one workspace. The bucket
+// is not new — `spend_report`'s `scope: "domain"` arm resolves through this same `skillDomainFor`
+// and renders that same bucket PER SURFACE — but nothing here may be read as bounded by the room
+// or the workspace the command was typed in. Whether the scan should refuse the `org` bucket and
+// run only for an EXPLICIT domain is a policy question OPE-1631 does not settle, and it is raised
+// on the ticket rather than decided here.
+//
+// 🔴 THREE NARROWINGS, AND THE RETURN TYPE ENFORCES THE LAST TWO.
+//   1. OWN DOMAIN ONLY. {@link reportDomainForBinding} resolves the caller's domain from their own
+//      binding — a caller never names one — and the row filter then keeps that domain's rows alone.
+//      The resolver is `skills/domain-skills.ts`'s `skillDomainFor`, the SAME policy the
+//      `spend_report` / `usage_report` domain scope resolves through (`resolveReportScope` →
+//      `resolveSkillDomainDetailed` → `skillDomainFor`), so a DM, a group chat, an external channel
+//      and an unassigned channel with no `org` pseudo-domain all resolve to NO domain and the scan
+//      does not run. Two different resolutions here would be the defect: the label and the filter
+//      must name one domain, decided once.
+//   2. AGGREGATE ONLY. The window sums to ONE set of totals. There is no per-surface and no
+//      per-principal breakdown, so nothing here identifies a person or a room. That is why this
+//      read needs no anti-doxxing masking of its own — it EMITS NO KEY, not because DM rows are
+//      absent from the data. They are present, folded into the `org` bucket per the note above.
+//      `spend_report` renders per-surface rows and therefore does mask DM keys, through
+//      `maskDmSurfaceKey`.
+//   3. THE CAP LEDGER ONLY. `spendRollup` reads `spend_ledger` — the durable, keyed table the
+//      caps themselves sum — never `usage_events`. So the figure the requester reads is derived
+//      from the same rows the gate enforces against, which is the whole point of showing it beside
+//      a cap proposal.
+//
+// 🔴 THE WINDOW IS MONTH-GRAINED, AND THAT IS STATED, NEVER ROUNDED AWAY. A `spend_ledger` row is
+// keyed by `period` — "YYYY-MM" (operational/store.ts) — so the ledger CANNOT answer a rolling
+// 30-day question at all; the finest window it holds is a calendar month. This scan therefore sums
+// the calendar months the last-N-days window touches, which is one month or two, and reports those
+// period names in {@link DomainSpendWindow.periods} so every caller renders what was actually
+// summed. It over-covers rather than under-covers, and a caller that printed "the last 30 days"
+// without the periods would be making a claim the ledger cannot support.
+
+/** The calendar-month periods ("YYYY-MM") a window of `days` back from `nowISO` touches, oldest
+ *  first. One or two entries for a 30-day window, depending on where in the month `nowISO` falls. */
+export function periodsCoveringDays(nowISO: string, days: number): string[] {
+  const now = new Date(nowISO);
+  if (Number.isNaN(now.getTime())) throw new Error(`periodsCoveringDays: not an ISO instant: ${JSON.stringify(nowISO)}`);
+  if (!Number.isFinite(days) || days < 0) throw new Error(`periodsCoveringDays: days must be a non-negative finite number, got ${days}`);
+  const start = new Date(now.getTime() - days * 86_400_000);
+  // COUNT the months between the two ends, then emit that many — never a walk that steps a live
+  // cursor forward and stops when it recognises the end month. A stepping cursor keeps its
+  // day-of-month, so `setUTCMonth(+1)` from the 30th of January lands on 2 March and February
+  // vanishes from the window: a whole month of the domain's spend silently missing from the answer.
+  // `Date.UTC` normalises an out-of-range month index, so the addition below rolls the year itself.
+  const span = (now.getUTCFullYear() - start.getUTCFullYear()) * 12 + (now.getUTCMonth() - start.getUTCMonth());
+  const periods: string[] = [];
+  for (let i = 0; i <= span; i++) periods.push(periodOf(new Date(Date.UTC(start.getUTCFullYear(), start.getUTCMonth() + i, 1)).toISOString()));
+  return periods;
+}
+
+/** The caller's own domain, resolved from their binding — the report-side gate for a caller that
+ *  holds a {@link SurfaceBinding} but no live eve context (a slash command has no model turn, so
+ *  `resolveReportScope`'s `BindableContext` form does not reach it). Same policy, same refusal
+ *  reasons: it delegates to `skillDomainFor` rather than restating the rule. */
+export function reportDomainForBinding(binding: SurfaceBinding, domains: readonly Domain[]): SkillDomainResult {
+  // The two partition keys `skillDomainFor` reads, derived exactly as memory/partition.ts's
+  // `resolvePartition` derives them: the DOMAIN grain takes `domainSurface ?? surface`, so a
+  // Discord thread resolves through its parent channel (binding.ts's `domainSurface`).
+  const workspaceKey = `${binding.platform}/${binding.workspace}`;
+  return skillDomainFor(
+    binding,
+    { surfaceKey: `${workspaceKey}/${binding.surface}`, domainKey: `${workspaceKey}/${binding.domainSurface ?? binding.surface}` },
+    domains,
+  );
+}
+
+/** One domain's spend over a month-grained window. AGGREGATE ONLY — no field names a surface, a
+ *  principal or another domain, which is what makes this shape safe to hand an unprivileged
+ *  caller. */
+export interface DomainSpendWindow {
+  readonly domain: string;
+  /** The calendar-month periods actually summed, oldest first — always rendered, never implied. */
+  readonly periods: readonly string[];
+  /** Billable tokens (input + output), as the caps count them. */
+  readonly tokens: number;
+  /** DERIVED USD — the figure every cap compares against (spend/store.ts SurfacePeriodSpend.usd). */
+  readonly usd: number;
+  readonly calls: number;
+}
+
+export interface DomainSpendWindowDeps {
+  readonly spendRollup?: typeof spendRollup;
+  /** The configured domains. Injectable so a test pins the roster the filter reads. */
+  readonly domains?: readonly Domain[];
+}
+
+/**
+ * Sum ONE domain's `spend_ledger` rows over the calendar months a `days`-long window touches.
+ *
+ * 🔴 `org` IS THE STORE FILTER, not a filter over the answer (OPE-1446): it is passed to
+ * `spendRollup`, so a foreign tenant's rows never enter the process. The `l.org` conjunct below is
+ * the second belt, exactly as `spend_report`'s rollup keeps one.
+ *
+ * `domainName` is the caller's OWN domain from {@link reportDomainForBinding} — never a caller
+ * argument. Rows are attributed with {@link domainOfUsageRow}, the same hop the `spend_report`
+ * ledger rollup uses, with no `kind` — a ledger row carries its turn's CONVERSATION MODE
+ * (OPE-1862), never the turn-origin tag that hop reads.
+ */
+export async function domainSpendWindow(org: string, domainName: string, nowISO: string, days: number, deps: DomainSpendWindowDeps = {}): Promise<DomainSpendWindow> {
+  const periods = periodsCoveringDays(nowISO, days);
+  const domains = deps.domains ?? getConfig().loadDomains();
+  // 🔴 THE PERIOD RANGE IS A STORE FILTER (OPE-1653), and on this path the cost is the point.
+  // This scan runs on the SLASH-COMMAND path, where a Discord interaction must answer inside 3
+  // seconds. Reading the org's whole ledger history to keep one or two months of it costs rows
+  // transferred, parsed and aggregated on every invocation, and that cost grows with the
+  // deployment's age. THE BOUND CAN NOW CUT THE ROWS THE ENGINE SCANS TOO (OPE-1677): both
+  // adapters declare a `(org_id, period)` index on `spend_ledger`. SQLite plans the range on it
+  // from the schema alone. Postgres plans it on the index once the ledger is large enough for the
+  // index to beat a sequential scan, and only where an OWNER-mode schema run has created it — a
+  // two-role deployment gets the index from the owner/migration role's schema step, never from
+  // the runtime role's boot (docs/extending/database.md). No measurement in this repo attributes
+  // a 3-second breach to this read — the deadline is why the read is worth bounding, never
+  // evidence that the bound alone meets it.
+  // `periodsCoveringDays` returns CONTIGUOUS
+  // calendar months oldest first, so the two ends bound exactly the set `periods` names — the
+  // range and the `periods.includes` belt below can never disagree.
+  const rows = await (deps.spendRollup ?? spendRollup)(org, { periodFrom: periods[0], periodTo: periods[periods.length - 1] });
+  const mine = rows.filter((l) => l.org === org && periods.includes(l.period) && domainOfUsageRow(l.surfaceKey, undefined, domains) === domainName);
+  return {
+    domain: domainName,
+    periods,
+    tokens: mine.reduce((sum, l) => sum + l.tokens, 0),
+    usd: mine.reduce((sum, l) => sum + l.usd, 0),
+    calls: mine.reduce((sum, l) => sum + l.calls, 0),
+  };
+}
+
+// --- assumed-model pricing (hook-written rows carry no model id) --------------------
+
+export interface AssumedModelPricing {
+  /** The model id assumed, if any resolved (explicit input, or the deploy's sole
+   *  priced model). Absent when nothing could be assumed. */
+  readonly model?: string;
+  /** Its pricing, when `model` resolved AND has a configured rate. */
+  readonly pricing?: ModelPricing;
+  /** Always present — explains what happened, for the tool's output text. */
+  readonly note: string;
+}
+
+/**
+ * Resolve which model to price hook-written usage rows against (they carry no
+ * `model` field — see hooks/spend.ts). `explicit` (a caller-supplied assumption)
+ * always wins; otherwise falls back to spend/pricing.ts's soleConfiguredModel() —
+ * safe ONLY because there's exactly one priced model to assume. Never guesses among
+ * several candidates (that would be exactly the invented-number failure mode D5
+ * forbids) — a multi-model deployment must pass assumedModelId explicitly.
+ */
+export function resolveAssumedModel(explicit?: string): AssumedModelPricing {
+  const model = explicit ?? soleConfiguredModel();
+  if (!model) {
+    return {
+      note: "token $ omitted — hook-written usage rows carry no model id, and this deployment has no single default model to assume (pass assumedModelId, or ship exactly one entry in the built-in pricing table).",
+    };
+  }
+  const pricing = modelPricing(model);
+  if (!pricing) {
+    return { model, note: `token $ omitted — "${model}" has no configured pricing (checked the deployer pricing table and the built-in table).` };
+  }
+  return {
+    model,
+    pricing,
+    note: explicit
+      ? `token $ estimated at "${model}" rates (you supplied this model id — hook-written usage rows don't carry one).`
+      : `token $ estimated at "${model}" rates (this deployment's only priced model — hook-written usage rows carry no model id).`,
+  };
+}
+
+// --- per-row pricing (item 17: a row may now carry its OWN recorded model) ----------
+// hooks/spend.ts stamps a row's `model` when the routing wrapper resolved one for that
+// call (model/model-stamp.ts) — pre-existing rows, and rows from a call the wrapper
+// never touched (an unrouted static `model` config, or a call outside a session), still
+// carry no model at all. A report must price EACH KIND correctly: a stamped row gets
+// its OWN model's rate (exact); a stampless row falls back to the assumed model (the
+// pre-item-17 behaviour, unchanged); a stamped row whose model has no configured rate
+// is shown tokens-only — it must NOT borrow the assumed model's rate, which would price
+// its real tokens at a DIFFERENT model's cost (silently wrong, not honestly omitted).
+
+/** The token-count + optional recorded-model shape rowCostUsd needs — a structural
+ *  subset of UsageEventEntry/UsageSummaryRow, so either can be passed directly. */
+export type PriceableRow = UsageTokens & { readonly model?: string };
+
+/**
+ * One row's USD cost: its OWN stamped model's rate when it has one AND this
+ * deployment has priced it (exact); otherwise the report's assumed-model fallback,
+ * ONLY for rows that carry no model at all. Undefined when neither prices it.
+ *
+ * 🔴 `shape` SAYS WHETHER THE ROW IS ONE CALL, and the caller must answer honestly, because "row"
+ * means two different things among this function's callers (OPE-2055). `session_cost` and the
+ * analytics executor walk RAW `usage_events` rows — one row, one model call, so a long-context tier
+ * applies. `spend_report` walks rows the store already grouped by (surfaceKey, principalId, kind,
+ * surfaceMode, model), each carrying its own `events` count — a sum with no prompt size in it, where
+ * the tier must never fire. See {@link UsageShape}. The default is `"aggregate"`, the
+ * non-surcharging answer, so a caller that says nothing cannot be over-billed.
+ */
+export function rowCostUsd(row: PriceableRow, assumed: AssumedModelPricing, shape: UsageShape = "aggregate"): number | undefined {
+  if (row.model) {
+    const exact = modelPricing(row.model);
+    return exact ? estimateCostUsd(row, exact, shape) : undefined;
+  }
+  return assumed.pricing ? estimateCostUsd(row, assumed.pricing, shape) : undefined;
+}
+
+/** How a set of rows split across the three pricing paths above — the basis for an
+ *  honest note when a report mixes stamped and stampless rows. */
+export interface PricingMix {
+  /** Rows priced exactly, by their own recorded model. */
+  readonly exact: number;
+  /** Stampless rows priced via the assumed-model fallback. */
+  readonly assumed: number;
+  /** Rows with no price at all (a stamped model this deployment hasn't configured a
+   *  rate for, or a stampless row with no assumable model either). */
+  readonly unpriced: number;
+  /**
+   * Rows recorded under the UNKNOWN_MODEL sentinel (OPE-369) — a token-bearing model call the host
+   * could not attribute to any model. A SUBSET of {@link unpriced} (no rate table names the
+   * sentinel), broken out because the two are different findings for a reader: an unpriced row is
+   * "configure a rate for this model", an unattributed one is "the model stamp went missing" — an
+   * instrumentation defect, not a pricing gap, and the only one of the two worth chasing in code.
+   */
+  readonly unattributed: number;
+}
+
+export function pricingMix(rows: readonly PriceableRow[], assumed: AssumedModelPricing): PricingMix {
+  let exact = 0;
+  let assumedCount = 0;
+  let unpriced = 0;
+  let unattributed = 0;
+  for (const r of rows) {
+    if (r.model) {
+      if (modelPricing(r.model)) exact++;
+      else unpriced++;
+      if (r.model === UNKNOWN_MODEL) unattributed++;
+    } else if (assumed.pricing) {
+      assumedCount++;
+    } else {
+      unpriced++;
+    }
+  }
+  return { exact, assumed: assumedCount, unpriced, unattributed };
+}
+
+/**
+ * Compose the honest $ note for a report given its pricing mix. Supersedes using
+ * `assumed.note` verbatim once ANY row carries a stamped model: that note describes
+ * only the assumed-model FALLBACK path ("hook-written rows carry no model id") and
+ * would misleadingly suggest $ is guessed/omitted even when most or all rows are now
+ * priced exactly by their own recorded model. Pre-item-17 behaviour (no stamped rows
+ * at all) reproduces `assumed.note` verbatim — no wording change for that case.
+ */
+export function pricingNote(mix: PricingMix, assumed: AssumedModelPricing): string {
+  if (mix.exact === 0) return assumed.note; // unchanged legacy wording — nothing stamped
+  const parts: string[] = [
+    mix.assumed === 0 && mix.unpriced === 0
+      ? "$ figures are exact — every priced row carries its own recorded model id."
+      : `${mix.exact} row(s) priced exactly by their own recorded model id.`,
+  ];
+  if (mix.assumed > 0) parts.push(`${mix.assumed} row(s) with no recorded model: ${assumed.note}`);
+  // The unattributed rows are a SUBSET of `unpriced`, so they are subtracted out of that sentence
+  // rather than double-counted — and given their own, because "configure a rate" is the wrong
+  // remedy for them and would send a reader off to price a model id in agent/spend/model-pricing.ts that
+  // doesn't exist.
+  const unpricedButAttributed = mix.unpriced - mix.unattributed;
+  if (unpricedButAttributed > 0) {
+    parts.push(`${unpricedButAttributed} row(s) omitted — a recorded model this deployment hasn't configured a rate for (see agent/spend/model-pricing.ts), never priced at another model's rate.`);
+  }
+  if (mix.unattributed > 0) {
+    parts.push(
+      `${mix.unattributed} row(s) omitted as "${UNKNOWN_MODEL}" — a real model call the host could not attribute to any model (the per-call model stamp was missing), so no rate was applied to it. ` +
+        `Its tokens are recorded in full, and where the gateway measured the call its exact $ is stored too; only the rate-derived $ is withheld. This is an instrumentation gap, not a pricing one.`,
+    );
+  }
+  return parts.join(" ");
+}
+
+// --- token attribution: where the tokens went, beside what they cost (OPE-1611) ------
+// The billed dollars are settled elsewhere and stay settled: `usd_micros_measured` is the
+// gateway's own figure and `usd_micros` the rate-derived one, and NOTHING here touches either.
+// What this section adds is the other question a spend reader has — WHY was a call cheap, and how
+// much of the output was reasoning — answered from token counts alone, with the coverage stated
+// so an absent answer never reads as a zero.
+
+/** How a set of rollup rows split across the cache/reasoning attribution dimensions. */
+export interface TokenAttribution {
+  /** Model calls in scope (the rollup's event count). */
+  readonly calls: number;
+  readonly cacheReadTokens: number;
+  readonly cacheWriteTokens: number;
+  readonly reasoningTokens: number;
+  /** Calls whose source REPORTED a cache split. `calls - cacheReportedCalls` is the honest
+   *  "unreported" count — those rows' cache zeros assert nothing. */
+  readonly cacheReportedCalls: number;
+  /** Calls that reported a reasoning-token count at all. */
+  readonly reasoningReportedCalls: number;
+}
+
+/** Sum the attribution dimensions across rollup rows. Pure. */
+export function tokenAttribution(
+  rows: readonly Pick<UsageSummaryRow, "cacheReadTokens" | "cacheWriteTokens" | "reasoningTokens" | "cacheReportedCalls" | "reasoningReportedCalls" | "events">[],
+): TokenAttribution {
+  const acc = { calls: 0, cacheReadTokens: 0, cacheWriteTokens: 0, reasoningTokens: 0, cacheReportedCalls: 0, reasoningReportedCalls: 0 };
+  for (const r of rows) {
+    acc.calls += r.events;
+    acc.cacheReadTokens += r.cacheReadTokens;
+    acc.cacheWriteTokens += r.cacheWriteTokens;
+    acc.reasoningTokens += r.reasoningTokens;
+    acc.cacheReportedCalls += r.cacheReportedCalls;
+    acc.reasoningReportedCalls += r.reasoningReportedCalls;
+  }
+  return acc;
+}
+
+/**
+ * The honest one-line attribution note that rides BESIDE a report's dollars.
+ *
+ * 🔴 IT NAMES NO DOLLARS, EVER, and that is the ruling it implements (Tommy, 2026-09-08): the
+ * gateway's measured `costUsd` is the billed truth, so "caching saved $X" derived from a token
+ * count nothing billed against would be a guess wearing a number. The note says how many tokens
+ * each dimension carried and — the part that makes it trustworthy — how much of that is known.
+ *
+ * 🔴 THE CACHE ARM KEYS ON THE TOKEN COUNT, NOT ON THE REPORTED-FIELD FLAG, and the distinction is
+ * the whole value of the line. The Vercel AI Gateway is recorded as billing the prompt-cache
+ * discount with `usage.cachedInputTokens` reading `0` rather than absent
+ * (docs/security/spend-and-cost.md, from the 2026-08-11 rate solve). A published zero sets
+ * `cacheTokensReported` true, so a note that trusted that flag would print "every call reported a
+ * split: 0 read, 0 write" — an affirmative "no caching" over calls the gateway discounted. A ZERO
+ * TOTAL therefore reads as UNATTRIBUTED here, whatever the flag says, and the field count rides
+ * along as the secondary fact rather than the verdict.
+ *
+ * 🔴 AND THE ZERO ARM SPLITS ON WHETHER ANY CALL PUBLISHED A FIELD, because the two silences have
+ * different causes and only one of them is the gateway's. With `cacheReportedCalls === 0` no source
+ * published the dimension at all, so the note claims nothing about caching and names no backend:
+ * blaming the gateway there would explain a provider-payload silence with someone else's billing
+ * behaviour. `ModelBackend` is swappable (docs/deploy/configuration-reference.md) — a self-host on
+ * OpenRouter or a direct provider SDK is supported — so the discount sentence is stated for the
+ * Vercel AI Gateway backend by name, never as a fact about every deployment. An operator who reads
+ * "the saving is already inside the cost" about a backend that does not behave that way stops
+ * looking for a real gap.
+ */
+export function tokenAttributionNote(a: TokenAttribution): string {
+  if (a.calls === 0) return "No model calls in scope — nothing to attribute.";
+  const parts: string[] = [];
+  const cacheTokens = a.cacheReadTokens + a.cacheWriteTokens;
+  parts.push(
+    cacheTokens === 0
+      ? a.cacheReportedCalls === 0
+        ? `Cache: UNATTRIBUTED across all ${a.calls} call(s) — no call published a cache field at all, ` +
+          `so nothing here says whether caching happened.`
+        : `Cache: UNATTRIBUTED across all ${a.calls} call(s) — no cache tokens were reported at all ` +
+          `(${a.cacheReportedCalls} call(s) published a cache field, every one of them zero). A zero is NOT a measurement that caching did not happen: ` +
+          `on the Vercel AI Gateway backend a cached call is billed at the discount while the cached-token count reads 0 ` +
+          `(docs/security/spend-and-cost.md), so on that backend the saving shows in the cost and never in the split.`
+      : `Cache: ${a.cacheReadTokens} read / ${a.cacheWriteTokens} write token(s)` +
+        (a.cacheReportedCalls < a.calls
+          ? `; ${a.calls - a.cacheReportedCalls} of ${a.calls} call(s) published no cache field at all, so nothing is claimed about those.`
+          : ` across ${a.calls} call(s), all of which published a cache field.`),
+  );
+  parts.push(
+    a.reasoningReportedCalls === 0
+      ? `Reasoning tokens: UNREPORTED on all ${a.calls} call(s).`
+      : `Reasoning: ${a.reasoningTokens} token(s) across ${a.reasoningReportedCalls} of ${a.calls} call(s) that reported the dimension.`,
+  );
+  // No "$" anywhere in this string, and the suite asserts that literally: the whole point of the
+  // line is that it answers WHERE the tokens went without answering what they saved.
+  parts.push("These are ATTRIBUTION counts only — no dollar figure is derived from them, and the billed cost above stands unchanged.");
+  return parts.join(" ");
+}
+
+// --- measured-vs-derived cost drift (OPE-369) ----------------------------------------
+// The whole point of storing BOTH answers on a ledger row (see operational/store.ts's CostSource
+// section): where the gateway measured a call, we also kept what OUR rate table said the same call
+// cost, so the two can be compared without re-deriving anything. Divergence is a finding about the
+// rate table — the very failure spend/pricing.ts's BUILT_IN comment documents happening twice
+// already (a published catalog rate that wasn't what got billed; a stale entry naming a model the
+// deploy no longer ran, mispricing by ~10x). This is a summary line, deliberately not a subsystem.
+
+export interface CostDrift {
+  /** USD the gateway billed, over the rows it measured. */
+  readonly measuredUsd: number;
+  /** USD our rate table derived FOR THOSE SAME rows — the comparable half. */
+  readonly derivedUsd: number;
+  /** derived − measured. Positive = the rate table OVER-states the bill. */
+  readonly divergenceUsd: number;
+  /** Divergence as a percentage of the measured figure. Absent when nothing was measured, or
+   *  when the measured total is 0 (a percentage of zero is not a number a report may print). */
+  readonly divergencePct?: number;
+  /** Calls the gateway measured, and calls in scope overall — the COVERAGE of the comparison.
+   *  A tiny divergence over 3 of 40,000 calls means something very different from one over all
+   *  of them, so the denominator always travels with the number. */
+  readonly measuredCalls: number;
+  readonly totalCalls: number;
+}
+
+/** Summarise measured-vs-derived divergence across already-scoped ledger rollup rows (pure). */
+export function summariseCostDrift(rows: readonly SurfacePeriodSpend[]): CostDrift {
+  let measuredUsd = 0;
+  let derivedUsd = 0;
+  let measuredCalls = 0;
+  let totalCalls = 0;
+  for (const r of rows) {
+    measuredUsd += r.usdMeasured;
+    derivedUsd += r.usdDerivedOnMeasured;
+    measuredCalls += r.measuredCalls;
+    totalCalls += r.calls;
+  }
+  const divergenceUsd = derivedUsd - measuredUsd;
+  return {
+    measuredUsd,
+    derivedUsd,
+    divergenceUsd,
+    ...(measuredCalls > 0 && measuredUsd > 0 ? { divergencePct: (divergenceUsd / measuredUsd) * 100 } : {}),
+    measuredCalls,
+    totalCalls,
+  };
+}
+
+/** The one-sentence reading of a {@link CostDrift}, for a report's note block. Always says what
+ *  the coverage was, because a divergence figure without its denominator is not interpretable. */
+export function costDriftNote(drift: CostDrift): string {
+  if (drift.measuredCalls === 0) {
+    return `costDrift: no gateway-measured cost on any ledger row this period (${drift.totalCalls} call(s) in scope), so every $ above is rate-derived from this deployment's own price table. Measured cost is a GATEWAY feature — its absence is expected on a direct-provider deployment and is not a fault.`;
+  }
+  const pct = drift.divergencePct === undefined ? "n/a" : `${drift.divergencePct >= 0 ? "+" : ""}${drift.divergencePct.toFixed(1)}%`;
+  const direction = drift.divergenceUsd === 0 ? "agrees with" : drift.divergenceUsd > 0 ? "OVER-states" : "UNDER-states";
+  return (
+    `costDrift: over the ${drift.measuredCalls} of ${drift.totalCalls} call(s) the gateway measured, it billed $${drift.measuredUsd.toFixed(4)} where this deployment's rate table derived $${drift.derivedUsd.toFixed(4)} ` +
+    `— the rate table ${direction} the bill by $${Math.abs(drift.divergenceUsd).toFixed(4)} (${pct}). The caps enforce the DERIVED figure, so a persistent divergence means the price table needs re-measuring (spend/pricing.ts), not that the caps are broken.`
+  );
+}
+
+// --- routine cadence + cost prediction ----------------------------------------------
+
+// THE DISPATCHER FLOOR (OPE-146 / audit §S9). Whatever a trigger asks for, the dispatcher
+// evaluates the store once every DISPATCH_TICK_MINUTES and a routine is dispatched at most
+// ONCE per tick — so no routine can fire more than 1440/DISPATCH_TICK_MINUTES times a day.
+// The prediction used to read the trigger literally and over-count anything finer: an
+// `everyMinutes: 5` routine was projected at 288 fires/day against an actual ~144, i.e. a
+// 2× over-statement of its projected spend. Predictions are labelled estimates, but an
+// estimate that ignores a hard floor the same package enforces is just wrong.
+const MAX_FIRES_PER_DAY = 1440 / DISPATCH_TICK_MINUTES;
+
+function cronFiresPerDay(expr: string): number | undefined {
+  try {
+    const parsed = parseCron(expr);
+    const start = new Date();
+    start.setUTCSeconds(0, 0);
+    // Count TICK WINDOWS containing at least one matching minute, not matching minutes: a
+    // `* * * * *` cron matches 1440 times but is dispatched once per tick. Windows are
+    // indexed off midnight so the count doesn't depend on when this happens to run.
+    const ticks = new Set<number>();
+    for (let i = 0; i < 1440; i++) {
+      const t = new Date(start.getTime() + i * 60_000);
+      if (cronMatches(parsed, t)) ticks.add(Math.floor((t.getUTCHours() * 60 + t.getUTCMinutes()) / DISPATCH_TICK_MINUTES));
+    }
+    return ticks.size;
+  } catch {
+    return undefined; // a malformed cron on a live routine — treat as unknowable, not a crash
+  }
+}
+
+/**
+ * Fires/day for a clock-scheduled trigger, or undefined when the cadence is
+ * unknowable for PREDICTION purposes. Per D6: `watch` re-evaluates on `everyMinutes`
+ * but posts only on a state DIFF, so how often it actually spends tokens isn't
+ * derivable from the schedule alone; `event` isn't clock-scheduled at all.
+ *
+ * Capped at the dispatcher's own tick floor (see {@link MAX_FIRES_PER_DAY}) — a cadence
+ * finer than the tick simply cannot be achieved, so predicting it would over-state spend.
+ */
+export function firesPerDay(trigger: RoutineTrigger): number | undefined {
+  switch (trigger.kind) {
+    case "interval":
+      return Math.min(MAX_FIRES_PER_DAY, 1440 / Math.max(1, trigger.everyMinutes));
+    case "cron":
+      return cronFiresPerDay(trigger.expr);
+    case "watch":
+    case "event":
+      return undefined;
+  }
+}
+
+export interface RoutinePredictionRow {
+  readonly surfaceKey: string;
+  /** WHAT THIS LINE MAY BE PUBLISHED AS (OPE-1862) — folded from the conversation mode of the
+   *  usage rows behind it (`foldDisclosure`). A prediction groups a surface's `kind: "routine"`
+   *  rows, and that tag is exactly the one that says nothing about the conversation, so the fold
+   *  is the only thing standing between a routine fired in a DM and a published DM key. */
+  readonly disclosure: SurfaceDisclosure;
+  /** Distinct routine-fired sessions observed in the report window (usageSummary's
+   *  `sessions` for this surface's kind="routine" rows). */
+  readonly observedFires: number;
+  readonly avgTokensPerFire: number;
+  /** Sum of fires/day across this surface's active cron/interval routines. */
+  readonly cadencePerDay?: number;
+  readonly projected: {
+    readonly tokens7d: number;
+    readonly tokens30d: number;
+    readonly costUsd7d?: number;
+    readonly costUsd30d?: number;
+  } | null;
+  /** Why `projected` is null — too little signal, or no predictable-cadence routine. */
+  readonly skippedReason?: string;
+}
+
+const MIN_FIRES_FOR_PREDICTION = 3;
+
+/**
+ * Predict 7d/30d token (and $, if priced) spend per surface from routine-fired usage:
+ * avg tokens/fire (this window's historical average) × the surface's currently
+ * ACTIVE cron/interval cadence. ESTIMATES ONLY (label downstream) — skips a surface
+ * with fewer than MIN_FIRES_FOR_PREDICTION observed fires (not enough signal) or
+ * whose only routines are watch/event or inactive (cadence unknowable right now).
+ * `routineRows` should already be scoped (org/domain-filtered) usageSummary rows
+ * with kind === "routine".
+ */
+export async function buildRoutinePredictions(
+  org: string,
+  routineRows: readonly UsageSummaryRow[],
+  pricing: ModelPricing | undefined,
+): Promise<RoutinePredictionRow[]> {
+  const bySurface = new Map<string, { inputTokens: number; outputTokens: number; cacheReadTokens: number; sessions: number; rows: UsageSummaryRow[] }>();
+  for (const r of routineRows) {
+    const acc = bySurface.get(r.surfaceKey) ?? { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, sessions: 0, rows: [] };
+    // Kept only to fold this surface's disclosure (OPE-1862) — see RoutinePredictionRow.
+    acc.rows.push(r);
+    acc.inputTokens += r.inputTokens;
+    acc.outputTokens += r.outputTokens;
+    acc.cacheReadTokens += r.cacheReadTokens;
+    // Routine fires rarely span multiple senders (routine.createdBy is audit-only,
+    // and the dispatched turn typically carries no per-turn human sender), so
+    // summing `sessions` across this surface's (principal,model) rows is a much
+    // safer approximation here than the general conversation-count problem
+    // approxConversationCount documents for live channel/dm traffic.
+    acc.sessions += r.sessions;
+    bySurface.set(r.surfaceKey, acc);
+  }
+
+  const store = getOperationalStore();
+  const out: RoutinePredictionRow[] = [];
+  for (const [surfaceKey, acc] of bySurface) {
+    if (acc.sessions < MIN_FIRES_FOR_PREDICTION) {
+      out.push({
+        surfaceKey,
+        disclosure: foldDisclosure(acc.rows),
+        observedFires: acc.sessions,
+        avgTokensPerFire: acc.sessions > 0 ? (acc.inputTokens + acc.outputTokens) / acc.sessions : 0,
+        projected: null,
+        skippedReason: `fewer than ${MIN_FIRES_FOR_PREDICTION} observed fires in this window — not enough signal to predict`,
+      });
+      continue;
+    }
+
+    const avgTokensPerFire = (acc.inputTokens + acc.outputTokens) / acc.sessions;
+
+    const routines = await store.listRoutines(org, surfaceKey);
+    let cadence = 0;
+    let sawClockScheduled = false;
+    for (const routine of routines) {
+      if (routine.status !== "active") continue;
+      const fpd = firesPerDay(routine.trigger);
+      if (fpd !== undefined) {
+        cadence += fpd;
+        sawClockScheduled = true;
+      }
+    }
+    if (!sawClockScheduled) {
+      out.push({
+        surfaceKey,
+        disclosure: foldDisclosure(acc.rows),
+        observedFires: acc.sessions,
+        avgTokensPerFire,
+        projected: null,
+        skippedReason: "no active cron/interval routine found for this surface — cadence unknowable (watch/event routines don't have a predictable fire rate)",
+      });
+      continue;
+    }
+
+    const avgInput = acc.inputTokens / acc.sessions;
+    const avgOutput = acc.outputTokens / acc.sessions;
+    const avgCacheRead = acc.cacheReadTokens / acc.sessions;
+    // 🔴 "aggregate", and the divisor is why. These are averages per FIRE — `acc.sessions` counts
+    // distinct sessions, not model calls — and one fire runs a whole session, which is many calls.
+    // So `avgInput` is a per-conversation total, not any prompt's size, and testing it against a
+    // per-call tier boundary would surcharge every routine whose FIRE totals 272,001 tokens across
+    // its turns (OPE-2055). A per-call average would have to divide by `events`, which this
+    // accumulator does not carry. The cost of withholding the tier here is an understated
+    // prediction for a routine that genuinely runs long prompts — stated, not silent.
+    const costPerFire = pricing ? estimateCostUsd({ inputTokens: avgInput, outputTokens: avgOutput, cacheReadTokens: avgCacheRead }, pricing, "aggregate") : undefined;
+
+    out.push({
+      surfaceKey,
+      disclosure: foldDisclosure(acc.rows),
+      observedFires: acc.sessions,
+      avgTokensPerFire,
+      cadencePerDay: cadence,
+      projected: {
+        tokens7d: avgTokensPerFire * cadence * 7,
+        tokens30d: avgTokensPerFire * cadence * 30,
+        ...(costPerFire !== undefined ? { costUsd7d: costPerFire * cadence * 7, costUsd30d: costPerFire * cadence * 30 } : {}),
+      },
+    });
+  }
+  return out;
+}
+
+// --- display labels: raw Slack ids → human names (best-effort, display-only) ---------
+// Usage rows carry bare platform ids ("U0EXOWNER", "slack:T…:U…" principals;
+// "slack/T…/C…" surface keys). Reports render friendlier with names attached, so the
+// tools resolve labels through these helpers — INJECTED lookups (live: slack-events.ts's
+// memoized users.info / conversations.info fetchers), every failure → no label, never an
+// error. Labels are decoration on top of the raw id, which always stays in the row: a
+// display name is neither unique nor stable, so the id remains the ground truth.
+
+export interface SlackLabelDeps {
+  readonly userName: (userId: string) => Promise<string | undefined>;
+  readonly channelName: (channelId: string) => Promise<string | undefined>;
+}
+
+/** The Slack member id embedded in a usage-row principal id, if any: a bare "U…"/"W…"
+ *  id, or the last segment of a composite "slack:T…:U…" / "slack:T…:bot:U…" principal. */
+export function slackUserIdIn(principalId: string): string | undefined {
+  const candidate = principalId.includes(":") ? principalId.slice(principalId.lastIndexOf(":") + 1) : principalId;
+  return /^[UW][A-Z0-9]{5,}$/.test(candidate) ? candidate : undefined;
+}
+
+/** The Slack channel id in a fully-qualified surface key ("slack/T…/C…"), if any. */
+export function slackChannelIdIn(surfaceKey: string): string | undefined {
+  const parts = surfaceKey.split("/");
+  if (parts[0] !== "slack" || parts.length < 3) return undefined;
+  const id = parts[2];
+  return /^[CGD][A-Z0-9]{5,}$/.test(id) ? id : undefined;
+}
+
+export interface SlackLabels {
+  /** principalId (as it appears in the rows) → display name. */
+  readonly users: ReadonlyMap<string, string>;
+  /** surfaceKey (as it appears in the rows) → "#channel-name". */
+  readonly channels: ReadonlyMap<string, string>;
+}
+
+/**
+ * Resolve display labels for a report's principal ids + surface keys in one pass,
+ * deduplicated, all lookups concurrent, every failure silently unlabelled. DMs ("D…"
+ * ids) get no conversations.info name — they stay unlabelled by design.
+ */
+export async function resolveSlackLabels(
+  principalIds: readonly string[],
+  surfaceKeys: readonly string[],
+  deps: SlackLabelDeps,
+): Promise<SlackLabels> {
+  const users = new Map<string, string>();
+  const channels = new Map<string, string>();
+  const lookups: Promise<void>[] = [];
+  for (const pid of new Set(principalIds)) {
+    const userId = slackUserIdIn(pid);
+    if (!userId) continue;
+    lookups.push(
+      deps
+        .userName(userId)
+        .then((name) => {
+          if (name) users.set(pid, name);
+        })
+        .catch(() => {}),
+    );
+  }
+  for (const key of new Set(surfaceKeys)) {
+    const channelId = slackChannelIdIn(key);
+    if (!channelId || channelId.startsWith("D")) continue;
+    lookups.push(
+      deps
+        .channelName(channelId)
+        .then((name) => {
+          if (name) channels.set(key, `#${name}`);
+        })
+        .catch(() => {}),
+    );
+  }
+  await Promise.all(lookups);
+  return { users, channels };
+}
+
+// --- usage_report aggregations -------------------------------------------------------
+
+/**
+ * "How many conversations happened" from grouped usageSummary rows. APPROXIMATE, not
+ * exact: usageSummary groups by (surfaceKey, principalId, kind, surfaceMode, model), and a single
+ * session's turns CAN carry different principalIds (per-turn caller identity is
+ * rewritten every turn — ground truth in the build plan), so summing `sessions`
+ * across a surface's principal-groups can double-count a session touched by more
+ * than one sender. There is no query that recovers the true distinct count from
+ * already-grouped data (it would need the raw per-event rows) — this is the
+ * documented, honestly-labelled approximation. kind==="sandbox" rows are excluded:
+ * they share a session_id with a real conversation-kind row and would double-count it
+ * on top of the principal-split issue.
+ */
+export function approxConversationCount(rows: readonly UsageSummaryRow[]): number {
+  let total = 0;
+  for (const r of rows) {
+    if (r.kind === "sandbox") continue;
+    total += r.sessions;
+  }
+  return total;
+}
+
+export interface UserActivity {
+  readonly principalId: string;
+  /** Row (~model-call) count — an exact sum, unlike the conversation estimate above. */
+  readonly events: number;
+  readonly inputTokens: number;
+  readonly outputTokens: number;
+}
+
+/** Per-user activity (events + tokens), excluding sandbox rows and rows with no
+ *  resolved principal. Summing `events` (a plain row count) across groups is exact —
+ *  unlike `sessions` (a distinct count), it can't be double-counted by re-grouping. */
+export function aggregateByUser(rows: readonly UsageSummaryRow[]): UserActivity[] {
+  const byUser = new Map<string, UserActivity>();
+  for (const r of rows) {
+    if (r.kind === "sandbox" || !r.principalId) continue;
+    const acc = byUser.get(r.principalId) ?? { principalId: r.principalId, events: 0, inputTokens: 0, outputTokens: 0 };
+    byUser.set(r.principalId, {
+      principalId: r.principalId,
+      events: acc.events + r.events,
+      inputTokens: acc.inputTokens + r.inputTokens,
+      outputTokens: acc.outputTokens + r.outputTokens,
+    });
+  }
+  return [...byUser.values()].sort((a, b) => b.events - a.events);
+}
+
+export interface SurfaceActivity {
+  readonly surfaceKey: string;
+  readonly events: number;
+  /** Same approximation caveat as approxConversationCount, scoped to this surface. */
+  readonly sessions: number;
+  readonly inputTokens: number;
+  readonly outputTokens: number;
+}
+
+/** Busiest-surfaces breakdown (events + tokens exact; sessions approximate — see
+ *  approxConversationCount), excluding sandbox rows. Sorted busiest-first. */
+export function aggregateBySurface(rows: readonly UsageSummaryRow[]): SurfaceActivity[] {
+  const bySurface = new Map<string, SurfaceActivity>();
+  for (const r of rows) {
+    if (r.kind === "sandbox") continue;
+    const acc = bySurface.get(r.surfaceKey) ?? { surfaceKey: r.surfaceKey, events: 0, sessions: 0, inputTokens: 0, outputTokens: 0 };
+    bySurface.set(r.surfaceKey, {
+      surfaceKey: r.surfaceKey,
+      events: acc.events + r.events,
+      sessions: acc.sessions + r.sessions,
+      inputTokens: acc.inputTokens + r.inputTokens,
+      outputTokens: acc.outputTokens + r.outputTokens,
+    });
+  }
+  return [...bySurface.values()].sort((a, b) => b.events - a.events);
+}