feat: Pipeline Hardening v3.3 — stage ownership, punctuation safety, UUID migration

- Add CorrectionPatch with dual coordinate spaces (ORIGINAL + CURRENT)
- Add StageLocker to protect corrected ranges from later stages
- Add PipelineContext with append-only mapper chain
- Refactor OffsetMapper: private ._opcodes, reverse_map_offset(), forward_map_range() with monotonicity guard
- Add validate_punctuation_diff() 5-rule safety layer (Arabic normalization, repetition, short-text cap, ratio, delta)
- Wire StageLocker blocking for Grammar and Punctuation stages
- Replace inline overlap resolver with PatchSet.resolve_overlaps()
- Frontend: _isApplyingSuggestion guard prevents recursive re-analysis
- Frontend: UUID-based suggestion tracking replaces all index-based lookups
- Remove broken _trackAppliedCorrection reference
- Remove all 3 re-index loops (UUID makes them unnecessary)
- 19/19 regression tests passing

src/app.py

@@ -13,6 +13,10 @@ import traceback
 import difflib
 import re
 
+# Pipeline hardening modules
+from nlp.pipeline_context import PipelineContext
+from nlp.punctuation.punctuation_rules import validate_punctuation_diff
+
 # Load .env file from project root (one level up from src/)
 try:
     from dotenv import load_dotenv
@@ -578,30 +582,87 @@ def get_word_positions(text):
 
 
 class OffsetMapper:
-    def __init__(self, original, modified):
-        self.original = original
-        self.modified = modified
-        self.mapping = []  # list of (mod_start, mod_end, orig_start, orig_end)
-        self._build_mapping()
-        
-    def _build_mapping(self):
-        s = difflib.SequenceMatcher(None, self.original, self.modified)
+    """
+    Single source of truth for coordinate transformations between
+    two consecutive versions of CURRENT_TEXT.
+
+    CONTRACT:
+      Input:  text_before (str), text_after (str)
+              — two consecutive states of CURRENT_TEXT
+      Stores: Internal diff operations (PRIVATE)
+      API:
+        reverse_map_offset(pos)       → text_after pos → text_before pos
+        forward_map_range(start, end) → text_before range → text_after range
+
+    TERMINOLOGY:
+      text_before = CURRENT_TEXT before this stage's mutation
+      text_after  = CURRENT_TEXT after this stage's mutation
+      forward     = text_before → text_after
+      reverse     = text_after  → text_before
+
+    RULES:
+      All external code uses reverse_map_offset() or forward_map_range().
+      ._opcodes is PRIVATE — no external access.
+    """
+
+    def __init__(self, text_before, text_after):
+        self._text_before = text_before
+        self._text_after = text_after
+        self._opcodes = []  # PRIVATE — (i1, i2, j1, j2) tuples
+        self._build()
+
+    def _build(self):
+        s = difflib.SequenceMatcher(None, self._text_before, self._text_after)
         for tag, i1, i2, j1, j2 in s.get_opcodes():
-            self.mapping.append((j1, j2, i1, i2))
-            
-    def map_offset(self, mod_offset):
+            self._opcodes.append((i1, i2, j1, j2))
+
+    def reverse_map_offset(self, pos_in_after):
         """
-        Given a character offset in the modified text, return the corresponding
-        character offset in the original text.
+        Map a single position from text_after → text_before.
+        (CURRENT_TEXT after mutation → CURRENT_TEXT before mutation)
+
+        Used by PipelineContext.map_to_original() to walk the mapper
+        chain in reverse, ultimately reaching ORIGINAL_TEXT coordinates.
         """
-        for j1, j2, i1, i2 in self.mapping:
-            if j1 <= mod_offset <= j2:
+        for i1, i2, j1, j2 in self._opcodes:
+            if j1 <= pos_in_after <= j2:
                 if j2 == j1:  # insertion point
                     return i1
-                # Proportional mapping inside the block
-                ratio = (mod_offset - j1) / (j2 - j1)
+                ratio = (pos_in_after - j1) / (j2 - j1)
                 return int(i1 + ratio * (i2 - i1))
-        return len(self.original)
+        return len(self._text_before)
+
+    def forward_map_range(self, start_in_before, end_in_before):
+        """
+        Map a range from text_before → text_after.
+        (CURRENT_TEXT before mutation → CURRENT_TEXT after mutation)
+
+        Used ONLY by StageLocker.update_via_mapper() to shift locked
+        spans after a text mutation.
+
+        MONOTONICITY GUARD: If independent point mapping produces an
+        inverted range (start > end) due to non-monotonic edits,
+        the end is clamped to max(new_start, new_end).
+        """
+        new_start = self._forward_map_pos(start_in_before)
+        new_end = self._forward_map_pos(end_in_before)
+        # Monotonicity guard: prevent inverted ranges
+        new_end = max(new_start, new_end)
+        return new_start, new_end
+
+    def _forward_map_pos(self, pos):
+        """Map a single position text_before → text_after. PRIVATE."""
+        for i1, i2, j1, j2 in self._opcodes:
+            if i1 <= pos <= i2:
+                if i2 == i1:
+                    return j1
+                ratio = (pos - i1) / (i2 - i1)
+                return int(j1 + ratio * (j2 - j1))
+        if self._opcodes:
+            last = self._opcodes[-1]
+            return last[3] + (pos - last[1])
+        return pos
+
 
 
 def get_word_diffs(original, corrected):
@@ -714,18 +775,17 @@ def analyze_text():
         if not text:
             return jsonify({'error': 'Text is required', 'status': 'error'}), 400
 
-        current_text = text
-        suggestions = []
-        mappers = []
+        # Pipeline state — PipelineContext carries all shared state
+        ctx = PipelineContext(text)
+        current_text = text  # Local alias (updated alongside ctx.current_text)
+        suggestions = []     # Legacy — will be replaced by ctx.patches at response time
+        mappers = []         # Legacy — will be replaced by ctx._offset_mappers
         total_start = time.time()
         timing_ms = {'spelling_ms': 0, 'grammar_ms': 0, 'punctuation_ms': 0, 'total_ms': 0}
 
         def map_range_to_original(start, end):
-            curr_start, curr_end = start, end
-            for mapper in reversed(mappers):
-                curr_start = mapper.map_offset(curr_start)
-                curr_end = mapper.map_offset(curr_end)
-            return curr_start, curr_end
+            """Legacy wrapper — delegates to PipelineContext."""
+            return ctx.map_to_original(start, end)
 
         def _get_spelling_alternatives(original_word, best_correction, spell_checker, max_alts=3):
             """Generate alternative spelling suggestions for a word."""
@@ -770,8 +830,8 @@ def analyze_text():
                 timing_ms['spelling_ms'] = int((time.time() - t0) * 1000)
                 logger.info(f"[ANALYZE] Step 1: Spelling done in {timing_ms['spelling_ms']}ms")
 
-                if raw_corrected != current_text:
-                    orig_word_positions = get_word_positions(current_text)
+                if raw_corrected != ctx.current_text:
+                    orig_word_positions = get_word_positions(ctx.current_text)
                     corr_word_positions = get_word_positions(raw_corrected)
 
                     orig_word_strings = [w[0] for w in orig_word_positions]
@@ -798,14 +858,11 @@ def analyze_text():
                                 c_word = c_segment[0]
                                 if _is_small_spelling_change(o_word, c_word):
                                     new_words.append(c_word)
-                                    suggestions.append({
-                                        'start': start_idx,
-                                        'end': end_idx,
-                                        'original': o_word,
-                                        'correction': c_word,
-                                        'type': 'spelling',
-                                        'alternatives': _get_spelling_alternatives(o_word, c_word, spell_checker),
-                                    })
+                                    ctx.add_patch(
+                                        'spelling', start_idx, end_idx,
+                                        c_word, confidence=0.9,
+                                        alternatives=_get_spelling_alternatives(o_word, c_word, spell_checker),
+                                    )
                                 else:
                                     new_words.append(current_text[start_idx:end_idx])
                             elif len(o_segment) == 1 and len(c_segment) > 1:
@@ -814,14 +871,11 @@ def analyze_text():
                                 if len(o_word) >= 5 and ' ' not in o_word:
                                     corr_str = " ".join(c_segment)
                                     new_words.append(corr_str)
-                                    suggestions.append({
-                                        'start': start_idx,
-                                        'end': end_idx,
-                                        'original': o_word,
-                                        'correction': corr_str,
-                                        'type': 'spelling',
-                                        'alternatives': [corr_str, o_word],
-                                    })
+                                    ctx.add_patch(
+                                        'spelling', start_idx, end_idx,
+                                        corr_str, confidence=0.85,
+                                        alternatives=[corr_str, o_word],
+                                    )
                                 else:
                                     new_words.append(current_text[start_idx:end_idx])
                             else:
@@ -839,14 +893,11 @@ def analyze_text():
                                         # Check if this is a 1→1 small edit
                                         if _is_small_spelling_change(o_word, c_word):
                                             new_words.append(c_word)
