opencode-skills-collection 3.0.35 → 3.0.36

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

@@ -0,0 +1,115 @@
+// 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/bundled-skills/vercel-optimize/lib/gates/platform-fluid-compute.mjs

@@ -0,0 +1,83 @@
+// 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/bundled-skills/vercel-optimize/lib/gates/region-misconfig.mjs

@@ -0,0 +1,64 @@
+// 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/bundled-skills/vercel-optimize/lib/gates/route-errors.mjs

@@ -0,0 +1,80 @@
+// 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/bundled-skills/vercel-optimize/lib/gates/scanner-driven.mjs

@@ -0,0 +1,122 @@
+// 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/bundled-skills/vercel-optimize/lib/gates/select-candidates.mjs

@@ -0,0 +1,134 @@
+// 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;
+}