@agent-native/core 0.147.0 → 0.148.0

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

@@ -6,7 +6,7 @@ import {
   type BigQueryTableRef,
 } from "./bigquery.js";
 import { requireRequestCredentialContext } from "./credentials-context.js";
-import { getAccessToken } from "./gcloud.js";
+import { fetchGoogleWithRetry, getAccessToken } from "./gcloud.js";
 import {
   getScopedSettingRecord,
   putScopedSettingRecord,
@@ -78,6 +78,19 @@ 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;
+const DEFAULT_BACKFILL_LOOKBACK_DAYS = 60;
+const MIN_BACKFILL_LOOKBACK_DAYS = 30;
+const MAX_BACKFILL_LOOKBACK_DAYS = 60;
+const DEFAULT_BACKFILL_SKIP_EVENTS = ["http.response"];
+const MAX_BACKFILL_SKIP_EVENTS = 32;
+const BACKFILL_LOOKBACK_DAYS_ENV = "ANALYTICS_BIGQUERY_BACKFILL_LOOKBACK_DAYS";
+const BACKFILL_SKIP_EVENTS_ENV = "ANALYTICS_BIGQUERY_BACKFILL_SKIP_EVENTS";
+
+export interface FirstPartyAnalyticsBackfillOptions {
+  lookbackDays?: number;
+  skipEventNames?: string[];
+  now?: () => string;
+}
 
 export interface FirstPartyAnalyticsInsertOptions {
   /** Maximum rows in one BigQuery insertAll request. */
@@ -319,7 +332,7 @@ async function insertBatch(
   token: string,
   rows: Record<string, unknown>[],
 ): Promise<void> {
-  const response = await fetch(
+  const response = await fetchGoogleWithRetry(
     `https://bigquery.googleapis.com/bigquery/v2/projects/${table.projectId}/datasets/${table.datasetId}/tables/${table.tableId}/insertAll`,
     {
       method: "POST",
@@ -336,6 +349,7 @@ async function insertBatch(
         })),
       }),
     },
+    "BigQuery insertAll",
   );
   if (!response.ok) {
     const text = await response.text();
@@ -939,6 +953,7 @@ export async function queryFirstPartyAnalyticsInBigQuery(
 
 export async function assertFirstPartyAnalyticsBigQueryReady(
   configuredTable?: string | null,
+  options: { includeRowCount?: boolean } = {},
 ): Promise<{ table: BigQueryTableRef; rowCount: number }> {
   const table = await getFirstPartyAnalyticsTable(configuredTable);
   const expectedColumns = new Map<string, readonly string[]>([
@@ -1017,6 +1032,9 @@ export async function assertFirstPartyAnalyticsBigQueryReady(
         missingColumns.join(", "),
     );
   }
+  if (options.includeRowCount === false) {
+    return { table, rowCount: 0 };
+  }
   const result = await runQuery(
     "SELECT COUNT(*) AS row_count FROM " + quote + table.fullyQualified + quote,
   );
@@ -1027,6 +1045,7 @@ export async function assertFirstPartyAnalyticsBigQueryReady(
 export async function getFirstPartyAnalyticsBigQueryMetrics(
   scope: FirstPartyAnalyticsScope,
   configuredTable?: string | null,
+  options: { includeLegacyOwnerRows?: boolean; startDate?: string } = {},
 ): Promise<{
   eventCount: number;
   dailyRollupRows: number;
@@ -1037,14 +1056,20 @@ export async function getFirstPartyAnalyticsBigQueryMetrics(
   const physical = firstPartyAnalyticsPhysicalTables(table);
   const ownerEmail = sqlLiteral(scope.userEmail);
   const today = sqlLiteral(new Date().toISOString().slice(0, 10));
+  const includeLegacyOwnerRows = options.includeLegacyOwnerRows !== false;
   const tenantFilter = scope.orgId
-    ? `(org_id = ${sqlLiteral(scope.orgId)} OR (org_id IS NULL AND owner_email = ${ownerEmail}))`
+    ? includeLegacyOwnerRows
+      ? `(org_id = ${sqlLiteral(scope.orgId)} OR (org_id IS NULL AND owner_email = ${ownerEmail}))`
+      : `(org_id = ${sqlLiteral(scope.orgId)})`
     : `(org_id IS NULL AND owner_email = ${ownerEmail})`;
+  const startDateFilter = options.startDate
+    ? ` AND event_date >= ${sqlLiteral(options.startDate)}`
+    : "";
   const result = await runQuery(`
     WITH scoped_events AS (
       SELECT *
       FROM \`${physical.events}\`
-      WHERE ${tenantFilter} AND event_date <= ${today}
+      WHERE ${tenantFilter}${startDateFilter} AND event_date <= ${today}
     )
     SELECT
       COUNT(*) AS event_count,
@@ -1121,26 +1146,92 @@ function serializeBackfillCursor(
   return JSON.stringify(cursor);
 }
 
+function boundedLookbackDays(value: number): number {
+  if (
+    !Number.isInteger(value) ||
+    value < MIN_BACKFILL_LOOKBACK_DAYS ||
+    value > MAX_BACKFILL_LOOKBACK_DAYS
+  ) {
+    throw new Error(
+      `BigQuery backfill lookback must be an integer between ${MIN_BACKFILL_LOOKBACK_DAYS} and ${MAX_BACKFILL_LOOKBACK_DAYS} days`,
+    );
+  }
+  return value;
+}
+
+function configuredLookbackDays(requested: number | undefined): number {
+  if (requested !== undefined) return boundedLookbackDays(requested);
+  const raw = process.env[BACKFILL_LOOKBACK_DAYS_ENV]?.trim();
+  if (!raw) return DEFAULT_BACKFILL_LOOKBACK_DAYS;
+  const parsed = Number(raw);
+  return Number.isInteger(parsed) &&
+    parsed >= MIN_BACKFILL_LOOKBACK_DAYS &&
+    parsed <= MAX_BACKFILL_LOOKBACK_DAYS
+    ? parsed
+    : DEFAULT_BACKFILL_LOOKBACK_DAYS;
+}
+
+function configuredSkipEventNames(requested: string[] | undefined): string[] {
+  const raw = requested
+    ? requested
+    : (
+        process.env[BACKFILL_SKIP_EVENTS_ENV] ??
+        DEFAULT_BACKFILL_SKIP_EVENTS.join(",")
+      )
+        .split(",")
+        .map((name) => name.trim());
+  const names = [...new Set(raw)].filter(Boolean);
+  if (names.length > MAX_BACKFILL_SKIP_EVENTS) {
+    throw new Error(
+      `BigQuery backfill skips at most ${MAX_BACKFILL_SKIP_EVENTS} event names`,
+    );
+  }
+  return names;
+}
+
+function backfillLookbackStart(now: string, lookbackDays: number): string {
+  const date = new Date(now);
+  if (Number.isNaN(date.getTime())) {
+    throw new Error(`Invalid BigQuery backfill clock value: ${now}`);
+  }
+  date.setUTCDate(date.getUTCDate() - lookbackDays);
+  return date.toISOString();
+}
+
 function backfillBranchSql(
   predicate: string,
   predicateArgs: string[],
   cursor: FirstPartyAnalyticsBackfillCursor,
+  lookbackStart: string,
+  skipEventNames: string[],
 ): {
   sql: string;
-  args: string[];
+  args: unknown[];
 } {
-  const cursorSql = cursor.receivedAt
-    ? "(received_at > ? OR (received_at = ? AND id > ?))"
-    : "";
-  const cursorArgs = cursor.receivedAt
-    ? [cursor.receivedAt, cursor.receivedAt, cursor.id]
-    : [];
+  const cursorSql = cursor.receivedAt ? "(received_at, id) > (?, ?)" : "";
+  const cursorArgs = cursor.receivedAt ? [cursor.receivedAt, cursor.id] : [];
+  const skipSql =
+    skipEventNames.length === DEFAULT_BACKFILL_SKIP_EVENTS.length &&
+    skipEventNames[0] === DEFAULT_BACKFILL_SKIP_EVENTS[0]
+      ? "event_name IS DISTINCT FROM 'http.response'"
+      : skipEventNames.length
+        ? `(event_name IS NULL OR event_name NOT IN (${skipEventNames.map(() => "?").join(", ")}))`
+        : "";
+  const filters = ["received_at >= ?", skipSql].filter(Boolean);
   return {
     sql: `SELECT id, received_at
       FROM analytics_events
-      WHERE ${predicate}${cursorSql ? ` AND ${cursorSql}` : ""}
+      WHERE ${predicate}
+        AND ${filters.join("\n        AND ")}${cursorSql ? `\n        AND ${cursorSql}` : ""}
       ORDER BY received_at ASC, id ASC LIMIT ?`,
-    args: [...predicateArgs, ...cursorArgs],
+    args: [
+      ...predicateArgs,
+      lookbackStart,
+      ...(skipSql === "event_name IS DISTINCT FROM 'http.response'"
+        ? []
+        : skipEventNames),
+      ...cursorArgs,
+    ],
   };
 }
 
@@ -1191,6 +1282,7 @@ export async function backfillFirstPartyAnalyticsBatch(
   cursor: string | null,
   limit: number,
   configuredTable?: string | null,
+  options?: FirstPartyAnalyticsBackfillOptions,
 ): Promise<FirstPartyAnalyticsBackfillBatch> {
   const boundedLimit = Math.min(
     Math.max(Math.floor(limit), 1),
@@ -1198,6 +1290,12 @@ export async function backfillFirstPartyAnalyticsBatch(
   );
   const db = getDbExec();
   const parsedCursor = parseBackfillCursor(cursor);
+  const lookbackDays = configuredLookbackDays(options?.lookbackDays);
+  const lookbackStart = backfillLookbackStart(
+    options?.now?.() ?? new Date().toISOString(),
+    lookbackDays,
+  );
+  const skipEventNames = configuredSkipEventNames(options?.skipEventNames);
   const branches = scope.orgId
     ? [
         { predicate: "org_id = ?", args: [scope.orgId] },
@@ -1218,6 +1316,8 @@ export async function backfillFirstPartyAnalyticsBatch(
       branch.predicate,
       branch.args,
       parsedCursor,
+      lookbackStart,
+      skipEventNames,
     );
     const result = await db.execute({
       sql: scoped.sql,

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

@@ -0,0 +1,140 @@
+import { and, count, eq, gte, isNull, or } from "drizzle-orm";
+
+import { getDb, schema } from "../db/index.js";
+
+export interface FirstPartyAnalyticsPurgeScope {
+  userEmail: string;
+  orgId: string;
+}
+
+export interface FirstPartyAnalyticsPostgresPurgeCounts {
+  eventRows: number;
+  dailyRollupRows: number;
+  userDayRows: number;
+}
+
+export interface FirstPartyAnalyticsPurgeWindow {
+  startReceivedAt: string;
+  startEventDate: string;
+}
+
+function scopePredicate(
+  table: {
+    orgId: any;
+    ownerEmail: any;
+  },
+  scope: FirstPartyAnalyticsPurgeScope,
+  includeLegacyOwnerRows: boolean,
+) {
+  if (!includeLegacyOwnerRows) return eq(table.orgId, scope.orgId);
+  return or(
+    eq(table.orgId, scope.orgId),
+    and(isNull(table.orgId), eq(table.ownerEmail, scope.userEmail)),
+  );
+}
+
+function windowPredicate(
+  table: {
+    eventDate: any;
+    receivedAt?: any;
+  },
+  predicate: any,
+  window: FirstPartyAnalyticsPurgeWindow,
+) {
+  return table.receivedAt
+    ? and(predicate, gte(table.receivedAt, window.startReceivedAt))
+    : and(predicate, gte(table.eventDate, window.startEventDate));
+}
+
+async function countScopedRows(table: any, predicate: any): Promise<number> {
+  const [row] = await (getDb() as any)
+    .select({ count: count() })
+    .from(table)
+    .where(predicate);
+  const value = Number(row?.count ?? 0);
+  return Number.isFinite(value) ? value : 0;
+}
+
+export async function countFirstPartyAnalyticsPostgresRows(
+  scope: FirstPartyAnalyticsPurgeScope,
+  includeLegacyOwnerRows: boolean,
+  window: FirstPartyAnalyticsPurgeWindow,
+): Promise<FirstPartyAnalyticsPostgresPurgeCounts> {
+  const predicates = [
+    windowPredicate(
+      schema.analyticsEvents,
+      scopePredicate(schema.analyticsEvents, scope, includeLegacyOwnerRows),
+      window,
+    ),
+    windowPredicate(
+      schema.analyticsEventDailyRollups,
+      scopePredicate(
+        schema.analyticsEventDailyRollups,
+        scope,
+        includeLegacyOwnerRows,
+      ),
+      window,
+    ),
+    windowPredicate(
+      schema.analyticsUserDays,
+      scopePredicate(schema.analyticsUserDays, scope, includeLegacyOwnerRows),
+      window,
+    ),
+  ];
+  const [eventRows, dailyRollupRows, userDayRows] = await Promise.all([
+    countScopedRows(schema.analyticsEvents, predicates[0]),
+    countScopedRows(schema.analyticsEventDailyRollups, predicates[1]),
+    countScopedRows(schema.analyticsUserDays, predicates[2]),
+  ]);
+  return { eventRows, dailyRollupRows, userDayRows };
+}
+
+export async function purgeFirstPartyAnalyticsPostgresRows(
+  scope: FirstPartyAnalyticsPurgeScope,
+  includeLegacyOwnerRows: boolean,
+  window: FirstPartyAnalyticsPurgeWindow,
+): Promise<FirstPartyAnalyticsPostgresPurgeCounts> {
+  const counts = await countFirstPartyAnalyticsPostgresRows(
+    scope,
+    includeLegacyOwnerRows,
+    window,
+  );
+  await (getDb() as any).transaction(async (tx: any) => {
+    await tx
+      .delete(schema.analyticsEvents)
+      .where(
+        windowPredicate(
+          schema.analyticsEvents,
+          scopePredicate(schema.analyticsEvents, scope, includeLegacyOwnerRows),
+          window,
+        ),
+      );
+    await tx
+      .delete(schema.analyticsEventDailyRollups)
+      .where(
+        windowPredicate(
+          schema.analyticsEventDailyRollups,
+          scopePredicate(
+            schema.analyticsEventDailyRollups,
+            scope,
+            includeLegacyOwnerRows,
+          ),
+          window,
+        ),
+      );
+    await tx
+      .delete(schema.analyticsUserDays)
+      .where(
+        windowPredicate(
+          schema.analyticsUserDays,
+          scopePredicate(
+            schema.analyticsUserDays,
+            scope,
+            includeLegacyOwnerRows,
+          ),
+          window,
+        ),
+      );
+  });
+  return counts;
+}

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

@@ -0,0 +1,207 @@
+import { and, eq, sql } from "drizzle-orm";
+
+import { schema } from "../db/index.js";
+
+export const FIRST_PARTY_POSTGRES_EVENT_VOLUME_LIMIT_ENV =
+  "ANALYTICS_FIRST_PARTY_POSTGRES_EVENT_VOLUME_LIMIT";
+export const FIRST_PARTY_POSTGRES_EVENT_VOLUME_WINDOW_DAYS_ENV =
+  "ANALYTICS_FIRST_PARTY_POSTGRES_EVENT_VOLUME_WINDOW_DAYS";
+
+export const DEFAULT_FIRST_PARTY_POSTGRES_EVENT_VOLUME_LIMIT = 1_000_000;
+export const DEFAULT_FIRST_PARTY_POSTGRES_EVENT_VOLUME_WINDOW_DAYS = 30;
+
+const MAX_EVENT_VOLUME_LIMIT = 100_000_000;
+const MIN_VOLUME_WINDOW_DAYS = 1;
+const MAX_VOLUME_WINDOW_DAYS = 90;
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+export interface FirstPartyPostgresEventVolumeConfig {
+  eventLimit: number;
+  windowDays: number;
+}
+
+export interface FirstPartyPostgresEventVolumeScope {
+  ownerEmail: string;
+  orgId: string | null;
+  receivedAt: string;
+}
+
+export interface FirstPartyPostgresEventVolumeReservation {
+  tenantKey: string;
+  windowStart: string;
+  eventCount: number;
+  eventLimit: number;
+}
+
+export class FirstPartyPostgresEventVolumeLimitError extends Error {
+  readonly statusCode = 429;
+
+  constructor(
+    readonly reservation: FirstPartyPostgresEventVolumeReservation,
+    requested: number,
+  ) {
+    super(
+      `Postgres first-party Analytics volume limit reached for this ${reservation.windowStart} window: ${reservation.eventCount}/${reservation.eventLimit} events reserved; connect your own analytics database or BigQuery before sending more events (requested ${requested}).`,
+    );
+    this.name = "FirstPartyPostgresEventVolumeLimitError";
+  }
+}
+
+function parseIntegerEnv(
+  environment: Record<string, string | undefined>,
+  key: string,
+  fallback: number,
+  minimum: number,
+  maximum: number,
+): number {
+  const raw = environment[key]?.trim();
+  if (!raw) return fallback;
+  if (!/^\d+$/.test(raw)) {
+    throw new Error(
+      `${key} must be an integer between ${minimum} and ${maximum}`,
+    );
+  }
+  const value = Number(raw);
+  if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
+    throw new Error(
+      `${key} must be an integer between ${minimum} and ${maximum}`,
+    );
+  }
+  return value;
+}
+
+export function getFirstPartyPostgresEventVolumeConfig(
+  environment: Record<string, string | undefined> = process.env,
+): FirstPartyPostgresEventVolumeConfig {
+  return {
+    eventLimit: parseIntegerEnv(
+      environment,
+      FIRST_PARTY_POSTGRES_EVENT_VOLUME_LIMIT_ENV,
+      DEFAULT_FIRST_PARTY_POSTGRES_EVENT_VOLUME_LIMIT,
+      1,
+      MAX_EVENT_VOLUME_LIMIT,
+    ),
+    windowDays: parseIntegerEnv(
+      environment,
+      FIRST_PARTY_POSTGRES_EVENT_VOLUME_WINDOW_DAYS_ENV,
+      DEFAULT_FIRST_PARTY_POSTGRES_EVENT_VOLUME_WINDOW_DAYS,
+      MIN_VOLUME_WINDOW_DAYS,
+      MAX_VOLUME_WINDOW_DAYS,
+    ),
+  };
+}
+
+export function firstPartyPostgresEventVolumeWindowStart(
+  receivedAt: string,
+  windowDays: number,
+): string {
+  if (!Number.isInteger(windowDays) || windowDays < 1) {
+    throw new Error(
+      "First-party Analytics volume window must be a positive integer",
+    );
+  }
+  const receivedAtMs = Date.parse(receivedAt);
+  if (!Number.isFinite(receivedAtMs)) {
+    throw new Error(
+      "First-party Analytics volume receivedAt must be an ISO timestamp",
+    );
+  }
+  const windowMs = windowDays * DAY_MS;
+  return new Date(Math.floor(receivedAtMs / windowMs) * windowMs).toISOString();
+}
+
+function tenantKey(
+  scope: Pick<FirstPartyPostgresEventVolumeScope, "ownerEmail" | "orgId">,
+): string {
+  return scope.orgId ? `org:${scope.orgId}` : `user:${scope.ownerEmail}`;
+}
+
+function reservationId(tenant: string, windowStart: string): string {
+  return `aevu_${encodeURIComponent(tenant)}_${encodeURIComponent(windowStart)}`;
+}
+
+export async function reserveFirstPartyPostgresEventVolume(
+  transaction: any,
+  scope: FirstPartyPostgresEventVolumeScope,
+  requested: number,
+): Promise<FirstPartyPostgresEventVolumeReservation> {
+  if (!Number.isInteger(requested) || requested < 1) {
+    throw new Error(
+      "First-party Analytics volume reservation must be positive",
+    );
+  }
+  const config = getFirstPartyPostgresEventVolumeConfig();
+  const scopedTenantKey = tenantKey(scope);
+  const windowStart = firstPartyPostgresEventVolumeWindowStart(
+    scope.receivedAt,
+    config.windowDays,
+  );
+
+  await transaction
+    .insert(schema.analyticsEventVolumeUsage)
+    .values({
+      id: reservationId(scopedTenantKey, windowStart),
+      tenantKey: scopedTenantKey,
+      ownerEmail: scope.ownerEmail,
+      orgId: scope.orgId,
+      windowStart,
+      eventCount: 0,
+      eventLimit: config.eventLimit,
+      updatedAt: scope.receivedAt,
+    })
+    .onConflictDoNothing({
+      target: [
+        schema.analyticsEventVolumeUsage.tenantKey,
+        schema.analyticsEventVolumeUsage.windowStart,
+      ],
+    });
+
+  const [updated] = await transaction
+    .update(schema.analyticsEventVolumeUsage)
+    .set({
+      eventCount: sql`${schema.analyticsEventVolumeUsage.eventCount} + ${requested}`,
+      eventLimit: config.eventLimit,
+      updatedAt: scope.receivedAt,
+    })
+    .where(
+      and(
+        eq(schema.analyticsEventVolumeUsage.tenantKey, scopedTenantKey),
+        eq(schema.analyticsEventVolumeUsage.windowStart, windowStart),
+        sql`${schema.analyticsEventVolumeUsage.eventCount} + ${requested} <= ${config.eventLimit}`,
+      ),
+    )
+    .returning({
+      eventCount: schema.analyticsEventVolumeUsage.eventCount,
+      eventLimit: schema.analyticsEventVolumeUsage.eventLimit,
+    });
+
+  if (!updated) {
+    const [current] = await transaction
+      .select({
+        eventCount: schema.analyticsEventVolumeUsage.eventCount,
+        eventLimit: schema.analyticsEventVolumeUsage.eventLimit,
+      })
+      .from(schema.analyticsEventVolumeUsage)
+      .where(
+        and(
+          eq(schema.analyticsEventVolumeUsage.tenantKey, scopedTenantKey),
+          eq(schema.analyticsEventVolumeUsage.windowStart, windowStart),
+        ),
+      )
+      .limit(1);
+    const reservation = {
+      tenantKey: scopedTenantKey,
+      windowStart,
+      eventCount: Number(current?.eventCount ?? 0),
+      eventLimit: Number(current?.eventLimit ?? config.eventLimit),
+    };
+    throw new FirstPartyPostgresEventVolumeLimitError(reservation, requested);
+  }
+
+  return {
+    tenantKey: scopedTenantKey,
+    windowStart,
+    eventCount: Number(updated.eventCount),
+    eventLimit: Number(updated.eventLimit),
+  };
+}

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

@@ -25,6 +25,7 @@ import {
   recordFirstPartyAnalyticsQueryPressure,
 } from "./first-party-analytics-health.js";
 import { upsertFirstPartyAnalyticsRollups } from "./first-party-analytics-rollups.js";
+import { reserveFirstPartyPostgresEventVolume } from "./first-party-analytics-volume.js";
 
 export interface AnalyticsScope {
   userEmail: string;
@@ -578,6 +579,7 @@ export async function recordAnalyticsEvents(
     orgId: key.orgId ?? null,
   });
 
+  let bigQueryInsertError: unknown = null;
   if (rows.length && (backend.sink === "dual" || backend.sink === "bigquery")) {
     try {
       await runWithRequestContext(
@@ -588,21 +590,47 @@ export async function recordAnalyticsEvents(
         () => insertFirstPartyAnalyticsRows(rows, backend.table),
       );
     } catch (error) {
-      if (backend.sink === "bigquery") throw error;
+      if (backend.sink === "bigquery") {
+        // Keep SQL-only exception issues, public-key metadata, and session
+        // replay links durable even when the warehouse is temporarily down.
+        // The request still fails below so callers do not mistake a warehouse
+        // outage for a successful BigQuery write.
+        bigQueryInsertError = error;
+      }
       // Dual-write mode keeps Postgres as the recoverable source until the
       // backfill has completed. A BigQuery outage must not lose live events.
-      console.error(
-        "[first-party-analytics] BigQuery dual-write failed; retaining Postgres event:",
-        error,
-      );
+      if (backend.sink === "dual") {
+        console.error(
+          "[first-party-analytics] BigQuery dual-write failed; retaining Postgres event:",
+          error,
+        );
+      }
     }
   }
 
+  let postgresInsertError: unknown = null;
   if (rows.length && backend.sink !== "bigquery") {
-    await db.transaction(async (tx: any) => {
-      await tx.insert(schema.analyticsEvents).values(rows);
-      await upsertFirstPartyAnalyticsRollups(rows, tx);
-    });
+    try {
+      await db.transaction(async (tx: any) => {
+        if (backend.sink === "postgres" || backend.sink === "dual") {
+          await reserveFirstPartyPostgresEventVolume(
+            tx,
+            {
+              ownerEmail: key.ownerEmail,
+              orgId: key.orgId ?? null,
+              receivedAt,
+            },
+            rows.length,
+          );
+        }
+        await tx.insert(schema.analyticsEvents).values(rows);
+        await upsertFirstPartyAnalyticsRollups(rows, tx);
+      });
+    } catch (error) {
+      // Preserve SQL-only exception issues and public-key metadata below even
+      // when a Postgres volume reservation or insert rejects the batch.
+      postgresInsertError = error;
+    }
   }
   if (rows.length) {
     await touchPublicKeyLastUsedAt(key.id, receivedAt);
@@ -627,6 +655,9 @@ export async function recordAnalyticsEvents(
     }
   }
 
+  if (bigQueryInsertError) throw bigQueryInsertError;
+  if (postgresInsertError) throw postgresInsertError;
+
   return { accepted: rows.length, keyId: key.id };
 }