merge(release/v3.8.51): refresh #12605 onto current tip

scripts/check/check-docs-counts-sync.mjs

@@ -218,12 +218,16 @@ function readCodeFacts() {
     "const t=computeFreeModelTotals();const cli=Object.values(CLI_TOOLS);",
     "const by=(c)=>cli.filter(x=>x.category===c).length;",
     // "Free forever" = every provider whose free access renews or needs no key at all.
-    // one-time-initial (signup credits) and discontinued pools are excluded on purpose.
+    // one-time-initial (signup credits) and discontinued pools are excluded on purpose,
+    // and so is every eligibility-gated row: a provider nobody can sign up for without
+    // clearing a gate is not "free forever" for the reader of the headline.
     "const FOREVER=new Set(['recurring-monthly','recurring-daily','recurring-uncapped',",
     "'recurring-credit','keyless']);",
-    "const ff=new Set();for(const m of t.perModel)if(FOREVER.has(m.freeType))ff.add(m.provider);",
+    "const ff=new Set();for(const m of t.perModel)",
+    "if(FOREVER.has(m.freeType)&&!m.eligibilityGate)ff.add(m.provider);",
     'console.log("@@"+JSON.stringify({freeSteady:t.steadyRecurringTokens,entries:t.perModel.length,',
-    "freeFirst:t.firstMonthRealisticTokens,freePools:t.poolCount,engines:ENGINE_IDS.length,",
+    "freeFirst:t.firstMonthRealisticTokens,freeGated:t.gatedRecurringTokens,",
+    "freePools:t.poolCount,engines:ENGINE_IDS.length,",
     "cliTotal:cli.length,cliCode:by('code'),cliAgent:by('agent'),",
     "mcpTools:countUniqueMcpTools(cols),mcpScopes:sc.size,providers:pids.size,freeForever:ff.size,",
     "modePacks:Object.keys(MODE_PACKS),",
@@ -271,6 +275,20 @@ export function extractHeadlineClaims(content) {
   return claims;
 }
 
+// The eligibility-gated figure ("+~6M behind regional identity verification") is validated
+// with its own anchor so it can neither drift nor be silently dropped once it exists.
+const GATED_ANCHOR = /^\s*behind regional identity verification/i;
+
+export function extractGatedClaims(content) {
+  const claims = [];
+  for (const m of content.matchAll(/\+?~?(\d+(?:\.\d+)?)([BM])\b/g)) {
+    const after = content.slice(m.index + m[0].length, m.index + m[0].length + 60);
+    if (!GATED_ANCHOR.test(after)) continue;
+    claims.push({ tokens: Number(m[1]) * (m[2] === "B" ? 1e9 : 1e6), unit: m[2], text: m[0] });
+  }
+  return claims;
+}
+
 export function checkFreeTierHeadline(content, totals) {
   const claims = extractHeadlineClaims(content);
   if (!claims.length) return { ok: true, detail: "no aggregate free-tier headline in this file" };
@@ -279,14 +297,31 @@ export function checkFreeTierHeadline(content, totals) {
   const stale = claims.filter(
     (c) => Math.abs(c.value - steady) >= 0.05 && Math.abs(c.value - first) >= 0.05
   );
-  if (!stale.length)
-    return { ok: true, detail: `${claims.length} headline claim(s) match the live catalog` };
-  return {
-    ok: false,
-    detail:
+  const problems = [];
+  if (stale.length) {
+    problems.push(
       `stale headline ${[...new Set(stale.map((c) => c.text))].join(", ")} — live catalog ` +
-      `computes ~${steady.toFixed(2)}B steady / ~${first.toFixed(2)}B first month`,
-  };
+        `computes ~${steady.toFixed(2)}B steady / ~${first.toFixed(2)}B first month`
+    );
+  }
+  if (totals.g != null && totals.g > 0) {
+    const gated = extractGatedClaims(content);
+    const tol = (c) => (c.unit === "B" ? 0.05e9 : 0.5e6);
+    const gatedStale = gated.filter((c) => Math.abs(c.tokens - totals.g) >= tol(c));
+    if (!gated.length) {
+      problems.push(
+        `missing gated figure — live catalog computes ${Math.round(totals.g / 1e6)}M behind regional identity verification`
+      );
+    } else if (gatedStale.length) {
+      problems.push(
+        `stale gated figure ${[...new Set(gatedStale.map((c) => c.text))].join(", ")} — live catalog ` +
+          `computes ${Math.round(totals.g / 1e6)}M behind regional identity verification`
+      );
+    }
+  }
+  if (!problems.length)
+    return { ok: true, detail: `${claims.length} headline claim(s) match the live catalog` };
+  return { ok: false, detail: problems.join("; ") };
 }
 
 // PURE: docs prose that names the product version ("OmniRoute v3.8.50 ·",
@@ -599,12 +634,12 @@ export function buildChecks() {
         },
         {
           label: "Free-tier headline (live catalog)",
-          actual: `~${(f.freeSteady / 1e9).toFixed(2)}B steady / ${f.freePools} pools`,
+          actual: `~${(f.freeSteady / 1e9).toFixed(2)}B steady / ${f.freePools} pools / ${Math.round(f.freeGated / 1e6)}M gated`,
           docKey: "free-tier headline",
           strict: true,
           files: ["README.md", "docs/reference/FREE_TIERS.md"],
           validate: (content) =>
-            checkFreeTierHeadline(content, { s: f.freeSteady, m: f.freeFirst }),
+            checkFreeTierHeadline(content, { s: f.freeSteady, m: f.freeFirst, g: f.freeGated }),
         },
         claim(
           f.engines,