outcome-cli 1.0.0

package/src/modules/omnibridge/core/triangulation-engine.ts

@@ -0,0 +1,530 @@
+/**
+ * Triangulation Engine
+ *
+ * Self-healing system using three anchor types (Spatial, Semantic, Functional)
+ * to locate elements even when UI changes.
+ *
+ * Requirements: 2.1, 2.2, 2.4, 2.5, 2.6
+ */
+
+import type {
+  IntentDocument,
+  IntentElement,
+  AnchorSet,
+  SpatialAnchor,
+  SemanticAnchor,
+  FunctionalAnchor,
+  LocateResult,
+  HealResult,
+  OmniBridgeError,
+} from './types.js';
+
+/**
+ * Confidence threshold below which elements are flagged for review
+ * Requirement 2.5
+ */
+const CONFIDENCE_THRESHOLD = 0.7;
+
+/**
+ * Minimum anchors required for successful location
+ * Requirement 2.2
+ */
+const MIN_ANCHORS_FOR_MATCH = 2;
+
+/**
+ * Triangulation Engine class
+ * Implements self-healing element location using three-anchor system
+ */
+export class TriangulationEngine {
+  /**
+   * Store anchors for an element (Requirement 2.1)
+   * Creates all three anchor types: Spatial, Semantic, and Functional
+   */
+  storeAnchors(
+    element: IntentElement,
+    document: IntentDocument,
+    elementIndex: number
+  ): AnchorSet {
+    const spatial = this.createSpatialAnchor(element, document, elementIndex);
+    const semantic = this.createSemanticAnchor(element);
+    const functional = this.createFunctionalAnchor(element);
+
+    return {
+      spatial,
+      semantic,
+      functional,
+    };
+  }
+
+  /**
+   * Create a Spatial anchor for an element
+   * Stores region, relative position, and nearby landmarks
+   */
+  private createSpatialAnchor(
+    element: IntentElement,
+    document: IntentDocument,
+    elementIndex: number
+  ): SpatialAnchor {
+    // Determine region based on element context and position
+    const region = this.inferRegion(element, document, elementIndex);
+
+    // Calculate relative position (normalized 0-1)
+    const totalElements = document.elements.length;
+    const relativePosition = {
+      x: 0.5, // Default to center (would be calculated from actual DOM position)
+      y: totalElements > 0 ? elementIndex / totalElements : 0,
+    };
+
+    // Find nearby landmarks (other semantic elements)
+    const nearbyLandmarks = this.findNearbyLandmarks(document, elementIndex);
+
+    return {
+      region,
+      relativePosition,
+      nearbyLandmarks,
+    };
+  }
+
+  /**
+   * Infer the region of an element based on its context
+   */
+  private inferRegion(
+    element: IntentElement,
+    document: IntentDocument,
+    elementIndex: number
+  ): SpatialAnchor['region'] {
+    const totalElements = document.elements.length;
+    const positionRatio = totalElements > 0 ? elementIndex / totalElements : 0.5;
+
+    // Check for explicit region indicators
+    if (element.tagName === 'header' || element.ariaRole === 'banner') {
+      return 'header';
+    }
+    if (element.tagName === 'footer' || element.ariaRole === 'contentinfo') {
+      return 'footer';
+    }
+    if (element.tagName === 'aside' || element.ariaRole === 'complementary') {
+      return 'sidebar';
+    }
+    if (element.tagName === 'nav' || element.ariaRole === 'navigation') {
+      // Navigation at top is header, at bottom is footer
+      return positionRatio < 0.3 ? 'header' : positionRatio > 0.7 ? 'footer' : 'main';
+    }
+
+    // Infer from position
+    if (positionRatio < 0.15) return 'header';
+    if (positionRatio > 0.85) return 'footer';
+
+    return 'main';
+  }
+
+
+  /**
+   * Find nearby landmark elements for spatial context
+   */
+  private findNearbyLandmarks(
+    document: IntentDocument,
+    elementIndex: number,
+    range: number = 3
+  ): string[] {
+    const landmarks: string[] = [];
+    const elements = document.elements;
+
+    // Look at elements before and after
+    for (let i = Math.max(0, elementIndex - range); i < Math.min(elements.length, elementIndex + range + 1); i++) {
+      if (i === elementIndex) continue;
+
+      const el = elements[i];
+      // Include elements with strong semantic meaning as landmarks
+      if (
+        el.ariaRole ||
+        el.tagName === 'nav' ||
+        el.tagName === 'header' ||
+        el.tagName === 'footer' ||
+        el.tagName === 'main' ||
+        el.role === 'navigation' ||
+        el.intentId.includes('NAV_ID') ||
+        el.intentId.includes('ACTION_ID')
+      ) {
+        landmarks.push(el.intentId);
+      }
+    }
+
+    return landmarks.slice(0, 5); // Limit to 5 landmarks
+  }
+
+  /**
+   * Create a Semantic anchor for an element
+   * Stores Intent_ID, labels, ARIA roles, and text content
+   */
+  private createSemanticAnchor(element: IntentElement): SemanticAnchor {
+    return {
+      intentId: element.intentId,
+      labels: [element.label, ...element.contextHints].filter(Boolean),
+      ariaRoles: element.ariaRole ? [element.ariaRole] : [],
+      textContent: element.label,
+    };
+  }
+
+  /**
+   * Create a Functional anchor for an element
+   * Stores event types, form targets, and navigation targets
+   */
+  private createFunctionalAnchor(element: IntentElement): FunctionalAnchor {
+    const eventTypes: string[] = [];
+    let formTarget: string | undefined;
+    let navigationTarget: string | undefined;
+
+    // Infer event types from element role and tag
+    if (element.role === 'action' || element.tagName === 'button') {
+      eventTypes.push('click');
+    }
+    if (element.role === 'input' || ['input', 'textarea', 'select'].includes(element.tagName)) {
+      eventTypes.push('input', 'change', 'focus', 'blur');
+    }
+    if (element.role === 'navigation' || element.tagName === 'a') {
+      eventTypes.push('click');
+      // Extract navigation target from intentId if it's a nav element
+      if (element.intentId.includes('NAV_ID')) {
+        navigationTarget = element.intentId;
+      }
+    }
+
+    // Check if element is part of a form
+    if (element.intentId.includes('INPUT_ID') || element.intentId.includes('SUBMIT')) {
+      formTarget = 'form';
+    }
+
+    return {
+      eventTypes,
+      formTarget,
+      navigationTarget,
+    };
+  }
+
+  /**
+   * Locate an element using stored anchors (Requirement 2.2)
+   * Returns found=true if 2+ anchors match
+   */
+  locate(anchors: AnchorSet, document: IntentDocument): LocateResult {
+    let bestMatch: IntentElement | undefined;
+    let bestMatchCount = 0;
+    let bestConfidence = 0;
+
+    for (let i = 0; i < document.elements.length; i++) {
+      const element = document.elements[i];
+      const currentAnchors = this.storeAnchors(element, document, i);
+
+      const { matchCount, confidence } = this.calculateAnchorMatch(anchors, currentAnchors);
+
+      if (matchCount > bestMatchCount || (matchCount === bestMatchCount && confidence > bestConfidence)) {
+        bestMatch = element;
+        bestMatchCount = matchCount;
+        bestConfidence = confidence;
+      }
+    }
+
+    // Requirement 2.2: Return found=true if 2+ anchors match
+    const found = bestMatchCount >= MIN_ANCHORS_FOR_MATCH;
+
+    // Requirement 2.5: Flag for review if confidence < 70%
+    const flaggedForReview = bestConfidence < CONFIDENCE_THRESHOLD;
+
+    return {
+      found,
+      element: found ? bestMatch : undefined,
+      matchedAnchors: bestMatchCount,
+      confidence: bestConfidence,
+      flaggedForReview,
+    };
+  }
+
+
+  /**
+   * Calculate how well two anchor sets match
+   * Returns match count (0-3) and confidence score (0-1)
+   */
+  private calculateAnchorMatch(
+    stored: AnchorSet,
+    current: AnchorSet
+  ): { matchCount: number; confidence: number } {
+    let matchCount = 0;
+    let totalConfidence = 0;
+
+    // Check Spatial anchor match
+    const spatialMatch = this.matchSpatialAnchor(stored.spatial, current.spatial);
+    if (spatialMatch > 0.5) {
+      matchCount++;
+      totalConfidence += spatialMatch;
+    }
+
+    // Check Semantic anchor match
+    const semanticMatch = this.matchSemanticAnchor(stored.semantic, current.semantic);
+    if (semanticMatch > 0.5) {
+      matchCount++;
+      totalConfidence += semanticMatch;
+    }
+
+    // Check Functional anchor match
+    const functionalMatch = this.matchFunctionalAnchor(stored.functional, current.functional);
+    if (functionalMatch > 0.5) {
+      matchCount++;
+      totalConfidence += functionalMatch;
+    }
+
+    // Calculate overall confidence
+    const confidence = matchCount > 0 ? totalConfidence / 3 : 0;
+
+    return { matchCount, confidence };
+  }
+
+  /**
+   * Match two Spatial anchors
+   * Returns similarity score 0-1
+   */
+  private matchSpatialAnchor(stored: SpatialAnchor, current: SpatialAnchor): number {
+    let score = 0;
+
+    // Region match (40% weight)
+    if (stored.region === current.region) {
+      score += 0.4;
+    }
+
+    // Position proximity (30% weight)
+    const positionDistance = Math.sqrt(
+      Math.pow(stored.relativePosition.x - current.relativePosition.x, 2) +
+      Math.pow(stored.relativePosition.y - current.relativePosition.y, 2)
+    );
+    const positionScore = Math.max(0, 1 - positionDistance);
+    score += positionScore * 0.3;
+
+    // Landmark overlap (30% weight)
+    const landmarkOverlap = this.calculateSetOverlap(
+      stored.nearbyLandmarks,
+      current.nearbyLandmarks
+    );
+    score += landmarkOverlap * 0.3;
+
+    return score;
+  }
+
+  /**
+   * Match two Semantic anchors
+   * Returns similarity score 0-1
+   */
+  private matchSemanticAnchor(stored: SemanticAnchor, current: SemanticAnchor): number {
+    let score = 0;
+
+    // Intent ID match (50% weight) - most important
+    if (stored.intentId === current.intentId) {
+      score += 0.5;
+    } else {
+      // Partial match on intent category
+      const storedCategory = stored.intentId.split('_ID:')[0];
+      const currentCategory = current.intentId.split('_ID:')[0];
+      if (storedCategory === currentCategory) {
+        score += 0.2;
+      }
+    }
+
+    // Label overlap (25% weight)
+    const labelOverlap = this.calculateSetOverlap(stored.labels, current.labels);
+    score += labelOverlap * 0.25;
+
+    // ARIA role match (15% weight)
+    const ariaOverlap = this.calculateSetOverlap(stored.ariaRoles, current.ariaRoles);
+    score += ariaOverlap * 0.15;
+
+    // Text content similarity (10% weight)
+    const textSimilarity = this.calculateTextSimilarity(stored.textContent, current.textContent);
+    score += textSimilarity * 0.1;
+
+    return score;
+  }
+
+  /**
+   * Match two Functional anchors
+   * Returns similarity score 0-1
+   */
+  private matchFunctionalAnchor(stored: FunctionalAnchor, current: FunctionalAnchor): number {
+    let score = 0;
+
+    // Event types overlap (40% weight)
+    const eventOverlap = this.calculateSetOverlap(stored.eventTypes, current.eventTypes);
+    score += eventOverlap * 0.4;
+
+    // Form target match (30% weight)
+    if (stored.formTarget && current.formTarget) {
+      if (stored.formTarget === current.formTarget) {
+        score += 0.3;
+      }
+    } else if (!stored.formTarget && !current.formTarget) {
+      score += 0.3; // Both have no form target
+    }
+
+    // Navigation target match (30% weight)
+    if (stored.navigationTarget && current.navigationTarget) {
+      if (stored.navigationTarget === current.navigationTarget) {
+        score += 0.3;
+      }
+    } else if (!stored.navigationTarget && !current.navigationTarget) {
+      score += 0.3; // Both have no navigation target
+    }
+
+    return score;
+  }
+
+
+  /**
+   * Calculate overlap between two string arrays
+   * Returns 0-1 (Jaccard similarity)
+   */
+  private calculateSetOverlap(a: string[], b: string[]): number {
+    if (a.length === 0 && b.length === 0) return 1;
+    if (a.length === 0 || b.length === 0) return 0;
+
+    const setA = new Set(a.map(s => s.toLowerCase()));
+    const setB = new Set(b.map(s => s.toLowerCase()));
+
+    let intersection = 0;
+    for (const item of setA) {
+      if (setB.has(item)) {
+        intersection++;
+      }
+    }
+
+    const union = setA.size + setB.size - intersection;
+    return union > 0 ? intersection / union : 0;
+  }
+
+  /**
+   * Calculate text similarity between two strings
+   * Uses simple word overlap for efficiency
+   */
+  private calculateTextSimilarity(a: string, b: string): number {
+    if (!a && !b) return 1;
+    if (!a || !b) return 0;
+
+    const wordsA = a.toLowerCase().split(/\s+/).filter(Boolean);
+    const wordsB = b.toLowerCase().split(/\s+/).filter(Boolean);
+
+    return this.calculateSetOverlap(wordsA, wordsB);
+  }
+
+  /**
+   * Heal (re-locate) an element after UI changes (Requirement 2.2)
+   * Updates anchors if element is found with 2+ anchor matches
+   */
+  heal(oldAnchors: AnchorSet, newDocument: IntentDocument): HealResult {
+    const locateResult = this.locate(oldAnchors, newDocument);
+
+    if (!locateResult.found || !locateResult.element) {
+      return {
+        healed: false,
+        changeLog: `Element not found. Matched ${locateResult.matchedAnchors}/3 anchors with confidence ${(locateResult.confidence * 100).toFixed(1)}%`,
+      };
+    }
+
+    // Find the element index to create new anchors
+    const elementIndex = newDocument.elements.findIndex(
+      el => el.intentId === locateResult.element!.intentId
+    );
+
+    const newAnchors = this.storeAnchors(locateResult.element, newDocument, elementIndex);
+
+    // Generate change log
+    const changes: string[] = [];
+    if (oldAnchors.spatial.region !== newAnchors.spatial.region) {
+      changes.push(`Region changed: ${oldAnchors.spatial.region} → ${newAnchors.spatial.region}`);
+    }
+    if (oldAnchors.semantic.intentId !== newAnchors.semantic.intentId) {
+      changes.push(`Intent ID changed: ${oldAnchors.semantic.intentId} → ${newAnchors.semantic.intentId}`);
+    }
+
+    return {
+      healed: true,
+      newAnchors,
+      changeLog: changes.length > 0
+        ? `Healed with ${locateResult.matchedAnchors}/3 anchors. Changes: ${changes.join('; ')}`
+        : `Healed with ${locateResult.matchedAnchors}/3 anchors. No significant changes.`,
+    };
+  }
+
+  /**
+   * Detect schema drift when all anchors fail (Requirement 2.6)
+   * Returns a schema_drift error with details about what changed
+   */
+  detectSchemaDrift(
+    anchors: AnchorSet,
+    document: IntentDocument
+  ): OmniBridgeError | null {
+    const locateResult = this.locate(anchors, document);
+
+    // If element was found, no schema drift
+    if (locateResult.found) {
+      return null;
+    }
+
+    // If all anchors failed (0 matches), this is schema drift
+    if (locateResult.matchedAnchors === 0) {
+      const details = this.generateSchemaDriftDetails(anchors, document);
+      return {
+        type: 'schema_drift',
+        details,
+        confidence: locateResult.confidence,
+      };
+    }
+
+    // Partial match (1 anchor) - not schema drift, just element moved
+    return null;
+  }
+
+  /**
+   * Generate details about what changed during schema drift
+   */
+  private generateSchemaDriftDetails(anchors: AnchorSet, document: IntentDocument): string {
+    const details: string[] = [];
+
+    // Check if the region still exists
+    const regionsInDoc = new Set(document.elements.map((_, i) =>
+      this.inferRegion(document.elements[i], document, i)
+    ));
+    if (!regionsInDoc.has(anchors.spatial.region)) {
+      details.push(`Region '${anchors.spatial.region}' no longer exists`);
+    }
+
+    // Check if similar intent IDs exist
+    const intentCategory = anchors.semantic.intentId.split('_ID:')[0];
+    const similarIntents = document.elements.filter(el =>
+      el.intentId.startsWith(intentCategory)
+    );
+    if (similarIntents.length === 0) {
+      details.push(`No elements with category '${intentCategory}' found`);
+    } else {
+      details.push(`Found ${similarIntents.length} elements with category '${intentCategory}' but none match`);
+    }
+
+    // Check if any landmarks remain
+    const currentLandmarks = document.elements
+      .filter(el => el.ariaRole || el.role === 'navigation')
+      .map(el => el.intentId);
+    const landmarkOverlap = this.calculateSetOverlap(
+      anchors.spatial.nearbyLandmarks,
+      currentLandmarks
+    );
+    if (landmarkOverlap < 0.2) {
+      details.push('Most nearby landmarks have changed');
+    }
+
+    return details.length > 0
+      ? details.join('. ')
+      : 'Element and surrounding context have changed significantly';
+  }
+}
+
+/**
+ * Create a new Triangulation Engine instance
+ */
+export function createTriangulationEngine(): TriangulationEngine {
+  return new TriangulationEngine();
+}