Fix structural regressions

diff.txt

@@ -0,0 +1,296 @@
+commit cf83a1acd06e1a347cae033a7cb9fdeff8dfcd01
+Author: YoussefReda9 <youssefreda9004@gmail.com>
+Date:   Tue Jun 30 04:36:40 2026 +0300
+
+    Fix: 10 critical NLP logic bugs in grammar, spelling, and punctuation to prevent false positives
+
+diff --git a/src/nlp/spelling/araspell_rules.py b/src/nlp/spelling/araspell_rules.py
+index 634f134..0102cae 100644
+--- a/src/nlp/spelling/araspell_rules.py
++++ b/src/nlp/spelling/araspell_rules.py
+@@ -129,14 +129,9 @@ class AraSpellPostProcessor:
+     @staticmethod
+     def remove_duplicate_words(text: str) -> str:
+         """Remove consecutive duplicate words. e.g. كتاب كتاب → كتاب"""
+-        words = text.split()
+-        if len(words) < 2:
+-            return text
+-        result = [words[0]]
+-        for i in range(1, len(words)):
+-            if words[i] != words[i-1]:
+-                result.append(words[i])
+-        return ' '.join(result)
++        # Bug 2.11: Destroys rhetorical repetition (التوكيد اللفظي) like "صفا صفا".
++        # Disabled as it destroys valid Arabic phrases.
++        return text
+     
+     @staticmethod
+     def normalize_spaces(text: str) -> str:
+@@ -337,11 +332,11 @@ class AraSpellPostProcessor:
+             if any(word.endswith(e) for e in PROTECTED_ENDINGS):
+                 result.append(word)
+                 continue
+-            if word in PROTECTED_HA_WORDS:
++            if word in PROTECTED_HA_WORDS or word in ['هذه', 'هاته']:
+                 result.append(word)
+                 continue
+             if len(word) >= 3 and word.endswith('ه'):
+-                if word[-2] in AraSpellPostProcessor.ARABIC_CONSONANTS:
++                if word[-2] in AraSpellPostProcessor.ARABIC_CONSONANTS or word[-2] in 'اويءؤئ':
+                     candidate_with_ta = word[:-1] + 'ة'
+                     # Default: prefer ة (correct Arabic orthography for feminine nouns)
+                     if vocab_manager:
+@@ -389,11 +384,8 @@ class AraSpellPostProcessor:
+             if i + 1 < len(words):
+                 next_word = words[i + 1]
+                 # Bug 2.11: Destroys Badal structures (الأستاذ أستاذ -> الأستاذ)
+-                if word == next_word: # Only remove exact duplicates, not normalized duplicates
+-                    keep = next_word if next_word.startswith('ال') and not word.startswith('ال') else word
+-                    result.append(keep)
+-                    i += 2
+-                    continue
++                # and Rhetorical Repetition (التوكيد اللفظي)
++                # Removed the aggressive duplicate word deletion.
+             result.append(word)
+             i += 1
+         return ' '.join(result)
+@@ -1177,7 +1169,15 @@ class ArabicSpellChecker:
+             logger.info("[MLM/CONTEXTUAL] Disabled by configuration (use_contextual=False)")
+ 
+     def _fix_repeated_end_chars(self, text: str) -> str:
+-        text = re.sub(r'([ا-ي])\1+\b', r'\1', text)
++        # Exclude 'ي' if it is preceded by a Kasra or another Yaa (e.g., يحيي)
++        def _replace_repeated(m):
++            w = m.group(0)
++            char = m.group(2)
++            if w.endswith('يي'):
++                if self.vocab_manager and self.vocab_manager.is_iv(w):
++                    return w
++            return m.group(1) + char
++        text = re.sub(r'\b([^\s]+?)([\u0621-\u064A])\2+\b', _replace_repeated, text)
+         return text
+     
+     def _fix_merged_with_errors(self, text: str) -> str:
+
+commit ee5e50414a8f53b71d5fa3d4f864c812ee835567
+Author: YoussefReda9 <youssefreda9004@gmail.com>
+Date:   Tue Jun 30 04:11:41 2026 +0300
+
+    Fix 30 NLP edge cases in Grammar, Spelling, and Punctuation (Phase 10 results and Extension UI improvements)
+
+diff --git a/src/nlp/spelling/araspell_rules.py b/src/nlp/spelling/araspell_rules.py
+index 39d02b7..634f134 100644
+--- a/src/nlp/spelling/araspell_rules.py
++++ b/src/nlp/spelling/araspell_rules.py
+@@ -154,17 +154,9 @@ class AraSpellPostProcessor:
+     @staticmethod
+     def remove_word_repetition_with_wa(text: str) -> str:
+         """Remove word و word → word"""
+-        words = text.split()
+-        result = []
+-        i = 0
+-        while i < len(words):
+-            if i + 2 < len(words) and words[i] == words[i+2] and words[i+1] == 'و':
+-                result.append(words[i])
+-                i += 3
+-            else:
+-                result.append(words[i])
+-                i += 1
+-        return ' '.join(result)
++        # Bug 2.9: This deletes valid rhetorical repetition (التوكيد اللفظي) like "صنفا وصنفا"
++        # Disabled as it is highly destructive to valid Arabic.
++        return text
+     
+     # --- Hamza & Ta Marbuta Handling ---
+     
+@@ -181,7 +173,7 @@ class AraSpellPostProcessor:
+         'اذا': 'إذا', 'اذ': 'إذ',
+         'اي': 'أي', 'اين': 'أين',
+         'او': 'أو',
+-        'اما': 'أما',
++        
+         'ان': 'أن', 'انه': 'أنه', 'انها': 'أنها', 'انهم': 'أنهم',
+         'اخر': 'آخر', 'اخرى': 'أخرى',
+         'الان': 'الآن',
+@@ -201,9 +193,9 @@ class AraSpellPostProcessor:
+         'اهل': 'أهل',
+         'اطفال': 'أطفال',
+         'اصدقاء': 'أصدقاء', 'اصدقائي': 'أصدقائي',
+-        'اعتقد': 'أعتقد', 'اريد': 'أريد', 'احب': 'أحب',
+-        'اعرف': 'أعرف', 'اعلم': 'أعلم',
+-        'اخذ': 'أخذ', 'اكل': 'أكل',
++        'اريد': 'أريد', 'احب': 'أحب',
++        'اعلم': 'أعلم',
++        'اكل': 'أكل',
+         'الايام': 'الأيام',
+         'الاطفال': 'الأطفال',
+         'الاسعار': 'الأسعار',
+@@ -243,10 +235,8 @@ class AraSpellPostProcessor:
+         'ادارة': 'إدارة', 'ادارية': 'إدارية',
+         'اعلام': 'إعلام', 'اعلامي': 'إعلامي',
+         'احتمال': 'احتمال', 'احتفال': 'احتفال',
+-        'ازور': 'أزور', 'اذهب': 'أذهب', 'اكتب': 'أكتب',
+         'اقرا': 'أقرأ', 'اقرأ': 'أقرأ',
+-        'اعمل': 'أعمل', 'ادرس': 'أدرس',
+-        'اشتري': 'أشتري', 'اسافر': 'أسافر',
++        'اسافر': 'أسافر',
+         'احبه': 'أحبه',
+         'مسؤول': 'مسؤول', 'مسؤولية': 'مسؤولية',
+         'رؤية': 'رؤية', 'رؤيا': 'رؤيا',
+@@ -259,7 +249,7 @@ class AraSpellPostProcessor:
+         'مصطفي': 'مصطفى', 'موسي': 'موسى', 'عيسي': 'عيسى',
+         'هدي': 'هدى', 'بني': 'بنى',
+         'معني': 'معنى', 'مبني': 'مبنى',
+-        'علي': 'على',  # Common alif maqsura confusion
++        
+         'الي': 'إلى',
+         # FIX-47: Verb+pronoun hamza entries (احبه→أحبه)
+         'احبه': 'أحبه', 'احبها': 'أحبها', 'احبك': 'أحبك',
+@@ -280,16 +270,9 @@ class AraSpellPostProcessor:
+     @staticmethod
+     def fix_hamza_conservative(text: str) -> str:
+         """Conservative Hamza normalization — only at word END, not middle."""
+-        words = text.split()
+-        result = []
+-        for word in words:
+-            if len(word) >= 3:
+-                if word.endswith('أ'):
+-                    word = word[:-1] + 'ا'
+-                if word.endswith('إ'):
+-                    word = word[:-1] + 'ا'
+-            result.append(word)
+-        return ' '.join(result)
++        # Bug 2.5: Blindly changing أ at the end of word to ا corrupts valid orthography (قرأ -> قرا)
++        # Disabled as it is highly destructive.
++        return text
+     
+     # Attached prefixes that can precede hamza-whitelist words
+     # Ordered longest-first so وال is tried before و
+@@ -364,8 +347,12 @@ class AraSpellPostProcessor:
+                     if vocab_manager:
+                         ta_iv = vocab_manager.is_iv(candidate_with_ta)
+                         ha_iv = vocab_manager.is_iv(word)
+-                        if ta_iv:
+-                            # Always prefer ة when it's a valid word
++                        if ha_iv and ta_iv:
++                            # Bug 2.2: Do not prefer ة if ه is also valid (possessive pronoun)
++                            result.append(word)
++                            continue
++                        elif ta_iv:
++                            # Prefer ة when ONLY the ة form is valid
+                             result.append(candidate_with_ta)
+                             continue
+                         elif ha_iv:
+@@ -401,7 +388,8 @@ class AraSpellPostProcessor:
+                     word = word[:-1]
+             if i + 1 < len(words):
+                 next_word = words[i + 1]
+-                if normalize_word(word) == normalize_word(next_word):
++                # Bug 2.11: Destroys Badal structures (الأستاذ أستاذ -> الأستاذ)
++                if word == next_word: # Only remove exact duplicates, not normalized duplicates
+                     keep = next_word if next_word.startswith('ال') and not word.startswith('ال') else word
+                     result.append(keep)
+                     i += 2
+@@ -454,18 +442,8 @@ class AraSpellPostProcessor:
+                     result.append(word + next_word)
+                     i += 2
+                     continue
+-                if len(word) >= 2 and len(next_word) >= 2 and word[-1] == next_word[0]:
+-                    if not (word in STANDALONE_WORDS and next_word in STANDALONE_WORDS):
+-                        result.append(word[:-1] + next_word)
+-                        i += 2
+-                        continue
+-                if (2 <= len(word) <= 4 and 
+-                    1 <= len(next_word) <= 2 and
+-                    3 <= len(word) + len(next_word) <= 7):
+-                    if not (word in STANDALONE_WORDS and next_word in STANDALONE_WORDS):
+-                        result.append(word + next_word)
+-                        i += 2
+-                        continue
++                # Bug 2.3: Destructive word merging (يوم مشمس -> يومشمس)
++                # Removed generic boundary letter merging.
+             result.append(word)
+             i += 1
+         return ' '.join(result)
+@@ -779,15 +757,7 @@ class WordAligner:
+         if in_iv and not out_iv:
+             return input_word
+         if in_iv and out_iv:
+-            # Fix S1: When only difference is ه→ة at word end, prefer ة
+-            # (correct Arabic orthography — ة is the standard feminine ending)
+-            if (input_word.endswith('ه') and output_word.endswith('ة')
+-                    and input_word[:-1] == output_word[:-1]):
+-                return output_word
+-            # Fix S1: Also handle ة→ه (don't regress a correct ة to ه)
+-            if (input_word.endswith('ة') and output_word.endswith('ه')
+-                    and input_word[:-1] == output_word[:-1]):
+-                return input_word
++            # Bug 2.2: Do not prefer ة over ه if both are IV, because ه is often a valid possessive pronoun.
+             return input_word 
+         if len(input_word) == len(output_word) and len(input_word) >= 3:
+             for i in range(len(input_word)):
+@@ -1211,51 +1181,23 @@ class ArabicSpellChecker:
+         return text
+     
+     def _fix_merged_with_errors(self, text: str) -> str:
+-        text = re.sub(r'ال([ا-ي])\1+([ا-ي]{2,})', r'ال\2', text)
++        # Bug 2.10: This regex was r'ال\2', deleting all instances of the character
++        text = re.sub(r'ال([ا-ي])\1+([ا-ي]{2,})', r'ال\1\2', text)
+         text = re.sub(r'\b([ا-ي]{3,})([ا-ي])\2+\b', r'\1\2', text)
+         return text
+ 
+     def _split_merged_words_linguistic(self, text: str) -> str:
+-        text = re.sub(
+-            r'\b(في|من|إلى|الى|حتى|منذ|خلال|بعد|قبل)(ال)?([ا-ي]{3,})',
+-            r'\1 \2\3', text
+-        )
+-        text = re.sub(r'\b(كل)([ا-ي]{3,})', r'\1 \2', text)
+-        text = re.sub(r'([ا-ي]{3,})(ال)([ا-ي]{3,})', r'\1 \2\3', text)
+-        text = re.sub(r'\b([بلك])(ال)?([ا-ي]{3,})', r'\1 \2\3', text)
+-        text = re.sub(r'([ا-ي]{4,})(عليكم|عليك|عليه|عليها)', r'\1 \2', text)
+-        text = re.sub(r'([ا-ي]{3,})(على|عن)([ا-ي]{3,})', r'\1 \2 \3', text)
++        # Bug 2.7: Catastrophic preposition splitting (e.g. منطق -> من طق)
++        # Disabled generic regex splitting as it is highly destructive to valid vocabulary.
+         return text
+     
+     def _split_long_words_heuristic(self, text: str, max_length: int = 15) -> str:
+-        words = text.split()
+-        result = []
+-        for word in words:
+-            if len(word) <= max_length:
+-                result.append(word)
+-                continue
+-            if 'ال' in word[2:]:
+-                parts = word.split('ال', 1)
+-                if len(parts[0]) >= 2 and len(parts[1]) >= 3:
+-                    result.extend([parts[0], 'ال' + parts[1]])
+-                    continue
+-            if len(word) >= 8:
+-                split_found = False
+-                for split_pos in [2, 3]:
+-                    prefix = word[:split_pos]
+-                    suffix = word[split_pos:]
+-                    if prefix in ['في', 'من', 'على', 'عن', 'مع', 'كل', 'ب', 'ل', 'ك']:
+-                        result.extend([prefix, suffix])
+-                        split_found = True
+-                        break
+-                if not split_found:
+-                    result.append(word)
+-            else:
+-                result.append(word)
+-        return ' '.join(result)
++        # Bug 2.8: Overzealous long word splitting (e.g. فيتامينات -> في تامينات)
++        # Disabled as it creates more errors than it fixes.
++        return text
+     
+     def _normalize_tanween_patterns(self, text: str) -> str:
+-        text = re.sub(r'([ا-ي]{2,})أ\b', r'\1اً', text)
++        # Bug 2.6: Blind replacement of trailing أ with اً corrupts verbs and nominative cases (قرأ -> قراً)
+         text = re.sub(r'\s+أ\s+', ' ', text)
+         text = re.sub(r'\b([بلك])\s+([ا-ي])', r'\1\2', text)
+         return text
+@@ -1661,3 +1603,4 @@ class ArabicSpellChecker:
+             result = ' '.join(res_words_list)
+ 
+         return result
++

diff_gram.txt

