@canonry/canonry 5.12.0 → 5.14.0

package/dist/{chunk-KBSAEALE.js → chunk-S6LJSUZO.js}

@@ -17,12 +17,12 @@ import {
   resolveOperatorApiKeyIds,
   runWithUsageTags,
   saveConfigPatch
-} from "./chunk-WJGUBZSW.js";
+} from "./chunk-2W6GCJ3O.js";
 import {
   deleteSiteCrawlGraphLayout,
   persistSiteCrawlGraphLayout,
   prepareSiteCrawlGraphLayout
-} from "./chunk-LWGYRN3T.js";
+} from "./chunk-4LPV6ZZY.js";
 import {
   PACKAGE_VERSION
 } from "./chunk-AOJU5LKX.js";
@@ -73,6 +73,7 @@ import {
   createCredentialChecker,
   createFastifyLogger,
   createLogger,
+  createRunCompetitorResolver,
   createUserSession,
   deliverWebhook,
   determineCitationState,
@@ -134,7 +135,10 @@ import {
   loadDuckdb,
   markSessionFailed,
   measurementRunCompleteness,
+  measurementRunSlotState,
+  measurementSlotKey,
   migrate,
+  newerFullSweep,
   nextRunFromCron,
   nextRunFromSchedule,
   notifications,
@@ -164,6 +168,7 @@ import {
   resolveVercelSyncDeadlineMs,
   resolveWebhookTarget,
   runChecks,
+  runFills,
   runs,
   schedules,
   serializeUserSessionCookie,
@@ -179,7 +184,7 @@ import {
   siteLivenessState,
   toAlertView,
   usageCounters
-} from "./chunk-DOC4QQLS.js";
+} from "./chunk-RGMUT5KY.js";
 import {
   AGENT_MEMORY_VALUE_MAX_BYTES,
   AGENT_NONE,
@@ -211,6 +216,7 @@ import {
   ONBOARDING_FLOW_VERSION,
   ProviderNames,
   ROUTE_CAPABLE_CITED_URL_PROVIDERS,
+  RUN_FILL_PROVIDER_BREAKER,
   ResearchQueryStatuses,
   ResearchRunStatuses,
   RunKinds,
@@ -272,6 +278,7 @@ import {
   filterCapturedCitedUrls,
   forbidden,
   formatIsoDateInTimeZone,
+  formatRunErrorOneLine,
   frameAncestorsHeaderValue,
   googleAdsAccessibleCustomerDtoSchema,
   googleAdsAccessibleCustomersResponseSchema,
@@ -313,6 +320,7 @@ import {
   observeTemplateLinkEdges,
   parseMeasurementRunManifestV1,
   parseOriginList,
+  parseRunError,
   providerError,
   providerSupportsLocationContext,
   registrableDomain,
@@ -337,7 +345,7 @@ import {
   visibilityReportRequestSchema,
   winnabilityClassLabel,
   withRetry
-} from "./chunk-NYRRWWEE.js";
+} from "./chunk-45EGDRVF.js";
 
 // src/runtime-context.ts
 function cliRuntimeContext(env = process.env, stdio = process) {
@@ -6483,7 +6491,7 @@ function nonBlank(value) {
   return trimmed ? trimmed : void 0;
 }
 function resolveBuildCommit(env = process.env) {
-  const embedded = true ? "3cbbec137ff9c498f0b59f30a5e2b84c99af6f40" : void 0;
+  const embedded = true ? "f4648ef75d44ebb5a3396cf05739a56a4aa2b7ee" : void 0;
   return nonBlank(embedded) ?? nonBlank(env.CANONRY_COMMIT);
 }
 function resolveInstanceIdentity(env = process.env) {
@@ -6831,6 +6839,8 @@ var JobRunner = class {
     this.registry = registry;
   }
   recoverStaleRuns() {
+    const staleFills = this.db.update(runFills).set({ status: "failed", finishedAt: (/* @__PURE__ */ new Date()).toISOString(), error: "Server restarted while the fill was in progress" }).where(inArray(runFills.status, ["queued", "running"])).run();
+    if (staleFills.changes > 0) log2.warn("fill.recovered-stale", { count: staleFills.changes });
     const stale = this.db.select({
       id: runs.id,
       projectId: runs.projectId,
@@ -6956,7 +6966,8 @@ var JobRunner = class {
       }
       log2.info("run.dispatch", { runId, providerCount: activeProviders.length, providers: activeProviders.map((p) => p.adapter.name) });
       const projectCompetitors = this.db.select().from(competitors).where(eq2(competitors.projectId, projectId)).all();
-      const competitorDomains = projectCompetitors.map((c) => c.domain);
+      const runCompetitors = createRunCompetitorResolver(this.db, projectCompetitors.map((c) => c.domain))(existingRun.measurementPlanVersionId);
+      const competitorDomains = runCompetitors.domains;
       const allDomains = effectiveDomains({
         canonicalDomain: project.canonicalDomain,
         ownedDomains: project.ownedDomains
@@ -7156,146 +7167,20 @@ var JobRunner = class {
           }
         }
       };
-      const processNodeForProvider = async (registeredProvider, unit) => {
-        const { adapter, config: providerConfig } = registeredProvider;
-        const providerName = adapter.name;
-        const gate = executionGates.get(providerName);
-        if (!gate) {
-          throw new Error(`Missing execution gate for provider ${providerName}`);
-        }
-        const config = unit.requestedModel ? { ...providerConfig, model: unit.requestedModel } : providerConfig;
-        const requestedContext = unit.context;
-        const supportedContext = requestedContext && providerSupportsLocationContext(adapter) ? { status: "applied", resolved: requestedContext } : null;
-        try {
-          await gate.run(async () => {
-            this.throwIfRunCancelled(runId);
-            providerDispatchCounts.set(providerName, (providerDispatchCounts.get(providerName) ?? 0) + 1);
-            const raw = await adapter.executeTrackedQuery(
-              {
-                query: unit.queryText,
-                canonicalDomains: allDomains,
-                competitorDomains,
-                location: requestedContext ?? void 0
-              },
-              config
-            );
-            this.throwIfRunCancelled(runId);
-            const providerResult = adapter.normalizeResult(raw);
-            const rawGroundingSources = providerResult.groundingSources;
-            const normalized = {
-              ...providerResult,
-              groundingSources: Array.isArray(rawGroundingSources) ? rawGroundingSources : []
-            };
-            let citedUrlCapture;
-            try {
-              citedUrlCapture = await captureCitedUrls(providerName, rawGroundingSources);
-            } catch (err) {
-              citedUrlCapture = {
-                citedUrls: [],
-                captureStatus: "failed",
-                sourceCount: normalized.groundingSources.length,
-                resolvedCount: 0,
-                captureVersion: CITED_URL_CAPTURE_VERSION
-              };
-              log2.warn("query.cited-url-capture-failed", {
-                runId,
-                provider: providerName,
-                query: unit.queryText,
-                error: describeError(err)
-              });
-            }
-            this.throwIfRunCancelled(runId);
-            const citationState = determineCitationState(normalized, allDomains);
-            const answerMentioned = determineAnswerMentioned(
-              normalized.answerText,
-              allBrandNames,
-              allDomains
-            );
-            const overlap = computeCompetitorOverlap(normalized, competitorDomains);
-            const extractedCompetitors = extractRecommendedCompetitors(
-              normalized.answerText,
-              allDomains,
-              normalized.citedDomains,
-              competitorDomains,
-              allBrandNames
-            );
-            const snapshotId = crypto6.randomUUID();
-            let screenshotRelPath = null;
-            if (raw.screenshotPath && fs3.existsSync(raw.screenshotPath)) {
-              const screenshotDir = path3.join(os3.homedir(), ".canonry", "screenshots", runId);
-              if (!fs3.existsSync(screenshotDir)) fs3.mkdirSync(screenshotDir, { recursive: true });
-              const destPath = path3.join(screenshotDir, `${snapshotId}.png`);
-              fs3.renameSync(raw.screenshotPath, destPath);
-              screenshotRelPath = `${runId}/${snapshotId}.png`;
-            }
-            this.db.insert(querySnapshots).values({
-              id: snapshotId,
-              runId,
-              queryId: unit.queryId,
-              queryText: unit.queryText,
-              provider: providerName,
-              // `model` is what was REQUESTED and `served_model` is what
-              // answered. The manifest froze the request, so it is the
-              // authority here: an adapter that reports its own default rather
-              // than what it was handed would otherwise overwrite the identity
-              // the revision recorded, and nothing would show that it moved.
-              model: unit.requestedModel ?? raw.model,
-              servedModel: raw.servedModel ?? null,
-              citationState,
-              answerMentioned,
-              answerText: normalized.answerText,
-              citedDomains: normalized.citedDomains,
-              citedUrls: citedUrlCapture.citedUrls,
-              captureStatus: citedUrlCapture.captureStatus,
-              sourceCount: citedUrlCapture.sourceCount,
-              resolvedCount: citedUrlCapture.resolvedCount,
-              captureVersion: citedUrlCapture.captureVersion,
-              retrievalStatus: normalized.retrievalStatus,
-              retrievalContract: raw.retrievalContract,
-              competitorOverlap: overlap,
-              recommendedCompetitors: extractedCompetitors,
-              // Only claim the geography the provider actually honoured. A
-              // requested-but-unsupported context stores `location: null` —
-              // "no claim" — rather than the label we asked for, mirroring
-              // `supportedContext` itself: this field is never non-null when
-              // that one is null.
-              location: supportedContext ? requestedContext?.label ?? null : null,
-              measurementExecutionId: unit.executionId,
-              requestedContext,
-              supportedContext,
-              screenshotPath: screenshotRelPath,
-              rawResponse: JSON.stringify({
-                model: raw.model,
-                servedModel: raw.servedModel ?? null,
-                groundingSources: normalized.groundingSources,
-                searchQueries: normalized.searchQueries,
-                apiResponse: raw.rawResponse
-              }),
-              createdAt: (/* @__PURE__ */ new Date()).toISOString()
-            }).run();
-            totalSnapshotsInserted++;
-            log2.info("query.citation", {
-              runId,
-              provider: providerName,
-              query: unit.queryText,
-              executionId: unit.executionId,
-              location: requestedContext?.label ?? null,
-              citationState,
-              answerMentioned
-            });
-          });
-        } catch (err) {
-          if (err instanceof RunCancelledError) {
-            throw err;
-          }
-          const msg = describeError(err);
-          const stack = err instanceof Error ? err.stack : void 0;
-          log2.error("query.failed", { runId, provider: providerName, query: unit.queryText, executionId: unit.executionId, error: msg, stack });
-          if (!providerErrors.has(providerName)) {
-            providerErrors.set(providerName, msg);
-          }
+      const slotContext = {
+        runId,
+        allDomains,
+        competitorDomains,
+        competitorAliases: runCompetitors.aliases,
+        allBrandNames,
+        executionGates,
+        providerDispatchCounts,
+        providerErrors,
+        onInserted: () => {
+          totalSnapshotsInserted++;
         }
       };
+      const processNodeForProvider = (registeredProvider, unit) => this.executePlanSlot(slotContext, registeredProvider, unit);
       if (existingRun.kind === RunKinds["answer-visibility"] && existingRun.trigger !== RunTriggers.probe && existingRun.measurementPlanVersionId === null) {
         const definition = buildSimpleMeasurementDefinition({
           capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -7442,7 +7327,7 @@ var JobRunner = class {
         status: "failed",
         finishedAt: (/* @__PURE__ */ new Date()).toISOString(),
         error: errorMessage
-      }).where(eq2(runs.id, runId)).run();
+      }).where(and2(eq2(runs.id, runId), inArray(runs.status, ["queued", "running"]))).run();
       this.flushProviderUsage(providerDispatchCounts, providerReservations);
       const abortReason2 = classifyRunAbortReason(errorMessage);
       const phases = buildPhases({ startTime, providerCallStart, providerCallEnd });
@@ -7483,6 +7368,366 @@ var JobRunner = class {
       }
     }
   }
+  /**
+   * Complete a partial plan run in place: record only the expected slots it
+   * never answered, under the same run id, then finalize the run once.
+   *
+   * The parent run is never written from an error path and only ever leaves
+   * `partial` through the completion compare-and-set, so a failed or
+   * interrupted fill leaves the run as the sweep left it, plus any answers the
+   * fill did record. Its timestamps, manifest and identity are never touched:
+   * it stays the same sweep, with the same place in every history.
+   */
+  async executeRunFill(fillId) {
+    const claim = this.db.update(runFills).set({ status: "running", startedAt: (/* @__PURE__ */ new Date()).toISOString() }).where(and2(eq2(runFills.id, fillId), eq2(runFills.status, "queued"))).run();
+    if (claim.changes !== 1) {
+      log2.warn("fill.not-claimed", { fillId });
+      return;
+    }
+    try {
+      await this.runClaimedFill(fillId);
+    } catch (err) {
+      const error = describeError(err);
+      log2.error("fill.aborted", { fillId, error });
+      this.db.update(runFills).set({ status: "failed", finishedAt: (/* @__PURE__ */ new Date()).toISOString(), error }).where(and2(eq2(runFills.id, fillId), eq2(runFills.status, "running"))).run();
+    }
+  }
+  async runClaimedFill(fillId) {
+    const fill = this.db.select().from(runFills).where(eq2(runFills.id, fillId)).get();
+    if (!fill) return;
+    const { runId, projectId } = fill;
+    const requested = new Set(parseJsonColumn(fill.providers, []).map((provider) => provider.trim().toLocaleLowerCase("en")));
+    const providerDispatchCounts = /* @__PURE__ */ new Map();
+    const providerReservations = /* @__PURE__ */ new Map();
+    const providerErrors = /* @__PURE__ */ new Map();
+    let filled = 0;
+    let fatal = null;
+    let superseded = false;
+    try {
+      const run = this.getRunState(runId);
+      if (!run) throw new Error(`Run ${runId} not found`);
+      if (run.status !== "partial") throw new Error(`Run ${runId} is ${run.status}; only a partial run can be filled`);
+      const runCreatedAt = this.db.select({ createdAt: runs.createdAt }).from(runs).where(eq2(runs.id, runId)).get().createdAt;
+      const project = this.db.select().from(projects).where(eq2(projects.id, projectId)).get();
+      if (!project) throw new Error(`Project ${projectId} not found`);
+      const projectQueries = this.db.select().from(queries).where(eq2(queries.projectId, projectId)).all();
+      const plan = resolvePlanExecution(run, projectQueries);
+      if (!plan) throw new Error(`Run ${runId} did not measure a published plan`);
+      const recorded = new Set(
+        this.db.select({ executionId: querySnapshots.measurementExecutionId, provider: querySnapshots.provider }).from(querySnapshots).where(eq2(querySnapshots.runId, runId)).all().flatMap((row) => row.executionId ? [measurementSlotKey(row.executionId, row.provider)] : [])
+      );
+      const unitsByProvider = /* @__PURE__ */ new Map();
+      for (const [provider, units] of plan.unitsByProvider) {
+        if (requested.size > 0 && !requested.has(provider)) continue;
+        const missing = units.filter((unit) => !recorded.has(measurementSlotKey(unit.executionId, provider)));
+        if (missing.length > 0) unitsByProvider.set(provider, missing);
+      }
+      const activeProviders = [];
+      for (const provider of unitsByProvider.keys()) {
+        const registered = this.registry.get(provider);
+        if (registered) activeProviders.push(registered);
+        else providerErrors.set(provider, `No ${provider} provider is configured on this instance, so its missing answers did not run.`);
+      }
+      const projectCompetitors = this.db.select().from(competitors).where(eq2(competitors.projectId, projectId)).all();
+      const runCompetitors = createRunCompetitorResolver(this.db, projectCompetitors.map((c) => c.domain))(run.measurementPlanVersionId);
+      const competitorDomains = runCompetitors.domains;
+      const allDomains = effectiveDomains({ canonicalDomain: project.canonicalDomain, ownedDomains: project.ownedDomains });
+      const allBrandNames = effectiveBrandNames({ displayName: project.displayName, aliases: project.aliases });
+      const todayPeriod = getCurrentUsageDay();
+      const dispatchable = [];
+      for (const registered of activeProviders) {
+        const name = registered.adapter.name;
+        const count = unitsByProvider.get(name)?.length ?? 0;
+        const scope = `${projectId}:${name}`;
+        const limit = registered.config.quotaPolicy.maxRequestsPerDay;
+        const quota = reserveDailyQueryQuota(this.db, { scope, period: todayPeriod, count, limit });
+        if (!quota.reserved) {
+          providerErrors.set(name, `Daily quota exceeded for ${name}: ${quota.used} queries used today, limit is ${limit}. This fill needs ${count} more.`);
+          continue;
+        }
+        providerReservations.set(name, { scope, period: todayPeriod, reserved: count });
+        dispatchable.push(registered);
+      }
+      const executionGates = /* @__PURE__ */ new Map();
+      for (const registered of dispatchable) {
+        executionGates.set(
+          registered.adapter.name,
+          getSharedProviderExecutionGate(
+            registered.adapter.name,
+            registered.config.quotaPolicy.maxConcurrency,
+            registered.config.quotaPolicy.maxRequestsPerMinute
+          )
+        );
+      }
+      const consecutiveFailures = /* @__PURE__ */ new Map();
+      const stopped = /* @__PURE__ */ new Set();
+      const newerSweepExists = () => {
+        if (!superseded && newerFullSweep(this.db, { id: runId, projectId, createdAt: runCreatedAt })) {
+          superseded = true;
+          log2.warn("fill.superseded", { fillId, runId });
+        }
+        return superseded;
+      };
+      let removed = false;
+      const attemptRemoved = () => {
+        if (!removed && this.db.select({ status: runFills.status }).from(runFills).where(eq2(runFills.id, fillId)).get()?.status !== "running") {
+          removed = true;
+          log2.warn("fill.attempt-removed", { fillId, runId });
+        }
+        return removed;
+      };
+      const slotRecorded = (provider, executionId) => this.db.select({ id: querySnapshots.id }).from(querySnapshots).where(and2(
+        eq2(querySnapshots.runId, runId),
+        eq2(querySnapshots.measurementExecutionId, executionId),
+        eq2(querySnapshots.provider, provider)
+      )).get() !== void 0;
+      const ctx = {
+        runId,
+        allDomains,
+        competitorDomains,
+        competitorAliases: runCompetitors.aliases,
+        allBrandNames,
+        executionGates,
+        providerDispatchCounts,
+        providerErrors,
+        onInserted: () => {
+          filled++;
+        },
+        fill: {
+          shouldSkip: (provider, executionId) => stopped.has(provider) || attemptRemoved() || newerSweepExists() || slotRecorded(provider, executionId),
+          onOutcome: (provider, ok) => {
+            if (ok) {
+              consecutiveFailures.set(provider, 0);
+              return;
+            }
+            const failures = (consecutiveFailures.get(provider) ?? 0) + 1;
+            consecutiveFailures.set(provider, failures);
+            if (failures >= RUN_FILL_PROVIDER_BREAKER && !stopped.has(provider)) {
+              stopped.add(provider);
+              log2.warn("fill.provider-stopped", { fillId, runId, provider, failures });
+            }
+          }
+        }
+      };
+      log2.info("fill.dispatch", {
+        fillId,
+        runId,
+        missing: Object.fromEntries([...unitsByProvider].map(([provider, units]) => [provider, units.length]))
+      });
+      const unitsFor = (registered) => unitsByProvider.get(registered.adapter.name) ?? [];
+      const apiProviders = dispatchable.filter((p) => !isBrowserProvider(p.adapter.name));
+      const browserProviders = dispatchable.filter((p) => isBrowserProvider(p.adapter.name));
+      await runWithConcurrency(apiProviders, resolveProviderFanout(), async (registered) => {
+        await runWithConcurrency(
+          unitsFor(registered),
+          Math.max(1, registered.config.quotaPolicy.maxConcurrency),
+          (unit) => this.executePlanSlot(ctx, registered, unit)
+        );
+      });
+      for (const registered of browserProviders) {
+        for (const unit of unitsFor(registered)) await this.executePlanSlot(ctx, registered, unit);
+      }
+    } catch (err) {
+      fatal = describeError(err);
+      log2.error("fill.failed", { fillId, runId, error: fatal });
+    } finally {
+      this.flushProviderUsage(providerDispatchCounts, providerReservations);
+    }
+    const outcome = this.finalizeRunFill({ fillId, runId, filled, fatal, providerErrors, superseded });
+    log2.info("fill.finished", { fillId, runId, filled, ...outcome });
+    if (outcome.justCompleted && !outcome.superseded && this.onRunCompleted) {
+      this.onRunCompleted(runId, projectId, { origin: "fill" }).catch((err) => {
+        log2.error("notification.callback-failed", { runId, error: describeError(err) });
+      });
+    }
+  }
+  /** Record the fill's outcome and, if the run is now whole, complete it exactly once. */
+  finalizeRunFill(input) {
+    const finishedAt = (/* @__PURE__ */ new Date()).toISOString();
+    return this.db.transaction((tx) => {
+      const txDb = tx;
+      const parent = txDb.select({ projectId: runs.projectId, createdAt: runs.createdAt, error: runs.error }).from(runs).where(eq2(runs.id, input.runId)).get();
+      const superseded = input.superseded || parent !== void 0 && newerFullSweep(txDb, { id: input.runId, projectId: parent.projectId, createdAt: parent.createdAt }) !== void 0;
+      const state = measurementRunSlotState(txDb, input.runId);
+      const complete3 = state.planned && state.readable && state.missing.length === 0 && !state.hasUnboundSnapshot;
+      let justCompleted = false;
+      if (complete3) {
+        justCompleted = txDb.update(runs).set({ status: "completed", error: null }).where(and2(eq2(runs.id, input.runId), eq2(runs.status, "partial"))).run().changes === 1;
+      } else if (state.readable && !input.fatal) {
+        const previous = parseRunError(parent?.error)?.providers ?? {};
+        const fresh = buildRunErrorFromMessages(input.providerErrors).providers ?? {};
+        const remaining = /* @__PURE__ */ new Map();
+        for (const slot of state.missing) remaining.set(slot.provider, (remaining.get(slot.provider) ?? 0) + 1);
+        const providers = {};
+        for (const [provider, count] of remaining) {
+          providers[provider] = fresh[provider] ?? previous[provider] ?? { message: `${count} expected measurement(s) have not run.` };
+        }
+        txDb.update(runs).set({ error: serializeRunError({ providers }) }).where(and2(eq2(runs.id, input.runId), eq2(runs.status, "partial"))).run();
+      }
+      const status = complete3 ? "completed" : input.filled > 0 ? "partial" : "failed";
+      const reason = input.fatal ?? (superseded ? "Stopped because a newer sweep started; no answers were added behind it." : null) ?? (input.providerErrors.size > 0 ? formatRunErrorOneLine(buildRunErrorFromMessages(input.providerErrors)) : null);
+      txDb.update(runFills).set({ status, filled: input.filled, error: complete3 ? null : reason, finishedAt }).where(eq2(runFills.id, input.fillId)).run();
+      return { justCompleted, superseded };
+    });
+  }
+  /**
+   * The plan-aware unit of work: one execution node, one provider.
+   *
+   * Deliberately a separate worker from the legacy query-by-query path rather
+   * than a generalization of it. The legacy path is the behaviour every
+   * planless project already depends on; leaving its body alone is what
+   * makes "planless is byte-identical" a fact rather than a hope.
+   *
+   * A method rather than a closure inside `executeRun` so a sweep and a fill
+   * record a slot through the same code: a filled answer is indistinguishable
+   * from one the sweep recorded itself, which is what lets it count.
+   */
+  async executePlanSlot(ctx, registeredProvider, unit) {
+    const { adapter, config: providerConfig } = registeredProvider;
+    const providerName = adapter.name;
+    const gate = ctx.executionGates.get(providerName);
+    if (!gate) {
+      throw new Error(`Missing execution gate for provider ${providerName}`);
+    }
+    const config = unit.requestedModel ? { ...providerConfig, model: unit.requestedModel } : providerConfig;
+    const requestedContext = unit.context;
+    const supportedContext = requestedContext && providerSupportsLocationContext(adapter) ? { status: "applied", resolved: requestedContext } : null;
+    if (ctx.fill?.shouldSkip(providerName, unit.executionId)) return;
+    try {
+      await gate.run(async () => {
+        this.throwIfRunCancelled(ctx.runId);
+        if (ctx.fill?.shouldSkip(providerName, unit.executionId)) return;
+        ctx.providerDispatchCounts.set(providerName, (ctx.providerDispatchCounts.get(providerName) ?? 0) + 1);
+        const raw = await adapter.executeTrackedQuery(
+          {
+            query: unit.queryText,
+            canonicalDomains: ctx.allDomains,
+            competitorDomains: ctx.competitorDomains,
+            location: requestedContext ?? void 0
+          },
+          config
+        );
+        this.throwIfRunCancelled(ctx.runId);
+        const providerResult = adapter.normalizeResult(raw);
+        const rawGroundingSources = providerResult.groundingSources;
+        const normalized = {
+          ...providerResult,
+          groundingSources: Array.isArray(rawGroundingSources) ? rawGroundingSources : []
+        };
+        let citedUrlCapture;
+        try {
+          citedUrlCapture = await captureCitedUrls(providerName, rawGroundingSources);
+        } catch (err) {
+          citedUrlCapture = {
+            citedUrls: [],
+            captureStatus: "failed",
+            sourceCount: normalized.groundingSources.length,
+            resolvedCount: 0,
+            captureVersion: CITED_URL_CAPTURE_VERSION
+          };
+          log2.warn("query.cited-url-capture-failed", {
+            runId: ctx.runId,
+            provider: providerName,
+            query: unit.queryText,
+            error: describeError(err)
+          });
+        }
+        this.throwIfRunCancelled(ctx.runId);
+        const citationState = determineCitationState(normalized, ctx.allDomains);
+        const answerMentioned = determineAnswerMentioned(
+          normalized.answerText,
+          ctx.allBrandNames,
+          ctx.allDomains
+        );
+        const overlap = computeCompetitorOverlap(normalized, ctx.competitorDomains, ctx.competitorAliases);
+        const extractedCompetitors = extractRecommendedCompetitors(
+          normalized.answerText,
+          ctx.allDomains,
+          normalized.citedDomains,
+          ctx.competitorDomains,
+          ctx.allBrandNames,
+          ctx.competitorAliases
+        );
+        const snapshotId = crypto6.randomUUID();
+        let screenshotRelPath = null;
+        if (raw.screenshotPath && fs3.existsSync(raw.screenshotPath)) {
+          const screenshotDir = path3.join(os3.homedir(), ".canonry", "screenshots", ctx.runId);
+          if (!fs3.existsSync(screenshotDir)) fs3.mkdirSync(screenshotDir, { recursive: true });
+          const destPath = path3.join(screenshotDir, `${snapshotId}.png`);
+          fs3.renameSync(raw.screenshotPath, destPath);
+          screenshotRelPath = `${ctx.runId}/${snapshotId}.png`;
+        }
+        const insert = this.db.insert(querySnapshots).values({
+          id: snapshotId,
+          runId: ctx.runId,
+          queryId: unit.queryId,
+          queryText: unit.queryText,
+          provider: providerName,
+          // `model` is what was REQUESTED and `served_model` is what
+          // answered. The manifest froze the request, so it is the
+          // authority here: an adapter that reports its own default rather
+          // than what it was handed would otherwise overwrite the identity
+          // the revision recorded, and nothing would show that it moved.
+          model: unit.requestedModel ?? raw.model,
+          servedModel: raw.servedModel ?? null,
+          citationState,
+          answerMentioned,
+          answerText: normalized.answerText,
+          citedDomains: normalized.citedDomains,
+          citedUrls: citedUrlCapture.citedUrls,
+          captureStatus: citedUrlCapture.captureStatus,
+          sourceCount: citedUrlCapture.sourceCount,
+          resolvedCount: citedUrlCapture.resolvedCount,
+          captureVersion: citedUrlCapture.captureVersion,
+          retrievalStatus: normalized.retrievalStatus,
+          retrievalContract: raw.retrievalContract,
+          competitorOverlap: overlap,
+          recommendedCompetitors: extractedCompetitors,
+          // Only claim the geography the provider actually honoured. A
+          // requested-but-unsupported context stores `location: null` —
+          // "no claim" — rather than the label we asked for, mirroring
+          // `supportedContext` itself: this field is never non-null when
+          // that one is null.
+          location: supportedContext ? requestedContext?.label ?? null : null,
+          measurementExecutionId: unit.executionId,
+          requestedContext,
+          supportedContext,
+          screenshotPath: screenshotRelPath,
+          rawResponse: JSON.stringify({
+            model: raw.model,
+            servedModel: raw.servedModel ?? null,
+            groundingSources: normalized.groundingSources,
+            searchQueries: normalized.searchQueries,
+            apiResponse: raw.rawResponse
+          }),
+          createdAt: (/* @__PURE__ */ new Date()).toISOString()
+        });
+        const written = ctx.fill ? insert.onConflictDoNothing().run() : insert.run();
+        if (written.changes > 0) ctx.onInserted();
+        ctx.fill?.onOutcome(providerName, true);
+        log2.info("query.citation", {
+          runId: ctx.runId,
+          provider: providerName,
+          query: unit.queryText,
+          executionId: unit.executionId,
+          location: requestedContext?.label ?? null,
+          citationState,
+          answerMentioned
+        });
+      });
+    } catch (err) {
+      if (err instanceof RunCancelledError) {
+        throw err;
+      }
+      const msg = describeError(err);
+      const stack = err instanceof Error ? err.stack : void 0;
+      log2.error("query.failed", { runId: ctx.runId, provider: providerName, query: unit.queryText, executionId: unit.executionId, error: msg, stack });
+      if (!ctx.providerErrors.has(providerName)) {
+        ctx.providerErrors.set(providerName, msg);
+      }
+      ctx.fill?.onOutcome(providerName, false);
+    }
+  }
   incrementUsage(scope, metric, count) {
     const now = (/* @__PURE__ */ new Date()).toISOString();
     const period = now.slice(0, 10);
@@ -11329,10 +11574,11 @@ async function backfillAnswerVisibilityCommand(opts) {
   let reparsed = 0;
   let providerErrors = 0;
   if (scopedProjects.length > 0) {
-    const runRows = projectFilter ? db.select({ id: runs.id, projectId: runs.projectId }).from(runs).where(and13(
+    const runRows = projectFilter ? db.select({ id: runs.id, projectId: runs.projectId, planVersionId: runs.measurementPlanVersionId }).from(runs).where(and13(
       eq15(runs.kind, RunKinds["answer-visibility"]),
       inArray6(runs.projectId, scopedProjects.map((project) => project.id))
-    )).all() : db.select({ id: runs.id, projectId: runs.projectId }).from(runs).where(eq15(runs.kind, RunKinds["answer-visibility"])).all();
+    )).all() : db.select({ id: runs.id, projectId: runs.projectId, planVersionId: runs.measurementPlanVersionId }).from(runs).where(eq15(runs.kind, RunKinds["answer-visibility"])).all();
+    const planVersionByRun = new Map(runRows.map((run) => [run.id, run.planVersionId]));
     const runIdsByProject = /* @__PURE__ */ new Map();
     for (const run of runRows) {
       const existing = runIdsByProject.get(run.projectId);
@@ -11341,6 +11587,7 @@ async function backfillAnswerVisibilityCommand(opts) {
     }
     for (const project of scopedProjects) {
       const competitorDomains = db.select({ domain: competitors.domain }).from(competitors).where(eq15(competitors.projectId, project.id)).all().map((row) => row.domain);
+      const competitorsForRun = createRunCompetitorResolver(db, competitorDomains);
       const runIds = runIdsByProject.get(project.id) ?? [];
       if (runIds.length === 0) continue;
       const projectDomains = effectiveDomains({
@@ -11355,6 +11602,7 @@ async function backfillAnswerVisibilityCommand(opts) {
         const batchRunIds = runIds.slice(offset, offset + SNAPSHOT_BATCH_SIZE);
         const snapshotRows = db.select({
           id: querySnapshots.id,
+          runId: querySnapshots.runId,
           provider: querySnapshots.provider,
           citationState: querySnapshots.citationState,
           answerMentioned: querySnapshots.answerMentioned,
@@ -11395,13 +11643,15 @@ async function backfillAnswerVisibilityCommand(opts) {
             };
             const nextCitationState = determineCitationState(normalized, projectDomains);
             const nextCitedDomains = reparsedResult.citedDomains;
-            const nextCompetitorOverlap = computeCompetitorOverlap(normalized, competitorDomains);
+            const runCompetitors = competitorsForRun(planVersionByRun.get(snapshot.runId));
+            const nextCompetitorOverlap = computeCompetitorOverlap(normalized, runCompetitors.domains, runCompetitors.aliases);
             const nextRecommendedCompetitors = extractRecommendedCompetitors(
               normalized.answerText,
               projectDomains,
               normalized.citedDomains,
-              competitorDomains,
-              projectBrandNames
+              runCompetitors.domains,
+              projectBrandNames,
+              runCompetitors.aliases
             );
             const nextRawResponse = stringifyStoredSnapshotEnvelope(
               snapshot.rawResponse,
@@ -11628,8 +11878,10 @@ function backfillProjectAnswerMentions(db, projectId, opts) {
   const project = db.select().from(projects).where(eq15(projects.id, projectId)).get();
   if (!project) return { examined: 0, updated: 0, mentioned: 0 };
   const competitorDomains = db.select({ domain: competitors.domain }).from(competitors).where(eq15(competitors.projectId, projectId)).all().map((row) => row.domain);
-  const runRows = db.select({ id: runs.id }).from(runs).where(and13(eq15(runs.kind, RunKinds["answer-visibility"]), eq15(runs.projectId, projectId))).all();
+  const runRows = db.select({ id: runs.id, planVersionId: runs.measurementPlanVersionId }).from(runs).where(and13(eq15(runs.kind, RunKinds["answer-visibility"]), eq15(runs.projectId, projectId))).all();
   const runIds = runRows.map((r) => r.id);
+  const planVersionByRun = new Map(runRows.map((run) => [run.id, run.planVersionId]));
+  const competitorsForRun = createRunCompetitorResolver(db, competitorDomains);
   let examined = 0;
   let updated = 0;
   let wouldUpdate = 0;
@@ -11649,6 +11901,7 @@ function backfillProjectAnswerMentions(db, projectId, opts) {
     const batchRunIds = runIds.slice(offset, offset + SNAPSHOT_BATCH_SIZE);
     const snapshotRows = db.select({
       id: querySnapshots.id,
+      runId: querySnapshots.runId,
       provider: querySnapshots.provider,
       answerMentioned: querySnapshots.answerMentioned,
       answerText: querySnapshots.answerText,
@@ -11674,13 +11927,15 @@ function backfillProjectAnswerMentions(db, projectId, opts) {
         retrievalStatus: "unknown",
         searchQueries: []
       };
-      const nextCompetitorOverlap = computeCompetitorOverlap(normalized, competitorDomains);
+      const runCompetitors = competitorsForRun(planVersionByRun.get(snapshot.runId));
+      const nextCompetitorOverlap = computeCompetitorOverlap(normalized, runCompetitors.domains, runCompetitors.aliases);
       const nextRecommendedCompetitors = extractRecommendedCompetitors(
         answerText,
         projectDomains,
         citedDomains,
-        competitorDomains,
-        projectBrandNames
+        runCompetitors.domains,
+        projectBrandNames,
+        runCompetitors.aliases
       );
       const nextPatch = {};
       if (snapshot.answerMentioned !== nextAnswerMentioned) {
@@ -11777,7 +12032,7 @@ function readStoredGroundingSources(rawResponse) {
   return result2;
 }
 async function backfillInsightsCommand(project, opts) {
-  const { IntelligenceService: IntelligenceService2 } = await import("./intelligence-service-K4U55A2J.js");
+  const { IntelligenceService: IntelligenceService2 } = await import("./intelligence-service-CJKOXPOP.js");
   const config = loadConfig();
   const db = createClient(config.database);
   migrate(db);
@@ -13024,8 +13279,8 @@ var Notifier = class {
     this.serverUrl = serverUrl;
   }
   /** Called after a run completes (success, partial, or failed). */
-  async onRunCompleted(runId, projectId) {
-    log17.info("run.completed", { runId, projectId });
+  async onRunCompleted(runId, projectId, opts) {
+    log17.info("run.completed", { runId, projectId, origin: opts?.origin ?? "sweep" });
     const notifs = this.db.select().from(notifications).where(eq17(notifications.projectId, projectId)).all().filter((n) => n.enabled);
     if (notifs.length === 0) {
       log17.info("notifications.none-enabled", { projectId });
@@ -13045,7 +13300,7 @@ var Notifier = class {
     const transitions = this.computeTransitions(runId, projectId);
     const events = [];
     log17.info("run.status", { runId: run.id, status: run.status, projectId });
-    if (run.status === "completed" || run.status === "partial") {
+    if ((run.status === "completed" || run.status === "partial") && opts?.origin !== "fill") {
       events.push("run.completed");
     }
     if (run.status === "failed") {
@@ -13496,7 +13751,7 @@ var RunCoordinator = class {
   intelligenceService;
   onInsightsGenerated;
   onAeroEvent;
-  async onRunCompleted(runId, projectId) {
+  async onRunCompleted(runId, projectId, opts) {
     const runRow = this.db.select().from(runs).where(eq18(runs.id, runId)).get();
     const kind = runRow?.kind ?? RunKinds["answer-visibility"];
     if (runRow?.trigger === RunTriggers.probe) {
@@ -13558,7 +13813,7 @@ var RunCoordinator = class {
       }
     }
     try {
-      await this.notifier.onRunCompleted(runId, projectId);
+      await (opts ? this.notifier.onRunCompleted(runId, projectId, opts) : this.notifier.onRunCompleted(runId, projectId));
     } catch (err) {
       log18.error("notifier.failed", { runId, error: describeError(err) });
     }
@@ -17990,7 +18245,7 @@ async function createServer(opts) {
       void sessionRegistry.drainNow(project.name);
     }
   );
-  jobRunner.onRunCompleted = (runId, projectId) => runCoordinator.onRunCompleted(runId, projectId);
+  jobRunner.onRunCompleted = (runId, projectId, opts2) => opts2 ? runCoordinator.onRunCompleted(runId, projectId, opts2) : runCoordinator.onRunCompleted(runId, projectId);
   const snapshotService = new SnapshotService(registry);
   const liveProjectIds = new Set(
     opts.db.select({ id: projects.id }).from(projects).all().map((project) => project.id)
@@ -19347,6 +19602,14 @@ async function createServer(opts) {
         app.log.error({ runId, err }, "Job runner failed");
       });
     },
+    getProviderDailyLimits: () => Object.fromEntries(
+      registry.getAll().map((provider) => [provider.adapter.name, provider.config.quotaPolicy.maxRequestsPerDay])
+    ),
+    onRunFillCreated: (fillId, runId) => {
+      jobRunner.executeRunFill(fillId).catch((err) => {
+        app.log.error({ fillId, runId, err: describeError(err) }, "Run fill failed");
+      });
+    },
     onRunCancelled: (runId) => {
       const controller = siteAuditAbortControllers.get(runId);
       if (controller && !controller.signal.aborted) {