@oriro/orirocli 0.1.0

package/skills/craft/vercel-optimize/lib/observation-safety.mjs

@@ -0,0 +1,217 @@
+export function splitCustomerSafeObservations(observations, abstentions = [], signals = {}) {
+  const safe = [];
+  const heldBack = [];
+  for (const observation of Array.isArray(observations) ? observations : []) {
+    const unsafeReason = unsupportedObservationReason(observation, abstentions, signals);
+    if (unsafeReason) {
+      heldBack.push({
+        candidateRef: observation?.candidateRef ?? null,
+        reason: unsafeReason,
+        needsEvidence: true,
+      });
+    } else {
+      safe.push(observation);
+    }
+  }
+  return { observations: safe, heldBackObservations: heldBack };
+}
+
+function unsupportedObservationReason(observation, abstentions = [], signals = {}) {
+  if (contradictsNoChangeReason(observation, abstentions)) {
+    return "This observation repeated an action that another investigation rejected. Re-run with a single scoped candidate before applying it.";
+  }
+  if (hasUnsupportedWafBotCategoryClaim(observation)) {
+    return "This observation described an Observability bot category as a WAF-rule condition without supported rule evidence. Re-run with documented WAF condition evidence before applying it.";
+  }
+  if (hasUnsafeBotProtectionObservation(observation)) {
+    return "This observation recommended Bot Protection or WAF changes without a staged safe-rollout plan and allowlist review. Promote it to a verified platform recommendation before applying it.";
+  }
+  if (hasStaleNextCacheApiObservation(observation, signals)) {
+    return "This observation used a cache API that does not match the detected framework-version evidence. Re-run with the current Next.js cache evidence before applying it.";
+  }
+  if (hasUnsupportedFrameworkCausalClaim(observation)) {
+    return "This observation made a framework-specific cause claim that verification could not support. Re-run with runtime logs or official framework evidence before applying it.";
+  }
+  if (hasUnsupportedStaticGenerationClaim(observation)) {
+    return "This observation made a static-generation behavior claim that verification could not support. Re-run with route-manifest or runtime evidence before applying it.";
+  }
+  if (hasUnsupportedSourceAbsenceClaim(observation)) {
+    return "This observation made a source-file absence claim that verification could not support. Re-run with a file-existence check or runtime logs before applying it.";
+  }
+  if (hasUnsupportedCacheLifeCdnClaim(observation)) {
+    return "This observation depended on an unsupported cacheLife-to-CDN claim. Re-run with production header evidence before applying it.";
+  }
+  if (hasUnsupportedRuntimeRootCauseClaim(observation)) {
+    return "This observation made a runtime root-cause claim that needs log, stack, or upstream response evidence before it can ship.";
+  }
+  if (hasImplementationGradeObservationAction(observation)) {
+    return "This observation described an implementation change that needs the ready-to-apply recommendation evidence bar before it can ship.";
+  }
+  return null;
+}
+
+function observationText(observation) {
+  return [observation?.summary, observation?.evidence, observation?.suggestedAction]
+    .filter(Boolean)
+    .join(" ");
+}
+
+function evidenceText(observation) {
+  return [observation?.summary, observation?.evidence].filter(Boolean).join(" ");
+}
+
+function hasUnsupportedWafBotCategoryClaim(observation) {
+  const text = observationText(observation);
+  if (!/\bWAF\b/i.test(text)) return false;
+  return (
+    /\bbot_category\s*=/i.test(text) ||
+    /\btarget(?:ing)?\s+(?:browser_impersonation|automated_browser|ecommerce|monitor)\b/i.test(text)
+  );
+}
+
+function hasUnsafeBotProtectionObservation(observation) {
+  const text = observationText(observation);
+  if (!/\b(?:Bot Protection|BotID|bot_filter|WAF|managed bot rules?)\b/i.test(text)) return false;
+  const recommendsAction =
+    /\b(?:enable|add|create|configure|challenge|deny|block|rate-limit|target)\b/i.test(
+      String(observation?.suggestedAction ?? ""),
+    );
+  if (!recommendsAction) return false;
+  const hasSafeRollout = /\b(?:staged|log mode|log action|dry run)\b/i.test(text);
+  const hasAllowlist = /\ballowlist|exclusions?\b/i.test(text);
+  return !(hasSafeRollout && hasAllowlist);
+}
+
+function hasStaleNextCacheApiObservation(observation, signals = {}) {
+  const text = observationText(observation);
+  if (!/\bunstable_cache\b/.test(text)) return false;
+  if (signals?.stack?.framework !== "next") return false;
+  const major = parseInt(
+    String(signals?.stack?.frameworkVersion ?? "").match(/\d+/)?.[0] ?? "",
+    10,
+  );
+  return Number.isFinite(major) && major >= 16;
+}
+
+function hasImplementationGradeObservationAction(observation) {
+  const action = String(observation?.suggestedAction ?? "");
+  if (action.trim() === "") return false;
+  if (
+    /\b(?:use cache:\s*remote|unstable_cache|Cache-Control|s-maxage|cacheLife|export const revalidate|checkBotId|BotID)\b/i.test(
+      action,
+    )
+  )
+    return true;
+  return (
+    /\b(?:enable|add|wrap|apply|move|parallelize|set|create|configure|deny|challenge|block|fix|replace|refactor|rewrite|upgrade|downgrade)\b/i.test(
+      action,
+    ) ||
+    /\bcache\s+(?:the|this|that|shared|public|origin|response|route|data|lookup|fetch|helper)\b/i.test(
+      action,
+    ) ||
+    /\bturn\s+(?:on|off)\b/i.test(action) ||
+    /\bswitch\s+(?:to|from|the|this)\b/i.test(action) ||
+    /\buse\s+Promise\.all\b/i.test(action) ||
+    /\b(?:raise|lower|increase|decrease)\s+(?:the\s+)?(?:TTL|timeout|memory|CPU|cache|cache lifetime|duration)\b/i.test(
+      action,
+    )
+  );
+}
+
+function contradictsNoChangeReason(observation, abstentions) {
+  const target = candidateTarget(observation?.candidateRef);
+  if (!target) return false;
+  const lowerObservationText = observationText(observation).toLowerCase();
+  const relevantReasons = abstentions
+    .filter((a) => candidateTarget(a?.candidateRef) === target)
+    .map((a) => String(a?.reason ?? "").toLowerCase());
+  if (relevantReasons.length === 0) return false;
+
+  if (
+    /\bparalleliz(?:e|ing)\b/.test(lowerObservationText) &&
+    /\bgetsession\b/.test(lowerObservationText) &&
+    relevantReasons.some(
+      (reason) =>
+        /\bgetsession\b/.test(reason) &&
+        /\b(?:gates?|redirect|auth-preserving|blocked)\b/.test(reason),
+    )
+  ) {
+    return true;
+  }
+  return false;
+}
+
+function candidateTarget(ref) {
+  if (typeof ref !== "string") return null;
+  const idx = ref.indexOf(":");
+  if (idx === -1) return null;
+  return ref.slice(idx + 1);
+}
+
+function hasUnsupportedFrameworkCausalClaim(observation) {
+  const text = observationText(observation).toLowerCase();
+  if (!text.includes("notfound") || !text.includes("use cache")) return false;
+  return (
+    /known next\.js cache components edge case/.test(text) ||
+    /next\.js\s+\d+(?:\.\d+)?[^.]{0,120}treats[^.]{0,120}dynamic api/.test(text) ||
+    /can surface as 5xx/.test(text) ||
+    /surface as 500/.test(text) ||
+    /instead of throwing inside (?:the )?cache/.test(text) ||
+    /cache boundary/.test(text)
+  );
+}
+
+function hasUnsupportedStaticGenerationClaim(observation) {
+  const text = observationText(observation).toLowerCase();
+  if (!/\bgeneratestaticparams\b/.test(text)) return false;
+  return (
+    /\b(?:returns?\s*(?:an\s+)?empty|\[\])\b[^.\n]{0,240}\b(?:every request|on[- ]demand|no params? (?:are )?prebuilt|populate generatestaticparams|served from (?:the )?cdn|hit bucket|cachebreakdown)\b/i.test(
+      text,
+    ) ||
+    /\b(?:every request|on[- ]demand|no params? (?:are )?prebuilt|populate generatestaticparams|served from (?:the )?cdn|hit bucket|cachebreakdown)\b[^.\n]{0,240}\b(?:returns?\s*(?:an\s+)?empty|\[\])\b/i.test(
+      text,
+    ) ||
+    /\bdynamic\s*=\s*['"`]error['"`]\b[^.\n]{0,240}\b(?:generatestaticparams|dynamicparams|every request|on[- ]demand)\b/i.test(
+      text,
+    )
+  );
+}
+
+function hasUnsupportedSourceAbsenceClaim(observation) {
+  const ref = String(observation?.candidateRef ?? "");
+  if (!ref.startsWith("route_errors:")) return false;
+  const text = observationText(observation).toLowerCase();
+  return /\b(?:enoent|no\s+(?:matching|corresponding)\s+(?:mdx|file|post)|missing\s+(?:mdx|file|post)|does\s+not\s+exist|not\s+found\s+on\s+disk)\b/.test(
+    text,
+  );
+}
+
+function hasUnsupportedCacheLifeCdnClaim(observation) {
+  return hasUnsupportedCacheLifeCdnText(observationText(observation));
+}
+
+export function hasUnsupportedCacheLifeCdnText(text) {
+  if (typeof text !== "string" || !/\bcacheLife\b/i.test(text)) return false;
+  if (/\btoLaunch-\d+\b/i.test(text)) return true;
+  return (
+    /\bcacheLife\b[^.\n]{0,240}\b(?:Cache-Control|s-maxage|CDN|edge cache|cache breakdown|x-vercel-cache|HIT|MISS|function (?:still )?runs per request|every request invokes the function|canonical|toLaunch-\d+)\b/i.test(
+      text,
+    ) ||
+    /\b(?:Cache-Control|s-maxage|CDN|edge cache|cache breakdown|x-vercel-cache|HIT|MISS|function (?:still )?runs per request|every request invokes the function|canonical|toLaunch-\d+)\b[^.\n]{0,240}\bcacheLife\b/i.test(
+      text,
+    ) ||
+    /\b(?:no|never|without|missing)\s+cacheLife\b[^.\n]{0,240}\b(?:no|not|never|0%|every|per request|function)\b[^.\n]{0,120}\b(?:cache|cached|hit|runs?|invoke)/i.test(
+      text,
+    )
+  );
+}
+
+function hasUnsupportedRuntimeRootCauseClaim(observation) {
+  const text = observationText(observation);
+  if (!/\b(?:caused by|root cause|responsible for failures|would produce)\b/i.test(text))
+    return false;
+  if (!/\b(?:5xx|500|error|failures?)\b/i.test(text)) return false;
+  return !/\b(?:logs?\s+(?:show|confirm|include|contain)|stack\s+(?:shows|trace|evidence)|trace\s+(?:shows|confirms)|exception\s+(?:shows|confirms)|response body\s+(?:shows|confirms)|runtime evidence)\b/i.test(
+    evidenceText(observation),
+  );
+}

