@oriro/orirocli 0.1.0

package/skills/craft/vercel-optimize/lib/gates/platform-bot-protection.mjs

@@ -0,0 +1,123 @@
+// Recommend BotID only when there's EVIDENCE of bot traffic or scale large enough that the rec is defensible.
+// Without an evidence gate the rec fires on quiet hobby sites and erodes trust.
+const MIN_BOT_PCT = 0.05;
+const MIN_EDGE_COST = 25; // halved for 14d window
+const MIN_TOTAL_REQUESTS = 14_000; // ~14k/14d matches the prior 30k/30d rate
+const MIN_TOTAL_FDT_BYTES = 1_000_000;
+
+export const metadata = {
+  id: "platform_bot_protection",
+  threshold:
+    "botIdEnabled=false AND (botPct >= 0.05 OR edge_cost >= $25/window OR requests >= 14k/14d)",
+  billingDimension: "edge-requests",
+  scope: "account",
+  sourceCitation: "vercel-optimize gate threshold",
+  description:
+    "When BotID is disabled AND there is evidence (observed bot bandwidth share, edge cost, or substantial request volume) that bot traffic is non-trivial. Bot traffic inflates edge request counts without delivering user value; staged bot protection can reduce waste on bot-heavy projects. Skipped on quiet projects with no bot evidence — the recommendation would be noise.",
+};
+
+export function gate(signals) {
+  // BotID surfaces under several legacy fields; check all.
+  const botEnabled =
+    signals.project?.security?.botIdEnabled === true ||
+    signals.project?.security?.botProtection === true ||
+    signals.project?.botProtection?.enabled === true ||
+    signals.project?.delegatedProtection?.bot === true;
+  if (botEnabled) return [];
+
+  // Project config failed — we can't tell if BotID is on, so stay silent.
+  if (signals.project?.error) return [];
+
+  const totalRequests = totalRequestsFromSignals(signals);
+  const botShare = computeBotShare(signals);
+  const edgeService = (signals.usage?.services ?? []).find((s) =>
+    /edge.request/i.test(s.name ?? ""),
+  );
+  const edgeCost = edgeService?.billedCost ?? null;
+
+  // Require observable bot share, edge cost, OR substantial traffic — otherwise rec is just config nagging.
+  const hasObservedBots = botShare?.botPct != null && botShare.botPct >= MIN_BOT_PCT;
+  const hasMaterialEdgeCost = edgeCost != null && edgeCost >= MIN_EDGE_COST;
+  const hasSubstantialTraffic = totalRequests >= MIN_TOTAL_REQUESTS;
+  if (!hasObservedBots && !hasMaterialEdgeCost && !hasSubstantialTraffic) return [];
+
+  const challengeRule = signals.project?.security?.managedRules?.bot_filter;
+  const ruleNote = challengeRule?.active
+    ? `firewall bot_filter rule active (action=${challengeRule.action ?? "?"})`
+    : "no firewall bot_filter rule";
+
+  // Kicker on high observed bot share — harder evidence than config alone.
+  let priority = edgeCost != null ? Math.max(20, Math.round(edgeCost)) : 30;
+  if (botShare?.botPct != null && botShare.botPct > 0.2) priority += 20;
+
+  // Confidence bumps when we can SEE bot traffic, not just infer from config.
+  let confidence = edgeCost != null ? 0.85 : 0.6;
+  if (botShare?.botPct != null && botShare.botPct > 0.2)
+    confidence = Math.min(0.95, confidence + 0.05);
+
+  const botShareNote =
+    botShare?.botPct != null
+      ? `bot_fdt_pct=${(botShare.botPct * 100).toFixed(0)}%`
+      : "bot_fdt_pct=unknown";
+
+  return [
+    {
+      kind: metadata.id,
+      scope: "account",
+      files: [],
+      priority,
+      confidence,
+      o11ySignal:
+        edgeCost != null
+          ? `edge_cost=${edgeCost.toFixed(0)},bot_protection=disabled,${botShareNote},${ruleNote}`
+          : `requests=${totalRequests},bot_protection=disabled,${botShareNote},${ruleNote}`,
+      reason:
+        botShare?.botPct != null && botShare.botPct > 0.2
+          ? "BotID disabled with observable bot bandwidth share"
+          : "BotID disabled with observable traffic",
+      question:
+        botShare?.botPct != null && botShare.botPct > 0.2
+          ? `Bot traffic accounts for ${(botShare.botPct * 100).toFixed(0)}% of FDT bytes (top category: ${botShare.topCategory ?? "unknown"}). Would enabling BotID + a challenge rule reduce that share?`
+          : "Would enabling BotID (Bot Protection) reduce edge request volume from automated traffic?",
+      evidence: {
+        botEnabled: false,
+        edgeCost,
+        totalRequests,
+        managedRules: challengeRule ?? null,
+        botShare: botShare ?? null,
+      },
+    },
+  ];
+}
+
+function totalRequestsFromSignals(signals) {
+  const rows = signals.metrics?.requestsByRouteCache?.rows;
+  if (!Array.isArray(rows)) return 0;
+  return rows.reduce((s, r) => s + (r.value ?? 0), 0);
+}
+
+// CLI convention: bot_category="" means "not classified as a bot" (human + unclassified); any non-empty = bot.
+function computeBotShare(signals) {
+  const rows = signals.metrics?.fdtByBot?.rows;
+  if (!Array.isArray(rows) || rows.length === 0) return null;
+  let humanBytes = 0;
+  let botBytes = 0;
+  let topCategory = null;
+  let topBytes = 0;
+  for (const r of rows) {
+    const v = r.value ?? 0;
+    const cat = r.bot_category ?? "";
+    if (cat === "") {
+      humanBytes += v;
+    } else {
+      botBytes += v;
+      if (v > topBytes) {
+        topBytes = v;
+        topCategory = cat;
+      }
+    }
+  }
+  const total = humanBytes + botBytes;
+  if (total < MIN_TOTAL_FDT_BYTES) return null;
+  return { humanBytes, botBytes, botPct: botBytes / total, topCategory };
+}

