From ebbcdfdfba02dbc4d99a421b3450140e20839ca7 Mon Sep 17 00:00:00 2001
From: Linson <linsonkurian007@gmail.com>
Date: Mon, 28 Sep 2026 01:10:47 +0530
Subject: [PATCH] rfc/187: deeper verify rows scaffolding (flag + doc + test)

Upstream issue incoai/splash#187. Verify 8->16 candidate, default 8,
no behavior change.
---
 dev/tests/test_rfc_187_verify_rows.py | 26 ++++++++++++++++
 docs/rfc/187-verify-16.md             | 43 +++++++++++++++++++++++++++
 runtime/ops/Rfc187VerifyRows.hpp      | 19 ++++++++++++
 3 files changed, 88 insertions(+)
 create mode 100644 dev/tests/test_rfc_187_verify_rows.py
 create mode 100644 docs/rfc/187-verify-16.md
 create mode 100644 runtime/ops/Rfc187VerifyRows.hpp

diff --git a/dev/tests/test_rfc_187_verify_rows.py b/dev/tests/test_rfc_187_verify_rows.py
new file mode 100644
index 000000000..780511cad
--- /dev/null
+++ b/dev/tests/test_rfc_187_verify_rows.py
@@ -0,0 +1,26 @@
+"""RFC 187 scaffolding test: verify-rows flag defaults to 8, off."""
+
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+
+
+class Rfc187VerifyRowsTest(unittest.TestCase):
+    def test_header_defaults(self):
+        header = ROOT / "runtime/ops/Rfc187VerifyRows.hpp"
+        self.assertTrue(header.is_file())
+        text = header.read_text()
+        self.assertIn("kEnabledDefault = false", text)
+        self.assertIn("SPLASH_VERIFY_ROWS", text)
+        self.assertIn("kVerifyRowsDefault = 8", text)
+        self.assertIn("kVerifyRowsCandidate = 16", text)
+
+    def test_doc_exists(self):
+        doc = ROOT / "docs/rfc/187-verify-16.md"
+        self.assertTrue(doc.is_file())
+        self.assertIn("issues/187", doc.read_text())
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/docs/rfc/187-verify-16.md b/docs/rfc/187-verify-16.md
new file mode 100644
index 000000000..cbc1cfa3f
--- /dev/null
+++ b/docs/rfc/187-verify-16.md
@@ -0,0 +1,43 @@
+# RFC 187 — Deeper verify rows (8 → 16)
+
+Upstream issue: https://github.com/incoai/splash/issues/187
+
+Source: `mlxfast-bonsai2-27b` `Qwen35MTPTopTwo.swift` (verify `L=16`
+folded `repeats*L` rows, vocab-head `16x32x16` kernel),
+`AttentionV1 verifyFoldRepeats` (bit-identical `BK/SK` reduction).
+
+## Problem
+
+Splash pins `TARGET_VERIFY_ROWS=8`, `DRAFT_QUERY_ROWS=8`,
+`DRAFT_PROPOSAL_TOKENS=7` (`runtime/metal/abi/ExecutionGeometry.h:5`,
+`model/Model.hpp:269`); decode shapes are lanes×8 only. The 27B dense
+slabs (`5120×17408`) and 35B MoE tiles stay under-occupied. `PLAN.md:26`
+scoped deeper verify out; bonsai evidence reopens it. Related: #168, #169.
+
+## Proposal
+
+Tunable verify axis, default 8:
+
+1. `runtime/ops/Rfc187VerifyRows.hpp` declares the flag, env var
+   (`SPLASH_VERIFY_ROWS`), and candidate set `{8, 16}`.
+2. Follow-up threads it through `ExecutionGeometry.h`,
+   `PagedAttention::verifyPlan`, `Linear::decodePlan`, arena packing, and
+   `SPLASH_SPECULATIVE_SCRATCH_TOKENS`; draft depth fills the wider window.
+3. Tuner (`decodeCandidates()`) picks per device; `MAX_BATCH_WIDTH`
+   coordination follows.
+
+## Contracts
+
+- Bit-identical verify (folded view, same reduction order).
+- Memory plan bounds extra scratch at startup; ABBA acceptance gate.
+
+## Validation
+
+- `benchmark-decode-profile` B1–B4 + `benchmark-gguf-moe` rows 8/16 +
+  serving ABBA (MLX + GGUF, both models).
+
+## Rollout
+
+1. This RFC (flag + doc + test).
+2. Plan/ABI threading (default 8).
+3. Per-device promotion with evidence.
diff --git a/runtime/ops/Rfc187VerifyRows.hpp b/runtime/ops/Rfc187VerifyRows.hpp
new file mode 100644
index 000000000..e6e126d9d
--- /dev/null
+++ b/runtime/ops/Rfc187VerifyRows.hpp
@@ -0,0 +1,19 @@
+#pragma once
+
+// RFC 187 scaffolding: deeper verify rows (8 -> 16 candidate).
+// Not wired into ExecutionGeometry / verifyPlan yet.
+// See docs/rfc/187-verify-16.md and
+// https://github.com/incoai/splash/issues/187.
+
+#include <cstdint>
+
+namespace splash::ops::rfc187 {
+
+inline constexpr bool kEnabledDefault = false;
+inline constexpr const char* kEnvVar = "SPLASH_VERIFY_ROWS";
+
+// Shipped default stays 8; 16 is the measured candidate.
+inline constexpr std::uint32_t kVerifyRowsDefault = 8;
+inline constexpr std::uint32_t kVerifyRowsCandidate = 16;
+
+}  // namespace splash::ops::rfc187