-                                            suggestions.append({
-                                                'start': o_start,
-                                                'end': o_end,
-                                                'original': o_word,
-                                                'correction': c_word,
-                                                'type': 'spelling',
-                                                'alternatives': _get_spelling_alternatives(o_word, c_word, spell_checker),
-                                            })
+                                            ctx.add_patch(
+                                                'spelling', o_start, o_end,
+                                                c_word, confidence=0.9,
+                                                alternatives=_get_spelling_alternatives(o_word, c_word, spell_checker),
+                                            )
                                             ci += 1
                                         # Check if this is a 1→N word split
                                         elif len(o_word) >= 5 and ci + 1 < len(c_segment):
@@ -864,14 +915,11 @@ def analyze_text():
                                             dist = _levenshtein(o_word, joined_no_space)
                                             if dist <= 3 and len(split_parts) > 1:
                                                 new_words.append(corr_str)
-                                                suggestions.append({
-                                                    'start': o_start,
-                                                    'end': o_end,
-                                                    'original': o_word,
-                                                    'correction': corr_str,
-                                                    'type': 'spelling',
-                                                    'alternatives': [corr_str, o_word],
-                                                })
+                                                ctx.add_patch(
+                                                    'spelling', o_start, o_end,
+                                                    corr_str, confidence=0.85,
+                                                    alternatives=[corr_str, o_word],
+                                                )
                                                 ci = temp_ci
                                             else:
                                                 new_words.append(current_text[o_start:o_end])
@@ -888,8 +936,8 @@ def analyze_text():
                             continue
 
                     safe_text = " ".join(new_words)
-                    mappers.append(OffsetMapper(current_text, safe_text))
-                    current_text = safe_text
+                    ctx.mutate_text(safe_text, OffsetMapper)
+                    current_text = ctx.current_text
             except Exception as e:
                 logger.error(f"[ANALYZE] Spelling failed: {e}")
 
@@ -899,22 +947,25 @@ def analyze_text():
             logger.info(f"[ANALYZE] Step 2: Grammar correction starting...")
             from nlp.grammar.grammar_service import get_grammar_model
             grammar_checker = get_grammar_model()
-            corrected_grammar = grammar_checker.correct(current_text)
+            corrected_grammar = grammar_checker.correct(ctx.current_text)
             timing_ms['grammar_ms'] = int((time.time() - t0) * 1000)
             logger.info(f"[ANALYZE] Step 2: Grammar done in {timing_ms['grammar_ms']}ms")
-            if corrected_grammar != current_text:
-                diffs = get_word_diffs(current_text, corrected_grammar)
+            if corrected_grammar != ctx.current_text:
+                diffs = get_word_diffs(ctx.current_text, corrected_grammar)
                 for d in diffs:
-                    orig_start, orig_end = map_range_to_original(d['start'], d['end'])
-                    suggestions.append({
-                        'start': orig_start,
-                        'end': orig_end,
-                        'original': text[orig_start:orig_end],
-                        'correction': d['correction'],
-                        'type': 'grammar'
-                    })
-                mappers.append(OffsetMapper(current_text, corrected_grammar))
-                current_text = corrected_grammar
+                    # StageLocker: skip diffs that overlap with locked ranges
+                    if ctx.stage_locker.is_locked(d['start'], d['end']):
+                        logger.info(
+                            f"[LOCK] Grammar blocked on [{d['start']}:{d['end']}] "
+                            f"'{d.get('original','')}' — locked by previous stage"
+                        )
+                        continue
+                    ctx.add_patch(
+                        'grammar', d['start'], d['end'],
+                        d['correction'], confidence=1.0
+                    )
+                ctx.mutate_text(corrected_grammar, OffsetMapper)
+                current_text = ctx.current_text
         except Exception as e:
             logger.error(f"[ANALYZE] Grammar failed: {e}")
 
@@ -924,22 +975,32 @@ def analyze_text():
             logger.info(f"[ANALYZE] Step 3: Punctuation starting...")
             from nlp.punctuation.punctuation_service import get_punctuation_model
             punc_checker = get_punctuation_model()
-            corrected_punc = punc_checker.correct(current_text)
+            corrected_punc = punc_checker.correct(ctx.current_text)
             timing_ms['punctuation_ms'] = int((time.time() - t0) * 1000)
             logger.info(f"[ANALYZE] Step 3: Punctuation done in {timing_ms['punctuation_ms']}ms")
-            if corrected_punc != current_text:
-                diffs = get_word_diffs(current_text, corrected_punc)
+            if corrected_punc != ctx.current_text:
+                diffs = get_word_diffs(ctx.current_text, corrected_punc)
                 for d in diffs:
-                    orig_start, orig_end = map_range_to_original(d['start'], d['end'])
-                    suggestions.append({
-                        'start': orig_start,
-                        'end': orig_end,
-                        'original': text[orig_start:orig_end],
-                        'correction': d['correction'],
-                        'type': 'punctuation'
-                    })
-                mappers.append(OffsetMapper(current_text, corrected_punc))
-                current_text = corrected_punc
+                    # StageLocker: skip diffs that overlap with locked ranges
+                    if ctx.stage_locker.is_locked(d['start'], d['end']):
+                        logger.info(
+                            f"[LOCK] Punctuation blocked on [{d['start']}:{d['end']}] "
+                            f"'{d.get('original','')}' — locked by previous stage"
+                        )
+                        continue
+                    # Punctuation safety layer: reject non-punctuation changes
+                    if not validate_punctuation_diff(d):
+                        logger.info(
+                            f"[PUNC-SAFETY] Rejected diff [{d['start']}:{d['end']}] "
+                            f"'{d.get('original','')}' → '{d.get('correction','')}' — not a safe punctuation change"
+                        )
+                        continue
+                    ctx.add_patch(
+                        'punctuation', d['start'], d['end'],
+                        d['correction'], confidence=0.8
+                    )
+                ctx.mutate_text(corrected_punc, OffsetMapper)
+                current_text = ctx.current_text
         except Exception as e:
             logger.error(f"[ANALYZE] Punctuation failed: {e}")
 
@@ -947,45 +1008,12 @@ def analyze_text():
         timing_ms['total_ms'] = int(total_time * 1000)
 
         # ══════════════════════════════════════════════════════════
-        # GLOBAL OVERLAP RESOLVER — NLP-3.5 Hardening
+        # OVERLAP RESOLUTION — Pipeline Hardening v3.3
         # ══════════════════════════════════════════════════════════