package/skills/craft/vercel-optimize/lib/gates/platform-fluid-compute.mjs

@@ -0,0 +1,94 @@
+// Second branch (slow p95 + traffic floor) keeps the gate useful on teams where
+// cold-start isn't directly observable — common on CLI v53 — trading specificity for coverage.
+export const metadata = {
+  id: "platform_fluid_compute",
+  threshold: "fluid=false AND (any cold_start signal OR any route with p95>1000ms AND inv>1000)",
+  billingDimension: "function-duration",
+  scope: "account",
+  sourceCitation: "vercel-optimize gate threshold",
+  description:
+    "When Fluid Compute is disabled on a project that shows cold-start pressure (high cold-start rate) or sustained slow function p95 on hot routes. Fluid Compute reduces cold starts via instance reuse — recommend turning it on at the project level rather than per-route.",
+};
+
+export function gate(signals) {
+  // If project config failed to load we can't tell if Fluid is on; recommending it when already-on
+  // erodes trust badly, so stay silent and let Strengths note the gap.
+  if (signals.project?.error) return [];
+
+  const fluidEnabled =
+    signals.project?.resourceConfig?.fluid === true ||
+    signals.project?.defaultResourceConfig?.fluid === true;
+  if (fluidEnabled) return [];
+
+  const cold = extractHighColdRoutes(signals);
+  const slow = extractSlowHotRoutes(signals);
+  if (cold.length === 0 && slow.length === 0) return [];
+
+  return [
+    {
+      kind: metadata.id,
+      scope: "account",
+      files: [],
+      priority: 50,
+      confidence: cold.length > 0 ? 0.85 : 0.65,
+      o11ySignal:
+        cold.length > 0
+          ? `${cold.length} route(s) with high cold-start rate`
+          : `${slow.length} hot route(s) with p95>1s; cold-start not directly observable`,
+      reason:
+        cold.length > 0
+          ? "cold starts observed and Fluid Compute is disabled"
+          : "slow hot routes and Fluid Compute is disabled",
+      question:
+        "Would enabling Fluid Compute reduce cold-start and warm-instance reuse overhead for the observed hot routes?",
+      evidence: { fluidEnabled, highColdRoutes: cold.slice(0, 5), slowHotRoutes: slow.slice(0, 5) },
+    },
+  ];
+}
+
+function extractHighColdRoutes(signals) {
+  const live = signals.metrics?.fnStartTypeByRoute?.rows;
+  if (Array.isArray(live) && live.some((r) => "coldCount" in r || "coldPct" in r)) {
+    return live.filter((r) => r.route && (r.coldPct ?? 0) > 0.3 && (r.total ?? 0) > 100);
+  }
+  // Legacy pre-derived fixture shape.
+  const direct = signals.metrics?.coldStartByRoute?.rows;
+  if (Array.isArray(direct)) {
+    return direct.filter((r) => r.route && (r.coldPct ?? 0) > 0.3 && (r.total ?? 0) > 100);
+  }
+  const legacy = signals.metrics?.coldStarts?.series;
+  if (Array.isArray(legacy)) {
+    return legacy
+      .map((s) => {
+        const total = s.summary?.count ?? 0;
+        const coldCount = s.summary?.coldCount ?? s.summary?.sum ?? 0;
+        return { route: s.groupValues?.route, total, coldPct: total > 0 ? coldCount / total : 0 };
+      })
+      .filter((r) => r.route && r.coldPct > 0.3 && r.total > 100);
+  }
+  return [];
+}
+
+function extractSlowHotRoutes(signals) {
+  const dur = signals.metrics?.fnDurationP95ByRoute?.rows;
+  const cache = signals.metrics?.requestsByRouteCache?.rows;
+  if (!Array.isArray(dur)) return [];
+
+  // Sum requests per route across cache_result.
+  const inv = new Map();
+  for (const r of cache ?? []) {
+    if (!r.route) continue;
+    inv.set(r.route, (inv.get(r.route) ?? 0) + (r.value ?? 0));
+  }
+  return (
+    dur
+      .filter((r) => r.route)
+      .map((r) => ({
+        route: r.route,
+        p95Ms: Math.round(r.value ?? 0),
+        invocations: inv.get(r.route) ?? 0,
+      }))
+      // inv>500 floor is the 14d-window equivalent of the old 1000/30d.
+      .filter((r) => r.p95Ms > 1000 && r.invocations > 500)
+  );
+}