package/skills/craft/vercel-optimize/lib/project-facts.mjs

@@ -0,0 +1,101 @@
+// Single source for "already on" project facts. Feeds report Strengths, sub-agent brief, and verifier contradiction check.
+// contradictPhrases must lowercase exactly — verifier does case-insensitive substring match.
+
+// Stable order = byte-identical brief output. Empty result when project config didn't load — don't pretend.
+export function deriveProjectFacts(signals) {
+  const out = [];
+  const cfg = signals?.project?.defaultResourceConfig;
+  const projectErr = signals?.project?.error;
+  if (!cfg || projectErr) return out;
+
+  if (cfg.fluid === true) {
+    out.push({
+      id: "fluid_compute",
+      strength:
+        "Fluid Compute is enabled (`defaultResourceConfig.fluid=true`) — instance reuse + reduced cold starts active.",
+      briefLine:
+        "Fluid Compute is ENABLED on this project (`defaultResourceConfig.fluid=true`). Do not recommend toggling it on.",
+      contradictPhrases: [
+        "enable fluid compute",
+        "enable fluid",
+        "turn on fluid compute",
+        "switch to fluid compute",
+        "migrate to fluid compute",
+        "opt in to fluid compute",
+      ],
+    });
+  }
+  if (cfg.elasticConcurrencyEnabled === true) {
+    out.push({
+      id: "in_function_concurrency",
+      strength:
+        "In-function concurrency is enabled — multiple invocations share a single function instance, lowering active CPU costs on I/O-bound work.",
+      briefLine: "In-function concurrency is ENABLED. Do not recommend toggling it on.",
+      contradictPhrases: [
+        "enable in-function concurrency",
+        "enable elastic concurrency",
+        "turn on in-function concurrency",
+        "enable concurrent invocations",
+      ],
+    });
+  }
+  if (cfg.functionDefaultMemoryType === "standard") {
+    out.push({
+      id: "memory_standard",
+      strength:
+        "Function memory tier: Standard (2GB) — the cost-efficient default; upgrade to Performance (4GB) only with memory, CPU-bound, or latency-sensitive route evidence.",
+      briefLine:
+        "Function memory tier is Standard (2GB), the cost-efficient default. Recommending an upgrade to Performance (4GB) requires memory, CPU-bound, or latency-sensitive route evidence.",
+      contradictPhrases: [],
+    });
+  } else if (cfg.functionDefaultMemoryType === "performance") {
+    out.push({
+      id: "memory_performance",
+      strength:
+        "Function memory tier: **Performance (4GB)** — verify this is intentional; Performance costs ~2x Standard. If your routes don't saturate Standard's memory headroom, downgrade.",
+      briefLine:
+        "Function memory tier is Performance (4GB). Do not recommend upgrading further — the next valid tier change is downgrading to Standard.",
+      contradictPhrases: [
+        "upgrade memory to performance",
+        "upgrade to performance memory",
+        "switch to performance memory",
+        "enable performance memory",
+      ],
+    });
+  }
+  if (Array.isArray(cfg.functionDefaultRegions) && cfg.functionDefaultRegions.length > 0) {
+    const r = cfg.functionDefaultRegions;
+    out.push({
+      id: "function_regions",
+      strength: `Function regions: \`${r.join(", ")}\` (${r.length === 1 ? "single region" : "multi-region"}).`,
+      briefLine: `Function regions configured: ${r.join(", ")}. If your rec hinges on region placement, it must accept this configuration as the starting point.`,
+      contradictPhrases: [],
+    });
+  }
+  if (cfg.functionZeroConfigFailover === true) {
+    out.push({
+      id: "zero_config_failover",
+      strength: "Function failover is enabled in project config.",
+      briefLine: "Function failover is ENABLED in project config. Do not recommend enabling it.",
+      contradictPhrases: [
+        "enable zero-config failover",
+        "enable multi-region failover",
+        "turn on zero-config failover",
+      ],
+    });
+  }
+  return out;
+}
+
+// `why` excluded — citing a fact as evidence ("fluid is on, so …") is legitimate, not contradiction.
+export function findRecContradictions(rec, facts) {
+  if (!rec || typeof rec !== "object") return [];
+  if (!Array.isArray(facts) || facts.length === 0) return [];
+  const haystack = [rec.what, rec.fix, rec.desiredBehavior, rec.currentBehavior]
+    .map((s) => (typeof s === "string" ? s.toLowerCase() : ""))
+    .join("\n");
+  if (!haystack) return [];
+  return facts.filter((f) =>
+    (f.contradictPhrases ?? []).some((p) => haystack.includes(p.toLowerCase())),
+  );
+}

