@open-everywhere/core 0.1.0

package/agent/analytics/compile.ts

@@ -0,0 +1,461 @@
+// The ANALYTICS COMPILER (OPE-66) — the PURE, unit-tested function that turns a validated query
+// object + a resolved AnalyticsScope into a parameterized query the store executes. This is where
+// the security bar is met: NO model-supplied string ever becomes SQL text or a SQL identifier.
+//
+//   • Dimension/measure/filter-dim NAMES are looked up in the registry (analytics/registry.ts) and
+//     mapped to FIXED SQL fragments. An unknown name never reaches here (zod enum) and even if it
+//     did, the lookup returns undefined and we throw — a name is never concatenated into SQL.
+//   • Filter VALUES are the only free strings, and they exclusively become BIND PARAMETERS (`?`),
+//     never SQL text.
+//   • The SCOPE predicate is injected HOST-SIDE, always FIRST in the WHERE, from the verified
+//     AnalyticsScope (org from resolvePartition, the domain channel-list from config-as-code). A
+//     model filter can only AND further conjuncts on — it can never widen the scope.
+//
+// DUAL-ENGINE: the compiled form uses `?` placeholders + engine-identical fragments; the store
+// adapters render `?`→`$n` for Postgres via assembleAnalyticsSql. The differential-oracle test
+// (scripts/analytics-query-test.ts) runs the SAME compiled query on sqlite AND pglite and asserts
+// identical, scope-correct rows.
+//
+// AGGREGATE vs ROWS: aggregate mode SQL-groups at the finest grain needed (real columns + a ts
+// substr bucket + the surface column(s) behind a `domain` group + `model` when est_usd is asked),
+// fetches up to an internal scan cap, and the caller (analytics/execute.ts) FOLDS host-side to the
+// requested output grain (computing `domain` and the ISO `week` bucket, pricing `est_usd`, DM-
+// masking). Rows mode returns the raw listing, ordered newest-first, hard-capped in SQL.
+
+import { z } from "zod";
+import { DATASETS, DATASET_NAMES, type DatasetName, type DatasetSpec, type TsBucket } from "./registry.js";
+import type { AnalyticsScope } from "../access/analytics-scope.js";
+import type { CompiledAnalyticsQuery } from "../operational/store.js";
+import { domainForChannel, criteriaDomain, domainRoster, type Domain } from "../memory/domain.js";
+
+export type { CompiledAnalyticsQuery } from "../operational/store.js";
+
+// --- the model-facing grammar (zod) --------------------------------------------------------
+
+const ALL_DIMS = [...new Set(DATASET_NAMES.flatMap((d) => Object.keys(DATASETS[d].dims)))] as [string, ...string[]];
+const ALL_MEASURES = [...new Set(DATASET_NAMES.flatMap((d) => Object.keys(DATASETS[d].measures)))] as [string, ...string[]];
+
+/** The ENTIRE model-facing query grammar. Deliberate absences (nl-analytics-query-plan §grammar):
+ *  no expressions, no HAVING, no joins, no OR trees, no regex/LIKE beyond `prefix`, no model-visible
+ *  `org`. Names are enums (unknown → schema failure); only filter `value` is a free string, and it
+ *  only ever becomes a bind parameter. */
+export const analyticsQuerySchema = z.object({
+  dataset: z.enum(DATASET_NAMES as [DatasetName, ...DatasetName[]]),
+  scope: z.enum(["org", "domain", "self"]),
+  mode: z.enum(["aggregate", "rows"]).default("aggregate"),
+  select: z.array(z.enum(ALL_MEASURES)).optional().describe("measures (aggregate mode)"),
+  groupBy: z.array(z.enum(ALL_DIMS)).optional(),
+  filters: z
+    .array(
+      z.object({
+        dim: z.enum(ALL_DIMS),
+        op: z.enum(["eq", "in", "prefix"]),
+        value: z.union([z.string(), z.array(z.string())]),
+      }),
+    )
+    .optional(),
+  since: z.string().optional().describe("ISO-8601 lower bound on ts (audit/usage)"),
+  until: z.string().optional().describe("ISO-8601 upper bound on ts (audit/usage)"),
+  tsBucket: z.enum(["hour", "day", "week", "month"]).optional().describe('bucket for the "ts" group dimension (default day)'),
+  orderBy: z.object({ by: z.enum([...ALL_DIMS, ...ALL_MEASURES] as [string, ...string[]]), dir: z.enum(["asc", "desc"]) }).optional(),
+  limit: z.number().int().positive().optional(),
+});
+
+export type AnalyticsQuery = z.infer<typeof analyticsQuerySchema>;
+
+// --- caps (host-clamped; re-checked in SQL LIMIT + host-side) --------------------------------
+
+const AGGREGATE_LIMIT_MAX = 200;
+export const ROWS_LIMIT_MAX = 100;
+/** Internal SQL scan cap for aggregate mode: fetch up to this many pre-fold rows so the host fold
+ *  (domain/week coarsening) is correct, then apply the ≤200 output limit. Bounds work without
+ *  letting a fold silently drop groups. */
+export const AGGREGATE_SCAN_CAP = 5000;
+const MAX_WINDOW_DAYS = 365;
+
+// --- compiled forms -------------------------------------------------------------------------
+// CompiledAnalyticsQuery's canonical home is operational/store.ts (re-exported above) — the
+// store seam names it without a cycle back into agent/analytics/*.
+
+export type OutputDimKind = "column" | "ts" | "domain";
+export interface OutputDim {
+  readonly name: string;
+  readonly kind: OutputDimKind;
+  /** physical column (kind column); for a ts dim, the ts column; for domain, the surface source. */
+  readonly column?: string;
+  readonly tsBucket?: TsBucket;
+}
+
+/** The host-side post-processing plan (analytics/execute.ts consumes it). */
+export interface AnalyticsPlan {
+  readonly mode: "aggregate" | "rows";
+  readonly dataset: DatasetName;
+  readonly outputDims: readonly OutputDim[];
+  readonly measures: readonly string[];
+  readonly wantsEstUsd: boolean;
+  readonly dmUnmasked: boolean;
+  readonly rowColumns: readonly string[];
+  /** aggregate-mode output cap (rows mode caps in SQL). */
+  readonly outputLimit: number;
+  /** rows/spend/audit surface source for domain fold + DM masking. */
+  readonly surfaceColumn: string | null;
+  readonly surfaceParts: readonly string[] | null;
+  /** The column carrying each row's conversation mode, which is what the DM mask routes on
+   *  (OPE-1862). Required on every dataset since OPE-1866 gave `audit` one — see the registry for
+   *  why the type, rather than a comment, is what forbids a dataset that cannot classify. */
+  readonly surfaceModeColumn: string;
+  /** The turn-origin tag column, the mask's legacy fallback for unstamped rows (usage only). */
+  readonly surfaceKindColumn: string | null;
+  /** aggregate-mode output ordering (applied AFTER the host fold); absent → first measure desc. */
+  readonly orderBy?: { readonly by: string; readonly dir: "asc" | "desc" };
+}
+
+export interface CompiledAnalytics {
+  readonly sql: CompiledAnalyticsQuery;
+  readonly plan: AnalyticsPlan;
+}
+
+// --- helpers --------------------------------------------------------------------------------
+
+/** substr length for a ts bucket (ISO-8601 prefix): hour "YYYY-MM-DDThh" (13), day (10), month
+ *  "YYYY-MM" (7). week groups by DAY in SQL (10) and folds to the ISO-week start host-side. */
+function tsSubstrLen(bucket: TsBucket): number {
+  switch (bucket) {
+    case "hour":
+      return 13;
+    case "month":
+      return 7;
+    case "day":
+    case "week":
+      return 10;
+  }
+}
+
+/** The channel keys (`platform/workspace/surface`) an explicit domain covers, from config-as-code.
+ *  The EXACT entries of its reach: a container is unbounded, so no parameter list can stand for it.
+ *  Empty for a pseudo/criteria domain (no reach) → a fail-closed `1=0` scope predicate. */
+function domainChannels(domainName: string, domains: readonly Domain[]): string[] {
+  const d = domains.find((x) => x.name === domainName);
+  return d ? domainRoster(d) : [];
+}
+
+/** A domain-scope conjunct over a channel-key list, dataset-shaped. usage/spend match one
+ *  surface_key column; audit matches the (platform, workspace, surface) triple per channel. Every
+ *  value is a bind param — no key text is concatenated into SQL. An empty list → `1 = 0`. */
+function channelScopeConjunct(spec: DatasetSpec, channels: readonly string[], params: unknown[]): string {
+  if (channels.length === 0) return "1 = 0";
+  if (spec.surfaceColumn) {
+    const placeholders = channels.map(() => "?").join(", ");
+    params.push(...channels);
+    return `${spec.surfaceColumn} IN (${placeholders})`;
+  }
+  // audit: OR of (platform=? AND workspace=? AND surface=?) per channel key.
+  const parts = spec.surfaceParts!;
+  const ors = channels.map((key) => {
+    const seg = key.split("/");
+    // A channel key is platform/workspace/surface; surface may itself contain a "/" — the first two
+    // segments are platform+workspace, the remainder is the surface.
+    const platform = seg[0] ?? "";
+    const workspace = seg[1] ?? "";
+    const surface = seg.slice(2).join("/");
+    params.push(platform, workspace, surface);
+    return `(${parts[0]} = ? AND ${parts[1]} = ? AND ${parts[2]} = ?)`;
+  });
+  return `(${ors.join(" OR ")})`;
+}
+
+/**
+ * The PLATFORM conjunct for a self-scope read (OPE-309 phase 0b) — the namespace half of "the
+ * caller's own rows".
+ *
+ * 🔴 WHY IT EXISTS. `principal_id` is a BARE vendor id in all three tables. `principal_id = ?`
+ * alone therefore matches that spelling on every connected platform at once, so a Discord user
+ * whose snowflake spells the same string as a Slack member id read that person's audit, usage and
+ * spend rows through `scope:"self"` — a live cross-platform read, needing two surfaces rather than
+ * a second workspace. The scope's `platform` comes from the VERIFIED binding, never the model.
+ *
+ * Two shapes, because the datasets store the platform differently: audit has a real `platform`
+ * column (equality); usage/spend carry it as the first segment of `surface_key` (a bound-param
+ * `LIKE '<platform>/%'` prefix — the wildcard is SQL text, the value is a parameter). A dataset
+ * with neither compiles to `1 = 0`: fail-closed, because an unnamespaced self read is the defect.
+ */
+function selfPlatformConjunct(spec: DatasetSpec, platform: string, params: unknown[]): string {
+  if (spec.platformColumn) {
+    params.push(platform);
+    return `${spec.platformColumn} = ?`;
+  }
+  if (spec.surfaceColumn) {
+    params.push(`${platform}/`);
+    return `${spec.surfaceColumn} LIKE (? || '%')`;
+  }
+  return "1 = 0";
+}
+
+// --- the compiler ---------------------------------------------------------------------------
+
+/**
+ * Compile a validated query object under a resolved scope. Throws model-friendly Errors for
+ * scope/grammar violations the zod schema can't express (rows mode a scope can't have, a measure/dim
+ * not on the chosen dataset, spend+self, an over-long window). PURE — no I/O, no ctx.
+ */
+export function compileAnalyticsQuery(input: AnalyticsQuery, scope: AnalyticsScope, domains: readonly Domain[]): CompiledAnalytics {
+  const dataset = input.dataset;
+  const spec = DATASETS[dataset];
+  const mode = input.mode;
+
+  // --- scope/dataset feasibility --------------------------------------------------------------
+  // There is no "this dataset has no per-person column" refusal, because no dataset is in that
+  // shape: `principalColumn` is required and all three set `principal_id`. The refusal that used to
+  // stand here could never print, and its remedy ("use dataset usage") named the dataset the caller
+  // was already allowed to read. The census in analytics-compile-test.ts is what keeps the
+  // invariant — a new dataset without a per-person column reds there.
+  if (mode === "rows" && !scope.rowMode) {
+    throw new Error(`rows mode isn't available at your standing for this scope (aggregates only). Use mode "aggregate", or ask an org/domain admin. (scope=${scope.grain})`);
+  }
+
+  const where: string[] = [];
+  const params: unknown[] = [];
+
+  // 1. SCOPE conjuncts — always first, host-injected from the VERIFIED scope. -------------------
+  where.push("org_id = ?");
+  params.push(scope.org);
+  if (scope.grain === "domain") {
+    where.push(channelScopeConjunct(spec, domainChannels(scope.domain!, domains), params));
+  } else if (scope.grain === "self") {
+    // TWO conjuncts, always: the id AND the namespace it lives in. Splitting them would be the
+    // OPE-309 defect — see selfPlatformConjunct. A scope that names no platform is a HOST bug
+    // (resolveAnalyticsScope reads it off the verified binding), so it throws rather than
+    // compiling a query that reads across platforms.
+    if (!scope.platform) {
+      throw new Error('analytics scope "self" carries no platform — a bare principal id names no namespace, so the read cannot be compiled (access/analytics-scope.ts).');
+    }
+    where.push(`${spec.principalColumn} = ?`);
+    params.push(scope.principalId);
+    where.push(selfPlatformConjunct(spec, scope.platform, params));
+  }
+  // grain "org": org_id alone (whole tenant).
+
+  // 2. Time bounds (audit/usage only — spend is keyed by calendar-month period, not ts). --------
+  const tsCol = Object.values(spec.dims).find((d) => d.kind === "ts")?.kind === "ts" ? (spec.dims.ts as { column: string } | undefined)?.column : undefined;
+  if (tsCol) {
+    if (input.since !== undefined && input.until !== undefined) {
+      const spanMs = Date.parse(input.until) - Date.parse(input.since);
+      if (Number.isFinite(spanMs) && spanMs > MAX_WINDOW_DAYS * 86_400_000) {
+        throw new Error(`the query window exceeds the ${MAX_WINDOW_DAYS}-day maximum — narrow "since"/"until".`);
+      }
+    }
+    if (input.since !== undefined) {
+      where.push(`${tsCol} >= ?`);
+      params.push(input.since);
+    }
+    if (input.until !== undefined) {
+      where.push(`${tsCol} <= ?`);
+      params.push(input.until);
+    }
+  }
+
+  // 3. Model filters — each a further conjunct; values are bind params only. --------------------
+  for (const f of input.filters ?? []) {
+    const dim = spec.dims[f.dim];
+    if (!dim) throw new Error(`filter dimension "${f.dim}" isn't available on dataset "${dataset}" (valid: ${Object.keys(spec.dims).join(", ")}).`);
+    if (dim.kind === "domain") {
+      // A domain filter narrows to that domain's channels (a bound-param scope-shaped conjunct).
+      const names = Array.isArray(f.value) ? f.value : [f.value];
+      const chans = names.flatMap((n) => domainChannels(n, domains));
+      where.push(channelScopeConjunct(spec, chans, params));
+      continue;
+    }
+    const col = dim.column!;
+    if (f.op === "eq") {
+      const v = Array.isArray(f.value) ? f.value[0] : f.value;
+      where.push(`${col} = ?`);
+      params.push(v);
+    } else if (f.op === "in") {
+      const vals = Array.isArray(f.value) ? f.value : [f.value];
+      if (vals.length === 0) {
+        where.push("1 = 0");
+      } else {
+        where.push(`${col} IN (${vals.map(() => "?").join(", ")})`);
+        params.push(...vals);
+      }
+    } else {
+      // prefix — LIKE (? || '%'): the prefix is a bind param; the wildcard is SQL text, not a value.
+      const v = Array.isArray(f.value) ? f.value[0] : f.value;
+      where.push(`${col} LIKE (? || '%')`);
+      params.push(v);
+    }
+  }
+
+  // 4. SELECT / GROUP BY ------------------------------------------------------------------------
+  if (mode === "rows") {
+    const cols = [...spec.rowColumns];
+    if (dataset === "audit" && scope.auditDetail) cols.push("detail"); // org-admin only (compile-time gate)
+    const select = cols.map((c) => ({ expr: c, alias: c }));
+    return {
+      sql: {
+        table: spec.table,
+        select,
+        groupBy: [],
+        where,
+        params,
+        orderBy: { expr: spec.rowOrderColumn, dir: "DESC" },
+        limit: Math.min(input.limit ?? ROWS_LIMIT_MAX, ROWS_LIMIT_MAX),
+      },
+      plan: {
+        mode,
+        dataset,
+        outputDims: [],
+        measures: [],
+        wantsEstUsd: false,
+        dmUnmasked: scope.dmUnmasked,
+        rowColumns: cols,
+        outputLimit: Math.min(input.limit ?? ROWS_LIMIT_MAX, ROWS_LIMIT_MAX),
+        surfaceColumn: spec.surfaceColumn,
+        surfaceParts: spec.surfaceParts,
+        surfaceModeColumn: spec.surfaceModeColumn,
+        surfaceKindColumn: spec.surfaceKindColumn,
+      },
+    };
+  }
+
+  // aggregate mode
+  const groupDims = input.groupBy ?? [];
+  const measures = input.select && input.select.length > 0 ? input.select : [Object.keys(spec.measures)[0]!];
+  for (const m of measures) {
+    if (!spec.measures[m]) throw new Error(`measure "${m}" isn't available on dataset "${dataset}" (valid: ${Object.keys(spec.measures).join(", ")}).`);
+  }
+  for (const g of groupDims) {
+    if (!spec.dims[g]) throw new Error(`dimension "${g}" isn't available on dataset "${dataset}" (valid: ${Object.keys(spec.dims).join(", ")}).`);
+  }
+
+  const tsBucket: TsBucket = input.tsBucket ?? "day";
+  const wantsEstUsd = measures.includes("est_usd");
+
+  // SQL group set: the columns/exprs we group by in SQL (finest grain). Map dims → SQL columns;
+  // `domain` → its surface source column(s); `ts` → substr bucket. `model` is forced in when est_usd
+  // is asked (so each SQL row has one model to price), even if the output doesn't group by it.
+  const sqlGroup: { expr: string; alias: string }[] = [];
+  const outputDims: OutputDim[] = [];
+  const seen = new Set<string>();
+  const addGroup = (expr: string, alias: string) => {
+    if (seen.has(alias)) return;
+    seen.add(alias);
+    sqlGroup.push({ expr, alias });
+  };
+
+  for (const g of groupDims) {
+    const dim = spec.dims[g];
+    if (dim.kind === "column") {
+      addGroup(dim.column, dim.column);
+      outputDims.push({ name: g, kind: "column", column: dim.column });
+    } else if (dim.kind === "ts") {
+      addGroup(`substr(${dim.column}, 1, ${tsSubstrLen(tsBucket)})`, "ts");
+      outputDims.push({ name: g, kind: "ts", column: dim.column, tsBucket });
+    } else {
+      // domain — group SQL by the surface source; fold to a domain name host-side.
+      if (spec.surfaceColumn) addGroup(spec.surfaceColumn, spec.surfaceColumn);
+      else for (const p of spec.surfaceParts!) addGroup(p, p);
+      outputDims.push({ name: g, kind: "domain", column: spec.surfaceColumn ?? undefined });
+    }
+  }
+  if (wantsEstUsd && spec.dims.model?.kind === "column") addGroup((spec.dims.model as { column: string }).column, "model");
+  // 🔴 OPE-1862 — THE MASK'S INPUT IS FORCED INTO THE GROUPING, exactly as `model` is forced in for
+  // est_usd above. A `surface` output dim is masked host-side, and the mask reads the row's
+  // conversation mode; without this column in the GROUP BY the aggregate arrives with no mode at
+  // all, every group reads as unclassified, and the answer collapses to one masked bucket. Added
+  // only when `surface` is actually grouped — no other dimension publishes a surface key.
+  if (groupDims.includes("surface")) addGroup(spec.surfaceModeColumn, spec.surfaceModeColumn);
+  // 🔴 AND THE LEGACY `kind` COLUMN IS DELIBERATELY *NOT* FORCED IN BESIDE IT. It would let a
+  // pre-OPE-1862 usage row classify here exactly as it does in `usage_report` — but forcing a
+  // column into the GROUP BY SPLITS each SQL group, and the host fold ADDS every `kind: "sql"`
+  // measure across those splits. `sessions` is `COUNT(DISTINCT session_id)`, and one session
+  // writes rows under several origin tags (a delegated child files under its parent's session id;
+  // a sandbox row shares it), so a surface with one session that also ran a sandbox would report
+  // TWO. A wrong session count is a worse defect than the narrower masking, and the masking errs
+  // CLOSED: an unstamped usage row folds as unclassified in aggregate mode. `surface_mode` above
+  // is safe to force because a surface's mode is a property of the surface, so it cannot split a
+  // session's rows once they are stamped. Rows mode still reads `kind` — it never re-aggregates.
+
+  // SQL measures: the sql-kind measures requested, plus the token sums est_usd needs to price.
+  const sqlMeasureNames = new Set(measures.filter((m) => spec.measures[m]?.kind === "sql"));
+  if (wantsEstUsd) for (const t of ["input_tokens", "output_tokens", "cache_read_tokens"]) if (spec.measures[t]) sqlMeasureNames.add(t);
+  const sqlMeasures = [...sqlMeasureNames].map((m) => ({ expr: (spec.measures[m] as { expr: string }).expr, alias: m }));
+
+  const select = [...sqlGroup, ...sqlMeasures];
+  return {
+    sql: {
+      table: spec.table,
+      select,
+      groupBy: sqlGroup.map((g) => g.expr),
+      where,
+      params,
+      orderBy: null, // aggregate results are sorted host-side AFTER the domain/week fold
+      limit: AGGREGATE_SCAN_CAP,
+    },
+    plan: {
+      mode,
+      dataset,
+      outputDims,
+      measures,
+      wantsEstUsd,
+      dmUnmasked: scope.dmUnmasked,
+      rowColumns: spec.rowColumns,
+      outputLimit: Math.min(input.limit ?? AGGREGATE_LIMIT_MAX, AGGREGATE_LIMIT_MAX),
+      surfaceColumn: spec.surfaceColumn,
+      surfaceParts: spec.surfaceParts,
+      surfaceModeColumn: spec.surfaceModeColumn,
+      surfaceKindColumn: spec.surfaceKindColumn,
+      ...(input.orderBy ? { orderBy: input.orderBy } : {}),
+    },
+  };
+}
+
+// --- SQL assembly (shared by both store adapters; keeps raw SQL parameterized + tested once) ----
+
+/**
+ * Render a CompiledAnalyticsQuery to a single parameterized SQL string. `style` picks the
+ * placeholder syntax: "qmark" (SQLite `?`) or "dollar" (Postgres `$1..$n`). Every non-param token
+ * is registry-derived (safe); `limit` is a host-clamped integer inlined as a literal.
+ */
+export function assembleAnalyticsSql(q: CompiledAnalyticsQuery, style: "qmark" | "dollar"): { sql: string; params: unknown[] } {
+  const selectSql = q.select.map((s) => `${s.expr} AS ${s.alias}`).join(", ");
+  const whereSql = q.where.length ? `WHERE ${q.where.join(" AND ")}` : "";
+  const groupSql = q.groupBy.length ? `GROUP BY ${q.groupBy.join(", ")}` : "";
+  const orderSql = q.orderBy ? `ORDER BY ${q.orderBy.expr} ${q.orderBy.dir}` : "";
+  const limit = Math.max(0, Math.trunc(q.limit)); // defensive: always a bounded integer literal
+  let sql = `SELECT ${selectSql} FROM ${q.table} ${whereSql} ${groupSql} ${orderSql} LIMIT ${limit}`.replace(/\s+/g, " ").trim();
+  if (style === "dollar") {
+    let i = 0;
+    sql = sql.replace(/\?/g, () => `$${++i}`);
+  }
+  return { sql, params: [...q.params] };
+}
+
+// --- domain fold + ISO week (host-side coarsening the SQL layer can't do) --------------------
+
+/** The Monday (UTC) that starts the ISO week containing a "YYYY-MM-DD" day, as "YYYY-MM-DD". */
+export function isoWeekStart(day: string): string {
+  const d = new Date(`${day}T00:00:00Z`);
+  if (Number.isNaN(d.getTime())) return day;
+  const dow = (d.getUTCDay() + 6) % 7; // Mon=0 … Sun=6
+  d.setUTCDate(d.getUTCDate() - dow);
+  return d.toISOString().slice(0, 10);
+}
+
+/** The domain a raw aggregate row belongs to, for a `domain` output dim: the explicit domain its
+ *  reconstructed channel key matches, else the `org` pseudo-domain fallback (served at org grain).
+ *  Reuses memory/domain.ts — the SAME channel→domain map the rest of the system uses. */
+export function domainOfRow(row: Record<string, unknown>, plan: AnalyticsPlan, domains: readonly Domain[]): string {
+  let key: string | undefined;
+  if (plan.surfaceColumn) {
+    const v = row[plan.surfaceColumn];
+    key = typeof v === "string" ? v : undefined;
+  } else if (plan.surfaceParts) {
+    const parts = plan.surfaceParts.map((p) => String(row[p] ?? ""));
+    key = parts.join("/");
+  }
+  if (!key) return "(unassigned)";
+  const explicit = domainForChannel(key, domains);
+  if (explicit) return explicit.name;
+  return criteriaDomain("org", domains)?.name ?? "(unassigned)";
+}

