@canonry/canonry 4.133.3 → 4.134.1

package/dist/{chunk-HENMGNLT.js → chunk-DVJGFY3J.js}

@@ -19,6 +19,9 @@ import {
   AdsHistoricalCampaignRollupStatuses,
   AdsInsightLevels,
   AdsIntegrityDecisions,
+  AdsLiveDeliveryBases,
+  AdsLiveEntityTypes,
+  AdsLivePresences,
   AdsOperationKinds,
   AdsOperationStates,
   AdsOperationStepStates,
@@ -96,6 +99,8 @@ import {
   adsImageUploadRequestSchema,
   adsInsightLevelSchema,
   adsInsightsResponseSchema,
+  adsLiveDeliveryDtoSchema,
+  adsLiveDeliveryQuerySchema,
   adsOperationReconcileResponseSchema,
   adsOperationResponseSchema,
   adsOperationStepDtoSchema,
@@ -183,6 +188,7 @@ import {
   discoverySessionDetailDtoSchema,
   discoverySessionDtoSchema,
   doctorReportSchema,
+  dollarsToMicros,
   domainClassificationsResponseDtoSchema,
   effectiveBrandNames,
   effectiveDomains,
@@ -199,9 +205,11 @@ import {
   formatDateRange,
   formatDeltaCopy,
   formatIsoDate,
+  formatIsoDateInTimeZone,
   formatNumber,
   formatRatio,
   formatWindowCountDelta,
+  ga4AiReferralDailyDtoSchema,
   ga4AiReferralHistoryEntrySchema,
   ga4SessionHistoryEntrySchema,
   ga4SocialReferralHistoryEntrySchema,
@@ -242,6 +250,7 @@ import {
   internalError,
   isBrowserProvider,
   isReadOnlyKey,
+  isoDateDaysBeforeInTimeZone,
   keywordDtoSchema,
   keywordGenerateRequestSchema,
   latestProjectRunDtoSchema,
@@ -356,7 +365,7 @@ import {
   wordpressSchemaDeployResultDtoSchema,
   wordpressSchemaStatusResultDtoSchema,
   wordpressStatusDtoSchema
-} from "./chunk-YRRQFOAH.js";
+} from "./chunk-CF5WTWXI.js";
 
 // src/intelligence-service.ts
 import { eq as eq44, desc as desc21, asc as asc9, and as and35, ne as ne6, or as or10, inArray as inArray15, gte as gte12, lte as lte8 } from "drizzle-orm";
@@ -1462,6 +1471,8 @@ var researchRunQueries = sqliteTable("research_run_queries", {
   groundingSources: text("grounding_sources", { mode: "json" }).$type().notNull().default([]),
   citedDomains: text("cited_domains", { mode: "json" }).$type().notNull().default([]),
   searchQueries: text("search_queries", { mode: "json" }).$type().notNull().default([]),
+  namedCompetitors: text("named_competitors", { mode: "json" }).$type().notNull().default([]),
+  citedCompetitorDomains: text("cited_competitor_domains", { mode: "json" }).$type().notNull().default([]),
   answerMentioned: integer("answer_mentioned", { mode: "boolean" }),
   citationState: text("citation_state"),
   rawResponse: text("raw_response", { mode: "json" }).$type(),
@@ -4266,6 +4277,16 @@ var MIGRATION_VERSIONS = [
         updated_at                TEXT NOT NULL
       )`
     ]
+  },
+  {
+    // Keep research batches useful as a competitor-comparison workspace while
+    // retaining their strict isolation from tracked visibility snapshots.
+    version: 110,
+    name: "research-query-named-and-cited-competitors",
+    statements: [
+      `ALTER TABLE research_run_queries ADD COLUMN named_competitors TEXT NOT NULL DEFAULT '[]'`,
+      `ALTER TABLE research_run_queries ADD COLUMN cited_competitor_domains TEXT NOT NULL DEFAULT '[]'`
+    ]
   }
 ];
 function rebuildBacklinkTableWithSource(tx, table) {
@@ -17392,6 +17413,7 @@ var SCHEMA_TABLE = {
   AdsDisconnectResponse: adsDisconnectResponseSchema,
   AdsGeoSearchResponse: adsGeoSearchResponseSchema,
   AdsInsightsResponse: adsInsightsResponseSchema,
+  AdsLiveDeliveryDto: adsLiveDeliveryDtoSchema,
   AdsOperationReconcileResponse: adsOperationReconcileResponseSchema,
   AdsOperationResponse: adsOperationResponseSchema,
   AdsSummaryDto: adsSummaryDtoSchema,
@@ -17441,6 +17463,7 @@ var SCHEMA_TABLE = {
   ResearchRunDetailDto: researchRunDetailSchema,
   ResearchRunListDto: researchRunListSchema,
   DoctorReportDto: doctorReportSchema,
+  GA4AiReferralDailyDto: ga4AiReferralDailyDtoSchema,
   GA4AiReferralHistoryEntry: ga4AiReferralHistoryEntrySchema,
   GA4MeasurementAnalysisDto: gaMeasurementAnalysisDtoSchema,
   GA4SessionHistoryEntry: ga4SessionHistoryEntrySchema,
@@ -20395,6 +20418,35 @@ var routeCatalog = [
       404: errorResponse("Project not found.")
     }
   },
+  {
+    method: "get",
+    path: "/api/v1/projects/{name}/ads/live-delivery",
+    summary: "Live provider read of ads status and metrics, with the local snapshot delta",
+    description: "Calls the OpenAI Ads API right now with the stored connection and returns the provider's current status and metrics unaggregated, alongside the corresponding local snapshot values and an explicit per-entity delta. Dates on both sides are the ad account's local calendar dates. The first day of the window is measured from 00:00 in the account timezone on both sides, so it is a whole day either way and a difference on it is real; the current local day is in progress on both sides, so a difference there is snapshot staleness. Read-only: it never creates, updates, pauses, or activates anything, and it never waits for a sync run. The window counts calendar days in the account timezone, not fixed 24-hour periods, so a daylight-saving transition cannot move the first day. The walk is bounded by per-level caps and a budget of 40 reader calls (see bounds). Admission has two rules: a project may have only one live read running at a time (a second request is refused for as long as the first is actually walking, which can exceed any interval), and consecutive reads are spaced by at least one minute. The interval is counted as soon as the provider is called, so a read that fails upstream still holds it; only a read rejected before the provider was called leaves the next one free. A reader call is not one HTTP request: each list or insight read auto-paginates up to 100 pages, so the worst-case upstream cost of a single request is about 4000 HTTP requests, reported as bounds.maxUpstreamHttpRequests.",
+    tags: ["ads"],
+    parameters: [
+      nameParameter,
+      {
+        name: "campaignId",
+        in: "query",
+        description: "Scope the walk to a single campaign.",
+        schema: stringSchema
+      },
+      {
+        name: "lookbackDays",
+        in: "query",
+        description: "Metrics window in calendar days of the ad account timezone (1-30, default 7).",
+        schema: integerSchema
+      }
+    ],
+    responses: {
+      200: jsonResponse("Live provider state and snapshot delta returned.", "AdsLiveDeliveryDto"),
+      400: errorResponse("Invalid query, or no ads connection for this project."),
+      404: errorResponse("Project not found."),
+      429: errorResponse("Another live read for this project is still running, or the minimum interval since the last provider read has not elapsed. error.details.reason says which."),
+      502: errorResponse("The OpenAI Ads API read failed.")
+    }
+  },
   {
     method: "post",
     path: "/api/v1/projects/{name}/bing/connect",
@@ -21155,7 +21207,8 @@ var routeCatalog = [
   {
     method: "get",
     path: "/api/v1/projects/{name}/ga/ai-referral-history",
-    summary: "Get AI referral sessions per day grouped by source and landing page",
+    summary: "Get raw AI referral detail rows per day, landing page, and attribution dimension",
+    description: "Detail rows, not totals. One row per landing page per attribution dimension, so a single day of one source is many rows and each is commonly worth one session. Use /ga/ai-referral-daily for per-date or per-source session counts.",
     tags: ["ga4"],
     parameters: [nameParameter, analyticsWindowParameter],
     responses: {
@@ -21164,6 +21217,19 @@ var routeCatalog = [
       404: errorResponse("Project not found.")
     }
   },
+  {
+    method: "get",
+    path: "/api/v1/projects/{name}/ga/ai-referral-daily",
+    summary: "Get AI referral sessions per day and per source",
+    description: "Sums landing pages within one attribution dimension and never across dimensions, so totalSessions equals the aiSessionsDeduped reported by /ga/traffic for the same window. Sessions only: GA counts users as a distinct count at the grain requested, so an AI-referral user total cannot be summed from these rows and no un-dimensioned AI-referral fetch exists to supply one.",
+    tags: ["ga4"],
+    parameters: [nameParameter, analyticsWindowParameter],
+    responses: {
+      200: jsonResponse("AI referral daily series returned.", "GA4AiReferralDailyDto"),
+      400: errorResponse("GA4 is not connected."),
+      404: errorResponse("Project not found.")
+    }
+  },
   {
     method: "get",
     path: "/api/v1/projects/{name}/ga/social-referral-history",
@@ -28465,6 +28531,116 @@ function registerAdsActivationRoutes(app, opts) {
   });
 }
 
+// ../api-routes/src/ads-live-delivery.ts
+function liveComparisonWindow(fetchedAtMs, lookbackDays, timezone) {
+  const fetchedAtIso = new Date(fetchedAtMs).toISOString();
+  return {
+    startDate: isoDateDaysBeforeInTimeZone(fetchedAtIso, lookbackDays, timezone),
+    endDate: formatIsoDateInTimeZone(fetchedAtIso, timezone)
+  };
+}
+var EMPTY_METRIC_VALUES = {
+  impressions: 0,
+  clicks: 0,
+  spendMicros: 0,
+  conversions: 0
+};
+function presenceOf(live, stored) {
+  if (live && stored) return AdsLivePresences.both;
+  if (live) return AdsLivePresences["live-only"];
+  return AdsLivePresences["stored-only"];
+}
+function fieldDelta(field, live, stored) {
+  return live === stored ? null : { field, live, stored };
+}
+function buildFieldDeltas(live, stored) {
+  if (!live || !stored) return [];
+  const deltas = [
+    fieldDelta("status", live.status, stored.status),
+    fieldDelta("reviewStatus", live.reviewStatus, stored.reviewStatus),
+    fieldDelta("name", live.name, stored.name)
+  ];
+  return deltas.filter((delta) => delta !== null);
+}
+function foldLiveRows(rows) {
+  let values = EMPTY_METRIC_VALUES;
+  for (const row of rows) {
+    values = {
+      impressions: values.impressions + Math.round(row.impressions ?? 0),
+      clicks: values.clicks + Math.round(row.clicks ?? 0),
+      spendMicros: values.spendMicros + dollarsToMicros(row.spend ?? 0),
+      conversions: values.conversions + Math.round(row.conversions ?? 0)
+    };
+  }
+  return values;
+}
+function sameMetrics(a, b) {
+  return a.impressions === b.impressions && a.clicks === b.clicks && a.spendMicros === b.spendMicros && a.conversions === b.conversions;
+}
+function buildMetricDeltas(liveRows, storedRows, window) {
+  if (liveRows === null && storedRows === null) return null;
+  const liveByDate = /* @__PURE__ */ new Map();
+  for (const row of liveRows ?? []) {
+    if (row.date === null) continue;
+    const bucket = liveByDate.get(row.date) ?? [];
+    bucket.push(row);
+    liveByDate.set(row.date, bucket);
+  }
+  const storedByDate = /* @__PURE__ */ new Map();
+  for (const row of storedRows ?? []) {
+    if (row.date < window.startDate || row.date > window.endDate) continue;
+    storedByDate.set(row.date, row);
+  }
+  const dates = [.../* @__PURE__ */ new Set([...liveByDate.keys(), ...storedByDate.keys()])].sort();
+  return dates.map((date) => {
+    const liveBucket = liveByDate.get(date);
+    const storedRow = storedByDate.get(date);
+    const live = liveBucket ? foldLiveRows(liveBucket) : null;
+    const stored = storedRow ? {
+      impressions: storedRow.impressions,
+      clicks: storedRow.clicks,
+      spendMicros: storedRow.spendMicros,
+      conversions: storedRow.conversions
+    } : null;
+    const drifted = live === null || stored === null || !sameMetrics(live, stored);
+    return { date, live, stored, drifted };
+  });
+}
+function buildLiveEntityComparison(observation, window) {
+  const presence = presenceOf(observation.live, observation.stored);
+  const fieldDeltas = buildFieldDeltas(observation.live, observation.stored);
+  const metricDeltas = buildMetricDeltas(observation.liveMetrics, observation.storedMetrics, window);
+  const drifted = presence !== AdsLivePresences.both || fieldDeltas.length > 0 || (metricDeltas?.some((delta) => delta.drifted) ?? false);
+  return {
+    entityType: observation.entityType,
+    id: observation.id,
+    parentId: observation.parentId,
+    presence,
+    live: observation.live,
+    stored: observation.stored,
+    fieldDeltas,
+    liveMetrics: observation.liveMetrics,
+    metricDeltas,
+    drifted
+  };
+}
+function summarizeLiveDrift(entities) {
+  let driftedEntities = 0;
+  let statusDrifted = 0;
+  let metricsDrifted = 0;
+  for (const entity of entities) {
+    if (entity.drifted) driftedEntities += 1;
+    if (entity.fieldDeltas.some((delta) => delta.field === "status")) statusDrifted += 1;
+    if (entity.metricDeltas?.some((delta) => delta.drifted)) metricsDrifted += 1;
+  }
+  return {
+    entitiesCompared: entities.length,
+    driftedEntities,
+    statusDrifted,
+    metricsDrifted
+  };
+}
+
 // ../api-routes/src/ads.ts
 function runSourceDto(row) {
   const parsed = runStatusSchema.safeParse(row.status);
@@ -28599,6 +28775,12 @@ function storedActivityAssessment(snapshotStatus, rollupStatus, rollupImpression
       }
   }
 }
+var ADS_LIVE_MAX_CAMPAIGNS = 5;
+var ADS_LIVE_MAX_AD_GROUPS_PER_CAMPAIGN = 10;
+var ADS_LIVE_MAX_ADS_PER_AD_GROUP = 20;
+var ADS_LIVE_MAX_READER_CALLS = 40;
+var DEFAULT_ADS_LIVE_MAX_PAGES_PER_READER_CALL = 100;
+var DEFAULT_ADS_LIVE_DELIVERY_MIN_INTERVAL_MS = 6e4;
 var DEFAULT_RECONCILE_SWEEP_INTERVAL_MS = 6e4;
 var DEFAULT_RECONCILE_PENDING_STALE_MS = 5 * 6e4;
 var DEFAULT_RECONCILE_BACKOFF_BASE_MS = 5 * 6e4;
@@ -28961,6 +29143,47 @@ async function executeAdsRead(surface, read) {
     });
   }
 }
+function resolveAdsLiveDeliveryReader(opts, projectName) {
+  const apiKey = opts.adsCredentialStore?.getConnection(projectName)?.apiKey;
+  if (!apiKey) {
+    throw validationError("No OpenAI Ads API key configured for this project");
+  }
+  if (!opts.adsLiveDeliveryReader) {
+    throw validationError("Ads live delivery reads are not configured for this deployment");
+  }
+  return { apiKey, reader: opts.adsLiveDeliveryReader };
+}
+function upstreamStatusOf(error) {
+  return typeof error === "object" && error !== null && "status" in error && typeof error.status === "number" && Number.isInteger(error.status) ? error.status : null;
+}
+function liveReadFailure(surface, entityId, error) {
+  return { surface, entityId, upstreamStatus: upstreamStatusOf(error) };
+}
+function liveReadProviderError(surface, error) {
+  const upstreamStatus = upstreamStatusOf(error);
+  return providerError(
+    `OpenAI Ads API ${surface} read failed`,
+    upstreamStatus === null ? void 0 : { upstreamStatus }
+  );
+}
+function liveEntityState(entity) {
+  return {
+    name: entity.name,
+    status: entity.status,
+    reviewStatus: entity.reviewStatus,
+    mode: entity.mode,
+    updatedAt: entity.updatedAt
+  };
+}
+function storedEntityState(row) {
+  return {
+    name: row.name,
+    status: row.status,
+    reviewStatus: row.reviewStatus ?? null,
+    upstreamUpdatedAt: row.upstreamUpdatedAt,
+    syncedAt: row.syncedAt
+  };
+}
 async function executeAdsOperation(app, request, input) {
   const hash = requestHash({ kind: input.kind, entityType: input.entityType, payload: input.payload });
   const existing = readOperationByKey(app, input.projectId, input.operationKey);
@@ -29599,6 +29822,21 @@ async function adsRoutes(app, opts) {
     opts.adsAccountVerificationCacheTtlMs ?? DEFAULT_ADS_ACCOUNT_VERIFICATION_CACHE_TTL_MS
   );
   const verificationCache = /* @__PURE__ */ new Map();
+  const liveDeliveryMinIntervalMs = Math.max(
+    0,
+    opts.adsLiveDeliveryMinIntervalMs ?? DEFAULT_ADS_LIVE_DELIVERY_MIN_INTERVAL_MS
+  );
+  const liveDeliveryMaxPagesPerReaderCall = Math.max(
+    1,
+    opts.adsLiveDeliveryMaxPagesPerReaderCall ?? DEFAULT_ADS_LIVE_MAX_PAGES_PER_READER_CALL
+  );
+  const liveDeliveryInFlight = /* @__PURE__ */ new Set();
+  const liveDeliveryLastAttemptAtMs = /* @__PURE__ */ new Map();
+  const pruneLiveDeliveryAttempts = (nowMs) => {
+    for (const [projectId, lastAtMs] of liveDeliveryLastAttemptAtMs) {
+      if (nowMs - lastAtMs >= liveDeliveryMinIntervalMs) liveDeliveryLastAttemptAtMs.delete(projectId);
+    }
+  };
   const reconcilePolicy = {
     pendingMinIdleMs: pendingStaleMs,
     backoffBaseMs,
@@ -30378,6 +30616,264 @@ async function adsRoutes(app, opts) {
     };
     return response;
   });
+  app.get("/projects/:name/ads/live-delivery", async (request) => {
+    const project = resolveProject(app.db, request.params.name);
+    const parsed = adsLiveDeliveryQuerySchema.safeParse(request.query);
+    if (!parsed.success) {
+      throw validationError("Invalid ads live delivery query", { issues: parsed.error.issues });
+    }
+    const { campaignId, lookbackDays } = parsed.data;
+    const connection = app.db.select().from(adsConnections).where(eq28(adsConnections.projectId, project.id)).get();
+    if (!connection) {
+      throw validationError('No ads connection for this project. Run "canonry ads connect" first.');
+    }
+    const { apiKey, reader } = resolveAdsLiveDeliveryReader(opts, project.name);
+    const verifyAdsAccount = opts.verifyAdsAccount;
+    if (!verifyAdsAccount) {
+      throw validationError("Ads account verification is not configured for this deployment");
+    }
+    const fetchedAtMs = Date.now();
+    const lastAttemptAtMs = liveDeliveryLastAttemptAtMs.get(project.id);
+    const remainingIntervalMs = liveDeliveryMinIntervalMs > 0 && lastAttemptAtMs !== void 0 ? lastAttemptAtMs + liveDeliveryMinIntervalMs - fetchedAtMs : 0;
+    if (liveDeliveryInFlight.has(project.id)) {
+      throw quotaExceeded("OpenAI Ads live delivery reads", {
+        reason: "read-in-flight",
+        minIntervalMs: liveDeliveryMinIntervalMs,
+        // A LOWER bound, and only when the interval itself still blocks. How
+        // much longer the running walk needs is unknowable from here, so once
+        // it has outlived the interval there is no honest number to give and
+        // the field is absent rather than guessed.
+        ...remainingIntervalMs > 0 ? { retryAfterMs: remainingIntervalMs } : {}
+      });
+    }
+    if (remainingIntervalMs > 0) {
+      throw quotaExceeded("OpenAI Ads live delivery reads", {
+        reason: "min-interval",
+        minIntervalMs: liveDeliveryMinIntervalMs,
+        retryAfterMs: remainingIntervalMs
+      });
+    }
+    liveDeliveryInFlight.add(project.id);
+    const spendLiveDeliveryAttempt = () => {
+      if (liveDeliveryMinIntervalMs <= 0) return;
+      pruneLiveDeliveryAttempts(fetchedAtMs);
+      liveDeliveryLastAttemptAtMs.set(project.id, fetchedAtMs);
+    };
+    try {
+      let readerCalls = 0;
+      let truncated = false;
+      const errors = [];
+      const callProvider = async (surface, entityId, run) => {
+        if (readerCalls >= ADS_LIVE_MAX_READER_CALLS) {
+          truncated = true;
+          return null;
+        }
+        readerCalls += 1;
+        try {
+          return await run();
+        } catch (error) {
+          errors.push(liveReadFailure(surface, entityId, error));
+          return null;
+        }
+      };
+      readerCalls += 1;
+      let account;
+      spendLiveDeliveryAttempt();
+      try {
+        account = await verifyAdsAccount(apiKey);
+      } catch (error) {
+        throw liveReadProviderError("account identity", error);
+      }
+      if (account.id !== connection.adAccountId) {
+        throw validationError("The configured key belongs to a different OpenAI ad account; reconnect this project");
+      }
+      readerCalls += 1;
+      let liveCampaigns;
+      try {
+        liveCampaigns = await reader.listCampaigns(apiKey);
+      } catch (error) {
+        throw liveReadProviderError("campaign list", error);
+      }
+      const scopedCampaigns = campaignId === void 0 ? liveCampaigns : liveCampaigns.filter((campaign) => campaign.id === campaignId);
+      if (scopedCampaigns.length > ADS_LIVE_MAX_CAMPAIGNS) truncated = true;
+      const walkedCampaigns = scopedCampaigns.slice(0, ADS_LIVE_MAX_CAMPAIGNS);
+      const storedCampaignRows = app.db.select().from(adsCampaigns).where(and22(
+        eq28(adsCampaigns.projectId, project.id),
+        campaignId === void 0 ? void 0 : eq28(adsCampaigns.id, campaignId)
+      )).all();
+      const storedAdGroupRows = app.db.select().from(adsAdGroups).where(and22(
+        eq28(adsAdGroups.projectId, project.id),
+        campaignId === void 0 ? void 0 : eq28(adsAdGroups.campaignId, campaignId)
+      )).all();
+      const storedAdGroupIds = new Set(storedAdGroupRows.map((row) => row.id));
+      const storedAdRows = app.db.select().from(adsAds).where(eq28(adsAds.projectId, project.id)).all().filter((row) => campaignId === void 0 || storedAdGroupIds.has(row.adGroupId));
+      const storedInsightRows = app.db.select({
+        level: adsInsightsDaily.level,
+        entityId: adsInsightsDaily.entityId,
+        date: adsInsightsDaily.date,
+        impressions: adsInsightsDaily.impressions,
+        clicks: adsInsightsDaily.clicks,
+        spendMicros: adsInsightsDaily.spendMicros,
+        conversions: adsInsightsDaily.conversions
+      }).from(adsInsightsDaily).where(eq28(adsInsightsDaily.projectId, project.id)).all();
+      const storedCampaignById = new Map(storedCampaignRows.map((row) => [row.id, row]));
+      const storedAdGroupById = new Map(storedAdGroupRows.map((row) => [row.id, row]));
+      const storedAdById = new Map(storedAdRows.map((row) => [row.id, row]));
+      const storedMetricsByEntity = /* @__PURE__ */ new Map();
+      for (const row of storedInsightRows) {
+        const key = `${row.level}:${row.entityId}`;
+        const bucket = storedMetricsByEntity.get(key) ?? [];
+        bucket.push({
+          date: row.date,
+          impressions: row.impressions,
+          clicks: row.clicks,
+          spendMicros: row.spendMicros,
+          conversions: row.conversions
+        });
+        storedMetricsByEntity.set(key, bucket);
+      }
+      const storedMetricsFor = (level, entityId) => storedMetricsByEntity.get(`${level}:${entityId}`) ?? [];
+      const accountTimezone = account.timezone ?? "UTC";
+      const window = liveComparisonWindow(fetchedAtMs, lookbackDays, accountTimezone);
+      const insightsRequest = {
+        startDate: window.startDate,
+        fetchedAtMs,
+        timezone: accountTimezone
+      };
+      const observations = [];
+      const walkedCampaignIds = /* @__PURE__ */ new Set();
+      const walkedAdGroupIds = /* @__PURE__ */ new Set();
+      const walkedAdIds = /* @__PURE__ */ new Set();
+      for (const campaign of walkedCampaigns) {
+        walkedCampaignIds.add(campaign.id);
+        const campaignMetrics = await callProvider(
+          "campaign insights",
+          campaign.id,
+          () => reader.campaignInsights(apiKey, campaign.id, insightsRequest)
+        );
+        observations.push({
+          entityType: AdsLiveEntityTypes.campaign,
+          id: campaign.id,
+          parentId: null,
+          live: liveEntityState(campaign),
+          stored: storedCampaignById.has(campaign.id) ? storedEntityState(storedCampaignById.get(campaign.id)) : null,
+          // A metrics call that did not happen is not evidence about metrics, so
+          // both sides stay null and no delta is claimed.
+          liveMetrics: campaignMetrics,
+          storedMetrics: campaignMetrics === null ? null : storedMetricsFor(AdsInsightLevels.campaign, campaign.id)
+        });
+        const liveAdGroups = await callProvider(
+          "ad group list",
+          campaign.id,
+          () => reader.listAdGroups(apiKey, campaign.id)
+        );
+        if (liveAdGroups === null) continue;
+        if (liveAdGroups.length > ADS_LIVE_MAX_AD_GROUPS_PER_CAMPAIGN) truncated = true;
+        for (const adGroup of liveAdGroups.slice(0, ADS_LIVE_MAX_AD_GROUPS_PER_CAMPAIGN)) {
+          walkedAdGroupIds.add(adGroup.id);
+          const adGroupMetrics = await callProvider(
+            "ad group insights",
+            adGroup.id,
+            () => reader.adGroupInsights(apiKey, adGroup.id, insightsRequest)
+          );
+          observations.push({
+            entityType: AdsLiveEntityTypes.ad_group,
+            id: adGroup.id,
+            parentId: campaign.id,
+            live: liveEntityState(adGroup),
+            stored: storedAdGroupById.has(adGroup.id) ? storedEntityState(storedAdGroupById.get(adGroup.id)) : null,
+            liveMetrics: adGroupMetrics,
+            storedMetrics: adGroupMetrics === null ? null : storedMetricsFor(AdsInsightLevels.ad_group, adGroup.id)
+          });
+          const liveAds = await callProvider(
+            "ad list",
+            adGroup.id,
+            () => reader.listAds(apiKey, adGroup.id)
+          );
+          if (liveAds === null) continue;
+          if (liveAds.length > ADS_LIVE_MAX_ADS_PER_AD_GROUP) truncated = true;
+          for (const ad of liveAds.slice(0, ADS_LIVE_MAX_ADS_PER_AD_GROUP)) {
+            walkedAdIds.add(ad.id);
+            observations.push({
+              entityType: AdsLiveEntityTypes.ad,
+              id: ad.id,
+              parentId: adGroup.id,
+              live: liveEntityState(ad),
+              stored: storedAdById.has(ad.id) ? storedEntityState(storedAdById.get(ad.id)) : null,
+              // The provider has no per-ad insights surface (same reason ads-sync
+              // stores no ad-level rollups), so ads carry status evidence only.
+              liveMetrics: null,
+              storedMetrics: null
+            });
+          }
+        }
+      }
+      if (!truncated && errors.length === 0) {
+        for (const row of storedCampaignRows) {
+          if (walkedCampaignIds.has(row.id)) continue;
+          observations.push({
+            entityType: AdsLiveEntityTypes.campaign,
+            id: row.id,
+            parentId: null,
+            live: null,
+            stored: storedEntityState(row),
+            liveMetrics: null,
+            storedMetrics: null
+          });
+        }
+        for (const row of storedAdGroupRows) {
+          if (walkedAdGroupIds.has(row.id)) continue;
+          observations.push({
+            entityType: AdsLiveEntityTypes.ad_group,
+            id: row.id,
+            parentId: row.campaignId,
+            live: null,
+            stored: storedEntityState(row),
+            liveMetrics: null,
+            storedMetrics: null
+          });
+        }
+        for (const row of storedAdRows) {
+          if (walkedAdIds.has(row.id)) continue;
+          observations.push({
+            entityType: AdsLiveEntityTypes.ad,
+            id: row.id,
+            parentId: row.adGroupId,
+            live: null,
+            stored: storedEntityState(row),
+            liveMetrics: null,
+            storedMetrics: null
+          });
+        }
+      }
+      const entities = observations.map(
+        (observation) => buildLiveEntityComparison(observation, window)
+      );
+      const response = {
+        basis: AdsLiveDeliveryBases.liveProviderRead,
+        fetchedAt: new Date(fetchedAtMs).toISOString(),
+        adAccountId: account.id,
+        storedSnapshotSyncedAt: connection.lastSyncedAt ?? null,
+        metricsWindow: { lookbackDays },
+        bounds: {
+          maxCampaigns: ADS_LIVE_MAX_CAMPAIGNS,
+          maxAdGroupsPerCampaign: ADS_LIVE_MAX_AD_GROUPS_PER_CAMPAIGN,
+          maxAdsPerAdGroup: ADS_LIVE_MAX_ADS_PER_AD_GROUP,
+          maxReaderCalls: ADS_LIVE_MAX_READER_CALLS,
+          readerCalls,
+          maxPagesPerReaderCall: liveDeliveryMaxPagesPerReaderCall,
+          maxUpstreamHttpRequests: ADS_LIVE_MAX_READER_CALLS * liveDeliveryMaxPagesPerReaderCall,
+          truncated
+        },
+        entities,
+        drift: summarizeLiveDrift(entities),
+        errors
+      };
+      return response;
+    } finally {
+      liveDeliveryInFlight.delete(project.id);
+    }
+  });
   app.get("/projects/:name/ads/summary", async (request) => {
     const project = resolveProject(app.db, request.params.name);
     const row = app.db.select().from(adsConnections).where(eq28(adsConnections.projectId, project.id)).get();
@@ -31322,6 +31818,160 @@ function buildSessionHistory(landingPageDays, dailyTotals) {
   });
 }
 
+// ../api-routes/src/ga-ai-referral-aggregation.ts
+function normalizeAiTrafficClass(value) {
+  return value === AiReferralTrafficClasses.paid ? AiReferralTrafficClasses.paid : AiReferralTrafficClasses.organic;
+}
+function emptyAiCounts() {
+  return { sessions: 0, users: 0 };
+}
+function resolveWinningDimensions(rows) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const key = `${row.date}\0${row.source}\0${row.medium}`;
+    let group = groups.get(key);
+    if (!group) {
+      group = { date: row.date, source: row.source, medium: row.medium, byDimension: /* @__PURE__ */ new Map() };
+      groups.set(key, group);
+    }
+    let dim = group.byDimension.get(row.sourceDimension);
+    if (!dim) {
+      dim = { paidSessions: 0, organicSessions: 0 };
+      group.byDimension.set(row.sourceDimension, dim);
+    }
+    const sessions = row.sessions ?? 0;
+    if (normalizeAiTrafficClass(row.trafficClass) === AiReferralTrafficClasses.paid) {
+      dim.paidSessions += sessions;
+    } else {
+      dim.organicSessions += sessions;
+    }
+  }
+  const winners = [];
+  for (const group of groups.values()) {
+    const dims = [...group.byDimension.values()];
+    const bestSessions = dims.reduce((best, d) => d.paidSessions + d.organicSessions > best.paidSessions + best.organicSessions ? d : best);
+    winners.push({
+      date: group.date,
+      source: group.source,
+      medium: group.medium,
+      paidSessions: bestSessions.paidSessions,
+      organicSessions: bestSessions.organicSessions
+    });
+  }
+  return winners;
+}
+function resolveLegacyWinningUsers(rows) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const key = `${row.date}\0${row.source}\0${row.medium}`;
+    let byDimension = groups.get(key);
+    if (!byDimension) {
+      byDimension = /* @__PURE__ */ new Map();
+      groups.set(key, byDimension);
+    }
+    let dim = byDimension.get(row.sourceDimension);
+    if (!dim) {
+      dim = { paidUsers: 0, organicUsers: 0 };
+      byDimension.set(row.sourceDimension, dim);
+    }
+    const users = row.users ?? 0;
+    if (normalizeAiTrafficClass(row.trafficClass) === AiReferralTrafficClasses.paid) {
+      dim.paidUsers += users;
+    } else {
+      dim.organicUsers += users;
+    }
+  }
+  let paidUsers = 0;
+  let organicUsers = 0;
+  for (const byDimension of groups.values()) {
+    const dims = [...byDimension.values()];
+    const best = dims.reduce((winner, d) => d.paidUsers + d.organicUsers > winner.paidUsers + winner.organicUsers ? d : winner);
+    paidUsers += best.paidUsers;
+    organicUsers += best.organicUsers;
+  }
+  return { paidUsers, organicUsers };
+}
+function summarizeAiReferralCounts(rows) {
+  const paidDeduped = emptyAiCounts();
+  const organicDeduped = emptyAiCounts();
+  const paidBySession = emptyAiCounts();
+  const organicBySession = emptyAiCounts();
+  const bySessionChannelGroup = /* @__PURE__ */ new Map();
+  for (const winner of resolveWinningDimensions(rows)) {
+    paidDeduped.sessions += winner.paidSessions;
+    organicDeduped.sessions += winner.organicSessions;
+  }
+  const legacyUsers = resolveLegacyWinningUsers(rows);
+  paidDeduped.users = legacyUsers.paidUsers;
+  organicDeduped.users = legacyUsers.organicUsers;
+  for (const row of rows) {
+    if (row.sourceDimension !== "session") continue;
+    const sessions = row.sessions ?? 0;
+    const users = row.users ?? 0;
+    bySessionChannelGroup.set(
+      row.channelGroup,
+      (bySessionChannelGroup.get(row.channelGroup) ?? 0) + sessions
+    );
+    const bucket = normalizeAiTrafficClass(row.trafficClass) === AiReferralTrafficClasses.paid ? paidBySession : organicBySession;
+    bucket.sessions += sessions;
+    bucket.users += users;
+  }
+  return {
+    paidDeduped,
+    organicDeduped,
+    paidBySession,
+    organicBySession,
+    bySessionChannelGroup,
+    deduped: {
+      sessions: paidDeduped.sessions + organicDeduped.sessions,
+      users: paidDeduped.users + organicDeduped.users
+    },
+    bySession: {
+      sessions: paidBySession.sessions + organicBySession.sessions,
+      users: paidBySession.users + organicBySession.users
+    }
+  };
+}
+function buildAiReferralDailySeries(rows) {
+  const byDate = /* @__PURE__ */ new Map();
+  const sourceTotals = /* @__PURE__ */ new Map();
+  let totalSessions = 0;
+  let totalPaidSessions = 0;
+  let totalOrganicSessions = 0;
+  for (const winner of resolveWinningDimensions(rows)) {
+    const sessions = winner.paidSessions + winner.organicSessions;
+    let bySource = byDate.get(winner.date);
+    if (!bySource) {
+      bySource = /* @__PURE__ */ new Map();
+      byDate.set(winner.date, bySource);
+    }
+    let bucket = bySource.get(winner.source);
+    if (!bucket) {
+      bucket = { source: winner.source, sessions: 0, paidSessions: 0, organicSessions: 0 };
+      bySource.set(winner.source, bucket);
+    }
+    bucket.sessions += sessions;
+    bucket.paidSessions += winner.paidSessions;
+    bucket.organicSessions += winner.organicSessions;
+    sourceTotals.set(winner.source, (sourceTotals.get(winner.source) ?? 0) + sessions);
+    totalSessions += sessions;
+    totalPaidSessions += winner.paidSessions;
+    totalOrganicSessions += winner.organicSessions;
+  }
+  const days = [...byDate.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([date, bySource]) => {
+    const sources2 = [...bySource.values()].sort((a, b) => b.sessions - a.sessions || a.source.localeCompare(b.source));
+    return {
+      date,
+      sessions: sources2.reduce((sum, s) => sum + s.sessions, 0),
+      paidSessions: sources2.reduce((sum, s) => sum + s.paidSessions, 0),
+      organicSessions: sources2.reduce((sum, s) => sum + s.organicSessions, 0),
+      bySource: sources2
+    };
+  });
+  const sources = [...sourceTotals.entries()].sort(([aSource, aSessions], [bSource, bSessions]) => bSessions - aSessions || aSource.localeCompare(bSource)).map(([source]) => source);
+  return { days, sources, totalSessions, totalPaidSessions, totalOrganicSessions };
+}
+
 // ../api-routes/src/ga.ts
 function gaLog(level, action, ctx) {
   const entry = { ts: (/* @__PURE__ */ new Date()).toISOString(), level, module: "GA4Routes", action, ...ctx };
@@ -31378,12 +32028,6 @@ function pickWinningDimension(rows, tupleKey) {
   }
   return [...winners.values()].sort((a, b) => (b.sessions ?? 0) - (a.sessions ?? 0));
 }
-function normalizeAiTrafficClass(value) {
-  return value === AiReferralTrafficClasses.paid ? AiReferralTrafficClasses.paid : AiReferralTrafficClasses.organic;
-}
-function emptyAiCounts() {
-  return { sessions: 0, users: 0 };
-}
 function persistAcquisitionMeasurement(db, input) {
   const { startDate, endDate } = input.report;
   db.transaction((tx) => {
@@ -31512,70 +32156,6 @@ function persistMeasurementError(db, projectId, component, message, updatedAt) {
     }
   }).run();
 }
-function summarizeAiReferralCounts(rows) {
-  const dedupeGroups = /* @__PURE__ */ new Map();
-  const bySessionChannelGroup = /* @__PURE__ */ new Map();
-  const paidDeduped = emptyAiCounts();
-  const organicDeduped = emptyAiCounts();
-  const paidBySession = emptyAiCounts();
-  const organicBySession = emptyAiCounts();
-  for (const row of rows) {
-    const isPaid = normalizeAiTrafficClass(row.trafficClass) === AiReferralTrafficClasses.paid;
-    const sessions = row.sessions ?? 0;
-    const users = row.users ?? 0;
-    const key = `${row.date}\0${row.source}\0${row.medium}`;
-    let byDimension = dedupeGroups.get(key);
-    if (!byDimension) {
-      byDimension = /* @__PURE__ */ new Map();
-      dedupeGroups.set(key, byDimension);
-    }
-    let dim = byDimension.get(row.sourceDimension);
-    if (!dim) {
-      dim = { paidSessions: 0, organicSessions: 0, paidUsers: 0, organicUsers: 0 };
-      byDimension.set(row.sourceDimension, dim);
-    }
-    if (isPaid) {
-      dim.paidSessions += sessions;
-      dim.paidUsers += users;
-    } else {
-      dim.organicSessions += sessions;
-      dim.organicUsers += users;
-    }
-    if (row.sourceDimension === "session") {
-      bySessionChannelGroup.set(
-        row.channelGroup,
-        (bySessionChannelGroup.get(row.channelGroup) ?? 0) + sessions
-      );
-      const sessionBucket = isPaid ? paidBySession : organicBySession;
-      sessionBucket.sessions += sessions;
-      sessionBucket.users += users;
-    }
-  }
-  for (const byDimension of dedupeGroups.values()) {
-    const dims = [...byDimension.values()];
-    const bestSessions = dims.reduce((best, d) => d.paidSessions + d.organicSessions > best.paidSessions + best.organicSessions ? d : best);
-    const bestUsers = dims.reduce((best, d) => d.paidUsers + d.organicUsers > best.paidUsers + best.organicUsers ? d : best);
-    paidDeduped.sessions += bestSessions.paidSessions;
-    organicDeduped.sessions += bestSessions.organicSessions;
-    paidDeduped.users += bestUsers.paidUsers;
-    organicDeduped.users += bestUsers.organicUsers;
-  }
-  return {
-    paidDeduped,
-    organicDeduped,
-    paidBySession,
-    organicBySession,
-    bySessionChannelGroup,
-    deduped: {
-      sessions: paidDeduped.sessions + organicDeduped.sessions,
-      users: paidDeduped.users + organicDeduped.users
-    },
-    bySession: {
-      sessions: paidBySession.sessions + organicBySession.sessions,
-      users: paidBySession.users + organicBySession.users
-    }
-  };
-}
 async function refreshOAuthTokenIfNeeded(googleStore, authConfig, canonicalDomain, oauthConn) {
   const expiresAt = oauthConn.tokenExpiresAt ? new Date(oauthConn.tokenExpiresAt).getTime() : 0;
   const fiveMinutes = 5 * 60 * 1e3;
@@ -32277,6 +32857,23 @@ async function ga4Routes(app, opts) {
     ).orderBy(gaAiReferrals.date).all();
     return rows;
   });
+  app.get("/projects/:name/ga/ai-referral-daily", async (request, _reply) => {
+    const project = resolveProject(app.db, request.params.name);
+    requireGa4Connection(opts, project.name, project.canonicalDomain);
+    const cutoffDate = windowCutoff(parseWindow(request.query.window))?.slice(0, 10) ?? null;
+    const conditions = [eq31(gaAiReferrals.projectId, project.id)];
+    if (cutoffDate) conditions.push(sql15`${gaAiReferrals.date} >= ${cutoffDate}`);
+    const rows = app.db.select({
+      date: gaAiReferrals.date,
+      source: gaAiReferrals.source,
+      medium: gaAiReferrals.medium,
+      trafficClass: gaAiReferrals.trafficClass,
+      sourceDimension: gaAiReferrals.sourceDimension,
+      channelGroup: gaAiReferrals.channelGroup,
+      sessions: gaAiReferrals.sessions
+    }).from(gaAiReferrals).where(and25(...conditions)).all();
+    return buildAiReferralDailySeries(rows);
+  });
   app.get("/projects/:name/ga/social-referral-history", async (request, _reply) => {
     const project = resolveProject(app.db, request.params.name);
     requireGa4Connection(opts, project.name, project.canonicalDomain);
@@ -43406,7 +44003,7 @@ function serializeRun(row) {
   return { id: row.id, projectId: row.projectId, status: row.status, provider: row.provider, requestedModel: row.requestedModel, resolvedModel: row.resolvedModel, location: row.location ?? null, totalQueries: row.totalQueries, completedQueries: row.completedQueries, failedQueries: row.failedQueries, error: row.error, startedAt: row.startedAt, finishedAt: row.finishedAt, createdAt: row.createdAt };
 }
 function serializeQuery(row) {
-  return { id: row.id, position: row.position, query: row.queryText, status: row.status, requestedModel: row.requestedModel, resolvedModel: row.resolvedModel, servedModel: row.servedModel, answerText: row.answerText, groundingSources: row.groundingSources, citedDomains: row.citedDomains, searchQueries: row.searchQueries, answerMentioned: row.answerMentioned, citationState: row.citationState, error: row.error, startedAt: row.startedAt, finishedAt: row.finishedAt, createdAt: row.createdAt };
+  return { id: row.id, position: row.position, query: row.queryText, status: row.status, requestedModel: row.requestedModel, resolvedModel: row.resolvedModel, servedModel: row.servedModel, answerText: row.answerText, groundingSources: row.groundingSources, citedDomains: row.citedDomains, searchQueries: row.searchQueries, namedCompetitors: row.namedCompetitors, citedCompetitorDomains: row.citedCompetitorDomains, answerMentioned: row.answerMentioned, citationState: row.citationState, error: row.error, startedAt: row.startedAt, finishedAt: row.finishedAt, createdAt: row.createdAt };
 }
 
 // ../api-routes/src/index.ts
@@ -43527,6 +44124,9 @@ async function apiRoutes(app, opts) {
       adsCredentialStore: opts.adsCredentialStore,
       verifyAdsAccount: opts.verifyAdsAccount,
       adsReader: opts.adsReader,
+      adsLiveDeliveryReader: opts.adsLiveDeliveryReader,
+      adsLiveDeliveryMinIntervalMs: opts.adsLiveDeliveryMinIntervalMs,
+      adsLiveDeliveryMaxPagesPerReaderCall: opts.adsLiveDeliveryMaxPagesPerReaderCall,
       onAdsSyncRequested: opts.onAdsSyncRequested,
       adsOperator: opts.adsOperator,
       adsReconcileSweepIntervalMs: opts.adsReconcileSweepIntervalMs,
@@ -43870,6 +44470,15 @@ function computeCompetitorOverlap(normalized, competitorDomains) {
   }
   return [...overlapSet];
 }
+function computeCitedCompetitorDomains(citedDomains, competitorDomains) {
+  const citedCompetitors = /* @__PURE__ */ new Set();
+  for (const citedDomain of citedDomains) {
+    for (const competitorDomain of competitorDomains) {
+      if (domainMatches(citedDomain, competitorDomain)) citedCompetitors.add(competitorDomain);
+    }
+  }
+  return [...citedCompetitors];
+}
 function escapeRegExp5(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
@@ -43930,7 +44539,7 @@ function extractRecommendedCompetitors(answerText, ownDomains, citedDomains, com
   for (const pattern of candidatePatterns) {
     let match;
     while ((match = pattern.exec(answerText)) !== null) {
-      const candidate = cleanCandidateName(match[1] ?? "");
+      const candidate = cleanCandidateName(match[1]);
       const candidateKey = brandKeyFromText(candidate);
       if (!candidateKey) continue;
       if (genericKeys.has(candidateKey)) continue;
@@ -44645,6 +45254,7 @@ export {
   classifyAiUserFetch,
   determineCitationState,
   computeCompetitorOverlap,
+  computeCitedCompetitorDomains,
   extractRecommendedCompetitors,
   getPlaceDetails,
   hashPlaceDetails,