@agent-native/core 0.141.5 → 0.141.6

package/corpus/templates/analytics/app/pages/DataSources.tsx

@@ -120,11 +120,19 @@ interface GitHubOAuthStatus {
 
 interface FirstPartyAnalyticsHealthResponse {
   status: "healthy" | "monitor" | "recommend_bigquery" | "unavailable";
+  externalBackendRecommendation?: "none" | "connect" | "use" | "unknown";
   metrics: {
     eventCount: number;
     slowQueryCount24h: number;
     maxQueryDurationMs24h: number;
   };
+  externalBackends?: Array<{
+    id: "bigquery" | "amplitude";
+    label: string;
+    role: "warehouse" | "product-analytics";
+    configured: boolean | null;
+    setupLink: string;
+  }>;
   bigQuery: {
     configured: boolean | null;
   };
@@ -1615,23 +1623,25 @@ function FirstPartyAnalyticsCard() {
   });
   const health = rawHealth as FirstPartyAnalyticsHealthResponse | undefined;
   const healthStatus = isHealthError ? "unavailable" : health?.status;
-  const bigQueryConfigured = health?.bigQuery.configured === true;
-  const healthTitleKey =
-    healthStatus === "recommend_bigquery"
-      ? bigQueryConfigured
-        ? "dataSources.bigQueryConnectedTitle"
-        : "dataSources.bigQueryRecommendationTitle"
-      : null;
-  const healthDescriptionKey =
-    healthStatus === "recommend_bigquery"
-      ? bigQueryConfigured
-        ? "dataSources.bigQueryConnectedDescription"
-        : "dataSources.bigQueryRecommendationDescription"
-      : healthStatus === "monitor"
-        ? "dataSources.bigQueryMonitorDescription"
-        : healthStatus === "healthy"
-          ? "dataSources.bigQueryHealthyDescription"
-          : "dataSources.bigQueryHealthUnavailable";
+  const externalBackends = health?.externalBackends ?? [];
+  const externalBackendConfigured = externalBackends.some(
+    (backend) => backend.configured === true,
+  );
+  const recommendsExternalBackend = healthStatus === "recommend_bigquery";
+  const healthTitleKey = recommendsExternalBackend
+    ? externalBackendConfigured
+      ? "analyticsBackend.connectedTitle"
+      : "analyticsBackend.recommendationTitle"
+    : null;
+  const healthDescriptionKey = recommendsExternalBackend
+    ? externalBackendConfigured
+      ? "analyticsBackend.connectedDescription"
+      : "analyticsBackend.recommendationDescription"
+    : healthStatus === "monitor"
+      ? "analyticsBackend.monitorDescription"
+      : healthStatus === "healthy"
+        ? "analyticsBackend.healthyDescription"
+        : "analyticsBackend.unavailableDescription";
 
   const createKey = useActionMutation("create-analytics-public-key", {
     onSuccess: (result: any) => {
@@ -1681,7 +1691,7 @@ function FirstPartyAnalyticsCard() {
             <div className="flex shrink-0 items-center gap-2">
               {isLoading ? (
                 <Skeleton className="h-4 w-20 rounded-full" />
-              ) : healthStatus === "recommend_bigquery" ? (
+              ) : recommendsExternalBackend ? (
                 <span
                   className="flex min-w-0 items-center gap-1.5 text-xs font-medium text-amber-500"
                   title={healthTitleKey ? t(healthTitleKey) : undefined}
@@ -1690,13 +1700,13 @@ function FirstPartyAnalyticsCard() {
                   <span className="max-w-[12rem] truncate">
                     {healthTitleKey
                       ? t(healthTitleKey)
-                      : t("dataSources.bigQueryRecommendationTitle")}
+                      : t("analyticsBackend.recommendationTitle")}
                   </span>
                 </span>
               ) : connected ? (
                 <span className="flex items-center gap-1.5 text-xs text-emerald-500 font-medium whitespace-nowrap">
                   <IconCheck className="h-3.5 w-3.5" />
-                  {t("dataSources.configured")}
+                  {t("analyticsBackend.configured")}
                 </span>
               ) : (
                 <span className="flex items-center gap-1.5 text-xs text-muted-foreground whitespace-nowrap">
@@ -1722,7 +1732,7 @@ function FirstPartyAnalyticsCard() {
             ) : (
               <div
                 className={`rounded-md border p-3 text-xs ${
-                  healthStatus === "recommend_bigquery"
+                  recommendsExternalBackend
                     ? "border-amber-500/30 bg-amber-500/10"
                     : "border-border/50 bg-muted/20"
                 }`}
@@ -1731,7 +1741,7 @@ function FirstPartyAnalyticsCard() {
                   <div className="flex min-w-0 items-start gap-2">
                     <IconAlertCircle
                       className={`mt-px h-3.5 w-3.5 shrink-0 ${
-                        healthStatus === "recommend_bigquery"
+                        recommendsExternalBackend
                           ? "text-amber-500"
                           : "text-muted-foreground"
                       }`}
@@ -1747,15 +1757,41 @@ function FirstPartyAnalyticsCard() {
                       </p>
                     </div>
                   </div>
-                  {healthStatus === "recommend_bigquery" &&
-                  !bigQueryConfigured ? (
-                    <Button asChild size="sm" className="shrink-0 text-xs">
-                      <Link to="/data-sources?source=bigquery">
-                        {t("dataSources.bigQuerySetup")}
-                      </Link>
-                    </Button>
-                  ) : null}
                 </div>
+                {externalBackends.length > 0 && (
+                  <div className="mt-3 border-t border-border/30 pt-3">
+                    <div className="mb-2 text-muted-foreground">
+                      {t("analyticsBackend.options")}
+                    </div>
+                    <div className="flex flex-wrap gap-2">
+                      {externalBackends.map((backend) => {
+                        const statusLabel =
+                          backend.configured === true
+                            ? t("analyticsBackend.configured")
+                            : backend.configured === false
+                              ? t("analyticsBackend.setUp")
+                              : t("dataSources.statusUnknown");
+                        return (
+                          <Button
+                            asChild
+                            key={backend.id}
+                            size="sm"
+                            variant={
+                              backend.configured === true
+                                ? "outline"
+                                : "default"
+                            }
+                            className="text-xs"
+                          >
+                            <Link to={backend.setupLink}>
+                              {backend.label} · {statusLabel}
+                            </Link>
+                          </Button>
+                        );
+                      })}
+                    </div>
+                  </div>
+                )}
                 {health && healthStatus !== "unavailable" && (
                   <div className="mt-3 grid grid-cols-3 gap-2 border-t border-border/30 pt-3">
                     <div>

package/corpus/templates/analytics/changelog/2026-08-05-historical-analytics-rollups-now-repair-automatically-after-.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-08-05
+---
+
+Historical Analytics rollups now repair automatically after an upgrade

package/corpus/templates/analytics/netlify.toml

@@ -34,3 +34,7 @@ timeout = 120
 
 [functions.uptime-monitor-sweep-background]
 timeout = 120
+
+[functions.analytics-rollup-backfill-background]
+timeout = 300
+memory = "2gb"

package/corpus/templates/analytics/scripts/emit-netlify-dashboard-report-cron.ts

@@ -22,6 +22,10 @@ const UPTIME_SCHEDULED_NAME = "uptime-monitor-cron";
 const UPTIME_WORKER_NAME = "uptime-monitor-sweep-background";
 const UPTIME_ROUTE_PATH = "/api/uptime-monitors/run";
 const UPTIME_SCHEDULE = "* * * * *";
+const ROLLUP_SCHEDULED_NAME = "analytics-rollup-backfill-cron";
+const ROLLUP_WORKER_NAME = "analytics-rollup-backfill-background";
+const ROLLUP_ROUTE_PATH = "/api/analytics-rollups/backfill";
+const ROLLUP_SCHEDULE = "*/15 * * * *";
 
 function ensureDir(dir: string) {
   mkdirSync(dir, { recursive: true });
@@ -388,6 +392,105 @@ export const config = {
   writeFileSync(path.join(dest, `${UPTIME_WORKER_NAME}.mjs`), source);
 }
 
+function emitRollupScheduledTrigger(token: string) {
+  const dest = path.join(FUNCTIONS_DIR, ROLLUP_SCHEDULED_NAME);
+  rmSync(dest, { recursive: true, force: true });
+  ensureDir(dest);
+
+  const source = `const WORKER_PATH = "/.netlify/functions/${ROLLUP_WORKER_NAME}";
+const CRON_TOKEN = ${JSON.stringify(token)};
+
+function siteOrigin(request) {
+  const configured = process.env.URL || process.env.DEPLOY_URL;
+  if (configured) return configured;
+  const url = new URL(request.url);
+  return url.origin;
+}
+
+export default async function handler(request) {
+  const url = new URL(WORKER_PATH, siteOrigin(request));
+  const response = await fetch(url.toString(), {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      "x-agent-native-analytics-rollup-cron": CRON_TOKEN,
+    },
+    body: JSON.stringify({ scheduled: true }),
+  });
+
+  if (!response.ok && response.status !== 202) {
+    console.error(
+      "[analytics-rollup-backfill-cron] Background backfill trigger failed:",
+      response.status,
+    );
+  }
+}
+
+export const config = {
+  name: "analytics rollup backfill cron trigger",
+  generator: "agent-native analytics build",
+  schedule: ${JSON.stringify(ROLLUP_SCHEDULE)},
+};
+`;
+
+  writeFileSync(path.join(dest, `${ROLLUP_SCHEDULED_NAME}.mjs`), source);
+}
+
+function emitRollupBackgroundWorker(token: string) {
+  const dest = path.join(FUNCTIONS_DIR, ROLLUP_WORKER_NAME);
+  rmSync(dest, { recursive: true, force: true });
+  cloneServerBundleForFunction(SERVER_DIR, dest);
+  rmSync(path.join(dest, "server.mjs"), { force: true });
+
+  const source = `globalThis.__AGENT_NATIVE_BACKGROUND_RUNTIME__ = true;
+globalThis.__AGENT_NATIVE_ANALYTICS_ROLLUP_BACKFILL_SCHEDULED_RUNTIME__ = true;
+
+const CRON_TOKEN = ${JSON.stringify(token)};
+const ROUTE_PATH = ${JSON.stringify(ROLLUP_ROUTE_PATH)};
+let cachedHandler;
+
+function timingSafeEquals(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i += 1) {
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return diff === 0;
+}
+
+export default async function handler(request, context) {
+  const token = request.headers.get("x-agent-native-analytics-rollup-cron") || "";
+  if (!timingSafeEquals(token, CRON_TOKEN)) {
+    return new Response("Unauthorized", { status: 401 });
+  }
+
+  cachedHandler ??= (await import("./main.mjs")).default;
+  const url = new URL(request.url);
+  url.pathname = ROUTE_PATH;
+  url.search = "";
+
+  const rewritten = new Request(url.toString(), {
+    method: "POST",
+    headers: new Headers({ "content-type": "application/json" }),
+    body: JSON.stringify({ scheduled: true }),
+  });
+
+  return await cachedHandler(rewritten, context);
+}
+
+export const config = {
+  name: "analytics rollup backfill background sweep",
+  generator: "agent-native analytics build",
+  background: true,
+  nodeBundler: "none",
+  includedFiles: ["**"],
+  preferStatic: false,
+};
+`;
+
+  writeFileSync(path.join(dest, `${ROLLUP_WORKER_NAME}.mjs`), source);
+}
+
 function isDirectRun(): boolean {
   const entrypoint = process.argv[1];
   return Boolean(
@@ -407,12 +510,15 @@ function main(): void {
   const token = randomBytes(32).toString("hex");
   const alertToken = randomBytes(32).toString("hex");
   const uptimeToken = randomBytes(32).toString("hex");
+  const rollupToken = randomBytes(32).toString("hex");
   emitScheduledTrigger(token);
   emitBackgroundWorker(token);
   emitAlertScheduledTrigger(alertToken);
   emitAlertBackgroundWorker(alertToken);
   emitUptimeScheduledTrigger(uptimeToken);
   emitUptimeBackgroundWorker(uptimeToken);
+  emitRollupScheduledTrigger(rollupToken);
+  emitRollupBackgroundWorker(rollupToken);
   console.log(
     `[dashboard-report-cron] Emitted Netlify scheduled trigger "${SCHEDULED_NAME}" (${SCHEDULE}) and background worker "${WORKER_NAME}".`,
   );
@@ -422,6 +528,9 @@ function main(): void {
   console.log(
     `[uptime-monitor-cron] Emitted Netlify scheduled trigger "${UPTIME_SCHEDULED_NAME}" (${UPTIME_SCHEDULE}) and background worker "${UPTIME_WORKER_NAME}".`,
   );
+  console.log(
+    `[analytics-rollup-backfill-cron] Emitted Netlify scheduled trigger "${ROLLUP_SCHEDULED_NAME}" (${ROLLUP_SCHEDULE}) and background worker "${ROLLUP_WORKER_NAME}".`,
+  );
 }
 
 if (isDirectRun()) {

package/corpus/templates/analytics/server/jobs/analytics-rollup-backfill.ts

@@ -0,0 +1,342 @@
+import { getDbExec, getDialect, isPostgres } from "@agent-native/core/db";
+
+import { FIRST_PARTY_ANALYTICS_ROLLUP_LOCK_KEY } from "../lib/analytics-rollup-lock";
+
+const BACKFILL_STATE_ID = "historical-v1";
+const BACKFILL_LEASE_MINUTES = 15;
+
+const POSTGRES_BACKFILL_STATEMENTS = [
+  `
+    INSERT INTO analytics_event_daily_rollups (
+      id, tenant_key, owner_email, org_id, event_date, event_name,
+      app, template, event_count
+    )
+    SELECT
+      md5(random()::text || clock_timestamp()::text), tenant_key,
+      MIN(owner_email), MIN(org_id), event_date, event_name, app, template,
+      COUNT(*)::INTEGER
+    FROM (
+      SELECT
+        CASE
+          WHEN org_id IS NOT NULL AND org_id <> '' THEN 'org:' || org_id
+          ELSE 'user:' || owner_email
+        END AS tenant_key,
+        owner_email,
+        org_id,
+        COALESCE(NULLIF(event_date, ''), substr(timestamp, 1, 10)) AS event_date,
+        event_name,
+        COALESCE(app, '') AS app,
+        COALESCE(template, '') AS template
+      FROM analytics_events
+    ) AS historical_events
+    WHERE event_date <> ''
+    GROUP BY tenant_key, event_date, event_name, app, template
+    ON CONFLICT (tenant_key, event_date, event_name, app, template)
+    DO UPDATE SET event_count = GREATEST(
+      analytics_event_daily_rollups.event_count,
+      EXCLUDED.event_count
+    )
+  `,
+  `
+    INSERT INTO analytics_user_days (
+      id, tenant_key, owner_email, org_id, event_date, user_key
+    )
+    SELECT
+      md5(random()::text || clock_timestamp()::text), tenant_key,
+      owner_email, org_id, event_date, user_key
+    FROM (
+      SELECT DISTINCT
+        CASE
+          WHEN org_id IS NOT NULL AND org_id <> '' THEN 'org:' || org_id
+          ELSE 'user:' || owner_email
+        END AS tenant_key,
+        owner_email,
+        org_id,
+        COALESCE(NULLIF(event_date, ''), substr(timestamp, 1, 10)) AS event_date,
+        COALESCE(
+          NULLIF(user_key, ''),
+          NULLIF(user_id, ''),
+          NULLIF(anonymous_id, '')
+        ) AS user_key
+      FROM analytics_events
+      WHERE COALESCE(
+        NULLIF(user_key, ''),
+        NULLIF(user_id, ''),
+        NULLIF(anonymous_id, '')
+      ) IS NOT NULL
+    ) AS historical_user_days
+    WHERE event_date <> '' AND user_key <> ''
+    ON CONFLICT (tenant_key, event_date, user_key) DO NOTHING
+  `,
+] as const;
+
+const SQLITE_BACKFILL_STATEMENTS = [
+  `
+    INSERT INTO analytics_event_daily_rollups (
+      id, tenant_key, owner_email, org_id, event_date, event_name,
+      app, template, event_count
+    )
+    SELECT
+      lower(hex(randomblob(16))), tenant_key, MIN(owner_email), MIN(org_id),
+      event_date, event_name, app, template, COUNT(*)
+    FROM (
+      SELECT
+        CASE
+          WHEN org_id IS NOT NULL AND org_id <> '' THEN 'org:' || org_id
+          ELSE 'user:' || owner_email
+        END AS tenant_key,
+        owner_email,
+        org_id,
+        COALESCE(NULLIF(event_date, ''), substr(timestamp, 1, 10)) AS event_date,
+        event_name,
+        COALESCE(app, '') AS app,
+        COALESCE(template, '') AS template
+      FROM analytics_events
+    ) AS historical_events
+    WHERE event_date <> ''
+    GROUP BY tenant_key, event_date, event_name, app, template
+    ON CONFLICT (tenant_key, event_date, event_name, app, template)
+    DO UPDATE SET event_count = MAX(
+      analytics_event_daily_rollups.event_count,
+      excluded.event_count
+    )
+  `,
+  `
+    INSERT INTO analytics_user_days (
+      id, tenant_key, owner_email, org_id, event_date, user_key
+    )
+    SELECT
+      lower(hex(randomblob(16))), tenant_key, owner_email, org_id,
+      event_date, user_key
+    FROM (
+      SELECT DISTINCT
+        CASE
+          WHEN org_id IS NOT NULL AND org_id <> '' THEN 'org:' || org_id
+          ELSE 'user:' || owner_email
+        END AS tenant_key,
+        owner_email,
+        org_id,
+        COALESCE(NULLIF(event_date, ''), substr(timestamp, 1, 10)) AS event_date,
+        COALESCE(
+          NULLIF(user_key, ''),
+          NULLIF(user_id, ''),
+          NULLIF(anonymous_id, '')
+        ) AS user_key
+      FROM analytics_events
+      WHERE COALESCE(
+        NULLIF(user_key, ''),
+        NULLIF(user_id, ''),
+        NULLIF(anonymous_id, '')
+      ) IS NOT NULL
+    ) AS historical_user_days
+    WHERE event_date <> '' AND user_key <> ''
+    ON CONFLICT (tenant_key, event_date, user_key) DO NOTHING
+  `,
+] as const;
+
+type BackfillStatus =
+  | "completed"
+  | "already-complete"
+  | "skipped-lock"
+  | "already-running";
+
+export interface AnalyticsRollupBackfillResult {
+  status: BackfillStatus;
+  remaining: number;
+}
+
+let running = false;
+
+function nowSql(): string {
+  return isPostgres() ? "now()::text" : "datetime('now')";
+}
+
+function ensureStateSql(): string {
+  return isPostgres()
+    ? `INSERT INTO analytics_rollup_backfill_state (id, status, updated_at)
+       VALUES (?, 'pending', ${nowSql()})
+       ON CONFLICT (id) DO NOTHING`
+    : `INSERT OR IGNORE INTO analytics_rollup_backfill_state
+       (id, status, updated_at)
+       VALUES (?, 'pending', ${nowSql()})`;
+}
+
+function createBackfillLeaseToken(): string {
+  if (typeof globalThis.crypto?.randomUUID === "function") {
+    return globalThis.crypto.randomUUID();
+  }
+  return `analytics-rollup-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+}
+
+function claimStateSql(): string {
+  return `UPDATE analytics_rollup_backfill_state
+          SET status = 'running', lease_token = ?,
+              lease_expires_at = datetime('now', '+${BACKFILL_LEASE_MINUTES} minutes'),
+              updated_at = datetime('now')
+        WHERE id = ?
+          AND (
+            status = 'pending'
+            OR (
+              status = 'running'
+              AND (
+                lease_expires_at IS NULL
+                OR lease_expires_at <= datetime('now')
+              )
+            )
+          )`;
+}
+
+function releaseStateLeaseSql(): string {
+  return `UPDATE analytics_rollup_backfill_state
+             SET status = 'pending', lease_token = NULL,
+                 lease_expires_at = NULL, updated_at = datetime('now')
+           WHERE id = ? AND lease_token = ?`;
+}
+
+async function stateStatus(db: {
+  execute: (query: { sql: string; args: unknown[] }) => Promise<{
+    rows: any[];
+    rowsAffected: number;
+  }>;
+}): Promise<string | null> {
+  const result = await db.execute({
+    sql: "SELECT status FROM analytics_rollup_backfill_state WHERE id = ?",
+    args: [BACKFILL_STATE_ID],
+  });
+  const status = result.rows[0]?.status;
+  return typeof status === "string" ? status : null;
+}
+
+async function completeState(tx: {
+  execute: (query: { sql: string; args: unknown[] }) => Promise<unknown>;
+}): Promise<void> {
+  await tx.execute({
+    sql: `UPDATE analytics_rollup_backfill_state
+          SET status = 'completed', completed_at = ${nowSql()}, updated_at = ${nowSql()}
+        WHERE id = ?`,
+    args: [BACKFILL_STATE_ID],
+  });
+}
+
+async function runBackfillStatements(tx: {
+  execute: (query: string) => Promise<unknown>;
+}): Promise<void> {
+  const statements = isPostgres()
+    ? POSTGRES_BACKFILL_STATEMENTS
+    : SQLITE_BACKFILL_STATEMENTS;
+  for (const statement of statements) await tx.execute(statement);
+}
+
+export async function isHistoricalAnalyticsRollupBackfillComplete(): Promise<boolean> {
+  return (await stateStatus(getDbExec())) === "completed";
+}
+
+async function runTransactionalBackfill(
+  db: ReturnType<typeof getDbExec>,
+): Promise<BackfillStatus> {
+  if (!db.transaction) {
+    throw new Error(
+      "Analytics rollup backfill requires a database transaction",
+    );
+  }
+
+  return db.transaction(async (tx) => {
+    if (isPostgres()) {
+      const lockResult = await tx.execute({
+        sql: "SELECT pg_try_advisory_xact_lock(hashtextextended(?, 0::bigint)) AS acquired",
+        args: [FIRST_PARTY_ANALYTICS_ROLLUP_LOCK_KEY],
+      });
+      const acquired = lockResult.rows[0]?.acquired;
+      if (acquired !== true && acquired !== "t") return "skipped-lock";
+    }
+
+    await tx.execute({ sql: ensureStateSql(), args: [BACKFILL_STATE_ID] });
+    if ((await stateStatus(tx)) === "completed") return "already-complete";
+
+    await runBackfillStatements(tx);
+    await completeState(tx);
+    return "completed";
+  });
+}
+
+async function runD1Backfill(
+  db: ReturnType<typeof getDbExec>,
+): Promise<BackfillStatus> {
+  if (!db.atomicBatch) {
+    throw new Error("D1 Analytics rollup backfill requires an atomic batch");
+  }
+
+  await db.execute({ sql: ensureStateSql(), args: [BACKFILL_STATE_ID] });
+  const leaseToken = createBackfillLeaseToken();
+  const claim = await db.execute({
+    sql: claimStateSql(),
+    args: [leaseToken, BACKFILL_STATE_ID],
+  });
+  if (claim.rowsAffected !== 1) {
+    return (await stateStatus(db)) === "completed"
+      ? "already-complete"
+      : "skipped-lock";
+  }
+
+  try {
+    const results = await db.atomicBatch([
+      ...SQLITE_BACKFILL_STATEMENTS,
+      {
+        sql: `UPDATE analytics_rollup_backfill_state
+                SET status = 'completed', completed_at = ${nowSql()},
+                    lease_token = NULL, lease_expires_at = NULL,
+                    updated_at = ${nowSql()}
+              WHERE id = ? AND status = 'running' AND lease_token = ?`,
+        args: [BACKFILL_STATE_ID, leaseToken],
+      },
+    ]);
+    if (results[results.length - 1]?.rowsAffected !== 1) {
+      throw new Error(
+        "Analytics rollup backfill lost its D1 lease before completion",
+      );
+    }
+    return "completed";
+  } catch (error) {
+    try {
+      await db.execute({
+        sql: releaseStateLeaseSql(),
+        args: [BACKFILL_STATE_ID, leaseToken],
+      });
+    } catch (releaseError) {
+      console.warn(
+        "[analytics-rollup-backfill] Failed to release D1 lease after backfill error:",
+        releaseError instanceof Error ? releaseError.message : releaseError,
+      );
+    }
+    throw error;
+  }
+}
+
+/**
+ * Rebuild historical compact rollups outside the server boot path. The state
+ * row is completed in the same transaction as both aggregates, so a timeout
+ * or failed write leaves the job pending and a later scheduled run retries it.
+ * D1 claims a short lease before its atomic batch so concurrent isolates do not
+ * each scan the full event history.
+ */
+export async function runAnalyticsRollupBackfillOnce(): Promise<AnalyticsRollupBackfillResult> {
+  if (running) {
+    return { status: "already-running", remaining: 1 };
+  }
+  running = true;
+
+  try {
+    const db = getDbExec();
+    const status =
+      getDialect() === "d1"
+        ? await runD1Backfill(db)
+        : await runTransactionalBackfill(db);
+    return {
+      status,
+      remaining:
+        status === "completed" || status === "already-complete" ? 0 : 1,
+    };
+  } finally {
+    running = false;
+  }
+}

package/corpus/templates/analytics/server/lib/analytics-rollup-lock.ts

@@ -0,0 +1,8 @@
+/**
+ * Shared with the historical backfill so live ingest and migration work hold
+ * the same transaction-scoped Postgres lock while they update rollups.
+ */
+export const FIRST_PARTY_ANALYTICS_ROLLUP_LOCK_KEY =
+  "agent-native:analytics-rollup-backfill";
+export const FIRST_PARTY_ANALYTICS_ROLLUP_LOCK_SQL =
+  "SELECT pg_advisory_xact_lock(hashtextextended(?, 0::bigint))";