package/agent/analytics/execute.ts

@@ -0,0 +1,166 @@
+// ANALYTICS EXECUTE (OPE-66) — the host-side post-processing the SQL layer can't express: fold to
+// the requested output grain (computing the `domain` dimension and the ISO `week` bucket), price
+// the derived `est_usd` measure (spend/reporting.ts's honest per-row estimate), DM-mask surfaces
+// (the 2026-07-05 anti-doxxing rule), sort, and cap. PURE over injected deps (store + domains +
+// pricing) so the differential-oracle test can drive it directly on either engine.
+//
+// Aggregate mode: the SQL query already grouped at the finest grain (real columns + a ts substr +
+// the surface behind `domain` + `model` when est_usd is asked). This RE-AGGREGATES those raw groups
+// into the caller's requested output dims — the same host-side re-grouping spend_report does — so a
+// coarser output grain (by domain, by week, dropping the est_usd model split) sums correctly.
+
+import type { OperationalStore } from "../operational/store.js";
+import type { Domain } from "../memory/domain.js";
+import { type AnalyticsPlan, type CompiledAnalytics, domainOfRow, isoWeekStart } from "./compile.js";
+import { DATASETS, type DatasetName } from "./registry.js";
+import { rowCostUsd, type AssumedModelPricing } from "../spend/reporting.js";
+import { maskSurfaceKey, surfaceDisclosureOf } from "../spend/dm-mask.js";
+
+export interface AnalyticsResult {
+  readonly mode: "aggregate" | "rows";
+  readonly dataset: string;
+  /** aggregate: one object per output group ({...dims, ...measures}); rows: one per raw row. */
+  readonly rows: readonly Record<string, unknown>[];
+  readonly rowCount: number;
+  /** true when the SQL scan or the output cap dropped rows — the answer is a prefix, not complete. */
+  readonly truncated: boolean;
+}
+
+export interface AnalyticsExecuteDeps {
+  readonly store: Pick<OperationalStore, "runAnalyticsQuery">;
+  readonly domains: readonly Domain[];
+  readonly assumed: AssumedModelPricing;
+}
+
+/**
+ * Is this measure one the SQL layer summed (and therefore one the host-side re-fold must add up)?
+ *
+ * 🔴 READ FROM THE REGISTRY, NOT FROM A LIST HERE. This used to be a hand-maintained
+ * `NUMERIC_MEASURE` set — and it had already drifted: it named the usage dataset's eight measures
+ * and NOT the spend dataset's `usd`, so `query_analytics dataset:"spend" select:["usd"]` initialised
+ * the accumulator to 0 and then never added anything to it, reporting **$0.00 of spend** for every
+ * query, silently, since the spend dataset shipped. A closed allowlist parallel to the registry is
+ * exactly the drift the registry's own header says it exists to prevent, so the predicate now
+ * derives from the one definition: every `kind: "sql"` measure is summable, `est_usd` (the only
+ * `kind: "est_usd"` one) is priced host-side just below. A new measure is now numeric BY DEFAULT —
+ * the failure mode flips from "silently zero" to "obviously wrong if it isn't a number", which is
+ * the right direction for a money figure. (Found while adding OPE-369's `usd_measured`.)
+ */
+function isSummableMeasure(dataset: string, measure: string): boolean {
+  return DATASETS[dataset as DatasetName]?.measures[measure]?.kind === "sql";
+}
+
+/**
+ * Mask a surface value for the room's benefit, unless the scope may see DMs unbucketed.
+ *
+ * 🔴 ONE ROAD, AND NOW NO EXCEPTION (OPE-1862, OPE-1866): EVERY dataset — `audit` included — is
+ * classified by the CONVERSATION MODE its own row carries (`spend/dm-mask.ts`, the same decision
+ * `spend_report` and `usage_report` take), so a Discord or Teams DM masks exactly as a Slack one
+ * does, and a row nothing stamped masks too. `audit` was the last holdout: it carried no mode, so
+ * the mask fell back to the SLACK DM id shape against a bare surface id, and only Slack's audit
+ * DMs were covered. `audit_entry.surface_mode` closed that, the fallback is deleted, and NO id
+ * shape is read anywhere in this file. Nothing may reintroduce one — a report that has to guess
+ * what a surface id means has already failed.
+ */
+function maskSurface(value: unknown, row: Record<string, unknown>, plan: AnalyticsPlan, dmUnmasked: boolean): unknown {
+  if (dmUnmasked || typeof value !== "string") return value;
+  const mode = row[plan.surfaceModeColumn];
+  const kind = plan.surfaceKindColumn ? row[plan.surfaceKindColumn] : undefined;
+  return maskSurfaceKey(
+    value,
+    surfaceDisclosureOf({
+      surfaceKey: value,
+      ...(typeof mode === "string" ? { surfaceMode: mode } : {}),
+      ...(typeof kind === "string" ? { kind } : {}),
+    }),
+  );
+}
+
+/** Coerce a SQL scalar to a finite number (Postgres returns bigint sums as strings). */
+function num(v: unknown): number {
+  const n = typeof v === "number" ? v : Number(v);
+  return Number.isFinite(n) ? n : 0;
+}
+
+export async function executeAnalytics(compiled: CompiledAnalytics, deps: AnalyticsExecuteDeps): Promise<AnalyticsResult> {
+  const { sql, plan } = compiled;
+  const raw = await deps.store.runAnalyticsQuery(sql);
+
+  if (plan.mode === "rows") {
+    const rows = raw.slice(0, plan.outputLimit).map((r) => shapeRow(r, plan));
+    return { mode: "rows", dataset: plan.dataset, rows, rowCount: rows.length, truncated: raw.length >= plan.outputLimit };
+  }
+
+  // aggregate — fold raw SQL groups into the requested output grain.
+  const groups = new Map<string, Record<string, unknown>>();
+  for (const r of raw) {
+    const dimValues: Record<string, unknown> = {};
+    const keyParts: string[] = [];
+    for (const d of plan.outputDims) {
+      let value: unknown;
+      if (d.kind === "domain") value = domainOfRow(r, plan, deps.domains);
+      else if (d.kind === "ts") value = d.tsBucket === "week" ? isoWeekStart(String(r.ts ?? "")) : r.ts;
+      else value = maskSurface(r[d.column!], r, plan, plan.dmUnmasked || d.name !== "surface");
+      dimValues[d.name] = value ?? null;
+      keyParts.push(`${d.name}=${String(value)}`);
+    }
+    const key = keyParts.join("\u0000");
+    let acc = groups.get(key);
+    if (!acc) {
+      acc = { ...dimValues };
+      for (const m of plan.measures) if (m !== "est_usd") acc[m] = 0;
+      groups.set(key, acc);
+    }
+    for (const m of plan.measures) {
+      if (m === "est_usd") continue;
+      if (isSummableMeasure(plan.dataset, m)) acc[m] = num(acc[m]) + num(r[m]);
+    }
+    if (plan.wantsEstUsd) {
+      // "one-call": `r` is a single dataset row (one model call), priced on its own and then summed
+      // into the group below — never the group's totals priced once. That order is what lets a
+      // long-context tier apply honestly: it fires on the calls that really were long (OPE-2055).
+      const cost = rowCostUsd(
+        { inputTokens: num(r.input_tokens), outputTokens: num(r.output_tokens), cacheReadTokens: num(r.cache_read_tokens), model: typeof r.model === "string" ? r.model : undefined },
+        deps.assumed,
+        "one-call",
+      );
+      if (cost !== undefined) acc.est_usd = num(acc.est_usd) + cost;
+    }
+  }
+
+  let out = [...groups.values()];
+  // Sort: the requested orderBy (a measure or an output dim), else the first numeric measure desc.
+  const sortKey = plan.orderBy?.by ?? plan.measures.find((m) => m !== "est_usd" || plan.wantsEstUsd) ?? plan.measures[0];
+  const dir = plan.orderBy?.dir === "asc" ? 1 : -1;
+  if (sortKey) {
+    out.sort((a, b) => {
+      const av = a[sortKey];
+      const bv = b[sortKey];
+      if (typeof av === "number" && typeof bv === "number") return (av - bv) * dir;
+      return String(av ?? "").localeCompare(String(bv ?? "")) * dir;
+    });
+  }
+  const truncated = raw.length >= sql.limit || out.length > plan.outputLimit;
+  out = out.slice(0, plan.outputLimit);
+  return { mode: "aggregate", dataset: plan.dataset, rows: out, rowCount: out.length, truncated };
+}
+
+/** Shape one raw rows-mode SQL row: keep the dataset's row columns, mask a DM surface, parse the
+ *  audit `detail` JSON (present only when org-admin standing selected it in compile). */
+function shapeRow(r: Record<string, unknown>, plan: AnalyticsPlan): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const c of plan.rowColumns) {
+    let v = r[c];
+    if (v === null || v === undefined) continue;
+    if (c === "surface_key" || c === "surface") v = maskSurface(v, r, plan, plan.dmUnmasked);
+    out[c] = v;
+  }
+  if ("detail" in r && r.detail != null) {
+    try {
+      out.detail = typeof r.detail === "string" ? JSON.parse(r.detail) : r.detail;
+    } catch {
+      out.detail = r.detail;
+    }
+  }
+  return out;
+}