@agent-native/core 0.146.7 → 0.146.8

package/corpus/README.md

@@ -31,4 +31,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 ## Generated Counts
 
-- template files: 7921
+- template files: 7922

package/corpus/templates/analytics/DEVELOPING.md

@@ -183,6 +183,65 @@ Conventions:
 - Use `fatal()` for required arg validation
 - `helpers.ts` loads `dotenv/config` so env vars are available
 
+### Dedicated first-party Analytics backfill
+
+`backfill:first-party-bigquery` is a resumable, bounded Neon-to-BigQuery worker
+for an explicitly selected organization. It is dry-run by default. It uses the
+scoped credential resolver, fixed high-water marks, separate organization and
+legacy-owner cursors, atomic local checkpoints, a local lock, and a durable
+database lease shared with the shipped worker. The tuple-paging indexes are
+installed by the additive analytics migration. It does not change the Analytics
+sink or perform cutover.
+
+```bash
+pnpm backfill:first-party-bigquery \
+  --owner-email=<owner-email> \
+  --org-id=<org-id>
+```
+
+Production execution requires both `--execute` and the explicit
+`AGENT_NATIVE_ANALYTICS_BIGQUERY_BACKFILL_ALLOW=1` environment gate. Start with a bounded
+`--max-batches` budget and increase concurrency only after checking database
+health between runs. The dedicated worker claims the durable migration-job
+lease, so the shipped worker and another operator using a different checkpoint
+path cannot copy the same job concurrently. A crashed dedicated worker leaves
+that lease to expire before the shipped worker can resume it.
+
+```bash
+AGENT_NATIVE_ANALYTICS_BIGQUERY_BACKFILL_ALLOW=1 pnpm backfill:first-party-bigquery \
+  --execute \
+  --owner-email=<owner-email> \
+  --org-id=<org-id> \
+  --batch-size=1000 \
+  --concurrency=2 \
+  --max-batches=100
+```
+
+The checkpoint file contains cursors and counts, not event payloads or
+credentials. A short page triggers a fresh high-water check so rows written
+while the worker is running are included. A partial BigQuery acknowledgement
+does not advance the cursor; retry it promptly, or run an insertId-deduplication
+or `MERGE` pass on the target table before finalizing.
+
+Before finalization, quiesce the source event writes and verify the final
+high-water marks. The `--owner-email` and `--org-id` values are trusted operator
+inputs, so execution is limited to the approved production operator and the
+two explicit environment gates. Then use the separate `--finalize` command
+with both gates below. The command rechecks the source high-water marks before
+marking the durable job complete; the normal migration action's approval gate
+still controls cutover:
+
+```bash
+AGENT_NATIVE_ANALYTICS_BIGQUERY_BACKFILL_FINALIZE_ALLOW=1 \
+AGENT_NATIVE_ANALYTICS_BIGQUERY_BACKFILL_QUIESCENT=1 \
+pnpm backfill:first-party-bigquery \
+  --finalize \
+  --owner-email=<owner-email> \
+  --org-id=<org-id>
+```
+
+Do not delete a lock file until the owning process has been verified stopped.
+
 ## TypeScript Everywhere
 
 All code in this project must be TypeScript (`.ts`). Never create `.js`, `.cjs`, or `.mjs` files. Node 22+ runs `.ts` files natively, so no compilation step is needed for scripts. Use ESM imports (`import`), not CommonJS (`require`).

package/corpus/templates/analytics/package.json

@@ -11,6 +11,7 @@
     "format.fix": "oxfmt --write .",
     "typecheck": "agent-native typecheck",
     "migrate:production": "tsx scripts/migrate-production.ts",
+    "backfill:first-party-bigquery": "tsx scripts/first-party-analytics-bigquery-backfill.ts",
     "action": "agent-native action",
     "script": "agent-native script"
   },

package/corpus/templates/analytics/scripts/first-party-analytics-bigquery-backfill.ts

