FluffyAIcode
diff --git a/‎docs/adr/0015-kakeya-attention-and-engine-substrate.md‎
Lines changed: 35 additions & 0 deletions b/‎docs/adr/0015-kakeya-attention-and-engine-substrate.md‎
Lines changed: 35 additions & 0 deletions
diff --git a/‎inference_engine/bridge/manifest.py‎
Lines changed: 71 additions & 0 deletions b/‎inference_engine/bridge/manifest.py‎
Lines changed: 71 additions & 0 deletions
diff --git a/‎scripts/chat_mlx_kakeya.py‎
Lines changed: 7 additions & 1 deletion b/‎scripts/chat_mlx_kakeya.py‎
Lines changed: 7 additions & 1 deletion
@@ -93,6 +93,41 @@ full-attention fraction:
   *only* way to bound memory at full recall — and vLLM, having no restoration,
   **must keep full KV and cannot match it**. This is the engine's target regime.
 
+## Mac (MLX) interactive engine — full verifier/proposer/f_θ pipeline, f_θ default-ON
+
+The Apple-Silicon interactive CLI (`scripts/research/k3_integrated_niah_eval_mac.py
+--chat`) runs the **full Kakeya engine** — gemma-4 verifier (MLX) + **DFlash
+proposer** (fused spec-decode) + **f_θ K/V restoration** + **S5 bounded KV** — not
+verifier-only. It reuses the validated `fused_specdecode_generate_mlx_trim`
+per-turn sequence; the NIAH evidence loop is untouched.
+
+- **f_θ runs by default in chat.** `--force-f-theta` is auto-enabled in `--chat`
+  unless the fast all-MLX path (`--all-mlx-drafter`, f_θ bypassed) is explicitly
+  chosen. It bypasses the S5 native-prefill short-circuit so f_θ **executes** each
+  turn: it projects the proposer's hidden states → verifier K/V for the **25
+  sliding layers** and injects them.
+- **gemma-4 caveat (honest).** On gemma-4 those restored sliding-layer K/V are
+  **recall-irrelevant** — the 5 exact full-attention layers carry recall (the "S5
+  free lunch"), so f_θ's output is effectively *discarded by the recall path*. We
+  still run f_θ by default so the **full verifier/proposer/f_θ pipeline is
+  exercised end-to-end**; on **full-attention models** the same f_θ path is
+  load-bearing (it is the only way to bound memory at full recall).
+- **Forensic — when f_θ stopped running.** f_θ was silently bypassed under
+  `--s5-exact-full-attn` on **2026-06-12** by the *"Optimize MLX adaptive S5
+  native smoke path"* commits (`b3a04d0` / `1f6e58c`), which made
+  `build_restoration` short-circuit to `{}` under S5; the same *"adaptive S5
+  native"* path also let the proposer go to `blocks=0` while keeping the fused
+  label — caught by the evidence gate (`0a6fb19`, *"enforce PR #109 review
+  constraints"*) which added `--force-fused-specdecode`. Both squashed into main
+  via #117. f_θ remained S5-bypassed until `--force-f-theta` (this ADR's change)
+  made it default-on in the interactive chat.
+- **Measured (Mac M4, via the git-bus bridge).** Both chat turns:
+  **`f_theta_ran=TRUE`** restoring the **25 sliding layers** + **proposer
+  `blocks=2/4`, `mean_accept_len=4.0/3.5`** + correct answers ("Paris"; "red,
+  yellow, and blue") + natural `<end_of_turn>` stop + bounded resident KV
+  (12–18 MB). Torch-bridge path is slow (~0.5–6 tok/s); the all-MLX path
+  (proposer-only) is the fast option.
+
 ## Feasibility probes so far (informed the design — NOT the product)
 
 These ran on the eager-transformers research bench; they validate correctness and
 
@@ -678,6 +678,77 @@ def _harness_preset(
             params={"max_new_tokens": ("int:max_new_tokens", "64")},
             validate_reports=False,
         ),
+        Preset(
+            name="mlx-kakeya-fused-chat-smoke",
+            description="Run gemma-4 on the FULL Kakeya fused engine (verifier + "
+                        "DFlash proposer + f_θ + S5 bounded KV) via the harness "
+                        "--chat --chat-scripted mode — NOT verifier-only. Verifies "
+                        "the proposer is live (blocks>0, mean_accept_len>0) AND the "
+                        "answer is correct AND KV is bounded, per turn. Writes a "
+                        "transcript JSON.",
+            command_templates=(
+                (
+                    "python3", "scripts/research/k3_integrated_niah_eval_mac.py",
+                    "--verifier-path", "${ENV:KAKEYA_MAC_VERIFIER_PATH}",
+                    "--drafter-id", "${ENV:KAKEYA_MAC_DRAFTER_ID}",
+                    "--f-theta-dir", "${ENV:KAKEYA_MAC_FTHETA_DIR}",
+                    "--s5-exact-full-attn", "--fused-specdecode",
+                    "--all-mlx-drafter", "--cuda-trim",
+                    "--sink-size", "4", "--window-size", "64",
+                    "--block-size", "{block_size}",
+                    "--max-new-tokens", "{max_new_tokens}",
+                    "--prefill-chunk-size", "512",
+                    "--chat",
+                    "--chat-scripted",
+                    "What is the capital of France? Answer in one short sentence."
+                    "||Name three primary colors.",
+                    "--output",
+                    "results/research/k3_mac_bridge_mlx_kakeya_fused_chat.json",
+                ),
+            ),
+            timeout_minutes=60,
+            params={
+                "max_new_tokens": ("int:max_new_tokens", "64"),
+                "block_size": ("int:block_size", "4"),
+            },
+            validate_reports=False,
+        ),
+        Preset(
+            name="mlx-kakeya-fused-chat-ftheta",
+            description="Like mlx-kakeya-fused-chat-smoke but on the TORCH drafter "
+                        "+ f_θ path with --force-f-theta: f_θ restoration ACTUALLY "
+                        "RUNS each turn (projects proposer hidden → verifier K/V, "
+                        "injected into the sliding layers) even though on gemma-4 "
+                        "those K/V are recall-irrelevant (the exact layers carry "
+                        "recall). Verifies the FULL verifier/proposer/f_θ pipeline: "
+                        "report shows f_theta_ran=true + blocks>0. (No "
+                        "--all-mlx-drafter; torch bridge path is slower.)",
+            command_templates=(
+                (
+                    "python3", "scripts/research/k3_integrated_niah_eval_mac.py",
+                    "--verifier-path", "${ENV:KAKEYA_MAC_VERIFIER_PATH}",
+                    "--drafter-id", "${ENV:KAKEYA_MAC_DRAFTER_ID}",
+                    "--f-theta-dir", "${ENV:KAKEYA_MAC_FTHETA_DIR}",
+                    "--s5-exact-full-attn", "--fused-specdecode",
+                    "--sink-size", "4", "--window-size", "64",
+                    "--block-size", "{block_size}",
+                    "--max-new-tokens", "{max_new_tokens}",
+                    "--prefill-chunk-size", "512",
+                    "--chat",
+                    "--chat-scripted",
+                    "What is the capital of France? Answer in one short sentence."
+                    "||Name three primary colors.",
+                    "--output",
+                    "results/research/k3_mac_bridge_mlx_kakeya_fused_chat_ftheta.json",
+                ),
+            ),
+            timeout_minutes=90,
+            params={
+                "max_new_tokens": ("int:max_new_tokens", "32"),
+                "block_size": ("int:block_size", "4"),
+            },
+            validate_reports=False,
+        ),
     )
 }
 
 
@@ -192,8 +192,14 @@ def _iter():
                 stop_reason = "loop"
                 break
         dt = max(time.time() - t0, 1e-9)
+        _txt = tok.decode(toks, skip_special_tokens=True)
+        # gemma-4 sometimes bleeds its reasoning channel after the answer; cut it.
+        for _cut in ("<|channel", "<channel", "\nthought", "\nthink"):
+            _i = _txt.find(_cut)
+            if _i > 0:
+                _txt = _txt[:_i]
         return {
-            "text": tok.decode(toks, skip_special_tokens=True),
+            "text": _txt.strip(),
             "n_tokens": len(toks),
             "stop_reason": stop_reason,
             "decode_tps": round(len(toks) / dt, 2),