package/skills/craft/vercel-optimize/lib/gates/region-misconfig.mjs

@@ -0,0 +1,71 @@
+// Region-misconfig gate. Branch 2 (scanner-only) — per-region TTFB data gap.
+//
+// The intended Branch 1 (region-grouped TTFB metric) was preflight-tested but the
+// CLI returned INTERNAL_ERROR for the `--group-by route --group-by function_region`
+// combination, and SAML re-auth blocked single-dim verification (see Phase 0 in
+// plans/wild-splashing-flamingo.md). Ship scanner-only with `evidence.dataGap` and
+// add the query later when verifiable.
+//
+// Fires when a single-region pin is found AND the project has meaningful surface area
+// (routes.length > 20). Skips multi-region configs (informational only).
+export const metadata = {
+  id: "region_misconfig",
+  threshold: "single-region pin found AND routes.length > 20 (scanner-only branch)",
+  billingDimension: "function-duration",
+  scope: "account",
+  sourceCitation: "vercel-optimize gate threshold",
+  description:
+    "A single function region is pinned in `vercel.json` or per-route `preferredRegion`. Without per-region TTFB data (data gap), the gate can't quantify the geographic latency cost — but a single-region pin on a project with 20+ routes is worth auditing against Speed Insights traffic geo.",
+};
+
+const ROUTE_FLOOR = 20;
+const SCANNER_PATTERN = "region-pin-in-config";
+
+export function gate(signals) {
+  const findings = (signals?.codebase?.findings ?? []).filter((f) => f.pattern === SCANNER_PATTERN);
+  if (findings.length === 0) return [];
+
+  const routes = signals?.codebase?.routes ?? [];
+  if (routes.length < ROUTE_FLOOR) return [];
+
+  const singleRegionFindings = findings.filter(
+    (f) => Array.isArray(f.regions) && f.regions.length === 1,
+  );
+  if (singleRegionFindings.length === 0) return [];
+
+  const allPinned = new Set();
+  for (const f of singleRegionFindings) {
+    for (const r of f.regions ?? []) allPinned.add(r);
+  }
+  const regionList = [...allPinned];
+
+  // If multiple distinct single-region pins exist across files, the surface is partly
+  // multi-region by accident; that's noteworthy but lower priority.
+  const homogeneous = regionList.length === 1;
+
+  return [
+    {
+      kind: metadata.id,
+      scope: "account",
+      files: singleRegionFindings.map((f) => f.file).slice(0, 6),
+      priority: homogeneous ? 42 : 38,
+      confidence: 0.6, // low — no per-region TTFB data
+      o11ySignal: `pinned_regions=${regionList.join(",")} routes=${routes.length}`,
+      reason: homogeneous
+        ? `all functions pinned to a single region (${regionList[0]}) on a project with ${routes.length} routes`
+        : `${regionList.length} different single-region pins across files`,
+      question:
+        "Are the pinned function regions aligned with the dominant user geography and the data source location? Speed Insights TTFB-by-country can ground the comparison.",
+      evidence: {
+        metric: "codebase.findings",
+        pinnedRegions: regionList,
+        findingsCount: singleRegionFindings.length,
+        routeCount: routes.length,
+        sampleFiles: singleRegionFindings
+          .slice(0, 3)
+          .map((f) => ({ file: f.file, regions: f.regions, subtype: f.subtype })),
+        dataGap: "region-grouped-TTFB-unavailable",
+      },
+    },
+  ];
+}

