pagesight 0.19.0 → 0.20.0

package/docs/usage.md

@@ -26,25 +26,27 @@ GA evidence identifies the credential source variable, credential type, and serv
 account email when present. It never includes the token or private key. Aggregate
 results include a concise per-observation `summary` alongside full observations.
 
-| Operation                                    | Required inputs                                          |
-| -------------------------------------------- | -------------------------------------------------------- |
-| `discover`                                   | `url`; optional `providers` (`["gsc", "ga"]` by default) |
-| `bing.sites`                                 | None                                                     |
-| `bing.queries`, `bing.pages`, `bing.traffic` | `site`                                                   |
-| `gsc.sites`                                  | None                                                     |
-| `gsc.sitemaps`                               | `site`                                                   |
-| `gsc.inspect`                                | `site`, `url`                                            |
-| `gsc.report`                                 | `site`, `request`; optional `maxPages`                   |
-| `ga.accounts`                                | None                                                     |
-| `ga.property`, `ga.key-events`               | `property`                                               |
-| `ga.realtime`                                | `property`, `request`; moving window, no offset          |
-| `ga.report`                                  | `property`, `request`; optional `maxPages`               |
-| `page`                                       | `url`                                                    |
-| `speed.psi`                                  | `url`; optional `strategy` (`mobile` or `desktop`)       |
-| `speed.crux`, `speed.history`                | `url`; optional `origin: true`, `formFactor`             |
-| `doctor`                                     | `config`                                                 |
-| `assess`                                     | `snapshot`; optional `maxRows` (default 10, max 100)     |
-| `snapshot`                                   | `config`, `startDate`, `endDate`; optional `maxPages`    |
+| Operation                                    | Required inputs                                                            |
+| -------------------------------------------- | -------------------------------------------------------------------------- |
+| `discover`                                   | `url`; optional `providers` (`["gsc", "ga"]` by default)                   |
+| `bing.sites`                                 | None                                                                       |
+| `bing.queries`, `bing.pages`, `bing.traffic` | `site`                                                                     |
+| `gsc.sites`                                  | None                                                                       |
+| `gsc.sitemaps`                               | `site`                                                                     |
+| `gsc.inspect`                                | `site`, `url`                                                              |
+| `gsc.report`                                 | `site`, `request`; optional `maxPages`                                     |
+| `ga.accounts`                                | None                                                                       |
+| `ga.property`, `ga.key-events`               | `property`                                                                 |
+| `ga.realtime`                                | `property`, `request`; moving window, no offset                            |
+| `ga.report`                                  | `property`, `request`; optional `maxPages`                                 |
+| `page`                                       | `url`                                                                      |
+| `speed.psi`                                  | `url`; optional `strategy` (`mobile` or `desktop`)                         |
+| `speed.crux`, `speed.history`                | `url`; optional `origin: true`, `formFactor`                               |
+| `doctor`                                     | `config`                                                                   |
+| `crawl`                                      | `config`; optional crawl bounds and `inspectLimit` (see [crawl](crawl.md)) |
+| `investigate`                                | `config`, `url`, `startDate`, `endDate`; optional `maxPages`, `maxRows`    |
+| `assess`                                     | `snapshot`; optional `maxRows` (default 10, max 100)                       |
+| `snapshot`                                   | `config`, `startDate`, `endDate`; optional `maxPages`                      |
 
 `operationSchema` and `configSchema` are exported for typed validation. The MCP
 `observe` input uses the same schema. `page` observes fetched HTML, status,
@@ -54,6 +56,7 @@ link, social-meta and contrast checks.
 
 See [measurement and verification](measurement.md) for saved-snapshot assessments,
 Realtime requests, freshness limits and repeatable browser checks.