@@ -0,0 +1,839 @@
+import {
+  open,
+  mkdir,
+  readFile,
+  rename,
+  unlink,
+  writeFile,
+} from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  closeDbExec,
+  getDbExec,
+  withMigrationRuntime,
+} from "@agent-native/core/db";
+import { runWithRequestContext } from "@agent-native/core/server";
+
+import { output, parseArgs } from "../actions/helpers.js";
+import {
+  acquireDedicatedFirstPartyAnalyticsBackfillLease,
+  getFirstPartyAnalyticsBigQueryBackfillJob,
+} from "../server/jobs/analytics-bigquery-backfill.js";
+import {
+  createFirstPartyAnalyticsInserter,
+  FIRST_PARTY_ANALYTICS_BACKFILL_COLUMNS,
+  getFirstPartyAnalyticsBackend,
+  saveFirstPartyAnalyticsBackend,
+  type FirstPartyAnalyticsScope,
+} from "../server/lib/first-party-analytics-backend.js";
+
+const DEFAULT_BATCH_SIZE = 1_000;
+const MAX_BATCH_SIZE = 2_500;
+const DEFAULT_CONCURRENCY = 2;
+const MAX_CONCURRENCY = 4;
+const DEFAULT_MAX_BATCHES = 1_000;
+const MAX_MAX_BATCHES = 10_000;
+const DEFAULT_CHECKPOINT_PATH = ".analytics-first-party-bigquery-backfill.json";
+const QUERY_TIMEOUT_MS = 30_000;
+const JOB_TABLE = "analytics_bigquery_backfill_jobs";
+const FINALIZE_ALLOW_ENV =
+  "AGENT_NATIVE_ANALYTICS_BIGQUERY_BACKFILL_FINALIZE_ALLOW";
+const FINALIZE_QUIESCENT_ENV =
+  "AGENT_NATIVE_ANALYTICS_BIGQUERY_BACKFILL_QUIESCENT";
+
+type BranchName = "org" | "legacy";
+
+export interface BackfillCursor {
+  receivedAt: string;
+  id: string;
+}
+
+export interface BranchCheckpoint {
+  cutoff: BackfillCursor | null;
+  cursor: BackfillCursor | null;
+  copied: number;
+  complete: boolean;
+}
+
+export interface DedicatedBackfillCheckpoint {
+  version: 1;
+  scope: {
+    userEmail: string;
+    orgId: string;
+  };
+  table: string | null;
+  branches: Record<BranchName, BranchCheckpoint>;
+  updatedAt: string;
+}
+
+export interface DedicatedBackfillOptions {
+  scope: FirstPartyAnalyticsScope & { orgId: string };
+  table: string | null;
+  batchSize: number;
+  concurrency: number;
+  maxBatches: number;
+  checkpointPath: string;
+}
+
+export interface FinalizeResult {
+  mode: "finalize";
+  copied: number;
+  cursor: BackfillCursor | null;
+  jobId: string;
+  status: "completed";
+}
+
+interface DbQuery {
+  sql: string;
+  args: unknown[];
+  timeoutMs: number;
+  maxAttempts: 1;
+}
+
+interface DbExecutor {
+  execute(query: DbQuery): Promise<{ rows: unknown[] }>;
+}
+
+export interface CheckpointStore {
+  load(): Promise<DedicatedBackfillCheckpoint | null>;
+  save(checkpoint: DedicatedBackfillCheckpoint): Promise<void>;
+}
+
+export interface DedicatedBackfillDependencies {
+  db: DbExecutor;
+  upload: (rows: Array<Record<string, unknown>>) => Promise<number>;
+  checkpointStore: CheckpointStore;
+  now?: () => string;
+  onProgress?: (progress: {
+    branch: BranchName;
+    batches: number;
+    copiedThisRun: number;
+    copiedTotal: number;
+  }) => void;
+}
+
+export interface DedicatedBackfillResult {
+  batches: number;
+  copiedThisRun: number;
+  copiedTotal: number;
+  complete: boolean;
+  checkpoint: DedicatedBackfillCheckpoint;
+}
+
+interface BranchSpec {
+  name: BranchName;
+  predicate: string;
+  predicateArgs: string[];
+}
+
+const PROJECTED_COLUMNS = FIRST_PARTY_ANALYTICS_BACKFILL_COLUMNS.join(", ");
+
+function positiveInteger(
+  raw: string | undefined,
+  name: string,
+  fallback: number,
+  maximum: number,
+): number {
+  if (raw === undefined) return fallback;
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < 1) {
+    throw new Error(`${name} must be a positive integer`);
+  }
+  return Math.min(value, maximum);
+}
+
+function requiredArg(args: Record<string, string>, name: string): string {
+  const value = args[name]?.trim();
+  if (!value) throw new Error(`--${name} is required`);
+  return value;
+}
+
+export function parseDedicatedBackfillOptions(
+  args = parseArgs(),
+): DedicatedBackfillOptions & { execute: boolean; finalize: boolean } {
+  const userEmail = requiredArg(args, "owner-email");
+  const orgId = requiredArg(args, "org-id");
+  return {
+    scope: { userEmail, orgId },
+    table: args.table?.trim() || null,
+    batchSize: positiveInteger(
+      args["batch-size"],
+      "--batch-size",
+      DEFAULT_BATCH_SIZE,
+      MAX_BATCH_SIZE,
+    ),
+    concurrency: positiveInteger(
+      args.concurrency,
+      "--concurrency",
+      DEFAULT_CONCURRENCY,
+      MAX_CONCURRENCY,
+    ),
+    maxBatches: positiveInteger(
+      args["max-batches"],
+      "--max-batches",
+      DEFAULT_MAX_BATCHES,
+      MAX_MAX_BATCHES,
+    ),
+    checkpointPath: resolve(args.checkpoint || DEFAULT_CHECKPOINT_PATH),
+    execute: args.execute === "true",
+    finalize: args.finalize === "true",
+  };
+}
+
+function branchSpecs(
+  scope: FirstPartyAnalyticsScope & { orgId: string },
+): BranchSpec[] {
+  return [
+    {
+      name: "org",
+      predicate: "org_id = ?",
+      predicateArgs: [scope.orgId],
+    },
+    {
+      name: "legacy",
+      predicate: "org_id IS NULL AND owner_email = ?",
+      predicateArgs: [scope.userEmail],
+    },
+  ];
+}
+
+export function buildHighWaterMarkQuery(spec: BranchSpec): DbQuery {
+  return {
+    sql: `SELECT received_at, id
+      FROM analytics_events
+      WHERE ${spec.predicate}
+      ORDER BY received_at DESC, id DESC
+      LIMIT 1`,
+    args: spec.predicateArgs,
+    timeoutMs: QUERY_TIMEOUT_MS,
+    maxAttempts: 1,
+  };
+}
+
+export function buildPageQuery(
+  spec: BranchSpec,
+  state: BranchCheckpoint,
+  batchSize: number,
+): DbQuery {
+  if (!state.cutoff) {
+    throw new Error(`Cannot page ${spec.name} without a high-water mark`);
+  }
+  const args: unknown[] = [
+    ...spec.predicateArgs,
+    state.cutoff.receivedAt,
+    state.cutoff.receivedAt,
+    state.cutoff.id,
+  ];
+  let cursorClause = "";
+  if (state.cursor) {
+    cursorClause = " AND (received_at > ? OR (received_at = ? AND id > ?))";
+    args.push(
+      state.cursor.receivedAt,
+      state.cursor.receivedAt,
+      state.cursor.id,
+    );
+  }
+  args.push(batchSize);
+  return {
+    sql: `SELECT ${PROJECTED_COLUMNS}
+      FROM analytics_events
+      WHERE ${spec.predicate}
+        AND (received_at < ? OR (received_at = ? AND id <= ?))${cursorClause}
+      ORDER BY received_at ASC, id ASC
+      LIMIT ?`,
+    args,
+    timeoutMs: QUERY_TIMEOUT_MS,
+    maxAttempts: 1,
+  };
+}
+
+function cursorFromRow(row: unknown, description: string): BackfillCursor {
+  if (!row || typeof row !== "object") {
+    throw new Error(`${description} is not an object`);
+  }
+  const record = row as Record<string, unknown>;
+  const receivedAt = record.received_at;
+  const id = record.id;
+  if (typeof receivedAt !== "string" || !receivedAt) {
+    throw new Error(`${description} is missing received_at`);
+  }
+  if (typeof id !== "string" || !id) {
+    throw new Error(`${description} is missing id`);
+  }
+  return { receivedAt, id };
+}
+
+function assertCheckpointCursor(
+  cursor: unknown,
+  description: string,
+): asserts cursor is BackfillCursor {
+  if (!cursor || typeof cursor !== "object") {
+    throw new Error(`Backfill checkpoint ${description} is not an object`);
+  }
+  const record = cursor as Record<string, unknown>;
+  if (typeof record.receivedAt !== "string" || !record.receivedAt) {
+    throw new Error(`Backfill checkpoint ${description} is missing receivedAt`);
+  }
+  if (typeof record.id !== "string" || !record.id) {
+    throw new Error(`Backfill checkpoint ${description} is missing id`);
+  }
+}
+
+function emptyBranchCheckpoint(): BranchCheckpoint {
+  return { cutoff: null, cursor: null, copied: 0, complete: false };
+}
+
+function newCheckpoint(
+  options: DedicatedBackfillOptions,
+  now: string,
+): DedicatedBackfillCheckpoint {
+  return {
+    version: 1,
+    scope: {
+      userEmail: options.scope.userEmail,
+      orgId: options.scope.orgId,
+    },
+    table: options.table,
+    branches: {
+      org: emptyBranchCheckpoint(),
+      legacy: emptyBranchCheckpoint(),
+    },
+    updatedAt: now,
+  };
+}
+
+function assertCheckpointMatches(
+  checkpoint: DedicatedBackfillCheckpoint,
+  options: DedicatedBackfillOptions,
+): void {
+  if (checkpoint.version !== 1) {
+    throw new Error(
+      `Unsupported backfill checkpoint version: ${checkpoint.version}`,
+    );
+  }
+  if (
+    checkpoint.scope.userEmail !== options.scope.userEmail ||
+    checkpoint.scope.orgId !== options.scope.orgId
+  ) {
+    throw new Error(
+      "Backfill checkpoint scope does not match --owner-email/--org-id",
+    );
+  }
+  if (checkpoint.table !== options.table) {
+    throw new Error(
+      "Backfill checkpoint table does not match the current BigQuery table",
+    );
+  }
+  for (const branch of ["org", "legacy"] as const) {
+    const state = checkpoint.branches[branch];
+    if (!state)
+      throw new Error(`Backfill checkpoint is missing ${branch} state`);
+    if (!Number.isInteger(state.copied) || state.copied < 0) {
+      throw new Error(`Backfill checkpoint has an invalid ${branch} count`);
+    }
+    if (state.cutoff) {
+      assertCheckpointCursor(state.cutoff, `${branch} cutoff`);
+    }
+    if (state.cursor) {
+      assertCheckpointCursor(state.cursor, `${branch} cursor`);
+    }
+    if (state.cursor && !state.cutoff) {
+      throw new Error(
+        `Backfill checkpoint has a ${branch} cursor without a cutoff`,
+      );
+    }
+  }
+}
+
+function latestCursor(
+  checkpoint: DedicatedBackfillCheckpoint,
+): BackfillCursor | null {
+  const cursors = [
+    checkpoint.branches.org.cursor,
+    checkpoint.branches.legacy.cursor,
+  ]
+    .filter((cursor): cursor is BackfillCursor => cursor !== null)
+    .sort(
+      (left, right) =>
+        left.receivedAt.localeCompare(right.receivedAt) ||
+        left.id.localeCompare(right.id),
+    );
+  return cursors[cursors.length - 1] ?? null;
+}
+
+function compareCursors(left: BackfillCursor, right: BackfillCursor): number {
+  return (
+    left.receivedAt.localeCompare(right.receivedAt) ||
+    left.id.localeCompare(right.id)
+  );
+}
+
+export async function assertSourceAtCheckpoint(
+  scope: DedicatedBackfillOptions["scope"],
+  checkpoint: DedicatedBackfillCheckpoint,
+  db: DbExecutor = getDbExec(),
+): Promise<void> {
+  for (const spec of branchSpecs(scope)) {
+    const result = await db.execute(buildHighWaterMarkQuery(spec));
+    const latestRow = result.rows[0];
+    if (!latestRow) continue;
+    const latest = cursorFromRow(
+      latestRow,
+      `${spec.name} final high-water mark`,
+    );
+    const cutoff = checkpoint.branches[spec.name].cutoff;
+    if (!cutoff || compareCursors(latest, cutoff) > 0) {
+      throw new Error(
+        `Refusing to finalize: ${spec.name} branch has events after the checkpoint cutoff; quiesce source writes and retry the finalization`,
+      );
+    }
+  }
+}
+
+export class JsonCheckpointStore implements CheckpointStore {
+  constructor(private readonly path: string) {}
+
+  async load(): Promise<DedicatedBackfillCheckpoint | null> {
+    try {
+      const raw = await readFile(this.path, "utf8");
+      const parsed: unknown = JSON.parse(raw);
+      if (!parsed || typeof parsed !== "object") {
+        throw new Error("checkpoint is not an object");
+      }
+      return parsed as DedicatedBackfillCheckpoint;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+      throw new Error(
+        `Unable to read backfill checkpoint ${this.path}: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+
+  async save(checkpoint: DedicatedBackfillCheckpoint): Promise<void> {
+    await mkdir(dirname(this.path), { recursive: true });
+    const temporaryPath = `${this.path}.${process.pid}.tmp`;
+    await writeFile(temporaryPath, `${JSON.stringify(checkpoint, null, 2)}\n`, {
+      encoding: "utf8",
+      mode: 0o600,
+    });
+    await rename(temporaryPath, this.path);
+  }
+}
+
+async function refreshBranchCutoff(
+  spec: BranchSpec,
+  state: BranchCheckpoint,
+  checkpoint: DedicatedBackfillCheckpoint,
+  dependencies: DedicatedBackfillDependencies,
+  now: () => string,
+): Promise<void> {
+  const result = await dependencies.db.execute(buildHighWaterMarkQuery(spec));
+  const row = result.rows[0];
+  const latest = row
+    ? cursorFromRow(row, `${spec.name} high-water mark`)
+    : null;
+  if (latest && (!state.cutoff || compareCursors(latest, state.cutoff) > 0)) {
+    state.cutoff = latest;
+    state.complete = false;
+  } else {
+    state.complete = true;
+  }
+  checkpoint.updatedAt = now();
+  await dependencies.checkpointStore.save(checkpoint);
+}
+
+export async function acquireCheckpointLock(
+  checkpointPath: string,
+): Promise<() => Promise<void>> {
+  const lockPath = `${checkpointPath}.lock`;
+  await mkdir(dirname(lockPath), { recursive: true });
+  let handle: Awaited<ReturnType<typeof open>>;
+  try {
+    handle = await open(lockPath, "wx", 0o600);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "EEXIST") {
+      throw new Error(
+        `Another backfill worker owns ${lockPath}; inspect it before removing the lock`,
+      );
+    }
+    throw error;
+  }
+  try {
+    await handle.writeFile(
+      `${JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() })}\n`,
+      "utf8",
+    );
+  } catch (error) {
+    await handle.close();
+    await unlink(lockPath).catch(() => undefined);
+    throw error;
+  }
+  await handle.close();
+  return async () => {
+    await unlink(lockPath).catch((error: unknown) => {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    });
+  };
+}
+
+export async function runDedicatedBackfill(
+  options: DedicatedBackfillOptions,
+  dependencies: DedicatedBackfillDependencies,
+): Promise<DedicatedBackfillResult> {
+  const now = dependencies.now ?? (() => new Date().toISOString());
+  const checkpoint =
+    (await dependencies.checkpointStore.load()) ??
+    newCheckpoint(options, now());
+  assertCheckpointMatches(checkpoint, options);
+  await dependencies.checkpointStore.save(checkpoint);
+
+  let batches = 0;
+  let copiedThisRun = 0;
+  let stop = false;
+  for (const spec of branchSpecs(options.scope)) {
+    const state = checkpoint.branches[spec.name];
+    if (state.complete) continue;
+
+    if (!state.cutoff) {
+      await refreshBranchCutoff(spec, state, checkpoint, dependencies, now);
+      if (state.complete) continue;
+    }
+
+    while (!state.complete) {
+      if (batches >= options.maxBatches) {
+        stop = true;
+        break;
+      }
+      const result = await dependencies.db.execute(
+        buildPageQuery(spec, state, options.batchSize),
+      );
+      const rows = result.rows as Array<Record<string, unknown>>;
+      if (!rows.length) {
+        await refreshBranchCutoff(spec, state, checkpoint, dependencies, now);
+        if (state.complete) break;
+        continue;
+      }
+
+      const copied = await dependencies.upload(rows);
+      if (copied !== rows.length) {
+        throw new Error(
+          `BigQuery acknowledged ${copied} of ${rows.length} rows; checkpoint was not advanced`,
+        );
+      }
+
+      state.cursor = cursorFromRow(rows[rows.length - 1], `${spec.name} page`);
+      state.copied += copied;
+      copiedThisRun += copied;
+      batches += 1;
+      state.complete = false;
+      checkpoint.updatedAt = now();
+      await dependencies.checkpointStore.save(checkpoint);
+      dependencies.onProgress?.({
+        branch: spec.name,
+        batches,
+        copiedThisRun,
+        copiedTotal: state.copied,
+      });
+      if (rows.length < options.batchSize) {
+        await refreshBranchCutoff(spec, state, checkpoint, dependencies, now);
+      }
+    }
+    if (stop) break;
+  }
+
+  return {
+    batches,
+    copiedThisRun,
+    copiedTotal:
+      checkpoint.branches.org.copied + checkpoint.branches.legacy.copied,
+    complete:
+      checkpoint.branches.org.complete && checkpoint.branches.legacy.complete,
+    checkpoint,
+  };
+}
+
+const USAGE = `Dedicated first-party Analytics Neon -> BigQuery backfill
+
+Dry-run (default):
+  pnpm backfill:first-party-bigquery --owner-email=<email> --org-id=<org>
+
+Execute only after an explicit production approval:
+  AGENT_NATIVE_ANALYTICS_BIGQUERY_BACKFILL_ALLOW=1 pnpm backfill:first-party-bigquery \
+    --execute --owner-email=<email> --org-id=<org>
+
+Options:
+  --table=<dataset.table>       Optional override, must match the approved table
+  --batch-size=<n>              Source page size, default 1000, max 2500
+  --concurrency=<n>             BigQuery requests in flight, default 2, max 4
+  --max-batches=<n>             Work budget per invocation, default 1000
+  --checkpoint=<path>           Atomic local checkpoint path
+
+After the checkpoint is complete, reconcile it into the shipped durable job
+after quiescing source event writes and checking the final high-water marks:
+  AGENT_NATIVE_ANALYTICS_BIGQUERY_BACKFILL_FINALIZE_ALLOW=1 \
+  AGENT_NATIVE_ANALYTICS_BIGQUERY_BACKFILL_QUIESCENT=1 \
+  pnpm backfill:first-party-bigquery \
+    --finalize --owner-email=<email> --org-id=<org>
+`;
+
+async function runApprovedWorker(
+  options: DedicatedBackfillOptions,
+): Promise<DedicatedBackfillResult> {
+  let releaseLock: (() => Promise<void>) | null = null;
+  let releaseLease: (() => Promise<void>) | null = null;
+  try {
+    releaseLock = await acquireCheckpointLock(options.checkpointPath);
+    return await withMigrationRuntime(async () =>
+      runWithRequestContext(options.scope, async () => {
+        const backend = await getFirstPartyAnalyticsBackend(options.scope);
+        if (backend.sink !== "dual") {
+          throw new Error(
+            `Refusing to backfill while the source sink is ${backend.sink}; prepare must establish dual-write first`,
+          );
+        }
+        if (options.table && backend.table && options.table !== backend.table) {
+          throw new Error(
+            "--table does not match the scoped first-party Analytics backend setting",
+          );
+        }
+        const configuredTable = options.table ?? backend.table;
+        if (!configuredTable) {
+          throw new Error(
+            "Refusing to start the dedicated backfill without a configured BigQuery table",
+          );
+        }
+        const workerOptions = { ...options, table: configuredTable };
+        releaseLease = await acquireDedicatedFirstPartyAnalyticsBackfillLease(
+          options.scope,
+          configuredTable,
+        );
+        const insertRows = await createFirstPartyAnalyticsInserter(
+          configuredTable,
+          {
+            maxRowsPerRequest: 500,
+            maxConcurrentRequests: options.concurrency,
+          },
+        );
+        const result = await runDedicatedBackfill(workerOptions, {
+          db: getDbExec(),
+          upload: (rows) => insertRows(rows),
+          checkpointStore: new JsonCheckpointStore(options.checkpointPath),
+          onProgress: (progress) => {
+            console.error(JSON.stringify({ type: "progress", ...progress }));
+          },
+        });
+        return result;
+      }),
+    );
+  } finally {
+    const leaseToRelease = releaseLease as (() => Promise<void>) | null;
+    const lockToRelease = releaseLock as (() => Promise<void>) | null;
+    if (leaseToRelease) {
+      try {
+        await leaseToRelease();
+      } finally {
+        if (lockToRelease) {
+          try {
+            await closeDbExec();
+          } finally {
+            await lockToRelease();
+          }
+        }
+      }
+    } else if (lockToRelease) {
+      try {
+        await closeDbExec();
+      } finally {
+        await lockToRelease();
+      }
+    }
+  }
+}
+
+async function runApprovedFinalize(
+  options: DedicatedBackfillOptions,
+): Promise<FinalizeResult> {
+  let releaseLock: (() => Promise<void>) | null = null;
+  try {
+    releaseLock = await acquireCheckpointLock(options.checkpointPath);
+    return await withMigrationRuntime(async () =>
+      runWithRequestContext(options.scope, async () => {
+        const backend = await getFirstPartyAnalyticsBackend(options.scope);
+        if (backend.sink !== "dual") {
+          throw new Error(
+            `Refusing to finalize while the source sink is ${backend.sink}; prepare must establish dual-write first`,
+          );
+        }
+        const configuredTable = options.table ?? backend.table;
+        const finalizeOptions = { ...options, table: configuredTable };
+        const checkpoint = await new JsonCheckpointStore(
+          options.checkpointPath,
+        ).load();
+        if (!checkpoint) {
+          throw new Error(
+            `Backfill checkpoint ${options.checkpointPath} does not exist`,
+          );
+        }
+        assertCheckpointMatches(checkpoint, finalizeOptions);
+        if (
+          !checkpoint.branches.org.complete ||
+          !checkpoint.branches.legacy.complete
+        ) {
+          throw new Error(
+            "Refusing to finalize before both organization and legacy-owner branches are complete",
+          );
+        }
+
+        const job = await getFirstPartyAnalyticsBigQueryBackfillJob(
+          options.scope,
+        );
+        if (!job) {
+          throw new Error(
+            "Prepare the organization before reconciling the dedicated backfill checkpoint",
+          );
+        }
+        if (job.table !== checkpoint.table) {
+          throw new Error(
+            `Durable backfill targets ${job.table}, checkpoint targets ${checkpoint.table}`,
+          );
+        }
+        if (job.status === "completed") {
+          return {
+            mode: "finalize",
+            copied:
+              checkpoint.branches.org.copied +
+              checkpoint.branches.legacy.copied,
+            cursor: latestCursor(checkpoint),
+            jobId: job.id,
+            status: "completed",
+          };
+        }
+        if (
+          job.status === "running" &&
+          (!job.leaseExpiresAt || Date.parse(job.leaseExpiresAt) > Date.now())
+        ) {
+          throw new Error(
+            "The shipped backfill worker currently owns the durable job lease; wait for it to stop before finalizing",
+          );
+        }
+
+        await assertSourceAtCheckpoint(options.scope, checkpoint);
+
+        const cursor = latestCursor(checkpoint);
+        const now = new Date().toISOString();
+        const update = await getDbExec().execute({
+          sql: `UPDATE ${JOB_TABLE}
+                  SET status = 'completed', backfill_cursor = ?,
+                      copied_count = ?, lease_token = NULL,
+                      lease_expires_at = NULL, next_run_at = ?,
+                      last_error = NULL, completed_at = ?, updated_at = ?
+                WHERE id = ? AND table_ref = ?
+                  AND (status = 'pending'
+                       OR (status = 'running' AND lease_expires_at IS NOT NULL
+                           AND lease_expires_at <= ?))`,
+          args: [
+            cursor ? JSON.stringify(cursor) : null,
+            Math.max(
+              job.copied,
+              checkpoint.branches.org.copied +
+                checkpoint.branches.legacy.copied,
+            ),
+            now,
+            now,
+            now,
+            job.id,
+            checkpoint.table,
+            now,
+          ],
+          timeoutMs: 5_000,
+          maxAttempts: 1,
+        });
+        if (update.rowsAffected !== 1) {
+          throw new Error(
+            "The durable backfill job changed while it was being finalized; inspect status before retrying",
+          );
+        }
+        await saveFirstPartyAnalyticsBackend(options.scope, {
+          ...backend,
+          table: checkpoint.table,
+          backfillCursor: cursor ? JSON.stringify(cursor) : null,
+          backfillCompleted: true,
+        });
+        return {
+          mode: "finalize",
+          copied:
+            checkpoint.branches.org.copied + checkpoint.branches.legacy.copied,
+          cursor,
+          jobId: job.id,
+          status: "completed",
+        };
+      }),
+    );
+  } finally {
+    if (releaseLock) {
+      try {
+        await closeDbExec();
+      } finally {
+        await releaseLock();
+      }
+    }
+  }
+}
+
+async function main(): Promise<void> {
+  const args = parseArgs();
+  if (args.help) {
+    console.log(USAGE);
+    return;
+  }
+  const options = parseDedicatedBackfillOptions(args);
+  if (options.execute && options.finalize) {
+    throw new Error("Choose either --execute or --finalize, not both");
+  }
+  if (!options.execute && !options.finalize) {
+    output({
+      mode: "dry-run",
+      batchSize: options.batchSize,
+      concurrency: options.concurrency,
+      maxBatches: options.maxBatches,
+      checkpointPath: options.checkpointPath,
+      message:
+        "No data was copied. Pass --execute and AGENT_NATIVE_ANALYTICS_BIGQUERY_BACKFILL_ALLOW=1 after production approval.",
+    });
+    return;
+  }
+  if (options.finalize) {
+    if (process.env[FINALIZE_ALLOW_ENV] !== "1") {
+      throw new Error(
+        `Checkpoint finalization is disabled. Set ${FINALIZE_ALLOW_ENV}=1 only after explicit production approval.`,
+      );
+    }
+    if (process.env[FINALIZE_QUIESCENT_ENV] !== "1") {
+      throw new Error(
+        `Checkpoint finalization requires source event writes to be quiesced. Set ${FINALIZE_QUIESCENT_ENV}=1 only after the final high-water check and explicit production approval.`,
+      );
+    }
+    output(await runApprovedFinalize(options));
+    return;
+  }
+  if (process.env.AGENT_NATIVE_ANALYTICS_BIGQUERY_BACKFILL_ALLOW !== "1") {
+    throw new Error(
+      "Production execution is disabled. Set AGENT_NATIVE_ANALYTICS_BIGQUERY_BACKFILL_ALLOW=1 only after explicit approval.",
+    );
+  }
+  output(await runApprovedWorker(options));
+}
+
+if (
+  process.argv[1] &&
+  resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+) {
+  try {
+    await main();
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  }
+}

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

@@ -10,6 +10,7 @@ import {
 
 const JOB_TABLE = "analytics_bigquery_backfill_jobs";
 const LEASE_MS = 5 * 60 * 1000;
+const DEDICATED_LEASE_MS = 24 * 60 * 60 * 1000;
 const ERROR_RETRY_MS = 5 * 60 * 1000;
 const DEFAULT_BATCH_SIZE = 250;
 const MAX_BATCH_SIZE = 750;
@@ -191,6 +192,75 @@ export async function getFirstPartyAnalyticsBigQueryBackfillJob(
   return row ? rowToJob(row) : null;
 }
 
+export async function acquireDedicatedFirstPartyAnalyticsBackfillLease(
+  scope: FirstPartyAnalyticsScope,
+  table: string,
+): Promise<() => Promise<void>> {
+  if (!scope.orgId) {
+    throw new Error("Dedicated BigQuery backfill requires an organization");
+  }
+  const id = jobId(scope.orgId);
+  const token = randomUUID();
+  const now = new Date().toISOString();
+  const leaseExpiresAt = new Date(
+    Date.now() + DEDICATED_LEASE_MS,
+  ).toISOString();
+  const claimed = await executor().execute({
+    sql: `UPDATE ${JOB_TABLE}
+             SET status = 'running', lease_token = ?, lease_expires_at = ?,
+                 updated_at = ?
+           WHERE id = ? AND table_ref = ?
+             AND (status = 'pending'
+                  OR (status = 'running' AND lease_expires_at IS NOT NULL
+                      AND lease_expires_at <= ?))`,
+    args: [token, leaseExpiresAt, now, id, table, now],
+    timeoutMs: 5_000,
+    maxAttempts: 1,
+  });
+  if (claimed.rowsAffected !== 1) {
+    const job = await getFirstPartyAnalyticsBigQueryBackfillJob(scope);
+    if (!job) {
+      throw new Error(
+        "Prepare the organization before starting the dedicated BigQuery backfill",
+      );
+    }
+    if (job.table !== table) {
+      throw new Error(
+        `BigQuery backfill already targets ${job.table}; the dedicated worker requested ${table}`,
+      );
+    }
+    if (job.status === "completed") {
+      throw new Error(
+        "The durable BigQuery backfill is already completed; do not run the dedicated worker again",
+      );
+    }
+    throw new Error(
+      "Another BigQuery backfill worker owns the durable lease; wait for it to stop before retrying",
+    );
+  }
+
+  let released = false;
+  return async () => {
+    if (released) return;
+    const releasedAt = new Date().toISOString();
+    const result = await executor().execute({
+      sql: `UPDATE ${JOB_TABLE}
+               SET status = 'pending', lease_token = NULL,
+                   lease_expires_at = NULL, next_run_at = ?, updated_at = ?
+             WHERE id = ? AND lease_token = ?`,
+      args: [leaseExpiresAt, releasedAt, id, token],
+      timeoutMs: 5_000,
+      maxAttempts: 1,
+    });
+    if (result.rowsAffected !== 1) {
+      throw new Error(
+        "The dedicated BigQuery backfill lost its durable lease before release",
+      );
+    }
+    released = true;
+  };
+}
+
 export async function queueFirstPartyAnalyticsBigQueryBackfill(
   scope: FirstPartyAnalyticsScope,
   table: string,

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

@@ -75,6 +75,16 @@ const FIRST_PARTY_QUERY_TABLES = [
 const BACKEND_CONFIG_CACHE_TTL_MS = 30_000;
 const MAX_BACKFILL_BATCH_SIZE = 750;
 const MAX_INSERT_BATCH_SIZE = 200;
+const MAX_DEDICATED_INSERT_BATCH_SIZE = 500;
+const MAX_DEDICATED_INSERT_CONCURRENCY = 4;
+const MAX_INSERT_REQUEST_BYTES = 8 * 1024 * 1024;
+
+export interface FirstPartyAnalyticsInsertOptions {
+  /** Maximum rows in one BigQuery insertAll request. */
+  maxRowsPerRequest?: number;
+  /** Maximum insertAll requests in flight for a dedicated backfill worker. */
+  maxConcurrentRequests?: number;
+}
 
 const backendConfigCache = new Map<
   string,
@@ -224,7 +234,7 @@ const FIRST_PARTY_ANALYTICS_RAW_SCHEMA = [
   ["org_id", "STRING"],
 ] as const;
 
-const FIRST_PARTY_ANALYTICS_BACKFILL_COLUMNS = [
+export const FIRST_PARTY_ANALYTICS_BACKFILL_COLUMNS = [
   "id",
   "public_key_id",
   "event_name",
@@ -352,9 +362,114 @@ async function insertBatch(
   }
 }
 
+function boundedInsertOption(
+  value: number | undefined,
+  fallback: number,
+  maximum: number,
+  name: string,
+): number {
+  if (value === undefined) return fallback;
+  if (!Number.isInteger(value) || value < 1) {
+    throw new Error(`${name} must be a positive integer`);
+  }
+  return Math.min(value, maximum);
+}
+
+async function insertPayloadRows(
+  table: BigQueryTableRef,
+  token: string,
+  payloadRows: Record<string, unknown>[],
+  options: FirstPartyAnalyticsInsertOptions = {},
+): Promise<void> {
+  const maxRowsPerRequest = boundedInsertOption(
+    options.maxRowsPerRequest,
+    MAX_INSERT_BATCH_SIZE,
+    MAX_DEDICATED_INSERT_BATCH_SIZE,
+    "maxRowsPerRequest",
+  );
+  const maxConcurrentRequests = boundedInsertOption(
+    options.maxConcurrentRequests,
+    1,
+    MAX_DEDICATED_INSERT_CONCURRENCY,
+    "maxConcurrentRequests",
+  );
+  const batches: Record<string, unknown>[][] = [];
+  const encoder = new TextEncoder();
+  let currentBatch: Record<string, unknown>[] = [];
+  let currentBytes = 2;
+  for (const row of payloadRows) {
+    const rowBytes = encoder.encode(
+      JSON.stringify({
+        insertId: typeof row.id === "string" ? row.id : undefined,
+        json: row,
+      }),
+    ).byteLength;
+    if (rowBytes + 2 > MAX_INSERT_REQUEST_BYTES) {
+      throw new Error(
+        "A first-party Analytics row exceeds the BigQuery request limit",
+      );
+    }
+    if (
+      currentBatch.length > 0 &&
+      (currentBatch.length >= maxRowsPerRequest ||
+        currentBytes + rowBytes + 1 > MAX_INSERT_REQUEST_BYTES)
+    ) {
+      batches.push(currentBatch);
+      currentBatch = [];
+      currentBytes = 2;
+    }
+    currentBatch.push(row);
+    currentBytes += rowBytes + 1;
+  }
+  if (currentBatch.length > 0) batches.push(currentBatch);
+
+  let nextBatch = 0;
+  const worker = async (): Promise<void> => {
+    while (true) {
+      const batchIndex = nextBatch;
+      nextBatch += 1;
+      const batch = batches[batchIndex];
+      if (!batch) return;
+      await insertBatch(table, token, batch);
+    }
+  };
+
+  await Promise.all(
+    Array.from(
+      { length: Math.min(maxConcurrentRequests, batches.length) },
+      () => worker(),
+    ),
+  );
+}
+
+/**
+ * Create a long-lived inserter for a dedicated backfill process. The table is
+ * resolved once, while the token is refreshed through the existing scoped
+ * resolver for every page so a multi-hour run does not use an expired token.
+ */
+export async function createFirstPartyAnalyticsInserter(
+  configuredTable?: string | null,
+  options: FirstPartyAnalyticsInsertOptions = {},
+): Promise<
+  (
+    rows: Array<FirstPartyAnalyticsEventRow | Record<string, unknown>>,
+  ) => Promise<number>
+> {
+  requireRequestCredentialContext("GOOGLE_APPLICATION_CREDENTIALS_JSON");
+  const table = await getFirstPartyAnalyticsTable(configuredTable);
+  return async (rows) => {
+    if (!rows.length) return 0;
+    const token = await getAccessToken();
+    const payloadRows = rows.map(firstPartyEventRowToBigQuery);
+    await insertPayloadRows(table, token, payloadRows, options);
+    return payloadRows.length;
+  };
+}
+
 export async function insertFirstPartyAnalyticsRows(
   rows: Array<FirstPartyAnalyticsEventRow | Record<string, unknown>>,
   configuredTable?: string | null,
+  options: FirstPartyAnalyticsInsertOptions = {},
 ): Promise<number> {
   if (!rows.length) return 0;
   requireRequestCredentialContext("GOOGLE_APPLICATION_CREDENTIALS_JSON");
@@ -363,17 +478,7 @@ export async function insertFirstPartyAnalyticsRows(
     getAccessToken(),
   ]);
   const payloadRows = rows.map(firstPartyEventRowToBigQuery);
-  for (
-    let offset = 0;
-    offset < payloadRows.length;
-    offset += MAX_INSERT_BATCH_SIZE
-  ) {
-    await insertBatch(
-      table,
-      token,
-      payloadRows.slice(offset, offset + MAX_INSERT_BATCH_SIZE),
-    );
-  }
+  await insertPayloadRows(table, token, payloadRows, options);
   return payloadRows.length;
 }
 

package/corpus/templates/factory/actions/run-factory-automation.ts

@@ -35,6 +35,7 @@ export default defineAction({
     return queueAutomationRunNow({
       userEmail,
       orgId,
+      appId: "factory",
       scope: "organization",
       name: definition.name,
     });

package/corpus/templates/factory/netlify.toml

@@ -1,5 +1,5 @@
 [build]
-command = "NITRO_PRESET=netlify pnpm --filter factory build && if [ \"${CONTEXT:-}\" = \"production\" ]; then pnpm --filter factory migrate:production; fi"
+command = "export DATABASE_URL=\"${NETLIFY_DATABASE_URL:-$DATABASE_URL}\" && pnpm install && DATABASE_URL=\"${NETLIFY_DATABASE_URL_UNPOOLED:-$DATABASE_URL}\" NITRO_PRESET=netlify pnpm --filter factory build && if [ \"${CONTEXT:-}\" = \"production\" ]; then DATABASE_URL=\"${NETLIFY_DATABASE_URL_UNPOOLED:-$DATABASE_URL}\" pnpm --filter factory migrate:production; fi"
 publish = "dist"
 functions = ".netlify/functions-internal"
 

package/dist/collab/struct-routes.d.ts

@@ -13,8 +13,8 @@
  * Body: { json: any, fieldName?: string, type?: "map"|"array", requestSource?: string }
  */
 export declare const postCollabJson: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    ok?: undefined;
     error: string;
+    ok?: undefined;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/observability/routes.d.ts

@@ -41,27 +41,27 @@ export declare function createObservabilityHandler(): import("h3").EventHandlerW
     thumbsUpRate: number;
     avgEvalScore: number;
 } | {
-    error?: undefined;
-    ok?: undefined;
     summary: import("./types.js").TraceSummary;
     spans: import("./types.js").TraceSpan[];
     id?: undefined;
-} | {
     error?: undefined;
     ok?: undefined;
+} | {
     summary?: undefined;
     spans?: undefined;
     id: string;
-} | {
+    error?: undefined;
     ok?: undefined;
+} | {
     summary?: undefined;
     spans?: undefined;
     id?: undefined;
     error: any;
+    ok?: undefined;
 } | {
-    error?: undefined;
     summary?: undefined;
     spans?: undefined;
     id?: undefined;
     ok: boolean;
+    error?: undefined;
 }>>;

package/dist/progress/routes.d.ts

@@ -15,6 +15,6 @@ export declare function createProgressHandler(): import("h3").EventHandlerWithFe
     error: string;
     ok?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
+    error?: undefined;
 }>>;

package/dist/resources/handlers.d.ts

@@ -48,8 +48,8 @@ export declare function handleUpdateResource(event: any): Promise<import("./stor
 }>;
 /** DELETE /_agent-native/resources/:id — delete a resource */
 export declare function handleDeleteResource(event: any): Promise<{
-    error: string;
     ok?: undefined;
+    error: string;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/secrets/routes.d.ts

@@ -34,16 +34,16 @@ export declare function createListSecretsHandler(): import("h3").EventHandlerWit
 /** POST /_agent-native/secrets/:key — write a secret. */
 export declare function createWriteSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: string;
-    status?: undefined;
     ok?: undefined;
+    status?: undefined;
 } | {
     ok: boolean;
     status: string;
     error?: undefined;
 } | {
+    ok?: undefined;
     error: string;
     removed?: undefined;
-    ok?: undefined;
 } | {
     ok: boolean;
     removed: boolean;
@@ -54,9 +54,9 @@ export declare function createWriteSecretHandler(): import("h3").EventHandlerWit
  * or the current stored value without changing anything.
  */
 export declare function createTestSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
+    ok?: undefined;
     error: string;
     note?: undefined;
-    ok?: undefined;
 } | {
     ok: boolean;
     note?: undefined;

package/dist/server/agent-engine-api-key-route.d.ts

@@ -27,10 +27,10 @@ export declare function resolveAgentEngineApiKeyWriteTarget(event: H3Event, scop
 export declare function createAgentEngineApiKeyHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: any;
 } | {
+    error?: undefined;
     ok: boolean;
     key: string;
     baseUrlKey?: string;
     scope: AgentEngineApiKeyScope;
-    error?: undefined;
 }>>;
 export {};

package/dist/server/realtime-token.d.ts

@@ -26,8 +26,8 @@ export declare function createRealtimeTokenHandler(): import("h3").EventHandlerW
     expiresAt?: undefined;
     ttlSeconds?: undefined;
 } | {
-    error?: undefined;
     token: string;
     expiresAt: string;
     ttlSeconds: number;
+    error?: undefined;
 }>>;

package/dist/server/transcribe-voice.d.ts

@@ -20,6 +20,6 @@ export declare function createTranscribeVoiceHandler(): import("h3").EventHandle
     error: string;
     text?: undefined;
 } | {
-    error?: undefined;
     text: string;
+    error?: undefined;
 }>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.146.7",
+  "version": "0.146.8",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {
@@ -412,8 +412,8 @@
     "y-protocols": "^1.0.7",
     "yjs": "^13.6.31",
     "zod": "^4.3.6",
-    "@agent-native/toolkit": "^0.13.5",
-    "@agent-native/recap-cli": "0.5.3"
+    "@agent-native/recap-cli": "0.5.3",
+    "@agent-native/toolkit": "^0.13.5"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.71",