package/skills/craft/vercel-optimize/lib/gates/route-errors.mjs

@@ -0,0 +1,95 @@
+// Errored function invocations still bill at full duration, so high-volume 5xx is a cost issue, not just reliability.
+import { withRouteShapeWarnings } from "../route-normalize.mjs";
+
+const MIN_VOLUME_FOR_RATE_EMISSION = 1000;
+
+export const metadata = {
+  id: "route_errors",
+  threshold: `count > 250 OR (totalRequests >= ${MIN_VOLUME_FOR_RATE_EMISSION} AND errorRate > 0.01)`,
+  billingDimension: "function-duration",
+  scope: "route",
+  sourceCitation: "vercel-optimize gate threshold",
+  description:
+    "Routes producing > 250 5xx errors over the window, or with > 1% error rate on at least 1,000 total requests. Errored function invocations still bill at full duration; high error rates also poison user experience.",
+};
+
+export function gate(signals) {
+  const errors = extractErrors(signals);
+  return errors
+    .filter(
+      (e) =>
+        e.count > 250 || (e.total >= MIN_VOLUME_FOR_RATE_EMISSION && (e.errorRate ?? 0) > 0.01),
+    )
+    .map((e) =>
+      withRouteShapeWarnings(
+        {
+          kind: metadata.id,
+          scope: "route",
+          route: e.route,
+          files: [],
+          priority: e.count,
+          confidence: 0.93,
+          o11ySignal:
+            e.errorRate != null
+              ? `errs=${e.count},rate=${(e.errorRate * 100).toFixed(1)}%`
+              : `errs=${e.count}`,
+          reason: "concentrated 5xx errors",
+          question: `Why does ${e.route} produce ${e.count} 5xx errors over the window, and what code path is failing?`,
+          evidence: {
+            metric: e.metric,
+            route: e.route,
+            count: e.count,
+            totalRequests: e.total,
+            errorRate: e.errorRate,
+          },
+        },
+        signals,
+      ),
+    );
+}
+
+function extractErrors(signals) {
+  const fnStatus = signals.metrics?.fnStatusByRoute;
+  if (Array.isArray(fnStatus?.rows)) return extractFromStatusRows(fnStatus.rows, "fnStatusByRoute");
+
+  const m = signals.metrics?.requestsByRouteStatus;
+  const cache = signals.metrics?.requestsByRouteCache;
+  if (!m?.ok && !Array.isArray(m?.rows)) return [];
+
+  const errors = extractFromStatusRows(m?.rows ?? [], "requestsByRouteStatus");
+
+  // cache rollup is summed across cache_result, giving per-route total request count.
+  const totalByRoute = new Map();
+  for (const row of cache?.rows ?? []) {
+    if (!row.route) continue;
+    totalByRoute.set(row.route, (totalByRoute.get(row.route) ?? 0) + (row.value ?? 0));
+  }
+
+  return errors.map((e) => {
+    const total = totalByRoute.get(e.route) ?? 0;
+    return {
+      ...e,
+      total,
+      errorRate: total > 0 ? e.count / total : null,
+    };
+  });
+}
+
+function extractFromStatusRows(rows, metric) {
+  const errByRoute = new Map();
+  const totalByRoute = new Map();
+  for (const row of rows) {
+    const route = row.route;
+    if (!route) continue;
+    const v = row.value ?? 0;
+    const status = String(row.http_status ?? "");
+    if (/^5\d\d$/.test(status)) errByRoute.set(route, (errByRoute.get(route) ?? 0) + v);
+    totalByRoute.set(route, (totalByRoute.get(route) ?? 0) + v);
+  }
+
+  return [...errByRoute.entries()].map(([route, count]) => {
+    const total = totalByRoute.get(route) ?? 0;
+    const errorRate = total > 0 ? count / total : null;
+    return { route, count, total, errorRate, metric };
+  });
+}

