refactor(web): adds SearchSpace interface

This new interface is being added in preparation for efficient multi-tokenization correction-search.  SearchPath has been modified to implement it, and a new type (SearchCluster) will be added in the near future as an additional implementing type.

Build-bot: skip build:web
Test-bot: skip

Author: jahorton

web/src/engine/predictive-text/worker-thread/src/main/correction/context-token.ts

@@ -204,18 +204,7 @@ export class ContextToken {
    * received that can correspond to the current instance.
    */
   get exampleInput(): string {
-    /*
-     * TODO:  with clear limits (strict cost minimization?) / prior calculation
-     * attempts, return the best _suggestion_ for this token.  This is
-     * especially relevant for epic/dict-breaker - we want to best model the token
-     * as it would apply within the word-breaking algorithm.
-     *
-     * If not possible, find the best of the deepest search paths and append the
-     * most likely keystroke data afterward.
-     */
-    const transforms = this.searchSpace.inputSequence.map((dist) => dist[0].sample)
-    const composite = transforms.reduce((accum, current) => buildMergedTransform(accum, current), {insert: '', deleteLeft: 0});
-    return composite.insert;
+    return this.searchSpace.bestExample.text;
   }
 
   /**

web/src/engine/predictive-text/worker-thread/src/main/correction/distance-modeler.ts

@@ -6,6 +6,7 @@ import { LexicalModelTypes } from '@keymanapp/common-types';
 import { ClassicalDistanceCalculation } from './classical-calculation.js';
 import { ExecutionTimer, STANDARD_TIME_BETWEEN_DEFERS } from './execution-timer.js';
 import { QUEUE_NODE_COMPARATOR, SearchPath } from './search-path.js';
+import { PathResult } from './search-space.js';
 import { subsetByChar, subsetByInterval, mergeSubset, TransformSubset } from '../transform-subsets.js';
 
 import Distribution = LexicalModelTypes.Distribution;
@@ -599,23 +600,6 @@ export class SearchResult {
   }
 }
 
-type NullPath = {
-  type: 'none'
-}
-
-type IntermediateSearchPath = {
-  type: 'intermediate',
-  cost: number
-}
-
-type CompleteSearchPath = {
-  type: 'complete',
-  cost: number,
-  finalNode: SearchNode
-}
-
-export type PathResult = NullPath | IntermediateSearchPath | CompleteSearchPath;
-
 // Current best guesstimate of how compositor will retrieve ideal corrections.
 export async function *getBestMatches(searchSpace: SearchPath, timer: ExecutionTimer): AsyncGenerator<SearchResult> {
   let currentReturns: {[resultKey: string]: SearchNode} = {};

web/src/engine/predictive-text/worker-thread/src/main/correction/search-path.ts

@@ -8,10 +8,11 @@
  * engine.
  */
 
-import { QueueComparator as Comparator, PriorityQueue } from '@keymanapp/web-utils';
+import { QueueComparator as Comparator, KMWString, PriorityQueue } from '@keymanapp/web-utils';
 import { LexicalModelTypes } from '@keymanapp/common-types';
 
-import { EDIT_DISTANCE_COST_SCALE, PathResult, SearchNode, SearchResult } from './distance-modeler.js';
+import { EDIT_DISTANCE_COST_SCALE, SearchNode, SearchResult } from './distance-modeler.js';
+import { PathResult, SearchSpace } from './search-space.js';
 
 import Distribution = LexicalModelTypes.Distribution;
 import LexicalModel = LexicalModelTypes.LexicalModel;
@@ -25,7 +26,7 @@ export const QUEUE_NODE_COMPARATOR: Comparator<SearchNode> = function(arg1, arg2
 
 // The set of search spaces corresponding to the same 'context' for search.
 // Whenever a wordbreak boundary is crossed, a new instance should be made.
-export class SearchPath {
+export class SearchPath implements SearchSpace {
   private selectionQueue: PriorityQueue<SearchNode> = new PriorityQueue(QUEUE_NODE_COMPARATOR);
   private inputs: Distribution<Transform>;
 
@@ -110,6 +111,20 @@ export class SearchPath {
     }
   }
 
+  public get inputCount(): number {
+    return (this.parentPath?.inputCount ?? 0) + (this.inputs ? 1 : 0);
+  }
+
+  public get bestExample(): {text: string, p: number} {
+    const bestPrefix = this.parentPath?.bestExample ?? { text: '', p: 1 };
+    const bestLocalInput = this.inputs?.reduce((max, curr) => max.p < curr.p ? curr : max) ?? { sample: { insert: '', deleteLeft: 0 }, p: 1};
+
+    return {
+      text: KMWString.substring(bestPrefix.text, 0, KMWString.length(bestPrefix.text) - bestLocalInput.sample.deleteLeft) + bestLocalInput.sample.insert,
+      p: bestPrefix.p * bestLocalInput.p
+    }
+  }
+
   increaseMaxEditDistance() {
     this.parentPath.increaseMaxEditDistance();
 
@@ -304,7 +319,7 @@ export class SearchPath {
     };
   }
 
-  public previousResults(): SearchResult[] {
+  public get previousResults(): SearchResult[] {
     return Object.values(this.returnedValues).map(v => new SearchResult(v));
   }
 }

web/src/engine/predictive-text/worker-thread/src/main/correction/search-space.ts

@@ -0,0 +1,81 @@
+/*
+ * Keyman is copyright (C) SIL Global. MIT License.
+ *
+ * Created by jahorton on 2025-10-09
+ *
+ * This file the predictive-text engine's SearchSpace class, which is used to
+ * manage the search-space(s) for text corrections within the engine.
+ */
+
+import { SearchNode, SearchResult } from "./distance-modeler.js";
+
+export let SPACE_ID_SEED = 0;
+
+export function generateSpaceSeed(): number {
+  return SPACE_ID_SEED++;
+}
+
+type NullPath = {
+  type: 'none'
+}
+
+type IntermediateSearchPath = {
+  type: 'intermediate',
+  cost: number
+}
+
+type CompleteSearchPath = {
+  type: 'complete',
+  cost: number,
+  finalNode: SearchNode
+}
+
+export type PathResult = NullPath | IntermediateSearchPath | CompleteSearchPath;
+
+/**
+ * Represents all or a portion of the dynamically-generated graph used to search
+ * for predictive-text corrections.
+ */
+export interface SearchSpace {
+  /**
+   * Retrieves the lowest-cost / lowest-distance edge from the batcher's search
+   * area, checks its validity as a correction to the input text, and reports on
+   * what sort of result the edge's destination node represents.
+   * @returns
+   */
+  handleNextNode(): PathResult;
+
+  /**
+   * Reports the cost of the lowest-cost / lowest-distance edge held within the
+   * batcher's search area.
+   * @returns
+   */
+  readonly currentCost: number;
+
+  /**
+   * Returns the set of previously-processed results under this batcher's domain.
+   */
+  readonly previousResults: SearchResult[];
+
+  /**
+   * When true, this indicates that the currently-represented portion of context
+   * has fat-finger data available, which itself indicates that the user has
+   * corrections enabled.
+   */
+  readonly correctionsEnabled: boolean;
+
+  /**
+   * Reports the total number of input keystrokes represented by this
+   * graph/subgraph.
+   *
+   * (Their fat-finger alternates, when provided, do not influence this count -
+   * they're associated with the original keystroke that affected the context.)
+   */
+  readonly inputCount: number;
+
+  /**
+   * Determines the best example text representable by this batcher's portion of
+   * the correction-search graph and its paths.
+   */
+  readonly bestExample: { text: string, p: number };
+}

web/src/engine/predictive-text/worker-thread/src/main/predict-helpers.ts

@@ -532,7 +532,7 @@ export async function correctAndEnumerate(
      * Worst-case, it's possible to temporarily add normalization if a code deep-dive
      * is needed in the future.
      */
-    if(searchSpace.inputSequence.length <= 1) {
+    if(searchSpace.inputCount <= 1) {
       /* Suppose a key distribution:  most likely with p=0.5, second-most with 0.4 - a pretty
        * ambiguous case that would only arise very near the center of the boundary between two keys.
        * Raising (0.5/0.4)^16 ~= 35.53.  (At time of writing, SINGLE_CHAR_KEY_PROB_EXPONENT = 16.)