ultracode 5.4.0 → 5.6.0

package/dist/chunks/tracing-tool-handlers-4BDCXTZZ.js

@@ -0,0 +1,3935 @@
+import { GraphologyPathBuilder } from './chunk-Y2JFD44R.js';
+import { projectPathParam } from './chunk-NJUB245U.js';
+import { BaseToolHandler } from './chunk-SAMX3HJQ.js';
+import './chunk-WIE3G5ES.js';
+import './chunk-CTXFPNDA.js';
+import './chunk-TJSOOFXA.js';
+import './chunk-XK2NY7RB.js';
+import './chunk-HEMJHRHZ.js';
+import { init_logging, log } from './chunk-VCCBEJQ5.js';
+import './chunk-NAQKA54E.js';
+import { z } from 'zod';
+
+// src/tools/handlers/tracing-tool-handlers.ts
+init_logging();
+
+// src/tracing/condition-analyzer.ts
+var GUARD_PATTERNS = [/^if\s*\([^)]+\)\s*(return|throw)/, /^\s*(return|throw)\s+if/, /^guard\s+/, /^unless\s+/];
+var VALIDATION_PATTERNS = [/valid/i, /check/i, /verify/i, /assert/i, /ensure/i, /require/i];
+var ConditionAnalyzer = class {
+  storage;
+  decisionPointCache = /* @__PURE__ */ new Map();
+  constructor(storage) {
+    this.storage = storage;
+  }
+  // ===========================================================================
+  // 3. DECISION POINT DETECTION
+  // ===========================================================================
+  /**
+   * Find all decision points in a scenario
+   * Optimized with:
+   * - Decision point caching
+   * - Parallel entry point collection
+   * - Entity prefetching for DFS traversal
+   */
+  async findDecisionPoints(params) {
+    const { scenario, includeGuards = true, includeEffects = true, groupBy = "impact" } = params;
+    const cacheKey = `${scenario}:${includeGuards}:${includeEffects}`;
+    const cachedPoints = this.decisionPointCache.get(cacheKey);
+    const entryPoints = await this.findEntryPoints(scenario);
+    const allDecisionPoints = [];
+    if (cachedPoints) {
+      const relevantPoints = cachedPoints.filter((p) => entryPoints.some((e) => p.location.startsWith(e.filePath)));
+      if (relevantPoints.length > 0) {
+        allDecisionPoints.push(...relevantPoints);
+      }
+    }
+    if (allDecisionPoints.length === 0) {
+      const pointsPromises = entryPoints.map(async (entry) => {
+        const localVisited = /* @__PURE__ */ new Set();
+        return this.collectDecisionPoints(entry.id, localVisited, includeGuards, includeEffects);
+      });
+      const pointsArrays = await Promise.all(pointsPromises);
+      for (const points of pointsArrays) {
+        allDecisionPoints.push(...points);
+      }
+      this.decisionPointCache.set(cacheKey, allDecisionPoints);
+    }
+    const uniquePoints = this.deduplicateDecisionPoints(allDecisionPoints);
+    const sortedPoints = this.sortDecisionPoints(uniquePoints, groupBy);
+    const mermaid = this.generateFlowDiagram(sortedPoints, entryPoints);
+    const summary = this.calculateSummary(sortedPoints);
+    return {
+      scenario,
+      entryPoints: entryPoints.map((e) => ({ name: e.name, file: e.filePath })),
+      decisionPoints: sortedPoints,
+      flowDiagram: { mermaid },
+      summary
+    };
+  }
+  /**
+   * Find entry points for a scenario
+   */
+  async findEntryPoints(scenario) {
+    const entities = await this.storage.searchEntities({
+      namePattern: scenario
+    });
+    if (entities.length > 0) {
+      return entities.slice(0, 5);
+    }
+    const keywords = scenario.split(/\s+/);
+    for (const keyword of keywords) {
+      const results = await this.storage.searchEntities({
+        namePattern: keyword
+      });
+      if (results.length > 0) {
+        return results.slice(0, 5);
+      }
+    }
+    return [];
+  }
+  /**
+   * Collect decision points starting from an entity
+   */
+  async collectDecisionPoints(entityId, visited, includeGuards, includeEffects, depth = 0, maxDepth = 10) {
+    if (visited.has(entityId) || depth > maxDepth) return [];
+    visited.add(entityId);
+    const points = [];
+    const entity = await this.storage.getEntity(entityId);
+    if (!entity) return points;
+    const entityPoints = this.extractDecisionPoints(entity, includeGuards, includeEffects);
+    points.push(...entityPoints);
+    const rels = await this.storage.getRelationshipsForEntity(entityId, "calls" /* CALLS */);
+    for (const rel of rels) {
+      if (rel.fromId === entityId) {
+        const childPoints = await this.collectDecisionPoints(
+          rel.toId,
+          visited,
+          includeGuards,
+          includeEffects,
+          depth + 1,
+          maxDepth
+        );
+        points.push(...childPoints);
+      }
+    }
+    return points;
+  }
+  /**
+   * Extract decision points from an entity
+   */
+  extractDecisionPoints(entity, includeGuards, includeEffects) {
+    const points = [];
+    const meta = entity.metadata;
+    let pointIndex = 0;
+    if (meta["controlFlow"]?.branches && Array.isArray(meta["controlFlow"].branches)) {
+      for (const branch of meta["controlFlow"].branches) {
+        const type = this.classifyConditionType(branch.condition, entity.name);
+        if (type === "guard" && !includeGuards) continue;
+        const point = {
+          id: `dp-${entity.id}-${pointIndex++}`,
+          location: `${entity.filePath}:${entity.location.start.line}`,
+          type,
+          condition: branch.condition,
+          outcomes: this.buildOutcomes(branch),
+          impact: this.assessImpact(type, branch),
+          dataDepends: this.extractDataDependencies(branch.condition),
+          triggeredBy: entity.name
+        };
+        if (includeEffects && branch.effects) {
+          point.effects = branch.effects;
+        }
+        points.push(point);
+      }
+    }
+    if (meta["controlFlow"]?.loops && Array.isArray(meta["controlFlow"].loops)) {
+      for (const loop of meta["controlFlow"].loops) {
+        points.push({
+          id: `dp-${entity.id}-${pointIndex++}`,
+          location: `${entity.filePath}:${entity.location.start.line}`,
+          type: "loop",
+          condition: loop.condition,
+          outcomes: {
+            continue: "Next iteration",
+            break: "Exit loop"
+          },
+          impact: "medium",
+          dataDepends: this.extractDataDependencies(loop.condition || ""),
+          triggeredBy: entity.name
+        });
+      }
+    }
+    if (meta["controlFlow"]?.exceptions && Array.isArray(meta["controlFlow"].exceptions)) {
+      for (const exc of meta["controlFlow"].exceptions) {
+        points.push({
+          id: `dp-${entity.id}-${pointIndex++}`,
+          location: `${entity.filePath}:${entity.location.start.line}`,
+          type: "error_handling",
+          action: `catch ${exc.type || "Error"}`,
+          outcomes: {
+            caught: "Handle error",
+            rethrown: "Propagate error"
+          },
+          impact: "high",
+          dataDepends: [],
+          triggeredBy: entity.name
+        });
+      }
+    }
+    return points;
+  }
+  /**
+   * Classify condition type
+   */
+  classifyConditionType(condition, entityName) {
+    if (VALIDATION_PATTERNS.some((p) => p.test(condition) || p.test(entityName))) {
+      return "validation";
+    }
+    if (GUARD_PATTERNS.some((p) => p.test(condition))) {
+      return "guard";
+    }
+    if (condition.includes("set") || condition.includes("update") || condition.includes("=")) {
+      return "state_mutation";
+    }
+    if (condition.includes("response") || condition.includes("status") || condition.includes("error")) {
+      return "api_response";
+    }
+    if (condition.includes("feature") || condition.includes("flag") || condition.includes("enabled")) {
+      return "feature_flag";
+    }
+    return "guard";
+  }
+  /**
+   * Build outcomes map from branch info
+   */
+  buildOutcomes(branch) {
+    const outcomes = {};
+    outcomes["true"] = branch.target || "continue";
+    outcomes["false"] = "skip";
+    if (branch.condition.includes("===") || branch.condition.includes("==")) {
+      const parts = branch.condition.split(/===?/);
+      if (parts.length === 2) {
+        outcomes[`${parts[1]?.trim()}`] = branch.target || "match";
+      }
+    }
+    return outcomes;
+  }
+  /**
+   * Assess impact level of a decision point
+   */
+  assessImpact(type, branch) {
+    if (type === "validation" && branch.target === "throw") {
+      return "critical";
+    }
+    if (type === "api_response" && branch.condition.includes("error")) {
+      return "critical";
+    }
+    if (type === "guard") {
+      return "high";
+    }
+    if (type === "error_handling") {
+      return "high";
+    }
+    if (type === "state_mutation") {
+      return "medium";
+    }
+    if (type === "feature_flag") {
+      return "medium";
+    }
+    return "low";
+  }
+  /**
+   * Extract data dependencies from a condition
+   */
+  extractDataDependencies(condition) {
+    if (!condition) return [];
+    const deps = [];
+    const varPattern = /\b([a-z_][a-zA-Z0-9_]*(?:\.[a-zA-Z0-9_]+)*)\b/g;
+    const keywords = /* @__PURE__ */ new Set([
+      "if",
+      "else",
+      "true",
+      "false",
+      "null",
+      "undefined",
+      "and",
+      "or",
+      "not",
+      "in",
+      "of",
+      "typeof",
+      "instanceof",
+      "return",
+      "throw",
+      "new",
+      "this",
+      "super"
+    ]);
+    let match;
+    while ((match = varPattern.exec(condition)) !== null) {
+      const word = match[1];
+      if (!keywords.has(word) && !keywords.has(word.split(".")[0])) {
+        deps.push(word);
+      }
+    }
+    return [...new Set(deps)];
+  }
+  // ===========================================================================
+  // 4. ANALYSIS HELPERS
+  // ===========================================================================
+  /**
+   * Analyze conditions summary from paths
+   */
+  analyzeConditions(paths) {
+    let guards = 0;
+    let branches = 0;
+    const criticalConditions = /* @__PURE__ */ new Set();
+    for (const path of paths) {
+      for (const step of path.steps) {
+        if (step.action === "condition") {
+          branches++;
+          if (step.branches) {
+            const outcomes = Object.values(step.branches);
+            if (outcomes.some((o) => o === "return" || o === "throw")) {
+              guards++;
+            }
+          }
+          if (step.condition) {
+            criticalConditions.add(step.condition);
+          }
+        }
+        if (step.action === "guard") {
+          guards++;
+        }
+      }
+    }
+    return {
+      guards,
+      branches,
+      criticalConditions: Array.from(criticalConditions)
+    };
+  }
+  /**
+   * Deduplicate decision points by location
+   */
+  deduplicateDecisionPoints(points) {
+    const seen = /* @__PURE__ */ new Map();
+    for (const point of points) {
+      const key = `${point.location}:${point.condition || point.action}`;
+      if (!seen.has(key)) {
+        seen.set(key, point);
+      }
+    }
+    return Array.from(seen.values());
+  }
+  /**
+   * Sort decision points by criteria
+   */
+  sortDecisionPoints(points, groupBy) {
+    const impactOrder = {
+      critical: 0,
+      high: 1,
+      medium: 2,
+      low: 3
+    };
+    switch (groupBy) {
+      case "impact":
+        return points.sort((a, b) => impactOrder[a.impact] - impactOrder[b.impact]);
+      case "type":
+        return points.sort((a, b) => a.type.localeCompare(b.type));
+      default:
+        return points.sort((a, b) => a.location.localeCompare(b.location));
+    }
+  }
+  /**
+   * Calculate summary statistics
+   */
+  calculateSummary(points) {
+    let possibleOutcomes = 0;
+    const statesModified = /* @__PURE__ */ new Set();
+    for (const point of points) {
+      possibleOutcomes += Object.keys(point.outcomes).length;
+      if (point.type === "state_mutation" && point.dataDepends) {
+        for (const dep of point.dataDepends) {
+          statesModified.add(dep);
+        }
+      }
+    }
+    return {
+      totalDecisionPoints: points.length,
+      criticalPoints: points.filter((p) => p.impact === "critical").length,
+      possibleOutcomes,
+      statesModified: Array.from(statesModified)
+    };
+  }
+  // ===========================================================================
+  // 5. DIAGRAM GENERATION
+  // ===========================================================================
+  /**
+   * Generate Mermaid flowchart for decision points
+   */
+  generateFlowDiagram(points, entryPoints) {
+    const lines = ["flowchart TD"];
+    for (let i = 0; i < entryPoints.length; i++) {
+      const entry = entryPoints[i];
+      lines.push(`  E${i}[${this.sanitizeMermaidLabel(entry.name)}]`);
+    }
+    const grouped = /* @__PURE__ */ new Map();
+    for (const point of points) {
+      const key = point.triggeredBy || "unknown";
+      if (!grouped.has(key)) {
+        grouped.set(key, []);
+      }
+      grouped.get(key).push(point);
+    }
+    let nodeIdx = 0;
+    const nodeMap = /* @__PURE__ */ new Map();
+    for (const [trigger, triggerPoints] of grouped) {
+      lines.push(`  subgraph ${this.sanitizeMermaidLabel(trigger)}`);
+      for (const point of triggerPoints) {
+        const nodeId = `D${nodeIdx++}`;
+        nodeMap.set(point.id, nodeId);
+        const shape = this.getNodeShape(point.type);
+        const label = point.condition ? this.sanitizeMermaidLabel(point.condition.substring(0, 30)) : point.action || point.type;
+        lines.push(`    ${nodeId}${shape.open}${label}${shape.close}`);
+        for (const [outcome, target] of Object.entries(point.outcomes)) {
+          lines.push(`    ${nodeId} -->|${outcome}| ${nodeId}_${this.sanitizeMermaidLabel(target)}`);
+        }
+      }
+      lines.push("  end");
+    }
+    for (let i = 0; i < entryPoints.length; i++) {
+      const entryName = entryPoints[i].name;
+      const firstPoint = grouped.get(entryName)?.[0];
+      if (firstPoint) {
+        const targetNode = nodeMap.get(firstPoint.id);
+        if (targetNode) {
+          lines.push(`  E${i} --> ${targetNode}`);
+        }
+      }
+    }
+    return lines.join("\n");
+  }
+  /**
+   * Get Mermaid node shape based on decision type
+   */
+  getNodeShape(type) {
+    switch (type) {
+      case "validation":
+      case "guard":
+        return { open: "{", close: "}" };
+      // Diamond
+      case "error_handling":
+        return { open: "[[", close: "]]" };
+      // Subroutine
+      case "loop":
+        return { open: "((", close: "))" };
+      // Circle
+      case "state_mutation":
+        return { open: "[/", close: "/]" };
+      // Parallelogram
+      case "feature_flag":
+        return { open: "{{", close: "}}" };
+      // Hexagon
+      default:
+        return { open: "[", close: "]" };
+    }
+  }
+  /**
+   * Sanitize label for Mermaid
+   */
+  sanitizeMermaidLabel(text) {
+    return text.replace(/["\n\r]/g, " ").replace(/[{}[\]<>|]/g, "").trim().substring(0, 50);
+  }
+  // ===========================================================================
+  // 6. CACHE MANAGEMENT
+  // ===========================================================================
+  /**
+   * Clear condition cache
+   */
+  clearCache() {
+    this.decisionPointCache.clear();
+  }
+};
+
+// src/tracing/state-tracker.ts
+var STATE_PATTERNS = {
+  SETTER: /^set[A-Z]/,
+  BOOLEAN: /^(is|has|should|can|will)[A-Z]/
+};
+var StateTracker = class {
+  storage;
+  constructor(storage) {
+    this.storage = storage;
+  }
+  // ===========================================================================
+  // 3. STATE CHANGE DETECTION
+  // ===========================================================================
+  /**
+   * Detect state changes in an entity
+   */
+  async detectStateChanges(entity) {
+    const changes = [];
+    const meta = entity.metadata;
+    if (Array.isArray(meta["stateModifications"])) {
+      for (const state of meta["stateModifications"]) {
+        changes.push({
+          variable: state,
+          isMutation: true
+        });
+      }
+    }
+    if (Array.isArray(meta["assignments"])) {
+      for (const assignment of meta["assignments"]) {
+        changes.push({
+          variable: assignment.target,
+          from: assignment.from,
+          to: assignment.to,
+          isMutation: assignment.isMutation ?? false
+        });
+      }
+    }
+    if (Array.isArray(meta["calls"])) {
+      for (const call of meta["calls"]) {
+        if (this.isMutatingCall(call.name)) {
+          const target = this.extractMutationTarget(call);
+          if (target) {
+            changes.push({
+              variable: target,
+              isMutation: true
+            });
+          }
+        }
+      }
+    }
+    return changes;
+  }
+  /**
+   * Detect state reads in an entity
+   */
+  async detectStateReads(entity) {
+    const reads = /* @__PURE__ */ new Set();
+    const meta = entity.metadata;
+    if (Array.isArray(meta["stateReads"])) {
+      for (const state of meta["stateReads"]) {
+        reads.add(state);
+      }
+    }
+    if (Array.isArray(meta["parameters"])) {
+      for (const param of meta["parameters"]) {
+        reads.add(param.name);
+      }
+    }
+    if (meta["controlFlow"]?.branches && Array.isArray(meta["controlFlow"].branches)) {
+      for (const branch of meta["controlFlow"].branches) {
+        const statesInCondition = this.extractStatesFromCondition(branch.condition);
+        for (const state of statesInCondition) {
+          reads.add(state);
+        }
+      }
+    }
+    return Array.from(reads);
+  }
+  /**
+   * Check if a call is mutating
+   */
+  isMutatingCall(callName) {
+    const mutatingMethods = [
+      "push",
+      "pop",
+      "shift",
+      "unshift",
+      "splice",
+      "set",
+      "delete",
+      "clear",
+      "add",
+      "remove",
+      "assign",
+      "extend",
+      "update",
+      "modify"
+    ];
+    const lowerName = callName.toLowerCase();
+    return mutatingMethods.some((m) => lowerName.includes(m)) || STATE_PATTERNS.SETTER.test(callName);
+  }
+  /**
+   * Extract mutation target from a call
+   */
+  extractMutationTarget(call) {
+    if (call.target) return call.target;
+    const match = call.name.match(/^set([A-Z]\w*)/);
+    if (match) {
+      return match[1].charAt(0).toLowerCase() + match[1].slice(1);
+    }
+    return null;
+  }
+  /**
+   * Extract state variables from a condition expression
+   */
+  extractStatesFromCondition(condition) {
+    if (!condition) return [];
+    const states = [];
+    const varPattern = /\b([a-z_][a-zA-Z0-9_]*)\b/g;
+    const keywords = /* @__PURE__ */ new Set([
+      "if",
+      "else",
+      "true",
+      "false",
+      "null",
+      "undefined",
+      "and",
+      "or",
+      "not",
+      "in",
+      "of",
+      "typeof",
+      "instanceof"
+    ]);
+    let match;
+    while ((match = varPattern.exec(condition)) !== null) {
+      if (!keywords.has(match[1])) {
+        states.push(match[1]);
+      }
+    }
+    return states;
+  }
+  // ===========================================================================
+  // 4. STATE IMPACT ANALYSIS
+  // ===========================================================================
+  /**
+   * Analyze the impact of a state variable
+   */
+  async analyzeStateImpact(params) {
+    const { state, scenarios } = params;
+    const usages = await this.findStateUsages(state);
+    const scenarioAnalysis = {};
+    for (const scenario of scenarios) {
+      scenarioAnalysis[scenario.label] = await this.analyzeScenario(state, scenario.value, usages);
+    }
+    const conflicts = this.detectConflicts(state, usages);
+    const rippleEffects = await this.calculateRippleEffects(state, usages);
+    return {
+      state,
+      usages,
+      scenarioAnalysis,
+      conflicts,
+      rippleEffects
+    };
+  }
+  /**
+   * Find all usages of a state variable
+   */
+  async findStateUsages(state) {
+    const usages = [];
+    const allEntities = await this.storage.getAllEntities();
+    for (const entity of allEntities) {
+      const meta = entity.metadata;
+      if (Array.isArray(meta["stateReads"]) && meta["stateReads"].includes(state)) {
+        usages.push({
+          location: `${entity.filePath}:${entity.location.start.line}`,
+          usage: "read",
+          code: entity.name,
+          entityName: entity.name
+        });
+      }
+      if (Array.isArray(meta["stateModifications"]) && meta["stateModifications"].includes(state)) {
+        usages.push({
+          location: `${entity.filePath}:${entity.location.start.line}`,
+          usage: "assignment",
+          code: entity.name,
+          entityName: entity.name
+        });
+      }
+      if (meta["controlFlow"]?.branches && Array.isArray(meta["controlFlow"].branches)) {
+        for (const branch of meta["controlFlow"].branches) {
+          if (branch.condition?.includes(state)) {
+            usages.push({
+              location: `${entity.filePath}:${entity.location.start.line}`,
+              usage: "condition",
+              code: branch.condition,
+              entityName: entity.name
+            });
+          }
+        }
+      }
+      if (Array.isArray(meta["parameters"]) && meta["parameters"].some(
+        (p) => p !== null && typeof p === "object" && "name" in p && p.name === state
+      )) {
+        usages.push({
+          location: `${entity.filePath}:${entity.location.start.line}`,
+          usage: "parameter",
+          code: entity.name,
+          entityName: entity.name
+        });
+      }
+    }
+    return usages;
+  }
+  /**
+   * Analyze a specific scenario
+   */
+  async analyzeScenario(_state, value, usages) {
+    const reachablePaths = [];
+    const blockedPaths = [];
+    const enabledFeatures = [];
+    const stateChanges = [];
+    for (const usage of usages) {
+      if (usage.usage === "condition") {
+        const wouldPass = this.simulateCondition(usage.code, value);
+        if (wouldPass) {
+          reachablePaths.push(`${usage.entityName}: ${usage.code} \u2192 true`);
+        } else {
+          blockedPaths.push(`${usage.entityName}: ${usage.code} \u2192 false`);
+        }
+      }
+      if (usage.usage === "assignment") {
+        stateChanges.push(`${usage.entityName} modifies state`);
+      }
+    }
+    for (const path of reachablePaths) {
+      const feature = this.inferFeatureFromPath(path);
+      if (feature) {
+        enabledFeatures.push(feature);
+      }
+    }
+    return {
+      reachablePaths,
+      blockedPaths,
+      enabledFeatures,
+      stateChanges
+    };
+  }
+  /**
+   * Simulate a condition with given state value
+   */
+  simulateCondition(condition, value) {
+    if (condition.includes("=== true") || condition.includes("== true")) {
+      return value === true;
+    }
+    if (condition.includes("=== false") || condition.includes("== false")) {
+      return value === false;
+    }
+    if (condition.includes("!")) {
+      return !value;
+    }
+    return !!value;
+  }
+  /**
+   * Infer feature name from path description
+   */
+  inferFeatureFromPath(path) {
+    const match = path.match(/^(\w+):/);
+    return match ? match[1] : null;
+  }
+  /**
+   * Detect conflicts in state usage
+   */
+  detectConflicts(state, usages) {
+    const conflicts = [];
+    const assignments = usages.filter((u) => u.usage === "assignment");
+    if (assignments.length > 1) {
+      conflicts.push({
+        description: `Multiple assignment points for '${state}'`,
+        location: assignments.map((a) => a.location).join(", "),
+        risk: "medium",
+        recommendation: "Ensure clear assignment order or use single source of truth"
+      });
+    }
+    const conditionUsages = usages.filter((u) => u.usage === "condition");
+    const hasAssignment = assignments.length > 0;
+    if (conditionUsages.length > 0 && !hasAssignment) {
+      conflicts.push({
+        description: `State '${state}' read but never set in analyzed scope`,
+        location: conditionUsages[0].location,
+        risk: "high",
+        recommendation: "Verify state is initialized before use"
+      });
+    }
+    return conflicts;
+  }
+  /**
+   * Calculate ripple effects of state changes
+   */
+  async calculateRippleEffects(_state, usages) {
+    const components = /* @__PURE__ */ new Set();
+    for (const usage of usages) {
+      if (usage.entityName) {
+        components.add(usage.entityName);
+      }
+    }
+    const directEffects = components.size;
+    let indirectEffects = 0;
+    for (const component of components) {
+      const entity = await this.storage.searchEntities({ namePattern: component });
+      if (entity.length > 0) {
+        const rels = await this.storage.getRelationshipsForEntity(entity[0].id, "calls" /* CALLS */);
+        indirectEffects += rels.length;
+      }
+    }
+    return {
+      directEffects,
+      indirectEffects,
+      affectedComponents: Array.from(components)
+    };
+  }
+  // ===========================================================================
+  // 5. STATE DEPENDENCY TRACKING
+  // ===========================================================================
+  /**
+   * Build complete state dependency graph for an entity
+   */
+  async buildStateDependencies(entityId) {
+    const entity = await this.storage.getEntity(entityId);
+    if (!entity) return [];
+    const dependencies = [];
+    const reads = await this.detectStateReads(entity);
+    for (const state of reads) {
+      const modifiers = await this.findModifiers(state);
+      dependencies.push({
+        state,
+        modifiedBy: modifiers,
+        stateType: this.inferType(state)
+      });
+    }
+    return dependencies;
+  }
+  /**
+   * Find all entities that modify a state
+   */
+  async findModifiers(state) {
+    const modifiers = [];
+    const entities = await this.storage.getAllEntities();
+    for (const entity of entities) {
+      const meta = entity.metadata;
+      if (Array.isArray(meta["stateModifications"]) && meta["stateModifications"].includes(state)) {
+        modifiers.push(entity.name);
+      }
+      if (STATE_PATTERNS.SETTER.test(entity.name)) {
+        const targetState = entity.name.replace(/^set/, "").toLowerCase();
+        if (targetState === state.toLowerCase()) {
+          modifiers.push(entity.name);
+        }
+      }
+    }
+    return modifiers;
+  }
+  /**
+   * Infer state type from name
+   */
+  inferType(state) {
+    if (STATE_PATTERNS.BOOLEAN.test(state)) return "boolean";
+    if (state.endsWith("Count") || state.endsWith("Index")) return "number";
+    if (state.endsWith("List") || state.endsWith("Array")) return "array";
+    if (state.endsWith("Map") || state.endsWith("Dict")) return "object";
+    return "unknown";
+  }
+  // ===========================================================================
+  // 6. CACHE MANAGEMENT
+  // ===========================================================================
+  /**
+   * Clear state cache
+   */
+  clearCache() {
+  }
+};
+
+// src/tracing/data-flow-analyzer.ts
+var DEFAULT_MAX_DEPTH = 15;
+var DATA_SOURCE_PATTERNS = {
+  API: /fetch|axios|http|request|api/i,
+  STORAGE: /localStorage|sessionStorage|cookie|database|db/i,
+  PROPS: /props|input|param/i,
+  STATE: /state|store|redux|context/i,
+  CONFIG: /config|settings|env|options/i,
+  USER_INPUT: /input|form|event|click/i
+};
+var TRANSFORM_PATTERNS = {
+  PARSE: /parse|decode|deserialize|from(JSON|XML|YAML)/i,
+  MAP: /\.map\(|\.reduce\(|\.filter\(|transform/i,
+  VALIDATE: /valid|check|verify|assert|ensure/i,
+  NORMALIZE: /normaliz|sanitiz|clean|format/i,
+  MERGE: /merge|combine|assign|spread/i
+};
+var DataFlowAnalyzer = class {
+  storage;
+  semanticSearch;
+  stateTracker;
+  constructor(storage, semanticSearch) {
+    this.storage = storage;
+    this.semanticSearch = semanticSearch;
+    this.stateTracker = new StateTracker(storage);
+  }
+  // ===========================================================================
+  // 3. MAIN ANALYSIS
+  // ===========================================================================
+  /**
+   * Trace data flow from entry point to target state
+   */
+  async traceDataFlow(params) {
+    const { entryPoint, targetState, dataSources, trackTransformations = true } = params;
+    const entryEntity = await this.findEntity(entryPoint);
+    if (!entryEntity) {
+      throw new Error(`Entry point not found: ${entryPoint}`);
+    }
+    const sources = dataSources && dataSources.length > 0 ? dataSources : await this.identifyDataSources(entryEntity);
+    const dataFlows = [];
+    const allCriticalConditions = /* @__PURE__ */ new Set();
+    for (const source of sources) {
+      const flow = await this.traceSourceToTarget(source, targetState, entryEntity, trackTransformations);
+      if (flow) {
+        dataFlows.push(flow);
+        for (const cond of flow.criticalConditions) {
+          allCriticalConditions.add(cond);
+        }
+      }
+    }
+    const behaviorMatrix = await this.buildBehaviorMatrix(dataFlows, targetState);
+    const summary = {
+      dataSourcesAnalyzed: sources.length,
+      branchingPoints: dataFlows.reduce((sum, f) => sum + f.flow.filter((s) => s.action === "branch").length, 0),
+      possibleOutcomes: behaviorMatrix.combinations.length,
+      criticalDecisions: Array.from(allCriticalConditions)
+    };
+    return {
+      entryPoint,
+      targetState,
+      dataFlows,
+      behaviorMatrix,
+      summary
+    };
+  }
+  // ===========================================================================
+  // 4. DATA SOURCE IDENTIFICATION
+  // ===========================================================================
+  /**
+   * Identify data sources from entry point
+   */
+  async identifyDataSources(entryEntity) {
+    const sources = [];
+    const meta = entryEntity.metadata;
+    if (Array.isArray(meta["parameters"])) {
+      for (const param of meta["parameters"]) {
+        sources.push(param.name);
+      }
+    }
+    if (Array.isArray(meta["calls"])) {
+      for (const call of meta["calls"]) {
+        const sourceType = this.classifyDataSource(call.name);
+        if (sourceType) {
+          sources.push(`${sourceType}:${call.name}`);
+        }
+      }
+    }
+    if (Array.isArray(meta["stateReads"])) {
+      for (const state of meta["stateReads"]) {
+        sources.push(`state:${state}`);
+      }
+    }
+    return sources;
+  }
+  /**
+   * Classify a call as a data source type
+   */
+  classifyDataSource(callName) {
+    for (const [type, pattern] of Object.entries(DATA_SOURCE_PATTERNS)) {
+      if (pattern.test(callName)) {
+        return type.toLowerCase();
+      }
+    }
+    return null;
+  }
+  // ===========================================================================
+  // 5. FLOW TRACING
+  // ===========================================================================
+  /**
+   * Trace data flow from a source to target
+   */
+  async traceSourceToTarget(source, targetState, entryEntity, trackTransformations) {
+    const flow = [];
+    const criticalConditions = [];
+    const visited = /* @__PURE__ */ new Set();
+    let currentEntity = entryEntity;
+    let stepOrder = 1;
+    let currentData = source;
+    while (currentEntity && stepOrder <= DEFAULT_MAX_DEPTH) {
+      if (visited.has(currentEntity.id)) break;
+      visited.add(currentEntity.id);
+      const meta = currentEntity.metadata;
+      if (trackTransformations && Array.isArray(meta["calls"])) {
+        for (const call of meta["calls"]) {
+          const transformType = this.classifyTransformation(call.name);
+          if (transformType) {
+            flow.push({
+              step: stepOrder++,
+              location: `${currentEntity.filePath}:${currentEntity.location.start.line}`,
+              action: transformType,
+              input: currentData,
+              output: `transformed(${currentData})`,
+              transformation: call.name
+            });
+            currentData = `transformed(${currentData})`;
+          }
+        }
+      }
+      if (meta["controlFlow"]?.branches && Array.isArray(meta["controlFlow"].branches)) {
+        for (const branch of meta["controlFlow"].branches) {
+          if (this.conditionInvolvesData(branch.condition, source)) {
+            flow.push({
+              step: stepOrder++,
+              location: `${currentEntity.filePath}:${currentEntity.location.start.line}`,
+              action: "branch",
+              condition: branch.condition,
+              branches: {
+                true: branch.target || "continue",
+                false: "skip"
+              }
+            });
+            criticalConditions.push(branch.condition);
+          }
+        }
+      }
+      if (Array.isArray(meta["stateModifications"]) && meta["stateModifications"].includes(targetState)) {
+        flow.push({
+          step: stepOrder++,
+          location: `${currentEntity.filePath}:${currentEntity.location.start.line}`,
+          action: "setState",
+          input: currentData,
+          output: targetState
+        });
+        break;
+      }
+      const nextEntity = await this.findNextInFlow(currentEntity, currentData);
+      currentEntity = nextEntity;
+    }
+    const affectsTarget = flow.some((s) => s.action === "setState" && s.output === targetState);
+    if (flow.length === 0) {
+      return null;
+    }
+    return {
+      source,
+      flow,
+      affectsTarget,
+      criticalConditions
+    };
+  }
+  /**
+   * Classify transformation type
+   */
+  classifyTransformation(callName) {
+    for (const [type, pattern] of Object.entries(TRANSFORM_PATTERNS)) {
+      if (pattern.test(callName)) {
+        switch (type) {
+          case "PARSE":
+            return "parse";
+          case "MAP":
+            return "transform";
+          case "VALIDATE":
+            return "validate";
+          default:
+            return "transform";
+        }
+      }
+    }
+    return null;
+  }
+  /**
+   * Check if condition involves specific data
+   */
+  conditionInvolvesData(condition, data) {
+    if (!condition || !data) return false;
+    const dataVar = data.split(":").pop() || data;
+    return condition.toLowerCase().includes(dataVar.toLowerCase());
+  }
+  /**
+   * Find next entity in data flow
+   */
+  async findNextInFlow(currentEntity, data) {
+    const rels = await this.storage.getRelationshipsForEntity(currentEntity.id, "calls" /* CALLS */);
+    for (const rel of rels) {
+      if (rel.fromId === currentEntity.id) {
+        const callee = await this.storage.getEntity(rel.toId);
+        if (callee) {
+          const callMeta = rel.metadata;
+          if (Array.isArray(callMeta?.["arguments"]) && callMeta["arguments"].includes(data) || this.entityHandlesData(callee, data)) {
+            return callee;
+          }
+        }
+      }
+    }
+    return null;
+  }
+  /**
+   * Check if entity handles specific data
+   */
+  entityHandlesData(entity, data) {
+    const meta = entity.metadata;
+    const dataVar = data.split(":").pop() || data;
+    if (Array.isArray(meta["parameters"]) && meta["parameters"].some(
+      (p) => p !== null && typeof p === "object" && "name" in p && typeof p.name === "string" && p.name.toLowerCase().includes(dataVar.toLowerCase())
+    )) {
+      return true;
+    }
+    if (Array.isArray(meta["stateReads"]) && meta["stateReads"].some((s) => s.toLowerCase().includes(dataVar.toLowerCase()))) {
+      return true;
+    }
+    return false;
+  }
+  // ===========================================================================
+  // 6. BEHAVIOR MATRIX
+  // ===========================================================================
+  /**
+   * Build behavior matrix showing input/output combinations
+   */
+  async buildBehaviorMatrix(flows, targetState) {
+    const combinations = [];
+    const allConditions = [];
+    for (const flow of flows) {
+      for (const step of flow.flow) {
+        if (step.action === "branch" && step.condition) {
+          allConditions.push({
+            source: flow.source,
+            condition: step.condition
+          });
+        }
+      }
+    }
+    const maxCombinations = Math.min(2 ** allConditions.length, 16);
+    for (let i = 0; i < maxCombinations; i++) {
+      const inputs = {};
+      const pathParts = [];
+      for (let j = 0; j < allConditions.length; j++) {
+        const cond = allConditions[j];
+        const value = (i & 1 << j) !== 0;
+        inputs[`${cond.source}:${cond.condition}`] = value;
+        pathParts.push(`${cond.condition}=${value}`);
+      }
+      const result = {};
+      let targetReached = false;
+      for (const flow of flows) {
+        if (flow.affectsTarget) {
+          const wouldExecute = this.evaluateFlowWithConditions(flow, inputs);
+          if (wouldExecute) {
+            result[targetState] = `from ${flow.source}`;
+            targetReached = true;
+          }
+        }
+      }
+      if (!targetReached) {
+        result[targetState] = "unchanged";
+      }
+      combinations.push({
+        inputs,
+        result,
+        path: pathParts.join(" \u2192 ")
+      });
+    }
+    return { combinations };
+  }
+  /**
+   * Evaluate if a flow would execute with given conditions
+   */
+  evaluateFlowWithConditions(flow, conditions) {
+    for (const step of flow.flow) {
+      if (step.action === "branch" && step.condition) {
+        const key = `${flow.source}:${step.condition}`;
+        const conditionValue = conditions[key];
+        if (conditionValue === false) {
+          if (step.branches?.["false"] === "skip" || step.branches?.["false"] === "return") {
+            return false;
+          }
+        }
+      }
+    }
+    return true;
+  }
+  // ===========================================================================
+  // 7. UTILITY METHODS
+  // ===========================================================================
+  /**
+   * Find entity by name or pattern
+   */
+  async findEntity(nameOrPattern) {
+    const entities = await this.storage.searchEntities({
+      namePattern: nameOrPattern
+    });
+    if (entities.length > 0) {
+      return entities[0];
+    }
+    if (this.semanticSearch) {
+      try {
+        const results = await this.semanticSearch.search(nameOrPattern, {
+          limit: 1,
+          minSimilarity: 0.6
+        });
+        if (results.length > 0) {
+          return this.storage.getEntity(results[0].entityId);
+        }
+      } catch {
+      }
+    }
+    return null;
+  }
+  /**
+   * Clear caches
+   */
+  clearCache() {
+    this.stateTracker.clearCache();
+  }
+};
+
+// src/tracing/output-formatter.ts
+var OutputFormatter = class {
+  // ===========================================================================
+  // 2. TRACE FLOW FORMATTING
+  // ===========================================================================
+  /**
+   * Format trace flow result as text
+   */
+  formatTraceFlowAsText(result) {
+    const lines = [];
+    lines.push(`\u2550\u2550\u2550 Trace Flow: ${result.from} \u2192 ${result.to} \u2550\u2550\u2550`);
+    lines.push("");
+    if (result.paths.length === 0) {
+      lines.push("\u274C No paths found between these points.");
+      if (result._debug && typeof result._debug === "object") {
+        const debug = result._debug;
+        lines.push("");
+        lines.push("--- Debug Info ---");
+        lines.push(`Source: ${debug["sourceEntityName"]} (${debug["sourceEntityId"]})`);
+        lines.push(`Target: ${debug["targetEntityName"]} (${debug["targetEntityId"]})`);
+        const graphStats = debug["graphStats"];
+        lines.push(`Graph: ${graphStats?.nodes} nodes, ${graphStats?.edges} edges`);
+        lines.push(`Linear trace: ${debug["linearTraceSummary"]}`);
+        lines.push(`Nodes visited: ${debug["nodesVisited"]}`);
+      }
+      return lines.join("\n");
+    }
+    lines.push(`Found ${result.paths.length} path(s):`);
+    lines.push("");
+    for (let i = 0; i < result.paths.length; i++) {
+      const path = result.paths[i];
+      lines.push(`\u2500\u2500\u2500 Path ${i + 1} (confidence: ${Math.round(path.confidence * 100)}%) \u2500\u2500\u2500`);
+      lines.push(`Summary: ${path.summary}`);
+      lines.push("");
+      for (const step of path.steps) {
+        const stepLine = this.formatStep(step);
+        lines.push(stepLine);
+      }
+      if (path.warnings && path.warnings.length > 0) {
+        lines.push("");
+        lines.push("\u26A0\uFE0F Warnings:");
+        for (const warning of path.warnings) {
+          lines.push(`  \u2022 ${warning}`);
+        }
+      }
+      lines.push("");
+    }
+    if (result.statesSummary.modified.length > 0 || result.statesSummary.read.length > 0) {
+      lines.push("\u2500\u2500\u2500 States \u2500\u2500\u2500");
+      if (result.statesSummary.modified.length > 0) {
+        lines.push(`Modified: ${result.statesSummary.modified.join(", ")}`);
+      }
+      if (result.statesSummary.read.length > 0) {
+        lines.push(`Read: ${result.statesSummary.read.join(", ")}`);
+      }
+      if (result.statesSummary.critical.length > 0) {
+        lines.push(`Critical: ${result.statesSummary.critical.join(", ")}`);
+      }
+      lines.push("");
+    }
+    if (result.conditionsSummary.branches > 0) {
+      lines.push("\u2500\u2500\u2500 Conditions \u2500\u2500\u2500");
+      lines.push(`Guards: ${result.conditionsSummary.guards}`);
+      lines.push(`Branches: ${result.conditionsSummary.branches}`);
+      if (result.conditionsSummary.criticalConditions.length > 0) {
+        lines.push(`Critical: ${result.conditionsSummary.criticalConditions.join("; ")}`);
+      }
+      lines.push("");
+    }
+    return lines.join("\n");
+  }
+  /**
+   * Format a single step
+   */
+  formatStep(step) {
+    const prefix = `  ${step.order}. `;
+    const icon = this.getStepIcon(step.action);
+    let line = `${prefix}${icon} ${step.entity}`;
+    line += ` (${step.file}:${step.line})`;
+    if (step.condition) {
+      line += `
+     \u2514\u2500 if: ${step.condition}`;
+    }
+    if (step.awaits) {
+      line += `
+     \u2514\u2500 await: ${step.awaitTarget || "async"}`;
+    }
+    if (step.stateChanges && step.stateChanges.length > 0) {
+      for (const change of step.stateChanges) {
+        line += `
+     \u2514\u2500 ${change.variable}`;
+        if (change.from && change.to) {
+          line += `: ${change.from} \u2192 ${change.to}`;
+        }
+      }
+    }
+    return line;
+  }
+  /**
+   * Get icon for step action
+   */
+  getStepIcon(action) {
+    const icons = {
+      call: "\u2192",
+      condition: "\u25C7",
+      setState: "\u25CF",
+      await: "\u23F3",
+      return: "\u21A9",
+      throw: "\u26A1",
+      loop: "\u21BB",
+      guard: "\u{1F6E1}"
+    };
+    return icons[action] || "\u2022";
+  }
+  /**
+   * Format trace flow as Mermaid sequence diagram
+   */
+  formatTraceFlowAsMermaid(result) {
+    if (result.mermaid) {
+      return result.mermaid;
+    }
+    const lines = ["sequenceDiagram"];
+    const participants = /* @__PURE__ */ new Set();
+    for (const path of result.paths) {
+      for (const step of path.steps) {
+        participants.add(step.entity);
+      }
+    }
+    let idx = 0;
+    const participantIds = /* @__PURE__ */ new Map();
+    for (const p of participants) {
+      const id = `P${idx++}`;
+      participantIds.set(p, id);
+      lines.push(`  participant ${id} as ${this.sanitize(p)}`);
+    }
+    for (let i = 0; i < Math.min(result.paths.length, 2); i++) {
+      const path = result.paths[i];
+      lines.push(`  Note right of P0: Path ${i + 1}`);
+      for (let j = 0; j < path.steps.length - 1; j++) {
+        const from = path.steps[j];
+        const to = path.steps[j + 1];
+        const fromId = participantIds.get(from.entity) || "P0";
+        const toId = participantIds.get(to.entity) || "P0";
+        const arrow = from.awaits ? "-->>" : "->>";
+        const label = from.condition || from.action;
+        lines.push(`  ${fromId}${arrow}${toId}: ${this.sanitize(label)}`);
+      }
+    }
+    return lines.join("\n");
+  }
+  // ===========================================================================
+  // 3. TRACE BACKWARDS FORMATTING
+  // ===========================================================================
+  /**
+   * Format trace backwards result as text
+   */
+  formatTraceBackwardsAsText(result) {
+    const lines = [];
+    lines.push(`\u2550\u2550\u2550 Trace Backwards: ${result.target.name} \u2550\u2550\u2550`);
+    lines.push(`Location: ${result.target.file}`);
+    lines.push(`Signature: ${result.target.signature}`);
+    lines.push("");
+    lines.push(`\u2500\u2500\u2500 Callers (${result.callers.length}) \u2500\u2500\u2500`);
+    if (result.callers.length === 0) {
+      lines.push("\u274C No callers found - this may be dead code");
+    } else {
+      for (const caller of result.callers) {
+        const prob = this.getProbabilityIcon(caller.probability);
+        lines.push(`  ${prob} ${caller.name} (${caller.file}:${caller.line})`);
+        if (caller.condition) {
+          lines.push(`     \u2514\u2500 when: ${caller.condition}`);
+        }
+      }
+    }
+    lines.push("");
+    if (result.blockingConditions.length > 0) {
+      lines.push(`\u2500\u2500\u2500 Blocking Conditions (${result.blockingConditions.length}) \u2500\u2500\u2500`);
+      for (const block of result.blockingConditions) {
+        lines.push(`  \u26D4 ${block.condition}`);
+        lines.push(`     Location: ${block.location}`);
+        lines.push(`     Recommendation: ${block.recommendation}`);
+      }
+      lines.push("");
+    }
+    if (result.statesDependencies.length > 0) {
+      lines.push(`\u2500\u2500\u2500 State Dependencies (${result.statesDependencies.length}) \u2500\u2500\u2500`);
+      for (const dep of result.statesDependencies) {
+        lines.push(`  \u{1F4CA} ${dep.state} (${dep.stateType || "unknown"})`);
+        if (dep.modifiedBy.length > 0) {
+          lines.push(`     Modified by: ${dep.modifiedBy.join(", ")}`);
+        } else {
+          lines.push(`     \u26A0\uFE0F No known modifiers`);
+        }
+        if (dep.requiredValue) {
+          lines.push(`     Required: ${dep.requiredValue}`);
+        }
+      }
+      lines.push("");
+    }
+    if (result.callChains.length > 0) {
+      lines.push(`\u2500\u2500\u2500 Call Chains (${result.callChains.length}) \u2500\u2500\u2500`);
+      for (let i = 0; i < result.callChains.length; i++) {
+        const chain = result.callChains[i];
+        const likelihood = this.getLikelihoodIcon(chain.likelihood);
+        lines.push(`  ${i + 1}. ${likelihood} ${chain.chain.join(" \u2192 ")}`);
+        if (chain.guards.length > 0) {
+          lines.push(`     Guards: ${chain.guards.join("; ")}`);
+        }
+        if (chain.entryPoint) {
+          lines.push(`     Entry: ${chain.entryPoint}`);
+        }
+      }
+      lines.push("");
+    }
+    lines.push("\u2500\u2500\u2500 Diagnosis \u2500\u2500\u2500");
+    if (result.diagnosis.mostLikely) {
+      lines.push(`\u{1F3AF} Most likely: ${result.diagnosis.mostLikely}`);
+    }
+    if (result.diagnosis.possibleReasons.length > 0) {
+      lines.push("Possible reasons:");
+      for (const reason of result.diagnosis.possibleReasons) {
+        lines.push(`  \u2022 ${reason}`);
+      }
+    }
+    if (result.diagnosis.suggestedDebugPoints.length > 0) {
+      lines.push("Debug points:");
+      for (const point of result.diagnosis.suggestedDebugPoints) {
+        lines.push(`  \u{1F50D} ${point}`);
+      }
+    }
+    return lines.join("\n");
+  }
+  /**
+   * Get icon for call probability
+   */
+  getProbabilityIcon(prob) {
+    switch (prob) {
+      case "always":
+        return "\u2705";
+      case "conditional":
+        return "\u2753";
+      case "rare":
+        return "\u26A0\uFE0F";
+      default:
+        return "\u2022";
+    }
+  }
+  /**
+   * Get icon for likelihood
+   */
+  getLikelihoodIcon(likelihood) {
+    switch (likelihood) {
+      case "high":
+        return "\u{1F7E2}";
+      case "medium":
+        return "\u{1F7E1}";
+      case "low":
+        return "\u{1F534}";
+      default:
+        return "\u26AA";
+    }
+  }
+  // ===========================================================================
+  // 4. DATA FLOW FORMATTING
+  // ===========================================================================
+  /**
+   * Format data flow result as text
+   */
+  formatDataFlowAsText(result) {
+    const lines = [];
+    lines.push(`\u2550\u2550\u2550 Data Flow: ${result.entryPoint} \u2192 ${result.targetState} \u2550\u2550\u2550`);
+    lines.push("");
+    lines.push(`Data sources analyzed: ${result.summary.dataSourcesAnalyzed}`);
+    lines.push(`Branching points: ${result.summary.branchingPoints}`);
+    lines.push(`Possible outcomes: ${result.summary.possibleOutcomes}`);
+    lines.push("");
+    for (let i = 0; i < result.dataFlows.length; i++) {
+      const flow = result.dataFlows[i];
+      const affects = flow.affectsTarget ? "\u2705" : "\u274C";
+      lines.push(`\u2500\u2500\u2500 Flow ${i + 1}: ${flow.source} ${affects} \u2500\u2500\u2500`);
+      for (const step of flow.flow) {
+        const icon = this.getDataFlowIcon(step.action);
+        let line = `  ${step.step}. ${icon} ${step.action}`;
+        if (step.input && step.output) {
+          line += `: ${step.input} \u2192 ${step.output}`;
+        }
+        if (step.transformation) {
+          line += ` [${step.transformation}]`;
+        }
+        lines.push(line);
+        if (step.condition) {
+          lines.push(`     \u2514\u2500 if: ${step.condition}`);
+        }
+      }
+      if (flow.criticalConditions.length > 0) {
+        lines.push(`  Critical: ${flow.criticalConditions.join("; ")}`);
+      }
+      lines.push("");
+    }
+    if (result.behaviorMatrix.combinations.length > 0) {
+      lines.push("\u2500\u2500\u2500 Behavior Matrix \u2500\u2500\u2500");
+      for (const combo of result.behaviorMatrix.combinations.slice(0, 8)) {
+        const inputs = Object.entries(combo.inputs).map(([k, v]) => `${k.split(":").pop()}=${v}`).join(", ");
+        const outputs = Object.entries(combo.result).map(([k, v]) => `${k}=${v}`).join(", ");
+        lines.push(`  ${inputs} \u2192 ${outputs}`);
+      }
+      if (result.behaviorMatrix.combinations.length > 8) {
+        lines.push(`  ... and ${result.behaviorMatrix.combinations.length - 8} more combinations`);
+      }
+    }
+    return lines.join("\n");
+  }
+  /**
+   * Get icon for data flow action
+   */
+  getDataFlowIcon(action) {
+    const icons = {
+      parse: "\u{1F4E5}",
+      transform: "\u{1F504}",
+      branch: "\u25C7",
+      setState: "\u{1F4BE}",
+      fetch: "\u{1F310}",
+      validate: "\u2713",
+      emit: "\u{1F4E4}"
+    };
+    return icons[action] || "\u2022";
+  }
+  // ===========================================================================
+  // 5. STATE IMPACT FORMATTING
+  // ===========================================================================
+  /**
+   * Format state impact result as text
+   */
+  formatStateImpactAsText(result) {
+    const lines = [];
+    lines.push(`\u2550\u2550\u2550 State Impact: ${result.state} \u2550\u2550\u2550`);
+    lines.push("");
+    lines.push(`\u2500\u2500\u2500 Usages (${result.usages.length}) \u2500\u2500\u2500`);
+    const usagesByType = this.groupBy(result.usages, "usage");
+    for (const [type, usages] of Object.entries(usagesByType)) {
+      lines.push(`  ${type}: ${usages.length}`);
+      for (const usage of usages.slice(0, 3)) {
+        lines.push(`    \u2022 ${usage.entityName || usage.location}`);
+      }
+      if (usages.length > 3) {
+        lines.push(`    ... and ${usages.length - 3} more`);
+      }
+    }
+    lines.push("");
+    lines.push("\u2500\u2500\u2500 Scenario Analysis \u2500\u2500\u2500");
+    for (const [label, analysis] of Object.entries(result.scenarioAnalysis)) {
+      lines.push(`  ${label}:`);
+      lines.push(`    Reachable: ${analysis.reachablePaths.length} paths`);
+      lines.push(`    Blocked: ${analysis.blockedPaths.length} paths`);
+      if (analysis.enabledFeatures.length > 0) {
+        lines.push(`    Features: ${analysis.enabledFeatures.join(", ")}`);
+      }
+    }
+    lines.push("");
+    if (result.conflicts.length > 0) {
+      lines.push(`\u2500\u2500\u2500 Conflicts (${result.conflicts.length}) \u2500\u2500\u2500`);
+      for (const conflict of result.conflicts) {
+        lines.push(`  \u26A0\uFE0F ${conflict.description}`);
+        lines.push(`     Risk: ${conflict.risk}`);
+        lines.push(`     Fix: ${conflict.recommendation}`);
+      }
+      lines.push("");
+    }
+    lines.push("\u2500\u2500\u2500 Ripple Effects \u2500\u2500\u2500");
+    lines.push(`  Direct: ${result.rippleEffects.directEffects} components`);
+    lines.push(`  Indirect: ${result.rippleEffects.indirectEffects} dependencies`);
+    if (result.rippleEffects.affectedComponents.length > 0) {
+      lines.push(`  Components: ${result.rippleEffects.affectedComponents.join(", ")}`);
+    }
+    return lines.join("\n");
+  }
+  // ===========================================================================
+  // 6. DECISION POINTS FORMATTING
+  // ===========================================================================
+  /**
+   * Format decision points result as text
+   */
+  formatDecisionPointsAsText(result) {
+    const lines = [];
+    lines.push(`\u2550\u2550\u2550 Decision Points: ${result.scenario} \u2550\u2550\u2550`);
+    lines.push("");
+    lines.push(`Entry points: ${result.entryPoints.map((e) => e.name).join(", ")}`);
+    lines.push(`Total: ${result.summary.totalDecisionPoints} | Critical: ${result.summary.criticalPoints}`);
+    lines.push(`Possible outcomes: ${result.summary.possibleOutcomes}`);
+    lines.push("");
+    const byType = this.groupBy(result.decisionPoints, "type");
+    for (const [type, points] of Object.entries(byType)) {
+      lines.push(`\u2500\u2500\u2500 ${type.toUpperCase()} (${points.length}) \u2500\u2500\u2500`);
+      for (const point of points) {
+        const impact = this.getImpactIcon(point.impact);
+        lines.push(`  ${impact} ${point.condition || point.action || point.type}`);
+        lines.push(`     Location: ${point.location}`);
+        lines.push(`     Outcomes: ${Object.keys(point.outcomes).join(", ")}`);
+        if (point.dataDepends.length > 0) {
+          lines.push(`     Depends on: ${point.dataDepends.join(", ")}`);
+        }
+      }
+      lines.push("");
+    }
+    return lines.join("\n");
+  }
+  /**
+   * Get icon for impact level
+   */
+  getImpactIcon(impact) {
+    switch (impact) {
+      case "critical":
+        return "\u{1F534}";
+      case "high":
+        return "\u{1F7E0}";
+      case "medium":
+        return "\u{1F7E1}";
+      case "low":
+        return "\u{1F7E2}";
+      default:
+        return "\u26AA";
+    }
+  }
+  // ===========================================================================
+  // 7. UTILITY METHODS
+  // ===========================================================================
+  /**
+   * Sanitize string for Mermaid
+   */
+  sanitize(text) {
+    return text.replace(/["\n\r]/g, " ").replace(/[{}[\]<>|]/g, "").trim().substring(0, 40);
+  }
+  /**
+   * Group array by property
+   */
+  groupBy(array, key) {
+    return array.reduce(
+      (groups, item) => {
+        const value = String(item[key]);
+        if (!groups[value]) {
+          groups[value] = [];
+        }
+        groups[value].push(item);
+        return groups;
+      },
+      {}
+    );
+  }
+};
+
+// src/tracing/ngrx-resolution.ts
+var NGRX_RELATIONSHIP_TYPES = /* @__PURE__ */ new Set([
+  "listens_to_action" /* LISTENS_TO_ACTION */,
+  // effect -> action (ofType)
+  "handles_action" /* HANDLES_ACTION */,
+  // reducer -> action (on)
+  "selects_state" /* SELECTS_STATE */,
+  // component -> selector
+  "dispatches_action" /* DISPATCHES_ACTION */,
+  // component/effect -> action
+  "modifies_state" /* MODIFIES_STATE */
+  // reducer -> state slice
+]);
+function getDirectory(filePath) {
+  const lastSlash = Math.max(filePath.lastIndexOf("/"), filePath.lastIndexOf("\\"));
+  return lastSlash >= 0 ? filePath.slice(0, lastSlash) : "";
+}
+function getFeatureBaseName(filePath) {
+  const fileName = filePath.split(/[/\\]/).pop() || "";
+  const match = fileName.match(/^([a-z0-9-]+)\.(reducer|selector|reducers|selectors|state)/i);
+  return match ? match[1] : null;
+}
+function extractFeatureFromName(name) {
+  let match = name.match(/^([a-z]+)Reducer$/i);
+  if (match) return match[1];
+  match = name.match(/^select([A-Z][a-z]+)Feature$/);
+  if (match) return match[1];
+  match = name.match(/^select([A-Z][a-z]+)State$/);
+  if (match) return match[1];
+  return null;
+}
+async function findReducerToSelectorConnections(storage) {
+  const connections = [];
+  const reducers = await storage.findEntities({
+    filters: { entityType: ["ngrx_reducer"] },
+    limit: 500
+  });
+  const selectors = await storage.findEntities({
+    filters: { entityType: ["ngrx_selector"] },
+    limit: 500
+  });
+  const featureSelectors = selectors.filter((s) => {
+    if (s.name.includes("Feature") || s.name.endsWith("State")) {
+      return true;
+    }
+    const meta = s.metadata;
+    if (meta?.["ngrxSelector"]?.featureName) {
+      return true;
+    }
+    return false;
+  });
+  for (const reducer of reducers) {
+    const reducerDir = getDirectory(reducer.filePath);
+    const reducerBaseName = getFeatureBaseName(reducer.filePath);
+    for (const selector of featureSelectors) {
+      const selectorDir = getDirectory(selector.filePath);
+      const selectorBaseName = getFeatureBaseName(selector.filePath);
+      let confidence = 0;
+      if (reducerDir === selectorDir) {
+        confidence += 0.5;
+      }
+      const reducerParent = getDirectory(reducerDir);
+      const selectorParent = getDirectory(selectorDir);
+      if (reducerParent === selectorParent && reducerParent !== "") {
+        confidence += 0.3;
+      }
+      if (reducerBaseName && selectorBaseName && reducerBaseName === selectorBaseName) {
+        confidence += 0.4;
+      }
+      const reducerFeature = extractFeatureFromName(reducer.name);
+      const selectorFeature = extractFeatureFromName(selector.name);
+      if (reducerFeature && selectorFeature && reducerFeature.toLowerCase() === selectorFeature.toLowerCase()) {
+        confidence += 0.3;
+      }
+      if (confidence >= 0.5) {
+        connections.push({
+          reducerId: reducer.id,
+          selectorId: selector.id,
+          confidence: Math.min(1, confidence)
+        });
+      }
+    }
+  }
+  return connections;
+}
+async function resolveNgRxTarget(storage, phantomId) {
+  const phantomEntity = await storage.getEntity(phantomId);
+  if (!phantomEntity) return null;
+  const name = phantomEntity.name;
+  const colonIndex = name.lastIndexOf(":");
+  const targetName = colonIndex >= 0 ? name.slice(colonIndex + 1) : name;
+  const entities = await storage.searchEntities({ namePattern: targetName });
+  for (const entity of entities) {
+    if (entity.name === targetName && entity.id !== phantomId) {
+      return entity.id;
+    }
+  }
+  return null;
+}
+async function findIncomingNgRxRelationships(storage, entityName) {
+  const types = Array.from(NGRX_RELATIONSHIP_TYPES);
+  return storage.findIncomingRelationshipsByName(entityName, types);
+}
+function isInvertedNgRxRelation(relType) {
+  return relType === "handles_action" /* HANDLES_ACTION */ || relType === "listens_to_action" /* LISTENS_TO_ACTION */;
+}
+
+// src/tracing/path-enrichment.ts
+function determineAction(node, position, totalLength) {
+  if (position === totalLength - 1) {
+    return "return";
+  }
+  if (node.controlFlow?.branches && node.controlFlow.branches.length > 0) {
+    return "condition";
+  }
+  if (node.controlFlow?.awaits && node.controlFlow.awaits.length > 0) {
+    return "await";
+  }
+  if (node.controlFlow?.loops && node.controlFlow.loops.length > 0) {
+    return "loop";
+  }
+  if (node.controlFlow?.exceptions && node.controlFlow.exceptions.length > 0) {
+    return "throw";
+  }
+  return "call";
+}
+function calculateConfidence(raw) {
+  let confidence = 1;
+  confidence -= raw.entityIds.length * 0.02;
+  confidence -= raw.conditionCount * 0.1;
+  confidence -= raw.weight * 0.05;
+  return Math.max(0.1, Math.min(1, confidence));
+}
+function generatePathSummary(steps) {
+  if (steps.length === 0) return "Empty path";
+  if (steps.length === 1) {
+    return `Direct call to ${steps[0].entity}`;
+  }
+  const first = steps[0];
+  const last = steps[steps.length - 1];
+  const conditions = steps.filter((s) => s.action === "condition").length;
+  const awaits = steps.filter((s) => s.awaits).length;
+  let summary = `${first.entity} \u2192 ${last.entity} (${steps.length} steps)`;
+  if (conditions > 0) {
+    summary += `, ${conditions} condition${conditions > 1 ? "s" : ""}`;
+  }
+  if (awaits > 0) {
+    summary += `, ${awaits} await${awaits > 1 ? "s" : ""}`;
+  }
+  return summary;
+}
+function generateWarnings(raw, graph) {
+  const warnings = [];
+  if (raw.entityIds.length > 10) {
+    warnings.push("Long call chain - may indicate design issues");
+  }
+  if (raw.conditionCount > 5) {
+    warnings.push("Many conditional branches - path may be rarely executed");
+  }
+  let asyncCount = 0;
+  for (const id of raw.entityIds) {
+    const node = graph.nodes.get(id);
+    if (node?.controlFlow?.awaits && node.controlFlow.awaits.length > 0) {
+      asyncCount++;
+    }
+  }
+  if (asyncCount > 3) {
+    warnings.push("Multiple async boundaries - consider timing issues");
+  }
+  return warnings;
+}
+function getConfidenceLevel(score) {
+  if (score >= 0.7) return "high";
+  if (score >= 0.4) return "medium";
+  return "low";
+}
+function enrichPath(raw, graph, pathIndex) {
+  const steps = [];
+  for (let j = 0; j < raw.entityIds.length; j++) {
+    const nodeId = raw.entityIds[j];
+    const node = graph.nodes.get(nodeId);
+    if (!node) continue;
+    const step = {
+      order: j + 1,
+      entity: node.name,
+      entityId: nodeId,
+      file: node.file,
+      line: node.line,
+      action: determineAction(node, j, raw.entityIds.length)
+    };
+    if (node.controlFlow?.branches && node.controlFlow.branches.length > 0) {
+      step.condition = node.controlFlow.branches[0]?.condition;
+      step.branches = {};
+      for (const branch of node.controlFlow.branches) {
+        step.branches[branch.condition] = branch.target || "continue";
+      }
+    }
+    if (node.controlFlow?.awaits && node.controlFlow.awaits.length > 0) {
+      step.awaits = true;
+      step.awaitTarget = node.controlFlow.awaits[0]?.target;
+    }
+    steps.push(step);
+  }
+  const confidence = calculateConfidence(raw);
+  return {
+    id: `path-${pathIndex + 1}`,
+    confidence,
+    steps,
+    summary: generatePathSummary(steps),
+    warnings: generateWarnings(raw, graph)
+  };
+}
+function enrichPaths(rawPaths, graph) {
+  return rawPaths.map((raw, i) => enrichPath(raw, graph, i));
+}
+
+// src/tracing/path-builder.ts
+var DEFAULT_MAX_DEPTH2 = 15;
+var DEFAULT_MAX_PATHS = 10;
+var CONDITION_WEIGHT = 0.3;
+var CALL_WEIGHT = 0.1;
+var ASYNC_WEIGHT = 0.2;
+var PathBuilder = class {
+  storage;
+  adjacencyCache = /* @__PURE__ */ new Map();
+  nodeCache = /* @__PURE__ */ new Map();
+  constructor(storage) {
+    this.storage = storage;
+  }
+  // ===========================================================================
+  // 3. ADJACENCY GRAPH BUILDING
+  // ===========================================================================
+  /**
+   * Build adjacency graph from storage for efficient traversal.
+   * Uses batch loading and caching for performance.
+   */
+  async buildAdjacencyGraph(startIds, maxDepth = DEFAULT_MAX_DEPTH2) {
+    const cacheKey = `${startIds.sort().join(",")}:${maxDepth}`;
+    const cached = this.adjacencyCache.get(cacheKey);
+    if (cached) return cached;
+    const nodes = /* @__PURE__ */ new Map();
+    const forward = /* @__PURE__ */ new Map();
+    const backward = /* @__PURE__ */ new Map();
+    const weights = /* @__PURE__ */ new Map();
+    const visited = /* @__PURE__ */ new Set();
+    const queue = startIds.map((id) => ({
+      id,
+      depth: 0
+    }));
+    while (queue.length > 0) {
+      const batch = queue.splice(0, Math.min(16, queue.length));
+      const validBatch = batch.filter(({ id, depth }) => !visited.has(id) && depth <= maxDepth);
+      if (validBatch.length === 0) continue;
+      for (const { id } of validBatch) visited.add(id);
+      const batchIds = validBatch.map(({ id }) => id);
+      const entityMap = await this.storage.getEntitiesBatch(batchIds);
+      for (const { id, depth } of validBatch) {
+        const entity = entityMap.get(id);
+        if (!entity) continue;
+        const node = this.entityToNode(entity);
+        nodes.set(id, node);
+        const outRels = await this.storage.getRelationshipsForEntity(id);
+        const outgoing = [];
+        const incoming = [];
+        for (const rel of outRels) {
+          const weight = this.calculateEdgeWeight(rel, entity);
+          const edgeKey = `${rel.fromId}:${rel.toId}`;
+          weights.set(edgeKey, weight);
+          if (rel.fromId === id) {
+            let targetId = rel.toId;
+            if (NGRX_RELATIONSHIP_TYPES.has(rel.type)) {
+              const resolvedId = await resolveNgRxTarget(this.storage, rel.toId);
+              if (resolvedId) {
+                targetId = resolvedId;
+              }
+            }
+            outgoing.push(targetId);
+            if (depth < maxDepth && !visited.has(targetId)) {
+              queue.push({ id: targetId, depth: depth + 1 });
+            }
+          } else {
+            incoming.push(rel.fromId);
+            if (depth < maxDepth && !visited.has(rel.fromId)) {
+              queue.push({ id: rel.fromId, depth: depth + 1 });
+            }
+          }
+        }
+        const incomingNgRx = await findIncomingNgRxRelationships(this.storage, entity.name);
+        for (const rel of incomingNgRx) {
+          const isInvertedRelation = isInvertedNgRxRelation(rel.type);
+          if (isInvertedRelation) {
+            if (!outgoing.includes(rel.fromId)) {
+              outgoing.push(rel.fromId);
+              const weight = this.calculateEdgeWeight(rel, entity);
+              weights.set(`${id}:${rel.fromId}`, weight);
+              if (depth < maxDepth && !visited.has(rel.fromId)) {
+                queue.push({ id: rel.fromId, depth: depth + 1 });
+              }
+            }
+          } else {
+            if (!incoming.includes(rel.fromId)) {
+              incoming.push(rel.fromId);
+              const weight = this.calculateEdgeWeight(rel, entity);
+              weights.set(`${rel.fromId}:${id}`, weight);
+              if (depth < maxDepth && !visited.has(rel.fromId)) {
+                queue.push({ id: rel.fromId, depth: depth + 1 });
+              }
+            }
+          }
+        }
+        forward.set(id, outgoing);
+        backward.set(id, incoming);
+        node.outgoing = outgoing;
+        node.incoming = incoming;
+      }
+    }
+    const reducerSelectorConnections = await findReducerToSelectorConnections(this.storage);
+    const missingConnIds = /* @__PURE__ */ new Set();
+    for (const conn of reducerSelectorConnections) {
+      if (nodes.has(conn.reducerId) || nodes.has(conn.selectorId)) {
+        if (!nodes.has(conn.reducerId)) missingConnIds.add(conn.reducerId);
+        if (!nodes.has(conn.selectorId)) missingConnIds.add(conn.selectorId);
+      }
+    }
+    const missingEntities = missingConnIds.size > 0 ? await this.storage.getEntitiesBatch([...missingConnIds]) : /* @__PURE__ */ new Map();
+    for (const conn of reducerSelectorConnections) {
+      if (nodes.has(conn.reducerId) || nodes.has(conn.selectorId)) {
+        if (!nodes.has(conn.reducerId)) {
+          const reducerEntity = missingEntities.get(conn.reducerId);
+          if (reducerEntity) {
+            nodes.set(conn.reducerId, this.entityToNode(reducerEntity));
+            forward.set(conn.reducerId, []);
+            backward.set(conn.reducerId, []);
+          }
+        }
+        if (!nodes.has(conn.selectorId)) {
+          const selectorEntity = missingEntities.get(conn.selectorId);
+          if (selectorEntity) {
+            nodes.set(conn.selectorId, this.entityToNode(selectorEntity));
+            forward.set(conn.selectorId, []);
+            backward.set(conn.selectorId, []);
+          }
+        }
+        const reducerOutgoing = forward.get(conn.reducerId) || [];
+        if (!reducerOutgoing.includes(conn.selectorId)) {
+          reducerOutgoing.push(conn.selectorId);
+          forward.set(conn.reducerId, reducerOutgoing);
+        }
+        const selectorIncoming = backward.get(conn.selectorId) || [];
+        if (!selectorIncoming.includes(conn.reducerId)) {
+          selectorIncoming.push(conn.reducerId);
+          backward.set(conn.selectorId, selectorIncoming);
+        }
+        const edgeKey = `${conn.reducerId}:${conn.selectorId}`;
+        weights.set(edgeKey, CALL_WEIGHT * (2 - conn.confidence));
+        const reducerNode = nodes.get(conn.reducerId);
+        const selectorNode = nodes.get(conn.selectorId);
+        if (reducerNode && !reducerNode.outgoing.includes(conn.selectorId)) {
+          reducerNode.outgoing.push(conn.selectorId);
+        }
+        if (selectorNode && !selectorNode.incoming.includes(conn.reducerId)) {
+          selectorNode.incoming.push(conn.reducerId);
+        }
+      }
+    }
+    const graph = { nodes, forward, backward, weights };
+    if (nodes.size < 1e4) {
+      this.adjacencyCache.set(cacheKey, graph);
+    }
+    return graph;
+  }
+  /**
+   * Convert Entity to GraphNode with control flow info
+   */
+  entityToNode(entity) {
+    const cached = this.nodeCache.get(entity.id);
+    if (cached) return cached;
+    const node = {
+      id: entity.id,
+      name: entity.name,
+      type: entity.type,
+      file: entity.filePath,
+      line: entity.location.start.line,
+      outgoing: [],
+      incoming: []
+    };
+    const meta = entity.metadata;
+    if (meta["controlFlow"]) {
+      node.controlFlow = {
+        branches: meta["controlFlow"].branches,
+        loops: meta["controlFlow"].loops,
+        awaits: meta["controlFlow"].awaits,
+        exceptions: meta["controlFlow"].exceptions
+      };
+    }
+    if (meta["calls"]) {
+      node.calls = meta["calls"];
+    }
+    if (meta["complexity"]) {
+      node.complexity = meta["complexity"];
+    }
+    this.nodeCache.set(entity.id, node);
+    return node;
+  }
+  /**
+   * Calculate edge weight based on relationship type and conditions
+   */
+  calculateEdgeWeight(rel, _fromEntity) {
+    let weight = CALL_WEIGHT;
+    if (rel.metadata?.["conditional"]) {
+      weight += CONDITION_WEIGHT;
+    }
+    if (rel.metadata?.["isAwait"] || rel.metadata?.["isAsync"]) {
+      weight += ASYNC_WEIGHT;
+    }
+    if (rel.weight) {
+      weight *= rel.weight;
+    }
+    return weight;
+  }
+  // ===========================================================================
+  // 4. FORWARD PATH FINDING (BFS - Shortest Paths)
+  // ===========================================================================
+  /**
+   * Find all paths from source to target using BFS.
+   * Returns paths sorted by weight (shortest/simplest first).
+   *
+   * Optimized with:
+   * - Loop unrolling for neighbor iteration
+   * - Early termination when enough paths found
+   * - Priority queue simulation via sorted insertion
+   */
+  async findPathsForward(sourceId, targetId, options = {}) {
+    const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH2;
+    const maxPaths = options.maxPaths ?? DEFAULT_MAX_PATHS;
+    const graph = await this.buildAdjacencyGraph([sourceId], maxDepth);
+    if (!graph.nodes.has(sourceId)) {
+      return [];
+    }
+    const paths = [];
+    const queue = [
+      {
+        path: [sourceId],
+        relationships: [],
+        weight: 0,
+        conditionCount: 0
+      }
+    ];
+    const visited = /* @__PURE__ */ new Map();
+    visited.set(sourceId, 0);
+    while (queue.length > 0 && paths.length < maxPaths) {
+      const current = queue.shift();
+      const currentNode = current.path[current.path.length - 1];
+      if (currentNode === targetId) {
+        paths.push({
+          entityIds: current.path,
+          relationships: current.relationships,
+          weight: current.weight,
+          conditionCount: current.conditionCount
+        });
+        continue;
+      }
+      if (current.path.length >= maxDepth) continue;
+      const neighbors = graph.forward.get(currentNode) || [];
+      const len4 = neighbors.length - neighbors.length % 4;
+      for (let i = 0; i < len4; i += 4) {
+        this.processNeighbor(neighbors[i], current, graph, visited, queue, options);
+        this.processNeighbor(neighbors[i + 1], current, graph, visited, queue, options);
+        this.processNeighbor(neighbors[i + 2], current, graph, visited, queue, options);
+        this.processNeighbor(neighbors[i + 3], current, graph, visited, queue, options);
+      }
+      for (let i = len4; i < neighbors.length; i++) {
+        this.processNeighbor(neighbors[i], current, graph, visited, queue, options);
+      }
+      queue.sort((a, b) => a.weight - b.weight);
+    }
+    return paths.sort((a, b) => a.weight - b.weight);
+  }
+  /**
+   * Process a single neighbor in BFS
+   */
+  processNeighbor(neighborId, current, graph, visited, queue, options) {
+    if (current.path.includes(neighborId)) return;
+    const currentNode = current.path[current.path.length - 1];
+    const edgeKey = `${currentNode}:${neighborId}`;
+    const edgeWeight = graph.weights.get(edgeKey) ?? CALL_WEIGHT;
+    const newWeight = current.weight + edgeWeight;
+    const bestWeight = visited.get(neighborId);
+    if (bestWeight !== void 0 && bestWeight <= newWeight) return;
+    if (options.weightThreshold && newWeight > options.weightThreshold) return;
+    visited.set(neighborId, newWeight);
+    const node = graph.nodes.get(neighborId);
+    const isConditional = node?.controlFlow?.branches && node.controlFlow.branches.length > 0;
+    queue.push({
+      path: [...current.path, neighborId],
+      relationships: [...current.relationships, edgeKey],
+      weight: newWeight,
+      conditionCount: current.conditionCount + (isConditional ? 1 : 0)
+    });
+  }
+  // ===========================================================================
+  // 5. BACKWARD PATH FINDING (DFS - All Callers)
+  // ===========================================================================
+  /**
+   * Find all paths leading to target using DFS (backwards traversal).
+   * Used for "why doesn't X get called?" analysis.
+   */
+  async findPathsBackward(targetId, options = {}) {
+    const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH2;
+    const maxPaths = options.maxPaths ?? DEFAULT_MAX_PATHS;
+    const graph = await this.buildAdjacencyGraph([targetId], maxDepth);
+    if (!graph.nodes.has(targetId)) {
+      return [];
+    }
+    const paths = [];
+    const currentPath = [];
+    const currentRels = [];
+    const dfs = (nodeId, depth, weight, conditionCount) => {
+      if (depth > maxDepth || paths.length >= maxPaths) return;
+      currentPath.push(nodeId);
+      const callers = graph.backward.get(nodeId) || [];
+      if (callers.length === 0 && currentPath.length > 1) {
+        paths.push({
+          entityIds: [...currentPath].reverse(),
+          relationships: [...currentRels].reverse(),
+          weight,
+          conditionCount
+        });
+      } else {
+        const state = { depth, weight, conditionCount };
+        const ctx = { currentPath, currentRels, graph, dfs };
+        const len4 = callers.length - callers.length % 4;
+        for (let i = 0; i < len4; i += 4) {
+          this.processCallerDFS(callers[i], nodeId, state, ctx);
+          this.processCallerDFS(callers[i + 1], nodeId, state, ctx);
+          this.processCallerDFS(callers[i + 2], nodeId, state, ctx);
+          this.processCallerDFS(callers[i + 3], nodeId, state, ctx);
+        }
+        for (let i = len4; i < callers.length; i++) {
+          this.processCallerDFS(callers[i], nodeId, state, ctx);
+        }
+      }
+      currentPath.pop();
+    };
+    dfs(targetId, 0, 0, 0);
+    return paths.sort((a, b) => a.weight - b.weight);
+  }
+  /**
+   * Process a single caller in DFS
+   */
+  processCallerDFS(callerId, currentId, state, ctx) {
+    if (ctx.currentPath.includes(callerId)) return;
+    const edgeKey = `${callerId}:${currentId}`;
+    const edgeWeight = ctx.graph.weights.get(edgeKey) ?? CALL_WEIGHT;
+    const newWeight = state.weight + edgeWeight;
+    const node = ctx.graph.nodes.get(callerId);
+    const isConditional = node?.controlFlow?.branches && node.controlFlow.branches.length > 0;
+    ctx.currentRels.push(edgeKey);
+    ctx.dfs(callerId, state.depth + 1, newWeight, state.conditionCount + (isConditional ? 1 : 0));
+    ctx.currentRels.pop();
+  }
+  // ===========================================================================
+  // 6. PATH ENRICHMENT (Delegated to extracted module)
+  // ===========================================================================
+  /**
+   * Convert raw paths to enriched TracePaths with full information.
+   * Delegates to the extracted path-enrichment module.
+   */
+  async enrichPaths(rawPaths, graph) {
+    return enrichPaths(rawPaths, graph);
+  }
+  // ===========================================================================
+  // 7. UTILITY METHODS
+  // ===========================================================================
+  /**
+   * Clear caches (call after graph changes)
+   */
+  clearCache() {
+    this.adjacencyCache.clear();
+    this.nodeCache.clear();
+  }
+  /**
+   * Get call probability based on conditions
+   */
+  getCallProbability(node) {
+    if (!node.controlFlow?.branches || node.controlFlow.branches.length === 0) {
+      return "always";
+    }
+    const hasGuard = node.controlFlow.branches.some((b) => b.target === "return" || b.target === "throw");
+    if (hasGuard) {
+      return "rare";
+    }
+    return "conditional";
+  }
+  /**
+   * Get confidence level from numeric score
+   */
+  getConfidenceLevel(score) {
+    return getConfidenceLevel(score);
+  }
+  /**
+   * Find entity by name using semantic search
+   * Decomposed query for 512-token models
+   *
+   * @param name - Entity name to search for
+   * @param type - Optional entity type filter
+   * @param filePath - Optional file path filter (partial match supported)
+   */
+  async findEntityByName(name, type, filePath) {
+    const entities = await this.storage.searchEntities({
+      namePattern: name,
+      types: type ? [type] : void 0,
+      filePath,
+      // Pass to SQL for efficient filtering
+      limit: filePath ? 1e3 : 100
+      // Higher limit when filtering by file
+    });
+    if (entities.length > 0) {
+      if (filePath) {
+        const normalizedFilter = filePath.replace(/\\/g, "/").toLowerCase();
+        const fileMatches = entities.filter((e) => {
+          const entityPath = (e.filePath || "").replace(/\\/g, "/").toLowerCase();
+          return entityPath.includes(normalizedFilter) || entityPath.endsWith(normalizedFilter);
+        });
+        if (fileMatches.length > 0) {
+          const exact2 = fileMatches.find((e) => e.name === name || e.name.endsWith(`.${name}`));
+          return exact2 || fileMatches[0];
+        }
+      }
+      const exact = entities.find((e) => e.name === name || e.name.endsWith(`.${name}`));
+      return exact || entities[0];
+    }
+    return null;
+  }
+  /**
+   * Get all callers of an entity
+   */
+  async getCallers(entityId) {
+    const rels = await this.storage.getRelationshipsForEntity(entityId, "calls" /* CALLS */);
+    const callerIds = rels.filter((rel) => rel.toId === entityId).map((rel) => rel.fromId);
+    if (callerIds.length === 0) return [];
+    const entityMap = await this.storage.getEntitiesBatch(callerIds);
+    const callers = [];
+    for (const id of callerIds) {
+      const caller = entityMap.get(id);
+      if (caller) {
+        const node = this.entityToNode(caller);
+        callers.push({
+          entity: caller,
+          probability: this.getCallProbability(node)
+        });
+      }
+    }
+    return callers;
+  }
+  /**
+   * Get all callees of an entity
+   */
+  async getCallees(entityId) {
+    const rels = await this.storage.getRelationshipsForEntity(entityId, "calls" /* CALLS */);
+    const calleeIds = rels.filter((rel) => rel.fromId === entityId).map((rel) => rel.toId);
+    if (calleeIds.length === 0) return [];
+    const entityMap = await this.storage.getEntitiesBatch(calleeIds);
+    return calleeIds.map((id) => entityMap.get(id)).filter((e) => e != null);
+  }
+};
+
+// src/tracing/trace-engine.ts
+init_logging();
+var DEFAULT_MAX_DEPTH3 = 15;
+var DEFAULT_MAX_PATHS2 = 5;
+var REAL_CODE_TYPES = /* @__PURE__ */ new Set(["method", "function", "async_function", "class", "interface", "property"]);
+function isRealEntity(entity) {
+  if (entity.id.startsWith("external:")) return false;
+  if (entity.filePath?.includes("external://")) return false;
+  if (entity.type === "import") return false;
+  return true;
+}
+var TraceEngine = class {
+  storage;
+  semanticSearch;
+  pathBuilder;
+  graphologyBuilder;
+  useOptimized;
+  // Cache for resolveEntity results (cleared on clearCache())
+  resolveEntityCache = /* @__PURE__ */ new Map();
+  constructor(storage, semanticSearch, useOptimized = true) {
+    this.storage = storage;
+    this.semanticSearch = semanticSearch;
+    this.pathBuilder = new PathBuilder(storage);
+    this.graphologyBuilder = new GraphologyPathBuilder(storage);
+    this.useOptimized = useOptimized;
+  }
+  /**
+   * Enable or disable optimized graphology-based tracing
+   */
+  setOptimizedMode(enabled) {
+    this.useOptimized = enabled;
+  }
+  /**
+   * Check if optimized mode is enabled
+   */
+  isOptimizedMode() {
+    return this.useOptimized;
+  }
+  /**
+   * Get graph statistics (only available in optimized mode)
+   */
+  async getGraphStats() {
+    if (!this.graphologyBuilder.isLoaded()) {
+      await this.graphologyBuilder.loadGraph();
+    }
+    return this.graphologyBuilder.getStats();
+  }
+  // ===========================================================================
+  // 3. TRACE FLOW (A → B)
+  // ===========================================================================
+  /**
+   * Trace execution flow from point A to point B.
+   * Uses optimized graphology-based traversal by default.
+   */
+  async traceFlow(params) {
+    const maxDepth = params.maxDepth ?? DEFAULT_MAX_DEPTH3;
+    if (this.useOptimized) {
+      return this.traceFlowOptimized(params, maxDepth);
+    }
+    return this.traceFlowLegacy(params, maxDepth);
+  }
+  /**
+   * Optimized trace flow using graphology (O(V+E) instead of O(2^n))
+   */
+  async traceFlowOptimized(params, maxDepth) {
+    const startTime = performance.now();
+    const stats = await this.graphologyBuilder.loadGraph();
+    log.i("TRACEENGINE", "graph_loaded", {
+      nodes: stats.nodes,
+      edges: stats.edges,
+      timeMs: +stats.loadTimeMs.toFixed(0)
+    });
+    const sourceEntity = await this.resolveEntity(params.from);
+    const targetEntity = await this.resolveEntity(params.to);
+    if (!sourceEntity) {
+      throw new Error(`Could not find source entity: ${params.from}`);
+    }
+    if (!targetEntity) {
+      throw new Error(`Could not find target entity: ${params.to}`);
+    }
+    log.d("TRACEENGINE", "resolved", {
+      from: params.from,
+      srcId: sourceEntity.id,
+      srcName: sourceEntity.name,
+      to: params.to,
+      tgtId: targetEntity.id,
+      tgtName: targetEntity.name
+    });
+    const linearTrace = await this.graphologyBuilder.traceLinearFlow(sourceEntity.id, targetEntity.id, maxDepth);
+    const paths = [];
+    if (linearTrace.found) {
+      paths.push(this.linearTraceToTracePath(linearTrace));
+    }
+    if (params.trackConditions && linearTrace.found) {
+      const additionalPaths = await this.graphologyBuilder.findPaths(
+        sourceEntity.id,
+        targetEntity.id,
+        DEFAULT_MAX_PATHS2 - 1,
+        maxDepth
+      );
+      const enrichedPaths = this.graphologyBuilder.enrichPaths(additionalPaths);
+      for (const p of enrichedPaths) {
+        if (p.steps.length !== paths[0]?.steps.length) {
+          paths.push(p);
+        }
+      }
+    }
+    let statesSummary = { modified: [], read: [], critical: [] };
+    if (params.trackStates && paths.length > 0) {
+      statesSummary = await this.analyzeStatesInPaths(paths);
+    }
+    let conditionsSummary = { guards: 0, branches: 0, criticalConditions: [] };
+    if (params.trackConditions && paths.length > 0) {
+      conditionsSummary = this.analyzeConditionsInPaths(paths);
+    }
+    let mermaid;
+    if (params.format === "mermaid" && paths.length > 0) {
+      mermaid = this.generateMermaidDiagram(paths, sourceEntity.name, targetEntity.name);
+    }
+    await this.annotateApiContractBoundaries(paths);
+    const totalTime = performance.now() - startTime;
+    log.i("TRACEENGINE", "trace_done", { timeMs: +totalTime.toFixed(0), visited: linearTrace.nodesVisited });
+    return {
+      from: params.from,
+      to: params.to,
+      paths,
+      statesSummary,
+      conditionsSummary,
+      mermaid,
+      // Debug info for troubleshooting
+      _debug: {
+        sourceEntityId: sourceEntity.id,
+        sourceEntityName: sourceEntity.name,
+        targetEntityId: targetEntity.id,
+        targetEntityName: targetEntity.name,
+        graphStats: stats,
+        linearTraceSummary: linearTrace.summary,
+        nodesVisited: linearTrace.nodesVisited,
+        found: linearTrace.found,
+        timeMs: totalTime
+      }
+    };
+  }
+  /**
+   * Convert LinearTrace to TracePath format
+   */
+  linearTraceToTracePath(linear) {
+    return {
+      id: "path-1",
+      confidence: linear.found ? 0.9 : 0.1,
+      steps: linear.steps.map((s) => ({
+        order: s.order,
+        entity: s.entity,
+        entityId: s.entityId,
+        file: s.file,
+        line: s.line,
+        action: s.action,
+        condition: s.branches?.[0]?.condition,
+        branches: s.branches?.reduce(
+          (acc, b) => {
+            acc[b.condition] = b.target;
+            return acc;
+          },
+          {}
+        )
+      })),
+      summary: linear.summary,
+      warnings: []
+    };
+  }
+  /**
+   * Annotate trace path steps that cross API contract boundaries (Swagger/OpenAPI).
+   * Adds crossesApiContract and contractInfo to steps where entity has isApiContract metadata.
+   */
+  async annotateApiContractBoundaries(paths) {
+    const entityIds = /* @__PURE__ */ new Set();
+    for (const path of paths) {
+      for (const step of path.steps) {
+        if (step.entityId) entityIds.add(step.entityId);
+      }
+    }
+    if (entityIds.size === 0) return;
+    const entityBatch = await this.storage.getEntitiesBatch(Array.from(entityIds));
+    let annotated = 0;
+    for (const path of paths) {
+      for (const step of path.steps) {
+        if (!step.entityId) continue;
+        const entity = entityBatch.get(step.entityId);
+        if (entity?.metadata?.["isApiContract"]) {
+          const swaggerType = entity.metadata["swaggerType"];
+          step["crossesApiContract"] = true;
+          step["contractInfo"] = {
+            type: "swagger",
+            swaggerType,
+            endpoint: swaggerType === "endpoint" ? `${entity.metadata["httpMethod"] || ""} ${entity.metadata["path"] || ""}`.trim() : void 0,
+            schemaName: swaggerType === "schema" ? entity.name : void 0
+          };
+          annotated++;
+        }
+      }
+      if (annotated > 0 && path.warnings) {
+        path.warnings.push("Path crosses API contract boundary \u2014 changes may affect external consumers");
+      }
+    }
+  }
+  /**
+   * Legacy trace flow implementation (for fallback/comparison)
+   */
+  async traceFlowLegacy(params, maxDepth) {
+    const sourceEntity = await this.resolveEntity(params.from);
+    const targetEntity = await this.resolveEntity(params.to);
+    if (!sourceEntity) {
+      throw new Error(`Could not find source entity: ${params.from}`);
+    }
+    if (!targetEntity) {
+      throw new Error(`Could not find target entity: ${params.to}`);
+    }
+    const rawPaths = await this.pathBuilder.findPathsForward(sourceEntity.id, targetEntity.id, {
+      maxDepth,
+      maxPaths: DEFAULT_MAX_PATHS2
+    });
+    if (rawPaths.length === 0) {
+      return {
+        from: params.from,
+        to: params.to,
+        paths: [],
+        statesSummary: { modified: [], read: [], critical: [] },
+        conditionsSummary: { guards: 0, branches: 0, criticalConditions: [] }
+      };
+    }
+    const graph = await this.pathBuilder.buildAdjacencyGraph([sourceEntity.id, targetEntity.id], maxDepth);
+    const paths = await this.pathBuilder.enrichPaths(rawPaths, graph);
+    let statesSummary = { modified: [], read: [], critical: [] };
+    if (params.trackStates) {
+      statesSummary = await this.analyzeStatesInPaths(paths);
+    }
+    let conditionsSummary = { guards: 0, branches: 0, criticalConditions: [] };
+    if (params.trackConditions) {
+      conditionsSummary = this.analyzeConditionsInPaths(paths);
+    }
+    let mermaid;
+    if (params.format === "mermaid") {
+      mermaid = this.generateMermaidDiagram(paths, sourceEntity.name, targetEntity.name);
+    }
+    return {
+      from: params.from,
+      to: params.to,
+      paths,
+      statesSummary,
+      conditionsSummary,
+      mermaid
+    };
+  }
+  // ===========================================================================
+  // 4. TRACE BACKWARDS (Why not called?)
+  // ===========================================================================
+  /**
+   * Trace backwards from a target to find why it might not be called.
+   * Uses optimized graphology-based traversal by default.
+   */
+  async traceBackwards(params) {
+    const maxDepth = params.depth ?? DEFAULT_MAX_DEPTH3;
+    const targetEntity = await this.resolveEntity(params.target);
+    if (!targetEntity) {
+      throw new Error(`Could not find target entity: ${params.target}`);
+    }
+    if (this.useOptimized) {
+      const startTime = performance.now();
+      await this.graphologyBuilder.loadGraph();
+      const backwardsResult = await this.graphologyBuilder.traceBackwards(targetEntity.id, maxDepth);
+      const callers2 = backwardsResult.callers.map((c) => ({
+        name: c.name,
+        entityId: c.id,
+        file: "",
+        // Will be filled from entity lookup if needed
+        line: 0,
+        probability: c.probability
+      }));
+      const blockingConditions2 = callers2.filter((c) => c.probability === "conditional" || c.probability === "rare").map((c) => ({
+        condition: `Conditional call from ${c.name}`,
+        location: c.file ? `${c.file}:${c.line}` : c.name,
+        currentValue: "unknown",
+        recommendation: `Check conditions in ${c.name}`
+      }));
+      const callChains2 = backwardsResult.entryPoints.map((ep) => ({
+        chain: [ep.name, "...", targetEntity.name],
+        guards: [],
+        likelihood: "medium",
+        entryPoint: ep.name
+      }));
+      const totalTime = performance.now() - startTime;
+      log.i("TRACEENGINE", "back_trace_done", { timeMs: +totalTime.toFixed(0) });
+      return {
+        target: {
+          name: targetEntity.name,
+          entityId: targetEntity.id,
+          file: targetEntity.filePath,
+          signature: this.getEntitySignature(targetEntity)
+        },
+        callers: callers2,
+        blockingConditions: blockingConditions2,
+        statesDependencies: params.includeStates ? await this.findStateDependencies(targetEntity) : [],
+        callChains: callChains2,
+        diagnosis: this.generateDiagnosis(
+          params.question,
+          callers2,
+          blockingConditions2,
+          params.includeStates ? await this.findStateDependencies(targetEntity) : [],
+          callChains2
+        )
+      };
+    }
+    const callersWithProbability = await this.pathBuilder.getCallers(targetEntity.id);
+    const callers = await Promise.all(
+      callersWithProbability.map(async ({ entity, probability }) => {
+        const callerInfo = {
+          name: entity.name,
+          entityId: entity.id,
+          file: entity.filePath,
+          line: entity.location.start.line,
+          probability
+        };
+        const meta = entity.metadata;
+        if (meta["controlFlow"]?.branches) {
+          const branches = meta["controlFlow"].branches;
+          if (branches.length > 0) {
+            callerInfo.condition = branches[0]?.condition;
+          }
+        }
+        return callerInfo;
+      })
+    );
+    const blockingConditions = await this.findBlockingConditions(targetEntity, callers);
+    let statesDependencies = [];
+    if (params.includeStates) {
+      statesDependencies = await this.findStateDependencies(targetEntity);
+    }
+    const rawPaths = await this.pathBuilder.findPathsBackward(targetEntity.id, {
+      maxDepth,
+      maxPaths: DEFAULT_MAX_PATHS2
+    });
+    const callChains = rawPaths.map((raw) => {
+      const graph = this.pathBuilder["adjacencyCache"].values().next().value;
+      const guards = [];
+      for (const id of raw.entityIds) {
+        const node = graph?.nodes.get(id);
+        if (node?.controlFlow?.branches) {
+          for (const branch of node.controlFlow.branches) {
+            if (branch.target === "return" || branch.target === "throw") {
+              guards.push(`${node.name}: ${branch.condition}`);
+            }
+          }
+        }
+      }
+      let entryPoint;
+      if (graph) {
+        const firstId = raw.entityIds[0];
+        const firstNode = graph.nodes.get(firstId);
+        if (firstNode && (!graph.backward.get(firstId) || graph.backward.get(firstId).length === 0)) {
+          entryPoint = firstNode.name;
+        }
+      }
+      return {
+        chain: raw.entityIds.map((id) => {
+          const node = graph?.nodes.get(id);
+          return node?.name || id;
+        }),
+        guards,
+        likelihood: this.pathBuilder.getConfidenceLevel(1 - raw.weight),
+        entryPoint
+      };
+    });
+    const diagnosis = this.generateDiagnosis(
+      params.question,
+      callers,
+      blockingConditions,
+      statesDependencies,
+      callChains
+    );
+    return {
+      target: {
+        name: targetEntity.name,
+        entityId: targetEntity.id,
+        file: targetEntity.filePath,
+        signature: this.getEntitySignature(targetEntity)
+      },
+      callers,
+      blockingConditions,
+      statesDependencies,
+      callChains,
+      diagnosis
+    };
+  }
+  // ===========================================================================
+  // 5. ENTITY RESOLUTION
+  // ===========================================================================
+  /**
+   * Resolve entity by name or semantic search query.
+   * Uses decomposed queries for 512-token efficiency.
+   *
+   * Supports file-qualified format: "filePath:entityName"
+   * Examples:
+   *   - "main" - finds first entity named "main"
+   *   - "src/index.ts:main" - finds "main" in src/index.ts
+   *   - "index.ts:main" - finds "main" in any file ending with index.ts
+   */
+  async resolveEntity(nameOrQuery) {
+    const cached = this.resolveEntityCache.get(nameOrQuery);
+    if (cached !== void 0) return cached;
+    const result = await this.resolveEntityUncached(nameOrQuery);
+    this.resolveEntityCache.set(nameOrQuery, result);
+    return result;
+  }
+  async resolveEntityUncached(nameOrQuery) {
+    const fileQualifiedMatch = nameOrQuery.match(
+      /^(.+?\.(?:ts|js|tsx|jsx|py|go|rs|java|kt|kts|c|cs|csx|cpp|h|hpp)):(.+)$/i
+    );
+    let name = nameOrQuery;
+    let filePath;
+    if (fileQualifiedMatch) {
+      filePath = fileQualifiedMatch[1];
+      name = fileQualifiedMatch[2];
+    }
+    const normalizedFilter = filePath ? filePath.replace(/\\/g, "/").toLowerCase() : void 0;
+    const filterByFile = (entities) => {
+      if (!normalizedFilter) return null;
+      for (const e of entities) {
+        const entityPath = (e.filePath || "").replace(/\\/g, "/").toLowerCase();
+        if (entityPath.includes(normalizedFilter) || entityPath.endsWith(normalizedFilter)) {
+          return e;
+        }
+      }
+      return null;
+    };
+    const exactMatch = await this.pathBuilder.findEntityByName(name, void 0, filePath);
+    if (exactMatch && isRealEntity(exactMatch)) {
+      return exactMatch;
+    }
+    const patternEntities = await this.storage.searchEntities({
+      namePattern: name
+    });
+    if (patternEntities.length > 0) {
+      if (normalizedFilter) {
+        const filtered = filterByFile(patternEntities);
+        if (filtered) return filtered;
+      }
+      return patternEntities[0];
+    }
+    if (!name.includes(".")) {
+      const suffixPattern = `.${name}`;
+      const allEntities = await this.storage.searchEntities({});
+      const suffixMatches = allEntities.filter((e) => e.name.endsWith(suffixPattern) && isRealEntity(e));
+      const prioritized = suffixMatches.sort((a, b) => {
+        const aReal = REAL_CODE_TYPES.has(a.type) ? 0 : 1;
+        const bReal = REAL_CODE_TYPES.has(b.type) ? 0 : 1;
+        return aReal - bReal;
+      });
+      if (prioritized.length === 1) {
+        return prioritized[0];
+      } else if (prioritized.length > 1 && normalizedFilter) {
+        const filtered = filterByFile(prioritized);
+        if (filtered) return filtered;
+      } else if (prioritized.length > 1) {
+        log.d("TRACEENGINE", "multiple_suffix_matches", {
+          name,
+          count: prioritized.length,
+          first: prioritized[0]?.name
+        });
+        return prioritized[0];
+      }
+    }
+    if (this.semanticSearch) {
+      try {
+        const results = await this.semanticSearch.search(name, {
+          limit: filePath ? 10 : 1,
+          minSimilarity: 0.6
+        });
+        if (results.length > 0) {
+          const candidateIds = results.map((r) => r.entityId);
+          const candidateMap = await this.storage.getEntitiesBatch(candidateIds);
+          if (normalizedFilter) {
+            for (const result of results) {
+              const entity = candidateMap.get(result.entityId);
+              if (entity) {
+                const entityPath = (entity.filePath || "").replace(/\\/g, "/").toLowerCase();
+                if (entityPath.includes(normalizedFilter) || entityPath.endsWith(normalizedFilter)) {
+                  return entity;
+                }
+              }
+            }
+          }
+          return candidateMap.get(results[0].entityId) || null;
+        }
+      } catch {
+      }
+    }
+    return null;
+  }
+  // ===========================================================================
+  // 6. STATE ANALYSIS
+  // ===========================================================================
+  /**
+   * Analyze state changes across all paths
+   */
+  async analyzeStatesInPaths(paths) {
+    const modified = /* @__PURE__ */ new Set();
+    const read = /* @__PURE__ */ new Set();
+    const critical = /* @__PURE__ */ new Set();
+    const allEntityIds = /* @__PURE__ */ new Set();
+    for (const path of paths) {
+      for (const step of path.steps) {
+        allEntityIds.add(step.entityId);
+      }
+    }
+    const entityMap = allEntityIds.size > 0 ? await this.storage.getEntitiesBatch([...allEntityIds]) : /* @__PURE__ */ new Map();
+    for (const path of paths) {
+      for (const step of path.steps) {
+        const entity = entityMap.get(step.entityId);
+        if (!entity?.metadata) continue;
+        const meta = entity.metadata;
+        if (Array.isArray(meta["stateModifications"])) {
+          for (const state of meta["stateModifications"]) {
+            modified.add(state);
+          }
+        }
+        if (Array.isArray(meta["stateReads"])) {
+          for (const state of meta["stateReads"]) {
+            read.add(state);
+          }
+        }
+        if (step.condition && Array.isArray(meta["stateReads"])) {
+          for (const state of meta["stateReads"]) {
+            critical.add(state);
+          }
+        }
+      }
+    }
+    return {
+      modified: Array.from(modified),
+      read: Array.from(read),
+      critical: Array.from(critical)
+    };
+  }
+  /**
+   * Find state dependencies for a target entity
+   */
+  async findStateDependencies(target) {
+    const dependencies = [];
+    const meta = target.metadata;
+    const stateReads = Array.isArray(meta["stateReads"]) ? meta["stateReads"] : [];
+    for (const state of stateReads) {
+      const modifiers = await this.findStateModifiers(state);
+      dependencies.push({
+        state,
+        modifiedBy: modifiers.map((e) => e.name),
+        stateType: this.inferStateType(state)
+      });
+    }
+    return dependencies;
+  }
+  /**
+   * Find entities that modify a given state
+   */
+  async findStateModifiers(stateName) {
+    const entities = await this.storage.searchEntities({
+      namePattern: stateName
+    });
+    return entities.filter((e) => {
+      const meta = e.metadata;
+      const mods = Array.isArray(meta["stateModifications"]) ? meta["stateModifications"] : [];
+      return mods.includes(stateName) || e.name.toLowerCase().includes("set");
+    });
+  }
+  /**
+   * Infer state type from context
+   */
+  inferStateType(state) {
+    if (state.startsWith("is") || state.startsWith("has") || state.startsWith("should")) {
+      return "boolean";
+    }
+    if (state.endsWith("Count") || state.endsWith("Index") || state.endsWith("Id")) {
+      return "number";
+    }
+    if (state.endsWith("List") || state.endsWith("Array") || state.endsWith("s")) {
+      return "array";
+    }
+    return "unknown";
+  }
+  // ===========================================================================
+  // 7. CONDITION ANALYSIS
+  // ===========================================================================
+  /**
+   * Analyze conditions across all paths
+   */
+  analyzeConditionsInPaths(paths) {
+    let guards = 0;
+    let branches = 0;
+    const criticalConditions = /* @__PURE__ */ new Set();
+    for (const path of paths) {
+      for (const step of path.steps) {
+        if (step.action === "condition") {
+          branches++;
+          if (step.branches) {
+            const outcomes = Object.values(step.branches);
+            if (outcomes.some((o) => o === "return" || o === "throw")) {
+              guards++;
+            }
+          }
+          if (step.condition) {
+            criticalConditions.add(step.condition);
+          }
+        }
+        if (step.action === "guard") {
+          guards++;
+        }
+      }
+    }
+    return {
+      guards,
+      branches,
+      criticalConditions: Array.from(criticalConditions)
+    };
+  }
+  /**
+   * Find conditions that might block execution
+   */
+  async findBlockingConditions(target, callers) {
+    const blocking = [];
+    for (const caller of callers) {
+      if (caller.condition && caller.probability === "conditional") {
+        blocking.push({
+          condition: caller.condition,
+          location: `${caller.file}:${caller.line}`,
+          currentValue: "unknown (static analysis)",
+          recommendation: `Check if condition '${caller.condition}' evaluates to true`
+        });
+      }
+    }
+    const targetMeta = target.metadata;
+    if (Array.isArray(targetMeta["preconditions"])) {
+      for (const pre of targetMeta["preconditions"]) {
+        blocking.push({
+          condition: pre,
+          location: `${target.filePath}:${target.location.start.line}`,
+          currentValue: "required",
+          recommendation: `Ensure precondition '${pre}' is satisfied`
+        });
+      }
+    }
+    return blocking;
+  }
+  // ===========================================================================
+  // 8. DIAGNOSIS GENERATION
+  // ===========================================================================
+  /**
+   * Generate diagnosis based on analysis results
+   */
+  generateDiagnosis(question, callers, blocking, states, chains) {
+    const possibleReasons = [];
+    const suggestedDebugPoints = [];
+    let mostLikely;
+    switch (question) {
+      case "why_not_called":
+        if (callers.length === 0) {
+          possibleReasons.push("No callers found - method may be unused");
+          possibleReasons.push("Target may be behind an API contract boundary \u2014 check swagger consumers");
+          mostLikely = "Dead code - no call sites exist (or called via API contract)";
+        } else {
+          const conditionalCallers = callers.filter((c) => c.probability !== "always");
+          if (conditionalCallers.length === callers.length) {
+            possibleReasons.push("All call sites are conditional");
+            mostLikely = "Conditions not met at runtime";
+            for (const caller of conditionalCallers) {
+              suggestedDebugPoints.push(`${caller.file}:${caller.line} - ${caller.condition || "check condition"}`);
+            }
+          }
+          if (blocking.length > 0) {
+            possibleReasons.push(`${blocking.length} blocking condition(s) detected`);
+            for (const b of blocking) {
+              suggestedDebugPoints.push(`${b.location} - ${b.condition}`);
+            }
+          }
+          if (states.length > 0) {
+            possibleReasons.push(`Depends on ${states.length} state(s)`);
+            for (const s of states) {
+              if (s.modifiedBy.length === 0) {
+                possibleReasons.push(`State '${s.state}' has no known modifiers`);
+              }
+            }
+          }
+        }
+        break;
+      case "what_affects":
+        if (states.length > 0) {
+          possibleReasons.push(`Direct state dependencies: ${states.map((s) => s.state).join(", ")}`);
+        }
+        if (blocking.length > 0) {
+          possibleReasons.push(`Guard conditions: ${blocking.map((b) => b.condition).join(", ")}`);
+        }
+        if (chains.length > 0) {
+          const entryPoints = chains.filter((c) => c.entryPoint).map((c) => c.entryPoint);
+          if (entryPoints.length > 0) {
+            possibleReasons.push(`Entry points: ${entryPoints.join(", ")}`);
+          }
+        }
+        break;
+      case "dependencies":
+        for (const chain of chains) {
+          possibleReasons.push(`Call chain: ${chain.chain.join(" \u2192 ")}`);
+          if (chain.guards.length > 0) {
+            possibleReasons.push(`  Guards: ${chain.guards.join("; ")}`);
+          }
+        }
+        break;
+    }
+    if (suggestedDebugPoints.length === 0 && callers.length > 0) {
+      suggestedDebugPoints.push(`${callers[0].file}:${callers[0].line} - First caller`);
+    }
+    return {
+      possibleReasons,
+      suggestedDebugPoints,
+      mostLikely
+    };
+  }
+  // ===========================================================================
+  // 9. OUTPUT GENERATION
+  // ===========================================================================
+  /**
+   * Generate Mermaid sequence diagram
+   */
+  generateMermaidDiagram(paths, sourceName, targetName) {
+    const lines = ["sequenceDiagram"];
+    lines.push(`  participant S as ${this.sanitizeMermaidId(sourceName)}`);
+    lines.push(`  participant T as ${this.sanitizeMermaidId(targetName)}`);
+    const participants = /* @__PURE__ */ new Set();
+    for (const path of paths) {
+      for (const step of path.steps) {
+        if (step.entity !== sourceName && step.entity !== targetName) {
+          participants.add(step.entity);
+        }
+      }
+    }
+    let idx = 1;
+    const participantMap = /* @__PURE__ */ new Map();
+    participantMap.set(sourceName, "S");
+    participantMap.set(targetName, "T");
+    for (const p of participants) {
+      const id = `P${idx++}`;
+      participantMap.set(p, id);
+      lines.push(`  participant ${id} as ${this.sanitizeMermaidId(p)}`);
+    }
+    for (let i = 0; i < Math.min(paths.length, 3); i++) {
+      const path = paths[i];
+      lines.push(`  Note over S,T: Path ${i + 1} (confidence: ${Math.round(path.confidence * 100)}%)`);
+      for (let j = 0; j < path.steps.length - 1; j++) {
+        const from = path.steps[j];
+        const to = path.steps[j + 1];
+        const fromId = participantMap.get(from.entity) || "S";
+        const toId = participantMap.get(to.entity) || "T";
+        let arrow = "->>";
+        if (from.awaits) arrow = "-->>";
+        const label = from.condition ? `${from.action}[${from.condition}]` : from.action;
+        lines.push(`  ${fromId}${arrow}${toId}: ${label}`);
+      }
+    }
+    return lines.join("\n");
+  }
+  /**
+   * Sanitize string for Mermaid ID
+   */
+  sanitizeMermaidId(name) {
+    return name.replace(/[^a-zA-Z0-9_]/g, "_").substring(0, 30);
+  }
+  /**
+   * Get entity signature for display
+   */
+  getEntitySignature(entity) {
+    const params = entity.metadata.parameters || [];
+    const paramStr = params.map((p) => `${p.name}: ${p.type || "any"}`).join(", ");
+    const returnType = entity.metadata.returnType || "void";
+    return `${entity.name}(${paramStr}): ${returnType}`;
+  }
+  // ===========================================================================
+  // 10. CACHE MANAGEMENT
+  // ===========================================================================
+  /**
+   * Clear all caches
+   */
+  clearCache() {
+    this.pathBuilder.clearCache();
+    this.graphologyBuilder.clear();
+    this.resolveEntityCache.clear();
+  }
+};
+
+// src/tracing/ngrx-trace-engine.ts
+var NgRxTraceEngine = class {
+  storage;
+  constructor(storage) {
+    this.storage = storage;
+  }
+  /**
+   * Trace NgRx flow from source to target
+   */
+  async traceNgRxFlow(params) {
+    const maxDepth = params.maxDepth ?? 20;
+    const sourceEntity = await this.resolveNgRxEntity(params.from);
+    if (!sourceEntity) {
+      throw new Error(`Could not find NgRx source entity: ${params.from}`);
+    }
+    const targetEntity = await this.resolveNgRxEntity(params.to);
+    if (!targetEntity) {
+      throw new Error(`Could not find NgRx target entity: ${params.to}`);
+    }
+    const paths = await this.findNgRxPaths(sourceEntity, targetEntity, maxDepth);
+    const actionFlow = this.analyzeActionFlow(paths);
+    let mermaid;
+    if (params.format === "mermaid") {
+      mermaid = this.generateMermaidDiagram(paths, sourceEntity.name, targetEntity.name);
+    }
+    return {
+      from: params.from,
+      to: params.to,
+      paths,
+      actionFlow,
+      mermaid
+    };
+  }
+  /**
+   * Find paths through NgRx relationships
+   */
+  async findNgRxPaths(source, target, maxDepth) {
+    const paths = [];
+    const visited = /* @__PURE__ */ new Set();
+    const queue = [
+      {
+        entityId: source.id,
+        path: [this.entityToStep(source, 1, "dispatch")],
+        actionChain: [],
+        depth: 0
+      }
+    ];
+    while (queue.length > 0 && paths.length < 5) {
+      const current = queue.shift();
+      if (current.depth > maxDepth) continue;
+      if (current.entityId === target.id) {
+        paths.push({
+          id: `ngrx-path-${paths.length + 1}`,
+          confidence: 1 - current.depth * 0.05,
+          // Confidence decreases with depth
+          steps: current.path,
+          summary: this.generatePathSummary(current.path),
+          actionChain: current.actionChain
+        });
+        continue;
+      }
+      const pathKey = `${current.entityId}:${current.depth}`;
+      if (visited.has(pathKey)) continue;
+      visited.add(pathKey);
+      const relationships = await this.getNgRxRelationships(current.entityId);
+      for (const rel of relationships) {
+        const nextEntityId = rel.fromId === current.entityId ? rel.toId : rel.fromId;
+        const nextEntity = await this.storage.getEntity(nextEntityId);
+        if (!nextEntity) continue;
+        const stepType = this.determineStepType(rel.type, nextEntity);
+        const nextStep = this.entityToStep(nextEntity, current.path.length + 1, stepType);
+        const newActionChain = [...current.actionChain];
+        const meta = rel.metadata;
+        if (meta?.["actionType"]) {
+          newActionChain.push(meta["actionType"]);
+        }
+        queue.push({
+          entityId: nextEntityId,
+          path: [...current.path, nextStep],
+          actionChain: newActionChain,
+          depth: current.depth + 1
+        });
+      }
+    }
+    return paths;
+  }
+  /**
+   * Get NgRx-specific relationships for an entity
+   */
+  async getNgRxRelationships(entityId) {
+    const allRels = await this.storage.getRelationshipsForEntity(entityId);
+    return allRels.filter(
+      (rel) => [
+        "dispatches_action" /* DISPATCHES_ACTION */,
+        "listens_to_action" /* LISTENS_TO_ACTION */,
+        "handles_action" /* HANDLES_ACTION */,
+        "selects_state" /* SELECTS_STATE */,
+        "modifies_state" /* MODIFIES_STATE */,
+        "depends_on" /* DEPENDS_ON */
+        // For selector composition
+      ].includes(rel.type)
+    );
+  }
+  /**
+   * Resolve NgRx entity by name pattern
+   */
+  async resolveNgRxEntity(namePattern) {
+    const entities = await this.storage.searchEntities({
+      namePattern
+    });
+    if (entities.length > 0) {
+      const ngrxEntity = entities.find((e) => {
+        const meta = e.metadata;
+        return meta?.["ngrxType"];
+      });
+      return ngrxEntity || entities[0];
+    }
+    const partialEntities = await this.storage.searchEntities({
+      namePattern: `*${namePattern}*`
+    });
+    if (partialEntities.length > 0) {
+      return partialEntities[0];
+    }
+    return null;
+  }
+  /**
+   * Convert entity to flow step
+   */
+  entityToStep(entity, order, type) {
+    const meta = entity.metadata;
+    return {
+      order,
+      type,
+      entityName: entity.name,
+      entityId: entity.id,
+      file: entity.filePath,
+      line: entity.location.start.line,
+      actionType: meta?.["actionType"] || meta?.["ngrxType"],
+      stateProperty: meta?.["statePath"],
+      description: this.generateStepDescription(type, entity.name, meta)
+    };
+  }
+  /**
+   * Determine step type from relationship type and entity
+   */
+  determineStepType(relType, entity) {
+    const meta = entity.metadata;
+    const ngrxType = meta?.["ngrxType"];
+    if (ngrxType === "effect") return "effect";
+    if (ngrxType === "reducer") return "reducer";
+    if (ngrxType === "selector") return "selector";
+    if (ngrxType === "action") return "dispatch";
+    switch (relType) {
+      case "dispatches_action" /* DISPATCHES_ACTION */:
+        return "dispatch";
+      case "listens_to_action" /* LISTENS_TO_ACTION */:
+        return "effect";
+      case "handles_action" /* HANDLES_ACTION */:
+        return "reducer";
+      case "modifies_state" /* MODIFIES_STATE */:
+        return "state";
+      case "selects_state" /* SELECTS_STATE */:
+        return "subscribe";
+      default:
+        return "dispatch";
+    }
+  }
+  /**
+   * Generate human-readable step description
+   */
+  generateStepDescription(type, entityName, meta) {
+    switch (type) {
+      case "dispatch":
+        return `Dispatches action: ${meta?.["actionType"] || entityName}`;
+      case "effect":
+        return `Effect ${entityName} handles action via ofType()`;
+      case "reducer":
+        return `Reducer ${entityName} processes action via on()`;
+      case "state":
+        return `State modified: ${meta?.["stateChanges"]?.join(", ") || "unknown"}`;
+      case "selector":
+        return `Selector ${entityName} reads state`;
+      case "subscribe":
+        return `Component subscribes to ${entityName}`;
+      default:
+        return entityName;
+    }
+  }
+  /**
+   * Generate path summary
+   */
+  generatePathSummary(steps) {
+    const parts = steps.map((s) => {
+      switch (s.type) {
+        case "dispatch":
+          return `dispatch(${s.entityName})`;
+        case "effect":
+          return `\u2192 Effect.${s.entityName}`;
+        case "reducer":
+          return `\u2192 Reducer.on()`;
+        case "state":
+          return `\u2192 state.${s.stateProperty || "?"}`;
+        case "selector":
+          return `\u2192 ${s.entityName}`;
+        case "subscribe":
+          return `\u2192 select()`;
+        default:
+          return `\u2192 ${s.entityName}`;
+      }
+    });
+    return parts.join(" ");
+  }
+  /**
+   * Analyze action flow from paths
+   */
+  analyzeActionFlow(paths) {
+    const dispatched = /* @__PURE__ */ new Set();
+    const handled = /* @__PURE__ */ new Set();
+    const stateChanges = /* @__PURE__ */ new Set();
+    for (const path of paths) {
+      for (const action of path.actionChain) {
+        dispatched.add(action);
+      }
+      for (const step of path.steps) {
+        if (step.type === "reducer" && step.actionType) {
+          handled.add(step.actionType);
+        }
+        if (step.type === "state" && step.stateProperty) {
+          stateChanges.add(step.stateProperty);
+        }
+      }
+    }
+    return {
+      dispatched: Array.from(dispatched),
+      handled: Array.from(handled),
+      stateChanges: Array.from(stateChanges)
+    };
+  }
+  /**
+   * Generate Mermaid sequence diagram
+   */
+  generateMermaidDiagram(paths, sourceName, targetName) {
+    const lines = ["sequenceDiagram"];
+    lines.push(`  participant C as Component`);
+    lines.push(`  participant A as Action`);
+    lines.push(`  participant E as Effect`);
+    lines.push(`  participant R as Reducer`);
+    lines.push(`  participant S as Store`);
+    lines.push(`  participant SEL as Selector`);
+    lines.push(`  Note over C,SEL: ${this.sanitize(sourceName)} \u2192 ${this.sanitize(targetName)}`);
+    for (let i = 0; i < Math.min(paths.length, 2); i++) {
+      const path = paths[i];
+      lines.push(`  Note over C,SEL: Path ${i + 1}`);
+      for (const step of path.steps) {
+        switch (step.type) {
+          case "dispatch":
+            lines.push(`  C->>A: dispatch(${this.sanitize(step.entityName)})`);
+            break;
+          case "effect":
+            lines.push(`  A->>E: ofType()`);
+            lines.push(`  E->>A: dispatch new action`);
+            break;
+          case "reducer":
+            lines.push(`  A->>R: on(action)`);
+            lines.push(`  R->>S: update state`);
+            break;
+          case "selector":
+            lines.push(`  S->>SEL: state change`);
+            break;
+          case "subscribe":
+            lines.push(`  SEL->>C: select()`);
+            break;
+        }
+      }
+    }
+    return lines.join("\n");
+  }
+  /**
+   * Sanitize string for Mermaid
+   */
+  sanitize(str) {
+    return str.replace(/[^a-zA-Z0-9_]/g, "_").substring(0, 20);
+  }
+};
+
+// src/tools/handlers/tracing-tool-handlers.ts
+var TraceFlowSchema = z.object({
+  from: z.string().describe("Starting point (function/method name or semantic query)"),
+  to: z.string().describe("Ending point (function/method name or semantic query)"),
+  projectPath: projectPathParam,
+  trackStates: z.boolean().optional().default(true).describe("Track state changes along paths"),
+  trackConditions: z.boolean().optional().default(true).describe("Track conditions/branches"),
+  maxDepth: z.number().optional().default(15).describe("Maximum traversal depth"),
+  format: z.enum(["sequence", "tree", "graph", "mermaid"]).optional().default("sequence").describe("Output format"),
+  highlightRecentChanges: z.boolean().optional().default(false).describe("Annotate trace nodes with recently-changed status (Prolly Tree)"),
+  recentCommitsCount: z.number().optional().default(10).describe("Number of recent commits to consider for highlighting")
+});
+var TraceBackwardsSchema = z.object({
+  target: z.string().describe("Target method/function to analyze"),
+  question: z.enum(["why_not_called", "what_affects", "dependencies"]).describe("Type of analysis: why_not_called, what_affects, or dependencies"),
+  projectPath: projectPathParam,
+  depth: z.number().optional().default(15).describe("Backward traversal depth"),
+  includeStates: z.boolean().optional().default(true).describe("Include state dependencies"),
+  includeEffects: z.boolean().optional().default(true).describe("Include side effects"),
+  highlightRecentChanges: z.boolean().optional().default(false).describe("Annotate trace nodes with recently-changed status (Prolly Tree)"),
+  recentCommitsCount: z.number().optional().default(10).describe("Number of recent commits to consider for highlighting")
+});
+var TraceDataFlowSchema = z.object({
+  entryPoint: z.string().describe("Entry point function (e.g., 'AppInit()')"),
+  targetState: z.string().describe("Target state to trace (e.g., 'startPage')"),
+  projectPath: projectPathParam,
+  dataSources: z.array(z.string()).optional().describe("Data sources to analyze (auto-detected if not specified)"),
+  trackTransformations: z.boolean().optional().default(true).describe("Track data transformations")
+});
+var AnalyzeStateImpactSchema = z.object({
+  state: z.string().describe("State variable to analyze (e.g., 'user.isAuthenticated')"),
+  scenarios: z.array(
+    z.object({
+      value: z.any().describe("Value for this scenario"),
+      label: z.string().describe("Human-readable label")
+    })
+  ).min(1).describe("Scenarios to analyze"),
+  projectPath: projectPathParam,
+  scope: z.string().optional().describe("Scope of analysis (semantic query)")
+});
+var FindDecisionPointsSchema = z.object({
+  scenario: z.string().describe("Scenario to analyze (semantic query or function name)"),
+  projectPath: projectPathParam,
+  includeGuards: z.boolean().optional().default(true).describe("Include guard conditions"),
+  includeEffects: z.boolean().optional().default(true).describe("Include side effects"),
+  groupBy: z.enum(["impact", "location", "type"]).optional().default("impact").describe("How to group results")
+});
+var TraceNgRxFlowSchema = z.object({
+  from: z.string().describe("Starting point (component method, effect name, or action)"),
+  to: z.string().describe("Ending point (component property, selector, or state property)"),
+  projectPath: projectPathParam,
+  maxDepth: z.number().optional().default(20).describe("Maximum traversal depth"),
+  includeActions: z.boolean().optional().default(true).describe("Include intermediate action details"),
+  format: z.enum(["sequence", "mermaid", "json"]).optional().default("sequence").describe("Output format")
+});
+var TraceFlowToolHandler = class extends BaseToolHandler {
+  traceEngine = null;
+  formatter = new OutputFormatter();
+  parseArgs(args) {
+    return TraceFlowSchema.parse(args);
+  }
+  async execute(args) {
+    const storage = await this.ensureGraphStorageForProject(args.projectPath);
+    const projectContext = storage.getProjectContext?.();
+    log.d("TRACEFLOW", "storage_ctx", { ctx: JSON.stringify(projectContext) });
+    this.traceEngine = new TraceEngine(storage, void 0);
+    const params = {
+      from: args.from,
+      to: args.to,
+      trackStates: args.trackStates,
+      trackConditions: args.trackConditions,
+      maxDepth: args.maxDepth,
+      format: args.format
+    };
+    const result = await this.traceEngine.traceFlow(params);
+    let recentlyChangedAnnotation;
+    if (args.highlightRecentChanges) {
+      const { getRecentlyChangedEntities } = await import('./recently-changed-FX5QR4Z2.js');
+      const adapter = storage.getLibSQLAdapter?.();
+      if (adapter) {
+        const recentlyChanged = await getRecentlyChangedEntities(adapter, {
+          lastCommits: args.recentCommitsCount
+        });
+        if (recentlyChanged) {
+          const changedNodes = [];
+          for (const path of result.paths) {
+            for (const step of path.steps) {
+              if (step.entityId && recentlyChanged.changedIds.has(step.entityId)) {
+                changedNodes.push(step.entityId);
+                step["recentlyChanged"] = true;
+              }
+            }
+          }
+          recentlyChangedAnnotation = {
+            recentlyChangedNodes: [...new Set(changedNodes)],
+            totalAnnotated: new Set(changedNodes).size,
+            commitsAnalyzed: recentlyChanged.commitsAnalyzed
+          };
+        }
+      }
+    }
+    let output;
+    if (args.format === "mermaid") {
+      output = JSON.stringify(
+        {
+          success: true,
+          ...result,
+          ...recentlyChangedAnnotation ? { recentlyChangedAnnotation } : {},
+          formatted: result.mermaid || this.formatter.formatTraceFlowAsMermaid(result)
+        },
+        null,
+        2
+      );
+    } else {
+      output = JSON.stringify(
+        {
+          success: true,
+          ...result,
+          ...recentlyChangedAnnotation ? { recentlyChangedAnnotation } : {},
+          formatted: this.formatter.formatTraceFlowAsText(result),
+          // Include debug info if present
+          _debug: result._debug
+        },
+        null,
+        2
+      );
+    }
+    return {
+      content: [{ type: "text", text: output }]
+    };
+  }
+};
+var TraceBackwardsToolHandler = class extends BaseToolHandler {
+  traceEngine = null;
+  formatter = new OutputFormatter();
+  parseArgs(args) {
+    return TraceBackwardsSchema.parse(args);
+  }
+  async execute(args) {
+    const storage = await this.ensureGraphStorageForProject(args.projectPath);
+    this.traceEngine = new TraceEngine(storage, void 0);
+    const params = {
+      target: args.target,
+      question: args.question,
+      depth: args.depth,
+      includeStates: args.includeStates,
+      includeEffects: args.includeEffects
+    };
+    const result = await this.traceEngine.traceBackwards(params);
+    let recentlyChangedAnnotation;
+    if (args.highlightRecentChanges) {
+      const { getRecentlyChangedEntities } = await import('./recently-changed-FX5QR4Z2.js');
+      const adapter = storage.getLibSQLAdapter?.();
+      if (adapter) {
+        const recentlyChanged = await getRecentlyChangedEntities(adapter, {
+          lastCommits: args.recentCommitsCount
+        });
+        if (recentlyChanged) {
+          const changedNodes = [];
+          for (const caller of result.callers) {
+            if (caller.entityId && recentlyChanged.changedIds.has(caller.entityId)) {
+              changedNodes.push(caller.entityId);
+              caller["recentlyChanged"] = true;
+            }
+          }
+          recentlyChangedAnnotation = {
+            recentlyChangedNodes: [...new Set(changedNodes)],
+            totalAnnotated: new Set(changedNodes).size,
+            commitsAnalyzed: recentlyChanged.commitsAnalyzed
+          };
+        }
+      }
+    }
+    const output = JSON.stringify(
+      {
+        success: true,
+        ...result,
+        ...recentlyChangedAnnotation ? { recentlyChangedAnnotation } : {},
+        formatted: this.formatter.formatTraceBackwardsAsText(result)
+      },
+      null,
+      2
+    );
+    return {
+      content: [{ type: "text", text: output }]
+    };
+  }
+};
+var TraceDataFlowToolHandler = class extends BaseToolHandler {
+  dataFlowAnalyzer = null;
+  formatter = new OutputFormatter();
+  parseArgs(args) {
+    return TraceDataFlowSchema.parse(args);
+  }
+  async execute(args) {
+    const storage = await this.ensureGraphStorageForProject(args.projectPath);
+    this.dataFlowAnalyzer = new DataFlowAnalyzer(storage, void 0);
+    const params = {
+      entryPoint: args.entryPoint,
+      targetState: args.targetState,
+      dataSources: args.dataSources,
+      trackTransformations: args.trackTransformations
+    };
+    const result = await this.dataFlowAnalyzer.traceDataFlow(params);
+    const output = JSON.stringify(
+      {
+        success: true,
+        ...result,
+        formatted: this.formatter.formatDataFlowAsText(result),
+        nextSteps: [
+          "taint_analysis() \u2014 security-focused analysis of the same data flows",
+          "analyze_state_chaos() \u2014 detect state management issues in traced flow"
+        ]
+      },
+      null,
+      2
+    );
+    return {
+      content: [{ type: "text", text: output }]
+    };
+  }
+};
+var AnalyzeStateImpactToolHandler = class extends BaseToolHandler {
+  stateTracker = null;
+  formatter = new OutputFormatter();
+  parseArgs(args) {
+    return AnalyzeStateImpactSchema.parse(args);
+  }
+  async execute(args) {
+    const storage = await this.ensureGraphStorageForProject(args.projectPath);
+    this.stateTracker = new StateTracker(storage);
+    const params = {
+      state: args.state,
+      scenarios: args.scenarios,
+      scope: args.scope
+    };
+    const result = await this.stateTracker.analyzeStateImpact(params);
+    const output = JSON.stringify(
+      {
+        success: true,
+        ...result,
+        formatted: this.formatter.formatStateImpactAsText(result)
+      },
+      null,
+      2
+    );
+    return {
+      content: [{ type: "text", text: output }]
+    };
+  }
+};
+var FindDecisionPointsToolHandler = class extends BaseToolHandler {
+  conditionAnalyzer = null;
+  formatter = new OutputFormatter();
+  parseArgs(args) {
+    return FindDecisionPointsSchema.parse(args);
+  }
+  async execute(args) {
+    const storage = await this.ensureGraphStorageForProject(args.projectPath);
+    this.conditionAnalyzer = new ConditionAnalyzer(storage);
+    const params = {
+      scenario: args.scenario,
+      includeGuards: args.includeGuards,
+      includeEffects: args.includeEffects,
+      groupBy: args.groupBy
+    };
+    const result = await this.conditionAnalyzer.findDecisionPoints(params);
+    const output = JSON.stringify(
+      {
+        success: true,
+        ...result,
+        formatted: this.formatter.formatDecisionPointsAsText(result)
+      },
+      null,
+      2
+    );
+    return {
+      content: [{ type: "text", text: output }]
+    };
+  }
+};
+var TraceNgRxFlowToolHandler = class extends BaseToolHandler {
+  ngrxEngine = null;
+  parseArgs(args) {
+    return TraceNgRxFlowSchema.parse(args);
+  }
+  async execute(args) {
+    const storage = await this.ensureGraphStorageForProject(args.projectPath);
+    this.ngrxEngine = new NgRxTraceEngine(storage);
+    const result = await this.ngrxEngine.traceNgRxFlow({
+      from: args.from,
+      to: args.to,
+      maxDepth: args.maxDepth,
+      includeActions: args.includeActions,
+      format: args.format
+    });
+    let output;
+    if (args.format === "mermaid") {
+      output = JSON.stringify(
+        {
+          success: true,
+          ...result,
+          formatted: result.mermaid || "No paths found"
+        },
+        null,
+        2
+      );
+    } else {
+      const lines = [];
+      lines.push(`NgRx Flow: ${args.from} \u2192 ${args.to}`);
+      lines.push(`Found ${result.paths.length} path(s)
+`);
+      for (const path of result.paths) {
+        lines.push(`Path ${path.id} (confidence: ${Math.round(path.confidence * 100)}%)`);
+        lines.push(`Summary: ${path.summary}`);
+        lines.push("Steps:");
+        for (const step of path.steps) {
+          lines.push(`  ${step.order}. [${step.type}] ${step.description}`);
+          lines.push(`     File: ${step.file}:${step.line}`);
+        }
+        lines.push("");
+      }
+      lines.push("Action Flow:");
+      lines.push(`  Dispatched: ${result.actionFlow.dispatched.join(", ") || "none"}`);
+      lines.push(`  Handled: ${result.actionFlow.handled.join(", ") || "none"}`);
+      lines.push(`  State Changes: ${result.actionFlow.stateChanges.join(", ") || "none"}`);
+      output = JSON.stringify(
+        {
+          success: true,
+          ...result,
+          formatted: lines.join("\n")
+        },
+        null,
+        2
+      );
+    }
+    return {
+      content: [{ type: "text", text: output }]
+    };
+  }
+};
+function createTracingToolHandlers(context) {
+  const handlers = /* @__PURE__ */ new Map();
+  handlers.set("trace_flow", new TraceFlowToolHandler(context));
+  handlers.set("trace_backwards", new TraceBackwardsToolHandler(context));
+  handlers.set("trace_data_flow", new TraceDataFlowToolHandler(context));
+  handlers.set("analyze_state_impact", new AnalyzeStateImpactToolHandler(context));
+  handlers.set("find_decision_points", new FindDecisionPointsToolHandler(context));
+  handlers.set("trace_ngrx_flow", new TraceNgRxFlowToolHandler(context));
+  return handlers;
+}
+var TRACING_TOOL_DEFINITIONS = [
+  {
+    name: "trace_flow",
+    description: `Trace execution flow from point A to point B in the codebase.
+
+Finds all possible paths and analyzes:
+- State changes along each path
+- Conditions and branches
+- Async boundaries
+- Call sequences
+
+Example: trace_flow(from: "handleLogin", to: "redirectToHome")
+
+Returns paths with confidence scores, state changes, and Mermaid diagrams.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        from: { type: "string", description: "Starting point (function/method name or semantic query)" },
+        to: { type: "string", description: "Ending point (function/method name or semantic query)" },
+        trackStates: { type: "boolean", description: "Track state changes along paths", default: true },
+        trackConditions: { type: "boolean", description: "Track conditions/branches", default: true },
+        maxDepth: { type: "number", description: "Maximum traversal depth", default: 15 },
+        format: {
+          type: "string",
+          enum: ["sequence", "tree", "graph", "mermaid"],
+          description: "Output format",
+          default: "sequence"
+        },
+        projectPath: { type: "string", description: "Project directory path. If not specified, uses current project." }
+      },
+      required: ["from", "to"]
+    }
+  },
+  {
+    name: "trace_backwards",
+    description: `Trace backwards from a method to find why it might not be called.
+
+Analysis types:
+- why_not_called: Find blocking conditions and missing callers
+- what_affects: Identify all dependencies
+- dependencies: Full dependency graph
+
+Example: trace_backwards(target: "FinishTask", question: "why_not_called")
+
+Returns callers, blocking conditions, state dependencies, and diagnosis.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        target: { type: "string", description: "Target method/function to analyze" },
+        question: {
+          type: "string",
+          enum: ["why_not_called", "what_affects", "dependencies"],
+          description: "Type of analysis"
+        },
+        depth: { type: "number", description: "Backward traversal depth", default: 15 },
+        includeStates: { type: "boolean", description: "Include state dependencies", default: true },
+        includeEffects: { type: "boolean", description: "Include side effects", default: true },
+        projectPath: { type: "string", description: "Project directory path. If not specified, uses current project." }
+      },
+      required: ["target", "question"]
+    }
+  },
+  {
+    name: "trace_data_flow",
+    description: `Trace how data flows from sources to affect a target state.
+
+Identifies:
+- Data sources (API, storage, props, config)
+- Transformations (parse, map, validate)
+- Branching based on data values
+- Behavior matrix for different inputs
+
+Example: trace_data_flow(entryPoint: "AppInit", targetState: "startPage")
+
+Returns data flows, critical conditions, and behavior combinations.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        entryPoint: { type: "string", description: "Entry point function" },
+        targetState: { type: "string", description: "Target state to trace" },
+        dataSources: {
+          type: "array",
+          items: { type: "string" },
+          description: "Data sources to analyze (auto-detected if not specified)"
+        },
+        trackTransformations: { type: "boolean", description: "Track data transformations", default: true },
+        projectPath: { type: "string", description: "Project directory path. If not specified, uses current project." }
+      },
+      required: ["entryPoint", "targetState"]
+    }
+  },
+  {
+    name: "analyze_state_impact",
+    description: `Analyze the impact of a state variable across different scenarios.
+
+Analyzes:
+- All usages of the state
+- Reachable/blocked paths per scenario
+- Enabled features
+- Conflicts and race conditions
+- Ripple effects
+
+Example: analyze_state_impact(state: "isAuthenticated", scenarios: [{value: true, label: "logged in"}, {value: false, label: "logged out"}])
+
+Returns usage analysis, scenario comparisons, and conflict detection.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        state: { type: "string", description: "State variable to analyze" },
+        scenarios: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              value: { description: "Value for this scenario" },
+              label: { type: "string", description: "Human-readable label" }
+            },
+            required: ["value", "label"]
+          },
+          description: "Scenarios to analyze",
+          minItems: 1
+        },
+        scope: { type: "string", description: "Scope of analysis (semantic query)" },
+        projectPath: { type: "string", description: "Project directory path. If not specified, uses current project." }
+      },
+      required: ["state", "scenarios"]
+    }
+  },
+  {
+    name: "find_decision_points",
+    description: `Find all decision points in a scenario's execution flow.
+
+Decision point types:
+- validation: Input validation
+- api_response: API response handling
+- state_mutation: State changes
+- guard: Guard conditions
+- loop: Loop control
+- error_handling: try-catch
+- feature_flag: Feature toggles
+
+Example: find_decision_points(scenario: "user checkout flow")
+
+Returns decision points grouped by impact with Mermaid flowchart.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        scenario: { type: "string", description: "Scenario to analyze" },
+        includeGuards: { type: "boolean", description: "Include guard conditions", default: true },
+        includeEffects: { type: "boolean", description: "Include side effects", default: true },
+        groupBy: {
+          type: "string",
+          enum: ["impact", "location", "type"],
+          description: "How to group results",
+          default: "impact"
+        },
+        projectPath: { type: "string", description: "Project directory path. If not specified, uses current project." }
+      },
+      required: ["scenario"]
+    }
+  },
+  {
+    name: "trace_ngrx_flow",
+    description: `Trace NgRx/Redux event-driven flow from action dispatch to state subscription.
+
+**IMPORTANT**: Use this for Angular projects with NgRx state management instead of trace_flow.
+Standard trace_flow cannot follow NgRx event-driven relationships.
+
+Follows the NgRx chain:
+1. Component/Effect dispatches action
+2. Effect listens via ofType()
+3. Effect dispatches new action
+4. Reducer handles action via on()
+5. Reducer modifies state
+6. Selector reads state
+7. Component subscribes via select()
+
+Example: trace_ngrx_flow(from: "MobileTaskEffects.postMessages2$", to: "TestEndComponent.setCompleteContent")
+
+Returns:
+- Flow paths through NgRx entities
+- Action chain (all actions traversed)
+- State changes made
+- Mermaid sequence diagram`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        from: { type: "string", description: "Starting point (component method, effect name, or action)" },
+        to: { type: "string", description: "Ending point (component property, selector, or state property)" },
+        maxDepth: { type: "number", description: "Maximum traversal depth", default: 20 },
+        includeActions: { type: "boolean", description: "Include intermediate action details", default: true },
+        format: {
+          type: "string",
+          enum: ["sequence", "mermaid", "json"],
+          description: "Output format",
+          default: "sequence"
+        },
+        projectPath: { type: "string", description: "Project directory path. If not specified, uses current project." }
+      },
+      required: ["from", "to"]
+    }
+  }
+];
+
+export { AnalyzeStateImpactToolHandler, FindDecisionPointsToolHandler, TRACING_TOOL_DEFINITIONS, TraceBackwardsToolHandler, TraceDataFlowToolHandler, TraceFlowToolHandler, TraceNgRxFlowToolHandler, createTracingToolHandlers };
+//# sourceMappingURL=tracing-tool-handlers-4BDCXTZZ.js.map
+//# sourceMappingURL=tracing-tool-handlers-4BDCXTZZ.js.map