fix(mlx-fused): long-decode degeneration past RotatingKVCache wrap + correct quality gate

[FluffyAIcode]

Summary

Fixes the long-decode degeneration in the Mac (MLX) fused spec-decode engine, where long answers (>~1024 tokens) collapsed into a runaway repeat (由于由于…). The root cause was found via a hypothesis-driven debug loop with runtime evidence on the Mac M4 — and the initial hypothesis was disproven, which also exposed a false-positive quality gate that this PR corrects.

Root cause (confirmed on Mac M4, prompt 请详细解释POW的工作原理)

• The decode cache is the model's native hybrid cache: sliding layers are RotatingKVCache (max_size≈1024), full layers are KVCache. The S5 --window-size 64 only feeds the analytical memory math; it does not bound the decode cache.
• At 128 and 800 tokens the fused output is coherent; the bug only appears past the ring wrap (offset ≥ max_size, gen≈1017).
• Once the ring wraps, mlx_lm.trim_prompt_cache is all-or-nothing and refuses (a rotating layer is is_trimmable only while offset < max_size). The fused speculative loop's rejected-draft rollback then silently fails (15 trim short:true events), so cache.offset runs +8 ahead of committed past_len on every post-wrap block → RoPE/causal misalignment → logit corruption → collapse.
• Decisive A/B: a native-greedy control on the same prompt stayed fully coherent past the wrap (clean termination at gen 1247), proving the model handles >1024 fine and the fused engine was at fault.

The fix (correctness-first)

_sliding_ring_would_wrap() + if wrap_l1: L = 1 in fused_specdecode_generate: detect the impending wrap and commit single-token blocks past it. With L=1 the bonus token is always accepted (it is argmax(next_token_logits)), so there is never a rejected tail to trim and offset stays == past_len. Cost: the speculative speedup is forgone past max_size (a sound wrapped-ring rollback for perf is noted as optional follow-up).

Validation (re-run, 1300 tokens, Mac M4)

signal	before	after
trim short:true events	15	0
post-wrap offset desync	76/76 blocks	0/225
post-wrap max cyc_frac	1.0 (collapse)	0.158
fused final text	由于由于… runaway	coherent, clean stop @ gen 1241 (matches native control)

kakeya_mlx_wrap_degeneration_fix.txt

Quality-gate correction (k3_report_gate.py)

The runtime evidence disproved the RESTORATION_COVERAGE theory ("restoration covers only ≤ window decode tokens"): a 1300-token run with 332 evicted-unrestored positions stayed coherent once the trim-desync was fixed. So "tokens > window" and even "evicted > 0" are not degeneration signals — the old rule was a pure false-positive (it would fail every coherent answer > 64 tokens).

• Remove the RESTORATION_COVERAGE rule.
• Add _has_runaway_substring so OUTPUT_DEGENERATE catches the newline-free 由于由于… collapse the line-based detector missed; conservative (≥8× tiled short unit) so templated 矿工 A/B/C enumerations do not false-fire.
• Gate module stays at 100% coverage.

Skill doc — reusable debugging template

Added the whole investigation to docs/kakeyainferenceenginebuildskill.md as a worked case-study template (§7): reproduce at increasing scale → add a native-greedy A/B control → instrument the indicated mechanism → fix correctness-first → re-validate, plus two generalizable lessons (runtime evidence overrides plausible hypotheses; gate on observed outcomes, not theorized proxies).

Changes

• inference_engine/backends/mlx/fused_specdecode.py: _sliding_ring_would_wrap + single-token commit past the ring wrap (uses getattr(adapter, "_cache", None)).
• inference_engine/bench/k3_report_gate.py: drop disproven RESTORATION_COVERAGE; add char-level runaway detector to OUTPUT_DEGENERATE.
• scripts/research/k3_integrated_niah_eval_mac.py: keep --chat-native-ref as a permanent A/B coherence control (now captures native text); Phase-1 KDBG instrumentation removed.
• inference_engine/bridge/manifest.py: mlx-kakeya-degen-probe repurposed as a long-decode regression guard.
• Tests: unit-cover _sliding_ring_would_wrap, _has_runaway_substring, and the corrected gate.
• Docs: kakeyainferenceenginebuildskill.md §5 row + §7 case-study template; kakeya-autonomous-iteration-and-self-correction.md confirmed root cause + "verify, don't trust the comment" lesson.

Testing

• ✅ pytest tests/inference_engine/bench/test_k3_report_gate.py (50 passed, gate 100% coverage)
• ✅ pytest tests/backends/mlx/test_fused_specdecode.py -k wrap (new helper tests)
• ✅ pytest tests/inference_engine/bridge/test_manifest.py (31 passed)
• ✅ Mac M4 1300-token validation run (table above)
• ⚠️ 4 tests in test_fused_specdecode.py (test_fused_loop_*, test_adapter_prefill_forward_commit) fail identically on origin/main — pre-existing stale fakes/expectations in the aux-capture path, unrelated to this fix.

_{To show artifacts inline, enable in settings.}