pagesight 0.18.0 → 0.19.0

package/src/api/compare-snapshots.ts

@@ -1,221 +1,9 @@
-import { z } from "zod";
+import { canonical, normalizeReport, parseNumericValue, Incompatible, requireSame } from "./report-table.js";
 import { RequestError } from "../shared/http.js";
 import { capture, type Evidence } from "./evidence.js";
 import type { ImportedSnapshot } from "./evidence-schema.js";
-import { gaRequestSchema, gscRequestSchema } from "./schema.js";
 
-const gscRow = z
-  .object({
-    keys: z.array(z.string()).optional(),
-    clicks: z.number().finite(),
-    impressions: z.number().finite(),
-    ctr: z.number().finite(),
-    position: z.number().finite(),
-  })
-  .passthrough();
-const gscResponse = z
-  .object({
-    rows: z.array(gscRow).default([]),
-    responseAggregationType: z.string().min(1),
-    metadata: z.record(z.unknown()).optional(),
-  })
-  .passthrough();
-const gaResponse = z
-  .object({
-    dimensionHeaders: z.array(z.object({ name: z.string() })).default([]),
-    metricHeaders: z.array(z.object({ name: z.string(), type: z.string().optional() })).min(1),
-    rows: z
-      .array(
-        z.object({
-          dimensionValues: z.array(z.object({ value: z.string() })).default([]),
-          metricValues: z.array(z.object({ value: z.string() })),
-        }),
-      )
-      .default([]),
-    metadata: z.object({ timeZone: z.string().min(1), currencyCode: z.string().optional() }).passthrough(),
-  })
-  .passthrough();
-const gaComparisonDimensions = new Set([
-  "hostName",
-  "sessionDefaultChannelGroup",
-  "sessionSourceMedium",
-  "eventName",
-  "landingPagePlusQueryString",
-  "sessionSource",
-]);
-
-function canonical(value: unknown): string {
-  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
-  if (value && typeof value === "object")
-    return `{${Object.entries(value)
-      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
-      .map(([k, v]) => `${JSON.stringify(k)}:${canonical(v)}`)
-      .join(",")}}`;
-  return JSON.stringify(value) ?? "undefined";
-}
-
-type RawValue = number | string;
-type Report = {
-  request: unknown;
-  start: string;
-  end: string;
-  dimensions: string[];
-  metrics: string[];
-  semantics: unknown;
-  rows: Map<string, { keys: string[]; values: RawValue[] }>;
-  warnings: string[];
-};
-class Incompatible extends Error {}
-const requireSame = (a: unknown, b: unknown, message: string) => {
-  if (canonical(a) !== canonical(b)) throw new Incompatible(message);
-};
-
-type SnapshotContext = ImportedSnapshot["pages"][0]["response"]["context"];
-
-function normalizeReport(observation: Evidence, context: SnapshotContext): Report {
-  let report: Report | undefined;
-  let offset = 0;
-  for (const page of observation.pages) {
-    let current: Omit<Report, "rows">;
-    let rows: Array<{ keys: string[]; values: RawValue[] }>;
-    if (observation.provider === "gsc") {
-      const q = gscRequestSchema.parse(page.request);
-      const response = gscResponse.parse(page.response);
-      if (
-        q.dataState !== "final" ||
-        Object.keys(response.metadata ?? {}).some((key) => key.startsWith("first_incomplete"))
-      )
-        throw new Incompatible("GSC data must be finalized.");
-      if (q.startRow !== offset)
-        throw new Incompatible("Report must contain contiguous pages starting at offset zero.");
-      if (q.dimensions.some((dimension) => dimension === "date" || dimension === "hour"))
-        throw new Incompatible(
-          "Time dimensions need a separate alignment policy; this comparison uses non-time row keys.",
-        );
-      const { startDate, endDate, startRow: _startRow, rowLimit: _rowLimit, ...scope } = q;
-      current = {
-        request: scope,
-        start: startDate,
-        end: endDate,
-        dimensions: q.dimensions,
-        metrics: ["clicks", "impressions", "ctr", "position"],
-        semantics: { aggregation: response.responseAggregationType, timezone: "America/Los_Angeles" },
-        warnings: [],
-      };
-      if (!context.observedGscDates.includes(endDate))
-        current.warnings.push(
-          "GSC has no observed date row for the requested end date; trailing days may be unavailable or have no activity.",
-        );
-      rows = response.rows.map((r) => ({ keys: r.keys ?? [], values: [r.clicks, r.impressions, r.ctr, r.position] }));
-    } else {
-      const q = gaRequestSchema.parse(page.request);
-      const response = gaResponse.parse(page.response);
-      if (q.dateRanges.length !== 1) throw new Incompatible("GA comparison requires exactly one date range.");
-      if (
-        q.dimensions.some(
-          (dimension) => !gaComparisonDimensions.has(dimension.name) || Object.hasOwn(dimension, "dimensionExpression"),
-        )
-      )
-        throw new Incompatible("GA comparison supports only snapshot dimension names without dimension expressions.");
-      if (q.offset !== offset) throw new Incompatible("Report must contain contiguous pages starting at offset zero.");
-      const { dateRanges, offset: _offset, limit: _limit, returnPropertyQuota: _quota, ...scope } = q;
-      const dimensions = q.dimensions.map((d) => d.name);
-      const metrics = q.metrics.map((m) => m.name);
-      if (new Set(metrics).size !== metrics.length)
-        throw new Incompatible("GA metric names must be unique to preserve every compared value.");
-      requireSame(
-        response.dimensionHeaders.map((h) => h.name),
-        dimensions,
-        "GA dimension headers must match the request.",
-      );
-      requireSame(
-        response.metricHeaders.map((h) => h.name),
-        metrics,
-        "GA metric headers must match the request.",
-      );
-      current = {
-        request: scope,
-        start: dateRanges[0].startDate,
-        end: dateRanges[0].endDate,
-        dimensions,
-        metrics,
-        semantics: {
-          timezone: response.metadata.timeZone,
-          currency: response.metadata.currencyCode ?? null,
-          metrics: response.metricHeaders,
-        },
-        warnings: [],
-      };
-      if (response.metadata.subjectToThresholding) current.warnings.push("GA report is subject to thresholding.");
-      if (response.metadata.dataLossFromOtherRow)
-        current.warnings.push("GA high-cardinality rows were combined into (other).");
-      if (Array.isArray(response.metadata.samplingMetadatas) && response.metadata.samplingMetadatas.length)
-        current.warnings.push("GA report is sampled.");
-      const collectedDate = new Intl.DateTimeFormat("en-CA", {
-        timeZone: response.metadata.timeZone,
-        year: "numeric",
-        month: "2-digit",
-        day: "2-digit",
-      }).format(new Date(observation.finishedAt));
-      if (Date.parse(collectedDate) - Date.parse(current.end) < 3 * 86400000)
-        current.warnings.push(
-          "GA was collected fewer than three property-calendar days after the requested end date; recent data may still change.",
-        );
-      if (response.metricHeaders.some((h) => h.type === "TYPE_CURRENCY") && !response.metadata.currencyCode)
-        throw new Incompatible("GA currency metrics require a known response currency.");
-      rows = response.rows.map((r) => ({
-        keys: r.dimensionValues.map((v) => v.value),
-        values: r.metricValues.map((v) => v.value),
-      }));
-    }
-    requireSame(
-      { startDate: current.start, endDate: current.end },
-      { startDate: context.requestedDates.startDate, endDate: context.requestedDates.endDate },
-      "Report period does not match the snapshot context.",
-    );
-    if (report) {
-      requireSame(
-        [report.request, report.start, report.end, report.semantics],
-        [current.request, current.start, current.end, current.semantics],
-        "Report scope or metadata changed between pages.",
-      );
-      report.warnings.push(...current.warnings);
-    } else report = { ...current, rows: new Map() };
-    for (const row of rows) {
-      if (row.keys.length !== current.dimensions.length || row.values.length !== current.metrics.length)
-        throw new Incompatible("Row shape does not match the requested dimensions and metrics.");
-      const key = canonical(row.keys);
-      if (report.rows.has(key)) throw new Incompatible("Duplicate row keys make this report ambiguous.");
-      report.rows.set(key, row);
-    }
-    offset += rows.length;
-  }
-  if (!report) throw new Incompatible("No report pages available.");
-  if (
-    observation.pagination &&
-    (observation.pagination.rowsReturned !== offset ||
-      observation.pagination.nextOffset !== (observation.pagination.exhausted ? null : offset))
-  )
-    throw new Incompatible("Report pagination does not match the retained rows.");
-  if (observation.status !== "ok" || !observation.pagination?.exhausted || observation.error)
-    report.warnings.push(
-      "Report has incomplete pagination or a provider failure; only observed common rows can be compared.",
-    );
-  return report;
-}
-
-function parseNumericValue(value: RawValue): number | null {
-  if (typeof value === "string" && !/^-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?$/u.test(value)) return null;
-  const result = Number(value);
-  if (typeof value === "string" && !/^-?\d+$/u.test(value)) {
-    const mantissa = value.split(/[eE]/u)[0];
-    const significant = mantissa.replace(/[-.]/gu, "").replace(/^0+/u, "").replace(/0+$/u, "");
-    if (significant.length > 15 || (result === 0 && /[1-9]/u.test(mantissa))) return null;
-  }
-  return Number.isFinite(result) && Math.abs(result) <= Number.MAX_SAFE_INTEGER ? result : null;
-}
-
-function metric(baseline: RawValue, current: RawValue) {
+function metric(baseline: number | string, current: number | string) {
   const before = parseNumericValue(baseline);
   const after = parseNumericValue(current);
   if (before === null || after === null)
@@ -233,6 +21,8 @@ function metric(baseline: RawValue, current: RawValue) {
   return { baseline, current, delta, percentChange: percent !== null && Number.isFinite(percent) ? percent : null };
 }
 
+type SnapshotContext = ImportedSnapshot["pages"][0]["response"]["context"];
+
 function compareObservation(
   baseline: Evidence | undefined,
   current: Evidence | undefined,

package/src/api/execute.ts

@@ -1,3 +1,6 @@
+import { assessSnapshot } from "./assessment.js";
+import { opportunities } from "./opportunities.js";
+import { gaRealtime } from "./ga-realtime.js";
 import { importUiFindings } from "./ui-findings.js";
 import { doctor } from "./doctor.js";
 import { ZodError } from "zod";
@@ -45,6 +48,14 @@ export async function execute(input: unknown): Promise<Evidence> {
 
 async function dispatch(op: ParsedOperation): Promise<Evidence> {
   switch (op.operation) {
+    case "opportunities":
+      return opportunities(op.snapshot, {
+        minImpressions: op.minImpressions,
+        maxClicks: op.maxClicks,
+        maxRows: op.maxRows,
+      });
+    case "assess":
+      return assessSnapshot(op.snapshot, op.maxRows);
     case "evidence.import":
       return importUiFindings(op.document);
     case "compare":
@@ -109,6 +120,8 @@ async function dispatch(op: ParsedOperation): Promise<Evidence> {
           "Configured key events are not necessarily validated product outcomes; inspect event names. Check nextPageToken.",
         ],
       );
+    case "ga.realtime":
+      return gaRealtime(op.property, op.request);
     case "ga.report":
       return gaReport(op.property, op.request, op.maxPages);
     case "page":

package/src/api/ga-freshness.ts

@@ -0,0 +1,20 @@
+export function gaFreshnessWarnings(endDates: string[], timeZone: unknown, collectedAt: string): string[] {
+  if (typeof timeZone !== "string" || !timeZone)
+    return ["GA property timezone is unavailable; report freshness could not be assessed."];
+  let collectedDate: string;
+  try {
+    collectedDate = new Intl.DateTimeFormat("en-CA", {
+      timeZone,
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+    }).format(new Date(collectedAt));
+  } catch {
+    return ["GA property timezone or collection time is invalid; report freshness could not be assessed."];
+  }
+  return endDates.some((end) => Date.parse(collectedDate) - Date.parse(end) < 3 * 86400000)
+    ? [
+        "GA was collected fewer than three property-calendar days after the requested end date; recent data may still change. This precaution is not a finalization guarantee for older data.",
+      ]
+    : [];
+}

package/src/api/ga-realtime.ts

@@ -0,0 +1,40 @@
+import { gaFetch, normalizeGaProperty, type GaReport } from "../providers/ga.js";
+import { RequestError } from "../shared/http.js";
+import { createEvidence, fail, type Evidence } from "./evidence.js";
+import type { GaRealtimeRequest } from "./schema.js";
+
+export async function gaRealtime(
+  property: string,
+  request: GaRealtimeRequest,
+  query = (r: GaRealtimeRequest) => gaFetch<GaReport>(`${normalizeGaProperty(property)}:runRealtimeReport`, r),
+): Promise<Evidence> {
+  const result = createEvidence("ga", "realtime", normalizeGaProperty(property));
+  result.warnings.push(
+    "Realtime is a moving window of reported property activity, not a historical or finalized report. Requested filters determine scope; no production hostname filter is added.",
+    "Activity does not identify a particular browser test or prove event counts are correct. Empty rows do not prove collection failed.",
+    "Realtime dimensions and metrics differ from standard reports. Windows beyond 29 minutes ago require Analytics 360; overlapping ranges count overlapping events in both ranges.",
+  );
+  try {
+    const response = await query(request);
+    result.pages.push({ request, response });
+    if (response.rows !== undefined && !Array.isArray(response.rows))
+      throw new RequestError("Invalid realtime rows", null, "invalid_response");
+    const count = response.rows?.length ?? 0;
+    const total = response.rowCount ?? (count === 0 && Array.isArray(response.metricHeaders) ? 0 : undefined);
+    if (!Number.isSafeInteger(total) || Number(total) < count)
+      throw new RequestError("Invalid realtime rowCount", null, "invalid_response");
+    const exhausted = total === count;
+    result.pagination = { exhausted, nextOffset: null, rowsReturned: count };
+    if (!exhausted) {
+      result.status = "partial";
+      result.warnings.push(
+        "Realtime rows were truncated. The API has no offset or page token; narrow dimensions or raise the limit. Missing rows are unknown, not zero.",
+      );
+    }
+  } catch (error) {
+    result.failedRequest = request;
+    fail(result, error);
+  }
+  result.finishedAt = new Date().toISOString();
+  return result;
+}

package/src/api/opportunities.ts

@@ -0,0 +1,317 @@
+import { z } from "zod";
+import { assessSnapshot, type AssessmentTable } from "./assessment.js";
+import { capture } from "./evidence.js";
+import type { ImportedSnapshot } from "./evidence-schema.js";
+import { configSchema, httpUrl } from "./schema.js";
+import { parseNumericValue } from "./report-table.js";
+
+export interface OpportunityPolicy {
+  minImpressions: number;
+  maxClicks: number;
+  maxRows: number;
+}
+const pageSchema = z.object({
+  url: z.string(),
+  finalUrl: z.string(),
+  status: z.number().int(),
+  title: z.string().nullable(),
+  description: z.string().nullable(),
+  canonical: z.string().nullable(),
+  robots: z.array(z.string()),
+  xRobotsTag: z.string().nullable(),
+  warnings: z.array(z.string()).default([]),
+});
+const inspectionSchema = z.object({
+  inspectionResult: z.object({
+    indexStatusResult: z.object({
+      verdict: z.string().optional(),
+      coverageState: z.string().optional(),
+      indexingState: z.string().optional(),
+      robotsTxtState: z.string().optional(),
+      googleCanonical: z.string().optional(),
+      userCanonical: z.string().optional(),
+      lastCrawlTime: z.string().optional(),
+    }),
+  }),
+});
+const organicNames = [
+  "ga.report.landingPagePlusQueryString+sessionSource.organic",
+  "ga.report.landingPagePlusQueryString+sessionSource+eventName.organic",
+];
+function configuredPath(raw: string, site: string): string | null {
+  try {
+    const url = new URL(raw);
+    if (url.origin === new URL(site).origin && url.href === raw && !raw.includes("#") && !url.username && !url.password)
+      return url.pathname + url.search;
+  } catch {
+    /* Invalid provider URL remains raw evidence. */
+  }
+  return null;
+}
+
+export async function opportunities(snapshot: ImportedSnapshot, policy: OpportunityPolicy) {
+  const config = configSchema.parse(snapshot.pages[0].response.context.config);
+  const observations = snapshot.pages[0].response.observations;
+  // Selection must use all retained rows, not the assessment's presentation cap.
+  const assessment = await assessSnapshot(snapshot, Number.MAX_SAFE_INTEGER);
+  const assessed = assessment.pages[0]?.response as
+    | {
+        tables: AssessmentTable[];
+        snapshotSha256: string;
+        limitations: string[];
+      }
+    | undefined;
+  const tables = assessed?.tables ?? [];
+  const search = tables.find((t) => t.observation === "gsc.report.page");
+  const limits = [
+    ...(assessed?.limitations ?? []),
+    "Cutoffs select an investigation cohort, not a CTR benchmark, SEO score or forecast. Position and query/device/country mix can explain few clicks.",
+    "Candidate ordering covers retained GSC page rows only. Missing pages and missing GA rows are unknown, not zero.",
+    "GA is associated by configured origin and exact path/query only, not verified canonical identity. Landing page is session entry, not event location; no cross-provider funnel is computed.",
+    "Technical observations describe their collection times; they need not represent the historical reporting period. No live requests or imported-claim verification occur.",
+  ];
+  let unusableSearchRows = 0;
+  const result = await capture(
+    "pagesight",
+    "opportunities",
+    snapshot.target,
+    {
+      snapshotSha256: assessed?.snapshotSha256 ?? null,
+      ...policy,
+    },
+    async () => {
+      const candidates = (search?.rows ?? [])
+        .flatMap((row) => {
+          const values = Object.fromEntries(search!.metrics.map((m, i) => [m, row.values[i]]));
+          const impressions = parseNumericValue(values.impressions);
+          const clicks = parseNumericValue(values.clicks);
+          const ctr = parseNumericValue(values.ctr);
+          const position = parseNumericValue(values.position);
+          if (
+            impressions === null ||
+            clicks === null ||
+            !Number.isSafeInteger(impressions) ||
+            !Number.isSafeInteger(clicks) ||
+            impressions < 0 ||
+            ctr === null ||
+            ctr < 0 ||
+            ctr > 1 ||
+            position === null ||
+            position < 0 ||
+            clicks < 0 ||
+            clicks > impressions
+          ) {
+            unusableSearchRows++;
+            return [];
+          }
+          if (impressions < policy.minImpressions || clicks > policy.maxClicks) return [];
+          return [{ url: row.keys[0], values, impressions, clicks }];
+        })
+        .sort(
+          (a, b) =>
+            b.impressions - a.impressions || a.clicks - b.clicks || (a.url < b.url ? -1 : a.url > b.url ? 1 : 0),
+        );
+      const selected = candidates.slice(0, policy.maxRows).map((candidate) => {
+        const unknowns: string[] = [
+          "No page-filtered query/device/country breakdown is used for this candidate; property query totals are not page-level evidence.",
+        ];
+        const nextChecks = [
+          "Inspect page-filtered Search Console queries, device/country mix and position before deciding whether a title/snippet change is appropriate.",
+        ];
+        const path = configuredPath(candidate.url, config.site);
+        if (path === null) unknowns.push("No supported configured-origin/exact-path association for this GSC URL.");
+        const organic = organicNames.map((name) => {
+          const table = tables.find((t) => t.observation === name);
+          const matched = path === null ? [] : (table?.rows.filter((r) => r.keys[0] === path) ?? []);
+          if (!table || !matched.length)
+            unknowns.push(`${name}: ${table ? "no exact observed row; not zero activity" : "report unavailable"}.`);
+          return {
+            source: name,
+            association: path === null ? "unmatched" : "configured-origin-exact-path-not-canonical",
+            dimensions: table?.dimensions ?? [],
+            metrics: table?.metrics ?? [],
+            rows: matched.slice(0, policy.maxRows),
+            observedMatchingRows: matched.length,
+            omittedMatchingRows: Math.max(0, matched.length - policy.maxRows),
+            complete: table?.complete ?? false,
+            limitations: table?.limitations ?? [],
+          };
+        });
+        const technical = observations.flatMap((observation) => {
+          if (observation.status !== "ok" || observation.error || observation.pages.length !== 1) return [];
+          const page = observation.pages[0];
+          const request = page.request as Record<string, unknown> | null;
+          if (
+            observation.provider === "web" &&
+            observation.operation === "page" &&
+            observation.target === candidate.url &&
+            request?.url === candidate.url
+          ) {
+            const parsed = pageSchema.safeParse(page.response);
+            if (!parsed.success || parsed.data.url !== candidate.url) return [];
+            if (
+              parsed.data.canonical !== candidate.url ||
+              parsed.data.status !== 200 ||
+              parsed.data.finalUrl !== candidate.url ||
+              [...parsed.data.robots, parsed.data.xRobotsTag ?? ""].some((v) => /noindex/i.test(v))
+            )
+              nextChecks.push(
+                "Check redirects, canonical and indexing directives against intentional route policy before proposing content edits.",
+              );
+            return [
+              {
+                source: observation.name,
+                kind: "html",
+                collectedAt: observation.finishedAt,
+                evidence: parsed.data as unknown,
+                limitations: [
+                  ...observation.warnings,
+                  ...parsed.data.warnings,
+                  "HTML only; JavaScript execution and crawler access were not tested.",
+                ],
+              },
+            ];
+          }
+          if (
+            observation.provider === "gsc" &&
+            observation.operation === "inspect" &&
+            observation.target === config.gscSite &&
+            request?.inspectionUrl === candidate.url &&
+            request.siteUrl === config.gscSite
+          ) {
+            const parsed = inspectionSchema.safeParse(page.response);
+            if (parsed.success) {
+              const index = parsed.data.inspectionResult.indexStatusResult;
+              if (
+                [index.googleCanonical, index.userCanonical].some(
+                  (canonical) => canonical !== undefined && canonical !== candidate.url,
+                )
+              )
+                nextChecks.unshift(
+                  "Check Google's reported canonical URLs against intentional route policy; canonical differences do not authorize additional GA associations or a rewritten candidate URL.",
+                );
+              if (parsed.data.inspectionResult.indexStatusResult.verdict !== "PASS")
+                nextChecks.unshift(
+                  "Reconcile Google's stored inspection verdict and crawl date with the historical impressions and current route policy before a snippet experiment; these observations may describe different times.",
+                );
+              return [
+                {
+                  source: observation.name,
+                  kind: "google-indexed-state",
+                  collectedAt: observation.finishedAt,
+                  evidence: parsed.data.inspectionResult.indexStatusResult as unknown,
+                  limitations: [
+                    ...observation.warnings,
+                    "Google's stored indexed state, not a live fetch or proof of historical state.",
+                  ],
+                },
+              ];
+            }
+          }
+          return [];
+        });
+        if (!technical.some((t) => t.kind === "html")) {
+          unknowns.push("No usable exact-URL HTML observation.");
+          nextChecks.push(
+            "Collect this URL's HTML metadata and verify title, description, canonical and robots directives.",
+          );
+        }
+        if (!technical.some((t) => t.kind === "google-indexed-state")) {
+          unknowns.push("No usable exact-URL Google inspection.");
+          nextChecks.push("Inspect this exact URL in Search Console; indexed state is not a live fetch.");
+        }
+        nextChecks.push(
+          "Validate the meaning and instrumentation dates of relevant events; compare a later equivalent window without treating event counts as a conversion rate.",
+        );
+        return {
+          url: candidate.url,
+          reason: `${candidate.impressions} observed impressions and ${candidate.clicks} clicks meet the supplied cutoffs. Investigate; this does not establish underperformance.`,
+          search: {
+            source: search!.observation,
+            keys: [candidate.url],
+            metrics: candidate.values,
+            complete: search!.complete,
+            limitations: search!.limitations,
+          },
+          organic,
+          technical,
+          unknowns,
+          nextChecks,
+          suggestedRequests: [
+            {
+              operation: "gsc.report",
+              site: config.gscSite,
+              maxPages: 1,
+              request: {
+                ...snapshot.pages[0].response.context.requestedDates,
+                dimensions: ["query"],
+                dataState: "final",
+                dimensionFilterGroups: [
+                  {
+                    groupType: "and",
+                    filters: [{ dimension: "page", operator: "equals", expression: candidate.url }],
+                  },
+                ],
+              },
+            },
+            ...(httpUrl.safeParse(candidate.url).success && !technical.some((t) => t.kind === "html")
+              ? [{ operation: "page", url: candidate.url }]
+              : []),
+            ...(httpUrl.safeParse(candidate.url).success && !technical.some((t) => t.kind === "google-indexed-state")
+              ? [{ operation: "gsc.inspect", site: config.gscSite, url: candidate.url }]
+              : []),
+          ],
+        };
+      });
+      const associatedPaths = new Set(
+        selected.map((candidate) => configuredPath(candidate.url, config.site)).filter((path) => path !== null),
+      );
+      const unassociatedOrganic = organicNames.map((source) => {
+        const table = tables.find((table) => table.observation === source);
+        const rows = table?.rows.filter((row) => !associatedPaths.has(row.keys[0])) ?? [];
+        return {
+          source,
+          available: Boolean(table),
+          meaning:
+            "Not associated with displayed candidates; includes URL variants, special values and landings outside this selected cohort.",
+          dimensions: table?.dimensions ?? [],
+          metrics: table?.metrics ?? [],
+          rows: rows.slice(0, policy.maxRows),
+          observedRows: table ? rows.length : null,
+          omittedRows: Math.max(0, rows.length - policy.maxRows),
+          complete: table?.complete ?? false,
+          limitations: [
+            ...(table?.limitations ?? []),
+            "(other) aggregates and (not set) values cannot establish exact landing identity. Missing associations are not zero traffic.",
+          ],
+        };
+      });
+      return {
+        site: config.site,
+        basis: "saved-snapshot-not-reverified",
+        snapshotSha256: assessed?.snapshotSha256 ?? null,
+        collectedAt: snapshot.finishedAt,
+        requestedDates: snapshot.pages[0].response.context.requestedDates,
+        policy: {
+          ...policy,
+          ordering: "impressions-desc,clicks-asc,url-asc",
+          meaning: "caller-adjustable investigation cutoffs, not quality benchmarks",
+        },
+        searchReportAvailable: Boolean(search),
+        observedSearchRows: search?.observedRows ?? null,
+        unusableSearchRows,
+        qualifyingObservedRows: search ? candidates.length : null,
+        omittedCandidates: Math.max(0, candidates.length - policy.maxRows),
+        candidates: selected,
+        unassociatedOrganic,
+        limitations: limits,
+      };
+    },
+  );
+  if (
+    result.status !== "error" &&
+    (assessment.status !== "ok" || !search || !search.complete || unusableSearchRows > 0)
+  )
+    result.status = "partial";
+  return result;
+}