@agent-native/core 0.122.1 → 0.122.3

package/corpus/templates/analytics/app/pages/adhoc/sql-dashboard/report-panel-window.ts

@@ -1,8 +1,8 @@
-import { MAX_CONCURRENT_SQL_QUERIES } from "@shared/sql-query-limits";
-
 import type { SqlPanel } from "./types";
 
-export const REPORT_PANEL_CHUNK_SIZE = MAX_CONCURRENT_SQL_QUERIES;
+// Keep each report window within the browser-side SQL query concurrency limit
+// so a cold window does not serialize into multiple waves before readiness.
+export const REPORT_PANEL_CHUNK_SIZE = 4;
 
 export function listReportablePanelIds(panels: SqlPanel[]): string[] {
   return panels

package/corpus/templates/analytics/changelog/2026-07-25-analytics-dashboards-and-scheduled-reports-are-faster-and-mo.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-07-25
+---
+
+Analytics dashboards and scheduled reports are faster and more reliable with large event histories.

package/corpus/templates/analytics/server/db/schema.ts

@@ -193,6 +193,18 @@ export const bigqueryCache = table("bigquery_cache", {
   expiresAt: text("expires_at").notNull(),
 });
 
+/**
+ * First-party dashboard panel result cache — see
+ * server/lib/first-party-analytics-cache.ts.
+ */
+export const firstPartyAnalyticsCache = table("first_party_analytics_cache", {
+  key: text("key").primaryKey(),
+  sql: text("sql").notNull(),
+  result: text("result").notNull(),
+  createdAt: text("created_at").notNull(),
+  expiresAt: text("expires_at").notNull(),
+});
+
 /**
  * Public write keys for the first-party analytics ingestion endpoint.
  * The key is intentionally public/write-only: it can create events for the

package/corpus/templates/analytics/server/lib/dashboard-panel-query.ts

@@ -446,10 +446,14 @@ export async function runDashboardPanelQuery(args: {
   }
 
   if (source === "first-party") {
-    return await queryFirstPartyAnalytics(query, {
-      userEmail: ctx.userEmail,
-      orgId: ctx.orgId ?? null,
-    });
+    return await queryFirstPartyAnalytics(
+      query,
+      {
+        userEmail: ctx.userEmail,
+        orgId: ctx.orgId ?? null,
+      },
+      { cache: true },
+    );
   }
 
   if (source === "demo") {

package/corpus/templates/analytics/server/lib/dashboard-report.ts

@@ -15,6 +15,8 @@ import {
   EMBED_TOKEN_QUERY_PARAM,
 } from "@agent-native/core/shared";
 
+import { interpolate } from "../../app/pages/adhoc/sql-dashboard/interpolate";
+import { serializePanelSql } from "../../app/pages/adhoc/sql-dashboard/panel-sql";
 import {
   listReportablePanelIds,
   REPORT_PANEL_CHUNK_SIZE,
@@ -32,6 +34,7 @@ import {
   type DashboardReportCaptureOutcome,
   type DashboardReportSubscription,
 } from "./dashboard-report-subscriptions";
+import { queryFirstPartyAnalytics } from "./first-party-analytics.js";
 
 type ReportSnapshot = {
   dashboardId: string;
@@ -42,6 +45,8 @@ type ReportSnapshot = {
   reportSettingsUrl: string;
   generatedAt: string;
   panelIds: string[];
+  panels: SqlDashboardConfig["panels"];
+  variables?: Record<string, string>;
 };
 
 const DATE_FILTER_TYPES: ReadonlySet<FilterType> = new Set([
@@ -58,7 +63,9 @@ const LOCAL_SCREENSHOT_TIMEOUT_MS = 90_000;
 const SERVERLESS_SCREENSHOT_TIMEOUT_MS = 90_000;
 const SERVERLESS_SECOND_READY_TIMEOUT_MS = 45_000;
 // Cap browser work separately from the sweep-level delivery deadline.
-const SERVERLESS_CHUNKED_ATTEMPT_TIMEOUT_MS = 150_000;
+// Reserve time under Netlify's 300s background-function limit for cleanup and
+// email delivery (see MAX_CAPTURE_CLEANUP_RESERVE_MS / delivery reserves below).
+const SERVERLESS_CHUNKED_ATTEMPT_TIMEOUT_MS = 210_000;
 const BROWSER_CLEANUP_TIMEOUT_MS = 10_000;
 const DASHBOARD_REPORT_EMAIL_TIMEOUT_MS = 10_000;
 const DASHBOARD_REPORT_EMAIL_OVERHEAD_RESERVE_MS = 5_000;
@@ -226,6 +233,8 @@ async function collectReportSnapshot(
     }),
     generatedAt: new Date().toISOString(),
     panelIds: listReportablePanelIds(config.panels),
+    panels: config.panels,
+    variables: config.variables,
   };
 }
 
@@ -375,6 +384,14 @@ function boundedStageTimeout(capMs: number, deadlineAt?: number): number {
   return Math.max(1, Math.min(capMs, remainingMs));
 }
 
+function reportDeliveryReserveMs(recipientCount: number): number {
+  return (
+    MAX_CAPTURE_CLEANUP_RESERVE_MS +
+    recipientCount * DASHBOARD_REPORT_EMAIL_TIMEOUT_MS +
+    DASHBOARD_REPORT_EMAIL_OVERHEAD_RESERVE_MS
+  );
+}
+
 async function runWithinCaptureDeadline<T>(
   operation: () => Promise<T>,
   deadlineAt?: number,
@@ -448,7 +465,15 @@ async function waitForDashboardReportReady(
         if (root.getAttribute("data-dashboard-report-ready") !== "true") {
           return false;
         }
-        return !root.querySelector("[data-dashboard-report-loading='true']");
+        if (root.querySelector("[data-dashboard-report-loading='true']")) {
+          return false;
+        }
+        // A panel that errored (including its own query-call timeout) clears
+        // its loading marker just like a successful panel, so without this
+        // check the capture would treat a broken panel as "ready" and bake
+        // its raw error text into the delivered screenshot instead of
+        // failing the attempt so the retry sweep can pick it up.
+        return !root.querySelector("[role='alert']");
       })()`,
       undefined,
       { timeout },
@@ -505,6 +530,101 @@ async function waitForDashboardReportReady(
   }
 }
 
+const PREWARM_CONCURRENCY = 3;
+const PREWARM_PANEL_TIMEOUT_MS = 20_000;
+const PREWARM_MAX_BUDGET_MS = 45_000;
+
+/**
+ * Runs first-party panel queries once, directly, before the browser capture
+ * starts, so the capture's own query-dashboard-panel calls hit a warm cache
+ * instead of several panels racing each other cold for database time inside
+ * a single capture window — that contention, not any one query alone, is
+ * what was pushing panels past their capture timeout. Best-effort: a panel
+ * that fails or times out here is simply computed cold by the capture later,
+ * exactly as it always was, so this can never make a report worse than
+ * before it existed. Bounded to time left after reserving the full chunked
+ * capture attempt and delivery tail, so prewarming cannot starve capture.
+ * The per-panel timeout only bounds how long a worker waits before logging;
+ * it is also passed to the database/cache layers, and the original query is
+ * still awaited before this function returns so it cannot overlap capture.
+ */
+async function prewarmFirstPartyPanelCache(
+  sub: DashboardReportSubscription,
+  snapshot: ReportSnapshot,
+  deadlineAt?: number,
+  recipientCount = 0,
+): Promise<void> {
+  const panels = (snapshot.panels ?? []).filter(
+    (panel) => panel.source === "first-party" && panel.sql != null,
+  );
+  if (!panels.length) return;
+
+  const remaining = deadlineAt ? deadlineAt - Date.now() : Infinity;
+  const budgetMs = Math.max(
+    0,
+    Math.min(
+      PREWARM_MAX_BUDGET_MS,
+      deadlineAt
+        ? remaining -
+            SERVERLESS_CHUNKED_ATTEMPT_TIMEOUT_MS -
+            reportDeliveryReserveMs(recipientCount)
+        : PREWARM_MAX_BUDGET_MS,
+    ),
+  );
+  if (budgetMs <= 0) return;
+  const prewarmDeadline = Date.now() + budgetMs;
+
+  const vars: Record<string, string> = { ...snapshot.variables };
+  for (const [key, value] of Object.entries(snapshot.filters)) {
+    if (key.startsWith("f_")) vars[key.slice(2)] = value;
+  }
+  const scope = { userEmail: sub.ownerEmail, orgId: sub.orgId ?? null };
+
+  let index = 0;
+  async function worker(): Promise<void> {
+    while (index < panels.length && Date.now() < prewarmDeadline) {
+      const panel = panels[index++];
+      const sql = interpolate(serializePanelSql(panel.sql), vars, {
+        failClosedTimeVariables: true,
+      });
+      if (!sql.trim()) continue;
+      const panelTimeoutMs = Math.max(
+        1,
+        Math.min(PREWARM_PANEL_TIMEOUT_MS, prewarmDeadline - Date.now()),
+      );
+      const query = queryFirstPartyAnalytics(sql, scope, {
+        cache: true,
+        timeoutMs: panelTimeoutMs,
+      });
+      let timeout: ReturnType<typeof setTimeout> | undefined;
+      try {
+        await Promise.race([
+          query,
+          new Promise<never>((_, reject) => {
+            timeout = setTimeout(
+              () => reject(new Error("prewarm panel timeout")),
+              panelTimeoutMs,
+            );
+            timeout.unref?.();
+          }),
+        ]);
+      } catch (err) {
+        console.warn(
+          `[dashboard-report] prewarm failed for panel ${panel.id}:`,
+          err instanceof Error ? err.message : err,
+        );
+      } finally {
+        if (timeout) clearTimeout(timeout);
+        await query.catch(() => undefined);
+      }
+    }
+  }
+
+  await Promise.all(
+    Array.from({ length: PREWARM_CONCURRENCY }, () => worker()),
+  );
+}
+
 async function assertDashboardReportPanelWindow(
   page: any,
   expectedPanelIds: string[],
@@ -1358,14 +1478,25 @@ export async function sendDashboardReportSubscription(
     () => collectReportSnapshot(sub),
     options.deadlineAt,
   );
+  try {
+    await prewarmFirstPartyPanelCache(
+      sub,
+      snapshot,
+      options.deadlineAt,
+      recipients.length,
+    );
+  } catch (err) {
+    console.warn(
+      "[dashboard-report] panel cache prewarm failed (non-fatal):",
+      err instanceof Error ? err.message : err,
+    );
+  }
   const captureTimeoutMs = options.deadlineAt
     ? Math.min(
         SERVERLESS_CHUNKED_ATTEMPT_TIMEOUT_MS,
         options.deadlineAt -
           Date.now() -
-          MAX_CAPTURE_CLEANUP_RESERVE_MS -
-          recipients.length * DASHBOARD_REPORT_EMAIL_TIMEOUT_MS -
-          DASHBOARD_REPORT_EMAIL_OVERHEAD_RESERVE_MS,
+          reportDeliveryReserveMs(recipients.length),
       )
     : undefined;
   const capture = await captureDashboardPngWithFallback(

package/corpus/templates/analytics/server/lib/dashboard-time-scope.ts

@@ -14,7 +14,7 @@ type DashboardFilterLike = {
   default?: unknown;
 };
 
-type DashboardPanelLike = {
+export type DashboardPanelLike = {
   id?: unknown;
   title?: unknown;
   chartType?: unknown;
@@ -64,6 +64,241 @@ function hasExplicitLowerBound(sql: string): boolean {
   );
 }
 
+const ANALYTICS_SCAN_RE = /\b(?:FROM|JOIN)\s+analytics_events\b/gi;
+const TOP_LEVEL_CTE_HEAD_RE = /^\s*WITH\b/i;
+const CTE_NAME_RE =
+  /^\s*((?:[A-Za-z_]\w*|"(?:[^"]|"")*"|`(?:[^`]|``)*`|\[(?:[^\]]|\]\])*\]))\s*(?:\([^)]*\)\s*)?AS\s*(?:(?:NOT\s+)?MATERIALIZED\s*)?\(/i;
+
+type TopLevelCte = { name: string; bodyStart: number; bodyEnd: number };
+
+type TopLevelCteParse = {
+  ctes: TopLevelCte[];
+  outerQueryStart: number;
+};
+
+function findClosingParenthesis(sql: string, bodyStart: number): number {
+  let depth = 1;
+  let quote: "'" | '"' | "`" | null = null;
+  let lineComment = false;
+  let blockComment = false;
+
+  for (let i = bodyStart; i < sql.length; i += 1) {
+    const char = sql[i];
+    const next = sql[i + 1];
+
+    if (lineComment) {
+      if (char === "\n") lineComment = false;
+      continue;
+    }
+    if (blockComment) {
+      if (char === "*" && next === "/") {
+        blockComment = false;
+        i += 1;
+      }
+      continue;
+    }
+    if (quote) {
+      if (char === quote) {
+        if (next === quote) {
+          i += 1;
+        } else {
+          quote = null;
+        }
+      }
+      continue;
+    }
+    if (char === "-" && next === "-") {
+      lineComment = true;
+      i += 1;
+      continue;
+    }
+    if (char === "/" && next === "*") {
+      blockComment = true;
+      i += 1;
+      continue;
+    }
+    if (char === "'" || char === '"' || char === "`") {
+      quote = char;
+      continue;
+    }
+    if (char === "(") depth += 1;
+    else if (char === ")") {
+      depth -= 1;
+      if (depth === 0) return i;
+    }
+  }
+
+  return -1;
+}
+
+function skipSqlTrivia(sql: string, start: number): number {
+  let i = start;
+  while (i < sql.length) {
+    if (/\s/.test(sql[i])) {
+      i += 1;
+      continue;
+    }
+    if (sql[i] === "-" && sql[i + 1] === "-") {
+      i += 2;
+      while (i < sql.length && sql[i] !== "\n") i += 1;
+      continue;
+    }
+    if (sql[i] === "/" && sql[i + 1] === "*") {
+      const end = sql.indexOf("*/", i + 2);
+      if (end === -1) return sql.length;
+      i = end + 2;
+      continue;
+    }
+    break;
+  }
+  return i;
+}
+
+function splitTopLevelUnionBranches(sql: string): string[] {
+  const branches: string[] = [];
+  let start = 0;
+  let depth = 0;
+  let quote: "'" | '"' | "`" | null = null;
+  let lineComment = false;
+  let blockComment = false;
+
+  for (let i = 0; i < sql.length; i += 1) {
+    const char = sql[i];
+    const next = sql[i + 1];
+
+    if (lineComment) {
+      if (char === "\n") lineComment = false;
+      continue;
+    }
+    if (blockComment) {
+      if (char === "*" && next === "/") {
+        blockComment = false;
+        i += 1;
+      }
+      continue;
+    }
+    if (quote) {
+      if (char === quote) {
+        if (next === quote) i += 1;
+        else quote = null;
+      }
+      continue;
+    }
+    if (char === "-" && next === "-") {
+      lineComment = true;
+      i += 1;
+      continue;
+    }
+    if (char === "/" && next === "*") {
+      blockComment = true;
+      i += 1;
+      continue;
+    }
+    if (char === "'" || char === '"' || char === "`") {
+      quote = char;
+      continue;
+    }
+    if (char === "(") {
+      depth += 1;
+      continue;
+    }
+    if (char === ")") {
+      depth = Math.max(0, depth - 1);
+      continue;
+    }
+    if (depth !== 0) continue;
+
+    const union = /^UNION\b/i.exec(sql.slice(i));
+    if (!union) continue;
+    branches.push(sql.slice(start, i));
+    start = skipSqlTrivia(sql, i + union[0].length);
+    const modifier = /^(?:ALL|DISTINCT)\b/i.exec(sql.slice(start));
+    if (modifier) start = skipSqlTrivia(sql, start + modifier[0].length);
+    i = start - 1;
+  }
+
+  branches.push(sql.slice(start));
+  return branches;
+}
+
+/** One top-level `name AS (...)` common-table-expression's body span. */
+function topLevelCtes(sql: string): TopLevelCteParse | null {
+  const sqlStart = skipSqlTrivia(sql, 0);
+  const head = TOP_LEVEL_CTE_HEAD_RE.exec(sql.slice(sqlStart));
+  if (!head) return null;
+  const ctes: TopLevelCte[] = [];
+  let i = skipSqlTrivia(sql, sqlStart + head[0].length);
+  const recursive = /^RECURSIVE\b/i.exec(sql.slice(i));
+  if (recursive) i = skipSqlTrivia(sql, i + recursive[0].length);
+  while (i < sql.length) {
+    const nameMatch = CTE_NAME_RE.exec(sql.slice(i));
+    if (!nameMatch) return null;
+    const name = nameMatch[1];
+    const bodyStart = i + nameMatch[0].length;
+    const bodyEnd = findClosingParenthesis(sql, bodyStart);
+    if (bodyEnd === -1) return null;
+    ctes.push({ name, bodyStart, bodyEnd });
+    const k = skipSqlTrivia(sql, bodyEnd + 1);
+    if (sql[k] === ",") {
+      i = k + 1;
+      continue;
+    }
+    return { ctes, outerQueryStart: k };
+  }
+  return null;
+}
+
+function hasAnyTimeBound(text: string): boolean {
+  // .search() ignores the shared global-flagged regex's lastIndex state,
+  // unlike .test(), which would otherwise give wrong results across calls.
+  return (
+    text.search(TEMPORAL_VARIABLE_RE) !== -1 || hasExplicitLowerBound(text)
+  );
+}
+
+/**
+ * True if every `analytics_events` scan in `sql` has its own time bound.
+ *
+ * `hasExplicitLowerBound`/time-variable checks used to run against the whole
+ * SQL string: a multi-CTE panel with a bound ANYWHERE (e.g. only on the
+ * final SELECT, or only on one of several sibling CTEs) passed validation
+ * even though an earlier, unbounded sibling CTE still did a full-table scan
+ * — the exact shape of several production incidents (2026-07-25 org-wide
+ * audit). This only tightens the check for that specific shape: sibling
+ * top-level CTEs each need their own bound. It deliberately does NOT require
+ * every nested subquery to be independently bounded — a correlated lookup
+ * nested inside an already-bounded outer query (e.g. "has this id EVER
+ * appeared as a referrer") is a legitimate, intentionally all-time pattern,
+ * and over-flagging it would make this check untrustworthy.
+ */
+function everyScanIsBounded(sql: string): boolean {
+  const parsed = topLevelCtes(sql);
+  if (!parsed) {
+    // A WITH query that we cannot parse must fail closed. Falling back to a
+    // whole-query bound lets a bounded sibling hide an unbounded CTE.
+    if (TOP_LEVEL_CTE_HEAD_RE.test(sql.slice(skipSqlTrivia(sql, 0)))) {
+      return false;
+    }
+    return hasAnyTimeBound(sql);
+  }
+  const units = [
+    ...parsed.ctes.map(({ bodyStart, bodyEnd }) =>
+      sql.slice(bodyStart, bodyEnd),
+    ),
+    sql.slice(parsed.outerQueryStart),
+  ];
+  return units.every((unit) =>
+    splitTopLevelUnionBranches(unit).every((branch) => {
+      const scans = branch.match(ANALYTICS_SCAN_RE) ?? [];
+      if (scans.length === 0) return true;
+      // A single lower bound cannot prove that every scan in a join or nested
+      // branch is bounded. Fail closed until the SQL has one scan per branch.
+      if (scans.length > 1) return false;
+      return hasAnyTimeBound(branch);
+    }),
+  );
+}
+
 function hasIntentionalHistoryDescription(
   panel: DashboardPanelLike,
   config: Record<string, unknown>,
@@ -166,5 +401,19 @@ export function validateFirstPartyDashboardTimeScope(
     return `panel[${index}] ${label} reads first-party analytics without a time bound; use {{timeRange}} with a non-empty default filter, or explicitly set config.timeScope to "cohort-history" or "all-time" for intentional history scans`;
   }
 
+  // A bound anywhere in the SQL text (checked above) is not the same as
+  // every CTE/subquery that reads analytics_events having its own bound — a
+  // multi-CTE panel can look bound overall while an earlier CTE still does a
+  // full-table scan. Skip this for "all-time" and "cohort-history": both are
+  // explicit escape hatches, and a cohort-defining CTE (e.g. "first ever
+  // active date per user") is legitimately unbounded by design.
+  if (
+    scope !== "all-time" &&
+    scope !== "cohort-history" &&
+    !everyScanIsBounded(sql)
+  ) {
+    return `panel[${index}] ${label} has at least one analytics_events read (in a CTE or subquery) without its own time bound — a {{timeRange}} reference or literal bound elsewhere in the SQL does not cover it; add a bound to every analytics_events scan, or set config.timeScope to "all-time" for an intentional full-history scan`;
+  }
+
   return null;
 }

package/corpus/templates/analytics/server/lib/first-party-analytics-cache.ts

@@ -0,0 +1,167 @@
+import { createHash } from "crypto";
+
+import { getDbExec } from "@agent-native/core/db";
+
+import type { AnalyticsQueryResult } from "./first-party-analytics.js";
+
+/**
+ * First-party dashboard panel query cache.
+ *
+ * `analytics_events` grows unbounded and several panels (rolling-window and
+ * cohort self-joins) are inherently expensive, so a page with many panels or
+ * a daily report screenshot capturing many panels at once repeatedly
+ * recomputes the same rows under concurrent load — that contention, not any
+ * single query alone, is what was pushing panels past their timeout budget.
+ * This mirrors bigquery.ts's L1 (in-process) + L2 (SQL-backed, shared across
+ * serverless invocations) cache, but keyed per scoped+interpolated SQL text
+ * (which already embeds org_id/owner_email via query args) and with a much
+ * shorter TTL since this is the app's own live data, not an immutable
+ * warehouse result.
+ */
+
+interface L1Entry {
+  result: AnalyticsQueryResult;
+  createdAt: number;
+}
+
+const CACHE_TTL_MS = 5 * 60 * 1000;
+const MAX_L1_ENTRIES = 500;
+
+const l1Cache = new Map<string, L1Entry>();
+// De-dupes identical concurrent cache misses (e.g. the same panel query fired
+// by several viewers, or by the report capture's 4-panel concurrent window)
+// so only one of them actually hits the database.
+const inFlight = new Map<string, Promise<AnalyticsQueryResult>>();
+
+function inFlightKey(key: string, timeoutMs?: number): string {
+  return `${key}:${timeoutMs ?? "unbounded"}`;
+}
+
+export interface FirstPartyCacheOptions {
+  timeoutMs?: number;
+}
+
+export function firstPartyCacheKey(
+  scopedSql: string,
+  args: Array<string | null>,
+): string {
+  return createHash("sha256")
+    .update(`${scopedSql}\n${JSON.stringify(args)}`)
+    .digest("hex");
+}
+
+function getL1(key: string): AnalyticsQueryResult | null {
+  const entry = l1Cache.get(key);
+  if (!entry) return null;
+  if (Date.now() - entry.createdAt > CACHE_TTL_MS) {
+    l1Cache.delete(key);
+    return null;
+  }
+  return entry.result;
+}
+
+function setL1(key: string, result: AnalyticsQueryResult): void {
+  if (l1Cache.size >= MAX_L1_ENTRIES) {
+    const oldest = l1Cache.keys().next().value;
+    if (oldest) l1Cache.delete(oldest);
+  }
+  l1Cache.set(key, { result, createdAt: Date.now() });
+}
+
+async function getL2(
+  key: string,
+  timeoutMs?: number,
+): Promise<AnalyticsQueryResult | null> {
+  try {
+    const db = getDbExec();
+    const nowIso = new Date().toISOString();
+    const { rows } = await db.execute({
+      sql: "SELECT result FROM first_party_analytics_cache WHERE key = ? AND expires_at > ?",
+      args: [key, nowIso],
+      timeoutMs,
+    });
+    if (!rows.length) return null;
+    const raw = (rows[0] as { result: string }).result;
+    return JSON.parse(raw) as AnalyticsQueryResult;
+  } catch (err) {
+    console.warn("[first-party-analytics] L2 cache read failed:", err);
+    return null;
+  }
+}
+
+async function setL2(
+  key: string,
+  sql: string,
+  result: AnalyticsQueryResult,
+  timeoutMs?: number,
+): Promise<void> {
+  try {
+    const db = getDbExec();
+    const now = new Date();
+    const expiresAt = new Date(now.getTime() + CACHE_TTL_MS);
+    const serialized = JSON.stringify(result);
+    // Upsert via delete+insert to stay dialect-agnostic (SQLite/Postgres).
+    await db.execute({
+      sql: "DELETE FROM first_party_analytics_cache WHERE key = ?",
+      args: [key],
+      timeoutMs,
+    });
+    await db.execute({
+      sql: "INSERT INTO first_party_analytics_cache (key, sql, result, created_at, expires_at) VALUES (?, ?, ?, ?, ?)",
+      args: [key, sql, serialized, now.toISOString(), expiresAt.toISOString()],
+      timeoutMs,
+    });
+    // Opportunistically prune expired rows so the table doesn't grow
+    // unbounded — the keyspace is effectively every distinct panel/filter
+    // combination. Run ~1% of the time to avoid thrashing on every write.
+    if (Math.random() < 0.01) {
+      await db.execute({
+        sql: "DELETE FROM first_party_analytics_cache WHERE expires_at <= ?",
+        args: [now.toISOString()],
+        timeoutMs,
+      });
+    }
+  } catch (err) {
+    console.warn("[first-party-analytics] L2 cache write failed:", err);
+  }
+}
+
+/**
+ * Returns a cached result for (key, sql) if fresh, otherwise runs `compute`
+ * exactly once — even under concurrent callers with the same key — and
+ * caches the result.
+ */
+export async function withFirstPartyCache(
+  key: string,
+  sql: string,
+  compute: () => Promise<AnalyticsQueryResult>,
+  options: FirstPartyCacheOptions = {},
+): Promise<AnalyticsQueryResult> {
+  const l1Hit = getL1(key);
+  if (l1Hit) return l1Hit;
+
+  // A report prewarm may have a shorter deadline than a normal panel request;
+  // never let those callers inherit one another's database timeout.
+  const requestKey = inFlightKey(key, options.timeoutMs);
+  const existing = inFlight.get(requestKey);
+  if (existing) return existing;
+
+  // Register the in-flight promise synchronously (before any `await`) so two
+  // callers racing on the same key can't both slip past the check above and
+  // both hit L2/compute.
+  const promise = (async () => {
+    const l2Hit = await getL2(key, options.timeoutMs);
+    if (l2Hit) {
+      setL1(key, l2Hit);
+      return l2Hit;
+    }
+    const result = await compute();
+    setL1(key, result);
+    await setL2(key, sql, result, options.timeoutMs);
+    return result;
+  })().finally(() => {
+    inFlight.delete(requestKey);
+  });
+  inFlight.set(requestKey, promise);
+  return promise;
+}