@@ -0,0 +1,311 @@
+diff --git a/src/nlp/grammar/grammar_rules.py b/src/nlp/grammar/grammar_rules.py
+index 141fb50..1f80154 100644
+--- a/src/nlp/grammar/grammar_rules.py
++++ b/src/nlp/grammar/grammar_rules.py
+@@ -77,31 +77,8 @@ class ArabicGrammarGuard:
+         return " ".join(corrected_tokens)
+ 
+     def smart_asmaa_khamsa_fix(self, text):
+-        tokens = simple_word_tokenize(text)
+-        disambig_tokens = self.mle.disambiguate(tokens)
+-        corrected_tokens = []
+-        verb_seen = False
+-
+-        for i, token_info in enumerate(disambig_tokens):
+-            word = tokens[i]
+-
+-            pos_tag = token_info.analyses[0].analysis.get('pos', 'unknown') if token_info.analyses else 'unknown'
+-
+-            if pos_tag == 'verb':
+-                verb_seen = True
+-                corrected_tokens.append(word)
+-                continue
+-
+-            is_asmaa = any(word.startswith(root) or word.startswith('أ' + root[1:]) for root in self.asmaa_khamsa_roots if len(root)>1)
+-
+-            if is_asmaa and len(word) >= 3:
+-                if verb_seen:
+-                    word = word.replace('ا', 'و').replace('ي', 'و')
+-                    verb_seen = False
+-
+-            corrected_tokens.append(word)
+-
+-        return " ".join(corrected_tokens)
++        # Bug 1.1: Disabled blind replacement of ا and ي with و as it corrupts object position
++        return text
+ 
+     def _apply_jazm_to_verb(self, word, token_info):
+         # 1. Handle Af'al Khamsa using camel_tools analysis
+@@ -182,7 +159,7 @@ class ArabicGrammarGuard:
+         disambig_tokens = self.mle.disambiguate(tokens)
+ 
+         nasb_particles = ['أن', 'ان', 'لن', 'كي', 'لكي', 'حتى', 'حتي', 'إذن', 'اذا']
+-        jazm_particles = ['لم', 'لما', 'لا']
++        jazm_particles = ['لم', 'لما']
+ 
+         corrected_tokens = []
+ 
+@@ -196,12 +173,16 @@ class ArabicGrammarGuard:
+ 
+             if i > 0:
+                 prev_word = tokens[i-1]
+-                if prev_word in nasb_particles or word.startswith('ل'):
++                if prev_word in nasb_particles:
+                     is_nasb_context = True
+-                if prev_word in jazm_particles or word.startswith('ل') or word.startswith('ول'):
++                if prev_word in jazm_particles:
+                     is_jazm_context = True
++                # Lam Al-Ta'leel / Lam Al-Amr logic was flawed (triggering for ANY word starting with ل)
++                # Ensure it only applies to actual verbs starting with 'لي' or 'لت' etc.
++                if (word.startswith('ل') or word.startswith('ول') or word.startswith('فل')) and len(word) >= 4 and word[1] in ['ي', 'ت', 'ن', 'أ']:
++                    is_nasb_context = True
+ 
+-            is_present_tense = word.startswith('ي') or word.startswith('ت') or word.startswith('ن') or word.startswith('أ')
++            is_present_tense = word.startswith('ي') or word.startswith('ت') or word.startswith('ن') or word.startswith('أ') or word.startswith('لي') or word.startswith('لت') or word.startswith('ولي') or word.startswith('فلي')
+             if (pos_tag == 'verb' or is_present_tense) and (is_nasb_context or is_jazm_context):
+                 if is_jazm_context:
+                     word = self._apply_jazm_to_verb(word, token_info)
+@@ -223,9 +204,14 @@ class ArabicGrammarGuard:
+         # When a feminine noun is followed by a masculine adjective, add ة
+         # e.g. السيارة جميل → السيارة جميلة
+         words = text.split()
++        KNOWN_MASC_TA_MARBUTA = {'خليفة', 'أسامة', 'حمزة', 'طلحة', 'معاوية', 'عبيدة', 'قضاة', 'دعاة', 'رماة', 'حماة'}
+         for i in range(len(words) - 1):
+             noun = words[i]
+             adj = words[i + 1]
++            # Strip prefixes like 'ال' to check root
++            clean_noun = noun[2:] if noun.startswith('ال') else noun
++            if clean_noun in KNOWN_MASC_TA_MARBUTA:
++                continue
+             is_fem_noun = (noun in KNOWN_FEMININE_NOUNS or
+                           (noun.endswith('ة') and len(noun) >= 3) or
+                           (noun.startswith('ال') and noun.endswith('ة')))
+@@ -250,6 +236,9 @@ class ArabicGrammarGuard:
+         'النيران', 'نيران', 'الألوان', 'ألوان', 'البلدان', 'بلدان',
+         'الأوطان', 'أوطان', 'الأبدان', 'أبدان', 'الأركان', 'أركان',
+         'الفرسان', 'فرسان', 'الغزلان', 'غزلان', 'القضبان', 'قضبان',
++        'فرعون', 'قانون', 'القانون', 'كانون', 'قارون', 'طاعون',
++        'عربون', 'هارون', 'زيدون', 'معجون', 'مجنون', 'زيتون', 'صابون',
++        'الفرعون', 'قوانين'
+     }
+ 
+     def fix_prepositions_advanced(self, text):
+@@ -261,31 +250,36 @@ class ArabicGrammarGuard:
+             stem = m.group(2)
+             suffix = m.group(3)
+             full_word = stem + suffix
+-            # Skip words in blocklist (root nouns, not duals)
+-            if full_word in self._PREP_BLOCKLIST:
+-                return m.group(0)  # return unchanged
+-            # Skip ال-prefixed words ending in ان — almost always root nouns
+-            if stem.startswith('ال') and suffix == 'ان':
+-                return m.group(0)  # return unchanged
+-            return f'{prep} {stem}ين'
+-
+-        text = re.sub(r'\b([وف]?(?:في|من|إلى|على|عن|حتى))\s+([أ-ي]{4,})(ون|ان)\b', _prep_replace, text)
++            
++            # Use camel-tools disambiguation to determine if it's really a dual/plural
++            tokens = simple_word_tokenize(full_word)
++            disambig_tokens = self.mle.disambiguate(tokens)
++            if disambig_tokens and disambig_tokens[0].analyses:
++                num = disambig_tokens[0].analyses[0].analysis.get('num', 's')
++                # Only apply ين suffix if the word is actually Dual or Plural
++                if num in ['d', 'p']:
++                    return f'{prep} {stem}ين'
++            return m.group(0)
++
++        text = re.sub(r'\b([وف]?(?:في|من|إلى|على|عن|حتى))\s+([أ-ي]{3,})(ون|ان)\b', _prep_replace, text)
+ 
+         # (وبالمبرمجون) -> (وبالمبرمجين)
+         # FIX-33b: Same blocklist protection as first regex
+         def _attached_prep_replace(m):
+-            prefix = m.group(1)  # وب، ب، فب، ول، ل، etc.
++            prefix = m.group(1)
+             stem = m.group(2)
+             suffix = m.group(3)
+-            full_word = 'ال' + stem + suffix  # reconstruct with ال for blocklist check
+-            if full_word in self._PREP_BLOCKLIST:
+-                return m.group(0)
+-            # Words ending in ان with 4+ char stems are almost always root nouns
+-            if suffix == 'ان':
+-                return m.group(0)
+-            return f'{prefix}ال{stem}ين'
++            full_word = 'ال' + stem + suffix
++            
++            tokens = simple_word_tokenize(full_word)
++            disambig_tokens = self.mle.disambiguate(tokens)
++            if disambig_tokens and disambig_tokens[0].analyses:
++                num = disambig_tokens[0].analyses[0].analysis.get('num', 's')
++                if num in ['d', 'p']:
++                    return f'{prefix}ال{stem}ين'
++            return m.group(0)
+ 
+-        text = re.sub(r'\b([وف]?[بلكف])ال([أ-ي]{4,})(ون|ان)\b', _attached_prep_replace, text)
++        text = re.sub(r'\b([وف]?[بلكف])ال([أ-ي]{3,})(ون|ان)\b', _attached_prep_replace, text)
+ 
+         # (ولمهندسون) -> (ولمهندسين)
+         # FIX-33b: Same protection — reconstruct full word for blocklist
+@@ -321,8 +315,8 @@ class ArabicGrammarGuard:
+                 if word == 'ذو': return 'ذا'
+                 if word == 'فو': return 'فا'
+                 if word == 'حمو': return 'حما'
+-                if word.endswith('ون'): return word[:-2] + 'ين'
+-                if word.endswith('ان'): return word[:-2] + 'ين'
++                if word.endswith('ون') and num == 'p' and word not in ('قانون', 'فرعون', 'كانون', 'معجون', 'طاعون', 'مجنون'): return word[:-2] + 'ين'
++                if word.endswith('ان') and num == 'd' and word not in ('امتحان', 'إنسان', 'ميدان', 'سلطان', 'شيطان'): return word[:-2] + 'ين'
+             elif target_case == 'n': # Marfoo'
+                 if word in ('أبا', 'أبي'): return 'أبو'
+                 if word in ('أخا', 'أخي'): return 'أخو'
+@@ -481,30 +475,18 @@ class ArabicGrammarGuard:
+                 # FIX-08: Expanded feminine plurals
+                 'المهندسات', 'مهندسات', 'الطبيبات', 'طبيبات',
+                 'اللاعبات', 'لاعبات', 'الممثلات', 'ممثلات',
+-                'الشركات', 'شركات', 'الجامعات', 'جامعات',
+-                'المدارس', 'مدارس', 'المستشفيات', 'مستشفيات',
+-                'الحكومات', 'حكومات', 'المنظمات', 'منظمات',
+-                'الطائرات', 'طائرات', 'السيارات', 'سيارات',
+             }
+ 
+-            if noun_word in KNOWN_PLURALS_MASC:
++            if noun_num == 'd':
++                pass # Dual noun, skip plural logic to prevent corruption
++            elif noun_word in KNOWN_PLURALS_MASC:
+                 is_plural_masc = True
+             elif noun_word in KNOWN_PLURALS_FEM:
+                 is_plural_fem = True
+-            elif noun_word.endswith('ون') or noun_word.endswith('ين'):
+-                # Sound masculine plural — but only if 4+ chars (avoid short words)
+-                if len(noun_word) >= 5:
+-                    is_plural_masc = True
+-            elif noun_word.endswith('ات') and len(noun_word) >= 5:
+-                is_plural_fem = True
+-            # FIX-08: Broken plural heuristic — common patterns
+-            elif noun_num == 'p':
+-                # Trust POS tagger when it says plural AND word is long enough
+-                if len(noun_word) >= 4:
+-                    if noun_gen == 'f':
+-                        is_plural_fem = True
+-                    else:
+-                        is_plural_masc = True
++            elif (noun_word.endswith('ون') or (noun_word.endswith('ين') and noun_num == 'p')) and len(noun_word) >= 5:
++                # Bug 1.14: Check noun_num == 'p' to prevent duals from triggering plural logic
++                is_plural_masc = True
++            # Bug 1.2: Disabled POS tagger heuristic for broken plurals and generic 'ات' ending because it forces 'ن' on non-human plurals
+             
+             is_singular_fem = False
+             if not is_plural_masc and not is_plural_fem:
+@@ -574,7 +556,8 @@ class ArabicGrammarGuard:
+             return word
+ 
+         # إن وأخواتها
+-        text = re.sub(r'\b(إن|أن|كأن|لكن|لعل|ليت|ان|كان)\s+(أبوك|ابوك|أخوك|اخوك|ذو|فوك)\b',
++        # Bug 1.13: removed كان from this regex because it caused كان أخوك -> كان أخاك
++        text = re.sub(r'\b(إن|أن|كأن|لكن|لعل|ليت|ان)\s+(أبوك|ابوك|أخوك|اخوك|ذو|فوك)\b',
+                       lambda m: f"{m.group(1)} {_add_hamza(m.group(2)).replace('و', 'ا')}", text)
+ 
+         # الأفعال المتعدية (Object position)
+@@ -596,19 +579,19 @@ class ArabicGrammarGuard:
+         
+         # FIX-PC010: Add targeted safe regex for Nasb/Jazm particles + verb
+         # Only match clear present tense verbs starting with ي/ت/ن/أ and ending in ون
+-        text = re.sub(r'\b(أن|ان|لن|كي|حتى|لم|لما)\s+([يتا][\u0600-\u06FF]{2,})ون\b',
++        text = re.sub(r'\b(أن|ان|لن|كي|حتى|لم|لما)\s+([يتاأن][\u0600-\u06FF]{2,})ون\b',
+                       r'\1 \2وا', text)
+ 
+         return text
+ 
+     def fix_conditional_sentences(self, text):
+-        conditional_particles = {'إن', 'ان', 'من', 'ما', 'متى', 'متي', 'مهما', 'أينما', 'حيثما', 'أيان', 'ايان', 'كيفما', 'أنى', 'اني'}
++        conditional_particles = {'إن', 'ان', 'متى', 'متي', 'مهما', 'أينما', 'حيثما', 'أيان', 'ايان', 'كيفما', 'أنى', 'اني'}
+         tokens = simple_word_tokenize(text)
+         disambig_tokens = self.mle.disambiguate(tokens)
+         corrected_tokens = list(tokens)
+         
+         # Lookahead for 2nd person context
+-        has_2nd_person_context = any(t.endswith('كم') or t.endswith('كمو') or t.startswith('ت') for t in tokens)
++        has_2nd_person_context = False
+         
+         in_cond = False
+         verbs_jazmed = 0
+@@ -634,10 +617,6 @@ class ArabicGrammarGuard:
+                 # Apply jazm using the comprehensive camel_tools helper
+                 word = self._apply_jazm_to_verb(word, token_info)
+                     
+-                # Fix pronoun mismatch if 2nd person context exists
+-                if has_2nd_person_context and word.startswith('ي') and (word.endswith('وا') or word.endswith('ا') or word.endswith('ي')):
+-                    word = 'ت' + word[1:]
+-                    
+                 corrected_tokens[i] = word
+                 # Increment jazmed verbs counter (handles both فعل الشرط and جواب الشرط)
+                 verbs_jazmed += 1
+@@ -714,8 +693,8 @@ class ArabicGrammarGuard:
+                     else:
+                         corrected_tokens[i+1] = base_adj + ('ان' if is_nom else 'ين')
+                         
+-            # Plural Human Adjective Agreement
+-            elif w1_num == 'p' and w1_pos in ['noun', 'unknown']:
++            # Plural Human Adjective Agreement (Sound Plurals Only)
++            elif w1_num == 'p' and w1_pos in ['noun', 'unknown'] and (w1.endswith('ون') or w1.endswith('ين') or w1.endswith('ات')):
+                 base_adj = None
+                 for suffix in ['ان', 'ين', 'تان', 'تين', 'ة', 'ون', 'ات', 'ين', '']:
+                     stem = w2[:-len(suffix)] if suffix else w2
+@@ -726,9 +705,11 @@ class ArabicGrammarGuard:
+                 if base_adj:
+                     if w1.endswith('ون') or w1.endswith('ين') or w1_gen == 'm':
+                         is_nom = w1.endswith('ون')
+-                        corrected_tokens[i+1] = base_adj + ('ون' if is_nom else 'ين')
++                        if not w2.endswith('ان') and not w2.endswith('ين') and not w2.endswith('ات'):
++                            corrected_tokens[i+1] = base_adj + ('ون' if is_nom else 'ين')
+                     elif w1.endswith('ات') or w1_gen == 'f':
+-                        corrected_tokens[i+1] = base_adj + 'ات'
++                        if not w2.endswith('ان') and not w2.endswith('ين') and not w2.endswith('ات'):
++                            corrected_tokens[i+1] = base_adj + 'ات'
+ 
+         return " ".join(corrected_tokens)
+ 
+@@ -866,8 +847,9 @@ class ArabicGrammarGuard:
+         }
+         words = text.split()
+         for i, w in enumerate(words):
+-            if w in _ALWAYS_TANWEEN:
+-                words[i] = _ALWAYS_TANWEEN[w]
++            clean_w = w.rstrip('.,،؛;:!؟?()[]{}«»"\'…')
++            if clean_w in _ALWAYS_TANWEEN:
++                words[i] = _ALWAYS_TANWEEN[clean_w] + w[len(clean_w):]
+         return ' '.join(words)
+ 
+     def fix_initial_hamza(self, text):
+@@ -920,16 +902,27 @@ class ArabicGrammarGuard:
+         _PRONOUN_SUFFIXES = {'ه', 'ها', 'ك', 'كم', 'كن', 'هم', 'هن', 'ني', 'نا'}
+         words = text.split()
+         for i, w in enumerate(words):
+-            if w in _HAMZA_FIXES:
+-                words[i] = _HAMZA_FIXES[w]
++            clean_w = w.rstrip('.,،؛;:!؟?()[]{}«»"\'…')
++            if clean_w in _HAMZA_FIXES:
++                words[i] = _HAMZA_FIXES[clean_w] + w[len(clean_w):]
+                 continue
+             # إنّ/أنّ: kasra at sentence start, fathah mid-sentence
+             _is_sent_start = (i == 0) or (words[i-1][-1] in '.؟!؛' if words[i-1] else False)
+-            if _is_sent_start and w in _INNA_SENTENCE_INITIAL:
+-                words[i] = _INNA_SENTENCE_INITIAL[w]
++            if _is_sent_start and clean_w in _INNA_SENTENCE_INITIAL:
++                words[i] = _INNA_SENTENCE_INITIAL[clean_w] + w[len(clean_w):]
+                 continue
+-            if not _is_sent_start and w in _ANNA_MID_SENTENCE:
+-                words[i] = _ANNA_MID_SENTENCE[w]
++            if not _is_sent_start and clean_w in _ANNA_MID_SENTENCE:
++                if clean_w == 'ان':
++                    # Bug 1.5: Added تقول and all variants to Qawl check
++                    if i > 0 and words[i-1].rstrip('.,،؛;:!؟?()[]{}«»"\'…') in ('قال', 'قالت', 'يقول', 'يقولون', 'قلت', 'قلنا', 'تقول', 'يقولوا'):
++                        words[i] = 'إن' + w[len(clean_w):]
++                    else:
++                        pass # leave it alone to avoid breaking conditional
++                else:
++                    if i > 0 and words[i-1].rstrip('.,،؛;:!؟?()[]{}«»"\'…') in ('قال', 'قالت', 'يقول', 'يقولون', 'قلت', 'قلنا', 'تقول', 'يقولوا'):
++                        words[i] = _INNA_SENTENCE_INITIAL[clean_w] + w[len(clean_w):]
++                    else:
++                        words[i] = _ANNA_MID_SENTENCE[clean_w] + w[len(clean_w):]
+                 continue
+             for stem, fixed in _HAMZA_STEMS.items():
+                 if w.startswith(stem) and len(w) > len(stem):

diff_punc.txt

@@ -0,0 +1,46 @@
+diff --git a/src/nlp/punctuation/punctuation_rules.py b/src/nlp/punctuation/punctuation_rules.py
+index 0d44de2..43b59d8 100644
+--- a/src/nlp/punctuation/punctuation_rules.py
++++ b/src/nlp/punctuation/punctuation_rules.py
+@@ -60,7 +60,9 @@ def arabic_postprocessing(text: str) -> str:
+     # Only applies if a colon is actually present on the verb or the name
+     def _fix_misplaced(m):
+         verb, col1, name, col2 = m.groups()
+-        if col1 == ':' or col2 == ':':
++        if col1 == ':':
++            return f"{verb}: {name}"
++        if col2 == ':':
+             return f"{verb} {name}:"
+         return m.group(0)
+         
+@@ -87,9 +89,9 @@ def arabic_postprocessing(text: str) -> str:
+             return match.group(0)
+             
+         if prev_word.startswith(('ال', 'لل', 'بال', 'فال', 'وال', 'كال')):
+-            return context + " " 
++            return match.group(0)  # Preserve the colon! Do not delete it.
+             
+-        return match.group(0)
++        return context + ' '
+         
+     text = re.sub(r'([^:]+)(:)', _colon_guard, text)
+     
+@@ -132,16 +134,11 @@ _EXCL_CUES = {'يا', 'ما', 'كم', 'لا', 'هل', 'أين', 'متى',
+ def _normalize_for_comparison(text: str) -> str:
+     """
+     Normalize Arabic for safe comparison.
+-    Prevents false rejection from hamza/alef/ya variants.
++    Only removes diacritics to prevent punctuation model from stripping harakat.
++    Does NOT fold hamza/ya/ta-marbuta to ensure we catch spelling regressions!
+     """
+     # Remove diacritics
+     text = re.sub(r'[\u064B-\u0652]', '', text)
+-    # Fold hamza/alef variants: أ إ آ → ا
+-    text = re.sub(r'[أإآ]', 'ا', text)
+-    # Fold ya: ى → ي
+-    text = text.replace('ى', 'ي')
+-    # Fold ta marbuta: ة → ه (comparison only)
+-    text = text.replace('ة', 'ه')
+     return text
+ 
+ 

diff_spell.txt

@@ -0,0 +1,264 @@
+diff --git a/src/nlp/spelling/araspell_rules.py b/src/nlp/spelling/araspell_rules.py
+index 39d02b7..0102cae 100644
+--- a/src/nlp/spelling/araspell_rules.py
++++ b/src/nlp/spelling/araspell_rules.py
+@@ -129,14 +129,9 @@ class AraSpellPostProcessor:
+     @staticmethod
+     def remove_duplicate_words(text: str) -> str:
+         """Remove consecutive duplicate words. e.g. كتاب كتاب → كتاب"""
+-        words = text.split()
+-        if len(words) < 2:
+-            return text
+-        result = [words[0]]
+-        for i in range(1, len(words)):
+-            if words[i] != words[i-1]:
+-                result.append(words[i])
+-        return ' '.join(result)
++        # Bug 2.11: Destroys rhetorical repetition (التوكيد اللفظي) like "صفا صفا".
++        # Disabled as it destroys valid Arabic phrases.
++        return text
+     
+     @staticmethod
+     def normalize_spaces(text: str) -> str:
+@@ -154,17 +149,9 @@ class AraSpellPostProcessor:
+     @staticmethod
+     def remove_word_repetition_with_wa(text: str) -> str:
+         """Remove word و word → word"""
+-        words = text.split()
+-        result = []
+-        i = 0
+-        while i < len(words):
+-            if i + 2 < len(words) and words[i] == words[i+2] and words[i+1] == 'و':
+-                result.append(words[i])
+-                i += 3
+-            else:
+-                result.append(words[i])
+-                i += 1
+-        return ' '.join(result)
++        # Bug 2.9: This deletes valid rhetorical repetition (التوكيد اللفظي) like "صنفا وصنفا"
++        # Disabled as it is highly destructive to valid Arabic.
++        return text
+     
+     # --- Hamza & Ta Marbuta Handling ---
+     
+@@ -181,7 +168,7 @@ class AraSpellPostProcessor:
+         'اذا': 'إذا', 'اذ': 'إذ',
+         'اي': 'أي', 'اين': 'أين',
+         'او': 'أو',
+-        'اما': 'أما',
++        
+         'ان': 'أن', 'انه': 'أنه', 'انها': 'أنها', 'انهم': 'أنهم',
+         'اخر': 'آخر', 'اخرى': 'أخرى',
+         'الان': 'الآن',
+@@ -201,9 +188,9 @@ class AraSpellPostProcessor:
+         'اهل': 'أهل',
+         'اطفال': 'أطفال',
+         'اصدقاء': 'أصدقاء', 'اصدقائي': 'أصدقائي',
+-        'اعتقد': 'أعتقد', 'اريد': 'أريد', 'احب': 'أحب',
+-        'اعرف': 'أعرف', 'اعلم': 'أعلم',
+-        'اخذ': 'أخذ', 'اكل': 'أكل',
++        'اريد': 'أريد', 'احب': 'أحب',
++        'اعلم': 'أعلم',
++        'اكل': 'أكل',
+         'الايام': 'الأيام',
+         'الاطفال': 'الأطفال',
+         'الاسعار': 'الأسعار',
+@@ -243,10 +230,8 @@ class AraSpellPostProcessor:
+         'ادارة': 'إدارة', 'ادارية': 'إدارية',
+         'اعلام': 'إعلام', 'اعلامي': 'إعلامي',
+         'احتمال': 'احتمال', 'احتفال': 'احتفال',
+-        'ازور': 'أزور', 'اذهب': 'أذهب', 'اكتب': 'أكتب',
+         'اقرا': 'أقرأ', 'اقرأ': 'أقرأ',
+-        'اعمل': 'أعمل', 'ادرس': 'أدرس',
+-        'اشتري': 'أشتري', 'اسافر': 'أسافر',
++        'اسافر': 'أسافر',
+         'احبه': 'أحبه',
+         'مسؤول': 'مسؤول', 'مسؤولية': 'مسؤولية',
+         'رؤية': 'رؤية', 'رؤيا': 'رؤيا',
+@@ -259,7 +244,7 @@ class AraSpellPostProcessor:
+         'مصطفي': 'مصطفى', 'موسي': 'موسى', 'عيسي': 'عيسى',
+         'هدي': 'هدى', 'بني': 'بنى',
+         'معني': 'معنى', 'مبني': 'مبنى',
+-        'علي': 'على',  # Common alif maqsura confusion
++        
+         'الي': 'إلى',
+         # FIX-47: Verb+pronoun hamza entries (احبه→أحبه)
+         'احبه': 'أحبه', 'احبها': 'أحبها', 'احبك': 'أحبك',
+@@ -280,16 +265,9 @@ class AraSpellPostProcessor:
+     @staticmethod
+     def fix_hamza_conservative(text: str) -> str:
+         """Conservative Hamza normalization — only at word END, not middle."""
+-        words = text.split()
+-        result = []
+-        for word in words:
+-            if len(word) >= 3:
+-                if word.endswith('أ'):
+-                    word = word[:-1] + 'ا'
+-                if word.endswith('إ'):
+-                    word = word[:-1] + 'ا'
+-            result.append(word)
+-        return ' '.join(result)
++        # Bug 2.5: Blindly changing أ at the end of word to ا corrupts valid orthography (قرأ -> قرا)
++        # Disabled as it is highly destructive.
++        return text
+     
+     # Attached prefixes that can precede hamza-whitelist words
+     # Ordered longest-first so وال is tried before و
+@@ -354,18 +332,22 @@ class AraSpellPostProcessor:
+             if any(word.endswith(e) for e in PROTECTED_ENDINGS):
+                 result.append(word)
+                 continue
+-            if word in PROTECTED_HA_WORDS:
++            if word in PROTECTED_HA_WORDS or word in ['هذه', 'هاته']:
+                 result.append(word)
+                 continue
+             if len(word) >= 3 and word.endswith('ه'):
+-                if word[-2] in AraSpellPostProcessor.ARABIC_CONSONANTS:
++                if word[-2] in AraSpellPostProcessor.ARABIC_CONSONANTS or word[-2] in 'اويءؤئ':
+                     candidate_with_ta = word[:-1] + 'ة'
+                     # Default: prefer ة (correct Arabic orthography for feminine nouns)
+                     if vocab_manager:
+                         ta_iv = vocab_manager.is_iv(candidate_with_ta)
+                         ha_iv = vocab_manager.is_iv(word)
+-                        if ta_iv:
+-                            # Always prefer ة when it's a valid word
++                        if ha_iv and ta_iv:
++                            # Bug 2.2: Do not prefer ة if ه is also valid (possessive pronoun)
++                            result.append(word)
++                            continue
++                        elif ta_iv:
++                            # Prefer ة when ONLY the ة form is valid
+                             result.append(candidate_with_ta)
+                             continue
+                         elif ha_iv:
+@@ -401,11 +383,9 @@ class AraSpellPostProcessor:
+                     word = word[:-1]
+             if i + 1 < len(words):
+                 next_word = words[i + 1]
+-                if normalize_word(word) == normalize_word(next_word):
+-                    keep = next_word if next_word.startswith('ال') and not word.startswith('ال') else word
+-                    result.append(keep)
+-                    i += 2
+-                    continue
++                # Bug 2.11: Destroys Badal structures (الأستاذ أستاذ -> الأستاذ)
++                # and Rhetorical Repetition (التوكيد اللفظي)
++                # Removed the aggressive duplicate word deletion.
+             result.append(word)
+             i += 1
+         return ' '.join(result)
+@@ -454,18 +434,8 @@ class AraSpellPostProcessor:
+                     result.append(word + next_word)
+                     i += 2
+                     continue
+-                if len(word) >= 2 and len(next_word) >= 2 and word[-1] == next_word[0]:
+-                    if not (word in STANDALONE_WORDS and next_word in STANDALONE_WORDS):
+-                        result.append(word[:-1] + next_word)
+-                        i += 2
+-                        continue
+-                if (2 <= len(word) <= 4 and 
+-                    1 <= len(next_word) <= 2 and
+-                    3 <= len(word) + len(next_word) <= 7):
+-                    if not (word in STANDALONE_WORDS and next_word in STANDALONE_WORDS):
+-                        result.append(word + next_word)
+-                        i += 2
+-                        continue
++                # Bug 2.3: Destructive word merging (يوم مشمس -> يومشمس)
++                # Removed generic boundary letter merging.
+             result.append(word)
+             i += 1
+         return ' '.join(result)
+@@ -779,15 +749,7 @@ class WordAligner:
+         if in_iv and not out_iv:
+             return input_word
+         if in_iv and out_iv:
+-            # Fix S1: When only difference is ه→ة at word end, prefer ة
+-            # (correct Arabic orthography — ة is the standard feminine ending)
+-            if (input_word.endswith('ه') and output_word.endswith('ة')
+-                    and input_word[:-1] == output_word[:-1]):
+-                return output_word
+-            # Fix S1: Also handle ة→ه (don't regress a correct ة to ه)
+-            if (input_word.endswith('ة') and output_word.endswith('ه')
+-                    and input_word[:-1] == output_word[:-1]):
+-                return input_word
++            # Bug 2.2: Do not prefer ة over ه if both are IV, because ه is often a valid possessive pronoun.
+             return input_word 
+         if len(input_word) == len(output_word) and len(input_word) >= 3:
+             for i in range(len(input_word)):
+@@ -1207,55 +1169,35 @@ class ArabicSpellChecker:
+             logger.info("[MLM/CONTEXTUAL] Disabled by configuration (use_contextual=False)")
+ 
+     def _fix_repeated_end_chars(self, text: str) -> str:
+-        text = re.sub(r'([ا-ي])\1+\b', r'\1', text)
++        # Exclude 'ي' if it is preceded by a Kasra or another Yaa (e.g., يحيي)
++        def _replace_repeated(m):
++            w = m.group(0)
++            char = m.group(2)
++            if w.endswith('يي'):
++                if self.vocab_manager and self.vocab_manager.is_iv(w):
++                    return w
++            return m.group(1) + char
++        text = re.sub(r'\b([^\s]+?)([\u0621-\u064A])\2+\b', _replace_repeated, text)
+         return text
+     
+     def _fix_merged_with_errors(self, text: str) -> str:
+-        text = re.sub(r'ال([ا-ي])\1+([ا-ي]{2,})', r'ال\2', text)
++        # Bug 2.10: This regex was r'ال\2', deleting all instances of the character
++        text = re.sub(r'ال([ا-ي])\1+([ا-ي]{2,})', r'ال\1\2', text)
+         text = re.sub(r'\b([ا-ي]{3,})([ا-ي])\2+\b', r'\1\2', text)
+         return text
+ 
+     def _split_merged_words_linguistic(self, text: str) -> str:
+-        text = re.sub(
+-            r'\b(في|من|إلى|الى|حتى|منذ|خلال|بعد|قبل)(ال)?([ا-ي]{3,})',
+-            r'\1 \2\3', text
+-        )
+-        text = re.sub(r'\b(كل)([ا-ي]{3,})', r'\1 \2', text)
+-        text = re.sub(r'([ا-ي]{3,})(ال)([ا-ي]{3,})', r'\1 \2\3', text)
+-        text = re.sub(r'\b([بلك])(ال)?([ا-ي]{3,})', r'\1 \2\3', text)
+-        text = re.sub(r'([ا-ي]{4,})(عليكم|عليك|عليه|عليها)', r'\1 \2', text)
+-        text = re.sub(r'([ا-ي]{3,})(على|عن)([ا-ي]{3,})', r'\1 \2 \3', text)
++        # Bug 2.7: Catastrophic preposition splitting (e.g. منطق -> من طق)
++        # Disabled generic regex splitting as it is highly destructive to valid vocabulary.
+         return text
+     
+     def _split_long_words_heuristic(self, text: str, max_length: int = 15) -> str:
+-        words = text.split()
+-        result = []
+-        for word in words:
+-            if len(word) <= max_length:
+-                result.append(word)
+-                continue
+-            if 'ال' in word[2:]:
+-                parts = word.split('ال', 1)
+-                if len(parts[0]) >= 2 and len(parts[1]) >= 3:
+-                    result.extend([parts[0], 'ال' + parts[1]])
+-                    continue
+-            if len(word) >= 8:
+-                split_found = False
+-                for split_pos in [2, 3]:
+-                    prefix = word[:split_pos]
+-                    suffix = word[split_pos:]
+-                    if prefix in ['في', 'من', 'على', 'عن', 'مع', 'كل', 'ب', 'ل', 'ك']:
+-                        result.extend([prefix, suffix])
+-                        split_found = True
+-                        break
+-                if not split_found:
+-                    result.append(word)
+-            else:
+-                result.append(word)
+-        return ' '.join(result)
++        # Bug 2.8: Overzealous long word splitting (e.g. فيتامينات -> في تامينات)
++        # Disabled as it creates more errors than it fixes.
++        return text
+     
+     def _normalize_tanween_patterns(self, text: str) -> str:
+-        text = re.sub(r'([ا-ي]{2,})أ\b', r'\1اً', text)
++        # Bug 2.6: Blind replacement of trailing أ with اً corrupts verbs and nominative cases (قرأ -> قراً)
+         text = re.sub(r'\s+أ\s+', ' ', text)
+         text = re.sub(r'\b([بلك])\s+([ا-ي])', r'\1\2', text)
+         return text
+@@ -1661,3 +1603,4 @@ class ArabicSpellChecker:
+             result = ' '.join(res_words_list)
+ 
+         return result
++

extension/content-inline.css

@@ -395,18 +395,22 @@
   font-weight: 700 !important;
   background: linear-gradient(135deg, #8BB8E8, #6BA3E0) !important;
   -webkit-background-clip: text !important;
+  background-clip: text !important;
   -webkit-text-fill-color: transparent !important;
   letter-spacing: -0.3px !important;
 }
 
 .bayan-il-modal-close {
+  display: flex !important;
+  align-items: center !important;
+  justify-content: center !important;
+  width: 28px !important;
+  height: 28px !important;
   background: none !important;
   border: none !important;
   color: #8A939F !important;
   cursor: pointer !important;
-  font-size: 18px !important;
-  padding: 4px !important;
-  line-height: 1 !important;
+  padding: 0 !important;
   border-radius: 6px !important;
   transition: background 150ms ease, color 150ms ease !important;
 }
@@ -553,9 +557,11 @@
 /* ── Header Divider ── */
 
 .bayan-il-header-divider {
-  width: 1px !important;
-  height: 20px !important;
+  width: 2px !important;
+  height: 24px !important;
   background: #3a3a4d !important;
+  border-radius: 9999px !important;
+  flex-shrink: 0 !important;
 }
 
 /* ── Suggestion Cards ── */
@@ -916,6 +922,15 @@
 .bayan-il-popover-label {
   font-weight: 700 !important;
 }
+.bayan-il-popover-arrow {
+  color: #8A939F !important;
+  font-size: 12px !important;
+  margin: 0 4px !important;
+}
+.bayan-il-popover-correction {
+  color: #6BC98A !important;
+  font-weight: 600 !important;
+}
 .bayan-il-popover-alternatives {
   display: flex !important;
   flex-direction: column !important;
@@ -974,6 +989,58 @@
   margin-bottom: 0 !important;
 }
 
+/* ── Tooltip Popover — Light Theme ── */
+
+.bayan-il-suggestion-popover[data-bayan-theme="light"] {
+  background: #FAF9F6 !important;
+  border-color: rgba(26, 29, 33, 0.12) !important;
+  box-shadow: 0 16px 40px rgba(0, 0, 0, 0.1) !important;
+  color: #1A1D21 !important;
+}
+
+.bayan-il-suggestion-popover[data-bayan-theme="light"] .bayan-il-popover-original-word {
+  color: #3A424E !important;
+}
+
+.bayan-il-suggestion-popover[data-bayan-theme="light"] .bayan-il-tooltip-original {
+  color: #C53030 !important;
+}
+
+.bayan-il-suggestion-popover[data-bayan-theme="light"] .bayan-il-popover-correction {
+  color: #2F8554 !important;
+}
+
+.bayan-il-suggestion-popover[data-bayan-theme="light"] .bayan-il-popover-arrow {
+  color: #5A6472 !important;
+}
+
+.bayan-il-suggestion-popover[data-bayan-theme="light"] .bayan-il-popover-alt-btn {
+  background: #FAF9F6 !important;
+  border-color: rgba(26, 29, 33, 0.12) !important;
+  color: #1A1D21 !important;
+}
+
+.bayan-il-suggestion-popover[data-bayan-theme="light"] .bayan-il-popover-alt-main {
+  background: linear-gradient(135deg, #2B6CB8, #6B57A8) !important;
+  color: white !important;
+  border-color: transparent !important;
+}
+
+.bayan-il-suggestion-popover[data-bayan-theme="light"] .bayan-il-popover-dismiss {
+  border-color: rgba(26, 29, 33, 0.18) !important;
+  color: #5A6472 !important;
+}
+
+.bayan-il-suggestion-popover[data-bayan-theme="light"] .bayan-il-popover-dismiss:hover {
+  color: #C53030 !important;
+  border-color: #C53030 !important;
+  background: rgba(197, 48, 48, 0.06) !important;
+}
+
+.bayan-il-suggestion-popover[data-bayan-theme="light"] .bayan-il-popover-hint {
+  color: #5A6472 !important;
+}
+
 /* Modal Panel UI Sync */
 .bayan-il-sidebar-panel {
   display: flex !important;
@@ -1141,51 +1208,4 @@
   opacity: 0.9 !important;
 }
 
-/* Modal header wrapper */
-.bayan-il-modal-top-bar {
-  display: flex !important;
-  align-items: center !important;
-  justify-content: space-between !important;
-  padding: 0 0.5rem !important;
-}
-.bayan-il-modal-brand {
-  display: flex !important;
-  align-items: center !important;
-  gap: 0.5rem !important;
-}
-.bayan-il-modal-title {
-  font-size: 1.25rem !important;
-  font-weight: 700 !important;
-  background: linear-gradient(135deg, #6BA3E0, #A594E8) !important;
-  -webkit-background-clip: text !important;
-  -webkit-text-fill-color: transparent !important;
-}
-.bayan-il-modal-close {
-  background: none !important;
-  border: none !important;
-  color: #B4BBC6 !important;
-  font-size: 1.25rem !important;
-  cursor: pointer !important;
-}
-.bayan-il-modal-close:hover {
-  color: #E88A8A !important;
-}
-
-
-
-
-.bayan-il-header-divider {
-  width: 1px !important;
-  height: 18px !important;
-  background: rgba(236, 238, 242, 0.2) !important;
-  margin: 0 10px !important;
-}
-
-.bayan-il-modal-top-bar {
-  cursor: grab !important;
-}
-
-.bayan-il-modal-top-bar:active {
-  cursor: grabbing !important;
-}
 

extension/content-inline.js

@@ -462,7 +462,7 @@
     if (!original || !correction) return;
 
     const suggestion = { id: sid, original, correction, type, start, end };
-    const typeLabels = { spelling: 'إملائي', grammar: 'نحوي', punctuation: 'ترقيم' };
+    const typeLabels = { spelling: 'خطأ إملائي', grammar: 'خطأ نحوي', punctuation: 'علامات ترقيم' };
 
     tooltip = document.createElement('div');
     tooltip.setAttribute('data-bayan-theme', currentBayanTheme);
@@ -471,23 +471,22 @@
 
     const typeLabel = typeLabels[type] || type;
     const typeClass = type === 'spelling' ? 'bayan-il-popover-type--spelling' : type === 'grammar' ? 'bayan-il-popover-type--grammar' : 'bayan-il-popover-type--punctuation';
-    const icon = type === 'spelling' ? '✕' : type === 'grammar' ? '!' : '✓';
-    
+
     safeHTML(tooltip, `
-        <div class="bayan-il-popover-type ${typeClass}">
-          <span class="bayan-il-popover-type-icon">${icon}</span> ${typeLabel}
-        </div>
+        <div class="bayan-il-popover-type ${typeClass}">${typeLabel}</div>
         <div class="bayan-il-popover-original-word">
           <span class="bayan-il-popover-label">الكلمة:</span>
           <span class="bayan-il-tooltip-original">${esc(original)}</span>
+          <span class="bayan-il-popover-arrow">←</span>
+          <span class="bayan-il-popover-correction">${correction ? esc(correction) : '<s style="opacity:0.5">حذف</s>'}</span>
         </div>
         <div class="bayan-il-popover-alternatives">
           <button class="bayan-il-popover-alt-btn bayan-il-popover-alt-main" data-action="apply">
-            ${correction ? esc(correction) : '<s style="opacity:0.5">حذف</s>'}
+            ${correction ? '✓ ' + esc(correction) : '<s style="opacity:0.5">حذف</s>'}
           </button>
         </div>
         <button type="button" class="bayan-il-popover-dismiss" data-action="ignore" title="تجاهل هذا الاقتراح">تجاهل</button>
-        <p class="bayan-il-popover-hint">اختر التصحيح المناسب</p>
+        <p class="bayan-il-popover-hint">اختر التصحيح المناسب · Escape للإغلاق</p>
     `);
 
     document.body.appendChild(tooltip);
@@ -525,6 +524,11 @@
     });
 
     setTimeout(() => document.addEventListener('click', outsideClick, { once: true }), 100);
+
+    const escHandler = (e) => {
+      if (e.key === 'Escape') { hideTooltip(); document.removeEventListener('keydown', escHandler); }
+    };
+    document.addEventListener('keydown', escHandler);
   }
 
   function outsideClick(e) {
@@ -1135,14 +1139,22 @@
     safeHTML(modalPanel, `
       <div class="bayan-il-modal-top-bar" id="bayan-modal-drag-handle">
         <div class="bayan-il-modal-brand">
-           <img src="${chrome.runtime.getURL('assets/icons/icon128.png')}" alt="بيان" style="width: 24px; height: 24px; object-fit: contain;" draggable="false" />
+           <img src="${chrome.runtime.getURL('assets/icons/icon48.png')}" alt="بيان" style="width: 28px; height: 28px; object-fit: contain; border-radius: 6px;" draggable="false" />
            <div class="bayan-il-header-divider"></div>
            <span class="bayan-il-modal-title">بيان</span>
         </div>
-        <button class="bayan-il-modal-close" title="إغلاق">✕</button>
+        <button class="bayan-il-modal-close" title="إغلاق"><svg width="16" height="16" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12"/></svg></button>
       </div>
 
       <div class="bayan-il-modal-body-scroll">
+        <div class="bayan-il-modal-sugg-card">
+          <div class="bayan-il-modal-sugg-header">
+            <h3 class="bayan-il-modal-section-title">الاقتراحات (<span id="bayan-modal-sugg-count">٠</span>)</h3>
+            <button id="bayan-modal-apply-all" class="bayan-il-modal-apply-all" style="display:none;" type="button">تطبيق الكل</button>
+          </div>
+          <div id="bayan-modal-cards" class="bayan-il-modal-cards" role="list" aria-live="polite" aria-label="اقتراحات التصحيح"></div>
+        </div>
+
         <div class="bayan-il-modal-score-card">
           <h3 class="bayan-il-modal-section-title">تقييم الكتابة</h3>
           <div class="bayan-il-modal-score-ring" role="img" aria-label="تقييم الكتابة">
@@ -1160,14 +1172,6 @@
             <span class="bayan-il-modal-count bayan-il-modal-count--punctuation"><strong id="bayan-modal-count-punctuation">٠</strong> ترقيم</span>
           </div>
         </div>
-
-        <div class="bayan-il-modal-sugg-card">
-          <div class="bayan-il-modal-sugg-header">
-            <h3 class="bayan-il-modal-section-title">الاقتراحات (<span id="bayan-modal-sugg-count">٠</span>)</h3>
-            <button id="bayan-modal-apply-all" class="bayan-il-modal-apply-all" style="display:none;" type="button">تطبيق الكل</button>
-          </div>
-          <div id="bayan-modal-cards" class="bayan-il-modal-cards" role="list" aria-live="polite" aria-label="اقتراحات التصحيح"></div>
-        </div>
       </div>
     `);
 

old2.py

@@ -0,0 +1,1663 @@
+# AraSpell — Arabic Spell Checker Pipeline (Rules & Classes)
+# Extracted from AraSpell.py — NO global model loading, NO Gradio dependencies.
+# All classes are imported by araspell_service.py.
+
+import re
+import math
+import logging
+import torch
+from collections import Counter
+from enum import Enum
+from typing import List, Tuple, Optional
+
+import Levenshtein
+import jellyfish
+
+logger = logging.getLogger(__name__)
+
+# ─────────────────────────────────────────────────────────────────────────────
+# ERROR TYPE ENUM
+# ─────────────────────────────────────────────────────────────────────────────
+
+class ErrorType(Enum):
+    """Types of spelling errors"""
+    CHAR_REPETITION = "char_repetition"
+    WORD_MERGE = "word_merge"
+    CHAR_SUBSTITUTION = "char_substitution"
+    MIXED = "mixed"
+    CLEAN = "clean"
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# KEYBOARD PROXIMITY (Phase 12 — from original AraSpell.py L475-520)
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class RulesBasedCorrector:
+    """Arabic keyboard-proximity and character substitution rules."""
+
+    # Arabic keyboard layout adjacency mapping
+    KEYBOARD_NEIGHBORS = {
+        'ض': ['ص', 'ق'],
+        'ص': ['ض', 'ث', 'ق'],
+        'ث': ['ص', 'ق'],
+        'ق': ['ض', 'ص', 'ث', 'ف', 'غ'],
+        'ف': ['ق', 'غ', 'ع', 'ب'],
+        'غ': ['ق', 'ف', 'ع', 'ه'],
+        'ع': ['ف', 'غ', 'ه', 'خ'],
+        'ه': ['غ', 'ع', 'خ', 'ح'],
+        'خ': ['ع', 'ه', 'ح', 'ج'],
+        'ح': ['ه', 'خ', 'ج'],
+        'ج': ['خ', 'ح', 'د'],
+        'د': ['ج', 'ذ'],
+        'ذ': ['د'],
+        'ش': ['س', 'ي', 'ئ'],
+        'س': ['ش', 'ي', 'ب'],
+        'ي': ['ش', 'س', 'ب', 'ت'],
+        'ب': ['ي', 'س', 'ف', 'ل', 'ن'],
+        'ل': ['ب', 'ا', 'ن', 'م'],
+        'ا': ['ل', 'ت', 'م'],
+        'ت': ['ي', 'ا', 'ن'],
+        'ن': ['ب', 'ل', 'ت', 'م', 'ك'],
+        'م': ['ل', 'ا', 'ن', 'ك'],
+        'ك': ['ن', 'م', 'ط'],
+        'ط': ['ك', 'ظ'],
+        'ظ': ['ط'],
+        'ئ': ['ش', 'ء', 'ر'],
+        'ء': ['ئ', 'ؤ'],
+        'ؤ': ['ء', 'ر'],
+        'ر': ['ئ', 'ؤ', 'لا', 'ى', 'ز'],
+        'لا': ['ر', 'ى'],
+        'ى': ['ر', 'لا', 'ة', 'ز'],
+        'ة': ['ى', 'و', 'ز'],
+        'و': ['ة', 'ز'],
+        'ز': ['ر', 'ى', 'ة', 'و'],
+        'أ': ['ا', 'إ', 'آ'],
+        'إ': ['ا', 'أ'],
+        'آ': ['ا', 'أ'],
+    }
+
+    @staticmethod
+    def is_keyboard_neighbor(char1: str, char2: str) -> bool:
+        """Check if two Arabic chars are adjacent on the keyboard."""
+        neighbors = RulesBasedCorrector.KEYBOARD_NEIGHBORS.get(char1, [])
+        return char2 in neighbors
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# POST PROCESSOR
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class AraSpellPostProcessor:
+    """Arabic text post-processing techniques."""
+    
+    ARABIC_HARAKAT = 'ًٌٍَُِّْ'
+    TATWEEL = 'ـ'
+    NORMALIZER_MAP = {
+        'ﻹ': 'لإ', 'ﻷ': 'لأ', 'ﻵ': 'لآ', 'ﻻ': 'لا', 'ﷲ': 'الله'
+    }
+    ARABIC_CONSONANTS = set('بتثجحخدذرزسشصضطظعغفقكلمن')
+    
+    # --- Basic Normalization ---
+    
+    @staticmethod
+    def remove_harakat(text: str) -> str:
+        """Remove Arabic diacritics"""
+        return re.sub(r'[ً-ْ]', '', text)
+    
+    @staticmethod
+    def remove_tatweel(text: str) -> str:
+        """Remove Arabic kashida/tatweel"""
+        return text.replace(AraSpellPostProcessor.TATWEEL, '')
+    
+    @staticmethod
+    def normalize_special_chars(text: str) -> str:
+        """Normalize special Arabic ligatures"""
+        for old, new in AraSpellPostProcessor.NORMALIZER_MAP.items():
+            text = text.replace(old, new)
+        return text
+    
+    # --- Core Functions ---
+    
+    @staticmethod
+    def unified_collapse_repeated(text: str) -> str:
+        """
+        Collapse repeated characters.
+        Arabic: 3+ consecutive → 1 | Latin: 2+ consecutive → 1
+        """
+        text = re.sub(r"([\u0600-\u06FF])\1{2,}", r"\1", text)
+        text = re.sub(r"([a-zA-Z])\1+", r"\1", text)
+        return text
+    
+    @staticmethod
+    def remove_duplicate_words(text: str) -> str:
+        """Remove consecutive duplicate words. e.g. كتاب كتاب → كتاب"""
+        words = text.split()
+        if len(words) < 2:
+            return text
+        result = [words[0]]
+        for i in range(1, len(words)):
+            if words[i] != words[i-1]:
+                result.append(words[i])
+        return ' '.join(result)
+    
+    @staticmethod
+    def normalize_spaces(text: str) -> str:
+        """Normalize whitespace: multiple spaces, unicode spaces, punctuation spacing."""
+        text = re.sub(r' +', ' ', text)
+        text = text.replace('\u00A0', ' ')
+        text = text.replace('\u200B', '')
+        text = text.replace('\u200C', '')
+        text = text.replace('\u200D', '')
+        text = text.strip()
+        text = re.sub(r'\s*([،؛؟!.])\s*', r'\1 ', text)
+        text = text.strip()
+        return text
+    
+    @staticmethod
+    def remove_word_repetition_with_wa(text: str) -> str:
+        """Remove word و word → word"""
+        words = text.split()
+        result = []
+        i = 0
+        while i < len(words):
+            if i + 2 < len(words) and words[i] == words[i+2] and words[i+1] == 'و':
+                result.append(words[i])
+                i += 3
+            else:
+                result.append(words[i])
+                i += 1
+        return ' '.join(result)
+    
+    # --- Hamza & Ta Marbuta Handling ---
+    
+    # Common Arabic words with hamza errors — covers the most frequent
+    # spelling mistakes in informal Arabic writing
+    HAMZA_WHITELIST = {
+        'الي': 'إلى', 'الى': 'إلى',
+        'انت': 'أنت', 'انتم': 'أنتم', 'انتي': 'أنتِ',
+        'انتو': 'أنتم', 'انتن': 'أنتن',
+        'انا': 'أنا',
+        'امس': 'أمس',
+        'لان': 'لأن', 'لانه': 'لأنه', 'لانها': 'لأنها',
+        'لانهم': 'لأنهم', 'لانك': 'لأنك',
+        'اذا': 'إذا', 'اذ': 'إذ',
+        'اي': 'أي', 'اين': 'أين',
+        'او': 'أو',
+        'اما': 'أما',
+        'ان': 'أن', 'انه': 'أنه', 'انها': 'أنها', 'انهم': 'أنهم',
+        'اخر': 'آخر', 'اخرى': 'أخرى',
+        'الان': 'الآن',
+        'اول': 'أول', 'اولى': 'أولى',
+        'اصبح': 'أصبح', 'اصبحت': 'أصبحت',
+        'اكثر': 'أكثر', 'اقل': 'أقل',
+        'اعلى': 'أعلى', 'ادنى': 'أدنى',
+        'اسرع': 'أسرع', 'ابطا': 'أبطأ',
+        'اكبر': 'أكبر', 'اصغر': 'أصغر',
+        'احسن': 'أحسن', 'اسوا': 'أسوأ',
+        'امام': 'أمام',
+        'اثناء': 'أثناء',
+        'ايضا': 'أيضاً', 'ايض': 'أيضاً',
+        'اساسي': 'أساسي', 'اساسية': 'أساسية',
+        'اخي': 'أخي', 'اخت': 'أخت', 'اخو': 'أخو',
+        'ابي': 'أبي', 'اب': 'أب', 'ابو': 'أبو',
+        'اهل': 'أهل',
+        'اطفال': 'أطفال',
+        'اصدقاء': 'أصدقاء', 'اصدقائي': 'أصدقائي',
+        'اعتقد': 'أعتقد', 'اريد': 'أريد', 'احب': 'أحب',
+        'اعرف': 'أعرف', 'اعلم': 'أعلم',
+        'اخذ': 'أخذ', 'اكل': 'أكل',
+        'الايام': 'الأيام',
+        'الاطفال': 'الأطفال',
+        'الاسعار': 'الأسعار',
+        'الاولى': 'الأولى',
+        'الاخير': 'الأخير', 'الاخيرة': 'الأخيرة',
+        'واصدقائي': 'وأصدقائي',
+        # FIX-14: Additional hamza entries
+        'ابناء': 'أبناء',
+        'اجمل': 'أجمل', 'اجمع': 'أجمع',
+        'اعلن': 'أعلن', 'اعلنت': 'أعلنت',
+        'اكد': 'أكد', 'اكدت': 'أكدت',
+        'اشار': 'أشار', 'اشارت': 'أشارت',
+        'ارسل': 'أرسل', 'ارسلت': 'أرسلت',
+        'اضاف': 'أضاف', 'اضافت': 'أضافت',
+        'اخيرا': 'أخيراً', 'اخيراً': 'أخيراً',
+        'اساسا': 'أساساً', 'اساساً': 'أساساً',
+        'احيانا': 'أحياناً', 'احياناً': 'أحياناً',
+        'ابدا': 'أبداً', 'ابداً': 'أبداً',
+        'اصلا': 'أصلاً', 'اصلاً': 'أصلاً',
+        'اخبار': 'أخبار', 'اخبر': 'أخبر',
+        'امر': 'أمر', 'امور': 'أمور',
+        'اهم': 'أهم', 'اهمية': 'أهمية',
+        'اصبح': 'أصبح', 'اصل': 'أصل',
+        'اثر': 'أثر', 'اثار': 'آثار',
+        'اساء': 'أساء', 'اساس': 'أساس',
+        'استاذ': 'أستاذ', 'اسلام': 'إسلام',
+        # Batch 3: More hamza entries for remaining FN cases
+        'اسرة': 'أسرة', 'اسر': 'أسر',
+        'اعضاء': 'أعضاء', 'اعداد': 'أعداد',
+        'اعمال': 'أعمال', 'اعمار': 'أعمار',
+        'انجاز': 'إنجاز', 'انجازات': 'إنجازات',
+        'انشاء': 'إنشاء', 'انتاج': 'إنتاج',
+        'انتخابات': 'انتخابات', 'انتظار': 'انتظار',
+        'اسلامي': 'إسلامي', 'اسلامية': 'إسلامية',
+        'امكانية': 'إمكانية', 'امكان': 'إمكان',
+        'اشكالية': 'إشكالية',
+        'ادارة': 'إدارة', 'ادارية': 'إدارية',
+        'اعلام': 'إعلام', 'اعلامي': 'إعلامي',
+        'احتمال': 'احتمال', 'احتفال': 'احتفال',
+        'ازور': 'أزور', 'اذهب': 'أذهب', 'اكتب': 'أكتب',
+        'اقرا': 'أقرأ', 'اقرأ': 'أقرأ',
+        'اعمل': 'أعمل', 'ادرس': 'أدرس',
+        'اشتري': 'أشتري', 'اسافر': 'أسافر',
+        'احبه': 'أحبه',
+        'مسؤول': 'مسؤول', 'مسؤولية': 'مسؤولية',
+        'رؤية': 'رؤية', 'رؤيا': 'رؤيا',
+        'مؤسسة': 'مؤسسة', 'مؤتمر': 'مؤتمر',
+        'تأثير': 'تأثير', 'تأكيد': 'تأكيد',
+        'البنايه': 'البناية',
+        'جدا': 'جداً', 'جداً': 'جداً',
+        # FIX-14: Alif maqsura common errors
+        'المستشفي': 'المستشفى',
+        'مصطفي': 'مصطفى', 'موسي': 'موسى', 'عيسي': 'عيسى',
+        'هدي': 'هدى', 'بني': 'بنى',
+        'معني': 'معنى', 'مبني': 'مبنى',
+        'علي': 'على',  # Common alif maqsura confusion
+        'الي': 'إلى',
+        # FIX-47: Verb+pronoun hamza entries (احبه→أحبه)
+        'احبه': 'أحبه', 'احبها': 'أحبها', 'احبك': 'أحبك',
+        'احبكم': 'أحبكم', 'احببت': 'أحببت',
+        'افهم': 'أفهم', 'افهمه': 'أفهمه', 'افهمها': 'أفهمها',
+        'افهمك': 'أفهمك',
+        'اعطي': 'أعطي', 'اعطاه': 'أعطاه', 'اعطاها': 'أعطاها',
+        'اعطى': 'أعطى', 'اعطت': 'أعطت', 'اعطيت': 'أعطيت',
+        'احتاج': 'أحتاج', 'احتاجه': 'أحتاجه',
+        'استطيع': 'أستطيع', 'استطع': 'أستطع',
+        'اتمنى': 'أتمنى', 'اتوقع': 'أتوقع',
+        'اشعر': 'أشعر', 'اظن': 'أظن', 'افضل': 'أفضل',
+        'اخاف': 'أخاف', 'اتذكر': 'أتذكر', 'اتعلم': 'أتعلم',
+        'ارجو': 'أرجو', 'اتوقف': 'أتوقف', 'انصح': 'أنصح',
+        'انسان': 'إنسان', 'انسانية': 'إنسانية',
+    }
+    
+    @staticmethod
+    def fix_hamza_conservative(text: str) -> str:
+        """Conservative Hamza normalization — only at word END, not middle."""
+        words = text.split()
+        result = []
+        for word in words:
+            if len(word) >= 3:
+                if word.endswith('أ'):
+                    word = word[:-1] + 'ا'
+                if word.endswith('إ'):
+                    word = word[:-1] + 'ا'
+            result.append(word)
+        return ' '.join(result)
+    
+    # Attached prefixes that can precede hamza-whitelist words
+    # Ordered longest-first so وال is tried before و
+    HAMZA_PREFIXES = ['وبال', 'فبال', 'وال', 'بال', 'فال', 'كال', 'ول', 'فل',
+                      'وب', 'فب', 'وك', 'فك', 'و', 'ف', 'ب', 'ك', 'ل']
+
+    @staticmethod
+    def fix_common_hamza(text: str) -> str:
+        """
+        Fix common hamza placement errors using a whitelist.
+        Also handles prefixed words: و/ف/ب/ك/ل + whitelist word.
+        Handles adjacent punctuation (e.g. واصدقائي، → وأصدقائي،)
+        """
+        words = text.split()
+        result = []
+        for word in words:
+            # Separate leading/trailing punctuation from the core word
+            match = re.match(r'^([\.,،؛؟!:;?\(\)\[\]«»"\'\s]*)(.*?)([\.,،؛؟!:;?\(\)\[\]«»"\'\s]*)$', word)
+            if not match or not match.group(2):
+                result.append(word)
+                continue
+                
+            lead_punct = match.group(1)
+            core_word = match.group(2)
+            trail_punct = match.group(3)
+
+            # Check exact match first
+            if core_word in AraSpellPostProcessor.HAMZA_WHITELIST:
+                result.append(lead_punct + AraSpellPostProcessor.HAMZA_WHITELIST[core_word] + trail_punct)
+                continue
+
+            # Try stripping common prefixes and looking up the remainder
+            fixed = False
+            for prefix in AraSpellPostProcessor.HAMZA_PREFIXES:
+                if core_word.startswith(prefix) and len(core_word) > len(prefix) + 1:
+                    remainder = core_word[len(prefix):]
+                    if remainder in AraSpellPostProcessor.HAMZA_WHITELIST:
+                        result.append(lead_punct + prefix + AraSpellPostProcessor.HAMZA_WHITELIST[remainder] + trail_punct)
+                        fixed = True
+                        break
+            if not fixed:
+                result.append(word)
+        return ' '.join(result)
+    
+    @staticmethod
+    def fix_ha_ta_marbuta(text: str, vocab_manager=None) -> str:
+        """
+        Smart ه → ة fix at end of words.
+        Strategy: Always prefer ة when the previous char is a consonant,
+        UNLESS the ه form is specifically a known word and the ة form is NOT.
+        """
+        PROTECTED_ENDINGS = ['لله']
+        # Words that genuinely end in ه (not ة)
+        PROTECTED_HA_WORDS = {
+            'الله', 'لله', 'فيه', 'عليه', 'منه', 'به', 'له', 'إليه',
+            'وجه', 'نزه', 'سفه', 'فقه', 'نبه', 'شبه', 'مكره', 'تنبه',
+            'اتجه', 'توجه', 'تشابه',
+        }
+        words = text.split()
+        result = []
+        for word in words:
+            if any(word.endswith(e) for e in PROTECTED_ENDINGS):
+                result.append(word)
+                continue
+            if word in PROTECTED_HA_WORDS:
+                result.append(word)
+                continue
+            if len(word) >= 3 and word.endswith('ه'):
+                if word[-2] in AraSpellPostProcessor.ARABIC_CONSONANTS:
+                    candidate_with_ta = word[:-1] + 'ة'
+                    # Default: prefer ة (correct Arabic orthography for feminine nouns)
+                    if vocab_manager:
+                        ta_iv = vocab_manager.is_iv(candidate_with_ta)
+                        ha_iv = vocab_manager.is_iv(word)
+                        if ta_iv:
+                            # Always prefer ة when it's a valid word
+                            result.append(candidate_with_ta)
+                            continue
+                        elif ha_iv:
+                            result.append(word)
+                            continue
+                    # No vocab manager — default to ة
+                    result.append(candidate_with_ta)
+                    continue
+            result.append(word)
+        return ' '.join(result)
+    
+    # --- Hallucination Removal ---
+    
+    @staticmethod
+    def remove_hallucinations(text: str) -> str:
+        """Remove model hallucinations: duplicate words, trailing 'و' artifacts."""
+        words = text.split()
+        if not words:
+            return text
+        result = []
+        i = 0
+        
+        def normalize_word(w: str) -> str:
+            w = w.replace('ال', '').replace('ة', 'ه')
+            w = re.sub(r'[أإآ]', 'ا', w)
+            return w
+        
+        while i < len(words):
+            word = words[i]
+            if len(word) > 4 and word.endswith('و'):
+                prev_char = word[-2]
+                if prev_char in 'ةهاأإآء':
+                    word = word[:-1]
+            if i + 1 < len(words):
+                next_word = words[i + 1]
+                if normalize_word(word) == normalize_word(next_word):
+                    keep = next_word if next_word.startswith('ال') and not word.startswith('ال') else word
+                    result.append(keep)
+                    i += 2
+                    continue
+            result.append(word)
+            i += 1
+        return ' '.join(result)
+    
+    @staticmethod
+    def remove_hallucinated_prefix(text: str, original: str) -> str:
+        """Remove particles (و/في) added by model if not in original"""
+        if not original:
+            return text
+        if text.startswith('و ') and not original.startswith('و'):
+            rest = text[2:].strip()
+            if AraSpellPostProcessor.normalize_special_chars(rest) == AraSpellPostProcessor.normalize_special_chars(original):
+                return rest
+        return text
+    
+    # --- Word Splitting & Merging ---
+    
+    @staticmethod
+    def merge_separated_al(text: str) -> str:
+        """Merge 'ال' separated by space: ال + كتاب → الكتاب"""
+        return re.sub(r'\bال\s+(\w+)', r'ال\1', text)
+    
+    @staticmethod
+    def join_fragments(text: str) -> str:
+        """Join short fragments with validation."""
+        words = text.split()
+        if len(words) < 2:
+            return text
+        STANDALONE_WORDS = {
+            'من', 'في', 'على', 'عن', 'مع', 'إلى', 'الى', 'حتى', 'منذ', 'خلال', 
+            'بعد', 'قبل', 'ب', 'ل', 'ك', 'و', 'أو', 'لا', 'ما', 'لم', 'لن',
+            'هو', 'هي', 'هم', 'أن', 'إن', 'كل', 'كان', 'قد', 'قال', 'ذلك',
+            'هذا', 'هذه', 'تلك', 'التي', 'الذي', 'التى', 'اللذي'
+        }
+        result = []
+        i = 0
+        while i < len(words):
+            word = words[i]
+            if i + 1 < len(words):
+                next_word = words[i + 1]
+                if word in STANDALONE_WORDS and next_word in STANDALONE_WORDS:
+                    result.append(word)
+                    i += 1
+                    continue
+                if len(next_word) == 1:
+                    result.append(word + next_word)
+                    i += 2
+                    continue
+                if len(word) >= 2 and len(next_word) >= 2 and word[-1] == next_word[0]:
+                    if not (word in STANDALONE_WORDS and next_word in STANDALONE_WORDS):
+                        result.append(word[:-1] + next_word)
+                        i += 2
+                        continue
+                if (2 <= len(word) <= 4 and 
+                    1 <= len(next_word) <= 2 and
+                    3 <= len(word) + len(next_word) <= 7):
+                    if not (word in STANDALONE_WORDS and next_word in STANDALONE_WORDS):
+                        result.append(word + next_word)
+                        i += 2
+                        continue
+            result.append(word)
+            i += 1
+        return ' '.join(result)
+    
+    # --- Main Pipelines ---
+    
+    @staticmethod
+    def full_postprocess(text: str, original: str = "", vocab_manager=None) -> str:
+        """Apply all post-processing steps."""
+        if original:
+            text = AraSpellPostProcessor.remove_hallucinated_prefix(text, original)
+        text = AraSpellPostProcessor.normalize_special_chars(text)
+        text = AraSpellPostProcessor.remove_hallucinations(text)
+        text = AraSpellPostProcessor.unified_collapse_repeated(text)
+        text = AraSpellPostProcessor.fix_hamza_conservative(text)
+        text = AraSpellPostProcessor.fix_common_hamza(text)  # Fix S3: hamza whitelist
+        text = AraSpellPostProcessor.fix_ha_ta_marbuta(text, vocab_manager=vocab_manager)
+        text = AraSpellPostProcessor.remove_word_repetition_with_wa(text)
+        text = AraSpellPostProcessor.remove_duplicate_words(text)
+        text = AraSpellPostProcessor.normalize_spaces(text)
+        return text
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# ERROR CLASSIFIER
+# ─────────────────────────────────────────────────────────────────────────────
+
+class ErrorClassifier:
+    """Classify type of spelling error"""
+    
+    NON_ARABIC_KEYBOARD = set('پگچژکەڕڤڵڎےۀۃھیټډڼڑ')
+    
+    @staticmethod
+    def has_char_substitution(text: str) -> bool:
+        return any(c in ErrorClassifier.NON_ARABIC_KEYBOARD for c in text)
+    
+    @staticmethod
+    def has_char_repetition(text: str, threshold: int = 3) -> bool:
+        return bool(re.search(r"(.)\1{" + str(threshold - 1) + ",}", text))
+    
+    @staticmethod
+    def has_word_merge(text: str, max_word_len: int = 8) -> bool:
+        words = text.split()
+        if any(len(w) > max_word_len for w in words):
+            return True
+        if len(words) == 1 and len(text) > 6:
+            return True
+        return False
+    
+    @staticmethod
+    def classify(text: str) -> ErrorType:
+        has_rep = ErrorClassifier.has_char_repetition(text)
+        has_merge = ErrorClassifier.has_word_merge(text)
+        has_sub = ErrorClassifier.has_char_substitution(text)
+        error_count = sum([has_rep, has_merge, has_sub])
+        if error_count >= 2:
+            return ErrorType.MIXED
+        elif has_sub:
+            return ErrorType.CHAR_SUBSTITUTION
+        elif has_rep:
+            return ErrorType.CHAR_REPETITION
+        elif has_merge:
+            return ErrorType.WORD_MERGE
+        else:
+            return ErrorType.CLEAN
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# RULES-BASED CORRECTOR
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class RulesBasedCorrector:
+    """Rules-based correction with keyboard proximity mapping."""
+    
+    SUBSTITUTION_MAP = {
+        'ک': 'ك', 'ی': 'ي', 'ے': 'ي',
+        'پ': 'ب', 'چ': 'ج', 'ژ': 'ز',
+        'گ': 'ك', 'ڤ': 'ف', 'ڵ': 'ل',
+        'ڕ': 'ر', 'ڎ': 'د', 'ڼ': 'ن',
+        'ټ': 'ت', 'ډ': 'د', 'ړ': 'ر',
+        'ۀ': 'ه', 'ۃ': 'ة', 'ھ': 'ه',
+        'ە': 'ه', 'ڑ': 'ر'
+    }
+    
+    PREPOSITIONS = {
+        'من', 'في', 'على', 'عن', 'مع', 'إلى', 'الى',
+        'حتى', 'منذ', 'خلال', 'بعد', 'قبل',
+        'ب', 'ل', 'ك', 'لل'
+    }
+    
+    KEYBOARD_NEIGHBORS = {
+        'ض': ['ص', 'ق'], 'ص': ['ض', 'ث', 'ق'], 'ث': ['ص', 'ق'],
+        'ق': ['ض', 'ص', 'ث', 'ف', 'غ'], 'ف': ['ق', 'غ', 'ع', 'ب'],
+        'غ': ['ق', 'ف', 'ع', 'ه'], 'ع': ['ف', 'غ', 'ه', 'خ'],
+        'ه': ['غ', 'ع', 'خ', 'ح'], 'خ': ['ع', 'ه', 'ح', 'ج'],
+        'ح': ['ه', 'خ', 'ج'], 'ج': ['خ', 'ح', 'د'],
+        'د': ['ج', 'ذ'], 'ذ': ['د'],
+        'ش': ['س', 'ي', 'ئ'], 'س': ['ش', 'ي', 'ب'],
+        'ي': ['ش', 'س', 'ب', 'ت'], 'ب': ['ي', 'س', 'ف', 'ل', 'ن'],
+        'ل': ['ب', 'ا', 'ن', 'م'], 'ا': ['ل', 'ت', 'م'],
+        'ت': ['ي', 'ا', 'ن'], 'ن': ['ب', 'ل', 'ت', 'م', 'ك'],
+        'م': ['ل', 'ا', 'ن', 'ك'], 'ك': ['ن', 'م', 'ط'],
+        'ط': ['ك', 'ظ'], 'ظ': ['ط'],
+        'ئ': ['ش', 'ء', 'ر'], 'ء': ['ئ', 'ؤ'], 'ؤ': ['ء', 'ر'],
+        'ر': ['ئ', 'ؤ', 'لا', 'ى', 'ز'], 'لا': ['ر', 'ى'],
+        'ى': ['ر', 'لا', 'ة', 'ز'], 'ة': ['ى', 'و', 'ز'],
+        'و': ['ة', 'ز'], 'ز': ['ر', 'ى', 'ة', 'و'],
+        'أ': ['ا', 'إ', 'آ'], 'إ': ['ا', 'أ'], 'آ': ['ا', 'أ'],
+    }
+    
+    @staticmethod
+    def is_keyboard_neighbor(char1: str, char2: str) -> bool:
+        neighbors = RulesBasedCorrector.KEYBOARD_NEIGHBORS.get(char1, [])
+        return char2 in neighbors
+    
+    @staticmethod
+    def fix_char_substitution(text: str) -> str:
+        for old, new in RulesBasedCorrector.SUBSTITUTION_MAP.items():
+            text = text.replace(old, new)
+        return text
+    
+    @staticmethod
+    def fix_char_repetition(text: str) -> str:
+        text = re.sub(r'([^\d\s])\1{2,}', r'\1', text)
+        return text
+    
+    @staticmethod
+    def advanced_heuristic_repair(text: str) -> str:
+        text = RulesBasedCorrector.fix_char_substitution(text)
+        text = RulesBasedCorrector.fix_char_repetition(text)
+        words = text.split()
+        processed_words = []
+        for word in words:
+            processed_words.append(RulesBasedCorrector._recursive_split(word))
+        return ' '.join(processed_words)
+
+    @staticmethod
+    def _recursive_split(word: str) -> str:
+        if len(word) < 4:
+            return word
+        separables = sorted(['من', 'في', 'على', 'عن', 'مع', 'إلى', 'الى', 'حتى', 'منذ', 'خلال', 'بعد', 'قبل'], key=len, reverse=True)
+        for sep in separables:
+            if word == sep:
+                return word
+            if word.startswith(sep):
+                remainder = word[len(sep):]
+                if len(remainder) >= 3:
+                     return sep + " " + RulesBasedCorrector._recursive_split(remainder)
+        if word.startswith('يا') and len(word) > 4:
+             return 'يا ' + RulesBasedCorrector._recursive_split(word[2:])
+        return word
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# OUTPUT VALIDATOR (Hallucination Prevention)
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class OutputValidator:
+    """Validate model outputs to prevent hallucinations"""
+    
+    @staticmethod
+    def calculate_edit_distance(s1: str, s2: str) -> int:
+        return Levenshtein.distance(s1, s2)
+    
+    @staticmethod
+    def check_character_preservation(original: str, corrected: str) -> Tuple[bool, str]:
+        chars_original = set(original)
+        chars_corrected = set(corrected)
+        if not chars_original:
+            return True, "valid"
+        intersection = chars_original & chars_corrected
+        union = chars_original | chars_corrected
+        jaccard = len(intersection) / len(union) if union else 0
+        if jaccard < 0.35:
+            return False, "low_character_similarity"
+        return True, "valid"
+
+    @staticmethod
+    def check_word_count(original: str, corrected: str) -> Tuple[bool, str]:
+        len_orig = len(original.split())
+        len_corr = len(corrected.split())
+        if len_orig == 1:
+            if len_corr <= 3:
+                return True, "valid"
+            if len(original) > 12 and len_corr <= 6:
+                return True, "valid"
+        ratio = len_corr / len_orig if len_orig > 0 else 0
+        if ratio > 2.0 or ratio < 0.5:
+             return False, "word_count_mismatch"
+        return True, "valid"
+
+    def validate(self, original: str, corrected: str, error_type: str) -> Tuple[bool, str]:
+        if not corrected or not corrected.strip():
+            return False, "empty_output"
+        original_no_space = original.replace(' ', '').replace('\u200c', '')
+        corrected_no_space = corrected.replace(' ', '').replace('\u200c', '')
+        if original_no_space == corrected_no_space:
+            return True, "space_leniency_accept"
+        len_orig = len(original)
+        len_corr = len(corrected)
+        if len_corr > len_orig * 2.5:
+             return False, "too_long"
+        if len_corr < len_orig * 0.5:
+             if error_type == ErrorType.CHAR_REPETITION:
+                 pass
+             else:
+                 return False, "too_short"
+        is_valid_count, reason = self.check_word_count(original, corrected)
+        if not is_valid_count:
+            return False, reason
+        is_valid_chars, reason = self.check_character_preservation(original, corrected)
+        if not is_valid_chars:
+             return False, reason
+        return True, "valid"
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# VOCABULARY MANAGER
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class VocabularyManager:
+    """Centralized vocabulary management for OOV/IV detection using CamelTools."""
+    
+    def __init__(self, tokenizer):
+        self.tokenizer = tokenizer
+        from camel_tools.morphology.database import MorphologyDB
+        from camel_tools.morphology.analyzer import Analyzer
+        self._db = MorphologyDB.builtin_db()
+        self.analyzer = Analyzer(self._db)
+        logger.info("VocabularyManager initialized with CamelTools Analyzer")
+    
+    def is_iv(self, word: str) -> bool:
+        clean = re.sub(r'[^\w]', '', word)
+        if not clean:
+            return True
+        return len(self.analyzer.analyze(clean)) > 0
+    
+    def is_oov(self, word: str) -> bool:
+        return not self.is_iv(word)
+    
+    def get_frequency_rank(self, word: str) -> int:
+        clean = re.sub(r'[^\w]', '', word)
+        return self.vocab_rank.get(clean, 999999)
+    
+    def all_words_iv(self, text: str) -> bool:
+        words = text.split()
+        return all(self.is_iv(w) for w in words)
+    
+    def count_oov_words(self, text: str) -> int:
+        words = text.split()
+        return sum(1 for w in words if self.is_oov(w))
+    
+    def get_oov_words(self, text: str) -> List[str]:
+        words = text.split()
+        return [w for w in words if self.is_oov(w)]
+    
+    def words_are_equivalent(self, word1: str, word2: str) -> bool:
+        norm1 = self.normalize_for_comparison(word1)
+        norm2 = self.normalize_for_comparison(word2)
+        return norm1 == norm2
+    
+    @staticmethod
+    def damerau_levenshtein_distance(s1: str, s2: str) -> int:
+        return jellyfish.damerau_levenshtein_distance(s1, s2)
+    
+    def calculate_similarity(self, original: str, corrected: str) -> float:
+        dist = self.damerau_levenshtein_distance(original, corrected)
+        max_len = max(len(original), len(corrected), 1)
+        return 1.0 - (dist / max_len)
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# WORD ALIGNER
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class WordAligner:
+    """Aligns input and output words to create hybrid corrections."""
+    
+    def __init__(self, vocab_manager):
+        self.vocab = vocab_manager
+    
+    def align_words(self, input_text: str, output_text: str) -> str:
+        input_words = input_text.split()
+        output_words = output_text.split()
+        if abs(len(input_words) - len(output_words)) > 2:
+            input_oov = self.vocab.count_oov_words(input_text)
+            output_oov = self.vocab.count_oov_words(output_text)
+            return output_text if output_oov < input_oov else input_text
+        result = []
+        min_len = min(len(input_words), len(output_words))
+        for i in range(min_len):
+            in_word = input_words[i]
+            out_word = output_words[i]
+            best_word = self._select_best_word(in_word, out_word)
+            result.append(best_word)
+        if len(output_words) > min_len:
+            result.extend(output_words[min_len:])
+        elif len(input_words) > min_len:
+            for w in input_words[min_len:]:
+                 if self.vocab.is_iv(w):
+                     result.append(w)
+        return ' '.join(result)
+    
+    def _select_best_word(self, input_word: str, output_word: str) -> str:
+        if input_word == output_word:
+            return input_word
+        in_iv = self.vocab.is_iv(input_word)
+        out_iv = self.vocab.is_iv(output_word)
+        if not in_iv and out_iv:
+            return output_word
+        if in_iv and not out_iv:
+            return input_word
+        if in_iv and out_iv:
+            # Fix S1: When only difference is ه→ة at word end, prefer ة
+            # (correct Arabic orthography — ة is the standard feminine ending)
+            if (input_word.endswith('ه') and output_word.endswith('ة')
+                    and input_word[:-1] == output_word[:-1]):
+                return output_word
+            # Fix S1: Also handle ة→ه (don't regress a correct ة to ه)
+            if (input_word.endswith('ة') and output_word.endswith('ه')
+                    and input_word[:-1] == output_word[:-1]):
+                return input_word
+            return input_word 
+        if len(input_word) == len(output_word) and len(input_word) >= 3:
+            for i in range(len(input_word)):
+                if input_word[i] != output_word[i]:
+                    hybrid = input_word[:i] + output_word[i] + input_word[i+1:]
+                    if self.vocab.is_iv(hybrid):
+                        return hybrid
+                    hybrid2 = output_word[:i] + input_word[i] + output_word[i+1:]
+                    if self.vocab.is_iv(hybrid2):
+                        return hybrid2
+        return output_word
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# SPLIT/MERGE SPECIALIST
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class SplitMergeSpecialist:
+    """Handles word splitting and merging with vocabulary validation."""
+    
+    SEPARABLE_PREFIXES = [
+        'من', 'في', 'على', 'عن', 'مع', 'إلى', 'الى', 'حتى', 'منذ', 'خلال', 
+        'بعد', 'قبل', 'بين', 'حول', 'تحت', 'فوق', 'أمام', 'وراء', 'دون',
+        'أن', 'لن', 'لم', 'قد', 'سوف', 'كي', 'إذا', 'لو', 'مثل', 'غير',
+        'يا',
+    ]
+    
+    PROTECTED_WORDS = {
+        'في', 'من', 'على', 'عن', 'مع', 'إلى', 'الى', 'ان', 'أن', 'لا', 'ما', 'هو', 'هي',
+        'لم', 'لن', 'قد', 'كل', 'كان', 'ذلك', 'هذا', 'هذه', 'التي', 'الذي', 'بين',
+    }
+    
+    ATTACHED_PREFIXES = [
+        'وال', 'بال', 'فال', 'كال', 'لل',
+        'وب', 'وف', 'ول', 'وك', 'وم', 'ون',
+        'فب', 'فل', 'فك', 'فم',
+    ]
+    
+    PRONOUN_SUFFIXES = {'كم', 'هم', 'ها', 'هن', 'كن', 'نا', 'هما', 'كما', 'تم', 'تن'}
+    
+    def __init__(self, vocab_manager):
+        self.vocab = vocab_manager
+        self.separable_prefixes = sorted(
+            self.SEPARABLE_PREFIXES, key=len, reverse=True
+        )
+    
+    def split_word(self, word: str) -> str:
+        if len(word) < 5:
+            return word
+        if self.vocab.is_iv(word):
+            return word
+        if word in self.PROTECTED_WORDS:
+            return word
+        for prefix in self.ATTACHED_PREFIXES:
+            if word.startswith(prefix):
+                remainder = word[len(prefix):]
+                if self.vocab.is_iv(remainder):
+                    return word
+                if prefix.endswith('ال') and self.vocab.is_iv(remainder):
+                    return word
+        for prefix in self.separable_prefixes:
+            if word.startswith(prefix) and len(word) > len(prefix) + 2:
+                remainder = word[len(prefix):]
+                if self.vocab.is_iv(remainder):
+                    return f"{prefix} {remainder}"
+        for i in range(3, len(word) - 2):
+            left = word[:i]
+            right = word[i:]
+            if self.vocab.is_iv(left) and self.vocab.is_iv(right):
+                return f"{left} {right}"
+        return word
+    
+    def merge_fragments(self, text: str) -> str:
+        words = text.split()
+        if len(words) < 2:
+            return text
+        result = []
+        i = 0
+        while i < len(words):
+            word = words[i]
+            if i + 1 < len(words):
+                next_word = words[i + 1]
+                merged = word + next_word
+                if len(next_word) == 1 and next_word in 'ةهاي':
+                    if self.vocab.is_iv(merged):
+                        result.append(merged)
+                        i += 2
+                        continue
+                if word == 'ال' and len(next_word) >= 2:
+                    if self.vocab.is_iv(merged):
+                        result.append(merged)
+                        i += 2
+                        continue
+                if self.vocab.is_oov(word) and self.vocab.is_oov(next_word):
+                    if self.vocab.is_iv(merged):
+                        result.append(merged)
+                        i += 2
+                        continue
+                if len(word) <= 2 and self.vocab.is_oov(word):
+                    if self.vocab.is_iv(merged):
+                        result.append(merged)
+                        i += 2
+                        continue
+                if next_word in self.PRONOUN_SUFFIXES:
+                    if self.vocab.is_iv(merged) and not self.vocab.is_iv(word):
+                        result.append(merged)
+                        i += 2
+                        continue
+                if len(word) <= 3 and len(next_word) <= 3:
+                    if len(merged) >= 5 and self.vocab.is_iv(merged):
+                        result.append(merged)
+                        i += 2
+                        continue
+            result.append(word)
+            i += 1
+        return ' '.join(result)
+    
+    def process_text(self, text: str) -> str:
+        text = self.merge_fragments(text)
+        words = text.split()
+        processed = []
+        for word in words:
+            if self.vocab.is_oov(word) and len(word) >= 4:
+                split_result = self.split_word(word)
+                processed.append(split_result)
+            else:
+                processed.append(word)
+        return ' '.join(processed)
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# EDIT DISTANCE CORRECTOR
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class EditDistanceCorrector:
+    """Generates candidates based on Levenshtein distance."""
+    
+    def __init__(self, tokenizer):
+        self.tokenizer = tokenizer
+        self.vocab = {
+            w for w in tokenizer.get_vocab().keys() 
+            if w.isalpha() and not w.startswith('##') and len(w) > 1
+        }
+        self.vocab_rank = {w: i for w, i in tokenizer.get_vocab().items()}
+
+    def edits1(self, word):
+        letters    = 'أابتثجحخدذرزسشصضطظعغفقكلمنهويءآىةئؤ'
+        splits     = [(word[:i], word[i:])    for i in range(len(word) + 1)]
+        deletes    = [L + R[1:]               for L, R in splits if R]
+        transposes = [L + R[1] + R[0] + R[2:] for L, R in splits if len(R)>1]
+        replaces   = [L + c + R[1:]           for L, R in splits if R for c in letters]
+        inserts    = [L + c + R               for L, R in splits for c in letters]
+        return set(deletes + transposes + replaces + inserts)
+
+    def edits2(self, word):
+        return (e2 for e1 in self.edits1(word) for e2 in self.edits1(e1))
+
+    def known(self, words):
+        return set(w for w in words if w in self.vocab)
+
+    def generate_candidate(self, text: str) -> str:
+        words = text.split()
+        corrected_words = []
+        for word in words:
+            clean_word = re.sub(r'[^\w]', '', word)
+            if clean_word in self.vocab:
+                corrected_words.append(word)
+                continue
+            candidates = self.known(self.edits1(clean_word))
+            if not candidates:
+                if len(clean_word) < 7: 
+                    candidates = self.known(self.edits2(clean_word))
+            if candidates:
+                best_candidate = min(candidates, key=lambda w: self.vocab_rank.get(w, 999999))
+                corrected_words.append(best_candidate)
+            else:
+                corrected_words.append(word)
+        return ' '.join(corrected_words)
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# CONTEXTUAL CORRECTOR (MLM-based) — Optional, disabled by default to save RAM
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class ContextualCorrector:
+    """MLM-based contextual correction for confusion pairs"""
+    
+    CONFUSION_PAIRS = [
+        ('ض', 'ظ'), ('ذ', 'ز'), ('ث', 'س'), ('ص', 'س'),
+        ('ط', 'ت'), ('ق', 'ك'), ('ه', 'ة'), ('ا', 'ى'),
+        ('ت', 'د'), ('د', 'ض'), ('ك', 'ق'), ('غ', 'ق'),
+        ('ج', 'ش'), ('س', 'ز'), ('ف', 'ب'), ('و', 'و'),
+        ('ؤ', 'و'), ('ئ', 'ي'), ('ء', 'أ'), ('إ', 'أ'),
+    ]
+    
+    def __init__(self, model_name: str = 'aubmindlab/bert-base-arabertv02', cache_size: int = 10000):
+        from transformers import AutoTokenizer, AutoModelForMaskedLM
+        
+        self.tokenizer = AutoTokenizer.from_pretrained(model_name)
+        self.model = AutoModelForMaskedLM.from_pretrained(model_name)
+        self.device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
+        self.model = self.model.to(self.device)
+        self.model.eval()
+        self.confusion_map = self._build_confusion_map()
+        self.cache_hits = 0
+        self.cache_misses = 0
+        self._score_cache = {}
+        self.cache_size = cache_size
+        self.vocab = self.tokenizer.get_vocab()
+    
+    def _build_confusion_map(self):
+        confusion_map = {}
+        for char1, char2 in self.CONFUSION_PAIRS:
+            if char1 not in confusion_map:
+                confusion_map[char1] = []
+            if char2 not in confusion_map:
+                confusion_map[char2] = []
+            confusion_map[char1].append(char2)
+            confusion_map[char2].append(char1)
+        return confusion_map
+    
+    def get_confusable_chars(self, char: str) -> List[str]:
+        return self.confusion_map.get(char, [])
+    
+    def generate_candidates(self, word: str) -> List[str]:
+        candidates = [word]
+        for i, char in enumerate(word):
+            confusables = self.get_confusable_chars(char)
+            for conf_char in confusables:
+                candidate = word[:i] + conf_char + word[i+1:]
+                if candidate not in candidates:
+                    candidates.append(candidate)
+        for i in range(len(word) - 1):
+            if word[i] == word[i+1]:
+                candidate = word[:i] + word[i+1:]
+                if candidate not in candidates:
+                    candidates.append(candidate)
+        COMMON_CHARS = 'ابتثجحخدذرزسشصضطظعغفقكلمنهويأإآءئؤةى'
+        for i in range(len(word) + 1):
+            for char in COMMON_CHARS:
+                candidate = word[:i] + char + word[i:]
+                if candidate in self.vocab and candidate not in candidates:
+                    candidates.append(candidate)
+        if len(word) < 7:
+            for i in range(len(word)):
+                for char in COMMON_CHARS:
+                    if char != word[i]:
+                        candidate = word[:i] + char + word[i+1:]
+                        if candidate in self.vocab and candidate not in candidates:
+                            candidates.append(candidate)
+        for i in range(len(word)):
+            candidate = word[:i] + word[i+1:]
+            if len(candidate) > 1:
+                if candidate in self.vocab and candidate not in candidates:
+                    candidates.append(candidate)
+        return candidates
+    
+    def score_with_mlm(self, text: str, position: int, word: str) -> float:
+        cache_key = f"{text}|{position}|{word}"
+        if cache_key in self._score_cache:
+            self.cache_hits += 1
+            return self._score_cache[cache_key]
+        self.cache_misses += 1
+        words = text.split()
+        if position >= len(words):
+            return 0.0
+        masked_words = words.copy()
+        masked_words[position] = '[MASK]'
+        masked_text = ' '.join(masked_words)
+        inputs = self.tokenizer(masked_text, return_tensors='pt', padding=True, truncation=True)
+        inputs = {k: v.to(self.device) for k, v in inputs.items()}
+        with torch.no_grad():
+            outputs = self.model(**inputs)
+            predictions = outputs.logits
+        mask_token_index = (inputs['input_ids'] == self.tokenizer.mask_token_id).nonzero(as_tuple=True)[1]
+        if len(mask_token_index) == 0:
+            return 0.0
+        mask_token_logits = predictions[0, mask_token_index[0], :]
+        probs = torch.softmax(mask_token_logits, dim=0)
+        word_tokens = self.tokenizer.encode(word, add_special_tokens=False)
+        if not word_tokens:
+            return 0.0
+        word_token_id = word_tokens[0]
+        score = probs[word_token_id].item()
+        if len(self._score_cache) >= self.cache_size:
+            self._score_cache.pop(next(iter(self._score_cache)))
+        self._score_cache[cache_key] = score
+        return score
+    
+    def score_candidates_batch(self, text: str, position: int, candidates: List[str]) -> dict:
+        scores = {}
+        for candidate in candidates:
+            scores[candidate] = self.score_with_mlm(text, position, candidate)
+        return scores
+    
+    def predict_masked_token(self, text: str, position: int, top_k: int = 5) -> List[Tuple[str, float]]:
+        words = text.split()
+        if position >= len(words):
+            return []
+        masked_words = words.copy()
+        masked_words[position] = '[MASK]'
+        masked_text = ' '.join(masked_words)
+        inputs = self.tokenizer(masked_text, return_tensors='pt', padding=True, truncation=True).to(self.device)
+        with torch.no_grad():
+            outputs = self.model(**inputs)
+            predictions = outputs.logits
+        mask_token_index = (inputs['input_ids'] == self.tokenizer.mask_token_id).nonzero(as_tuple=True)[1]
+        if len(mask_token_index) == 0:
+            return []
+        mask_token_logits = predictions[0, mask_token_index[0], :]
+        probs = torch.softmax(mask_token_logits, dim=0)
+        top_k_weights, top_k_indices = torch.topk(probs, top_k, sorted=True)
+        results = []
+        for i in range(top_k):
+            token_id = top_k_indices[i].item()
+            score = top_k_weights[i].item()
+            token = self.tokenizer.decode([token_id]).strip()
+            if not token.startswith("##") and token not in self.tokenizer.all_special_tokens:
+                results.append((token, score))
+        return results
+
+    def refine_sentence_with_mask(self, text: str, threshold: float = 0.001, vocab_manager=None, raw_model_output=None) -> str:
+        words = text.split()
+        refined_words = words.copy()
+        raw_words = raw_model_output.split() if raw_model_output else []
+        for i, word in enumerate(words):
+            if vocab_manager and vocab_manager.is_iv(word):
+                continue
+            if i < len(raw_words) and word == raw_words[i]:
+                continue
+            if len(word) <= 2:
+                continue
+            current_score = self.score_with_mlm(text, i, word)
+            if current_score > threshold:
+                continue
+            predictions = self.predict_masked_token(text, i, top_k=10)
+            for pred_word, pred_score in predictions:
+                if pred_word == word:
+                    continue
+                if abs(len(pred_word) - len(word)) > 1:
+                     continue
+                dist = Levenshtein.distance(word, pred_word)
+                max_len = max(len(word), len(pred_word))
+                similarity = 1.0 - (dist / max_len)
+                if similarity < 0.90:
+                    continue
+                if vocab_manager and vocab_manager.is_oov(pred_word):
+                    continue
+                if pred_score < 0.12:
+                    continue
+                is_original_common = current_score > 0.001
+                if is_original_common:
+                     if pred_score > current_score * 1000:
+                         refined_words[i] = pred_word
+                         break
+                else:
+                    if pred_score > current_score * 50 and pred_score > 0.2:
+                        refined_words[i] = pred_word
+                        break
+        return ' '.join(refined_words)
+    
+    def calculate_sentence_score(self, text: str) -> float:
+        words = text.split()
+        if not words:
+            return 0.0
+        total_score = 0.0
+        scored_words = 0
+        for i, word in enumerate(words):
+            score = self.score_with_mlm(text, i, word)
+            total_score += score
+            scored_words += 1
+        if scored_words == 0:
+            return 0.0
+        return total_score / scored_words
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# MAIN SPELL CHECKER CLASS
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class ArabicSpellChecker:
+    """Main Arabic Spell Checker class"""
+    
+    def __init__(self, model, tokenizer, device, use_contextual: bool = True):
+        self.model = model
+        self.tokenizer = tokenizer
+        self.device = device
+        
+        self.postprocessor = AraSpellPostProcessor()
+        self.classifier = ErrorClassifier()
+        self.rules = RulesBasedCorrector()
+        self.validator = OutputValidator()
+        self.vocab_manager = VocabularyManager(tokenizer)
+        self.edit_corrector = EditDistanceCorrector(tokenizer)
+        self.split_merge = SplitMergeSpecialist(self.vocab_manager)
+        self.word_aligner = WordAligner(self.vocab_manager)
+        
+        self.use_contextual = use_contextual
+        if use_contextual:
+            try:
+                logger.info("=" * 60)
+                logger.info("[MLM/CONTEXTUAL] Loading AraBERT MLM model...")
+                self.contextual = ContextualCorrector()
+                logger.info("[MLM/CONTEXTUAL] ✅ LOADED SUCCESSFULLY")
+                logger.info(f"[MLM/CONTEXTUAL] Device: {self.contextual.device}")
+                logger.info(f"[MLM/CONTEXTUAL] Vocab size: {len(self.contextual.vocab)}")
+                logger.info("=" * 60)
+            except Exception as e:
+                logger.warning("=" * 60)
+                logger.warning(f"[MLM/CONTEXTUAL] ❌ FAILED TO LOAD: {e}")
+                logger.warning("[MLM/CONTEXTUAL] Spelling will work without contextual validation")
+                logger.warning("=" * 60)
+                self.contextual = None
+                self.use_contextual = False
+        else:
+            self.contextual = None
+            logger.info("[MLM/CONTEXTUAL] Disabled by configuration (use_contextual=False)")
+
+    def _fix_repeated_end_chars(self, text: str) -> str:
+        text = re.sub(r'([ا-ي])\1+\b', r'\1', text)
+        return text
+    
+    def _fix_merged_with_errors(self, text: str) -> str:
+        text = re.sub(r'ال([ا-ي])\1+([ا-ي]{2,})', r'ال\2', text)
+        text = re.sub(r'\b([ا-ي]{3,})([ا-ي])\2+\b', r'\1\2', text)
+        return text
+
+    def _split_merged_words_linguistic(self, text: str) -> str:
+        text = re.sub(
+            r'\b(في|من|إلى|الى|حتى|منذ|خلال|بعد|قبل)(ال)?([ا-ي]{3,})',
+            r'\1 \2\3', text
+        )
+        text = re.sub(r'\b(كل)([ا-ي]{3,})', r'\1 \2', text)
+        text = re.sub(r'([ا-ي]{3,})(ال)([ا-ي]{3,})', r'\1 \2\3', text)
+        text = re.sub(r'\b([بلك])(ال)?([ا-ي]{3,})', r'\1 \2\3', text)
+        text = re.sub(r'([ا-ي]{4,})(عليكم|عليك|عليه|عليها)', r'\1 \2', text)
+        text = re.sub(r'([ا-ي]{3,})(على|عن)([ا-ي]{3,})', r'\1 \2 \3', text)
+        return text
+    
+    def _split_long_words_heuristic(self, text: str, max_length: int = 15) -> str:
+        words = text.split()
+        result = []
+        for word in words:
+            if len(word) <= max_length:
+                result.append(word)
+                continue
+            if 'ال' in word[2:]:
+                parts = word.split('ال', 1)
+                if len(parts[0]) >= 2 and len(parts[1]) >= 3:
+                    result.extend([parts[0], 'ال' + parts[1]])
+                    continue
+            if len(word) >= 8:
+                split_found = False
+                for split_pos in [2, 3]:
+                    prefix = word[:split_pos]
+                    suffix = word[split_pos:]
+                    if prefix in ['في', 'من', 'على', 'عن', 'مع', 'كل', 'ب', 'ل', 'ك']:
+                        result.extend([prefix, suffix])
+                        split_found = True
+                        break
+                if not split_found:
+                    result.append(word)
+            else:
+                result.append(word)
+        return ' '.join(result)
+    
+    def _normalize_tanween_patterns(self, text: str) -> str:
+        text = re.sub(r'([ا-ي]{2,})أ\b', r'\1اً', text)
+        text = re.sub(r'\s+أ\s+', ' ', text)
+        text = re.sub(r'\b([بلك])\s+([ا-ي])', r'\1\2', text)
+        return text
+    
+    def preprocess(self, text: str) -> str:
+        """Preprocessing pipeline"""
+        text = self.postprocessor.remove_harakat(text)
+        text = self.postprocessor.remove_tatweel(text)
+        text = self.postprocessor.normalize_special_chars(text)
+        text = self._fix_repeated_end_chars(text)
+        text = self._fix_merged_with_errors(text)
+        text = self._split_merged_words_linguistic(text)
+        text = self._split_long_words_heuristic(text)
+        text = self._normalize_tanween_patterns(text)
+        text = self.postprocessor.merge_separated_al(text)
+        text = self.postprocessor.unified_collapse_repeated(text)
+        text = self.rules.fix_char_substitution(text)
+        text = self.rules.fix_char_repetition(text)
+        text = self.postprocessor.normalize_spaces(text)
+        return text
+    
+    def postprocess(self, text: str, original: str = "") -> str:
+        """Postprocessing pipeline"""
+        return self.postprocessor.full_postprocess(text, original, vocab_manager=self.vocab_manager)
+    
+    def model_inference(self, text: str, num_return_sequences: int = 5) -> List[str]:
+        """Run seq2seq model inference and return top candidates."""
+        inputs = self.tokenizer(text, return_tensors='pt', padding=True, truncation=True, max_length=128)
+        inputs = {k: v.to(self.device) for k, v in inputs.items()}
+        with torch.no_grad():
+            outputs = self.model.generate(
+                **inputs,
+                num_beams=5,
+                num_return_sequences=num_return_sequences,
+                early_stopping=True,
+                return_dict_in_generate=True,
+                output_scores=True
+            )
+        candidates = self.tokenizer.batch_decode(outputs.sequences, skip_special_tokens=True)
+        self._last_beam_scores = {}
+        if hasattr(outputs, 'sequences_scores') and outputs.sequences_scores is not None:
+            scores = outputs.sequences_scores.tolist()
+            for cand, score in zip(candidates, scores):
+                self._last_beam_scores[cand] = score
+        return candidates
+    
+    def correct(self, text: str) -> str:
+        """
+        Main correction pipeline (RERANKING APPROACH)
+        
+        Steps:
+        1. Preprocess
+        2. Generate Candidates (Model Beams + Baseline)
+        3. Rerank Candidates (Validator + Fluency)
+        4. Select Best
+        5. Postprocess
+        """
+        if not text or not text.strip():
+            return text
+        
+        original = text
+        
+        # 1. Preprocess
+        preprocessed_text = self.preprocess(text)
+        
+        # 2. Classify error type
+        error_type = self.classifier.classify(preprocessed_text)
+        
+        # 3. Generate Candidates
+        candidates = []
+        candidates.append(preprocessed_text)
+        
+        rules_candidate = self.rules.advanced_heuristic_repair(text)
+        candidates.append(rules_candidate)
+        
+        edit_candidate = self.edit_corrector.generate_candidate(text)
+        if edit_candidate != text and edit_candidate != rules_candidate:
+            candidates.append(edit_candidate)
+        
+        raw_model_output = None
+        try:
+            model_candidates = self.model_inference(preprocessed_text, num_return_sequences=5)
+            raw_model_output = model_candidates[0] if model_candidates else None
+            candidates.extend(model_candidates)
+            
+            if model_candidates:
+                hybrid_candidate = self.word_aligner.align_words(preprocessed_text, model_candidates[0])
+                if hybrid_candidate not in candidates:
+                    candidates.append(hybrid_candidate)
+                for beam in model_candidates[1:3]:
+                    hybrid_beam = self.word_aligner.align_words(preprocessed_text, beam)
+                    if hybrid_beam not in candidates:
+                        candidates.append(hybrid_beam)
+            
+            if model_candidates and len(model_candidates) >= 3:
+                try:
+                    beam_word_lists = [c.split() for c in model_candidates]
+                    max_words = max(len(wl) for wl in beam_word_lists)
+                    voted_words = []
+                    for pos in range(max_words):
+                        words_at_pos = []
+                        for wl in beam_word_lists:
+                            if pos < len(wl):
+                                words_at_pos.append(wl[pos])
+                        if words_at_pos:
+                            most_common = Counter(words_at_pos).most_common(1)[0][0]
+                            voted_words.append(most_common)
+                    voted_candidate = ' '.join(voted_words)
+                    if voted_candidate not in candidates:
+                        candidates.append(voted_candidate)
+                except Exception:
+                    pass
+        except Exception as e:
+            logger.warning(f"Model inference failed: {e}")
+        
+        # Remove duplicates
+        unique_candidates = []
+        seen = set()
+        for c in candidates:
+            if c not in seen:
+                unique_candidates.append(c)
+                seen.add(c)
+        candidates = unique_candidates
+        
+        # 4. Rerank Candidates
+        best_candidate = preprocessed_text
+        best_score = -1.0
+        candidate_scores = []
+        
+        for cand in candidates:
+            is_valid, reason = self.validator.validate(original, cand, error_type.value)
+            if len(cand) < len(original) * 0.5:
+                is_valid = False
+                reason = "too_short"
+
+            input_oov_count = self.vocab_manager.count_oov_words(original)
+            cand_oov_count = self.vocab_manager.count_oov_words(cand)
+            vocab_boost = 1.0
+            
+            if input_oov_count > 0 and cand_oov_count < input_oov_count:
+                oov_reduction = input_oov_count - cand_oov_count
+                vocab_boost = 1.0 + (oov_reduction * 0.3)
+                if cand_oov_count == 0 and self.vocab_manager.all_words_iv(cand):
+                    if not is_valid and reason not in ["empty_output"]:
+                        is_valid = True
+                        reason = "vocab_aware_accept"
+            elif cand_oov_count > input_oov_count:
+                vocab_boost = 0.5
+            elif input_oov_count == 0 and cand_oov_count == 0:
+                vocab_boost = 1.0
+            
+            validity_factor = 1.0 if is_valid else 0.001
+            
+            fluency_score = 0.0
+            if self.use_contextual and self.contextual:
+                try:
+                    fluency_score = self.contextual.calculate_sentence_score(cand)
+                except Exception as e:
+                    logger.warning(f"Scoring failed: {e}")
+                    fluency_score = 0.5
+            else:
+                fluency_score = 1.0 
+            
+            dist = VocabularyManager.damerau_levenshtein_distance(preprocessed_text, cand)
+            max_len = max(len(preprocessed_text), len(cand), 1)
+            similarity = 1.0 - (dist / max_len)
+            if cand == preprocessed_text:
+                similarity = 1.0
+            
+            keyboard_bonus = 1.0
+            input_words = preprocessed_text.split()
+            cand_words = cand.split()
+            if len(input_words) == len(cand_words):
+                for iw, cw in zip(input_words, cand_words):
+                    if iw != cw and len(iw) == len(cw):
+                        for ic, cc in zip(iw, cw):
+                            if ic != cc and RulesBasedCorrector.is_keyboard_neighbor(ic, cc):
+                                keyboard_bonus *= 1.05
+            
+            if fluency_score > 0.85 and cand_oov_count == 0:
+                 if not is_valid and reason in ["too_short", "low_character_similarity", "word_count_mismatch"]:
+                      if len(cand) >= len(original) * 0.4:
+                          is_valid = True
+                          reason = "high_confidence_override"
+                          vocab_boost *= 1.2
+                          validity_factor = 1.0
+            
+            fluency_exp = 0.3
+            similarity_exp = 3.0
+            beam_boost = 1.0
+            if raw_model_output and cand == raw_model_output:
+                beam_boost = 1.15
+            
+            final_score = (fluency_score ** fluency_exp) * (similarity ** similarity_exp) * validity_factor * vocab_boost * keyboard_bonus * beam_boost
+            
+            candidate_scores.append({
+                'text': cand, 'is_valid': is_valid, 'reason': reason,
+                'fluency': fluency_score, 'similarity': similarity,
+                'vocab_boost': vocab_boost, 'input_oov': input_oov_count,
+                'cand_oov': cand_oov_count, 'final_score': final_score
+            })
+            
+            if final_score > best_score:
+                best_score = final_score
+                best_candidate = cand
+        
+        # Output Quality Scoring
+        if best_candidate != preprocessed_text:
+            preprocessed_score = 0.0
+            for cs in candidate_scores:
+                if cs['text'] == preprocessed_text:
+                    preprocessed_score = cs['final_score']
+                    break
+            if preprocessed_score > 0 and best_score < preprocessed_score * 1.05:
+                best_oov = self.vocab_manager.count_oov_words(best_candidate)
+                prep_oov = self.vocab_manager.count_oov_words(preprocessed_text)
+                if best_oov > prep_oov:
+                    best_candidate = preprocessed_text
+                    best_score = preprocessed_score
+        
+        # Contextual Validation Layer
+        if best_candidate != preprocessed_text and self.use_contextual and self.contextual:
+            try:
+                input_fluency = self.contextual.calculate_sentence_score(preprocessed_text)
+                best_fluency = 0.0
+                for cs in candidate_scores:
+                    if cs['text'] == best_candidate:
+                        best_fluency = cs['fluency']
+                        break
+                if input_fluency > 0 and best_fluency > 0:
+                    if input_fluency > best_fluency * 1.5:
+                        input_oov = self.vocab_manager.count_oov_words(preprocessed_text)
+                        best_oov = self.vocab_manager.count_oov_words(best_candidate)
+                        if input_oov <= best_oov:
+                            best_candidate = preprocessed_text
+            except Exception:
+                pass
+        
+        # 5. Postprocess Winner
+        result = self.postprocess(best_candidate, original)
+        
+        # IV-Safe Postprocessing Check
+        if result != best_candidate:
+            result_words = result.split()
+            best_words = best_candidate.split()
+            if len(result_words) == len(best_words):
+                fixed_words = []
+                for idx_fw, (rw, bw) in enumerate(zip(result_words, best_words)):
+                    if rw != bw:
+                        bw_iv = self.vocab_manager.is_iv(bw)
+                        rw_iv = self.vocab_manager.is_iv(rw)
+                        if bw_iv and not rw_iv:
+                            fixed_words.append(bw)
+                        else:
+                            fixed_words.append(rw)
+                    else:
+                        fixed_words.append(rw)
+                result = ' '.join(fixed_words)
+        
+        # 6. Contextual fine-tuning
+        if self.use_contextual and self.contextual:
+             if len(result) > 3:
+                 result = self.contextual.refine_sentence_with_mask(
+                     result, vocab_manager=self.vocab_manager,
+                     raw_model_output=raw_model_output
+                 )
+        
+        # 7. Safe Split/Merge Post-processing
+        result = self.split_merge.merge_fragments(result)
+        
+        # 8. Output Stability Test
+        if result != preprocessed_text and raw_model_output:
+            try:
+                re_preprocessed = self.preprocess(result)
+                stability_dist = VocabularyManager.damerau_levenshtein_distance(result, re_preprocessed)
+                result_len = max(len(result), 1)
+                if stability_dist > 0:
+                    stability_ratio = stability_dist / result_len
+                    if stability_ratio > 0.15:
+                        raw_re = self.preprocess(raw_model_output)
+                        raw_stability = VocabularyManager.damerau_levenshtein_distance(
+                            raw_model_output, raw_re
+                        ) / max(len(raw_model_output), 1)
+                        if raw_stability < stability_ratio:
+                            raw_oov = self.vocab_manager.count_oov_words(raw_model_output)
+                            our_oov = self.vocab_manager.count_oov_words(result)
+                            if raw_oov <= our_oov:
+                                result = raw_model_output
+            except Exception:
+                pass
+        
+        # 9. Bidirectional Word-Level Validation
+        if raw_model_output and result != raw_model_output:
+            result_words = result.split()
+            raw_words = raw_model_output.split()
+            if len(result_words) == len(raw_words):
+                corrected_words = []
+                changed = False
+                for rw, raw_w in zip(result_words, raw_words):
+                    if rw != raw_w:
+                        rw_iv = self.vocab_manager.is_iv(rw)
+                        raw_iv = self.vocab_manager.is_iv(raw_w)
+                        if not rw_iv and raw_iv:
+                            corrected_words.append(raw_w)
+                            changed = True
+                        elif rw_iv and raw_iv:
+                            input_words_list = preprocessed_text.split()
+                            idx = len(corrected_words)
+                            if idx < len(input_words_list):
+                                input_w = input_words_list[idx]
+                                rw_dist = Levenshtein.distance(input_w, rw)
+                                raw_dist = Levenshtein.distance(input_w, raw_w)
+                                if raw_dist < rw_dist:
+                                    corrected_words.append(raw_w)
+                                    changed = True
+                                else:
+                                    corrected_words.append(rw)
+                            else:
+                                corrected_words.append(rw)
+                        else:
+                            corrected_words.append(rw)
+                    else:
+                        corrected_words.append(rw)
+                if changed:
+                    new_result = ' '.join(corrected_words)
+                    new_oov = self.vocab_manager.count_oov_words(new_result)
+                    old_oov = self.vocab_manager.count_oov_words(result)
+                    if new_oov <= old_oov:
+                        result = new_result
+        
+        # 10. SAFETY NET
+        if raw_model_output and raw_model_output != result:
+            raw_oov = self.vocab_manager.count_oov_words(raw_model_output)
+            our_oov = self.vocab_manager.count_oov_words(result)
+            if raw_oov == 0 and our_oov > 0:
+                is_valid, reason = self.validator.validate(original, raw_model_output, "mixed")
+                if is_valid or reason == "space_leniency_accept":
+                    result = raw_model_output
+            elif raw_oov == 0 and our_oov == 0:
+                raw_dist = VocabularyManager.damerau_levenshtein_distance(original, raw_model_output)
+                our_dist = VocabularyManager.damerau_levenshtein_distance(original, result)
+                result_vs_raw_dist = VocabularyManager.damerau_levenshtein_distance(result, raw_model_output)
+                if raw_dist < our_dist and result_vs_raw_dist <= 3:
+                    raw_valid, _ = self.validator.validate(original, raw_model_output, "mixed")
+                    if raw_valid:
+                        result = raw_model_output
+            elif raw_oov == 0:
+                raw_wc = len(raw_model_output.split())
+                our_wc = len(result.split())
+                if raw_wc != our_wc:
+                    raw_dist = VocabularyManager.damerau_levenshtein_distance(original, raw_model_output)
+                    our_dist = VocabularyManager.damerau_levenshtein_distance(original, result)
+                    if raw_dist < our_dist:
+                        raw_valid, _ = self.validator.validate(original, raw_model_output, "mixed")
+                        if raw_valid:
+                            result = raw_model_output
+        # ── FINAL PASS: Hamza whitelist + Ta Marbuta fixes (unrevertable) ──
+        # These are applied AFTER all validation/safety steps so they can't
+        # be undone by Steps 8-10 which compare against raw_model_output.
+        # The root issue: Steps 8-10 use edit distance to INPUT (which has errors)
+        # so they revert corrections back to the erroneous form.
+        result = AraSpellPostProcessor.fix_common_hamza(result)
+        result = AraSpellPostProcessor.fix_ha_ta_marbuta(result, vocab_manager=self.vocab_manager)
+
+        # 11. DESTRUCTIVE TOKENIZATION GUARD
+        # Arabic orthography does not use standalone 1-letter words except prepositions.
+        # If the model creates a standalone 1-letter word that was not in the original,
+        # check if it's a legitimate prefix separation (e.g. بالشاروع→ب الشارع).
+        orig_standalone = set(w for w in original.split() if len(w) == 1)
+        orig_words = original.split()
+        res_words_list = result.split()
+        for idx, w in enumerate(res_words_list):
+            if len(w) == 1 and w not in orig_standalone:
+                if w in 'واتيبلفك':
+                    # Check if this is a legitimate prefix separation:
+                    # The original word should have started with this letter as a prefix
+                    is_prefix_separation = False
+                    if w in 'وفبلك' and idx + 1 < len(res_words_list):
+                        next_word = res_words_list[idx + 1]
+                        combined = w + next_word
+                        # If any original word started with the prefix letter and
+                        # the remainder matches the next word, it's legitimate
+                        for ow in orig_words:
+                            if ow.startswith(w) and len(ow) > 2:
+                                is_prefix_separation = True
+                                break
+                    
+                    if not is_prefix_separation:
+                        logger.info(f"[SPELLING] Blocked destructive tokenization (hallucinated standalone '{w}'): '{original}' -> '{result}'")
+                        result = original
+                        break
+
+        # 12. MORPHOLOGICAL MUTATION GUARD (Verb -> Noun)
+        # Prevents spelling from changing a plural verb (e.g. صممو) to a noun (e.g. مصممو) by prepending م
+        if len(orig_words) == len(res_words_list):
+            for idx in range(len(orig_words)):
+                ow = orig_words[idx]
+                rw = res_words_list[idx]
+                # If the word didn't start with م but the correction does, and it looks like a plural verb
+                if not ow.startswith('م') and rw.startswith('م') and rw[1:] == ow and ow.endswith('و'):
+                    logger.info(f"[SPELLING] Blocked morphological mutation (verb→noun '{ow}'→'{rw}')")
+                    res_words_list[idx] = ow
+            result = ' '.join(res_words_list)
+
+        return result

old_gram2.py

@@ -0,0 +1,940 @@
+# ArabicGrammarGuard — Rule-based Arabic grammar post-processing
+# Extracted from Grammer_Rules.py — uses camel-tools for morphological analysis.
+# All classes are imported by grammar_service.py.
+
+import re
+import logging
+from camel_tools.tokenizers.word import simple_word_tokenize
+from camel_tools.disambig.mle import MLEDisambiguator
+
+logger = logging.getLogger(__name__)
+
+KNOWN_FEMININE_NOUNS = {
+    'السيارة', 'سيارة', 'المدرسة', 'مدرسة', 'المدينة', 'مدينة',
+    'البنت', 'الشمس', 'الأرض', 'الطالبة', 'طالبة',
+    'الجامعة', 'جامعة', 'الشركة', 'شركة', 'الحكومة', 'حكومة',
+    'الغرفة', 'غرفة', 'الحديقة', 'حديقة', 'المكتبة', 'مكتبة',
+    'الدولة', 'دولة', 'الرحلة', 'رحلة', 'اللغة', 'لغة',
+    'القصة', 'قصة', 'الفكرة', 'فكرة', 'النتيجة', 'نتيجة',
+}
+
+# Common adjectives that have masculine/feminine pairs
+MASC_TO_FEM_ADJ = {
+    'جميل': 'جميلة', 'كبير': 'كبيرة', 'صغير': 'صغيرة',
+    'طويل': 'طويلة', 'قصير': 'قصيرة', 'جديد': 'جديدة',
+    'قديم': 'قديمة', 'بعيد': 'بعيدة', 'قريب': 'قريبة',
+    'سريع': 'سريعة', 'بطيء': 'بطيئة', 'واسع': 'واسعة',
+    'ضيق': 'ضيقة', 'عميق': 'عميقة', 'خفيف': 'خفيفة',
+    'ثقيل': 'ثقيلة', 'نظيف': 'نظيفة', 'مشرق': 'مشرقة',
+    'ذكي': 'ذكية', 'غني': 'غنية', 'فقير': 'فقيرة',
+    'متفوق': 'متفوقة', 'مجتهد': 'مجتهدة', 'ممتاز': 'ممتازة',
+}
+
+
+class ArabicGrammarGuard:
+    def __init__(self):
+        self.mle = MLEDisambiguator.pretrained()
+
+        self.number_words = ["واحد", "اثنان", "اثنين", "ثلاث", "أربع", "خمس", "ست", "سبع", "ثمان", "تسع", "عشر",
+                             "عشرون", "عشرين", "ثلاثون", "ثلاثين", "أربعون", "أربعين", "خمسون", "خمسين",
+                             "ستون", "ستين", "سبعون", "سبعين", "ثمانون", "ثمانين", "تسعون", "تسعين", "مائة", "ألف"]
+
+        self.asmaa_khamsa_roots = ['اب', 'اخ', 'حم', 'فو', 'ذو']
+
+    def preserve_numbers(self, original_text, generated_text):
+        orig_digits = re.findall(r'\d+', original_text)
+        gen_digits = re.findall(r'\d+', generated_text)
+        if orig_digits and gen_digits and orig_digits != gen_digits:
+            return original_text
+
+        orig_words = [w for w in original_text.split() if any(num in w for num in self.number_words)]
+        gen_words = [w for w in generated_text.split() if any(num in w for num in self.number_words)]
+        if len(orig_words) > 0 and len(gen_words) > 0:
+            if not any(orig[:3] in gen for orig in orig_words for gen in gen_words):
+                 return original_text
+        return generated_text
+
+    def fix_number_and_gender_agreement(self, text):
+        tokens = simple_word_tokenize(text)
+        disambig_tokens = self.mle.disambiguate(tokens)
+        corrected_tokens = list(tokens)
+
+        for i in range(len(disambig_tokens) - 1):
+            w1_info = disambig_tokens[i].analyses[0] if disambig_tokens[i].analyses else None
+            w2_info = disambig_tokens[i+1].analyses[0] if disambig_tokens[i+1].analyses else None
+            if not w1_info or not w2_info: continue
+
+            w1_pos = w1_info.analysis.get('pos', 'unknown')
+            w2_pos = w2_info.analysis.get('pos', 'unknown')
+            w1_word = corrected_tokens[i]
+            w2_word = corrected_tokens[i+1]
+
+            if w1_pos == 'verb' and w2_pos == 'noun':
+                if (w1_word.endswith('ون') or w1_word.endswith('وا')) and (w2_word.endswith('ون') or w2_word.endswith('ين')):
+                    if w1_word.endswith('ون'): corrected_tokens[i] = w1_word[:-2]
+                    elif w1_word.endswith('وا'): corrected_tokens[i] = w1_word[:-2]
+
+        return " ".join(corrected_tokens)
+
+    def smart_asmaa_khamsa_fix(self, text):
+        tokens = simple_word_tokenize(text)
+        disambig_tokens = self.mle.disambiguate(tokens)
+        corrected_tokens = []
+        verb_seen = False
+
+        for i, token_info in enumerate(disambig_tokens):
+            word = tokens[i]
+
+            pos_tag = token_info.analyses[0].analysis.get('pos', 'unknown') if token_info.analyses else 'unknown'
+
+            if pos_tag == 'verb':
+                verb_seen = True
+                corrected_tokens.append(word)
+                continue
+
+            is_asmaa = any(word.startswith(root) or word.startswith('أ' + root[1:]) for root in self.asmaa_khamsa_roots if len(root)>1)
+
+            if is_asmaa and len(word) >= 3:
+                if verb_seen:
+                    word = word.replace('ا', 'و').replace('ي', 'و')
+                    verb_seen = False
+
+            corrected_tokens.append(word)
+
+        return " ".join(corrected_tokens)
+
+    def _apply_jazm_to_verb(self, word, token_info):
+        # 1. Handle Af'al Khamsa using camel_tools analysis
+        if token_info and token_info.analyses:
+            analysis = token_info.analyses[0].analysis
+            num = analysis.get('num', 's')
+            per = analysis.get('per', '3')
+            gen = analysis.get('gen', 'm')
+            
+            if num == 'p' and gen == 'm':
+                if word.endswith('ون'):
+                    return word[:-2] + 'وا'
+            elif num == 'd':
+                if word.endswith('ان'):
+                    return word[:-2] + 'ا'
+            elif num == 's' and per == '2' and gen == 'f':
+                if word.endswith('ين'):
+                    return word[:-2] + 'ي'
+
+        # 2. Handle defective verbs in jazm context
+        match = re.search(r'^(.*?)([يوىاَُِْ]?)$', word)
+        if match:
+            stem = match.group(1)
+            ending = match.group(2)
+
+            fatha_bases = ['سع', 'خش', 'رض', 'نس', 'بق', 'ر', 'نه', 'حظ', 'رع', 'أب', 'تمن', 'لق', 'هو', 'سل']
+            damma_bases = ['دع', 'رج', 'شك', 'نم', 'غز', 'عف', 'سم', 'دن', 'بد', 'خل', 'عل']
+            kasra_bases = ['مش', 'جر', 'قض', 'بك', 'هد', 'رم', 'أت', 'بن', 'ق', 'وف', 'شف', 'غن', 'عط', 'تق', 'شتر', 'عتن', 'ستدع', 'نته', 'رو']
+
+            fatha_stems = {p + b for p in ['ي', 'ت', 'أ', 'ن'] for b in fatha_bases}
+            damma_stems = {p + b for p in ['ي', 'ت', 'أ', 'ن'] for b in damma_bases}
+            kasra_stems = {p + b for p in ['ي', 'ت', 'أ', 'ن'] for b in kasra_bases}
+
+            if stem in fatha_stems:
+                return stem + 'َ'
+            elif stem in damma_stems:
+                return stem + 'ُ'
+            elif stem in kasra_stems:
+                return stem + 'ِ'
+            elif ending == 'و' and len(stem) >= 2:
+                return stem + 'ُ'
+            elif ending == 'ي' and len(stem) >= 2:
+                return stem + 'ِ'
+            elif (ending == 'ى' or ending == 'ا') and len(stem) >= 2:
+                if not word.endswith('وا'):
+                    return stem + 'َ'
+
+        return word
+
+    def _apply_nasb_to_verb(self, word, token_info):
+        # 1. Handle Af'al Khamsa using camel_tools analysis
+        if token_info and token_info.analyses:
+            analysis = token_info.analyses[0].analysis
+            num = analysis.get('num', 's')
+            per = analysis.get('per', '3')
+            gen = analysis.get('gen', 'm')
+            
+            if num == 'p' and gen == 'm':
+                if word.endswith('ون'):
+                    return word[:-2] + 'وا'
+            elif num == 'd':
+                if word.endswith('ان'):
+                    return word[:-2] + 'ا'
+            elif num == 's' and per == '2' and gen == 'f':
+                if word.endswith('ين'):
+                    return word[:-2] + 'ي'
+
+        # 2. Handle defective verbs in nasb
+        if word.endswith('و') and len(word) > 3:
+            return word + 'َ'
+        elif word.endswith('ي') and len(word) > 3:
+            return word + 'َ'
+            
+        return word
+
+    def fix_verbs_nasb_and_jazm(self, text):
+        tokens = simple_word_tokenize(text)
+        disambig_tokens = self.mle.disambiguate(tokens)
+
+        nasb_particles = ['أن', 'ان', 'لن', 'كي', 'لكي', 'حتى', 'حتي', 'إذن', 'اذا']
+        jazm_particles = ['لم', 'لما', 'لا']
+
+        corrected_tokens = []
+
+        for i, token_info in enumerate(disambig_tokens):
+            word = tokens[i]
+
+            pos_tag = token_info.analyses[0].analysis.get('pos', 'unknown') if token_info.analyses else 'unknown'
+
+            is_nasb_context = False
+            is_jazm_context = False
+
+            if i > 0:
+                prev_word = tokens[i-1]
+                if prev_word in nasb_particles or word.startswith('ل'):
+                    is_nasb_context = True
+                if prev_word in jazm_particles or word.startswith('ل') or word.startswith('ول'):
+                    is_jazm_context = True
+
+            is_present_tense = word.startswith('ي') or word.startswith('ت') or word.startswith('ن') or word.startswith('أ')
+            if (pos_tag == 'verb' or is_present_tense) and (is_nasb_context or is_jazm_context):
+                if is_jazm_context:
+                    word = self._apply_jazm_to_verb(word, token_info)
+                elif is_nasb_context:
+                    word = self._apply_nasb_to_verb(word, token_info)
+
+            corrected_tokens.append(word)
+        return " ".join(corrected_tokens)
+
+    def fix_gender_agreement(self, text):
+
+        text = re.sub(r'\bأحد عشر\s+([أ-ي]+ة)\b', r'إحدى عشرة \1', text)
+        text = re.sub(r'\bأحد عشرة\s+([أ-ي]+ة)\b', r'إحدى عشرة \1', text)
+
+        text = re.sub(r'\bإحدى عشرة\s+([أ-ي]+ا|رجل[اأ]|طالب[اأ]|مهندس[اأ])\b', r'أحد عشر \1', text)
+        text = re.sub(r'\bإحدى عشر\s+([أ-ي]+ا|رجل[اأ]|طالب[اأ]|مهندس[اأ])\b', r'أحد عشر \1', text)
+
+        # ── Batch 6: Noun-adjective gender agreement ──
+        # When a feminine noun is followed by a masculine adjective, add ة
+        # e.g. السيارة جميل → السيارة جميلة
+        words = text.split()
+        for i in range(len(words) - 1):
+            noun = words[i]
+            adj = words[i + 1]
+            is_fem_noun = (noun in KNOWN_FEMININE_NOUNS or
+                          (noun.endswith('ة') and len(noun) >= 3) or
+                          (noun.startswith('ال') and noun.endswith('ة')))
+            if is_fem_noun and adj in MASC_TO_FEM_ADJ:
+                words[i + 1] = MASC_TO_FEM_ADJ[adj]
+        text = ' '.join(words)
+
+        return text
+
+    # FIX-33: Words ending in ان that are root-form nouns, NOT duals/plurals.
+    # These must never have ان→ين replacement.
+    _PREP_BLOCKLIST = {
+        'الامتحان', 'امتحان', 'الإنسان', 'إنسان', 'انسان', 'الانسان',
+        'الميدان', 'ميدان', 'البرلمان', 'برلمان', 'السلطان', 'سلطان',
+        'العنوان', 'عنوان', 'الديوان', 'ديوان', 'البستان', 'بستان',
+        'البنيان', 'بنيان', 'الإيمان', 'إيمان', 'ايمان', 'الايمان',
+        'الأمان', 'أمان', 'امان', 'الامان', 'العدوان', 'عدوان',
+        'البيان', 'بيان', 'البرهان', 'برهان', 'الشيطان', 'شيطان',
+        'الأذان', 'أذان', 'السودان', 'لبنان', 'عمان', 'الأردن',
+        'الحيوان', 'حيوان', 'القرآن', 'قرآن', 'الدخان', 'دخان',
+        'المكان', 'مكان', 'الزمان', 'زمان', 'الجدران', 'جدران',
+        'النيران', 'نيران', 'الألوان', 'ألوان', 'البلدان', 'بلدان',
+        'الأوطان', 'أوطان', 'الأبدان', 'أبدان', 'الأركان', 'أركان',
+        'الفرسان', 'فرسان', 'الغزلان', 'غزلان', 'القضبان', 'قضبان',
+    }
+
+    def fix_prepositions_advanced(self, text):
+        # Allow conjunctions (و، ف) before prepositions
+        # (في المهندسون) -> (في المهندسين)
+        # FIX-33: Use callback to skip root-form nouns ending in ان
+        def _prep_replace(m):
+            prep = m.group(1)
+            stem = m.group(2)
+            suffix = m.group(3)
+            full_word = stem + suffix
+            # Skip words in blocklist (root nouns, not duals)
+            if full_word in self._PREP_BLOCKLIST:
+                return m.group(0)  # return unchanged
+            # Skip ال-prefixed words ending in ان — almost always root nouns
+            if stem.startswith('ال') and suffix == 'ان':
+                return m.group(0)  # return unchanged
+            return f'{prep} {stem}ين'
+
+        text = re.sub(r'\b([وف]?(?:في|من|إلى|على|عن|حتى))\s+([أ-ي]{4,})(ون|ان)\b', _prep_replace, text)
+
+        # (وبالمبرمجون) -> (وبالمبرمجين)
+        # FIX-33b: Same blocklist protection as first regex
+        def _attached_prep_replace(m):
+            prefix = m.group(1)  # وب، ب، فب، ول، ل، etc.
+            stem = m.group(2)
+            suffix = m.group(3)
+            full_word = 'ال' + stem + suffix  # reconstruct with ال for blocklist check
+            if full_word in self._PREP_BLOCKLIST:
+                return m.group(0)
+            # Words ending in ان with 4+ char stems are almost always root nouns
+            if suffix == 'ان':
+                return m.group(0)
+            return f'{prefix}ال{stem}ين'
+
+        text = re.sub(r'\b([وف]?[بلكف])ال([أ-ي]{4,})(ون|ان)\b', _attached_prep_replace, text)
+
+        # (ولمهندسون) -> (ولمهندسين)
+        # FIX-33b: Same protection — reconstruct full word for blocklist
+        def _lam_prep_replace(m):
+            prefix = m.group(1)  # ول، ل، فل
+            stem = m.group(2)
+            suffix = m.group(3)
+            # Check blocklist with common prefixed forms
+            if (stem + suffix) in self._PREP_BLOCKLIST:
+                return m.group(0)
+            if suffix == 'ان':
+                return m.group(0)
+            return f'{prefix}{stem}ين'
+
+        text = re.sub(r'\b([وف]?ل)([أ-ي]{4,})(ون|ان)\b', _lam_prep_replace, text)
+        return text
+
+    def fix_kana_and_inna(self, text):
+        """
+        Fix cases (Nominative/Accusative) of nouns after Inna and Kana sisters.
+        """
+        tokens = simple_word_tokenize(text)
+        disambig_tokens = self.mle.disambiguate(tokens)
+        corrected_tokens = list(tokens)
+        
+        INNA_SISTERS = {'إن', 'أن', 'كأ��', 'لكن', 'ليت', 'لعل', 'ان'}
+        KANA_SISTERS = {'كان', 'أصبح', 'اصبح', 'أضحى', 'اضحى', 'ظل', 'أمسى', 'امسى', 'بات', 'صار', 'ليس'}
+        
+        def get_corrected_case(word, target_case, num):
+            if target_case == 'a': # Mansoub
+                if word == 'أبو': return 'أبا'
+                if word == 'أخو': return 'أخا'
+                if word == 'ذو': return 'ذا'
+                if word == 'فو': return 'فا'
+                if word == 'حمو': return 'حما'
+                if word.endswith('ون'): return word[:-2] + 'ين'
+                if word.endswith('ان'): return word[:-2] + 'ين'
+            elif target_case == 'n': # Marfoo'
+                if word in ('أبا', 'أبي'): return 'أبو'
+                if word in ('أخا', 'أخي'): return 'أخو'
+                if word in ('ذا', 'ذي'): return 'ذو'
+                if word in ('فا', 'في'): return 'فو'
+                if word in ('حما', 'حمي'): return 'حمو'
+                if word.endswith('ين'):
+                    if num == 'p': return word[:-2] + 'ون'
+                    elif num == 'd': return word[:-2] + 'ان'
+            return word
+
+        state = None # 'inna' or 'kana'
+        noun_count = 0
+        subject_num = 's'
+        
+        for i, t in enumerate(disambig_tokens):
+            word = corrected_tokens[i]
+            
+            if word in INNA_SISTERS:
+                state = 'inna'
+                noun_count = 0
+                continue
+            elif word in KANA_SISTERS:
+                state = 'kana'
+                noun_count = 0
+                continue
+                
+            if state and t.analyses:
+                analysis = t.analyses[0].analysis
+                pos = analysis.get('pos')
+                
+                # Check for nouns/adjectives
+                if pos in ('noun', 'adj', 'noun_prop'):
+                    num = analysis.get('num', 's')
+                    noun_count += 1
+                    
+                    new_word = word
+                    if state == 'inna':
+                        if noun_count == 1:
+                            subject_num = num
+                            new_word = get_corrected_case(word, 'a', num) # اسم إن منصوب
+                        elif noun_count == 2:
+                            new_word = get_corrected_case(word, 'n', subject_num) # خبر إن مرفوع
+                            state = None
+                    elif state == 'kana':
+                        if noun_count == 1:
+                            subject_num = num
+                            new_word = get_corrected_case(word, 'n', num) # اسم كان مرفوع
+                        elif noun_count == 2:
+                            new_word = get_corrected_case(word, 'a', subject_num) # خبر كان منصوب
+                            state = None
+                            
+                    if new_word != word:
+                        pattern = r'(?<![أ-يa-zA-Z])' + re.escape(word) + r'(?![أ-يa-zA-Z])'
+                        text = re.sub(pattern, new_word, text, count=1)
+                        corrected_tokens[i] = new_word
+                        
+                elif pos == 'verb':
+                    # Verb encountered, predicate might be a verbal sentence, reset to avoid false positives
+                    state = None
+            
+            # Reset state on punctuation
+            if word in {'.', '،', ':', '؟', '!', '؛'}:
+                state = None
+                
+        return text
+
+    def fix_subject_verb_agreement(self, text):
+        """
+        Fix G1: When a CONFIRMED plural noun PRECEDES a singular verb (SVO order),
+        the verb must agree in number and gender.
+
+        Arabic rule: In VSO order, verb can be singular even with plural subject.
+        But in SVO order, subject-verb agreement is required.
+
+        EXCLUSIONS:
+        - Pronouns (أنا, أنت, هو, etc.) — these are NOT plural
+        - Proper nouns — don't modify verbs after names
+        - Words tagged as singular by the disambiguator
+        """
+        tokens = simple_word_tokenize(text)
+        if len(tokens) < 2:
+            return text
+        disambig_tokens = self.mle.disambiguate(tokens)
+        corrected_tokens = list(tokens)
+
+        # Words that should NEVER trigger plural verb agreement
+        EXCLUDED_WORDS = {
+            # Pronouns (all singular/dual)
+            'أنا', 'انا', 'أنت', 'انت', 'أنتِ', 'هو', 'هي',
+            'نحن', 'أنتما', 'هما',
+            # Common words that look like nouns but aren't plural
+            'كان', 'وكان', 'كانت', 'وكانت', 'ليس', 'ليست',
+            'هذا', 'هذه', 'ذلك', 'تلك', 'هناك',
+        }
+
+        for i in range(len(disambig_tokens) - 1):
+            noun_info = disambig_tokens[i].analyses[0] if disambig_tokens[i].analyses else None
+            verb_info = disambig_tokens[i+1].analyses[0] if disambig_tokens[i+1].analyses else None
+            if not noun_info or not verb_info:
+                continue
+
+            noun_pos = noun_info.analysis.get('pos', 'unknown')
+            verb_pos = verb_info.analysis.get('pos', 'unknown')
+            noun_word = corrected_tokens[i]
+            verb_word = corrected_tokens[i+1]
+
+            # Skip excluded words
+            if noun_word in EXCLUDED_WORDS:
+                continue
+
+            # Known verbs that are frequently mistagged as nouns by the tagger without diacritics
+            KNOWN_VERBS = {'بنى', 'طبخ', 'صمم', 'لعب', 'كتب', 'شرح', 'حضر', 'تدرب', 'وافق', 'أصدر', 'اصدر', 'بني', 'عمل'}
+
+            # Only process noun → verb patterns (SVO order)
+            if noun_pos != 'noun' or (verb_pos != 'verb' and verb_word not in KNOWN_VERBS):
+                continue
+
+            noun_num = noun_info.analysis.get('num', 's')
+            noun_gen = noun_info.analysis.get('gen', 'm')
+            verb_num = verb_info.analysis.get('num', 's')
+
+            # Skip if verb is already plural
+            # Removed singular verb check to allow fixing gender mismatch on already plural verbs (e.g. البنات يذهبون -> يذهبن)
+            
+            # Only trigger on CONFIRMED plurals:
+            # 1. Known broken plural nouns (hardcoded list)
+            # 2. Sound masculine plural ending in ون/ين
+            # 3. Sound feminine plural ending in ات
+            # Do NOT rely on POS tagger alone — it misclassifies too many words
+
+            is_plural_masc = False
+            is_plural_fem = False
+
+            KNOWN_PLURALS_MASC = {
+                'الطلاب', 'طلاب', 'الرجال', 'رجال', 'الأولاد', 'أولاد',
+                'الأطباء', 'أطباء', 'الاطباء', 'اطباء',
+                'العمال', 'عمال', 'الشباب', 'الأبناء',
+                'المهندسون', 'المعلمون', 'المهندسين', 'المعلمين',
+                # FIX-08: Expanded plural lists
+                'اللاعبون', 'اللاعبين', 'لاعبون', 'لاعبين',
+                'المسلمون', 'المسلمين', 'مسلمون', 'مسلمين',
+                'العرب', 'الناس', 'الأطفال', 'أطفال', 'اطفال',
+                'الأصدقاء', 'أصدقاء', 'اصدقاء',
+                'العلماء', 'علماء', 'الأعداء', 'أعداء',
+                'الوزراء', 'وزراء', 'الأمراء', 'أمراء',
+                'الكتّاب', 'كتّاب', 'الأدباء', 'أدباء',
+                'السكان', 'سكان', 'الجنود', 'جنود',
+                'الأساتذة', 'أساتذة', 'التلاميذ', 'تلاميذ',
+                'المواطنون', 'المواطنين', 'المسؤولون', 'المسؤولين',
+                'الطلبة', 'طلبة', 'الأقارب', 'أقارب',
+            }
+            KNOWN_PLURALS_FEM = {
+                'الطالبات', 'طالبات', 'النساء', 'نساء', 'البنات', 'بنات',
+                'المعلمات', 'معلمات', 'الأمهات', 'أمهات',
+                # FIX-08: Expanded feminine plurals
+                'المهندسات', 'مهندسات', 'الطبيبات', 'طبيبات',
+                'اللاعبات', 'لاعبات', 'الممثلات', 'ممثلات',
+                'الشركات', 'شركات', 'الجامعات', 'جامعات',
+                'المدارس', 'مدارس', 'المستشفيات', 'مستشفيات',
+                'الحكومات', 'حكومات', 'المنظمات', 'منظمات',
+                'الطائرات', 'طائرات', 'السيارات', 'سيارات',
+            }
+
+            if noun_word in KNOWN_PLURALS_MASC:
+                is_plural_masc = True
+            elif noun_word in KNOWN_PLURALS_FEM:
+                is_plural_fem = True
+            elif noun_word.endswith('ون') or noun_word.endswith('ين'):
+                # Sound masculine plural — but only if 4+ chars (avoid short words)
+                if len(noun_word) >= 5:
+                    is_plural_masc = True
+            elif noun_word.endswith('ات') and len(noun_word) >= 5:
+                is_plural_fem = True
+            # FIX-08: Broken plural heuristic — common patterns
+            elif noun_num == 'p':
+                # Trust POS tagger when it says plural AND word is long enough
+                if len(noun_word) >= 4:
+                    if noun_gen == 'f':
+                        is_plural_fem = True
+                    else:
+                        is_plural_masc = True
+            
+            is_singular_fem = False
+            if not is_plural_masc and not is_plural_fem:
+                if noun_gen == 'f' or noun_word.endswith('ة') or noun_word in KNOWN_FEMININE_NOUNS:
+                    is_singular_fem = True
+                else:
+                    continue
+
+            # Fix the verb to agree with the plural subject
+            # Detect if verb is present tense (starts with ي/ت/ن/أ)
+            _is_present = (verb_word.startswith('ي') or verb_word.startswith('ت')
+                          or verb_word.startswith('ن') or verb_word.startswith('أ'))
+
+            if _is_present:
+                # Present tense: يذهب→يذهبون (masc) / يذهبن (fem)
+                if is_plural_fem:
+                    if verb_word.endswith('ون') or verb_word.endswith('ين'):
+                        verb_word = verb_word[:-2]
+                    if not verb_word.endswith('ن') and not verb_word.endswith('نَ'):
+                        corrected_tokens[i+1] = verb_word + 'ن'
+                elif is_plural_masc:
+                    if verb_word.endswith('ن') and not verb_word.endswith('ون') and not verb_word.endswith('ين'):
+                        verb_word = verb_word[:-1]
+                    if (not verb_word.endswith('ون') and not verb_word.endswith('وا')
+                            and not verb_word.endswith('ين')):
+                        if verb_word.endswith('وَ'):
+                            verb_word = verb_word[:-1]
+                        corrected_tokens[i+1] = verb_word + 'ون'
+                elif is_singular_fem:
+                    if verb_word.startswith('ي'):
+                        corrected_tokens[i+1] = 'ت' + verb_word[1:]
+            else:
+                # Past tense: ذهب→ذهبوا (masc) / ذهبن (fem)
+                if is_plural_fem:
+                    if verb_word.endswith('وا') or verb_word.endswith('ون'):
+                        verb_word = verb_word[:-2]
+                    elif verb_word.endswith('ت') or verb_word.endswith('تْ') or verb_word.endswith('تَ') or verb_word.endswith('و'):
+                        verb_word = verb_word[:-1]
+                    if not verb_word.endswith('ن') and not verb_word.endswith('نَ'):
+                        if verb_word.endswith('ى') or verb_word.endswith('ا'):
+                            verb_word = verb_word[:-1]
+                        corrected_tokens[i+1] = verb_word + 'ن'
+                elif is_plural_masc:
+                    if verb_word.endswith('ت') or verb_word.endswith('تْ') or verb_word.endswith('تَ'):
+                        verb_word = verb_word[:-1]
+                    if verb_word.endswith('ن') and not verb_word.endswith('ون') and not verb_word.endswith('ين'):
+                        verb_word = verb_word[:-1]
+                    if (not verb_word.endswith('وا') and not verb_word.endswith('ون')
+                            and not verb_word.endswith('ين')):
+                        if verb_word.endswith('وَ'):
+                            verb_word = verb_word[:-1]
+                        elif verb_word.endswith('ى') or verb_word.endswith('ا'):
+                            verb_word = verb_word[:-1]
+                        corrected_tokens[i+1] = verb_word + 'وا'
+                elif is_singular_fem:
+                    if not verb_word.endswith('ت') and not verb_word.endswith('تْ') and not verb_word.endswith('تَ'):
+                        if verb_word.endswith('ى'):
+                            verb_word = verb_word[:-1] + 'ا'
+                        corrected_tokens[i+1] = verb_word + 'ت'
+
+        return " ".join(corrected_tokens)
+
+    def regex_rules_fallback(self, text):
+        def _add_hamza(word):
+            if word.startswith('ا') and not word.startswith('ال'):
+                return 'أ' + word[1:]
+            return word
+
+        # إن وأخواتها
+        text = re.sub(r'\b(إن|أن|كأن|لكن|لعل|ليت|ان|كان)\s+(أبوك|ابوك|أخوك|اخوك|ذو|فوك)\b',
+                      lambda m: f"{m.group(1)} {_add_hamza(m.group(2)).replace('و', 'ا')}", text)
+
+        # الأفعال المتعدية (Object position)
+        text = re.sub(r'\b(رأيت|شاهدت|قابلت|زرت|سمعت|عرفت|وجدت|أحب|أكرمت|صادفت)\s+(أبوك|ابوك|أخوك|اخوك|ذو|فوك)\b',
+                      lambda m: f"{m.group(1)} {_add_hamza(m.group(2)).replace('و', 'ا')}", text)
+
+        # حروف الجر المنفصلة بمسافة (في أخوك -> في أخيك)
+        text = re.sub(r'\b([وف]?(?:في|من|إلى|الي|على|علي|عن))\s+(أبوك|ابوك|أباك|اباك|أخوك|اخوك|أخاك|اخاك|ذو|ذا)\b',
+                      lambda m: f"{m.group(1)} {_add_hamza(m.group(2)).replace('و', 'ي').replace('ا', 'ي')}", text)
+
+        # حروف الجر المتصلة بدون مسافة (بأخوك، لأبوك -> بأخيك، لأبيك)
+        text = re.sub(r'\b([وف]?[بل])(أبوك|ابوك|أباك|اباك|أخوك|اخوك|أخاك|اخاك|ذو|ذا)\b',
+                      lambda m: f"{m.group(1)}{m.group(2).replace('و', 'ي').replace('ا', 'ي')}", text)
+
+        # NOTE: Broad preposition case (ون→��ن) and nasb (ون→وا) regex rules
+        # were REMOVED because they caused massive overcorrection on correct text.
+        # These patterns are handled by CamelTools-based rules (fix_prepositions_advanced,
+        # fix_verbs_nasb_and_jazm) which have POS-tag awareness.
+        
+        # FIX-PC010: Add targeted safe regex for Nasb/Jazm particles + verb
+        # Only match clear present tense verbs starting with ي/ت/ن/أ and ending in ون
+        text = re.sub(r'\b(أن|ان|لن|كي|حتى|لم|لما)\s+([يتا][\u0600-\u06FF]{2,})ون\b',
+                      r'\1 \2وا', text)
+
+        return text
+
+    def fix_conditional_sentences(self, text):
+        conditional_particles = {'إن', 'ان', 'من', 'ما', 'متى', 'متي', 'مهما', 'أينما', 'حيثما', 'أيان', 'ايان', 'كيفما', 'أنى', 'اني'}
+        tokens = simple_word_tokenize(text)
+        disambig_tokens = self.mle.disambiguate(tokens)
+        corrected_tokens = list(tokens)
+        
+        # Lookahead for 2nd person context
+        has_2nd_person_context = any(t.endswith('كم') or t.endswith('كمو') or t.startswith('ت') for t in tokens)
+        
+        in_cond = False
+        verbs_jazmed = 0
+        
+        for i, token_info in enumerate(disambig_tokens):
+            word = corrected_tokens[i]
+            pos_tag = token_info.analyses[0].analysis.get('pos', 'unknown') if token_info.analyses else 'unknown'
+            
+            if word in conditional_particles:
+                # To prevent overcorrection (e.g. 'إن الأطباء' treating 'إن' as conditional),
+                # ensure the immediately following word is a verb.
+                next_pos = 'unknown'
+                if i + 1 < len(disambig_tokens):
+                    if disambig_tokens[i+1].analyses:
+                        next_pos = disambig_tokens[i+1].analyses[0].analysis.get('pos', 'unknown')
+                
+                if next_pos == 'verb':
+                    in_cond = True
+                    verbs_jazmed = 0
+                continue
+                
+            if in_cond and pos_tag == 'verb':
+                # Apply jazm using the comprehensive camel_tools helper
+                word = self._apply_jazm_to_verb(word, token_info)
+                    
+                # Fix pronoun mismatch if 2nd person context exists
+                if has_2nd_person_context and word.startswith('ي') and (word.endswith('وا') or word.endswith('ا') or word.endswith('ي')):
+                    word = 'ت' + word[1:]
+                    
+                corrected_tokens[i] = word
+                # Increment jazmed verbs counter (handles both فعل الشرط and جواب الشرط)
+                verbs_jazmed += 1
+                if verbs_jazmed >= 2:
+                    in_cond = False
+                    
+        return " ".join(corrected_tokens)
+
+    def fix_demonstrative_agreement(self, text):
+        tokens = simple_word_tokenize(text)
+        disambig_tokens = self.mle.disambiguate(tokens)
+        corrected_tokens = list(tokens)
+        
+        for i in range(len(disambig_tokens) - 1):
+            w1 = corrected_tokens[i]
+            w2 = corrected_tokens[i+1]
+            
+            if w1 not in ['هذا', 'هذه', 'هذان', 'هاتان', 'هذين', 'هاتين', 'هؤلاء']:
+                continue
+                
+            w2_info = disambig_tokens[i+1].analyses[0].analysis if disambig_tokens[i+1].analyses else {}
+            w2_num = w2_info.get('num', 's')
+            w2_gen = w2_info.get('gen', 'm')
+            
+            # Use heuristics to override or reinforce POS tags for duals
+            if w2.endswith('تان') or w2.endswith('تين'):
+                if w2_num == 'd':
+                    w2_gen = 'f'
+            
+            if w2_num == 'd':
+                is_nom = w2.endswith('ان') or w2.endswith('تان')
+                if w2_gen == 'f':
+                    corrected_tokens[i] = 'هاتان' if is_nom else 'هاتين'
+                elif w2_gen == 'm':
+                    corrected_tokens[i] = 'هذان' if is_nom else 'هذين'
+                    
+        return " ".join(corrected_tokens)
+
+    def fix_noun_adjective_agreement_advanced(self, text):
+        tokens = simple_word_tokenize(text)
+        disambig_tokens = self.mle.disambiguate(tokens)
+        corrected_tokens = list(tokens)
+        
+        for i in range(len(disambig_tokens) - 1):
+            w1 = corrected_tokens[i]
+            w2 = corrected_tokens[i+1]
+            
+            w1_info = disambig_tokens[i].analyses[0].analysis if disambig_tokens[i].analyses else {}
+            w1_pos = w1_info.get('pos', 'unknown')
+            w1_num = w1_info.get('num', 's')
+            w1_gen = w1_info.get('gen', 'm')
+            
+            # Heuristic override for duals (camel_tools sometimes gets them wrong)
+            if w1.endswith('تان') or w1.endswith('تين'):
+                w1_gen = 'f'
+                w1_num = 'd'
+            elif w1.endswith('ان') or w1.endswith('ين'):
+                if len(w1) > 4:
+                    w1_num = 'd'
+            
+            # Dual Adjective Agreement
+            if w1_num == 'd' and w1_pos in ['noun', 'unknown', 'noun_prop']:
+                base_adj = None
+                for suffix in ['ان', 'ين', 'تان', 'تين', 'ة', 'ون', 'ات', '']:
+                    stem = w2[:-len(suffix)] if suffix else w2
+                    if stem in MASC_TO_FEM_ADJ:
+                        base_adj = stem
+                        break
+                
+                if base_adj:
+                    is_nom = w1.endswith('ان') or w1.endswith('تان')
+                    if w1_gen == 'f':
+                        corrected_tokens[i+1] = base_adj + ('تان' if is_nom else 'تين')
+                    else:
+                        corrected_tokens[i+1] = base_adj + ('ان' if is_nom else 'ين')
+                        
+            # Plural Human Adjective Agreement
+            elif w1_num == 'p' and w1_pos in ['noun', 'unknown']:
+                base_adj = None
+                for suffix in ['ان', 'ين', 'تان', 'تين', 'ة', 'ون', 'ات', 'ين', '']:
+                    stem = w2[:-len(suffix)] if suffix else w2
+                    if stem in MASC_TO_FEM_ADJ:
+                        base_adj = stem
+                        break
+                
+                if base_adj:
+                    if w1.endswith('ون') or w1.endswith('ين') or w1_gen == 'm':
+                        is_nom = w1.endswith('ون')
+                        corrected_tokens[i+1] = base_adj + ('ون' if is_nom else 'ين')
+                    elif w1.endswith('ات') or w1_gen == 'f':
+                        corrected_tokens[i+1] = base_adj + 'ات'
+
+        return " ".join(corrected_tokens)
+
+
+    def process(self, original_text, generated_text):
+        """Apply all grammar rules to model output."""
+        text = self.preserve_numbers(original_text, generated_text)
+        
+        # ── Fix Hallucinated Subject Gender ──
+        # If model incorrectly changes female subject to male, restore it.
+        orig_words = original_text.split()
+        corr_words = text.split()
+        if len(orig_words) == len(corr_words):
+            for i, (o, c) in enumerate(zip(orig_words, corr_words)):
+                o_clean = o.rstrip('.,،؛;:!؟?()[]{}«»"\'…')
+                c_clean = c.rstrip('.,،؛;:!؟?()[]{}«»"\'…')
+                # If model dropped 'ة' from a word of length >= 4
+                if o_clean.endswith('ة') and not c_clean.endswith('ة') and o_clean[:-1] == c_clean:
+                    corr_words[i] = o
+            text = " ".join(corr_words)
+
+        # Each rule is wrapped in try/except so that if camel-tools
+        # functions fail, the regex-based rules still execute.
+        for rule_name, rule_fn in [
+            ('fix_demonstrative_agreement', self.fix_demonstrative_agreement),
+            ('fix_number_and_gender_agreement', self.fix_number_and_gender_agreement),
+            ('smart_asmaa_khamsa_fix', self.smart_asmaa_khamsa_fix),
+            ('fix_verbs_nasb_and_jazm', self.fix_verbs_nasb_and_jazm),
+            ('fix_gender_agreement', self.fix_gender_agreement),
+            ('fix_noun_adjective_agreement_advanced', self.fix_noun_adjective_agreement_advanced),
+            ('fix_prepositions_advanced', self.fix_prepositions_advanced),
+            ('fix_subject_verb_agreement', self.fix_subject_verb_agreement),
+            ('fix_kana_and_inna', self.fix_kana_and_inna),
+            ('fix_conditional_sentences', self.fix_conditional_sentences),
+            ('fix_tanween_fathah', self.fix_tanween_fathah),
+            ('fix_initial_hamza', self.fix_initial_hamza),
+            ('fix_suffix_hallucination', self.fix_suffix_hallucination),
+            ('regex_rules_fallback', self.regex_rules_fallback),
+        ]:
+            try:
+                text = rule_fn(text, original_text) if rule_name == 'fix_suffix_hallucination' else rule_fn(text)
+            except Exception as e:
+                logger.warning(f"[GRAMMAR-RULES] {rule_name} failed: {e}")
+
+        text = re.sub(r'\s+', ' ', text).strip()
+        return text
+
+    def fix_suffix_hallucination(self, text, original_text):
+        """
+        Revert grammar hallucination where extra consonants are appended to pronoun suffixes.
+        Example: شجعتهم → شجعتهمت
+        """
+        orig_words = original_text.split()
+        curr_words = text.split()
+        
+        if len(orig_words) == len(curr_words):
+            for i in range(len(orig_words)):
+                ow = orig_words[i]
+                cw = curr_words[i]
+                # If the current word is just the original word + 1 consonant, and original ended in a suffix
+                if len(cw) == len(ow) + 1 and cw.startswith(ow):
+                    added_char = cw[-1]
+                    if ow.endswith(('هم', 'هن', 'كم', 'كن', 'ها', 'نا')) and added_char in 'تمةنل':
+                        curr_words[i] = ow
+                        logger.info(f"[GRAMMAR-RULES] Reverted suffix hallucination: {cw} → {ow}")
+            text = ' '.join(curr_words)
+        return text
+
+    def fix_tanween_fathah(self, text):
+        """
+        Add tanween fathah (ً) to indefinite accusative nouns ending in ا.
+        
+        Arabic rule: Words like جدا, كثيرا, قرارا should be جداً, كثيراً, قراراً.
+        The trailing ا without tanween is a common orthographic error.
+        
+        From legacy AraSpell._normalize_tanween_patterns():
+        Only apply to words >= 3 chars ending in ا where the ا is NOT part of
+        the root (e.g. NOT ما، إلى، على، أنا، هذا).
+        """
+        # Common words ending in ا that should NOT get tanween
+        _NO_TANWEEN = {
+            'ما', 'إذا', 'هذا', 'أنا', 'إلى', 'على', 'حتى', 'متى', 'لما',
+            'إلا', 'أما', 'كما', 'ربما', 'مهما',
+            'عندما', 'بينما', 'حينما', 'كلما',
+        }
+        # Words that ALWAYS get tanween
+        _ALWAYS_TANWEEN = {
+            'جدا': 'جداً',
+            'كثيرا': 'كثيراً',
+            'شكرا': 'شكراً',
+            'نظرا': 'نظراً',
+            'قليلا': 'قليلاً',
+            'أيضا': 'أيضاً',
+            'فورا': 'فوراً',
+            'سابقا': 'سابقاً',
+            'لاحقا': 'لاحقاً',
+            'حاليا': 'حالياً',
+            'تقريبا': 'تقريباً',
+            'خصوصا': 'خصوصاً',
+            'عموما': 'عموماً',
+            'دائما': 'دائماً',
+            'مباشرا': 'مباشراً',
+            'أبدا': 'أبداً',
+            'غالبا': 'غالباً',
+            'أحيانا': 'أحياناً',
+            'مثلا': 'مثلاً',
+            'قرارا': 'قراراً',
+            'جديدا': 'جديداً',
+            'كبيرا': 'كبيراً',
+            'صغيرا': 'صغيراً',
+            'طويلا': 'طويلاً',
+            'قصيرا': 'قصيراً',
+            'سريعا': 'سريعاً',
+            'بطيئا': 'بطيئاً',
+            'جيدا': 'جيداً',
+            'سيئا': 'سيئاً',
+            'عظيما': 'عظيماً',
+            'قويا': 'قوياً',
+            'ضعيفا': 'ضعيفاً',
+            'صعبا': 'صعباً',
+            'سهلا': 'سهلاً',
+            'هاما': 'هاماً',
+            'نهائيا': 'نهائياً',
+            'رسميا': 'رسمياً',
+            'تماما': 'تماماً',
+            'عاجلا': 'عاجلاً',
+            'أولا': 'أولاً',
+            'ثانيا': 'ثانياً',
+            'ثالثا': 'ثالثاً',
+            'أخيرا': 'أخيراً',
+            'حقا': 'حقاً',
+            'حقيقيا': 'حقيقياً',
+            'علميا': 'علمياً',
+            'عمليا': 'عملياً',
+        }
+        words = text.split()
+        for i, w in enumerate(words):
+            if w in _ALWAYS_TANWEEN:
+                words[i] = _ALWAYS_TANWEEN[w]
+        return ' '.join(words)
+
+    def fix_initial_hamza(self, text):
+        """
+        Fix missing hamza on initial alef for common verb/noun patterns.
+        
+        Arabic rule: أفعل-pattern verbs and certain nouns require hamza:
+        - اعلن → أعلن (أَفْعَل form IV verb)
+        - اصدر → أصدر
+        - اسلم → أسلم
+        """
+        # Common words where initial ا should be أ
+        _HAMZA_FIXES = {
+            'اعلن': 'أعلن', 'اعلنت': 'أعلنت', 'اعلنوا': 'أعلنوا',
+            'اصدر': 'أصدر', 'اصدرت': 'أصدرت', 'اصدروا': 'أصدروا',
+            'اسلم': 'أسلم', 'اسلمت': 'أسلمت', 'اسلموا': 'أسلموا',
+            'اكد': 'أكد', 'اكدت': 'أكدت', 'اكدوا': 'أكدوا',
+            'اعطى': 'أعطى', 'اعطت': 'أعطت', 'اعطوا': 'أعطوا',
+            'انجز': 'أنجز', 'انجزت': 'أنجزت', 'انجزوا': 'أنجزوا',
+            'ارسل': 'أرسل', 'ارسلت': 'أرسلت', 'ارسلوا': 'أرسلوا',
+            'اخرج': 'أخرج', 'اخرجت': 'أخرجت', 'اخرجوا': 'أخرجوا',
+            'انشأ': 'أنشأ', 'انشأت': 'أنشأت', 'انشأوا': 'أنشأوا',
+            'اضاف': 'أضاف', 'اضافت': 'أضافت', 'اضافوا': 'أضافوا',
+            'احب': 'أحب', 'احبت': 'أحبت', 'احبوا': 'أحبوا',
+            'افهم': 'أفهم', 'افهمت': 'أفهمت', 'افهموا': 'أفهموا',
+            'اعجب': 'أعجب', 'اعجبت': 'أعجبت', 'اعجبوا': 'أعجبوا',
+            'اكرم': 'أكرم', 'اكرمت': 'أكرمت', 'اكرموا': 'أكرموا',
+            'انقذ': 'أنقذ', 'انقذت': 'أنقذت', 'انقذوا': 'أنقذوا',
+            'الامهات': 'الأمهات', 'الاطفال': 'الأطفال',
+            'الامة': 'الأمة', 'الاستاذ': 'الأستاذ',
+            'ايضا': 'أيضا',
+            'اول': 'أول',
+        }
+        # Context-dependent إنّ/أنّ hamza: kasra (إ) at sentence start, fathah (أ) mid-sentence
+        _INNA_SENTENCE_INITIAL = {
+            'ان': 'إن', 'انه': 'إنه', 'انها': 'إنها',
+            'اننا': 'إننا', 'انهم': 'إنهم', 'انك': 'إنك', 'انكم': 'إنكم',
+        }
+        _ANNA_MID_SENTENCE = {
+            'ان': 'أن', 'انه': 'أنه', 'انها': 'أنها',
+            'اننا': 'أننا', 'انهم': 'أنهم', 'انك': 'أنك', 'انكم': 'أنكم',
+        }
+        _HAMZA_STEMS = {
+            'احب': 'أحب', 'افهم': 'أفهم', 'اعلن': 'أعلن',
+            'اصدر': 'أصدر', 'اسلم': 'أسلم', 'اكد': 'أكد',
+            'انجز': 'أنجز', 'ارسل': 'أرسل', 'اخرج': 'أخرج',
+            'اضاف': 'أضاف', 'اعجب': 'أعجب', 'اكرم': 'أكرم',
+            'انقذ': 'أنقذ',
+        }
+        _PRONOUN_SUFFIXES = {'ه', 'ها', 'ك', 'كم', 'كن', 'هم', 'هن', 'ني', 'نا'}
+        words = text.split()
+        for i, w in enumerate(words):
+            if w in _HAMZA_FIXES:
+                words[i] = _HAMZA_FIXES[w]
+                continue
+            # إنّ/أنّ: kasra at sentence start, fathah mid-sentence
+            _is_sent_start = (i == 0) or (words[i-1][-1] in '.؟!؛' if words[i-1] else False)
+            if _is_sent_start and w in _INNA_SENTENCE_INITIAL:
+                words[i] = _INNA_SENTENCE_INITIAL[w]
+                continue
+            if not _is_sent_start and w in _ANNA_MID_SENTENCE:
+                words[i] = _ANNA_MID_SENTENCE[w]
+                continue
+            for stem, fixed in _HAMZA_STEMS.items():
+                if w.startswith(stem) and len(w) > len(stem):
+                    suffix = w[len(stem):]
+                    if suffix in _PRONOUN_SUFFIXES:
+                        words[i] = fixed + suffix
+                        break
+        return ' '.join(words)

old_rules.py

@@ -0,0 +1,1606 @@
+# AraSpell — Arabic Spell Checker Pipeline (Rules & Classes)
+# Extracted from AraSpell.py — NO global model loading, NO Gradio dependencies.
+# All classes are imported by araspell_service.py.
+
+import re
+import math
+import logging
+import torch
+from collections import Counter
+from enum import Enum
+from typing import List, Tuple, Optional
+
+import Levenshtein
+import jellyfish
+
+logger = logging.getLogger(__name__)
+
+# ─────────────────────────────────────────────────────────────────────────────
+# ERROR TYPE ENUM
+# ─────────────────────────────────────────────────────────────────────────────
+
+class ErrorType(Enum):
+    """Types of spelling errors"""
+    CHAR_REPETITION = "char_repetition"
+    WORD_MERGE = "word_merge"
+    CHAR_SUBSTITUTION = "char_substitution"
+    MIXED = "mixed"
+    CLEAN = "clean"
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# KEYBOARD PROXIMITY (Phase 12 — from original AraSpell.py L475-520)
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class RulesBasedCorrector:
+    """Arabic keyboard-proximity and character substitution rules."""
+
+    # Arabic keyboard layout adjacency mapping
+    KEYBOARD_NEIGHBORS = {
+        'ض': ['ص', 'ق'],
+        'ص': ['ض', 'ث', 'ق'],
+        'ث': ['ص', 'ق'],
+        'ق': ['ض', 'ص', 'ث', 'ف', 'غ'],
+        'ف': ['ق', 'غ', 'ع', 'ب'],
+        'غ': ['ق', 'ف', 'ع', 'ه'],
+        'ع': ['ف', 'غ', 'ه', 'خ'],
+        'ه': ['غ', 'ع', 'خ', 'ح'],
+        'خ': ['ع', 'ه', 'ح', 'ج'],
+        'ح': ['ه', 'خ', 'ج'],
+        'ج': ['خ', 'ح', 'د'],
+        'د': ['ج', 'ذ'],
+        'ذ': ['د'],
+        'ش': ['س', 'ي', 'ئ'],
+        'س': ['ش', 'ي', 'ب'],
+        'ي': ['ش', 'س', 'ب', 'ت'],
+        'ب': ['ي', 'س', 'ف', 'ل', 'ن'],
+        'ل': ['ب', 'ا', 'ن', 'م'],
+        'ا': ['ل', 'ت', 'م'],
+        'ت': ['ي', 'ا', 'ن'],
+        'ن': ['ب', 'ل', 'ت', 'م', 'ك'],
+        'م': ['ل', 'ا', 'ن', 'ك'],
+        'ك': ['ن', 'م', 'ط'],
+        'ط': ['ك', 'ظ'],
+        'ظ': ['ط'],
+        'ئ': ['ش', 'ء', 'ر'],
+        'ء': ['ئ', 'ؤ'],
+        'ؤ': ['ء', 'ر'],
+        'ر': ['ئ', 'ؤ', 'لا', 'ى', 'ز'],
+        'لا': ['ر', 'ى'],
+        'ى': ['ر', 'لا', 'ة', 'ز'],
+        'ة': ['ى', 'و', 'ز'],
+        'و': ['ة', 'ز'],
+        'ز': ['ر', 'ى', 'ة', 'و'],
+        'أ': ['ا', 'إ', 'آ'],
+        'إ': ['ا', 'أ'],
+        'آ': ['ا', 'أ'],
+    }
+
+    @staticmethod
+    def is_keyboard_neighbor(char1: str, char2: str) -> bool:
+        """Check if two Arabic chars are adjacent on the keyboard."""
+        neighbors = RulesBasedCorrector.KEYBOARD_NEIGHBORS.get(char1, [])
+        return char2 in neighbors
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# POST PROCESSOR
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class AraSpellPostProcessor:
+    """Arabic text post-processing techniques."""
+    
+    ARABIC_HARAKAT = 'ًٌٍَُِّْ'
+    TATWEEL = 'ـ'
+    NORMALIZER_MAP = {
+        'ﻹ': 'لإ', 'ﻷ': 'لأ', 'ﻵ': 'لآ', 'ﻻ': 'لا', 'ﷲ': 'الله'
+    }
+    ARABIC_CONSONANTS = set('بتثجحخدذرزسشصضطظعغفقكلمن')
+    
+    # --- Basic Normalization ---
+    
+    @staticmethod
+    def remove_harakat(text: str) -> str:
+        """Remove Arabic diacritics"""
+        return re.sub(r'[ً-ْ]', '', text)
+    
+    @staticmethod
+    def remove_tatweel(text: str) -> str:
+        """Remove Arabic kashida/tatweel"""
+        return text.replace(AraSpellPostProcessor.TATWEEL, '')
+    
+    @staticmethod
+    def normalize_special_chars(text: str) -> str:
+        """Normalize special Arabic ligatures"""
+        for old, new in AraSpellPostProcessor.NORMALIZER_MAP.items():
+            text = text.replace(old, new)
+        return text
+    
+    # --- Core Functions ---
+    
+    @staticmethod
+    def unified_collapse_repeated(text: str) -> str:
+        """
+        Collapse repeated characters.
+        Arabic: 3+ consecutive → 1 | Latin: 2+ consecutive → 1
+        """
+        text = re.sub(r"([\u0600-\u06FF])\1{2,}", r"\1", text)
+        text = re.sub(r"([a-zA-Z])\1+", r"\1", text)
+        return text
+    
+    @staticmethod
+    def remove_duplicate_words(text: str) -> str:
+        """Remove consecutive duplicate words. e.g. كتاب كتاب → كتاب"""
+        words = text.split()
+        if len(words) < 2:
+            return text
+        result = [words[0]]
+        for i in range(1, len(words)):
+            if words[i] != words[i-1]:
+                result.append(words[i])
+        return ' '.join(result)
+    
+    @staticmethod
+    def normalize_spaces(text: str) -> str:
+        """Normalize whitespace: multiple spaces, unicode spaces, punctuation spacing."""
+        text = re.sub(r' +', ' ', text)
+        text = text.replace('\u00A0', ' ')
+        text = text.replace('\u200B', '')
+        text = text.replace('\u200C', '')
+        text = text.replace('\u200D', '')
+        text = text.strip()
+        text = re.sub(r'\s*([،؛؟!.])\s*', r'\1 ', text)
+        text = text.strip()
+        return text
+    
+    @staticmethod
+    def remove_word_repetition_with_wa(text: str) -> str:
+        """Remove word و word → word"""
+        # Bug 2.9: This deletes valid rhetorical repetition (التوكيد اللفظي) like "صنفا وصنفا"
+        # Disabled as it is highly destructive to valid Arabic.
+        return text
+    
+    # --- Hamza & Ta Marbuta Handling ---
+    
+    # Common Arabic words with hamza errors — covers the most frequent
+    # spelling mistakes in informal Arabic writing
+    HAMZA_WHITELIST = {
+        'الي': 'إلى', 'الى': 'إلى',
+        'انت': 'أنت', 'انتم': 'أنتم', 'انتي': 'أنتِ',
+        'انتو': 'أنتم', 'انتن': 'أنتن',
+        'انا': 'أنا',
+        'امس': 'أمس',
+        'لان': 'لأن', 'لانه': 'لأنه', 'لانها': 'لأنها',
+        'لانهم': 'لأنهم', 'لانك': 'لأنك',
+        'اذا': 'إذا', 'اذ': 'إذ',
+        'اي': 'أي', 'اين': 'أين',
+        'او': 'أو',
+        
+        'ان': 'أن', 'انه': 'أنه', 'انها': 'أنها', 'انهم': 'أنهم',
+        'اخر': 'آخر', 'اخرى': 'أخرى',
+        'الان': 'الآن',
+        'اول': 'أول', 'اولى': 'أولى',
+        'اصبح': 'أصبح', 'اصبحت': 'أصبحت',
+        'اكثر': 'أكثر', 'اقل': 'أقل',
+        'اعلى': 'أعلى', 'ادنى': 'أدنى',
+        'اسرع': 'أسرع', 'ابطا': 'أبطأ',
+        'اكبر': 'أكبر', 'اصغر': 'أصغر',
+        'احسن': 'أحسن', 'اسوا': 'أسوأ',
+        'امام': 'أمام',
+        'اثناء': 'أثناء',
+        'ايضا': 'أيضاً', 'ايض': 'أيضاً',
+        'اساسي': 'أساسي', 'اساسية': 'أساسية',
+        'اخي': 'أخي', 'اخت': 'أخت', 'اخو': 'أخو',
+        'ابي': 'أبي', 'اب': 'أب', 'ابو': 'أبو',
+        'اهل': 'أهل',
+        'اطفال': 'أطفال',
+        'اصدقاء': 'أصدقاء', 'اصدقائي': 'أصدقائي',
+        'اريد': 'أريد', 'احب': 'أحب',
+        'اعلم': 'أعلم',
+        'اكل': 'أكل',
+        'الايام': 'الأيام',
+        'الاطفال': 'الأطفال',
+        'الاسعار': 'الأسعار',
+        'الاولى': 'الأولى',
+        'الاخير': 'الأخير', 'الاخيرة': 'الأخيرة',
+        'واصدقائي': 'وأصدقائي',
+        # FIX-14: Additional hamza entries
+        'ابناء': 'أبناء',
+        'اجمل': 'أجمل', 'اجمع': 'أجمع',
+        'اعلن': 'أعلن', 'اعلنت': 'أعلنت',
+        'اكد': 'أكد', 'اكدت': 'أكدت',
+        'اشار': 'أشار', 'اشارت': 'أشارت',
+        'ارسل': 'أرسل', 'ارسلت': 'أرسلت',
+        'اضاف': 'أضاف', 'اضافت': 'أضافت',
+        'اخيرا': 'أخيراً', 'اخيراً': 'أخيراً',
+        'اساسا': 'أساساً', 'اساساً': 'أساساً',
+        'احيانا': 'أحياناً', 'احياناً': 'أحياناً',
+        'ابدا': 'أبداً', 'ابداً': 'أبداً',
+        'اصلا': 'أصلاً', 'اصلاً': 'أصلاً',
+        'اخبار': 'أخبار', 'اخبر': 'أخبر',
+        'امر': 'أمر', 'امور': 'أمور',
+        'اهم': 'أهم', 'اهمية': 'أهمية',
+        'اصبح': 'أصبح', 'اصل': 'أصل',
+        'اثر': 'أثر', 'اثار': 'آثار',
+        'اساء': 'أساء', 'اساس': 'أساس',
+        'استاذ': 'أستاذ', 'اسلام': 'إسلام',
+        # Batch 3: More hamza entries for remaining FN cases
+        'اسرة': 'أسرة', 'اسر': 'أسر',
+        'اعضاء': 'أعضاء', 'اعداد': 'أعداد',
+        'اعمال': 'أعمال', 'اعمار': 'أعما��',
+        'انجاز': 'إنجاز', 'انجازات': 'إنجازات',
+        'انشاء': 'إنشاء', 'انتاج': 'إنتاج',
+        'انتخابات': 'انتخابات', 'انتظار': 'انتظار',
+        'اسلامي': 'إسلامي', 'اسلامية': 'إسلامية',
+        'امكانية': 'إمكانية', 'امكان': 'إمكان',
+        'اشكالية': 'إشكالية',
+        'ادارة': 'إدارة', 'ادارية': 'إدارية',
+        'اعلام': 'إعلام', 'اعلامي': 'إعلامي',
+        'احتمال': 'احتمال', 'احتفال': 'احتفال',
+        'اقرا': 'أقرأ', 'اقرأ': 'أقرأ',
+        'اسافر': 'أسافر',
+        'احبه': 'أحبه',
+        'مسؤول': 'مسؤول', 'مسؤولية': 'مسؤولية',
+        'رؤية': 'رؤية', 'رؤيا': 'رؤيا',
+        'مؤسسة': 'مؤسسة', 'مؤتمر': 'مؤتمر',
+        'تأثير': 'تأثير', 'تأكيد': 'تأكيد',
+        'البنايه': 'البناية',
+        'جدا': 'جداً', 'جداً': 'جداً',
+        # FIX-14: Alif maqsura common errors
+        'المستشفي': 'المستشفى',
+        'مصطفي': 'مصطفى', 'موسي': 'موسى', 'عيسي': 'عيسى',
+        'هدي': 'هدى', 'بني': 'بنى',
+        'معني': 'معنى', 'مبني': 'مبنى',
+        
+        'الي': 'إلى',
+        # FIX-47: Verb+pronoun hamza entries (احبه→أحبه)
+        'احبه': 'أحبه', 'احبها': 'أحبها', 'احبك': 'أحبك',
+        'احبكم': 'أحبكم', 'احببت': 'أحببت',
+        'افهم': 'أفهم', 'افهمه': 'أفهمه', 'افهمها': 'أفهمها',
+        'افهمك': 'أفهمك',
+        'اعطي': 'أعطي', 'اعطاه': 'أعطاه', 'اعطاها': 'أعطاها',
+        'اعطى': 'أعطى', 'اعطت': 'أعطت', 'اعطيت': 'أعطيت',
+        'احتاج': 'أحتاج', 'احتاجه': 'أحتاجه',
+        'استطيع': 'أستطيع', 'استطع': 'أستطع',
+        'اتمنى': 'أتمنى', 'اتوقع': 'أتوقع',
+        'اشعر': 'أشعر', 'اظن': 'أظن', 'افضل': 'أفضل',
+        'اخاف': 'أخاف', 'اتذكر': 'أتذكر', 'اتعلم': 'أتعلم',
+        'ارجو': 'أرجو', 'اتوقف': 'أتوقف', 'انصح': 'أنصح',
+        'انسان': 'إنسان', 'انسانية': 'إنسانية',
+    }
+    
+    @staticmethod
+    def fix_hamza_conservative(text: str) -> str:
+        """Conservative Hamza normalization — only at word END, not middle."""
+        # Bug 2.5: Blindly changing أ at the end of word to ا corrupts valid orthography (قرأ -> قرا)
+        # Disabled as it is highly destructive.
+        return text
+    
+    # Attached prefixes that can precede hamza-whitelist words
+    # Ordered longest-first so وال is tried before و
+    HAMZA_PREFIXES = ['وبال', 'فبال', 'وال', 'بال', 'فال', 'كال', 'ول', 'فل',
+                      'وب', 'فب', 'وك', 'فك', 'و', 'ف', 'ب', 'ك', 'ل']
+
+    @staticmethod
+    def fix_common_hamza(text: str) -> str:
+        """
+        Fix common hamza placement errors using a whitelist.
+        Also handles prefixed words: و/ف/ب/ك/ل + whitelist word.
+        Handles adjacent punctuation (e.g. واصدقائي، → وأصدقائي،)
+        """
+        words = text.split()
+        result = []
+        for word in words:
+            # Separate leading/trailing punctuation from the core word
+            match = re.match(r'^([\.,،؛؟!:;?\(\)\[\]«»"\'\s]*)(.*?)([\.,،؛؟!:;?\(\)\[\]«»"\'\s]*)$', word)
+            if not match or not match.group(2):
+                result.append(word)
+                continue
+                
+            lead_punct = match.group(1)
+            core_word = match.group(2)
+            trail_punct = match.group(3)
+
+            # Check exact match first
+            if core_word in AraSpellPostProcessor.HAMZA_WHITELIST:
+                result.append(lead_punct + AraSpellPostProcessor.HAMZA_WHITELIST[core_word] + trail_punct)
+                continue
+
+            # Try stripping common prefixes and looking up the remainder
+            fixed = False
+            for prefix in AraSpellPostProcessor.HAMZA_PREFIXES:
+                if core_word.startswith(prefix) and len(core_word) > len(prefix) + 1:
+                    remainder = core_word[len(prefix):]
+                    if remainder in AraSpellPostProcessor.HAMZA_WHITELIST:
+                        result.append(lead_punct + prefix + AraSpellPostProcessor.HAMZA_WHITELIST[remainder] + trail_punct)
+                        fixed = True
+                        break
+            if not fixed:
+                result.append(word)
+        return ' '.join(result)
+    
+    @staticmethod
+    def fix_ha_ta_marbuta(text: str, vocab_manager=None) -> str:
+        """
+        Smart ه → ة fix at end of words.
+        Strategy: Always prefer ة when the previous char is a consonant,
+        UNLESS the ه form is specifically a known word and the ة form is NOT.
+        """
+        PROTECTED_ENDINGS = ['لله']
+        # Words that genuinely end in ه (not ة)
+        PROTECTED_HA_WORDS = {
+            'الله', 'لله', 'فيه', 'عليه', 'منه', 'به', 'له', 'إليه',
+            'وجه', 'نزه', 'سفه', 'فقه', 'نبه', 'شبه', 'مكره', 'تنبه',
+            'اتجه', 'توجه', 'تشابه',
+        }
+        words = text.split()
+        result = []
+        for word in words:
+            if any(word.endswith(e) for e in PROTECTED_ENDINGS):
+                result.append(word)
+                continue
+            if word in PROTECTED_HA_WORDS:
+                result.append(word)
+                continue
+            if len(word) >= 3 and word.endswith('ه'):
+                if word[-2] in AraSpellPostProcessor.ARABIC_CONSONANTS:
+                    candidate_with_ta = word[:-1] + 'ة'
+                    # Default: prefer ة (correct Arabic orthography for feminine nouns)
+                    if vocab_manager:
+                        ta_iv = vocab_manager.is_iv(candidate_with_ta)
+                        ha_iv = vocab_manager.is_iv(word)
+                        if ha_iv and ta_iv:
+                            # Bug 2.2: Do not prefer ة if ه is also valid (possessive pronoun)
+                            result.append(word)
+                            continue
+                        elif ta_iv:
+                            # Prefer ة when ONLY the ة form is valid
+                            result.append(candidate_with_ta)
+                            continue
+                        elif ha_iv:
+                            result.append(word)
+                            continue
+                    # No vocab manager — default to ة
+                    result.append(candidate_with_ta)
+                    continue
+            result.append(word)
+        return ' '.join(result)
+    
+    # --- Hallucination Removal ---
+    
+    @staticmethod
+    def remove_hallucinations(text: str) -> str:
+        """Remove model hallucinations: duplicate words, trailing 'و' artifacts."""
+        words = text.split()
+        if not words:
+            return text
+        result = []
+        i = 0
+        
+        def normalize_word(w: str) -> str:
+            w = w.replace('ال', '').replace('ة', 'ه')
+            w = re.sub(r'[أإآ]', 'ا', w)
+            return w
+        
+        while i < len(words):
+            word = words[i]
+            if len(word) > 4 and word.endswith('و'):
+                prev_char = word[-2]
+                if prev_char in 'ةهاأإآء':
+                    word = word[:-1]
+            if i + 1 < len(words):
+                next_word = words[i + 1]
+                # Bug 2.11: Destroys Badal structures (الأستاذ أستاذ -> الأستاذ)
+                if word == next_word: # Only remove exact duplicates, not normalized duplicates
+                    keep = next_word if next_word.startswith('ال') and not word.startswith('ال') else word
+                    result.append(keep)
+                    i += 2
+                    continue
+            result.append(word)
+            i += 1
+        return ' '.join(result)
+    
+    @staticmethod
+    def remove_hallucinated_prefix(text: str, original: str) -> str:
+        """Remove particles (و/في) added by model if not in original"""
+        if not original:
+            return text
+        if text.startswith('و ') and not original.startswith('و'):
+            rest = text[2:].strip()
+            if AraSpellPostProcessor.normalize_special_chars(rest) == AraSpellPostProcessor.normalize_special_chars(original):
+                return rest
+        return text
+    
+    # --- Word Splitting & Merging ---
+    
+    @staticmethod
+    def merge_separated_al(text: str) -> str:
+        """Merge 'ال' separated by space: ال + كتاب → الكتاب"""
+        return re.sub(r'\bال\s+(\w+)', r'ال\1', text)
+    
+    @staticmethod
+    def join_fragments(text: str) -> str:
+        """Join short fragments with validation."""
+        words = text.split()
+        if len(words) < 2:
+            return text
+        STANDALONE_WORDS = {
+            'من', 'في', 'على', 'عن', 'مع', 'إلى', 'الى', 'حتى', 'منذ', 'خلال', 
+            'بعد', 'قبل', 'ب', 'ل', 'ك', 'و', 'أو', 'لا', 'ما', 'لم', 'لن',
+            'هو', 'هي', 'هم', 'أن', 'إن', 'كل', 'كان', 'قد', 'قال', 'ذلك',
+            'هذا', 'هذه', 'تلك', 'التي', 'الذي', 'التى', 'اللذي'
+        }
+        result = []
+        i = 0
+        while i < len(words):
+            word = words[i]
+            if i + 1 < len(words):
+                next_word = words[i + 1]
+                if word in STANDALONE_WORDS and next_word in STANDALONE_WORDS:
+                    result.append(word)
+                    i += 1
+                    continue
+                if len(next_word) == 1:
+                    result.append(word + next_word)
+                    i += 2
+                    continue
+                # Bug 2.3: Destructive word merging (يوم مشمس -> يومشمس)
+                # Removed generic boundary letter merging.
+            result.append(word)
+            i += 1
+        return ' '.join(result)
+    
+    # --- Main Pipelines ---
+    
+    @staticmethod
+    def full_postprocess(text: str, original: str = "", vocab_manager=None) -> str:
+        """Apply all post-processing steps."""
+        if original:
+            text = AraSpellPostProcessor.remove_hallucinated_prefix(text, original)
+        text = AraSpellPostProcessor.normalize_special_chars(text)
+        text = AraSpellPostProcessor.remove_hallucinations(text)
+        text = AraSpellPostProcessor.unified_collapse_repeated(text)
+        text = AraSpellPostProcessor.fix_hamza_conservative(text)
+        text = AraSpellPostProcessor.fix_common_hamza(text)  # Fix S3: hamza whitelist
+        text = AraSpellPostProcessor.fix_ha_ta_marbuta(text, vocab_manager=vocab_manager)
+        text = AraSpellPostProcessor.remove_word_repetition_with_wa(text)
+        text = AraSpellPostProcessor.remove_duplicate_words(text)
+        text = AraSpellPostProcessor.normalize_spaces(text)
+        return text
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# ERROR CLASSIFIER
+# ─────────────────────────────────────────────────────────────────────────────
+
+class ErrorClassifier:
+    """Classify type of spelling error"""
+    
+    NON_ARABIC_KEYBOARD = set('پگچژکەڕڤڵڎےۀۃھیټډڼڑ')
+    
+    @staticmethod
+    def has_char_substitution(text: str) -> bool:
+        return any(c in ErrorClassifier.NON_ARABIC_KEYBOARD for c in text)
+    
+    @staticmethod
+    def has_char_repetition(text: str, threshold: int = 3) -> bool:
+        return bool(re.search(r"(.)\1{" + str(threshold - 1) + ",}", text))
+    
+    @staticmethod
+    def has_word_merge(text: str, max_word_len: int = 8) -> bool:
+        words = text.split()
+        if any(len(w) > max_word_len for w in words):
+            return True
+        if len(words) == 1 and len(text) > 6:
+            return True
+        return False
+    
+    @staticmethod
+    def classify(text: str) -> ErrorType:
+        has_rep = ErrorClassifier.has_char_repetition(text)
+        has_merge = ErrorClassifier.has_word_merge(text)
+        has_sub = ErrorClassifier.has_char_substitution(text)
+        error_count = sum([has_rep, has_merge, has_sub])
+        if error_count >= 2:
+            return ErrorType.MIXED
+        elif has_sub:
+            return ErrorType.CHAR_SUBSTITUTION
+        elif has_rep:
+            return ErrorType.CHAR_REPETITION
+        elif has_merge:
+            return ErrorType.WORD_MERGE
+        else:
+            return ErrorType.CLEAN
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# RULES-BASED CORRECTOR
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class RulesBasedCorrector:
+    """Rules-based correction with keyboard proximity mapping."""
+    
+    SUBSTITUTION_MAP = {
+        'ک': 'ك', 'ی': 'ي', 'ے': 'ي',
+        'پ': 'ب', 'چ': 'ج', 'ژ': 'ز',
+        'گ': 'ك', 'ڤ': 'ف', 'ڵ': 'ل',
+        'ڕ': 'ر', 'ڎ': 'د', 'ڼ': 'ن',
+        'ټ': 'ت', 'ډ': 'د', 'ړ': 'ر',
+        'ۀ': 'ه', 'ۃ': 'ة', 'ھ': 'ه',
+        'ە': 'ه', 'ڑ': 'ر'
+    }
+    
+    PREPOSITIONS = {
+        'من', 'في', 'على', 'عن', 'مع', 'إلى', 'الى',
+        'حتى', 'منذ', 'خلال', 'بعد', 'قبل',
+        'ب', 'ل', 'ك', 'لل'
+    }
+    
+    KEYBOARD_NEIGHBORS = {
+        'ض': ['ص', 'ق'], 'ص': ['ض', 'ث', 'ق'], 'ث': ['ص', 'ق'],
+        'ق': ['ض', 'ص', 'ث', 'ف', 'غ'], 'ف': ['ق', 'غ', 'ع', 'ب'],
+        'غ': ['ق', 'ف', 'ع', 'ه'], 'ع': ['ف', 'غ', 'ه', 'خ'],
+        'ه': ['غ', 'ع', 'خ', 'ح'], 'خ': ['ع', 'ه', 'ح', 'ج'],
+        'ح': ['ه', 'خ', 'ج'], 'ج': ['خ', 'ح', 'د'],
+        'د': ['ج', 'ذ'], 'ذ': ['د'],
+        'ش': ['س', 'ي', 'ئ'], 'س': ['ش', 'ي', 'ب'],
+        'ي': ['ش', 'س', 'ب', 'ت'], 'ب': ['ي', 'س', 'ف', 'ل', 'ن'],
+        'ل': ['ب', 'ا', 'ن', 'م'], 'ا': ['ل', 'ت', 'م'],
+        'ت': ['ي', 'ا', 'ن'], 'ن': ['ب', 'ل', 'ت', 'م', 'ك'],
+        'م': ['ل', 'ا', 'ن', 'ك'], 'ك': ['ن', 'م', 'ط'],
+        'ط': ['ك', 'ظ'], 'ظ': ['ط'],
+        'ئ': ['ش', 'ء', 'ر'], 'ء': ['ئ', 'ؤ'], 'ؤ': ['ء', 'ر'],
+        'ر': ['ئ', 'ؤ', 'لا', 'ى', 'ز'], 'لا': ['ر', 'ى'],
+        'ى': ['ر', 'لا', 'ة', 'ز'], 'ة': ['ى', 'و', 'ز'],
+        'و': ['ة', 'ز'], 'ز': ['ر', 'ى', 'ة', 'و'],
+        'أ': ['ا', 'إ', 'آ'], 'إ': ['ا', 'أ'], 'آ': ['ا', 'أ'],
+    }
+    
+    @staticmethod
+    def is_keyboard_neighbor(char1: str, char2: str) -> bool:
+        neighbors = RulesBasedCorrector.KEYBOARD_NEIGHBORS.get(char1, [])
+        return char2 in neighbors
+    
+    @staticmethod
+    def fix_char_substitution(text: str) -> str:
+        for old, new in RulesBasedCorrector.SUBSTITUTION_MAP.items():
+            text = text.replace(old, new)
+        return text
+    
+    @staticmethod
+    def fix_char_repetition(text: str) -> str:
+        text = re.sub(r'([^\d\s])\1{2,}', r'\1', text)
+        return text
+    
+    @staticmethod
+    def advanced_heuristic_repair(text: str) -> str:
+        text = RulesBasedCorrector.fix_char_substitution(text)
+        text = RulesBasedCorrector.fix_char_repetition(text)
+        words = text.split()
+        processed_words = []
+        for word in words:
+            processed_words.append(RulesBasedCorrector._recursive_split(word))
+        return ' '.join(processed_words)
+
+    @staticmethod
+    def _recursive_split(word: str) -> str:
+        if len(word) < 4:
+            return word
+        separables = sorted(['من', 'في', 'على', 'عن', 'مع', 'إلى', 'الى', 'حتى', 'منذ', 'خلال', 'بعد', 'قبل'], key=len, reverse=True)
+        for sep in separables:
+            if word == sep:
+                return word
+            if word.startswith(sep):
+                remainder = word[len(sep):]
+                if len(remainder) >= 3:
+                     return sep + " " + RulesBasedCorrector._recursive_split(remainder)
+        if word.startswith('يا') and len(word) > 4:
+             return 'يا ' + RulesBasedCorrector._recursive_split(word[2:])
+        return word
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# OUTPUT VALIDATOR (Hallucination Prevention)
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class OutputValidator:
+    """Validate model outputs to prevent hallucinations"""
+    
+    @staticmethod
+    def calculate_edit_distance(s1: str, s2: str) -> int:
+        return Levenshtein.distance(s1, s2)
+    
+    @staticmethod
+    def check_character_preservation(original: str, corrected: str) -> Tuple[bool, str]:
+        chars_original = set(original)
+        chars_corrected = set(corrected)
+        if not chars_original:
+            return True, "valid"
+        intersection = chars_original & chars_corrected
+        union = chars_original | chars_corrected
+        jaccard = len(intersection) / len(union) if union else 0
+        if jaccard < 0.35:
+            return False, "low_character_similarity"
+        return True, "valid"
+
+    @staticmethod
+    def check_word_count(original: str, corrected: str) -> Tuple[bool, str]:
+        len_orig = len(original.split())
+        len_corr = len(corrected.split())
+        if len_orig == 1:
+            if len_corr <= 3:
+                return True, "valid"
+            if len(original) > 12 and len_corr <= 6:
+                return True, "valid"
+        ratio = len_corr / len_orig if len_orig > 0 else 0
+        if ratio > 2.0 or ratio < 0.5:
+             return False, "word_count_mismatch"
+        return True, "valid"
+
+    def validate(self, original: str, corrected: str, error_type: str) -> Tuple[bool, str]:
+        if not corrected or not corrected.strip():
+            return False, "empty_output"
+        original_no_space = original.replace(' ', '').replace('\u200c', '')
+        corrected_no_space = corrected.replace(' ', '').replace('\u200c', '')
+        if original_no_space == corrected_no_space:
+            return True, "space_leniency_accept"
+        len_orig = len(original)
+        len_corr = len(corrected)
+        if len_corr > len_orig * 2.5:
+             return False, "too_long"
+        if len_corr < len_orig * 0.5:
+             if error_type == ErrorType.CHAR_REPETITION:
+                 pass
+             else:
+                 return False, "too_short"
+        is_valid_count, reason = self.check_word_count(original, corrected)
+        if not is_valid_count:
+            return False, reason
+        is_valid_chars, reason = self.check_character_preservation(original, corrected)
+        if not is_valid_chars:
+             return False, reason
+        return True, "valid"
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# VOCABULARY MANAGER
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class VocabularyManager:
+    """Centralized vocabulary management for OOV/IV detection using CamelTools."""
+    
+    def __init__(self, tokenizer):
+        self.tokenizer = tokenizer
+        from camel_tools.morphology.database import MorphologyDB
+        from camel_tools.morphology.analyzer import Analyzer
+        self._db = MorphologyDB.builtin_db()
+        self.analyzer = Analyzer(self._db)
+        logger.info("VocabularyManager initialized with CamelTools Analyzer")
+    
+    def is_iv(self, word: str) -> bool:
+        clean = re.sub(r'[^\w]', '', word)
+        if not clean:
+            return True
+        return len(self.analyzer.analyze(clean)) > 0
+    
+    def is_oov(self, word: str) -> bool:
+        return not self.is_iv(word)
+    
+    def get_frequency_rank(self, word: str) -> int:
+        clean = re.sub(r'[^\w]', '', word)
+        return self.vocab_rank.get(clean, 999999)
+    
+    def all_words_iv(self, text: str) -> bool:
+        words = text.split()
+        return all(self.is_iv(w) for w in words)
+    
+    def count_oov_words(self, text: str) -> int:
+        words = text.split()
+        return sum(1 for w in words if self.is_oov(w))
+    
+    def get_oov_words(self, text: str) -> List[str]:
+        words = text.split()
+        return [w for w in words if self.is_oov(w)]
+    
+    def words_are_equivalent(self, word1: str, word2: str) -> bool:
+        norm1 = self.normalize_for_comparison(word1)
+        norm2 = self.normalize_for_comparison(word2)
+        return norm1 == norm2
+    
+    @staticmethod
+    def damerau_levenshtein_distance(s1: str, s2: str) -> int:
+        return jellyfish.damerau_levenshtein_distance(s1, s2)
+    
+    def calculate_similarity(self, original: str, corrected: str) -> float:
+        dist = self.damerau_levenshtein_distance(original, corrected)
+        max_len = max(len(original), len(corrected), 1)
+        return 1.0 - (dist / max_len)
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# WORD ALIGNER
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class WordAligner:
+    """Aligns input and output words to create hybrid corrections."""
+    
+    def __init__(self, vocab_manager):
+        self.vocab = vocab_manager
+    
+    def align_words(self, input_text: str, output_text: str) -> str:
+        input_words = input_text.split()
+        output_words = output_text.split()
+        if abs(len(input_words) - len(output_words)) > 2:
+            input_oov = self.vocab.count_oov_words(input_text)
+            output_oov = self.vocab.count_oov_words(output_text)
+            return output_text if output_oov < input_oov else input_text
+        result = []
+        min_len = min(len(input_words), len(output_words))
+        for i in range(min_len):
+            in_word = input_words[i]
+            out_word = output_words[i]
+            best_word = self._select_best_word(in_word, out_word)
+            result.append(best_word)
+        if len(output_words) > min_len:
+            result.extend(output_words[min_len:])
+        elif len(input_words) > min_len:
+            for w in input_words[min_len:]:
+                 if self.vocab.is_iv(w):
+                     result.append(w)
+        return ' '.join(result)
+    
+    def _select_best_word(self, input_word: str, output_word: str) -> str:
+        if input_word == output_word:
+            return input_word
+        in_iv = self.vocab.is_iv(input_word)
+        out_iv = self.vocab.is_iv(output_word)
+        if not in_iv and out_iv:
+            return output_word
+        if in_iv and not out_iv:
+            return input_word
+        if in_iv and out_iv:
+            # Bug 2.2: Do not prefer ة over ه if both are IV, because ه is often a valid possessive pronoun.
+            return input_word 
+        if len(input_word) == len(output_word) and len(input_word) >= 3:
+            for i in range(len(input_word)):
+                if input_word[i] != output_word[i]:
+                    hybrid = input_word[:i] + output_word[i] + input_word[i+1:]
+                    if self.vocab.is_iv(hybrid):
+                        return hybrid
+                    hybrid2 = output_word[:i] + input_word[i] + output_word[i+1:]
+                    if self.vocab.is_iv(hybrid2):
+                        return hybrid2
+        return output_word
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# SPLIT/MERGE SPECIALIST
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class SplitMergeSpecialist:
+    """Handles word splitting and merging with vocabulary validation."""
+    
+    SEPARABLE_PREFIXES = [
+        'من', 'في', 'على', 'عن', 'مع', 'إلى', 'الى', 'حتى', 'منذ', 'خلال', 
+        'بعد', 'قبل', 'بين', 'حول', 'تحت', 'فوق', 'أمام', 'وراء', 'دون',
+        'أن', 'لن', 'لم', 'قد', 'سوف', 'كي', 'إذا', 'لو', 'مثل', 'غير',
+        'يا',
+    ]
+    
+    PROTECTED_WORDS = {
+        'في', 'من', 'على', 'عن', 'مع', 'إلى', 'الى', 'ان', 'أن', 'لا', 'ما', 'هو', 'هي',
+        'لم', 'لن', 'قد', 'كل', 'كان', 'ذلك', 'هذا', 'هذه', 'التي', 'الذي', 'بين',
+    }
+    
+    ATTACHED_PREFIXES = [
+        'وال', 'بال', 'فال', 'كال', 'لل',
+        'وب', 'وف', 'ول', 'وك', 'وم', 'ون',
+        'فب', 'فل', 'فك', 'فم',
+    ]
+    
+    PRONOUN_SUFFIXES = {'كم', 'هم', 'ها', 'هن', 'كن', 'نا', 'هما', 'كما', 'تم', 'تن'}
+    
+    def __init__(self, vocab_manager):
+        self.vocab = vocab_manager
+        self.separable_prefixes = sorted(
+            self.SEPARABLE_PREFIXES, key=len, reverse=True
+        )
+    
+    def split_word(self, word: str) -> str:
+        if len(word) < 5:
+            return word
+        if self.vocab.is_iv(word):
+            return word
+        if word in self.PROTECTED_WORDS:
+            return word
+        for prefix in self.ATTACHED_PREFIXES:
+            if word.startswith(prefix):
+                remainder = word[len(prefix):]
+                if self.vocab.is_iv(remainder):
+                    return word
+                if prefix.endswith('ال') and self.vocab.is_iv(remainder):
+                    return word
+        for prefix in self.separable_prefixes:
+            if word.startswith(prefix) and len(word) > len(prefix) + 2:
+                remainder = word[len(prefix):]
+                if self.vocab.is_iv(remainder):
+                    return f"{prefix} {remainder}"
+        for i in range(3, len(word) - 2):
+            left = word[:i]
+            right = word[i:]
+            if self.vocab.is_iv(left) and self.vocab.is_iv(right):
+                return f"{left} {right}"
+        return word
+    
+    def merge_fragments(self, text: str) -> str:
+        words = text.split()
+        if len(words) < 2:
+            return text
+        result = []
+        i = 0
+        while i < len(words):
+            word = words[i]
+            if i + 1 < len(words):
+                next_word = words[i + 1]
+                merged = word + next_word
+                if len(next_word) == 1 and next_word in 'ةهاي':
+                    if self.vocab.is_iv(merged):
+                        result.append(merged)
+                        i += 2
+                        continue
+                if word == 'ال' and len(next_word) >= 2:
+                    if self.vocab.is_iv(merged):
+                        result.append(merged)
+                        i += 2
+                        continue
+                if self.vocab.is_oov(word) and self.vocab.is_oov(next_word):
+                    if self.vocab.is_iv(merged):
+                        result.append(merged)
+                        i += 2
+                        continue
+                if len(word) <= 2 and self.vocab.is_oov(word):
+                    if self.vocab.is_iv(merged):
+                        result.append(merged)
+                        i += 2
+                        continue
+                if next_word in self.PRONOUN_SUFFIXES:
+                    if self.vocab.is_iv(merged) and not self.vocab.is_iv(word):
+                        result.append(merged)
+                        i += 2
+                        continue
+                if len(word) <= 3 and len(next_word) <= 3:
+                    if len(merged) >= 5 and self.vocab.is_iv(merged):
+                        result.append(merged)
+                        i += 2
+                        continue
+            result.append(word)
+            i += 1
+        return ' '.join(result)
+    
+    def process_text(self, text: str) -> str:
+        text = self.merge_fragments(text)
+        words = text.split()
+        processed = []
+        for word in words:
+            if self.vocab.is_oov(word) and len(word) >= 4:
+                split_result = self.split_word(word)
+                processed.append(split_result)
+            else:
+                processed.append(word)
+        return ' '.join(processed)
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# EDIT DISTANCE CORRECTOR
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class EditDistanceCorrector:
+    """Generates candidates based on Levenshtein distance."""
+    
+    def __init__(self, tokenizer):
+        self.tokenizer = tokenizer
+        self.vocab = {
+            w for w in tokenizer.get_vocab().keys() 
+            if w.isalpha() and not w.startswith('##') and len(w) > 1
+        }
+        self.vocab_rank = {w: i for w, i in tokenizer.get_vocab().items()}
+
+    def edits1(self, word):
+        letters    = 'أابتثجحخدذرزسشصضطظعغفقكلمنهويءآىةئؤ'
+        splits     = [(word[:i], word[i:])    for i in range(len(word) + 1)]
+        deletes    = [L + R[1:]               for L, R in splits if R]
+        transposes = [L + R[1] + R[0] + R[2:] for L, R in splits if len(R)>1]
+        replaces   = [L + c + R[1:]           for L, R in splits if R for c in letters]
+        inserts    = [L + c + R               for L, R in splits for c in letters]
+        return set(deletes + transposes + replaces + inserts)
+
+    def edits2(self, word):
+        return (e2 for e1 in self.edits1(word) for e2 in self.edits1(e1))
+
+    def known(self, words):
+        return set(w for w in words if w in self.vocab)
+
+    def generate_candidate(self, text: str) -> str:
+        words = text.split()
+        corrected_words = []
+        for word in words:
+            clean_word = re.sub(r'[^\w]', '', word)
+            if clean_word in self.vocab:
+                corrected_words.append(word)
+                continue
+            candidates = self.known(self.edits1(clean_word))
+            if not candidates:
+                if len(clean_word) < 7: 
+                    candidates = self.known(self.edits2(clean_word))
+            if candidates:
+                best_candidate = min(candidates, key=lambda w: self.vocab_rank.get(w, 999999))
+                corrected_words.append(best_candidate)
+            else:
+                corrected_words.append(word)
+        return ' '.join(corrected_words)
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# CONTEXTUAL CORRECTOR (MLM-based) — Optional, disabled by default to save RAM
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class ContextualCorrector:
+    """MLM-based contextual correction for confusion pairs"""
+    
+    CONFUSION_PAIRS = [
+        ('ض', 'ظ'), ('ذ', 'ز'), ('ث', 'س'), ('ص', 'س'),
+        ('ط', 'ت'), ('ق', 'ك'), ('ه', 'ة'), ('ا', 'ى'),
+        ('ت', 'د'), ('د', 'ض'), ('ك', 'ق'), ('غ', 'ق'),
+        ('ج', 'ش'), ('س', 'ز'), ('ف', 'ب'), ('و', 'و'),
+        ('ؤ', 'و'), ('ئ', 'ي'), ('ء', 'أ'), ('إ', 'أ'),
+    ]
+    
+    def __init__(self, model_name: str = 'aubmindlab/bert-base-arabertv02', cache_size: int = 10000):
+        from transformers import AutoTokenizer, AutoModelForMaskedLM
+        
+        self.tokenizer = AutoTokenizer.from_pretrained(model_name)
+        self.model = AutoModelForMaskedLM.from_pretrained(model_name)
+        self.device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
+        self.model = self.model.to(self.device)
+        self.model.eval()
+        self.confusion_map = self._build_confusion_map()
+        self.cache_hits = 0
+        self.cache_misses = 0
+        self._score_cache = {}
+        self.cache_size = cache_size
+        self.vocab = self.tokenizer.get_vocab()
+    
+    def _build_confusion_map(self):
+        confusion_map = {}
+        for char1, char2 in self.CONFUSION_PAIRS:
+            if char1 not in confusion_map:
+                confusion_map[char1] = []
+            if char2 not in confusion_map:
+                confusion_map[char2] = []
+            confusion_map[char1].append(char2)
+            confusion_map[char2].append(char1)
+        return confusion_map
+    
+    def get_confusable_chars(self, char: str) -> List[str]:
+        return self.confusion_map.get(char, [])
+    
+    def generate_candidates(self, word: str) -> List[str]:
+        candidates = [word]
+        for i, char in enumerate(word):
+            confusables = self.get_confusable_chars(char)
+            for conf_char in confusables:
+                candidate = word[:i] + conf_char + word[i+1:]
+                if candidate not in candidates:
+                    candidates.append(candidate)
+        for i in range(len(word) - 1):
+            if word[i] == word[i+1]:
+                candidate = word[:i] + word[i+1:]
+                if candidate not in candidates:
+                    candidates.append(candidate)
+        COMMON_CHARS = 'ابتثجحخدذرزسشصضطظعغفقكلمنهويأإآءئؤةى'
+        for i in range(len(word) + 1):
+            for char in COMMON_CHARS:
+                candidate = word[:i] + char + word[i:]
+                if candidate in self.vocab and candidate not in candidates:
+                    candidates.append(candidate)
+        if len(word) < 7:
+            for i in range(len(word)):
+                for char in COMMON_CHARS:
+                    if char != word[i]:
+                        candidate = word[:i] + char + word[i+1:]
+                        if candidate in self.vocab and candidate not in candidates:
+                            candidates.append(candidate)
+        for i in range(len(word)):
+            candidate = word[:i] + word[i+1:]
+            if len(candidate) > 1:
+                if candidate in self.vocab and candidate not in candidates:
+                    candidates.append(candidate)
+        return candidates
+    
+    def score_with_mlm(self, text: str, position: int, word: str) -> float:
+        cache_key = f"{text}|{position}|{word}"
+        if cache_key in self._score_cache:
+            self.cache_hits += 1
+            return self._score_cache[cache_key]
+        self.cache_misses += 1
+        words = text.split()
+        if position >= len(words):
+            return 0.0
+        masked_words = words.copy()
+        masked_words[position] = '[MASK]'
+        masked_text = ' '.join(masked_words)
+        inputs = self.tokenizer(masked_text, return_tensors='pt', padding=True, truncation=True)
+        inputs = {k: v.to(self.device) for k, v in inputs.items()}
+        with torch.no_grad():
+            outputs = self.model(**inputs)
+            predictions = outputs.logits
+        mask_token_index = (inputs['input_ids'] == self.tokenizer.mask_token_id).nonzero(as_tuple=True)[1]
+        if len(mask_token_index) == 0:
+            return 0.0
+        mask_token_logits = predictions[0, mask_token_index[0], :]
+        probs = torch.softmax(mask_token_logits, dim=0)
+        word_tokens = self.tokenizer.encode(word, add_special_tokens=False)
+        if not word_tokens:
+            return 0.0
+        word_token_id = word_tokens[0]
+        score = probs[word_token_id].item()
+        if len(self._score_cache) >= self.cache_size:
+            self._score_cache.pop(next(iter(self._score_cache)))
+        self._score_cache[cache_key] = score
+        return score
+    
+    def score_candidates_batch(self, text: str, position: int, candidates: List[str]) -> dict:
+        scores = {}
+        for candidate in candidates:
+            scores[candidate] = self.score_with_mlm(text, position, candidate)
+        return scores
+    
+    def predict_masked_token(self, text: str, position: int, top_k: int = 5) -> List[Tuple[str, float]]:
+        words = text.split()
+        if position >= len(words):
+            return []
+        masked_words = words.copy()
+        masked_words[position] = '[MASK]'
+        masked_text = ' '.join(masked_words)
+        inputs = self.tokenizer(masked_text, return_tensors='pt', padding=True, truncation=True).to(self.device)
+        with torch.no_grad():
+            outputs = self.model(**inputs)
+            predictions = outputs.logits
+        mask_token_index = (inputs['input_ids'] == self.tokenizer.mask_token_id).nonzero(as_tuple=True)[1]
+        if len(mask_token_index) == 0:
+            return []
+        mask_token_logits = predictions[0, mask_token_index[0], :]
+        probs = torch.softmax(mask_token_logits, dim=0)
+        top_k_weights, top_k_indices = torch.topk(probs, top_k, sorted=True)
+        results = []
+        for i in range(top_k):
+            token_id = top_k_indices[i].item()
+            score = top_k_weights[i].item()
+            token = self.tokenizer.decode([token_id]).strip()
+            if not token.startswith("##") and token not in self.tokenizer.all_special_tokens:
+                results.append((token, score))
+        return results
+
+    def refine_sentence_with_mask(self, text: str, threshold: float = 0.001, vocab_manager=None, raw_model_output=None) -> str:
+        words = text.split()
+        refined_words = words.copy()
+        raw_words = raw_model_output.split() if raw_model_output else []
+        for i, word in enumerate(words):
+            if vocab_manager and vocab_manager.is_iv(word):
+                continue
+            if i < len(raw_words) and word == raw_words[i]:
+                continue
+            if len(word) <= 2:
+                continue
+            current_score = self.score_with_mlm(text, i, word)
+            if current_score > threshold:
+                continue
+            predictions = self.predict_masked_token(text, i, top_k=10)
+            for pred_word, pred_score in predictions:
+                if pred_word == word:
+                    continue
+                if abs(len(pred_word) - len(word)) > 1:
+                     continue
+                dist = Levenshtein.distance(word, pred_word)
+                max_len = max(len(word), len(pred_word))
+                similarity = 1.0 - (dist / max_len)
+                if similarity < 0.90:
+                    continue
+                if vocab_manager and vocab_manager.is_oov(pred_word):
+                    continue
+                if pred_score < 0.12:
+                    continue
+                is_original_common = current_score > 0.001
+                if is_original_common:
+                     if pred_score > current_score * 1000:
+                         refined_words[i] = pred_word
+                         break
+                else:
+                    if pred_score > current_score * 50 and pred_score > 0.2:
+                        refined_words[i] = pred_word
+                        break
+        return ' '.join(refined_words)
+    
+    def calculate_sentence_score(self, text: str) -> float:
+        words = text.split()
+        if not words:
+            return 0.0
+        total_score = 0.0
+        scored_words = 0
+        for i, word in enumerate(words):
+            score = self.score_with_mlm(text, i, word)
+            total_score += score
+            scored_words += 1
+        if scored_words == 0:
+            return 0.0
+        return total_score / scored_words
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# MAIN SPELL CHECKER CLASS
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class ArabicSpellChecker:
+    """Main Arabic Spell Checker class"""
+    
+    def __init__(self, model, tokenizer, device, use_contextual: bool = True):
+        self.model = model
+        self.tokenizer = tokenizer
+        self.device = device
+        
+        self.postprocessor = AraSpellPostProcessor()
+        self.classifier = ErrorClassifier()
+        self.rules = RulesBasedCorrector()
+        self.validator = OutputValidator()
+        self.vocab_manager = VocabularyManager(tokenizer)
+        self.edit_corrector = EditDistanceCorrector(tokenizer)
+        self.split_merge = SplitMergeSpecialist(self.vocab_manager)
+        self.word_aligner = WordAligner(self.vocab_manager)
+        
+        self.use_contextual = use_contextual
+        if use_contextual:
+            try:
+                logger.info("=" * 60)
+                logger.info("[MLM/CONTEXTUAL] Loading AraBERT MLM model...")
+                self.contextual = ContextualCorrector()
+                logger.info("[MLM/CONTEXTUAL] ✅ LOADED SUCCESSFULLY")
+                logger.info(f"[MLM/CONTEXTUAL] Device: {self.contextual.device}")
+                logger.info(f"[MLM/CONTEXTUAL] Vocab size: {len(self.contextual.vocab)}")
+                logger.info("=" * 60)
+            except Exception as e:
+                logger.warning("=" * 60)
+                logger.warning(f"[MLM/CONTEXTUAL] ❌ FAILED TO LOAD: {e}")
+                logger.warning("[MLM/CONTEXTUAL] Spelling will work without contextual validation")
+                logger.warning("=" * 60)
+                self.contextual = None
+                self.use_contextual = False
+        else:
+            self.contextual = None
+            logger.info("[MLM/CONTEXTUAL] Disabled by configuration (use_contextual=False)")
+
+    def _fix_repeated_end_chars(self, text: str) -> str:
+        text = re.sub(r'([ا-ي])\1+\b', r'\1', text)
+        return text
+    
+    def _fix_merged_with_errors(self, text: str) -> str:
+        # Bug 2.10: This regex was r'ال\2', deleting all instances of the character
+        text = re.sub(r'ال([ا-ي])\1+([ا-ي]{2,})', r'ال\1\2', text)
+        text = re.sub(r'\b([ا-ي]{3,})([ا-ي])\2+\b', r'\1\2', text)
+        return text
+
+    def _split_merged_words_linguistic(self, text: str) -> str:
+        # Bug 2.7: Catastrophic preposition splitting (e.g. منطق -> من طق)
+        # Disabled generic regex splitting as it is highly destructive to valid vocabulary.
+        return text
+    
+    def _split_long_words_heuristic(self, text: str, max_length: int = 15) -> str:
+        # Bug 2.8: Overzealous long word splitting (e.g. فيتامينات -> في تامينات)
+        # Disabled as it creates more errors than it fixes.
+        return text
+    
+    def _normalize_tanween_patterns(self, text: str) -> str:
+        # Bug 2.6: Blind replacement of trailing أ with اً corrupts verbs and nominative cases (قرأ -> قراً)
+        text = re.sub(r'\s+أ\s+', ' ', text)
+        text = re.sub(r'\b([بلك])\s+([ا-ي])', r'\1\2', text)
+        return text
+    
+    def preprocess(self, text: str) -> str:
+        """Preprocessing pipeline"""
+        text = self.postprocessor.remove_harakat(text)
+        text = self.postprocessor.remove_tatweel(text)
+        text = self.postprocessor.normalize_special_chars(text)
+        text = self._fix_repeated_end_chars(text)
+        text = self._fix_merged_with_errors(text)
+        text = self._split_merged_words_linguistic(text)
+        text = self._split_long_words_heuristic(text)
+        text = self._normalize_tanween_patterns(text)
+        text = self.postprocessor.merge_separated_al(text)
+        text = self.postprocessor.unified_collapse_repeated(text)
+        text = self.rules.fix_char_substitution(text)
+        text = self.rules.fix_char_repetition(text)
+        text = self.postprocessor.normalize_spaces(text)
+        return text
+    
+    def postprocess(self, text: str, original: str = "") -> str:
+        """Postprocessing pipeline"""
+        return self.postprocessor.full_postprocess(text, original, vocab_manager=self.vocab_manager)
+    
+    def model_inference(self, text: str, num_return_sequences: int = 5) -> List[str]:
+        """Run seq2seq model inference and return top candidates."""
+        inputs = self.tokenizer(text, return_tensors='pt', padding=True, truncation=True, max_length=128)
+        inputs = {k: v.to(self.device) for k, v in inputs.items()}
+        with torch.no_grad():
+            outputs = self.model.generate(
+                **inputs,
+                num_beams=5,
+                num_return_sequences=num_return_sequences,
+                early_stopping=True,
+                return_dict_in_generate=True,
+                output_scores=True
+            )
+        candidates = self.tokenizer.batch_decode(outputs.sequences, skip_special_tokens=True)
+        self._last_beam_scores = {}
+        if hasattr(outputs, 'sequences_scores') and outputs.sequences_scores is not None:
+            scores = outputs.sequences_scores.tolist()
+            for cand, score in zip(candidates, scores):
+                self._last_beam_scores[cand] = score
+        return candidates
+    
+    def correct(self, text: str) -> str:
+        """
+        Main correction pipeline (RERANKING APPROACH)
+        
+        Steps:
+        1. Preprocess
+        2. Generate Candidates (Model Beams + Baseline)
+        3. Rerank Candidates (Validator + Fluency)
+        4. Select Best
+        5. Postprocess
+        """
+        if not text or not text.strip():
+            return text
+        
+        original = text
+        
+        # 1. Preprocess
+        preprocessed_text = self.preprocess(text)
+        
+        # 2. Classify error type
+        error_type = self.classifier.classify(preprocessed_text)
+        
+        # 3. Generate Candidates
+        candidates = []
+        candidates.append(preprocessed_text)
+        
+        rules_candidate = self.rules.advanced_heuristic_repair(text)
+        candidates.append(rules_candidate)
+        
+        edit_candidate = self.edit_corrector.generate_candidate(text)
+        if edit_candidate != text and edit_candidate != rules_candidate:
+            candidates.append(edit_candidate)
+        
+        raw_model_output = None
+        try:
+            model_candidates = self.model_inference(preprocessed_text, num_return_sequences=5)
+            raw_model_output = model_candidates[0] if model_candidates else None
+            candidates.extend(model_candidates)
+            
+            if model_candidates:
+                hybrid_candidate = self.word_aligner.align_words(preprocessed_text, model_candidates[0])
+                if hybrid_candidate not in candidates:
+                    candidates.append(hybrid_candidate)
+                for beam in model_candidates[1:3]:
+                    hybrid_beam = self.word_aligner.align_words(preprocessed_text, beam)
+                    if hybrid_beam not in candidates:
+                        candidates.append(hybrid_beam)
+            
+            if model_candidates and len(model_candidates) >= 3:
+                try:
+                    beam_word_lists = [c.split() for c in model_candidates]
+                    max_words = max(len(wl) for wl in beam_word_lists)
+                    voted_words = []
+                    for pos in range(max_words):
+                        words_at_pos = []
+                        for wl in beam_word_lists:
+                            if pos < len(wl):
+                                words_at_pos.append(wl[pos])
+                        if words_at_pos:
+                            most_common = Counter(words_at_pos).most_common(1)[0][0]
+                            voted_words.append(most_common)
+                    voted_candidate = ' '.join(voted_words)
+                    if voted_candidate not in candidates:
+                        candidates.append(voted_candidate)
+                except Exception:
+                    pass
+        except Exception as e:
+            logger.warning(f"Model inference failed: {e}")
+        
+        # Remove duplicates
+        unique_candidates = []
+        seen = set()
+        for c in candidates:
+            if c not in seen:
+                unique_candidates.append(c)
+                seen.add(c)
+        candidates = unique_candidates
+        
+        # 4. Rerank Candidates
+        best_candidate = preprocessed_text
+        best_score = -1.0
+        candidate_scores = []
+        
+        for cand in candidates:
+            is_valid, reason = self.validator.validate(original, cand, error_type.value)
+            if len(cand) < len(original) * 0.5:
+                is_valid = False
+                reason = "too_short"
+
+            input_oov_count = self.vocab_manager.count_oov_words(original)
+            cand_oov_count = self.vocab_manager.count_oov_words(cand)
+            vocab_boost = 1.0
+            
+            if input_oov_count > 0 and cand_oov_count < input_oov_count:
+                oov_reduction = input_oov_count - cand_oov_count
+                vocab_boost = 1.0 + (oov_reduction * 0.3)
+                if cand_oov_count == 0 and self.vocab_manager.all_words_iv(cand):
+                    if not is_valid and reason not in ["empty_output"]:
+                        is_valid = True
+                        reason = "vocab_aware_accept"
+            elif cand_oov_count > input_oov_count:
+                vocab_boost = 0.5
+            elif input_oov_count == 0 and cand_oov_count == 0:
+                vocab_boost = 1.0
+            
+            validity_factor = 1.0 if is_valid else 0.001
+            
+            fluency_score = 0.0
+            if self.use_contextual and self.contextual:
+                try:
+                    fluency_score = self.contextual.calculate_sentence_score(cand)
+                except Exception as e:
+                    logger.warning(f"Scoring failed: {e}")
+                    fluency_score = 0.5
+            else:
+                fluency_score = 1.0 
+            
+            dist = VocabularyManager.damerau_levenshtein_distance(preprocessed_text, cand)
+            max_len = max(len(preprocessed_text), len(cand), 1)
+            similarity = 1.0 - (dist / max_len)
+            if cand == preprocessed_text:
+                similarity = 1.0
+            
+            keyboard_bonus = 1.0
+            input_words = preprocessed_text.split()
+            cand_words = cand.split()
+            if len(input_words) == len(cand_words):
+                for iw, cw in zip(input_words, cand_words):
+                    if iw != cw and len(iw) == len(cw):
+                        for ic, cc in zip(iw, cw):
+                            if ic != cc and RulesBasedCorrector.is_keyboard_neighbor(ic, cc):
+                                keyboard_bonus *= 1.05
+            
+            if fluency_score > 0.85 and cand_oov_count == 0:
+                 if not is_valid and reason in ["too_short", "low_character_similarity", "word_count_mismatch"]:
+                      if len(cand) >= len(original) * 0.4:
+                          is_valid = True
+                          reason = "high_confidence_override"
+                          vocab_boost *= 1.2
+                          validity_factor = 1.0
+            
+            fluency_exp = 0.3
+            similarity_exp = 3.0
+            beam_boost = 1.0
+            if raw_model_output and cand == raw_model_output:
+                beam_boost = 1.15
+            
+            final_score = (fluency_score ** fluency_exp) * (similarity ** similarity_exp) * validity_factor * vocab_boost * keyboard_bonus * beam_boost
+            
+            candidate_scores.append({
+                'text': cand, 'is_valid': is_valid, 'reason': reason,
+                'fluency': fluency_score, 'similarity': similarity,
+                'vocab_boost': vocab_boost, 'input_oov': input_oov_count,
+                'cand_oov': cand_oov_count, 'final_score': final_score
+            })
+            
+            if final_score > best_score:
+                best_score = final_score
+                best_candidate = cand
+        
+        # Output Quality Scoring
+        if best_candidate != preprocessed_text:
+            preprocessed_score = 0.0
+            for cs in candidate_scores:
+                if cs['text'] == preprocessed_text:
+                    preprocessed_score = cs['final_score']
+                    break
+            if preprocessed_score > 0 and best_score < preprocessed_score * 1.05:
+                best_oov = self.vocab_manager.count_oov_words(best_candidate)
+                prep_oov = self.vocab_manager.count_oov_words(preprocessed_text)
+                if best_oov > prep_oov:
+                    best_candidate = preprocessed_text
+                    best_score = preprocessed_score
+        
+        # Contextual Validation Layer
+        if best_candidate != preprocessed_text and self.use_contextual and self.contextual:
+            try:
+                input_fluency = self.contextual.calculate_sentence_score(preprocessed_text)
+                best_fluency = 0.0
+                for cs in candidate_scores:
+                    if cs['text'] == best_candidate:
+                        best_fluency = cs['fluency']
+                        break
+                if input_fluency > 0 and best_fluency > 0:
+                    if input_fluency > best_fluency * 1.5:
+                        input_oov = self.vocab_manager.count_oov_words(preprocessed_text)
+                        best_oov = self.vocab_manager.count_oov_words(best_candidate)
+                        if input_oov <= best_oov:
+                            best_candidate = preprocessed_text
+            except Exception:
+                pass
+        
+        # 5. Postprocess Winner
+        result = self.postprocess(best_candidate, original)
+        
+        # IV-Safe Postprocessing Check
+        if result != best_candidate:
+            result_words = result.split()
+            best_words = best_candidate.split()
+            if len(result_words) == len(best_words):
+                fixed_words = []
+                for idx_fw, (rw, bw) in enumerate(zip(result_words, best_words)):
+                    if rw != bw:
+                        bw_iv = self.vocab_manager.is_iv(bw)
+                        rw_iv = self.vocab_manager.is_iv(rw)
+                        if bw_iv and not rw_iv:
+                            fixed_words.append(bw)
+                        else:
+                            fixed_words.append(rw)
+                    else:
+                        fixed_words.append(rw)
+                result = ' '.join(fixed_words)
+        
+        # 6. Contextual fine-tuning
+        if self.use_contextual and self.contextual:
+             if len(result) > 3:
+                 result = self.contextual.refine_sentence_with_mask(
+                     result, vocab_manager=self.vocab_manager,
+                     raw_model_output=raw_model_output
+                 )
+        
+        # 7. Safe Split/Merge Post-processing
+        result = self.split_merge.merge_fragments(result)
+        
+        # 8. Output Stability Test
+        if result != preprocessed_text and raw_model_output:
+            try:
+                re_preprocessed = self.preprocess(result)
+                stability_dist = VocabularyManager.damerau_levenshtein_distance(result, re_preprocessed)
+                result_len = max(len(result), 1)
+                if stability_dist > 0:
+                    stability_ratio = stability_dist / result_len
+                    if stability_ratio > 0.15:
+                        raw_re = self.preprocess(raw_model_output)
+                        raw_stability = VocabularyManager.damerau_levenshtein_distance(
+                            raw_model_output, raw_re
+                        ) / max(len(raw_model_output), 1)
+                        if raw_stability < stability_ratio:
+                            raw_oov = self.vocab_manager.count_oov_words(raw_model_output)
+                            our_oov = self.vocab_manager.count_oov_words(result)
+                            if raw_oov <= our_oov:
+                                result = raw_model_output
+            except Exception:
+                pass
+        
+        # 9. Bidirectional Word-Level Validation
+        if raw_model_output and result != raw_model_output:
+            result_words = result.split()
+            raw_words = raw_model_output.split()
+            if len(result_words) == len(raw_words):
+                corrected_words = []
+                changed = False
+                for rw, raw_w in zip(result_words, raw_words):
+                    if rw != raw_w:
+                        rw_iv = self.vocab_manager.is_iv(rw)
+                        raw_iv = self.vocab_manager.is_iv(raw_w)
+                        if not rw_iv and raw_iv:
+                            corrected_words.append(raw_w)
+                            changed = True
+                        elif rw_iv and raw_iv:
+                            input_words_list = preprocessed_text.split()
+                            idx = len(corrected_words)
+                            if idx < len(input_words_list):
+                                input_w = input_words_list[idx]
+                                rw_dist = Levenshtein.distance(input_w, rw)
+                                raw_dist = Levenshtein.distance(input_w, raw_w)
+                                if raw_dist < rw_dist:
+                                    corrected_words.append(raw_w)
+                                    changed = True
+                                else:
+                                    corrected_words.append(rw)
+                            else:
+                                corrected_words.append(rw)
+                        else:
+                            corrected_words.append(rw)
+                    else:
+                        corrected_words.append(rw)
+                if changed:
+                    new_result = ' '.join(corrected_words)
+                    new_oov = self.vocab_manager.count_oov_words(new_result)
+                    old_oov = self.vocab_manager.count_oov_words(result)
+                    if new_oov <= old_oov:
+                        result = new_result
+        
+        # 10. SAFETY NET
+        if raw_model_output and raw_model_output != result:
+            raw_oov = self.vocab_manager.count_oov_words(raw_model_output)
+            our_oov = self.vocab_manager.count_oov_words(result)
+            if raw_oov == 0 and our_oov > 0:
+                is_valid, reason = self.validator.validate(original, raw_model_output, "mixed")
+                if is_valid or reason == "space_leniency_accept":
+                    result = raw_model_output
+            elif raw_oov == 0 and our_oov == 0:
+                raw_dist = VocabularyManager.damerau_levenshtein_distance(original, raw_model_output)
+                our_dist = VocabularyManager.damerau_levenshtein_distance(original, result)
+                result_vs_raw_dist = VocabularyManager.damerau_levenshtein_distance(result, raw_model_output)
+                if raw_dist < our_dist and result_vs_raw_dist <= 3:
+                    raw_valid, _ = self.validator.validate(original, raw_model_output, "mixed")
+                    if raw_valid:
+                        result = raw_model_output
+            elif raw_oov == 0:
+                raw_wc = len(raw_model_output.split())
+                our_wc = len(result.split())
+                if raw_wc != our_wc:
+                    raw_dist = VocabularyManager.damerau_levenshtein_distance(original, raw_model_output)
+                    our_dist = VocabularyManager.damerau_levenshtein_distance(original, result)
+                    if raw_dist < our_dist:
+                        raw_valid, _ = self.validator.validate(original, raw_model_output, "mixed")
+                        if raw_valid:
+                            result = raw_model_output
+        # ── FINAL PASS: Hamza whitelist + Ta Marbuta fixes (unrevertable) ──
+        # These are applied AFTER all validation/safety steps so they can't
+        # be undone by Steps 8-10 which compare against raw_model_output.
+        # The root issue: Steps 8-10 use edit distance to INPUT (which has errors)
+        # so they revert corrections back to the erroneous form.
+        result = AraSpellPostProcessor.fix_common_hamza(result)
+        result = AraSpellPostProcessor.fix_ha_ta_marbuta(result, vocab_manager=self.vocab_manager)
+
+        # 11. DESTRUCTIVE TOKENIZATION GUARD
+        # Arabic orthography does not use standalone 1-letter words except prepositions.
+        # If the model creates a standalone 1-letter word that was not in the original,
+        # check if it's a legitimate prefix separation (e.g. بالشاروع→ب الشارع).
+        orig_standalone = set(w for w in original.split() if len(w) == 1)
+        orig_words = original.split()
+        res_words_list = result.split()
+        for idx, w in enumerate(res_words_list):
+            if len(w) == 1 and w not in orig_standalone:
+                if w in 'واتيبلفك':
+                    # Check if this is a legitimate prefix separation:
+                    # The original word should have started with this letter as a prefix
+                    is_prefix_separation = False
+                    if w in 'وفبلك' and idx + 1 < len(res_words_list):
+                        next_word = res_words_list[idx + 1]
+                        combined = w + next_word
+                        # If any original word started with the prefix letter and
+                        # the remainder matches the next word, it's legitimate
+                        for ow in orig_words:
+                            if ow.startswith(w) and len(ow) > 2:
+                                is_prefix_separation = True
+                                break
+                    
+                    if not is_prefix_separation:
+                        logger.info(f"[SPELLING] Blocked destructive tokenization (hallucinated standalone '{w}'): '{original}' -> '{result}'")
+                        result = original
+                        break
+
+        # 12. MORPHOLOGICAL MUTATION GUARD (Verb -> Noun)
+        # Prevents spelling from changing a plural verb (e.g. صممو) to a noun (e.g. مصممو) by prepending م
+        if len(orig_words) == len(res_words_list):
+            for idx in range(len(orig_words)):
+                ow = orig_words[idx]
+                rw = res_words_list[idx]
+                # If the word didn't start with م but the correction does, and it looks like a plural verb
+                if not ow.startswith('م') and rw.startswith('م') and rw[1:] == ow and ow.endswith('و'):
+                    logger.info(f"[SPELLING] Blocked morphological mutation (verb→noun '{ow}'→'{rw}')")
+                    res_words_list[idx] = ow
+            result = ' '.join(res_words_list)
+
+        return result
+

src/nlp/grammar/grammar_rules.py

@@ -718,16 +718,35 @@ class ArabicGrammarGuard:
         """Apply all grammar rules to model output."""
         text = self.preserve_numbers(original_text, generated_text)
         
-        # ── Fix Hallucinated Subject Gender ──
-        # If model incorrectly changes female subject to male, restore it.
+        # ── Fix Hallucinated Subject Gender & Protect Structured Data ──
         orig_words = original_text.split()
         corr_words = text.split()
         if len(orig_words) == len(corr_words):
-            for i, (o, c) in enumerate(zip(orig_words, corr_words)):
+            for i in range(len(orig_words)):
+                o = orig_words[i]
+                c = corr_words[i]
                 o_clean = o.rstrip('.,،؛;:!؟?()[]{}«»"\'…')
                 c_clean = c.rstrip('.,،؛;:!؟?()[]{}«»"\'…')
+                
+                # Protect structured data (English, JSON, Hashtags, Code)
+                if re.search(r'[a-zA-Z]|\{.*\}|\[.*\]|<.*>|#\S+|@\S+', o):
+                    corr_words[i] = o
+                    # Revert grammar hallucinations on adjacent Arabic words caused by structured data
+                    if i > 0:
+                        prev_o = orig_words[i-1]
+                        prev_c = corr_words[i-1]
+                        clean_c = prev_c.rstrip('.,،؛;:!؟?()[]{}«»"\'…')
+                        if len(clean_c) <= len(prev_o) + 2 and clean_c.startswith(prev_o):
+                            corr_words[i-1] = prev_o + prev_c[len(clean_c):]
+                    if i < len(orig_words) - 1:
+                        next_o = orig_words[i+1]
+                        next_c = corr_words[i+1]
+                        clean_c = next_c.rstrip('.,،؛;:!؟?()[]{}«»"\'…')
+                        if len(clean_c) <= len(next_o) + 2 and clean_c.startswith(next_o):
+                            corr_words[i+1] = next_o + next_c[len(clean_c):]
+                
                 # If model dropped 'ة' from a word of length >= 4
-                if o_clean.endswith('ة') and not c_clean.endswith('ة') and o_clean[:-1] == c_clean:
+                elif o_clean.endswith('ة') and not c_clean.endswith('ة') and o_clean[:-1] == c_clean:
                     corr_words[i] = o
             text = " ".join(corr_words)
 

src/nlp/punctuation/punctuation_rules.py

@@ -165,6 +165,31 @@ def validate_punctuation_diff(diff: dict, full_text: str = '') -> bool:
     original = diff.get('original', '')
     correction = diff.get('correction', '')
 
+    # ── Protect Structured Data (English, URLs, Emails, Hashtags, Code/JSON) ──
+    # Block punctuation modifications near structured data unless it's a valid terminal punctuation
+    if re.search(r'[a-zA-Z]|\{.*\}|\[.*\]|<.*>|#\S+|@\S+', original):
+        is_at_end = False
+        if full_text and 'end' in diff:
+            is_at_end = diff['end'] >= len(full_text) - 2
+        elif not full_text:
+            is_at_end = True
+        
+        orig_punct = sum(1 for c in original if c in '.,،؛؟!:;?!')
+        corr_punct = sum(1 for c in correction if c in '.,،؛؟!:;?!')
+        
+        # Block mid-sentence punctuation additions (e.g. adding comma after English word)
+        if corr_punct > orig_punct and not is_at_end:
+            logger.info(f"[PUNC-SAFETY] Blocked mid-sentence punctuation on structured data: '{original}' -> '{correction}'")
+            return False
+            
+        # Block spacing corruptions in JSON/Code (e.g. {"name"} -> { "name" })
+        if re.search(r'\{.*\}|\[.*\]|<.*>|https?://', original):
+            # Only allow if the ONLY change is appending a terminal mark at the very end
+            if original != correction and not (is_at_end and correction.endswith(('.', '؟')) and correction[:-1].rstrip() == original.rstrip()):
+                logger.info(f"[PUNC-SAFETY] Blocked corruption of JSON/Code/URL: '{original}' -> '{correction}'")
+                return False
+    correction = diff.get('correction', '')
+
     # ── Rule 0 (FIX-01 + FIX-30 + Merged Guard): Terminal punctuation ──
     # PuncAra-v1 unconditionally adds . or ؟ to every sentence.
     # This rule catches the pattern: "word" → "word." / "word؟" / "word،"

src/nlp/spelling/araspell_rules.py

@@ -630,6 +630,13 @@ class OutputValidator:
     def validate(self, original: str, corrected: str, error_type: str) -> Tuple[bool, str]:
         if not corrected or not corrected.strip():
             return False, "empty_output"
+            
+        # ── Protect Structured Data ──
+        # Reject spelling modifications to English, JSON, URLs, Emails, Hashtags
+        if re.search(r'[a-zA-Z]|\{.*\}|\[.*\]|<.*>|#\S+|@\S+', original):
+            if original != corrected:
+                return False, "structural_protection"
+                
         original_no_space = original.replace(' ', '').replace('\u200c', '')
         corrected_no_space = corrected.replace(' ', '').replace('\u200c', '')
         if original_no_space == corrected_no_space: