feat(keyhandler): integrate contextual user model into KeyHandler

- Wire ContextualUserModel into KeyHandler via LanguageModelManager
- Single walk per keystroke (remove post-walk suggest + re-walk)
- Selection flow: overrideCandidate → fixSpan → observe → save
- Global ContextualUserModel with aliasing shared_ptr
- Load from contextual-user-model.txt on startup, save on selection

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: tianjianjiang

Source/Engine/gramambular2/reading_grid_test.cpp

@@ -970,6 +970,38 @@ TEST(FixedSpanTest, ChainedOverrides) {
             << " us\n";
 }
 
+TEST(FixedSpanTest, ClearAlsoResetsFixedSpans) {
+  ReadingGrid grid(std::make_shared<SimpleLM>(kSampleData));
+  grid.setReadingSeparator("");
+  std::vector<std::string> readings = {"ㄍㄠ",    "ㄎㄜ",    "ㄐㄧˋ",
+                                        "ㄍㄨㄥ",  "ㄙ",      "ㄉㄜ˙",
+                                        "ㄋㄧㄢˊ", "ㄓㄨㄥ",  "ㄐㄧㄤˇ",
+                                        "ㄐㄧㄣ"};
+  for (const auto& r : readings) {
+    grid.insertReading(r);
+  }
+
+  auto nzNode = grid.spans()[6].nodeOf(2);
+  nzNode->selectOverrideUnigram(
+      "年終", ReadingGrid::Node::OverrideType::kOverrideValueWithHighScore);
+  grid.fixSpan(6, nzNode);
+  auto result = grid.walk();
+  bool hasNianzhong = false;
+  for (const auto& v : result.valuesAsStrings()) {
+    if (v == "年終") hasNianzhong = true;
+  }
+  ASSERT_TRUE(hasNianzhong);
+
+  grid.clear();
+
+  for (const auto& r : readings) {
+    grid.insertReading(r);
+  }
+  result = grid.walk();
+  ASSERT_EQ(result.valuesAsStrings(),
+            (std::vector<std::string>{"高科技", "公司", "的", "年中", "獎金"}));
+}
+
 // Phase 0B Tests: Algorithm Comparison
 
 TEST(AlgorithmComparisonTest, Basic10Syllables) {

Source/KeyHandler.mm

@@ -28,6 +28,7 @@
 #import "McBopomofoLM.h"
 #import "UTF8Helper.h"
 #import "UserOverrideModel.h"
+#import "contextual_user_model.h"
 #import "reading_grid.h"
 
 #import <algorithm>
@@ -60,6 +61,9 @@ @implementation KeyHandler {
     // user override model
     McBopomofo::UserOverrideModel *_userOverrideModel;
 
+    // contextual user model (KN backoff)
+    Formosa::Gramambular2::ContextualUserModel *_contextualUserModel;
+
     Formosa::Gramambular2::ReadingGrid *_grid;
     Formosa::Gramambular2::ReadingGrid::WalkResult _latestWalk;
 
@@ -104,6 +108,7 @@ - (void)setInputMode:(NSString *)value
             std::shared_ptr<Formosa::Gramambular2::LanguageModel> lm(_emptySharedPtr, _languageModel);
             _grid = new Formosa::Gramambular2::ReadingGrid(lm);
             _grid->setReadingSeparator("-");
+            _grid->setUserModel(_contextualUserModel);
         }
 
         if (!_bpmfReadingBuffer->isEmpty()) {
@@ -128,11 +133,13 @@ - (instancetype)init
         _languageModel = [LanguageModelManager languageModelMcBopomofo];
         _languageModel->setPhraseReplacementEnabled(Preferences.phraseReplacementEnabled);
         _userOverrideModel = [LanguageModelManager userOverrideModel];
+        _contextualUserModel = [LanguageModelManager contextualUserModel];
 
         // This returns a shared_ptr that in turn points to an unmanaged object.
         std::shared_ptr<Formosa::Gramambular2::LanguageModel> lm(_emptySharedPtr, _languageModel);
         _grid = new Formosa::Gramambular2::ReadingGrid(lm);
         _grid->setReadingSeparator("-");
+        _grid->setUserModel(_contextualUserModel);
 
         _inputMode = InputModeBopomofo;
     }
@@ -171,26 +178,48 @@ - (void)syncWithPreferences
 - (void)fixNodeWithReading:(NSString *)reading value:(NSString *)value originalCursorIndex:(size_t)originalCursorIndex useMoveCursorAfterSelectionSetting:(BOOL)flag
 {
     size_t actualCursor = self.actualCandidateCursorIndex;
-    Formosa::Gramambular2::ReadingGrid::Candidate candidate(reading.UTF8String, value.UTF8String);
-    if (!_grid->overrideCandidate(actualCursor, candidate)) {
+    std::string readingStr(reading.UTF8String);
+    std::string valueStr(value.UTF8String);
+    Formosa::Gramambular2::ReadingGrid::Candidate candidate(readingStr, valueStr);
+    if (!_grid->overrideCandidate(actualCursor, candidate,
+            Formosa::Gramambular2::ReadingGrid::Node::OverrideType::kOverrideValueWithScoreFromTopUnigram)) {
         return;
     }
 
-    Formosa::Gramambular2::ReadingGrid::WalkResult prevWalk = _latestWalk;
+    // Structurally fix the overridden node so the walk is constrained to it.
+    auto nodeOpt = _grid->findInSpan(actualCursor, [&readingStr](const auto& node) {
+        return node->reading() == readingStr && node->isOverridden();
+    });
+    if (nodeOpt) {
+        _grid->fixSpan(actualCursor, *nodeOpt);
+    }
+
     [self _walk];
 
-    // Update the user override model if warranted.
     size_t accumulatedCursor = 0;
     auto nodeIter = _latestWalk.findNodeAt(actualCursor, &accumulatedCursor);
     if (nodeIter == _latestWalk.nodes.cend()) {
         return;
     }
     Formosa::Gramambular2::ReadingGrid::NodePtr currentNode = *nodeIter;
-    if (currentNode != nullptr && currentNode->currentUnigram().score() > -8) {
-        _userOverrideModel->observe(prevWalk, _latestWalk, self.actualCandidateCursorIndex, [NSDate date].timeIntervalSince1970);
+    if (currentNode == nullptr) {
+        _grid->setCursor(originalCursorIndex);
+        return;
     }
 
-    if (currentNode != nullptr && flag && Preferences.moveCursorAfterSelectingCandidate) {
+    std::string leftReading = Formosa::Gramambular2::ContextualUserModel::kStartSentinel;
+    std::string leftValue;
+    if (nodeIter != _latestWalk.nodes.cbegin()) {
+        auto prevNode = *(nodeIter - 1);
+        leftReading = prevNode->reading();
+        leftValue = prevNode->value();
+    }
+    _contextualUserModel->observe(leftReading, leftValue,
+        currentNode->reading(), currentNode->value(),
+        [NSDate date].timeIntervalSince1970);
+    [LanguageModelManager saveContextualUserModel];
+
+    if (flag && Preferences.moveCursorAfterSelectingCandidate) {
         _grid->setCursor(accumulatedCursor);
     } else {
         _grid->setCursor(originalCursorIndex);
@@ -525,16 +554,6 @@ - (BOOL)handleInput:(KeyHandlerInput *)input state:(InputState *)inState stateCa
         _grid->insertReading(reading);
         [self _walk];
 
-        // get user override model suggestion
-        if (_inputMode != InputModePlainBopomofo) {
-            McBopomofo::UserOverrideModel::Suggestion suggestion = _userOverrideModel->suggest(_latestWalk, self.actualCandidateCursorIndex, [NSDate date].timeIntervalSince1970);
-            if (!suggestion.empty()) {
-                Formosa::Gramambular2::ReadingGrid::Node::OverrideType type = suggestion.forceHighScoreOverride ? Formosa::Gramambular2::ReadingGrid::Node::OverrideType::kOverrideValueWithHighScore : Formosa::Gramambular2::ReadingGrid::Node::OverrideType::kOverrideValueWithScoreFromTopUnigram;
-                _grid->overrideCandidate(self.actualCandidateCursorIndex, suggestion.candidate, type);
-                [self _walk];
-            }
-        }
-
         // then update the text
         _bpmfReadingBuffer->clear();
 

Source/LanguageModelManager+Privates.h

@@ -24,13 +24,17 @@
 #import "LanguageModelManager.h"
 #import "McBopomofoLM.h"
 #import "UserOverrideModel.h"
+#import "contextual_user_model.h"
 
 NS_ASSUME_NONNULL_BEGIN
 
 @interface LanguageModelManager ()
 @property (class, readonly, nonatomic) McBopomofo::McBopomofoLM *languageModelMcBopomofo;
 @property (class, readonly, nonatomic) McBopomofo::McBopomofoLM *languageModelPlainBopomofo;
 @property (class, readonly, nonatomic) McBopomofo::UserOverrideModel *userOverrideModel;
+@property (class, readonly, nonatomic) Formosa::Gramambular2::ContextualUserModel *contextualUserModel;
+@property (class, readonly, nonatomic) NSString *contextualUserModelDataPath;
++ (void)saveContextualUserModel;
 @end
 
 NS_ASSUME_NONNULL_END

Source/LanguageModelManager.mm

@@ -34,6 +34,11 @@
 static McBopomofo::McBopomofoLM gLanguageModelPlainBopomofo;
 static McBopomofo::UserOverrideModel gUserOverrideModel(kUserOverrideModelCapacity, kObservedOverrideHalflife);
 
+// Aliasing shared_ptr: wraps the stack-allocated LM for ContextualUserModel.
+static std::shared_ptr<Formosa::Gramambular2::LanguageModel> gEmptySharedPtr;
+static std::shared_ptr<Formosa::Gramambular2::LanguageModel> gLmPtr(gEmptySharedPtr, &gLanguageModelMcBopomofo);
+static Formosa::Gramambular2::ContextualUserModel gContextualUserModel(gLmPtr);
+
 static NSString *const kUserDataTemplateName = @"template-data";
 static NSString *const kUserDataPlainBopomofoTemplateName = @"template-data-plain-bpmf";
 static NSString *const kExcludedPhrasesMcBopomofoTemplateName = @"template-exclude-phrases";
@@ -72,6 +77,11 @@ + (void)loadDataModels
     if (!gLanguageModelPlainBopomofo.isAssociatedPhrasesV2Loaded()) {
         LTLoadAssociatedPhrases(gLanguageModelPlainBopomofo);
     }
+
+    NSString *cumPath = [self contextualUserModelDataPath];
+    if ([[NSFileManager defaultManager] fileExistsAtPath:cumPath]) {
+        gContextualUserModel.loadFromFile(cumPath.UTF8String);
+    }
 }
 
 + (void)loadDataModel:(InputMode)mode
@@ -430,6 +440,21 @@ + (NSString *)phraseReplacementDataPathMcBopomofo
     return &gUserOverrideModel;
 }
 
++ (Formosa::Gramambular2::ContextualUserModel *)contextualUserModel
+{
+    return &gContextualUserModel;
+}
+
++ (NSString *)contextualUserModelDataPath
+{
+    return [[self dataFolderPath] stringByAppendingPathComponent:@"contextual-user-model.txt"];
+}
+
++ (void)saveContextualUserModel
+{
+    gContextualUserModel.saveToFile([self contextualUserModelDataPath].UTF8String);
+}
+
 + (BOOL)phraseReplacementEnabled
 {
     return gLanguageModelMcBopomofo.phraseReplacementEnabled();