v0.8.5 Speculative-Decode Compatibility Checker — anti-bullshit pack #11

Speculative decoding (vLLM, SGLang, llama.cpp, transformers
`assistant_model`) requires the draft and target model to share an
EXACT vocabulary. If token IDs disagree, every draft token is rejected
by the target's verifier — you pay BOTH compute costs AND get WORSE
throughput than baseline. The system reports nominal output (just
slower), so the bug is invisible in unit tests. vLLM #4570 / #16757 /
#20409 / #12488 all surface variants of this.

🔬 Spec-Decode (19th mode):
- Two HF model id inputs with autocomplete (reuses v0.7.4 infra)
- Async fetch `tokenizer.json` from HF Hub for both ids; falls back
to `tokenizer_config.json` when the canonical artifact is missing
- Compares: tokenizer type (BPE/Unigram/WordPiece), vocab size,
full token→id sample on the smaller side, special tokens
(BOS/EOS/PAD/UNK), added tokens (chat-template extensions)
- Speedup band based on param ratio (parsed from id "8B"/"72B"
hints OR derived from `config.json` hidden_size × layers × vocab):
low (α=0.50), expected (α=0.70), high (α=0.85), capped at 3.5x
- 9 verdict codes: compatible / compatible_with_caveats /
partial_compatible / type_mismatch / vocab_size_mismatch /
incompatible / fetch_failed / identical_models / missing_input
- Per-side fetch error breakdown (gated/private/not_found/timeout/
parse_failed/network) so users debug the right input

Pure logic + async fetch in `js/spec_decode_compat.js`. Comment +
string-literal stripping is unnecessary here (input is two ids, not
code). 55 i18n keys × 4 langs (EN/ES/FR/ZH) = 220 keys, parity clean.

Solutions Hub: NEW `speculative_decode_mismatch` entry under setup
category, mapped to this mode + 4 external refs (vLLM docs, vLLM
#4570, transformers assistant_model, Leviathan et al. 2022).
HF autocomplete known-id list extended with `spec-target-id` /
`spec-draft-id`. Help modal v0.8.5 entry + Inventory + Setup tile.

Verified: 7/7 logic cases (vocab compare identical / cross-family /
type-mismatch + 4 param-hint parses) + 220/220 i18n parity + headless
e2e (tab/section/inputs/empty-hint/identical-hint render). 20 mode
tabs total.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

data/solutions_hub.json

@@ -218,6 +218,20 @@
       "best_for": "Generating the exact `python cli/diagnose_model.py` command for your model.",
       "not_for": "Browser-only diagnosis — this mode is a builder, not an executor."
     },
