@agent-native/core 0.145.8 → 0.146.1

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

@@ -0,0 +1,450 @@
+import { randomUUID } from "node:crypto";
+
+import { getDbExec, isPostgres } from "@agent-native/core/db";
+import { runWithRequestContext } from "@agent-native/core/server";
+
+import {
+  backfillFirstPartyAnalyticsBatch,
+  type FirstPartyAnalyticsScope,
+} from "../lib/first-party-analytics-backend.js";
+
+const JOB_TABLE = "analytics_bigquery_backfill_jobs";
+const LEASE_MS = 5 * 60 * 1000;
+const ERROR_RETRY_MS = 5 * 60 * 1000;
+const DEFAULT_BATCH_SIZE = 250;
+const MAX_BATCH_SIZE = 750;
+const DEFAULT_MAX_BATCHES_PER_SWEEP = 2;
+const MAX_BATCHES_PER_SWEEP = 4;
+const DEFAULT_MAX_ACTIVE_SESSIONS = 80;
+const DEFAULT_MAX_TOTAL_SESSIONS = 250;
+
+type Query =
+  | string
+  | {
+      sql: string;
+      args?: unknown[];
+      timeoutMs?: number;
+      maxAttempts?: number;
+    };
+
+interface QueryResult {
+  rows?: unknown[];
+  rowsAffected?: number;
+}
+
+interface Executor {
+  execute(query: Query): Promise<QueryResult>;
+  transaction?<T>(fn: (tx: Executor) => Promise<T>): Promise<T>;
+}
+
+export type BigQueryBackfillJobStatus = "pending" | "running" | "completed";
+
+export interface BigQueryBackfillJob {
+  id: string;
+  orgId: string;
+  ownerEmail: string;
+  table: string;
+  batchSize: number;
+  cursor: string | null;
+  status: BigQueryBackfillJobStatus;
+  copied: number;
+  leaseToken: string | null;
+  leaseExpiresAt: string | null;
+  nextRunAt: string;
+  lastError: string | null;
+  completedAt: string | null;
+  updatedAt: string;
+}
+
+export interface BigQueryBackfillSweepResult {
+  status:
+    | "disabled"
+    | "idle"
+    | "paused-pressure"
+    | "progress"
+    | "completed"
+    | "retry-scheduled";
+  batches: number;
+  copied: number;
+  remaining: number;
+  reason?: string;
+  error?: string;
+}
+
+function executor(): Executor {
+  return getDbExec() as unknown as Executor;
+}
+
+function jobId(orgId: string): string {
+  return `first-party-analytics:${orgId}`;
+}
+
+function boundedBatchSize(value: number | undefined): number {
+  if (!Number.isFinite(value)) return DEFAULT_BATCH_SIZE;
+  return Math.min(Math.max(Math.floor(value as number), 1), MAX_BATCH_SIZE);
+}
+
+function maxBatchesPerSweep(): number {
+  const raw = process.env.ANALYTICS_BIGQUERY_BACKFILL_SWEEP_LIMIT?.trim();
+  if (!raw) return DEFAULT_MAX_BATCHES_PER_SWEEP;
+  const parsed = Number.parseInt(raw, 10);
+  return Number.isFinite(parsed) && parsed > 0
+    ? Math.min(parsed, MAX_BATCHES_PER_SWEEP)
+    : DEFAULT_MAX_BATCHES_PER_SWEEP;
+}
+
+function positiveEnvNumber(name: string, fallback: number): number {
+  const raw = process.env[name]?.trim();
+  if (!raw) return fallback;
+  const parsed = Number.parseInt(raw, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function stringValue(row: Record<string, unknown>, ...keys: string[]): string {
+  for (const key of keys) {
+    const value = row[key];
+    if (typeof value === "string") return value;
+  }
+  return "";
+}
+
+function nullableStringValue(
+  row: Record<string, unknown>,
+  ...keys: string[]
+): string | null {
+  const value = stringValue(row, ...keys);
+  return value || null;
+}
+
+function numberValue(row: Record<string, unknown>, ...keys: string[]): number {
+  for (const key of keys) {
+    const value = row[key];
+    const parsed = typeof value === "number" ? value : Number(value);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return 0;
+}
+
+function rowToJob(row: Record<string, unknown>): BigQueryBackfillJob {
+  const status = stringValue(row, "status");
+  if (status !== "pending" && status !== "running" && status !== "completed") {
+    throw new Error(
+      `Unknown BigQuery backfill job status: ${status || "empty"}`,
+    );
+  }
+  return {
+    id: stringValue(row, "id"),
+    orgId: stringValue(row, "org_id", "orgId"),
+    ownerEmail: stringValue(row, "owner_email", "ownerEmail"),
+    table: stringValue(row, "table_ref", "tableRef"),
+    batchSize: boundedBatchSize(numberValue(row, "batch_size", "batchSize")),
+    cursor: nullableStringValue(row, "backfill_cursor", "backfillCursor"),
+    status,
+    copied: numberValue(row, "copied_count", "copiedCount"),
+    leaseToken: nullableStringValue(row, "lease_token", "leaseToken"),
+    leaseExpiresAt: nullableStringValue(
+      row,
+      "lease_expires_at",
+      "leaseExpiresAt",
+    ),
+    nextRunAt: stringValue(row, "next_run_at", "nextRunAt"),
+    lastError: nullableStringValue(row, "last_error", "lastError"),
+    completedAt: nullableStringValue(row, "completed_at", "completedAt"),
+    updatedAt: stringValue(row, "updated_at", "updatedAt"),
+  };
+}
+
+function rowFromResult(result: QueryResult): Record<string, unknown> | null {
+  const row = result.rows?.[0];
+  return row && typeof row === "object"
+    ? (row as Record<string, unknown>)
+    : null;
+}
+
+export async function getFirstPartyAnalyticsBigQueryBackfillJob(
+  scope: FirstPartyAnalyticsScope,
+): Promise<BigQueryBackfillJob | null> {
+  const result = await executor().execute({
+    sql: `SELECT id, org_id, owner_email, table_ref, batch_size,
+                 backfill_cursor, status, copied_count, lease_token,
+                 lease_expires_at, next_run_at, last_error, completed_at,
+                 updated_at
+            FROM ${JOB_TABLE}
+           WHERE id = ?
+           LIMIT 1`,
+    args: [jobId(scope.orgId ?? "")],
+    timeoutMs: 3_000,
+    maxAttempts: 1,
+  });
+  const row = rowFromResult(result);
+  return row ? rowToJob(row) : null;
+}
+
+export async function queueFirstPartyAnalyticsBigQueryBackfill(
+  scope: FirstPartyAnalyticsScope,
+  table: string,
+  requestedBatchSize?: number,
+  initialCursor?: string | null,
+): Promise<BigQueryBackfillJob> {
+  const now = new Date().toISOString();
+  const id = jobId(scope.orgId ?? "");
+  if (!scope.orgId)
+    throw new Error("BigQuery backfill requires an organization");
+  await executor().execute({
+    sql: `INSERT INTO ${JOB_TABLE} (
+            id, org_id, owner_email, table_ref, batch_size, backfill_cursor,
+              status, copied_count, lease_token, lease_expires_at, next_run_at,
+              last_error, completed_at, updated_at
+            ) VALUES (?, ?, ?, ?, ?, ?, 'pending', 0, NULL, NULL, ?, NULL, NULL, ?)
+            ON CONFLICT (id) DO NOTHING`,
+    args: [
+      id,
+      scope.orgId,
+      scope.userEmail,
+      table,
+      boundedBatchSize(requestedBatchSize),
+      initialCursor ?? null,
+      now,
+      now,
+    ],
+    timeoutMs: 5_000,
+    maxAttempts: 1,
+  });
+  const job = await getFirstPartyAnalyticsBigQueryBackfillJob(scope);
+  if (!job) throw new Error("BigQuery backfill job was not persisted");
+  if (job.table !== table) {
+    throw new Error(
+      `BigQuery backfill already targets ${job.table}; prepare the existing migration before changing tables`,
+    );
+  }
+  return job;
+}
+
+async function claimNextJob(
+  db: Executor,
+  now: string,
+): Promise<BigQueryBackfillJob | null> {
+  if (!db.transaction) {
+    throw new Error("BigQuery backfill requires a database transaction");
+  }
+  const token = randomUUID();
+  const leaseExpiresAt = new Date(Date.now() + LEASE_MS).toISOString();
+  return db.transaction(async (tx) => {
+    const candidateResult = await tx.execute({
+      sql: `SELECT id, org_id, owner_email, table_ref, batch_size,
+                   backfill_cursor, status, copied_count, lease_token,
+                   lease_expires_at, next_run_at, last_error, completed_at,
+                   updated_at
+              FROM ${JOB_TABLE}
+             WHERE next_run_at <= ?
+               AND (
+                 status = 'pending'
+                 OR (status = 'running' AND lease_expires_at IS NOT NULL
+                     AND lease_expires_at <= ?)
+               )
+             ORDER BY updated_at ASC
+             LIMIT 1`,
+      args: [now, now],
+      timeoutMs: 3_000,
+      maxAttempts: 1,
+    });
+    const candidate = rowFromResult(candidateResult);
+    if (!candidate) return null;
+
+    const updated = await tx.execute({
+      sql: `UPDATE ${JOB_TABLE}
+               SET status = 'running', lease_token = ?, lease_expires_at = ?,
+                   updated_at = ?
+             WHERE id = ?
+               AND next_run_at <= ?
+               AND (
+                 status = 'pending'
+                 OR (status = 'running' AND lease_expires_at IS NOT NULL
+                     AND lease_expires_at <= ?)
+               )`,
+      args: [token, leaseExpiresAt, now, candidate.id, now, now],
+      timeoutMs: 3_000,
+      maxAttempts: 1,
+    });
+    if (updated.rowsAffected !== 1) return null;
+    return rowToJob({
+      ...candidate,
+      status: "running",
+      lease_token: token,
+      lease_expires_at: leaseExpiresAt,
+      updated_at: now,
+    });
+  });
+}
+
+async function finishJob(
+  db: Executor,
+  job: BigQueryBackfillJob,
+  result: { nextCursor: string | null; copied: number; complete: boolean },
+  now: string,
+): Promise<void> {
+  const completedAt = result.complete ? now : null;
+  const updated = await db.execute({
+    sql: `UPDATE ${JOB_TABLE}
+             SET status = ?, backfill_cursor = ?, copied_count = copied_count + ?,
+                 lease_token = NULL, lease_expires_at = NULL,
+                 next_run_at = ?, last_error = NULL, completed_at = ?,
+                 updated_at = ?
+           WHERE id = ? AND lease_token = ?`,
+    args: [
+      result.complete ? "completed" : "pending",
+      result.nextCursor,
+      result.copied,
+      now,
+      completedAt,
+      now,
+      job.id,
+      job.leaseToken,
+    ],
+    timeoutMs: 5_000,
+    maxAttempts: 1,
+  });
+  if (updated.rowsAffected !== 1) {
+    throw new Error("BigQuery backfill lost its lease before saving progress");
+  }
+}
+
+async function scheduleRetry(
+  db: Executor,
+  job: BigQueryBackfillJob,
+  error: string,
+  now: string,
+): Promise<void> {
+  const retryAt = new Date(Date.now() + ERROR_RETRY_MS).toISOString();
+  await db.execute({
+    sql: `UPDATE ${JOB_TABLE}
+             SET status = 'pending', lease_token = NULL, lease_expires_at = NULL,
+                 next_run_at = ?, last_error = ?, updated_at = ?
+           WHERE id = ? AND lease_token = ?`,
+    args: [retryAt, error.slice(0, 1_000), now, job.id, job.leaseToken],
+    timeoutMs: 5_000,
+    maxAttempts: 1,
+  });
+}
+
+async function pressureSnapshot(
+  db: Executor,
+): Promise<{ paused: boolean; reason?: string }> {
+  if (!isPostgres()) return { paused: false };
+  try {
+    const result = await db.execute({
+      sql: `SELECT
+              COUNT(*) AS total_sessions,
+              SUM(CASE WHEN state = 'active' THEN 1 ELSE 0 END) AS active_sessions,
+              SUM(CASE WHEN wait_event_type IS NOT NULL THEN 1 ELSE 0 END) AS waiting_sessions,
+              SUM(CASE WHEN wait_event_type = 'Lock' THEN 1 ELSE 0 END) AS lock_waiters
+            FROM pg_stat_activity
+           WHERE pid <> pg_backend_pid()`,
+      timeoutMs: 2_000,
+      maxAttempts: 1,
+    });
+    const row = rowFromResult(result);
+    if (!row) return { paused: true, reason: "pressure probe returned no row" };
+    const total = numberValue(row, "total_sessions");
+    const active = numberValue(row, "active_sessions");
+    const waiting = numberValue(row, "waiting_sessions");
+    const lockWaiters = numberValue(row, "lock_waiters");
+    const maxActive = positiveEnvNumber(
+      "ANALYTICS_BIGQUERY_BACKFILL_MAX_ACTIVE_SESSIONS",
+      DEFAULT_MAX_ACTIVE_SESSIONS,
+    );
+    const maxTotal = positiveEnvNumber(
+      "ANALYTICS_BIGQUERY_BACKFILL_MAX_TOTAL_SESSIONS",
+      DEFAULT_MAX_TOTAL_SESSIONS,
+    );
+    if (lockWaiters > 0 || active >= maxActive || total >= maxTotal) {
+      return {
+        paused: true,
+        reason: `database pressure: total=${total}, active=${active}, waiting=${waiting}, lockWaiters=${lockWaiters}`,
+      };
+    }
+    return { paused: false };
+  } catch (error) {
+    return {
+      paused: true,
+      reason: `pressure probe failed: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+}
+
+export async function runFirstPartyAnalyticsBigQueryBackfillOnce(): Promise<BigQueryBackfillSweepResult> {
+  if (process.env.ANALYTICS_BIGQUERY_BACKFILL_JOBS?.trim() === "0") {
+    return { status: "disabled", batches: 0, copied: 0, remaining: 0 };
+  }
+
+  const db = executor();
+  const initialPressure = await pressureSnapshot(db);
+  if (initialPressure.paused) {
+    return {
+      status: "paused-pressure",
+      batches: 0,
+      copied: 0,
+      remaining: 1,
+      reason: initialPressure.reason,
+    };
+  }
+
+  let batches = 0;
+  let copied = 0;
+  for (let index = 0; index < maxBatchesPerSweep(); index += 1) {
+    const pressure = await pressureSnapshot(db);
+    if (pressure.paused) {
+      return {
+        status: "paused-pressure",
+        batches,
+        copied,
+        remaining: 1,
+        reason: pressure.reason,
+      };
+    }
+
+    const job = await claimNextJob(db, new Date().toISOString());
+    if (!job) {
+      return {
+        status: batches ? "progress" : "idle",
+        batches,
+        copied,
+        remaining: batches ? 1 : 0,
+      };
+    }
+
+    try {
+      const batch = await runWithRequestContext(
+        { userEmail: job.ownerEmail, orgId: job.orgId },
+        () =>
+          backfillFirstPartyAnalyticsBatch(
+            { userEmail: job.ownerEmail, orgId: job.orgId },
+            job.cursor,
+            job.batchSize,
+            job.table,
+          ),
+      );
+      const now = new Date().toISOString();
+      // The lease row is the progress source of truth; the backend setting is
+      // only the migration configuration and cutover marker.
+      await finishJob(db, job, batch, now);
+      batches += 1;
+      copied += batch.copied;
+      if (batch.complete) {
+        return { status: "completed", batches, copied, remaining: 0 };
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      await scheduleRetry(db, job, message, new Date().toISOString());
+      return {
+        status: "retry-scheduled",
+        batches,
+        copied,
+        remaining: 1,
+        error: message,
+      };
+    }
+  }
+
+  return { status: "progress", batches, copied, remaining: 1 };
+}

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

@@ -1,6 +1,6 @@
 import { getDbExec, getDialect, isPostgres } from "@agent-native/core/db";
 
-import { FIRST_PARTY_ANALYTICS_ROLLUP_LOCK_KEY } from "../lib/analytics-rollup-lock";
+import { FIRST_PARTY_ANALYTICS_ROLLUP_BACKFILL_LOCK_KEY } from "../lib/analytics-rollup-lock";
 
 const BACKFILL_STATE_ID = "historical-v1";
 const BACKFILL_LEASE_MINUTES = 15;
@@ -254,7 +254,7 @@ async function runTransactionalBackfill(
       );
       const lockResult = await tx.execute({
         sql: "SELECT pg_try_advisory_xact_lock(hashtextextended(?, 0::bigint)) AS acquired",
-        args: [FIRST_PARTY_ANALYTICS_ROLLUP_LOCK_KEY],
+        args: [FIRST_PARTY_ANALYTICS_ROLLUP_BACKFILL_LOCK_KEY],
       });
       const acquired = lockResult.rows[0]?.acquired;
       if (acquired !== true && acquired !== "t") return "skipped-lock";

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

@@ -1,8 +1,7 @@
 /**
- * Shared with the historical backfill so live ingest and migration work hold
- * the same transaction-scoped Postgres lock while they update rollups.
+ * Prevents concurrent historical backfills. Foreground ingest deliberately
+ * does not take this lock: a rebuild must never make request traffic queue
+ * behind a long-running transaction.
  */
-export const FIRST_PARTY_ANALYTICS_ROLLUP_LOCK_KEY =
+export const FIRST_PARTY_ANALYTICS_ROLLUP_BACKFILL_LOCK_KEY =
   "agent-native:analytics-rollup-backfill";
-export const FIRST_PARTY_ANALYTICS_ROLLUP_LOCK_SQL =
-  "SELECT pg_advisory_xact_lock(hashtextextended(?, 0::bigint))";

package/corpus/templates/analytics/server/lib/dashboard-collab-sync.ts

@@ -0,0 +1,77 @@
+import {
+  applyText,
+  hasCollabState,
+  seedFromText,
+} from "@agent-native/core/collab";
+
+export const DASHBOARD_COLLAB_SYNC_TIMEOUT_MS = 2_000;
+
+class DashboardCollabSyncTimeoutError extends Error {
+  constructor(timeoutMs: number) {
+    super(`timed out after ${timeoutMs}ms`);
+    this.name = "DashboardCollabSyncTimeoutError";
+  }
+}
+
+async function withTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs: number,
+): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise<T>((_, reject) => {
+        timer = setTimeout(
+          () => reject(new DashboardCollabSyncTimeoutError(timeoutMs)),
+          timeoutMs,
+        );
+      }),
+    ]);
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+  }
+}
+
+async function syncDashboardToCollab(
+  dashboardId: string,
+  config: Record<string, unknown>,
+  requestSource?: string,
+): Promise<void> {
+  const docId = `dash-${dashboardId}`;
+  const startedAt = Date.now();
+  try {
+    const configStr = JSON.stringify(config);
+    await withTimeout(
+      (async () => {
+        const exists = await hasCollabState(docId);
+        if (exists) {
+          await applyText(docId, configStr, "content", requestSource);
+        } else {
+          await seedFromText(docId, configStr);
+        }
+      })(),
+      DASHBOARD_COLLAB_SYNC_TIMEOUT_MS,
+    );
+  } catch (error) {
+    const elapsedMs = Date.now() - startedAt;
+    const message = error instanceof Error ? error.message : String(error);
+    const outcome =
+      error instanceof DashboardCollabSyncTimeoutError ? "timed out" : "failed";
+    console.warn(
+      `[analytics] Dashboard collab sync ${outcome} for ${dashboardId} after ${elapsedMs}ms: ${message}`,
+    );
+  }
+}
+
+/**
+ * Queue the live-editor sync after SQL has committed. SQL remains the source
+ * of truth, so a collab lock or unavailable database must not hold a mutation.
+ */
+export function queueDashboardCollabSync(
+  dashboardId: string,
+  config: Record<string, unknown>,
+  requestSource?: string,
+): void {
+  void syncDashboardToCollab(dashboardId, config, requestSource);
+}

package/corpus/templates/analytics/server/lib/demo-dashboards.ts

@@ -1,12 +1,8 @@
 import { createHash } from "node:crypto";
 
-import {
-  applyText,
-  hasCollabState,
-  seedFromText,
-} from "@agent-native/core/collab";
 import { getUserSetting, putUserSetting } from "@agent-native/core/settings";
 
+import { queueDashboardCollabSync } from "./dashboard-collab-sync";
 import { loadDashboardSeed } from "./dashboard-seeds";
 import { getDashboard, upsertDashboard } from "./dashboards-store";
 
@@ -187,23 +183,6 @@ function applyDemoMetadata(
   };
 }
 
-async function syncToCollab(
-  dashboardId: string,
-  config: Record<string, unknown>,
-): Promise<void> {
-  const docId = `dash-${dashboardId}`;
-  const configStr = JSON.stringify(config);
-  try {
-    if (await hasCollabState(docId)) {
-      await applyText(docId, configStr, "content", "agent");
-    } else {
-      await seedFromText(docId, configStr);
-    }
-  } catch {
-    // SQL is the source of truth; collab can seed lazily later.
-  }
-}
-
 async function readDemoState(email: string): Promise<DemoDashboardState> {
   return normalizeState(await getUserSetting(email, DEMO_DASHBOARD_STATE_KEY));
 }
@@ -277,7 +256,7 @@ export async function ensureDemoDashboardsForUser(
       // SQL is the source of truth and collab state can seed lazily. Do not
       // hold first-open installation (and the whole app shell) behind a remote
       // collab read/write that may be slow or temporarily unavailable.
-      void syncToCollab(dashboardId, config);
+      queueDashboardCollabSync(dashboardId, config, "agent");
       archivedAt = row.archivedAt;
       created = !existing;
     }

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

@@ -73,7 +73,7 @@ const FIRST_PARTY_QUERY_TABLES = [
   "analytics_user_days",
 ] as const;
 const BACKEND_CONFIG_CACHE_TTL_MS = 30_000;
-const MAX_BACKFILL_BATCH_SIZE = 5_000;
+const MAX_BACKFILL_BATCH_SIZE = 750;
 const MAX_INSERT_BATCH_SIZE = 200;
 
 const backendConfigCache = new Map<
@@ -1153,9 +1153,15 @@ export async function backfillFirstPartyAnalyticsBatch(
   const hydratedById = new Map(
     hydratedRows.map((row) => [backfillRowCursor(row).id, row]),
   );
-  const selectedEvents = selectedIds
-    .map((id) => hydratedById.get(id))
-    .filter((row): row is Record<string, unknown> => row !== undefined);
+  const selectedEvents = selectedIds.map((id) => {
+    const row = hydratedById.get(id);
+    if (!row) {
+      throw new Error(
+        `First-party analytics backfill row ${id} disappeared before hydration`,
+      );
+    }
+    return row;
+  });
   await insertFirstPartyAnalyticsRows(selectedEvents, configuredTable);
   const lastCursor = backfillRowCursor(selectedRows[selectedRows.length - 1]!);
   return {

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

@@ -1,8 +1,6 @@
-import { isPostgres } from "@agent-native/core/db";
 import { sql } from "@agent-native/core/db/schema";
 
 import { getDb, schema } from "../db/index.js";
-import { FIRST_PARTY_ANALYTICS_ROLLUP_LOCK_KEY } from "./analytics-rollup-lock.js";
 
 /**
  * The normalized subset emitted by first-party analytics ingest. Keeping this
@@ -143,15 +141,10 @@ export async function upsertFirstPartyAnalyticsRollups(
   }
 
   const writeRollups = async (tx: any) => {
-    if (isPostgres()) {
-      // The historical backfill takes this lock before its raw-event
-      // snapshot. Holding it through ingest's rollup increment prevents the
-      // backfill's monotonic upsert from losing a concurrently committed
-      // event.
-      await tx.execute(
-        sql`SELECT pg_advisory_xact_lock(hashtextextended(${FIRST_PARTY_ANALYTICS_ROLLUP_LOCK_KEY}, 0::bigint))`,
-      );
-    }
+    // Do not take the historical backfill advisory lock here. Foreground
+    // ingest must not wait behind a long-running rebuild; the incremental
+    // conflict update and the backfill's GREATEST upsert are both monotonic,
+    // and Postgres serializes the conflicting row updates itself.
     const dailyRows = [...dailyRollups.values()];
     await tx
       .insert(schema.analyticsEventDailyRollups)

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

@@ -29,20 +29,17 @@ function intervalMs(): number {
 }
 
 export default function registerAnalyticsRollupBackfillJobs(): void {
-  const isProd = process.env.NODE_ENV === "production";
   const flag =
     process.env.ANALYTICS_ROLLUP_BACKFILL_JOBS ??
     process.env.RUN_BACKGROUND_JOBS;
-  const enabled =
-    !platformSchedulerOwnsBackfill() &&
-    (flag === "1" || (isProd && flag !== "0"));
+  const enabled = !platformSchedulerOwnsBackfill() && flag === "1";
 
   if (!enabled) {
     if (!skippingLogged) {
       console.log(
         platformSchedulerOwnsBackfill()
           ? "[analytics-rollups] Skipping in-process cron because the platform scheduler owns historical rollup backfills."
-          : "[analytics-rollups] Skipping historical rollup backfill (set ANALYTICS_ROLLUP_BACKFILL_JOBS=1 or RUN_BACKGROUND_JOBS=1 to enable in dev; on by default in production)",
+          : "[analytics-rollups] Skipping historical rollup backfill (set ANALYTICS_ROLLUP_BACKFILL_JOBS=1 or RUN_BACKGROUND_JOBS=1 to enable explicitly)",
       );
       skippingLogged = true;
     }