package/skills/craft/vercel-optimize/lib/queries.mjs

@@ -0,0 +1,333 @@
+// Declarative metric-query registry. Single source for every `vercel metrics ...` call.
+//
+// CLI default --since is 1h. Mixing 1h with 14d windows silently produces incompatible rollups — every query MUST pass since: TIME_WINDOW. test/time-window.test.mjs enforces this.
+// 14d: long enough for weekly cycles, short enough to surface recent regressions before stale data dilutes them.
+
+import { normalizeSummary } from "./vercel.mjs";
+
+export const TIME_WINDOW = "14d";
+
+// CLI default cardinality cap is 10 — too small for a typical app.
+const ROUTE_LIMIT = 200;
+const HOST_LIMIT = 50;
+const DIM_LIMIT = 50;
+
+// CLI emits value under `<metric_id_with_underscores>_<aggregation>` (e.g. `vercel_request_count_sum`).
+function defaultNormalize(metricId, aggregation, groupBy) {
+  return (resp) => ({ rows: normalizeSummary(resp, metricId, aggregation, groupBy) });
+}
+
+// Collapse (route × function_start_type) rows into one row per route. Observed values: "cold", "hot", "prewarmed".
+function normalizeColdStart(metricId, aggregation) {
+  return (resp) => {
+    const rows = normalizeSummary(resp, metricId, aggregation, ["route", "function_start_type"]);
+    const byRoute = new Map();
+    for (const r of rows) {
+      if (!r.route) continue;
+      const prior = byRoute.get(r.route) ?? {
+        route: r.route,
+        total: 0,
+        coldCount: 0,
+        warmCount: 0,
+        prewarmedCount: 0,
+      };
+      const v = r.value ?? 0;
+      prior.total += v;
+      if (r.function_start_type === "cold") prior.coldCount += v;
+      else if (r.function_start_type === "hot") prior.warmCount += v;
+      else if (r.function_start_type === "prewarmed") prior.prewarmedCount += v;
+      byRoute.set(r.route, prior);
+    }
+    return {
+      rows: [...byRoute.values()].map((r) => ({
+        ...r,
+        coldPct: r.total > 0 ? r.coldCount / r.total : 0,
+      })),
+    };
+  };
+}
+
+export const QUERIES = [
+  {
+    id: "requestsByRouteCache",
+    metricId: "vercel.request.count",
+    aggregation: "sum",
+    groupBy: ["route", "cache_result"],
+    limit: ROUTE_LIMIT,
+    description:
+      "Request count per route × cache_result. Source of cache hit rate; total invocations folds across cache_result.",
+  },
+  {
+    id: "fnDurationP95ByRoute",
+    metricId: "vercel.function_invocation.function_duration_ms",
+    aggregation: "p95",
+    groupBy: ["route"],
+    limit: ROUTE_LIMIT,
+    description: "p95 wall-clock function duration per route. Canonical slow-route signal.",
+  },
+  {
+    id: "requestsByRouteStatus",
+    metricId: "vercel.request.count",
+    aggregation: "sum",
+    groupBy: ["route", "http_status"],
+    limit: ROUTE_LIMIT,
+    description:
+      "Request count per route × http_status. Compatibility fallback for older route_errors fixtures.",
+  },
+  {
+    id: "fnStatusByRoute",
+    metricId: "vercel.function_invocation.count",
+    aggregation: "sum",
+    groupBy: ["route", "http_status"],
+    limit: ROUTE_LIMIT,
+    description:
+      "Function invocation count per route × http_status. Canonical 5xx source for slow_route disqualification and route_errors.",
+  },
+  {
+    id: "requestsByRouteMethod",
+    metricId: "vercel.request.count",
+    aggregation: "sum",
+    groupBy: ["route", "request_method"],
+    limit: ROUTE_LIMIT,
+    description:
+      "Request count per route × request_method. Uncached_route gate uses this to skip mostly-POST routes (Server Actions, mutations) where 0% cache is correct behavior.",
+  },
+  {
+    id: "externalApiP75",
+    metricId: "vercel.external_api_request.request_duration_ms",
+    aggregation: "p75",
+    groupBy: ["origin_hostname"],
+    limit: HOST_LIMIT,
+    description: "p75 external API duration per origin hostname.",
+  },
+
+  {
+    id: "fnStartTypeByRoute",
+    metricId: "vercel.function_invocation.count",
+    aggregation: "sum",
+    groupBy: ["route", "function_start_type"],
+    limit: ROUTE_LIMIT,
+    description:
+      "Function invocation count split by cold | hot | prewarmed. Feeds cold_start gate.",
+    normalizer: normalizeColdStart("vercel.function_invocation.count", "sum"),
+  },
+  {
+    id: "fnGbHrByRoute",
+    metricId: "vercel.function_invocation.function_duration_gbhr",
+    aggregation: "sum",
+    groupBy: ["route"],
+    limit: ROUTE_LIMIT,
+    description: "Billed GB-hours per route (function duration in Fluid billing).",
+  },
+  {
+    id: "fnCpuMsByRoute",
+    metricId: "vercel.function_invocation.function_cpu_time_ms",
+    aggregation: "sum",
+    groupBy: ["route"],
+    limit: ROUTE_LIMIT,
+    description:
+      "Active CPU time per route. Fluid Compute bills on this; high CPU = expensive route.",
+  },
+  {
+    id: "fnPeakMemoryByRoute",
+    metricId: "vercel.function_invocation.peak_memory_mb",
+    aggregation: "max",
+    groupBy: ["route"],
+    limit: ROUTE_LIMIT,
+    description: "Peak memory observed per route. Compared against provisioned to right-size.",
+  },
+  {
+    id: "fnProvisionedMemoryByRoute",
+    metricId: "vercel.function_invocation.provisioned_memory_mb",
+    aggregation: "max",
+    groupBy: ["route"],
+    limit: ROUTE_LIMIT,
+    description: "Provisioned memory per route. Feeds oversized_memory gate.",
+  },
+  {
+    id: "fnTtfbP95ByRoute",
+    metricId: "vercel.function_invocation.ttfb_ms",
+    aggregation: "p95",
+    groupBy: ["route"],
+    limit: ROUTE_LIMIT,
+    description:
+      "Server-measured time-to-first-byte per route. Complements function_duration_ms p95.",
+  },
+
+  {
+    id: "fdtByRoute",
+    metricId: "vercel.request.fdt_total_bytes",
+    aggregation: "sum",
+    groupBy: ["route"],
+    limit: ROUTE_LIMIT,
+    description: "Fast Data Transfer bytes per route. Bandwidth cost driver.",
+  },
+  {
+    id: "fdtByBot",
+    metricId: "vercel.request.fdt_total_bytes",
+    aggregation: "sum",
+    groupBy: ["bot_category"],
+    limit: DIM_LIMIT,
+    description:
+      "FDT bytes by bot category. Empty `bot_category` = human traffic; non-empty = bots.",
+  },
+  {
+    id: "fdtByCache",
+    metricId: "vercel.request.fdt_total_bytes",
+    aggregation: "sum",
+    groupBy: ["cache_result"],
+    limit: DIM_LIMIT,
+    description: "FDT bytes by cache_result. Uncached vs cached bandwidth.",
+  },
+
+  {
+    id: "middlewareCount",
+    metricId: "vercel.middleware_invocation.count",
+    aggregation: "sum",
+    groupBy: ["request_path"],
+    limit: ROUTE_LIMIT,
+    description:
+      "Middleware invocations per request_path. Heavy middleware traffic = missing matcher.",
+  },
+  {
+    id: "middlewareDurationP95",
+    metricId: "vercel.middleware_invocation.duration_ms",
+    aggregation: "p95",
+    groupBy: ["request_path"],
+    limit: ROUTE_LIMIT,
+    description: "p95 middleware duration per request_path.",
+  },
+
+  {
+    id: "isrReadsByRoute",
+    metricId: "vercel.isr_operation.read_units",
+    aggregation: "sum",
+    groupBy: ["route"],
+    limit: ROUTE_LIMIT,
+    description: "ISR read units per route. Healthy when high relative to writes.",
+  },
+  {
+    id: "isrWritesByRoute",
+    metricId: "vercel.isr_operation.write_units",
+    aggregation: "sum",
+    groupBy: ["route"],
+    limit: ROUTE_LIMIT,
+    description: "ISR write units per route. High writes/reads = over-aggressive revalidate.",
+  },
+
+  {
+    id: "imageCount",
+    metricId: "vercel.image_transformation.count",
+    aggregation: "sum",
+    groupBy: [],
+    limit: 1,
+    description: "Total image transformations performed.",
+  },
+  {
+    id: "imageByHost",
+    metricId: "vercel.image_transformation.count",
+    aggregation: "sum",
+    groupBy: ["source_image_hostname"],
+    limit: HOST_LIMIT,
+    description:
+      "Image transformations per source hostname. Identify which hosts dominate the bill.",
+  },
+  {
+    id: "imageSourceBytes",
+    metricId: "vercel.image_transformation.source_size_bytes",
+    aggregation: "sum",
+    groupBy: [],
+    limit: 1,
+    description: "Bytes of source images optimized. High = ingress bandwidth cost.",
+  },
+
+  {
+    id: "cwvLcpByRoute",
+    metricId: "vercel.speed_insights_metric.lcp",
+    aggregation: "p75",
+    groupBy: ["route"],
+    limit: ROUTE_LIMIT,
+    description: "p75 Largest Contentful Paint per route. > 2500ms = poor.",
+  },
+  {
+    id: "cwvInpByRoute",
+    metricId: "vercel.speed_insights_metric.inp",
+    aggregation: "p75",
+    groupBy: ["route"],
+    limit: ROUTE_LIMIT,
+    description: "p75 Interaction to Next Paint per route. > 200ms = poor.",
+  },
+  {
+    id: "cwvClsByRoute",
+    metricId: "vercel.speed_insights_metric.cls",
+    aggregation: "p75",
+    groupBy: ["route"],
+    limit: ROUTE_LIMIT,
+    description: "p75 Cumulative Layout Shift per route. > 0.1 = poor.",
+  },
+  {
+    id: "cwvTtfbByRoute",
+    metricId: "vercel.speed_insights_metric.ttfb_ms",
+    aggregation: "p75",
+    groupBy: ["route"],
+    limit: ROUTE_LIMIT,
+    description: "p75 client-measured TTFB per route.",
+  },
+  {
+    id: "cwvCount",
+    metricId: "vercel.speed_insights_metric.count",
+    aggregation: "sum",
+    groupBy: [],
+    limit: 1,
+    description:
+      "Total Speed Insights measurements. Use to decide whether CWV gates have enough signal.",
+  },
+  {
+    id: "cwvCountByRoute",
+    metricId: "vercel.speed_insights_metric.count",
+    aggregation: "sum",
+    groupBy: ["route"],
+    limit: ROUTE_LIMIT,
+    description:
+      "Speed Insights measurements per route. CWV route gates require at least 50 samples on the specific route.",
+  },
+
+  {
+    id: "firewallByAction",
+    metricId: "vercel.firewall_action.count",
+    aggregation: "sum",
+    groupBy: ["waf_action"],
+    limit: DIM_LIMIT,
+    description: "Firewall action count per waf_action (allow | challenge | block | log).",
+  },
+  {
+    id: "botIdChecks",
+    metricId: "vercel.bot_id_check.count",
+    aggregation: "sum",
+    groupBy: [],
+    limit: 1,
+    description: "Total BotID checks. > 0 confirms BotID is wired up; = 0 confirms it is not.",
+  },
+
+  {
+    id: "externalApiCount",
+    metricId: "vercel.external_api_request.count",
+    aggregation: "sum",
+    groupBy: ["origin_hostname"],
+    limit: HOST_LIMIT,
+    description: "External API call count per origin hostname.",
+  },
+  {
+    id: "externalApiBytes",
+    metricId: "vercel.external_api_request.transfer_bytes",
+    aggregation: "sum",
+    groupBy: ["origin_hostname"],
+    limit: HOST_LIMIT,
+    description: "Outbound bytes per external API hostname.",
+  },
+];
+
+export function normalizerFor(entry) {
+  if (entry.normalizer) return entry.normalizer;
+  return defaultNormalize(entry.metricId, entry.aggregation, entry.groupBy);
+}