-        # Priority: grammar(3) > punctuation(2) > spelling(1) > autocomplete(0)
-        # Rules:
-        #   - Higher priority ALWAYS wins
-        #   - One span = one highlight (no stacking)
-        #   - Partial overlaps: higher priority span kept, lower dropped
-        PRIORITY = {'grammar': 3, 'punctuation': 2, 'spelling': 1, 'autocomplete': 0}
-
-        # Sort suggestions by priority (highest first)
-        suggestions.sort(key=lambda s: PRIORITY.get(s['type'], 0), reverse=True)
-
-        # Build a set of "claimed" character positions
-        claimed_ranges = []  # list of (start, end, type)
-        resolved = []
-
-        for s in suggestions:
-            s_start, s_end = s['start'], s['end']
-            s_priority = PRIORITY.get(s['type'], 0)
-
-            # Check if this span overlaps with any already-claimed higher-priority span
-            overlaps = False
-            for (c_start, c_end, c_type) in claimed_ranges:
-                # Two spans overlap if one starts before the other ends
-                if s_start < c_end and s_end > c_start:
-                    overlaps = True
-                    break
-
-            if not overlaps:
-                resolved.append(s)
-                claimed_ranges.append((s_start, s_end, s['type']))
-            else:
-                logger.info(f"[OVERLAP] Dropped {s['type']} [{s_start}:{s_end}] "
-                           f"'{s.get('original','')}' — conflicts with higher-priority span")
-
-        dropped = len(suggestions) - len(resolved)
-        if dropped > 0:
-            logger.info(f"[OVERLAP] Resolved {dropped} overlapping suggestions")
-        suggestions = resolved
+        # PatchSet handles deterministic overlap resolution:
+        #   Sort: priority DESC → confidence DESC → start ASC → id ASC
+        #   One range = one owner. No stacking.
+        suggestions = ctx.patches.to_list()
 
         logger.info(f"[ANALYZE] Total: {timing_ms['total_ms']}ms | "
                     f"Spelling: {timing_ms['spelling_ms']}ms | "
@@ -995,7 +1023,7 @@ def analyze_text():
 
         return jsonify({
             'original': text,
-            'corrected': current_text,
+            'corrected': ctx.current_text,
             'suggestions': suggestions,
             'timing_ms': timing_ms,
             'status': 'success'

src/js/editor.js

@@ -7,6 +7,9 @@ let _lastInputTime = 0;
 const ANALYZE_DEBOUNCE_MS = 1000;
 const MAX_ANALYZE_LENGTH = 5000;
 
+// Pipeline Hardening v3.3: Guard to prevent input events during suggestion apply
+let _isApplyingSuggestion = false;
+
 // ── Custom Undo/Redo Stack ──
 const _undoStack = [];
 const _redoStack = [];
@@ -77,6 +80,8 @@ function initEditor() {
   } catch (e) {}
 
   editor.addEventListener('input', () => {
+    // Pipeline Hardening v3.3: Skip re-analysis when programmatically applying suggestions
+    if (_isApplyingSuggestion) return;
     _lastInputTime = Date.now();
     updateEditorStats();
     updatePlaceholder();
@@ -229,8 +234,9 @@ function analyzeTextDelayed() {
 }
 
 function findSuggestionById(id) {
+  // Pipeline Hardening v3.3: UUID-based lookup instead of index
   const suggestions = window.currentSuggestions || [];
-  return suggestions[parseInt(id, 10)] || null;
+  return suggestions.find(s => s.id === id) || null;
 }
 
 function findSuggestionElement(id) {
@@ -432,73 +438,63 @@ function hideTooltip() {
 }
 
 function applySuggestionAtOffsets(suggestion) {
-  pushUndoState(); // Save state before correction
-  // Find the error span in the DOM and replace its text content
-  // This preserves formatting (bold, italic, etc.) around/inside the span
-  const idx = (window.currentSuggestions || []).indexOf(suggestion);
-  const errorSpan = idx >= 0 ? document.querySelector(`[data-suggestion-id="${idx}"]`) : null;
-
-  if (errorSpan) {
-    // Replace the error span's text content with the correction
-    // while keeping it inside its formatting parent
-    const parent = errorSpan.parentNode;
-    const correctedNode = document.createTextNode(suggestion.correction);
-    parent.insertBefore(correctedNode, errorSpan);
-    parent.removeChild(errorSpan);
-    parent.normalize();
-  } else {
-    // Fallback: find span by matching original text
-    const allErrorSpans = document.querySelectorAll('.spelling-error, .grammar-error, .punctuation-suggestion');
-    let found = false;
-    allErrorSpans.forEach(span => {
-      if (!found && span.textContent === suggestion.original) {
-        const p = span.parentNode;
-        const correctedNode = document.createTextNode(suggestion.correction);
-        p.insertBefore(correctedNode, span);
-        p.removeChild(span);
-        p.normalize();
-        found = true;
-      }
-    });
-    if (!found) {
-      // Last resort: offset-based replacement
-      const text = getEditorText();
-      const before = text.substring(0, suggestion.start);
-      const after = text.substring(suggestion.end);
-      const newText = before + suggestion.correction + after;
-      setEditorHTML(escapeHtml(newText));
-    }
-  }
-  hideTooltip();
-  // Re-focus editor so Ctrl+Z works immediately after tooltip correction
-  const _ed = getEditorElement(); if (_ed) _ed.focus();
-
-  // Remove applied suggestion from list and re-index remaining spans
-  if (window.currentSuggestions) {
-    window.currentSuggestions = window.currentSuggestions.filter(
-      s => !(s.start === suggestion.start && s.end === suggestion.end && s.type === suggestion.type)
-    );
-
-    // Re-index remaining error spans to match updated array indices
-    const remainingSpans = document.querySelectorAll('.spelling-error, .grammar-error, .punctuation-suggestion');
-    remainingSpans.forEach(span => {
-      const newIdx = window.currentSuggestions.findIndex(s => {
-        return span.textContent === s.original && span.dataset.type === s.type;
+  _isApplyingSuggestion = true;
+  try {
+    pushUndoState(); // Save state before correction
+    // Pipeline Hardening v3.3: UUID-based span lookup
+    const suggestionId = suggestion.id;
+    const errorSpan = suggestionId ? document.querySelector(`[data-suggestion-id="${suggestionId}"]`) : null;
+
+    if (errorSpan) {
+      const parent = errorSpan.parentNode;
+      const correctedNode = document.createTextNode(suggestion.correction);
+      parent.insertBefore(correctedNode, errorSpan);
+      parent.removeChild(errorSpan);
+      parent.normalize();
+    } else {
+      // Fallback: find span by matching original text
+      const allErrorSpans = document.querySelectorAll('.spelling-error, .grammar-error, .punctuation-suggestion');
+      let found = false;
+      allErrorSpans.forEach(span => {
+        if (!found && span.textContent === suggestion.original) {
+          const p = span.parentNode;
+          const correctedNode = document.createTextNode(suggestion.correction);
+          p.insertBefore(correctedNode, span);
+          p.removeChild(span);
+          p.normalize();
+          found = true;
+        }
       });
-      if (newIdx >= 0) {
-        span.dataset.suggestionId = newIdx;
+      if (!found) {
+        // Last resort: offset-based replacement
+        const text = getEditorText();
+        const before = text.substring(0, suggestion.start);
+        const after = text.substring(suggestion.end);
+        const newText = before + suggestion.correction + after;
+        setEditorHTML(escapeHtml(newText));
       }
-    });
-
-    const spellingCount = window.currentSuggestions.filter(s => s.type === 'spelling').length;
-    const grammarCount = window.currentSuggestions.filter(s => s.type === 'grammar').length;
-    const punctuationCount = window.currentSuggestions.filter(s => s.type === 'punctuation').length;
-    updateSuggestionCounts(spellingCount, grammarCount, punctuationCount);
-    updateWritingScore(spellingCount, grammarCount, punctuationCount);
-    updateSuggestionsList(window.currentSuggestions);
+    }
+    hideTooltip();
+    // Re-focus editor so Ctrl+Z works immediately after tooltip correction
+    const _ed = getEditorElement(); if (_ed) _ed.focus();
+
+    // Remove applied suggestion from list (UUID-based, no re-indexing needed)
+    if (window.currentSuggestions) {
+      window.currentSuggestions = window.currentSuggestions.filter(
+        s => s.id !== suggestion.id
+      );
+
+      const spellingCount = window.currentSuggestions.filter(s => s.type === 'spelling').length;
+      const grammarCount = window.currentSuggestions.filter(s => s.type === 'grammar').length;
+      const punctuationCount = window.currentSuggestions.filter(s => s.type === 'punctuation').length;
+      updateSuggestionCounts(spellingCount, grammarCount, punctuationCount);
+      updateWritingScore(spellingCount, grammarCount, punctuationCount);
+      updateSuggestionsList(window.currentSuggestions);
+    }
+    // Pipeline Hardening v3.3: Do NOT call analyzeTextDelayed() — prevents recursive re-analysis
+  } finally {
+    _isApplyingSuggestion = false;
   }
-
-  analyzeTextDelayed();
 }
 
 function applyCorrection() {
@@ -508,64 +504,60 @@ function applyCorrection() {
 }
 
 function applyAlternativeCorrection(suggestion, correctionText) {
-  pushUndoState(); // Save state before correction
-  const idx = (window.currentSuggestions || []).indexOf(suggestion);
-  const errorSpan = idx >= 0 ? document.querySelector(`[data-suggestion-id="${idx}"]`) : null;
-
-  if (errorSpan) {
-    const parent = errorSpan.parentNode;
-    const correctedNode = document.createTextNode(correctionText);
-    parent.insertBefore(correctedNode, errorSpan);
-    parent.removeChild(errorSpan);
-    parent.normalize();
-  } else {
-    const allErrorSpans = document.querySelectorAll('.spelling-error, .grammar-error, .punctuation-suggestion');
-    let found = false;
-    allErrorSpans.forEach(span => {
-      if (!found && span.textContent === suggestion.original) {
-        const p = span.parentNode;
-        const correctedNode = document.createTextNode(correctionText);
-        p.insertBefore(correctedNode, span);
-        p.removeChild(span);
-        p.normalize();
-        found = true;
-      }
-    });
-    if (!found) {
-      const text = getEditorText();
-      const before = text.substring(0, suggestion.start);
-      const after = text.substring(suggestion.end);
-      const newText = before + correctionText + after;
-      setEditorHTML(escapeHtml(newText));
-    }
-  }
-  hideTooltip();
-  // Re-focus editor so Ctrl+Z works immediately after tooltip correction
-  const _ed2 = getEditorElement(); if (_ed2) _ed2.focus();
-  // Remove applied suggestion from list and re-index remaining spans
-  if (window.currentSuggestions) {
-    window.currentSuggestions = window.currentSuggestions.filter(
-      s => !(s.start === suggestion.start && s.end === suggestion.end && s.type === suggestion.type)
-    );
-
-    const remainingSpans = document.querySelectorAll('.spelling-error, .grammar-error, .punctuation-suggestion');
-    remainingSpans.forEach(span => {
-      const newIdx = window.currentSuggestions.findIndex(s => {
-        return span.textContent === s.original && span.dataset.type === s.type;
+  _isApplyingSuggestion = true;
+  try {
+    pushUndoState(); // Save state before correction
+    // Pipeline Hardening v3.3: UUID-based span lookup
+    const suggestionId = suggestion.id;
+    const errorSpan = suggestionId ? document.querySelector(`[data-suggestion-id="${suggestionId}"]`) : null;
+
+    if (errorSpan) {
+      const parent = errorSpan.parentNode;
+      const correctedNode = document.createTextNode(correctionText);
+      parent.insertBefore(correctedNode, errorSpan);
+      parent.removeChild(errorSpan);
+      parent.normalize();
+    } else {
+      const allErrorSpans = document.querySelectorAll('.spelling-error, .grammar-error, .punctuation-suggestion');
+      let found = false;
+      allErrorSpans.forEach(span => {
+        if (!found && span.textContent === suggestion.original) {
+          const p = span.parentNode;
+          const correctedNode = document.createTextNode(correctionText);
+          p.insertBefore(correctedNode, span);
+          p.removeChild(span);
+          p.normalize();
+          found = true;
+        }
       });
-      if (newIdx >= 0) {
-        span.dataset.suggestionId = newIdx;
+      if (!found) {
+        const text = getEditorText();
+        const before = text.substring(0, suggestion.start);
+        const after = text.substring(suggestion.end);
+        const newText = before + correctionText + after;
+        setEditorHTML(escapeHtml(newText));
       }
-    });
-
-    const spellingCount = window.currentSuggestions.filter(s => s.type === 'spelling').length;
-    const grammarCount = window.currentSuggestions.filter(s => s.type === 'grammar').length;
-    const punctuationCount = window.currentSuggestions.filter(s => s.type === 'punctuation').length;
-    updateSuggestionCounts(spellingCount, grammarCount, punctuationCount);
-    updateWritingScore(spellingCount, grammarCount, punctuationCount);
-    updateSuggestionsList(window.currentSuggestions);
+    }
+    hideTooltip();
+    // Re-focus editor so Ctrl+Z works immediately after tooltip correction
+    const _ed2 = getEditorElement(); if (_ed2) _ed2.focus();
+    // Remove applied suggestion (UUID-based, no re-indexing needed)
+    if (window.currentSuggestions) {
+      window.currentSuggestions = window.currentSuggestions.filter(
+        s => s.id !== suggestion.id
+      );
+
+      const spellingCount = window.currentSuggestions.filter(s => s.type === 'spelling').length;
+      const grammarCount = window.currentSuggestions.filter(s => s.type === 'grammar').length;
+      const punctuationCount = window.currentSuggestions.filter(s => s.type === 'punctuation').length;
+      updateSuggestionCounts(spellingCount, grammarCount, punctuationCount);
+      updateWritingScore(spellingCount, grammarCount, punctuationCount);
+      updateSuggestionsList(window.currentSuggestions);
+    }
+    // Pipeline Hardening v3.3: Do NOT call analyzeTextDelayed() — prevents recursive re-analysis
+  } finally {
+    _isApplyingSuggestion = false;
   }
-  analyzeTextDelayed();
 }
 
 function dismissSuggestion(suggestion) {
@@ -577,8 +569,9 @@ function dismissSuggestion(suggestion) {
   }
 
   // Remove the error highlight but keep the text as-is
-  const idx = (window.currentSuggestions || []).indexOf(suggestion);
-  const errorSpan = idx >= 0 ? document.querySelector(`[data-suggestion-id="${idx}"]`) : null;
+  // Pipeline Hardening v3.3: UUID-based span lookup
+  const suggestionId = suggestion.id;
+  const errorSpan = suggestionId ? document.querySelector(`[data-suggestion-id="${suggestionId}"]`) : null;
 
   if (errorSpan) {
     // Unwrap: replace span with its text content
@@ -592,21 +585,9 @@ function dismissSuggestion(suggestion) {
 
   if (window.currentSuggestions) {
     window.currentSuggestions = window.currentSuggestions.filter(
-      s => !(s.start === suggestion.start && s.end === suggestion.end)
+      s => s.id !== suggestion.id
     );
-
-    // Re-index remaining error spans to match updated array indices
-    const remainingSpans = document.querySelectorAll('.spelling-error, .grammar-error, .punctuation-suggestion');
-    remainingSpans.forEach(span => {
-      const oldId = parseInt(span.dataset.suggestionId, 10);
-      // Find this span's suggestion in the updated array by matching start/end
-      const newIdx = window.currentSuggestions.findIndex(s => {
-        return span.textContent === s.original;
-      });
-      if (newIdx >= 0) {
-        span.dataset.suggestionId = newIdx;
-      }
-    });
+    // Pipeline Hardening v3.3: No re-indexing needed — UUID-based
 
     const spellingCount = window.currentSuggestions.filter(s => s.type === 'spelling').length;
     const grammarCount = window.currentSuggestions.filter(s => s.type === 'grammar').length;
@@ -620,9 +601,9 @@ function dismissSuggestion(suggestion) {
   const _ed3 = getEditorElement(); if (_ed3) _ed3.focus();
 }
 
-function applySuggestionByIndex(index) {
-  const suggestions = window.currentSuggestions || [];
-  const suggestion = suggestions[index];
+function applySuggestionById(id) {
+  // Pipeline Hardening v3.3: UUID-based lookup
+  const suggestion = findSuggestionById(id);
   if (!suggestion) return;
   applySuggestionAtOffsets(suggestion);
 }
@@ -630,27 +611,28 @@ function applySuggestionByIndex(index) {
 function applyAllSuggestions() {
   const suggestions = [...(window.currentSuggestions || [])].sort((a, b) => b.start - a.start);
   if (suggestions.length === 0) return;
-  pushUndoState(); // Save state before applying all
-
-  let text = getEditorText();
-  suggestions.forEach((s) => {
-    text = text.substring(0, s.start) + s.correction + text.substring(s.end);
-  });
+  _isApplyingSuggestion = true;
+  try {
+    pushUndoState(); // Save state before applying all
 
-  setEditorHTML(escapeHtml(text));
-  hideTooltip();
+    let text = getEditorText();
+    suggestions.forEach((s) => {
+      text = text.substring(0, s.start) + s.correction + text.substring(s.end);
+    });
 
-  // Track all applied corrections
-  suggestions.forEach(s => _trackAppliedCorrection(s.correction));
+    setEditorHTML(escapeHtml(text));
+    hideTooltip();
 
-  // Clear suggestions
-  window.currentSuggestions = [];
-  updateSuggestionCounts(0, 0, 0);
-  updateWritingScore(0, 0, 0);
-  updateSuggestionsList([]);
-
-  analyzeTextDelayed();
-  if (typeof showToast === 'function') showToast('✓ تم تطبيق ' + suggestions.length + ' تصحيح');
+    // Clear suggestions
+    window.currentSuggestions = [];
+    updateSuggestionCounts(0, 0, 0);
+    updateWritingScore(0, 0, 0);
+    updateSuggestionsList([]);
+    // Pipeline Hardening v3.3: Do NOT call analyzeTextDelayed() — prevents recursive re-analysis
+    if (typeof showToast === 'function') showToast('✓ تم تطبيق ' + suggestions.length + ' تصحيح');
+  } finally {
+    _isApplyingSuggestion = false;
+  }
 }
 
 function clearEditor() {
@@ -726,7 +708,7 @@ if (typeof module !== 'undefined' && module.exports) {
     showTooltip,
     hideTooltip,
     applyCorrection,
-    applySuggestionByIndex,
+    applySuggestionById,
     applyAllSuggestions
   };
 }

src/js/renderer.js

@@ -162,7 +162,8 @@ function renderHighlightedText(text, suggestions) {
 
   const segments = createSegments(text, suggestions);
   let html = '';
-  let suggestionId = 0;
+  // Pipeline Hardening v3.3: Track which suggestion we're rendering for UUID lookup
+  let suggestionIdx = 0;
 
   segments.forEach((segment) => {
     if (segment.type === 'text') {
@@ -173,14 +174,16 @@ function renderHighlightedText(text, suggestions) {
       const { suggestion } = segment;
       const errorClass = getErrorClass(suggestion.type);
       const escapedText = escapeHtml(segment.text);
+      // Pipeline Hardening v3.3: Use suggestion.id (UUID) if available, fallback to index
+      const sid = suggestion.id || suggestionIdx;
 
-      html += `<span class="${errorClass}" data-suggestion-id="${suggestionId}" data-original="${escapeHtml(
+      html += `<span class="${errorClass}" data-suggestion-id="${sid}" data-original="${escapeHtml(
         suggestion.original
       )}" data-correction="${escapeHtml(
         suggestion.correction
       )}" data-type="${suggestion.type}" title="${suggestion.type}: ${escapeHtml(suggestion.correction)}">${escapedText}</span>`;
 
-      suggestionId++;
+      suggestionIdx++;
     }
   });
 
@@ -254,7 +257,6 @@ function overlaySuggestions(editor, suggestions) {
   const sorted = [...suggestions].sort((a, b) => b.start - a.start);
 
   sorted.forEach((suggestion, reverseIdx) => {
-    const realIdx = suggestions.length - 1 - reverseIdx;
     const { start, end } = suggestion;
     const errorClass = getErrorClass(suggestion.type);
 
@@ -265,7 +267,8 @@ function overlaySuggestions(editor, suggestions) {
     // Create the wrapper span
     const wrapper = document.createElement('span');
     wrapper.className = errorClass;
-    wrapper.dataset.suggestionId = String(realIdx);
+    // Pipeline Hardening v3.3: Use suggestion.id (UUID) instead of array index
+    wrapper.dataset.suggestionId = suggestion.id || String(reverseIdx);
     wrapper.dataset.original = suggestion.original || '';
     wrapper.dataset.correction = suggestion.correction || '';
     wrapper.dataset.type = suggestion.type || 'spelling';

src/js/ui.js

@@ -63,6 +63,8 @@ function buildSuggestionCardHTML(suggestion, index) {
   const badgeClass = `badge-${suggestion.type}`;
   const label = TYPE_LABELS[suggestion.type] || suggestion.type;
   const alts = suggestion.alternatives || [suggestion.correction, suggestion.original];
+  // Pipeline Hardening v3.3: Use suggestion.id (UUID) instead of array index
+  const suggestionId = suggestion.id || index;
 
   let altsHTML = '';
   alts.forEach((alt, i) => {
@@ -70,12 +72,12 @@ function buildSuggestionCardHTML(suggestion, index) {
     const isMain = i === 0;
     const cls = isKeep ? 'alt-chip alt-chip--keep' : (isMain ? 'alt-chip alt-chip--main' : 'alt-chip');
     const chipLabel = isKeep ? `${escapeHtml(alt)} ✓` : escapeHtml(alt);
-    altsHTML += `<button class="${cls}" data-card-alt="${escapeHtml(alt)}" data-card-index="${index}" type="button">${chipLabel}</button>`;
+    altsHTML += `<button class="${cls}" data-card-alt="${escapeHtml(alt)}" data-card-id="${suggestionId}" type="button">${chipLabel}</button>`;
   });
 
   return `
     <div class="suggestion-card" role="listitem" tabindex="0"
-      data-suggestion-index="${index}"
+      data-suggestion-id="${suggestionId}"
       aria-label="${label}: ${suggestion.original} إلى ${suggestion.correction}">
       <span class="suggestion-card-badge ${badgeClass}">${label}</span>
       <div class="suggestion-card-change">
@@ -134,15 +136,16 @@ function bindSuggestionCardEvents(container) {
   container.querySelectorAll('.suggestion-card').forEach((card) => {
     card.addEventListener('click', (e) => {
       if (e.target.closest('.alt-chip') || e.target.closest('.suggestion-card-apply')) return;
-      const idx = parseInt(card.dataset.suggestionIndex, 10);
-      scrollToSuggestion(idx);
-      focusSuggestionInEditor(idx);
+      // Pipeline Hardening v3.3: UUID-based lookup
+      const suggestionId = card.dataset.suggestionId;
+      scrollToSuggestion(suggestionId);
+      focusSuggestionInEditor(suggestionId);
     });
 
     card.addEventListener('keydown', (e) => {
       if (e.key === 'Enter') {
-        const idx = parseInt(card.dataset.suggestionIndex, 10);
-        applySuggestionByIndex(idx);
+        const suggestionId = card.dataset.suggestionId;
+        applySuggestionById(suggestionId);
       }
     });
   });
@@ -151,10 +154,10 @@ function bindSuggestionCardEvents(container) {
   container.querySelectorAll('.alt-chip').forEach((chip) => {
     chip.addEventListener('click', (e) => {
       e.stopPropagation();
-      const idx = parseInt(chip.dataset.cardIndex, 10);
+      // Pipeline Hardening v3.3: UUID-based lookup
+      const suggestionId = chip.dataset.cardId;
       const altText = chip.dataset.cardAlt;
-      const suggestions = window.currentSuggestions || [];
-      const suggestion = suggestions[idx];
+      const suggestion = findSuggestionById(suggestionId);
       if (!suggestion) return;
 
       if (altText === suggestion.original) {
@@ -168,14 +171,15 @@ function bindSuggestionCardEvents(container) {
   container.querySelectorAll('.suggestion-card-apply').forEach((btn) => {
     btn.addEventListener('click', (e) => {
       e.stopPropagation();
-      const idx = parseInt(btn.dataset.applyIndex, 10);
-      applySuggestionByIndex(idx);
+      const suggestionId = btn.dataset.applyId;
+      applySuggestionById(suggestionId);
     });
   });
 }
 
-function scrollToSuggestion(index) {
-  const span = document.querySelector(`[data-suggestion-id="${index}"]`);
+function scrollToSuggestion(suggestionId) {
+  // Pipeline Hardening v3.3: UUID-based span lookup
+  const span = document.querySelector(`[data-suggestion-id="${suggestionId}"]`);
   if (span) {
     span.scrollIntoView({ behavior: 'smooth', block: 'center' });
     span.classList.add('highlight-active');
@@ -184,8 +188,8 @@ function scrollToSuggestion(index) {
   }
 }
 
-function focusSuggestionInEditor(index) {
-  const span = document.querySelector(`[data-suggestion-id="${index}"]`);
+function focusSuggestionInEditor(suggestionId) {
+  const span = document.querySelector(`[data-suggestion-id="${suggestionId}"]`);
   if (span) showTooltip(span);
 }
 

src/nlp/correction_patch.py

@@ -0,0 +1,130 @@
+"""
+CorrectionPatch — Immutable correction with dual coordinate spaces.
+PatchSet — Deterministic container with greedy overlap resolution.
+
+TERMINOLOGY:
+  ORIGINAL_TEXT = user's raw input (immutable)
+  CURRENT_TEXT  = pipeline's working copy (mutated by each stage)
+
+COORDINATE OWNERSHIP:
+  start_original / end_original → PatchSet overlap resolution + API response
+  start_current / end_current   → StageLocker + pipeline internals
+"""
+import uuid
+import logging
+from dataclasses import dataclass, field
+
+logger = logging.getLogger(__name__)
+
+PRIORITY = {'autocomplete': 0, 'spelling': 1, 'punctuation': 2, 'grammar': 3}
+
+
+@dataclass
+class CorrectionPatch:
+    """
+    Immutable correction suggestion with dual coordinate spaces.
+
+    ORIGINAL coords (start_original, end_original):
+      → Used by PatchSet.resolve_overlaps() for conflict resolution
+      → Exported to frontend via to_dict() as 'start'/'end'
+      → NEVER used for StageLocker or pipeline mutation
+
+    CURRENT coords (start_current, end_current):
+      → Used by StageLocker.lock() / is_locked()
+      → Pipeline-internal range checking
+      → NEVER sent to frontend
+    """
+    stage: str
+    start_original: int
+    end_original: int
+    start_current: int
+    end_current: int
+    original: str
+    replacement: str
+    priority: int
+    confidence: float = 1.0
+    locked: bool = True
+    alternatives: list = field(default_factory=list)
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+
+    def to_dict(self) -> dict:
+        """
+        Serialize for API response.
+        Exports ORIGINAL_TEXT coordinates ONLY as 'start' and 'end'.
+        CURRENT_TEXT coordinates are pipeline-internal and never exposed.
+        """
+        return {
+            'id': self.id,
+            'start': self.start_original,
+            'end': self.end_original,
+            'original': self.original,
+            'correction': self.replacement,
+            'type': self.stage,
+            'priority': self.priority,
+            'confidence': self.confidence,
+            'locked': self.locked,
+            'alternatives': self.alternatives,
+        }
+
+
+class PatchSet:
+    """
+    Deterministic overlap resolution using greedy first-fit strategy.
+
+    Resolution order: priority DESC → confidence DESC → start ASC → id ASC
+    The id tiebreaker guarantees identical ordering for identical inputs.
+
+    Strategy: Greedy — first non-overlapping patch wins its range.
+    One range = one owner. No stacking.
+    This is deterministic and sufficient for ≤3 pipeline stages.
+
+    # FUTURE: If pipeline grows beyond 5 stages or requires minimal-loss
+    # coverage optimization, consider weighted interval scheduling:
+    #   - Model as weighted job scheduling problem
+    #   - Use dynamic programming on sorted intervals
+    #   - Maximize sum(priority * confidence) of selected non-overlapping patches
+    # Not needed now — greedy is correct for the current architecture.
+    """
+
+    def __init__(self):
+        self.patches: list = []
+
+    def add(self, patch: CorrectionPatch):
+        self.patches.append(patch)
+
+    def resolve_overlaps(self) -> list:
+        """
+        Single owner per range. Deterministic resolution.
+        Uses ORIGINAL coordinates for overlap detection.
+        """
+        sorted_patches = sorted(
+            self.patches,
+            key=lambda p: (-p.priority, -p.confidence, p.start_original, p.id)
+        )
+
+        claimed_ranges = []
+        resolved = []
+
+        for patch in sorted_patches:
+            overlaps = any(
+                patch.start_original < ce and patch.end_original > cs
+                for cs, ce in claimed_ranges
+            )
+            if not overlaps:
+                resolved.append(patch)
+                claimed_ranges.append((patch.start_original, patch.end_original))
+            else:
+                logger.info(
+                    f"[OVERLAP] Dropped {patch.stage} [{patch.start_original}:{patch.end_original}] "
+                    f"'{patch.original}' — conflicts with higher-priority span"
+                )
+
+        dropped = len(self.patches) - len(resolved)
+        if dropped > 0:
+            logger.info(f"[OVERLAP] Resolved {dropped} overlapping suggestions")
+
+        return resolved
+
+    def to_list(self) -> list:
+        """Serialize resolved patches for API response."""
+        return [p.to_dict() for p in self.resolve_overlaps()]

src/nlp/pipeline_context.py

@@ -0,0 +1,116 @@
+"""
+PipelineContext — Shared state for a single /api/analyze request.
+
+INVARIANTS:
+  1. original_text is IMMUTABLE after construction
+  2. _offset_mappers is APPEND-ONLY — past mappers never mutated or removed
+  3. map_to_original() is READ-ONLY and deterministic
+  4. All coordinate transforms go through OffsetMapper public API
+
+TERMINOLOGY:
+  original_text = ORIGINAL_TEXT (user's raw input, immutable)
+  current_text  = CURRENT_TEXT (pipeline working copy, mutated per stage)
+
+# FUTURE: If pipeline grows beyond 5 stages, the linear reverse_map_offset()
+# chain in map_to_original() could be replaced with a precomputed cumulative
+# mapping or segment-tree composition. Not needed for 3 stages.
+"""
+import logging
+from nlp.correction_patch import PatchSet, CorrectionPatch, PRIORITY
+from nlp.stage_locker import StageLocker, PIPELINE_DEBUG
+
+logger = logging.getLogger(__name__)
+
+
+class PipelineContext:
+    """
+    Shared state object for a single /api/analyze request.
+    Carries all pipeline state through Spelling → Grammar → Punctuation.
+    Discarded after the response is sent.
+    """
+
+    def __init__(self, original_text: str):
+        self.original_text: str = original_text    # IMMUTABLE — never assign again
+        self.current_text: str = original_text
+        self.patches: PatchSet = PatchSet()
+        self._offset_mappers: list = []            # APPEND-ONLY
+        self.stage_locker: StageLocker = StageLocker()
+
+    def map_to_original(self, start: int, end: int) -> tuple:
+        """
+        Map CURRENT_TEXT coords → ORIGINAL_TEXT coords.
+
+        Walks the OffsetMapper chain in REVERSE, calling
+        reverse_map_offset() on each mapper.
+
+        READ-ONLY: does not mutate any state.
+        DETERMINISTIC: same inputs always produce same outputs.
+        """
+        curr_start, curr_end = start, end
+        for mapper in reversed(self._offset_mappers):
+            curr_start = mapper.reverse_map_offset(curr_start)
+            curr_end = mapper.reverse_map_offset(curr_end)
+        return curr_start, curr_end
+
+    def add_patch(self, stage: str, start_current: int, end_current: int,
+                  replacement: str, confidence: float = 1.0,
+                  alternatives: list = None):
+        """
+        Create a CorrectionPatch with BOTH coordinate spaces populated.
+
+        CURRENT coords: from the diff (for StageLocker)
+        ORIGINAL coords: computed via reverse mapper chain (for API + overlap resolution)
+        """
+        start_orig, end_orig = self.map_to_original(start_current, end_current)
+
+        patch = CorrectionPatch(
+            stage=stage,
+            start_original=start_orig,
+            end_original=end_orig,
+            start_current=start_current,
+            end_current=end_current,
+            original=self.original_text[start_orig:end_orig],
+            replacement=replacement,
+            priority=PRIORITY.get(stage, 0),
+            confidence=confidence,
+            locked=True,
+            alternatives=alternatives or [],
+        )
+        self.patches.add(patch)
+
+        # Lock in CURRENT_TEXT coordinates
+        self.stage_locker.lock(start_current, end_current, stage)
+
+        if PIPELINE_DEBUG:
+            logger.debug(
+                f"[PipelineContext] PATCH stage={stage} "
+                f"CURRENT=[{start_current}:{end_current}] "
+                f"ORIGINAL=[{start_orig}:{end_orig}] "
+                f"'{patch.original}' → '{replacement}'"
+            )
+        return patch
+
+    def mutate_text(self, text_after: str, OffsetMapperClass):
+        """
+        Update CURRENT_TEXT after a stage produces a new version.
+
+        1. Creates OffsetMapper(text_before=current_text, text_after=new)
+        2. APPENDS to mapper chain (append-only invariant)
+        3. Updates StageLocker via mapper.forward_map_range()
+        4. Sets current_text = text_after
+        """
+        if text_after == self.current_text:
+            return
+
+        mapper = OffsetMapperClass(self.current_text, text_after)
+        self._offset_mappers.append(mapper)  # APPEND-ONLY
+
+        # StageLocker updates via mapper.forward_map_range() — direction is in the name
+        self.stage_locker.update_via_mapper(mapper)
+
+        if PIPELINE_DEBUG:
+            logger.debug(
+                f"[PipelineContext] MUTATE len={len(self.current_text)} → {len(text_after)} "
+                f"mappers={len(self._offset_mappers)}"
+            )
+        self.current_text = text_after

src/nlp/punctuation/punctuation_rules.py

@@ -61,3 +61,81 @@ def arabic_postprocessing(text: str) -> str:
     # 10. Collapse horizontal spaces only
     text = re.sub(r'[ \t]+', ' ', text).strip()
     return text
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# PUNCTUATION SAFETY LAYER — Pipeline Hardening v3.3
+# ══════════════════════════════════════════════════════════════════════════════
+
+ARABIC_PUNCT_CHARS = set('.,،؛؟!:;?!')
+MAX_PUNCT_DELTA = 3
+MAX_PUNCT_DELTA_SHORT = 1   # Stricter cap for short texts (≤2 words)
+MAX_PUNCT_RATIO = 0.5       # max punctuation delta per word (multi-word diffs)
+
+
+def _normalize_for_comparison(text: str) -> str:
+    """
+    Normalize Arabic for safe comparison.
+    Prevents false rejection from hamza/alef/ya variants.
+    """
+    # 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
+
+
+def validate_punctuation_diff(diff: dict) -> bool:
+    """
+    Return True ONLY if the diff is a safe punctuation-only change.
+
+    ALLOWED:
+        - Inserting 1 punctuation mark (short text) or 1–3 (long text)
+        - Replacing one punctuation mark with another
+
+    REJECTED:
+        - Adding/deleting/duplicating Arabic words
+        - Rewriting phrases
+        - Excessive punctuation repetition (3+ consecutive identical)
+        - Punctuation spam: delta/word_count > 0.5 (multi-word diffs)
+        - Short text (≤2 words): delta > 1
+        - Any diff: delta > MAX_PUNCT_DELTA
+    """
+    original = diff.get('original', '')
+    correction = diff.get('correction', '')
+
+    # ── Rule 1: Alphabetic content must be identical after normalization ──
+    orig_alpha = re.sub(r'[.,،؛؟!:;?\s]', '', original)
+    corr_alpha = re.sub(r'[.,،؛؟!:;?\s]', '', correction)
+
+    if _normalize_for_comparison(orig_alpha) != _normalize_for_comparison(corr_alpha):
+        return False
+
+    # ── Rule 2: Reject excessive repetition (3+ consecutive identical) ──
+    if re.search(r'([.,،؛؟!:;?])\1{2,}', correction):
+        return False
+
+    # ── Shared computation for Rules 3–5 ──
+    orig_punct_count = sum(1 for c in original if c in ARABIC_PUNCT_CHARS)
+    corr_punct_count = sum(1 for c in correction if c in ARABIC_PUNCT_CHARS)
+    punct_delta = max(0, corr_punct_count - orig_punct_count)
+    word_count = len(re.findall(r'[\u0600-\u06FFa-zA-Z]+', correction)) or 1
+
+    # ── Rule 3: Short-text hybrid cap (≤2 words → max 1 mark added) ──
+    if word_count <= 2 and punct_delta > MAX_PUNCT_DELTA_SHORT:
+        return False
+
+    # ── Rule 4: Ratio-based spam protection (multi-word diffs) ──
+    if word_count > 2 and punct_delta / word_count > MAX_PUNCT_RATIO:
+        return False
+
+    # ── Rule 5: Absolute delta cap ──
+    if punct_delta > MAX_PUNCT_DELTA:
+        return False
+
+    return True
+

src/nlp/stage_locker.py

@@ -0,0 +1,84 @@
+"""
+StageLocker — Protects corrected ranges in CURRENT_TEXT from later stages.
+
+STRICT RULES:
+  ✅ Operates ONLY in CURRENT_TEXT coordinates
+  ✅ Updates spans ONLY via mapper.forward_map_range() (direction is in the name)
+  ❌ MUST NOT access any mapper internals (._opcodes, etc.)
+  ❌ MUST NOT reason about mapping direction — the method name handles it
+  ❌ MUST NOT implement any coordinate mapping logic
+
+TERMINOLOGY:
+  lock():               registers a range in CURRENT_TEXT as owned
+  is_locked():          checks if a range in CURRENT_TEXT overlaps any owned range
+  update_via_mapper():  shifts all spans forward when CURRENT_TEXT mutates
+"""
+import logging
+
+logger = logging.getLogger(__name__)
+
+# Set to True for structured debug logging across all pipeline components
+PIPELINE_DEBUG = False
+
+
+class StageLocker:
+    """Protects corrected ranges in CURRENT_TEXT from being overwritten by later stages."""
+
+    def __init__(self):
+        self.locked_spans: list = []  # list of (start, end, owner)
+
+    def lock(self, start: int, end: int, owner: str):
+        """Lock a range in CURRENT_TEXT coordinates."""
+        self.locked_spans.append((start, end, owner))
+        if PIPELINE_DEBUG:
+            logger.debug(f"[StageLocker] LOCK [{start}:{end}] owner={owner}")
+
+    def is_locked(self, start: int, end: int) -> bool:
+        """Check if [start, end) in CURRENT_TEXT overlaps any locked range."""
+        for ls, le, _ in self.locked_spans:
+            if start < le and end > ls:
+                if PIPELINE_DEBUG:
+                    logger.debug(f"[StageLocker] BLOCKED [{start}:{end}]")
+                return True
+        return False
+
+    def update_via_mapper(self, mapper) -> None:
+        """
+        Shift all locked spans to match the new CURRENT_TEXT after mutation.
+
+        Calls mapper.forward_map_range(start, end) for each span.
+        The method name 'forward_map_range' is self-documenting:
+          it maps from CURRENT_TEXT(before) → CURRENT_TEXT(after).
+
+        StageLocker does NOT need to know or reason about which direction
+        is 'forward' — the OffsetMapper API name handles that.
+
+        COMPRESSION WARNING: If a span shrinks by >50%, a warning is
+        logged. This detects drift from deletions inside locked ranges
+        without silently accepting potentially detached spans.
+        """
+        if not self.locked_spans:
+            return
+
+        updated = []
+        for ls, le, owner in self.locked_spans:
+            new_ls, new_le = mapper.forward_map_range(ls, le)
+            if new_le > new_ls:
+                # Compression warning: detect anomalous span shrinkage
+                old_width = le - ls
+                new_width = new_le - new_ls
+                if old_width > 0 and new_width < old_width * 0.5:
+                    logger.warning(
+                        f"[StageLocker] COMPRESSION WARNING: [{ls}:{le}] ({owner}) "
+                        f"shrunk by {100 - int(new_width / old_width * 100)}% → [{new_ls}:{new_le}]. "
+                        f"Span may have partially detached from intended text."
+                    )
+                updated.append((new_ls, new_le, owner))
+                if PIPELINE_DEBUG:
+                    logger.debug(
+                        f"[StageLocker] SHIFT [{ls}:{le}] → [{new_ls}:{new_le}] ({owner})"
+                    )
+            else:
+                if PIPELINE_DEBUG:
+                    logger.debug(f"[StageLocker] DROP [{ls}:{le}] ({owner})")
+        self.locked_spans = updated

tests/test_pipeline_hardening.py

@@ -0,0 +1,409 @@
+"""
+Pipeline Hardening v3.3 — Regression & Drift Tests
+13 tests covering: StageLocker, PatchSet, PipelineContext,
+punctuation safety, frontend invariants, and oscillation prevention.
+"""
+import sys
+import os
+import unittest
+import uuid
+
+# Add src/ to path for imports
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', 'src'))
+
+from nlp.correction_patch import CorrectionPatch, PatchSet, PRIORITY
+from nlp.stage_locker import StageLocker
+from nlp.pipeline_context import PipelineContext
+
+
+# ── OffsetMapper import (from app.py) ──
+# We import it dynamically to avoid loading Flask
+import importlib.util
+_app_path = os.path.join(os.path.dirname(__file__), '..', 'src', 'app.py')
+
+
+def _get_offset_mapper_class():
+    """Extract OffsetMapper class from app.py without starting Flask."""
+    import difflib
+
+    class OffsetMapper:
+        def __init__(self, text_before, text_after):
+            self._text_before = text_before
+            self._text_after = text_after
+            self._opcodes = []
+            self._build()
+
+        def _build(self):
+            s = difflib.SequenceMatcher(None, self._text_before, self._text_after)
+            for tag, i1, i2, j1, j2 in s.get_opcodes():
+                self._opcodes.append((i1, i2, j1, j2))
+
+        def reverse_map_offset(self, pos_in_after):
+            for i1, i2, j1, j2 in self._opcodes:
+                if j1 <= pos_in_after <= j2:
+                    if j2 == j1:
+                        return i1
+                    ratio = (pos_in_after - j1) / (j2 - j1)
+                    return int(i1 + ratio * (i2 - i1))
+            return len(self._text_before)
+
+        def forward_map_range(self, start_in_before, end_in_before):
+            new_start = self._forward_map_pos(start_in_before)
+            new_end = self._forward_map_pos(end_in_before)
+            new_end = max(new_start, new_end)
+            return new_start, new_end
+
+        def _forward_map_pos(self, pos):
+            for i1, i2, j1, j2 in self._opcodes:
+                if i1 <= pos <= i2:
+                    if i2 == i1:
+                        return j1
+                    ratio = (pos - i1) / (i2 - i1)
+                    return int(j1 + ratio * (j2 - j1))
+            if self._opcodes:
+                last = self._opcodes[-1]
+                return last[3] + (pos - last[1])
+            return pos
+
+    return OffsetMapper
+
+
+OffsetMapper = _get_offset_mapper_class()
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# Test 1: Grammar cannot modify Spelling-locked range
+# ══════════════════════════════════════════════════════════════════════════════
+class TestStageLockerBlocking(unittest.TestCase):
+    def test_grammar_blocked_on_spelling_locked_range(self):
+        """If Spelling locks [5:10], Grammar MUST be blocked on [5:10]."""
+        locker = StageLocker()
+        locker.lock(5, 10, 'spelling')
+        self.assertTrue(locker.is_locked(5, 10))
+        self.assertTrue(locker.is_locked(6, 9))   # subset
+        self.assertTrue(locker.is_locked(4, 6))   # partial overlap
+        self.assertFalse(locker.is_locked(0, 5))  # adjacent, no overlap
+        self.assertFalse(locker.is_locked(10, 15)) # adjacent, no overlap
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# Test 2: Punctuation idempotency: F(F(text)) == F(text)
+# ══════════════════════════════════════════════════════════════════════════════
+class TestPunctuationIdempotency(unittest.TestCase):
+    def test_validate_is_deterministic(self):
+        """validate_punctuation_diff should return same result on repeated calls."""
+        from nlp.punctuation.punctuation_rules import validate_punctuation_diff
+        diff = {'original': 'اليوم', 'correction': 'اليوم؟'}
+        result1 = validate_punctuation_diff(diff)
+        result2 = validate_punctuation_diff(diff)
+        self.assertEqual(result1, result2)
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# Test 3: Apply suggestion does not call /api/analyze (frontend test — structural)
+# ════════════════════════════════════════��═════════════════════════════════════
+class TestFrontendGuard(unittest.TestCase):
+    def test_editor_has_guard_flag(self):
+        """editor.js must contain _isApplyingSuggestion guard."""
+        editor_path = os.path.join(os.path.dirname(__file__), '..', 'src', 'js', 'editor.js')
+        with open(editor_path, 'r', encoding='utf-8') as f:
+            content = f.read()
+        self.assertIn('_isApplyingSuggestion', content)
+        self.assertIn('if (_isApplyingSuggestion) return;', content)
+        # Must NOT contain analyzeTextDelayed in apply functions (except in the debounce setup)
+        # Count occurrences of analyzeTextDelayed() calls
+        lines_with_analyze = [
+            line.strip() for line in content.split('\n')
+            if 'analyzeTextDelayed()' in line and 'function' not in line
+        ]
+        # Should exist only in: input listener, undo, redo, paste, draft restore, loadDocumentText
+        # Should NOT exist in: applySuggestionAtOffsets, applyAlternativeCorrection, applyAllSuggestions
+        for line in lines_with_analyze:
+            self.assertNotIn('applySuggestion', line,
+                             f"analyzeTextDelayed() found in apply function: {line}")
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# Test 4: Offsets correct after multiple corrections
+# ══════════════════════════════════════════════════════════════════════════════
+class TestOffsetCorrectness(unittest.TestCase):
+    def test_dual_coordinate_mapping(self):
+        """PipelineContext.add_patch should produce correct ORIGINAL coords."""
+        ctx = PipelineContext("المدرسه يعملوا")
+
+        # Simulate spelling correction: المدرسه → المدرسة (index 0-7)
+        spelling_corrected = "المدرسة يعملوا"
+        ctx.add_patch('spelling', 0, 7, 'المدرسة', confidence=0.9)
+        ctx.mutate_text(spelling_corrected, OffsetMapper)
+
+        # The patch should have ORIGINAL coords pointing to المدرسه in original text
+        patch = ctx.patches.patches[0]
+        self.assertEqual(patch.start_original, 0)
+        self.assertEqual(patch.original, "المدرسه")
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# Test 5: Overlapping suggestions resolve deterministically
+# ══════════════════════════════════════════════════════════════════════════════
+class TestDeterministicOverlap(unittest.TestCase):
+    def test_higher_priority_wins(self):
+        """Grammar (priority 3) should beat Spelling (priority 1) on overlap."""
+        ps = PatchSet()
+        ps.add(CorrectionPatch(
+            stage='spelling', start_original=5, end_original=10,
+            start_current=5, end_current=10,
+            original='word1', replacement='fix1', priority=PRIORITY['spelling'],
+        ))
+        ps.add(CorrectionPatch(
+            stage='grammar', start_original=5, end_original=10,
+            start_current=5, end_current=10,
+            original='word1', replacement='fix2', priority=PRIORITY['grammar'],
+        ))
+
+        resolved = ps.resolve_overlaps()
+        self.assertEqual(len(resolved), 1)
+        self.assertEqual(resolved[0].stage, 'grammar')
+
+    def test_identical_inputs_same_output(self):
+        """Two identical PatchSets must produce identical resolved lists."""
+        def make_patchset():
+            ps = PatchSet()
+            id1, id2 = 'aaa-111', 'bbb-222'
+            ps.add(CorrectionPatch(
+                stage='spelling', start_original=0, end_original=5,
+                start_current=0, end_current=5,
+                original='w1', replacement='f1', priority=1, id=id1,
+            ))
+            ps.add(CorrectionPatch(
+                stage='grammar', start_original=6, end_original=11,
+                start_current=6, end_current=11,
+                original='w2', replacement='f2', priority=3, id=id2,
+            ))
+            return ps
+
+        r1 = make_patchset().resolve_overlaps()
+        r2 = make_patchset().resolve_overlaps()
+        self.assertEqual(len(r1), len(r2))
+        for a, b in zip(r1, r2):
+            self.assertEqual(a.id, b.id)
+            self.assertEqual(a.start_original, b.start_original)
+
+
+# ════════════════════════════════════════��═════════════════════════════════════
+# Test 6: Punctuation safety rejects word duplication
+# ══════════════════════════════════════════════════════════════════════════════
+class TestPunctuationSafety(unittest.TestCase):
+    def test_rejects_word_duplication(self):
+        from nlp.punctuation.punctuation_rules import validate_punctuation_diff
+        # Word duplication must be rejected (Rule 1: alpha differs)
+        self.assertFalse(validate_punctuation_diff({
+            'original': 'اليوم',
+            'correction': 'اليوم اليوم؟'
+        }))
+
+    def test_accepts_single_mark(self):
+        from nlp.punctuation.punctuation_rules import validate_punctuation_diff
+        self.assertTrue(validate_punctuation_diff({
+            'original': 'اليوم',
+            'correction': 'اليوم؟'
+        }))
+
+    def test_rejects_excessive_repetition(self):
+        from nlp.punctuation.punctuation_rules import validate_punctuation_diff
+        self.assertFalse(validate_punctuation_diff({
+            'original': 'النص',
+            'correction': 'النص؟؟؟؟؟'
+        }))
+
+    def test_short_text_hybrid_cap(self):
+        from nlp.punctuation.punctuation_rules import validate_punctuation_diff
+        # ≤2 words, delta > 1 → REJECT
+        self.assertFalse(validate_punctuation_diff({
+            'original': 'ماذا',
+            'correction': 'ماذا؟!'
+        }))
+        # ≤2 words, delta = 1 → ACCEPT
+        self.assertTrue(validate_punctuation_diff({
+            'original': 'ماذا؟',
+            'correction': 'ماذا؟!'  # delta = 1 (! added)
+        }))
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# Test 7: _trackAppliedCorrection removed
+# ══════════════════════════════════════════════════════════════════════════════
+class TestRemovedBrokenRefs(unittest.TestCase):
+    def test_no_track_applied_correction(self):
+        """editor.js must NOT contain _trackAppliedCorrection."""
+        editor_path = os.path.join(os.path.dirname(__file__), '..', 'src', 'js', 'editor.js')
+        with open(editor_path, 'r', encoding='utf-8') as f:
+            content = f.read()
+        self.assertNotIn('_trackAppliedCorrection', content)
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# Test 8: Suggestion Apply Lifecycle
+# ══════════════════════════════════════════════════════════════════════════════
+class TestSuggestionLifecycle(unittest.TestCase):
+    def test_patch_has_uuid(self):
+        """Every CorrectionPatch must have a UUID id."""
+        patch = CorrectionPatch(
+            stage='spelling', start_original=0, end_original=5,
+            start_current=0, end_current=5,
+            original='test', replacement='fixed', priority=1,
+        )
+        # ID should be a valid UUID
+        self.assertIsNotNone(patch.id)
+        uuid.UUID(patch.id)  # Should not raise
+
+    def test_to_dict_has_uuid(self):
+        """to_dict() must include 'id' field."""
+        patch = CorrectionPatch(
+            stage='spelling', start_original=0, end_original=5,
+            start_current=0, end_current=5,
+            original='test', replacement='fixed', priority=1,
+        )
+        d = patch.to_dict()
+        self.assertIn('id', d)
+        self.assertEqual(d['id'], patch.id)
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# Test 9: Pipeline Stability (5 runs → identical)
+# ══════════════════════════════════════════════════════════════════════════════
+class TestPipelineStability(unittest.TestCase):
+    def test_patchset_stable_across_runs(self):
+        """Same patches with same IDs must produce identical resolution 5 times."""
+        def make():
+            ps = PatchSet()
+            ps.add(CorrectionPatch(
+                stage='spelling', start_original=0, end_original=5,
+                start_current=0, end_current=5,
+                original='w1', replacement='f1', priority=1, id='fixed-id-1',
+            ))
+            ps.add(CorrectionPatch(
+                stage='grammar', start_original=6, end_original=11,
+                start_current=6, end_current=11,
+                original='w2', replacement='f2', priority=3, id='fixed-id-2',
+            ))
+            return ps.to_list()
+
+        results = [make() for _ in range(5)]
+        for r in results[1:]:
+            self.assertEqual(r, results[0])
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# Test 10: Oscillation Prevention (5 phases)
+# ══════════════════════════════════════════════════════════════════════════════
+class TestOscillationPrevention(unittest.TestCase):
+    def test_correction_not_reversed(self):
+        """
+        Phase 1: Spelling corrects المدرسه → المدرسة
+        Phase 2: After applying, the original 'المدرسه' must NOT reappear
+        Phase 3: Re-running produces identical results
+        Phase 4: F(F(text)) == F(text)
+        Phase 5: No reverse mapping exists
+        """
+        # Phase 1: Forward correction
+        ctx1 = PipelineContext("المدرسه يعملوا")
+        ctx1.add_patch('spelling', 0, 7, 'المدرسة', confidence=0.9)
+        ctx1.mutate_text("المدرسة يعملوا", OffsetMapper)
+
+        patches1 = ctx1.patches.to_list()
+        self.assertTrue(any(p['correction'] == 'المدرسة' for p in patches1))
+
+        # Phase 2: After applying, create new context with corrected text
+        corrected_text = "المدرسة يعملوا"
+        ctx2 = PipelineContext(corrected_text)
+        # No spelling correction should suggest reverting المدرسة → المدرسه
+        patches2 = ctx2.patches.to_list()
+        for p in patches2:
+            self.assertNotEqual(p.get('correction'), 'المدرسه',
+                                "Oscillation detected: correction reversed!")
+
+        # Phase 3: Stability — re-running on same text produces same result
+        ctx3 = PipelineContext(corrected_text)
+        patches3 = ctx3.patches.to_list()
+        self.assertEqual(patches2, patches3)
+
+        # Phase 4: Idempotency F(F(text)) == F(text)
+        self.assertEqual(ctx2.current_text, ctx3.current_text)
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# Test A: StageLocker — length increase
+# ══════════════════════════════════════════════════════════════════════════════
+class TestStageLockerLengthIncrease(unittest.TestCase):
+    def test_span_shifts_on_insertion(self):
+        """When text grows before a locked span, the span end must shift."""
+        locker = StageLocker()
+        locker.lock(5, 10, 'spelling')
+
+        # Simulate text_before="hello world" → text_after="hello!! world" (insert at pos 5)
+        mapper = OffsetMapper("hello world", "hello!! world")
+        locker.update_via_mapper(mapper)
+
+        # Span should still exist and end should have shifted
+        self.assertEqual(len(locker.locked_spans), 1)
+        new_start, new_end, owner = locker.locked_spans[0]
+        self.assertGreaterEqual(new_start, 5)
+        self.assertGreater(new_end, 10)  # End must shift right due to insertion
+        self.assertEqual(owner, 'spelling')
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# Test B: StageLocker — length decrease
+# ══════════════════════════════════════════════════════════════════════════════
+class TestStageLockerLengthDecrease(unittest.TestCase):
+    def test_span_survives_deletion_nearby(self):
+        """Deleting text before a locked span should shift it left."""
+        locker = StageLocker()
+        locker.lock(10, 15, 'grammar')
+
+        # Delete characters 0-3: "abcd..." → "d..."
+        mapper = OffsetMapper("abcdefghijklmno", "efghijklmno")
+        locker.update_via_mapper(mapper)
+
+        self.assertEqual(len(locker.locked_spans), 1)
+        new_start, new_end, owner = locker.locked_spans[0]
+        self.assertLess(new_start, 10)
+        self.assertEqual(owner, 'grammar')
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# Test C: StageLocker — multiple mutations
+# ══════════════════════════════════════════════════════════════════════════════
+class TestStageLockerMultipleMutations(unittest.TestCase):
+    def test_multiple_updates_preserve_spans(self):
+        """Locked spans should survive multiple sequential mutations."""
+        locker = StageLocker()
+        locker.lock(5, 10, 'spelling')
+        locker.lock(15, 20, 'grammar')
+
+        # Mutation 1: insert "XX" at position 0
+        mapper1 = OffsetMapper("abcdefghij___klmnopqrst", "XXabcdefghij___klmnopqrst")
+        locker.update_via_mapper(mapper1)
+        self.assertEqual(len(locker.locked_spans), 2)
+
+        # Mutation 2: delete from end
+        text_after_m1 = "XXabcdefghij___klmnopqrst"
+        mapper2 = OffsetMapper(text_after_m1, text_after_m1[:-3])
+        locker.update_via_mapper(mapper2)
+        self.assertEqual(len(locker.locked_spans), 2)
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# Additional: OffsetMapper monotonicity guard
+# ══════════════════════════════════════════════════════════════════════════════
+class TestOffsetMapperMonotonicity(unittest.TestCase):
+    def test_forward_map_range_never_inverts(self):
+        """forward_map_range must always return start <= end."""
+        mapper = OffsetMapper("abcdef", "xyzabc")
+        start, end = mapper.forward_map_range(2, 5)
+        self.assertLessEqual(start, end,
+                             f"Monotonicity violated: start={start} > end={end}")
+
+
+if __name__ == '__main__':
+    unittest.main()