+See [investigating one URL](investigation.md) for fresh exact-page search, organic and technical evidence.
 
 ## CLI
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pagesight",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "See your site the way search engines and AI see it.",
   "keywords": [
     "ai-crawlers",
@@ -38,10 +38,13 @@
   "scripts": {
     "start": "bun run src/index.ts",
     "typecheck": "tsc -p tsconfig.json",
-    "test": "bun test __tests__"
+    "test": "bun test __tests__ && bun test browser-tests"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
+    "entities": "^8.1.0",
+    "ipaddr.js": "^2.5.0",
+    "playwright": "1.63.0",
     "saxes": "^6.0.0",
     "zod": "^3.24.4"
   },

package/src/api/change-record.ts

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import { httpUrl } from "./http-url.js";
+
+const contextChange = z.object({ at: z.string().datetime(), description: z.string().min(1).max(2000) }).strict();
+export const changeRecordSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    id: z.string().min(1).max(200),
+    site: httpUrl,
+    affectedUrls: z.array(httpUrl).min(1).max(100),
+    description: z.string().min(1).max(4000),
+    hypothesis: z.string().min(1).max(4000),
+    deployedAt: z.string().datetime(),
+    expectedSignal: z.string().min(1).max(2000),
+    measurementChanges: z.array(contextChange).max(100),
+    overlappingChanges: z.array(contextChange).max(100),
+  })
+  .strict()
+  .superRefine((record, ctx) => {
+    for (const [index, url] of record.affectedUrls.entries()) {
+      if (new URL(url).origin !== new URL(record.site).origin)
+        ctx.addIssue({
+          code: "custom",
+          path: ["affectedUrls", index],
+          message: "Affected URL must share the site's origin",
+        });
+    }
+    if (Date.parse(record.deployedAt) > Date.now())
+      ctx.addIssue({ code: "custom", path: ["deployedAt"], message: "Deployment must not be in the future" });
+  });
+export type ChangeRecord = z.infer<typeof changeRecordSchema>;

package/src/api/cloudflare.ts

@@ -0,0 +1,201 @@
+import { z } from "zod";
+import { cloudflareGraphql, type CloudflareQuery } from "../providers/cloudflare.js";
+import { aggregate, capture, type Evidence } from "./evidence.js";
+
+const responseSchema = z
+  .object({
+    data: z
+      .object({ viewer: z.object({ zones: z.array(z.object({ zoneTag: z.string() }).passthrough()) }).nullable() })
+      .nullable()
+      .optional(),
+    errors: z.array(z.unknown()).nullable().optional(),
+  })
+  .passthrough();
+type Input = { zone: string; hostname: string; startTime: string; endTime: string; limit: number };
+// AIDEV-NOTE: Fixed selections exclude IPs, query strings and credentials. New fields change the privacy contract.
+export function cloudflareRequests(input: Input): Array<{ name: string; dataset: string; request: CloudflareQuery }> {
+  const zoneVar = { zone: input.zone };
+  const filters = {
+    datetime_geq: input.startTime,
+    datetime_lt: input.endTime,
+    clientRequestHTTPHost: input.hostname.toLowerCase(),
+  };
+  return [
+    {
+      name: "settings",
+      dataset: "settings",
+      request: {
+        query: `query Settings($zone: string) { viewer { zones(filter: {zoneTag: $zone}) { zoneTag settings { httpRequestsAdaptiveGroups { enabled maxDuration maxPageSize notOlderThan availableFields } firewallEventsAdaptive { enabled maxDuration maxPageSize notOlderThan availableFields } } } } }`,
+        variables: zoneVar,
+      },
+    },
+    {
+      name: "http",
+      dataset: "httpRequestsAdaptiveGroups",
+      request: {
+        query: `query Http($zone: string, $filter: ZoneHttpRequestsAdaptiveGroupsFilter_InputObject, $limit: uint64) { viewer { zones(filter: {zoneTag: $zone}) { zoneTag httpRequestsAdaptiveGroups(filter: $filter, limit: $limit, orderBy: [count_DESC]) { count avg { sampleInterval } dimensions { clientRequestHTTPHost clientRequestPath edgeResponseStatus originResponseStatus cacheStatus userAgent verifiedBotCategory } } } } }`,
+        variables: { ...zoneVar, filter: filters, limit: input.limit },
+      },
+    },
+    {
+      name: "security",
+      dataset: "firewallEventsAdaptive",
+      request: {
+        query: `query Security($zone: string, $filter: FirewallEventsAdaptiveFilter_InputObject, $limit: uint64) { viewer { zones(filter: {zoneTag: $zone}) { zoneTag firewallEventsAdaptive(filter: $filter, limit: $limit, orderBy: [datetime_DESC]) { datetime action source clientRequestHTTPHost clientRequestPath edgeResponseStatus userAgent verifiedBotCategory sampleInterval } } } }`,
+        variables: { ...zoneVar, filter: filters, limit: input.limit },
+      },
+    },
+  ];
+}
+
+export async function cloudflareAudit(input: Input, query = cloudflareGraphql): Promise<Evidence> {
+  const observations: Evidence[] = [];
+  for (const planned of cloudflareRequests(input)) {
+    const observation = await capture("cloudflare", planned.name, input.zone, planned.request, () =>
+      query(planned.request),
+    );
+    observation.name = `cloudflare.${planned.name}`;
+    const raw = observation.pages[0]?.response;
+    if (raw !== undefined) {
+      const parsed = responseSchema.safeParse(raw);
+      const zones = parsed.success ? parsed.data.data?.viewer?.zones : undefined;
+      const zone = zones?.length === 1 && zones[0].zoneTag === input.zone ? zones[0] : undefined;
+      const usable = Boolean(zone && Object.hasOwn(zone, planned.dataset) && zone[planned.dataset] !== null);
+      if (!parsed.success || !usable || parsed.data.errors?.length) {
+        observation.status = usable ? "partial" : "error";
+        observation.error = {
+          code: parsed.success ? "graphql_error" : "invalid_response",
+          message: "Cloudflare returned unavailable or incomplete dataset evidence; inspect retained GraphQL response",
+          httpStatus: 200,
+        };
+      }
+    }
+    observation.credential = { source: "CLOUDFLARE_API_TOKEN", type: "api_token", clientEmail: null };
+    observation.warnings.push(
+      "Adaptive datasets can contain estimated/sampled values. Retain sampleInterval; do not multiply already estimated counts again.",
+      "Dataset availability, retained history and maximum query duration depend on zone settings. Missing or denied data is unknown, not zero.",
+    );
+    if (planned.name !== "settings")
+      observation.warnings.push(
+        `At most ${input.limit} ${planned.name === "http" ? "groups ordered by count descending" : "security events ordered newest first"} are retained; this is not exhaustive traffic or crawler coverage.`,
+      );
+    observations.push(observation);
+  }
+  const diagnostics: Array<{
+    dataset: string;
+    observedRows: number | null;
+    possiblyTruncated: boolean;
+    effectiveRowLimit: number;
+    unusableRows: number;
+    collectedAt: string;
+    errorPaths: unknown[];
+  }> = [];
+  const unknowns: string[] = [];
+  const settingsSchema = z.object({
+    enabled: z.boolean(),
+    maxDuration: z.number().nonnegative(),
+    maxPageSize: z.number().int().positive().optional(),
+    notOlderThan: z.number().nonnegative(),
+    availableFields: z.array(z.string()),
+  });
+  const settingsObservation = observations[0];
+  const settingsRaw = responseSchema.safeParse(settingsObservation.pages[0]?.response);
+  const settingsZone = settingsRaw.success
+    ? settingsRaw.data.data?.viewer?.zones?.find((z) => z.zoneTag === input.zone)
+    : undefined;
+  const settings = settingsZone?.settings as Record<string, unknown> | undefined;
+  for (let index = 1; index < observations.length; index++) {
+    const observation = observations[index];
+    const dataset = index === 1 ? "httpRequestsAdaptiveGroups" : "firewallEventsAdaptive";
+    const parsed = responseSchema.safeParse(observation.pages[0]?.response);
+    const zone = parsed.success ? parsed.data.data?.viewer?.zones?.find((z) => z.zoneTag === input.zone) : undefined;
+    const rows = Array.isArray(zone?.[dataset]) ? (zone[dataset] as unknown[]) : null;
+    const unusableRows =
+      rows?.filter((row) => {
+        if (!row || typeof row !== "object") return true;
+        const value = row as Record<string, unknown>;
+        const dimensions = value.dimensions as Record<string, unknown> | undefined;
+        const hostname = index === 1 ? dimensions?.clientRequestHTTPHost : value.clientRequestHTTPHost;
+        return typeof hostname !== "string" || hostname.toLowerCase() !== input.hostname.toLowerCase();
+      }).length ?? 0;
+    const declared = settingsObservation.status === "ok" ? settingsSchema.safeParse(settings?.[dataset]) : null;
+    if (!declared?.success)
+      unknowns.push(`${dataset}: settings unavailable or incomplete; retention/availability are unknown.`);
+    else {
+      if (!declared.data.enabled) unknowns.push(`${dataset}: dataset is currently disabled for this zone.`);
+      if (Date.parse(input.startTime) < Date.parse(settingsObservation.finishedAt) - declared.data.notOlderThan * 1000)
+        unknowns.push(`${dataset}: requested start is outside the currently declared retention window.`);
+      if (Date.parse(input.endTime) - Date.parse(input.startTime) > declared.data.maxDuration * 1000)
+        unknowns.push(`${dataset}: interval exceeds currently declared maximum duration.`);
+    }
+    const providerRowLimit = declared?.success ? declared.data.maxPageSize : undefined;
+    const effectiveRowLimit = Math.min(input.limit, providerRowLimit ?? input.limit);
+    if (providerRowLimit === undefined)
+      unknowns.push(`${dataset}: provider maximum page size unavailable; provider truncation is unknown.`);
+    if (rows && rows.length >= effectiveRowLimit)
+      unknowns.push(`${dataset}: retained row limit reached; additional rows may exist.`);
+    if (rows?.length === 0)
+      unknowns.push(`${dataset}: empty retained set, not proof of zero traffic or security actions.`);
+    if (unusableRows) {
+      unknowns.push(
+        `${dataset}: ${unusableRows} rows do not match the requested hostname/shape; raw data retained without association.`,
+      );
+      if (observation.status === "ok") observation.status = "partial";
+    }
+    if (!rows && observation.status === "ok") {
+      observation.status = "error";
+      observation.error = {
+        code: "invalid_response",
+        message: "Cloudflare dataset is not a row array",
+        httpStatus: 200,
+      };
+    }
+    const issues = unknowns.filter((u) => u.startsWith(`${dataset}:`));
+    observation.warnings.push(...issues);
+    diagnostics.push({
+      dataset,
+      observedRows: rows?.length ?? null,
+      possiblyTruncated: Boolean(rows && rows.length >= effectiveRowLimit),
+      effectiveRowLimit,
+      unusableRows,
+      collectedAt: observation.finishedAt,
+      errorPaths: parsed.success
+        ? (parsed.data.errors ?? [])
+            .slice(0, 3)
+            .map((e) => (e && typeof e === "object" ? ("path" in e ? e.path : null) : null))
+        : [],
+    });
+  }
+  const result = aggregate("cloudflare.audit", input.zone, input, observations);
+  Object.assign(result.pages[0].response as object, {
+    scope: {
+      zone: input.zone,
+      hostname: input.hostname,
+      startInclusive: input.startTime,
+      endExclusive: input.endTime,
+      timezone: "UTC",
+      limit: input.limit,
+      ordering: { http: "count_DESC", security: "datetime_DESC" },
+      querySignature: Bun.CryptoHasher.hash(
+        "sha256",
+        JSON.stringify(cloudflareRequests(input).map((p) => p.request.query)),
+        "hex",
+      ),
+      settingsCollectedAt: settingsObservation.finishedAt,
+      settingsMeaning: "Current zone settings, not proof of settings during the historical reporting window",
+    },
+    diagnostics,
+    unknowns,
+    limitations: [
+      "No path joins to GSC/GA: Cloudflare paths omit query strings. Cloudflare is not supported by Pagesight report comparisons or conversion funnels.",
+      "HTTP traffic is not verified search-engine crawling. User-Agent can be spoofed; verifiedBotCategory is Cloudflare's classification, not proof of Google indexing or a particular crawler identity.",
+      "Security events describe observed actions, not all requests or all challenges. Do not reconcile sampled event counts with HTTP groups as a funnel.",
+      "Edge status and origin status differ; cached/edge-handled requests may have no origin response. Status zero does not mean successful origin access.",
+      "No client IP, request query string, cookies or authentication headers are requested. Paths and user agents may still be sensitive: keep reports private.",
+      "Only read-only GraphQL analytics queries execute; no Cloudflare security, cache, DNS or crawler settings are modified.",
+    ],
+  });
+  result.credential = { source: "CLOUDFLARE_API_TOKEN", type: "api_token", clientEmail: null };
+  if (result.status === "ok" && unknowns.length) result.status = "partial";
+  return result;
+}

package/src/api/compare-snapshots.ts

@@ -23,7 +23,7 @@ function metric(baseline: number | string, current: number | string) {
 
 type SnapshotContext = ImportedSnapshot["pages"][0]["response"]["context"];
 
-function compareObservation(
+export function compareObservation(
   baseline: Evidence | undefined,
   current: Evidence | undefined,
   maxRows: number,

package/src/api/crawl.ts

@@ -0,0 +1,53 @@
+import { aggregate, capture, type Evidence } from "./evidence.js";
+import { crawlSite } from "../web/site-graph.js";
+import type { SiteConfig } from "./schema.js";
+import type { Executor } from "./execute.js";
+
+type Input = {
+  config: SiteConfig;
+  maxPages: number;
+  maxDepth: number;
+  maxLinks: number;
+  includeQuery: boolean;
+  inspectLimit: number;
+};
+export async function crawl(input: Input, run: Executor): Promise<Evidence> {
+  const { config } = input;
+  const request = {
+    site: config.site,
+    seeds: config.pages,
+    sitemap: config.sitemap,
+    maxPages: input.maxPages,
+    maxDepth: input.maxDepth,
+    maxLinks: input.maxLinks,
+    includeQuery: input.includeQuery,
+  };
+  const graph = await capture("web", "site-graph", config.site, request, () => crawlSite(request));
+  graph.name = "crawl.graph";
+  const data = graph.pages[0]?.response as Awaited<ReturnType<typeof crawlSite>> | undefined;
+  if (data && !data.complete) graph.status = "partial";
+  const observations = [graph];
+  const urls =
+    data?.pages
+      .filter((p) => p.status === 200 && p.contentType?.toLowerCase().includes("text/html"))
+      .slice(0, input.inspectLimit)
+      .map((p) => p.url) ?? [];
+  if (config.gscSite)
+    for (const url of urls)
+      observations.push({
+        ...(await run({ operation: "gsc.inspect", site: config.gscSite, url })),
+        name: `gsc.inspect:${url}`,
+      });
+  const result = aggregate("crawl", config.site, input, observations);
+  Object.assign(result.pages[0].response as object, {
+    context: config.context,
+    indexingSample: {
+      selected: config.gscSite ? urls : [],
+      limit: input.inspectLimit,
+      available: Boolean(config.gscSite),
+      meaning:
+        "Stored Google state for selected fetched HTML pages only; not a site indexing count. Missing inspection is unknown.",
+    },
+  });
+  return result;
+}

package/src/api/evaluate-change.ts

@@ -0,0 +1,189 @@
+import type { ChangeRecord } from "./change-record.js";
+import { compareObservation } from "./compare-snapshots.js";
+import { capture, type Evidence } from "./evidence.js";
+import type { ImportedSnapshot } from "./evidence-schema.js";
+import { canonical, normalizeReport, requireSame, Incompatible } from "./report-table.js";
+import { configSchema, gaRequestSchema, gscRequestSchema } from "./schema.js";
+import { snapshotOperations, observationName } from "./snapshot.js";
+import { normalizeGaProperty } from "../providers/ga.js";
+import { RequestError } from "../shared/http.js";
+
+export function localDay(at: string, timeZone: string): string {
+  const parts = new Intl.DateTimeFormat("en-US", {
+    timeZone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  }).formatToParts(new Date(at));
+  const value = (name: string) => parts.find((p) => p.type === name)!.value;
+  return `${value("year")}-${value("month")}-${value("day")}`;
+}
+function scope(provider: string, request: unknown) {
+  if (provider === "ga") {
+    const { offset: _offset, limit: _limit, returnPropertyQuota: _quota, ...rest } = gaRequestSchema.parse(request);
+    return rest;
+  }
+  const { startRow: _offset, rowLimit: _limit, ...rest } = gscRequestSchema.parse(request);
+  return rest;
+}
+export function boundReport(snapshot: ImportedSnapshot, name: string) {
+  const { context, observations } = snapshot.pages[0].response;
+  const config = configSchema.parse(context.config);
+  const expected = snapshotOperations(config, context.requestedDates.startDate, context.requestedDates.endDate, 1).find(
+    (op) => observationName(op) === name,
+  );
+  const observation = observations.find((o) => o.name === name);
+  if (!expected || !["ga.report", "gsc.report"].includes(expected.operation))
+    throw new Incompatible("Not a configured snapshot report.");
+  if (!observation || observation.status === "error" || !observation.pages.length)
+    throw new Incompatible("Report unavailable; absence is not zero.");
+  const provider = expected.operation === "ga.report" ? "ga" : "gsc";
+  const target =
+    expected.operation === "ga.report"
+      ? normalizeGaProperty(expected.property)
+      : expected.operation === "gsc.report"
+        ? expected.site
+        : "";
+  if (observation.provider !== provider || observation.operation !== "report" || observation.target !== target)
+    throw new Incompatible("Report identity does not match configured provider/property.");
+  if (expected.operation !== "ga.report" && expected.operation !== "gsc.report")
+    throw new Incompatible("Unsupported report.");
+  for (const page of observation.pages)
+    requireSame(
+      scope(provider, page.request),
+      scope(provider, expected.request),
+      "Report request differs from configured scope.",
+    );
+  return { observation, report: normalizeReport(observation, context) };
+}
+export const fingerprint = (value: unknown) => Bun.CryptoHasher.hash("sha256", canonical(value), "hex");
+
+export async function evaluateChange(
+  record: ChangeRecord,
+  baseline: ImportedSnapshot,
+  current: ImportedSnapshot | undefined,
+  maxRows: number,
+): Promise<Evidence> {
+  if (baseline.target !== record.site || (current && current.target !== record.site))
+    throw new RequestError("Change record and snapshots must identify the same exact site", null, "invalid_input");
+  const before = baseline.pages[0].response;
+  const after = current?.pages[0].response;
+  const names = [
+    ...new Set(
+      [...before.observations, ...(after?.observations ?? [])]
+        .filter((o) => o.operation === "report" && ["gsc", "ga"].includes(o.provider))
+        .map((o) => o.name),
+    ),
+  ].sort();
+  const result = await capture(
+    "pagesight",
+    "change.evaluate",
+    record.site,
+    {
+      recordSha256: fingerprint(record),
+      baselineSha256: fingerprint(baseline),
+      currentSha256: current ? fingerprint(current) : null,
+      maxRows,
+    },
+    async () => {
+      const observations = names.map((name) => {
+        try {
+          const a = boundReport(baseline, name);
+          const timezone = (a.report.semantics as { timezone: string }).timezone;
+          const deploymentDay = localDay(record.deployedAt, timezone);
+          if (a.report.end >= deploymentDay)
+            throw new Incompatible("Baseline must end before the deployment day in this report's timezone.");
+          if (!current || !after)
+            return {
+              name,
+              status: "pending",
+              reason: "After snapshot not supplied; no outcome is available.",
+              timezone,
+              deploymentDay,
+            };
+          const b = boundReport(current, name);
+          if (b.report.start <= deploymentDay)
+            throw new Incompatible("After period must start after the deployment day in this report's timezone.");
+          const identity = (snapshot: ImportedSnapshot) => {
+            const config = configSchema.parse(snapshot.pages[0].response.context.config);
+            return {
+              site: config.site,
+              gscSite: config.gscSite,
+              gaProperty: config.gaProperty ? normalizeGaProperty(config.gaProperty) : null,
+              productionHostname: config.productionHostname,
+            };
+          };
+          requireSame(
+            identity(baseline),
+            identity(current),
+            "Configured site, provider identity or production hostname changed.",
+          );
+          if (
+            a.observation.provider === "ga" &&
+            record.measurementChanges.some((change) => {
+              const day = localDay(change.at, timezone);
+              return day >= a.report.start && day <= b.report.end;
+            })
+          )
+            throw new Incompatible(
+              "A declared measurement change intersects the combined periods; GA deltas are withheld.",
+            );
+          return {
+            ...compareObservation(a.observation, b.observation, maxRows, before.context, after.context),
+            timezone,
+            deploymentDay,
+            gapDays: (Date.parse(b.report.start) - Date.parse(a.report.end)) / 86400000 - 1,
+            weekdays: {
+              baselineStart: new Date(a.report.start).getUTCDay(),
+              currentStart: new Date(b.report.start).getUTCDay(),
+            },
+          };
+        } catch (error) {
+          return {
+            name,
+            status: "incompatible",
+            reason:
+              error instanceof Incompatible
+                ? error.message
+                : "Unsupported report or reporting timezone; no delta calculated.",
+          };
+        }
+      });
+      return {
+        evaluationVersion: 1,
+        record,
+        recordVerification: "User-supplied deployment and change context, not independently verified",
+        scope: "Original configured snapshot reports; affectedUrls are annotations and do not filter report rows",
+        state: !current
+          ? observations.some((o) => o.status === "pending")
+            ? "pending"
+            : "unavailable"
+          : observations.some((o) => ["compared", "limited"].includes(o.status))
+            ? "descriptive"
+            : "unavailable",
+        observations,
+        confounded: record.overlappingChanges.length > 0,
+        contextChanged: Boolean(
+          after &&
+          canonical(configSchema.parse(before.context.config)) !== canonical(configSchema.parse(after.context.config)),
+        ),
+        limitations: [
+          "Cloudflare, Bing, crawl graphs, HTML, sitemaps and inspection evidence are unsupported; no cross-provider funnel is calculated.",
+          "Declared overlapping changes confound attribution. Configuration-context changes remain visible and can alter event interpretation.",
+          "Descriptive comparison only. This does not establish causality, statistical significance or the change's effect on rankings.",
+          "Deployment day is excluded in each report's timezone. Equal windows can still differ in weekdays, seasonality, demand or search-system changes.",
+          "Only declared measurement and overlapping changes are known. An empty list is not proof that no other changes occurred.",
+          "Affected URLs do not change property, hostname, channel or row scope. Missing rows remain unknown, never zero.",
+          "Collected timestamps do not prove immutable historical data; source hashes identify the supplied artifacts, not their authenticity.",
+        ],
+      };
+    },
+  );
+  const data = result.pages[0]?.response as { observations: Array<{ status: string }> } | undefined;
+  if (
+    result.status === "ok" &&
+    (!current || !data?.observations.length || data.observations.some((o) => o.status !== "compared"))
+  )
+    result.status = "partial";
+  return result;
+}

package/src/api/execute.ts

@@ -1,3 +1,11 @@
+import { verifyRender } from "./verify-render.js";
+import { followupChanges } from "./followup-changes.js";
+import { cloudflareAudit } from "./cloudflare.js";
+
+import { evaluateChange } from "./evaluate-change.js";
+import { crawl } from "./crawl.js";
+import { technicalChanges } from "./technical-changes.js";
+import { investigate } from "./investigation.js";
 import { assessSnapshot } from "./assessment.js";
 import { opportunities } from "./opportunities.js";
 import { gaRealtime } from "./ga-realtime.js";
@@ -34,6 +42,12 @@ export async function execute(input: unknown): Promise<Evidence> {
       "invalid_input",
     );
   }
+  if (
+    op.operation === "page.verify" &&
+    op.navigation &&
+    new URL(op.navigation.fromUrl).origin !== new URL(op.url).origin
+  )
+    throw new RequestError("Navigation source must share the target origin", null, "invalid_input");
   const result = await dispatch(op);
   if (op.operation.startsWith("ga.")) result.credential = await gaCredentialInfo();
   if (op.operation.startsWith("bing."))
@@ -48,6 +62,21 @@ export async function execute(input: unknown): Promise<Evidence> {
 
 async function dispatch(op: ParsedOperation): Promise<Evidence> {
   switch (op.operation) {
+    case "page.verify":
+      return verifyRender(op);
+    case "cloudflare.audit":
+      return cloudflareAudit(op);
+
+    case "change.followup":
+      return followupChanges(op.experiments, op.asOf ?? new Date().toISOString(), op.lagDays);
+    case "change.evaluate":
+      return evaluateChange(op.record, op.baseline, op.current, op.maxRows);
+    case "crawl":
+      return crawl(op, execute);
+    case "technical.compare":
+      return technicalChanges(op.baseline, op.current);
+    case "investigate":
+      return investigate(op, execute);
     case "opportunities":
       return opportunities(op.snapshot, {
         minImpressions: op.minImpressions,