package/skills/craft/vercel-optimize/lib/gates/scanner-driven.mjs

@@ -0,0 +1,150 @@
+// Signal source is the codebase itself, not traffic. COLD-PATH and NO-ROUTE-MAPPING findings
+// are dropped unless the scanner sets trafficIndependent (build configs, middleware matchers, etc.).
+// Annotation happens in scan-codebase.mjs; gates here just read scanner.o11ySignal.
+
+export const SCANNER_GATES = [
+  {
+    id: "image_optimization",
+    patterns: ["unoptimized-image"],
+    threshold: 2,
+    billingDimension: "image-optimization",
+    priority: 30,
+  },
+  {
+    id: "cache_header_gap",
+    patterns: ["max-age-without-s-maxage", "missing-cache-headers"],
+    threshold: 1,
+    billingDimension: "edge-requests",
+    priority: 40,
+  },
+  {
+    id: "rendering_candidate",
+    patterns: ["force-dynamic", "headers-in-page"],
+    threshold: 3,
+    billingDimension: "function-duration",
+    priority: 35,
+  },
+  {
+    id: "use_cache_date_stamp",
+    patterns: ["use-cache-date-stamp"],
+    threshold: 1,
+    billingDimension: "isr",
+    priority: 45,
+  },
+  {
+    id: "cache_components_suspense_dedupe",
+    patterns: ["cache-components-suspense-dedupe"],
+    threshold: 1,
+    billingDimension: "function-duration",
+    priority: 38,
+  },
+];
+
+export const metadata = {
+  id: "scanner-driven",
+  threshold: "per-kind: scanner matches.length >= threshold",
+  billingDimension: "mixed",
+  scope: "mixed",
+  sourceCitation: "vercel-optimize gate threshold",
+  description:
+    "Configured kinds emitted from scanner output. Each requires a minimum match count to avoid noise. Findings on cold-path or unmappable files are dropped unless the underlying scanner is trafficIndependent.",
+};
+
+export function gate(signals) {
+  const findings = signals.codebase?.findings ?? [];
+  if (findings.length === 0) return [];
+
+  const candidates = [];
+
+  for (const cfg of SCANNER_GATES) {
+    const matched = findings.filter((f) => {
+      if (!cfg.patterns.includes(f.pattern)) return false;
+      if (!f.trafficIndependent) {
+        if (!f.o11ySignal || f.o11ySignal === "scanner-only") return false;
+        if (f.o11ySignal === "COLD-PATH") return false;
+        if (f.o11ySignal === "NO-ROUTE-MAPPING") return false;
+      }
+      if (cfg.id === "cache_header_gap" && observedCacheHitRate(f.o11ySignal) >= 90) return false;
+      return true;
+    });
+
+    for (const group of groupFindings(cfg, matched)) {
+      if (group.findings.length < cfg.threshold) continue;
+      candidates.push(candidateForGroup(cfg, group));
+    }
+  }
+
+  return candidates;
+}
+
+function groupFindings(cfg, findings) {
+  const groups = new Map();
+  for (const finding of findings) {
+    const scope = finding.route ? "route" : "file";
+    const target = scope === "route" ? finding.route : finding.file;
+    if (!target) continue;
+    const key = `${cfg.id}:${scope}:${target}`;
+    if (!groups.has(key)) groups.set(key, { scope, target, findings: [] });
+    groups.get(key).findings.push(finding);
+  }
+  return [...groups.values()];
+}
+
+function candidateForGroup(cfg, group) {
+  const matched = group.findings;
+  const route = group.scope === "route" ? group.target : null;
+  return {
+    kind: cfg.id,
+    scope: group.scope,
+    route,
+    files: uniqueStrings(matched.map((m) => m.file)).slice(0, 6),
+    priority: cfg.priority + Math.min(matched.length, 10),
+    confidence: 0.88,
+    o11ySignal:
+      matched
+        .map((m) => m.o11ySignal)
+        .find((s) => s && s !== "COLD-PATH" && s !== "NO-ROUTE-MAPPING") ?? "scanner-only",
+    reason: `${matched.length} ${cfg.patterns.join("+")} finding(s)`,
+    question: questionFor(cfg.id, matched),
+    evidence: {
+      scannerMatches: matched.length,
+      patterns: cfg.patterns,
+      scope: group.scope,
+      route,
+      sampleFiles: matched.slice(0, 3).map((m) => ({ file: m.file, line: m.line })),
+    },
+  };
+}
+
+function questionFor(kindId, matched) {
+  const sample = matched
+    .slice(0, 3)
+    .map((m) => m.file)
+    .join(", ");
+  switch (kindId) {
+    case "image_optimization":
+      return `Which raw <img> tags in ${sample} should move to next/image (or the framework's image component)?`;
+    case "cache_header_gap":
+      return `Should the route handlers in ${sample} set Cache-Control with s-maxage to serve from the CDN?`;
+    case "rendering_candidate":
+      return `Why are the routes in ${sample} forced to dynamic rendering, and can any of them tolerate ISR or static generation?`;
+    case "use_cache_date_stamp":
+      return `Which 'use cache' boundaries in ${sample} embed new Date()/Date.now()/Math.random() that destabilizes cache keys, and can the timestamps be hoisted to a build constant or moved into a client useEffect?`;
+    case "cache_components_suspense_dedupe":
+      return `In ${sample}, which repeated fetch or helper is being re-invoked across separate <Suspense> boundaries, and can the promise be hoisted to the page level or moved to 'use cache: remote' for cross-boundary dedupe?`;
+    default:
+      return `Investigate ${matched.length} ${kindId} finding(s).`;
+  }
+}
+
+function uniqueStrings(values) {
+  return [...new Set(values.filter((v) => typeof v === "string" && v.length > 0))];
+}
+
+function observedCacheHitRate(signal) {
+  if (typeof signal !== "string") return null;
+  const m = /\bcache=([\d.]+)%/.exec(signal);
+  if (!m) return null;
+  const n = Number(m[1]);
+  return Number.isFinite(n) ? n : null;
+}