+    {
+      "id": "speculative_decode_mismatch",
+      "category": "setup",
+      "pain": "Speculative decoding silently rejects all draft tokens when target+draft tokenizer vocabs differ — worse throughput than baseline, no error.",
+      "tafagent_mode": "🔬 Speculative-Decode Compatibility",
+      "external_tools": [
+        {"name": "vLLM speculative decoding docs", "url": "https://docs.vllm.ai/en/latest/serving/speculative_decoding.html", "type": "docs"},
+        {"name": "vLLM #4570 — vocab mismatch report", "url": "https://github.com/vllm-project/vllm/issues/4570", "type": "issue"},
+        {"name": "transformers assistant_model docs", "url": "https://huggingface.co/docs/transformers/main/en/llm_optims#speculative-decoding", "type": "docs"},
+        {"name": "Leviathan et al. 2022 — speculative-decoding paper", "url": "https://arxiv.org/abs/2211.17192", "type": "paper"}
+      ],
+      "best_for": "Verifying a (target, draft) pair before launching a vLLM/SGLang cluster with spec-dec enabled. Surfaces vocab-size, type, and special-token mismatches.",
+      "not_for": "Measuring real-world acceptance rate α — that requires running both models on your domain. The tool only predicts a band based on param ratio."
+    },
     {
       "id": "peft_loading",
       "category": "training",

index.html

@@ -225,6 +225,9 @@
       <p><strong data-i18n="help.v084.cache.title">🔁 Prompt-Cache Diff Predictor</strong></p>
       <p data-i18n="help.v084.cache.body">Provider prompt caches each have different rules: Anthropic's <code>cache_control</code> breaks at the first token diff in the marked prefix; OpenAI auto-caches prefixes ≥1024 tokens; Gemini context caches require ≥32K tokens. A misplaced edit silently 10x's your bill — the API never warns you, and the cost only shows up on the next invoice. Paste old + new prompt, the predictor finds the longest common prefix, estimates tokens with three tokenizer profiles (English / code / CJK), and shows per-provider hit ratio + $ delta vs no-cache for Claude Opus/Sonnet/Haiku, GPT-5/mini, and Gemini 2.5 Pro. <em>Use case</em>: 'I tweaked the system prompt and the bill jumped — what broke?' → paste both prompts, see exactly which provider stopped caching.</p>
 
+      <p><strong data-i18n="help.v085.speculative.title">🔬 Speculative-Decode Compatibility</strong></p>
+      <p data-i18n="help.v085.speculative.body">Speculative decoding only works if target and draft share the exact same vocabulary. Mismatched vocabs cause every draft token to be rejected — you pay BOTH compute costs and get worse throughput than baseline. Worse, the system still emits correct output (just slower), so the bug is invisible in unit tests. vLLM #4570 / #16757 / #20409 / #12488 all surface variants. This tool fetches `tokenizer.json` from HF Hub for both model ids, compares tokenizer type, vocab size, full token→id map, special tokens, and added tokens, then estimates a speedup band based on param ratio and typical α=0.5/0.7/0.85 acceptance rates. <em>Use case</em>: before you launch a vLLM cluster with spec-dec enabled, verify the pair is actually compatible.</p>
+
       <p><strong data-i18n="help.v081.hub.title">🧭 Solutions Hub</strong></p>
       <p data-i18n="help.v081.hub.body">tafagent as integrator, not silo. 30+ pains across 7 categories (eval reliability · diagnostics · setup · training · retrieval · multimodal · observability), each mapped to (a) the tafagent mode that addresses it, if any, and (b) the best-of-breed external tools the community already trusts (RAGAS, MTEB, HELM, MCP Schema Validator, llm-stats, llguidance, GlitchMiner, etc.). Search box matches across pain, scenario, and tool name. <em>Use case</em>: 'I have problem X — does tafagent solve it, and if not, who does?'</p>
 
@@ -340,6 +343,7 @@
             <li data-i18n="inv.v082.cot"><strong>📋 JSON CoT</strong> — lints structured-output schemas for the answer-before-reasoning anti-pattern that silently breaks Chain-of-Thought.</li>
             <li data-i18n="inv.v083.peft"><strong>🔧 PEFT Lint</strong> — catches the silent <code>get_peft_model</code> base-load (peft #2115) + QLoRA order + target_modules / arch mismatch.</li>
             <li data-i18n="inv.v084.cache"><strong>🔁 Cache Diff</strong> — predicts whether a prompt edit invalidated the provider's prompt cache. Per-provider hit ratio + $ delta.</li>
+            <li data-i18n="inv.v085.speculative"><strong>🔬 Spec-Decode</strong> — verifies tokenizer vocab compatibility between target + draft before you ship speculative decoding (the bug that gives WORSE throughput silently).</li>
             <li data-i18n="inv.v081.hub"><strong>🧭 Solutions Hub</strong> — every documented pain mapped to a tafagent mode or curated external tool. Don't reinvent — find.</li>
           </ul>
         </details>
@@ -414,6 +418,7 @@
             <button data-mode-link="cot" data-i18n="modes.cot">📋 JSON CoT</button>
             <button data-mode-link="peft" data-i18n="modes.peft">🔧 PEFT Lint</button>
             <button data-mode-link="cache" data-i18n="modes.cache">🔁 Cache Diff</button>
+            <button data-mode-link="speculative" data-i18n="modes.speculative">🔬 Spec-Decode</button>
           </div>
         </div>
         <div class="task-tile">
@@ -473,6 +478,7 @@
         <button class="mode-btn" data-mode="cot" role="tab" aria-selected="false" data-i18n="modes.cot">📋 JSON CoT</button>
         <button class="mode-btn" data-mode="peft" role="tab" aria-selected="false" data-i18n="modes.peft">🔧 PEFT Lint</button>
         <button class="mode-btn" data-mode="cache" role="tab" aria-selected="false" data-i18n="modes.cache">🔁 Cache Diff</button>
+        <button class="mode-btn" data-mode="speculative" role="tab" aria-selected="false" data-i18n="modes.speculative">🔬 Spec-Decode</button>
         <button class="mode-btn" data-mode="hub" role="tab" aria-selected="false" data-i18n="modes.hub">🧭 Solutions</button>
       </div>
       <p id="mode-desc" class="recipe-desc" data-i18n="modes.desc">
@@ -1107,6 +1113,33 @@
       <div id="cache-output" style="margin-top: 1em;"></div>
     </section>
 
+    <!-- Speculative-Decode Compatibility Checker (mode=speculative, v0.8.5 #11) -->
+    <section id="speculative-section" style="display:none;">
+      <h2><span data-i18n="speculative.title">🔬 Speculative-Decode Compatibility</span>
+        <span class="info"><span class="tooltip" data-i18n="speculative.tip">
+          <strong>Why this matters</strong>: speculative decoding (vLLM, SGLang, llama.cpp, transformers) requires the draft and target model to share an EXACT vocabulary. Any token-id disagreement means the target rejects every draft token — you pay BOTH compute costs and get WORSE throughput than baseline. The system reports nominal output (just slower), so the bug is invisible in unit tests. This tool fetches `tokenizer.json` from HF Hub for both ids and compares.
+        </span></span>
+      </h2>
+      <p class="recipe-desc" data-i18n="speculative.desc">
+        <strong>Don't ship spec-dec with mismatched vocabs.</strong> Paste target + draft HF model ids → tool fetches tokenizers, compares vocab type, size, sampled token-ids, special tokens, added tokens → verdict + speedup estimate.
+      </p>
+      <div class="form-row">
+        <label for="spec-target-id" data-i18n="speculative.target_label">Target (large) model id:</label>
+        <input type="text" id="spec-target-id" placeholder="meta-llama/Llama-3.1-70B-Instruct" style="flex:1;" />
+      </div>
+      <div class="form-row">
+        <label for="spec-draft-id" data-i18n="speculative.draft_label">Draft (small) model id:</label>
+        <input type="text" id="spec-draft-id" placeholder="meta-llama/Llama-3.1-8B-Instruct" style="flex:1;" />
+      </div>
+      <div class="form-row">
+        <button type="button" id="spec-check-btn" data-i18n="speculative.check_btn">🔍 Check compatibility</button>
+        <button type="button" id="spec-example-good-btn" class="secondary" data-i18n="speculative.example_good_btn">↳ Example: Llama-3.1 8B/70B (good)</button>
+        <button type="button" id="spec-example-bad-btn" class="secondary" data-i18n="speculative.example_bad_btn">↳ Example: cross-family (bad)</button>
+      </div>
+      <p id="spec-status" class="recipe-desc" style="font-size:0.92em;"></p>
+      <div id="spec-output" style="margin-top: 1em;"></div>
+    </section>
+
     <section id="hub-section" style="display:none;">
       <h2><span data-i18n="hub.title">🧭 Solutions Hub</span>
         <span class="info"><span class="tooltip" data-i18n="hub.tip">

js/hf_autocomplete.js

@@ -200,7 +200,10 @@ export function attachHfAutocomplete(inputEl, options = {}) {
 // Convenience: attach to all known HF-id inputs in TAF Agent.
 // NIAH was added in v0.7.6 — keep this list in sync when adding new modes.
 export function attachAllHfAutocompletes() {
-  const ids = ["hf-id", "profile-hf-id", "unmask-id", "template-id", "quant-id", "niah-id"];
+  const ids = [
+    "hf-id", "profile-hf-id", "unmask-id", "template-id", "quant-id", "niah-id",
+    "spec-target-id", "spec-draft-id",
+  ];
   for (const id of ids) {
     const el = document.getElementById(id);
     if (el) attachHfAutocomplete(el);

js/i18n.js

@@ -637,6 +637,63 @@ export const TRANSLATIONS = {
     "help.v084.cache.title":       "🔁 Prompt-Cache Diff Predictor",
     "help.v084.cache.body":        "Provider prompt caches each have different rules: Anthropic's <code>cache_control</code> breaks at the first token diff in the marked prefix; OpenAI auto-caches prefixes ≥1024 tokens; Gemini context caches require ≥32K tokens. A misplaced edit silently 10x's your bill — the API never warns you, and the cost only shows up on the next invoice. Paste old + new prompt, the predictor finds the longest common prefix, estimates tokens with three tokenizer profiles (English / code / CJK), and shows per-provider hit ratio + $ delta vs no-cache for Claude Opus/Sonnet/Haiku, GPT-5/mini, and Gemini 2.5 Pro. <em>Use case</em>: 'I tweaked the system prompt and the bill jumped — what broke?' → paste both prompts, see exactly which provider stopped caching.",
 
+    // v0.8.5 — anti-bullshit pack #11: Speculative-Decode Compatibility
+    "modes.speculative":           "🔬 Spec-Decode",
+    "mode_desc.speculative":       "Fetches `tokenizer.json` from HF Hub for two model ids and verifies vocab compatibility before you wire up speculative decoding. Catches the silent-mismatch bug that wastes draft compute.",
+    "speculative.title":           "🔬 Speculative-Decode Compatibility",
+    "speculative.tip":             "Speculative decoding (vLLM, SGLang, llama.cpp, transformers) requires the draft and target model to share an EXACT vocabulary. Any token-id disagreement means the target rejects every draft token — you pay BOTH compute costs and get WORSE throughput than baseline. The system reports nominal output (just slower), so the bug is invisible in unit tests. This tool fetches `tokenizer.json` from HF Hub for both ids and compares.",
+    "speculative.desc":            "<strong>Don't ship spec-dec with mismatched vocabs.</strong> Paste target + draft HF model ids → tool fetches tokenizers, compares vocab type, size, sampled token-ids, special tokens, added tokens → verdict + speedup estimate.",
+    "speculative.target_label":    "Target (large) model id:",
+    "speculative.draft_label":     "Draft (small) model id:",
+    "speculative.target_label_short": "target",
+    "speculative.draft_label_short":  "draft",
+    "speculative.check_btn":       "🔍 Check compatibility",
+    "speculative.example_good_btn":"↳ Example: Llama-3.1 8B/70B (good)",
+    "speculative.example_bad_btn": "↳ Example: cross-family (bad)",
+    "speculative.status.fetching": "🔄 Fetching tokenizer.json from HF Hub for both models…",
+    "speculative.status.done":     "✅ {verdict}",
+    "speculative.status.error":    "❌ Error",
+    "speculative.type_mismatch_note": "tokenizer types differ; spec-dec impossible",
+    "speculative.vocab_size":      "Vocab size",
+    "speculative.size_diff":       "differ — every reused id is a misalignment",
+    "speculative.sampled":         "Token-id sample match",
+    "speculative.first_mismatch":  "First mismatch",
+    "speculative.special_diff":    "Special-token differences",
+    "speculative.added_diff":      "Added-token differences",
+    "speculative.added_diff_more": "+ more …",
+    "speculative.speedup.title":   "Estimated speedup band",
+    "speculative.speedup.params":  "target {target} / draft {draft} (param ratio {ratio})",
+    "speculative.speedup.low":     "Low (α=0.50)",
+    "speculative.speedup.expected":"Expected (α=0.70)",
+    "speculative.speedup.high":    "High (α=0.85)",
+    "speculative.speedup.disclaimer": "α = draft acceptance rate. Real speedup depends on prompt domain, lookahead K, and engine overhead. Bands assume ideal verifier batching.",
+    "speculative.speedup.draft_not_smaller": "Draft is not smaller than target — spec-dec is misuse here.",
+    "speculative.attribution":     "Refs:",
+    "speculative.side.target":     "Target",
+    "speculative.side.draft":      "Draft",
+    "speculative.fetch_error.missing_model_id": "missing model id",
+    "speculative.fetch_error.gated_or_private": "model is gated or private — can't fetch tokenizer without auth",
+    "speculative.fetch_error.not_found":        "model id not found on HF Hub",
+    "speculative.fetch_error.fetch_failed":     "fetch failed (HTTP error)",
+    "speculative.fetch_error.parse_failed":     "JSON parse failed (file malformed)",
+    "speculative.fetch_error.timeout":          "timeout (>8s, large tokenizer or slow connection)",
+    "speculative.fetch_error.network":          "network error",
+    "speculative.fetch_error.hint":             "Check the model id spelling. For gated models you'll need to view the tokenizer file via your HF account — this tool can't auth.",
+    "speculative.hint.missing_input":  "Enter both target and draft model ids, then Check.",
+    "speculative.hint.identical_models": "Target and draft are the same model — spec-dec is a no-op (and wasteful).",
+    "speculative.verdict.compatible":              "✅ Compatible — vocabs match",
+    "speculative.verdict.compatible_with_caveats": "✅ Compatible — but special/added tokens differ (review)",
+    "speculative.verdict.partial_compatible":      "⚠ Partial match (95-99.9% of sampled ids)",
+    "speculative.verdict.type_mismatch":           "❌ Tokenizer types differ — spec-dec impossible",
+    "speculative.verdict.vocab_size_mismatch":     "❌ Vocab sizes differ — id space misaligned",
+    "speculative.verdict.incompatible":            "❌ Incompatible — too many id mismatches",
+    "speculative.verdict.fetch_failed":            "ℹ Couldn't fetch tokenizer",
+    "speculative.verdict.identical_models":        "ℹ Identical models — spec-dec is a no-op",
+    "speculative.verdict.missing_input":           "ℹ Enter both ids",
+    "inv.v085.speculative":        "<strong>🔬 Spec-Decode</strong> — verifies tokenizer vocab compatibility between target + draft before you ship speculative decoding (the bug that gives WORSE throughput silently).",
+    "help.v085.speculative.title": "🔬 Speculative-Decode Compatibility",
+    "help.v085.speculative.body":  "Speculative decoding only works if target and draft share the exact same vocabulary. Mismatched vocabs cause every draft token to be rejected — you pay BOTH compute costs and get worse throughput than baseline. Worse, the system still emits correct output (just slower), so the bug is invisible in unit tests. vLLM #4570 / #16757 / #20409 / #12488 all surface variants. This tool fetches `tokenizer.json` from HF Hub for both model ids, compares tokenizer type, vocab size, full token→id map, special tokens, and added tokens, then estimates a speedup band based on param ratio and typical α=0.5/0.7/0.85 acceptance rates. <em>Use case</em>: before you launch a vLLM cluster with spec-dec enabled, verify the pair is actually compatible.",
+
     "inv.v081.hub":                "<strong>🧭 Solutions Hub</strong> — every documented pain mapped to a tafagent mode or curated external tool. Don't reinvent — find.",
     "help.v081.hub.title":         "🧭 Solutions Hub",
     "help.v081.hub.body":          "tafagent as integrator, not silo. 30+ pains across 7 categories (eval reliability · diagnostics · setup · training · retrieval · multimodal · observability), each mapped to (a) the tafagent mode that addresses it, if any, and (b) the best-of-breed external tools the community already trusts (RAGAS, MTEB, HELM, MCP Schema Validator, llm-stats, llguidance, GlitchMiner, etc.). Search box matches across pain, scenario, and tool name. <em>Use case</em>: 'I have problem X — does tafagent solve it, and if not, who does?'",
@@ -1733,6 +1790,63 @@ export const TRANSLATIONS = {
     "help.v084.cache.title":       "🔁 Predictor de Diff de Prompt-Cache",
     "help.v084.cache.body":        "Las prompt caches de cada proveedor tienen reglas distintas: el <code>cache_control</code> de Anthropic se rompe al primer token diferente del prefijo marcado; OpenAI auto-cachea prefijos ≥1024 tokens; las context caches de Gemini requieren ≥32K tokens. Una edición mal puesta silenciosamente 10x tu factura — la API no avisa, y el coste solo aparece en la siguiente factura. Pega prompt viejo + nuevo, el predictor halla el prefijo común más largo, estima tokens con tres perfiles de tokenizer (inglés / código / CJK), y muestra hit ratio por proveedor + delta $ vs sin caché para Claude Opus/Sonnet/Haiku, GPT-5/mini, y Gemini 2.5 Pro. <em>Caso de uso</em>: 'Tweaké el system prompt y la factura saltó — ¿qué se rompió?' → pega ambos prompts, ve exactamente qué proveedor dejó de cachear.",
 
+    // v0.8.5 — anti-bullshit pack #11: Speculative-Decode Compatibility
+    "modes.speculative":           "🔬 Spec-Decode",
+    "mode_desc.speculative":       "Hace fetch del `tokenizer.json` desde HF Hub para dos model ids y verifica compatibilidad de vocab antes de cablear speculative decoding. Atrapa el bug de mismatch silencioso que desperdicia compute del draft.",
+    "speculative.title":           "🔬 Compatibilidad de Speculative-Decode",
+    "speculative.tip":             "El speculative decoding (vLLM, SGLang, llama.cpp, transformers) requiere que draft y target compartan vocabulario EXACTO. Cualquier desacuerdo de token-id hace que el target rechace cada token del draft — pagas AMBOS computes y obtienes PEOR throughput que baseline. El sistema reporta output nominal (solo más lento), así que el bug es invisible en tests unitarios. Esta tool hace fetch de `tokenizer.json` desde HF Hub para ambos ids y compara.",
+    "speculative.desc":            "<strong>No envíes spec-dec con vocabs mismatched.</strong> Pega target + draft model ids → tool hace fetch de tokenizers, compara tipo de vocab, tamaño, token-ids muestreados, special tokens, added tokens → veredicto + estimación de speedup.",
+    "speculative.target_label":    "Model id del target (grande):",
+    "speculative.draft_label":     "Model id del draft (pequeño):",
+    "speculative.target_label_short": "target",
+    "speculative.draft_label_short":  "draft",
+    "speculative.check_btn":       "🔍 Verificar compatibilidad",
+    "speculative.example_good_btn":"↳ Ejemplo: Llama-3.1 8B/70B (bueno)",
+    "speculative.example_bad_btn": "↳ Ejemplo: cross-family (malo)",
+    "speculative.status.fetching": "🔄 Haciendo fetch de tokenizer.json desde HF Hub para ambos modelos…",
+    "speculative.status.done":     "✅ {verdict}",
+    "speculative.status.error":    "❌ Error",
+    "speculative.type_mismatch_note": "tipos de tokenizer difieren; spec-dec imposible",
+    "speculative.vocab_size":      "Tamaño del vocab",
+    "speculative.size_diff":       "difieren — cada id reusado es un mismatch",
+    "speculative.sampled":         "Match de token-id muestreado",
+    "speculative.first_mismatch":  "Primer mismatch",
+    "speculative.special_diff":    "Diferencias de special tokens",
+    "speculative.added_diff":      "Diferencias de added tokens",
+    "speculative.added_diff_more": "+ más …",
+    "speculative.speedup.title":   "Banda estimada de speedup",
+    "speculative.speedup.params":  "target {target} / draft {draft} (ratio de params {ratio})",
+    "speculative.speedup.low":     "Bajo (α=0.50)",
+    "speculative.speedup.expected":"Esperado (α=0.70)",
+    "speculative.speedup.high":    "Alto (α=0.85)",
+    "speculative.speedup.disclaimer": "α = tasa de aceptación del draft. El speedup real depende del dominio del prompt, lookahead K, y overhead del engine. Las bandas asumen verifier batching ideal.",
+    "speculative.speedup.draft_not_smaller": "El draft no es más pequeño que el target — spec-dec es mal uso aquí.",
+    "speculative.attribution":     "Referencias:",
+    "speculative.side.target":     "Target",
+    "speculative.side.draft":      "Draft",
+    "speculative.fetch_error.missing_model_id": "falta el model id",
+    "speculative.fetch_error.gated_or_private": "modelo es gated o privado — no se puede hacer fetch del tokenizer sin auth",
+    "speculative.fetch_error.not_found":        "model id no encontrado en HF Hub",
+    "speculative.fetch_error.fetch_failed":     "fetch falló (error HTTP)",
+    "speculative.fetch_error.parse_failed":     "parse JSON falló (archivo malformado)",
+    "speculative.fetch_error.timeout":          "timeout (>8s, tokenizer grande o conexión lenta)",
+    "speculative.fetch_error.network":          "error de red",
+    "speculative.fetch_error.hint":             "Verifica el spelling del model id. Para modelos gated necesitas ver el tokenizer vía tu cuenta HF — esta tool no puede autenticar.",
+    "speculative.hint.missing_input":  "Ingresa ambos model ids (target y draft), luego Verificar.",
+    "speculative.hint.identical_models": "Target y draft son el mismo modelo — spec-dec es un no-op (y desperdicio).",
+    "speculative.verdict.compatible":              "✅ Compatible — vocabs coinciden",
+    "speculative.verdict.compatible_with_caveats": "✅ Compatible — pero special/added tokens difieren (revisar)",
+    "speculative.verdict.partial_compatible":      "⚠ Match parcial (95-99.9% de los ids muestreados)",
+    "speculative.verdict.type_mismatch":           "❌ Tipos de tokenizer difieren — spec-dec imposible",
+    "speculative.verdict.vocab_size_mismatch":     "❌ Tamaños de vocab difieren — espacio de id desalineado",
+    "speculative.verdict.incompatible":            "❌ Incompatibles — demasiados mismatches de id",
+    "speculative.verdict.fetch_failed":            "ℹ No se pudo hacer fetch del tokenizer",
+    "speculative.verdict.identical_models":        "ℹ Modelos idénticos — spec-dec es un no-op",
+    "speculative.verdict.missing_input":           "ℹ Ingresa ambos ids",
+    "inv.v085.speculative":        "<strong>🔬 Spec-Decode</strong> — verifica compatibilidad de vocab del tokenizer entre target + draft antes de enviar speculative decoding (el bug que da PEOR throughput silenciosamente).",
+    "help.v085.speculative.title": "🔬 Compatibilidad de Speculative-Decode",
+    "help.v085.speculative.body":  "El speculative decoding solo funciona si target y draft comparten exactamente el mismo vocabulario. Vocabs mismatched hacen que cada token del draft sea rechazado — pagas AMBOS computes y obtienes peor throughput que baseline. Peor: el sistema sigue emitiendo output correcto (solo más lento), así que el bug es invisible en tests unitarios. vLLM #4570 / #16757 / #20409 / #12488 surfacen variantes. Esta tool hace fetch de `tokenizer.json` desde HF Hub para ambos ids, compara tipo de tokenizer, tamaño de vocab, mapa completo token→id, special tokens, y added tokens, luego estima una banda de speedup basada en ratio de params y tasas típicas α=0.5/0.7/0.85 de aceptación. <em>Caso de uso</em>: antes de lanzar un cluster vLLM con spec-dec habilitado, verifica que el par sea compatible.",
+
     "inv.v081.hub":                "<strong>🧭 Solutions Hub</strong> — cada pain documentado mapeado a un mode tafagent o herramienta externa curada. No reinventes — encuentra.",
     "help.v081.hub.title":         "🧭 Solutions Hub",
     "help.v081.hub.body":          "tafagent como integrador, no silo. 30+ pains en 7 categorías (eval reliability · diagnósticos · setup · training · retrieval · multimodal · observability), cada uno mapeado a (a) el mode tafagent que lo resuelve, si existe, y (b) las herramientas externas best-of-breed que la comunidad ya usa (RAGAS, MTEB, HELM, MCP Schema Validator, llm-stats, llguidance, GlitchMiner, etc.). Caja de búsqueda matchea pain, scenario, y nombre de herramienta. <em>Caso de uso</em>: 'tengo problema X — ¿lo resuelve tafagent, y si no, quién?'",
@@ -2693,6 +2807,63 @@ export const TRANSLATIONS = {
     "help.v084.cache.title":       "🔁 Prédicteur de Diff Prompt-Cache",
     "help.v084.cache.body":        "Les caches prompt de chaque fournisseur ont des règles différentes : le <code>cache_control</code> d'Anthropic casse au premier token différent du préfixe marqué ; OpenAI auto-cache les préfixes ≥1024 tokens ; les context caches Gemini requièrent ≥32K tokens. Une édition mal placée 10x silencieusement votre facture — l'API ne prévient pas, et le coût n'apparaît qu'à la facture suivante. Collez ancien + nouveau prompt, le prédicteur trouve le plus long préfixe commun, estime les tokens avec trois profils de tokenizer (anglais / code / CJK), et montre le taux de hit par fournisseur + delta $ vs sans cache pour Claude Opus/Sonnet/Haiku, GPT-5/mini, et Gemini 2.5 Pro. <em>Cas d'usage</em> : 'J'ai modifié le system prompt et la facture a sauté — qu'est-ce qui a cassé ?' → collez les deux prompts, voyez exactement quel fournisseur a arrêté de cacher.",
 
+    // v0.8.5 — anti-bullshit pack #11: Speculative-Decode Compatibility
+    "modes.speculative":           "🔬 Spec-Decode",
+    "mode_desc.speculative":       "Récupère `tokenizer.json` depuis HF Hub pour deux model ids et vérifie la compatibilité du vocab avant de configurer le speculative decoding. Attrape le bug de mismatch silencieux qui gaspille le compute du draft.",
+    "speculative.title":           "🔬 Compatibilité Speculative-Decode",
+    "speculative.tip":             "Le speculative decoding (vLLM, SGLang, llama.cpp, transformers) requiert que draft et target partagent un vocabulaire EXACT. Tout désaccord de token-id fait que le target rejette chaque token du draft — vous payez LES DEUX coûts de compute et obtenez UN PIRE débit que la baseline. Le système rapporte une sortie nominale (juste plus lente), donc le bug est invisible aux tests unitaires. Cet outil récupère `tokenizer.json` depuis HF Hub pour les deux ids et compare.",
+    "speculative.desc":            "<strong>Ne déployez pas spec-dec avec des vocabs mismatched.</strong> Collez target + draft model ids → l'outil fetch les tokenizers, compare type de vocab, taille, token-ids échantillonnés, special tokens, added tokens → verdict + estimation de speedup.",
+    "speculative.target_label":    "Model id du target (gros) :",
+    "speculative.draft_label":     "Model id du draft (petit) :",
+    "speculative.target_label_short": "target",
+    "speculative.draft_label_short":  "draft",
+    "speculative.check_btn":       "🔍 Vérifier compatibilité",
+    "speculative.example_good_btn":"↳ Exemple : Llama-3.1 8B/70B (bon)",
+    "speculative.example_bad_btn": "↳ Exemple : cross-family (mauvais)",
+    "speculative.status.fetching": "🔄 Récupération de tokenizer.json depuis HF Hub pour les deux modèles…",
+    "speculative.status.done":     "✅ {verdict}",
+    "speculative.status.error":    "❌ Erreur",
+    "speculative.type_mismatch_note": "types de tokenizer diffèrent ; spec-dec impossible",
+    "speculative.vocab_size":      "Taille du vocab",
+    "speculative.size_diff":       "diffèrent — chaque id réutilisé est un mismatch",
+    "speculative.sampled":         "Match de token-id échantillonné",
+    "speculative.first_mismatch":  "Premier mismatch",
+    "speculative.special_diff":    "Différences de special tokens",
+    "speculative.added_diff":      "Différences de added tokens",
+    "speculative.added_diff_more": "+ plus …",
+    "speculative.speedup.title":   "Bande de speedup estimée",
+    "speculative.speedup.params":  "target {target} / draft {draft} (ratio de params {ratio})",
+    "speculative.speedup.low":     "Bas (α=0.50)",
+    "speculative.speedup.expected":"Attendu (α=0.70)",
+    "speculative.speedup.high":    "Haut (α=0.85)",
+    "speculative.speedup.disclaimer": "α = taux d'acceptation du draft. Le speedup réel dépend du domaine du prompt, lookahead K, et overhead du moteur. Les bandes supposent un verifier batching idéal.",
+    "speculative.speedup.draft_not_smaller": "Le draft n'est pas plus petit que le target — spec-dec est un mauvais usage ici.",
+    "speculative.attribution":     "Réfs :",
+    "speculative.side.target":     "Target",
+    "speculative.side.draft":      "Draft",
+    "speculative.fetch_error.missing_model_id": "model id manquant",
+    "speculative.fetch_error.gated_or_private": "modèle gated ou privé — impossible de récupérer le tokenizer sans auth",
+    "speculative.fetch_error.not_found":        "model id non trouvé sur HF Hub",
+    "speculative.fetch_error.fetch_failed":     "fetch échoué (erreur HTTP)",
+    "speculative.fetch_error.parse_failed":     "parse JSON échoué (fichier malformé)",
+    "speculative.fetch_error.timeout":          "timeout (>8s, gros tokenizer ou connexion lente)",
+    "speculative.fetch_error.network":          "erreur réseau",
+    "speculative.fetch_error.hint":             "Vérifiez l'orthographe du model id. Pour les modèles gated, consultez le tokenizer via votre compte HF — cet outil ne peut pas auth.",
+    "speculative.hint.missing_input":  "Entrez les deux model ids (target et draft), puis Vérifier.",
+    "speculative.hint.identical_models": "Target et draft sont le même modèle — spec-dec est un no-op (et un gaspillage).",
+    "speculative.verdict.compatible":              "✅ Compatible — vocabs correspondent",
+    "speculative.verdict.compatible_with_caveats": "✅ Compatible — mais special/added tokens diffèrent (à revoir)",
+    "speculative.verdict.partial_compatible":      "⚠ Match partiel (95-99.9% des ids échantillonnés)",
+    "speculative.verdict.type_mismatch":           "❌ Types de tokenizer diffèrent — spec-dec impossible",
+    "speculative.verdict.vocab_size_mismatch":     "❌ Tailles de vocab diffèrent — espace d'id désaligné",
+    "speculative.verdict.incompatible":            "❌ Incompatibles — trop de mismatches d'id",
+    "speculative.verdict.fetch_failed":            "ℹ Récupération du tokenizer impossible",
+    "speculative.verdict.identical_models":        "ℹ Modèles identiques — spec-dec est un no-op",
+    "speculative.verdict.missing_input":           "ℹ Entrez les deux ids",
+    "inv.v085.speculative":        "<strong>🔬 Spec-Decode</strong> — vérifie la compatibilité du vocab du tokenizer entre target + draft avant de déployer le speculative decoding (le bug qui donne UN PIRE débit silencieusement).",
+    "help.v085.speculative.title": "🔬 Compatibilité Speculative-Decode",
+    "help.v085.speculative.body":  "Le speculative decoding ne marche que si target et draft partagent exactement le même vocabulaire. Des vocabs mismatched font que chaque token du draft est rejeté — vous payez LES DEUX coûts de compute et obtenez un pire débit que la baseline. Pire : le système émet toujours une sortie correcte (juste plus lente), donc le bug est invisible aux tests unitaires. vLLM #4570 / #16757 / #20409 / #12488 surfent les variantes. Cet outil récupère `tokenizer.json` depuis HF Hub pour les deux model ids, compare le type de tokenizer, la taille du vocab, la map complète token→id, les special tokens, et les added tokens, puis estime une bande de speedup basée sur le ratio de params et les taux α=0.5/0.7/0.85 d'acceptation typiques. <em>Cas d'usage</em> : avant de lancer un cluster vLLM avec spec-dec activé, vérifiez que la paire est compatible.",
+
     "inv.v081.hub":                "<strong>🧭 Solutions Hub</strong> — chaque pain documenté mappé à un mode tafagent ou outil externe curé. Ne réinventez pas — trouvez.",
     "help.v081.hub.title":         "🧭 Solutions Hub",
     "help.v081.hub.body":          "tafagent comme intégrateur, pas silo. 30+ pains à travers 7 catégories (eval reliability · diagnostics · setup · training · retrieval · multimodal · observability), chacun mappé à (a) le mode tafagent qui le résout, s'il existe, et (b) les outils externes best-of-breed que la communauté utilise déjà (RAGAS, MTEB, HELM, MCP Schema Validator, llm-stats, llguidance, GlitchMiner, etc.). La barre de recherche matche pain, scénario, et nom d'outil. <em>Cas d'usage</em> : 'j'ai le problème X — tafagent le résout-il, et sinon, qui ?'",
@@ -3653,6 +3824,63 @@ export const TRANSLATIONS = {
     "help.v084.cache.title":       "🔁 Prompt-Cache 差异预测器",
     "help.v084.cache.body":        "每个提供商的 prompt cache 有不同规则：Anthropic 的 <code>cache_control</code> 在标记前缀的第一个 token 差异处中断；OpenAI 自动缓存 ≥1024 token 的前缀；Gemini context cache 需要 ≥32K token。位置不当的编辑会悄悄使你的账单 10 倍——API 不会警告，成本只在下张账单上出现。粘贴新旧 prompt，预测器找到最长公共前缀，用三种 tokenizer 配置（英语/代码/CJK）估算 token，并显示每个提供商的命中率 + 与无缓存的 $ 差额，包括 Claude Opus/Sonnet/Haiku、GPT-5/mini 和 Gemini 2.5 Pro。<em>用例</em>：『我调整了 system prompt 后账单暴涨——什么坏了？』→ 粘贴两个 prompt，看到底哪个提供商停止缓存。",
 
+    // v0.8.5 — anti-bullshit pack #11: Speculative-Decode Compatibility
+    "modes.speculative":           "🔬 Spec-Decode",
+    "mode_desc.speculative":       "从 HF Hub 获取两个 model id 的 `tokenizer.json` 并在配置 speculative decoding 之前验证 vocab 兼容性。捕获浪费 draft 计算的静默不匹配 bug。",
+    "speculative.title":           "🔬 Speculative-Decode 兼容性",
+    "speculative.tip":             "Speculative decoding（vLLM、SGLang、llama.cpp、transformers）要求 draft 和 target 共享完全相同的词汇表。任何 token-id 不一致都会使 target 拒绝每个 draft token——你支付双倍计算成本且吞吐量比 baseline 更差。系统报告名义输出（只是更慢），所以 bug 在单元测试中不可见。这个工具从 HF Hub 获取两个 id 的 `tokenizer.json` 并比较。",
+    "speculative.desc":            "<strong>不要发布 vocab 不匹配的 spec-dec。</strong> 粘贴 target + draft model id → 工具获取 tokenizer，比较 vocab 类型、大小、采样的 token-id、special token、added token → 判定 + speedup 估算。",
+    "speculative.target_label":    "Target（大）model id：",
+    "speculative.draft_label":     "Draft（小）model id：",
+    "speculative.target_label_short": "target",
+    "speculative.draft_label_short":  "draft",
+    "speculative.check_btn":       "🔍 检查兼容性",
+    "speculative.example_good_btn":"↳ 示例：Llama-3.1 8B/70B（好）",
+    "speculative.example_bad_btn": "↳ 示例：跨 family（坏）",
+    "speculative.status.fetching": "🔄 从 HF Hub 获取两个模型的 tokenizer.json…",
+    "speculative.status.done":     "✅ {verdict}",
+    "speculative.status.error":    "❌ 错误",
+    "speculative.type_mismatch_note": "tokenizer 类型不同；spec-dec 不可能",
+    "speculative.vocab_size":      "Vocab 大小",
+    "speculative.size_diff":       "不同——每个重用的 id 都是一个不对齐",
+    "speculative.sampled":         "Token-id 采样匹配",
+    "speculative.first_mismatch":  "首次不匹配",
+    "speculative.special_diff":    "Special token 差异",
+    "speculative.added_diff":      "Added token 差异",
+    "speculative.added_diff_more": "+ 更多 …",
+    "speculative.speedup.title":   "估算的 speedup 范围",
+    "speculative.speedup.params":  "target {target} / draft {draft}（参数比 {ratio}）",
+    "speculative.speedup.low":     "低（α=0.50）",
+    "speculative.speedup.expected":"预期（α=0.70）",
+    "speculative.speedup.high":    "高（α=0.85）",
+    "speculative.speedup.disclaimer": "α = draft 接受率。实际 speedup 取决于 prompt 域、lookahead K 和引擎开销。范围假设理想的 verifier batching。",
+    "speculative.speedup.draft_not_smaller": "Draft 不比 target 小——这里 spec-dec 是误用。",
+    "speculative.attribution":     "参考：",
+    "speculative.side.target":     "Target",
+    "speculative.side.draft":      "Draft",
+    "speculative.fetch_error.missing_model_id": "缺少 model id",
+    "speculative.fetch_error.gated_or_private": "模型受限或私有——没有 auth 无法获取 tokenizer",
+    "speculative.fetch_error.not_found":        "在 HF Hub 上找不到 model id",
+    "speculative.fetch_error.fetch_failed":     "获取失败（HTTP 错误）",
+    "speculative.fetch_error.parse_failed":     "JSON 解析失败（文件格式不正确）",
+    "speculative.fetch_error.timeout":          "超时（>8 秒，大 tokenizer 或慢速连接）",
+    "speculative.fetch_error.network":          "网络错误",
+    "speculative.fetch_error.hint":             "检查 model id 拼写。受限模型需要通过你的 HF 账户查看 tokenizer 文件——这个工具无法 auth。",
+    "speculative.hint.missing_input":  "输入两个 model id（target 和 draft），然后检查。",
+    "speculative.hint.identical_models": "Target 和 draft 是同一个模型——spec-dec 是 no-op（且浪费）。",
+    "speculative.verdict.compatible":              "✅ 兼容——vocab 匹配",
+    "speculative.verdict.compatible_with_caveats": "✅ 兼容——但 special/added token 不同（请审查）",
+    "speculative.verdict.partial_compatible":      "⚠ 部分匹配（采样 id 的 95-99.9%）",
+    "speculative.verdict.type_mismatch":           "❌ Tokenizer 类型不同——spec-dec 不可能",
+    "speculative.verdict.vocab_size_mismatch":     "❌ Vocab 大小不同——id 空间不对齐",
+    "speculative.verdict.incompatible":            "❌ 不兼容——太多 id 不匹配",
+    "speculative.verdict.fetch_failed":            "ℹ 无法获取 tokenizer",
+    "speculative.verdict.identical_models":        "ℹ 模型相同——spec-dec 是 no-op",
+    "speculative.verdict.missing_input":           "ℹ 输入两个 id",
+    "inv.v085.speculative":        "<strong>🔬 Spec-Decode</strong> — 在发布 speculative decoding 前验证 target + draft 之间的 tokenizer vocab 兼容性（静默给出更差吞吐量的 bug）。",
+    "help.v085.speculative.title": "🔬 Speculative-Decode 兼容性",
+    "help.v085.speculative.body":  "Speculative decoding 仅当 target 和 draft 共享完全相同的词汇表时才能工作。Vocab 不匹配导致每个 draft token 被拒绝——你支付双倍计算成本且吞吐量比 baseline 更差。更糟：系统仍输出正确（只是更慢），所以 bug 在单元测试中不可见。vLLM #4570 / #16757 / #20409 / #12488 都显示了变种。这个工具从 HF Hub 获取两个 model id 的 `tokenizer.json`，比较 tokenizer 类型、vocab 大小、完整 token→id 映射、special token 和 added token，然后基于参数比和典型 α=0.5/0.7/0.85 接受率估算 speedup 范围。<em>用例</em>：在启动启用了 spec-dec 的 vLLM 集群之前，验证这对模型是否真的兼容。",
+
     "inv.v081.hub":                "<strong>🧭 Solutions Hub</strong> — 每个文档化的问题都映射到一个 tafagent 模式或精选外部工具。别重复发明 — 去找。",
     "help.v081.hub.title":         "🧭 Solutions Hub",
     "help.v081.hub.body":          "tafagent 作为集成者而非孤岛。30+ 问题跨 7 类别（评估可靠性 · 诊断 · 设置 · 训练 · 检索 · 多模态 · 可观测性），每个映射到（a）解决它的 tafagent 模式（若存在），以及（b）社区已信任的最佳外部工具（RAGAS、MTEB、HELM、MCP Schema Validator、llm-stats、llguidance、GlitchMiner 等）。搜索框匹配 pain、场景和工具名称。<em>用例</em>：'我有问题 X — tafagent 解决它吗，如果不，谁解决？'",

js/main.js

@@ -30,6 +30,7 @@ import {
 import { lintJsonCot, reorderJsonText, classifyFieldName } from "./json_cot_linter.js";
 import { lintPeftCode, ARCH_TARGET_MODULES } from "./peft_anti_pattern.js";
 import { diffPromptCache, PROVIDERS as CACHE_PROVIDERS } from "./prompt_cache_diff.js";
+import { checkCompatibility as specCheckCompat, parseParamHint } from "./spec_decode_compat.js";
 
 // Attach HF Hub search-as-you-type to all 5 model id inputs (Profile, Recipe,
 // Unmask, Template, Quant). Hits public huggingface.co/api/models. Idempotent.
@@ -222,6 +223,7 @@ document.addEventListener("click", (e) => {
       cot: "cot-section",
       peft: "peft-section",
       cache: "cache-section",
+      speculative: "speculative-section",
       hub: "hub-section",
     }[targetMode];
     if (sectionId) {
@@ -247,7 +249,7 @@ document.querySelectorAll(".mode-btn").forEach(btn => {
      "diagnose-section", "phase-section", "unmask-section",
      "template-section", "arena-section", "contam-section",
      "quant-section", "drift-section", "niah-section",
-     "saturation-section", "cot-section", "peft-section", "cache-section", "hub-section"].forEach(id => {
+     "saturation-section", "cot-section", "peft-section", "cache-section", "speculative-section", "hub-section"].forEach(id => {
       const el = $(id);
       if (el) el.style.display = "none";
     });
@@ -262,6 +264,7 @@ document.querySelectorAll(".mode-btn").forEach(btn => {
       cot: "cot-section",
       peft: "peft-section",
       cache: "cache-section",
+      speculative: "speculative-section",
       hub: "hub-section",
     };
     const sectionId = sectionMap[mode];
@@ -272,6 +275,7 @@ document.querySelectorAll(".mode-btn").forEach(btn => {
     if (mode === "cot") initCot();
     if (mode === "peft") initPeft();
     if (mode === "cache") initCacheDiff();
+    if (mode === "speculative") initSpeculative();
     if (mode === "hub") initHub();
   });
 });
@@ -3910,6 +3914,178 @@ $("cache-example-belowmin-btn")?.addEventListener("click", () => {
   runCacheDiff();
 });
 
+// ════════════════════════════════════════════════════════════════════
+// 🔬 Speculative-Decode Compatibility (v0.8.5 anti-bullshit pack #11)
+// ════════════════════════════════════════════════════════════════════
+const SPEC_VERDICT_BG = {
+  compatible:                 "#3fb950",
+  compatible_with_caveats:    "#3fb950",
+  partial_compatible:         "#d29922",
+  type_mismatch:              "#f85149",
+  vocab_size_mismatch:        "#f85149",
+  incompatible:               "#f85149",
+  fetch_failed:               "#8b949e",
+  identical_models:           "#58a6ff",
+  missing_input:              "#8b949e",
+};
+
+let __specInited = false;
+
+function initSpeculative() {
+  if (__specInited) return;
+  __specInited = true;
+  // No-op (no async preload); placeholder kept for symmetry.
+}
+
+function fmtParams(p) {
+  if (!p) return "—";
+  if (p >= 1e9) return `${(p / 1e9).toFixed(1)}B`;
+  if (p >= 1e6) return `${(p / 1e6).toFixed(1)}M`;
+  return p.toLocaleString();
+}
+
+function renderSpecResult(result) {
+  const verdict = t(`speculative.verdict.${result.code}`) || result.code;
+  const verdictBg = SPEC_VERDICT_BG[result.code] || "#8b949e";
+  const verdictBadge = `<span class="badge" style="background:${verdictBg};">${verdict}</span>`;
+
+  // Failure-mode short-circuits
+  if (result.code === "missing_input" || result.code === "identical_models") {
+    return `<div class="arena-result">
+      <p style="font-size:1.1em;">${verdictBadge}</p>
+      <p class="recipe-desc">${t(`speculative.hint.${result.code}`) || ""}</p>
+    </div>`;
+  }
+  if (result.code === "fetch_failed") {
+    const errs = (result.errors || []).map(e => {
+      const sideLabel = e.side === "target" ? (t("speculative.side.target") || "Target") : (t("speculative.side.draft") || "Draft");
+      const reason = t(`speculative.fetch_error.${e.error}`) || e.error;
+      return `<li><strong>${sideLabel}</strong>: ${reason}${e.status ? ` (HTTP ${e.status})` : ""}</li>`;
+    }).join("");
+    return `<div class="arena-result">
+      <p style="font-size:1.1em;">${verdictBadge}</p>
+      <ul>${errs}</ul>
+      <p class="recipe-desc subtle">${t("speculative.fetch_error.hint") || "Check the model id spelling. For gated models you'll need to view the tokenizer file via your HF account — this tool can't auth."}</p>
+    </div>`;
+  }
+
+  const p = result.params;
+
+  // Section 1 — vocab summary
+  const typeBadge = (label, val, bg) =>
+    `<span class="badge" style="background:${bg};">${label}: <code>${val ?? "—"}</code></span>`;
+  const typeRow = `
+    ${typeBadge(t("speculative.target_label_short") || "target", p.target_type, p.type_match ? "#3fb950" : "#f85149")}
+    ${typeBadge(t("speculative.draft_label_short") || "draft",  p.draft_type,  p.type_match ? "#3fb950" : "#f85149")}
+    ${p.type_match ? "" : `<span class="subtle"> ← ${t("speculative.type_mismatch_note") || "tokenizer types differ; spec-dec impossible"}</span>`}
+  `;
+
+  const sizeRow = `
+    <strong>${t("speculative.vocab_size") || "Vocab size"}:</strong>
+    target = <code>${p.target_vocab_size.toLocaleString()}</code>,
+    draft = <code>${p.draft_vocab_size.toLocaleString()}</code>
+    ${p.vocab_size_match ? "" : `<span style="color:#f85149;"> ← ${t("speculative.size_diff") || "differ — every reused id is a misalignment"}</span>`}
+  `;
+
+  // Sampled match
+  const matchPct = p.sampled_total > 0 ? Math.round(p.sampled_match_ratio * 100) : 0;
+  const matchColor = matchPct >= 99.9 ? "#3fb950" : matchPct >= 95 ? "#d29922" : "#f85149";
+  const sampleRow = `
+    <strong>${t("speculative.sampled") || "Token-id sample match"}:</strong>
+    <span style="color:${matchColor};font-weight:600;">${matchPct}%</span>
+    <span class="subtle">(${p.sampled_match_count.toLocaleString()} / ${p.sampled_total.toLocaleString()} tokens)</span>
+    ${p.first_mismatch ? `<br><span class="subtle">${t("speculative.first_mismatch") || "First mismatch"}: <code>${escapeHtml(p.first_mismatch.token).slice(0, 40)}</code> → target id ${p.first_mismatch.target_id ?? "—"}, draft id ${p.first_mismatch.draft_id ?? "—"}</span>` : ""}
+  `;
+
+  // Special / added token diffs
+  const specDiffRows = (p.special_tokens_diff || []).map(d =>
+    `<li><code>${d.name}</code>: target=<code>${escapeHtml(String(d.target ?? "—"))}</code>, draft=<code>${escapeHtml(String(d.draft ?? "—"))}</code></li>`
+  ).join("");
+  const specDiffBlock = specDiffRows
+    ? `<details style="margin-top:0.5em;"><summary>${t("speculative.special_diff") || "Special-token differences"} (${p.special_tokens_diff.length})</summary><ul>${specDiffRows}</ul></details>`
+    : "";
+
+  const addedDiffPreview = (p.added_tokens_diff || []).slice(0, 12).map(d =>
+    `<li><span class="subtle">${d.side === "target_only" ? "target only" : "draft only"}:</span> <code>${escapeHtml(d.token).slice(0, 40)}</code></li>`
+  ).join("");
+  const addedDiffBlock = addedDiffPreview
+    ? `<details style="margin-top:0.5em;"><summary>${t("speculative.added_diff") || "Added-token differences"} (${(p.added_tokens_diff||[]).length})</summary><ul>${addedDiffPreview}${p.added_tokens_diff.length > 12 ? `<li class="subtle">${t("speculative.added_diff_more") || "+ more …"}</li>` : ""}</ul></details>`
+    : "";
+
+  // Section 2 — speedup band (only when compatible-ish)
+  let speedupBlock = "";
+  if (p.speedup_expected != null) {
+    const ratio = p.param_ratio ? `${(p.param_ratio * 100).toFixed(1)}%` : "—";
+    speedupBlock = `
+      <div style="margin-top:1em;padding:0.75em;background:#161b22;border-left:3px solid #3fb950;border-radius:4px;">
+        <strong>${t("speculative.speedup.title") || "Estimated speedup band"}</strong><br>
+        <span class="subtle" style="font-size:0.85em;">${tFmt("speculative.speedup.params", { target: fmtParams(p.target_params), draft: fmtParams(p.draft_params), ratio }) || `target ${fmtParams(p.target_params)} / draft ${fmtParams(p.draft_params)} (param ratio ${ratio})`}</span>
+        <div style="margin-top:0.5em;display:flex;gap:1em;flex-wrap:wrap;">
+          <div>${t("speculative.speedup.low") || "Low (α=0.50)"}:<br><strong style="font-size:1.2em;">${p.speedup_low}×</strong></div>
+          <div>${t("speculative.speedup.expected") || "Expected (α=0.70)"}:<br><strong style="font-size:1.4em;color:#3fb950;">${p.speedup_expected}×</strong></div>
+          <div>${t("speculative.speedup.high") || "High (α=0.85)"}:<br><strong style="font-size:1.2em;">${p.speedup_high}×</strong></div>
+        </div>
+        <p class="subtle" style="font-size:0.78em;margin-top:0.5em;">${t("speculative.speedup.disclaimer") || "α = draft acceptance rate. Real speedup depends on prompt domain, lookahead K, and engine overhead. Bands assume ideal verifier batching."}</p>
+      </div>
+    `;
+  } else if (p.target_params && p.draft_params && p.param_ratio >= 1) {
+    speedupBlock = `<p class="recipe-desc" style="color:#f85149;margin-top:1em;">${t("speculative.speedup.draft_not_smaller") || "Draft is not smaller than target — spec-dec is misuse here."}</p>`;
+  }
+
+  // Attribution
+  const attribution = `
+    <p class="recipe-desc subtle" style="font-size:0.82em;margin-top:1em;">
+      ${t("speculative.attribution") || "Refs:"}
+      <a href="https://docs.vllm.ai/en/latest/serving/speculative_decoding.html" target="_blank" rel="noopener noreferrer">vLLM spec-dec docs</a> ·
+      <a href="https://docs.sglang.ai/router/router.html" target="_blank" rel="noopener noreferrer">SGLang</a> ·
+      <a href="https://huggingface.co/docs/transformers/main/en/llm_optims#speculative-decoding" target="_blank" rel="noopener noreferrer">transformers assistant_model</a> ·
+      <a href="https://arxiv.org/abs/2211.17192" target="_blank" rel="noopener noreferrer">Leviathan et al. 2022</a>
+    </p>
+  `;
+
+  return `<div class="arena-result">
+    <p style="font-size:1.1em;">${verdictBadge}</p>
+    <p>${typeRow}</p>
+    <p>${sizeRow}</p>
+    <p>${sampleRow}</p>
+    ${specDiffBlock}
+    ${addedDiffBlock}
+    ${speedupBlock}
+    ${attribution}
+  </div>`;
+}
+
+async function runSpecCheck() {
+  const targetId = $("spec-target-id")?.value?.trim() || "";
+  const draftId  = $("spec-draft-id")?.value?.trim() || "";
+  $("spec-status").textContent = t("speculative.status.fetching") || "🔄 Fetching tokenizer.json from HF Hub for both models…";
+  $("spec-output").innerHTML = "";
+  try {
+    const result = await specCheckCompat(targetId, draftId);
+    $("spec-output").innerHTML = renderSpecResult(result);
+    $("spec-status").textContent = tFmt("speculative.status.done", {
+      verdict: t(`speculative.verdict.${result.code}`) || result.code,
+    });
+  } catch (e) {
+    $("spec-status").textContent = (t("speculative.status.error") || "❌ Error") + " " + (e.message || e);
+  }
+}
+
+$("spec-check-btn")?.addEventListener("click", runSpecCheck);
+$("spec-example-good-btn")?.addEventListener("click", () => {
+  $("spec-target-id").value = "meta-llama/Llama-3.1-70B-Instruct";
+  $("spec-draft-id").value  = "meta-llama/Llama-3.1-8B-Instruct";
+  runSpecCheck();
+});
+$("spec-example-bad-btn")?.addEventListener("click", () => {
+  $("spec-target-id").value = "meta-llama/Llama-3.1-8B-Instruct";
+  $("spec-draft-id").value  = "mistralai/Mistral-7B-Instruct-v0.3";
+  runSpecCheck();
+});
+
+// (HF autocomplete on spec-target-id / spec-draft-id is registered via
+// the known-id list in hf_autocomplete.js; no extra wiring needed here.)
+
 // ════════════════════════════════════════════════════════════════════
 // Bootstrap
 // ════════════════════════════════════════════════════════════════════

js/spec_decode_compat.js

@@ -0,0 +1,372 @@
+// Speculative-Decode Compatibility Checker (v0.8.5 anti-bullshit pack #11)
+//
+// Pain: speculative decoding (vLLM, SGLang, llama.cpp, transformers
+// `assistant_model`) requires the draft and target model to share an
+// EXACT vocabulary. If token IDs disagree, every draft token is
+// rejected by the target's verifier — the user pays the draft compute
+// AND the full target compute, getting WORSE throughput than baseline.
+// Worse, the system reports nominal output (just slower) so the bug
+// is invisible in unit tests.
+//
+// Common silent failures:
+//   - Llama-3.1 draft + Llama-3.2 target (vocab differs by added tokens)
+//   - Mistral draft + Llama target (different tokenizer family entirely)
+//   - Quantized variant with different special tokens
+//   - Chat-template additions (`<|im_start|>` etc) on one side only
+//
+// vLLM #4570 / #16757 / #20409 / #12488 all surface variants of this.
+//
+// Tool: paste two HF model ids → fetch `tokenizer.json` from HF Hub for
+// both → compare vocab type, size, token-to-id sample, special tokens,
+// added tokens → verdict + speedup estimate when compatible.
+//
+// Pure logic + async fetch. No human strings; main.js does i18n.
+
+// =============================================================================
+// HF Hub fetching
+// =============================================================================
+//
+// HF Hub serves text-content files (tokenizer.json, tokenizer_config.json,
+// config.json) with CORS. The v0.7.4 autocomplete already proved this
+// path is reachable from the browser. We fetch with a short timeout so
+// the UI doesn't hang on gated/private/missing models.
+
+const HF_BASE = "https://huggingface.co";
+const FETCH_TIMEOUT_MS = 8000;
+
+async function fetchHfJson(modelId, fileName) {
+  if (typeof modelId !== "string" || !modelId.trim()) {
+    return { ok: false, error: "missing_model_id" };
+  }
+  const url = `${HF_BASE}/${encodeURI(modelId.trim())}/raw/main/${fileName}`;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  try {
+    const res = await fetch(url, { signal: controller.signal });
+    clearTimeout(timer);
+    if (res.status === 401 || res.status === 403) {
+      return { ok: false, error: "gated_or_private", status: res.status };
+    }
+    if (res.status === 404) {
+      return { ok: false, error: "not_found", status: 404 };
+    }
+    if (!res.ok) {
+      return { ok: false, error: "fetch_failed", status: res.status };
+    }
+    const text = await res.text();
+    try {
+      return { ok: true, data: JSON.parse(text), bytes: text.length };
+    } catch (e) {
+      return { ok: false, error: "parse_failed", message: String(e).slice(0, 200) };
+    }
+  } catch (e) {
+    clearTimeout(timer);
+    if (e.name === "AbortError") {
+      return { ok: false, error: "timeout" };
+    }
+    return { ok: false, error: "network", message: String(e).slice(0, 200) };
+  }
+}
+
+export async function fetchTokenizer(modelId) {
+  // tokenizer.json is the canonical fast-tokenizer artifact. If it's
+  // absent (some older models ship only sentencepiece), fall back to
+  // tokenizer_config.json which carries the special-tokens metadata
+  // even without the BPE merges.
+  const main = await fetchHfJson(modelId, "tokenizer.json");
+  if (main.ok) return { ...main, source: "tokenizer.json" };
+  const fallback = await fetchHfJson(modelId, "tokenizer_config.json");
+  if (fallback.ok) return { ...fallback, source: "tokenizer_config.json" };
+  return main; // surface the original error code
+}
+
+export async function fetchConfig(modelId) {
+  return await fetchHfJson(modelId, "config.json");
+}
+
+// =============================================================================
+// Vocab extraction + comparison
+// =============================================================================
+
+// Return a Map<string,id> for whatever shape the tokenizer.json carries.
+// HF fast tokenizers store vocab under `model.vocab`, which is either
+// {token: id} (BPE) or [[token, score], ...] (Unigram). Special tokens
+// live under top-level `added_tokens` (with id) and the model itself
+// keeps an `unk_token`/`bos_token`/`eos_token` etc shape.
+function extractVocab(tokenizer) {
+  if (!tokenizer || typeof tokenizer !== "object") return null;
+  const model = tokenizer.model;
+  if (!model) return null;
+  let vocab = null;
+  if (model.vocab && typeof model.vocab === "object" && !Array.isArray(model.vocab)) {
+    // BPE / WordPiece form
+    vocab = model.vocab;
+  } else if (Array.isArray(model.vocab)) {
+    // Unigram form: [[token, log_prob], ...]
+    vocab = {};
+    for (let i = 0; i < model.vocab.length; i++) {
+      const entry = model.vocab[i];
+      if (Array.isArray(entry)) vocab[entry[0]] = i;
+    }
+  }
+  return vocab;
+}
+
+function extractAddedTokens(tokenizer) {
+  if (!tokenizer || typeof tokenizer !== "object") return [];
+  const arr = tokenizer.added_tokens;
+  if (!Array.isArray(arr)) return [];
+  return arr.map(t => ({
+    id: typeof t.id === "number" ? t.id : null,
+    content: typeof t.content === "string" ? t.content : "",
+    special: !!t.special,
+  })).filter(t => t.content);
+}
+
+function extractSpecialTokens(tokenizer) {
+  // tokenizer.json places special-token strings on the post-processor /
+  // template — but the canonical names are in tokenizer_config.json.
+  // Return what's available; the UI can show "—" for missing.
+  if (!tokenizer || typeof tokenizer !== "object") return {};
+  return {
+    bos_token: tokenizer.bos_token ?? null,
+    eos_token: tokenizer.eos_token ?? null,
+    pad_token: tokenizer.pad_token ?? null,
+    unk_token: tokenizer.unk_token ?? null,
+  };
+}
+
+function tokenizerType(tokenizer) {
+  return tokenizer?.model?.type || null;
+}
+
+// Sample-match strategy: for full-vocab compare (which is fine in JS
+// for vocabs up to ~150K), build both maps and check equality. The
+// expensive branch — VOCABS DIFFER — short-circuits on the first
+// mismatch so the cost is bounded by the number of differing tokens.
+export function compareVocabs(targetTok, draftTok) {
+  const tType = tokenizerType(targetTok);
+  const dType = tokenizerType(draftTok);
+  const tVocab = extractVocab(targetTok);
+  const dVocab = extractVocab(draftTok);
+
+  if (!tVocab || !dVocab) {
+    return {
+      type_match: tType !== null && tType === dType,
+      target_type: tType,
+      draft_type: dType,
+      vocab_size_match: false,
+      target_vocab_size: tVocab ? Object.keys(tVocab).length : 0,
+      draft_vocab_size: dVocab ? Object.keys(dVocab).length : 0,
+      sampled_total: 0,
+      sampled_match_count: 0,
+      first_mismatch: null,
+      special_tokens_diff: [],
+      added_tokens_diff: [],
+    };
+  }
+
+  const tKeys = Object.keys(tVocab);
+  const dKeys = Object.keys(dVocab);
+  const tSize = tKeys.length;
+  const dSize = dKeys.length;
+  const sizeMatch = tSize === dSize;
+
+  // Sample comparison: walk every key on the SMALLER side. For each
+  // key, check the id matches exactly. First mismatch is recorded.
+  const sampleKeys = tSize <= dSize ? tKeys : dKeys;
+  const a = tSize <= dSize ? tVocab : dVocab;
+  const b = tSize <= dSize ? dVocab : tVocab;
+  const sideA = tSize <= dSize ? "target" : "draft";
+  const sideB = sideA === "target" ? "draft" : "target";
+
+  let matchCount = 0;
+  let firstMismatch = null;
+  for (const key of sampleKeys) {
+    const aId = a[key];
+    const bId = b[key];
+    if (aId === bId) {
+      matchCount++;
+    } else if (firstMismatch === null) {
+      firstMismatch = { token: key, [`${sideA}_id`]: aId, [`${sideB}_id`]: bId };
+    }
+  }
+
+  // Special-token diff
+  const tSpec = extractSpecialTokens(targetTok);
+  const dSpec = extractSpecialTokens(draftTok);
+  const specDiff = [];
+  for (const name of ["bos_token", "eos_token", "pad_token", "unk_token"]) {
+    if ((tSpec[name] ?? null) !== (dSpec[name] ?? null)) {
+      specDiff.push({ name, target: tSpec[name], draft: dSpec[name] });
+    }
+  }
+
+  // Added-tokens diff (chat-template tokens etc.)
+  const tAdded = extractAddedTokens(targetTok);
+  const dAdded = extractAddedTokens(draftTok);
+  const tAddedSet = new Set(tAdded.map(x => `${x.id}:${x.content}`));
+  const dAddedSet = new Set(dAdded.map(x => `${x.id}:${x.content}`));
+  const addedDiff = [];
+  for (const k of tAddedSet) if (!dAddedSet.has(k)) addedDiff.push({ side: "target_only", token: k });
+  for (const k of dAddedSet) if (!tAddedSet.has(k)) addedDiff.push({ side: "draft_only", token: k });
+
+  return {
+    type_match: tType === dType,
+    target_type: tType,
+    draft_type: dType,
+    vocab_size_match: sizeMatch,
+    target_vocab_size: tSize,
+    draft_vocab_size: dSize,
+    sampled_total: sampleKeys.length,
+    sampled_match_count: matchCount,
+    first_mismatch: firstMismatch,
+    special_tokens_diff: specDiff,
+    added_tokens_diff: addedDiff,
+  };
+}
+
+// =============================================================================
+// Param-count parsing — best-effort from model id strings
+// =============================================================================
+//
+// HF model ids commonly carry a size hint: "Llama-3.1-8B", "Qwen2.5-72B",
+// "Mistral-7B-v0.3". Parse the largest "{N}{B|M}" token; fall back to
+// fetched config.json hidden_size × num_hidden_layers heuristic.
+
+const PARAM_HINT_RE = /(\d+(?:\.\d+)?)\s*([bm])\b/i;
+
+export function parseParamHint(modelId) {
+  if (typeof modelId !== "string") return null;
+  // Pick the LAST match — for "Llama-3.1-8B" we want 8B, not the "3.1"
+  // (which doesn't carry b/m suffix anyway). Iterating to ensure we
+  // find size hints not just version numbers.
+  const matches = [...modelId.matchAll(/(\d+(?:\.\d+)?)\s*([bm])\b/gi)];
+  if (matches.length === 0) return null;
+  const last = matches[matches.length - 1];
+  const value = parseFloat(last[1]);
+  const unit = last[2].toLowerCase();
+  if (isNaN(value)) return null;
+  const params = unit === "b" ? value * 1e9 : value * 1e6;
+  return params;
+}
+
+// Approximate param count from config.json. Highly heuristic.
+function paramsFromConfig(config) {
+  if (!config) return null;
+  const h = config.hidden_size ?? config.n_embd ?? config.d_model;
+  const l = config.num_hidden_layers ?? config.n_layer ?? config.num_layers;
+  const v = config.vocab_size;
+  if (typeof h !== "number" || typeof l !== "number" || typeof v !== "number") return null;
+  // Rough transformer param count: 12 × h² × l + h × v (embedding) + h × v (output, if not tied).
+  // Not exact but order-of-magnitude usable for ratio computation.
+  return 12 * h * h * l + 2 * h * v;
+}
+
+// =============================================================================
+// Speedup estimation
+// =============================================================================
+//
+// Speculative decoding theoretical maximum speedup:
+//   S = 1 / ((1 - α^(K+1)) / (1 - α) × (T_d / T_t) + α^(K+1))
+// where α = draft acceptance rate, K = lookahead, T_d/T_t = ratio of
+// draft to target step time. For practical config (K=4-7, α=0.6-0.8):
+//   S ≈ 1 + α × (1 - param_ratio)
+// up to a ceiling of ~3-4x. Anything beyond that is wishful.
+//
+// Without α measured in-domain, return a band: low (α=0.5), expected
+// (α=0.7), high (α=0.85). Surfaces the uncertainty honestly.
+
+function speedupBand(targetParams, draftParams) {
+  if (!targetParams || !draftParams) return null;
+  const ratio = draftParams / targetParams;
+  if (ratio >= 1) {
+    // Draft must be smaller; this is misuse.
+    return { ratio, code: "draft_not_smaller" };
+  }
+  const compute = (alpha) => {
+    const s = 1 + alpha * (1 - ratio);
+    // Cap at empirical 3.5x ceiling — beyond that, the assumptions break.
+    return Math.min(s, 3.5);
+  };
+  return {
+    ratio,
+    low:      Math.round(compute(0.50) * 100) / 100,
+    expected: Math.round(compute(0.70) * 100) / 100,
+    high:     Math.round(compute(0.85) * 100) / 100,
+  };
+}
+
+// =============================================================================
+// Public entry point — orchestrates fetch + compare + speedup
+// =============================================================================
+
+const COMPATIBLE_THRESHOLD = 0.999;        // 99.9% of sampled tokens map identically
+const PARTIAL_THRESHOLD    = 0.95;          // >=95% but <99.9%
+
+export async function checkCompatibility(targetId, draftId) {
+  if (!targetId || !draftId) {
+    return { code: "missing_input", params: { targetId, draftId }, errors: [] };
+  }
+  if (targetId.trim() === draftId.trim()) {
+    return { code: "identical_models", params: { targetId, draftId }, errors: [] };
+  }
+
+  const [tTok, dTok, tCfg, dCfg] = await Promise.all([
+    fetchTokenizer(targetId),
+    fetchTokenizer(draftId),
+    fetchConfig(targetId),
+    fetchConfig(draftId),
+  ]);
+
+  const errors = [];
+  if (!tTok.ok) errors.push({ side: "target", error: tTok.error, status: tTok.status });
+  if (!dTok.ok) errors.push({ side: "draft",  error: dTok.error, status: dTok.status });
+  if (!tTok.ok || !dTok.ok) {
+    return { code: "fetch_failed", params: { targetId, draftId }, errors };
+  }
+
+  const cmp = compareVocabs(tTok.data, dTok.data);
+
+  // Param ratio + speedup estimate
+  const tParams = paramsFromConfig(tCfg.ok ? tCfg.data : null) || parseParamHint(targetId);
+  const dParams = paramsFromConfig(dCfg.ok ? dCfg.data : null) || parseParamHint(draftId);
+  const speedup = speedupBand(tParams, dParams);
+
+  const sampledMatchRatio = cmp.sampled_total === 0
+    ? 0
+    : cmp.sampled_match_count / cmp.sampled_total;
+
+  let code;
+  if (!cmp.type_match) {
+    code = "type_mismatch";
+  } else if (!cmp.vocab_size_match) {
+    code = "vocab_size_mismatch";
+  } else if (sampledMatchRatio >= COMPATIBLE_THRESHOLD) {
+    code = cmp.special_tokens_diff.length || cmp.added_tokens_diff.length
+      ? "compatible_with_caveats"
+      : "compatible";
+  } else if (sampledMatchRatio >= PARTIAL_THRESHOLD) {
+    code = "partial_compatible";
+  } else {
+    code = "incompatible";
+  }
+
+  return {
+    code,
+    params: {
+      targetId, draftId,
+      ...cmp,
+      sampled_match_ratio: Math.round(sampledMatchRatio * 10000) / 10000,
+      target_params: tParams,
+      draft_params: dParams,
+      param_ratio: speedup?.ratio ?? null,
+      speedup_low:      speedup?.low ?? null,
+      speedup_expected: speedup?.expected ?? null,
+      speedup_high:     speedup?.high ?? null,
+      target_source: tTok.source,
+      draft_source: dTok.source,
+    },
+    errors,
+  };
+}