package/skills/craft/vercel-optimize/lib/gates/select-candidates.mjs

@@ -0,0 +1,137 @@
+// Deterministic launch selection for the code-scope investigation budget.
+//
+// Raw priority still orders candidates inside each pass. The default budget is
+// impact-first, with failure-mode diversity when a kind's top signal is large
+// enough to justify taking a first-pass slot.
+
+const DEFAULT_KIND_CAPS = new Map([
+  ["slow_route", 2],
+  ["uncached_route", 2],
+  ["route_errors", 2],
+]);
+
+const DIVERSITY_ELIGIBILITY = new Map([
+  // A handful of 5xx errors can pass the route_errors gate because the rate is
+  // high, but that should not displace much larger cost/performance signals in
+  // the default six-candidate pass.
+  ["route_errors", (candidate) => numberFromEvidence(candidate, "count") >= 1000],
+
+  // Scanner-driven cache findings are valuable, but the default pass should
+  // spend a slot only when observability shows meaningful route traffic or a
+  // very slow route handler.
+  [
+    "cache_header_gap",
+    (candidate) => {
+      const invocations = numberFromSignal(candidate?.o11ySignal, "inv");
+      const p95Ms = durationMsFromSignal(candidate?.o11ySignal, "p95");
+      return invocations >= 50_000 || p95Ms >= 2000;
+    },
+  ],
+  ["rendering_candidate", (candidate) => numberFromSignal(candidate?.o11ySignal, "inv") >= 50_000],
+]);
+
+export function selectLaunchCandidates(candidates, budget, { diversify = false } = {}) {
+  const pool = Array.isArray(candidates) ? candidates : [];
+  if (budget === Infinity) {
+    return { selected: pool, skipped: [], selectionMode: "all" };
+  }
+  if (!Number.isInteger(budget) || budget < 1) {
+    throw new TypeError("selectLaunchCandidates budget must be a positive integer or Infinity");
+  }
+  if (!diversify) {
+    return {
+      selected: pool.slice(0, budget),
+      skipped: pool.slice(budget),
+      selectionMode: "priority",
+    };
+  }
+
+  const selected = [];
+  const selectedKeys = new Set();
+  const countsByKind = new Map();
+
+  const add = (candidate) => {
+    const key = candidateIdentity(candidate);
+    if (selectedKeys.has(key)) return false;
+    selectedKeys.add(key);
+    selected.push(candidate);
+    const kind = candidate.kind ?? "<unknown>";
+    countsByKind.set(kind, (countsByKind.get(kind) ?? 0) + 1);
+    return true;
+  };
+
+  // First pass: one candidate per failure mode, preserving the existing sorted
+  // order. This is where the default run gets broad coverage, but only for
+  // kinds whose signal is strong enough for a default slot.
+  for (const candidate of pool) {
+    if (selected.length >= budget) break;
+    const kind = candidate.kind ?? "<unknown>";
+    if ((countsByKind.get(kind) ?? 0) > 0) continue;
+    if (!isDiversityEligible(candidate)) continue;
+    add(candidate);
+  }
+
+  // Second pass: allow a second entry for high-frequency families, but avoid
+  // letting slow_route consume the entire default budget when other kinds exist.
+  for (const candidate of pool) {
+    if (selected.length >= budget) break;
+    const kind = candidate.kind ?? "<unknown>";
+    const cap = DEFAULT_KIND_CAPS.get(kind) ?? 1;
+    if ((countsByKind.get(kind) ?? 0) >= cap) continue;
+    if (!isDiversityEligible(candidate)) continue;
+    add(candidate);
+  }
+
+  // Final fill: if the project only has one or two candidate kinds, use the
+  // whole requested budget rather than leaving slots empty.
+  for (const candidate of pool) {
+    if (selected.length >= budget) break;
+    add(candidate);
+  }
+
+  return {
+    selected,
+    skipped: pool.filter((candidate) => !selectedKeys.has(candidateIdentity(candidate))),
+    selectionMode: "diverse-default",
+  };
+}
+
+function candidateIdentity(candidate) {
+  return [
+    candidate?.kind ?? "",
+    candidate?.route ?? "",
+    candidate?.hostname ?? "",
+    candidate?.scope ?? "",
+    candidate?.o11ySignal ?? "",
+  ].join("\u0000");
+}
+
+function isDiversityEligible(candidate) {
+  const fn = DIVERSITY_ELIGIBILITY.get(candidate?.kind);
+  return fn ? fn(candidate) : true;
+}
+
+function numberFromEvidence(candidate, key) {
+  const value = candidate?.evidence?.[key];
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
+function numberFromSignal(signal, key) {
+  if (typeof signal !== "string") return 0;
+  const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const re = new RegExp(`(?:^|,)${escaped}=([\\d.]+)`);
+  const m = re.exec(signal);
+  if (!m) return 0;
+  const n = Number(m[1]);
+  return Number.isFinite(n) ? n : 0;
+}
+
+function durationMsFromSignal(signal, key) {
+  if (typeof signal !== "string") return 0;
+  const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const re = new RegExp(`(?:^|,)${escaped}=([\\d.]+)ms`);
+  const m = re.exec(signal);
+  if (!m) return 0;
+  const n = Number(m[1]);
+  return Number.isFinite(n) ? n : 0;
+}